From 972dcfcdbfe75dcfeb777150c136576cf1a71e99 Mon Sep 17 00:00:00 2001 From: Tudor Florea Date: Fri, 9 Oct 2015 22:59:03 +0200 Subject: initial commit for Enea Linux 5.0 arm Signed-off-by: Tudor Florea --- documentation/Makefile | 395 + documentation/README | 91 + documentation/adt-manual/adt-command.xml | 224 + documentation/adt-manual/adt-intro.xml | 179 + .../adt-manual/adt-manual-customization.xsl | 19 + .../adt-manual-eclipse-customization.xsl | 27 + documentation/adt-manual/adt-manual-intro.xml | 33 + documentation/adt-manual/adt-manual.xml | 135 + documentation/adt-manual/adt-package.xml | 101 + documentation/adt-manual/adt-prepare.xml | 671 ++ documentation/adt-manual/adt-style.css | 984 ++ documentation/adt-manual/figures/adt-title.png | Bin 0 -> 13498 bytes .../bsp-guide/bsp-guide-customization.xsl | 19 + .../bsp-guide/bsp-guide-eclipse-customization.xsl | 27 + documentation/bsp-guide/bsp-guide.xml | 138 + documentation/bsp-guide/bsp-style.css | 984 ++ documentation/bsp-guide/bsp.xml | 1527 +++ documentation/bsp-guide/figures/bsp-title.png | Bin 0 -> 17388 bytes .../dev-manual/dev-manual-common-tasks.xml | 9738 ++++++++++++++++++ .../dev-manual/dev-manual-customization.xsl | 19 + .../dev-manual-eclipse-customization.xsl | 27 + documentation/dev-manual/dev-manual-intro.xml | 240 + documentation/dev-manual/dev-manual-model.xml | 2112 ++++ documentation/dev-manual/dev-manual-newbie.xml | 1692 +++ documentation/dev-manual/dev-manual-qemu.xml | 419 + documentation/dev-manual/dev-manual-start.xml | 418 + documentation/dev-manual/dev-manual.xml | 124 + documentation/dev-manual/dev-style.css | 984 ++ documentation/dev-manual/figures/app-dev-flow.png | Bin 0 -> 53301 bytes documentation/dev-manual/figures/bsp-dev-flow.png | Bin 0 -> 42751 bytes documentation/dev-manual/figures/dev-title.png | Bin 0 -> 11813 bytes documentation/dev-manual/figures/git-workflow.png | Bin 0 -> 26586 bytes .../dev-manual/figures/index-downloads.png | Bin 0 -> 100374 bytes .../dev-manual/figures/kernel-dev-flow.png | Bin 0 -> 35561 bytes .../dev-manual/figures/kernel-overview-1.png | Bin 0 -> 35839 bytes .../figures/kernel-overview-2-generic.png | Bin 0 -> 39931 bytes .../dev-manual/figures/recipe-workflow.png | Bin 0 -> 48276 bytes documentation/dev-manual/figures/source-repos.png | Bin 0 -> 188986 bytes documentation/dev-manual/figures/yp-download.png | Bin 0 -> 230971 bytes .../figures/kernel-architecture-overview.png | Bin 0 -> 40748 bytes .../kernel-dev/figures/kernel-dev-title.png | Bin 0 -> 13453 bytes documentation/kernel-dev/kernel-dev-advanced.xml | 1074 ++ documentation/kernel-dev/kernel-dev-common.xml | 915 ++ .../kernel-dev/kernel-dev-concepts-appx.xml | 253 + .../kernel-dev/kernel-dev-customization.xsl | 18 + .../kernel-dev-eclipse-customization.xsl | 27 + documentation/kernel-dev/kernel-dev-examples.xml | 918 ++ documentation/kernel-dev/kernel-dev-faq.xml | 140 + documentation/kernel-dev/kernel-dev-intro.xml | 147 + documentation/kernel-dev/kernel-dev-maint-appx.xml | 220 + documentation/kernel-dev/kernel-dev-style.css | 984 ++ documentation/kernel-dev/kernel-dev.xml | 115 + documentation/mega-manual/figures/adt-title.png | Bin 0 -> 13498 bytes .../figures/analysis-for-package-splitting.png | Bin 0 -> 63291 bytes documentation/mega-manual/figures/app-dev-flow.png | Bin 0 -> 52670 bytes documentation/mega-manual/figures/bsp-dev-flow.png | Bin 0 -> 42751 bytes documentation/mega-manual/figures/bsp-title.png | Bin 0 -> 17388 bytes .../mega-manual/figures/buildhistory-web.png | Bin 0 -> 49966 bytes documentation/mega-manual/figures/buildhistory.png | Bin 0 -> 44913 bytes .../mega-manual/figures/building-an-image.png | Bin 0 -> 14891 bytes .../figures/configuration-compile-autoreconf.png | Bin 0 -> 46080 bytes .../figures/cross-development-toolchains.png | Bin 0 -> 59275 bytes documentation/mega-manual/figures/dev-title.png | Bin 0 -> 11813 bytes documentation/mega-manual/figures/git-workflow.png | Bin 0 -> 26586 bytes .../mega-manual/figures/image-generation.png | Bin 0 -> 50418 bytes documentation/mega-manual/figures/images.png | Bin 0 -> 22926 bytes .../mega-manual/figures/index-downloads.png | Bin 0 -> 58263 bytes .../figures/kernel-architecture-overview.png | Bin 0 -> 40748 bytes .../mega-manual/figures/kernel-dev-flow.png | Bin 0 -> 35561 bytes .../mega-manual/figures/kernel-dev-title.png | Bin 0 -> 13453 bytes .../mega-manual/figures/kernel-overview-1.png | Bin 0 -> 35839 bytes .../figures/kernel-overview-2-generic.png | Bin 0 -> 39931 bytes documentation/mega-manual/figures/kernel-title.png | Bin 0 -> 13970 bytes .../mega-manual/figures/kernelshark-all.png | Bin 0 -> 89316 bytes .../figures/kernelshark-choose-events.png | Bin 0 -> 57372 bytes .../figures/kernelshark-i915-display.png | Bin 0 -> 98765 bytes .../figures/kernelshark-output-display.png | Bin 0 -> 204454 bytes documentation/mega-manual/figures/layer-input.png | Bin 0 -> 45856 bytes documentation/mega-manual/figures/lttngmain0.png | Bin 0 -> 120581 bytes .../mega-manual/figures/oprofileui-busybox.png | Bin 0 -> 98334 bytes .../figures/oprofileui-copy-to-user.png | Bin 0 -> 105661 bytes .../mega-manual/figures/oprofileui-downloading.png | Bin 0 -> 37301 bytes .../mega-manual/figures/oprofileui-processes.png | Bin 0 -> 95741 bytes .../mega-manual/figures/package-feeds.png | Bin 0 -> 27711 bytes documentation/mega-manual/figures/patching.png | Bin 0 -> 42523 bytes .../figures/perf-probe-do_fork-profile.png | Bin 0 -> 59078 bytes .../mega-manual/figures/perf-report-cycles-u.png | Bin 0 -> 171368 bytes .../mega-manual/figures/perf-systemwide-libc.png | Bin 0 -> 136826 bytes .../mega-manual/figures/perf-systemwide.png | Bin 0 -> 140616 bytes .../figures/perf-wget-busybox-annotate-menu.png | Bin 0 -> 22364 bytes .../figures/perf-wget-busybox-annotate-udhcpc.png | Bin 0 -> 171529 bytes .../figures/perf-wget-busybox-debuginfo.png | Bin 0 -> 174971 bytes .../figures/perf-wget-busybox-dso-zoom-menu.png | Bin 0 -> 23735 bytes .../figures/perf-wget-busybox-dso-zoom.png | Bin 0 -> 101685 bytes .../perf-wget-busybox-expanded-stripped.png | Bin 0 -> 95140 bytes .../figures/perf-wget-flat-stripped.png | Bin 0 -> 178919 bytes ...erf-wget-g-copy-from-user-expanded-stripped.png | Bin 0 -> 138550 bytes ...perf-wget-g-copy-to-user-expanded-debuginfo.png | Bin 0 -> 102790 bytes ...to-user-expanded-stripped-unresolved-hidden.png | Bin 0 -> 110101 bytes .../perf-wget-g-copy-to-user-expanded-stripped.png | Bin 0 -> 102812 bytes documentation/mega-manual/figures/poky-title.png | Bin 0 -> 11592 bytes .../mega-manual/figures/profile-title.png | Bin 0 -> 12799 bytes .../figures/pybootchartgui-linux-yocto.png | Bin 0 -> 36366 bytes .../figures/pychart-linux-yocto-rpm-nostrip.png | Bin 0 -> 98053 bytes .../figures/pychart-linux-yocto-rpm.png | Bin 0 -> 81053 bytes .../mega-manual/figures/recipe-workflow.png | Bin 0 -> 48276 bytes .../mega-manual/figures/sched-wakeup-profile.png | Bin 0 -> 123810 bytes .../mega-manual/figures/sdk-generation.png | Bin 0 -> 45456 bytes documentation/mega-manual/figures/sdk.png | Bin 0 -> 20074 bytes .../mega-manual/figures/source-fetching.png | Bin 0 -> 38860 bytes documentation/mega-manual/figures/source-input.png | Bin 0 -> 39872 bytes documentation/mega-manual/figures/source-repos.png | Bin 0 -> 188986 bytes .../mega-manual/figures/sysprof-callers.png | Bin 0 -> 145043 bytes .../mega-manual/figures/sysprof-copy-from-user.png | Bin 0 -> 132976 bytes .../mega-manual/figures/sysprof-copy-to-user.png | Bin 0 -> 132074 bytes .../mega-manual/figures/user-configuration.png | Bin 0 -> 23687 bytes .../figures/using-a-pre-built-image.png | Bin 0 -> 12733 bytes .../mega-manual/figures/yocto-environment-ref.png | Bin 0 -> 83206 bytes .../mega-manual/figures/yocto-environment.png | Bin 0 -> 73095 bytes .../mega-manual/figures/yocto-project-transp.png | Bin 0 -> 8626 bytes documentation/mega-manual/figures/yp-download.png | Bin 0 -> 230971 bytes .../mega-manual/mega-manual-customization.xsl | 34 + documentation/mega-manual/mega-manual.xml | 53 + documentation/mega-manual/mega-style.css | 983 ++ documentation/poky.ent | 66 + .../profile-manual/figures/kernelshark-all.png | Bin 0 -> 89316 bytes .../figures/kernelshark-choose-events.png | Bin 0 -> 57372 bytes .../figures/kernelshark-i915-display.png | Bin 0 -> 98765 bytes .../figures/kernelshark-output-display.png | Bin 0 -> 204454 bytes .../profile-manual/figures/lttngmain0.png | Bin 0 -> 120581 bytes .../profile-manual/figures/oprofileui-busybox.png | Bin 0 -> 98334 bytes .../figures/oprofileui-copy-to-user.png | Bin 0 -> 105661 bytes .../figures/oprofileui-downloading.png | Bin 0 -> 37301 bytes .../figures/oprofileui-processes.png | Bin 0 -> 95741 bytes .../figures/perf-probe-do_fork-profile.png | Bin 0 -> 59078 bytes .../figures/perf-report-cycles-u.png | Bin 0 -> 171368 bytes .../figures/perf-systemwide-libc.png | Bin 0 -> 136826 bytes .../profile-manual/figures/perf-systemwide.png | Bin 0 -> 140616 bytes .../figures/perf-wget-busybox-annotate-menu.png | Bin 0 -> 22364 bytes .../figures/perf-wget-busybox-annotate-udhcpc.png | Bin 0 -> 171529 bytes .../figures/perf-wget-busybox-debuginfo.png | Bin 0 -> 174971 bytes .../figures/perf-wget-busybox-dso-zoom-menu.png | Bin 0 -> 23735 bytes .../figures/perf-wget-busybox-dso-zoom.png | Bin 0 -> 101685 bytes .../perf-wget-busybox-expanded-stripped.png | Bin 0 -> 95140 bytes .../figures/perf-wget-flat-stripped.png | Bin 0 -> 178919 bytes ...erf-wget-g-copy-from-user-expanded-stripped.png | Bin 0 -> 138550 bytes ...perf-wget-g-copy-to-user-expanded-debuginfo.png | Bin 0 -> 102790 bytes ...to-user-expanded-stripped-unresolved-hidden.png | Bin 0 -> 110101 bytes .../perf-wget-g-copy-to-user-expanded-stripped.png | Bin 0 -> 102812 bytes .../profile-manual/figures/profile-title.png | Bin 0 -> 12799 bytes .../figures/pybootchartgui-linux-yocto.png | Bin 0 -> 36366 bytes .../figures/pychart-linux-yocto-rpm-nostrip.png | Bin 0 -> 98053 bytes .../figures/pychart-linux-yocto-rpm.png | Bin 0 -> 81053 bytes .../figures/sched-wakeup-profile.png | Bin 0 -> 123810 bytes .../profile-manual/figures/sysprof-callers.png | Bin 0 -> 145043 bytes .../figures/sysprof-copy-from-user.png | Bin 0 -> 132976 bytes .../figures/sysprof-copy-to-user.png | Bin 0 -> 132074 bytes .../profile-manual/profile-manual-arch.xml | 45 + .../profile-manual-customization.xsl | 19 + .../profile-manual-eclipse-customization.xsl | 27 + .../profile-manual/profile-manual-examples.xml | 39 + .../profile-manual/profile-manual-intro.xml | 102 + .../profile-manual/profile-manual-style.css | 984 ++ .../profile-manual/profile-manual-usage.xml | 3695 +++++++ documentation/profile-manual/profile-manual.xml | 105 + documentation/ref-manual/TODO | 11 + documentation/ref-manual/closer-look.xml | 1304 +++ .../examples/hello-autotools/hello_2.3.bb | 8 + .../examples/hello-single/files/helloworld.c | 8 + .../ref-manual/examples/hello-single/hello.bb | 17 + .../ref-manual/examples/libxpm/libxpm_3.5.6.bb | 14 + .../examples/mtd-makefile/mtd-utils_1.0.0.bb | 15 + documentation/ref-manual/faq.xml | 799 ++ .../figures/analysis-for-package-splitting.png | Bin 0 -> 63291 bytes .../ref-manual/figures/buildhistory-web.png | Bin 0 -> 49966 bytes documentation/ref-manual/figures/buildhistory.png | Bin 0 -> 44913 bytes .../figures/configuration-compile-autoreconf.png | Bin 0 -> 46080 bytes .../figures/cross-development-toolchains.png | Bin 0 -> 59275 bytes .../ref-manual/figures/image-generation.png | Bin 0 -> 50418 bytes documentation/ref-manual/figures/images.png | Bin 0 -> 22926 bytes documentation/ref-manual/figures/layer-input.png | Bin 0 -> 45856 bytes documentation/ref-manual/figures/package-feeds.png | Bin 0 -> 27711 bytes documentation/ref-manual/figures/patching.png | Bin 0 -> 42523 bytes documentation/ref-manual/figures/poky-title.png | Bin 0 -> 11592 bytes .../ref-manual/figures/sdk-generation.png | Bin 0 -> 45456 bytes documentation/ref-manual/figures/sdk.png | Bin 0 -> 20074 bytes .../ref-manual/figures/source-fetching.png | Bin 0 -> 38860 bytes documentation/ref-manual/figures/source-input.png | Bin 0 -> 39872 bytes .../ref-manual/figures/user-configuration.png | Bin 0 -> 23687 bytes .../ref-manual/figures/yocto-environment-ref.png | Bin 0 -> 83206 bytes documentation/ref-manual/introduction.xml | 572 ++ documentation/ref-manual/migration.xml | 2019 ++++ documentation/ref-manual/ref-bitbake.xml | 472 + documentation/ref-manual/ref-classes.xml | 3489 +++++++ documentation/ref-manual/ref-features.xml | 420 + documentation/ref-manual/ref-images.xml | 169 + .../ref-manual/ref-manual-customization.xsl | 21 + .../ref-manual-eclipse-customization.xsl | 27 + documentation/ref-manual/ref-manual.xml | 160 + documentation/ref-manual/ref-qa-checks.xml | 1217 +++ documentation/ref-manual/ref-structure.xml | 1129 ++ documentation/ref-manual/ref-style.css | 985 ++ documentation/ref-manual/ref-tasks.xml | 695 ++ documentation/ref-manual/ref-variables.xml | 10284 +++++++++++++++++++ documentation/ref-manual/ref-varlocality.xml | 196 + documentation/ref-manual/resources.xml | 130 + documentation/ref-manual/technical-details.xml | 1421 +++ documentation/ref-manual/usingpoky.xml | 915 ++ documentation/template/Vera.ttf | Bin 0 -> 65932 bytes documentation/template/Vera.xml | 1 + documentation/template/VeraMoBd.ttf | Bin 0 -> 49052 bytes documentation/template/VeraMoBd.xml | 1 + documentation/template/VeraMono.ttf | Bin 0 -> 49224 bytes documentation/template/VeraMono.xml | 1 + documentation/template/component.title.xsl | 39 + documentation/template/division.title.xsl | 24 + documentation/template/draft.png | Bin 0 -> 24847 bytes documentation/template/fop-config.xml | 58 + documentation/template/formal.object.heading.xsl | 21 + documentation/template/gloss-permalinks.xsl | 14 + documentation/template/ohand-color.svg | 150 + documentation/template/permalinks.xsl | 25 + documentation/template/poky-db-pdf.xsl | 64 + documentation/template/poky-ref-manual.png | Bin 0 -> 32145 bytes documentation/template/poky.svg | 163 + documentation/template/qa-code-permalinks.xsl | 23 + documentation/template/section.title.xsl | 55 + documentation/template/titlepage.templates.xml | 1227 +++ documentation/template/yocto-project-qs.png | Bin 0 -> 17829 bytes documentation/tools/eclipse-help.sed | 18 + documentation/tools/mega-manual.sed | 31 + documentation/tools/poky-docbook-to-pdf | 51 + .../yocto-project-qs/figures/building-an-image.png | Bin 0 -> 14891 bytes .../figures/using-a-pre-built-image.png | Bin 0 -> 12733 bytes .../yocto-project-qs/figures/yocto-environment.png | Bin 0 -> 73095 bytes .../figures/yocto-project-transp.png | Bin 0 -> 8626 bytes documentation/yocto-project-qs/qs-style.css | 983 ++ .../yocto-project-qs-customization.xsl | 15 + .../yocto-project-qs-eclipse-customization.xsl | 25 + .../yocto-project-qs-titlepage.xsl | 3820 +++++++ .../yocto-project-qs/yocto-project-qs.xml | 968 ++ 241 files changed, 66564 insertions(+) create mode 100644 documentation/Makefile create mode 100644 documentation/README create mode 100644 documentation/adt-manual/adt-command.xml create mode 100644 documentation/adt-manual/adt-intro.xml create mode 100644 documentation/adt-manual/adt-manual-customization.xsl create mode 100644 documentation/adt-manual/adt-manual-eclipse-customization.xsl create mode 100644 documentation/adt-manual/adt-manual-intro.xml create mode 100644 documentation/adt-manual/adt-manual.xml create mode 100644 documentation/adt-manual/adt-package.xml create mode 100644 documentation/adt-manual/adt-prepare.xml create mode 100644 documentation/adt-manual/adt-style.css create mode 100644 documentation/adt-manual/figures/adt-title.png create mode 100644 documentation/bsp-guide/bsp-guide-customization.xsl create mode 100644 documentation/bsp-guide/bsp-guide-eclipse-customization.xsl create mode 100644 documentation/bsp-guide/bsp-guide.xml create mode 100644 documentation/bsp-guide/bsp-style.css create mode 100644 documentation/bsp-guide/bsp.xml create mode 100644 documentation/bsp-guide/figures/bsp-title.png create mode 100644 documentation/dev-manual/dev-manual-common-tasks.xml create mode 100644 documentation/dev-manual/dev-manual-customization.xsl create mode 100644 documentation/dev-manual/dev-manual-eclipse-customization.xsl create mode 100644 documentation/dev-manual/dev-manual-intro.xml create mode 100644 documentation/dev-manual/dev-manual-model.xml create mode 100644 documentation/dev-manual/dev-manual-newbie.xml create mode 100644 documentation/dev-manual/dev-manual-qemu.xml create mode 100644 documentation/dev-manual/dev-manual-start.xml create mode 100644 documentation/dev-manual/dev-manual.xml create mode 100644 documentation/dev-manual/dev-style.css create mode 100644 documentation/dev-manual/figures/app-dev-flow.png create mode 100644 documentation/dev-manual/figures/bsp-dev-flow.png create mode 100644 documentation/dev-manual/figures/dev-title.png create mode 100644 documentation/dev-manual/figures/git-workflow.png create mode 100644 documentation/dev-manual/figures/index-downloads.png create mode 100644 documentation/dev-manual/figures/kernel-dev-flow.png create mode 100644 documentation/dev-manual/figures/kernel-overview-1.png create mode 100644 documentation/dev-manual/figures/kernel-overview-2-generic.png create mode 100644 documentation/dev-manual/figures/recipe-workflow.png create mode 100644 documentation/dev-manual/figures/source-repos.png create mode 100644 documentation/dev-manual/figures/yp-download.png create mode 100755 documentation/kernel-dev/figures/kernel-architecture-overview.png create mode 100644 documentation/kernel-dev/figures/kernel-dev-title.png create mode 100644 documentation/kernel-dev/kernel-dev-advanced.xml create mode 100644 documentation/kernel-dev/kernel-dev-common.xml create mode 100644 documentation/kernel-dev/kernel-dev-concepts-appx.xml create mode 100644 documentation/kernel-dev/kernel-dev-customization.xsl create mode 100644 documentation/kernel-dev/kernel-dev-eclipse-customization.xsl create mode 100644 documentation/kernel-dev/kernel-dev-examples.xml create mode 100644 documentation/kernel-dev/kernel-dev-faq.xml create mode 100644 documentation/kernel-dev/kernel-dev-intro.xml create mode 100644 documentation/kernel-dev/kernel-dev-maint-appx.xml create mode 100644 documentation/kernel-dev/kernel-dev-style.css create mode 100644 documentation/kernel-dev/kernel-dev.xml create mode 100644 documentation/mega-manual/figures/adt-title.png create mode 100644 documentation/mega-manual/figures/analysis-for-package-splitting.png create mode 100644 documentation/mega-manual/figures/app-dev-flow.png create mode 100644 documentation/mega-manual/figures/bsp-dev-flow.png create mode 100644 documentation/mega-manual/figures/bsp-title.png create mode 100644 documentation/mega-manual/figures/buildhistory-web.png create mode 100644 documentation/mega-manual/figures/buildhistory.png create mode 100755 documentation/mega-manual/figures/building-an-image.png create mode 100644 documentation/mega-manual/figures/configuration-compile-autoreconf.png create mode 100644 documentation/mega-manual/figures/cross-development-toolchains.png create mode 100644 documentation/mega-manual/figures/dev-title.png create mode 100644 documentation/mega-manual/figures/git-workflow.png create mode 100644 documentation/mega-manual/figures/image-generation.png create mode 100644 documentation/mega-manual/figures/images.png create mode 100644 documentation/mega-manual/figures/index-downloads.png create mode 100755 documentation/mega-manual/figures/kernel-architecture-overview.png create mode 100644 documentation/mega-manual/figures/kernel-dev-flow.png create mode 100644 documentation/mega-manual/figures/kernel-dev-title.png create mode 100644 documentation/mega-manual/figures/kernel-overview-1.png create mode 100644 documentation/mega-manual/figures/kernel-overview-2-generic.png create mode 100644 documentation/mega-manual/figures/kernel-title.png create mode 100644 documentation/mega-manual/figures/kernelshark-all.png create mode 100644 documentation/mega-manual/figures/kernelshark-choose-events.png create mode 100644 documentation/mega-manual/figures/kernelshark-i915-display.png create mode 100644 documentation/mega-manual/figures/kernelshark-output-display.png create mode 100644 documentation/mega-manual/figures/layer-input.png create mode 100644 documentation/mega-manual/figures/lttngmain0.png create mode 100644 documentation/mega-manual/figures/oprofileui-busybox.png create mode 100644 documentation/mega-manual/figures/oprofileui-copy-to-user.png create mode 100644 documentation/mega-manual/figures/oprofileui-downloading.png create mode 100644 documentation/mega-manual/figures/oprofileui-processes.png create mode 100644 documentation/mega-manual/figures/package-feeds.png create mode 100644 documentation/mega-manual/figures/patching.png create mode 100644 documentation/mega-manual/figures/perf-probe-do_fork-profile.png create mode 100644 documentation/mega-manual/figures/perf-report-cycles-u.png create mode 100644 documentation/mega-manual/figures/perf-systemwide-libc.png create mode 100644 documentation/mega-manual/figures/perf-systemwide.png create mode 100644 documentation/mega-manual/figures/perf-wget-busybox-annotate-menu.png create mode 100644 documentation/mega-manual/figures/perf-wget-busybox-annotate-udhcpc.png create mode 100644 documentation/mega-manual/figures/perf-wget-busybox-debuginfo.png create mode 100644 documentation/mega-manual/figures/perf-wget-busybox-dso-zoom-menu.png create mode 100644 documentation/mega-manual/figures/perf-wget-busybox-dso-zoom.png create mode 100644 documentation/mega-manual/figures/perf-wget-busybox-expanded-stripped.png create mode 100644 documentation/mega-manual/figures/perf-wget-flat-stripped.png create mode 100644 documentation/mega-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png create mode 100644 documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png create mode 100644 documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png create mode 100644 documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png create mode 100644 documentation/mega-manual/figures/poky-title.png create mode 100644 documentation/mega-manual/figures/profile-title.png create mode 100644 documentation/mega-manual/figures/pybootchartgui-linux-yocto.png create mode 100644 documentation/mega-manual/figures/pychart-linux-yocto-rpm-nostrip.png create mode 100644 documentation/mega-manual/figures/pychart-linux-yocto-rpm.png create mode 100644 documentation/mega-manual/figures/recipe-workflow.png create mode 100644 documentation/mega-manual/figures/sched-wakeup-profile.png create mode 100644 documentation/mega-manual/figures/sdk-generation.png create mode 100644 documentation/mega-manual/figures/sdk.png create mode 100644 documentation/mega-manual/figures/source-fetching.png create mode 100644 documentation/mega-manual/figures/source-input.png create mode 100644 documentation/mega-manual/figures/source-repos.png create mode 100644 documentation/mega-manual/figures/sysprof-callers.png create mode 100644 documentation/mega-manual/figures/sysprof-copy-from-user.png create mode 100644 documentation/mega-manual/figures/sysprof-copy-to-user.png create mode 100644 documentation/mega-manual/figures/user-configuration.png create mode 100644 documentation/mega-manual/figures/using-a-pre-built-image.png create mode 100644 documentation/mega-manual/figures/yocto-environment-ref.png create mode 100644 documentation/mega-manual/figures/yocto-environment.png create mode 100755 documentation/mega-manual/figures/yocto-project-transp.png create mode 100644 documentation/mega-manual/figures/yp-download.png create mode 100644 documentation/mega-manual/mega-manual-customization.xsl create mode 100644 documentation/mega-manual/mega-manual.xml create mode 100644 documentation/mega-manual/mega-style.css create mode 100644 documentation/poky.ent create mode 100644 documentation/profile-manual/figures/kernelshark-all.png create mode 100644 documentation/profile-manual/figures/kernelshark-choose-events.png create mode 100644 documentation/profile-manual/figures/kernelshark-i915-display.png create mode 100644 documentation/profile-manual/figures/kernelshark-output-display.png create mode 100644 documentation/profile-manual/figures/lttngmain0.png create mode 100644 documentation/profile-manual/figures/oprofileui-busybox.png create mode 100644 documentation/profile-manual/figures/oprofileui-copy-to-user.png create mode 100644 documentation/profile-manual/figures/oprofileui-downloading.png create mode 100644 documentation/profile-manual/figures/oprofileui-processes.png create mode 100644 documentation/profile-manual/figures/perf-probe-do_fork-profile.png create mode 100644 documentation/profile-manual/figures/perf-report-cycles-u.png create mode 100644 documentation/profile-manual/figures/perf-systemwide-libc.png create mode 100644 documentation/profile-manual/figures/perf-systemwide.png create mode 100644 documentation/profile-manual/figures/perf-wget-busybox-annotate-menu.png create mode 100644 documentation/profile-manual/figures/perf-wget-busybox-annotate-udhcpc.png create mode 100644 documentation/profile-manual/figures/perf-wget-busybox-debuginfo.png create mode 100644 documentation/profile-manual/figures/perf-wget-busybox-dso-zoom-menu.png create mode 100644 documentation/profile-manual/figures/perf-wget-busybox-dso-zoom.png create mode 100644 documentation/profile-manual/figures/perf-wget-busybox-expanded-stripped.png create mode 100644 documentation/profile-manual/figures/perf-wget-flat-stripped.png create mode 100644 documentation/profile-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png create mode 100644 documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png create mode 100644 documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png create mode 100644 documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png create mode 100644 documentation/profile-manual/figures/profile-title.png create mode 100644 documentation/profile-manual/figures/pybootchartgui-linux-yocto.png create mode 100644 documentation/profile-manual/figures/pychart-linux-yocto-rpm-nostrip.png create mode 100644 documentation/profile-manual/figures/pychart-linux-yocto-rpm.png create mode 100644 documentation/profile-manual/figures/sched-wakeup-profile.png create mode 100644 documentation/profile-manual/figures/sysprof-callers.png create mode 100644 documentation/profile-manual/figures/sysprof-copy-from-user.png create mode 100644 documentation/profile-manual/figures/sysprof-copy-to-user.png create mode 100644 documentation/profile-manual/profile-manual-arch.xml create mode 100644 documentation/profile-manual/profile-manual-customization.xsl create mode 100644 documentation/profile-manual/profile-manual-eclipse-customization.xsl create mode 100644 documentation/profile-manual/profile-manual-examples.xml create mode 100644 documentation/profile-manual/profile-manual-intro.xml create mode 100644 documentation/profile-manual/profile-manual-style.css create mode 100644 documentation/profile-manual/profile-manual-usage.xml create mode 100644 documentation/profile-manual/profile-manual.xml create mode 100644 documentation/ref-manual/TODO create mode 100644 documentation/ref-manual/closer-look.xml create mode 100644 documentation/ref-manual/examples/hello-autotools/hello_2.3.bb create mode 100644 documentation/ref-manual/examples/hello-single/files/helloworld.c create mode 100644 documentation/ref-manual/examples/hello-single/hello.bb create mode 100644 documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb create mode 100644 documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb create mode 100644 documentation/ref-manual/faq.xml create mode 100644 documentation/ref-manual/figures/analysis-for-package-splitting.png create mode 100644 documentation/ref-manual/figures/buildhistory-web.png create mode 100644 documentation/ref-manual/figures/buildhistory.png create mode 100644 documentation/ref-manual/figures/configuration-compile-autoreconf.png create mode 100644 documentation/ref-manual/figures/cross-development-toolchains.png create mode 100644 documentation/ref-manual/figures/image-generation.png create mode 100644 documentation/ref-manual/figures/images.png create mode 100644 documentation/ref-manual/figures/layer-input.png create mode 100644 documentation/ref-manual/figures/package-feeds.png create mode 100644 documentation/ref-manual/figures/patching.png create mode 100644 documentation/ref-manual/figures/poky-title.png create mode 100644 documentation/ref-manual/figures/sdk-generation.png create mode 100644 documentation/ref-manual/figures/sdk.png create mode 100644 documentation/ref-manual/figures/source-fetching.png create mode 100644 documentation/ref-manual/figures/source-input.png create mode 100644 documentation/ref-manual/figures/user-configuration.png create mode 100644 documentation/ref-manual/figures/yocto-environment-ref.png create mode 100644 documentation/ref-manual/introduction.xml create mode 100644 documentation/ref-manual/migration.xml create mode 100644 documentation/ref-manual/ref-bitbake.xml create mode 100644 documentation/ref-manual/ref-classes.xml create mode 100644 documentation/ref-manual/ref-features.xml create mode 100644 documentation/ref-manual/ref-images.xml create mode 100644 documentation/ref-manual/ref-manual-customization.xsl create mode 100644 documentation/ref-manual/ref-manual-eclipse-customization.xsl create mode 100644 documentation/ref-manual/ref-manual.xml create mode 100644 documentation/ref-manual/ref-qa-checks.xml create mode 100644 documentation/ref-manual/ref-structure.xml create mode 100644 documentation/ref-manual/ref-style.css create mode 100644 documentation/ref-manual/ref-tasks.xml create mode 100644 documentation/ref-manual/ref-variables.xml create mode 100644 documentation/ref-manual/ref-varlocality.xml create mode 100644 documentation/ref-manual/resources.xml create mode 100644 documentation/ref-manual/technical-details.xml create mode 100644 documentation/ref-manual/usingpoky.xml create mode 100644 documentation/template/Vera.ttf create mode 100644 documentation/template/Vera.xml create mode 100644 documentation/template/VeraMoBd.ttf create mode 100644 documentation/template/VeraMoBd.xml create mode 100644 documentation/template/VeraMono.ttf create mode 100644 documentation/template/VeraMono.xml create mode 100644 documentation/template/component.title.xsl create mode 100644 documentation/template/division.title.xsl create mode 100644 documentation/template/draft.png create mode 100644 documentation/template/fop-config.xml create mode 100644 documentation/template/formal.object.heading.xsl create mode 100644 documentation/template/gloss-permalinks.xsl create mode 100644 documentation/template/ohand-color.svg create mode 100644 documentation/template/permalinks.xsl create mode 100644 documentation/template/poky-db-pdf.xsl create mode 100644 documentation/template/poky-ref-manual.png create mode 100644 documentation/template/poky.svg create mode 100644 documentation/template/qa-code-permalinks.xsl create mode 100644 documentation/template/section.title.xsl create mode 100644 documentation/template/titlepage.templates.xml create mode 100644 documentation/template/yocto-project-qs.png create mode 100644 documentation/tools/eclipse-help.sed create mode 100644 documentation/tools/mega-manual.sed create mode 100755 documentation/tools/poky-docbook-to-pdf create mode 100755 documentation/yocto-project-qs/figures/building-an-image.png create mode 100644 documentation/yocto-project-qs/figures/using-a-pre-built-image.png create mode 100644 documentation/yocto-project-qs/figures/yocto-environment.png create mode 100755 documentation/yocto-project-qs/figures/yocto-project-transp.png create mode 100644 documentation/yocto-project-qs/qs-style.css create mode 100644 documentation/yocto-project-qs/yocto-project-qs-customization.xsl create mode 100644 documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl create mode 100644 documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl create mode 100644 documentation/yocto-project-qs/yocto-project-qs.xml (limited to 'documentation') diff --git a/documentation/Makefile b/documentation/Makefile new file mode 100644 index 0000000000..3bc9a213ee --- /dev/null +++ b/documentation/Makefile @@ -0,0 +1,395 @@ +# This is a single Makefile to handle all generated Yocto Project documents. +# The Makefile needs to live in the documents directory and all figures used +# in any manuals must be .PNG files and live in the individual book's figures +# directory as well as in the figures directory for the mega-manual. +# Note that the figures for the Yocto Project Development Manual +# differ depending on the BRANCH being built. +# +# The Makefile has these targets: +# +# pdf: generates a PDF version of a manual. Not valid for the Quick Start +# or the mega-manual (single, large HTML file comprised of all +# Yocto Project manuals). +# html: generates an HTML version of a manual. +# eclipse: generates an HTML version of a manual that can be used as +# eclipse help (including necessary metadata files). +# tarball: creates a tarball for the doc files. +# validate: validates +# publish: pushes generated files to the Yocto Project website +# clean: removes files +# +# The Makefile generates an HTML and PDF version of every document except the +# Yocto Project Quick Start and the single, HTML mega-manual, which is comprised +# of all the individual Yocto Project manuals. These two manuals are in HTML +# form only. The variable DOC indicates the folder name for a given manual. The +# variable VER represents the distro version of the Yocto Release for which the +# manuals are being generated. The variable BRANCH is used to indicate the +# branch (edison or denzil) and is used only when DOC=dev-manual or +# DOC=mega-manual. If you do not specify a BRANCH, the default branch used +# will be for the latest Yocto Project release. If you build for either +# edison or denzil, you must use BRANCH. You do not need to use BRANCH for +# any release beyond denzil. +# +# To build a manual, you must invoke Makefile with the DOC argument. If you +# are going to publish the manual, then you must invoke Makefile with both the +# DOC and the VER argument. Furthermore, if you are building or publishing +# the edison or denzil versions of the Yocto Poject Development Manual or +# the mega-manual, you must also use the BRANCH argument. +# +# Examples: +# +# make DOC=bsp-guide +# make DOC=yocto-project-qs +# make pdf DOC=ref-manual +# make DOC=dev-manual BRANCH=edison +# make DOC=mega-manual BRANCH=denzil +# +# The first example generates the HTML and PDF versions of the BSP Guide. +# The second example generates the HTML version only of the Quick Start. Note that +# the Quick Start only has an HTML version available. The third example generates +# both the PDF and HTML versions of the Yocto Project Reference Manual. The +# fourth example generates both the PDF and HTML 'edison' versions of the YP +# Development Manual. The last exmample generates the HTML version of the +# mega-manual and uses the 'denzil' branch when choosing figures for the +# tarball of figures. Any example that does not use the BRANCH argument +# builds the current version of the manual set. +# +# Use the publish target to push the generated manuals to the Yocto Project +# website. All files needed for the manual's HTML form are pushed as well as the +# PDF version (if applicable). +# Examples: +# +# make publish DOC=bsp-guide VER=1.3 +# make publish DOC=adt-manual VER=1.3 +# make publish DOC=dev-manual VER=1.1.1 BRANCH=edison +# make publish DOC=dev-manual VER=1.2 BRANCH=denzil +# +# The first example publishes the 1.3 version of both the PDF and HTML versions of +# the BSP Guide. The second example publishes the 1.3 version of both the PDF and +# HTML versions of the ADT Manual. The third example publishes the PDF and HTML +# 'edison' versions of the YP Development Manual. The fourth example publishes +# the PDF and HTML 'denzil' versions of the YP Development Manual. +# + +ifeq ($(DOC),bsp-guide) +XSLTOPTS = --xinclude +ALLPREQ = html pdf eclipse tarball +TARFILES = bsp-style.css bsp-guide.html bsp-guide.pdf figures/bsp-title.png \ + eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css + +endif + +ifeq ($(DOC),dev-manual) +XSLTOPTS = --xinclude +ALLPREQ = html pdf eclipse tarball +# +# Note that the tarfile might produce the "Cannot stat: No such file or directory" error +# message for .PNG files that are not present when building a particular branch. The +# list of files is all-inclusive for all branches. Note, if you don't provide a BRANCH +# option, it defaults to the latest stuff. This would be appropriate for "master" branch. +# + + ifeq ($(BRANCH),edison) +TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ + figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ + figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/kernel-example-repos-edison.png \ + figures/kernel-overview-1.png figures/kernel-overview-2.png \ + figures/kernel-overview-3-edison.png \ + figures/source-repos.png figures/yp-download.png \ + figures/wip.png + else ifeq ($(BRANCH),denzil) +TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ + figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ + figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/kernel-example-repos-denzil.png \ + figures/kernel-overview-1.png figures/kernel-overview-2.png \ + figures/kernel-overview-3-denzil.png \ + figures/source-repos.png figures/yp-download.png \ + figures/wip.png + else +TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ + figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ + figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ + figures/source-repos.png figures/yp-download.png figures/recipe-workflow.png \ + eclipse + endif + +MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css + +endif + +ifeq ($(DOC),yocto-project-qs) +XSLTOPTS = --xinclude +ALLPREQ = html eclipse tarball +TARFILES = yocto-project-qs.html qs-style.css figures/yocto-environment.png \ + figures/building-an-image.png figures/using-a-pre-built-image.png \ + figures/yocto-project-transp.png \ + eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css +endif + +ifeq ($(DOC),mega-manual) +XSLTOPTS = --stringparam html.stylesheet mega-style.css \ + --stringparam chapter.autolabel 1 \ + --stringparam section.autolabel 1 \ + --stringparam section.label.includes.component.label 1 \ + --xinclude +ALLPREQ = html tarball + + ifeq ($(BRANCH),edison) +TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \ + figures/using-a-pre-built-image.png \ + figures/poky-title.png \ + figures/adt-title.png figures/bsp-title.png \ + figures/kernel-title.png figures/kernel-architecture-overview.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ + figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/kernel-example-repos-edison.png \ + figures/kernel-overview-1.png figures/kernel-overview-2.png \ + figures/kernel-overview-3-edison.png \ + figures/source-repos.png figures/yp-download.png \ + figures/wip.png + else ifeq ($(BRANCH),denzil) +TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \ + figures/using-a-pre-built-image.png \ + figures/poky-title.png \ + figures/adt-title.png figures/bsp-title.png \ + figures/kernel-title.png figures/kernel-architecture-overview.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ + figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/kernel-example-repos-denzil.png \ + figures/kernel-overview-1.png figures/kernel-overview-2.png \ + figures/kernel-overview-3-denzil.png \ + figures/source-repos.png figures/yp-download.png \ + figures/wip.png + else +TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \ + 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/kernel-dev-title.png figures/kernel-architecture-overview.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ + figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ + figures/source-repos.png figures/yp-download.png \ + figures/profile-title.png figures/kernelshark-all.png \ + figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \ + figures/kernelshark-output-display.png figures/lttngmain0.png \ + figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \ + figures/oprofileui-downloading.png figures/oprofileui-processes.png \ + figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \ + figures/perf-systemwide.png figures/perf-systemwide-libc.png \ + figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \ + figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \ + figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \ + figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \ + figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \ + figures/sched-wakeup-profile.png figures/sysprof-callers.png \ + figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \ + figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \ + figures/package-feeds.png figures/layer-input.png figures/images.png figures/sdk.png \ + figures/source-fetching.png figures/patching.png figures/configuration-compile-autoreconf.png \ + figures/analysis-for-package-splitting.png figures/image-generation.png \ + figures/sdk-generation.png figures/recipe-workflow.png + endif + +MANUALS = $(DOC)/$(DOC).html +FIGURES = figures +STYLESHEET = $(DOC)/*.css + +endif + +ifeq ($(DOC),ref-manual) +XSLTOPTS = --xinclude +ALLPREQ = html pdf eclipse tarball +TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ + figures/buildhistory.png figures/buildhistory-web.png eclipse \ + figures/cross-development-toolchains.png figures/layer-input.png \ + figures/package-feeds.png figures/source-input.png \ + figures/user-configuration.png figures/yocto-environment-ref.png \ + figures/images.png figures/sdk.png figures/source-fetching.png \ + figures/patching.png figures/configuration-compile-autoreconf.png \ + figures/analysis-for-package-splitting.png figures/image-generation.png \ + figures/sdk-generation.png +MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css +endif + + +ifeq ($(DOC),adt-manual) +XSLTOPTS = --xinclude +ALLPREQ = html pdf eclipse tarball +TARFILES = adt-manual.html adt-manual.pdf adt-style.css figures/adt-title.png \ + eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css +endif + +ifeq ($(DOC),profile-manual) +XSLTOPTS = --xinclude +ALLPREQ = html pdf eclipse tarball +TARFILES = profile-manual.html profile-manual.pdf profile-manual-style.css \ + figures/profile-title.png figures/kernelshark-all.png \ + figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \ + figures/kernelshark-output-display.png figures/lttngmain0.png \ + figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \ + figures/oprofileui-downloading.png figures/oprofileui-processes.png \ + figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \ + figures/perf-systemwide.png figures/perf-systemwide-libc.png \ + figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \ + figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \ + figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \ + figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \ + figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \ + figures/sched-wakeup-profile.png figures/sysprof-callers.png \ + figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \ + eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css +endif + +ifeq ($(DOC),kernel-dev) +XSLTOPTS = --xinclude +ALLPREQ = html pdf eclipse tarball +TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png \ + figures/kernel-architecture-overview.png \ + eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css +endif + + +## +# These URI should be rewritten by your distribution's xml catalog to +# match your localy installed XSL stylesheets. +XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current +XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl + +all: $(ALLPREQ) + +pdf: +ifeq ($(DOC),yocto-project-qs) + @echo " " + @echo "ERROR: You cannot generate a yocto-project-qs PDF file." + @echo " " + +else ifeq ($(DOC),mega-manual) + @echo " " + @echo "ERROR: You cannot generate a mega-manual PDF file." + @echo " " + +else + + cd $(DOC); ../tools/poky-docbook-to-pdf $(DOC).xml ../template; cd .. +endif + +html: +ifeq ($(DOC),mega-manual) +# See http://www.sagehill.net/docbookxsl/HtmlOutput.html + @echo " " + @echo "******** Building "$(DOC) + @echo " " + cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd .. + @echo " " + @echo "******** Using mega-manual.sed to process external links" + @echo " " + cd $(DOC); sed -f ../tools/mega-manual.sed < mega-manual.html > mega-output.html; cd .. + @echo " " + @echo "******** Cleaning up transient file mega-output.html" + @echo " " + cd $(DOC); rm mega-manual.html; mv mega-output.html mega-manual.html; cd .. +else +# See http://www.sagehill.net/docbookxsl/HtmlOutput.html + @echo " " + @echo "******** Building "$(DOC) + @echo " " + cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd .. +endif + + +eclipse: BASE_DIR = html/$(DOC)/ + +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),) + @echo " " + @echo "ERROR: You can only create eclipse documentation" + @echo " of the following documentation parts:" + @echo " - adt-manual" + @echo " - bsp-guide" + @echo " - dev-manual" + @echo " - kernel-dev" + @echo " - profile-manual" + @echo " - ref-manual" + @echo " - yocto-project-qs" + @echo " " +else + @echo " " + @echo "******** Building eclipse help of "$(DOC) + @echo " " + cd $(DOC) && \ + xsltproc $(XSLTOPTS) \ + --stringparam base.dir '$(BASE_DIR)' \ + -o eclipse/$(DOC).html \ + $(DOC)-eclipse-customization.xsl $(DOC).xml && \ + mv eclipse/toc.xml eclipse/$(DOC)-toc.xml && \ + cp -rf $(FIGURES) eclipse/$(BASE_DIR) && \ + cd ..; + + $(call modify-eclipse) +endif + +eclipse-resolve-links: + @echo " " + @echo "******** Using eclipse-help.sed to process external links" + @echo " " + $(foreach FILE, \ + $(wildcard $(DOC)/eclipse/html/$(DOC)/*.html), \ + $(shell sed -i -f tools/eclipse-help.sed $(FILE))) + +tarball: html + @echo " " + @echo "******** Creating Tarball of document files" + @echo " " + cd $(DOC); tar -cvzf $(DOC).tgz $(TARFILES); cd .. + +validate: + cd $(DOC); xmllint --postvalid --xinclude --noout $(DOC).xml; cd .. + + +publish: + @if test -f $(DOC)/$(DOC).html; \ + then \ + echo " "; \ + echo "******** Publishing "$(DOC)".html"; \ + echo " "; \ + scp -r $(MANUALS) $(STYLESHEET) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \ + cd $(DOC); scp -r $(FIGURES) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \ + else \ + echo " "; \ + echo $(DOC)".html missing. Generate the file first then try again."; \ + echo " "; \ + fi + +clean: + rm -rf $(MANUALS); rm $(DOC)/$(DOC).tgz; diff --git a/documentation/README b/documentation/README new file mode 100644 index 0000000000..d01678d4f4 --- /dev/null +++ b/documentation/README @@ -0,0 +1,91 @@ +documentation +============= + +This is the directory that contains the Yocto Project documentation. The Yocto +Project source repositories at http://git.yoctoproject.org/cgit.cgi have two +instances of the "documentation" directory. You should understand each of +these instances. + + poky/documentation - The directory within the poky Git repository containing + the set of Yocto Project manuals. When you clone the + poky Git repository, the documentation directory + contains the manuals. The state of the manuals in this + directory is guaranteed to reflect the latest Yocto + Project release. The manuals at the tip of this + directory will also likely contain most manual + development changes. + + yocto-docs/documentation - The Git repository for the Yocto Project manuals. + This repository is where manual development + occurs. If you plan on contributing back to the + Yocto Project documentation, you should set up + a local Git repository based on this upstream + repository as follows: + + git clone git://git.yoctoproject.org/yocto-docs + + Changes and patches are first pushed to the + yocto-docs Git repository. Later, they make it + into the poky Git repository found at + git://git.yoctoproject.org/poky. + +Manual Organization +=================== + +Folders exist for individual manuals as follows: + +* adt-manual - The Yocto Project Application 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 +* profile-manual - The Yocto Project Profile and Tracing 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 +is located in the tools directory. Also note that the figures folder in the +mega-manual directory contains duplicates of all the figures in the YP folders +directories for all YP manuals and guides. + +If you want to find HTML versions of the Yocto Project manuals on the web, +go to http://www.yoctoproject.org and click on the "Documentation" tab. From +there you have access to archived documentation from previous releases, current +documentation for the latest release, and "Docs in Progress" for the release +currently being developed. + +In general, the Yocto Project site (http://www.yoctoproject.org) is a great +reference for both information and downloads. + +Makefile +======== + +The Makefile processes manual directories to create HTML, PDF, +tarballs, etc. Details on how the Makefile work are documented +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. +The DOC variable specifies the manual you are making: + + $ make DOC=adt-manual + +poky.ent +======== + +This file defines variables used for documentation production. The variables +are used to define release pathnames, URLs for the published manuals, etc. + +template +======== +Contains various templates, fonts, and some old PNG files. + +tools +===== +Contains a tool to convert the DocBook files to PDF format. This folder also +contains the mega-manual.sed file, which is used by Makefile to process +cross-references from within the manual that normally go to an external +manual. diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml new file mode 100644 index 0000000000..164b1efbff --- /dev/null +++ b/documentation/adt-manual/adt-command.xml @@ -0,0 +1,224 @@ + %poky; ] > + + +Using the Command Line + + + Recall that earlier the manual discussed how to use an existing toolchain + tarball that had been installed into the default installation + directory, /opt/poky/&DISTRO;, which is outside of the + Build Directory + (see the section "Using a Cross-Toolchain Tarball)". + And, that sourcing your architecture-specific environment setup script + initializes a suitable cross-toolchain development environment. + + + + During this setup, locations for the compiler, QEMU scripts, QEMU binary, + a special version of pkgconfig and other useful + utilities are added to the PATH variable. + Also, variables to assist + pkgconfig and autotools + are also defined so that, for example, configure.sh + can find pre-generated test results for tests that need target hardware + on which to run. + + + + Collectively, these conditions allow you to easily use the toolchain + outside of the OpenEmbedded build environment on both Autotools-based + projects and Makefile-based projects. + This chapter provides information for both these types of projects. + + + +
+Autotools-Based Projects + + + 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. + + +
+ Creating and Running a Project Based on GNU Autotools + + + Follow these steps to create a simple Autotools-based project: + + Create your directory: + Create a clean directory for your project and then make + that directory your working location: + + $ mkdir $HOME/helloworld + $ cd $HOME/helloworld + + Populate the directory: + Create hello.c, Makefile.am, + and configure.in files as follows: + + For hello.c, include + these lines: + + #include <stdio.h> + + main() + { + printf("Hello World!\n"); + } + + For Makefile.am, + include these lines: + + bin_PROGRAMS = hello + hello_SOURCES = hello.c + + For configure.in, + include these lines: + + AC_INIT(hello.c) + AM_INIT_AUTOMAKE(hello,0.1) + AC_PROG_CC + AC_PROG_INSTALL + AC_OUTPUT(Makefile) + + + Source the cross-toolchain + environment setup file: + Installation of the cross-toolchain creates a cross-toolchain + environment setup script in the directory that the ADT + 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 ADT installation directory that uses the + 32-bit Intel x86 Architecture and using the + &DISTRO_NAME; Yocto Project release: + + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + + Generate the local aclocal.m4 + files and create the configure script: + The following GNU Autotools generate the local + aclocal.m4 files and create the + configure script: + + $ aclocal + $ autoconf + + Generate files needed by GNU + coding standards: + GNU coding standards require certain files in order for the + project to be compliant. + This command creates those files: + + $ touch NEWS README AUTHORS ChangeLog + + Generate the configure + file: + This command generates the configure: + + $ automake -a + + Cross-compile the project: + This command compiles the project using the cross-compiler: + + $ ./configure ${CONFIGURE_FLAGS} + + Make and install the project: + These two commands generate and install the project into the + destination directory: + + $ make + $ make install DESTDIR=./tmp + + Verify the installation: + 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. + + $ file ./tmp/usr/local/bin/hello + + Execute your project: + 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: + + $ ./hello + + As expected, the project displays the "Hello World!" message. + + + +
+ +
+ Passing Host Options + + + For an Autotools-based project, you can use the cross-toolchain by just + passing the appropriate host option to configure.sh. + 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 armv5te-poky-linux-gnueabi. + You will notice that the name of the script is + environment-setup-armv5te-poky-linux-gnueabi. + Thus, the following command works: + + $ ./configure --host=armv5te-poky-linux-gnueabi \ + --with-libtool-sysroot=sysroot-dir + + + + + This single command updates your project and rebuilds it using the appropriate + cross-toolchain tools. + + If the configure script results in problems recognizing the + --with-libtool-sysroot=sysroot-dir option, + regenerate the script to enable the support by doing the following and then + run the script again: + + $ libtoolize --automake + $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ + [-I dir_containing_your_project-specific_m4_macros] + $ autoconf + $ autoheader + $ automake -a + + + +
+
+ +
+Makefile-Based Projects + + + For a Makefile-based project, you use the cross-toolchain by making sure + the tools are used. + You can do this as follows: + + CC=arm-poky-linux-gnueabi-gcc + LD=arm-poky-linux-gnueabi-ld + CFLAGS=”${CFLAGS} --sysroot=<sysroot-dir>” + CXXFLAGS=”${CXXFLAGS} --sysroot=<sysroot-dir>” + + +
+ +
+ diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml new file mode 100644 index 0000000000..ed13a23a5f --- /dev/null +++ b/documentation/adt-manual/adt-intro.xml @@ -0,0 +1,179 @@ + %poky; ] > + + + The Application Development Toolkit (ADT) + + + Part of the Yocto Project development solution is an Application Development + Toolkit (ADT). + The ADT provides you with a custom-built, cross-development + platform suited for developing a user-targeted product application. + + + + Fundamentally, the ADT consists of the following: + + An architecture-specific cross-toolchain and matching + sysroot both built by the OpenEmbedded build system. + The toolchain and sysroot are based on a + Metadata + configuration and extensions, + which allows you to cross-develop on the host machine for the target hardware. + + The Eclipse IDE Yocto Plug-in. + The Quick EMUlator (QEMU), which lets you simulate target hardware. + + Various user-space tools that greatly enhance your application + development experience. + + + +
+ The Cross-Development Toolchain + + + The + Cross-Development Toolchain + 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 either by running the ADT Installer + script, a toolchain installer script, or through a + Build Directory + that is based on your Metadata configuration or extension for + your targeted device. + The cross-toolchain works with a matching target sysroot. + +
+ +
+ Sysroot + + + The matching target sysroot contains needed headers and libraries for generating + binaries that run on the target architecture. + The 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. + +
+ +
+ Eclipse Yocto Plug-in + + + 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. + + + + 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 + "Working Within Eclipse" section + of the Yocto Project Development Manual. + +
+ +
+ The QEMU Emulator + + + The QEMU emulator allows you to simulate your hardware while running your + application or image. + QEMU is made available a number of ways: + + + If you use the ADT Installer script to install ADT, you can + specify whether or not to install QEMU. + + + If you have cloned the poky Git + repository to create a + Source Directory + and you have sourced the environment setup script, QEMU is + installed and automatically available. + + + If you have downloaded a Yocto Project release and unpacked + it to create a + Source Directory + and you have sourced the environment setup script, QEMU is + installed and automatically available. + + + 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. + + + +
+ +
+ User-Space Tools + + + User-space tools are included as part of the distribution. + You will find these tools helpful during development. + The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust. + These tools are common development tools for the Linux platform. + + LatencyTOP: 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. + + PowerTOP: Helps you determine what + software is using the most power. + You can find out more about PowerTOP at + . + OProfile: A system-wide profiler for Linux + systems that is capable of profiling all running code at low overhead. + You can find out more about OProfile at + . + For examples on how to setup and use this tool, see the + "OProfile" + section in the Yocto Project Profiling and Tracing Manual. + + Perf: 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 + . + For examples on how to setup and use this tool, see the + "perf" + section in the Yocto Project Profiling and Tracing Manual. + + SystemTap: 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 for more information + on SystemTap. + For examples on how to setup and use this tool, see the + "SystemTap" + section in the Yocto Project Profiling and Tracing Manual. + Lttng-ust: A User-space Tracer designed to + provide detailed information on user-space activity. + See for more information on Lttng-ust. + + + +
+ +
+ diff --git a/documentation/adt-manual/adt-manual-customization.xsl b/documentation/adt-manual/adt-manual-customization.xsl new file mode 100644 index 0000000000..f08087d93f --- /dev/null +++ b/documentation/adt-manual/adt-manual-customization.xsl @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/documentation/adt-manual/adt-manual-eclipse-customization.xsl b/documentation/adt-manual/adt-manual-eclipse-customization.xsl new file mode 100644 index 0000000000..d16ffbb68e --- /dev/null +++ b/documentation/adt-manual/adt-manual-eclipse-customization.xsl @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/adt-manual/adt-manual-intro.xml b/documentation/adt-manual/adt-manual-intro.xml new file mode 100644 index 0000000000..fccacc4ba4 --- /dev/null +++ b/documentation/adt-manual/adt-manual-intro.xml @@ -0,0 +1,33 @@ + %poky; ] > + + +Introduction + + + Welcome to the Yocto Project Application Developer's Guide. + This manual provides information that lets you begin developing applications + using the Yocto Project. + + + + The Yocto Project provides an application development environment based on + an Application Development Toolkit (ADT) and the availability of stand-alone + cross-development toolchains and other tools. + This manual describes the ADT and how you can configure and install it, + how to access and use the cross-development toolchains, how to + customize the development packages installation, + how to use command line development for both Autotools-based and Makefile-based projects, + and an introduction to the Eclipse IDE + Yocto Plug-in. + + The ADT is distribution-neutral and does not require the Yocto + Project reference distribution, which is called Poky. + This manual, however, uses examples that use the Poky distribution. + + + + diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml new file mode 100644 index 0000000000..57ca64ed17 --- /dev/null +++ b/documentation/adt-manual/adt-manual.xml @@ -0,0 +1,135 @@ + %poky; ] > + + + + + + + + + + + + Yocto Project Application Developer's Guide + + + + + Jessica Zhang + + Intel Corporation + + jessica.zhang@intel.com + + + + + + 1.0 + 6 April 2011 + Released with the Yocto Project 1.0 Release. + + + 1.0.1 + 23 May 2011 + Released with the Yocto Project 1.0.1 Release. + + + 1.1 + 6 October 2011 + Released with the Yocto Project 1.1 Release. + + + 1.2 + April 2012 + Released with the Yocto Project 1.2 Release. + + + 1.3 + October 2012 + Released with the Yocto Project 1.3 Release. + + + 1.4 + April 2013 + Released with the Yocto Project 1.4 Release. + + + 1.5 + October 2013 + Released with the Yocto Project 1.5 Release. + + + 1.5.1 + January 2014 + Released with the Yocto Project 1.5.1 Release. + + + 1.6 + April 2014 + Released with the Yocto Project 1.6 Release. + + + 1.7 + October 2014 + Released with the Yocto Project 1.7 Release. + + + 1.7.1 + January 2015 + Released with the Yocto Project 1.7.1 Release. + + + 1.7.2 + June 2015 + Released with the Yocto Project 1.7.2 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons. + + + For the latest version of this manual associated with this + Yocto Project release, see the + Yocto Project Application Developer's Guide + from the Yocto Project website. + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/adt-manual/adt-package.xml b/documentation/adt-manual/adt-package.xml new file mode 100644 index 0000000000..5c3196ea91 --- /dev/null +++ b/documentation/adt-manual/adt-package.xml @@ -0,0 +1,101 @@ + %poky; ] > + + +Optionally Customizing the Development Packages Installation + + + Because the Yocto Project is suited for embedded Linux development, it is + likely that you will need to customize your development packages installation. + For example, if you are developing a minimal image, then you might not need + certain packages (e.g. graphics support packages). + Thus, you would like to be able to remove those packages from your target sysroot. + + +
+ Package Management Systems + + + The OpenEmbedded build system supports the generation of sysroot files using + three different Package Management Systems (PMS): + + OPKG: A less well known PMS whose use + originated in the OpenEmbedded and OpenWrt embedded Linux projects. + This PMS works with files packaged in an .ipk format. + See for more + information about OPKG. + RPM: A more widely known PMS intended for GNU/Linux + distributions. + This PMS works with files packaged in an .rms format. + The build system currently installs through this PMS by default. + See + for more information about RPM. + Debian: The PMS for Debian-based systems + is built on many PMS tools. + The lower-level PMS tool dpkg forms the base of the Debian PMS. + For information on dpkg see + . + + +
+ +
+ Configuring the PMS + + + Whichever PMS you are using, you need to be sure that the + PACKAGE_CLASSES + variable in the conf/local.conf + file is set to reflect that system. + The first value you choose for the variable specifies the package file format for the root + filesystem at sysroot. + Additional values specify additional formats for convenience or testing. + See the configuration file for details. + + + + For build performance information related to the PMS, see the + "package.bbclass" + section in the Yocto Project Reference Manual. + + + + As an example, consider a scenario where you are using OPKG and you want to add + the libglade package to the target sysroot. + + + + First, you should generate the IPK file for the + libglade package and add it + into a working opkg repository. + Use these commands: + + $ bitbake libglade + $ bitbake package-index + + + + + Next, source the environment setup script found in the + Source Directory. + Follow that by setting up the installation destination to point to your + sysroot as sysroot_dir. + Finally, have an OPKG configuration file conf_file + that corresponds to the opkg repository you have just created. + The following command forms should now work: + + $ opkg-cl –f conf_file -o sysroot_dir update + $ opkg-cl –f cconf_file -o sysroot_dir \ + --force-overwrite install libglade + $ opkg-cl –f cconf_file -o sysroot_dir \ + --force-overwrite install libglade-dbg + $ opkg-cl –f conf_file> -o sysroot_dir> \ + --force-overwrite install libglade-dev + + +
+
+ diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml new file mode 100644 index 0000000000..3810568730 --- /dev/null +++ b/documentation/adt-manual/adt-prepare.xml @@ -0,0 +1,671 @@ + %poky; ] > + + + +Preparing for Application Development + + + In order to develop applications, you need set up your host development system. + Several ways exist that allow you to install cross-development tools, QEMU, the + Eclipse Yocto Plug-in, and other tools. + This chapter describes how to prepare for application development. + + +
+ Installing the ADT and Toolchains + + + The following list describes installation methods that set up varying degrees of tool + availability on your system. + Regardless of the installation method you choose, + you must source the cross-toolchain + environment setup script before you use a toolchain. + See the "Setting Up the + Cross-Development Environment" section for more information. + + + + Avoid mixing installation methods when installing toolchains for different architectures. + For example, avoid using the ADT Installer to install some toolchains and then hand-installing + cross-development toolchains by running the toolchain installer for different architectures. + Mixing installation methods can result in situations where the ADT Installer becomes + unreliable and might not install the toolchain. + If you must mix installation methods, you might avoid problems by deleting + /var/lib/opkg, thus purging the opkg package + metadata + + + + + Use the ADT installer script: + This method is the recommended way to install the ADT because it + automates much of the process for you. + For example, you can configure the installation to install the QEMU emulator + and the user-space NFS, specify which root filesystem profiles to download, + and define the target sysroot location. + Use an existing toolchain: + Using this method, you select and download an architecture-specific + toolchain installer and then run the script to hand-install the toolchain. + If you use this method, you just get the cross-toolchain and QEMU - you do not + get any of the other mentioned benefits had you run the ADT Installer script. + Use the toolchain from within the Build Directory: + If you already have a + Build Directory, + you can build the cross-toolchain within the directory. + However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you + do not get any of the other benefits without taking separate steps. + + + +
+ Using the ADT Installer + + + To run the ADT Installer, you need to get the ADT Installer tarball, be sure + you have the necessary host development packages that support the ADT Installer, + and then run the ADT Installer Script. + + + + For a list of the host packages needed to support ADT installation and use, see the + "ADT Installer Extras" lists in the + "Required Packages for the Host Development System" section + of the Yocto Project Reference Manual. + + +
+ Getting the ADT Installer Tarball + + + The ADT Installer is contained in the ADT Installer tarball. + You can get the tarball using either of these methods: + + Download the Tarball: + You can download the tarball from + into + any directory. + Build the Tarball: + You can use + BitBake + to generate the tarball inside an existing + Build Directory. + + If you use BitBake to generate the ADT Installer + tarball, you must source the + environment setup script + (&OE_INIT_FILE; + or + oe-init-build-env-memres) + located in the Source Directory before running the + bitbake command that creates the + tarball. + The following example commands establish + the + Source Directory, + check out the current release branch, set up the + build environment while also creating the default + Build Directory, and run the + bitbake command that results in the + tarball + poky/build/tmp/deploy/sdk/adt_installer.tar.bz2: + + Before using BitBake to build the ADT tarball, be + sure to make sure your + local.conf file is properly + configured. + + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; + $ source &OE_INIT_FILE; + $ bitbake adt-installer + + + +
+ +
+ Configuring and Running the ADT Installer Script + + + Before running the ADT Installer script, you need to unpack the tarball. + You can unpack the tarball in any directory you wish. + For example, this command copies the ADT Installer tarball from where + it was built into the home directory and then unpacks the tarball into + a top-level directory named adt-installer: + + $ cd ~ + $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME + $ tar -xjf adt_installer.tar.bz2 + + Unpacking it creates the directory adt-installer, + which contains the ADT Installer script (adt_installer) + and its configuration file (adt_installer.conf). + + + + Before you run the script, however, you should examine the ADT Installer configuration + file and be sure you are going to get what you want. + Your configurations determine which kernel and filesystem image are downloaded. + + + + The following list describes the configurations you can define for the ADT Installer. + For configuration values and restrictions, see the comments in + the adt-installer.conf file: + + + YOCTOADT_REPO: This area + includes the IPKG-based packages and the root filesystem upon which + the installation is based. + If you want to set up your own IPKG repository pointed to by + YOCTOADT_REPO, you need to be sure that the + directory structure follows the same layout as the reference directory + set up at . + Also, your repository needs to be accessible through HTTP. + YOCTOADT_TARGETS: The machine + target architectures for which you want to set up cross-development + environments. + YOCTOADT_QEMU: Indicates whether + or not to install the emulator QEMU. + YOCTOADT_NFS_UTIL: Indicates whether + or not to install user-mode NFS. + If you plan to use the Eclipse IDE Yocto plug-in against QEMU, + you should install NFS. + To boot QEMU images using our userspace NFS server, you need + to be running portmap or rpcbind. + If you are running rpcbind, you will also need to add the + -i option when rpcbind starts up. + Please make sure you understand the security implications of doing this. + You might also have to modify your firewall settings to allow + NFS booting to work. + YOCTOADT_ROOTFS_arch: The root + filesystem images you want to download from the + YOCTOADT_IPKG_REPO repository. + YOCTOADT_TARGET_SYSROOT_IMAGE_arch: The + particular root filesystem used to extract and create the target sysroot. + The value of this variable must have been specified with + YOCTOADT_ROOTFS_arch. + For example, if you downloaded both minimal and + sato-sdk images by setting + YOCTOADT_ROOTFS_arch + to "minimal sato-sdk", then YOCTOADT_ROOTFS_arch + must be set to either "minimal" or "sato-sdk". + + YOCTOADT_TARGET_SYSROOT_LOC_arch: The + location on the development host where the target sysroot is created. + + + + + + After you have configured the adt_installer.conf file, + run the installer using the following command: + + $ cd adt-installer + $ ./adt_installer + + Once the installer begins to run, you are asked to enter the + location for cross-toolchain installation. + The default location is + /opt/poky/release. + After either accepting the default location or selecting your + own location, you are prompted to run the installation script + interactively or in silent mode. + If you want to closely monitor the installation, + choose “I” for interactive mode rather than “S” for silent mode. + Follow the prompts from the script to complete the installation. + + + + Once the installation completes, the ADT, which includes the + cross-toolchain, is installed in the selected installation + directory. + You will notice environment setup files for the cross-toolchain + in the installation directory, and image tarballs in the + adt-installer directory according to your + installer configurations, and the target sysroot located + according to the + YOCTOADT_TARGET_SYSROOT_LOC_arch + variable also in your configuration file. + +
+
+ +
+ Using a Cross-Toolchain Tarball + + + If you want to simply install a cross-toolchain by hand, you can + do so by running the toolchain installer. + The installer includes the pre-built cross-toolchain, the + runqemu script, and support files. + If you use this method to install the cross-toolchain, you + might still need to install the target sysroot by installing and + extracting it separately. + For information on how to install the sysroot, see the + "Extracting the Root Filesystem" section. + + + + Follow these steps: + + Get your toolchain installer using one of the following methods: + + Go to + + and find the folder that matches your host + development system (i.e. i686 + for 32-bit machines or x86_64 + for 64-bit machines). + 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 + core-image-sato 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 x86_64 + folder and download the following installer: + + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + + Build your own toolchain installer. + For cases where you cannot use an installer + from the download area, you can build your own as + described in the + "Optionally Building a Toolchain Installer" + section. + + Once you have the installer, run it to install the toolchain: + + You must change the permissions on the toolchain + installer script so that it is executable. + + 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 ~/Downloads/. + + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + + The first thing the installer prompts you for is the + directory into which you want to install the toolchain. + The default directory used is + /opt/poky/&DISTRO;. + If you do not have write permissions for the directory + into which you are installing the toolchain, the + toolchain installer notifies you and exits. + Be sure you have write permissions in the directory and + run the installer again. + When the script finishes, the cross-toolchain is + installed. + You will notice environment setup files for the + cross-toolchain in the installation directory. + + + +
+ +
+ Using BitBake and the Build Directory + + + A final way of making the cross-toolchain available is to use BitBake + to generate the toolchain within an existing + Build Directory. + This method does not install the toolchain into the default + /opt directory. + As with the previous method, if you need to install the target sysroot, you must + do that separately as well. + + + + Follow these steps to generate the toolchain into the Build Directory: + + Set up the Build Environment: + Source the OpenEmbedded build environment setup + script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres) + located in the + Source Directory. + + Check your Local Configuration File: + At this point, you should be sure that the + MACHINE variable + in the local.conf file found in the + conf directory of the Build Directory + is set for the target architecture. + Comments within the local.conf file + list the values you can use for the + MACHINE variable. + + You can populate the Build Directory with the + cross-toolchains for more than a single architecture. + You just need to edit the MACHINE + variable in the local.conf file and + re-run the bitbake command. + + Generate the Cross-Toolchain: + Run bitbake meta-ide-support to + complete the cross-toolchain generation. + Once the bitbake command finishes, + the cross-toolchain is + generated and populated within the Build Directory. + You will notice environment setup files for the + cross-toolchain that contain the string + "environment-setup" in the + Build Directory's tmp folder. + Be aware that when you use this method to install the + toolchain, you still need to separately extract and install + the sysroot filesystem. + For information on how to do this, see the + "Extracting the Root Filesystem" section. + + + +
+
+ +
+ Setting Up the Cross-Development Environment + + + Before you can develop using the cross-toolchain, you need to set up the + cross-development environment by sourcing the toolchain's environment setup script. + If you used the ADT Installer or hand-installed cross-toolchain, + then you can find this script in the directory you chose for installation. + For this release, the default installation directory is + &YOCTO_ADTPATH_DIR;. + If you installed the toolchain in the + Build Directory, + you can find the environment setup + script for the toolchain in the Build Directory's tmp directory. + + + + Be sure to run the environment setup script that matches the + architecture for which you are developing. + Environment setup scripts begin with the string + "environment-setup" and include as part of their + name the architecture. + For example, the toolchain environment setup script for a 64-bit + IA-based architecture installed in the default installation directory + would be the following: + + &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux + + +
+ +
+ Securing Kernel and Filesystem Images + + + You will need to have a kernel and filesystem image to boot using your + hardware or the QEMU emulator. + Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem + as the target sysroot, you need to extract the root filesystem. + + +
+ Getting the Images + + + To get the kernel and filesystem images, you either have to build them or download + pre-built versions. + You can find examples for both these situations in the + "A Quick Test Run" section of + the Yocto Project Quick Start. + + + + The Yocto Project ships basic kernel and filesystem images for several + architectures (x86, x86-64, + mips, powerpc, and arm) + that you can use unaltered in the QEMU emulator. + These kernel images reside in the release + area - + and are ideal for experimentation using Yocto Project. + For information on the image types you can build using the OpenEmbedded build system, + see the + "Images" chapter in + the Yocto Project Reference Manual. + + + + If you are planning on developing against your image and you are not + building or using one of the Yocto Project development images + (e.g. core-image-*-dev), you must be sure to + include the development packages as part of your image recipe. + + + + Furthermore, if you plan on remotely deploying and debugging your + application from within the + Eclipse IDE, you must have an image that contains the Yocto Target Communication + Framework (TCF) agent (tcf-agent). + By default, the Yocto Project provides only one type of pre-built + image that contains the tcf-agent. + And, those images are SDK (e.g.core-image-sato-sdk). + + + + If you want to use a different image type that contains the tcf-agent, + you can do so one of two ways: + + Modify the conf/local.conf configuration in + the Build Directory + and then rebuild the image. + With this method, you need to modify the + EXTRA_IMAGE_FEATURES + variable to have the value of "tools-debug" before rebuilding the image. + Once the image is rebuilt, the tcf-agent will be included + in the image and is launched automatically after the boot. + Manually build the tcf-agent. + To build the agent, follow these steps: + + Be sure the ADT is installed as described in the + "Installing the ADT and Toolchains" section. + + Set up the cross-development environment as described in the + "Setting + Up the Cross-Development Environment" section. + Get the tcf-agent source code using + the following commands: + + $ git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git + $ cd org.eclipse.tcf.agent/agent + + Locate the + Makefile.inc file inside the + agent folder and modify it + for the cross-compilation environment by setting the + OPSYS and + MACHINE + variables according to your target. + + Use the cross-development tools to build the + tcf-agent. + Before you "Make" the file, be sure your cross-tools are set up first. + See the "Makefile-Based Projects" + section for information on how to make sure the cross-tools are set up + correctly. + If the build is successful, the tcf-agent output will + be obj/$(OPSYS)/$(MACHINE)/Debug/agent. + Deploy the agent into the image's root filesystem. + + + + +
+ +
+ Extracting the Root Filesystem + + + If you install your toolchain by hand or build it using BitBake and + you need a root filesystem, you need to extract it separately. + If you use the ADT Installer to install the ADT, the root + filesystem is automatically extracted and installed. + + + + Here are some cases where you need to extract the root filesystem: + + You want to boot the image using NFS. + + 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. + You want to develop your target application + using the root filesystem as the target sysroot. + + + + + + To extract the root filesystem, first source + the cross-development environment setup script. + If you built the toolchain in the Build Directory, you will find + the toolchain environment script in the + tmp directory. + If you installed the toolchain by hand, the environment setup + script is located in /opt/poky/&DISTRO;. + + + + After sourcing the environment script, use the + runqemu-extract-sdk command and provide the + filesystem image. + + + + Following is an example. + The second command sets up the environment. + In this case, the setup script is located in the + /opt/poky/&DISTRO; directory. + The third command extracts the root filesystem from a previously + built filesystem that is located in the + ~/Downloads directory. + Furthermore, this command extracts the root filesystem into the + qemux86-sato directory: + + $ 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 + + You could now point to the target sysroot at + qemux86-sato. + +
+
+ +
+ Optionally Building a Toolchain Installer + + + As an alternative to locating and downloading a toolchain installer, + you can build the toolchain installer one of two ways if you have a + Build Directory: + + + Use bitbake meta-toolchain. + This method requires you to still install the target + sysroot by installing and extracting it separately. + For information on how to install the sysroot, see the + "Extracting the Root Filesystem" + section. + + + Use bitbake image -c populate_sdk. + This method has significant advantages over the previous method + because it results in a toolchain installer that contains the + sysroot that matches your target root filesystem. + + + Another powerful feature is that the toolchain is + completely self-contained. + The binaries are linked against their own copy of + libc, 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 + populate_sdk archive. + + Another feature 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 gcc as a set of + compiler options. + Those options are set up by the environment script and + contained in variables like CC and LD. + 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. + + + + + + Remember, before using any BitBake command, you + must source the build environment setup script + (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres) + located in the Source Directory and you must make sure your + conf/local.conf variables are correct. + In particular, you need to be sure the + MACHINE + variable matches the architecture for which you are building and that + the + SDKMACHINE + 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). + + + + When the bitbake command completes, the toolchain + installer will be in + tmp/deploy/sdk in the Build Directory. + + 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 + IMAGE_INSTALL + variable inside your local.conf file to + install the appropriate library packages. + Following is an example using glibc static + development libraries: + + IMAGE_INSTALL_append = " glibc-staticdev" + + + +
+ +
+ diff --git a/documentation/adt-manual/adt-style.css b/documentation/adt-manual/adt-style.css new file mode 100644 index 0000000000..d722ad4b7f --- /dev/null +++ b/documentation/adt-manual/adt-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/adt-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/adt-manual/figures/adt-title.png b/documentation/adt-manual/figures/adt-title.png new file mode 100644 index 0000000000..6e71e41f1a Binary files /dev/null and b/documentation/adt-manual/figures/adt-title.png differ diff --git a/documentation/bsp-guide/bsp-guide-customization.xsl b/documentation/bsp-guide/bsp-guide-customization.xsl new file mode 100644 index 0000000000..3da37be06f --- /dev/null +++ b/documentation/bsp-guide/bsp-guide-customization.xsl @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl b/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl new file mode 100644 index 0000000000..1c80bee1cf --- /dev/null +++ b/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml new file mode 100644 index 0000000000..637a51211a --- /dev/null +++ b/documentation/bsp-guide/bsp-guide.xml @@ -0,0 +1,138 @@ + %poky; ] > + + + + + + + + + + + + Yocto Project Board Support Package Developer's Guide + + + + + Tom Zanussi + + Intel Corporation + + tom.zanussi@intel.com + + + Richard Purdie + + Linux Foundation + + richard.purdie@linuxfoundation.org + + + + + + 0.9 + 24 November 2010 + The initial document draft released with the Yocto Project 0.9 Release. + + + 1.0 + 6 April 2011 + Released with the Yocto Project 1.0 Release. + + + 1.0.1 + 23 May 2011 + Released with the Yocto Project 1.0.1 Release. + + + 1.1 + 6 October 2011 + Released with the Yocto Project 1.1 Release. + + + 1.2 + April 2012 + Released with the Yocto Project 1.2 Release. + + + 1.3 + October 2012 + Released with the Yocto Project 1.3 Release. + + + 1.4 + April 2013 + Released with the Yocto Project 1.4 Release. + + + 1.5 + October 2013 + Released with the Yocto Project 1.5 Release. + + + 1.5.1 + January 2014 + Released with the Yocto Project 1.5.1 Release. + + + 1.6 + April 2014 + Released with the Yocto Project 1.6 Release. + + + 1.7 + October 2014 + Released with the Yocto Project 1.7 Release. + + + 1.7.1 + January 2015 + Released with the Yocto Project 1.7.1 Release. + + + 1.7.2 + June 2015 + Released with the Yocto Project 1.7.2 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England & Wales as published by Creative Commons. + + + For the latest version of this manual associated with this + Yocto Project release, see the + Yocto Project Board Support Package (BSP) Developer's Guide + from the Yocto Project website. + + + + + + + + + + + diff --git a/documentation/bsp-guide/bsp-style.css b/documentation/bsp-guide/bsp-style.css new file mode 100644 index 0000000000..e407ca4a72 --- /dev/null +++ b/documentation/bsp-guide/bsp-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/bsp-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title { + background-position: bottom; + background-repeat: repeat-x; +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml new file mode 100644 index 0000000000..d4850234d1 --- /dev/null +++ b/documentation/bsp-guide/bsp.xml @@ -0,0 +1,1527 @@ + %poky; ] > + + + + Board Support Packages (BSP) - Developer's Guide + + + A Board Support Package (BSP) is a collection of information that + defines how to support a particular hardware device, set of devices, or + hardware platform. + The BSP includes information about the hardware features + present on the device and kernel configuration information along with any + additional hardware drivers required. + The BSP also lists any additional software + components required in addition to a generic Linux software stack for both + essential and optional platform features. + + + + This guide presents information about BSP Layers, defines a structure for components + so that BSPs follow a commonly understood layout, discusses how to customize + a recipe for a BSP, addresses BSP licensing, and provides information that + shows you how to create and manage a + BSP Layer using two Yocto Project + BSP Tools. + + +
+ BSP Layers + + + A BSP consists of a file structure inside a base directory. + Collectively, you can think of the base directory, its file structure, + and the contents as a BSP Layer. + Although not a strict requirement, layers in the Yocto Project use the + following well established naming convention: + + meta-bsp_name + + The string "meta-" is prepended to the machine or platform name, which is + "bsp_name" in the above form. + + + + To help understand the BSP layer concept, consider the BSPs that the + Yocto Project supports and provides with each release. + You can see the layers in the + Yocto Project Source Repositories + through a web interface at + . + 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. meta-minnow, + meta-raspberrypi, and + meta-intel). + Each of these layers is a repository unto itself and clicking on a + layer reveals information that includes two links from which you can choose + to set up a clone of the layer's repository on your local host system. + Here is an example that clones the Minnow Board BSP layer: + + $ git clone git://git.yoctoproject.org/meta-minnow + + For information on the BSP development workflow, see the + "Developing a Board Support Package (BSP)" + section in the Yocto Project Development Manual. + For more information on how to set up a local copy of source files + from a Git repository, see the + "Getting Set Up" + section also in the Yocto Project Development Manual. + + + + The layer's base directory (meta-bsp_name) is the root + of the BSP Layer. + This root is what you add to the + BBLAYERS + variable in the conf/bblayers.conf file found in the + Build Directory, + which is established after you run one of the OpenEmbedded build environment + setup scripts (i.e. + &OE_INIT_FILE; + and + oe-init-build-env-memres). + Adding the root allows the OpenEmbedded build system to recognize the BSP + definition and from it build an image. + Here is an example: + + BBLAYERS ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-yocto \ + /usr/local/src/yocto/meta-yocto-bsp \ + /usr/local/src/yocto/meta-mylayer \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-yocto \ + " + + + + + Some BSPs require additional layers on + top of the BSP's root layer in order to be functional. + For these cases, you also need to add those layers to the + BBLAYERS variable in order to build the BSP. + You must also specify in the "Dependencies" section of the BSP's + README file any requirements for additional + layers and, preferably, any + build instructions that might be contained elsewhere + in the README file. + + + + Some layers function as a layer to hold other BSP layers. + An example of this type of layer is the meta-intel layer. + The meta-intel layer contains many individual BSP layers. + + + + For more detailed information on layers, see the + "Understanding and Creating Layers" + section of the Yocto Project Development Manual. + +
+ + +
+ Example Filesystem Layout + + + Providing a common form allows end-users to understand and become familiar + with the layout. + A common format also encourages standardization of software support of hardware. + + + + The proposed form does have elements that are specific to the + OpenEmbedded build system. + It is intended that this information can be + used by other build systems besides the OpenEmbedded build system + and that it will be simple + to extract information and convert it to other formats if required. + The OpenEmbedded build system, through its standard layers mechanism, can directly + accept the format described as a layer. + The BSP captures all + the hardware-specific details in one place in a standard format, which is + useful for any person wishing to use the hardware platform regardless of + the build system they are using. + + + + The BSP specification does not include a build system or other tools - + it is concerned with the hardware-specific components only. + At the end-distribution point, you can ship the BSP combined with a build system + and other tools. + However, it is important to maintain the distinction that these + are separate components that happen to be combined in certain end products. + + + + Before looking at the common form for the file structure inside a BSP Layer, + you should be aware that some requirements do exist in order for a BSP to + be considered compliant with the Yocto Project. + For that list of requirements, see the + "Released BSP Requirements" + section. + + + + Below is the common form for the file structure inside a BSP Layer. + While you can use this basic form for the standard, realize that the actual structures + for specific BSPs could differ. + + + meta-bsp_name/ + meta-bsp_name/bsp_license_file + meta-bsp_name/README + meta-bsp_name/README.sources + meta-bsp_name/binary/bootable_images + meta-bsp_name/conf/layer.conf + meta-bsp_name/conf/machine/*.conf + meta-bsp_name/recipes-bsp/* + meta-bsp_name/recipes-core/* + meta-bsp_name/recipes-graphics/* + meta-bsp_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend + + + + + Below is an example of the Crown Bay BSP: + + + meta-crownbay/COPYING.MIT + meta-crownbay/README + meta-crownbay/README.sources + meta-crownbay/binary/ + meta-crownbay/conf/ + meta-crownbay/conf/layer.conf + meta-crownbay/conf/machine/ + meta-crownbay/conf/machine/crownbay.conf + meta-crownbay/conf/machine/crownbay-noemgd.conf + meta-crownbay/recipes-bsp/ + meta-crownbay/recipes-bsp/formfactor/ + meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend + meta-crownbay/recipes-bsp/formfactor/formfactor/ + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/ + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig + meta-crownbay/recipes-graphics/ + meta-crownbay/recipes-graphics/xorg-xserver/ + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/ + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/ + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf + meta-crownbay/recipes-kernel/ + meta-crownbay/recipes-kernel/linux/ + meta-crownbay/recipes-kernel/linux/linux-yocto-dev.bbappend + meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.10.bbappend + meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend + + + + + The following sections describe each part of the proposed BSP format. + + +
+ License Files + + + You can find these files in the BSP Layer at: + + meta-bsp_name/bsp_license_file + + + + + These optional files satisfy licensing requirements for the BSP. + The type or types of files here can vary depending on the licensing requirements. + For example, in the Crown Bay BSP all licensing requirements are handled with the + COPYING.MIT file. + + + + Licensing files can be MIT, BSD, GPLv*, and so forth. + These files are recommended for the BSP but are optional and totally up to the BSP developer. + +
+ +
+ README File + + You can find this file in the BSP Layer at: + + meta-bsp_name/README + + + + + This file provides information on how to boot the live images that are optionally + included in the binary/ directory. + The README file also provides special information needed for + building the image. + + + + At a minimum, the README file must + contain a list of dependencies, such as the names of + any other layers on which the BSP depends and the name of + the BSP maintainer with his or her contact information. + +
+ +
+ README.sources File + + You can find this file in the BSP Layer at: + + meta-bsp_name/README.sources + + + + + This file provides information on where to locate the BSP source files. + For example, information provides where to find the sources that comprise + the images shipped with the BSP. + Information is also included to help you find the + Metadata + used to generate the images that ship with the BSP. + +
+ +
+ Pre-built User Binaries + + You can find these files in the BSP Layer at: + + meta-bsp_name/binary/bootable_images + + + + + This optional area contains useful pre-built kernels and user-space filesystem + images appropriate to the target system. + This directory typically contains graphical (e.g. Sato) and minimal live images + when the BSP tarball has been created and made available in the + Yocto Project website. + You can use these kernels and images to get a system running and quickly get started + on development tasks. + + + + The exact types of binaries present are highly hardware-dependent. + However, a README file should be present in the BSP Layer that explains how to use + the kernels and images with the target hardware. + If pre-built binaries are present, source code to meet licensing requirements must also + exist in some form. + +
+ +
+ Layer Configuration File + + You can find this file in the BSP Layer at: + + meta-bsp_name/conf/layer.conf + + + + + The conf/layer.conf file identifies the file structure as a + layer, identifies the + contents of the layer, and contains information about how the build + system should use it. + Generally, a standard boilerplate file such as the following works. + In the following example, you would replace "bsp" and + "_bsp" with the actual name + of the BSP (i.e. bsp_name from the example template). + + + + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have a recipes directory, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "bsp" + BBFILE_PATTERN_bsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_bsp = "6" + + + + + To illustrate the string substitutions, here are the corresponding statements + from the Crown Bay conf/layer.conf file: + + BBFILE_COLLECTIONS += "crownbay" + BBFILE_PATTERN_crownbay = "^${LAYERDIR}/" + BBFILE_PRIORITY_crownbay = "6" + + + + + This file simply makes + BitBake + aware of the recipes and configuration directories. + The file must exist so that the OpenEmbedded build system can recognize the BSP. + +
+ +
+ Hardware Configuration Options + + You can find these files in the BSP Layer at: + + meta-bsp_name/conf/machine/*.conf + + + + + The machine files bind together all the information contained elsewhere + in the BSP into a format that the build system can understand. + If the BSP supports multiple machines, multiple machine configuration files + can be present. + These filenames correspond to the values to which users have set the + MACHINE variable. + + + + These files define things such as the kernel package to use + (PREFERRED_PROVIDER + of virtual/kernel), the hardware drivers to + include in different types of images, any special software components + that are needed, any bootloader information, and also any special image + format requirements. + + + + Each BSP Layer requires at least one machine file. + However, you can supply more than one file. + + + + This crownbay.conf file could also include + a hardware "tuning" file that is commonly used to + define the package architecture and specify + optimization flags, which are carefully chosen to give best + performance on a given processor. + + + + Tuning files are found in the meta/conf/machine/include + directory within the + Source Directory. + For example, the ia32-base.inc file resides in the + meta/conf/machine/include directory. + + + + To use an include file, you simply include them in the machine configuration file. + For example, the Crown Bay BSP crownbay.conf contains the + following statements: + + require conf/machine/include/intel-core2-32-common.inc + require conf/machine/include/meta-intel.inc + require conf/machine/include/meta-intel-emgd.inc + + +
+ +
+ Miscellaneous BSP-Specific Recipe Files + + You can find these files in the BSP Layer at: + + meta-bsp_name/recipes-bsp/* + + + + + This optional directory contains miscellaneous recipe files for the BSP. + Most notably would be the formfactor files. + For example, in the Crown Bay BSP there is the + formfactor_0.0.bbappend 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 machconfig file. + In the Crown Bay example, two machconfig files + exist: one that supports the Intel® Embedded Media and Graphics + Driver (Intel® EMGD) and one that does not: + + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend + + + + + If a BSP does not have a formfactor entry, defaults are established according to + the formfactor configuration file that is installed by the main + formfactor recipe + meta/recipes-bsp/formfactor/formfactor_0.0.bb, + which is found in the + Source Directory. + +
+ +
+ Display Support Files + + You can find these files in the BSP Layer at: + + meta-bsp_name/recipes-graphics/* + + + + + This optional directory contains recipes for the BSP if it has + special requirements for graphics support. + All files that are needed for the BSP to support a display are kept here. + For example, the Crown Bay BSP's xorg.conf file + detects the graphics support needed (i.e. the Intel® Embedded Media + Graphics Driver (EMGD) or the Video Electronics Standards Association + (VESA) graphics): + + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf + + +
+ +
+ Linux Kernel Configuration + + You can find these files in the BSP Layer at: + + meta-bsp_name/recipes-kernel/linux/linux-yocto_*.bbappend + + + + + These files append your specific changes to the main kernel recipe you are using. + + + For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the + Source Directory + at meta/recipes-kernel/linux. + You can append your specific changes to the kernel recipe by using a + similarly named append file, which is located in the BSP Layer (e.g. + the meta-bsp_name/recipes-kernel/linux directory). + + + Suppose you are using the linux-yocto_3.10.bb recipe to build + the kernel. + In other words, you have selected the kernel in your + bsp_name.conf file by adding these types + of statements: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "3.10%" + + + When the preferred provider is assumed by default, the + PREFERRED_PROVIDER statement does not appear in the + bsp_name.conf file. + + You would use the linux-yocto_3.10.bbappend file to append + specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. + + + As an example, look at the existing Crown Bay BSP. + The append file used is: + + meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend + + 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 meta-intel + Git source repository. + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/crownbay" + KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb" + + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" + KMACHINE_crownbay-noemgd = "crownbay" + KBRANCH_crownbay-noemgd = "standard/crownbay" + KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb" + + LINUX_VERSION_crownbay = "3.10.35" + SRCREV_meta_crownbay = "b6e58b33dd427fe471f8827c83e311acdf4558a4" + SRCREV_machine_crownbay = "cee957655fe67826b2e827e2db41f156fa8f0cc4" + SRCREV_emgd_crownbay = "42d5e4548e8e79e094fa8697949eed4cf6af00a3" + + LINUX_VERSION_crownbay-noemgd = "3.10.35" + SRCREV_meta_crownbay-noemgd = "b6e58b33dd427fe471f8827c83e311acdf4558a4" + SRCREV_machine_crownbay-noemgd = "cee957655fe67826b2e827e2db41f156fa8f0cc4" + + SRC_URI_crownbay = "git://git.yoctoproject.org/linux-yocto-3.10.git;protocol=git;nocheckout=1;branch=${KBRANCH},${KMETA},emgd-1.18;name=machine,meta,emgd" + + This append file contains statements used to support the Crown Bay BSP. + The file defines machines using the + COMPATIBLE_MACHINE + variable and uses the + KMACHINE variable to + ensure the machine name used by the OpenEmbedded build system maps to the + machine name used by the Linux Yocto kernel. + The file also uses the optional + KBRANCH variable + to ensure the build process uses the standard/crownbay + kernel branch. + The + KERNEL_FEATURES + variable enables features specific to the kernel + (e.g. graphics support in this case). + The append file points to specific commits in the + Source Directory Git + repository and the meta Git repository branches to identify the + exact kernel needed to build the Crown Bay BSP. + Finally, the file includes the + SRC_URI + statement to locate the source files. + + + + One thing missing in this particular BSP, which you will typically need when + developing a BSP, is the kernel configuration file (.config) 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 + SRC_URI + statement in the append file. + + + + For example, suppose you had some configuration options in a file called + network_configs.cfg. + You can place that file inside a directory named linux-yocto and then add + a SRC_URI 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. + + SRC_URI += "file://network_configs.cfg" + + + + + 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 SRC_URI statement like the following in your append file: + + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + + + + + The FILESEXTRAPATHS + 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 SRC_URI. + The FILESEXTRAPATHS variable enables the build process to + find those configuration files. + + + + + Other methods exist to accomplish grouping and defining configuration options. + For example, if you are working with a local clone of the kernel repository, + you could checkout the kernel's meta branch, make your changes, + and then push the changes to the local bare clone of the kernel. + The result is that you directly add configuration options to the + meta branch for your BSP. + The configuration options will likely end up in that location anyway if the BSP gets + added to the Yocto Project. + + + + In general, however, the Yocto Project maintainers take care of moving the + SRC_URI-specified + configuration options to the kernel's meta branch. + Not only is it easier for BSP developers to not have to worry about putting those + configurations in the branch, but having the maintainers do it allows them to apply + 'global' knowledge about the kinds of common configuration options multiple BSPs in + the tree are typically using. + This allows for promotion of common configurations into common features. + + +
+
+ +
+ Requirements and Recommendations for Released BSPs + + + Certain requirements exist for a released BSP to be considered + compliant with the Yocto Project. + Additionally, recommendations also exist. + This section describes the requirements and recommendations for + released BSPs. + + +
+ Released BSP Requirements + + + Before looking at BSP requirements, you should consider the following: + + The requirements here assume the BSP layer is a well-formed, "legal" + layer that can be added to the Yocto Project. + For guidelines on creating a layer that meets these base requirements, see the + "BSP Layers" and the + "Understanding + and Creating Layers" in the Yocto Project Development Manual. + The requirements in this section apply regardless of how you + ultimately 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 + "Third Party BSP Release Process" + wiki page. + The requirements for the BSP as it is made available to a developer + are completely independent of the released form of the BSP. + For example, the BSP Metadata can be contained within a Git repository + and could have a directory structure completely different from what appears + in the officially released BSP layer. + It is not required that specific packages or package + modifications exist in the BSP layer, beyond the requirements for general + compliance with the Yocto Project. + For example, no requirement exists dictating that a specific kernel or + kernel version be used in a given BSP. + + + + + Following are the requirements for a released BSP that conforms to the + Yocto Project: + + Layer Name: + The BSP must have a layer name that follows the Yocto + Project standards. + For information on BSP layer names, see the + "BSP Layers" section. + + File System Layout: + When possible, use the same directory names in your + BSP layer as listed in the recipes.txt file. + In particular, you should place recipes + (.bb files) and recipe + modifications (.bbappend files) into + recipes-* subdirectories by functional area + as outlined in recipes.txt. + If you cannot find a category in recipes.txt + to fit a particular recipe, you can make up your own + recipes-* subdirectory. + You can find recipes.txt in the + meta directory of the + Source Directory, + or in the OpenEmbedded Core Layer + (openembedded-core) found at + . + + Within any particular recipes-* category, the layout + should match what is found in the OpenEmbedded Core + Git repository (openembedded-core) + or the Source Directory (poky). + In other words, make sure you place related files in appropriately + related recipes-* subdirectories specific to the + recipe's function, or within a subdirectory containing a set of closely-related + recipes. + The recipes themselves should follow the general guidelines + for recipes used in the Yocto Project found in the + "Yocto Recipe and Patch Style Guide". + + License File: + You must include a license file in the + meta-bsp_name directory. + This license covers the BSP Metadata as a whole. + You must specify which license to use since there is no + default license if one is not specified. + See the + COPYING.MIT + file for the Fish River Island 2 BSP in the meta-fri2 BSP layer + as an example. + README File: + You must include a README file in the + meta-bsp_name directory. + See the + README + file for the Fish River Island 2 BSP in the meta-fri2 BSP layer + as an example. + At a minimum, the README file should + contain the following: + + A brief description about the hardware the BSP + targets. + A list of all the dependencies + on which a BSP layer depends. + These dependencies are typically a list of required layers needed + to build the BSP. + However, the dependencies should also contain information regarding + any other dependencies the BSP might have. + Any required special licensing information. + For example, this information includes information on + special variables needed to satisfy a EULA, + or instructions on information needed to build or distribute + binaries built from the BSP Metadata. + The name and contact information for the + BSP layer maintainer. + This is the person to whom patches and questions should + be sent. + For information on how to find the right person, see the + "How to Submit a Change" + section in the Yocto Project Development Manual. + + Instructions on how to build the BSP using the BSP + layer. + Instructions on how to boot the BSP build from + the BSP layer. + Instructions on how to boot the binary images + contained in the binary directory, + if present. + Information on any known bugs or issues that users + should know about when either building or booting the BSP + binaries. + + README.sources File: + You must include a README.sources in the + meta-bsp_name directory. + This file specifies exactly where you can find the sources used to + generate the binary images contained in the + binary directory, if present. + See the + README.sources + file for the Fish River Island 2 BSP in the meta-fri2 BSP layer + as an example. + Layer Configuration File: + You must include a conf/layer.conf in the + meta-bsp_name directory. + This file identifies the meta-bsp_name + BSP layer as a layer to the build system. + Machine Configuration File: + You must include one or more + conf/machine/bsp_name.conf + files in the meta-bsp_name directory. + These configuration files define machine targets that can be built + using the BSP layer. + Multiple machine configuration files define variations of machine + configurations that are supported by the BSP. + If a BSP supports multiple machine variations, you need to + adequately describe each variation in the BSP + README file. + Do not use multiple machine configuration files to describe disparate + hardware. + If you do have very different targets, you should create separate + BSP layers for each target. + It is completely possible for a developer to structure the + working repository as a conglomeration of unrelated BSP + files, and to possibly generate BSPs targeted for release + from that directory using scripts or some other mechanism + (e.g. meta-yocto-bsp layer). + Such considerations are outside the scope of this document. + + + +
+ +
+ Released BSP Recommendations + + + Following are recommendations for a released BSP that conforms to the + Yocto Project: + + Bootable Images: + BSP releases + can contain one or more bootable images. + Including bootable images allows users to easily try out the BSP + on their own hardware. + In some cases, it might not be convenient to include a + bootable image. + In this case, you might want to make two versions of the + BSP available: one that contains binary images, and one + that does not. + The version that does not contain bootable images avoids + unnecessary download times for users not interested in the images. + + If you need to distribute a BSP and include bootable images or build kernel and + filesystems meant to allow users to boot the BSP for evaluation + purposes, you should put the images and artifacts within a + binary/ subdirectory located in the + meta-bsp_name directory. + If you do include a bootable image as part of the BSP and the image + was built by software covered by the GPL or other open source licenses, + it is your responsibility to understand + and meet all licensing requirements, which could include distribution + of source files. + Use a Yocto Linux Kernel: + Kernel recipes in the BSP should be based on a Yocto Linux kernel. + Basing your recipes on these kernels reduces the costs for maintaining + the BSP and increases its scalability. + See the Yocto Linux Kernel category in the + Source Repositories + for these kernels. + + +
+
+ +
+ Customizing a Recipe for a BSP + + + If you plan on customizing a recipe for a particular BSP, you need to do the + following: + + Create a .bbappend + file for the modified recipe. + For information on using append files, see the + "Using .bbappend Files" + section in the Yocto Project Development Manual. + + + Ensure your directory structure in the BSP layer + that supports your machine is such that it can be found + by the build system. + See the example later in this section for more information. + + + Put the append file in a directory whose name matches + the machine's name and is located in an appropriate + sub-directory inside the BSP layer (i.e. + recipes-bsp, recipes-graphics, + recipes-core, and so forth). + + Place the BSP-specific files in the directory named for + your machine inside the BSP layer. + + + + + + Following is a specific example to help you better understand the process. + Consider an example that customizes a recipe by adding + a BSP-specific configuration file named interfaces to the + init-ifupdown_1.0.bb recipe for machine "xyz". + Do the following: + + Edit the init-ifupdown_1.0.bbappend file so that it + contains the following: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + + The append file needs to be in the + meta-xyz/recipes-core/init-ifupdown directory. + + Create and place the new interfaces + configuration file in the BSP's layer here: + + meta-xyz/recipes-core/init-ifupdown/files/xyz/interfaces + + The + FILESEXTRAPATHS + variable in the append files extends the search path + the build system uses to find files during the build. + Consequently, for this example you need to have the + files directory in the same location + as your append file. + + +
+ +
+ BSP Licensing Considerations + + + In some cases, a BSP contains separately licensed Intellectual Property (IP) + for a component or components. + For these cases, you are required to accept the terms of a commercial or other + type of license that requires some kind of explicit End User License Agreement (EULA). + Once the license is accepted, the OpenEmbedded build system can then build and + include the corresponding component in the final BSP image. + If the BSP is available as a pre-built image, you can download the image after + agreeing to the license or EULA. + + + + You could find that some separately licensed components that are essential + for normal operation of the system might not have an unencumbered (or free) + substitute. + Without these essential components, the system would be non-functional. + Then again, you might find that other licensed components that are simply + 'good-to-have' or purely elective do have an unencumbered, free replacement + component that you can use rather than agreeing to the separately licensed component. + Even for components essential to the system, you might find an unencumbered component + that is not identical but will work as a less-capable version of the + licensed version in the BSP recipe. + + + + For cases where you can substitute a free component and still + maintain the system's functionality, the "Downloads" page from the + Yocto Project website's + makes available de-featured BSPs + that are completely free of any IP encumbrances. + For these cases, you can use the substitution directly and + without any further licensing requirements. + If present, these fully de-featured BSPs are named appropriately + different as compared to the names of the respective + encumbered BSPs. + If available, these substitutions are your + simplest and most preferred options. + Use of these substitutions of course assumes the resulting functionality meets + system requirements. + + + + If however, a non-encumbered version is unavailable or + it provides unsuitable functionality or quality, you can use an encumbered + version. + + + + A couple different methods exist within the OpenEmbedded build system to + satisfy the licensing requirements for an encumbered BSP. + The following list describes them in order of preference: + + Use the + LICENSE_FLAGS + variable to define the recipes that have commercial or other + types of specially-licensed packages: + For each of those recipes, you can + specify a matching license string in a + local.conf variable named + LICENSE_FLAGS_WHITELIST. + Specifying the matching license string signifies that you agree to the license. + Thus, the build system can build the corresponding recipe and include + the component in the image. + See the + "Enabling + Commercially Licensed Recipes" section in the Yocto Project Reference + Manual for details on how to use these variables. + If you build as you normally would, without + specifying any recipes in the + LICENSE_FLAGS_WHITELIST, the build stops and + provides you with the list of recipes that you have + tried to include in the image that need entries in + the LICENSE_FLAGS_WHITELIST. + Once you enter the appropriate license flags into the whitelist, + restart the build to continue where it left off. + During the build, the prompt will not appear again + since you have satisfied the requirement. + Once the appropriate license flags are on the white list + in the LICENSE_FLAGS_WHITELIST variable, you + can build the encumbered image with no change at all + to the normal build process. + Get a pre-built version of the BSP: + You can get this type of BSP by visiting the + "Downloads" page of the + Yocto Project website. + You can download BSP tarballs that contain proprietary components + after agreeing to the licensing + requirements of each of the individually encumbered + packages as part of the download process. + Obtaining the BSP this way allows you to access an encumbered + image immediately after agreeing to the + click-through license agreements presented by the + website. + Note that if you want to build the image + yourself using the recipes contained within the BSP + tarball, you will still need to create an + appropriate LICENSE_FLAGS_WHITELIST to match the + encumbered recipes in the BSP. + + + + + Pre-compiled images are bundled with + a time-limited kernel that runs for a + predetermined amount of time (10 days) before it forces + the system to reboot. + This limitation is meant to discourage direct redistribution + of the image. + You must eventually rebuild the image if you want to remove this restriction. + +
+ +
+ Using the Yocto Project's BSP Tools + + + The Yocto Project includes a couple of tools that enable + you to create a BSP layer + from scratch and do basic configuration and maintenance + of the kernel without ever looking at a Metadata file. + These tools are yocto-bsp and yocto-kernel, + respectively. + + + + The following sections describe the common location and help features as well + as provide details for the + yocto-bsp and yocto-kernel tools. + + +
+ Common Features + + + Designed to have a command interface somewhat like + Git, each + tool is structured as a set of sub-commands under a + top-level command. + The top-level command (yocto-bsp + or yocto-kernel) itself does + nothing but invoke or provide help on the sub-commands + it supports. + + + + Both tools reside in the scripts/ subdirectory + of the Source Directory. + Consequently, to use the scripts, you must source the + environment just as you would when invoking a build: + + $ source oe-init-build-env build_dir + + + + + The most immediately useful function is to get help on both tools. + The built-in help system makes it easy to drill down at + any time and view the syntax required for any specific command. + Simply enter the name of the command with the help + switch: + + $ yocto-bsp help + Usage: + + Create a customized Yocto BSP layer. + + usage: yocto-bsp [--version] [--help] COMMAND [ARGS] + + Current 'yocto-bsp' commands are: + create Create a new Yocto BSP + list List available values for options and BSP properties + + See 'yocto-bsp 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 + -D, --debug output debug information + + + + + Similarly, entering just the name of a sub-command shows the detailed usage + for that sub-command: + + $ yocto-bsp create + + 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>] + + 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 + the top-level directory specified as 'meta-bsp-name'. The -o option + can be used to place the BSP layer in a directory with a different + name and location. + + ... + + + + + For any sub-command, you can use the word "help" option just before the + sub-command to get more extensive documentation: + + $ yocto-bsp help create + + NAME + yocto-bsp create - Create a new Yocto BSP + + SYNOPSIS + yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] + [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] + + DESCRIPTION + 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 the top-level directory specified as + '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'. + + ... + + + + + Now that you know where these two commands reside and how to access information + on them, you should find it relatively straightforward to discover the commands + necessary to create a BSP and perform basic kernel maintenance on that BSP using + the tools. + + You can also use the yocto-layer tool to create + a "generic" layer. + For information on this tool, see the + "Creating a General Layer Using the yocto-layer Script" + section in the Yocto Project Development Guide. + + + + + The next sections provide a concrete starting point to expand on a few points that + might not be immediately obvious or that could use further explanation. + +
+ + +
+ Creating a new BSP Layer Using the yocto-bsp Script + + + The yocto-bsp script creates a new + BSP layer for any architecture supported + by the Yocto Project, as well as QEMU versions of the same. + The default mode of the script's operation is to prompt you for information needed + to generate the BSP layer. + + + + For the current set of BSPs, the script prompts you for various important + parameters such as: + + The kernel to use + The branch of that kernel to use (or re-use) + Whether or not to use X, and if so, which drivers to use + Whether to turn on SMP + Whether the BSP has a keyboard + Whether the BSP has a touchscreen + Remaining configurable items associated with the BSP + + + + + You use the yocto-bsp create sub-command to create + a new BSP layer. + This command requires you to specify a particular kernel architecture + (karch) on which to base the BSP. + Assuming you have sourced the environment, you can use the + yocto-bsp list karch sub-command to list the + architectures available for BSP creation as follows: + + $ yocto-bsp list karch + Architectures available: + powerpc + i386 + x86_64 + arm + qemu + mips + + + + + The remainder of this section presents an example that uses + myarm as the machine name and qemu + as the machine architecture. + Of the available architectures, qemu is the only architecture + that causes the script to prompt you further for an actual architecture. + In every other way, this architecture is representative of how creating a BSP for + an actual machine would work. + The reason the example uses this architecture is because it is an emulated architecture + and can easily be followed without requiring actual hardware. + + + + As the yocto-bsp create command runs, default values for + the prompts appear in brackets. + Pressing enter without supplying anything on the command line or pressing enter + with an invalid response causes the script to accept the default value. + Once the script completes, the new meta-myarm BSP layer + is created in the current working directory. + This example assumes you have sourced the + &OE_INIT_FILE; + setup script. + + + + Following is the complete example: + + $ 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) + 3 + Would you like to use the default (3.10) kernel? (y/n) [default: y] y + Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y] + Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.10.git... + Please choose a machine branch to base your new BSP branch on: [default: standard/base] + 1) standard/arm-versatile-926ejs + 2) standard/base + 3) standard/beagleboard + 4) standard/beaglebone + 5) standard/ck + 6) standard/crownbay + 7) standard/edgerouter + 8) standard/emenlow + 9) standard/fri2 + 10) standard/fsl-mpc8315e-rdb + 11) standard/mti-malta32 + 12) standard/mti-malta64 + 13) standard/qemuppc + 14) standard/routerstationpro + 15) standard/sys940x + 1 + 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 + + Take a closer look at the example now: + + For the QEMU architecture, + the script first prompts you for which emulated architecture to use. + In the example, we use the ARM architecture. + + The script then prompts you for the kernel. + The default 3.14 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. + Next, the script asks whether you would like to have a new + branch created especially for your BSP in the local + Linux Yocto Kernel + Git repository . + If not, then the script re-uses an existing branch. + In this example, the default (or "yes") is accepted. + Thus, a new branch is created for the BSP rather than using a common, shared + branch. + The new branch is the branch committed to for any patches you might later add. + The reason a new branch is the default is that typically + new BSPs do require BSP-specific patches. + The tool thus assumes that most of time a new branch is required. + + Regardless of which choice you make in the previous step, + you are now given the opportunity to select a particular machine branch on + which to base your new BSP-specific machine branch + (or to re-use if you had elected to not create a new branch). + Because this example is generating an ARM-based BSP, the example + uses #1 at the prompt, which selects the ARM-versatile branch. + + The remainder of the prompts are routine. + Defaults are accepted for each. + By default, the script creates the new BSP Layer in the + current working directory of the + Source Directory, + (i.e. poky/build). + + + + + + Once the BSP Layer is created, you must add it to your + bblayers.conf file. + Here is an example: + + BBLAYERS = ? " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-yocto \ + /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 \ + " + + Adding the layer to this file allows the build system to build the BSP and + the yocto-kernel tool to be able to find the layer and + other Metadata it needs on which to operate. + +
+ +
+ Managing Kernel Patches and Config Items with yocto-kernel + + + Assuming you have created a BSP Layer using + + yocto-bsp and you added it to your + BBLAYERS + variable in the bblayers.conf file, you can now use + the yocto-kernel script to add patches and configuration + items to the BSP's kernel. + + + + The yocto-kernel script allows you to add, remove, and list patches + and kernel config settings to a BSP's kernel + .bbappend file. + All you need to do is use the appropriate sub-command. + Recall that the easiest way to see exactly what sub-commands are available + is to use the yocto-kernel built-in help as follows: + + $ yocto-kernel + 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 + config rm Remove bare kernel config options from a BSP + patch list List the patches associated with a BSP + patch add Patch the Yocto kernel for a BSP + patch rm Remove patches from a BSP + feature list List the features used by a BSP + feature add Have a BSP use a feature + feature rm Have a BSP stop using a feature + features list List the features available to BSPs + 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 + -D, --debug output debug information + + + + + The yocto-kernel patch add sub-command allows you to add a + patch to a BSP. + The following example adds two patches to the myarm BSP: + + $ yocto-kernel patch add myarm ~/test.patch + Added patches: + test.patch + + $ yocto-kernel patch add myarm ~/yocto-testmod.patch + Added patches: + yocto-testmod.patch + + Although the previous example adds patches one at a time, it is possible + to add multiple patches at the same time. + + + + You can verify patches have been added by using the + yocto-kernel patch list sub-command. + Here is an example: + + $ yocto-kernel patch list myarm + The current set of machine-specific patches for myarm is: + 1) test.patch + 2) yocto-testmod.patch + + + + + You can also use the yocto-kernel script to + remove a patch using the yocto-kernel patch rm sub-command. + Here is an example: + + $ yocto-kernel patch rm myarm + Specify the patches to remove: + 1) test.patch + 2) yocto-testmod.patch + 1 + Removed patches: + test.patch + + + + + Again, using the yocto-kernel patch list sub-command, + you can verify that the patch was in fact removed: + + $ yocto-kernel patch list myarm + The current set of machine-specific patches for myarm is: + 1) yocto-testmod.patch + + + + + In a completely similar way, you can use the yocto-kernel config add + sub-command to add one or more kernel config item settings to a BSP. + The following commands add a couple of config items to the + myarm BSP: + + $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y + Added items: + CONFIG_MISC_DEVICES=y + + $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y + Added items: + CONFIG_YOCTO_TESTMOD=y + + Although the previous example adds config items one at a time, it is possible + to add multiple config items at the same time. + + + + You can list the config items now associated with the BSP. + Doing so shows you the config items you added as well as others associated + with the BSP: + + $ yocto-kernel config list myarm + The current set of machine-specific kernel config items for myarm is: + 1) CONFIG_MISC_DEVICES=y + 2) CONFIG_YOCTO_TESTMOD=y + + + + + Finally, you can remove one or more config items using the + yocto-kernel config rm sub-command in a manner + completely analogous to yocto-kernel patch rm. + +
+
+
diff --git a/documentation/bsp-guide/figures/bsp-title.png b/documentation/bsp-guide/figures/bsp-title.png new file mode 100644 index 0000000000..f624dd4f94 Binary files /dev/null and b/documentation/bsp-guide/figures/bsp-title.png differ diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml new file mode 100644 index 0000000000..64504299cc --- /dev/null +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -0,0 +1,9738 @@ + %poky; ] > + + + +Common Tasks + + This chapter describes fundamental procedures such as creating layers, + adding new software packages, extending or customizing images, + porting work to new hardware (adding a new machine), and so forth. + You will find that the procedures documented here occur often in the + development cycle using the Yocto Project. + + +
+ Understanding and Creating Layers + + + The OpenEmbedded build system supports organizing + Metadata into multiple layers. + Layers allow you to isolate different types of customizations from + each other. + You might find it tempting to keep everything in one layer when + working on a single project. + However, the more modular your Metadata, the easier + it is to cope with future changes. + + + + To illustrate how layers are used to keep things modular, consider + machine customizations. + These types of customizations typically reside in a special layer, + rather than a general layer, called a Board Support Package (BSP) + Layer. + Furthermore, the machine customizations should be isolated from + recipes and Metadata that support a new GUI environment, + for example. + This situation gives you a couple of layers: one for the machine + configurations, and one for the GUI environment. + It is important to understand, however, that the BSP layer can + still make machine-specific additions to recipes within the GUI + environment layer without polluting the GUI layer itself + with those machine-specific changes. + You can accomplish this through a recipe that is a BitBake append + (.bbappend) file, which is described later + in this section. + + + + + +
+ Layers + + + The Source Directory + contains both general layers and BSP + layers right out of the box. + You can easily identify layers that ship with a + Yocto Project release in the Source Directory by their + folder names. + Folders that represent layers typically have names that begin with + the string meta-. + + It is not a requirement that a layer name begin with the + prefix meta-, but it is a commonly + accepted standard in the Yocto Project community. + + For example, when you set up the Source Directory structure, + you will see several layers: + meta, + meta-skeleton, + meta-selftest, + meta-yocto, and + meta-yocto-bsp. + Each of these folders represents a distinct layer. + + + + As another example, if you set up a local copy of the + meta-intel Git repository + and then explore the folder of that general layer, + you will discover many Intel-specific BSP layers inside. + For more information on BSP layers, see the + "BSP Layers" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide. + +
+ +
+ Creating Your Own Layer + + + It is very easy to create your own layers to use with the + OpenEmbedded build system. + The Yocto Project ships with scripts that speed up creating + general layers and BSP layers. + This section describes the steps you perform by hand to create + a layer so that you can better understand them. + For information about the layer-creation scripts, see the + "Creating a New BSP Layer Using the yocto-bsp Script" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide and the + "Creating a General Layer Using the yocto-layer Script" + section further down in this manual. + + + + Follow these general steps to create your layer: + + Check Existing Layers: + Before creating a new layer, you should be sure someone + has not already created a layer containing the Metadata + you need. + You can see the + OpenEmbedded Metadata Index + for a list of layers from the OpenEmbedded community + that can be used in the Yocto Project. + + Create a Directory: + Create the directory for your layer. + While not strictly required, prepend the name of the + folder with the string meta-. + For example: + + meta-mylayer + meta-GUI_xyz + meta-mymachine + + + Create a Layer Configuration + File: + Inside your new layer folder, you need to create a + conf/layer.conf file. + It is easiest to take an existing layer configuration + file and copy that to your layer's + conf directory and then modify the + file as needed. + The + meta-yocto-bsp/conf/layer.conf file + demonstrates the required syntax: + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "yoctobsp" + BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_yoctobsp = "5" + LAYERVERSION_yoctobsp = "3" + + Here is an explanation of the example: + + The configuration and + classes directory is appended to + BBPATH. + + All non-distro layers, which include all BSP + layers, are expected to append the layer + directory to the + BBPATH. + On the other hand, distro layers, such as + meta-yocto, can choose + to enforce their own precedence over + BBPATH. + For an example of that syntax, see the + layer.conf file for + the meta-yocto layer. + + The recipes for the layers are + appended to + BBFILES. + + The + BBFILE_COLLECTIONS + variable is then appended with the layer name. + + The + BBFILE_PATTERN + variable is set to a regular expression and is + used to match files from + BBFILES into a particular + layer. + In this case, + LAYERDIR + is used to make BBFILE_PATTERN match within the + layer's path. + The + BBFILE_PRIORITY + variable then assigns a priority to the layer. + Applying priorities is useful in situations + where the same recipe might appear in multiple + layers and allows you to choose the layer + that takes precedence. + The + LAYERVERSION + variable optionally specifies the version of a + layer as a single number. + + Note the use of the + LAYERDIR + variable, which expands to the directory of the current + layer. + Through the use of the BBPATH + variable, BitBake locates class files + (.bbclass), + configuration files, and files that are included + with include and + require statements. + For these cases, BitBake uses the first file that + matches the name found in BBPATH. + This is similar to the way the PATH + variable is used for binaries. + It is recommended, therefore, that you use unique + class and configuration + filenames in your custom layer. + Add Content: Depending + on the type of layer, add the content. + If the layer adds support for a machine, add the machine + configuration in a conf/machine/ + file within the layer. + If the layer adds distro policy, add the distro + configuration in a conf/distro/ + file within the layer. + If the layer introduces new recipes, put the recipes + you need in recipes-* + subdirectories within the layer. + In order to be compliant with the Yocto Project, + a layer must contain a + README file. + + + +
+ +
+ Best Practices to Follow When Creating Layers + + + To create layers that are easier to maintain and that will + not impact builds for other machines, you should consider the + information in the following sections. + + +
+ Avoid "Overlaying" Entire Recipes + + + Avoid "overlaying" entire recipes from other layers in your + configuration. + In other words, do not copy an entire recipe into your + layer and then modify it. + Rather, use an append file (.bbappend) + to override + only those parts of the original recipe you need to modify. + +
+ +
+ Avoid Duplicating Include Files + + + Avoid duplicating include files. + Use append files (.bbappend) + for each recipe + that uses an include file. + Or, if you are introducing a new recipe that requires + the included file, use the path relative to the original + layer directory to refer to the file. + For example, use + require recipes-core/somepackage/somefile.inc + instead of require somefile.inc. + If you're finding you have to overlay the include file, + it could indicate a deficiency in the include file in + the layer to which it originally belongs. + If this is the case, you need to address that deficiency + instead of overlaying the include file. + + + + For example, consider how support plug-ins for the Qt 4 + database are configured. + The Source Directory does not have MySQL or PostgreSQL. + However, OpenEmbedded's layer meta-oe + does. + Consequently, meta-oe uses + append files to modify the + QT_SQL_DRIVER_FLAGS variable to + enable the appropriate plug-ins. + This variable was added to the qt4.inc + include file in the Source Directory specifically to allow + the meta-oe layer to be able to control + which plug-ins are built. + +
+ +
+ Structure Your Layers + + + Proper use of overrides within append files and placement + of machine-specific files within your layer can ensure that + a build is not using the wrong Metadata and negatively + impacting a build for a different machine. + Following are some examples: + + Modifying Variables to Support + a Different Machine: + Suppose you have a layer named + meta-one that adds support + for building machine "one". + To do so, you use an append file named + base-files.bbappend and + create a dependency on "foo" by altering the + DEPENDS + variable: + + DEPENDS = "foo" + + The dependency is created during any build that + includes the layer + meta-one. + However, you might not want this dependency + for all machines. + For example, suppose you are building for + machine "two" but your + bblayers.conf file has the + meta-one layer included. + During the build, the + base-files for machine + "two" will also have the dependency on + foo. + To make sure your changes apply only when + building machine "one", use a machine override + with the DEPENDS statement: + + DEPENDS_one = "foo" + + You should follow the same strategy when using + _append and + _prepend operations: + + DEPENDS_append_one = " foo" + DEPENDS_prepend_one = "foo " + + 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: + + DEPENDS_append_powerpc64 = " libpfm4" + + + Avoiding "+=" and "=+" and using + machine-specific + _append + and _prepend operations + is recommended as well. + + Place Machine-Specific Files + in Machine-Specific Locations: + When you have a base recipe, such as + base-files.bb, that + contains a + SRC_URI + statement to a file, you can use an append file + to cause the build to use your own version of + the file. + For example, an append file in your layer at + meta-one/recipes-core/base-files/base-files.bbappend + could extend + FILESPATH + using + FILESEXTRAPATHS + as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" + + The build for machine "one" will pick up your + machine-specific file as long as you have the + file in + meta-one/recipes-core/base-files/base-files/. + However, if you are building for a different + machine and the + bblayers.conf file includes + the meta-one layer and + the location of your machine-specific file is + the first location where that file is found + according to FILESPATH, + builds for all machines will also use that + machine-specific file. + You can make sure that a machine-specific + file is used for a particular machine by putting + the file in a subdirectory specific to the + machine. + For example, rather than placing the file in + meta-one/recipes-core/base-files/base-files/ + as shown above, put it in + meta-one/recipes-core/base-files/base-files/one/. + Not only does this make sure the file is used + only when building for machine "one", but the + build process locates the file more quickly. + In summary, you need to place all files + referenced from SRC_URI + in a machine-specific subdirectory within the + layer in order to restrict those files to + machine-specific builds. + + +
+ +
+ Other Recommendations + + + We also recommend the following: + + Store custom layers in a Git repository + that uses the + meta-layer_name format. + + Clone the repository alongside other + meta directories in the + Source Directory. + + + Following these recommendations keeps your Source Directory and + its configuration entirely inside the Yocto Project's core + base. + +
+
+ +
+ Enabling Your Layer + + + Before the OpenEmbedded build system can use your new layer, + you need to enable it. + To enable your layer, simply add your layer's path to the + BBLAYERS + variable in your conf/bblayers.conf file, + which is found in the + Build Directory. + The following example shows how to enable a layer named + meta-mylayer: + + LCONF_VERSION = "6" + + BBPATH = "${TOPDIR}" + BBFILES ?= "" + + BBLAYERS ?= " \ + $HOME/poky/meta \ + $HOME/poky/meta-yocto \ + $HOME/poky/meta-yocto-bsp \ + $HOME/poky/meta-mylayer \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + $HOME/poky/meta \ + $HOME/poky/meta-yocto \ + " + + + + + BitBake parses each conf/layer.conf file + as specified in the BBLAYERS variable + within the conf/bblayers.conf file. + During the processing of each + conf/layer.conf file, BitBake adds the + recipes, classes and configurations contained within the + particular layer to the source directory. + +
+ +
+ Using .bbappend Files + + + Recipes used to append Metadata to other recipes are called + BitBake append files. + BitBake append files use the .bbappend file + type suffix, while the corresponding recipes to which Metadata + is being appended use the .bb file type + suffix. + + + + A .bbappend file allows your layer to make + additions or changes to the content of another layer's recipe + without having to copy the other recipe into your layer. + Your .bbappend file resides in your layer, + while the main .bb recipe file to + which you are appending Metadata resides in a different layer. + + + + Append files must have the same root names as their corresponding + recipes. + For example, the append file + someapp_&DISTRO;.bbappend must apply to + someapp_&DISTRO;.bb. + This means the original recipe and append file names are version + number-specific. + If the corresponding recipe is renamed to update to a newer + version, the corresponding .bbappend file must + be renamed (and possibly updated) as well. + During the build process, BitBake displays an error on starting + if it detects a .bbappend file that does + not have a corresponding recipe with a matching name. + See the + BB_DANGLINGAPPENDS_WARNONLY + variable for information on how to handle this error. + + + + Being able to append information to an existing recipe not only + avoids duplication, but also automatically applies recipe + changes in a different layer to your layer. + If you were copying recipes, you would have to manually merge + changes as they occur. + + + + As an example, consider the main formfactor recipe and a + corresponding formfactor append file both from the + Source Directory. + Here is the main formfactor recipe, which is named + formfactor_0.0.bb and located in the + "meta" layer at + meta/recipes-bsp/formfactor: + + SUMMARY = "Device formfactor information" + SECTION = "base" + LICENSE = "MIT" + LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \ + file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" + PR = "r45" + + SRC_URI = "file://config file://machconfig" + S = "${WORKDIR}" + + PACKAGE_ARCH = "${MACHINE_ARCH}" + INHIBIT_DEFAULT_DEPS = "1" + + do_install() { + # Install file only if it has contents + install -d ${D}${sysconfdir}/formfactor/ + install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ + if [ -s "${S}/machconfig" ]; then + install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ + fi + } + + In the main recipe, note the + SRC_URI + variable, which tells the OpenEmbedded build system where to + find files during the build. + + + + Following is the append file, which is named + formfactor_0.0.bbappend and is from the + Crown Bay BSP Layer named + meta-intel/meta-crownbay. + The file is in recipes-bsp/formfactor: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + + + + By default, the build system uses the + FILESPATH + variable to locate files. + This append file extends the locations by setting the + FILESEXTRAPATHS + variable. + Setting this variable in the .bbappend + file is the most reliable and recommended method for adding + directories to the search path used by the build system + to find files. + + + + The statement in this example extends the directories to include + ${THISDIR}/${PN}, + which resolves to a directory named + formfactor in the same directory + in which the append file resides (i.e. + meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor. + 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. + + + + Using the immediate expansion assignment operator + := is important because of the reference to + THISDIR. + The trailing colon character is important as it ensures that + items in the list remain colon-separated. + + + BitBake automatically defines the + THISDIR variable. + You should never set this variable yourself. + Using "_prepend" ensures your path will + be searched prior to other paths in the final list. + + + + Also, not all append files add extra files. + Many append files simply exist to add build options + (e.g. systemd). + For these cases, it is not necessary to use the + "_prepend" part of the statement. + + + +
+ +
+ Prioritizing Your Layer + + + Each layer is assigned a priority value. + Priority values control which layer takes precedence if there + are recipe files with the same name in multiple layers. + For these cases, the recipe file from the layer with a higher + priority number takes precedence. + Priority values also affect the order in which multiple + .bbappend files for the same recipe are + applied. + You can either specify the priority manually, or allow the + build system to calculate it based on the layer's dependencies. + + + + To specify the layer's priority manually, use the + BBFILE_PRIORITY + variable. + For example: + + BBFILE_PRIORITY_mylayer = "1" + + + + + It is possible for a recipe with a lower version number + PV + in a layer that has a higher priority to take precedence. + Also, the layer priority does not currently affect the + precedence order of .conf + or .bbclass files. + Future versions of BitBake might address this. + +
+ +
+ Managing Layers + + + You can use the BitBake layer management tool to provide a view + into the structure of recipes across a multi-layer project. + Being able to generate output that reports on configured layers + with their paths and priorities and on + .bbappend files and their applicable + recipes can help to reveal potential problems. + + + + Use the following form when running the layer management tool. + + $ bitbake-layers command [arguments] + + The following list describes the available commands: + + help: + Displays general help or help on a specified command. + + show-layers: + Shows the current configured layers. + + show-recipes: + Lists available recipes and the layers that provide them. + + show-overlayed: + Lists overlayed recipes. + A recipe is overlayed when a recipe with the same name + exists in another layer that has a higher layer + priority. + + show-appends: + Lists .bbappend files and the + recipe files to which they apply. + + show-cross-depends: + Lists dependency relationships between recipes that + cross layer boundaries. + + flatten: + Flattens the layer configuration into a separate output + directory. + Flattening your layer configuration builds a "flattened" + directory that contains the contents of all layers, + with any overlayed recipes removed and any + .bbappend files appended to the + corresponding recipes. + You might have to perform some manual cleanup of the + flattened layer as follows: + + Non-recipe files (such as patches) + are overwritten. + The flatten command shows a warning for these + files. + + Anything beyond the normal layer + setup has been added to the + layer.conf file. + Only the lowest priority layer's + layer.conf is used. + + Overridden and appended items from + .bbappend files need to be + cleaned up. + The contents of each + .bbappend end up in the + flattened recipe. + However, if there are appended or changed + variable values, you need to tidy these up + yourself. + Consider the following example. + Here, the bitbake-layers + command adds the line + #### bbappended ... so that + you know where the following lines originate: + + ... + DESCRIPTION = "A useful utility" + ... + EXTRA_OECONF = "‐‐enable-something" + ... + + #### bbappended from meta-anotherlayer #### + + DESCRIPTION = "Customized utility" + EXTRA_OECONF += "‐‐enable-somethingelse" + + Ideally, you would tidy up these utilities as + follows: + + ... + DESCRIPTION = "Customized utility" + ... + EXTRA_OECONF = "‐‐enable-something ‐‐enable-somethingelse" + ... + + + + +
+ +
+ Creating a General Layer Using the yocto-layer Script + + + The yocto-layer script simplifies + creating a new general layer. + + For information on BSP layers, see the + "BSP Layers" + section in the Yocto Project Board Specific (BSP) + Developer's Guide. + + The default mode of the script's operation is to prompt you for + information needed to generate the layer: + + The layer priority. + + Whether or not to create a sample recipe. + + Whether or not to create a sample + append file. + + + + + + Use the yocto-layer create sub-command + to create a new general layer. + In its simplest form, you can create a layer as follows: + + $ yocto-layer create mylayer + + The previous example creates a layer named + meta-mylayer in the current directory. + + + + As the yocto-layer create command runs, + default values for the prompts appear in brackets. + Pressing enter without supplying anything for the prompts + or pressing enter and providing an invalid response causes the + script to accept the default value. + Once the script completes, the new layer + is created in the current working directory. + The script names the layer by prepending + meta- to the name you provide. + + + + Minimally, the script creates the following within the layer: + + The conf + directory: + This directory contains the layer's configuration file. + The root name for the file is the same as the root name + your provided for the layer (e.g. + layer.conf). + + The + COPYING.MIT file: + The copyright and use notice for the software. + + The README + file: + A file describing the contents of your new layer. + + + + + + If you choose to generate a sample recipe file, the script + prompts you for the name for the recipe and then creates it + in layer/recipes-example/example/. + The script creates a .bb file and a + directory, which contains a sample + helloworld.c source file, along with + a sample patch file. + If you do not provide a recipe name, the script uses + "example". + + + + If you choose to generate a sample append file, the script + prompts you for the name for the file and then creates it + in layer/recipes-example-bbappend/example-bbappend/. + The script creates a .bbappend file and a + directory, which contains a sample patch file. + If you do not provide a recipe name, the script uses + "example". + The script also prompts you for the version of the append file. + The version should match the recipe to which the append file + is associated. + + + + The easiest way to see how the yocto-layer + script works is to experiment with the script. + You can also read the usage information by entering the + following: + + $ yocto-layer help + + + + + Once you create your general layer, you must add it to your + bblayers.conf file. + Here is an example where a layer named + meta-mylayer is added: + + BBLAYERS = ?" \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-yocto \ + /usr/local/src/yocto/meta-yocto-bsp \ + /usr/local/src/yocto/meta-mylayer \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-yocto \ + " + + Adding the layer to this file enables the build system to + locate the layer during the build. + +
+
+ +
+ Customizing Images + + + You can customize images to satisfy particular requirements. + This section describes several methods and provides guidelines for each. + + +
+ Customizing Images Using <filename>local.conf</filename> + + + Probably the easiest way to customize an image is to add a + package by way of the local.conf + configuration file. + Because it is limited to local use, this method generally only + allows you to add packages and is not as flexible as creating + your own customized image. + When you add packages using local variables this way, you need + to realize that these variable changes are in effect for every + build and consequently affect all images, which might not + be what you require. + + + + To add a package to your image using the local configuration + file, use the + IMAGE_INSTALL + variable with the _append operator: + + IMAGE_INSTALL_append = " strace" + + Use of the syntax is important - specifically, the space between + the quote and the package name, which is + strace in this example. + This space is required since the _append + operator does not add the space. + + + + Furthermore, you must use _append instead + of the += operator if you want to avoid + ordering issues. + The reason for this is because doing so unconditionally appends + to the variable and avoids ordering problems due to the + variable being set in image recipes and + .bbclass files with operators like + ?=. + Using _append ensures the operation takes + affect. + + + + As shown in its simplest use, + IMAGE_INSTALL_append affects all images. + It is possible to extend the syntax so that the variable + applies to a specific image only. + Here is an example: + + IMAGE_INSTALL_append_pn-core-image-minimal = " strace" + + This example adds strace to the + core-image-minimal image only. + + + + You can add packages using a similar approach through the + CORE_IMAGE_EXTRA_INSTALL + variable. + If you use this variable, only + core-image-* images are affected. + +
+ +
+ Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and + <filename>EXTRA_IMAGE_FEATURES</filename> + + + Another method for customizing your image is to enable or + disable high-level image features by using the + IMAGE_FEATURES + and EXTRA_IMAGE_FEATURES + variables. + Although the functions for both variables are nearly equivalent, + best practices dictate using IMAGE_FEATURES + from within a recipe and using + EXTRA_IMAGE_FEATURES from within + your local.conf file, which is found in the + Build Directory. + + + + To understand how these features work, the best reference is + meta/classes/core-image.bbclass. + In summary, the file looks at the contents of the + IMAGE_FEATURES variable and then maps + those contents into a set of package groups. + Based on this information, the build system automatically + adds the appropriate packages to the + IMAGE_INSTALL + variable. + Effectively, you are enabling extra features by extending the + class or creating a custom class for use with specialized image + .bb files. + + + + Use the EXTRA_IMAGE_FEATURES variable + from within your local configuration file. + Using a separate area from which to enable features with + this variable helps you avoid overwriting the features in the + image recipe that are enabled with + IMAGE_FEATURES. + The value of EXTRA_IMAGE_FEATURES is added + to IMAGE_FEATURES within + meta/conf/bitbake.conf. + + + + To illustrate how you can use these variables to modify your + image, consider an example that selects the SSH server. + The Yocto Project ships with two SSH servers you can use + with your images: Dropbear and OpenSSH. + Dropbear is a minimal SSH server appropriate for + resource-constrained environments, while OpenSSH is a + well-known standard SSH server implementation. + By default, the core-image-sato image + is configured to use Dropbear. + The core-image-full-cmdline and + core-image-lsb images both + include OpenSSH. + The core-image-minimal image does not + contain an SSH server. + + + + You can customize your image and change these defaults. + Edit the IMAGE_FEATURES variable + in your recipe or use the + EXTRA_IMAGE_FEATURES in your + local.conf file so that it configures the + image you are working with to include + ssh-server-dropbear or + ssh-server-openssh. + + + + See the + "Images" + section in the Yocto Project Reference Manual for a complete + list of image features that ship with the Yocto Project. + +
+ +
+ Customizing Images Using Custom .bb Files + + + You can also customize an image by creating a custom recipe + that defines additional software as part of the image. + The following example shows the form for the two lines you need: + + IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" + + inherit core-image + + + + + Defining the software using a custom recipe gives you total + control over the contents of the image. + It is important to use the correct names of packages in the + IMAGE_INSTALL + variable. + You must use the OpenEmbedded notation and not the Debian notation for the names + (e.g. glibc-dev instead of libc6-dev). + + + + The other method for creating a custom image is to base it on an existing image. + For example, if you want to create an image based on core-image-sato + but add the additional package strace to the image, + copy the meta/recipes-sato/images/core-image-sato.bb to a + new .bb and add the following line to the end of the copy: + + IMAGE_INSTALL += "strace" + + +
+ +
+ Customizing Images Using Custom Package Groups + + + For complex custom images, the best approach for customizing + an image is to create a custom package group recipe that is + used to build the image or images. + A good example of a package group recipe is + meta/recipes-core/packagegroups/packagegroup-core-boot.bb. + The + PACKAGES + variable lists the package group packages you wish to produce. + inherit packagegroup sets appropriate + default values and automatically adds -dev, + -dbg, and -ptest + complementary packages for every package specified in + PACKAGES. + Note that the inherit line should be towards + the top of the recipe, certainly before you set + PACKAGES. + For each package you specify in PACKAGES, + you can use + RDEPENDS + and + RRECOMMENDS + entries to provide a list of packages the parent task package + should contain. + Following is an example: + + DESCRIPTION = "My Custom Package Groups" + + inherit packagegroup + + PACKAGES = "\ + packagegroup-custom-apps \ + packagegroup-custom-tools \ + " + + RDEPENDS_packagegroup-custom-apps = "\ + dropbear \ + portmap \ + psplash" + + RDEPENDS_packagegroup-custom-tools = "\ + oprofile \ + oprofileui-server \ + lttng-control \ + lttng-viewer" + + RRECOMMENDS_packagegroup-custom-tools = "\ + kernel-module-oprofile" + + + + + In the previous example, two package group packages are created with their dependencies and their + recommended package dependencies listed: packagegroup-custom-apps, and + packagegroup-custom-tools. + To build an image using these package group packages, you need to add + packagegroup-custom-apps and/or + packagegroup-custom-tools to + IMAGE_INSTALL. + For other forms of image dependencies see the other areas of this section. + +
+
+ +
+ Writing a New Recipe + + + Recipes (.bb files) are fundamental components + in the Yocto Project environment. + Each software component built by the OpenEmbedded build system + requires a recipe to define the component. + This section describes how to create, write, and test a new + recipe. + + For information on variables that are useful for recipes and + for information about recipe naming issues, see the + "Required" + section of the Yocto Project Reference Manual. + + + +
+ Overview + + + The following figure shows the basic process for creating a + new recipe. + The remainder of the section provides details for the steps. + + +
+ +
+ Locate a Base Recipe + + + Before writing a recipe from scratch, it is often useful to + discover whether someone else has already written one that + meets (or comes close to meeting) your needs. + The Yocto Project and OpenEmbedded communities maintain many + recipes that might be candidates for what you are doing. + You can find a good central index of these recipes in the + OpenEmbedded metadata index. + + + + Working from an existing recipe or a skeleton recipe is the + best way to get started. + Here are some points on both methods: + + Locate and modify a recipe that + is close to what you want to do: + This method works when you are familiar with the + current recipe space. + The method does not work so well for those new to + the Yocto Project or writing recipes. + Some risks associated with this method are + using a recipe that has areas totally unrelated to + what you are trying to accomplish with your recipe, + not recognizing areas of the recipe that you might + have to add from scratch, and so forth. + All these risks stem from unfamiliarity with the + existing recipe space. + Use and modify the following + skeleton recipe: + + SUMMARY = "" + HOMEPAGE = "" + LICENSE = "" + + LIC_FILES_CHKSUM = "" + + SRC_URI = "" + SRC_URI[md5sum] = "" + SRC_URI[sha256sum] = "" + + S = "${WORKDIR}/${PN}-${PV}" + + inherit stuff + + Modifying this recipe is the recommended method for + creating a new recipe. + The recipe provides the fundamental areas that you need + to include, exclude, or alter to fit your needs. + + + +
+ +
+ Storing and Naming the Recipe + + + Once you have your base recipe, you should put it in your + own layer and name it appropriately. + Locating it correctly ensures that the OpenEmbedded build + system can find it when you use BitBake to process the + recipe. + + + + Storing Your Recipe: + The OpenEmbedded build system locates your recipe + through the layer's conf/layer.conf + file and the + BBFILES + variable. + This variable sets up a path from which the build system can + locate recipes. + Here is the typical use: + + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + Consequently, you need to be sure you locate your new recipe + inside your layer such that it can be found. + You can find more information on how layers are + structured in the + "Understanding and Creating Layers" + section. + Naming Your Recipe: + When you name your recipe, you need to follow this naming + convention: + + basename_version.bb + + Use lower-cased characters and do not include the reserved + suffixes -native, + -cross, -initial, + or -dev casually (i.e. do not use them + as part of your recipe name unless the string applies). + Here are some examples: + + cups_1.7.0.bb + gawk_4.0.2.bb + irssi_0.8.16-rc1.bb + + +
+ +
+ Understanding Recipe Syntax + + + Understanding recipe file syntax is important for + writing recipes. + The following list overviews the basic items that make up a + BitBake recipe file. + For more complete BitBake syntax descriptions, see the + "Syntax and Operators" + chapter of the BitBake User Manual. + + Variable Assignments and Manipulations: + Variable assignments allow a value to be assigned to a + variable. + The assignment can be static text or might include + the contents of other variables. + In addition to the assignment, appending and prepending + operations are also supported. + The following example shows some of the ways + you can use variables in recipes: + + S = "${WORKDIR}/postfix-${PV}" + CFLAGS += "-DNO_ASM" + SRC_URI_append = " file://fixup.patch" + + + Functions: + Functions provide a series of actions to be performed. + You usually use functions to override the default + implementation of a task function or to complement + a default function (i.e. append or prepend to an + existing function). + Standard functions use sh shell + syntax, although access to OpenEmbedded variables and + internal methods are also available. + The following is an example function from the + sed recipe: + + do_install () { + autotools_do_install + install -d ${D}${base_bindir} + mv ${D}${bindir}/sed ${D}${base_bindir}/sed + rmdir ${D}${bindir}/ + } + + It is also possible to implement new functions that + are called between existing tasks as long as the + new functions are not replacing or complementing the + default functions. + You can implement functions in Python + instead of shell. + Both of these options are not seen in the majority of + recipes. + Keywords: + BitBake recipes use only a few keywords. + You use keywords to include common + functions (inherit), load parts + of a recipe from other files + (include and + require) and export variables + to the environment (export). + The following example shows the use of some of + these keywords: + + export POSTCONF = "${STAGING_BINDIR}/postconf" + inherit autoconf + require otherfile.inc + + + Comments: + Any lines that begin with the hash character + (#) are treated as comment lines + and are ignored: + + # This is a comment + + + + + + + This next list summarizes the most important and most commonly + used parts of the recipe syntax. + For more information on these parts of the syntax, you can + reference the + Syntax and Operators + chapter in the BitBake User Manual. + + Line Continuation: \ - + Use the backward slash (\) + character to split a statement over multiple lines. + Place the slash character at the end of the line that + is to be continued on the next line: + + VAR = "A really long \ + line" + + + You cannot have any characters including spaces + or tabs after the slash character. + + + Using Variables: ${...} - + Use the ${varname} syntax to + access the contents of a variable: + + SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" + + + Quote All Assignments: "value" - + Use double quotes around the value in all variable + assignments. + + VAR1 = "${OTHERVAR}" + VAR2 = "The version is ${PV}" + + + Conditional Assignment: ?= - + Conditional assignment is used to assign a value to + a variable, but only when the variable is currently + unset. + Use the question mark followed by the equal sign + (?=) to make a "soft" assignment + used for conditional assignment. + Typically, "soft" assignments are used in the + local.conf file for variables + that are allowed to come through from the external + environment. + + Here is an example where + VAR1 is set to "New value" if + it is currently empty. + However, if VAR1 has already been + set, it remains unchanged: + + VAR1 ?= "New value" + + In this next example, VAR1 + is left with the value "Original value": + + VAR1 = "Original value" + VAR1 ?= "New value" + + + Appending: += - + Use the plus character followed by the equals sign + (+=) to append values to existing + variables. + + This operator adds a space between the existing + content of the variable and the new content. + + Here is an example: + + SRC_URI += "file://fix-makefile.patch" + + + Prepending: =+ - + Use the equals sign followed by the plus character + (=+) to prepend values to existing + variables. + + This operator adds a space between the new content + and the existing content of the variable. + + Here is an example: + + VAR =+ "Starts" + + + Appending: _append - + Use the _append operator to + append values to existing variables. + This operator does not add any additional space. + Also, the operator is applied after all the + +=, and + =+ operators have been applied and + after all = assignments have + occurred. + + The following example shows the space being + explicitly added to the start to ensure the appended + value is not merged with the existing value: + + SRC_URI_append = " file://fix-makefile.patch" + + You can also use the _append + operator with overrides, which results in the actions + only being performed for the specified target or + machine: + + SRC_URI_append_sh4 = " file://fix-makefile.patch" + + + Prepending: _prepend - + Use the _prepend operator to + prepend values to existing variables. + This operator does not add any additional space. + Also, the operator is applied after all the + +=, and + =+ operators have been applied and + after all = assignments have + occurred. + + The following example shows the space being + explicitly added to the end to ensure the prepended + value is not merged with the existing value: + + CFLAGS_prepend = "-I${S}/myincludes " + + You can also use the _prepend + operator with overrides, which results in the actions + only being performed for the specified target or + machine: + + CFLAGS_prepend_sh4 = "-I${S}/myincludes " + + + Overrides: - + You can use overrides to set a value conditionally, + typically based on how the recipe is being built. + For example, to set the + KBRANCH + variable's value to "standard/base" for any target + MACHINE, + except for qemuarm where it should be set to + "standard/arm-versatile-926ejs", you would do the + following: + + KBRANCH = "standard/base" + KBRANCH_qemuarm = "standard/arm-versatile-926ejs" + + Overrides are also used to separate alternate values + of a variable in other situations. + For example, when setting variables such as + FILES + and + RDEPENDS + that are specific to individual packages produced by + a recipe, you should always use an override that + specifies the name of the package. + + Indentation: + Use spaces for indentation rather than than tabs. + For shell functions, both currently work. + However, it is a policy decision of the Yocto Project + to use tabs in shell functions. + Realize that some layers have a policy to use spaces + for all indentation. + + Using Python for Complex Operations: ${@python_code} - + For more advanced processing, it is possible to use + Python code during variable assignments (e.g. + search and replacement on a variable). + You indicate Python code using the + ${@python_code} + syntax for the variable assignment: + + SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz + + + Shell Function Syntax: + Write shell functions as if you were writing a shell + script when you describe a list of actions to take. + You should ensure that your script works with a generic + sh and that it does not require + any bash or other shell-specific + functionality. + The same considerations apply to various system + utilities (e.g. sed, + grep, awk, + and so forth) that you might wish to use. + If in doubt, you should check with multiple + implementations - including those from BusyBox. + + + +
+ +
+ Running a Build on the Recipe + + + Creating a new recipe is usually an iterative process that + requires using BitBake to process the recipe multiple times in + order to progressively discover and add information to the + recipe file. + + + + Assuming you have sourced a build environment setup script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres) + and you are in the + Build Directory, + use BitBake to process your recipe. + All you need to provide is the + basename of the recipe as described + in the previous section: + + $ bitbake basename + + + + + + During the build, the OpenEmbedded build system creates a + temporary work directory for each recipe + (${WORKDIR}) + where it keeps extracted source files, log files, intermediate + compilation and packaging files, and so forth. + + + + The per-recipe temporary work directory is constructed as follows and + depends on several factors: + + BASE_WORKDIR ?= "${TMPDIR}/work" + WORKDIR = "${BASE_WORKDIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" + + As an example, assume a Source Directory top-level folder named + poky, a default Build Directory at + poky/build, and a + qemux86-poky-linux machine target system. + Furthermore, suppose your recipe is named + foo_1.3.0.bb. + In this case, the work directory the build system uses to + build the package would be as follows: + + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + + Inside this directory you can find sub-directories such as + image, packages-split, + and temp. + After the build, you can examine these to determine how well + the build went. + + You can find log files for each task in the recipe's + temp directory (e.g. + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp). + Log files are named log.taskname + (e.g. log.do_configure, + log.do_fetch, and + log.do_compile). + + + + + You can find more information about the build process in the + "A Closer Look at the Yocto Project Development Environment" + chapter of the Yocto Project Reference Manual. + + + + You can also reference the following variables in the + Yocto Project Reference Manual's glossary for more information: + + TMPDIR: + The top-level build output directory + MULTIMACH_TARGET_SYS: + The target system identifier + PN: + The recipe name + EXTENDPE: + The epoch - (if + PE + is not specified, which is usually the case for most + recipes, then EXTENDPE is blank) + PV: + The recipe version + PR: + The recipe revision + + +
+ +
+ Fetching Code + + + The first thing your recipe must do is specify how to fetch + the source files. + Fetching is controlled mainly through the + SRC_URI + variable. + Your recipe must have a SRC_URI variable + that points to where the source is located. + For a graphical representation of source locations, see the + "Sources" + section in the Yocto Project Reference Manual. + + + + The + do_fetch + task uses the prefix of each entry in the + SRC_URI variable value to determine which + fetcher to use to get your source files. + It is the SRC_URI variable that triggers + the fetcher. + The + do_patch + task uses the variable after source is fetched to apply + patches. + The OpenEmbedded build system uses + FILESOVERRIDES + for scanning directory locations for local files in + SRC_URI. + + + + The SRC_URI variable in your recipe must + define each unique location for your source files. + It is good practice to not hard-code pathnames in an URL used + in SRC_URI. + Rather than hard-code these paths, use + ${PV}, + which causes the fetch process to use the version specified in + the recipe filename. + Specifying the version in this manner means that upgrading the + recipe to a future version is as simple as renaming the recipe + to match the new version. + + + + Here is a simple example from the + meta/recipes-devtools/cdrtools/cdrtools-native_3.01a20.bb + recipe where the source comes from a single tarball. + Notice the use of the + PV + variable: + + SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2" + + + + + Files mentioned in SRC_URI whose names end + in a typical archive extension (e.g. .tar, + .tar.gz, .tar.bz2, + .zip, and so forth), are automatically + extracted during the + do_unpack + task. + For another example that specifies these types of files, see + the + "Autotooled Package" + section. + + + + Another way of specifying source is from an SCM. + For Git repositories, you must specify + SRCREV + and you should specify + PV + to include the revision with + SRCPV. + Here is an example from the recipe + meta/recipes-kernel/blktrace/blktrace_git.bb: + + SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385" + + PR = "r6" + PV = "1.0.5+git${SRCPV}" + + SRC_URI = "git://git.kernel.dk/blktrace.git \ + file://ldflags.patch" + + + + + If your SRC_URI statement includes + URLs pointing to individual files fetched from a remote server + other than a version control system, BitBake attempts to + verify the files against checksums defined in your recipe to + ensure they have not been tampered with or otherwise modified + since the recipe was written. + Two checksums are used: + SRC_URI[md5sum] and + SRC_URI[sha256sum]. + + + + If your SRC_URI variable points to + more than a single URL (excluding SCM URLs), you need to + provide the md5 and + sha256 checksums for each URL. + For these cases, you provide a name for each URL as part of + the SRC_URI and then reference that name + in the subsequent checksum statements. + Here is an example: + + SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \ + ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch + + SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8" + SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d" + + SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92" + SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430" + + + + + Proper values for md5 and + sha256 checksums might be available + with other signatures on the download page for the upstream + source (e.g. md5, + sha1, sha256, + GPG, and so forth). + Because the OpenEmbedded build system only deals with + sha256sum and md5sum, + you should verify all the signatures you find by hand. + + + + If no SRC_URI checksums are specified + when you attempt to build the recipe, the build will produce + an error for each missing checksum. + As part of the error message, the build system provides + the checksum string corresponding to the fetched file. + Once you have the correct checksums, you can copy and paste + them into your recipe and then run the build again to continue. + + As mentioned, if the upstream source provides signatures + for verifying the downloaded source code, you should + verify those manually before setting the checksum values + in the recipe and continuing with the build. + + + + + This final example is a bit more complicated and is from the + meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb + recipe. + The example's SRC_URI statement identifies + multiple files as the source files for the recipe: a tarball, a + patch file, a desktop file, and an icon. + + SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ + file://xwc.patch \ + file://rxvt.desktop \ + file://rxvt.png" + + + + + When you specify local files using the + file:// URI protocol, the build system + fetches files from the local machine. + The path is relative to the + FILESPATH + variable and searches specific directories in a certain order: + ${BP}, + ${BPN}, + and files. + The directories are assumed to be subdirectories of the + directory in which the recipe or append file resides. + For another example that specifies these types of files, see the + "Single .c File Package (Hello World!)" + section. + + + + The previous example also specifies a patch file. + Patch files are files whose names end in + .patch or .diff. + The build system automatically applies patches as described + in the + "Patching Code" section. + +
+ +
+ Unpacking Code + + + During the build, the + do_unpack + task unpacks the source with + ${S} + pointing to where it is unpacked. + + + + If you are fetching your source files from an upstream source + archived tarball and the tarball's internal structure matches + the common convention of a top-level subdirectory named + ${BPN}-${PV}, + then you do not need to set S. + However, if SRC_URI specifies to fetch + source from an archive that does not use this convention, + or from an SCM like Git or Subversion, your recipe needs to + define S. + + + + If processing your recipe using BitBake successfully unpacks + the source files, you need to be sure that the directory + pointed to by ${S} matches the structure + of the source. + +
+ +
+ Patching Code + + + Sometimes it is necessary to patch code after it has been + fetched. + Any files mentioned in SRC_URI whose + names end in .patch or + .diff are treated as patches. + The + do_patch + task automatically applies these patches. + + + + The build system should be able to apply patches with the "-p1" + option (i.e. one directory level in the path will be stripped + off). + If your patch needs to have more directory levels stripped off, + specify the number of levels using the "striplevel" option in + the SRC_URI entry for the patch. + Alternatively, if your patch needs to be applied in a specific + subdirectory that is not specified in the patch file, use the + "patchdir" option in the entry. + + + + As with all local files referenced in + SRC_URI + using file://, you should place + patch files in a directory next to the recipe either + named the same as the base name of the recipe + (BPN), + or "files". + +
+ +
+ Licensing + + + Your recipe needs to have both the + LICENSE + and + LIC_FILES_CHKSUM + variables: + + LICENSE: + This variable specifies the license for the software. + If you do not know the license under which the software + you are building is distributed, you should go to the + source code and look for that information. + Typical files containing this information include + COPYING, + LICENSE, and + README files. + You could also find the information near the top of + a source file. + For example, given a piece of software licensed under + the GNU General Public License version 2, you would + set LICENSE as follows: + + LICENSE = "GPLv2" + + The licenses you specify within + LICENSE can have any name as long + as you do not use spaces, since spaces are used as + separators between license names. + For standard licenses, use the names of the files in + meta/files/common-licenses/ + or the SPDXLICENSEMAP flag names + defined in meta/conf/licenses.conf. + + LIC_FILES_CHKSUM: + The OpenEmbedded build system uses this variable to + make sure the license text has not changed. + If it has, the build produces an error and it affords + you the chance to figure it out and correct the problem. + + You need to specify all applicable licensing + files for the software. + At the end of the configuration step, the build process + will compare the checksums of the files to be sure + the text has not changed. + Any differences result in an error with the message + containing the current checksum. + For more explanation and examples of how to set the + LIC_FILES_CHKSUM variable, see the + "Tracking License Changes" + section in the Yocto Project Reference Manual. + To determine the correct checksum string, you + can list the appropriate files in the + LIC_FILES_CHKSUM variable with + incorrect md5 strings, attempt to build the software, + and then note the resulting error messages that will + report the correct md5 strings. + See the + "Fetching Code" + section for additional information. + + + + Here is an example that assumes the software has a + COPYING file: + + LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" + + When you try to build the software, the build system + will produce an error and give you the correct string + that you can substitute into the recipe file for a + subsequent build. + + + + + + +
+ +
+ Configuring the Recipe + + + Most software provides some means of setting build-time + configuration options before compilation. + Typically, setting these options is accomplished by running a + configure script with some options, or by modifying a build + configuration file. + + + + A major part of build-time configuration is about checking for + build-time dependencies and possibly enabling optional + functionality as a result. + You need to specify any build-time dependencies for the + software you are building in your recipe's + DEPENDS + value, in terms of other recipes that satisfy those + dependencies. + You can often find build-time or runtime + dependencies described in the software's documentation. + + + + The following list provides configuration items of note based + on how your software is built: + + Autotools: + If your source files have a + configure.ac file, then your + software is built using Autotools. + If this is the case, you just need to worry about + modifying the configuration. + When using Autotools, your recipe needs to inherit + the + autotools + class and your recipe does not have to contain a + do_configure + task. + However, you might still want to make some adjustments. + For example, you can set + EXTRA_OECONF + to pass any needed configure options that are specific + to the recipe. + CMake: + If your source files have a + CMakeLists.txt file, then your + software is built using CMake. + If this is the case, you just need to worry about + modifying the configuration. + When you use CMake, your recipe needs to inherit + the + cmake + class and your recipe does not have to contain a + do_configure + task. + You can make some adjustments by setting + EXTRA_OECMAKE + to pass any needed configure options that are specific + to the recipe. + Other: + If your source files do not have a + configure.ac or + CMakeLists.txt file, then your + software is built using some method other than Autotools + or CMake. + If this is the case, you normally need to provide a + do_configure + task in your recipe + unless, of course, there is nothing to configure. + + Even if your software is not being built by + Autotools or CMake, you still might not need to deal + with any configuration issues. + You need to determine if configuration is even a required step. + You might need to modify a Makefile or some configuration file + used for the build to specify necessary build options. + Or, perhaps you might need to run a provided, custom + configure script with the appropriate options. + For the case involving a custom configure + script, you would run + ./configure ‐‐help and look for + the options you need to set. + + + + + Once configuration succeeds, it is always good practice to + look at the log.do_configure file to + ensure that the appropriate options have been enabled and no + additional build-time dependencies need to be added to + DEPENDS. + For example, if the configure script reports that it found + something not mentioned in DEPENDS, or + that it did not find something that it needed for some + desired optional functionality, then you would need to add + those to DEPENDS. + Looking at the log might also reveal items being checked for, + enabled, or both that you do not want, or items not being found + that are in DEPENDS, in which case + you would need to look at passing extra options to the + configure script as needed. + For reference information on configure options specific to the + software you are building, you can consult the output of the + ./configure ‐‐help command within + ${S} or consult the software's upstream + documentation. + +
+ +
+ Compilation + + + During a build, the do_compile task + happens after source is fetched, unpacked, and configured. + If the recipe passes through do_compile + successfully, nothing needs to be done. + + + + However, if the compile step fails, you need to diagnose the + failure. + Here are some common issues that cause failures: + + Parallel build failures: + These failures manifest themselves as intermittent + errors, or errors reporting that a file or directory + that should be created by some other part of the build + process could not be found. + This type of failure can occur even if, upon inspection, + the file or directory does exist after the build has + failed, because that part of the build process happened + in the wrong order. + To fix the problem, you need to either satisfy + the missing dependency in the Makefile or whatever + script produced the Makefile, or (as a workaround) + set + PARALLEL_MAKE + to an empty string: + + PARALLEL_MAKE = "" + + + For information on parallel Makefile issues, see the + "Debugging Parallel Make Races" + section. + + Improper host path usage: + This failure applies to recipes building for the target + or nativesdk only. + The failure occurs when the compilation process uses + improper headers, libraries, or other files from the + host system when cross-compiling for the target. + + To fix the problem, examine the + log.do_compile file to identify + the host paths being used (e.g. + /usr/include, + /usr/lib, and so forth) and then + either add configure options, apply a patch, or do both. + + Failure to find required + libraries/headers: + If a build-time dependency is missing because it has + not been declared in + DEPENDS, + or because the dependency exists but the path used by + the build process to find the file is incorrect and the + configure step did not detect it, the compilation + process could fail. + For either of these failures, the compilation process + notes that files could not be found. + In these cases, you need to go back and add additional + options to the configure script as well as possibly + add additional build-time dependencies to + DEPENDS. + Occasionally, it is necessary to apply a patch + to the source to ensure the correct paths are used. + If you need to specify paths to find files staged + into the sysroot from other recipes, use the variables + that the OpenEmbedded build system provides + (e.g. + STAGING_BINDIR, + STAGING_INCDIR, + STAGING_DATADIR, and so forth). + + + + +
+ +
+ Installing + + + During do_install, the task copies the + built files along with their hierarchy to locations that + would mirror their locations on the target device. + The installation process copies files from the + ${S}, + ${B}, + and + ${WORKDIR} + directories to the + ${D} + directory to create the structure as it should appear on the + target system. + + + + How your software is built affects what you must do to be + sure your software is installed correctly. + The following list describes what you must do for installation + depending on the type of build system used by the software + being built: + + Autotools and CMake: + If the software your recipe is building uses Autotools + or CMake, the OpenEmbedded build + system understands how to install the software. + Consequently, you do not have to have a + do_install task as part of your + recipe. + You just need to make sure the install portion of the + build completes with no issues. + However, if you wish to install additional files not + already being installed by + make install, you should do this + using a do_install_append function + using the install command as described in + the "Manual" bulleted item later in this list. + + Other (using + make install): + You need to define a + do_install function in your + recipe. + The function should call + oe_runmake install and will likely + need to pass in the destination directory as well. + How you pass that path is dependent on how the + Makefile being run is written + (e.g. DESTDIR=${D}, + PREFIX=${D}, + INSTALLROOT=${D}, and so forth). + + For an example recipe using + make install, see the + "Makefile-Based Package" + section. + Manual: + You need to define a + do_install function in your + recipe. + The function must first use + install -d to create the + directories under + ${D}. + Once the directories exist, your function can use + install to manually install the + built software into the directories. + You can find more information on + install at + . + + + + + + For the scenarios that do not use Autotools or + CMake, you need to track the installation + and diagnose and fix any issues until everything installs + correctly. + You need to look in the default location of + ${D}, which is + ${WORKDIR}/image, to be sure your + files have been installed correctly. + + + Notes + + + During the installation process, you might need to + modify some of the installed files to suit the target + layout. + For example, you might need to replace hard-coded paths + in an initscript with values of variables provided by + the build system, such as replacing + /usr/bin/ with + ${bindir}. + If you do perform such modifications during + do_install, be sure to modify the + destination file after copying rather than before + copying. + Modifying after copying ensures that the build system + can re-execute do_install if + needed. + + + oe_runmake install, which can be + run directly or can be run indirectly by the + autotools + and + cmake + classes, runs make install in + parallel. + Sometimes, a Makefile can have missing dependencies + between targets that can result in race conditions. + If you experience intermittent failures during + do_install, you might be able to + work around them by disabling parallel Makefile + installs by adding the following to the recipe: + + PARALLEL_MAKEINST = "" + + See + PARALLEL_MAKEINST + for additional information. + + + +
+ +
+ Enabling System Services + + + If you want to install a service, which is a process that + usually starts on boot and runs in the background, then + you must include some additional definitions in your recipe. + + + + If you are adding services and the service initialization + script or the service file itself is not installed, you must + provide for that installation in your recipe using a + do_install_append function. + If your recipe already has a do_install + function, update the function near its end rather than + adding an additional do_install_append + function. + + + + When you create the installation for your services, you need + to accomplish what is normally done by + make install. + In other words, make sure your installation arranges the output + similar to how it is arranged on the target system. + + + + The OpenEmbedded build system provides support for starting + services two different ways: + + SysVinit: + SysVinit is a system and service manager that + manages the init system used to control the very basic + functions of your system. + The init program is the first program + started by the Linux kernel when the system boots. + Init then controls the startup, running and shutdown + of all other programs. + To enable a service using SysVinit, your recipe + needs to inherit the + update-rc.d + class. + The class helps facilitate safely installing the + package on the target. + You will need to set the + INITSCRIPT_PACKAGES, + INITSCRIPT_NAME, + and + INITSCRIPT_PARAMS + variables within your recipe. + systemd: + System Management Daemon (systemd) was designed to + replace SysVinit and to provide + enhanced management of services. + For more information on systemd, see the systemd + homepage at + . + + To enable a service using systemd, your recipe + needs to inherit the + systemd + class. + See the systemd.bbclass file + located in your + Source Directory. + section for more information. + + + +
+ +
+ Packaging + + + Successful packaging is a combination of automated processes + performed by the OpenEmbedded build system and some + specific steps you need to take. + The following list describes the process: + + Splitting Files: + The do_package task splits the + files produced by the recipe into logical components. + Even software that produces a single binary might + still have debug symbols, documentation, and other + logical components that should be split out. + The do_package task ensures + that files are split up and packaged correctly. + + Running QA Checks: + The + insane + class adds a step to + the package generation process so that output quality + assurance checks are generated by the OpenEmbedded + build system. + This step performs a range of checks to be sure the + build's output is free of common problems that show + up during runtime. + For information on these checks, see the + insane + class and the + "QA Error and Warning Messages" + chapter in the Yocto Project Reference Manual. + + Hand-Checking Your Packages: + After you build your software, you need to be sure + your packages are correct. + Examine the + ${WORKDIR}/packages-split + directory and make sure files are where you expect + them to be. + If you discover problems, you can set + PACKAGES, + FILES, + do_install(_append), and so forth as + needed. + + Splitting an Application into Multiple Packages: + If you need to split an application into several + packages, see the + "Splitting an Application into Multiple Packages" + section for an example. + + Installing a Post-Installation Script: + For an example showing how to install a + post-installation script, see the + "Post-Installation Scripts" + section. + + Marking Package Architecture: + Depending on what your recipe is building and how it + is configured, it might be important to mark the + packages produced as being specific to a particular + machine, or to mark them as not being specific to + a particular machine or architecture at all. + By default, packages produced for the target are + marked as being specific to the architecture of the + target machine because that is usually the desired + result. + However, if the recipe configures the software to be + built specific to the target machine (e.g. the + MACHINE + value is passed into the configure script or a patch + is applied only for a particular machine), then you + should mark the packages produced as being + machine-specific by adding the following to the + recipe: + + PACKAGE_ARCH = "${MACHINE_ARCH}" + + On the other hand, if the recipe produces packages + that do not contain anything specific to the target + machine or architecture at all (e.g. recipes + that simply package script files or configuration + files), you should use the + allarch + class to do this for you by adding this to your + recipe: + + inherit allarch + + Ensuring that the package architecture is correct is + not critical while you are doing the first few builds + of your recipe. + However, it is important in order + to ensure that your recipe rebuilds (or does not + rebuild) appropriately in response to changes in + configuration, and to ensure that you get the + appropriate packages installed on the target machine, + particularly if you run separate builds for more + than one target machine. + + + +
+ +
+ Properly Versioning Pre-Release Recipes + + + Sometimes the name of a recipe can lead to versioning + problems when the recipe is upgraded to a final release. + For example, consider the + irssi_0.8.16-rc1.bb recipe file in + the list of example recipes in the + "Storing and Naming the Recipe" + section. + This recipe is at a release candidate stage (i.e. + "rc1"). + When the recipe is released, the recipe filename becomes + irssi_0.8.16.bb. + The version change from 0.8.16-rc1 + to 0.8.16 is seen as a decrease by the + build system and package managers, so the resulting packages + will not correctly trigger an upgrade. + + + + In order to ensure the versions compare properly, the + recommended convention is to set + PV + within the recipe to + "previous_version+current_version". + You can use an additional variable so that you can use the + current version elsewhere. + Here is an example: + + REALPV = "0.8.16-rc1" + PV = "0.8.15+${REALPV}" + + +
+ +
+ Post-Installation Scripts + + + Post-installation scripts run immediately after installing + a package on the target or during image creation when a + package is included in an image. + To add a post-installation script to a package, add a + pkg_postinst_PACKAGENAME() function to + the recipe file (.bb) and replace + PACKAGENAME with the name of the package + you want to attach to the postinst + script. + To apply the post-installation script to the main package + for the recipe, which is usually what is required, specify + ${PN} + in place of PACKAGENAME. + + + + A post-installation function has the following structure: + + pkg_postinst_PACKAGENAME() { + #!/bin/sh -e + # Commands to carry out + } + + + + + The script defined in the post-installation function is + called when the root filesystem is created. + If the script succeeds, the package is marked as installed. + If the script fails, the package is marked as unpacked and + the script is executed when the image boots again. + + + + Sometimes it is necessary for the execution of a + post-installation script to be delayed until the first boot. + For example, the script might need to be executed on the + device itself. + To delay script execution until boot time, use the following + structure in the post-installation script: + + pkg_postinst_PACKAGENAME() { + #!/bin/sh -e + if [ x"$D" = "x" ]; then + # Actions to carry out on the device go here + else + exit 1 + fi + } + + + + + The previous example delays execution until the image boots + again because the environment variable D + points to the directory containing the image when + the root filesystem is created at build time but is unset + when executed on the first boot. + + + + Equivalent support for pre-install, pre-uninstall, and + post-uninstall scripts exist by way of + pkg_preinst, + pkg_prerm, and + pkg_postrm, respectively. + These scrips work in exactly the same way as does + pkg_postinst with the exception that they + run at different times. + Also, because of when they run, they are not applicable to + being run at image creation time like + pkg_postinst. + +
+ +
+ Testing + + + The final step for completing your recipe is to be sure that + the software you built runs correctly. + To accomplish runtime testing, add the build's output + packages to your image and test them on the target. + + + + For information on how to customize your image by adding + specific packages, see the + "Customizing Images" + section. + +
+ +
+ Examples + + + To help summarize how to write a recipe, this section provides + some examples given various scenarios: + + Recipes that use local files + Using an Autotooled package + Using a Makefile-based package + Splitting an application into multiple packages + Adding binaries to an image + + + +
+ Single .c File Package (Hello World!) + + + Building an application from a single file that is stored + locally (e.g. under files) requires + a recipe that has the file listed in the + SRC_URI + variable. + Additionally, you need to manually write the + do_compile and + do_install tasks. + The S + variable defines the directory containing the source code, + which is set to + WORKDIR + in this case - the directory BitBake uses for the build. + + SUMMARY = "Simple helloworld application" + SECTION = "examples" + LICENSE = "MIT" + LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" + + SRC_URI = "file://helloworld.c" + + S = "${WORKDIR}" + + do_compile() { + ${CC} helloworld.c -o helloworld + } + + do_install() { + install -d ${D}${bindir} + install -m 0755 helloworld ${D}${bindir} + } + + + + + By default, the helloworld, + helloworld-dbg, and + helloworld-dev packages are built. + For information on how to customize the packaging process, + see the + "Splitting an Application into Multiple Packages" + section. + +
+ +
+ Autotooled Package + + Applications that use Autotools such as autoconf and + automake require a recipe that has a source archive listed in + SRC_URI and + also inherit the + autotools + class, which contains the definitions of all the steps + needed to build an Autotool-based application. + The result of the build is automatically packaged. + And, if the application uses NLS for localization, packages with local information are + generated (one package per language). + Following is one example: (hello_2.3.bb) + + SUMMARY = "GNU Helloworld application" + SECTION = "examples" + LICENSE = "GPLv2+" + LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" + + SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" + + inherit autotools gettext + + + + + The variable + LIC_FILES_CHKSUM + is used to track source license changes as described in the + "Tracking License Changes" section. + You can quickly create Autotool-based recipes in a manner similar to the previous example. + +
+ +
+ Makefile-Based Package + + + Applications that use GNU make also require a recipe that has + the source archive listed in + SRC_URI. + You do not need to add a do_compile step since by default BitBake + starts the make command to compile the application. + If you need additional make options, you should store them in the + EXTRA_OEMAKE + variable. + BitBake passes these options into the GNU make invocation. + Note that a do_install task is still required. + Otherwise, BitBake runs an empty do_install task by default. + + + + Some applications might require extra parameters to be passed to the compiler. + For example, the application might need an additional header path. + You can accomplish this by adding to the + CFLAGS variable. + The following example shows this: + + CFLAGS_prepend = "-I ${S}/include " + + + + + In the following example, mtd-utils is a makefile-based package: + + SUMMARY = "Tools for managing memory technology devices" + SECTION = "base" + DEPENDS = "zlib lzo e2fsprogs util-linux" + HOMEPAGE = "http://www.linux-mtd.infradead.org/" + LICENSE = "GPLv2+" + LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ + file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" + + # Use the latest version at 26 Oct, 2013 + SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b" + SRC_URI = "git://git.infradead.org/mtd-utils.git \ + file://add-exclusion-to-mkfs-jffs2-git-2.patch \ + " + + PV = "1.5.1+git${SRCPV}" + + S = "${WORKDIR}/git/" + + EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" + + do_install () { + oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir} + } + + PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc" + + FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool" + FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*" + FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image" + + PARALLEL_MAKE = "" + + BBCLASSEXTEND = "native" + + +
+ +
+ Splitting an Application into Multiple Packages + + + You can use the variables + PACKAGES and + FILES + to split an application into multiple packages. + + + + Following is an example that uses the libxpm recipe. + By default, this recipe generates a single package that contains the library along + with a few binaries. + You can modify the recipe to split the binaries into separate packages: + + require xorg-lib-common.inc + + SUMMARY = "X11 Pixmap library" + LICENSE = "X-BSD" + LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" + DEPENDS += "libxext libsm libxt" + PR = "r3" + PE = "1" + + XORG_PN = "libXpm" + + PACKAGES =+ "sxpm cxpm" + FILES_cxpm = "${bindir}/cxpm" + FILES_sxpm = "${bindir}/sxpm" + + + + + In the previous example, we want to ship the sxpm + and cxpm binaries in separate packages. + Since bindir would be packaged into the main + PN + package by default, we prepend the PACKAGES + variable so additional package names are added to the start of list. + This results in the extra FILES_* + variables then containing information that define which files and + directories go into which packages. + Files included by earlier packages are skipped by latter packages. + Thus, the main PN package + does not include the above listed files. + +
+ +
+ Packaging Externally Produced Binaries + + + Sometimes, you need to add pre-compiled binaries to an + image. + For example, suppose that binaries for proprietary code + exist, which are created by a particular division of a + company. + Your part of the company needs to use those binaries as + part of an image that you are building using the + OpenEmbedded build system. + Since you only have the binaries and not the source code, + you cannot use a typical recipe that expects to fetch the + source specified in + SRC_URI + and then compile it. + + + + One method is to package the binaries and then install them + as part of the image. + Generally, it is not a good idea to package binaries + since, among other things, it can hinder the ability to + reproduce builds and could lead to compatibility problems + with ABI in the future. + However, sometimes you have no choice. + + + + The easiest solution is to create a recipe that uses + the + bin_package + class and to be sure that you are using default locations + for build artifacts. + In most cases, the bin_package class + handles "skipping" the configure and compile steps as well + as sets things up to grab packages from the appropriate + area. + In particular, this class sets noexec + on both the + do_configure + and + do_compile + tasks, sets + FILES_${PN} to "/" so that it picks + up all files, and sets up a + do_install + task, which effectively copies all files from + ${S} to ${D}. + The bin_package class works well when + the files extracted into ${S} are + already laid out in the way they should be laid out + on the target. + For more information on these variables, see the + FILES, + PN, + S, + and + D + variables in the Yocto Project Reference Manual's variable + glossary. + + + + If you can't use the bin_package + class, you need to be sure you are doing the following: + + Create a recipe where the + do_configure and + do_compile tasks do nothing: + + do_configure[noexec] = "1" + do_compile[noexec] = "1" + + Alternatively, you can make these tasks an empty + function. + + Make sure your + do_install task installs the + binaries appropriately. + + Ensure that you set up + FILES (usually + FILES_${PN}) to point to the + files you have installed, which of course depends + on where you have installed them and whether + those files are in different locations than the + defaults. + + + +
+
+
+ +
+ Adding a New Machine + + + Adding a new machine to the Yocto Project is a straightforward + process. + This section describes how to add machines that are similar + to those that the Yocto Project already supports. + + Although well within the capabilities of the Yocto Project, + adding a totally new architecture might require + changes to gcc/glibc and to the site + information, which is beyond the scope of this manual. + + + + + For a complete example that shows how to add a new machine, + see the + "Creating a New BSP Layer Using the yocto-bsp Script" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. + + +
+ Adding the Machine Configuration File + + + To add a new machine, you need to add a new machine + configuration file to the layer's + conf/machine directory. + This configuration file provides details about the device + you are adding. + + + + The OpenEmbedded build system uses the root name of the + machine configuration file to reference the new machine. + For example, given a machine configuration file named + crownbay.conf, the build system + recognizes the machine as "crownbay". + + + + The most important variables you must set in your machine + configuration file or include from a lower-level configuration + file are as follows: + + TARGET_ARCH + (e.g. "arm") + PREFERRED_PROVIDER_virtual/kernel + + MACHINE_FEATURES + (e.g. "apm screen wifi") + + + + + You might also need these variables: + + SERIAL_CONSOLES + (e.g. "115200;ttyS0 115200;ttyS1") + KERNEL_IMAGETYPE + (e.g. "zImage") + IMAGE_FSTYPES + (e.g. "tar.gz jffs2") + + + + + You can find full details on these variables in the reference + section. + You can leverage existing machine .conf + files from meta-yocto-bsp/conf/machine/. + +
+ +
+ Adding a Kernel for the Machine + + + The OpenEmbedded build system needs to be able to build a kernel + for the machine. + You need to either create a new kernel recipe for this machine, + or extend an existing kernel recipe. + You can find several kernel recipe examples in the + Source Directory at + meta/recipes-kernel/linux + that you can use as references. + + + + If you are creating a new kernel recipe, normal recipe-writing + rules apply for setting up a + SRC_URI. + Thus, you need to specify any necessary patches and set + S + to point at the source code. + You need to create a do_configure task that + configures the unpacked kernel with a + defconfig file. + You can do this by using a make defconfig + command or, more commonly, by copying in a suitable + defconfig file and then running + make oldconfig. + By making use of inherit kernel and + potentially some of the linux-*.inc files, + most other functionality is centralized and the defaults of the + class normally work well. + + + + If you are extending an existing kernel recipe, it is usually + a matter of adding a suitable defconfig + file. + The file needs to be added into a location similar to + defconfig files used for other machines + in a given kernel recipe. + A possible way to do this is by listing the file in the + SRC_URI and adding the machine to the + expression in + COMPATIBLE_MACHINE: + + COMPATIBLE_MACHINE = '(qemux86|qemumips)' + + +
+ +
+ Adding a Formfactor Configuration File + + + A formfactor configuration file provides information about the + target hardware for which the image is being built and information that + the build system cannot obtain from other sources such as the kernel. + Some examples of information contained in a formfactor configuration file include + framebuffer orientation, whether or not the system has a keyboard, + the positioning of the keyboard in relation to the screen, and + the screen resolution. + + + + The build system uses reasonable defaults in most cases. + However, if customization is + necessary, you need to create a machconfig file + in the meta/recipes-bsp/formfactor/files + directory. + This directory contains directories for specific machines such as + qemuarm and qemux86. + For information about the settings available and the defaults, see the + meta/recipes-bsp/formfactor/files/config file found in the + same area. + + + + Following is an example for "qemuarm" machine: + + HAVE_TOUCHSCREEN=1 + HAVE_KEYBOARD=1 + + DISPLAY_CAN_ROTATE=0 + DISPLAY_ORIENTATION=0 + #DISPLAY_WIDTH_PIXELS=640 + #DISPLAY_HEIGHT_PIXELS=480 + #DISPLAY_BPP=16 + DISPLAY_DPI=150 + DISPLAY_SUBPIXEL_ORDER=vrgb + + +
+
+ +
+ Working With Libraries + + + Libraries are an integral part of your system. + This section describes some common practices you might find + helpful when working with libraries to build your system: + + How to include static library files + + How to use the Multilib feature to combine multiple versions of library files into a single image + + How to install multiple versions of the same library in parallel on the same system + + + + +
+ Including Static Library Files + + + If you are building a library and the library offers static linking, you can control + which static library files (*.a files) get included in the + built library. + + + + The PACKAGES + and FILES_* + variables in the + meta/conf/bitbake.conf configuration file define how files installed + by the do_install task are packaged. + By default, the PACKAGES variable includes + ${PN}-staticdev, which represents all static library files. + + Some previously released versions of the Yocto Project + defined the static library files through + ${PN}-dev. + + Following is part of the BitBake configuration file, where + you can see how the static library files are defined: + + PACKAGE_BEFORE_PN ?= "" + PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" + PACKAGES_DYNAMIC = "^${PN}-locale-.*" + FILES = "" + + FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \ + ${sysconfdir} ${sharedstatedir} ${localstatedir} \ + ${base_bindir}/* ${base_sbindir}/* \ + ${base_libdir}/*${SOLIBS} \ + ${base_prefix}/lib/udev/rules.d ${prefix}/lib/udev/rules.d \ + ${datadir}/${BPN} ${libdir}/${BPN}/* \ + ${datadir}/pixmaps ${datadir}/applications \ + ${datadir}/idl ${datadir}/omf ${datadir}/sounds \ + ${libdir}/bonobo/servers" + + FILES_${PN}-bin = "${bindir}/* ${sbindir}/*" + + FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ + ${datadir}/gnome/help" + SECTION_${PN}-doc = "doc" + + FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" + FILES_${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \ + ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ + ${datadir}/aclocal ${base_libdir}/*.o \ + ${libdir}/${BPN}/*.la ${base_libdir}/*.la" + SECTION_${PN}-dev = "devel" + ALLOW_EMPTY_${PN}-dev = "1" + RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" + + FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a" + SECTION_${PN}-staticdev = "devel" + RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" + + +
+ +
+ Combining Multiple Versions of Library Files into One Image + + + The build system offers the ability to build libraries with different + target optimizations or architecture formats and combine these together + into one system image. + You can link different binaries in the image + against the different libraries as needed for specific use cases. + This feature is called "Multilib." + + + + An example would be where you have most of a system compiled in 32-bit + mode using 32-bit libraries, but you have something large, like a database + engine, that needs to be a 64-bit application and uses 64-bit libraries. + Multilib allows you to get the best of both 32-bit and 64-bit libraries. + + + + While the Multilib feature is most commonly used for 32 and 64-bit differences, + the approach the build system uses facilitates different target optimizations. + You could compile some binaries to use one set of libraries and other binaries + to use a different set of libraries. + The libraries could differ in architecture, compiler options, or other + optimizations. + + + + This section overviews the Multilib process only. + For more details on how to implement Multilib, see the + Multilib wiki + page. + + + + Aside from this wiki page, several examples exist in the + meta-skeleton layer found in the + Source Directory: + + conf/multilib-example.conf + configuration file + conf/multilib-example2.conf + configuration file + recipes-multilib/images/core-image-multilib-example.bb + recipe + + + +
+ Preparing to Use Multilib + + + User-specific requirements drive the Multilib feature. + Consequently, there is no one "out-of-the-box" configuration that likely + exists to meet your needs. + + + + In order to enable Multilib, you first need to ensure your recipe is + extended to support multiple libraries. + Many standard recipes are already extended and support multiple libraries. + You can check in the meta/conf/multilib.conf + configuration file in the + Source Directory to see how this is + done using the + BBCLASSEXTEND + variable. + Eventually, all recipes will be covered and this list will + not be needed. + + + + For the most part, the Multilib class extension works automatically to + extend the package name from ${PN} to + ${MLPREFIX}${PN}, where MLPREFIX + is the particular multilib (e.g. "lib32-" or "lib64-"). + Standard variables such as + DEPENDS, + RDEPENDS, + RPROVIDES, + RRECOMMENDS, + PACKAGES, and + PACKAGES_DYNAMIC + are automatically extended by the system. + If you are extending any manual code in the recipe, you can use the + ${MLPREFIX} variable to ensure those names are extended + correctly. + This automatic extension code resides in multilib.bbclass. + +
+ +
+ Using Multilib + + + After you have set up the recipes, you need to define the actual + combination of multiple libraries you want to build. + You accomplish this through your local.conf + configuration file in the + Build Directory. + An example configuration would be as follows: + + MACHINE = "qemux86-64" + require conf/multilib.conf + MULTILIBS = "multilib:lib32" + DEFAULTTUNE_virtclass-multilib-lib32 = "x86" + IMAGE_INSTALL = "lib32-connman" + + This example enables an + additional library named lib32 alongside the + normal target packages. + When combining these "lib32" alternatives, the example uses "x86" for tuning. + For information on this particular tuning, see + meta/conf/machine/include/ia32/arch-ia32.inc. + + + + The example then includes lib32-connman + in all the images, which illustrates one method of including a + multiple library dependency. + You can use a normal image build to include this dependency, + for example: + + $ bitbake core-image-sato + + You can also build Multilib packages specifically with a command like this: + + $ bitbake lib32-connman + + +
+ +
+ Additional Implementation Details + + + Different packaging systems have different levels of native Multilib + support. + For the RPM Package Management System, the following implementation details + exist: + + A unique architecture is defined for the Multilib packages, + along with creating a unique deploy folder under + tmp/deploy/rpm in the + Build Directory. + For example, consider lib32 in a + qemux86-64 image. + The possible architectures in the system are "all", "qemux86_64", + "lib32_qemux86_64", and "lib32_x86". + The ${MLPREFIX} variable is stripped from + ${PN} during RPM packaging. + The naming for a normal RPM package and a Multilib RPM package in a + qemux86-64 system resolves to something similar to + bash-4.1-r2.x86_64.rpm and + bash-4.1.r2.lib32_x86.rpm, respectively. + + When installing a Multilib image, the RPM backend first + installs the base image and then installs the Multilib libraries. + + The build system relies on RPM to resolve the identical files in the + two (or more) Multilib packages. + + + + + For the IPK Package Management System, the following implementation details exist: + + The ${MLPREFIX} is not stripped from + ${PN} during IPK packaging. + The naming for a normal RPM package and a Multilib IPK package in a + qemux86-64 system resolves to something like + bash_4.1-r2.x86_64.ipk and + lib32-bash_4.1-rw_x86.ipk, respectively. + + The IPK deploy folder is not modified with + ${MLPREFIX} because packages with and without + the Multilib feature can exist in the same folder due to the + ${PN} differences. + IPK defines a sanity check for Multilib installation + using certain rules for file comparison, overridden, etc. + + + +
+
+ +
+ Installing Multiple Versions of the Same Library + + + Situations can exist where you need to install and use + multiple versions of the same library on the same system + at the same time. + These situations almost always exist when a library API + changes and you have multiple pieces of software that + depend on the separate versions of the library. + To accommodate these situations, you can install multiple + versions of the same library in parallel on the same system. + + + + The process is straightforward as long as the libraries use + proper versioning. + With properly versioned libraries, all you need to do to + individually specify the libraries is create separate, + appropriately named recipes where the + PN part of the + name includes a portion that differentiates each library version + (e.g.the major part of the version number). + Thus, instead of having a single recipe that loads one version + of a library (e.g. clutter), you provide + multiple recipes that result in different versions + of the libraries you want. + As an example, the following two recipes would allow the + two separate versions of the clutter + library to co-exist on the same system: + + clutter-1.6_1.6.20.bb + clutter-1.8_1.8.4.bb + + Additionally, if you have other recipes that depend on a given + library, you need to use the + DEPENDS + variable to create the dependency. + Continuing with the same example, if you want to have a recipe + depend on the 1.8 version of the clutter + library, use the following in your recipe: + + DEPENDS = "clutter-1.8" + + +
+
+ +
+ Creating Partitioned Images + + + Creating an image for a particular hardware target using the + OpenEmbedded build system does not necessarily mean you can boot + that image as is on your device. + Physical devices accept and boot images in various ways depending + on the specifics of the device. + Usually, information about the hardware can tell you what image + format the device requires. + Should your device require multiple partitions on an SD card, flash, + or an HDD, you can use the OpenEmbedded Image Creator, + wic, to create the properly partitioned image. + + + + The wic command generates partitioned images + from existing OpenEmbedded build artifacts. + Image generation is driven by partitioning commands contained + in an Openembedded kickstart file (.wks) + specified either directly on the command line or as one of a + selection of canned .wks files as shown + with the wic list images command in the + "Using an Existing Kickstart File" + section. + When applied to a given set of build artifacts, the result is an + image or set of images that can be directly written onto media and + used on a particular system. + + + + The wic command and the infrastructure + it is based on is by definition incomplete. + Its purpose is to allow the generation of customized images, + and as such was designed to be completely extensible through a + plugin interface. + See the + "Plugins" + section for information on these plugins. + + + + This section provides some background information on + wic, describes what you need to have in + place to run the tool, provides instruction on how to use + wic, and provides several examples. + + +
+ Background + + + This section provides some background on the + wic utility. + While none of this information is required to use + wic, you might find it interesting. + + + The name "wic" is derived from OpenEmbedded + Image Creator (oeic). + The "oe" diphthong in "oeic" was promoted to the + letter "w", because "oeic" is both difficult to remember and + pronounce. + + wic is loosely based on the + Meego Image Creator (mic) + framework. + The wic implementation has been + heavily modified to make direct use of OpenEmbedded + build artifacts instead of package installation and + configuration, which are already incorporated within + the OpenEmbedded artifacts. + + wic is a completely independent + standalone utility that initially provides + easier-to-use and more flexible replacements for a + couple bits of existing functionality in OE Core's + boot-directdisk.bbclass and + mkefidisk.sh scripts. + The difference between + wic and those examples is + that with wic the + functionality of those scripts is implemented + by a general-purpose partitioning language, which is + based on Redhat kickstart syntax. + + +
+ +
+ Requirements + + + In order to use the wic utility + with the OpenEmbedded Build system, your system needs + to meet the following requirements: + + The Linux distribution on your + development host must support the Yocto Project. + See the + "Supported Linux Distributions" + section in the Yocto Project Reference Manual for this + list of distributions. + + The standard system utilities, such as + cp, must be installed on your + development host system. + + + The + GNU Parted + package must be installed on your development host + system. + + + You need to have the build artifacts already + available, which typically means that you must + have already created an image using the + Openembedded build system (e.g. + core-image-minimal). + While it might seem redundant to generate an image in + order to create an image using + wic, the current version of + wic requires the artifacts + in the form generated by the build system. + + + You must have sourced one of the build environment + setup scripts (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres) + found in the + Build Directory. + + + +
+ +
+ Getting Help + + + You can get general help for the wic + by entering the wic command by itself + or by entering the command with a help argument as follows: + + $ wic -h + $ wic ‐‐help + + + + + Currently, wic supports two commands: + create and list. + You can get help for these commands as follows: + + $ wic help command + + + + + You can also get detailed help on a number of topics + from the help system. + The output of wic ‐‐help + displays a list of available help + topics under a "Help topics" heading. + You can have the help system display the help text for + a given topic by prefacing the topic with + wic help: + + $ wic help help_topic + + + + + You can find out more about the images + wic creates using the existing + kickstart files with the following form of the command: + + $ wic list image help + + where image is either + directdisk or + mkefidisk. + +
+ +
+ Operational Modes + + + You can use wic in two different + modes, depending on how much control you need for + specifying the Openembedded build artifacts that are + used for creating the image: Raw and Cooked: + + Raw Mode: + You explicitly specify build artifacts through + command-line arguments. + Cooked Mode: + The current + MACHINE + setting and image name are used to automatically locate + and provide the build artifacts. + + + + + Regardless of the mode you use, you need to have the build + artifacts ready and available. + Additionally, the environment must be set up using the + &OE_INIT_FILE; + or + oe-init-build-env-memres + script found in the + Build Directory. + + +
+ Raw Mode + + + The general form of the 'wic' command in raw mode is: + + $ wic create image_name.wks [options] [...] + + Where: + + image_name.wks + An OpenEmbedded kickstart file. You can provide + your own custom file or use a file from a set of + existing files as described by further options. + + -o OUTDIR, ‐‐outdir=OUTDIR + The name of a directory in which to create image. + + -i PROPERTIES_FILE, ‐‐infile=PROPERTIES_FILE + The name of a file containing the values for image + properties as a JSON file. + + -e IMAGE_NAME, ‐‐image-name=IMAGE_NAME + The name of the image from which to use the artifacts + (e.g. core-image-sato). + + -r ROOTFS_DIR, ‐‐rootfs-dir=ROOTFS_DIR + The path to the /rootfs directory to use as the + .wks rootfs source. + + -b BOOTIMG_DIR, ‐‐bootimg-dir=BOOTIMG_DIR + The path to the directory containing the boot artifacts + (e.g. /EFI or /syslinux) to use as the .wks bootimg + source. + + -k KERNEL_DIR, ‐‐kernel-dir=KERNEL_DIR + The path to the directory containing the kernel to use + in the .wks boot image. + + -n NATIVE_SYSROOT, ‐‐native-sysroot=NATIVE_SYSROOT + The path to the native sysroot containing the tools to use + to build the image. + + -s, ‐‐skip-build-check + Skips the build check. + + -D, ‐‐debug + Output debug information. + + + You do not need root privileges to run + wic. + In fact, you should not run as root when using the + utility. + + +
+ +
+ Cooked Mode + + + The general form of the wic command + using Cooked Mode is: + + $ wic create kickstart_file -e image_name + + Where: + + kickstart_file + An OpenEmbedded kickstart file. You can provide your own + custom file or supplied file. + + image_name + Specifies the image built using the OpenEmbedded build + system. + + This form is the simplest and most user-friendly, as it + does not require specifying all individual parameters. + All you need to provide is your own + .wks file or one provided with the + release. + +
+
+ +
+ Using an Existing Kickstart File + + + If you do not want to create your own + .wks file, you can use an existing + file provided by the wic installation. + Use the following command to list the available files: + + $ wic list images + directdisk Create a 'pcbios' direct disk image + mkefidisk Create an EFI disk image + + When you use an existing file, you do not have to use the + .wks extension. + Here is an example in Raw Mode that uses the + directdisk file: + + $ wic create directdisk -r rootfs_dir -b bootimg_dir \ + -k kernel_dir -n native_sysroot + + + + + Here are the actual partition language commands + used in the mkefidisk.wks file to generate + an image: + + # short-description: Create an EFI disk image + # long-description: Creates a partitioned EFI disk image that the user + # can directly dd to boot media. + + part /boot --source bootimg-efi --ondisk sda --label msdos --active --align 1024 + + part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 + + part swap --ondisk sda --size 44 --label swap1 --fstype=swap + + bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0" + + +
+ +
+ Examples + + + This section provides several examples that show how to use + the wic utility. + All the examples assume the list of requirements in the + "Requirements" section + have been met. + The examples assume the previously generated image is + core-image-minimal. + + +
+ Generate an Image using an Existing Kickstart File + + + This example runs in Cooked Mode and uses the + mkefidisk kickstart file: + + $ wic create mkefidisk -e core-image-minimal + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/mkefidisk-201310230946-sda.direct + + The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks + + This example shows the easiest way to create an image + by running in Cooked Mode and using the + -e option with an existing kickstart + file. + All that is necessary is to specify the image used to + generate the artifacts. + Your local.conf needs to have the + MACHINE + variable set to the machine you are using, which is + "minnow" in this example. + + + + The output specifies the exact created as well as where + it was created. + The output also names the artifacts used and the exact + .wks script that was used to generate + the image. + + You should always verify the details provided in the + output to make sure that the image was indeed created + exactly as expected. + + + + + Continuing with the example, you can now directly + dd the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + + $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb + [sudo] password for trz: + 182274+0 records in + 182274+0 records out + 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s + [trz@empanada ~]$ sudo eject /dev/sdb + + +
+ +
+ Using a Modified Kickstart File + + + Because wic image creation is driven + by the kickstart file, it is easy to affect image creation + by changing the parameters in the file. + This next example demonstrates that through modification + of the directdisk kickstart file. + + + + As mentioned earlier, you can use the command + wic list images to show the list + of existing kickstart files. + The directory in which these files reside is + scripts/lib/image/canned-wks/ + located in the + Source Directory. + Because the available files reside in this directory, you + can create and add your own custom files to the directory. + Subsequent use of the wic list images + command would then include your kickstart files. + + + + In this example, the existing + directdisk file already does most + of what is needed. + However, for the hardware in this example, the image will + need to boot from sdb instead of + sda, which is what the + directdisk kickstart file uses. + + + + The example begins by making a copy of the + directdisk.wks file in the + scripts/lib/image/canned-wks + directory and then changing the lines that specify the + target disk from which to boot. + + $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks + + Next, the example modifies the + directdisksdb.wks file and changes all + instances of "‐‐ondisk sda" + to "‐‐ondisk sdb". + The example changes the following two lines and leaves the + remaining lines untouched: + + part /boot ‐‐source bootimg-pcbios ‐‐ondisk sdb ‐‐label boot ‐‐active ‐‐align 1024 + part / ‐‐source rootfs ‐‐ondisk sdb ‐‐fstype=ext3 ‐‐label platform ‐‐align 1024 + + Once the lines are changed, the example generates the + directdisksdb image. + The command points the process at the + core-image-minimal artifacts for the + Next Unit of Computing (nuc) + MACHINE + the local.conf. + + $ wic create directdisksdb -e core-image-minimal + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct + + The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks + + Continuing with the example, you can now directly + dd the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + + $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb + 86018+0 records in + 86018+0 records out + 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s + [trz@empanada tmp]$ sudo eject /dev/sdb + + +
+ +
+ Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename> + + + This example creates an image based on + core-image-minimal and a + crownbay-noemgd + MACHINE + that works right out of the box. + + $ wic create directdisk -e core-image-minimal + + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/directdisk-201309252350-sda.direct + + The following build artifacts were used to create the image(s): + + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks + + +
+ +
+ Using a Modified Kickstart File and Running in Raw Mode + + + This next example manually specifies each build artifact + (runs in Raw Mode) and uses a modified kickstart file. + The example also uses the -o option + to cause wic to create the output + somewhere other than the default + /var/tmp/wic directory: + + $ wic create ~/test.wks -o /home/trz/testwic ‐‐rootfs-dir \ + /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ + ‐‐bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ + ‐‐kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ + ‐‐native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + Creating image(s)... + + Info: The new image(s) can be found here: + /home/trz/testwic/build/test-201309260032-sda.direct + + The following build artifacts were used to create the image(s): + + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + + The image(s) were created using OE kickstart file: + /home/trz/test.wks + + For this example, + MACHINE + did not have to be specified in the + local.conf file since the artifact is + manually specified. + +
+
+ +
+ Plugins + + + Plugins allow wic functionality to + be extended and specialized by users. + This section documents the plugin interface, which is + currently restricted to source plugins. + + + + Source plugins provide a mechanism to customize + various aspects of the image generation process in + wic, mainly the contents of + partitions. + The plugins provide a mechanism for mapping values + specified in .wks files using the + ‐‐source keyword to a + particular plugin implementation that populates a + corresponding partition. + + + + A source plugin is created as a subclass of + SourcePlugin. + The plugin file containing it is added to + scripts/lib/mic/plugins/source/ to + make the plugin implementation available to the + wic implementation. + For more information, see + scripts/lib/mic/pluginbase.py. + + + + Source plugins can also be implemented and added by + external layers. + As such, any plugins found in a + scripts/lib/mic/plugins/source/ + directory in an external layer are also made + available. + + + + When the wic implementation needs + to invoke a partition-specific implementation, it looks + for the plugin that has the same name as the + ‐‐source parameter given to + that partition. + For example, if the partition is set up as follows: + + part /boot ‐‐source bootimg-pcbios ... + + The methods defined as class members of the plugin + having the matching bootimg-pcbios.name + class member are used. + + + + To be more concrete, here is the plugin definition that + matches a + ‐‐source bootimg-pcbios usage, + along with an example + method called by the wic implementation + when it needs to invoke an implementation-specific + partition-preparation function: + + class BootimgPcbiosPlugin(SourcePlugin): + name = 'bootimg-pcbios' + + @classmethod + def do_prepare_partition(self, part, ...) + + If the subclass itself does not implement a function, a + default version in a superclass is located and + used, which is why all plugins must be derived from + SourcePlugin. + + + + The SourcePlugin class defines the + following methods, which is the current set of methods + that can be implemented or overridden by + ‐‐source plugins. + Any methods not implemented by a + SourcePlugin subclass inherit the + implementations present in the + SourcePlugin class. + For more information, see the + SourcePlugin source for details: + + + + + do_prepare_partition(): + Called to do the actual content population for a + partition. + In other words, the method prepares the final + partition image that is incorporated into the + disk image. + + do_configure_partition(): + Called before + do_prepare_partition(). + This method is typically used to create custom + configuration files for a partition (e.g. syslinux or + grub configuration files). + + do_install_disk(): + Called after all partitions have been prepared and + assembled into a disk image. + This method provides a hook to allow finalization of a + disk image, (e.g. writing an MBR). + + do_stage_partition(): + Special content-staging hook called before + do_prepare_partition(). + This method is normally empty. + Typically, a partition just uses the passed-in + parameters (e.g. the unmodified value of + bootimg_dir). + However, in some cases things might need to be + more tailored. + As an example, certain files might additionally + need to be taken from + bootimg_dir + /boot. + This hook allows those files to be staged in a + customized fashion. + + get_bitbake_var() + allows you to access non-standard variables + that you might want to use for this. + + + + + + + This scheme is extensible. + Adding more hooks is a simple matter of adding more + plugin methods to SourcePlugin and + derived classes. + The code that then needs to call the plugin methods uses + plugin.get_source_plugin_methods() + to find the method or methods needed by the call. + Retrieval of those methods is accomplished + by filling up a dict with keys + containing the method names of interest. + On success, these will be filled in with the actual + methods. + Please see the wic + implementation for examples and details. + +
+ +
+ OpenEmbedded Kickstart (.wks) Reference + + + The current wic implementation supports + only the basic kickstart partitioning commands: + partition (or part + for short) and bootloader. + + Future updates will implement more commands and options. + If you use anything that is not specifically + supported, results can be unpredictable. + + + + + The following is a list of the commands, their syntax, + and meanings. + The commands are based on the Fedora + kickstart versions but with modifications to + reflect wic capabilities. + You can see the original documentation for those commands + at the following links: + + + http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition + + + http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader + + + + +
+ Command: part or partition + + + This command creates a partition on the system and uses the + following syntax: + + part mntpoint + + The mntpoint + is where the + partition will be mounted and must be of one of the + following forms: + + /path: + For example, /, + /usr, and + /home + swap: + The partition will be used as swap space. + + + + + + Following are the supported options: + + ‐‐size: + The minimum partition size in MBytes. + Specify an integer value such as 500. + Do not append the number with "MB". + You do not need this option if you use + ‐‐source. + ‐‐source: + This option is a + wic-specific option that + names the source of the data that populates + the partition. + The most common value for this option is + "rootfs", but you can use any value that maps to + a valid source plugin. + For information on the source plugins, see the + "Plugins" + section. + If you use + ‐‐source rootfs, + wic creates a partition as + large as needed and to fill it with the contents of + the root filesystem pointed to by the + -r command-line option + or the equivalent rootfs derived from the + -e command-line + option. + The filesystem type used to create the + partition is driven by the value of the + ‐‐fstype option + specified for the partition. + See the entry on + ‐‐fstype that + follows for more information. + + If you use + ‐‐source plugin-name, + wic creates a partition as + large as needed and fills it with the contents of + the partition that is generated by the + specified plugin name using the data pointed + to by the -r command-line + option or the equivalent rootfs derived from the + -e command-line + option. + Exactly what those contents and + filesystem type end up being are dependent + on the given plugin implementation. + + ‐‐ondisk or ‐‐ondrive: + Forces the partition to be created on a particular + disk. + ‐‐fstype: + Sets the file system type for the partition. + Valid values are: + + ext4 + + ext3 + + ext2 + + btrfs + + squashfs + + swap + + + ‐‐fsoptions: + Specifies a free-form string of options to be + used when mounting the filesystem. + This string will be copied into the + /etc/fstab file of the + installed system and should be enclosed in + quotes. + If not specified, the default string + is "defaults". + + ‐‐label label: + Specifies the label to give to the filesystem to + be made on the partition. + If the given label is already in use by another + filesystem, a new label is created for the + partition. + ‐‐active: + Marks the partition as active. + ‐‐align (in KBytes): + This option is a wic-specific + option that says to start a partition on an + x KBytes boundary. + + +
+ +
+ Command: bootloader + + + This command specifies how the boot loader should be + configured and supports the following options: + + Bootloader functionality and boot partitions are + implemented by the various + ‐‐source + plugins that implement bootloader functionality. + The bootloader command essentially provides a means of + modifying bootloader configuration. + + + ‐‐timeout: + Specifies the number of seconds before the + bootloader times out and boots the default option. + + ‐‐append: + Specifies kernel parameters. + These parameters will be added to the syslinux + APPEND or + grub kernel command line. + + + +
+
+
+ +
+ Configuring the Kernel + + + Configuring the Yocto Project kernel consists of making sure the .config + file has all the right information in it for the image you are building. + You can use the menuconfig tool and configuration fragments to + make sure your .config file is just how you need it. + This section describes how to use menuconfig, create and use + configuration fragments, and how to interactively modify your .config + file to create the leanest kernel configuration file possible. + + + + For more information on kernel configuration, see the + "Changing the Configuration" + section in the Yocto Project Linux Kernel Development Manual. + + +
+ Using  <filename>menuconfig</filename> + + + The easiest way to define kernel configurations is to set them through the + menuconfig tool. + This tool provides an interactive method with which + to set kernel configurations. + For general information on menuconfig, see + . + + + + To use the menuconfig tool in the Yocto Project development + environment, you must launch it using BitBake. + Thus, the environment must be set up using the + &OE_INIT_FILE; + or + oe-init-build-env-memres + script found in the + Build Directory. + The following commands run menuconfig assuming the + Source Directory + top-level folder is ~/poky: + + $ cd poky + $ source oe-init-build-env + $ bitbake linux-yocto -c menuconfig + + Once menuconfig comes up, its standard interface allows you to + interactively examine and configure all the kernel configuration parameters. + After making your changes, simply exit the tool and save your changes to + create an updated version of the .config configuration file. + + + + Consider an example that configures the linux-yocto-3.14 + kernel. + The OpenEmbedded build system recognizes this kernel as + linux-yocto. + Thus, the following commands from the shell in which you previously sourced the + environment initialization script cleans the shared state cache and the + WORKDIR + directory and then runs menuconfig: + + $ bitbake linux-yocto -c menuconfig + + + + + Once menuconfig launches, use the interface + to navigate through the selections to find the configuration settings in + which you are interested. + For example, consider the CONFIG_SMP configuration setting. + You can find it at Processor Type and Features under + the configuration selection Symmetric Multi-processing Support. + After highlighting the selection, use the arrow keys to select or deselect + the setting. + When you are finished with all your selections, exit out and save them. + + + + Saving the selections updates the .config configuration file. + This is the file that the OpenEmbedded build system uses to configure the + kernel during the build. + You can find and examine this file in the Build Directory in + tmp/work/. + The actual .config is located in the area where the + specific kernel is built. + For example, if you were building a Linux Yocto kernel based on the + Linux 3.14 kernel and you were building a QEMU image targeted for + x86 architecture, the + .config file would be located here: + + poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f... + ...656ed30-r1/linux-qemux86-standard-build + + + The previous example directory is artificially split and many of the characters + in the actual filename are omitted in order to make it more readable. + Also, depending on the kernel you are using, the exact pathname + for linux-yocto-3.14... might differ. + + + + + Within the .config file, you can see the kernel settings. + For example, the following entry shows that symmetric multi-processor support + is not set: + + # CONFIG_SMP is not set + + + + + A good method to isolate changed configurations is to use a combination of the + menuconfig tool and simple shell commands. + Before changing configurations with menuconfig, copy the + existing .config and rename it to something else, + use menuconfig to make + as many changes as you want and save them, then compare the renamed configuration + file against the newly created file. + You can use the resulting differences as your base to create configuration fragments + to permanently save in your kernel layer. + + Be sure to make a copy of the .config and don't just + rename it. + The build system needs an existing .config + from which to work. + + +
+ +
+ Creating Configuration Fragments + + + Configuration fragments are simply kernel options that appear in a file + placed where the OpenEmbedded build system can find and apply them. + Syntactically, the configuration statement is identical to what would appear + in the .config file, which is in the + Build Directory in + tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type>. + + + + It is simple to create a configuration fragment. + For example, issuing the following from the shell creates a configuration fragment + file named my_smp.cfg that enables multi-processor support + within the kernel: + + $ echo "CONFIG_SMP=y" >> my_smp.cfg + + + All configuration files must use the .cfg extension in order + for the OpenEmbedded build system to recognize them as a configuration fragment. + + + + + Where do you put your configuration files? + You can place these configuration files in the same area pointed to by + SRC_URI. + The OpenEmbedded build system will pick up the configuration and add it to the + kernel's configuration. + For example, suppose you had a set of configuration options in a file called + myconfig.cfg. + If you put that file inside a directory named linux-yocto + that resides in the same directory as the kernel's append file and then add + a SRC_URI statement such as the following to the kernel's append file, + those configuration options will be picked up and applied when the kernel is built. + + SRC_URI += "file://myconfig.cfg" + + + + + As mentioned earlier, you can group related configurations into multiple files and + name them all in the SRC_URI statement as well. + For example, you could group separate configurations specifically for Ethernet and graphics + into their own files and add those by using a SRC_URI statement like the + following in your append file: + + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + + +
+ +
+ Fine-Tuning the Kernel Configuration File + + + You can make sure the .config file is as lean or efficient as + possible by reading the output of the kernel configuration fragment audit, + noting any issues, making changes to correct the issues, and then repeating. + + + + As part of the kernel build process, the + do_kernel_configcheck task runs. + This task validates the kernel configuration by checking the final + .config file against the input files. + During the check, the task produces warning messages for the following + issues: + + Requested options that did not make the final + .config file. + Configuration items that appear twice in the same + configuration fragment. + Configuration items tagged as "required" that were overridden. + + A board overrides a non-board specific option. + Listed options not valid for the kernel being processed. + In other words, the option does not appear anywhere. + + + The do_kernel_configcheck task can + also optionally report if an option is overridden during + processing. + + + + + For each output warning, a message points to the file + that contains a list of the options and a pointer to the config + fragment that defines them. + Collectively, the files are the key to streamlining the configuration. + + + + To streamline the configuration, do the following: + + Start with a full configuration that you + know works - it builds and boots successfully. + This configuration file will be your baseline. + + Separately run the + do_configme and + do_kernel_configcheck tasks. + + Take the resulting list of files from the + do_kernel_configcheck task + warnings and do the following: + + + Drop values that are redefined in the fragment + but do not change the final + .config file. + + + Analyze and potentially drop values from the + .config file that override + required configurations. + + + Analyze and potentially remove non-board + specific options. + + + Remove repeated and invalid options. + + + + After you have worked through the output of the kernel + configuration audit, you can re-run the + do_configme and + do_kernel_configcheck tasks to + see the results of your changes. + If you have more issues, you can deal with them as + described in the previous step. + + + + + + Iteratively working through steps two through four eventually yields + a minimal, streamlined configuration file. + Once you have the best .config, you can build the Linux + Yocto kernel. + +
+
+ +
+ Patching the Kernel + + + Patching the kernel involves changing or adding configurations to an existing kernel, + changing or adding recipes to the kernel that are needed to support specific hardware features, + or even altering the source code itself. + + You can use the yocto-kernel script + found in the Source Directory + under scripts to manage kernel patches and configuration. + See the "Managing kernel Patches and Config Items with yocto-kernel" + section in the Yocto Project Board Support Packages (BSP) Developer's Guide for + more information. + + + + This example creates a simple patch by adding some QEMU emulator console + output at boot time through printk statements in the kernel's + calibrate.c source code file. + Applying the patch and booting the modified image causes the added + messages to appear on the emulator's console. + + + + The example assumes a clean build exists for the qemux86 + machine in a + Source Directory + named poky. + Furthermore, the Build Directory is + build and is located in poky and + the kernel is based on the Linux 3.4 kernel. + For general information on how to configure the most efficient build, see the + "Building an Image" section + in the Yocto Project Quick Start. + + + + Also, for more information on patching the kernel, see the + "Applying Patches" + section in the Yocto Project Linux Kernel Development Manual. + + +
+ Create a Layer for your Changes + + + The first step is to create a layer so you can isolate your + changes. + Rather than use the yocto-layer script + to create the layer, this example steps through the process + by hand. + If you want information on the script that creates a general + layer, see the + "Creating a General Layer Using the yocto-layer Script" + section. + + + + These two commands create a directory you can use for your + layer: + + $ cd ~/poky + $ mkdir meta-mylayer + + Creating a directory that follows the Yocto Project layer naming + conventions sets up the layer for your changes. + The layer is where you place your configuration files, append + files, and patch files. + To learn more about creating a layer and filling it with the + files you need, see the "Understanding + and Creating Layers" section. + +
+ +
+ Finding the Kernel Source Code + + + Each time you build a kernel image, the kernel source code is fetched + and unpacked into the following directory: + + ${S}/linux + + See the "Finding the Temporary Source Code" + section and the + S variable + for more information about where source is kept during a build. + + + + For this example, we are going to patch the + init/calibrate.c file + by adding some simple console printk statements that we can + see when we boot the image using QEMU. + +
+ +
+ Creating the Patch + + + Two methods exist by which you can create the patch: + Git workflow and + Quilt workflow. + For kernel patches, the Git workflow is more appropriate. + This section assumes the Git workflow and shows the steps specific to + this example. + + Change the working directory: + Change to where the kernel source code is before making + your edits to the calibrate.c file: + + $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux + + Because you are working in an established Git repository, + you must be in this directory in order to commit your changes + and create the patch file. + The PV and + PR variables + represent the version and revision for the + linux-yocto recipe. + The PV variable includes the Git meta and machine + hashes, which make the directory name longer than you might + expect. + + Edit the source file: + Edit the init/calibrate.c file to have the + following changes: + + void calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + + Stage and commit your changes: + These Git commands display the modified file, stage it, and then + commit the file: + + $ git status + $ git add init/calibrate.c + $ git commit -m "calibrate: Add printk example" + + Generate the patch file: + This Git command creates the a patch file named + 0001-calibrate-Add-printk-example.patch + in the current directory. + + $ git format-patch -1 + + + + +
+ +
+ Set Up Your Layer for the Build + + These steps get your layer set up for the build: + + Create additional structure: + Create the additional layer structure: + + $ cd ~/poky/meta-mylayer + $ mkdir conf + $ mkdir recipes-kernel + $ mkdir recipes-kernel/linux + $ mkdir recipes-kernel/linux/linux-yocto + + The conf directory holds your configuration files, while the + recipes-kernel directory holds your append file and + your patch file. + Create the layer configuration file: + Move to the meta-mylayer/conf directory and create + the layer.conf file as follows: + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "mylayer" + BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" + BBFILE_PRIORITY_mylayer = "5" + + Notice mylayer as part of the last three + statements. + Create the kernel recipe append file: + Move to the meta-mylayer/recipes-kernel/linux directory and create + the linux-yocto_3.4.bbappend file as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + SRC_URI += "file://0001-calibrate-Add-printk-example.patch" + + The FILESEXTRAPATHS + and SRC_URI + statements enable the OpenEmbedded build system to find the patch file. + For more information on using append files, see the + "Using .bbappend Files" + section. + + Put the patch file in your layer: + Move the 0001-calibrate-Add-printk-example.patch file to + the meta-mylayer/recipes-kernel/linux/linux-yocto + directory. + + +
+ +
+ Set Up for the Build + + + Do the following to make sure the build parameters are set up for the example. + Once you set up these build parameters, they do not have to change unless you + change the target architecture of the machine you are building: + + Build for the correct target architecture: Your + selected MACHINE + definition within the local.conf file in the + Build Directory + specifies the target architecture used when building the Linux kernel. + By default, MACHINE is set to + qemux86, which specifies a 32-bit + Intel Architecture + target machine suitable for the QEMU emulator. + Identify your meta-mylayer + layer: The + BBLAYERS + variable in the + bblayers.conf file found in the + poky/build/conf directory needs to have the path to your local + meta-mylayer layer. + By default, the BBLAYERS variable contains paths to + meta, meta-yocto, and + meta-yocto-bsp in the + poky Git repository. + Add the path to your meta-mylayer location: + + BBLAYERS ?= " \ + $HOME/poky/meta \ + $HOME/poky/meta-yocto \ + $HOME/poky/meta-yocto-bsp \ + $HOME/poky/meta-mylayer \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + $HOME/poky/meta \ + $HOME/poky/meta-yocto \ + " + + + +
+ +
+ Build the Modified QEMU Kernel Image + + + The following steps build your modified kernel image: + + Be sure your build environment is initialized: + Your environment should be set up since you previously sourced + the + &OE_INIT_FILE; + script. + If it is not, source the script again from poky. + + $ cd ~/poky + $ source &OE_INIT_FILE; + + + Clean up: + Be sure to clean the shared state out by using BitBake + to run from within the Build Directory the + do_cleansstate + task as follows: + + $ bitbake -c cleansstate linux-yocto + + + + Never remove any files by hand from the + tmp/deploy + directory inside the + Build Directory. + Always use the various BitBake clean tasks to + clear out previous build artifacts. + For information on the clean tasks, see the + "do_clean", + "do_cleanall", + and + "do_cleansstate" + sections all in the Yocto Project Reference + Manual. + + + Build the image: + Next, build the kernel image using this command: + + $ bitbake -k linux-yocto + + + +
+ +
+ Boot the Image and Verify Your Changes + + + These steps boot the image and allow you to see the changes + + Boot the image: + Boot the modified image in the QEMU emulator + using this command: + + $ runqemu qemux86 + + Verify the changes: + Log into the machine using root with no password and then + use the following shell command to scroll through the console's boot output. + + # dmesg | less + + You should see the results of your printk statements + as part of the output. + + +
+
+ +
+ Making Images More Secure + + + Security is of increasing concern for embedded devices. + Consider the issues and problems discussed in just this + sampling of work found across the Internet: + + + "Security Risks of Embedded Systems" + by Bruce Schneier + + + "Internet Census 2012" + by Carna Botnet + + "Security Issues for Embedded Devices" + by Jake Edge + + + "They ought to know better: Exploiting Security +Gateways via their Web Interfaces" + by Ben Williams + + + + + + When securing your image is of concern, there are steps, tools, + and variables that you can consider to help you reach the + security goals you need for your particular device. + Not all situations are identical when it comes to making an + image secure. + Consequently, this section provides some guidance and suggestions + for consideration when you want to make your image more secure. + + Because the security requirements and risks are + different for every type of device, this section cannot + provide a complete reference on securing your custom OS. + It is strongly recommended that you also consult other sources + of information on embedded Linux system hardening and on + security. + + + +
+ General Considerations + + + General considerations exist that help you create more + secure images. + You should consider the following suggestions to help + make your device more secure: + + + Scan additional code you are adding to the system + (e.g. application code) by using static analysis + tools. + Look for buffer overflows and other potential + security problems. + + + Pay particular attention to the security for + any web-based administration interface. + + Web interfaces typically need to perform + administrative functions and tend to need to run with + elevated privileges. + Thus, the consequences resulting from the interface's + security becoming compromised can be serious. + Look for common web vulnerabilities such as + cross-site-scripting (XSS), unvalidated inputs, + and so forth. + As with system passwords, the default credentials + for accessing a web-based interface should not be the + same across all devices. + This is particularly true if the interface is enabled + by default as it can be assumed that many end-users + will not change the credentials. + + + Ensure you can update the software on the device to + mitigate vulnerabilities discovered in the future. + This consideration especially applies when your + device is network-enabled. + + + Ensure you remove or disable debugging functionality + before producing the final image. + For information on how to do this, see the + "Considerations Specific to the OpenEmbedded Build System" + section. + + + Ensure you have no network services listening that + are not needed. + + + Remove any software from the image that is not needed. + + + Enable hardware support for secure boot functionality + when your device supports this functionality. + + + +
+ +
+ Security Flags + + + The Yocto Project has security flags that you can enable that + help make your build output more secure. + The security flags are in the + meta/conf/distro/include/security_flags.inc + file in your + Source Directory + (e.g. poky). + + Depending on the recipe, certain security flags are enabled + and disabled by default. + + + + + + Use the following line in your + local.conf file or in your custom + distribution configuration file to enable the security + compiler and linker flags for your build: + + require conf/distro/include/security_flags.inc + + +
+ +
+ Considerations Specific to the OpenEmbedded Build System + + + You can take some steps that are specific to the + OpenEmbedded build system to make your images more secure: + + + Ensure "debug-tweaks" is not one of your selected + IMAGE_FEATURES. + When creating a new project, the default is to provide you + with an initial local.conf file that + enables this feature using the + EXTRA_IMAGE_FEATURES variable with the line: + + EXTRA_IMAGE_FEATURES = "debug-tweaks" + + To disable that feature, simply comment out that line in your + local.conf file, or + make sure IMAGE_FEATURES does not contain + "debug-tweaks" before producing your final image. + Among other things, leaving this in place sets the + root password as blank, which makes logging in for + debugging or inspection easy during + development but also means anyone can easily log in + during production. + + + It is possible to set a root password for the image + and also to set passwords for any extra users you might + add (e.g. administrative or service type users). + When you set up passwords for multiple images or + users, you should not duplicate passwords. + + + To set up passwords, use the + extrausers + class, which is the preferred method. + For an example on how to set up both root and user + passwords, see the + "extrausers.bbclass" + section. + + When adding extra user accounts or setting a + root password, be cautious about setting the + same password on every device. + If you do this, and the password you have set + is exposed, then every device is now potentially + compromised. + If you need this access but want to ensure + security, consider setting a different, + random password for each device. + Typically, you do this as a separate step after + you deploy the image onto the device. + + + + Consider enabling a Mandatory Access Control (MAC) + framework such as SMACK or SELinux and tuning it + appropriately for your device's usage. + You can find more information in the + meta-selinux + layer. + + + + + + +
+ +
+ Tools for Hardening Your Image + + + The Yocto Project provides tools for making your image + more secure. + You can find these tools in the + meta-security layer of the + Yocto Project Source Repositories. + +
+
+ +
+ Creating Your Own Distribution + + + When you build an image using the Yocto Project and + do not alter any distribution + Metadata, you are creating a + Poky distribution. + If you wish to gain more control over package alternative + selections, compile-time options, and other low-level + configurations, you can create your own distribution. + + + + To create your own distribution, the basic steps consist of + creating your own distribution layer, creating your own + distribution configuration file, and then adding any needed + code and Metadata to the layer. + The following steps provide some more detail: + + Create a layer for your new distro: + Create your distribution layer so that you can keep your + Metadata and code for the distribution separate. + It is strongly recommended that you create and use your own + layer for configuration and code. + Using your own layer as compared to just placing + configurations in a local.conf + configuration file makes it easier to reproduce the same + build configuration when using multiple build machines. + See the + "Creating a General Layer Using the yocto-layer Script" + section for information on how to quickly set up a layer. + + Create the distribution configuration file: + The distribution configuration file needs to be created in + the conf/distro directory of your + layer. + You need to name it using your distribution name + (e.g. mydistro.conf). + + The + DISTRO + variable in your + local.conf file determines the + name of your distribution. + + You can split out parts of your configuration file + into include files and then "require" them from within + your distribution configuration file. + Be sure to place the include files in the + conf/distro/include directory of + your layer. + A common example usage of include files would be to + separate out the selection of desired version and revisions + for individual recipes. + + Your configuration file needs to set the following + required variables: + + DISTRO_NAME + DISTRO_VERSION + + These following variables are optional and you typically + set them from the distribution configuration file: + + DISTRO_FEATURES + DISTRO_EXTRA_RDEPENDS + DISTRO_EXTRA_RRECOMMENDS + TCLIBC + + + If you want to base your distribution configuration file + on the very basic configuration from OE-Core, you + can use + conf/distro/defaultsetup.conf as + a reference and just include variables that differ + as compared to defaultsetup.conf. + Alternatively, you can create a distribution + configuration file from scratch using the + defaultsetup.conf file + or configuration files from other distributions + such as Poky or Angstrom as references. + + Provide miscellaneous variables: + Be sure to define any other variables for which you want to + create a default or enforce as part of the distribution + configuration. + You can include nearly any variable from the + local.conf file. + The variables you use are not limited to the list in the + previous bulleted item. + Point to Your distribution configuration file: + In your local.conf file in the + Build Directory, + set your + DISTRO + variable to point to your distribution's configuration file. + For example, if your distribution's configuration file is + named mydistro.conf, then you point + to it as follows: + + DISTRO = "mydistro" + + Add more to the layer if necessary: + Use your layer to hold other information needed for the + distribution: + + Add recipes for installing + distro-specific configuration files that are not + already installed by another recipe. + If you have distro-specific configuration files + that are included by an existing recipe, you should + add an append file (.bbappend) + for those. + For general information and recommendations + on how to add recipes to your layer, see the + "Creating Your Own Layer" + and + "Best Practices to Follow When Creating Layers" + sections. + Add any image recipes that are specific + to your distribution. + Add a psplash + append file for a branded splash screen. + For information on append files, see the + "Using .bbappend Files" + section. + Add any other append files to make + custom changes that are specific to individual + recipes. + + + +
+ +
+ Creating a Custom Template Configuration Directory + + + If you are producing your own customized version + of the build system for use by other users, you might + want to customize the message shown by the setup script or + you might want to change the template configuration files (i.e. + local.conf and + bblayers.conf) that are created in + a new build directory. + + + + The OpenEmbedded build system uses the environment variable + TEMPLATECONF to locate the directory + from which it gathers configuration information that ultimately + ends up in the + Build Directory's + conf directory. + By default, TEMPLATECONF is set as + follows in the poky repository: + + TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf} + + This is the directory used by the build system to find templates + from which to build some key configuration files. + If you look at this directory, you will see the + bblayers.conf.sample, + local.conf.sample, and + conf-notes.txt files. + The build system uses these files to form the respective + bblayers.conf file, + local.conf file, and display the list of + BitBake targets when running the setup script. + + + + To override these default configuration files with + configurations you want used within every new + Build Directory, simply set the + TEMPLATECONF variable to your directory. + The TEMPLATECONF variable is set in the + .templateconf file, which is in the + top-level + Source Directory + folder (e.g. poky). + Edit the .templateconf so that it can locate + your directory. + + + + Best practices dictate that you should keep your + template configuration directory in your custom distribution layer. + For example, suppose you have a layer named + meta-mylayer located in your home directory + and you want your template configuration directory named + myconf. + Changing the .templateconf as follows + causes the OpenEmbedded build system to look in your directory + and base its configuration files on the + *.sample configuration files it finds. + The final configuration files (i.e. + local.conf and + bblayers.conf ultimately still end up in + your Build Directory, but they are based on your + *.sample files. + + TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} + + + + + Aside from the *.sample configuration files, + the conf-notes.txt also resides in the + default meta-yocto/conf directory. + The scripts that set up the build environment + (i.e. + &OE_INIT_FILE; + and + oe-init-build-env-memres) + use this file to display BitBake targets as part of the script + output. + Customizing this conf-notes.txt file is a + good way to make sure your list of custom targets appears + as part of the script's output. + + + + Here is the default list of targets displayed as a result of + running either of the setup scripts: + + You can now run 'bitbake <target>' + + Common targets are: + core-image-minimal + core-image-sato + meta-toolchain + adt-installer + meta-ide-support + + + + + Changing the listed common targets is as easy as editing your + version of conf-notes.txt in your + custom template configuration directory and making sure you + have TEMPLATECONF set to your directory. + +
+ +
+ Building a Tiny System + + + Very small distributions have some significant advantages such + as requiring less on-die or in-package memory (cheaper), better + performance through efficient cache usage, lower power requirements + due to less memory, faster boot times, and reduced development + overhead. + Some real-world examples where a very small distribution gives + you distinct advantages are digital cameras, medical devices, + and small headless systems. + + + + This section presents information that shows you how you can + trim your distribution to even smaller sizes than the + poky-tiny distribution, which is around + 5 Mbytes, that can be built out-of-the-box using the Yocto Project. + + +
+ Overview + + + The following list presents the overall steps you need to + consider and perform to create distributions with smaller + root filesystems, achieve faster boot times, maintain your critical + functionality, and avoid initial RAM disks: + + + Determine your goals and guiding principles. + + + Understand what contributes to your image size. + + + Reduce the size of the root filesystem. + + + Reduce the size of the kernel. + + + Eliminate packaging requirements. + + + Look for other ways to minimize size. + + + Iterate on the process. + + + +
+ +
+ Goals and Guiding Principles + + + Before you can reach your destination, you need to know + where you are going. + Here is an example list that you can use as a guide when + creating very small distributions: + + Determine how much space you need + (e.g. a kernel that is 1 Mbyte or less and + a root filesystem that is 3 Mbytes or less). + + Find the areas that are currently + taking 90% of the space and concentrate on reducing + those areas. + + Do not create any difficult "hacks" + to achieve your goals. + Leverage the device-specific + options. + Work in a separate layer so that you + keep changes isolated. + For information on how to create layers, see + the "Understanding and Creating Layers" section. + + + +
+ +
+ Understand What Contributes to Your Image Size + + + It is easiest to have something to start with when creating + your own distribution. + You can use the Yocto Project out-of-the-box to create the + poky-tiny distribution. + Ultimately, you will want to make changes in your own + distribution that are likely modeled after + poky-tiny. + + To use poky-tiny in your build, + set the + DISTRO + variable in your + local.conf file to "poky-tiny" + as described in the + "Creating Your Own Distribution" + section. + + + + + Understanding some memory concepts will help you reduce the + system size. + Memory consists of static, dynamic, and temporary memory. + Static memory is the TEXT (code), DATA (initialized data + in the code), and BSS (uninitialized data) sections. + Dynamic memory represents memory that is allocated at runtime: + stacks, hash tables, and so forth. + Temporary memory is recovered after the boot process. + This memory consists of memory used for decompressing + the kernel and for the __init__ + functions. + + + + To help you see where you currently are with kernel and root + filesystem sizes, you can use two tools found in the + Source Directory in + the scripts/tiny/ directory: + + ksize.py: Reports + component sizes for the kernel build objects. + + dirsize.py: Reports + component sizes for the root filesystem. + + This next tool and command help you organize configuration + fragments and view file dependencies in a human-readable form: + + merge_config.sh: + Helps you manage configuration files and fragments + within the kernel. + With this tool, you can merge individual configuration + fragments together. + The tool allows you to make overrides and warns you + of any missing configuration options. + The tool is ideal for allowing you to iterate on + configurations, create minimal configurations, and + create configuration files for different machines + without having to duplicate your process. + The merge_config.sh script is + part of the Linux Yocto kernel Git repositories + (i.e. linux-yocto-3.14, + linux-yocto-3.10, + linux-yocto-3.8, and so forth) + in the + scripts/kconfig directory. + For more information on configuration fragments, + see the + "Generating Configuration Files" + section of the Yocto Project Linux Kernel Development + Manual and the "Creating Configuration Fragments" + section, which is in this manual. + bitbake -u depexp -g bitbake_target: + Using the BitBake command with these options brings up + a Dependency Explorer from which you can view file + dependencies. + Understanding these dependencies allows you to make + informed decisions when cutting out various pieces of the + kernel and root filesystem. + + +
+ +
+ Trim the Root Filesystem + + + The root filesystem is made up of packages for booting, + libraries, and applications. + To change things, you can configure how the packaging happens, + which changes the way you build them. + You can also modify the filesystem itself or select a different + filesystem. + + + + First, find out what is hogging your root filesystem by running the + dirsize.py script from your root directory: + + $ cd root-directory-of-image + $ dirsize.py 100000 > dirsize-100k.log + $ cat dirsize-100k.log + + You can apply a filter to the script to ignore files under + a certain size. + The previous example filters out any files below 100 Kbytes. + The sizes reported by the tool are uncompressed, and thus + will be smaller by a relatively constant factor in a + compressed root filesystem. + When you examine your log file, you can focus on areas of the + root filesystem that take up large amounts of memory. + + + + You need to be sure that what you eliminate does not cripple + the functionality you need. + One way to see how packages relate to each other is by using + the Dependency Explorer UI with the BitBake command: + + $ cd image-directory + $ bitbake -u depexp -g image + + Use the interface to select potential packages you wish to + eliminate and see their dependency relationships. + + + + When deciding how to reduce the size, get rid of packages that + result in minimal impact on the feature set. + For example, you might not need a VGA display. + Or, you might be able to get by with devtmpfs + and mdev instead of + udev. + + + + Use your local.conf file to make changes. + For example, to eliminate udev and + glib, set the following in the + local configuration file: + + VIRTUAL-RUNTIME_dev_manager = "" + + + + + Finally, you should consider exactly the type of root + filesystem you need to meet your needs while also reducing + its size. + For example, consider cramfs, + squashfs, ubifs, + ext2, or an initramfs + using initramfs. + Be aware that ext3 requires a 1 Mbyte + journal. + If you are okay with running read-only, you do not need this + journal. + + + + After each round of elimination, you need to rebuild your + system and then use the tools to see the effects of your + reductions. + + + +
+ +
+ Trim the Kernel + + + The kernel is built by including policies for hardware-independent + aspects. + What subsystems do you enable? + For what architecture are you building? + Which drivers do you build by default? + You can modify the kernel source if you want to help + with boot time. + + + + + Run the ksize.py script from the top-level + Linux build directory to get an idea of what is making up + the kernel: + + $ cd top-level-linux-build-directory + $ ksize.py > ksize.log + $ cat ksize.log + + When you examine the log, you will see how much space is + taken up with the built-in .o files for + drivers, networking, core kernel files, filesystem, sound, + and so forth. + The sizes reported by the tool are uncompressed, and thus + will be smaller by a relatively constant factor in a compressed + kernel image. + Look to reduce the areas that are large and taking up around + the "90% rule." + + + + To examine, or drill down, into any particular area, use the + -d option with the script: + + $ ksize.py -d > ksize.log + + Using this option breaks out the individual file information + for each area of the kernel (e.g. drivers, networking, and + so forth). + + + + Use your log file to see what you can eliminate from the kernel + based on features you can let go. + For example, if you are not going to need sound, you do not + need any drivers that support sound. + + + + After figuring out what to eliminate, you need to reconfigure + the kernel to reflect those changes during the next build. + You could run menuconfig and make all your + changes at once. + However, that makes it difficult to see the effects of your + individual eliminations and also makes it difficult to replicate + the changes for perhaps another target device. + A better method is to start with no configurations using + allnoconfig, create configuration + fragments for individual changes, and then manage the + fragments into a single configuration file using + merge_config.sh. + The tool makes it easy for you to iterate using the + configuration change and build cycle. + + + + Each time you make configuration changes, you need to rebuild + the kernel and check to see what impact your changes had on + the overall size. + +
+ +
+ Remove Package Management Requirements + + + Packaging requirements add size to the image. + One way to reduce the size of the image is to remove all the + packaging requirements from the image. + This reduction includes both removing the package manager + and its unique dependencies as well as removing the package + management data itself. + + + + To eliminate all the packaging requirements for an image, + be sure that "package-management" is not part of your + IMAGE_FEATURES + statement for the image. + When you remove this feature, you are removing the package + manager as well as its dependencies from the root filesystem. + +
+ +
+ Look for Other Ways to Minimize Size + + + Depending on your particular circumstances, other areas that you + can trim likely exist. + The key to finding these areas is through tools and methods + described here combined with experimentation and iteration. + Here are a couple of areas to experiment with: + + glibc: + In general, follow this process: + + Remove glibc + features from + DISTRO_FEATURES + that you think you do not need. + Build your distribution. + + If the build fails due to missing + symbols in a package, determine if you can + reconfigure the package to not need those + features. + For example, change the configuration to not + support wide character support as is done for + ncurses. + Or, if support for those characters is needed, + determine what glibc + features provide the support and restore the + configuration. + + Rebuild and repeat the process. + + + busybox: + For BusyBox, use a process similar as described for + glibc. + A difference is you will need to boot the resulting + system to see if you are able to do everything you + expect from the running system. + You need to be sure to integrate configuration fragments + into Busybox because BusyBox handles its own core + features and then allows you to add configuration + fragments on top. + + + +
+ +
+ Iterate on the Process + + + If you have not reached your goals on system size, you need + to iterate on the process. + The process is the same. + Use the tools and see just what is taking up 90% of the root + filesystem and the kernel. + Decide what you can eliminate without limiting your device + beyond what you need. + + + + Depending on your system, a good place to look might be + Busybox, which provides a stripped down + version of Unix tools in a single, executable file. + You might be able to drop virtual terminal services or perhaps + ipv6. + +
+
+ +
+ Working with Packages + + + This section describes a few tasks that involve packages: + + + Excluding packages from an image + + + Incrementing a package revision number + + + Handling a package name alias + + + Handling optional module packaging + + + Using Runtime Package Management + + + Setting up and running package test (ptest) + + + + +
+ Excluding Packages from an Image + + + You might find it necessary to prevent specific packages + from being installed into an image. + If so, you can use several variables to direct the build + system to essentially ignore installing recommended packages + or to not install a package at all. + + + + The following list introduces variables you can use to + prevent packages from being installed into your image. + Each of these variables only works with IPK and RPM + package types. + Support for Debian packages does not exist. + Also, you can use these variables from your + local.conf file or attach them to a + specific image recipe by using a recipe name override. + For more detail on the variables, see the descriptions in the + Yocto Project Reference Manual's glossary chapter. + + BAD_RECOMMENDATIONS: + Use this variable to specify "recommended-only" + packages that you do not want installed. + + NO_RECOMMENDATIONS: + Use this variable to prevent all "recommended-only" + packages from being installed. + + PACKAGE_EXCLUDE: + Use this variable to prevent specific packages from + being installed regardless of whether they are + "recommended-only" or not. + You need to realize that the build process could + fail with an error when you + prevent the installation of a package whose presence + is required by an installed package. + + + +
+ +
+ Incrementing a Package Revision Number + + + If a committed change results in changing the package output, + then the value of the + PR + variable needs to be increased (or "bumped"). + Increasing PR occurs one of two ways: + + Automatically using a Package Revision + Service (PR Service). + Manually incrementing the + PR variable. + + + + + Given that one of the challenges any build system and its + users face is how to maintain a package feed that is compatible + with existing package manager applications such as + RPM, APT, and OPKG, using an automated system is much + preferred over a manual system. + In either system, the main requirement is that version + numbering increases in a linear fashion and that a number of + version components exist that support that linear progression. + + + + The following two sections provide information on the PR Service + and on manual PR bumping. + + +
+ Working With a PR Service + + + As mentioned, attempting to maintain revision numbers in the + Metadata + is error prone, inaccurate, and causes problems for people + submitting recipes. + Conversely, the PR Service automatically generates + increasing numbers, particularly the revision field, + which removes the human element. + + For additional information on using a PR Service, you + can see the + PR Service + wiki page. + + + + + The Yocto Project uses variables in order of + decreasing priority to facilitate revision numbering (i.e. + PE, + PV, and + PR + for epoch, version, and revision, respectively). + The values are highly dependent on the policies and + procedures of a given distribution and package feed. + + + + Because the OpenEmbedded build system uses + "signatures", + which are unique to a given build, the build system + knows when to rebuild packages. + All the inputs into a given task are represented by a + signature, which can trigger a rebuild when different. + Thus, the build system itself does not rely on the + PR numbers to trigger a rebuild. + The signatures, however, can be used to generate + PR values. + + + + The PR Service works with both + OEBasic and + OEBasicHash generators. + The value of PR bumps when the + checksum changes and the different generator mechanisms + change signatures under different circumstances. + + + + As implemented, the build system includes values from + the PR Service into the PR field as + an addition using the form ".x" so + r0 becomes r0.1, + r0.2 and so forth. + This scheme allows existing PR values + to be used for whatever reasons, which include manual + PR bumps, should it be necessary. + + + + By default, the PR Service is not enabled or running. + Thus, the packages generated are just "self consistent". + The build system adds and removes packages and + there are no guarantees about upgrade paths but images + will be consistent and correct with the latest changes. + + + + The simplest form for a PR Service is for it to exist + for a single host development system that builds the + package feed (building system). + For this scenario, you can enable a local PR Service by + setting + PRSERV_HOST + in your local.conf file in the + Build Directory: + + PRSERV_HOST = "localhost:0" + + Once the service is started, packages will automatically + get increasing PR values and + BitBake will take care of starting and stopping the server. + + + + If you have a more complex setup where multiple host + development systems work against a common, shared package + feed, you have a single PR Service running and it is + connected to each building system. + For this scenario, you need to start the PR Service using + the bitbake-prserv command: + + bitbake-prserv ‐‐host ip ‐‐port port ‐‐start + + In addition to hand-starting the service, you need to + update the local.conf file of each + building system as described earlier so each system + points to the server and port. + + + + It is also recommended you use build history, which adds + some sanity checks to package versions, in conjunction with + the server that is running the PR Service. + To enable build history, add the following to each building + system's local.conf file: + + # It is recommended to activate "buildhistory" for testing the PR service + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + + For information on build history, see the + "Maintaining Build Output Quality" + section in the Yocto Project Reference Manual. + + + + The OpenEmbedded build system does not maintain + PR information as part of the + shared state (sstate) packages. + If you maintain an sstate feed, its expected that either + all your building systems that contribute to the sstate + feed use a shared PR Service, or you do not run a PR + Service on any of your building systems. + Having some systems use a PR Service while others do + not leads to obvious problems. + For more information on shared state, see the + "Shared State Cache" + section in the Yocto Project Reference Manual. + +
+ +
+ Manually Bumping PR + + + The alternative to setting up a PR Service is to manually + bump the + PR + variable. + + + + If a committed change results in changing the package output, + then the value of the PR variable needs to be increased + (or "bumped") as part of that commit. + For new recipes you should add the PR + variable and set its initial value equal to "r0", which is the default. + Even though the default value is "r0", the practice of adding it to a new recipe makes + it harder to forget to bump the variable when you make changes + to the recipe in future. + + + + If you are sharing a common .inc file with multiple recipes, + you can also use the + INC_PR + variable to ensure that + the recipes sharing the .inc file are rebuilt when the + .inc file itself is changed. + The .inc file must set INC_PR + (initially to "r0"), and all recipes referring to it should set PR + to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. + If the .inc file is changed then its + INC_PR should be incremented. + + + + When upgrading the version of a package, assuming the + PV + changes, the PR variable should be + reset to "r0" (or "$(INC_PR).0" if you are using + INC_PR). + + + + Usually, version increases occur only to packages. + However, if for some reason PV changes but does not + increase, you can increase the + PE + variable (Package Epoch). + The PE variable defaults to "0". + + + + Version numbering strives to follow the + + Debian Version Field Policy Guidelines. + These guidelines define how versions are compared and what "increasing" a version means. + +
+
+ +
+ Handling a Package Name Alias + + Sometimes a package name you are using might exist under + an alias or as a similarly named package in a different + distribution. + The OpenEmbedded build system implements a + do_distro_check + task that automatically connects to major distributions + and checks for these situations. + If the package exists under a different name in a different + distribution, you get a distro_check + mismatch. + You can resolve this problem by defining a per-distro recipe + name alias using the + DISTRO_PN_ALIAS + variable. + + + + Following is an example that shows how you specify the DISTRO_PN_ALIAS + variable: + + DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ + distro2=package_name_alias2 \ + distro3=package_name_alias3 \ + ..." + + + + + If you have more than one distribution alias, separate them with a space. + Note that the build system currently automatically checks the + Fedora, OpenSUSE, Debian, Ubuntu, + and Mandriva distributions for source package recipes without having to specify them + using the DISTRO_PN_ALIAS variable. + For example, the following command generates a report that lists the Linux distributions + that include the sources for each of the recipes. + + $ bitbake world -f -c distro_check + + The results are stored in the build/tmp/log/distro_check-${DATETIME}.results + file found in the + Source Directory. + +
+ +
+ Handling Optional Module Packaging + + + Many pieces of software split functionality into optional + modules (or plug-ins) and the plug-ins that are built + might depend on configuration options. + To avoid having to duplicate the logic that determines what + modules are available in your recipe or to avoid having + to package each module by hand, the OpenEmbedded build system + provides functionality to handle module packaging dynamically. + + + + To handle optional module packaging, you need to do two things: + + Ensure the module packaging is actually + done. + Ensure that any dependencies on optional + modules from other recipes are satisfied by your recipe. + + + + +
+ Making Sure the Packaging is Done + + + To ensure the module packaging actually gets done, you use + the do_split_packages function within + the populate_packages Python function + in your recipe. + The do_split_packages function + searches for a pattern of files or directories under a + specified path and creates a package for each one it finds + by appending to the + PACKAGES + variable and setting the appropriate values for + FILES_packagename, + RDEPENDS_packagename, + DESCRIPTION_packagename, and so forth. + Here is an example from the lighttpd + recipe: + + python populate_packages_prepend () { + lighttpd_libdir = d.expand('${libdir}') + do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$', + 'lighttpd-module-%s', 'Lighttpd module for %s', + extra_depends='') + } + + The previous example specifies a number of things in the + call to do_split_packages. + + A directory within the files installed + by your recipe through do_install + in which to search. + A regular expression used to match module + files in that directory. + In the example, note the parentheses () that mark + the part of the expression from which the module + name should be derived. + A pattern to use for the package names. + + A description for each package. + + An empty string for + extra_depends, which disables + the default dependency on the main + lighttpd package. + Thus, if a file in ${libdir} + called mod_alias.so is found, + a package called lighttpd-module-alias + is created for it and the + DESCRIPTION + is set to "Lighttpd module for alias". + + + + + Often, packaging modules is as simple as the previous + example. + However, more advanced options exist that you can use + within do_split_packages to modify its + behavior. + And, if you need to, you can add more logic by specifying + a hook function that is called for each package. + It is also perfectly acceptable to call + do_split_packages multiple times if + you have more than one set of modules to package. + + + + For more examples that show how to use + do_split_packages, see the + connman.inc file in the + meta/recipes-connectivity/connman/ + directory of the poky + source repository. + You can also find examples in + meta/classes/kernel.bbclass. + + + + Following is a reference that shows + do_split_packages mandatory and + optional arguments: + + Mandatory arguments + + root + The path in which to search + file_regex + Regular expression to match searched files. + Use parentheses () to mark the part of this + expression that should be used to derive the + module name (to be substituted where %s is + used in other function arguments as noted below) + output_pattern + Pattern to use for the package names. Must + include %s. + description + Description to set for each package. Must + include %s. + + Optional arguments + + postinst + Postinstall script to use for all packages + (as a string) + recursive + True to perform a recursive search - default + False + hook + A hook function to be called for every match. + The function will be called with the following + arguments (in the order listed): + + f + Full path to the file/directory match + pkg + The package name + file_regex + As above + output_pattern + As above + modulename + The module name derived using file_regex + + extra_depends + Extra runtime dependencies (RDEPENDS) to be + set for all packages. The default value of None + causes a dependency on the main package + (${PN}) - if you do not want this, pass empty + string '' for this parameter. + aux_files_pattern + Extra item(s) to be added to FILES for each + package. Can be a single string item or a list + of strings for multiple items. Must include %s. + postrm + postrm script to use for all packages (as a + string) + allow_dirs + True to allow directories to be matched - + default False + prepend + If True, prepend created packages to PACKAGES + instead of the default False which appends them + match_path + match file_regex on the whole relative path to + the root rather than just the file name + aux_files_pattern_verbatim + Extra item(s) to be added to FILES for each + package, using the actual derived module name + rather than converting it to something legal + for a package name. Can be a single string item + or a list of strings for multiple items. Must + include %s. + allow_links + True to allow symlinks to be matched - default + False + summary + Summary to set for each package. Must include %s; + defaults to description if not set. + + +
+ +
+ Satisfying Dependencies + + + The second part for handling optional module packaging + is to ensure that any dependencies on optional modules + from other recipes are satisfied by your recipe. + You can be sure these dependencies are satisfied by + using the + PACKAGES_DYNAMIC variable. + Here is an example that continues with the + lighttpd recipe shown earlier: + + PACKAGES_DYNAMIC = "lighttpd-module-.*" + + The name specified in the regular expression can of + course be anything. + In this example, it is lighttpd-module- + and is specified as the prefix to ensure that any + RDEPENDS + and RRECOMMENDS + on a package name starting with the prefix are satisfied + during build time. + If you are using do_split_packages + as described in the previous section, the value you put in + PACKAGES_DYNAMIC should correspond to + the name pattern specified in the call to + do_split_packages. + +
+
+ +
+ Using Runtime Package Management + + + During a build, BitBake always transforms a recipe into one or + more packages. + For example, BitBake takes the bash recipe + and currently produces the bash-dbg, + bash-staticdev, + bash-dev, bash-doc, + bash-locale, and + bash packages. + Not all generated packages are included in an image. + + + + In several situations, you might need to update, add, remove, + or query the packages on a target device at runtime + (i.e. without having to generate a new image). + Examples of such situations include: + + + You want to provide in-the-field updates to deployed + devices (e.g. security updates). + + + You want to have a fast turn-around development cycle + for one or more applications that run on your device. + + + You want to temporarily install the "debug" packages + of various applications on your device so that + debugging can be greatly improved by allowing + access to symbols and source debugging. + + + You want to deploy a more minimal package selection of + your device but allow in-the-field updates to add a + larger selection for customization. + + + + + + In all these situations, you have something similar to a more + traditional Linux distribution in that in-field devices + are able to receive pre-compiled packages from a server for + installation or update. + Being able to install these packages on a running, + in-field device is what is termed "runtime package + management". + + + + In order to use runtime package management, you + need a host/server machine that serves up the pre-compiled + packages plus the required metadata. + You also need package manipulation tools on the target. + The build machine is a likely candidate to act as the server. + However, that machine does not necessarily have to be the + package server. + The build machine could push its artifacts to another machine + that acts as the server (e.g. Internet-facing). + + + + A simple build that targets just one device produces + more than one package database. + In other words, the packages produced by a build are separated + out into a couple of different package groupings based on + criteria such as the target's CPU architecture, the target + board, or the C library used on the target. + For example, a build targeting the qemuarm + device produces the following three package databases: + all, armv5te, and + qemuarm. + If you wanted your qemuarm device to be + aware of all the packages that were available to it, + you would need to point it to each of these databases + individually. + In a similar way, a traditional Linux distribution usually is + configured to be aware of a number of software repositories + from which it retrieves packages. + + + + Using runtime package management is completely optional and + not required for a successful build or deployment in any + way. + But if you want to make use of runtime package management, + you need to do a couple things above and beyond the basics. + The remainder of this section describes what you need to do. + + +
+ Build Considerations + + + This section describes build considerations that you need + to be aware of in order to provide support for runtime + package management. + + + + When BitBake generates packages it needs to know + what format or formats to use. + In your configuration, you use the + PACKAGE_CLASSES + variable to specify the format. + + You can choose to have more than one format but you must + provide at least one. + + + + + If you would like your image to start off with a basic + package database of the packages in your current build + as well as have the relevant tools available on the + target for runtime package management, you can include + "package-management" in the + IMAGE_FEATURES + variable. + Including "package-management" in this + configuration variable ensures that when the image + is assembled for your target, the image includes + the currently-known package databases as well as + the target-specific tools required for runtime + package management to be performed on the target. + However, this is not strictly necessary. + You could start your image off without any databases + but only include the required on-target package + tool(s). + As an example, you could include "opkg" in your + IMAGE_INSTALL + variable if you are using the IPK package format. + You can then initialize your target's package database(s) + later once your image is up and running. + + + + Whenever you perform any sort of build step that can + potentially generate a package or modify an existing + package, it is always a good idea to re-generate the + package index with: + + $ bitbake package-index + + Realize that it is not sufficient to simply do the + following: + + $ bitbake some-package package-index + + This is because BitBake does not properly schedule the + package-index target fully after any + other target has completed. + Thus, be sure to run the package update step separately. + + + + As described below in the + "Using IPK" + section, if you are using IPK as your package format, you + can make use of the + distro-feed-configs recipe provided + by meta-oe in order to configure your + target to use your IPK databases. + + + + When your build is complete, your packages reside in the + ${TMPDIR}/deploy/package-format + directory. + For example, if ${TMPDIR} + is tmp and your selected package type + is IPK, then your IPK packages are available in + tmp/deploy/ipk. + +
+ +
+ Host or Server Machine Setup + + + Typically, packages are served from a server using + HTTP. + However, other protocols are possible. + If you want to use HTTP, then setup and configure a + web server, such as Apache 2 or lighttpd, on the machine + serving the packages. + + + + As previously mentioned, the build machine can act as the + package server. + In the following sections that describe server machine + setups, the build machine is assumed to also be the server. + + +
+ Serving Packages via Apache 2 + + + This example assumes you are using the Apache 2 + server: + + + Add the directory to your Apache + configuration, which you can find at + /etc/httpd/conf/httpd.conf. + Use commands similar to these on the + development system. + These example commands assume a top-level + Source Directory + named poky in your home + directory. + The example also assumes an RPM package type. + If you are using a different package type, such + as IPK, use "ipk" in the pathnames: + + <VirtualHost *:80> + .... + Alias /rpm ~/poky/build/tmp/deploy/rpm + <Directory "~/poky/build/tmp/deploy/rpm"> + Options +Indexes + </Directory> + </VirtualHost> + + + Reload the Apache configuration as described + in this step. + For all commands, be sure you have root + privileges. + + + + If your development system is using Fedora or + CentOS, use the following: + + # service httpd reload + + For Ubuntu and Debian, use the following: + + # /etc/init.d/apache2 reload + + For OpenSUSE, use the following: + + # /etc/init.d/apache2 reload + + + If you are using Security-Enhanced Linux + (SELinux), you need to label the files as + being accessible through Apache. + Use the following command from the development + host. + This example assumes RPM package types: + + # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm + + + +
+ +
+ Serving Packages via lighttpd + + + If you are using lighttpd, all you need + to do is to provide a link from your + ${TMPDIR}/deploy/package-format + directory to lighttpd's document-root. + You can determine the specifics of your lighttpd + installation by looking through its configuration file, + which is usually found at: + /etc/lighttpd/lighttpd.conf. + + + + For example, if you are using IPK, lighttpd's + document-root is set to + /var/www/lighttpd, and you had + packages for a target named "BOARD", + then you might create a link from your build location + to lighttpd's document-root as follows: + + # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir + + + + + At this point, you need to start the lighttpd server. + The method used to start the server varies by + distribution. + However, one basic method that starts it by hand is: + + # lighttpd -f /etc/lighttpd/lighttpd.conf + + +
+
+ +
+ Target Setup + + + Setting up the target differs depending on the + package management system. + This section provides information for RPM and IPK. + + +
+ Using RPM + + + The application for performing runtime package + management of RPM packages on the target is called + smart. + + + + On the target machine, you need to inform + smart of every package database + you want to use. + As an example, suppose your target device can use the + following three package databases from a server named + server.name: + all, i586, + and qemux86. + Given this example, issue the following commands on the + target: + + # smart channel ‐‐add all type=rpm-md baseurl=http://server.name/rpm/all + # smart channel ‐‐add i585 type=rpm-md baseurl=http://server.name/rpm/i586 + # smart channel ‐‐add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86 + + Also from the target machine, fetch the repository + information using this command: + + # smart update + + You can now use the smart query + and smart install commands to + find and install packages from the repositories. + +
+ +
+ Using IPK + + + The application for performing runtime package + management of IPK packages on the target is called + opkg. + + + + In order to inform opkg of the + package databases you want to use, simply create one + or more *.conf files in the + /etc/opkg directory on the target. + The opkg application uses them + to find its available package databases. + As an example, suppose you configured your HTTP server + on your machine named + www.mysite.com to serve files + from a BOARD-dir directory under + its document-root. + In this case, you might create a configuration + file on the target called + /etc/opkg/base-feeds.conf that + contains: + + src/gz all http://www.mysite.com/BOARD-dir/all + src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a + src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone + + + + + As a way of making it easier to generate and make + these IPK configuration files available on your + target, simply define + FEED_DEPLOYDIR_BASE_URI + to point to your server and the location within the + document-root which contains the databases. + For example: if you are serving your packages over + HTTP, your server's IP address is 192.168.7.1, and + your databases are located in a directory called + BOARD-dir underneath your HTTP + server's document-root, you need to set + FEED_DEPLOYDIR_BASE_URI to + http://192.168.7.1/BOARD-dir and + a set of configuration files will be generated for you + in your target to work with this feed. + + + + On the target machine, fetch (or refresh) the + repository information using this command: + + # opkg update + + You can now use the opkg list and + opkg install commands to find and + install packages from the repositories. + +
+
+
+ +
+ Testing Packages With ptest + + + A Package Test (ptest) runs tests against packages built + by the OpenEmbedded build system on the target machine. + A ptest contains at least two items: the actual test, and + a shell script (run-ptest) that starts + the test. + The shell script that starts the test must not contain + the actual test - the script only starts the test. + On the other hand, the test can be anything from a simple + shell script that runs a binary and checks the output to + an elaborate system of test binaries and data files. + + + + The test generates output in the format used by + Automake: + + result: testname + + where the result can be PASS, + FAIL, or SKIP, + and the testname can be any identifying string. + + + + For a list of Yocto Project recipes that are already + enabled with ptest, see the + Ptest + wiki page. + + A recipe is "ptest-enabled" if it inherits the + ptest + class. + + + +
+ Adding ptest to Your Build + + + To add package testing to your build, add the + DISTRO_FEATURES + and EXTRA_IMAGE_FEATURES + variables to your local.conf file, + which is found in the + Build Directory: + + DISTRO_FEATURES_append = " ptest" + EXTRA_IMAGE_FEATURES += "ptest-pkgs" + + Once your build is complete, the ptest files are installed + into the + /usr/lib/package/ptest + directory within the image, where + package + is the name of the package. + +
+ +
+ Running ptest + + + The ptest-runner package installs a + shell script that loops through all installed ptest test + suites and runs them in sequence. + Consequently, you might want to add this package to + your image. + +
+ +
+ Getting Your Package Ready + + + In order to enable a recipe to run installed ptests + on target hardware, + you need to prepare the recipes that build the packages + you want to test. + Here is what you have to do for each recipe: + + Be sure the recipe + inherits the + ptest + class: + Include the following line in each recipe: + + inherit ptest + + + Create run-ptest: + This script starts your test. + Locate the script where you will refer to it + using + SRC_URI. + Here is an example that starts a test for + dbus: + + #!/bin/sh + cd test + make -k runtest-TESTS + + + Ensure dependencies are + met: + If the test adds build or runtime dependencies + that normally do not exist for the package + (such as requiring "make" to run the test suite), + use the + DEPENDS + and + RDEPENDS + variables in your recipe in order for the package + to meet the dependencies. + Here is an example where the package has a runtime + dependency on "make": + + RDEPENDS_${PN}-ptest += "make" + + + Add a function to build the + test suite: + Not many packages support cross-compilation of + their test suites. + Consequently, you usually need to add a + cross-compilation function to the package. + + Many packages based on Automake compile and + run the test suite by using a single command + such as make check. + However, the native make check + builds and runs on the same computer, while + cross-compiling requires that the package is built + on the host but executed on the target. + The built version of Automake that ships with the + Yocto Project includes a patch that separates + building and execution. + Consequently, packages that use the unaltered, + patched version of make check + automatically cross-compiles. + Regardless, you still must add a + do_compile_ptest function to + build the test suite. + Add a function similar to the following to your + recipe: + + do_compile_ptest() { + oe_runmake buildtest-TESTS + } + + + Ensure special configurations + are set: + If the package requires special configurations + prior to compiling the test code, you must + insert a do_configure_ptest + function into the recipe. + + Install the test + suite: + The ptest class + automatically copies the file + run-ptest to the target and + then runs make install-ptest + to run the tests. + If this is not enough, you need to create a + do_install_ptest function and + make sure it gets called after the + "make install-ptest" completes. + + + +
+
+
+ +
+ Working with Source Files + + + The OpenEmbedded build system works with source files located + through the + SRC_URI + variable. + When you build something using BitBake, a big part of the operation + is locating and downloading all the source tarballs. + For images, downloading all the source for various packages can + take a significant amount of time. + + + + This section presents information for working with source + files that can lead to more efficient use of resources and + time. + + +
+ Setting up Effective Mirrors + + + As mentioned, a good deal that goes into a Yocto Project + build is simply downloading all of the source tarballs. + Maybe you have been working with another build system + (OpenEmbedded or Angstrom) for which you have built up a + sizable directory of source tarballs. + Or, perhaps someone else has such a directory for which you + have read access. + If so, you can save time by adding statements to your + configuration file so that the build process checks local + directories first for existing tarballs before checking the + Internet. + + + + Here is an efficient way to set it up in your + local.conf file: + + SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/" + INHERIT += "own-mirrors" + BB_GENERATE_MIRROR_TARBALLS = "1" + # BB_NO_NETWORK = "1" + + + + + In the previous example, the + BB_GENERATE_MIRROR_TARBALLS + variable causes the OpenEmbedded build system to generate + tarballs of the Git repositories and store them in the + DL_DIR + directory. + Due to performance reasons, generating and storing these + tarballs is not the build system's default behavior. + + + + You can also use the + PREMIRRORS + variable. + For an example, see the variable's glossary entry in the + Yocto Project Reference Manual. + +
+ +
+ Getting Source Files and Suppressing the Build + + + Another technique you can use to ready yourself for a + successive string of build operations, is to pre-fetch + all the source files without actually starting a build. + This technique lets you work through any download issues + and ultimately gathers all the source files into your + download directory + build/downloads, + which is located with + DL_DIR. + + + + Use the following BitBake command form to fetch all the + necessary sources without starting the build: + + $ bitbake -c fetchall target + + This variation of the BitBake command guarantees that you + have all the sources for that BitBake target should you + disconnect from the Internet and want to do the build + later offline. + +
+
+ +
+ Building Software from an External Source + + + By default, the OpenEmbedded build system uses the + Build Directory when + building source code. + The build process involves fetching the source files, unpacking + them, and then patching them if necessary before the build takes + place. + + + + Situations exist where you might want to build software from source + files that are external to and thus outside of the + OpenEmbedded build system. + For example, suppose you have a project that includes a new BSP with + a heavily customized kernel. + And, you want to minimize exposing the build system to the + development team so that they can focus on their project and + maintain everyone's workflow as much as possible. + In this case, you want a kernel source directory on the development + machine where the development occurs. + You want the recipe's + SRC_URI + variable to point to the external directory and use it as is, not + copy it. + + + + To build from software that comes from an external source, all you + need to do is inherit the + externalsrc + class and then set the + EXTERNALSRC + variable to point to your external source code. + Here are the statements to put in your + local.conf file: + + INHERIT += "externalsrc" + EXTERNALSRC_pn-myrecipe = "path-to-your-source-tree" + + + + + This next example shows how to accomplish the same thing by setting + EXTERNALSRC in the recipe itself or in the + recipe's append file: + + EXTERNALSRC = "path" + EXTERNALSRC_BUILD = "path" + + + In order for these settings to take effect, you must globally + or locally inherit the + externalsrc + class. + + + + + By default, externalsrc.bbclass builds + the source code in a directory separate from the external source + directory as specified by + EXTERNALSRC. + If you need to have the source built in the same directory in + which it resides, or some other nominated directory, you can set + EXTERNALSRC_BUILD + to point to that directory: + + EXTERNALSRC_BUILD_pn-myrecipe = "path-to-your-source-tree" + + +
+ +
+ Selecting an Initialization Manager + + + By default, the Yocto Project uses SysVinit as the initialization + manager. + However, support also exists for systemd, + which is a full replacement for init with + parallel starting of services, reduced shell overhead and other + features that are used by many distributions. + + + + If you want to use SysVinit, you do + not have to do anything. + But, if you want to use systemd, you must + take some steps as described in the following sections. + + +
+ Using systemd Exclusively + + + Set the these variables in your distribution configuration + file as follows: + + DISTRO_FEATURES_append = " systemd" + VIRTUAL-RUNTIME_init_manager = "systemd" + + You can also prevent the SysVinit + distribution feature from + being automatically enabled as follows: + + DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" + + Doing so removes any redundant SysVinit scripts. + + + + To remove initscripts from your image altogether, + set this variable also: + + VIRTUAL-RUNTIME_initscripts = "" + + + + + For information on the backfill variable, see + DISTRO_FEATURES_BACKFILL_CONSIDERED. + +
+ +
+ Using systemd for the Main Image and Using SysVinit for the Rescue Image + + + Set these variables in your distribution configuration + file as follows: + + DISTRO_FEATURES_append = " systemd" + VIRTUAL-RUNTIME_init_manager = "systemd" + + Doing so causes your main image to use the + packagegroup-core-boot.bb recipe and + systemd. + The rescue/minimal image cannot use this package group. + However, it can install SysVinit + and the appropriate packages will have support for both + systemd and SysVinit. + +
+
+ +
+ Using an External SCM + + + If you're working on a recipe that pulls from an external Source + Code Manager (SCM), it is possible to have the OpenEmbedded build + system notice new recipe changes added to the SCM and then build + the resulting packages that depend on the new recipes by using + the latest versions. + This only works for SCMs from which it is possible to get a + sensible revision number for changes. + Currently, you can do this with Apache Subversion (SVN), Git, and + Bazaar (BZR) repositories. + + + + To enable this behavior, the + PV + of the recipe needs to reference + SRCPV. + Here is an example: + + PV = "1.2.3+git${SRCPV} + + Then, you can add the following to your + local.conf: + + SRCREV_pn-PN = "${AUTOREV}" + + PN + is the name of the recipe for which you want to enable automatic source + revision updating. + + + + If you do not want to update your local configuration file, you can + add the following directly to the recipe to finish enabling + the feature: + + SRCREV = "${AUTOREV}" + + + + + The Yocto Project provides a distribution named + poky-bleeding, whose configuration + file contains the line: + + require conf/distro/include/poky-floating-revisions.inc + + This line pulls in the listed include file that contains + numerous lines of exactly that form: + + 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}" + . + . + . + + These lines allow you to experiment with building a + distribution that tracks the latest development source + for numerous packages. + Caution + The poky-bleeding distribution + is not tested on a regular basis. + Keep this in mind if you use it. + + +
+ +
+ Creating a Read-Only Root Filesystem + + + Suppose, for security reasons, you need to disable + your target device's root filesystem's write permissions + (i.e. you need a read-only root filesystem). + Or, perhaps you are running the device's operating system + from a read-only storage device. + For either case, you can customize your image for + that behavior. + + + + Supporting a read-only root filesystem requires that the system and + applications do not try to write to the root filesystem. + You must configure all parts of the target system to write + elsewhere, or to gracefully fail in the event of attempting to + write to the root filesystem. + + +
+ Creating the Root Filesystem + + + To create the read-only root filesystem, simply add the + "read-only-rootfs" feature to your image. + Using either of the following statements in your + image recipe or from within the + local.conf file found in the + Build Directory + causes the build system to create a read-only root filesystem: + + IMAGE_FEATURES = "read-only-rootfs" + + or + + EXTRA_IMAGE_FEATURES += "read-only-rootfs" + + + + + For more information on how to use these variables, see the + "Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES" + section. + For information on the variables, see + IMAGE_FEATURES + and EXTRA_IMAGE_FEATURES. + +
+ +
+ Post-Installation Scripts + + + It is very important that you make sure all + post-Installation (pkg_postinst) scripts + for packages that are installed into the image can be run + at the time when the root filesystem is created during the + build on the host system. + These scripts cannot attempt to run during first-boot on the + target device. + With the "read-only-rootfs" feature enabled, + the build system checks during root filesystem creation to make + sure all post-installation scripts succeed. + If any of these scripts still need to be run after the root + filesystem is created, the build immediately fails. + These build-time checks ensure that the build fails + rather than the target device fails later during its + initial boot operation. + + + + Most of the common post-installation scripts generated by the + build system for the out-of-the-box Yocto Project are engineered + so that they can run during root filesystem creation + (e.g. post-installation scripts for caching fonts). + However, if you create and add custom scripts, you need + to be sure they can be run during this file system creation. + + + + Here are some common problems that prevent + post-installation scripts from running during root filesystem + creation: + + + Not using $D in front of absolute + paths: + The build system defines + $D + when the root filesystem is created. + Furthermore, $D is blank when the + script is run on the target device. + This implies two purposes for $D: + ensuring paths are valid in both the host and target + environments, and checking to determine which + environment is being used as a method for taking + appropriate actions. + + + Attempting to run processes that are + specific to or dependent on the target + architecture: + You can work around these attempts by using native + tools to accomplish the same tasks, or + by alternatively running the processes under QEMU, + which has the qemu_run_binary + function. + For more information, see the + qemu + class. + + +
+ +
+ Areas With Write Access + + + With the "read-only-rootfs" feature enabled, + any attempt by the target to write to the root filesystem at + runtime fails. + Consequently, you must make sure that you configure processes + and applications that attempt these types of writes do so + to directories with write access (e.g. + /tmp or /var/run). + +
+
+ +
+ Performing Automated Runtime Testing + + + The OpenEmbedded build system makes available a series of automated + tests for images to verify runtime functionality. + You can run these tests on either QEMU or actual target hardware. + Tests are written in Python making use of the + unittest module, and the majority of them + run commands on the target system over SSH. + This section describes how you set up the environment to use these + tests, run available tests, and write and add your own tests. + + +
+ Enabling Tests + + + Depending on whether you are planning to run tests using + QEMU or on the hardware, you have to take + different steps to enable the tests. + See the following subsections for information on how to + enable both types of tests. + + +
+ Enabling Runtime Tests on QEMU + + + In order to run tests, you need to do the following: + + Set up to avoid interaction + with sudo for networking: + To accomplish this, you must do one of the + following: + + Add + NOPASSWD for your user + in /etc/sudoers either for + all commands or just for + runqemu-ifup. + You must provide the full path as that can + change if you are using multiple clones of the + source repository. + + On some distributions, you also need to + comment out "Defaults requiretty" in + /etc/sudoers. + + Manually configure a tap interface + for your system. + Run as root the script in + scripts/runqemu-gen-tapdevs, + which should generate a list of tap devices. + This is the option typically chosen for + Autobuilder-type environments. + + + Set the + DISPLAY variable: + You need to set this variable so that you have an X + server available (e.g. start + vncserver for a headless machine). + + Be sure your host's firewall + accepts incoming connections from + 192.168.7.0/24: + Some of the tests (in particular smart tests) start an + HTTP server on a random high number port, which is + used to serve files to the target. + The smart module serves + ${DEPLOY_DIR}/rpm so it can run + smart channel commands. That means your host's firewall + must accept incoming connections from 192.168.7.0/24, + which is the default IP range used for tap devices + by runqemu. + + + + + Once you start running the tests, the following happens: + + A copy of the root filesystem is written + to ${WORKDIR}/testimage. + + The image is booted under QEMU using the + standard runqemu script. + + A default timeout of 500 seconds occurs + to allow for the boot process to reach the login prompt. + You can change the timeout period by setting + TEST_QEMUBOOT_TIMEOUT + in the local.conf file. + + Once the boot process is reached and the + login prompt appears, the tests run. + The full boot log is written to + ${WORKDIR}/testimage/qemu_boot_log. + + Each test module loads in the order found + in TEST_SUITES. + You can find the full output of the commands run over + SSH in + ${WORKDIR}/testimgage/ssh_target_log. + + If no failures occur, the task running the + tests ends successfully. + You can find the output from the + unittest in the task log at + ${WORKDIR}/temp/log.do_testimage. + + + +
+ +
+ Enabling Runtime Tests on Hardware + + + The OpenEmbedded build system can run tests on real + hardware, and for certain devices it can also deploy + the image to be tested onto the device beforehand. + + + + For automated deployment, a "master image" is installed + onto the hardware once as part of setup. + Then, each time tests are to be run, the following + occurs: + + The master image is booted into and + used to write the image to be tested to + a second partition. + + The device is then rebooted using an + external script that you need to provide. + + The device boots into the image to be + tested. + + + + + + When running tests (independent of whether the image + has been deployed automatically or not), the device is + expected to be connected to a network on a + pre-determined IP address. + You can either use static IP addresses written into + the image, or set the image to use DHCP and have your + DHCP server on the test network assign a known IP address + based on the MAC address of the device. + + + + In order to run tests on hardware, you need to set + TEST_TARGET to an appropriate value. + For QEMU, you do not have to change anything, the default + value is "QemuTarget". + For running tests on hardware, the following options exist: + + "SimpleRemoteTarget": + Choose "SimpleRemoteTarget" if you are going to + run tests on a target system that is already + running the image to be tested and is available + on the network. + You can use "SimpleRemoteTarget" in conjunction + with either real hardware or an image running + within a separately started QEMU or any + other virtual machine manager. + + "GummibootTarget": + Choose "GummibootTarget" if your hardware is + an EFI-based machine with + gummiboot as bootloader and + core-image-testmaster + (or something similar) is installed. + Also, your hardware under test must be in a + DHCP-enabled network that gives it the same IP + address for each reboot. + If you choose "GummibootTarget", there are + additional requirements and considerations. + See the + "Selecting GummibootTarget" + section, which follows, for more information. + + "BeagleBoneTarget": + Choose "BeagleBoneTarget" if you are deploying + images and running tests on the BeagleBone + "Black" or original "White" hardware. + For information on how to use these tests, see the + comments at the top of the BeagleBoneTarget + meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py + file. + + "EdgeRouterTarget": + Choose "EdgeRouterTarget" is you are deploying + images and running tests on the Ubiquiti Networks + EdgeRouter Lite. + For information on how to use these tests, see the + comments at the top of the EdgeRouterTarget + meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py + file. + + "GrubTarget": + Choose the "supports deploying images and running + tests on any generic PC that boots using GRUB. + For information on how to use these tests, see the + comments at the top of the GrubTarget + meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py + file. + + "your-target": + Create your own custom target if you want to run + tests when you are deploying images and running + tests on a custom machine within your BSP layer. + To do this, you need to add a Python unit that + defines the target class under + lib/oeqa/controllers/ within + your layer. + You must also provide an empty + __init__.py. + For examples, see files in + meta-yocto-bsp/lib/oeqa/controllers/. + + + +
+ +
+ Selecting GummibootTarget + + + If you did not set TEST_TARGET to + "GummibootTarget", then you do not need any information + in this section. + You can skip down to the + "Running Tests" + section. + + + + If you did set TEST_TARGET to + "GummibootTarget", you also need to perform a one-time + setup of your master image by doing the following: + + Set EFI_PROVIDER: + Be sure that EFI_PROVIDER + is as follows: + + EFI_PROVIDER = "gummiboot" + + + Build the master image: + Build the core-image-testmaster + image. + The core-image-testmaster + recipe is provided as an example for a + "master" image and you can customize the image + recipe as you would any other recipe. + + Here are the image recipe requirements: + + Inherits + core-image + so that kernel modules are installed. + + Installs normal linux utilities + not busybox ones (e.g. + bash, + coreutils, + tar, + gzip, and + kmod). + + Uses a custom + Initial RAM Disk (initramfs) image with a + custom installer. + A normal image that you can install usually + creates a single rootfs partition. + This image uses another installer that + creates a specific partition layout. + Not all Board Support Packages (BSPs) + can use an installer. + For such cases, you need to manually create + the following partition layout on the + target: + + First partition mounted + under /boot, + labeled "boot". + + The main rootfs + partition where this image gets + installed, which is mounted under + /. + + Another partition + labeled "testrootfs" where test + images get deployed. + + + + + + Install image: + Install the image that you just built on the target + system. + + + + + + The final thing you need to do when setting + TEST_TARGET to "GummibootTarget" is + to set up the test image: + + Set up your local.conf file: + Make sure you have the following statements in + your local.conf file: + + IMAGE_FSTYPES += "tar.gz" + INHERIT += "testimage" + TEST_TARGET = "GummibootTarget" + TEST_TARGET_IP = "192.168.2.3" + + + Build your test image: + Use BitBake to build the image: + + $ bitbake core-image-sato + + + + +
+ +
+ Power Control + + + For most hardware targets other than SimpleRemoteTarget, + you can control power: + + + You can use + TEST_POWERCONTROL_CMD + together with + TEST_POWERCONTROL_EXTRA_ARGS + as a command that runs on the host and does power + cycling. + The test code passes one argument to that command: + off, on or cycle (off then on). + Here is an example that could appear in your + local.conf file: + + TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1" + + In this example, the expect script does the + following: + + ssh test@10.11.12.1 "pyctl nuc1 arg" + + It then runs a Python script that controls power + for a label called nuc1. + + You need to customize + TEST_POWERCONTROL_CMD + and + TEST_POWERCONTROL_EXTRA_ARGS + for your own setup. + The one requirement is that it accepts + "on", "off", and "cycle" as the last argument. + + + + When no command is defined, it connects to the + device over SSH and uses the classic reboot command + to reboot the device. + Classic reboot is fine as long as the machine + actually reboots (i.e. the SSH test has not + failed). + It is useful for scenarios where you have a simple + setup, typically with a single board, and where + some manual interaction is okay from time to time. + + + If you have no hardware to automatically perform power + control but still wish to experiment with automated + hardware testing, you can use the dialog-power-control + script that shows a dialog prompting you to perform the + required power action. + This script requires either KDialog or Zenity to be + installed. + To use this script, set the + TEST_POWERCONTROL_CMD + variable as follows: + + TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control" + + +
+ +
+ Serial Console Connection + + + For test target classes requiring a serial console + to interact with the bootloader (e.g. BeagleBoneTarget, + EdgeRouterTarget, and GrubTarget), you need to + specify a command to use to connect to the serial console + of the target machine by using the + TEST_POWERCONTROL_CMD + variable and optionally the + TEST_SERIALCONTROL_EXTRA_ARGS + variable. + + + + These cases could be a serial terminal program if the + machine is connected to a local serial port, or a + telnet or + ssh command connecting to a remote + console server. + Regardless of the case, the command simply needs to + connect to the serial console and forward that connection + to standard input and output as any normal terminal + program does. + For example, to use the picocom terminal program on + serial device /dev/ttyUSB0 + at 115200bps, you would set the variable as follows: + + TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" + + For local devices where the serial port device disappears + when the device reboots, an additional "serdevtry" wrapper + script is provided. + To use this wrapper, simply prefix the terminal command + with + ${COREBASE}/scripts/contrib/serdevtry: + + TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b +115200 /dev/ttyUSB0" + + +
+
+ +
+ Running Tests + + + You can start the tests automatically or manually: + + Automatically running tests: + To run the tests automatically after the + OpenEmbedded build system successfully creates an image, + first set the + TEST_IMAGE + variable to "1" in your local.conf + file in the + Build Directory: + + TEST_IMAGE = "1" + + Next, build your image. + If the image successfully builds, the tests will be + run: + + bitbake core-image-sato + + Manually running tests: + To manually run the tests, first globally inherit the + testimage + class by editing your local.conf + file: + + INHERIT += "testimage" + + Next, use BitBake to run the tests: + + bitbake -c testimage image + + + + + + All test files reside in + meta/lib/oeqa/runtime in the + Source Directory. + A test name maps directly to a Python module. + Each test module may contain a number of individual tests. + Tests are usually grouped together by the area + tested (e.g tests for systemd reside in + meta/lib/oeqa/runtime/systemd.py). + + + + You can add tests to any layer provided you place them in the + proper area and you extend + BBPATH + in the local.conf file as normal. + Be sure that tests reside in + layer/lib/oeqa/runtime. + + Be sure that module names do not collide with module names + used in the default set of test modules in + meta/lib/oeqa/runtime. + + + + + You can change the set of tests run by appending or overriding + TEST_SUITES + variable in local.conf. + Each name in TEST_SUITES represents a + required test for the image. + Test modules named within TEST_SUITES + cannot be skipped even if a test is not suitable for an image + (e.g. running the RPM tests on an image without + rpm). + Appending "auto" to TEST_SUITES causes the + build system to try to run all tests that are suitable for the + image (i.e. each test module may elect to skip itself). + + + + The order you list tests in TEST_SUITES + is important and influences test dependencies. + Consequently, tests that depend on other tests should be added + after the test on which they depend. + For example, since the ssh test + depends on the + ping test, "ssh" needs to come after + "ping" in the list. + The test class provides no re-ordering or dependency handling. + + Each module can have multiple classes with multiple test + methods. + And, Python unittest rules apply. + + + + + Here are some things to keep in mind when running tests: + + The default tests for the image are defined + as: + + DEFAULT_TEST_SUITES_pn-image = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg" + + Add your own test to the list of the + by using the following: + + TEST_SUITES_append = " mytest" + + Run a specific list of tests as follows: + + TEST_SUITES = "test1 test2 test3" + + Remember, order is important. + Be sure to place a test that is dependent on another test + later in the order. + + +
+ +
+ Exporting Tests + + + You can export tests so that they can run independently of + the build system. + Exporting tests is required if you want to be able to hand + the test execution off to a scheduler. + You can only export tests that are defined in + TEST_SUITES. + + + + If your image is already built, make sure the following are set + in your local.conf file. + Be sure to provide the IP address you need: + + TEST_EXPORT_ONLY = "1" + TEST_TARGET = "simpleremote" + TEST_TARGET_IP = "192.168.7.2" + TEST_SERVER_IP = "192.168.7.1" + + You can then export the tests with the following: + + $ bitbake core-image-sato -c testimage + + Exporting the tests places them in the + Build Directory in + tmp/testimage/core-image-sato, which + is controlled by the + TEST_EXPORT_DIR variable. + + + + You can now run the tests outside of the build environment: + + $ cd tmp/testimage/core-image-sato + $ ./runexported.py testdata.json + + + This "export" feature does not deploy or boot the target + image. + Your target (be it a Qemu or hardware one) + has to already be up and running when you call + runexported.py + + + + + The exported data (i.e. testdata.json) + contains paths to the Build Directory. + Thus, the contents of the directory can be moved + to another machine as long as you update some paths in the + JSON. + Usually, you only care about the + ${DEPLOY_DIR}/rpm directory + (assuming the RPM and Smart tests are enabled). + Consequently, running the tests on other machine + means that you have to move the contents and call + runexported.py with + "‐‐deploy-dir path" as + follows: + + ./runexported.py ‐‐deploy-dir /new/path/on/this/machine testdata.json + + runexported.py accepts other arguments + as well as described using ‐‐help. + +
+ +
+ Writing New Tests + + + As mentioned previously, all new test files need to be in the + proper place for the build system to find them. + New tests for additional functionality outside of the core + should be added to the layer that adds the functionality, in + layer/lib/oeqa/runtime + (as long as + BBPATH + is extended in the layer's + layer.conf file as normal). + Just remember that filenames need to map directly to test + (module) names and that you do not use module names that + collide with existing core tests. + + + + To create a new test, start by copying an existing module + (e.g. syslog.py or + gcc.py are good ones to use). + Test modules can use code from + meta/lib/oeqa/utils, which are helper + classes. + + + + Structure shell commands such that you rely on them and they + return a single code for success. + Be aware that sometimes you will need to parse the output. + See the df.py and + date.py modules for examples. + + + + You will notice that all test classes inherit + oeRuntimeTest, which is found in + meta/lib/oetest.py. + This base class offers some helper attributes, which are + described in the following sections: + + +
+ Class Methods + + + Class methods are as follows: + + hasPackage(pkg): + Returns "True" if pkg is in the + installed package list of the image, which is based + on the manifest file that is generated during the + do_rootfs task. + + hasFeature(feature): + Returns "True" if the feature is in + IMAGE_FEATURES + or + DISTRO_FEATURES. + + + +
+ +
+ Class Attributes + + + Class attributes are as follows: + + pscmd: + Equals "ps -ef" if procps is + installed in the image. + Otherwise, pscmd equals + "ps" (busybox). + + tc: + The called text context, which gives access to the + following attributes: + + d: + The BitBake datastore, which allows you to + use stuff such as + oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager"). + + testslist and testsrequired: + Used internally. + The tests do not need these. + + filesdir: + The absolute path to + meta/lib/oeqa/runtime/files, + which contains helper files for tests meant + for copying on the target such as small + files written in C for compilation. + + target: + The target controller object used to deploy + and start an image on a particular target + (e.g. QemuTarget, SimpleRemote, and + GummibootTarget). + Tests usually use the following: + + ip: + The target's IP address. + + server_ip: + The host's IP address, which is + usually used by the "smart" test + suite. + + run(cmd, timeout=None): + The single, most used method. + This command is a wrapper for: + ssh root@host "cmd". + The command returns a tuple: + (status, output), which are what + their names imply - the return code + of "cmd" and whatever output + it produces. + The optional timeout argument + represents the number of seconds the + test should wait for "cmd" to + return. + If the argument is "None", the + test uses the default instance's + timeout period, which is 300 + seconds. + If the argument is "0", the test + runs until the command returns. + + copy_to(localpath, remotepath): + scp localpath root@ip:remotepath. + + copy_from(remotepath, localpath): + scp root@host:remotepath localpath. + + + + + +
+ +
+ Instance Attributes + + + A single instance attribute exists, which is + target. + The target instance attribute is + identical to the class attribute of the same name, which + is described in the previous section. + This attribute exists as both an instance and class + attribute so tests can use + self.target.run(cmd) in instance + methods instead of + oeRuntimeTest.tc.target.run(cmd). + +
+
+
+ +
+ Debugging With the GNU Project Debugger (GDB) Remotely + + + GDB allows you to examine running programs, which in turn helps you to understand and fix problems. + It also allows you to perform post-mortem style analysis of program crashes. + GDB is available as a package within the Yocto Project and is + installed in SDK images by default. + See the "Images" chapter + in the Yocto Project Reference Manual for a description of these images. + You can find information on GDB at . + + + + For best results, install debug (-dbg) packages + for the applications you are going to debug. + Doing so makes extra debug symbols available that give you more + meaningful output. + + + + Sometimes, due to memory or disk space constraints, it is not possible + to use GDB directly on the remote target to debug applications. + These constraints arise because GDB needs to load the debugging information and the + binaries of the process being debugged. + Additionally, GDB needs to perform many computations to locate information such as function + names, variable names and values, stack traces and so forth - even before starting the + debugging process. + These extra computations place more load on the target system and can alter the + characteristics of the program being debugged. + + + + To help get past the previously mentioned constraints, you can use Gdbserver. + Gdbserver runs on the remote target and does not load any debugging information + from the debugged process. + Instead, a GDB instance processes the debugging information that is run on a + remote computer - the host GDB. + The host GDB then sends control commands to Gdbserver to make it stop or start the debugged + program, as well as read or write memory regions of that debugged program. + All the debugging information loaded and processed as well + as all the heavy debugging is done by the host GDB. + Offloading these processes gives the Gdbserver running on the target a chance to remain + small and fast. + + By default, source files are part of the + *-dbg packages in order to enable GDB + to show source lines in its output. + You can save further space on the target by setting the + PACKAGE_DEBUG_SPLIT_STYLE + variable to "debug-without-src" so that these packages do not + include the source files. + + + + + Because the host GDB is responsible for loading the debugging information and + for doing the necessary processing to make actual debugging happen, + you have to make sure the host can access the unstripped binaries complete + with their debugging information and also be sure the target is compiled with no optimizations. + The host GDB must also have local access to all the libraries used by the + debugged program. + Because Gdbserver does not need any local debugging information, the binaries on + the remote target can remain stripped. + However, the binaries must also be compiled without optimization + so they match the host's binaries. + + + + To remain consistent with GDB documentation and terminology, the binary being debugged + on the remote target machine is referred to as the "inferior" binary. + For documentation on GDB see the + GDB site. + + + + The remainder of this section describes the steps you need to take + to debug using the GNU project debugger. + + +
+ Set Up the Cross-Development Debugging Environment + + + 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 "Preparing for Application Development" + chapter of the Yocto Project Application Developer's Guide + describes this process. + Be sure you have read that chapter and have set up + your environment. + +
+ +
+ Launch Gdbserver on the Target + + + Make sure Gdbserver is installed on the target. + If it is not, install the package + gdbserver, which needs the + libthread-db1 package. + + + + Here is an example, that when entered from the host, + connects to the target and launches Gdbserver in order to + "debug" a binary named helloworld: + + $ gdbserver localhost:2345 /usr/bin/helloworld + + Gdbserver should now be listening on port 2345 for debugging + commands coming from a remote GDB process that is running on + the host computer. + Communication between Gdbserver and the host GDB are done + using TCP. + To use other communication protocols, please refer to the + Gdbserver documentation. + +
+ +
+ Launch GDB on the Host Computer + + + Running GDB on the host computer takes a number of stages, which + this section describes. + + +
+ Build the Cross-GDB Package + + A suitable GDB cross-binary is required that runs on your + host computer but also knows about the the ABI of the + remote target. + You can get this binary from the + Cross-Development Toolchain. + Here is an example where the toolchain has been installed + in the default directory + /opt/poky/&DISTRO;: + + /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb + + where arm is the target architecture + and linux-gnueabi is the target ABI. + + + + Alternatively, you can use BitBake to build the + gdb-cross binary. + Here is an example: + + $ bitbake gdb-cross + + Once the binary is built, you can find it here: + + tmp/sysroots/host-arch/usr/bin/target-platform/target-abi-gdb + + +
+ +
+ Create the GDB Initialization File and Point to Your Root Filesystem + + + Aside from the GDB cross-binary, you also need a GDB + initialization file in the same top directory in which + your binary resides. + When you start GDB on your host development system, GDB + finds this initialization file and executes all the + commands within. + For information on the .gdbinit, see + "Debugging with GDB", + which is maintained by + sourceware.org. + + + + You need to add a statement in the + ~/.gdbinit file that points to your + root filesystem. + Here is an example that points to the root filesystem for + an ARM-based target device: + + set sysroot ~/sysroot_arm + + +
+ +
+ Launch the Host GDB + + + Before launching the host GDB, you need to be sure + you have sourced the cross-debugging environment script, + which if you installed the root filesystem in the default + location is at /opt/poky/&DISTRO; + and begins with the string "environment-setup". + For more information, see the + "Setting Up the Cross-Development Environment" + section in the Yocto Project Application Developer's + Guide. + + + + Finally, switch to the directory where the binary resides + and run the cross-gdb binary. + Provide the binary file you are going to debug. + For example, the following command continues with the + example used in the previous section by loading + the helloworld binary as well as the + debugging information: + + $ arm-poky-linux-gnuabi-gdb helloworld + + The commands in your .gdbinit execute + and the GDB prompt appears. + +
+
+ +
+ Connect to the Remote GDB Server + + + From the target, you need to connect to the remote GDB + server that is running on the host. + You need to specify the remote host and port. + Here is the command continuing with the example: + + target remote 192.168.7.2:2345 + + +
+ +
+ Use the Debugger + + + You can now proceed with debugging as normal - as if you were debugging + on the local machine. + For example, to instruct GDB to break in the "main" function and then + continue with execution of the inferior binary use the following commands + from within GDB: + + (gdb) break main + (gdb) continue + + + + + For more information about using GDB, see the project's online documentation at + . + +
+
+ +
+ Debugging Parallel Make Races + + + A parallel make race occurs when the build + consists of several parts that are run simultaneously and + a situation occurs when the output or result of one + part is not ready for use with a different part of the build that + depends on that output. + Parallel make races are annoying and can sometimes be difficult + to reproduce and fix. + However, some simple tips and tricks exist that can help + you debug and fix them. + This section presents a real-world example of an error encountered + on the Yocto Project autobuilder and the process used to fix it. + + +
+ The Failure + + + For this example, assume that you are building an image that + depends on the "neard" package. + And, during the build, BitBake runs into problems and + creates the following output. + + This example log file has longer lines artificially + broken to make the listing easier to read. + + If you examine the output or the log file, you see the + failure during make: + + | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] + | DEBUG: Executing shell function do_compile + | NOTE: make -j 16 + | make ‐‐no-print-directory all-am + | /bin/mkdir -p include/near + | /bin/mkdir -p include/near + | /bin/mkdir -p include/near + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/types.h include/near/types.h + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/log.h include/near/log.h + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/plugin.h include/near/plugin.h + | /bin/mkdir -p include/near + | /bin/mkdir -p include/near + | /bin/mkdir -p include/near + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/tag.h include/near/tag.h + | /bin/mkdir -p include/near + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/adapter.h include/near/adapter.h + | /bin/mkdir -p include/near + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/ndef.h include/near/ndef.h + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/tlv.h include/near/tlv.h + | /bin/mkdir -p include/near + | /bin/mkdir -p include/near + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/setting.h include/near/setting.h + | /bin/mkdir -p include/near + | /bin/mkdir -p include/near + | /bin/mkdir -p include/near + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/device.h include/near/device.h + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/nfc_copy.h include/near/nfc_copy.h + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/snep.h include/near/snep.h + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/version.h include/near/version.h + | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ + 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h + | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h + | i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ + build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/ + yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0 + -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/ + lib/glib-2.0/include -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/ + tmp/sysroots/qemux86/usr/include/dbus-1.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/ + nightly-x86/build/build/tmp/sysroots/qemux86/usr/lib/dbus-1.0/include -I/home/pokybuild/yocto-autobuilder/ + yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/libnl3 + -DNEAR_PLUGIN_BUILTIN -DPLUGINDIR=\""/usr/lib/near/plugins"\" + -DCONFIGDIR=\""/etc/neard\"" -O2 -pipe -g -feliminate-unused-debug-types -c + -o tools/snep-send.o tools/snep-send.c + | In file included from tools/snep-send.c:16:0: + | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory + | #include <near/dbus.h> + | ^ + | compilation terminated. + | make[1]: *** [tools/snep-send.o] Error 1 + | make[1]: *** Waiting for unfinished jobs.... + | make: *** [all] Error 2 + | ERROR: oe_runmake failed + + +
+ +
+ Reproducing the Error + + + Because race conditions are intermittent, they do not + manifest themselves every time you do the build. + In fact, most times the build will complete without problems + even though the potential race condition exists. + Thus, once the error surfaces, you need a way to reproduce it. + + + + In this example, compiling the "neard" package is causing the + problem. + So the first thing to do is build "neard" locally. + Before you start the build, set the + PARALLEL_MAKE + variable in your local.conf file to + a high number (e.g. "-j 20"). + Using a high value for PARALLEL_MAKE + increases the chances of the race condition showing up: + + $ bitbake neard + + + + + Once the local build for "neard" completes, start a + devshell build: + + $ bitbake neard -c devshell + + For information on how to use a + devshell, see the + "Using a Development Shell" + section. + + + + In the devshell, do the following: + + $ make clean + $ make tools/snep-send.o + + The devshell commands cause the failure + to clearly be visible. + In this case, a missing dependency exists for the "neard" + Makefile target. + Here is some abbreviated, sample output with the + missing dependency clearly visible at the end: + + i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/scott-lenovo/...... + . + . + . + tools/snep-send.c + In file included from tools/snep-send.c:16:0: + tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory + #include <near/dbus.h> + ^ + compilation terminated. + make: *** [tools/snep-send.o] Error 1 + $ + + +
+ +
+ Creating a Patch for the Fix + + + Because there is a missing dependency for the Makefile + target, you need to patch the + Makefile.am file, which is generated + from Makefile.in. + You can use Quilt to create the patch: + + $ quilt new parallelmake.patch + Patch patches/parallelmake.patch is now on top + $ quilt add Makefile.am + File Makefile.am added to patch patches/parallelmake.patch + + For more information on using Quilt, see the + "Using a Quilt Workflow" + section. + + + + At this point you need to make the edits to + Makefile.am to add the missing + dependency. + For our example, you have to add the following line + to the file: + + tools/snep-send.$(OBJEXT): include/near/dbus.h + + + + + Once you have edited the file, use the + refresh command to create the patch: + + $ quilt refresh + Refreshed patch patches/parallelmake.patch + + Once the patch file exists, you need to add it back to the + originating recipe folder. + Here is an example assuming a top-level + Source Directory + named poky: + + $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard + + The final thing you need to do to implement the fix in the + build is to update the "neard" recipe (i.e. + neard-0.14.bb) so that the + SRC_URI + statement includes the patch file. + The recipe file is in the folder above the patch. + Here is what the edited SRC_URI + statement would look like: + + SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ + file://neard.in \ + file://neard.service.in \ + file://parallelmake.patch \ + " + + + + + With the patch complete and moved to the correct folder and + the SRC_URI statement updated, you can + exit the devshell: + + $ exit + + +
+ +
+ Testing the Build + + + With everything in place, you can get back to trying the + build again locally: + + $ bitbake neard + + This build should succeed. + + + + Now you can open up a devshell again + and repeat the clean and make operations as follows: + + $ bitbake neard -c devshell + $ make clean + $ make tools/snep-send.o + + The build should work without issue. + + + + As with all solved problems, if they originated upstream, you + need to submit the fix for the recipe in OE-Core and upstream + so that the problem is taken care of at its source. + See the + "How to Submit a Change" + section for more information. + +
+
+ +
+ Examining Builds Using the Toaster API + + + Toaster is an Application Programming Interface (API) and + web-based interface to the OpenEmbedded build system, which uses + BitBake. + Both interfaces are based on a Representational State Transfer + (REST) API that queries for and returns build information using + GET and JSON. + These types of search operations retrieve sets of objects from + a datastore used to collect build information. + The results contain all the data for the objects being returned. + You can order the results of the search by key and the search + parameters are consistent for all object types. + + + + Using the interfaces you can do the following: + + See information about the tasks executed + and reused during the build. + See what is built (recipes and + packages) and what packages were installed into the final + image. + See performance-related information such + as build time, CPU usage, and disk I/O. + Examine error, warning and trace messages + to aid in debugging. + + + + + This release of Toaster provides you with information + about a BitBake run. + The tool does not allow you to configure and launch a build. + However, future development includes plans to integrate the + configuration and build launching capabilities of + Hob. + + For more information on using Hob to build an image, + see the + "Image Development Using Hob" + section. + + + + The remainder of this section describes what you need to have in + place to use Toaster, how to start it, use it, and stop it. + For additional information on installing and running Toaster, see the + "Installation and Running" + section of the "Toaster" wiki page. + For complete information on the API and its search operation + URI, parameters, and responses, see the + REST API Contracts + Wiki page. + + +
+ Starting Toaster + + + Getting set up to use and start Toaster is simple. + First, be sure you have met the following requirements: + + You have set up your + Source Directory + by cloning the upstream poky + repository. + See the + Yocto Project Release + item for information on how to set up the Source + Directory. + Be sure your build machine has + Django + version 1.5 installed. + Make sure that port 8000 and 8200 are + free (i.e. they have no servers on them). + + + + + + Once you have met the requirements, follow these steps to + start Toaster running in the background of your shell: + + Set up your build environment: + Source a build environment script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + Start Toaster: + Start the Toaster service using this + command from within your + Build Directory: + + $ source toaster start + + + The Toaster must be started and running in order + for it to collect data. + + + + + + When Toaster starts, it creates some additional files in your + Build Directory. + Deleting these files will cause you to lose data or interrupt + Toaster: + + toaster.sqlite: + Toaster's database file. + toaster_web.log: + The log file of the web server. + toaster_ui.log: + The log file of the user interface component. + + toastermain.pid: + The PID of the web server. + toasterui.pid: + The PID of the DSI data bridge. + bitbake-cookerdaemon.log: + The BitBake server's log file. + + +
+ +
+ Using Toaster + + + Once Toaster is running, it logs information for any BitBake + run from your Build Directory. + This logging is automatic. + All you need to do is access and use the information. + + + + You access the information one of two ways: + + Open a Browser and enter + http://localhost:8000 + for the URL. + + Use the xdg-open + tool from the shell and pass it the same URL. + + + Either method opens the home page for the Toaster interface. + + + Notes + + + For information on how to delete information from the + Toaster database, see the + Deleting a Build from the Toaster Database + wiki page. + + + For information on how to set up an instance of Toaster + on a remote host, see the + Setting Up a Toaster Instance on a Remote Host + wiki page. + + + +
+ +
+ Examining Toaster Data + + + The Toaster database is persistent regardless of whether you + start or stop the service. + + + + Toaster's interface shows you a list of builds + (successful and unsuccessful) for which it has data. + You can click on any build to see related information. + This information includes configuration details, information + about tasks, all recipes and packages built and their + dependencies, packages and their directory structure as + installed in your final image, + execution time, CPU usage and disk I/O per task. + + + + For details on the interface, see the + Toaster Manual. + +
+ +
+ Stopping Toaster + + + Stop the Toaster service with the following command + from with the + Build Directory: + + $ source toaster stop + + The service stops but the Toaster database remains persistent. + +
+
+ +
+ Profiling with OProfile + + + OProfile is a + statistical profiler well suited for finding performance + bottlenecks in both user-space software and in the kernel. + This profiler provides answers to questions like "Which functions does my application spend + the most time in when doing X?" + Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling + applications on target hardware straight forward. + + For more information on how to set up and run OProfile, see the + "oprofile" + section in the Yocto Project Profiling and Tracing Manual. + + + + + To use OProfile, you need an image that has OProfile installed. + The easiest way to do this is with "tools-profile" in the + IMAGE_FEATURES variable. + You also need debugging symbols to be available on the system where the analysis + takes place. + You can gain access to the symbols by using "dbg-pkgs" in the + IMAGE_FEATURES variable or by + installing the appropriate debug (-dbg) + packages. + + + + For successful call graph analysis, the binaries must preserve the frame + pointer register and should also be compiled with the + -fno-omit-framepointer flag. + You can achieve this by setting the + SELECTED_OPTIMIZATION + variable with the following options: + + -fexpensive-optimizations + -fno-omit-framepointer + -frename-registers + -O2 + + You can also achieve it by setting the + DEBUG_BUILD + variable to "1" in the local.conf configuration file. + If you use the DEBUG_BUILD variable, + you also add extra debugging information that can make the debug + packages large. + + +
+ Profiling on the Target + + + Using OProfile, you can perform all the profiling work on the target device. + A simple OProfile session might look like the following: + + + + + # opcontrol ‐‐reset + # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 + . + . + [do whatever is being profiled] + . + . + # opcontrol ‐‐stop + $ opreport -cl + + + + + In this example, the reset command clears any previously profiled data. + The next command starts OProfile. + The options used when starting the profiler separate dynamic library data + within applications, disable kernel profiling, and enable callgraphing up to + five levels deep. + + To profile the kernel, you would specify the + ‐‐vmlinux=/path/to/vmlinux option. + The vmlinux file is usually in the source directory in the + /boot/ directory and must match the running kernel. + + + + + After you perform your profiling tasks, the next command stops the profiler. + After that, you can view results with the opreport command with options + to see the separate library symbols and callgraph information. + + + + Callgraphing logs information about time spent in functions and about a function's + calling function (parent) and called functions (children). + The higher the callgraphing depth, the more accurate the results. + However, higher depths also increase the logging overhead. + Consequently, you should take care when setting the callgraphing depth. + + On ARM, binaries need to have the frame pointer enabled for callgraphing to work. + To accomplish this use the -fno-omit-framepointer option + with gcc. + + + + + For more information on using OProfile, see the OProfile + online documentation at + . + +
+ +
+ Using OProfileUI + + + A graphical user interface for OProfile is also available. + You can download and build this interface from the Yocto Project at + . + If the "tools-profile" image feature is selected, all necessary binaries + are installed onto the target device for OProfileUI interaction. + For a list of image features that ship with the Yocto Project, + see the + "Image Features" + section in the Yocto Project Reference Manual. + + + + Even though the source directory usually includes all needed patches on the target device, you + might find you need other OProfile patches for recent OProfileUI features. + If so, see the + OProfileUI README for the most recent information. + + +
+ Online Mode + + + Using OProfile in online mode assumes a working network connection with the target + hardware. + With this connection, you just need to run "oprofile-server" on the device. + By default, OProfile listens on port 4224. + + You can change the port using the ‐‐port command-line + option. + + + + + The client program is called oprofile-viewer and its UI is relatively + straight forward. + You access key functionality through the buttons on the toolbar, which + are duplicated in the menus. + Here are the buttons: + + Connect: Connects to the remote host. + You can also supply the IP address or hostname. + Disconnect: Disconnects from the target. + + Start: Starts profiling on the device. + + Stop: Stops profiling on the device and + downloads the data to the local host. + Stopping the profiler generates the profile and displays it in the viewer. + + Download: Downloads the data from the + target and generates the profile, which appears in the viewer. + Reset: Resets the sample data on the device. + Resetting the data removes sample information collected from previous + sampling runs. + Be sure you reset the data if you do not want to include old sample information. + + Save: Saves the data downloaded from the + target to another directory for later examination. + Open: Loads previously saved data. + + + + + + The client downloads the complete profile archive from + the target to the host for processing. + This archive is a directory that contains the sample data, the object files, + and the debug information for the object files. + The archive is then converted using the oparchconv script, which is + included in this distribution. + The script uses opimport to convert the archive from + the target to something that can be processed on the host. + + + + Downloaded archives reside in the + Build Directory in + tmp and are cleared up when they are no longer in use. + + + + If you wish to perform kernel profiling, you need to be sure + a vmlinux file that matches the running kernel is available. + In the source directory, that file is usually located in + /boot/vmlinux-kernelversion, where + kernelversion is the version of the kernel. + The OpenEmbedded build system generates separate vmlinux + packages for each kernel it builds. + Thus, it should just be a question of making sure a matching package is + installed (e.g. opkg install kernel-vmlinux). + The files are automatically installed into development and profiling images + alongside OProfile. + A configuration option exists within the OProfileUI settings page that you can use to + enter the location of the vmlinux file. + + + + Waiting for debug symbols to transfer from the device can be slow, and it + is not always necessary to actually have them on the device for OProfile use. + All that is needed is a copy of the filesystem with the debug symbols present + on the viewer system. + The "Launch GDB on the Host Computer" + section covers how to create such a directory within + the source directory and how to use the OProfileUI Settings + Dialog to specify the location. + If you specify the directory, it will be used when the file checksums + match those on the system you are profiling. + +
+ +
+ Offline Mode + + + If network access to the target is unavailable, you can generate + an archive for processing in oprofile-viewer as follows: + + # opcontrol ‐‐reset + # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 + . + . + [do whatever is being profiled] + . + . + # opcontrol ‐‐stop + # oparchive -o my_archive + + + + + In the above example, my_archive is the name of the + archive directory where you would like the profile archive to be kept. + After the directory is created, you can copy it to another host and load it + using oprofile-viewer open functionality. + If necessary, the archive is converted. + +
+
+
+ +
+ Maintaining Open Source License Compliance During Your Product's Lifecycle + + + One of the concerns for a development organization using open source + software is how to maintain compliance with various open source + licensing during the lifecycle of the product. + While this section does not provide legal advice or + comprehensively cover all scenarios, it does + present methods that you can use to + assist you in meeting the compliance requirements during a software + release. + + + + With hundreds of different open source licenses that the Yocto + Project tracks, it is difficult to know the requirements of each + and every license. + However, the requirements of the major FLOSS licenses can begin + to be covered by + assuming that three main areas of concern exist: + + Source code must be provided. + License text for the software must be + provided. + Compilation scripts and modifications to the + source code must be provided. + + + There are other requirements beyond the scope of these + three and the methods described in this section + (e.g. the mechanism through which source code is distributed). + + + + As different organizations have different methods of complying with + open source licensing, this section is not meant to imply that + there is only one single way to meet your compliance obligations, + but rather to describe one method of achieving compliance. + The remainder of this section describes methods supported to meet the + previously mentioned three requirements. + Once you take steps to meet these requirements, + and prior to releasing images, sources, and the build system, + you should audit all artifacts to ensure completeness. + + The Yocto Project generates a license manifest during + image creation that is located + in ${DEPLOY_DIR}/licenses/image_name-datestamp + to assist with any audits. + + + +
+ Providing the Source Code + + + Compliance activities should begin before you generate the + final image. + The first thing you should look at is the requirement that + tops the list for most compliance groups - providing + the source. + The Yocto Project has a few ways of meeting this + requirement. + + + + One of the easiest ways to meet this requirement is + to provide the entire + DL_DIR + used by the build. + This method, however, has a few issues. + The most obvious is the size of the directory since it includes + all sources used in the build and not just the source used in + the released image. + It will include toolchain source, and other artifacts, which + you would not generally release. + However, the more serious issue for most companies is accidental + release of proprietary software. + The Yocto Project provides an + archiver + class to help avoid some of these concerns. + + + + Before you employ DL_DIR or the + archiver class, you need to decide how you choose to + provide source. + The source archiver class can generate tarballs and SRPMs + and can create them with various levels of compliance in mind. + + + + One way of doing this (but certainly not the only way) is to + release just the source as a tarball. + You can do this by adding the following to the + local.conf file found in the + Build Directory: + + INHERIT += "archiver" + ARCHIVER_MODE[src] = "original" + + During the creation of your image, the source from all + recipes that deploy packages to the image is placed within + subdirectories of + DEPLOY_DIR/sources based on the + LICENSE + for each recipe. + Releasing the entire directory enables you to comply with + requirements concerning providing the unmodified source. + It is important to note that the size of the directory can + get large. + + + + A way to help mitigate the size issue is to only release + tarballs for licenses that require the release of + source. + Let us assume you are only concerned with GPL code as + identified with the following: + + $ cd poky/build/tmp/deploy/sources + $ mkdir ~/gpl_source_release + $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done + + At this point, you could create a tarball from the + gpl_source_release directory and + provide that to the end user. + This method would be a step toward achieving compliance + with section 3a of GPLv2 and with section 6 of GPLv3. + +
+ +
+ Providing License Text + + + One requirement that is often overlooked is inclusion + of license text. + This requirement also needs to be dealt with prior to + generating the final image. + Some licenses require the license text to accompany + the binary. + You can achieve this by adding the following to your + local.conf file: + + COPY_LIC_MANIFEST = "1" + COPY_LIC_DIRS = "1" + + Adding these statements to the configuration file ensures + that the licenses collected during package generation + are included on your image. + 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 + of the license information with source as defined by the GPL + and other open source licenses. + +
+ +
+ Providing Compilation Scripts and Source Code Modifications + + + At this point, we have addressed all we need to address + prior to generating the image. + The next two requirements are addressed during the final + packaging of the release. + + + + By releasing the version of the OpenEmbedded build system + and the layers used during the build, you will be providing both + compilation scripts and the source code modifications in one + step. + + + + If the deployment team has a + BSP layer + and a distro layer, and those those layers are used to patch, + compile, package, or modify (in any way) any open source + software included in your released images, you + might be required to to release those layers under section 3 of + GPLv2 or section 1 of GPLv3. + One way of doing that is with a clean + checkout of the version of the Yocto Project and layers used + during your build. + Here is an example: + + # We built using the &DISTRO_NAME; branch of the poky repo + $ git clone -b &DISTRO_NAME; 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 + $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer + # clean up the .git repos + $ find . -name ".git" -type d -exec rm -rf {} \; + + One thing a development organization might want to consider + for end-user convenience is to modify + meta-yocto/conf/bblayers.conf.sample 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 bblayers.conf + file automatically: + + # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf + # changes incompatibly + LCONF_VERSION = "6" + + BBPATH = "${TOPDIR}" + BBFILES ?= "" + + BBLAYERS ?= " \ + ##OEROOT##/meta \ + ##OEROOT##/meta-yocto \ + ##OEROOT##/meta-yocto-bsp \ + ##OEROOT##/meta-mylayer \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + ##OEROOT##/meta \ + ##OEROOT##/meta-yocto \ + " + + Creating and providing an archive of the + Metadata layers + (recipes, configuration files, and so forth) + enables you to meet your + requirements to include the scripts to control compilation + as well as any modifications to the original source. + +
+
+ +
+ Using the Error Reporting Tool + + + The error reporting tool allows you to + submit errors encountered during builds to a central database. + Outside of the build environment, you can use a web interface to + browse errors, view statistics, and query for errors. + The tool works using a client-server system where the client + portion is integrated with the installed Yocto Project + Source Directory + (e.g. poky). + The server receives the information collected and saves it in a + database. + + + + A live instance of the error reporting server exists at + . + This server exists so that when you want to get help with + build failures, you can submit all of the information on the + failure easily and then point to the URL in your bug report + or send an email to the mailing list. + + If you send error reports to this server, the reports become + publicly visible. + + + +
+ Enabling and Using the Tool + + + By default, the error reporting tool is disabled. + You can enable it by inheriting the + report-error + class by adding the following statement to the end of + your local.conf file in your + Build Directory. + + INHERIT += "report-error" + + + + + By default, the error reporting feature stores information in + ${LOG_DIR}/error-report. + However, you can specify a directory to use by adding the following + to your local.conf file: + + ERR_REPORT_DIR = "path" + + Enabling error reporting causes the build process to collect + the errors and store them in a file as previously described. + When the build system encounters an error, it includes a command + as part of the console output. + You can run the command to send the error file to the server. + For example, the following command sends the errors to an upstream + server: + + send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server] + + In the above example, the server parameter is + optional. + By default, the errors are sent to a database used by the entire + community. + If you specify a particular server, you can send them to a different + database. + + + + When sending the error file, you receive a link that corresponds + to your entry in the database. + For example, here is a typical link: + + http://localhost:8000/Errors/Search/1/158 + + Following the link takes you to a web interface where you can + browse, query the errors, and view statistics. + +
+ +
+ Disabling the Tool + + + To disable the error reporting feature, simply remove or comment + out the following statement from the end of your + local.conf file in your + Build Directory. + + INHERIT += "report-error" + + +
+ +
+ Setting Up Your Own Error Reporting Server + + + If you want to set up your own error reporting server, you + can obtain the code from the Git repository at + . + Instructions on how to set it up are in the README document. + +
+
+
+ + diff --git a/documentation/dev-manual/dev-manual-customization.xsl b/documentation/dev-manual/dev-manual-customization.xsl new file mode 100644 index 0000000000..5dd425c810 --- /dev/null +++ b/documentation/dev-manual/dev-manual-customization.xsl @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/documentation/dev-manual/dev-manual-eclipse-customization.xsl b/documentation/dev-manual/dev-manual-eclipse-customization.xsl new file mode 100644 index 0000000000..8ac4c18f25 --- /dev/null +++ b/documentation/dev-manual/dev-manual-eclipse-customization.xsl @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml new file mode 100644 index 0000000000..21fba29670 --- /dev/null +++ b/documentation/dev-manual/dev-manual-intro.xml @@ -0,0 +1,240 @@ + %poky; ] > + + + +The Yocto Project Development Manual +
+ Introduction + + + Welcome to the Yocto Project Development Manual! + This manual provides information on how to use the Yocto Project to + develop embedded Linux images and user-space applications that + run on targeted devices. + The manual provides an overview of image, kernel, and + user-space application development using the Yocto Project. + Because much of the information in this manual is general, it + contains many references to other sources where you can find more + detail. + For example, you can find detailed information on Git, repositories, + and open source in general in many places on the Internet. + Another example specific to the Yocto Project is how to quickly + set up your host development system and build an image, which you + find in the + Yocto Project Quick Start. + + + + 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 Eclipse IDE. + + + + By default, using the Yocto Project creates a Poky distribution. + However, you can create your own distribution by providing key + Metadata. + A good example is Angstrom, which has had a distribution + based on the Yocto Project since its inception. + Other examples include commercial distributions like + Wind River Linux, + Mentor Embedded Linux, + ENEA Linux + and others. + See the "Creating Your Own Distribution" + section for more information. + +
+ +
+ What This Manual Provides + + + The following list describes what you can get from this manual: + + Information that lets you get set + up to develop using the Yocto Project. + Information to help developers who are new to + the open source environment and to the distributed revision + control system Git, which the Yocto Project uses. + + An understanding of common end-to-end + development models and tasks. + Information about common development tasks + generally used during image development for + embedded devices. + + Information on using the Yocto Project + integration of the QuickEMUlator (QEMU), which lets you + simulate running on hardware an image you have built using + the OpenEmbedded build system. + + Many references to other sources of related + information. + + +
+ +
+ What this Manual Does Not Provide + + + This manual will not give you the following: + + Step-by-step instructions when those instructions exist in other Yocto + Project documentation: + For example, the Yocto Project Application Developer's Guide contains detailed + instructions on how to run the + ADT Installer, + which is used to set up a cross-development environment. + Reference material: + This type of material resides in an appropriate reference manual. + For example, system variables are documented in the + Yocto Project Reference Manual. + Detailed public information that is not specific to the Yocto Project: + For example, exhaustive information on how to use Git is covered better through the + Internet than in this manual. + + +
+ +
+ Other Information + + + Because this manual presents overview information for many different + topics, supplemental information is recommended for full + comprehension. + The following list presents other sources of information you might find helpful: + + Yocto Project Website: + The home page for the Yocto Project provides lots of information on the project + as well as links to software and documentation. + + + Yocto Project Quick Start: + This short document lets you get started + with the Yocto Project and quickly begin building an image. + + + Yocto Project Reference Manual: + This manual is a reference + guide to the OpenEmbedded build system, which is based on BitBake. + The build system is sometimes referred to as "Poky". + + + Yocto Project Application Developer's Guide: + 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. + + + Yocto Project Board Support Package (BSP) Developer's Guide: + This guide defines the structure for BSP components. + Having a commonly understood structure encourages standardization. + + + Yocto Project Linux Kernel Development Manual: + This manual describes how to work with Linux Yocto kernels as well as provides a bit + of conceptual information on the construction of the Yocto Linux kernel tree. + + + Yocto Project Profiling and Tracing Manual: + This manual presents a set of common and generally useful tracing and + profiling schemes along with their applications (as appropriate) to each tool. + + + + Eclipse IDE Yocto Plug-in: + A step-by-step instructional video that + demonstrates how an application developer uses Yocto Plug-in features within + the Eclipse IDE. + + + FAQ: + A list of commonly asked questions and their answers. + + + Release Notes: + Features, updates and known issues for the current + release of the Yocto Project. + + + Hob: + A graphical user interface for BitBake. + Hob's primary goal is to enable a user to perform common tasks more easily. + + + Toaster: + An Application Programming Interface (API) and web-based + interface to the OpenEmbedded build system, which uses + BitBake, that reports build information. + + + Build Appliance: + A virtual machine that + enables you to build and boot a custom embedded Linux image + with the Yocto Project using a non-Linux development system. + + + Bugzilla: + The bug tracking application the Yocto Project uses. + If you find problems with the Yocto Project, you should report them using this + application. + + Yocto Project Mailing Lists: + To subscribe to the Yocto Project mailing + lists, click on the following URLs and follow the instructions: + + + for a Yocto Project Discussions mailing list. + + + for a Yocto Project Discussions mailing list about the + OpenEmbedded build system (Poky). + + + for a mailing list to receive official Yocto Project announcements + as well as Yocto Project milestones. + + + for a listing of all public mailing lists on + lists.yoctoproject.org. + + + Internet Relay Chat (IRC): + Two IRC channels on freenode are available + for Yocto Project and Poky discussions: #yocto and + #poky, respectively. + + + OpenEmbedded: + The build system used by the Yocto Project. + This project is the upstream, generic, embedded distribution + from which the Yocto Project derives its build system (Poky) + and to which it contributes. + + + BitBake: + The tool used by the OpenEmbedded build system + to process project metadata. + + + BitBake User Manual: + A comprehensive guide to the BitBake tool. + If you want information on BitBake, see this manual. + + + Quick EMUlator (QEMU): + An open-source machine emulator and virtualizer. + + + +
+
+ diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml new file mode 100644 index 0000000000..43c31b8405 --- /dev/null +++ b/documentation/dev-manual/dev-manual-model.xml @@ -0,0 +1,2112 @@ + %poky; ] > + + + +Common Development Models + + + Many development models exist for which you can use the Yocto Project. + This chapter overviews simple methods that use tools provided by the + Yocto Project: + + System Development: + System Development covers Board Support Package (BSP) development and kernel + modification or configuration. + For an example on how to create a BSP, see the + "Creating a New BSP Layer Using the yocto-bsp Script" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. + For more complete information on how to work with the kernel, see the + Yocto Project Linux Kernel Development Manual. + + User Application Development: + User Application Development covers development of applications that you intend + to run on target hardware. + For information on how to set up your host development system for user-space + application development, see the + Yocto Project Application Developer's Guide. + For a simple example of user-space application development using the + Eclipse IDE, see the + "Application + Development Workflow" section. + + Temporary Source Code Modification: + Direct modification of temporary source code is a convenient development model + to quickly iterate and develop towards a solution. + Once you implement the solution, you should of course take steps to + get the changes upstream and applied in the affected recipes. + Image Development using Hob: + You can use the Hob to build + custom operating system images within the build environment. + Hob provides an efficient interface to the OpenEmbedded build system. + Using a Development Shell: + You can use a devshell 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. + + + +
+ System Development Workflow + + + System development involves modification or creation of an image that you want to run on + a specific hardware target. + Usually, when you want to create an image that runs on embedded hardware, the image does + not require the same number of features that a full-fledged Linux distribution provides. + Thus, you can create a much smaller image that is designed to use only the + features for your particular hardware. + + + + To help you understand how system development works in the Yocto Project, this section + covers two types of image development: BSP creation and kernel modification or + configuration. + + +
+ Developing a Board Support Package (BSP) + + + A BSP is a collection of recipes that, when applied during a build, results in + an image that you can run on a particular board. + Thus, the package when compiled into the new image, supports the operation of the board. + + + + For a brief list of terms used when describing the development process in the Yocto Project, + see the "Yocto Project Terms" section. + + + + The remainder of this section presents the basic + steps used to create a BSP using the Yocto Project's + BSP Tools. + Although not required for BSP creation, the + meta-intel repository, which contains + many BSPs supported by the Yocto Project, is part of the example. + + + + For an example that shows how to create a new layer using the tools, see the + "Creating a New BSP Layer Using the yocto-bsp Script" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. + + + + The following illustration and list summarize the BSP creation general workflow. + + + + + + + + + Set up your host development system to support + development using the Yocto Project: See the + "The Linux Distribution" + and the + "The Packages" sections both + in the Yocto Project Quick Start for requirements. + Establish a local copy of the project files on your + system: You need this Source + Directory available on your host system. + Having these files on your system gives you access to the build + process and to the tools you need. + For information on how to set up the Source Directory, + see the + "Getting Set Up" section. + Establish the meta-intel + repository on your system: Having local copies + of these supported BSP layers on your system gives you + access to layers you might be able to build on or modify + to create your BSP. + For information on how to get these files, see the + "Getting Set Up" section. + Create your own BSP layer using the + yocto-bsp script: + Layers are ideal for + isolating and storing work for a given piece of hardware. + A layer is really just a location or area in which you place + the recipes and configurations for your BSP. + In fact, a BSP is, in itself, a special type of layer. + The simplest way to create a new BSP layer that is compliant with the + Yocto Project is to use the yocto-bsp script. + For information about that script, see the + "Creating a New BSP Layer Using the yocto-bsp Script" + section in the Yocto Project Board Support (BSP) Developer's Guide. + + + 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 + "Understanding and Creating Layers" + section. + For more information on BSP layers, see the + "BSP Layers" section in the + Yocto Project Board Support Package (BSP) Developer's Guide. + Five BSPs exist that are part of the + Yocto Project release: genericx86, genericx86-64, + beaglebone (ARM), + mpc8315e (PowerPC), + and edgerouter (MIPS). + The recipes and configurations for these five BSPs are located and dispersed + within the Source Directory. + On the other hand, the meta-intel 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 meta-intel + layer, the + Source Repositories + contain additional BSP layers such as + meta-minnow and + meta-raspberrypi. + When you set up a layer for a new BSP, you should follow a standard layout. + This layout is described in the + "Example Filesystem Layout" + section of the Board Support Package (BSP) Development Guide. + In the standard layout, you will notice a suggested structure for recipes and + configuration information. + You can see the standard layout for a BSP by examining + any supported BSP found in the meta-intel layer inside + the Source Directory. + Make configuration changes to your new BSP + layer: The standard BSP layer structure organizes the files you need + to edit in conf and several recipes-* + directories within the BSP layer. + Configuration changes identify where your new layer is on the local system + and identify which kernel you are going to use. + When you run the yocto-bsp script, you are able to interactively + configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). + + Make recipe changes to your new BSP layer: Recipe + changes include altering recipes (.bb files), removing + recipes you do not use, and adding new recipes or append files + (.bbappend) that you need to support your hardware. + + Prepare for the build: Once you have made all the + changes to your BSP layer, there remains a few things + you need to do for the OpenEmbedded build system in order for it to create your image. + You need to get the build environment ready by sourcing an environment setup script + (i.e. oe-init-build-env or + oe-init-build-env-memres) + and you need to be sure two key configuration files are configured appropriately: + the conf/local.conf and the + conf/bblayers.conf file. + You must make the OpenEmbedded build system aware of your new layer. + See the + "Enabling Your Layer" section + for information on how to let the build system know about your new layer. + The entire process for building an image is overviewed in the section + "Building an Image" section + of the Yocto Project Quick Start. + You might want to reference this information. + Build the image: The OpenEmbedded build system + uses the BitBake tool to build images based on the type of image you want to create. + You can find more information about BitBake in the + BitBake User Manual. + + The build process supports several types of images to satisfy different needs. + See the + "Images" chapter + in the Yocto Project Reference Manual for information on + supported images. + + + + + You can view a video presentation on "Building Custom Embedded Images with Yocto" + at Free Electrons. + After going to the page, just search for "Embedded". + You can also find supplemental information in the + + Yocto Project Board Support Package (BSP) Developer's Guide. + Finally, there is a wiki page write up of the example also located + + here that you might find helpful. + +
+ +
+ <anchor id='kernel-spot' />Modifying the Kernel + + + Kernel modification involves changing the Yocto Project kernel, which could involve changing + configuration options as well as adding new kernel recipes. + Configuration changes can be added in the form of configuration fragments, while recipe + modification comes through the kernel's recipes-kernel area + in a kernel layer you create. + + + + The remainder of this section presents a high-level overview of the Yocto Project + kernel architecture and the steps to modify the kernel. + You can reference the + "Patching the Kernel" section + for an example that changes the source code of the kernel. + For information on how to configure the kernel, see the + "Configuring the Kernel" section. + For more information on the kernel and on modifying the kernel, see the + Yocto Project Linux Kernel Development Manual. + + +
+ Kernel Overview + + + Traditionally, when one thinks of a patched kernel, they think of a base kernel + source tree and a fixed structure that contains kernel patches. + The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source + generator. + By the end of this section, this analogy will become clearer. + + + + You can find a web interface to the Yocto Project kernel source repositories at + . + If you look at the interface, you will see to the left a grouping of + Git repositories titled "Yocto Linux Kernel." + Within this group, you will find several kernels supported by + the Yocto Project: + + + linux-yocto-3.8 - 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. + + + linux-yocto-3.10 - The + stable Yocto Project kernel to use with the Yocto + Project Release 1.5. + This kernel is based on the Linux 3.10 released kernel. + + + linux-yocto-3.14 - The + stable Yocto Project kernel to use with the Yocto + Project Releases 1.6 and 1.7. + This kernel is based on the Linux 3.14 released kernel. + + + linux-yocto-3.17 - An + additional Yocto Project kernel used with the Yocto + Project Release 1.7. + This kernel is based on the Linux 3.17 released kernel. + + + linux-yocto-dev - A + development kernel based on the latest upstream release + candidate available. + + + + + + The kernels are maintained using the Git revision control system + that structures them using the familiar "tree", "branch", and "leaf" scheme. + Branches represent diversions from general code to more specific code, while leaves + represent the end-points for a complete and unique kernel whose source files, + when gathered from the root of the tree to the leaf, accumulate to create the files + necessary for a specific piece of hardware and its features. + The following figure displays this concept: + + + + + + Within the figure, the "Kernel.org Branch Point" represents the point in the tree + where a supported base kernel is modified from the Linux kernel. + For example, this could be the branch point for the linux-yocto-3.4 + kernel. + Thus, everything further to the right in the structure is based on the + linux-yocto-3.4 kernel. + Branch points to the right in the figure represent where the + linux-yocto-3.4 kernel is modified for specific hardware + or types of kernels, such as real-time kernels. + Each leaf thus represents the end-point for a kernel designed to run on a specific + targeted device. + + + + The overall result is a Git-maintained repository from which all the supported + kernel types can be derived for all the supported devices. + A big advantage to this scheme is the sharing of common features by keeping them in + "larger" branches within the tree. + This practice eliminates redundant storage of similar features shared among kernels. + + + + Keep in mind the figure does not take into account all the supported Yocto + Project kernel types, but rather shows a single generic kernel just for conceptual purposes. + Also keep in mind that this structure represents the Yocto Project source repositories + that are either pulled from during the build or established on the host development system + prior to the build by either cloning a particular kernel's Git repository or by + downloading and unpacking a tarball. + + + + Upstream storage of all the available kernel source code is one thing, while + representing and using the code on your host development system is another. + Conceptually, you can think of the kernel source repositories as all the + source files necessary for all the supported kernels. + As a developer, you are just interested in the source files for the kernel on + which you are working. + And, furthermore, you need them available on your host system. + + + + Kernel source code is available on your host system a couple of different + ways. + If you are working in the kernel all the time, you probably would want + to set up your own local Git repository of the kernel tree. + If you just need to make some patches to the kernel, you can access + temporary kernel source files that were extracted and used + during a build. + We will just talk about working with the temporary source code. + For more information on how to get kernel source code onto your + host system, see the + "Yocto Project Kernel" + bulleted item earlier in the manual. + + + + What happens during the build? + When you build the kernel on your development system, all files needed for the build + are taken from the source repositories pointed to by the + SRC_URI variable + and gathered in a temporary work area + where they are subsequently used to create the unique kernel. + Thus, in a sense, the process constructs a local source tree specific to your + kernel to generate the new kernel image - a source generator if you will. + + The following figure shows the temporary file structure + created on your host system when the build occurs. + This + Build Directory contains all the + source files used during the build. + + + + + + + + Again, for additional information on the Yocto Project kernel's + architecture and its branching strategy, see the + Yocto Project Linux Kernel Development Manual. + You can also reference the + "Patching the Kernel" + section for a detailed example that modifies the kernel. + +
+ +
+ Kernel Modification Workflow + + + This illustration and the following list summarizes the kernel modification general workflow. + + + + + + + + + Set up your host development system to support + development using the Yocto Project: See + "The Linux Distribution" and + "The Packages" sections both + in the Yocto Project Quick Start for requirements. + Establish a local copy of project files on your + system: Having the Source + Directory on your system gives you access to the build process and tools + you need. + For information on how to get these files, see the bulleted item + "Yocto Project Release" earlier in this manual. + + Establish the temporary kernel source files: + Temporary kernel source files are kept in the + Build Directory + created by the + OpenEmbedded build system when you run BitBake. + If you have never built the kernel in which you are + interested, you need to run an initial build to + establish local kernel source files. + If you are building an image for the first time, you need to get the build + environment ready by sourcing an environment setup script + (i.e. oe-init-build-env or + oe-init-build-env-memres). + You also need to be sure two key configuration files + (local.conf and bblayers.conf) + are configured appropriately. + The entire process for building an image is overviewed in the + "Building an Image" + section of the Yocto Project Quick Start. + You might want to reference this information. + You can find more information on BitBake in the + BitBake User Manual. + + The build process supports several types of images to satisfy different needs. + See the "Images" chapter in + the Yocto Project Reference Manual for information on supported images. + + Make changes to the kernel source code if + applicable: Modifying the kernel does not always mean directly + changing source files. + However, if you have to do this, you make the changes to the files in the + Build Directory. + Make kernel configuration changes + if applicable: + If your situation calls for changing the kernel's configuration, you can + use the yocto-kernel script or menuconfig + to enable and disable kernel configurations. + Using the script lets you interactively set up kernel configurations. + Using menuconfig allows you to interactively develop and test the + configuration changes you are making to the kernel. + When saved, changes using menuconfig update the kernel's + .config file. + Try to resist the temptation of directly editing the .config + file found in the Build Directory at + tmp/sysroots/<machine-name>/kernel. + Doing so, can produce unexpected results when the OpenEmbedded build system + regenerates the configuration file. + Once you are satisfied with the configuration changes made using + menuconfig, you can directly compare the + .config file against a saved original and gather those + changes into a config fragment to be referenced from within the kernel's + .bbappend file. + Rebuild the kernel image with your changes: + Rebuilding the kernel image applies your changes. + + +
+
+
+ +
+ Application Development Workflow + + + 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 + Application Development Toolkit (ADT) + and stand-alone + cross-development toolchains + 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 Eclipse IDE, + you can use an Eclipse Yocto Plug-in to + allow you to develop, deploy, and test your application all from within Eclipse. + + + + 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. + + +
+ Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark> + + + 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. + + + + The following illustration and list summarize the application development general workflow. + + + + + + + + + Prepare the host system for the Yocto Project: + See + "Supported Linux Distributions" + and + "Required Packages for the Host Development System" sections both + in the Yocto Project Reference Manual for requirements. + In particular, be sure your host system has the + xterm package installed. + + Secure the Yocto Project kernel target image: + You must have a target kernel image that has been built using the OpenEmbedded + build system. + 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. + + Download the image from + machines + if your target architecture is supported and you are going to develop + and test your application on actual hardware. + Download the image from + + machines/qemu if your target architecture is supported + and you are going to develop and test your application using the QEMU + emulator. + 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 + "Patching the Kernel" + section for an example. + + For information on pre-built kernel image naming schemes for images + that can run on the QEMU emulator, see the + "Downloading the Pre-Built Linux Kernel" + section in the Yocto Project Quick Start. + Install the ADT: + 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 + "Using the ADT Installer" + section + in the Yocto Project Application Developer's Guide. + If applicable, secure the target root filesystem + and the Cross-development toolchain: + 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. + 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. + You can find the cross-development toolchains at + toolchains. + Be sure to get the correct toolchain for your development host and your + target architecture. + See the "Using a Cross-Toolchain Tarball" + section in the Yocto Project Application Developer's Guide for information + and the + "Installing the Toolchain" + in the Yocto Project Quick Start for information on finding and installing + the correct toolchain based on your host development system and your target + architecture. + + Create and build your application: + 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. + Deploy the image with the application: + 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 + "Using the Quick EMUlator (QEMU)" + chapter for information on using QEMU. + + Test and debug the application: + 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. + + +
+ +
+ Working Within Eclipse + + + The Eclipse IDE is a popular development environment and it fully + supports development using the Yocto Project. + + This release of the Yocto Project supports both the Kepler + and Juno versions of the Eclipse IDE. + Thus, the following information provides setup information for + both versions. + + + + + 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. + + + + This section describes how to install and configure the Eclipse IDE + Yocto Plug-in and how to use it to develop your application. + + +
+ Setting Up the Eclipse IDE + + + To develop within the Eclipse IDE, you need to do the following: + + Install the optimal version of the Eclipse + IDE. + Configure the Eclipse IDE. + + Install the Eclipse Yocto Plug-in. + + Configure the Eclipse Yocto Plug-in. + + + + 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. + + + +
+ Installing the Eclipse IDE + + + It is recommended that you have the Kepler 4.3.2 version of + the Eclipse IDE installed on your development system. + However, if you currently have the Juno 4.2 version + installed and you do not want to upgrade the IDE, you can + configure Juno to work with the Yocto Project. + + + + If you do not have the Kepler 4.3.2 Eclipse IDE installed, + you can find the tarball at + . + From that site, choose the Eclipse Standard 4.3.2 version + particular to your development host. + This version contains the Eclipse Platform, the Java + Development Tools (JDT), and the Plug-in Development + Environment. + + + + 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 eclipse: + + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-standard-kepler-SR2-linux-gtk-x86_64.tar.gz + + +
+ +
+ Configuring the Eclipse IDE + + + This section presents the steps needed to configure the + Eclipse IDE. + + + + Before installing and configuring the Eclipse Yocto Plug-in, + you need to configure the Eclipse IDE. + Follow these general steps: + + Start the Eclipse IDE. + Make sure you are in your Workbench and + select "Install New Software" from the "Help" + pull-down menu. + Select + Kepler - &ECLIPSE_KEPLER_URL; + from the "Work with:" pull-down menu. + + For Juno, select + Juno - &ECLIPSE_JUNO_URL; + + + Expand the box next to "Linux Tools" + and select the + LTTng - Linux Tracing Toolkit + boxes. + Expand the box next to "Mobile and + Device Development" and select the following boxes: + + C/C++ Remote Launch (Requires RSE Remote System Explorer) + Remote System Explorer End-user Runtime + Remote System Explorer User Actions + Target Management Terminal + TCF Remote System Explorer add-in + TCF Target Explorer + + Expand the box next to "Programming + Languages" and select the + C/C++ Autotools Support + and C/C++ Development Tools + boxes. + Complete the installation and restart + the Eclipse IDE. + + +
+ +
+ Installing or Accessing the Eclipse Yocto Plug-in + + + 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. + + +
+ Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site + + + To install the Eclipse Yocto Plug-in from the update + site, follow these steps: + + Start up the Eclipse IDE. + + In Eclipse, select "Install New + Software" from the "Help" menu. + + Click "Add..." in the "Work with:" + area. + Enter + &ECLIPSE_DL_PLUGIN_URL;/kepler + in the URL field and provide a meaningful name + in the "Name" field. + + If you are using Juno, use + &ECLIPSE_DL_PLUGIN_URL;/juno + in the URL field. + + Click "OK" to have the entry added + to the "Work with:" drop-down list. + + Select the entry for the plug-in + from the "Work with:" drop-down list. + + Check the boxes next to + Yocto Project ADT Plug-in, + Yocto Project Bitbake Commander Plug-in, + and + Yocto Project Documentation plug-in. + + Complete the remaining software + installation steps and then restart the Eclipse + IDE to finish the installation of the plug-in. + + + +
+ +
+ Installing the Plug-in Using the Latest Source Code + + + To install the Eclipse Yocto Plug-in from the latest + source code, follow these steps: + + Be sure your development system + is not using OpenJDK to build the plug-in + by doing the following: + + Use the Oracle JDK. + If you don't have that, go to + + and download the appropriate tarball + for your development system and + extract it into your home directory. + + In the shell you are going + to do your work, export the location of + the Oracle Java as follows: + + export PATH=~/jdk1.7.0_40/bin:$PATH + + + In the same shell, create a Git + repository with: + + $ cd ~ + $ git clone git://git.yoctoproject.org/eclipse-poky-kepler + + + If you are using Juno, the repository is + located at + git://git.yoctoproject.org/eclipse-poky-juno. + + For this example, the repository is named + ~/eclipse-poky-kepler. + + Change to the directory where you + set up the Git repository: + + $ cd ~/eclipse-poky-kepler + + Be sure you are in the right branch + for your Git repository. + For this release set the branch to + &DISTRO_NAME;: + + $ git checkout &DISTRO_NAME; + + Change to the + scripts + directory within the Git repository: + + $ cd scripts + + Set up the local build environment + by running the setup script: + + $ ./setup.sh + + When the script finishes execution, + it prompts you with instructions on how to run + the build.sh script, which + is also in the scripts + directory of + the Git repository created earlier. + + Run the build.sh script + as directed. + Be sure to provide the name of the Git branch + along with the Yocto Project release you are + using. + Here is an example that uses the + &DISTRO_NAME; branch: + + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME; + + After running the script, the file + org.yocto.sdk-<release>-<date>-archive.zip + is in the current directory. + If necessary, start the Eclipse IDE + and be sure you are in the Workbench. + + Select "Install New Software" from the "Help" pull-down menu. + + Click "Add". + Provide anything you want in the + "Name" field. + Click "Archive" and browse to the + ZIP file you built in step eight. + This ZIP file should not be "unzipped", and must + be the *archive.zip file + created by running the + build.sh script. + + Click through the "Okay" buttons. + + Check the boxes + in the installation window and complete + the installation. + Restart the Eclipse IDE if + necessary. + + + + + At this point you should be able to configure the + Eclipse Yocto Plug-in as described in the + "Configuring the Eclipse Yocto Plug-in" + section. +
+
+ +
+ Configuring the Eclipse Yocto Plug-in + + + 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). + + + + To start, you need to do the following from within the + Eclipse IDE: + + Choose "Preferences" from the + "Windows" menu to display the Preferences Dialog. + + Click "Yocto Project ADT". + + + + +
+ Configuring the Cross-Compiler Options + + + 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. + + Selecting the Toolchain Type: + Choose between + Standalone pre-built toolchain + and + Build system derived toolchain + for Cross Compiler Options. + + + Standalone Pre-built Toolchain: + 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. + + Build System Derived Toolchain: + Select this mode if the + cross-toolchain has been installed + and built as part of the + Build Directory. + When you select + Build system derived toolchain, + you are using the toolchain bundled + inside the Build Directory. + + + + Point to the Toolchain: + 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 + &YOCTO_ADTPATH_DIR; + directory. + Sections "Configuring and Running the ADT Installer Script" + and + "Using a Cross-Toolchain Tarball" + in the Yocto Project Application Developer's + Guide describe how to install a stand-alone + cross-toolchain. + If you are using a system-derived + toolchain, the path you provide for the + Toolchain Root Location + field is the + Build Directory. + See the + "Using BitBake and the Build Directory" + section in the Yocto Project Application + Developer's Guide for information on how to + install the toolchain into the Build + Directory. + Specify the Sysroot Location: + 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 is + /opt/poky/&DISTRO;. + Additionally, when you use the ADT Installer + script, the same location is used for the QEMU + user-space tools and the NFS boot process. + + 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. + For information on how to install the + toolchain and on how to extract and install the + sysroot filesystem, see the + "Installing the ADT and Toolchains" + section in the Yocto Project Application + Developer's Guide. + + Select the Target Architecture: + The target architecture is the type of hardware + you are going to use or emulate. + Use the pull-down + Target Architecture 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 + "Building an Image" + section of the Yocto Project Quick Start for + more information. + + +
+ +
+ Configuring the Target Options + + + You can choose to emulate hardware using the QEMU + emulator, or you can choose to run your image on actual + hardware. + + QEMU: + 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. + If you selected + Build system derived toolchain, + the target kernel you built will be located in + the Build Directory in + tmp/deploy/images/machine + directory. + If you selected + Standalone pre-built toolchain, + the pre-built image you downloaded is located + in the directory you specified when you + downloaded the image. + 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 + serial, + nographic, and + kvm must all be outside the + brackets. + Use the man qemu command + to get help on all the options and their use. + The following is an example: + + serial ‘<-m 256 -full-screen>’ + + + Regardless of the mode, Sysroot is already + defined as part of the Cross-Compiler Options + configuration in the + Sysroot Location: field. + + External HW: + Select this option if you will be using actual + hardware. + + + + + Click the "OK" to save your plug-in configurations. + +
+
+
+ +
+ Creating the Project + + + 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 + "Using the Command Line" + in the Yocto Project Application Developer's Guide. + + Do not use special characters in project names + (e.g. spaces, underscores, etc.). Doing so can + cause configuration to fail. + + + + + To create a project based on a Yocto template and then display + the source code, follow these steps: + + Select "Project" from the "File -> New" menu. + + Double click CC++. + + Double click C Project + to create the project. + Expand Yocto Project ADT Project. + + Select Hello World ANSI C Autotools Project. + This is an Autotools-based project based on a Yocto + template. + Put a name in the Project name: + field. + Do not use hyphens as part of the name. + + Click "Next". + Add information in the + Author and + Copyright notice fields. + + Be sure the License + field is correct. + Click "Finish". + If the "open perspective" prompt appears, + click "Yes" so that you in the C/C++ perspective. + + The left-hand navigation pane shows your + project. + You can display your source by double clicking the + project's source file. + + +
+ +
+ Configuring the Cross-Toolchains + + + The earlier section, + "Configuring the Eclipse Yocto Plug-in", + sets up the default project configurations. + You can override these settings for a given project by following + these steps: + + 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. + 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 + "Configuring the Eclipse Yocto Plug-in" section. + The Yocto Project Settings Dialog allows you to override + those default settings for a given project. + + Make your configurations for the project + and click "OK". + If you are running the Juno version of Eclipse, you can + skip down to the next section where you build the + project. + If you are not working with Juno, you need to reconfigure the + project as described in the next step. + + Select "Reconfigure Project" from the + "Project" menu. + This selection reconfigures the project by running + autogen.sh in the workspace for + your project. + The script also runs libtoolize, + aclocal, + autoconf, + autoheader, + automake --a, and + ./configure. + Click on the "Console" tab beneath your source code to + see the results of reconfiguring your project. + + + +
+ +
+ Building the Project + + + To build the project in Juno, right click on the project in + the navigator pane and select "Build Project". + If you are not running Juno, select "Build Project" from the + "Project" menu. + The console should update and you can note the cross-compiler + you are using. + +
+ +
+ Starting QEMU in User-Space NFS Mode + + + To start the QEMU emulator from within Eclipse, follow these + steps: + + See the + "Using the Quick EMUlator (QEMU)" + chapter for more information on using QEMU. + + + Expose and select "External Tools" from + the "Run" menu. + Your image should appear as a selectable menu item. + + Select your image from the menu to launch + the emulator in a new window. + If needed, enter your host root password in + the shell window at the prompt. + This sets up a Tap 0 connection + needed for running in user-space NFS mode. + + Wait for QEMU to launch. + Once QEMU launches, you can begin operating + within that environment. + For example, you could determine the IP Address + for the user-space NFS by using the + ifconfig command. + + +
+ +
+ Deploying and Debugging the Application + + + 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. + + Select "Debug Configurations..." from the + "Run" menu. + In the left area, expand + C/C++Remote Application. + + Locate your project and select it to bring + up a new tabbed view in the Debug Configurations Dialog. + + 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 + /usr/bin/<programname>. + + Click on the "Debugger" tab to see the + cross-tool debugger you are using. + Click on the "Main" tab. + Create a new connection to the QEMU instance + by clicking on "new". + Select TCF, which means + Target Communication Framework. + Click "Next". + Clear out the "host name" field and enter + the IP Address determined earlier. + Click "Finish" to close the + New Connections Dialog. + Use the drop-down menu now in the + "Connection" field and pick the IP Address you entered. + + Click "Run" to bring up a login screen + and login. + Accept the debug perspective. + + + +
+ +
+ Running User-Space Tools + + + 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 "YoctoTools" menu. + + + + 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. + + + + Here are some specifics about the remote tools: + + OProfile: + Selecting this tool causes the + oprofile-server on the remote + target to launch on the local host machine. + The oprofile-viewer must be + installed on the local host machine and the + oprofile-server must be installed + on the remote target, respectively, in order to use. + You must compile and install the + oprofile-viewer 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. + You can locate both the viewer and server from + . + You can also find more information on setting up and + using this tool in the + "oprofile" + section of the Yocto Project Profiling and Tracing + Manual. + The oprofile-server is + installed by default on the + core-image-sato-sdk image. + + Lttng2.0 ust trace import: + Selecting this tool transfers the remote target's + Lttng 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 + and the + "LTTng (Linux Trace Toolkit, next generation)" + section, which is in the Yocto Project Profiling and + Tracing Manual. + Do not use + Lttng-user space (legacy) tool. + This tool no longer has any upstream support. + + Before you use the + Lttng2.0 ust trace import tool, + you need to setup the Lttng Eclipse plug-in and create a + Tracing project. + Do the following: + + Select "Open Perspective" from the + "Window" menu and then select "Tracing". + + Click "OK" to change the Eclipse + perspective into the Tracing perspective. + + Create a new Tracing project by + selecting "Project" from the "File -> New" menu. + + Choose "Tracing Project" from the + "Tracing" menu. + + Generate your tracing data on the + remote target. + Select "Lttng2.0 ust trace import" + from the "Yocto Project Tools" menu to + start the data import process. + Specify your remote connection name. + + For the Ust directory path, specify + the location of your remote tracing data. + Make sure the location ends with + ust (e.g. + /usr/mysession/ust). + + Click "OK" to complete the import + process. + The data is now in the local tracing project + you created. + 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. + Right click the mouse and select + "Open" to bring up the Eclipse Lttng Trace + Viewer so you view the tracing data. + + + PowerTOP: + Selecting this tool runs PowerTOP on the remote target + machine and displays the results in a new view called + PowerTOP. + The "Time to gather data(sec):" field is the time + passed in seconds before data is gathered from the + remote target for analysis. + The "show pids in wakeups list:" field corresponds + to the -p argument passed to + PowerTOP. + LatencyTOP and Perf: + 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 + perf, see the + "perf" + section in the Yocto Project Profiling and Tracing + Manual. + + + +
+ +
+ Customizing an Image Using a BitBake Commander Project and Hob + + + Within the Eclipse IDE, you can create a Yocto BitBake Commander + project, edit the Metadata, and + then use + Hob to build a customized image all within one IDE. + + +
+ Creating the Yocto BitBake Commander Project + + + To create a Yocto BitBake Commander project, follow these + steps: + + Select "Other" from the + "Window -> Open Perspective" menu + and then choose "Bitbake Commander". + + Click "OK" to change the perspective to + Bitbake Commander. + Select "Project" from the "File -> New" + menu to create a new Yocto + Bitbake Commander project. + Choose "New Yocto Project" from the + "Yocto Project Bitbake Commander" menu and click + "Next". + Enter the Project Name and choose the + Project Location. + The Yocto project's Metadata files will be put under + the directory + project_location/project_name. + If that directory does not exist, you need to check + the "Clone from Yocto Git Repository" box, which + would execute a git clone + command to get the project's Metadata files. + + Do not specify your BitBake Commander project + location as your Eclipse workspace. + Doing so causes an error indicating that the + current project overlaps the location of + another project. + This error occurs even if no such project exits. + + Select Finish to + create the project. + + +
+ +
+ Editing the Metadata + + + After you create the Yocto Bitbake Commander project, you + can modify the Metadata + files by opening them in the project. + When editing recipe files (.bb files), + you can view BitBake variable values and information by + hovering the mouse pointer over the variable name and + waiting a few seconds. + + + + To edit the Metadata, follow these steps: + + Select your Yocto Bitbake Commander + project. + Select "BitBake Recipe" from the + "File -> New -> Yocto BitBake Commander" menu + to open a new recipe wizard. + Point to your source by filling in the + "SRC_URL" field. + For example, you can add a recipe to your + Source Directory + by defining "SRC_URL" as follows: + + ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz + + Click "Populate" to calculate the + archive md5, sha256, license checksum values and to + auto-generate the recipe filename. + Fill in the "Description" field. + + Be sure values for all required + fields exist. + Click "Finish". + + +
+ +
+ Building and Customizing the Image Using Hob + + + To build and customize the image using Hob from within the + Eclipse IDE, follow these steps: + + Select your Yocto Bitbake Commander + project. + Select "Launch Hob" from the "Project" + menu. + Enter the + Build Directory + where you want to put your final images. + + Click "OK" to launch Hob. + + Use Hob to customize and build your own + images. + For information on Hob, see the + Hob Project Page + on the Yocto Project website. + + +
+
+
+ +
+ Workflow Using Stand-Alone Cross-Development Toolchains + + + If you want to develop an application without prior installation + of the ADT, you still can employ the + Cross Development Toolchain, + the QEMU emulator, and a number of supported target image files. + You just need to follow these general steps: + + Install the cross-development + toolchain for your target hardware: + For information on how to install the toolchain, see the + "Using a Cross-Toolchain Tarball" + section in the Yocto Project Application Developer's + Guide. + Download the Target Image: + The Yocto Project supports several target architectures + and has many pre-built kernel images and root filesystem + images. + If you are going to develop your application on + hardware, go to the + machines + 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 + .hddimg 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. + If you are going to develop your application and + then run and test it using the QEMU emulator, go to the + machines/qemu + download area. + From this area, go down into the directory for your + target architecture (e.g. qemux86_64 + for an Intel-based + 64-bit architecture). + Download kernel, root filesystem, and any other files you + need for your process. + In order to use the root filesystem in QEMU, you + need to extract it. + See the + "Extracting the Root Filesystem" + section for information on how to extract the root + filesystem. + Develop and Test your + Application: 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 + QEMU Home Page + to download and learn about the emulator. + You can see the + "Using the Quick EMUlator (QEMU)" + chapter for information on using QEMU within the Yocto + Project. + + +
+
+ +
+ Modifying Temporary Source Code + + + You might + find it helpful during development to modify the temporary source code used by recipes + to build packages. + For example, suppose you are developing a patch and you need to experiment a bit + to figure out your solution. + After you have initially built the package, you can iteratively tweak the + source code, which is located in the + Build Directory, and then + you can force a re-compile and quickly test your altered code. + Once you settle on a solution, you can then preserve your changes in the form of + patches. + You can accomplish these steps all within either a + Quilt or + Git workflow. + + +
+ Finding the Temporary Source Code + + + During a build, the unpacked temporary source code used by recipes + to build packages is available in the Build Directory as + defined by the + S variable. + Below is the default value for the S variable as defined in the + meta/conf/bitbake.conf configuration file in the + Source Directory: + + S = "${WORKDIR}/${BP}" + + You should be aware that many recipes override the S variable. + For example, recipes that fetch their source from Git usually set + S to ${WORKDIR}/git. + + The + BP + represents the base recipe name, which consists of the name and version: + + BP = "${BPN}-${PV}" + + + + + + The path to the work directory for the recipe + (WORKDIR) + is defined as follows: + + ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + + The actual directory depends on several things: + + TMPDIR: + The top-level build output directory + MULTIMACH_TARGET_SYS: + The target system identifier + PN: + The recipe name + EXTENDPE: + The epoch - (if + PE + is not specified, which is usually the case for most + recipes, then EXTENDPE is blank) + PV: + The recipe version + PR: + The recipe revision + + + + + As an example, assume a Source Directory top-level folder + name poky, a default Build Directory at + poky/build, and a + qemux86-poky-linux machine target + system. + Furthermore, suppose your recipe is named + foo_1.3.0.bb. + In this case, the work directory the build system uses to + build the package would be as follows: + + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + + + + + Now that you know where to locate the directory that has the temporary source code, + you can use a Quilt or Git workflow to make your edits, test the changes, + and preserve the changes in the form of patches. + +
+ +
+ Using a Quilt Workflow + + + Quilt + is a powerful tool that allows you to capture source code changes without having + a clean source tree. + This section outlines the typical workflow you can use to modify temporary source code, + test changes, and then preserve the changes in the form of a patch all using Quilt. + + + + Follow these general steps: + + Find the Source Code: + The temporary source code used by the OpenEmbedded build system is kept in the + Build Directory. + See the + "Finding the Temporary Source Code" + section to learn how to locate the directory that has the temporary source code for a + particular package. + Change Your Working Directory: + You need to be in the directory that has the temporary source code. + That directory is defined by the + S + variable. + Create a New Patch: + Before modifying source code, you need to create a new patch. + To create a new patch file, use quilt new as below: + + $ quilt new my_changes.patch + + Notify Quilt and Add Files: + After creating the patch, you need to notify Quilt about the files + you plan to edit. + You notify Quilt by adding the files to the patch you just created: + + $ quilt add file1.c file2.c file3.c + + + Edit the Files: + Make your changes in the temporary source code to the files you added + to the patch. + Test Your Changes: + Once you have modified the source code, the easiest way to + your changes is by calling the + do_compile task as shown in the + following example: + + $ bitbake -c compile -f name_of_package + + The -f or --force + option forces the specified task to execute. + If you find problems with your code, you can just keep editing and + re-testing iteratively until things work as expected. + All the modifications you make to the temporary source code + disappear once you run the + do_clean + or + do_cleanall + tasks using BitBake (i.e. + bitbake -c clean name_of_package + and + bitbake -c cleanall name_of_package). + Modifications will also disappear if you use the rm_work + feature as described in the + "Building an Image" + section of the Yocto Project Quick Start. + + Generate the Patch: + Once your changes work as expected, you need to use Quilt to generate the final patch that + contains all your modifications. + + $ quilt refresh + + At this point, the my_changes.patch file has all your edits made + to the file1.c, file2.c, and + file3.c files. + You can find the resulting patch file in the patches/ + subdirectory of the source (S) directory. + Copy the Patch File: + For simplicity, copy the patch file into a directory named files, + which you can create in the same directory that holds the recipe + (.bb) file or the + append (.bbappend) file. + Placing the patch here guarantees that the OpenEmbedded build system will find + the patch. + Next, add the patch into the + SRC_URI + of the recipe. + Here is an example: + + SRC_URI += "file://my_changes.patch" + + Increment the Recipe Revision Number: + Finally, don't forget to 'bump' the + PR + value in the recipe since the resulting packages have changed. + +
+ +
+ Using a Git Workflow + + Git is an even more powerful tool that allows you to capture source code changes without having + a clean source tree. + This section outlines the typical workflow you can use to modify temporary source code, + test changes, and then preserve the changes in the form of a patch all using Git. + For general information on Git as it is used in the Yocto Project, see the + "Git" section. + + + + This workflow uses Git only for its ability to manage local changes to the source code + and produce patches independent of any version control system used with the Yocto Project. + + + + Follow these general steps: + + Find the Source Code: + The temporary source code used by the OpenEmbedded build system is kept in the + Build Directory. + See the + "Finding the Temporary Source Code" + section to learn how to locate the directory that has the temporary source code for a + particular package. + Change Your Working Directory: + You need to be in the directory that has the temporary source code. + That directory is defined by the + S + variable. + If needed, initialize a Git Repository: + If the recipe you are working with does not use a Git fetcher, + you need to set up a Git repository as follows: + + $ git init + $ git add * + $ git commit -m "initial revision" + + The above Git commands initialize a Git repository that is based on the + files in your current working directory, stage all the files, and commit + the files. + At this point, your Git repository is aware of all the source code files. + Any edits you now make to files can be committed later and will be tracked by + Git. + Edit the Files: + Make your changes to the temporary source code. + Test Your Changes: + Once you have modified the source code, the easiest way + to test your changes is by calling the + do_compile task as shown in the + following example: + + $ bitbake -c compile -f name_of_package + + The -f or --force + option forces the specified task to execute. + If you find problems with your code, you can just keep editing and + re-testing iteratively until things work as expected. + All the modifications you make to the temporary source code + disappear once you -c clean, -c cleansstate, + or -c cleanall with BitBake for the package. + Modifications will also disappear if you use the rm_work + feature as described in the + "Building an Image" + section of the Yocto Project Quick Start. + + See the List of Files You Changed: + Use the git status command to see what files you have actually edited. + The ability to have Git track the files you have changed is an advantage that this + workflow has over the Quilt workflow. + Here is the Git command to list your changed files: + + $ git status + + Stage the Modified Files: + Use the git add command to stage the changed files so they + can be committed as follows: + + $ git add file1.c file2.c file3.c + + Commit the Staged Files and View Your Changes: + Use the git commit command to commit the changes to the + local repository. + Once you have committed the files, you can use the git log + command to see your changes: + + $ git commit -m "commit-summary-message" + $ git log + + The name of the patch file created in the next step is based on your + commit-summary-message. + Generate the Patch: + Once the changes are committed, use the git format-patch + command to generate a patch file: + + $ git format-patch -1 + + Specifying "-1" causes Git to generate the + patch file for the most recent commit. + At this point, the patch file has all your edits made + to the file1.c, file2.c, and + file3.c files. + You can find the resulting patch file in the current directory and it + is named according to the git commit summary line. + The patch file ends with .patch. + Copy the Patch File: + For simplicity, copy the patch file into a directory named files, + which you can create in the same directory that holds the recipe + (.bb) file or the + append (.bbappend) file. + Placing the patch here guarantees that the OpenEmbedded build system will find + the patch. + Next, add the patch into the + SRC_URI + of the recipe. + Here is an example: + + SRC_URI += "file://0001-commit-summary-message.patch" + + Increment the Recipe Revision Number: + Finally, don't forget to 'bump' the + PR + value in the recipe since the resulting packages have changed. + + +
+
+ +
+ Image Development Using Hob + + + The Hob 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. + + + + For a better understanding of Hob, see the project page at + + 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: + + You can setup and run Hob using these commands: + + $ source oe-init-build-env + $ hob + + You can set the + MACHINE + for which you are building the image. + 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. + + You can manage + layers. + You can select a base image and then add extra packages for your custom build. + + You can launch and monitor the build from within Hob. + + +
+ +
+ Using a Development Shell + + + When debugging certain commands or even when just editing packages, + devshell can be a useful tool. + When you invoke devshell, 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. + In the new terminal, all the OpenEmbedded build-related environment variables are + still defined so you can use commands such as configure and + make. + The commands execute just as if the OpenEmbedded build system were executing them. + Consequently, working this way can be helpful when debugging a build or preparing + software to be used with the OpenEmbedded build system. + + + + Following is an example that uses devshell on a target named + matchbox-desktop: + + $ bitbake matchbox-desktop -c devshell + + + + + This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. + The OE_TERMINAL + variable controls what type of shell is opened. + + + + For spawned terminals, the following occurs: + + The PATH variable includes the + cross-toolchain. + The pkgconfig variables find the correct + .pc files. + The configure command finds the + Yocto Project site files as well as any other necessary files. + + + + + Within this environment, you can run configure or compile + commands as if they were being run by + the OpenEmbedded build system itself. + As noted earlier, the working directory also automatically changes to the + Source Directory (S). + + + + When you are finished, you just exit the shell or close the terminal window. + + + + + It is worth remembering that when using devshell + you need to use the full compiler name such as arm-poky-linux-gnueabi-gcc + instead of just using gcc. + The same applies to other applications such as binutils, + libtool and so forth. + BitBake sets up environment variables such as CC + to assist applications, such as make to find the correct tools. + + + + It is also worth noting that devshell still works over + X11 forwarding and similar situations. + + +
+ +
+ diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml new file mode 100644 index 0000000000..2385187f4d --- /dev/null +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -0,0 +1,1692 @@ + %poky; ] > + + + +The Yocto Project Open Source Development Environment + + + This chapter helps you understand the Yocto Project as an open source development project. + In general, working in an open source environment is very different from working in a + closed, proprietary environment. + Additionally, the Yocto Project uses specific tools and constructs as part of its development + environment. + This chapter specifically addresses open source philosophy, using the + Yocto Project in a team environment, source repositories, Yocto Project + terms, licensing, the open source distributed version control system Git, + workflows, bug tracking, and how to submit changes. + + +
+ Open Source Philosophy + + + Open source philosophy is characterized by software development directed by peer production + and collaboration through an active community of developers. + Contrast this to the more standard centralized development models used by commercial software + companies where a finite set of developers produces a product for sale using a defined set + of procedures that ultimately result in an end product whose architecture and source material + are closed to the public. + + + + Open source projects conceptually have differing concurrent agendas, approaches, and production. + These facets of the development process can come from anyone in the public (community) that has a + stake in the software project. + The open source environment contains new copyright, licensing, domain, and consumer issues + that differ from the more traditional development environment. + In an open source environment, the end product, source material, and documentation are + all available to the public at no cost. + + + + A benchmark example of an open source project is the Linux kernel, which was initially conceived + and created by Finnish computer science student Linus Torvalds in 1991. + Conversely, a good example of a non-open source project is the + Windows family of operating + systems developed by Microsoft Corporation. + + + + Wikipedia has a good historical description of the Open Source Philosophy + here. + You can also find helpful information on how to participate in the Linux Community + here. + +
+ +
+ Using the Yocto Project in a Team Environment + + + It might not be immediately clear how you can use the Yocto + Project in a team environment, or scale it for a large team of + developers. + One of the strengths of the Yocto Project is that it is extremely + flexible. + Thus, you can adapt it to many different use cases and scenarios. + However, these characteristics can cause a struggle if you are trying + to create a working setup that scales across a large team. + + + + To help with these types of situations, this section presents + some of the project's most successful experiences, + practices, solutions, and available technologies that work well. + Keep in mind, the information here is a starting point. + You can build off it and customize it to fit any + particular working environment and set of practices. + + +
+ System Configurations + + + Systems across a large team should meet the needs of + two types of developers: those working on the contents of the + operating system image itself and those developing applications. + Regardless of the type of developer, their workstations must + be both reasonably powerful and run Linux. + + +
+ Application Development + + + For developers who mainly do application level work + on top of an existing software stack, + here are some practices that work best: + + Use a pre-built toolchain that + contains the software stack itself. + Then, develop the application code on top of the + stack. + This method works well for small numbers of relatively + isolated applications. + When possible, use the Yocto Project + plug-in for the Eclipse IDE + and other pieces of Application Development + Technology (ADT). + For more information, see the + "Application + Development Workflow" section as well as the + Yocto Project Application Developer's Guide. + + Keep your cross-development toolchains + updated. + You can do this through provisioning either as new + toolchain downloads or as updates through a package + update mechanism using opkg + to provide updates to an existing toolchain. + The exact mechanics of how and when to do this are a + question for local policy. + Use multiple toolchains installed locally + into different locations to allow development across + versions. + + +
+ +
+ Core System Development + + + For core system development, it is often best to have the + build system itself available on the developer workstations + so developers can run their own builds and directly + rebuild the software stack. + You should keep the core system unchanged as much as + possible and do your work in layers on top of the core system. + Doing so gives you a greater level of portability when + upgrading to new versions of the core system or Board + Support Packages (BSPs). + You can share layers amongst the developers of a particular + project and contain the policy configuration that defines + the project. + + + + Aside from the previous best practices, there exists a number + of tips and tricks that can help speed up core development + projects: + + Use a + Shared State Cache + (sstate) among groups of developers who are on a + fast network. + The best way to share sstate is through a + Network File System (NFS) share. + The first user to build a given component for the + first time contributes that object to the sstate, + while subsequent builds from other developers then + reuse the object rather than rebuild it themselves. + + Although it is possible to use other protocols for the + sstate such as HTTP and FTP, you should avoid these. + Using HTTP limits the sstate to read-only and + FTP provides poor performance. + + Have autobuilders contribute to the sstate + pool similarly to how the developer workstations + contribute. + For information, see the + "Autobuilders" + section. + Build stand-alone tarballs that contain + "missing" system requirements if for some reason + developer workstations do not meet minimum system + requirements such as latest Python versions, + chrpath, or other tools. + You can install and relocate the tarball exactly as you + would the usual cross-development toolchain so that + all developers can meet minimum version requirements + on most distributions. + Use a small number of shared, + high performance systems for testing purposes + (e.g. dual, six-core Xeons with 24 Gbytes of RAM + and plenty of disk space). + Developers can use these systems for wider, more + extensive testing while they continue to develop + locally using their primary development system. + + Enable the PR Service when package feeds + need to be incremental with continually increasing + PR + values. + Typically, this situation occurs when you use or + publish package feeds and use a shared state. + You should enable the PR Service for all users who + use the shared state pool. + For more information on the PR Service, see the + "Working With a PR Service". + + + +
+
+ +
+ Source Control Management (SCM) + + + Keeping your + Metadata + and any software you are developing under the + control of an SCM system that is compatible + with the OpenEmbedded build system is advisable. + Of the SCMs BitBake supports, the + Yocto Project team strongly recommends using + Git. + Git is a distributed system that is easy to backup, + allows you to work remotely, and then connects back to the + infrastructure. + + For information about BitBake, see the + BitBake User Manual. + + + + + It is relatively easy to set up Git services and create + infrastructure like + http://git.yoctoproject.org, + which is based on server software called + gitolite with cgit + being used to generate the web interface that lets you view the + repositories. + The gitolite software identifies users + using SSH keys and allows branch-based + access controls to repositories that you can control as little + or as much as necessary. + + + + The setup of these services is beyond the scope of this manual. + However, sites such as these exist that describe how to perform + setup: + + Git documentation: + Describes how to install gitolite + on the server. + The gitolite master index: + All topics for gitolite. + + Interfaces, frontends, and tools: + Documentation on how to create interfaces and frontends + for Git. + + +
+ +
+ Autobuilders + + + Autobuilders are often the core of a development project. + It is here that changes from individual developers are brought + together and centrally tested and subsequent decisions about + releases can be made. + Autobuilders also allow for "continuous integration" style + testing of software components and regression identification + and tracking. + + + + See "Yocto Project Autobuilder" + for more information and links to buildbot. + The Yocto Project team has found this implementation + works well in this role. + A public example of this is the Yocto Project + Autobuilders, which we use to test the overall health of the + project. + + + + The features of this system are: + + Highlights when commits break the build. + + Populates an sstate cache from which + developers can pull rather than requiring local + builds. + Allows commit hook triggers, + which trigger builds when commits are made. + + Allows triggering of automated image booting + and testing under the QuickEMUlator (QEMU). + + Supports incremental build testing and + from-scratch builds. + Shares output that allows developer + testing and historical regression investigation. + + Creates output that can be used for releases. + + Allows scheduling of builds so that resources + can be used efficiently. + + +
+ +
+ Policies and Change Flow + + + The Yocto Project itself uses a hierarchical structure and a + pull model. + Scripts exist to create and send pull requests + (i.e. create-pull-request and + send-pull-request). + This model is in line with other open source projects where + maintainers are responsible for specific areas of the project + and a single maintainer handles the final "top-of-tree" merges. + + + + You can also use a more collective push model. + The gitolite software supports both the + push and pull models quite easily. + + + + As with any development environment, it is important + to document the policy used as well as any main project + guidelines so they are understood by everyone. + It is also a good idea to have well structured + commit messages, which are usually a part of a project's + guidelines. + Good commit messages are essential when looking back in time and + trying to understand why changes were made. + + + + If you discover that changes are needed to the core layer of the + project, it is worth sharing those with the community as soon + as possible. + Chances are if you have discovered the need for changes, someone + else in the community needs them also. + +
+ +
+ Summary + + + This section summarizes the key recommendations described in the + previous sections: + + Use Git + as the source control system. + Maintain your Metadata in layers that make sense + for your situation. + See the "Understanding + and Creating Layers" section for more information on + layers. + + Separate the project's Metadata and code by using + separate Git repositories. + See the + "Yocto Project Source Repositories" + section for information on these repositories. + See the + "Getting Set Up" + section for information on how to set up local Git + repositories for related upstream Yocto Project + Git repositories. + + Set up the directory for the shared state cache + (SSTATE_DIR) + where it makes sense. + For example, set up the sstate cache on a system used + by developers in the same organization and share the + same source directories on their machines. + + Set up an Autobuilder and have it populate the + sstate cache and source directories. + The Yocto Project community encourages you + to send patches to the project to fix bugs or add features. + If you do submit patches, follow the project commit + guidelines for writing good commit messages. + See the "How to Submit a Change" + section. + Send changes to the core sooner than later + as others are likely to run into the same issues. + For some guidance on mailing lists to use, see the list in the + "How to Submit a Change" + section. + For a description of the available mailing lists, see the + "Mailing Lists" + section in the Yocto Project Reference Manual. + + + +
+
+ +
+ Yocto Project Source Repositories + + + The Yocto Project team maintains complete source repositories for all + Yocto Project files at + . + This web-based source code browser is organized into categories by + function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and + so forth. + From the interface, you can click on any particular item in the "Name" + column and see the URL at the bottom of the page that you need to clone + a Git repository for that particular item. + Having a local Git repository of the + Source Directory, which is + usually named "poky", allows + you to make changes, contribute to the history, and ultimately enhance + the Yocto Project's tools, Board Support Packages, and so forth. + + + + For any supported release of Yocto Project, you can also go to the + Yocto Project Website and + select the "Downloads" tab and get a released tarball of the + poky repository or any supported BSP tarballs. + Unpacking these tarballs gives you a snapshot of the released + files. + Notes + + + The recommended method for setting up the Yocto Project + Source Directory + and the files for supported BSPs + (e.g., meta-intel) is to use + Git to create a local copy of + the upstream repositories. + + + Be sure to always work in matching branches for both + the selected BSP repository and the + Source Directory + (i.e. poky) repository. + For example, if you have checked out the "master" branch + of poky and you are going to use + meta-intel, be sure to checkout the + "master" branch of meta-intel. + + + + + + + In summary, here is where you can get the project files needed for development: + + Source Repositories: + This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto + Metadata Layers. + You can create local copies of Git repositories for each of these areas. + + + + Index of /releases: + This is an index of releases such as + the Eclipse + Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers for cross-development toolchains, + and all released versions of Yocto Project in the form of images or tarballs. + Downloading and extracting these files does not produce a local copy of the + Git repository but rather a snapshot of a particular release or image. + + + + "Downloads" page for the + Yocto Project Website: + Access this page by going to the website and then selecting + the "Downloads" tab. + This page allows you to download any Yocto Project + release or Board Support Package (BSP) in tarball form. + The tarballs are similar to those found in the + Index of /releases: area. + + + + + +
+ +
+ Yocto Project Terms + + + Following is a list of terms and definitions users new to the Yocto Project development + environment might find helpful. + While some of these terms are universal, the list includes them just in case: + + Append Files: Files that append build information to + a recipe file. + Append files are known as BitBake append files and .bbappend files. + The OpenEmbedded build system expects every append file to have a corresponding + recipe (.bb) file. + Furthermore, the append file and corresponding recipe file + must use the same root filename. + The filenames can differ only in the file type suffix used (e.g. + formfactor_0.0.bb and formfactor_0.0.bbappend). + + Information in append files extends or overrides the + information in the similarly-named recipe file. + For an example of an append file in use, see the + "Using .bbappend Files" section. + + Append files can also use wildcard patterns in their version numbers + so they can be applied to more than one version of the underlying recipe file. + + + BitBake: + The task executor and scheduler used by the OpenEmbedded build + system to build images. + For more information on BitBake, see the + BitBake User Manual. + + + Build Directory: + This term refers to the area used by the OpenEmbedded build + system for builds. + The area is created when you source the + setup environment script that is found in the Source Directory + (i.e. &OE_INIT_FILE; + or + oe-init-build-env-memres). + The TOPDIR + variable points to the Build Directory. + + + You have a lot of flexibility when creating the Build + Directory. + Following are some examples that show how to create the + directory. + The examples assume your + Source Directory is + named poky: + + Create the Build Directory inside your + Source Directory and let the name of the Build + Directory default to build: + + $ cd $HOME/poky + $ source &OE_INIT_FILE; + + Create the Build Directory inside your + home directory and specifically name it + test-builds: + + $ cd $HOME + $ source poky/&OE_INIT_FILE; test-builds + + + Provide a directory path and + specifically name the Build Directory. + Any intermediate folders in the pathname must + exist. + This next example creates a Build Directory named + YP-&POKYVERSION; + in your home directory within the existing + directory mybuilds: + + $cd $HOME + $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; + + + + By default, the Build Directory contains + TMPDIR, + which is a temporary directory the build system uses for + its work. + TMPDIR cannot be under NFS. + Thus, by default, the Build Directory cannot be under NFS. + However, if you need the Build Directory to be under NFS, + you can set this up by setting TMPDIR + in your local.conf file + to use a local drive. + Doing so effectively separates TMPDIR + from TOPDIR, which is the Build + Directory. + + + Build System: + In the context of the Yocto Project, + this term refers to the OpenEmbedded build system used by the project. + This build system is based on the project known as "Poky." + For some historical information about Poky, see the + Poky term. + + Classes: Files that provide for logic encapsulation + and inheritance so that commonly used patterns can be defined once and then easily used + in multiple recipes. + For reference information on the Yocto Project classes, see the + "Classes" chapter of the + Yocto Project Reference Manual. + Class files end with the .bbclass filename extension. + + Configuration File: + Configuration information in various .conf + files provides global definitions of variables. + The conf/local.conf configuration file in + the + Build Directory + contains user-defined variables that affect every build. + The meta-yocto/conf/distro/poky.conf + configuration file defines Yocto "distro" configuration + variables used only when building with this policy. + Machine configuration files, which + are located throughout the + Source Directory, define + variables for specific hardware and are only used when building + for that target (e.g. the + machine/beaglebone.conf configuration + file defines variables for the Texas Instruments ARM Cortex-A8 + development board). + Configuration files end with a .conf + filename extension. + + + Cross-Development Toolchain: + In general, a cross-development toolchain is a collection of + software development tools and utilities that run on one + architecture and allow you to develop software for a + different, or targeted, architecture. + These toolchains contain cross-compilers, linkers, and + debuggers that are specific to the target architecture. + + + The Yocto Project supports two different cross-development + toolchains: + + A toolchain only used by and within + BitBake when building an image for a target + architecture. + 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. + + + + + + Creation of these toolchains is simple and automated. + For information on toolchain concepts as they apply to the + Yocto Project, see the + "Cross-Development Toolchain Generation" + section in the Yocto Project Reference Manual. + You can also find more information on using the + relocatable toolchain in the + Yocto Project + Application Developer's Guide. + + Image: + An image is an artifact of the BitBake build process given + a collection of recipes and related Metadata. + Images are the binary output that run on specific hardware or + QEMU and are used for specific use-cases. + For a list of the supported image types that the Yocto Project provides, see the + "Images" + chapter in the Yocto Project Reference Manual. + Layer: A collection of recipes representing the core, + a BSP, or an application stack. + For a discussion specifically on BSP Layers, see the + "BSP Layers" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide. + Meta-Toolchain: + A term sometimes used for + Cross-Development Toolchain. + + Metadata: + The files that BitBake parses when building an image. + In general, Metadata includes recipes, classes, and + configuration files. + In the context of the kernel ("kernel Metadata"), + it refers to Metadata in the meta + branches of the kernel source Git repositories. + + OE-Core: A core set of Metadata originating + with OpenEmbedded (OE) that is shared between OE and the Yocto Project. + This Metadata is found in the meta directory of the + Source Directory. + Package: + In the context of the Yocto Project, this term refers to a + recipe's packaged output produced by BitBake (i.e. a + "baked recipe"). + A package is generally the compiled binaries produced from the + recipe's sources. + You "bake" something by running it through BitBake. + It is worth noting that the term "package" can, in general, have subtle + meanings. For example, the packages referred to in the + "The Packages" section are + compiled binaries that, when installed, add functionality to your Linux + distribution. + Another point worth noting is that historically within the Yocto Project, + recipes were referred to as packages - thus, the existence of several BitBake + variables that are seemingly mis-named, + (e.g. PR, + PV, and + PE). + + Package Groups: + Arbitrary groups of software Recipes. + You use package groups to hold recipes that, when built, + usually accomplish a single task. + For example, a package group could contain the recipes for a + company’s proprietary or value-add software. + Or, the package group could contain the recipes that enable + graphics. + A package group is really just another recipe. + Because package group files are recipes, they end with the + .bb filename extension. + Poky: The term "poky" can mean several things. + In its most general sense, it is an open-source project that was initially developed + by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded + build system becoming a build system for embedded images. + After Intel Corporation acquired OpenedHand, the project poky became the basis for + the Yocto Project's build system. + + Within the Yocto Project source repositories, poky + exists as a separate Git repository + that can be cloned to yield a local copy on the host system. + Thus, "poky" can refer to the local copy of the Source Directory used to develop within + the Yocto Project. + Recipe: + A set of instructions for building packages. + A recipe describes where you get source code, which patches + to apply, how to configure the source, how to compile it and so on. + Recipes also describe dependencies for libraries or for other + recipes. + Recipes represent the logical unit of execution, the software + to build, the images to build, and use the + .bb file extension. + + + Source Directory: + This term refers to the directory structure created as a result + of creating a local copy of the poky Git + repository git://git.yoctoproject.org/poky + or expanding a released poky tarball. + + Creating a local copy of the poky + Git repository is the recommended method for setting up + your Source Directory. + + Sometimes you might hear the term "poky directory" used to refer + to this directory structure. + + The OpenEmbedded build system does not support file or + directory names that contain spaces. + Be sure that the Source Directory you use does not contain + these types of names. + + + The Source Directory contains BitBake, Documentation, + Metadata and other files that all support the Yocto Project. + Consequently, you must have the Source Directory in place on + your development system in order to do any development using + the Yocto Project. + + When you create a local copy of the Git repository, you + can name the repository anything you like. + Throughout much of the documentation, "poky" + is used as the name of the top-level folder of the local copy of + the poky Git repository. + So, for example, cloning the poky Git + repository results in a local Git repository whose top-level + folder is also named "poky". + + While it is not recommended that you use tarball expansion + to set up the Source Directory, if you do, the top-level + directory name of the Source Directory is derived from the + Yocto Project release tarball. + For example, downloading and unpacking + &YOCTO_POKY_TARBALL; results in a + Source Directory whose root folder is named + &YOCTO_POKY;. + + It is important to understand the differences between the + Source Directory created by unpacking a released tarball as + compared to cloning + git://git.yoctoproject.org/poky. + When you unpack a tarball, you have an exact copy of the files + based on the time of release - a fixed release point. + Any changes you make to your local files in the Source Directory + are on top of the release and will remain local only. + On the other hand, when you clone the poky + Git repository, you have an active development repository with + access to the upstream repository's branches and tags. + In this case, any local changes you make to the local + Source Directory can be later applied to active development + branches of the upstream poky Git + repository. + + For more information on concepts related to Git + repositories, branches, and tags, see the + "Repositories, Tags, and Branches" + section. + Task: + A unit of execution for BitBake (e.g. + do_compile, + do_fetch, + do_patch, + and so forth). + + Upstream: A reference to source code or repositories + that are not local to the development system but located in a master area that is controlled + by the maintainer of the source code. + For example, in order for a developer to work on a particular piece of code, they need to + first get a copy of it from an "upstream" source. + + +
+ +
+ Licensing + + + Because open source projects are open to the public, they have different licensing structures in place. + License evolution for both Open Source and Free Software has an interesting history. + If you are interested in this history, you can find basic information here: + + Open source license history + + Free software license + history + + + + + In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology + (MIT) License. + MIT licensing permits the reuse of software within proprietary software as long as the + license is distributed with that software. + MIT is also compatible with the GNU General Public License (GPL). + Patches to the Yocto Project follow the upstream licensing scheme. + You can find information on the MIT license + here. + You can find information on the GNU GPL + here. + + + + When you build an image using the Yocto Project, the build process uses a + known list of licenses to ensure compliance. + You can find this list in the + Source Directory at + meta/files/common-licenses. + Once the build completes, the list of all licenses found and used during that build are + kept in the + Build Directory at + tmp/deploy/licenses. + + + + If a module requires a license that is not in the base list, the build process + generates a warning during the build. + These tools make it easier for a developer to be certain of the licenses with which + their shipped products must comply. + However, even with these tools it is still up to the developer to resolve potential licensing issues. + + + + The base list of licenses used by the build process is a combination of the Software Package + Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects. + SPDX Group is a working group of the Linux Foundation + that maintains a specification + for a standard format for communicating the components, licenses, and copyrights + associated with a software package. + OSI is a corporation dedicated to the Open Source + Definition and the effort for reviewing and approving licenses that + conform to the Open Source Definition (OSD). + + + + You can find a list of the combined SPDX and OSI licenses that the + Yocto Project uses in the + meta/files/common-licenses directory in your + Source Directory. + + + + For information that can help you maintain compliance with various + open source licensing during the lifecycle of a product created using + the Yocto Project, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" + section. + +
+ +
+ Git + + + The Yocto Project makes extensive use of Git, + which is a free, open source distributed version control system. + Git supports distributed development, non-linear development, and can handle large projects. + It is best that you have some fundamental understanding of how Git tracks projects and + how to work with Git if you are going to use the Yocto Project for development. + This section provides a quick overview of how Git works and provides you with a summary + of some essential Git commands. + + + + For more information on Git, see + . + If you need to download Git, go to . + + +
+ Repositories, Tags, and Branches + + + As mentioned earlier in the section + "Yocto Project Source Repositories", + the Yocto Project maintains source repositories at + . + If you look at this web-interface of the repositories, each item is a separate + Git repository. + + + + Git repositories use branching techniques that track content change (not files) + within a project (e.g. a new feature or updated documentation). + Creating a tree-like structure based on project divergence allows for excellent historical + information over the life of a project. + This methodology also allows for an environment from which you can do lots of + local experimentation on projects as you develop changes or new features. + + + + A Git repository represents all development efforts for a given project. + For example, the Git repository poky contains all changes + and developments for Poky over the course of its entire life. + That means that all changes that make up all releases are captured. + The repository maintains a complete history of changes. + + + + You can create a local copy of any repository by "cloning" it with the Git + clone command. + When you clone a Git repository, you end up with an identical copy of the + repository on your development system. + Once you have a local copy of a repository, you can take steps to develop locally. + For examples on how to clone Git repositories, see the + "Getting Set Up" section. + + + + It is important to understand that Git tracks content change and + not files. + Git uses "branches" to organize different development efforts. + For example, the poky repository has + denzil, danny, + dylan, dora, + daisy, and master branches + among others. + You can see all the branches by going to + and + clicking on the + [...] + link beneath the "Branch" heading. + + + + Each of these branches represents a specific area of development. + The master branch represents the current or most recent + development. + All other branches represent offshoots of the master + branch. + + + + When you create a local copy of a Git repository, the copy has the same set + of branches as the original. + This means you can use Git to create a local working area (also called a branch) + that tracks a specific development branch from the source Git repository. + in other words, you can define your local Git environment to work on any development + branch in the repository. + To help illustrate, here is a set of commands that creates a local copy of the + poky Git repository and then creates and checks out a local + Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; + + In this example, the name of the top-level directory of your local + Source Directory + is "poky" and the name of that local working area (local branch) + you just created and checked out is "&DISTRO_NAME;". + The files in your local repository now reflect the same files that + are in the "&DISTRO_NAME;" 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, + your local environment matches the "tip" of that development branch + 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 + cloning and checking out the "master" branch. + Keep reading to see how you create a local snapshot of a Yocto + Project Release. + + + + Git uses "tags" to mark specific changes in a repository. + Typically, a tag is used to mark a special point such as the final + change before a project is released. + You can see the tags used with the poky Git + repository by going to + and + clicking on the + [...] + link beneath the "Tag" heading. + + + + Some key tags are dylan-9.0.0, + dora-10.0.0, daisy-11.0.0, + and &DISTRO_NAME;-&POKYVERSION;. + These tags represent Yocto Project releases. + + + + When you create a local copy of the Git repository, you also have access to all the + tags. + Similar to branches, you can create and checkout a local working Git branch based + on a tag name. + When you do this, you get a snapshot of the Git repository that reflects + the state of the files when the change was made associated with that tag. + The most common use is to checkout a working branch that matches a specific + Yocto Project release. + Here is an example: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION; + + In this example, the name of the top-level directory of your local Yocto Project + Files Git repository is poky. + And, the name of the local branch you have created and checked out is + my-&DISTRO_NAME;-&POKYVERSION;. + The files in your repository now exactly match the Yocto Project &DISTRO; + Release tag (&DISTRO_NAME;-&POKYVERSION;). + 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. + +
+ +
+ Basic Commands + + + Git has an extensive set of commands that lets you manage changes and perform + collaboration over the life of a project. + Conveniently though, you can manage with a small set of basic operations and workflows + once you understand the basic philosophy behind Git. + You do not have to be an expert in Git to be functional. + A good place to look for instruction on a minimal set of Git commands is + here. + If you need to download Git, you can do so + here. + + + + If you do not know much about Git, you should educate + yourself by visiting the links previously mentioned. + + + + The following list briefly describes some basic Git operations as a way to get started. + As with any set of commands, this list (in most cases) simply shows the base command and + omits the many arguments they support. + See the Git documentation for complete descriptions and strategies on how to use these commands: + + git init: Initializes an empty Git repository. + You cannot use Git commands unless you have a .git repository. + git clone: + Creates a local clone of a Git repository. + During collaboration, this command allows you to create a + local Git repository that is on equal footing with a fellow + developer’s Git repository. + + git add: Stages updated file contents + to the index that + Git uses to track changes. + You must stage all files that have changed before you can commit them. + git commit: Creates a "commit" that documents + the changes you made. + Commits are used for historical purposes, for determining if a maintainer of a project + will allow the change, and for ultimately pushing the change from your local Git repository + into the project’s upstream (or master) repository. + git status: Reports any modified files that + possibly need to be staged and committed. + git checkout <branch-name>: Changes + your working branch. + This command is analogous to "cd". + git checkout –b <working-branch>: 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. + git branch: Reports + existing local branches and + tells you the branch in which you are currently working. + git branch -D <branch-name>: + Deletes an existing local branch. + You need to be in a local branch other than the one you are deleting + in order to delete <branch-name>. + git pull: Retrieves information + from an upstream Git + repository and places it in your local Git repository. + You use this command to make sure you are synchronized with the repository + from which you are basing changes (.e.g. the master branch). + git push: + Sends all your committed local changes to an upstream Git + repository (e.g. a contribution repository). + The maintainer of the project draws from these repositories + when adding changes to the project’s master repository or + other development branch. + + git merge: Combines or adds changes from one + local branch of your repository with another branch. + When you create a local Git repository, the default branch is named "master". + A typical workflow is to create a temporary branch for isolated work, make and commit your + changes, switch to your local master branch, merge the changes from the temporary branch into the + local master branch, and then delete the temporary branch. + git cherry-pick: Choose and apply specific + commits from one branch into another branch. + There are times when you might not be able to merge all the changes in one branch with + another but need to pick out certain ones. + gitk: Provides a GUI view of the branches + and changes in your local Git repository. + This command is a good way to graphically see where things have diverged in your + local repository. + git log: Reports a history of your changes to the + repository. + git diff: Displays line-by-line differences + between your local working files and the same files in the upstream Git repository that your + branch currently tracks. + + +
+
+ +
+ Workflows + + + This section provides some overview on workflows using Git. + In particular, the information covers basic practices that describe roles and actions in a + collaborative development environment. + Again, if you are familiar with this type of development environment, you might want to just + skip this section. + + + + The Yocto Project files are maintained using Git in a "master" branch whose Git history + tracks every change and whose structure provides branches for all diverging functionality. + Although there is no need to use Git, many open source projects do so. + For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" + branch of a given Git repository. + The "master" branch is the “upstream” repository where the final builds of the project occur. + The maintainer is responsible for accepting changes from other developers and for + organizing the underlying branch structure to reflect release strategies and so forth. + For information on finding out who is responsible for (maintains) + a particular area of code, see the + "How to Submit a Change" + section. + + + + + The project also has an upstream contribution Git repository named + poky-contrib. + You can see all the branches in this repository using the web interface + of the + Source Repositories organized + within the "Poky Support" area. + These branches temporarily hold changes to the project that have been + submitted or committed by the Yocto Project development team and by + community members who contribute to the project. + The maintainer determines if the changes are qualified to be moved + from the "contrib" branches into the "master" branch of the Git + repository. + + + + Developers (including contributing community members) create and maintain cloned repositories + of the upstream "master" branch. + These repositories are local to their development platforms and are used to develop changes. + When a developer is satisfied with a particular feature or change, they "push" the changes + to the appropriate "contrib" repository. + + + + Developers are responsible for keeping their local repository up-to-date with "master". + They are also responsible for straightening out any conflicts that might arise within files + that are being worked on simultaneously by more than one person. + All this work is done locally on the developer’s machines before anything is pushed to a + "contrib" area and examined at the maintainer’s level. + + + + A somewhat formal method exists by which developers commit changes and push them into the + "contrib" area and subsequently request that the maintainer include them into "master" + This process is called “submitting a patch” or "submitting a change." + For information on submitting patches and changes, see the + "How to Submit a Change" section. + + + + To summarize the environment: a single point of entry exists for + changes into the project’s "master" branch of the Git repository, + which is controlled by the project’s maintainer. + And, a set of developers exist who independently develop, test, and + submit changes to "contrib" areas for the maintainer to examine. + The maintainer then chooses which changes are going to become a + permanent part of the project. + + + + + + + + While each development environment is unique, there are some best practices or methods + that help development run smoothly. + The following list describes some of these practices. + For more information about Git workflows, see the workflow topics in the + Git Community Book. + + Make Small Changes: It is best to keep the changes you commit + small as compared to bundling many disparate changes into a single commit. + This practice not only keeps things manageable but also allows the maintainer + to more easily include or refuse changes. + It is also good practice to leave the repository in a state that allows you to + still successfully build your project. In other words, do not commit half of a feature, + then add the other half as a separate, later commit. + Each commit should take you from one buildable project state to another + buildable state. + Use Branches Liberally: It is very easy to create, use, and + delete local branches in your working Git repository. + You can name these branches anything you like. + It is helpful to give them names associated with the particular feature or change + on which you are working. + Once you are done with a feature or change and have merged it + into your local master branch, simply discard the temporary + branch. + Merge Changes: The git merge + command allows you to take the + changes from one branch and fold them into another branch. + This process is especially helpful when more than a single developer might be working + on different parts of the same feature. + Merging changes also automatically identifies any collisions or "conflicts" + that might happen as a result of the same lines of code being altered by two different + developers. + Manage Branches: Because branches are easy to use, you should + use a system where branches indicate varying levels of code readiness. + For example, you can have a "work" branch to develop in, a "test" branch where the code or + change is tested, a "stage" branch where changes are ready to be committed, and so forth. + As your project develops, you can merge code across the branches to reflect ever-increasing + stable states of the development. + Use Push and Pull: The push-pull workflow is based on the + concept of developers "pushing" local commits to a remote repository, which is + usually a contribution repository. + This workflow is also based on developers "pulling" known states of the project down into their + local development repositories. + The workflow easily allows you to pull changes submitted by other developers from the + upstream repository into your work area ensuring that you have the most recent software + on which to develop. + The Yocto Project has two scripts named create-pull-request and + send-pull-request that ship with the release to facilitate this + workflow. + You can find these scripts in the scripts + folder of the + Source Directory. + For information on how to use these scripts, see the + "Using Scripts to Push a Change Upstream and Request a Pull" section. + + Patch Workflow: This workflow allows you to notify the + maintainer through an email that you have a change (or patch) you would like considered + for the "master" branch of the Git repository. + To send this type of change, you format the patch and then send the email using the Git commands + git format-patch and git send-email. + For information on how to use these scripts, see the + "How to Submit a Change" + section. + + + +
+ +
+ Tracking Bugs + + + The Yocto Project uses its own implementation of + Bugzilla to track bugs. + Implementations of Bugzilla work well for group development because they track bugs and code + changes, can be used to communicate changes and problems with developers, can be used to + submit and review patches, and can be used to manage quality assurance. + The home page for the Yocto Project implementation of Bugzilla is + &YOCTO_BUGZILLA_URL;. + + + + Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself + such as when discovering an issue with some component of the build system that acts contrary + to the documentation or your expectations. + Following is the general procedure for submitting a new bug using the Yocto Project + Bugzilla. + You can find more information on defect management, bug tracking, and feature request + processes all accomplished through the Yocto Project Bugzilla on the wiki page + here. + + Always use the Yocto Project implementation of Bugzilla to submit + a bug. + When submitting a new bug, be sure to choose the appropriate + Classification, Product, and Component for which the issue was found. + Defects for the Yocto Project fall into one of seven classifications: + Yocto Project Components, Infrastructure, Build System & Metadata, + Documentation, QA/Testing, Runtime and Hardware. + Each of these Classifications break down into multiple Products and, in some + cases, multiple Components. + Use the bug form to choose the correct Hardware and Architecture + for which the bug applies. + Indicate the Yocto Project version you were using when the issue + occurred. + Be sure to indicate the Severity of the bug. + Severity communicates how the bug impacted your work. + Select the appropriate "Documentation change" item + for the bug. + Fixing a bug may or may not affect the Yocto Project + documentation. + Provide a brief summary of the issue. + Try to limit your summary to just a line or two and be sure to capture the + essence of the issue. + Provide a detailed description of the issue. + You should provide as much detail as you can about the context, behavior, output, + and so forth that surrounds the issue. + You can even attach supporting files for output from logs by + using the "Add an attachment" button. + Be sure to copy the appropriate people in the + "CC List" for the bug. + See the "How to Submit a Change" + section for information about finding out who is responsible + for code. + Submit the bug by clicking the "Submit Bug" button. + + +
+ +
+ How to Submit a Change + + + Contributions to the Yocto Project and OpenEmbedded are very welcome. + Because the system is extremely configurable and flexible, we recognize that developers + will want to extend, configure or optimize it for their specific uses. + You should send patches to the appropriate mailing list so that they + can be reviewed and merged by the appropriate maintainer. + + + + Before submitting any change, be sure to find out who you should be + notifying. + Several methods exist through which you find out who you should be copying + or notifying: + + Maintenance File: + Examine the maintainers.inc file, which is + located in the + Source Directory + at meta-yocto/conf/distro/include, to + see who is responsible for code. + + Board Support Package (BSP) README Files: + For BSP maintainers of supported BSPs, you can examine + individual BSP README files. + In addition, some layers (such as the meta-intel layer), + include a MAINTAINERS file which contains + a list of all supported BSP maintainers for that layer. + + Search by File: + Using Git, you can enter the + following command to bring up a short list of all commits + against a specific file: + + git shortlog -- filename + + Just provide the name of the file for which you are interested. + The information returned is not ordered by history but does + include a list of all committers grouped by name. + From the list, you can see who is responsible for the bulk of + the changes against the file. + + + + + + For a list of the Yocto Project and related mailing lists, see the + "Mailing lists" section in + the Yocto Project Reference Manual. + + + + Here is some guidance on which mailing list to use for what type of change: + + For changes to the core + Metadata, send your patch to the + openembedded-core mailing list. + For example, a change to anything under the meta or + scripts directories + should be sent to this mailing list. + For changes to BitBake (anything under the bitbake + directory), send your patch to the + bitbake-devel mailing list. + For changes to meta-yocto, send your patch to the + poky mailing list. + For changes to other layers hosted on + yoctoproject.org (unless the + layer's documentation specifies otherwise), tools, and Yocto Project + documentation, use the + yocto mailing list. + For additional recipes that do not fit into the core Metadata, + you should determine which layer the recipe should go into and submit the + change in the manner recommended by the documentation (e.g. README) supplied + with the layer. If in doubt, please ask on the + yocto or + openembedded-devel + mailing lists. + + + + + When you send a patch, be sure to include a "Signed-off-by:" + line in the same style as required by the Linux kernel. + Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 + as follows: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + + + + + In a collaborative environment, it is necessary to have some sort of standard + or method through which you submit changes. + Otherwise, things could get quite chaotic. + One general practice to follow is to make small, controlled changes. + Keeping changes small and isolated aids review, makes merging/rebasing easier + and keeps the change history clean when anyone needs to refer to it in future. + + + + When you make a commit, you must follow certain standards established by the + OpenEmbedded and Yocto Project development teams. + For each commit, you must provide a single-line summary of the change and you + should almost always provide a more detailed description of what you did (i.e. + the body of the commit message). + The only exceptions for not providing a detailed description would be if your + change is a simple, self-explanatory change that needs no further description + beyond the summary. + Here are the guidelines for composing a commit message: + + Provide a single-line, short summary of the change. + This summary is typically viewable in the "shortlist" of changes. + Thus, providing something short and descriptive that gives the reader + a summary of the change is useful when viewing a list of many commits. + This short description should be prefixed by the recipe name (if changing a recipe), or + else the short form path to the file being changed. + + For the body of the commit message, provide detailed information + that describes what you changed, why you made the change, and the approach + you used. It may also be helpful if you mention how you tested the change. + Provide as much detail as you can in the body of the commit message. + + + If the change addresses a specific bug or issue that is + associated with a bug-tracking ID, include a reference to that + ID in your detailed description. + For example, the Yocto Project uses a specific convention for + bug references - any commit that addresses a specific bug should + use the following form for the detailed description: + + Fixes [YOCTO #bug-id] + + detailed description of change + + Where bug-id is replaced with the + specific bug ID from the Yocto Project Bugzilla instance. + + + + + You can find more guidance on creating well-formed commit messages at this OpenEmbedded + wiki page: + . + + + + The next two sections describe general instructions for both pushing + changes upstream and for submitting changes as patches. + + +
+ Using Scripts to Push a Change Upstream and Request a Pull + + + The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: + + Make your changes in your local Git repository. + Stage your changes by using the git add + command on each file you changed. + + Commit the change by using the + git commit command. + Be sure to provide a commit message that follows the + project’s commit message standards as described earlier. + + + Push the change to the upstream "contrib" repository by + using the git push command. + + Notify the maintainer that you have pushed a change by making a pull + request. + The Yocto Project provides two scripts that conveniently let you generate and send + pull requests to the Yocto Project. + These scripts are create-pull-request and + send-pull-request. + You can find these scripts in the scripts directory + within the Source Directory. + Using these scripts correctly formats the requests without introducing any + whitespace or HTML formatting. + The maintainer that receives your patches needs to be able to save and apply them + directly from your emails. + Using these scripts is the preferred method for sending patches. + For help on using these scripts, simply provide the + -h argument as follows: + + $ poky/scripts/create-pull-request -h + $ poky/scripts/send-pull-request -h + + + + + + You can find general Git information on how to push a change upstream in the + Git Community Book. + +
+ +
+ Using Email to Submit a Patch + + + You can submit patches without using the create-pull-request and + send-pull-request scripts described in the previous section. + However, keep in mind, the preferred method is to use the scripts. + + + + Depending on the components changed, you need to submit the email to a specific + mailing list. + For some guidance on which mailing list to use, see the list in the + "How to Submit a Change" + section. + For a description of the available mailing lists, see the + "Mailing Lists" + section in the Yocto Project Reference Manual. + + + + Here is the general procedure on how to submit a patch through email without using the + scripts: + + Make your changes in your local Git repository. + Stage your changes by using the git add + command on each file you changed. + Commit the change by using the + git commit --signoff command. + Using the --signoff option identifies you as the person + making the change and also satisfies the Developer's Certificate of + Origin (DCO) shown earlier. + When you form a commit, you must follow certain standards established by the + Yocto Project development team. + See the earlier section + "How to Submit a Change" + for Yocto Project commit message standards. + Format the commit into an email message. + To format commits, use the git format-patch command. + When you provide the command, you must include a revision list or a number of patches + as part of the command. + For example, either of these two commands takes your most + recent single commit and formats it as an email message in + the current directory: + + $ git format-patch -1 + + or + + $ git format-patch HEAD~ + + After the command is run, the current directory contains a + numbered .patch file for the commit. + If you provide several commits as part of the command, + the git format-patch command produces a + series of numbered files in the current directory – one for each commit. + If you have more than one patch, you should also use the + --cover option with the command, which generates a + cover letter as the first "patch" in the series. + You can then edit the cover letter to provide a description for + the series of patches. + For information on the git format-patch command, + see GIT_FORMAT_PATCH(1) displayed using the + man git-format-patch command. + If you are or will be a frequent contributor to the Yocto Project + or to OpenEmbedded, you might consider requesting a contrib area and the + necessary associated rights. + Import the files into your mail client by using the + git send-email command. + In order to use git send-email, you must have the + the proper Git packages installed. + For Ubuntu, Debian, and Fedora the package is git-email. + The git send-email command sends email by using a local + or remote Mail Transport Agent (MTA) such as + msmtp, sendmail, or through a direct + smtp configuration in your Git config + file. + If you are submitting patches through email only, it is very important + that you submit them without any whitespace or HTML formatting that + either you or your mailer introduces. + The maintainer that receives your patches needs to be able to save and + apply them directly from your emails. + A good way to verify that what you are sending will be applicable by the + maintainer is to do a dry run and send them to yourself and then + save and apply them as the maintainer would. + The git send-email command is the preferred method + for sending your patches since there is no risk of compromising whitespace + in the body of the message, which can occur when you use your own mail client. + The command also has several options that let you + specify recipients and perform further editing of the email message. + For information on how to use the git send-email command, + see GIT-SEND-EMAIL(1) displayed using + the man git-send-email command. + + + +
+
+
+ diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml new file mode 100644 index 0000000000..739fd7104b --- /dev/null +++ b/documentation/dev-manual/dev-manual-qemu.xml @@ -0,0 +1,419 @@ + %poky; ] > + + + +Using the Quick EMUlator (QEMU) + + + Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses + as part of its development "tool set". + As such, the information in this chapter is limited to the + Yocto Project integration of QEMU and not QEMU in general. + For official information and documentation on QEMU, see the + following references: + + QEMU Website: + The official website for the QEMU Open Source project. + + Documentation: + The QEMU user manual. + + + + + + This chapter provides an overview of the Yocto Project's integration of + QEMU, a description of how you use QEMU and its various options, running + under a Network File System (NFS) server, and a few tips and tricks you + might find helpful when using QEMU. + + +
+ Overview + + + Within the context of the Yocto Project, QEMU is an + emulator and virtualization machine that allows you to run a complete + image you have built using the Yocto Project as just another task + on your build system. + QEMU is useful for running and testing images and applications on + supported Yocto Project architectures without having actual hardware. + Among other things, the Yocto Project uses QEMU to run automated + Quality Assurance (QA) tests on final images shipped with each + release. + + + + QEMU is made available with the Yocto Project a number of ways. + The easiest and recommended method for getting QEMU is to run the + ADT installer. For more information on how to make sure you have + QEMU available, see the + "The QEMU Emulator" + section in the Yocto Project Application Developer's Guide. + +
+ +
+ Running QEMU + + + Running QEMU involves having your build environment set up, having the + right artifacts available, and understanding how to use the many + options that are available to you when you start QEMU using the + runqemu command. + + +
+ Setting Up the Environment + + + You run QEMU in the same environment from which you run BitBake. + This means you need to source a build environment script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + +
+ +
+ Using the <filename>runqemu</filename> Command + + + The basic runqemu command syntax is as + follows: + + $ runqemu [option ] [...] + + Based on what you provide on the command line, + runqemu does a good job of figuring out what + you are trying to do. + For example, by default, QEMU looks for the most recently built + image according to the timestamp when it needs to look for an + image. + Minimally, through the use of options, you must provide either + a machine name, a virtual machine image + (*.vmdk), or a kernel image + (*.bin). + + + + Following is a description of runqemu + options you can provide on the command line: + Tip + If you do provide some "illegal" option combination or perhaps + you do not provide enough in the way of options, + runqemu provides appropriate error + messaging to help you correct the problem. + + + QEMUARCH: + The QEMU machine architecture, which must be "qemux86", + "qemux86-64", "qemuarm", "qemumips", "qemumipsel", + “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", + or "qemuzynq". + + VM: + The virtual machine image, which must be a + .vmdk file. + Use this option when you want to boot a + .vmdk image. + The image filename you provide must contain one of the + following strings: "qemux86-64", "qemux86", "qemuarm", + "qemumips64", "qemumips", "qemuppc", or "qemush4". + + ROOTFS: + A root filesystem that has one of the following + filetype extensions: "ext2", "ext3", "ext4", "jffs2", + "nfs", or "btrfs". + If the filename you provide for this option uses “nfs”, it + must provide an explicit root filesystem path. + + KERNEL: + A kernel image, which is a .bin file. + When you provide a .bin file, + runqemu detects it and assumes the + file is a kernel image. + + MACHINE: + The architecture of the QEMU machine, which must be one + of the following: "qemux86", + "qemux86-64", "qemuarm", "qemumips", "qemumipsel", + “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", + or "qemuzynq". + The MACHINE and + QEMUARCH options are basically + identical. + If you do not provide a MACHINE + option, runqemu tries to determine + it based on other options. + + ramfs: + Indicates you are booting an initial RAM disk (initramfs) + image, which means the FSTYPE is + cpio.gz. + + iso: + Indicates you are booting an ISO image, which means the + FSTYPE is + .iso. + + nographic: + Disables the video console, which sets the console to + "ttys0". + + serial: + Enables a serial console on + /dev/ttyS0. + + biosdir: + Establishes a custom directory for BIOS, VGA BIOS and + keymaps. + + qemuparams=\"xyz\": + Specifies custom QEMU parameters. + Use this option to pass options other than the simple + "kvm" and "serial" options. + + bootparams=\"xyz\": + Specifies custom boot parameters for the kernel. + + audio: + Enables audio in QEMU. + The MACHINE option must be + either "qemux86" or "qemux86-64" in order for audio to be + enabled. + Additionally, the snd_intel8x0 + or snd_ens1370 driver must be + installed in linux guest. + + slirp: + Enables "slirp" networking, which is a different way + of networking that does not need root access + but also is not as easy to use or comprehensive + as the default. + + kvm: + Enables KVM when running "qemux86" or "qemux86-64" + QEMU architectures. + For KVM to work, all the following conditions must be met: + + + Your MACHINE must be either + "qemux86" or "qemux86-64". + + + Your build host has to have the KVM modules + installed, which are + /dev/kvm. + + + Your build host has to have virtio net device, which + are /dev/vhost-net. + + + The build host /dev/kvm + directory has to be both writable and readable. + + + The build host /dev/vhost-net + directory has to be either readable or writable + and “slirp-enabled”. + + + + publicvnc: + Enables a VNC server open to all hosts. + + + + + + For further understanding regarding option use with + runqemu, consider some examples. + + + + This example starts QEMU with + MACHINE set to "qemux86". + Assuming a standard + Build Directory, + runqemu automatically finds the + bzImage-qemux86.bin image file and + the + core-image-minimal-qemux86-20140707074611.rootfs.ext3 + (assuming the current build created a + core-image-minimal image). + + When more than one image with the same name exists, QEMU finds + and uses the most recently built image according to the + timestamp. + + + $ runqemu qemux86 + + This example produces the exact same results as the + previous example. + This command, however, specifically provides the image + and root filesystem type. + + $ runqemu qemux86 core-image-minimal ext3 + + This example specifies to boot an initial RAM disk image + and to enable audio in QEMU. + For this case, runqemu set the + internal variable FSTYPE to + "cpio.gz". + Also, for audio to be enabled, an appropriate driver must + be installed (see the previous description for the + audio option for more information). + + $ runqemu qemux86 ramfs audio + + This example does not provide enough information for + QEMU to launch. + While the command does provide a root filesystem type, it + must also minimally provide a + MACHINE, + KERNEL, or + VM option. + + $ runqemu ext3 + + This example specifies to boot a virtual machine image + (.vmdk file). + From the .vmdk, + runqemu determines the QEMU + architecture (MACHINE) to be + "qemux86" and the root filesystem type to be "vmdk". + + $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk + + +
+
+ +
+ Running Under a Network File System (NFS) Server + + + One method for running QEMU is to run it on an NFS server. + This is useful when you need to access the same file system from both + the build and the emulated system at the same time. + It is also worth noting that the system does not need root privileges + to run. + It uses a user space NFS server to avoid that. + This section describes how to set up for running QEMU using an NFS + server and then how you can start and stop the server. + + +
+ Setting Up to Use NFS + + + Once you are able to run QEMU in your environment, you can use the + runqemu-extract-sdk script, which is located + in the scripts directory along with + runqemu script. + The runqemu-extract-sdk takes a root + file system tarball and extracts it into a location that you + specify. + Then, when you run runqemu, you can specify + the location that has the file system to pass it to QEMU. + Here is an example that takes a file system and extracts it to + a directory named test-nfs: + + runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs + + Once you have extracted the file system, you can run + runqemu normally with the additional + location of the file system. + You can then also make changes to the files within + ./test-nfs and see those changes appear in the + image in real time. + Here is an example using the qemux86 image: + + runqemu qemux86 ./test-nfs + + +
+ +
+ Starting and Stopping NFS + + + You can manually start and stop the NFS share using these + commands: + + start: + Starts the NFS share: + + runqemu-export-rootfs start file-system-location + + + stop: + Stops the NFS share: + + runqemu-export-rootfs stop file-system-location + + + restart: + Restarts the NFS share: + + runqemu-export-rootfs restart file-system-location + + + + +
+
+ +
+ Tips and Tricks + + + The following list describes things you can do to make running QEMU + in the context of the Yocto Project a better experience: + + Switching Between Consoles: + When booting or running QEMU, you can switch between + supported consoles by using + Ctrl+Alt+number. + For example, Ctrl+Alt+3 switches you to the serial console as + long as that console is enabled. + Being able to switch consoles is helpful, for example, if the + main QEMU console breaks for some reason. + + Usually, "2" gets you to the main console and "3" gets you + to the serial console. + + + Removing the Splash Screen: + You can remove the splash screen when QEMU is booting by + using Alt+left. + Removing the splash screen allows you to see what is happening + in the background. + + Disabling the Cursor Grab: + The default QEMU integration captures the cursor within the + main window. + It does this since standard mouse devices only provide relative + input and not absolute coordinates. + You then have to break out of the grab using the "Ctrl+Alt" key + combination. + However, the Yocto Project's integration of QEMU enables the + wacom USB touch pad driver by default to allow input of absolute + coordinates. + This default means that the mouse can enter and leave the + main window without the grab taking effect leading to a better + user experience. + + + +
+ +
+ diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml new file mode 100644 index 0000000000..61434ff72c --- /dev/null +++ b/documentation/dev-manual/dev-manual-start.xml @@ -0,0 +1,418 @@ + %poky; ] > + + + +Getting Started with the Yocto Project + + + This chapter introduces the Yocto Project and gives you an idea of what you need to get started. + You can find enough information to set up your development host and build or use images for + hardware supported by the Yocto Project by reading the + Yocto Project Quick Start. + + + + The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides + some higher-level concepts you might want to consider. + + +
+ Introducing the Yocto Project + + + The Yocto Project is an open-source collaboration project focused on embedded Linux development. + The project currently provides a build system that is + referred to as the + OpenEmbedded build system + in the Yocto Project documentation. + The Yocto Project provides various ancillary tools for the embedded developer + and also features the Sato reference User Interface, which is optimized for + stylus driven, low-resolution screens. + + + + You can use the OpenEmbedded build system, which uses + BitBake, to develop complete Linux + images and associated user-space applications for architectures based + on ARM, MIPS, PowerPC, x86 and x86-64. + + By default, using the Yocto Project creates a Poky distribution. + However, you can create your own distribution by providing key + Metadata. + See the "Creating Your Own Distribution" + section for more information. + + While the Yocto Project does not provide a strict testing framework, + it does provide or generate for you artifacts that let you perform target-level and + emulated testing and debugging. + Additionally, if you are an Eclipse + IDE user, you can install an Eclipse Yocto Plug-in to allow you to + develop within that familiar environment. + +
+ +
+ Getting Set Up + + + Here is what you need to use the Yocto Project: + + Host System: You should have a reasonably current + Linux-based host system. + You will have the best results with a recent release of Fedora, + openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project + and officially supported. + For a list of the distributions under validation and their status, see the + "Supported Linux Distributions" section + in the Yocto Project Reference Manual and the wiki page at + Distribution Support. + + You should also have about 50 Gbytes of free disk space for building images. + + Packages: The OpenEmbedded build system + requires that certain packages exist on your development system (e.g. Python 2.6 or 2.7). + See "The Packages" + section in the Yocto Project Quick Start and the + "Required Packages for the Host Development System" + section in the Yocto Project Reference Manual for the exact + package requirements and the installation commands to install + them for the supported distributions. + + Yocto Project Release: + You need a release of the Yocto Project locally installed on + your development system. + The documentation refers to this set of locally installed files + as the Source Directory. + You create your Source Directory by using + Git to clone a local copy + of the upstream poky repository, + or by downloading and unpacking a tarball of an official + Yocto Project release. + The preferred method is to create a clone of the repository. + + Working from a copy of the upstream repository allows you + to contribute back into the Yocto Project or simply work with + the latest software on a development branch. + Because Git maintains and creates an upstream repository with + a complete history of changes and you are working with a local + clone of that repository, you have access to all the Yocto + Project development branches and tag names used in the upstream + repository. + You can view the Yocto Project Source Repositories at + + + The following transcript shows how to clone the + poky Git repository into the current + working directory. + The command creates the local repository in a directory + named poky. + For information on Git used within the Yocto Project, see + the "Git" section. + + $ git clone git://git.yoctoproject.org/poky + Cloning into 'poky'... + remote: Counting objects: 226790, done. + remote: Compressing objects: 100% (57465/57465), done. + 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. + + For another example of how to set up your own local Git + repositories, see this + + wiki page, which describes how to create local + Git repositories for both + poky and meta-intel. + + Yocto Project Kernel: + If you are going to be making modifications to a supported Yocto Project kernel, you + need to establish local copies of the source. + You can find Git repositories of supported Yocto Project kernels organized under + "Yocto Linux Kernel" in the Yocto Project Source Repositories at + . + This setup can involve creating a bare clone of the Yocto Project kernel and then + copying that cloned repository. + You can create the bare clone and the copy of the bare clone anywhere you like. + For simplicity, it is recommended that you create these structures outside of the + Source Directory, which is usually named poky. + As an example, the following transcript shows how to create the bare clone + of the linux-yocto-3.10 kernel and then create a copy of + that clone. + When you have a local Yocto Project kernel Git repository, you can + reference that repository rather than the upstream Git repository as + part of the clone command. + Doing so can speed up the process. + In the following example, the bare clone is named + linux-yocto-3.10.git, while the + copy is named my-linux-yocto-3.10-work: + + $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git + Cloning into bare repository 'linux-yocto-3.10.git'... + remote: Counting objects: 3364487, done. + remote: Compressing objects: 100% (507178/507178), done. + remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709) + Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done. + Resolving deltas: 100% (2827715/2827715), done. + + Now create a clone of the bare clone just created: + + $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work + Cloning into 'my-linux-yocto-3.10-work'... + done. + + + The meta-yocto-kernel-extras Git Repository: + The meta-yocto-kernel-extras Git repository contains Metadata needed + only if you are modifying and building the kernel image. + In particular, it contains the kernel BitBake append (.bbappend) + files that you + edit to point to your locally modified kernel source files and to build the kernel + image. + Pointing to these local files is much more efficient than requiring a download of the + kernel's source files from upstream each time you make changes to the kernel. + You can find the meta-yocto-kernel-extras Git Repository in the + "Yocto Metadata Layers" area of the Yocto Project Source Repositories at + . + It is good practice to create this Git repository inside the Source Directory. + Following is an example that creates the meta-yocto-kernel-extras Git + repository inside the Source Directory, which is named poky + in this case: + + $ cd ~/poky + $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras + Cloning into 'meta-yocto-kernel-extras'... + remote: Counting objects: 727, done. + remote: Compressing objects: 100% (452/452), done. + remote: Total 727 (delta 260), reused 719 (delta 252) + Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done. + Resolving deltas: 100% (260/260), done. + + Supported Board Support Packages (BSPs): + The Yocto Project supports many BSPs, which are maintained in + their own layers or in layers designed to contain several + BSPs. + To get an idea of machine support through BSP layers, you can + look at the + index of machines + for the release. + + The Yocto Project uses the following BSP layer naming + scheme: + + meta-bsp_name + + where bsp_name is the recognized + BSP name. + Here are some examples: + + meta-crownbay + meta-emenlow + meta-n450 + + See the + "BSP Layers" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide for more information on BSP Layers. + + A useful Git repository released with the Yocto + Project is meta-intel, which is a + parent layer that contains many supported + BSP Layers. + You can locate the meta-intel Git + repository in the "Yocto Metadata Layers" area of the Yocto + Project Source Repositories at + . + + Using + Git to create a local clone of the + upstream repository can be helpful if you are working with + BSPs. + Typically, you set up the meta-intel + Git repository inside the Source Directory. + For example, the following transcript shows the steps to clone + meta-intel. + + Be sure to work in the meta-intel + branch that matches your + Source Directory + (i.e. poky) branch. + For example, if you have checked out the "master" branch + of poky and you are going to use + meta-intel, be sure to checkout the + "master" branch of meta-intel. + + + $ 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. + + + The same + wiki page + referenced earlier covers how to set up the + meta-intel Git repository. + + Eclipse Yocto Plug-in: If you are developing + applications using the Eclipse Integrated Development Environment (IDE), + you will need this plug-in. + See the + "Setting up the Eclipse IDE" + section for more information. + + +
+ +
+ Building Images + + + The build process creates an entire Linux distribution, including the toolchain, from source. + For more information on this topic, see the + "Building an Image" + section in the Yocto Project Quick Start. + + + + The build process is as follows: + + Make sure you have set up the Source Directory described in the + previous section. + Initialize the build environment by sourcing a build + environment script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + Optionally ensure the conf/local.conf configuration file, + which is found in the + Build Directory, + is set up how you want it. + This file defines many aspects of the build environment including + the target machine architecture through the + MACHINE variable, + the development machine's processor use through the + BB_NUMBER_THREADS and + PARALLEL_MAKE variables, and + a centralized tarball download directory through the + DL_DIR variable. + + Build the image using the bitbake command. + If you want information on BitBake, see the + BitBake User Manual. + + Run the image either on the actual hardware or using the QEMU + emulator. + + +
+ +
+ Using Pre-Built Binaries and QEMU + + + Another option you have to get started is to use pre-built binaries. + The Yocto Project provides many types of binaries with each release. + See the "Images" + chapter in the Yocto Project Reference Manual + for descriptions of the types of binaries that ship with a Yocto Project + release. + + + + 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. + + + + Regardless of the type of image you are using, you need to download the pre-built kernel + that you will boot in the QEMU emulator and then download and extract the target root + filesystem for your target machine’s architecture. + You can get architecture-specific binaries and file systems from + machines. + You can get installation scripts for stand-alone toolchains from + toolchains. + Once you have all your files, you set up the environment to emulate the hardware + by sourcing an environment setup script. + Finally, you start the QEMU emulator. + You can find details on all these steps in the + "Using Pre-Built Binaries and QEMU" + section of the Yocto Project Quick Start. + You can learn more about using QEMU with the Yocto Project in the + "Using the Quick EMUlator (QEMU)" + section. + + + + Using QEMU to emulate your hardware can result in speed issues + depending on the target and host architecture mix. + For example, using the qemux86 image in the emulator + on an Intel-based 32-bit (x86) host machine is fast because the target and + host architectures match. + On the other hand, using the qemuarm image on the same Intel-based + host can be slower. + But, you still achieve faithful emulation of ARM-specific issues. + + + + To speed things up, the QEMU images support using distcc + to call a cross-compiler outside the emulated system. + If you used runqemu to start QEMU, and the + distccd application is present on the host system, any + BitBake cross-compiling toolchain available from the build system is automatically + used from within QEMU simply by calling distcc. + You can accomplish this by defining the cross-compiler variable + (e.g. export CC="distcc"). + Alternatively, if you are using a suitable SDK image or the appropriate + stand-alone toolchain is present, + the toolchain is also automatically used. + + + + Several mechanisms exist that let you connect to the system running on the + QEMU emulator: + + QEMU provides a framebuffer interface that makes standard + consoles available. + Generally, headless embedded devices have a serial port. + If so, you can configure the operating system of the running image + to use that port to run a console. + The connection uses standard IP networking. + + SSH servers exist in some QEMU images. + The core-image-sato QEMU image has a + Dropbear secure shell (SSH) server that runs with the root + password disabled. + The core-image-full-cmdline and + core-image-lsb QEMU images + have OpenSSH instead of Dropbear. + Including these SSH servers allow you to use standard + ssh and scp commands. + The core-image-minimal QEMU image, + however, contains no SSH server. + + You can use a provided, user-space NFS server to boot the QEMU session + using a local copy of the root filesystem on the host. + In order to make this connection, you must extract a root filesystem tarball by using the + runqemu-extract-sdk command. + After running the command, you must then point the runqemu + script to the extracted directory instead of a root filesystem image file. + + +
+
+ diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml new file mode 100644 index 0000000000..4e498b8201 --- /dev/null +++ b/documentation/dev-manual/dev-manual.xml @@ -0,0 +1,124 @@ + %poky; ] > + + + + + + + + + + + + Yocto Project Development Manual + + + + + Scott Rifenbark + + Intel Corporation + + scott.m.rifenbark@intel.com + + + + + + 1.1 + 6 October 2011 + The initial document released with the Yocto Project 1.1 Release. + + + 1.2 + April 2012 + Released with the Yocto Project 1.2 Release. + + + 1.3 + October 2012 + Released with the Yocto Project 1.3 Release. + + + 1.4 + April 2013 + Released with the Yocto Project 1.4 Release. + + + 1.5 + October 2013 + Released with the Yocto Project 1.5 Release. + + + 1.5.1 + January 2014 + Released with the Yocto Project 1.5.1 Release. + + + 1.6 + April 2014 + Released with the Yocto Project 1.6 Release. + + + 1.7 + October 2014 + Released with the Yocto Project 1.7 Release. + + + 1.7.1 + January 2015 + Released with the Yocto Project 1.7.1 Release. + + + 1.7.2 + June 2015 + Released with the Yocto Project 1.7.2 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the + Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by + Creative Commons. + + + + For the latest version of this manual associated with this + Yocto Project release, see the + Yocto Project Development Manual + from the Yocto Project website. + + + + + + + + + + + + + + + + + + + diff --git a/documentation/dev-manual/dev-style.css b/documentation/dev-manual/dev-style.css new file mode 100644 index 0000000000..b900ffc9b2 --- /dev/null +++ b/documentation/dev-manual/dev-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/dev-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/dev-manual/figures/app-dev-flow.png b/documentation/dev-manual/figures/app-dev-flow.png new file mode 100644 index 0000000000..ec93374ee7 Binary files /dev/null and b/documentation/dev-manual/figures/app-dev-flow.png differ diff --git a/documentation/dev-manual/figures/bsp-dev-flow.png b/documentation/dev-manual/figures/bsp-dev-flow.png new file mode 100644 index 0000000000..540b0abb9f Binary files /dev/null and b/documentation/dev-manual/figures/bsp-dev-flow.png differ diff --git a/documentation/dev-manual/figures/dev-title.png b/documentation/dev-manual/figures/dev-title.png new file mode 100644 index 0000000000..d3cac4a7e5 Binary files /dev/null and b/documentation/dev-manual/figures/dev-title.png differ diff --git a/documentation/dev-manual/figures/git-workflow.png b/documentation/dev-manual/figures/git-workflow.png new file mode 100644 index 0000000000..e401330a12 Binary files /dev/null and b/documentation/dev-manual/figures/git-workflow.png differ diff --git a/documentation/dev-manual/figures/index-downloads.png b/documentation/dev-manual/figures/index-downloads.png new file mode 100644 index 0000000000..41251d5d18 Binary files /dev/null and b/documentation/dev-manual/figures/index-downloads.png differ diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png new file mode 100644 index 0000000000..009105d122 Binary files /dev/null and b/documentation/dev-manual/figures/kernel-dev-flow.png differ diff --git a/documentation/dev-manual/figures/kernel-overview-1.png b/documentation/dev-manual/figures/kernel-overview-1.png new file mode 100644 index 0000000000..116c0b9bd4 Binary files /dev/null and b/documentation/dev-manual/figures/kernel-overview-1.png differ diff --git a/documentation/dev-manual/figures/kernel-overview-2-generic.png b/documentation/dev-manual/figures/kernel-overview-2-generic.png new file mode 100644 index 0000000000..889ff1bf0d Binary files /dev/null and b/documentation/dev-manual/figures/kernel-overview-2-generic.png differ diff --git a/documentation/dev-manual/figures/recipe-workflow.png b/documentation/dev-manual/figures/recipe-workflow.png new file mode 100644 index 0000000000..c0e960b13b Binary files /dev/null and b/documentation/dev-manual/figures/recipe-workflow.png differ diff --git a/documentation/dev-manual/figures/source-repos.png b/documentation/dev-manual/figures/source-repos.png new file mode 100644 index 0000000000..65c5f29a43 Binary files /dev/null and b/documentation/dev-manual/figures/source-repos.png differ diff --git a/documentation/dev-manual/figures/yp-download.png b/documentation/dev-manual/figures/yp-download.png new file mode 100644 index 0000000000..5770be6883 Binary files /dev/null and b/documentation/dev-manual/figures/yp-download.png differ diff --git a/documentation/kernel-dev/figures/kernel-architecture-overview.png b/documentation/kernel-dev/figures/kernel-architecture-overview.png new file mode 100755 index 0000000000..2aad172db3 Binary files /dev/null and b/documentation/kernel-dev/figures/kernel-architecture-overview.png differ diff --git a/documentation/kernel-dev/figures/kernel-dev-title.png b/documentation/kernel-dev/figures/kernel-dev-title.png new file mode 100644 index 0000000000..7a8dd54372 Binary files /dev/null and b/documentation/kernel-dev/figures/kernel-dev-title.png differ diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml new file mode 100644 index 0000000000..283f483112 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -0,0 +1,1074 @@ + %poky; ] > + + +Working with Advanced Metadata + +
+ Overview + + + In addition to supporting configuration fragments and patches, the + Yocto Project kernel tools also support rich + Metadata that you can + use to define complex policies and Board Support Package (BSP) support. + The purpose of the Metadata and the tools that manage it, known as + the kern-tools (kern-tools-native_git.bb), is + to help you manage the complexity of the configuration and sources + used to support multiple BSPs and Linux kernel types. + +
+ +
+ Using Kernel Metadata in a Recipe + + + The kernel sources in the Yocto Project contain kernel Metadata, which is + located in the meta branches of the kernel source + Git repositories. + This Metadata defines Board Support Packages (BSPs) that + correspond to definitions in linux-yocto recipes for the same BSPs. + A BSP consists of an aggregation of kernel policy and hardware-specific + feature enablements. + The BSP can be influenced from within the linux-yocto recipe. + + Linux kernel source that contains kernel Metadata is said to be + "linux-yocto style" kernel source. + A Linux kernel recipe that inherits from the + linux-yocto.inc include file is said to be a + "linux-yocto style" recipe. + + + + + Every linux-yocto style recipe must define the + KMACHINE + variable. + This variable is typically set to the same value as the + MACHINE + variable, which is used by + BitBake + (e.g. "edgerouter" or "fri2"). + Multiple BSPs can reuse the same KMACHINE + name if they are built using the same BSP description. + The "fri2" and "fri2-noemgd" BSP combination + in the meta-intel + layer is a good example of two BSPs using the same + KMACHINE value (i.e. "fri2"). + See the BSP Descriptions section + for more information. + + + + The linux-yocto style recipes can optionally define the following + variables: + + KBRANCH + KERNEL_FEATURES + KBRANCH_DEFAULT + LINUX_KERNEL_TYPE + + KBRANCH_DEFAULT defines the Linux kernel source + repository's default branch to use to build the Linux kernel. + The value is used as the default for KBRANCH, which + can define an alternate branch typically with a machine override as + follows: + + KBRANCH_fri2 = "standard/fri2" + + Unless you specify otherwise, KBRANCH_DEFAULT + initializes to "master". + + + + LINUX_KERNEL_TYPE defines the kernel type to be + used in assembling the configuration. + If you do not specify a LINUX_KERNEL_TYPE, + it defaults to "standard". + Together with + KMACHINE, + LINUX_KERNEL_TYPE defines the search + arguments used by the kernel tools to find the + appropriate description within the kernel Metadata with which to + build out the sources and configuration. + The linux-yocto recipes define "standard", "tiny", and "preempt-rt" + kernel types. + See the Kernel Types section + for more information on kernel types. + + + + During the build, the kern-tools search for the BSP description + file that most closely matches the KMACHINE + and LINUX_KERNEL_TYPE variables passed in from the + recipe. + The tools use the first BSP description it finds that match + both variables. + If the tools cannot find a match, they issue a warning such as + the following: + + WARNING: Can't find any BSP hardware or required configuration fragments. + WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and + meta/cfg/broken/fri2-broken/required_frags.txt in directory: + meta/cfg/broken/fri2-broken + + In this example, KMACHINE was set to "fri2-broken" + and LINUX_KERNEL_TYPE was set to "broken". + + + + The tools first search for the KMACHINE and + then for the LINUX_KERNEL_TYPE. + If the tools cannot find a partial match, they will use the + sources from the KBRANCH and any configuration + specified in the + SRC_URI. + + + + You can use the KERNEL_FEATURES variable + to include features (configuration fragments, patches, or both) that + are not already included by the KMACHINE and + LINUX_KERNEL_TYPE variable combination. + For example, to include a feature specified as "features/netfilter.scc", + specify: + + KERNEL_FEATURES += "features/netfilter.scc" + + To include a feature called "cfg/sound.scc" just for the + qemux86 machine, specify: + + KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc" + + The value of the entries in KERNEL_FEATURES + are dependent on their location within the kernel Metadata itself. + The examples here are taken from the + linux-yocto-3.4 repository where "features" + and "cfg" are subdirectories within the + meta/cfg/kernel-cache directory. + For more information, see the + "Kernel Metadata Syntax" section. + + The processing of the these variables has evolved some between the + 0.9 and 1.3 releases of the Yocto Project and associated + kern-tools sources. + The descriptions in this section are accurate for 1.3 and later + releases of the Yocto Project. + + +
+ +
+ Kernel Metadata Location + + + Kernel Metadata can be defined in either the kernel recipe + (recipe-space) or in the kernel tree (in-tree). + 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 + applies equally. + + + + If you are unfamiliar with the Linux kernel and only wish + to apply a configuration and possibly a couple of patches provided to + you by others, the recipe-space method is recommended. + This method is also a good approach if you are working with Linux kernel + sources you do not control or if you just do not want to maintain a + Linux kernel Git repository on your own. + For partial information on how you can define kernel Metadata in + the recipe-space, see the + "Modifying an Existing Recipe" + section. + + + + 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. + + +
+ Recipe-Space Metadata + + + When stored in recipe-space, the kernel Metadata files reside in a + directory hierarchy below + FILESEXTRAPATHS. + For a linux-yocto recipe or for a Linux kernel recipe derived + by copying and modifying + oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb + to a recipe in your layer, FILESEXTRAPATHS + is typically set to + ${THISDIR}/${PN}. + See the "Modifying an Existing Recipe" + section for more information. + + + + Here is an example that shows a trivial tree of kernel Metadata + stored in recipe-space within a BSP layer: + + meta-my_bsp_layer/ + `-- recipes-kernel + `-- linux + `-- linux-yocto + |-- bsp-standard.scc + |-- bsp.cfg + `-- standard.cfg + + + + + When the Metadata is stored in recipe-space, you must take + steps to ensure BitBake has the necessary information to decide + what files to fetch and when they need to be fetched again. + It is only necessary to specify the .scc + files on the + SRC_URI. + BitBake parses them and fetches any files referenced in the + .scc files by the include, + patch, or kconf commands. + Because of this, it is necessary to bump the recipe + PR + value when changing the content of files not explicitly listed + in the SRC_URI. + +
+ +
+ In-Tree Metadata + + + When stored in-tree, the kernel Metadata files reside in the + meta directory of the Linux kernel sources. + The meta directory can be present in the + same repository branch as the sources, + such as "master", or meta can be its own + orphan branch. + + 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. + + For the purposes of this document, we will discuss all + in-tree Metadata as residing below the + meta/cfg/kernel-cache directory. + + + + Following is an example that shows how a trivial tree of Metadata + is stored in a custom Linux kernel Git repository: + + meta/ + `-- cfg + `-- kernel-cache + |-- bsp-standard.scc + |-- bsp.cfg + `-- standard.cfg + + + + + To use a branch different from where the sources reside, + specify the branch in the KMETA variable + in your Linux kernel recipe. + Here is an example: + + KMETA = "meta" + + To use the same branch as the sources, set + KMETA to an empty string: + + KMETA = "" + + If you are working with your own sources and want to create an + orphan meta branch, use these commands + from within your Linux kernel Git repository: + + $ git checkout --orphan meta + $ git rm -rf . + $ git commit --allow-empty -m "Create orphan meta branch" + + + + + If you modify the Metadata in the linux-yocto + meta branch, you must not forget to update + the + SRCREV + statements in the kernel's recipe. + In particular, you need to update the + SRCREV_meta variable to match the commit in + the KMETA branch you wish to use. + Changing the data in these branches and not updating the + SRCREV statements to match will cause the + build to fetch an older commit. + +
+
+ +
+ Kernel Metadata Syntax + + + The kernel Metadata consists of three primary types of files: + scc + + + scc stands for Series Configuration + Control, but the naming has less significance in the + current implementation of the tooling than it had in the + past. + Consider scc files to be description files. + + + description files, configuration fragments, and patches. + The scc files define variables and include or + otherwise reference any of the three file types. + The description files are used to aggregate all types of kernel + Metadata into + what ultimately describes the sources and the configuration required + to build a Linux kernel tailored to a specific machine. + + + + The scc description files are used to define two + fundamental types of kernel Metadata: + + Features + Board Support Packages (BSPs) + + + + + Features aggregate sources in the form of patches and configuration + fragments into a modular reusable unit. + You can use features to implement conceptually separate kernel + Metadata descriptions such as pure configuration fragments, + simple patches, complex features, and kernel types. + Kernel types define general + kernel features and policy to be reused in the BSPs. + + + + BSPs define hardware-specific features and aggregate them with kernel + types to form the final description of what will be assembled and built. + + + + While the kernel Metadata syntax does not enforce any logical + separation of configuration fragments, patches, features or kernel + types, best practices dictate a logical separation of these types + of Metadata. + The following Metadata file hierarchy is recommended: + + base/ + bsp/ + cfg/ + features/ + ktypes/ + patches/ + + + + + The bsp directory contains the + BSP descriptions. + The remaining directories all contain "features". + Separating bsp from the rest of the structure + aids conceptualizing intended usage. + + + + Use these guidelines to help place your scc + description files within the structure: + + If your file contains + only configuration fragments, place the file in the + cfg directory. + If your file contains + only source-code fixes, place the file in the + patches directory. + If your file encapsulates + a major feature, often combining sources and configurations, + place the file in features directory. + + If your file aggregates + non-hardware configuration and patches in order to define a + base kernel policy or major kernel type to be reused across + multiple BSPs, place the file in ktypes + directory. + + + + + + These distinctions can easily become blurred - especially as + out-of-tree features slowly merge upstream over time. + Also, remember that how the description files are placed is + a purely logical organization and has no impact on the functionality + of the kernel Metadata. + There is no impact because all of cfg, + features, patches, and + ktypes, contain "features" as far as the kernel + tools are concerned. + + + + Paths used in kernel Metadata files are relative to + <base>, which is either + FILESEXTRAPATHS + if you are creating Metadata in + recipe-space, + or meta/cfg/kernel-cache/ if you are creating + Metadata in-tree. + + +
+ Configuration + + + The simplest unit of kernel Metadata is the configuration-only + feature. + This feature consists of one or more Linux kernel configuration + parameters in a configuration fragment file + (.cfg) and an .scc file + that describes the fragment. + + + + The Symmetric Multi-Processing (SMP) fragment included in the + linux-yocto-3.4 Git repository + consists of the following two files: + + cfg/smp.scc: + define KFEATURE_DESCRIPTION "Enable SMP" + kconf hardware smp.cfg + + cfg/smp.cfg: + CONFIG_SMP=y + CONFIG_SCHED_SMT=y + + You can find information on configuration fragment files in the + "Creating Configuration Fragments" + section of the Yocto Project Development Manual and in + the "Generating Configuration Files" + section earlier in this manual. + + + + KFEATURE_DESCRIPTION + provides a short description of the fragment. + Higher level kernel tools use this description. + + + + The kconf command is used to include the + actual configuration fragment in an .scc + file, and the "hardware" keyword identifies the fragment as + being hardware enabling, as opposed to general policy, + which would use the "non-hardware" keyword. + The distinction is made for the benefit of the configuration + validation tools, which warn you if a hardware fragment + overrides a policy set by a non-hardware fragment. + + The description file can include multiple + kconf statements, one per fragment. + + + + + As described in the + "Generating Configuration Files" + section, you can use the following BitBake command to audit your + configuration: + + $ bitbake linux-yocto -c kernel_configcheck -f + + +
+ +
+ Patches + + + Patch descriptions are very similar to configuration fragment + descriptions, which are described in the previous section. + However, instead of a .cfg file, these + descriptions work with source patches. + + + + A typical patch includes a description file and the patch itself: + + patches/mypatch.scc: + patch mypatch.patch + + patches/mypatch.patch: + typical-patch + + You can create the typical .patch + file using diff -Nurp or + git format-patch. + + + + The description file can include multiple patch statements, + one per patch. + +
+ +
+ Features + + + Features are complex kernel Metadata types that consist + of configuration fragments (kconf), patches + (patch), and possibly other feature + description files (include). + + + + Here is an example that shows a feature description file: + + features/myfeature.scc + define KFEATURE_DESCRIPTION "Enable myfeature" + + patch 0001-myfeature-core.patch + patch 0002-myfeature-interface.patch + + include cfg/myfeature_dependency.scc + kconf non-hardware myfeature.cfg + + This example shows how the patch and + kconf commands are used as well as + how an additional feature description file is included. + + + + Typically, features are less granular than configuration + fragments and are more likely than configuration fragments + and patches to be the types of things you want to specify + in the KERNEL_FEATURES variable of the + Linux kernel recipe. + See the "Using Kernel Metadata in a Recipe" + section earlier in the manual. + +
+ +
+ Kernel Types + + + A kernel type defines a high-level kernel policy by + aggregating non-hardware configuration fragments with + patches you want to use when building a Linux kernels of a + specific type. + Syntactically, kernel types are no different than features + as described in the "Features" + section. + The LINUX_KERNEL_TYPE variable in the kernel + recipe selects the kernel type. + See the "Using Kernel Metadata in a Recipe" + section for more information. + + + + As an example, the linux-yocto-3.4 + tree defines three kernel types: "standard", + "tiny", and "preempt-rt": + + "standard": + Includes the generic Linux kernel policy of the Yocto + Project linux-yocto kernel recipes. + This policy includes, among other things, which file + systems, networking options, core kernel features, and + debugging and tracing options are supported. + + "preempt-rt": + Applies the PREEMPT_RT + patches and the configuration options required to + build a real-time Linux kernel. + This kernel type inherits from the "standard" kernel type. + + "tiny": + Defines a bare minimum configuration meant to serve as a + base for very small Linux kernels. + The "tiny" kernel type is independent from the "standard" + configuration. + Although the "tiny" kernel type does not currently include + any source changes, it might in the future. + + + + + + The "standard" kernel type is defined by + standard.scc: + + # Include this kernel type fragment to get the standard features and + # configuration values. + + # Include all standard features + include standard-nocfg.scc + + kconf non-hardware standard.cfg + + # individual cfg block section + include cfg/fs/devtmpfs.scc + include cfg/fs/debugfs.scc + include cfg/fs/btrfs.scc + include cfg/fs/ext2.scc + include cfg/fs/ext3.scc + include cfg/fs/ext4.scc + + include cfg/net/ipv6.scc + include cfg/net/ip_nf.scc + include cfg/net/ip6_nf.scc + include cfg/net/bridge.scc + + + + + As with any .scc file, a + kernel type definition can aggregate other + .scc files with + include commands. + These definitions can also directly pull in + configuration fragments and patches with the + kconf and patch + commands, respectively. + + + + It is not strictly necessary to create a kernel type + .scc file. + The Board Support Package (BSP) file can implicitly define + the kernel type using a define + KTYPE myktype + line. + See the "BSP Descriptions" + section for more information. + +
+ +
+ BSP Descriptions + + + BSP descriptions combine kernel types with hardware-specific + features. + The hardware-specific portion is typically defined + independently, and then aggregated with each supported kernel + type. + Consider this simple BSP description that supports the "mybsp" + machine: + + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + + kconf mybsp.cfg + + Every BSP description should define the + KMACHINE, + KTYPE, + and KARCH + variables. + These variables allow the OpenEmbedded build system to identify + the description as meeting the criteria set by the recipe being + built. + This simple example supports the "mybsp" machine for the "standard" + kernel and the "i386" architecture. + + + + Be aware that a hard link between the + KTYPE variable and a kernel type + description file does not exist. + Thus, if you do not have kernel types defined in your kernel + Metadata, you only need to ensure that the kernel recipe's + LINUX_KERNEL_TYPE + variable and the KTYPE variable in the + BSP description file match. + + Future versions of the tooling make the specification of + KTYPE in the BSP optional. + + + + + If you did want to separate your kernel policy from your + hardware configuration, you could do so by specifying a kernel + type, such as "standard" and including that description file + in the BSP description file. + See the "Kernel Types" section + for more information. + + + + You might also have multiple hardware configurations that you + aggregate into a single hardware description file that you + could include in the BSP description file, rather than referencing + a single .cfg file. + Consider the following: + + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + + include standard.scc + include mybsp-hw.scc + + + + + In the above example, standard.scc + aggregates all the configuration fragments, patches, and + features that make up your standard kernel policy whereas + mybsp-hw.scc aggregates all those necessary + to support the hardware available on the "mybsp" machine. + For information on how to break a complete + .config file into the various + configuration fragments, see the + "Generating Configuration Files" + section. + + + + Many real-world examples are more complex. + Like any other .scc file, BSP + descriptions can aggregate features. + Consider the Fish River Island 2 (fri2) + BSP definition from the linux-yocto-3.4 + Git repository: + + fri2.scc: + kconf hardware fri2.cfg + + include cfg/x86.scc + include features/eg20t/eg20t.scc + include cfg/dmaengine.scc + include features/ericsson-3g/f5521gw.scc + include features/power/intel.scc + include cfg/efi.scc + include features/usb/ehci-hcd.scc + include features/usb/ohci-hcd.scc + include features/iwlwifi/iwlwifi.scc + + + + + The fri2.scc description file includes + a hardware configuration fragment + (fri2.cfg) specific to the Fish River + Island 2 BSP as well as several more general configuration + fragments and features enabling hardware found on the + machine. + This description file is then included in each of the three + "fri2" description files for the supported kernel types + (i.e. "standard", "preempt-rt", and "tiny"). + Consider the "fri2" description for the "standard" kernel + type: + + fri2-standard.scc: + define KMACHINE fri2 + define KTYPE standard + define KARCH i386 + + include ktypes/standard/standard.scc + branch fri2 + + git merge emgd-1.14 + + include fri2.scc + + # Extra fri2 configs above the minimal defined in fri2.scc + include cfg/efi-ext.scc + include features/drm-emgd/drm-emgd.scc + include cfg/vesafb.scc + + # default policy for standard kernels + include cfg/usb-mass-storage.scc + + The include command midway through the file + includes the fri2.scc description that + defines all hardware enablements for the BSP that is common to all + kernel types. + Using this command significantly reduces duplication. + + + + This "fri2" standard description introduces a few more variables + and commands that are worth further discussion. + Notice the branch fri2 command, which creates + a machine-specific branch into which source changes are applied. + With this branch set up, the git merge command + uses Git to merge in a feature branch named "emgd-1.14". + You could also handle this with the patch + command. + However, for commonly used features such as this, feature branches + are a convenient mechanism. + See the "Feature Branches" + section for more information. + + + + Now consider the "fri2" description for the "tiny" kernel type: + + fri2-tiny.scc: + define KMACHINE fri2 + define KTYPE tiny + define KARCH i386 + + include ktypes/tiny/tiny.scc + branch fri2 + + include fri2.scc + + As you might expect, the "tiny" description includes quite a + bit less. + In fact, it includes only the minimal policy defined by the + "tiny" kernel type and the hardware-specific configuration required + for booting the machine along with the most basic functionality of + the system as defined in the base "fri2" description file. + + + + Notice again the three critical variables: + KMACHINE, KTYPE, + and KARCH. + Of these variables, only the KTYPE has changed. + It is now set to "tiny". + +
+
+ +
+ Organizing Your Source + + + Many recipes based on the linux-yocto-custom.bb + recipe use Linux kernel sources that have only a single + branch - "master". + This type of repository structure is fine for linear development + supporting a single machine and architecture. + However, if you work with multiple boards and architectures, + a kernel source repository with multiple branches is more + efficient. + For example, suppose you need a series of patches for one board to boot. + Sometimes, these patches are works-in-progress or fundamentally wrong, + yet they are still necessary for specific boards. + In these situations, you most likely do not want to include these + patches in every kernel you build (i.e. have the patches as part of + the lone "master" branch). + It is situations like these that give rise to multiple branches used + within a Linux kernel sources Git repository. + + + + Repository organization strategies exist that maximize source reuse, + remove redundancy, and logically order your changes. + This section presents strategies for the following cases: + + Encapsulating patches in a feature description + and only including the patches in the BSP descriptions of + the applicable boards. + Creating a machine branch in your + kernel source repository and applying the patches on that + branch only. + Creating a feature branch in your + kernel source repository and merging that branch into your + BSP when needed. + + + + + The approach you take is entirely up to you + and depends on what works best for your development model. + + +
+ Encapsulating Patches + + + if you are reusing patches from an external tree and are not + working on the patches, you might find the encapsulated feature + to be appropriate. + Given this scenario, you do not need to create any branches in the + source repository. + Rather, you just take the static patches you need and encapsulate + them within a feature description. + Once you have the feature description, you simply include that into + the BSP description as described in the + "BSP Descriptions" + section. + + + + You can find information on how to create patches and BSP + descriptions in the "Patches" and + "BSP Descriptions" + sections. + +
+ +
+ Machine Branches + + + When you have multiple machines and architectures to support, + or you are actively working on board support, it is more + efficient to create branches in the repository based on + individual machines. + Having machine branches allows common source to remain in the + "master" branch with any features specific to a machine stored + in the appropriate machine branch. + This organization method frees you from continually reintegrating + your patches into a feature. + + + + Once you have a new branch, you can set up your kernel Metadata + to use the branch a couple different ways. + In the recipe, you can specify the new branch as the + KBRANCH to use for the board as + follows: + + KBRANCH = "mynewbranch" + + Another method is to use the branch command + in the BSP description: + + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + include standard.scc + + branch mynewbranch + + include mybsp-hw.scc + + + + + If you find + yourself with numerous branches, you might consider using a + hierarchical branching system similar to what the linux-yocto Linux + kernel repositories use: + + common/kernel_type/machine + + + + + If you had two kernel types, "standard" and "small" for + instance, three machines, and common + as mydir, the branches in your + Git repository might look like this: + + mydir/base + mydir/standard/base + mydir/standard/machine_a + mydir/standard/machine_b + mydir/standard/machine_c + mydir/small/base + mydir/small/machine_a + + + + + This organization can help clarify the branch relationships. + In this case, mydir/standard/machine_a + includes everything in mydir/base and + mydir/standard/base. + The "standard" and "small" branches add sources specific to those + kernel types that for whatever reason are not appropriate for the + other branches. + The "base" branches are an artifact of the way Git manages + its data internally on the filesystem: Git will not allow you + to use mydir/standard and + mydir/standard/machine_a because it + would have to create a file and a directory named "standard". + + +
+ +
+ Feature Branches + + + When you are actively developing new features, it can be more + efficient to work with that feature as a branch, rather than + as a set of patches that have to be regularly updated. + The Yocto Project Linux kernel tools provide for this with + the git merge command. + + + + To merge a feature branch into a BSP, insert the + git merge command after any + branch commands: + + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + include standard.scc + + branch mynewbranch + git merge myfeature + + include mybsp-hw.scc + + +
+
+ +
+ SCC Description File Reference + + + This section provides a brief reference for the commands you can use + within an SCC description file (.scc): + + branch [ref]: + Creates a new branch relative to the current branch + (typically ${KTYPE}) using + the currently checked-out branch, or "ref" if specified. + + define: + Defines variables, such as KMACHINE, + KTYPE, KARCH, + and KFEATURE_DESCRIPTION. + include SCC_FILE: + Includes an SCC file in the current file. + The file is parsed as if you had inserted it inline. + + kconf [hardware|non-hardware] CFG_FILE: + Queues a configuration fragment for merging into the final + Linux .config file. + git merge GIT_BRANCH: + Merges the feature branch into the current branch. + + patch PATCH_FILE: + Applies the patch to the current Git branch. + + +
+ +
+ diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml new file mode 100644 index 0000000000..58cc98ddff --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -0,0 +1,915 @@ + %poky; ] > + + + +Common Tasks + + + This chapter presents several common tasks you perform when you + work with the Yocto Project Linux kernel. + These tasks include preparing a layer, modifying an existing recipe, + iterative development, working with your own sources, and incorporating + out-of-tree modules. + + The examples presented in this chapter work with the Yocto Project + 1.2.2 Release and forward. + + + +
+ Creating and Preparing a Layer + + + If you are going to be modifying kernel recipes, it is recommended + that you create and prepare your own layer in which to do your + work. + Your layer contains its own + BitBake + append files + (.bbappend) and provides a convenient + mechanism to create your own recipe files + (.bb). + For details on how to create and work with layers, see the following + sections in the Yocto Project Development Manual: + + "Understanding and Creating Layers" for + general information on layers and how to create layers. + "Set Up Your Layer for the Build" for + specific instructions on setting up a layer for kernel + development. + + +
+ +
+ Modifying an Existing Recipe + + + In many cases, you can customize an existing linux-yocto recipe to + meet the needs of your project. + Each release of the Yocto Project provides a few Linux + kernel recipes from which you can choose. + These are located in the + Source Directory + in meta/recipes-kernel/linux. + + + + Modifying an existing recipe can consist of the following: + + Creating the append file + Applying patches + Changing the configuration + + + + + Before modifying an existing recipe, be sure that you have created + a minimal, custom layer from which you can work. + See the "Creating and Preparing a Layer" + section for some general resources. + You can also see the + "Set Up Your Layer for the Build" section + of the Yocto Project Development Manual for a detailed + example. + + +
+ Creating the Append File + + + You create this file in your custom layer. + You also name it accordingly based on the linux-yocto recipe + you are using. + For example, if you are modifying the + meta/recipes-kernel/linux/linux-yocto_3.4.bb + recipe, the append file will typically be located as follows + within your custom layer: + + your-layer/recipes-kernel/linux/linux-yocto_3.4.bbappend + + The append file should initially extend the + FILESPATH + search path by prepending the directory that contains your + files to the + FILESEXTRAPATHS + variable as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + The path ${THISDIR}/${PN} + expands to "linux-yocto" in the current directory for this + example. + If you add any new files that modify the kernel recipe and you + have extended FILESPATH as + described above, you must place the files in your layer in the + following area: + + your-layer/recipes-kernel/linux/linux-yocto/ + + If you are working on a new machine Board Support Package + (BSP), be sure to refer to the + Yocto Project Board Support Package (BSP) Developer's Guide. + + +
+ +
+ Applying Patches + + + If you have a single patch or a small series of patches + that you want to apply to the Linux kernel source, you + can do so just as you would with any other recipe. + You first copy the patches to the path added to + FILESEXTRAPATHS + in your .bbappend file as described in + the previous section, and then reference them in + SRC_URI + statements. + + + + For example, you can apply a three-patch series by adding the + following lines to your linux-yocto .bbappend + file in your layer: + + SRC_URI += "file://0001-first-change.patch" + SRC_URI += "file://0002-first-change.patch" + SRC_URI += "file://0003-first-change.patch" + + The next time you run BitBake to build the Linux kernel, BitBake + detects the change in the recipe and fetches and applies the patches + before building the kernel. + + + + For a detailed example showing how to patch the kernel, see the + "Patching the Kernel" + section in the Yocto Project Development Manual. + +
+ +
+ Changing the Configuration + + + You can make wholesale or incremental changes to the Linux + kernel .config file by including a + defconfig and by specifying + configuration fragments in the + SRC_URI. + + + + If you have a final Linux kernel .config + file you want to use, copy it to a directory named + files, which must be in + your layer's recipes-kernel/linux + directory, and name the file "defconfig". + Then, add the following lines to your linux-yocto + .bbappend file in your layer: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + SRC_URI += "file://defconfig" + + The SRC_URI tells the build system how to + search for the file, while the + FILESEXTRAPATHS + extends the + FILESPATH + variable (search directories) to include the + files directory you created for the + configuration changes. + + + + The build system applies the configurations from the + .config file before applying any + subsequent configuration fragments. + The final kernel configuration is a combination of the + configurations in the .config file and + any configuration fragments you provide. + You need to realize that if you have any configuration + fragments, the build system applies these on top of and + after applying the existing .config + file configurations. + + + + Generally speaking, the preferred approach is to determine the + incremental change you want to make and add that as a + configuration fragment. + For example, if you want to add support for a basic serial + console, create a file named 8250.cfg in + the files directory with the following + content (without indentation): + + CONFIG_SERIAL_8250=y + CONFIG_SERIAL_8250_CONSOLE=y + CONFIG_SERIAL_8250_PCI=y + CONFIG_SERIAL_8250_NR_UARTS=4 + CONFIG_SERIAL_8250_RUNTIME_UARTS=4 + CONFIG_SERIAL_CORE=y + CONFIG_SERIAL_CORE_CONSOLE=y + + Next, include this configuration fragment and extend the + FILESPATH variable in your + .bbappend file: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + SRC_URI += "file://8250.cfg" + + The next time you run BitBake to build the Linux kernel, BitBake + detects the change in the recipe and fetches and applies the + new configuration before building the kernel. + + + + For a detailed example showing how to configure the kernel, + see the + "Configuring the Kernel" + section in the Yocto Project Development Manual. + +
+
+ +
+ Using an Iterative Development Process + + + If you do not have existing patches or configuration files, + you can iteratively generate them from within the BitBake build + environment as described within this section. + During an iterative workflow, running a previously completed BitBake + task causes BitBake to invalidate the tasks that follow the + completed task in the build sequence. + Invalidated tasks rebuild the next time you run the build using + BitBake. + + + + As you read this section, be sure to substitute the name + of your Linux kernel recipe for the term + "linux-yocto". + + +
+ "-dirty" String + + + + + If kernel images are being built with "-dirty" on the + end of the version string, this simply means that + modifications in the source directory have not been committed. + + $ git status + + + + + You can use the above Git command to report modified, + removed, or added files. + You should commit those changes to the tree regardless of + whether they will be saved, exported, or used. + Once you commit the changes, you need to rebuild the kernel. + + + + To force a pickup and commit of all such pending changes, + enter the following: + + $ git add . + $ git commit -s -a -m "getting rid of -dirty" + + + + + Next, rebuild the kernel. + +
+ +
+ Generating Configuration Files + + + You can manipulate the .config file + used to build a linux-yocto recipe with the + menuconfig command as follows: + + $ bitbake linux-yocto -c menuconfig + + This command starts the Linux kernel configuration tool, + which allows you to prepare a new + .config file for the build. + When you exit the tool, be sure to save your changes + at the prompt. + + + + The resulting .config file is + located in + ${WORKDIR} under the + linux-${MACHINE}-${KTYPE}-build directory. + You can use the entire .config file as the + defconfig file as described in the + "Changing the Configuration" section. + + + + A better method is to create a configuration fragment using the + differences between two configuration files: one previously + created and saved, and one freshly created using the + menuconfig tool. + + + + To create a configuration fragment using this method, follow + these steps: + + Complete a build at least through the kernel + configuration task as follows: + + $ bitbake linux-yocto -c kernel_configme -f + + Run the menuconfig + command: + + $ bitbake linux-yocto -c menuconfig + + Run the diffconfig + command to prepare a configuration fragment. + The resulting file fragment.cfg + will be placed in the + ${WORKDIR} directory: + + $ bitbake linux-yocto -c diffconfig + + + + + + The diffconfig command creates a file that is a + list of Linux kernel CONFIG_ assignments. + See the "Changing the Configuration" + section for information on how to use the output as a + configuration fragment. + + You can also use this method to create configuration + fragments for a BSP. + See the "BSP Descriptions" + section for more information. + + + + + The kernel tools also provide configuration validation. + You can use these tools to produce warnings for when a + requested configuration does not appear in the final + .config file or when you override a + policy configuration in a hardware configuration fragment. + Here is an example with some sample output of the command + that runs these tools: + + $ bitbake linux-yocto -c kernel_configcheck -f + + ... + + NOTE: validating kernel configuration + This BSP sets 3 invalid/obsolete kernel options. + These config options are not offered anywhere within this kernel. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/invalid.cfg + + This BSP sets 21 kernel options that are possibly non-hardware related. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/specified_non_hdw.cfg + + WARNING: There were 2 hardware options requested that do not + have a corresponding value present in the final ".config" file. + This probably means you are not't getting the config you wanted. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/mismatch.cfg + + + + + The output describes the various problems that you can + encounter along with where to find the offending configuration + items. + You can use the information in the logs to adjust your + configuration files and then repeat the + kernel_configme and + kernel_configcheck commands until + they produce no warnings. + + + + For more information on how to use the + menuconfig tool, see the + "Using menuconfig" + section in the Yocto Project Development Manual. + +
+ +
+ Modifying Source Code + + + You can experiment with source code changes and create a + simple patch without leaving the BitBake environment. + To get started, be sure to complete a build at + least through the kernel configuration task: + + $ bitbake linux-yocto -c kernel_configme -f + + Taking this step ensures you have the sources prepared + and the configuration completed. + You can find the sources in the + ${WORKDIR}/linux directory. + + + + You can edit the sources as you would any other Linux source + tree. + However, keep in mind that you will lose changes if you + trigger the + do_fetch + task for the recipe. + You can avoid triggering this task by not using BitBake to + run the + cleanall, + cleansstate, + or forced + fetch + commands. + Also, do not modify the recipe itself while working + with temporary changes or BitBake might run the + fetch command depending on the + changes to the recipe. + + + + To test your temporary changes, instruct BitBake to run the + compile again. + The -f option forces the command to run + even though BitBake might think it has already done so: + + $ bitbake linux-yocto -c compile -f + + If the compile fails, you can update the sources and repeat + the compile. + Once compilation is successful, you can inspect and test + the resulting build (i.e. kernel, modules, and so forth) from + the Build Directory: + + ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build + + Alternatively, you can run the deploy + command to place the kernel image in the + tmp/deploy/images directory: + + $ bitbake linux-yocto -c deploy + + And, of course, you can perform the remaining installation and + packaging steps by issuing: + + $ bitbake linux-yocto + + + + + For rapid iterative development, the edit-compile-repeat loop + described in this section is preferable to rebuilding the + entire recipe because the installation and packaging tasks + are very time consuming. + + + + Once you are satisfied with your source code modifications, + you can make them permanent by generating patches and + applying them to the + SRC_URI + statement as described in the + "Applying Patches" + section. + If you are not familiar with generating patches, refer to the + "Creating the Patch" + section in the Yocto Project Development Manual. + +
+
+ +
+ Working With Your Own Sources + + + If you cannot work with one of the Linux kernel + versions supported by existing linux-yocto recipes, you can + still make use of the Yocto Project Linux kernel tooling by + working with your own sources. + When you use your own sources, you will not be able to + leverage the existing kernel + Metadata and + stabilization work of the linux-yocto sources. + However, you will be able to manage your own Metadata in the same + format as the linux-yocto sources. + Maintaining format compatibility facilitates converging with + linux-yocto on a future, mutually-supported kernel version. + + + + To help you use your own sources, the Yocto Project provides a + linux-yocto custom recipe + (linux-yocto-custom.bb) that uses + kernel.org sources + and the Yocto Project Linux kernel tools for managing + kernel Metadata. + You can find this recipe in the + poky Git repository of the + Yocto Project Source Repository + at: + + poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb + + + + + Here are some basic steps you can use to work with your own sources: + + Copy the linux-yocto-custom.bb + recipe to your layer and give it a meaningful name. + The name should include the version of the Linux kernel you + are using (e.g. linux-yocto-myproject_3.5.bb, + where "3.5" is the base version of the Linux kernel + with which you would be working). + In the same directory inside your layer, + create a matching directory + to store your patches and configuration files (e.g. + linux-yocto-myproject). + + Edit the following variables in your recipe + as appropriate for your project: + + SRC_URI: + The SRC_URI should be a Git + repository that uses one of the supported Git fetcher + protocols (i.e. file, + git, http, + and so forth). + The skeleton recipe provides an example + SRC_URI as a syntax reference. + + LINUX_VERSION: + The Linux kernel version you are using (e.g. + "3.4"). + LINUX_VERSION_EXTENSION: + The Linux kernel CONFIG_LOCALVERSION + that is compiled into the resulting kernel and visible + through the uname command. + + SRCREV: + The commit ID from which you want to build. + + PR: + Treat this variable the same as you would in any other + recipe. + Increment the variable to indicate to the OpenEmbedded + build system that the recipe has changed. + + PV: + The default PV assignment is + typically adequate. + It combines the LINUX_VERSION + with the Source Control Manager (SCM) revision + as derived from the + SRCPV + variable. + The combined results are a string with + the following form: + + 3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 + + While lengthy, the extra verbosity in PV + helps ensure you are using the exact + sources from which you intend to build. + + COMPATIBLE_MACHINE: + A list of the machines supported by your new recipe. + This variable in the example recipe is set + by default to a regular expression that matches + only the empty string, "(^$)". + This default setting triggers an explicit build + failure. + You must change it to match a list of the machines + that your new recipe supports. + For example, to support the qemux86 + and qemux86-64 machines, use + the following form: + + COMPATIBLE_MACHINE = "qemux86|qemux86-64" + + + Provide further customizations to your recipe + as needed just as you would customize an existing + linux-yocto recipe. + See the "Modifying + an Existing Recipe" section for information. + + + +
+ +
+ Working with Out-of-Tree Modules + + + This section describes steps to build out-of-tree modules on + your target and describes how to incorporate out-of-tree modules + in the build. + + +
+ Building Out-of-Tree Modules on the Target + + + If you want to be able to build out-of-tree modules on + the target, there are some steps you need to take + on the target that is running your SDK image. + Briefly, the kernel-dev package + is installed by default on all + *.sdk images. + However, you need to create some scripts prior to + attempting to build the out-of-tree modules on the target + that is running that image. + + + + Prior to attempting to build the out-of-tree modules, + you need to be on the target as root and you need to + change to the /usr/src/kernel directory. + Next, make the scripts: + + # cd /usr/src/kernel + # make scripts + + Because all SDK image recipes include + dev-pkgs, the + kernel-dev packages will be installed + as part of the SDK image. + The SDK uses the scripts when building out-of-tree + modules. + Once you have switched to that directory and created the + scripts, you should be able to build your out-of-tree modules + on the target. + +
+ +
+ Incorporating Out-of-Tree Modules + + + While it is always preferable to work with sources integrated + into the Linux kernel sources, if you need an external kernel + module, the hello-mod.bb recipe is + available as a template from which you can create your + own out-of-tree Linux kernel module recipe. + + + + This template recipe is located in the + poky Git repository of the + Yocto Project Source Repository + at: + + poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb + + + + + To get started, copy this recipe to your layer and give it a + meaningful name (e.g. mymodule_1.0.bb). + In the same directory, create a new directory named + files where you can store any source files, + patches, or other files necessary for building + the module that do not come with the sources. + Finally, update the recipe as needed for the module. + Typically, you will need to set the following variables: + + DESCRIPTION + + LICENSE* + + SRC_URI + + PV + + + + + + Depending on the build system used by the module sources, + you might need to make some adjustments. + For example, a typical module Makefile + looks much like the one provided with the + hello-mod template: + + obj-m := hello.o + + SRC := $(shell pwd) + + all: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) + + modules_install: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install + ... + + + + + The important point to note here is the + KERNEL_SRC + variable. + The + module + class sets this variable and the + KERNEL_PATH + variable to + ${STAGING_KERNEL_DIR} + with the necessary Linux kernel build information to build + modules. + If your module Makefile uses a different + variable, you might want to override the + do_compile() + step, or create a patch to + the Makefile to work with the more typical + KERNEL_SRC or + KERNEL_PATH variables. + + + + After you have prepared your recipe, you will likely want to + include the module in your images. + To do this, see the documentation for the following variables in + the Yocto Project Reference Manual and set one of them + appropriately for your machine configuration file: + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS + + MACHINE_EXTRA_RDEPENDS + + MACHINE_EXTRA_RRECOMMENDS + + + + + + Modules are often not required for boot and can be excluded from + certain build configurations. + The following allows for the most flexibility: + + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" + + The value is derived by appending the module filename without + the .ko extension to the string + "kernel-module-". + + + + Because the variable is + RRECOMMENDS + and not a + RDEPENDS + variable, the build will not fail if this module is not + available to include in the image. + +
+
+ + +
+ Inspecting Changes and Commits + + + A common question when working with a kernel is: + "What changes have been applied to this tree?" + Rather than using "grep" across directories to see what has + changed, you can use Git to inspect or search the kernel tree. + Using Git is an efficient way to see what has changed in the tree. + + +
+ What Changed in a Kernel? + + + Following are a few examples that show how to use Git + commands to examine changes. + These examples are by no means the only way to see changes. + + In the following examples, unless you provide a commit + range, kernel.org history is blended + with Yocto Project kernel changes. + You can form ranges by using branch names from the + kernel tree as the upper and lower commit markers with + the Git commands. + You can see the branch names through the web interface + to the Yocto Project source repositories at + . + + To see a full range of the changes, use the + git whatchanged command and specify a + commit range for the branch + (<commit>..<commit>). + + + + Here is an example that looks at what has changed in the + emenlow branch of the + linux-yocto-3.4 kernel. + The lower commit range is the commit associated with the + standard/base branch, while + the upper commit range is the commit associated with the + standard/emenlow branch. + + $ git whatchanged origin/standard/base..origin/standard/emenlow + + + + + To see short, one line summaries of changes use the + git log command: + + $ git log --oneline origin/standard/base..origin/standard/emenlow + + + + + Use this command to see code differences for the changes: + + $ git diff origin/standard/base..origin/standard/emenlow + + + + + Use this command to see the commit log messages and the + text differences: + + $ git show origin/standard/base..origin/standard/emenlow + + + + + Use this command to create individual patches for + each change. + Here is an example that that creates patch files for each + commit and places them in your Documents + directory: + + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + + +
+ +
+ Showing a Particular Feature or Branch Change + + + Tags in the Yocto Project kernel tree divide changes for + significant features or branches. + The git show <tag> command shows + changes based on a tag. + Here is an example that shows systemtap + changes: + + $ git show systemtap + + You can use the + git branch --contains <tag> command + to show the branches that contain a particular feature. + This command shows the branches that contain the + systemtap feature: + + $ git branch --contains systemtap + + +
+
+
+ diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml new file mode 100644 index 0000000000..ac91749cd6 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml @@ -0,0 +1,253 @@ + %poky; ] > + + +Advanced Kernel Concepts + +
+ Yocto Project Kernel Development and Maintenance + + Kernels available through the Yocto Project, like other kernels, are based off the Linux + kernel releases from . + At the beginning of a major development cycle, the Yocto Project team + chooses its kernel based on factors such as release timing, the anticipated release + timing of final upstream kernel.org versions, and Yocto Project + feature requirements. + Typically, the kernel chosen is in the + final stages of development by the community. + In other words, the kernel is in the release + candidate or "rc" phase and not yet a final release. + But, by being in the final stages of external development, the team knows that the + kernel.org final release will clearly be within the early stages of + the Yocto Project development window. + + + This balance allows the team to deliver the most up-to-date kernel + possible, while still ensuring that the team has a stable official release for + the baseline Linux kernel version. + + + The ultimate source for kernels available through the Yocto Project are released kernels + from kernel.org. + In addition to a foundational kernel from kernel.org, the + kernels available contain a mix of important new mainline + developments, non-mainline developments (when there is no alternative), + Board Support Package (BSP) developments, + and custom features. + These additions result in a commercially released Yocto Project Linux kernel that caters + to specific embedded designer needs for targeted hardware. + + + Once a kernel is officially released, the Yocto Project team goes into + their next development cycle, or upward revision (uprev) cycle, while still + continuing maintenance on the released kernel. + It is important to note that the most sustainable and stable way + to include feature development upstream is through a kernel uprev process. + Back-porting hundreds of individual fixes and minor features from various + kernel versions is not sustainable and can easily compromise quality. + + + During the uprev cycle, the Yocto Project team uses an ongoing analysis of + kernel development, BSP support, and release timing to select the best + possible kernel.org version. + The team continually monitors community kernel + development to look for significant features of interest. + The team does consider back-porting large features if they have a significant advantage. + User or community demand can also trigger a back-port or creation of new + functionality in the Yocto Project baseline kernel during the uprev cycle. + + + Generally speaking, every new kernel both adds features and introduces new bugs. + These consequences are the basic properties of upstream kernel development and are + managed by the Yocto Project team's kernel strategy. + It is the Yocto Project team's policy to not back-port minor features to the released kernel. + They only consider back-porting significant technological jumps - and, that is done + after a complete gap analysis. + The reason for this policy is that back-porting any small to medium sized change + from an evolving kernel can easily create mismatches, incompatibilities and very + subtle errors. + + + These policies result in both a stable and a cutting + edge kernel that mixes forward ports of existing features and significant and critical + new functionality. + Forward porting functionality in the kernels available through the Yocto Project kernel + can be thought of as a "micro uprev." + The many “micro uprevs” produce a kernel version with a mix of + important new mainline, non-mainline, BSP developments and feature integrations. + This kernel gives insight into new features and allows focused + amounts of testing to be done on the kernel, which prevents + surprises when selecting the next major uprev. + The quality of these cutting edge kernels is evolving and the kernels are used in leading edge + feature and BSP development. + +
+ +
+ Kernel Architecture + + This section describes the architecture of the kernels available through the + Yocto Project and provides information + on the mechanisms used to achieve that architecture. + + +
+ Overview + + As mentioned earlier, a key goal of the Yocto Project is to present the + developer with + a kernel that has a clear and continuous history that is visible to the user. + The architecture and mechanisms used achieve that goal in a manner similar to the + upstream kernel.org. + + + You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with + added features logically structured on top of the baseline. + The features are tagged and organized by way of a branching strategy implemented by the + source code manager (SCM) Git. + For information on Git as applied to the Yocto Project, see the + "Git" section in the + Yocto Project Development Manual. + + + The result is that the user has the ability to see the added features and + the commits that make up those features. + In addition to being able to see added features, the user can also view the history of what + made up the baseline kernel. + + + The following illustration shows the conceptual Yocto Project kernel. + + + + + + In the illustration, the "Kernel.org Branch Point" + marks the specific spot (or release) from + which the Yocto Project kernel is created. + From this point "up" in the tree, features and differences are organized and tagged. + + + The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel + type and BSP that is organized further up the tree. + Placing these common features in the + tree this way means features do not have to be duplicated along individual branches of the + structure. + + + From the Yocto Project Baseline Kernel, branch points represent specific functionality + for individual BSPs as well as real-time kernels. + The illustration represents this through three BSP-specific branches and a real-time + kernel branch. + Each branch represents some unique functionality for the BSP or a real-time kernel. + + + In this example structure, the real-time kernel branch has common features for all + real-time kernels and contains + more branches for individual BSP-specific real-time kernels. + The illustration shows three branches as an example. + Each branch points the way to specific, unique features for a respective real-time + kernel as they apply to a given BSP. + + + The resulting tree structure presents a clear path of markers (or branches) to the + developer that, for all practical purposes, is the kernel needed for any given set + of requirements. + +
+ +
+ Branching Strategy and Workflow + + The Yocto Project team creates kernel branches at points where functionality is + no longer shared and thus, needs to be isolated. + For example, board-specific incompatibilities would require different functionality + and would require a branch to separate the features. + Likewise, for specific kernel features, the same branching strategy is used. + + + This branching strategy results in a tree that has features organized to be specific + for particular functionality, single kernel types, or a subset of kernel types. + This strategy also results in not having to store the same feature twice + internally in the tree. + Rather, the kernel team stores the unique differences required to apply the + feature onto the kernel type in question. + + The Yocto Project team strives to place features in the tree such that they can be + shared by all boards and kernel types where possible. + However, during development cycles or when large features are merged, + the team cannot always follow this practice. + In those cases, the team uses isolated branches to merge features. + + + + BSP-specific code additions are handled in a similar manner to kernel-specific additions. + Some BSPs only make sense given certain kernel types. + So, for these types, the team creates branches off the end of that kernel type for all + of the BSPs that are supported on that kernel type. + From the perspective of the tools that create the BSP branch, the BSP is really no + different than a feature. + Consequently, the same branching strategy applies to BSPs as it does to features. + So again, rather than store the BSP twice, the team only stores the unique + differences for the BSP across the supported multiple kernels. + + + While this strategy can result in a tree with a significant number of branches, it is + important to realize that from the developer's point of view, there is a linear + path that travels from the baseline kernel.org, through a select + group of features and ends with their BSP-specific commits. + In other words, the divisions of the kernel are transparent and are not relevant + to the developer on a day-to-day basis. + From the developer's perspective, this path is the "master" branch. + The developer does not need to be aware of the existence of any other branches at all. + Of course, there is value in the existence of these branches + in the tree, should a person decide to explore them. + For example, a comparison between two BSPs at either the commit level or at the line-by-line + code diff level is now a trivial operation. + + + Working with the kernel as a structured tree follows recognized community best practices. + In particular, the kernel as shipped with the product, should be + considered an "upstream source" and viewed as a series of + historical and documented modifications (commits). + These modifications represent the development and stabilization done + by the Yocto Project kernel development team. + + + Because commits only change at significant release points in the product life cycle, + developers can work on a branch created + from the last relevant commit in the shipped Yocto Project kernel. + As mentioned previously, the structure is transparent to the developer + because the kernel tree is left in this state after cloning and building the kernel. + +
+ +
+ Source Code Manager - Git + + The Source Code Manager (SCM) is Git. + This SCM is the obvious mechanism for meeting the previously mentioned goals. + Not only is it the SCM for kernel.org but, + Git continues to grow in popularity and supports many different work flows, + front-ends and management techniques. + + + You can find documentation on Git at . + You can also get an introduction to Git as it applies to the Yocto Project in the + "Git" + section in the Yocto Project Development Manual. + These referenced sections overview Git and describe a minimal set of + commands that allows you to be functional using Git. + + You can use as much, or as little, of what Git has to offer to accomplish what + you need for your project. + You do not have to be a "Git Master" in order to use it with the Yocto Project. + + +
+
+
+ diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl new file mode 100644 index 0000000000..8676d66c3a --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-customization.xsl @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + A + + + + diff --git a/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl new file mode 100644 index 0000000000..7d1bb8dc08 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + A + + + diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml new file mode 100644 index 0000000000..9d9aef6d06 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-examples.xml @@ -0,0 +1,918 @@ + %poky; ] > + + + +Working with the Yocto Project Kernel + + +
+ Introduction + + This chapter describes how to accomplish tasks involving a kernel's tree structure. + The information is designed to help the developer that wants to modify the Yocto + Project kernel and contribute changes upstream to the Yocto Project. + The information covers the following: + + Tree construction + Build strategies + Workflow examples + + +
+ +
+ Tree Construction + + This section describes construction of the Yocto Project kernel source repositories + as accomplished by the Yocto Project team to create kernel repositories. + These kernel repositories are found under the heading "Yocto Linux Kernel" at + &YOCTO_GIT_URL;/cgit.cgi + and can be shipped as part of a Yocto Project release. + The team creates these repositories by + compiling and executing the set of feature descriptions for every BSP/feature + in the product. + Those feature descriptions list all necessary patches, + configuration, branching, tagging and feature divisions found in a kernel. + Thus, the Yocto Project kernel repository (or tree) is built. + + + The existence of this tree allows you to access and clone a particular + Yocto Project kernel repository and use it to build images based on their configurations + and features. + + + You can find the files used to describe all the valid features and BSPs + in the Yocto Project kernel in any clone of the Yocto Project kernel source repository + Git tree. + For example, the following command clones the Yocto Project baseline kernel that + branched off of linux.org version 3.4: + + $ git clone git://git.yoctoproject.org/linux-yocto-3.4 + + For another example of how to set up a local Git repository of the Yocto Project + kernel files, see the + "Yocto Project Kernel" bulleted + item in the Yocto Project Development Manual. + + + Once you have cloned the kernel Git repository on your local machine, you can + switch to the meta branch within the repository. + Here is an example that assumes the local Git repository for the kernel is in + a top-level directory named linux-yocto-3.4: + + $ cd ~/linux-yocto-3.4 + $ git checkout -b meta origin/meta + + Once you have checked out and switched to the meta branch, + you can see a snapshot of all the kernel configuration and feature descriptions that are + used to build that particular kernel repository. + These descriptions are in the form of .scc files. + + + You should realize, however, that browsing your local kernel repository + for feature descriptions and patches is not an effective way to determine what is in a + particular kernel branch. + Instead, you should use Git directly to discover the changes in a branch. + Using Git is an efficient and flexible way to inspect changes to the kernel. + For examples showing how to use Git to inspect kernel commits, see the following sections + in this chapter. + + Ground up reconstruction of the complete kernel tree is an action only taken by the + Yocto Project team during an active development cycle. + When you create a clone of the kernel Git repository, you are simply making it + efficiently available for building and development. + + + + The following steps describe what happens when the Yocto Project Team constructs + the Yocto Project kernel source Git repository (or tree) found at + given the + introduction of a new top-level kernel feature or BSP. + These are the actions that effectively create the tree + that includes the new feature, patch or BSP: + + A top-level kernel feature is passed to the kernel build subsystem. + Normally, this feature is a BSP for a particular kernel type. + The file that describes the top-level feature is located by searching + these system directories: + + The in-tree kernel-cache directories, which are located + in meta/cfg/kernel-cache + Areas pointed to by SRC_URI statements + found in recipes + + For a typical build, the target of the search is a + feature description in an .scc file + whose name follows this format: + + <bsp_name>-<kernel_type>.scc + + + Once located, the feature description is either compiled into a simple script + of actions, or into an existing equivalent script that is already part of the + shipped kernel. + Extra features are appended to the top-level feature description. + These features can come from the + KERNEL_FEATURES + variable in recipes. + Each extra feature is located, compiled and appended to the script + as described in step three. + The script is executed to produce a series of meta-* + directories. + These directories are descriptions of all the branches, tags, patches and configurations that + need to be applied to the base Git repository to completely create the + source (build) branch for the new BSP or feature. + The base repository is cloned, and the actions + listed in the meta-* directories are applied to the + tree. + The Git repository is left with the desired branch checked out and any + required branching, patching and tagging has been performed. + + + + The kernel tree is now ready for developer consumption to be locally cloned, + configured, and built into a Yocto Project kernel specific to some target hardware. + The generated meta-* directories add to the kernel + as shipped with the Yocto Project release. + Any add-ons and configuration data are applied to the end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + http://git.yoctoproject.org/cgit.cgi + is the combination of all supported boards and configurations. + The technique the Yocto Project team uses is flexible and allows for seamless + blending of an immutable history with additional patches specific to a + deployment. + Any additions to the kernel become an integrated part of the branches. + + +
+ +
+ Build Strategy + + Once a local Git repository of the Yocto Project kernel exists on a development system, + you can consider the compilation phase of kernel development - building a kernel image. + Some prerequisites exist that are validated by the build process before compilation + starts: + + + + The + SRC_URI points + to the kernel Git repository. + A BSP build branch exists. + This branch has the following form: + + <kernel_type>/<bsp_name> + + + + + The OpenEmbedded build system makes sure these conditions exist before attempting compilation. + Other means, however, do exist, such as as bootstrapping a BSP, see + the "Workflow Examples". + + + + Before building a kernel, the build process verifies the tree + and configures the kernel by processing all of the + configuration "fragments" specified by feature descriptions in the .scc + files. + As the features are compiled, associated kernel configuration fragments are noted + and recorded in the meta-* series of directories in their compilation order. + The fragments are migrated, pre-processed and passed to the Linux Kernel + Configuration subsystem (lkc) as raw input in the form + of a .config file. + The lkc uses its own internal dependency constraints to do the final + processing of that information and generates the final .config file + that is used during compilation. + + + + Using the board's architecture and other relevant values from the board's template, + kernel compilation is started and a kernel image is produced. + + + + The other thing that you notice once you configure a kernel is that + the build process generates a build tree that is separate from your kernel's local Git + source repository tree. + This build tree has a name that uses the following form, where + ${MACHINE} is the metadata name of the machine (BSP) and "kernel_type" is one + of the Yocto Project supported kernel types (e.g. "standard"): + + linux-${MACHINE}-<kernel_type>-build + + + + + The existing support in the kernel.org tree achieves this + default functionality. + + + + This behavior means that all the generated files for a particular machine or BSP are now in + the build tree directory. + The files include the final .config file, all the .o + files, the .a files, and so forth. + Since each machine or BSP has its own separate build directory in its own separate branch + of the Git repository, you can easily switch between different builds. + +
+ +
+ Workflow Examples + + + As previously noted, the Yocto Project kernel has built-in Git integration. + However, these utilities are not the only way to work with the kernel repository. + The Yocto Project has not made changes to Git or to other tools that + would invalidate alternate workflows. + Additionally, the way the kernel repository is constructed results in using + only core Git functionality, thus allowing any number of tools or front ends to use the + resulting tree. + + + + This section contains several workflow examples. + Many of the examples use Git commands. + You can find Git documentation at + . + You can find a simple overview of using Git with the Yocto Project in the + "Git" + section of the Yocto Project Development Manual. + + +
+ Change Inspection: Changes/Commits + + + A common question when working with a kernel is: + "What changes have been applied to this tree?" + + + + In projects that have a collection of directories that + contain patches to the kernel, it is possible to inspect or "grep" the contents + of the directories to get a general feel for the changes. + This sort of patch inspection is not an efficient way to determine what has been + done to the kernel. + The reason it is inefficient is because there are many optional patches that are + selected based on the kernel type and the feature description. + Additionally, patches could exist in directories that are not included in the search. + + + + A more efficient way to determine what has changed in the branch is to use + Git and inspect or search the kernel tree. + This method gives you a full view of not only the source code modifications, + but also provides the reasons for the changes. + + +
+ What Changed in a Kernel? + + + Following are a few examples that show how to use Git commands to examine changes. + Because Git repositories in the Yocto Project do not break existing Git + functionality, and because there exists many permutations of these types of + Git commands, many methods exist by which you can discover changes. + + In the following examples, unless you provide a commit range, + kernel.org history is blended with Yocto Project + kernel changes. + You can form ranges by using branch names from the kernel tree as the + upper and lower commit markers with the Git commands. + You can see the branch names through the web interface to the + Yocto Project source repositories at + . + For example, the branch names for the linux-yocto-3.4 + kernel repository can be seen at + . + + To see a full range of the changes, use the + git whatchanged command and specify a commit range + for the branch (<commit>..<commit>). + + + + Here is an example that looks at what has changed in the + emenlow branch of the + linux-yocto-3.4 kernel. + The lower commit range is the commit associated with the + standard/base branch, while + the upper commit range is the commit associated with the + standard/emenlow branch. + + $ git whatchanged origin/standard/base..origin/standard/emenlow + + + + + To see a summary of changes use the git log command. + Here is an example using the same branches: + + $ git log --oneline origin/standard/base..origin/standard/emenlow + + The git log output might be more useful than + the git whatchanged as you get + a short, one-line summary of each change and not the entire commit. + + + + If you want to see code differences associated with all the changes, use + the git diff command. + Here is an example: + + $ git diff origin/standard/base..origin/standard/emenlow + + + + + You can see the commit log messages and the text differences using the + git show command: + Here is an example: + + $ git show origin/standard/base..origin/standard/emenlow + + + + + You can create individual patches for each change by using the + git format-patch command. + Here is an example that that creates patch files for each commit and + places them in your Documents directory: + + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + + +
+ +
+ Show a Particular Feature or Branch Change + + + Developers use tags in the Yocto Project kernel tree to divide changes for significant + features or branches. + Once you know a particular tag, you can use Git commands + to show changes associated with the tag and find the branches that contain + the feature. + + Because BSP branch, kernel.org, and feature tags are all + present, there could be many tags. + + The git show <tag> command shows changes that are tagged by + a feature. + Here is an example that shows changes tagged by the systemtap + feature: + + $ git show systemtap + + You can use the git branch --contains <tag> command + to show the branches that contain a particular feature. + This command shows the branches that contain the systemtap + feature: + + $ git branch --contains systemtap + + + + + You can use many other comparisons to isolate BSP and kernel changes. + For example, you can compare against kernel.org tags + such as the v3.4 tag. + +
+
+ +
+ Development: Saving Kernel Modifications + + + Another common operation is to build a BSP supplied by the Yocto Project, make some + changes, rebuild, and then test. + Those local changes often need to be exported, shared or otherwise maintained. + + + + Since the Yocto Project kernel source tree is backed by Git, this activity is + much easier as compared to with previous releases. + Because Git tracks file modifications, additions and deletions, it is easy + to modify the code and later realize that you need to save the changes. + It is also easy to determine what has changed. + This method also provides many tools to commit, undo and export those modifications. + + + + This section and its sub-sections, describe general application of Git's + push and pull commands, which are used to + get your changes upstream or source your code from an upstream repository. + The Yocto Project provides scripts that help you work in a collaborative development + environment. + For information on these scripts, see the + "Using Scripts to Push a Change + Upstream and Request a Pull" and + "Using Email to Submit a Patch" + sections in the Yocto Project Development Manual. + + + + There are many ways to save kernel modifications. + The technique employed + depends on the destination for the patches: + + + Bulk storage + Internal sharing either through patches or by using Git + External submissions + Exporting for integration into another Source Code + Manager (SCM) + + + + + Because of the following list of issues, the destination of the patches also influences + the method for gathering them: + + + Bisectability + Commit headers + Division of subsystems for separate submission or review + + + +
+ Bulk Export + + + This section describes how you can "bulk" export changes that have not + been separated or divided. + This situation works well when you are simply storing patches outside of the kernel + source repository, either permanently or temporarily, and you are not committing + incremental changes during development. + + This technique is not appropriate for full integration of upstream submission + because changes are not properly divided and do not provide an avenue for per-change + commit messages. + Therefore, this example assumes that changes have not been committed incrementally + during development and that you simply must gather and export them. + + + # bulk export of ALL modifications without separation or division + # of the changes + + $ git add . + $ git commit -s -a -m <msg> + or + $ git commit -s -a # and interact with $EDITOR + + + + + The previous operations capture all the local changes in the project source + tree in a single Git commit. + And, that commit is also stored in the project's source tree. + + + + Once the changes are exported, you can restore them manually using a template + or through integration with the default_kernel. + + +
+ +
+ Incremental/Planned Sharing + + + This section describes how to save modifications when you are making incremental + commits or practicing planned sharing. + The examples in this section assume that you have incrementally committed + changes to the tree during development and now need to export them. + The sections that follow + describe how you can export your changes internally through either patches or by + using Git commands. + + + + During development, the following commands are of interest. + For full Git documentation, refer to the Git documentation at + . + + + # edit a file + $ vi <path>/file + # stage the change + $ git add <path>/file + # commit the change + $ git commit -s + # remove a file + $ git rm <path>/file + # commit the change + $ git commit -s + + ... etc. + + + + + Distributed development with Git is possible when you use a universally + agreed-upon unique commit identifier (set by the creator of the commit) that maps to a + specific change set with a specific parent. + This identifier is created for you when + you create a commit, and is re-created when you amend, alter or re-apply + a commit. + As an individual in isolation, this is of no interest. + However, if you + intend to share your tree with normal Git push and + pull operations for + distributed development, you should consider the ramifications of changing a + commit that you have already shared with others. + + + + Assuming that the changes have not been pushed upstream, or pulled into + another repository, you can update both the commit content and commit messages + associated with development by using the following commands: + + + $ Git add <path>/file + $ Git commit --amend + $ Git rebase or Git rebase -i + + + + + Again, assuming that the changes have not been pushed upstream, and that + no pending works-in-progress exist (use git status to check), then + you can revert (undo) commits by using the following commands: + + + # remove the commit, update working tree and remove all + # traces of the change + $ git reset --hard HEAD^ + # remove the commit, but leave the files changed and staged for re-commit + $ git reset --soft HEAD^ + # remove the commit, leave file change, but not staged for commit + $ git reset --mixed HEAD^ + + + + + You can create branches, "cherry-pick" changes, or perform any number of Git + operations until the commits are in good order for pushing upstream + or for pull requests. + After a push or pull command, + commits are normally considered + "permanent" and you should not modify them. + If the commits need to be changed, you can incrementally do so with new commits. + These practices follow standard Git workflow and the kernel.org best + practices, which is recommended. + + It is recommended to tag or branch before adding changes to a Yocto Project + BSP or before creating a new one. + The reason for this recommendation is because the branch or tag provides a + reference point to facilitate locating and exporting local changes. + + + +
+ Exporting Changes Internally by Using Patches + + + This section describes how you can extract committed changes from a working directory + by exporting them as patches. + Once the changes have been extracted, you can use the patches for upstream submission, + place them in a Yocto Project template for automatic kernel patching, + or apply them in many other common uses. + + + + This example shows how to create a directory with sequentially numbered patches. + Once the directory is created, you can apply it to a repository using the + git am command to reproduce the original commit and all + the related information such as author, date, commit log, and so forth. + + The new commit identifiers (ID) will be generated upon re-application. + This action reflects that the commit is now applied to an underlying commit + with a different ID. + + + # <first-commit> can be a tag if one was created before development + # began. It can also be the parent branch if a branch was created + # before development began. + + $ git format-patch -o <dir> <first commit>..<last commit> + + + + + In other words: + + # Identify commits of interest. + + # If the tree was tagged before development + $ git format-patch -o <save dir> <tag> + + # If no tags are available + $ git format-patch -o <save dir> HEAD^ # last commit + $ git format-patch -o <save dir> HEAD^^ # last 2 commits + $ git whatchanged # identify last commit + $ git format-patch -o <save dir> <commit id> + $ git format-patch -o <save dir> <rev-list> + + +
+ +
+ Exporting Changes Internally by Using Git + + + This section describes how you can export changes from a working directory + by pushing the changes into a master repository or by making a pull request. + Once you have pushed the changes to the master repository, you can then + pull those same changes into a new kernel build at a later time. + + + + Use this command form to push the changes: + + $ git push ssh://<master_server>/<path_to_repo> + <local_branch>:<remote_branch> + + + + + For example, the following command pushes the changes from your local branch + yocto/standard/common-pc/base to the remote branch with the same name + in the master repository //git.mycompany.com/pub/git/kernel-3.4. + + $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ + yocto/standard/common-pc/base:yocto/standard/common-pc/base + + + + + A pull request entails using the git request-pull command to compose + an email to the + maintainer requesting that a branch be pulled into the master repository, see + for an example. + + Other commands such as git stash or branching can also be used to save + changes, but are not covered in this document. + + +
+
+ +
+ Exporting Changes for External (Upstream) Submission + + + This section describes how to export changes for external upstream submission. + If the patch series is large or the maintainer prefers to pull + changes, you can submit these changes by using a pull request. + However, it is common to send patches as an email series. + This method allows easy review and integration of the changes. + + Before sending patches for review be sure you understand the + community standards for submitting and documenting changes and follow their best practices. + For example, kernel patches should follow standards such as: + + + + Documentation/SubmittingPatches (in any linux + kernel source tree) + + + + + + The messages used to commit changes are a large part of these standards. + Consequently, be sure that the headers for each commit have the required information. + For information on how to follow the Yocto Project commit message standards, see the + "How to Submit a + Change" section in the Yocto Project Development Manual. + + + + If the initial commits were not properly documented or do not meet those standards, + you can re-base by using the git rebase -i command to + manipulate the commits and + get them into the required format. + Other techniques such as branching and cherry-picking commits are also viable options. + + + + Once you complete the commits, you can generate the email that sends the patches + to the maintainer(s) or lists that review and integrate changes. + The command git send-email is commonly used to ensure + that patches are properly + formatted for easy application and avoid mailer-induced patch damage. + + + + The following is an example of dumping patches for external submission: + + # dump the last 4 commits + $ git format-patch --thread -n -o ~/rr/ HEAD^^^^ + $ git send-email --compose --subject '[RFC 0/N] <patch series summary>' \ + --to foo@yoctoproject.org --to bar@yoctoproject.org \ + --cc list@yoctoproject.org ~/rr + # the editor is invoked for the 0/N patch, and when complete the entire + # series is sent via email for review + + +
+ +
+ Exporting Changes for Import into Another SCM + + + When you want to export changes for import into another + Source Code Manager (SCM), you can use any of the previously discussed + techniques. + However, if the patches are manually applied to a secondary tree and then + that tree is checked into the SCM, you can lose change information such as + commit logs. + This process is not recommended. + + + + Many SCMs can directly import Git commits, or can translate Git patches so that + information is not lost. + Those facilities are SCM-dependent and you should use them whenever possible. + +
+
+ +
+ Working with the Yocto Project Kernel in Another SCM + + + This section describes kernel development in an SCM other than Git, + which is not the same as exporting changes to another SCM described earlier. + For this scenario, you use the OpenEmbedded build system to + develop the kernel in a different SCM. + The following must be true for you to accomplish this: + + The delivered Yocto Project kernel must be exported into the second + SCM. + Development must be exported from that secondary SCM into a + format that can be used by the OpenEmbedded build system. + + + +
+ Exporting the Delivered Kernel to the SCM + + + Depending on the SCM, it might be possible to export the entire Yocto Project + kernel Git repository, branches and all, into a new environment. + This method is preferred because it has the most flexibility and potential to maintain + the meta data associated with each commit. + + + + When a direct import mechanism is not available, it is still possible to + export a branch (or series of branches) and check them into a new repository. + + + + The following commands illustrate some of the steps you could use to + import the yocto/standard/common-pc/base + kernel into a secondary SCM: + + $ git checkout yocto/standard/common-pc/base + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + + + + You could now relocate the CVS repository and use it in a centralized manner. + + + + The following commands illustrate how you can condense and merge two BSPs into a + second SCM: + + $ git checkout yocto/standard/common-pc/base + $ git merge yocto/standard/common-pc-64/base + # resolve any conflicts and commit them + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + + +
+ +
+ Importing Changes for the Build + + + Once development has reached a suitable point in the second development + environment, you need to export the changes as patches. + To export them, place the changes in a recipe and + automatically apply them to the kernel during patching. + +
+
+ +
+ Creating a BSP Based on an Existing Similar BSP + + + This section overviews the process of creating a BSP based on an + existing similar BSP. + The information is introductory in nature and does not provide step-by-step examples. + For detailed information on how to create a new BSP, see + the "Creating a New BSP Layer Using the yocto-bsp Script" section in the + Yocto Project Board Support Package (BSP) Developer's Guide, or see the + Transcript:_creating_one_generic_Atom_BSP_from_another + wiki page. + + + + The basic steps you need to follow are: + + Make sure you have set up a local Source Directory: + You must create a local + Source Directory + by either creating a Git repository (recommended) or + extracting a Yocto Project release tarball. + Choose an existing BSP available with the Yocto Project: + Try to map your board features as closely to the features of a BSP that is + already supported and exists in the Yocto Project. + Starting with something as close as possible to your board makes developing + your BSP easier. + You can find all the BSPs that are supported and ship with the Yocto Project + on the Yocto Project's Download page at + . + Be sure you have the Base BSP: + You need to either have a local Git repository of the base BSP set up or + have downloaded and extracted the files from a release BSP tarball. + Either method gives you access to the BSP source files. + Make a copy of the existing BSP, thus isolating your new + BSP work: + Copying the existing BSP file structure gives you a new area in which to work. + Make configuration and recipe changes to your new BSP: + Configuration changes involve the files in the BSP's conf + directory. + Changes include creating a machine-specific configuration file and editing the + layer.conf file. + The configuration changes identify the kernel you will be using. + Recipe changes include removing, modifying, or adding new recipe files that + instruct the build process on what features to include in the image. + Prepare for the build: + Before you actually initiate the build, you need to set up the build environment + by sourcing the environment initialization script. + After setting up the environment, you need to make some build configuration + changes to the local.conf and bblayers.conf + files. + Build the image: + The OpenEmbedded build system uses BitBake to create the image. + You need to decide on the type of image you are going to build (e.g. minimal, base, + core, sato, and so forth) and then start the build using the bitbake + command. + + +
+ +
+ "-dirty" String + + + If kernel images are being built with "-dirty" on the end of the version + string, this simply means that modifications in the source + directory have not been committed. + + $ git status + + + + + You can use the above Git command to report modified, removed, or added files. + You should commit those changes to the tree regardless of whether they will be saved, + exported, or used. + Once you commit the changes you need to rebuild the kernel. + + + + To brute force pickup and commit all such pending changes, enter the following: + + $ git add . + $ git commit -s -a -m "getting rid of -dirty" + + + + + Next, rebuild the kernel. + +
+
+
+ diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml new file mode 100644 index 0000000000..2b99ad2dde --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-faq.xml @@ -0,0 +1,140 @@ + %poky; ] > + + +Kernel Development FAQ + +
+ Common Questions and Solutions + + + The following lists some solutions for common questions. + + + + + + + How do I use my own Linux kernel .config + file? + + + + + Refer to the "Changing the Configuration" + section for information. + + + + + + + + How do I create configuration fragments? + + + + + Refer to the "Generating Configuration Files" + section for information. + + + + + + + + How do I use my own Linux kernel sources? + + + + + Refer to the "Working With Your Own Sources" + section for information. + + + + + + + + How do I install/not-install the kernel image on the rootfs? + + + + + The kernel image (e.g. vmlinuz) is provided + by the kernel-image package. + Image recipes depend on kernel-base. + To specify whether or not the kernel + image is installed in the generated root filesystem, override + RDEPENDS_kernel-base to include or not + include "kernel-image". + See the + "Using .bbappend Files" + section in the Yocto Project Development Manual for information on + how to use an append file to override metadata. + + + + + + + + How do I install a specific kernel module? + + + + + Linux kernel modules are packaged individually. + To ensure a specific kernel module is included in an image, + include it in the appropriate machine + RRECOMMENDS + variable. + These other variables are useful for installing specific + modules: + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS + MACHINE_EXTRA_RDEPENDS + MACHINE_EXTRA_RRECOMMENDS + + For example, set the following in the qemux86.conf + file to include the ab123 kernel modules + with images built for the qemux86 machine: + + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" + + For more information, see the + "Incorporating Out-of-Tree Modules" + section. + + + + + + + + How do I change the Linux kernel command line? + + + + + The Linux kernel command line is typically specified in + the machine config using the APPEND variable. + For example, you can add some helpful debug information doing + the following: + + APPEND += "printk.time=y initcall_debug debug" + + + + + + +
+
+ diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml new file mode 100644 index 0000000000..38ef36de5a --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -0,0 +1,147 @@ + %poky; ] > + + +Introduction + + + +
+ Overview + + + Regardless of how you intend to make use of the Yocto Project, + chances are you will work with the Linux kernel. + This manual provides background information on the Yocto Linux kernel + Metadata, + describes common tasks you can perform using the kernel tools, + and shows you how to use the kernel Metadata needed to work with + the kernel inside the Yocto Project. + + + + Each Yocto Project release has a set of linux-yocto recipes, whose + Git repositories you can view in the Yocto + Source Repositories under + the "Yocto Linux Kernel" heading. + New recipes for the release track the latest upstream developments + and introduce newly supported platforms. + Previous recipes in the release are refreshed and supported for at + least one additional release. + As they align, these previous releases are updated to include the + latest from the Long Term Support Initiative (LTSI) project. + Also included is a linux-yocto development recipe + (linux-yocto-dev.bb) should you want to work + with the very latest in upstream Linux kernel development and + kernel Metadata development. + + + + The Yocto Project also provides a powerful set of kernel + tools for managing Linux kernel sources and configuration data. + You can use these tools to make a single configuration change, + apply multiple patches, or work with your own kernel sources. + + + + In particular, the kernel tools allow you to generate configuration + fragments that specify only what you must, and nothing more. + Configuration fragments only need to contain the highest level + visible CONFIG options as presented by the Linux + kernel menuconfig system. + Contrast this against a complete Linux kernel + .config, which includes all the automatically + selected CONFIG options. + This efficiency reduces your maintenance effort and allows you + to further separate your configuration in ways that make sense for + your project. + A common split separates policy and hardware. + For example, all your kernels might support + the proc and sys filesystems, + but only specific boards require sound, USB, or specific drivers. + Specifying these configurations individually allows you to aggregate + them together as needed, but maintains them in only one place. + Similar logic applies to separating source changes. + + + + If you do not maintain your own kernel sources and need to make + only minimal changes to the sources, the released recipes provide a + vetted base upon which to layer your changes. + Doing so allows you to benefit from the continual kernel + integration and testing performed during development of the + Yocto Project. + + + + If, instead, you have a very specific Linux kernel source tree + and are unable to align with one of the official linux-yocto + recipes, an alternative exists by which you can use the Yocto + Project Linux kernel tools with your own kernel sources. + +
+ +
+ Other Resources + + + The sections that follow provide instructions for completing + specific Linux kernel development tasks. + These instructions assume you are comfortable working with + BitBake + recipes and basic open-source development tools. + Understanding these concepts will facilitate the process of working + with the kernel recipes. + If you find you need some additional background, please be sure to + review and understand the following documentation: + + Yocto Project Quick Start + + The "Modifying Temporary Source Code" + section in the Yocto Project Development Manual + + The "Understanding and Creating Layers" section + in the Yocto Project Development Manual + The "Modifying the Kernel" section + in the Yocto Project Development Manual. + + + + + Finally, while this document focuses on the manual creation of + recipes, patches, and configuration files, the Yocto Project + Board Support Package (BSP) tools are available to automate + this process with existing content and work well to create the + initial framework and boilerplate code. + For details on these tools, see the + "Using the Yocto Project's BSP Tools" + section in the Yocto Project Board Support Package (BSP) Developer's + Guide. + +
+
+ diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml new file mode 100644 index 0000000000..a72dcff01b --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml @@ -0,0 +1,220 @@ + %poky; ] > + + +Kernel Maintenance + +
+ Tree Construction + + This section describes construction of the Yocto Project kernel source repositories + as accomplished by the Yocto Project team to create kernel repositories. + These kernel repositories are found under the heading "Yocto Linux Kernel" at + &YOCTO_GIT_URL;/cgit.cgi + and can be shipped as part of a Yocto Project release. + The team creates these repositories by + compiling and executing the set of feature descriptions for every BSP + and feature in the product. + Those feature descriptions list all necessary patches, + configuration, branching, tagging and feature divisions found in a kernel. + Thus, the Yocto Project kernel repository (or tree) is built. + + + The existence of this tree allows you to access and clone a particular + Yocto Project kernel repository and use it to build images based on their configurations + and features. + + + You can find the files used to describe all the valid features and BSPs + in the Yocto Project kernel in any clone of the Yocto Project kernel source repository + Git tree. + For example, the following command clones the Yocto Project baseline kernel that + branched off of linux.org version 3.4: + + $ git clone git://git.yoctoproject.org/linux-yocto-3.4 + + For another example of how to set up a local Git repository of the Yocto Project + kernel files, see the + "Yocto Project Kernel" bulleted + item in the Yocto Project Development Manual. + + + Once you have cloned the kernel Git repository on your local machine, you can + switch to the meta branch within the repository. + Here is an example that assumes the local Git repository for the kernel is in + a top-level directory named linux-yocto-3.4: + + $ cd linux-yocto-3.4 + $ git checkout -b meta origin/meta + + Once you have checked out and switched to the meta branch, + you can see a snapshot of all the kernel configuration and feature descriptions that are + used to build that particular kernel repository. + These descriptions are in the form of .scc files. + + + You should realize, however, that browsing your local kernel repository + for feature descriptions and patches is not an effective way to determine what is in a + particular kernel branch. + Instead, you should use Git directly to discover the changes in a branch. + Using Git is an efficient and flexible way to inspect changes to the kernel. + + Ground up reconstruction of the complete kernel tree is an action only taken by the + Yocto Project team during an active development cycle. + When you create a clone of the kernel Git repository, you are simply making it + efficiently available for building and development. + + + + The following steps describe what happens when the Yocto Project Team constructs + the Yocto Project kernel source Git repository (or tree) found at + given the + introduction of a new top-level kernel feature or BSP. + These are the actions that effectively create the tree + that includes the new feature, patch or BSP: + + A top-level kernel feature is passed to the kernel build subsystem. + Normally, this feature is a BSP for a particular kernel type. + The file that describes the top-level feature is located by searching + these system directories: + + The in-tree kernel-cache directories, which are located + in meta/cfg/kernel-cache + Areas pointed to by SRC_URI statements + found in recipes + + For a typical build, the target of the search is a + feature description in an .scc file + whose name follows this format: + + bsp_name-kernel_type.scc + + + Once located, the feature description is either compiled into a simple script + of actions, or into an existing equivalent script that is already part of the + shipped kernel. + Extra features are appended to the top-level feature description. + These features can come from the + KERNEL_FEATURES + variable in recipes. + Each extra feature is located, compiled and appended to the script + as described in step three. + The script is executed to produce a series of meta-* + directories. + These directories are descriptions of all the branches, tags, patches and configurations that + need to be applied to the base Git repository to completely create the + source (build) branch for the new BSP or feature. + The base repository is cloned, and the actions + listed in the meta-* directories are applied to the + tree. + The Git repository is left with the desired branch checked out and any + required branching, patching and tagging has been performed. + + + + The kernel tree is now ready for developer consumption to be locally cloned, + configured, and built into a Yocto Project kernel specific to some target hardware. + The generated meta-* directories add to the kernel + as shipped with the Yocto Project release. + Any add-ons and configuration data are applied to the end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + http://git.yoctoproject.org/cgit.cgi + is the combination of all supported boards and configurations. + The technique the Yocto Project team uses is flexible and allows for seamless + blending of an immutable history with additional patches specific to a + deployment. + Any additions to the kernel become an integrated part of the branches. + + +
+ +
+ Build Strategy + + + + + Once a local Git repository of the Yocto Project kernel exists on a development system, + you can consider the compilation phase of kernel development - building a kernel image. + Some prerequisites exist that are validated by the build process before compilation + starts: + + + + The + SRC_URI points + to the kernel Git repository. + A BSP build branch exists. + This branch has the following form: + + kernel_type/bsp_name + + + + + The OpenEmbedded build system makes sure these conditions exist before attempting compilation. + Other means, however, do exist, such as as bootstrapping a BSP. + + + + Before building a kernel, the build process verifies the tree + and configures the kernel by processing all of the + configuration "fragments" specified by feature descriptions in the .scc + files. + As the features are compiled, associated kernel configuration fragments are noted + and recorded in the meta-* series of directories in their compilation order. + The fragments are migrated, pre-processed and passed to the Linux Kernel + Configuration subsystem (lkc) as raw input in the form + of a .config file. + The lkc uses its own internal dependency constraints to do the final + processing of that information and generates the final .config file + that is used during compilation. + + + + Using the board's architecture and other relevant values from the board's template, + kernel compilation is started and a kernel image is produced. + + + + The other thing that you notice once you configure a kernel is that + the build process generates a build tree that is separate from your kernel's local Git + source repository tree. + This build tree has a name that uses the following form, where + ${MACHINE} is the metadata name of the machine (BSP) and "kernel_type" is one + of the Yocto Project supported kernel types (e.g. "standard"): + + linux-${MACHINE}-kernel_type-build + + + + + The existing support in the kernel.org tree achieves this + default functionality. + + + + This behavior means that all the generated files for a particular machine or BSP are now in + the build tree directory. + The files include the final .config file, all the .o + files, the .a files, and so forth. + Since each machine or BSP has its own separate + Build Directory + in its own separate branch + of the Git repository, you can easily switch between different builds. + +
+
+ diff --git a/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css new file mode 100644 index 0000000000..6e0c1c7fc9 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/kernel-dev-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml new file mode 100644 index 0000000000..4ab95cbfce --- /dev/null +++ b/documentation/kernel-dev/kernel-dev.xml @@ -0,0 +1,115 @@ + %poky; ] > + + + + + + + + + + + + Yocto Project Linux Kernel Development Manual + + + + + Darren Hart + + Intel Corporation + + darren.hart@intel.com + + + + + + 1.4 + April 2013 + Released with the Yocto Project 1.4 Release. + + + 1.5 + October 2013 + Released with the Yocto Project 1.5 Release. + + + 1.5.1 + January 2014 + Released with the Yocto Project 1.5.1 Release. + + + 1.6 + April 2014 + Released with the Yocto Project 1.6 Release. + + + 1.7 + October 2014 + Released with the Yocto Project 1.7 Release. + + + 1.7.1 + January 2015 + Released with the Yocto Project 1.7.1 Release. + + + 1.7.2 + June 2015 + Released with the Yocto Project 1.7.2 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons. + + + For the latest version of this manual associated with this + Yocto Project release, see the + Yocto Project Linux Kernel Development Manual + from the Yocto Project website. + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/mega-manual/figures/adt-title.png b/documentation/mega-manual/figures/adt-title.png new file mode 100644 index 0000000000..6e71e41f1a Binary files /dev/null and b/documentation/mega-manual/figures/adt-title.png differ diff --git a/documentation/mega-manual/figures/analysis-for-package-splitting.png b/documentation/mega-manual/figures/analysis-for-package-splitting.png new file mode 100644 index 0000000000..04f2794ea9 Binary files /dev/null and b/documentation/mega-manual/figures/analysis-for-package-splitting.png differ diff --git a/documentation/mega-manual/figures/app-dev-flow.png b/documentation/mega-manual/figures/app-dev-flow.png new file mode 100644 index 0000000000..4927b93d67 Binary files /dev/null and b/documentation/mega-manual/figures/app-dev-flow.png differ diff --git a/documentation/mega-manual/figures/bsp-dev-flow.png b/documentation/mega-manual/figures/bsp-dev-flow.png new file mode 100644 index 0000000000..540b0abb9f Binary files /dev/null and b/documentation/mega-manual/figures/bsp-dev-flow.png differ diff --git a/documentation/mega-manual/figures/bsp-title.png b/documentation/mega-manual/figures/bsp-title.png new file mode 100644 index 0000000000..f624dd4f94 Binary files /dev/null and b/documentation/mega-manual/figures/bsp-title.png differ diff --git a/documentation/mega-manual/figures/buildhistory-web.png b/documentation/mega-manual/figures/buildhistory-web.png new file mode 100644 index 0000000000..f6db86c977 Binary files /dev/null and b/documentation/mega-manual/figures/buildhistory-web.png differ diff --git a/documentation/mega-manual/figures/buildhistory.png b/documentation/mega-manual/figures/buildhistory.png new file mode 100644 index 0000000000..9a77bde68b Binary files /dev/null and b/documentation/mega-manual/figures/buildhistory.png differ diff --git a/documentation/mega-manual/figures/building-an-image.png b/documentation/mega-manual/figures/building-an-image.png new file mode 100755 index 0000000000..1fbea5ab00 Binary files /dev/null and b/documentation/mega-manual/figures/building-an-image.png differ diff --git a/documentation/mega-manual/figures/configuration-compile-autoreconf.png b/documentation/mega-manual/figures/configuration-compile-autoreconf.png new file mode 100644 index 0000000000..a07464f04c Binary files /dev/null and b/documentation/mega-manual/figures/configuration-compile-autoreconf.png differ diff --git a/documentation/mega-manual/figures/cross-development-toolchains.png b/documentation/mega-manual/figures/cross-development-toolchains.png new file mode 100644 index 0000000000..d36670a198 Binary files /dev/null and b/documentation/mega-manual/figures/cross-development-toolchains.png differ diff --git a/documentation/mega-manual/figures/dev-title.png b/documentation/mega-manual/figures/dev-title.png new file mode 100644 index 0000000000..d3cac4a7e5 Binary files /dev/null and b/documentation/mega-manual/figures/dev-title.png differ diff --git a/documentation/mega-manual/figures/git-workflow.png b/documentation/mega-manual/figures/git-workflow.png new file mode 100644 index 0000000000..e401330a12 Binary files /dev/null and b/documentation/mega-manual/figures/git-workflow.png differ diff --git a/documentation/mega-manual/figures/image-generation.png b/documentation/mega-manual/figures/image-generation.png new file mode 100644 index 0000000000..ab962580c3 Binary files /dev/null and b/documentation/mega-manual/figures/image-generation.png differ diff --git a/documentation/mega-manual/figures/images.png b/documentation/mega-manual/figures/images.png new file mode 100644 index 0000000000..d99eac1fbf Binary files /dev/null and b/documentation/mega-manual/figures/images.png differ diff --git a/documentation/mega-manual/figures/index-downloads.png b/documentation/mega-manual/figures/index-downloads.png new file mode 100644 index 0000000000..c907997db2 Binary files /dev/null and b/documentation/mega-manual/figures/index-downloads.png differ diff --git a/documentation/mega-manual/figures/kernel-architecture-overview.png b/documentation/mega-manual/figures/kernel-architecture-overview.png new file mode 100755 index 0000000000..2aad172db3 Binary files /dev/null and b/documentation/mega-manual/figures/kernel-architecture-overview.png differ diff --git a/documentation/mega-manual/figures/kernel-dev-flow.png b/documentation/mega-manual/figures/kernel-dev-flow.png new file mode 100644 index 0000000000..009105d122 Binary files /dev/null and b/documentation/mega-manual/figures/kernel-dev-flow.png differ diff --git a/documentation/mega-manual/figures/kernel-dev-title.png b/documentation/mega-manual/figures/kernel-dev-title.png new file mode 100644 index 0000000000..7a8dd54372 Binary files /dev/null and b/documentation/mega-manual/figures/kernel-dev-title.png differ diff --git a/documentation/mega-manual/figures/kernel-overview-1.png b/documentation/mega-manual/figures/kernel-overview-1.png new file mode 100644 index 0000000000..116c0b9bd4 Binary files /dev/null and b/documentation/mega-manual/figures/kernel-overview-1.png differ diff --git a/documentation/mega-manual/figures/kernel-overview-2-generic.png b/documentation/mega-manual/figures/kernel-overview-2-generic.png new file mode 100644 index 0000000000..889ff1bf0d Binary files /dev/null and b/documentation/mega-manual/figures/kernel-overview-2-generic.png differ diff --git a/documentation/mega-manual/figures/kernel-title.png b/documentation/mega-manual/figures/kernel-title.png new file mode 100644 index 0000000000..59d86c00dc Binary files /dev/null and b/documentation/mega-manual/figures/kernel-title.png differ diff --git a/documentation/mega-manual/figures/kernelshark-all.png b/documentation/mega-manual/figures/kernelshark-all.png new file mode 100644 index 0000000000..99b40bafe5 Binary files /dev/null and b/documentation/mega-manual/figures/kernelshark-all.png differ diff --git a/documentation/mega-manual/figures/kernelshark-choose-events.png b/documentation/mega-manual/figures/kernelshark-choose-events.png new file mode 100644 index 0000000000..e8dd62a571 Binary files /dev/null and b/documentation/mega-manual/figures/kernelshark-choose-events.png differ diff --git a/documentation/mega-manual/figures/kernelshark-i915-display.png b/documentation/mega-manual/figures/kernelshark-i915-display.png new file mode 100644 index 0000000000..bb0edfb7fd Binary files /dev/null and b/documentation/mega-manual/figures/kernelshark-i915-display.png differ diff --git a/documentation/mega-manual/figures/kernelshark-output-display.png b/documentation/mega-manual/figures/kernelshark-output-display.png new file mode 100644 index 0000000000..ae2d0e5730 Binary files /dev/null and b/documentation/mega-manual/figures/kernelshark-output-display.png differ diff --git a/documentation/mega-manual/figures/layer-input.png b/documentation/mega-manual/figures/layer-input.png new file mode 100644 index 0000000000..0a4f2e74f3 Binary files /dev/null and b/documentation/mega-manual/figures/layer-input.png differ diff --git a/documentation/mega-manual/figures/lttngmain0.png b/documentation/mega-manual/figures/lttngmain0.png new file mode 100644 index 0000000000..5f60113cc3 Binary files /dev/null and b/documentation/mega-manual/figures/lttngmain0.png differ diff --git a/documentation/mega-manual/figures/oprofileui-busybox.png b/documentation/mega-manual/figures/oprofileui-busybox.png new file mode 100644 index 0000000000..a8275c65d2 Binary files /dev/null and b/documentation/mega-manual/figures/oprofileui-busybox.png differ diff --git a/documentation/mega-manual/figures/oprofileui-copy-to-user.png b/documentation/mega-manual/figures/oprofileui-copy-to-user.png new file mode 100644 index 0000000000..deb6470204 Binary files /dev/null and b/documentation/mega-manual/figures/oprofileui-copy-to-user.png differ diff --git a/documentation/mega-manual/figures/oprofileui-downloading.png b/documentation/mega-manual/figures/oprofileui-downloading.png new file mode 100644 index 0000000000..57742d6723 Binary files /dev/null and b/documentation/mega-manual/figures/oprofileui-downloading.png differ diff --git a/documentation/mega-manual/figures/oprofileui-processes.png b/documentation/mega-manual/figures/oprofileui-processes.png new file mode 100644 index 0000000000..ae547028f4 Binary files /dev/null and b/documentation/mega-manual/figures/oprofileui-processes.png differ diff --git a/documentation/mega-manual/figures/package-feeds.png b/documentation/mega-manual/figures/package-feeds.png new file mode 100644 index 0000000000..4bc311f3d6 Binary files /dev/null and b/documentation/mega-manual/figures/package-feeds.png differ diff --git a/documentation/mega-manual/figures/patching.png b/documentation/mega-manual/figures/patching.png new file mode 100644 index 0000000000..8ecd018502 Binary files /dev/null and b/documentation/mega-manual/figures/patching.png differ diff --git a/documentation/mega-manual/figures/perf-probe-do_fork-profile.png b/documentation/mega-manual/figures/perf-probe-do_fork-profile.png new file mode 100644 index 0000000000..1a1070deb8 Binary files /dev/null and b/documentation/mega-manual/figures/perf-probe-do_fork-profile.png differ diff --git a/documentation/mega-manual/figures/perf-report-cycles-u.png b/documentation/mega-manual/figures/perf-report-cycles-u.png new file mode 100644 index 0000000000..68ec6af80b Binary files /dev/null and b/documentation/mega-manual/figures/perf-report-cycles-u.png differ diff --git a/documentation/mega-manual/figures/perf-systemwide-libc.png b/documentation/mega-manual/figures/perf-systemwide-libc.png new file mode 100644 index 0000000000..2b72869c77 Binary files /dev/null and b/documentation/mega-manual/figures/perf-systemwide-libc.png differ diff --git a/documentation/mega-manual/figures/perf-systemwide.png b/documentation/mega-manual/figures/perf-systemwide.png new file mode 100644 index 0000000000..12ce2444ae Binary files /dev/null and b/documentation/mega-manual/figures/perf-systemwide.png differ diff --git a/documentation/mega-manual/figures/perf-wget-busybox-annotate-menu.png b/documentation/mega-manual/figures/perf-wget-busybox-annotate-menu.png new file mode 100644 index 0000000000..ceb34eaead Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-busybox-annotate-menu.png differ diff --git a/documentation/mega-manual/figures/perf-wget-busybox-annotate-udhcpc.png b/documentation/mega-manual/figures/perf-wget-busybox-annotate-udhcpc.png new file mode 100644 index 0000000000..3581e9daa6 Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-busybox-annotate-udhcpc.png differ diff --git a/documentation/mega-manual/figures/perf-wget-busybox-debuginfo.png b/documentation/mega-manual/figures/perf-wget-busybox-debuginfo.png new file mode 100644 index 0000000000..c317b49a4e Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-busybox-debuginfo.png differ diff --git a/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom-menu.png b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom-menu.png new file mode 100644 index 0000000000..1913c867d0 Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom-menu.png differ diff --git a/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom.png b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom.png new file mode 100644 index 0000000000..a1962c437a Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom.png differ diff --git a/documentation/mega-manual/figures/perf-wget-busybox-expanded-stripped.png b/documentation/mega-manual/figures/perf-wget-busybox-expanded-stripped.png new file mode 100644 index 0000000000..b642d06c8b Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-busybox-expanded-stripped.png differ diff --git a/documentation/mega-manual/figures/perf-wget-flat-stripped.png b/documentation/mega-manual/figures/perf-wget-flat-stripped.png new file mode 100644 index 0000000000..c8f395ab53 Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-flat-stripped.png differ diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png b/documentation/mega-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png new file mode 100644 index 0000000000..bb7c764ce0 Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png differ diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png new file mode 100644 index 0000000000..a799af5127 Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png differ diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png new file mode 100644 index 0000000000..e91808ae40 Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png differ diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png new file mode 100644 index 0000000000..812302d0a8 Binary files /dev/null and b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png differ diff --git a/documentation/mega-manual/figures/poky-title.png b/documentation/mega-manual/figures/poky-title.png new file mode 100644 index 0000000000..2893d84620 Binary files /dev/null and b/documentation/mega-manual/figures/poky-title.png differ diff --git a/documentation/mega-manual/figures/profile-title.png b/documentation/mega-manual/figures/profile-title.png new file mode 100644 index 0000000000..ce5c682b58 Binary files /dev/null and b/documentation/mega-manual/figures/profile-title.png differ diff --git a/documentation/mega-manual/figures/pybootchartgui-linux-yocto.png b/documentation/mega-manual/figures/pybootchartgui-linux-yocto.png new file mode 100644 index 0000000000..2b6bfdacf9 Binary files /dev/null and b/documentation/mega-manual/figures/pybootchartgui-linux-yocto.png differ diff --git a/documentation/mega-manual/figures/pychart-linux-yocto-rpm-nostrip.png b/documentation/mega-manual/figures/pychart-linux-yocto-rpm-nostrip.png new file mode 100644 index 0000000000..444675c543 Binary files /dev/null and b/documentation/mega-manual/figures/pychart-linux-yocto-rpm-nostrip.png differ diff --git a/documentation/mega-manual/figures/pychart-linux-yocto-rpm.png b/documentation/mega-manual/figures/pychart-linux-yocto-rpm.png new file mode 100644 index 0000000000..8ee35352d8 Binary files /dev/null and b/documentation/mega-manual/figures/pychart-linux-yocto-rpm.png differ diff --git a/documentation/mega-manual/figures/recipe-workflow.png b/documentation/mega-manual/figures/recipe-workflow.png new file mode 100644 index 0000000000..c0e960b13b Binary files /dev/null and b/documentation/mega-manual/figures/recipe-workflow.png differ diff --git a/documentation/mega-manual/figures/sched-wakeup-profile.png b/documentation/mega-manual/figures/sched-wakeup-profile.png new file mode 100644 index 0000000000..2f25811889 Binary files /dev/null and b/documentation/mega-manual/figures/sched-wakeup-profile.png differ diff --git a/documentation/mega-manual/figures/sdk-generation.png b/documentation/mega-manual/figures/sdk-generation.png new file mode 100644 index 0000000000..c37e2748ca Binary files /dev/null and b/documentation/mega-manual/figures/sdk-generation.png differ diff --git a/documentation/mega-manual/figures/sdk.png b/documentation/mega-manual/figures/sdk.png new file mode 100644 index 0000000000..a539cc52f0 Binary files /dev/null and b/documentation/mega-manual/figures/sdk.png differ diff --git a/documentation/mega-manual/figures/source-fetching.png b/documentation/mega-manual/figures/source-fetching.png new file mode 100644 index 0000000000..26aefb50c2 Binary files /dev/null and b/documentation/mega-manual/figures/source-fetching.png differ diff --git a/documentation/mega-manual/figures/source-input.png b/documentation/mega-manual/figures/source-input.png new file mode 100644 index 0000000000..f7515058ef Binary files /dev/null and b/documentation/mega-manual/figures/source-input.png differ diff --git a/documentation/mega-manual/figures/source-repos.png b/documentation/mega-manual/figures/source-repos.png new file mode 100644 index 0000000000..65c5f29a43 Binary files /dev/null and b/documentation/mega-manual/figures/source-repos.png differ diff --git a/documentation/mega-manual/figures/sysprof-callers.png b/documentation/mega-manual/figures/sysprof-callers.png new file mode 100644 index 0000000000..640c8d9140 Binary files /dev/null and b/documentation/mega-manual/figures/sysprof-callers.png differ diff --git a/documentation/mega-manual/figures/sysprof-copy-from-user.png b/documentation/mega-manual/figures/sysprof-copy-from-user.png new file mode 100644 index 0000000000..8d31427824 Binary files /dev/null and b/documentation/mega-manual/figures/sysprof-copy-from-user.png differ diff --git a/documentation/mega-manual/figures/sysprof-copy-to-user.png b/documentation/mega-manual/figures/sysprof-copy-to-user.png new file mode 100644 index 0000000000..7a5bab7991 Binary files /dev/null and b/documentation/mega-manual/figures/sysprof-copy-to-user.png differ diff --git a/documentation/mega-manual/figures/user-configuration.png b/documentation/mega-manual/figures/user-configuration.png new file mode 100644 index 0000000000..f2b3f8e7fe Binary files /dev/null and b/documentation/mega-manual/figures/user-configuration.png differ diff --git a/documentation/mega-manual/figures/using-a-pre-built-image.png b/documentation/mega-manual/figures/using-a-pre-built-image.png new file mode 100644 index 0000000000..b03130d123 Binary files /dev/null and b/documentation/mega-manual/figures/using-a-pre-built-image.png differ diff --git a/documentation/mega-manual/figures/yocto-environment-ref.png b/documentation/mega-manual/figures/yocto-environment-ref.png new file mode 100644 index 0000000000..650c6c8030 Binary files /dev/null and b/documentation/mega-manual/figures/yocto-environment-ref.png differ diff --git a/documentation/mega-manual/figures/yocto-environment.png b/documentation/mega-manual/figures/yocto-environment.png new file mode 100644 index 0000000000..82b7a55a35 Binary files /dev/null and b/documentation/mega-manual/figures/yocto-environment.png differ diff --git a/documentation/mega-manual/figures/yocto-project-transp.png b/documentation/mega-manual/figures/yocto-project-transp.png new file mode 100755 index 0000000000..31d2b147fd Binary files /dev/null and b/documentation/mega-manual/figures/yocto-project-transp.png differ diff --git a/documentation/mega-manual/figures/yp-download.png b/documentation/mega-manual/figures/yp-download.png new file mode 100644 index 0000000000..5770be6883 Binary files /dev/null and b/documentation/mega-manual/figures/yp-download.png differ diff --git a/documentation/mega-manual/mega-manual-customization.xsl b/documentation/mega-manual/mega-manual-customization.xsl new file mode 100644 index 0000000000..a8b9bd6b5b --- /dev/null +++ b/documentation/mega-manual/mega-manual-customization.xsl @@ -0,0 +1,34 @@ + + + + + + + appendix toc + chapter toc + article nop + book nop + part nop + preface nop + qandadiv nop + qandaset nop + reference nop + section nop + set nop + + + + + + + + + + + + A + + + + + diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml new file mode 100644 index 0000000000..01af789aed --- /dev/null +++ b/documentation/mega-manual/mega-manual.xml @@ -0,0 +1,53 @@ + %poky; ] > + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/mega-manual/mega-style.css b/documentation/mega-manual/mega-style.css new file mode 100644 index 0000000000..45b77ac958 --- /dev/null +++ b/documentation/mega-manual/mega-style.css @@ -0,0 +1,983 @@ +/* + 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-position: top; + margin-top: -256px; + padding-right: 50px; + margin-left: 50px; + text-align: center; + width: 600px; +} + +h3.author { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/poky.ent b/documentation/poky.ent new file mode 100644 index 0000000000..4fa1a08c4f --- /dev/null +++ b/documentation/poky.ent @@ -0,0 +1,66 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/profile-manual/figures/kernelshark-all.png b/documentation/profile-manual/figures/kernelshark-all.png new file mode 100644 index 0000000000..99b40bafe5 Binary files /dev/null and b/documentation/profile-manual/figures/kernelshark-all.png differ diff --git a/documentation/profile-manual/figures/kernelshark-choose-events.png b/documentation/profile-manual/figures/kernelshark-choose-events.png new file mode 100644 index 0000000000..e8dd62a571 Binary files /dev/null and b/documentation/profile-manual/figures/kernelshark-choose-events.png differ diff --git a/documentation/profile-manual/figures/kernelshark-i915-display.png b/documentation/profile-manual/figures/kernelshark-i915-display.png new file mode 100644 index 0000000000..bb0edfb7fd Binary files /dev/null and b/documentation/profile-manual/figures/kernelshark-i915-display.png differ diff --git a/documentation/profile-manual/figures/kernelshark-output-display.png b/documentation/profile-manual/figures/kernelshark-output-display.png new file mode 100644 index 0000000000..ae2d0e5730 Binary files /dev/null and b/documentation/profile-manual/figures/kernelshark-output-display.png differ diff --git a/documentation/profile-manual/figures/lttngmain0.png b/documentation/profile-manual/figures/lttngmain0.png new file mode 100644 index 0000000000..5f60113cc3 Binary files /dev/null and b/documentation/profile-manual/figures/lttngmain0.png differ diff --git a/documentation/profile-manual/figures/oprofileui-busybox.png b/documentation/profile-manual/figures/oprofileui-busybox.png new file mode 100644 index 0000000000..a8275c65d2 Binary files /dev/null and b/documentation/profile-manual/figures/oprofileui-busybox.png differ diff --git a/documentation/profile-manual/figures/oprofileui-copy-to-user.png b/documentation/profile-manual/figures/oprofileui-copy-to-user.png new file mode 100644 index 0000000000..deb6470204 Binary files /dev/null and b/documentation/profile-manual/figures/oprofileui-copy-to-user.png differ diff --git a/documentation/profile-manual/figures/oprofileui-downloading.png b/documentation/profile-manual/figures/oprofileui-downloading.png new file mode 100644 index 0000000000..57742d6723 Binary files /dev/null and b/documentation/profile-manual/figures/oprofileui-downloading.png differ diff --git a/documentation/profile-manual/figures/oprofileui-processes.png b/documentation/profile-manual/figures/oprofileui-processes.png new file mode 100644 index 0000000000..ae547028f4 Binary files /dev/null and b/documentation/profile-manual/figures/oprofileui-processes.png differ diff --git a/documentation/profile-manual/figures/perf-probe-do_fork-profile.png b/documentation/profile-manual/figures/perf-probe-do_fork-profile.png new file mode 100644 index 0000000000..1a1070deb8 Binary files /dev/null and b/documentation/profile-manual/figures/perf-probe-do_fork-profile.png differ diff --git a/documentation/profile-manual/figures/perf-report-cycles-u.png b/documentation/profile-manual/figures/perf-report-cycles-u.png new file mode 100644 index 0000000000..68ec6af80b Binary files /dev/null and b/documentation/profile-manual/figures/perf-report-cycles-u.png differ diff --git a/documentation/profile-manual/figures/perf-systemwide-libc.png b/documentation/profile-manual/figures/perf-systemwide-libc.png new file mode 100644 index 0000000000..2b72869c77 Binary files /dev/null and b/documentation/profile-manual/figures/perf-systemwide-libc.png differ diff --git a/documentation/profile-manual/figures/perf-systemwide.png b/documentation/profile-manual/figures/perf-systemwide.png new file mode 100644 index 0000000000..12ce2444ae Binary files /dev/null and b/documentation/profile-manual/figures/perf-systemwide.png differ diff --git a/documentation/profile-manual/figures/perf-wget-busybox-annotate-menu.png b/documentation/profile-manual/figures/perf-wget-busybox-annotate-menu.png new file mode 100644 index 0000000000..ceb34eaead Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-busybox-annotate-menu.png differ diff --git a/documentation/profile-manual/figures/perf-wget-busybox-annotate-udhcpc.png b/documentation/profile-manual/figures/perf-wget-busybox-annotate-udhcpc.png new file mode 100644 index 0000000000..3581e9daa6 Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-busybox-annotate-udhcpc.png differ diff --git a/documentation/profile-manual/figures/perf-wget-busybox-debuginfo.png b/documentation/profile-manual/figures/perf-wget-busybox-debuginfo.png new file mode 100644 index 0000000000..c317b49a4e Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-busybox-debuginfo.png differ diff --git a/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom-menu.png b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom-menu.png new file mode 100644 index 0000000000..1913c867d0 Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom-menu.png differ diff --git a/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom.png b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom.png new file mode 100644 index 0000000000..a1962c437a Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom.png differ diff --git a/documentation/profile-manual/figures/perf-wget-busybox-expanded-stripped.png b/documentation/profile-manual/figures/perf-wget-busybox-expanded-stripped.png new file mode 100644 index 0000000000..b642d06c8b Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-busybox-expanded-stripped.png differ diff --git a/documentation/profile-manual/figures/perf-wget-flat-stripped.png b/documentation/profile-manual/figures/perf-wget-flat-stripped.png new file mode 100644 index 0000000000..c8f395ab53 Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-flat-stripped.png differ diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png b/documentation/profile-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png new file mode 100644 index 0000000000..bb7c764ce0 Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png differ diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png new file mode 100644 index 0000000000..a799af5127 Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png differ diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png new file mode 100644 index 0000000000..e91808ae40 Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png differ diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png new file mode 100644 index 0000000000..812302d0a8 Binary files /dev/null and b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png differ diff --git a/documentation/profile-manual/figures/profile-title.png b/documentation/profile-manual/figures/profile-title.png new file mode 100644 index 0000000000..ce5c682b58 Binary files /dev/null and b/documentation/profile-manual/figures/profile-title.png differ diff --git a/documentation/profile-manual/figures/pybootchartgui-linux-yocto.png b/documentation/profile-manual/figures/pybootchartgui-linux-yocto.png new file mode 100644 index 0000000000..2b6bfdacf9 Binary files /dev/null and b/documentation/profile-manual/figures/pybootchartgui-linux-yocto.png differ diff --git a/documentation/profile-manual/figures/pychart-linux-yocto-rpm-nostrip.png b/documentation/profile-manual/figures/pychart-linux-yocto-rpm-nostrip.png new file mode 100644 index 0000000000..444675c543 Binary files /dev/null and b/documentation/profile-manual/figures/pychart-linux-yocto-rpm-nostrip.png differ diff --git a/documentation/profile-manual/figures/pychart-linux-yocto-rpm.png b/documentation/profile-manual/figures/pychart-linux-yocto-rpm.png new file mode 100644 index 0000000000..8ee35352d8 Binary files /dev/null and b/documentation/profile-manual/figures/pychart-linux-yocto-rpm.png differ diff --git a/documentation/profile-manual/figures/sched-wakeup-profile.png b/documentation/profile-manual/figures/sched-wakeup-profile.png new file mode 100644 index 0000000000..2f25811889 Binary files /dev/null and b/documentation/profile-manual/figures/sched-wakeup-profile.png differ diff --git a/documentation/profile-manual/figures/sysprof-callers.png b/documentation/profile-manual/figures/sysprof-callers.png new file mode 100644 index 0000000000..640c8d9140 Binary files /dev/null and b/documentation/profile-manual/figures/sysprof-callers.png differ diff --git a/documentation/profile-manual/figures/sysprof-copy-from-user.png b/documentation/profile-manual/figures/sysprof-copy-from-user.png new file mode 100644 index 0000000000..8d31427824 Binary files /dev/null and b/documentation/profile-manual/figures/sysprof-copy-from-user.png differ diff --git a/documentation/profile-manual/figures/sysprof-copy-to-user.png b/documentation/profile-manual/figures/sysprof-copy-to-user.png new file mode 100644 index 0000000000..7a5bab7991 Binary files /dev/null and b/documentation/profile-manual/figures/sysprof-copy-to-user.png differ diff --git a/documentation/profile-manual/profile-manual-arch.xml b/documentation/profile-manual/profile-manual-arch.xml new file mode 100644 index 0000000000..19d1155229 --- /dev/null +++ b/documentation/profile-manual/profile-manual-arch.xml @@ -0,0 +1,45 @@ + %poky; ] > + + + +Overall Architecture of the Linux Tracing and Profiling Tools + +
+ Architecture of the Tracing and Profiling Tools + + + It may seem surprising to see a section covering an 'overall architecture' + for what seems to be a random collection of tracing tools that together + make up the Linux tracing and profiling space. + The fact is, however, that in recent years this seemingly disparate + set of tools has started to converge on a 'core' set of underlying + mechanisms: + + + + + static tracepoints + dynamic tracepoints + + kprobes + uprobes + + + the perf_events subsystem + debugfs + + + + + Tying it Together: Rather than enumerating here how each tool makes use of + these common mechanisms, textboxes like this will make note of the + specific usages in each tool as they come up in the course + of the text. + +
+
+ diff --git a/documentation/profile-manual/profile-manual-customization.xsl b/documentation/profile-manual/profile-manual-customization.xsl new file mode 100644 index 0000000000..7284aec365 --- /dev/null +++ b/documentation/profile-manual/profile-manual-customization.xsl @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/documentation/profile-manual/profile-manual-eclipse-customization.xsl b/documentation/profile-manual/profile-manual-eclipse-customization.xsl new file mode 100644 index 0000000000..e4ff6e99ab --- /dev/null +++ b/documentation/profile-manual/profile-manual-eclipse-customization.xsl @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + A + + + diff --git a/documentation/profile-manual/profile-manual-examples.xml b/documentation/profile-manual/profile-manual-examples.xml new file mode 100644 index 0000000000..9630c6c307 --- /dev/null +++ b/documentation/profile-manual/profile-manual-examples.xml @@ -0,0 +1,39 @@ + %poky; ] > + + + +Real-World Examples + + + This chapter contains real-world examples. + + +
+ Slow Write Speed on Live Images + + + In one of our previous releases (denzil), users noticed that booting + off of a live image and writing to disk was noticeably slower. + This included the boot itself, especially the first one, since first + boots tend to do a significant amount of writing due to certain + post-install scripts. + + + + The problem (and solution) was discovered by using the Yocto tracing + tools, in this case 'perf stat', 'perf script', 'perf record' + and 'perf report'. + + + + See all the unvarnished details of how this bug was diagnosed and + solved here: Yocto Bug #3049 + +
+ +
+ diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml new file mode 100644 index 0000000000..0d3f5a6099 --- /dev/null +++ b/documentation/profile-manual/profile-manual-intro.xml @@ -0,0 +1,102 @@ + %poky; ] > + + + +Yocto Project Profiling and Tracing Manual +
+ Introduction + + + Yocto bundles a number of tracing and profiling tools - this 'HOWTO' + describes their basic usage and shows by example how to make use + of them to examine application and system behavior. + + + + The tools presented are for the most part completely open-ended and + have quite good and/or extensive documentation of their own which + can be used to solve just about any problem you might come across + in Linux. + Each section that describes a particular tool has links to that + tool's documentation and website. + + + + The purpose of this 'HOWTO' is to present a set of common and + generally useful tracing and profiling idioms along with their + application (as appropriate) to each tool, in the context of a + general-purpose 'drill-down' methodology that can be applied + to solving a large number (90%?) of problems. + For help with more advanced usages and problems, please see + the documentation and/or websites listed for each tool. + + + + The final section of this 'HOWTO' is a collection of real-world + examples which we'll be continually adding to as we solve more + problems using the tools - feel free to add your own examples + to the list! + +
+ +
+ General Setup + + + Most of the tools are available only in 'sdk' images or in images + built after adding 'tools-profile' to your local.conf. + So, in order to be able to access all of the tools described here, + please first build and boot an 'sdk' image e.g. + + $ bitbake core-image-sato-sdk + + or alternatively by adding 'tools-profile' to the + EXTRA_IMAGE_FEATURES line in your local.conf: + + EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile" + + If you use the 'tools-profile' method, you don't need to build an + sdk image - the tracing and profiling tools will be included in + non-sdk images as well e.g.: + + $ bitbake core-image-sato + + + By default, the Yocto build system strips symbols from the + binaries it packages, which makes it difficult to use some + of the tools. + You can prevent that by putting the following + in your local.conf when you build the image: + + + + INHIBIT_PACKAGE_STRIP = "1" + + The above setting will noticeably increase the size of your image. + + + + If you've already built a stripped image, you can generate + debug packages (xxx-dbg) which you can manually install as + needed. + + + + To generate debug info for packages, you can add dbg-pkgs to + EXTRA_IMAGE_FEATURES in local.conf. For example: + + EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs" + + Additionally, in order to generate the right type of + debuginfo, we also need to add the following to local.conf: + + PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' + + +
+
+ diff --git a/documentation/profile-manual/profile-manual-style.css b/documentation/profile-manual/profile-manual-style.css new file mode 100644 index 0000000000..f3cca8536d --- /dev/null +++ b/documentation/profile-manual/profile-manual-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/profile-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/profile-manual/profile-manual-usage.xml b/documentation/profile-manual/profile-manual-usage.xml new file mode 100644 index 0000000000..95ad73909c --- /dev/null +++ b/documentation/profile-manual/profile-manual-usage.xml @@ -0,0 +1,3695 @@ + %poky; ] > + + + +Basic Usage (with examples) for each of the Yocto Tracing Tools + + + This chapter presents basic usage examples for each of the tracing + tools. + + +
+ perf + + + The 'perf' tool is the profiling and tracing tool that comes + bundled with the Linux kernel. + + + + Don't let the fact that it's part of the kernel fool you into thinking + that it's only for tracing and profiling the kernel - you can indeed + use it to trace and profile just the kernel, but you can also use it + to profile specific applications separately (with or without kernel + context), and you can also use it to trace and profile the kernel + and all applications on the system simultaneously to gain a system-wide + view of what's going on. + + + + In many ways, perf aims to be a superset of all the tracing and profiling + tools available in Linux today, including all the other tools covered + in this HOWTO. The past couple of years have seen perf subsume a lot + of the functionality of those other tools and, at the same time, those + other tools have removed large portions of their previous functionality + and replaced it with calls to the equivalent functionality now + implemented by the perf subsystem. Extrapolation suggests that at + some point those other tools will simply become completely redundant + and go away; until then, we'll cover those other tools in these pages + and in many cases show how the same things can be accomplished in + perf and the other tools when it seems useful to do so. + + + + The coverage below details some of the most common ways you'll likely + want to apply the tool; full documentation can be found either within + the tool itself or in the man pages at + perf(1). + + +
+ Setup + + + For this section, we'll assume you've already performed the basic + setup outlined in the General Setup section. + + + + In particular, you'll get the most mileage out of perf if you + profile an image built with INHIBIT_PACKAGE_STRIP = "1" in your + local.conf. + + + + perf runs on the target system for the most part. You can archive + profile data and copy it to the host for analysis, but for the + rest of this document we assume you've ssh'ed to the host and + will be running the perf commands on the target. + +
+ +
+ Basic Usage + + + The perf tool is pretty much self-documenting. To remind yourself + of the available commands, simply type 'perf', which will show you + basic usage along with the available perf subcommands: + + root@crownbay:~# perf + + usage: perf [--version] [--help] COMMAND [ARGS] + + The most commonly used perf commands are: + annotate Read perf.data (created by perf record) and display annotated code + archive Create archive with object files with build-ids found in perf.data file + bench General framework for benchmark suites + buildid-cache Manage build-id cache. + buildid-list List the buildids in a perf.data file + diff Read two perf.data files and display the differential profile + evlist List the event names in a perf.data file + inject Filter to augment the events stream with additional information + kmem Tool to trace/measure kernel memory(slab) properties + kvm Tool to trace/measure kvm guest os + list List all symbolic event types + lock Analyze lock events + probe Define new dynamic tracepoints + record Run a command and record its profile into perf.data + report Read perf.data (created by perf record) and display the profile + sched Tool to trace/measure scheduler properties (latencies) + script Read perf.data (created by perf record) and display trace output + stat Run a command and gather performance counter statistics + test Runs sanity tests. + timechart Tool to visualize total system behavior during a workload + top System profiling tool. + + See 'perf help COMMAND' for more information on a specific command. + + + +
+ Using perf to do Basic Profiling + + + As a simple test case, we'll profile the 'wget' of a fairly large + file, which is a minimally interesting case because it has both + file and network I/O aspects, and at least in the case of standard + Yocto images, it's implemented as part of busybox, so the methods + we use to analyze it can be used in a very similar way to the whole + host of supported busybox applets in Yocto. + + root@crownbay:~# rm linux-2.6.19.2.tar.bz2; \ + wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + + The quickest and easiest way to get some basic overall data about + what's going on for a particular workload is to profile it using + 'perf stat'. 'perf stat' basically profiles using a few default + counters and displays the summed counts at the end of the run: + + root@crownbay:~# perf stat wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |***************************************************| 41727k 0:00:00 ETA + + Performance counter stats for 'wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2': + + 4597.223902 task-clock # 0.077 CPUs utilized + 23568 context-switches # 0.005 M/sec + 68 CPU-migrations # 0.015 K/sec + 241 page-faults # 0.052 K/sec + 3045817293 cycles # 0.663 GHz + <not supported> stalled-cycles-frontend + <not supported> stalled-cycles-backend + 858909167 instructions # 0.28 insns per cycle + 165441165 branches # 35.987 M/sec + 19550329 branch-misses # 11.82% of all branches + + 59.836627620 seconds time elapsed + + Many times such a simple-minded test doesn't yield much of + interest, but sometimes it does (see Real-world Yocto bug + (slow loop-mounted write speed)). + + + + Also, note that 'perf stat' isn't restricted to a fixed set of + counters - basically any event listed in the output of 'perf list' + can be tallied by 'perf stat'. For example, suppose we wanted to + see a summary of all the events related to kernel memory + allocation/freeing along with cache hits and misses: + + root@crownbay:~# perf stat -e kmem:* -e cache-references -e cache-misses wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |***************************************************| 41727k 0:00:00 ETA + + Performance counter stats for 'wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2': + + 5566 kmem:kmalloc + 125517 kmem:kmem_cache_alloc + 0 kmem:kmalloc_node + 0 kmem:kmem_cache_alloc_node + 34401 kmem:kfree + 69920 kmem:kmem_cache_free + 133 kmem:mm_page_free + 41 kmem:mm_page_free_batched + 11502 kmem:mm_page_alloc + 11375 kmem:mm_page_alloc_zone_locked + 0 kmem:mm_page_pcpu_drain + 0 kmem:mm_page_alloc_extfrag + 66848602 cache-references + 2917740 cache-misses # 4.365 % of all cache refs + + 44.831023415 seconds time elapsed + + So 'perf stat' gives us a nice easy way to get a quick overview of + what might be happening for a set of events, but normally we'd + need a little more detail in order to understand what's going on + in a way that we can act on in a useful way. + + + + To dive down into a next level of detail, we can use 'perf + record'/'perf report' which will collect profiling data and + present it to use using an interactive text-based UI (or + simply as text if we specify --stdio to 'perf report'). + + + + As our first attempt at profiling this workload, we'll simply + run 'perf record', handing it the workload we want to profile + (everything after 'perf record' and any perf options we hand + it - here none - will be executed in a new shell). perf collects + samples until the process exits and records them in a file named + 'perf.data' in the current working directory. + + root@crownbay:~# perf record wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |************************************************| 41727k 0:00:00 ETA + [ perf record: Woken up 1 times to write data ] + [ perf record: Captured and wrote 0.176 MB perf.data (~7700 samples) ] + + To see the results in a 'text-based UI' (tui), simply run + 'perf report', which will read the perf.data file in the current + working directory and display the results in an interactive UI: + + root@crownbay:~# perf report + + + + + + + + + The above screenshot displays a 'flat' profile, one entry for + each 'bucket' corresponding to the functions that were profiled + during the profiling run, ordered from the most popular to the + least (perf has options to sort in various orders and keys as + well as display entries only above a certain threshold and so + on - see the perf documentation for details). Note that this + includes both userspace functions (entries containing a [.]) and + kernel functions accounted to the process (entries containing + a [k]). (perf has command-line modifiers that can be used to + restrict the profiling to kernel or userspace, among others). + + + + Notice also that the above report shows an entry for 'busybox', + which is the executable that implements 'wget' in Yocto, but that + instead of a useful function name in that entry, it displays + a not-so-friendly hex value instead. The steps below will show + how to fix that problem. + + + + Before we do that, however, let's try running a different profile, + one which shows something a little more interesting. The only + difference between the new profile and the previous one is that + we'll add the -g option, which will record not just the address + of a sampled function, but the entire callchain to the sampled + function as well: + + root@crownbay:~# perf record -g wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |************************************************| 41727k 0:00:00 ETA + [ perf record: Woken up 3 times to write data ] + [ perf record: Captured and wrote 0.652 MB perf.data (~28476 samples) ] + + + root@crownbay:~# perf report + + + + + + + + + Using the callgraph view, we can actually see not only which + functions took the most time, but we can also see a summary of + how those functions were called and learn something about how the + program interacts with the kernel in the process. + + + + Notice that each entry in the above screenshot now contains a '+' + on the left-hand side. This means that we can expand the entry and + drill down into the callchains that feed into that entry. + Pressing 'enter' on any one of them will expand the callchain + (you can also press 'E' to expand them all at the same time or 'C' + to collapse them all). + + + + In the screenshot above, we've toggled the __copy_to_user_ll() + entry and several subnodes all the way down. This lets us see + which callchains contributed to the profiled __copy_to_user_ll() + function which contributed 1.77% to the total profile. + + + + As a bit of background explanation for these callchains, think + about what happens at a high level when you run wget to get a file + out on the network. Basically what happens is that the data comes + into the kernel via the network connection (socket) and is passed + to the userspace program 'wget' (which is actually a part of + busybox, but that's not important for now), which takes the buffers + the kernel passes to it and writes it to a disk file to save it. + + + + The part of this process that we're looking at in the above call + stacks is the part where the kernel passes the data it's read from + the socket down to wget i.e. a copy-to-user. + + + + Notice also that here there's also a case where the hex value + is displayed in the callstack, here in the expanded + sys_clock_gettime() function. Later we'll see it resolve to a + userspace function call in busybox. + + + + + + + + The above screenshot shows the other half of the journey for the + data - from the wget program's userspace buffers to disk. To get + the buffers to disk, the wget program issues a write(2), which + does a copy-from-user to the kernel, which then takes care via + some circuitous path (probably also present somewhere in the + profile data), to get it safely to disk. + + + + Now that we've seen the basic layout of the profile data and the + basics of how to extract useful information out of it, let's get + back to the task at hand and see if we can get some basic idea + about where the time is spent in the program we're profiling, + wget. Remember that wget is actually implemented as an applet + in busybox, so while the process name is 'wget', the executable + we're actually interested in is busybox. So let's expand the + first entry containing busybox: + + + + + + + + Again, before we expanded we saw that the function was labeled + with a hex value instead of a symbol as with most of the kernel + entries. Expanding the busybox entry doesn't make it any better. + + + + The problem is that perf can't find the symbol information for the + busybox binary, which is actually stripped out by the Yocto build + system. + + + + One way around that is to put the following in your local.conf + when you build the image: + + INHIBIT_PACKAGE_STRIP = "1" + + However, we already have an image with the binaries stripped, + so what can we do to get perf to resolve the symbols? Basically + we need to install the debuginfo for the busybox package. + + + + To generate the debug info for the packages in the image, we can + add dbg-pkgs to EXTRA_IMAGE_FEATURES in local.conf. For example: + + EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs" + + Additionally, in order to generate the type of debuginfo that + perf understands, we also need to add the following to local.conf: + + PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' + + Once we've done that, we can install the debuginfo for busybox. + The debug packages once built can be found in + build/tmp/deploy/rpm/* on the host system. Find the + busybox-dbg-...rpm file and copy it to the target. For example: + + [trz@empanada core2]$ scp /home/trz/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2_32/busybox-dbg-1.20.2-r2.core2_32.rpm root@192.168.1.31: + root@192.168.1.31's password: + busybox-dbg-1.20.2-r2.core2_32.rpm 100% 1826KB 1.8MB/s 00:01 + + Now install the debug rpm on the target: + + root@crownbay:~# rpm -i busybox-dbg-1.20.2-r2.core2_32.rpm + + Now that the debuginfo is installed, we see that the busybox + entries now display their functions symbolically: + + + + + + + + If we expand one of the entries and press 'enter' on a leaf node, + we're presented with a menu of actions we can take to get more + information related to that entry: + + + + + + + + One of these actions allows us to show a view that displays a + busybox-centric view of the profiled functions (in this case we've + also expanded all the nodes using the 'E' key): + + + + + + + + Finally, we can see that now that the busybox debuginfo is + installed, the previously unresolved symbol in the + sys_clock_gettime() entry mentioned previously is now resolved, + and shows that the sys_clock_gettime system call that was the + source of 6.75% of the copy-to-user overhead was initiated by + the handle_input() busybox function: + + + + + + + + At the lowest level of detail, we can dive down to the assembly + level and see which instructions caused the most overhead in a + function. Pressing 'enter' on the 'udhcpc_main' function, we're + again presented with a menu: + + + + + + + + Selecting 'Annotate udhcpc_main', we get a detailed listing of + percentages by instruction for the udhcpc_main function. From the + display, we can see that over 50% of the time spent in this + function is taken up by a couple tests and the move of a + constant (1) to a register: + + + + + + + + As a segue into tracing, let's try another profile using a + different counter, something other than the default 'cycles'. + + + + The tracing and profiling infrastructure in Linux has become + unified in a way that allows us to use the same tool with a + completely different set of counters, not just the standard + hardware counters that traditional tools have had to restrict + themselves to (of course the traditional tools can also make use + of the expanded possibilities now available to them, and in some + cases have, as mentioned previously). + + + + We can get a list of the available events that can be used to + profile a workload via 'perf list': + + root@crownbay:~# perf list + + List of pre-defined events (to be used in -e): + cpu-cycles OR cycles [Hardware event] + stalled-cycles-frontend OR idle-cycles-frontend [Hardware event] + stalled-cycles-backend OR idle-cycles-backend [Hardware event] + instructions [Hardware event] + cache-references [Hardware event] + cache-misses [Hardware event] + branch-instructions OR branches [Hardware event] + branch-misses [Hardware event] + bus-cycles [Hardware event] + ref-cycles [Hardware event] + + cpu-clock [Software event] + task-clock [Software event] + page-faults OR faults [Software event] + minor-faults [Software event] + major-faults [Software event] + context-switches OR cs [Software event] + cpu-migrations OR migrations [Software event] + alignment-faults [Software event] + emulation-faults [Software event] + + L1-dcache-loads [Hardware cache event] + L1-dcache-load-misses [Hardware cache event] + L1-dcache-prefetch-misses [Hardware cache event] + L1-icache-loads [Hardware cache event] + L1-icache-load-misses [Hardware cache event] + . + . + . + rNNN [Raw hardware event descriptor] + cpu/t1=v1[,t2=v2,t3 ...]/modifier [Raw hardware event descriptor] + (see 'perf list --help' on how to encode it) + + mem:<addr>[:access] [Hardware breakpoint] + + sunrpc:rpc_call_status [Tracepoint event] + sunrpc:rpc_bind_status [Tracepoint event] + sunrpc:rpc_connect_status [Tracepoint event] + sunrpc:rpc_task_begin [Tracepoint event] + skb:kfree_skb [Tracepoint event] + skb:consume_skb [Tracepoint event] + skb:skb_copy_datagram_iovec [Tracepoint event] + net:net_dev_xmit [Tracepoint event] + net:net_dev_queue [Tracepoint event] + net:netif_receive_skb [Tracepoint event] + net:netif_rx [Tracepoint event] + napi:napi_poll [Tracepoint event] + sock:sock_rcvqueue_full [Tracepoint event] + sock:sock_exceed_buf_limit [Tracepoint event] + udp:udp_fail_queue_rcv_skb [Tracepoint event] + hda:hda_send_cmd [Tracepoint event] + hda:hda_get_response [Tracepoint event] + hda:hda_bus_reset [Tracepoint event] + scsi:scsi_dispatch_cmd_start [Tracepoint event] + scsi:scsi_dispatch_cmd_error [Tracepoint event] + scsi:scsi_eh_wakeup [Tracepoint event] + drm:drm_vblank_event [Tracepoint event] + drm:drm_vblank_event_queued [Tracepoint event] + drm:drm_vblank_event_delivered [Tracepoint event] + random:mix_pool_bytes [Tracepoint event] + random:mix_pool_bytes_nolock [Tracepoint event] + random:credit_entropy_bits [Tracepoint event] + gpio:gpio_direction [Tracepoint event] + gpio:gpio_value [Tracepoint event] + block:block_rq_abort [Tracepoint event] + block:block_rq_requeue [Tracepoint event] + block:block_rq_issue [Tracepoint event] + block:block_bio_bounce [Tracepoint event] + block:block_bio_complete [Tracepoint event] + block:block_bio_backmerge [Tracepoint event] + . + . + writeback:writeback_wake_thread [Tracepoint event] + writeback:writeback_wake_forker_thread [Tracepoint event] + writeback:writeback_bdi_register [Tracepoint event] + . + . + writeback:writeback_single_inode_requeue [Tracepoint event] + writeback:writeback_single_inode [Tracepoint event] + kmem:kmalloc [Tracepoint event] + kmem:kmem_cache_alloc [Tracepoint event] + kmem:mm_page_alloc [Tracepoint event] + kmem:mm_page_alloc_zone_locked [Tracepoint event] + kmem:mm_page_pcpu_drain [Tracepoint event] + kmem:mm_page_alloc_extfrag [Tracepoint event] + vmscan:mm_vmscan_kswapd_sleep [Tracepoint event] + vmscan:mm_vmscan_kswapd_wake [Tracepoint event] + vmscan:mm_vmscan_wakeup_kswapd [Tracepoint event] + vmscan:mm_vmscan_direct_reclaim_begin [Tracepoint event] + . + . + module:module_get [Tracepoint event] + module:module_put [Tracepoint event] + module:module_request [Tracepoint event] + sched:sched_kthread_stop [Tracepoint event] + sched:sched_wakeup [Tracepoint event] + sched:sched_wakeup_new [Tracepoint event] + sched:sched_process_fork [Tracepoint event] + sched:sched_process_exec [Tracepoint event] + sched:sched_stat_runtime [Tracepoint event] + rcu:rcu_utilization [Tracepoint event] + workqueue:workqueue_queue_work [Tracepoint event] + workqueue:workqueue_execute_end [Tracepoint event] + signal:signal_generate [Tracepoint event] + signal:signal_deliver [Tracepoint event] + timer:timer_init [Tracepoint event] + timer:timer_start [Tracepoint event] + timer:hrtimer_cancel [Tracepoint event] + timer:itimer_state [Tracepoint event] + timer:itimer_expire [Tracepoint event] + irq:irq_handler_entry [Tracepoint event] + irq:irq_handler_exit [Tracepoint event] + irq:softirq_entry [Tracepoint event] + irq:softirq_exit [Tracepoint event] + irq:softirq_raise [Tracepoint event] + printk:console [Tracepoint event] + task:task_newtask [Tracepoint event] + task:task_rename [Tracepoint event] + syscalls:sys_enter_socketcall [Tracepoint event] + syscalls:sys_exit_socketcall [Tracepoint event] + . + . + . + syscalls:sys_enter_unshare [Tracepoint event] + syscalls:sys_exit_unshare [Tracepoint event] + raw_syscalls:sys_enter [Tracepoint event] + raw_syscalls:sys_exit [Tracepoint event] + + + + + Tying it Together: These are exactly the same set of events defined + by the trace event subsystem and exposed by + ftrace/tracecmd/kernelshark as files in + /sys/kernel/debug/tracing/events, by SystemTap as + kernel.trace("tracepoint_name") and (partially) accessed by LTTng. + + + + Only a subset of these would be of interest to us when looking at + this workload, so let's choose the most likely subsystems + (identified by the string before the colon in the Tracepoint events) + and do a 'perf stat' run using only those wildcarded subsystems: + + root@crownbay:~# perf stat -e skb:* -e net:* -e napi:* -e sched:* -e workqueue:* -e irq:* -e syscalls:* wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + Performance counter stats for 'wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2': + + 23323 skb:kfree_skb + 0 skb:consume_skb + 49897 skb:skb_copy_datagram_iovec + 6217 net:net_dev_xmit + 6217 net:net_dev_queue + 7962 net:netif_receive_skb + 2 net:netif_rx + 8340 napi:napi_poll + 0 sched:sched_kthread_stop + 0 sched:sched_kthread_stop_ret + 3749 sched:sched_wakeup + 0 sched:sched_wakeup_new + 0 sched:sched_switch + 29 sched:sched_migrate_task + 0 sched:sched_process_free + 1 sched:sched_process_exit + 0 sched:sched_wait_task + 0 sched:sched_process_wait + 0 sched:sched_process_fork + 1 sched:sched_process_exec + 0 sched:sched_stat_wait + 2106519415641 sched:sched_stat_sleep + 0 sched:sched_stat_iowait + 147453613 sched:sched_stat_blocked + 12903026955 sched:sched_stat_runtime + 0 sched:sched_pi_setprio + 3574 workqueue:workqueue_queue_work + 3574 workqueue:workqueue_activate_work + 0 workqueue:workqueue_execute_start + 0 workqueue:workqueue_execute_end + 16631 irq:irq_handler_entry + 16631 irq:irq_handler_exit + 28521 irq:softirq_entry + 28521 irq:softirq_exit + 28728 irq:softirq_raise + 1 syscalls:sys_enter_sendmmsg + 1 syscalls:sys_exit_sendmmsg + 0 syscalls:sys_enter_recvmmsg + 0 syscalls:sys_exit_recvmmsg + 14 syscalls:sys_enter_socketcall + 14 syscalls:sys_exit_socketcall + . + . + . + 16965 syscalls:sys_enter_read + 16965 syscalls:sys_exit_read + 12854 syscalls:sys_enter_write + 12854 syscalls:sys_exit_write + . + . + . + + 58.029710972 seconds time elapsed + + Let's pick one of these tracepoints and tell perf to do a profile + using it as the sampling event: + + root@crownbay:~# perf record -g -e sched:sched_wakeup wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + + + + + + + + + The screenshot above shows the results of running a profile using + sched:sched_switch tracepoint, which shows the relative costs of + various paths to sched_wakeup (note that sched_wakeup is the + name of the tracepoint - it's actually defined just inside + ttwu_do_wakeup(), which accounts for the function name actually + displayed in the profile: + + /* + * Mark the task runnable and perform wakeup-preemption. + */ + static void + ttwu_do_wakeup(struct rq *rq, struct task_struct *p, int wake_flags) + { + trace_sched_wakeup(p, true); + . + . + . + } + + A couple of the more interesting callchains are expanded and + displayed above, basically some network receive paths that + presumably end up waking up wget (busybox) when network data is + ready. + + + + Note that because tracepoints are normally used for tracing, + the default sampling period for tracepoints is 1 i.e. for + tracepoints perf will sample on every event occurrence (this + can be changed using the -c option). This is in contrast to + hardware counters such as for example the default 'cycles' + hardware counter used for normal profiling, where sampling + periods are much higher (in the thousands) because profiling should + have as low an overhead as possible and sampling on every cycle + would be prohibitively expensive. + +
+ +
+ Using perf to do Basic Tracing + + + Profiling is a great tool for solving many problems or for + getting a high-level view of what's going on with a workload or + across the system. It is however by definition an approximation, + as suggested by the most prominent word associated with it, + 'sampling'. On the one hand, it allows a representative picture of + what's going on in the system to be cheaply taken, but on the other + hand, that cheapness limits its utility when that data suggests a + need to 'dive down' more deeply to discover what's really going + on. In such cases, the only way to see what's really going on is + to be able to look at (or summarize more intelligently) the + individual steps that go into the higher-level behavior exposed + by the coarse-grained profiling data. + + + + As a concrete example, we can trace all the events we think might + be applicable to our workload: + + root@crownbay:~# perf record -g -e skb:* -e net:* -e napi:* -e sched:sched_switch -e sched:sched_wakeup -e irq:* + -e syscalls:sys_enter_read -e syscalls:sys_exit_read -e syscalls:sys_enter_write -e syscalls:sys_exit_write + wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + + We can look at the raw trace output using 'perf script' with no + arguments: + + root@crownbay:~# perf script + + perf 1262 [000] 11624.857082: sys_exit_read: 0x0 + perf 1262 [000] 11624.857193: sched_wakeup: comm=migration/0 pid=6 prio=0 success=1 target_cpu=000 + wget 1262 [001] 11624.858021: softirq_raise: vec=1 [action=TIMER] + wget 1262 [001] 11624.858074: softirq_entry: vec=1 [action=TIMER] + wget 1262 [001] 11624.858081: softirq_exit: vec=1 [action=TIMER] + wget 1262 [001] 11624.858166: sys_enter_read: fd: 0x0003, buf: 0xbf82c940, count: 0x0200 + wget 1262 [001] 11624.858177: sys_exit_read: 0x200 + wget 1262 [001] 11624.858878: kfree_skb: skbaddr=0xeb248d80 protocol=0 location=0xc15a5308 + wget 1262 [001] 11624.858945: kfree_skb: skbaddr=0xeb248000 protocol=0 location=0xc15a5308 + wget 1262 [001] 11624.859020: softirq_raise: vec=1 [action=TIMER] + wget 1262 [001] 11624.859076: softirq_entry: vec=1 [action=TIMER] + wget 1262 [001] 11624.859083: softirq_exit: vec=1 [action=TIMER] + wget 1262 [001] 11624.859167: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400 + wget 1262 [001] 11624.859192: sys_exit_read: 0x1d7 + wget 1262 [001] 11624.859228: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400 + wget 1262 [001] 11624.859233: sys_exit_read: 0x0 + wget 1262 [001] 11624.859573: sys_enter_read: fd: 0x0003, buf: 0xbf82c580, count: 0x0200 + wget 1262 [001] 11624.859584: sys_exit_read: 0x200 + wget 1262 [001] 11624.859864: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400 + wget 1262 [001] 11624.859888: sys_exit_read: 0x400 + wget 1262 [001] 11624.859935: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400 + wget 1262 [001] 11624.859944: sys_exit_read: 0x400 + + This gives us a detailed timestamped sequence of events that + occurred within the workload with respect to those events. + + + + In many ways, profiling can be viewed as a subset of tracing - + theoretically, if you have a set of trace events that's sufficient + to capture all the important aspects of a workload, you can derive + any of the results or views that a profiling run can. + + + + Another aspect of traditional profiling is that while powerful in + many ways, it's limited by the granularity of the underlying data. + Profiling tools offer various ways of sorting and presenting the + sample data, which make it much more useful and amenable to user + experimentation, but in the end it can't be used in an open-ended + way to extract data that just isn't present as a consequence of + the fact that conceptually, most of it has been thrown away. + + + + Full-blown detailed tracing data does however offer the opportunity + to manipulate and present the information collected during a + tracing run in an infinite variety of ways. + + + + Another way to look at it is that there are only so many ways that + the 'primitive' counters can be used on their own to generate + interesting output; to get anything more complicated than simple + counts requires some amount of additional logic, which is typically + very specific to the problem at hand. For example, if we wanted to + make use of a 'counter' that maps to the value of the time + difference between when a process was scheduled to run on a + processor and the time it actually ran, we wouldn't expect such + a counter to exist on its own, but we could derive one called say + 'wakeup_latency' and use it to extract a useful view of that metric + from trace data. Likewise, we really can't figure out from standard + profiling tools how much data every process on the system reads and + writes, along with how many of those reads and writes fail + completely. If we have sufficient trace data, however, we could + with the right tools easily extract and present that information, + but we'd need something other than pre-canned profiling tools to + do that. + + + + Luckily, there is a general-purpose way to handle such needs, + called 'programming languages'. Making programming languages + easily available to apply to such problems given the specific + format of data is called a 'programming language binding' for + that data and language. Perf supports two programming language + bindings, one for Python and one for Perl. + + + + Tying it Together: Language bindings for manipulating and + aggregating trace data are of course not a new + idea. One of the first projects to do this was IBM's DProbes + dpcc compiler, an ANSI C compiler which targeted a low-level + assembly language running on an in-kernel interpreter on the + target system. This is exactly analogous to what Sun's DTrace + did, except that DTrace invented its own language for the purpose. + Systemtap, heavily inspired by DTrace, also created its own + one-off language, but rather than running the product on an + in-kernel interpreter, created an elaborate compiler-based + machinery to translate its language into kernel modules written + in C. + + + + Now that we have the trace data in perf.data, we can use + 'perf script -g' to generate a skeleton script with handlers + for the read/write entry/exit events we recorded: + + root@crownbay:~# perf script -g python + generated Python script: perf-script.py + + The skeleton script simply creates a python function for each + event type in the perf.data file. The body of each function simply + prints the event name along with its parameters. For example: + + def net__netif_rx(event_name, context, common_cpu, + common_secs, common_nsecs, common_pid, common_comm, + skbaddr, len, name): + print_header(event_name, common_cpu, common_secs, common_nsecs, + common_pid, common_comm) + + print "skbaddr=%u, len=%u, name=%s\n" % (skbaddr, len, name), + + We can run that script directly to print all of the events + contained in the perf.data file: + + root@crownbay:~# perf script -s perf-script.py + + in trace_begin + syscalls__sys_exit_read 0 11624.857082795 1262 perf nr=3, ret=0 + sched__sched_wakeup 0 11624.857193498 1262 perf comm=migration/0, pid=6, prio=0, success=1, target_cpu=0 + irq__softirq_raise 1 11624.858021635 1262 wget vec=TIMER + irq__softirq_entry 1 11624.858074075 1262 wget vec=TIMER + irq__softirq_exit 1 11624.858081389 1262 wget vec=TIMER + syscalls__sys_enter_read 1 11624.858166434 1262 wget nr=3, fd=3, buf=3213019456, count=512 + syscalls__sys_exit_read 1 11624.858177924 1262 wget nr=3, ret=512 + skb__kfree_skb 1 11624.858878188 1262 wget skbaddr=3945041280, location=3243922184, protocol=0 + skb__kfree_skb 1 11624.858945608 1262 wget skbaddr=3945037824, location=3243922184, protocol=0 + irq__softirq_raise 1 11624.859020942 1262 wget vec=TIMER + irq__softirq_entry 1 11624.859076935 1262 wget vec=TIMER + irq__softirq_exit 1 11624.859083469 1262 wget vec=TIMER + syscalls__sys_enter_read 1 11624.859167565 1262 wget nr=3, fd=3, buf=3077701632, count=1024 + syscalls__sys_exit_read 1 11624.859192533 1262 wget nr=3, ret=471 + syscalls__sys_enter_read 1 11624.859228072 1262 wget nr=3, fd=3, buf=3077701632, count=1024 + syscalls__sys_exit_read 1 11624.859233707 1262 wget nr=3, ret=0 + syscalls__sys_enter_read 1 11624.859573008 1262 wget nr=3, fd=3, buf=3213018496, count=512 + syscalls__sys_exit_read 1 11624.859584818 1262 wget nr=3, ret=512 + syscalls__sys_enter_read 1 11624.859864562 1262 wget nr=3, fd=3, buf=3077701632, count=1024 + syscalls__sys_exit_read 1 11624.859888770 1262 wget nr=3, ret=1024 + syscalls__sys_enter_read 1 11624.859935140 1262 wget nr=3, fd=3, buf=3077701632, count=1024 + syscalls__sys_exit_read 1 11624.859944032 1262 wget nr=3, ret=1024 + + That in itself isn't very useful; after all, we can accomplish + pretty much the same thing by simply running 'perf script' + without arguments in the same directory as the perf.data file. + + + + We can however replace the print statements in the generated + function bodies with whatever we want, and thereby make it + infinitely more useful. + + + + As a simple example, let's just replace the print statements in + the function bodies with a simple function that does nothing but + increment a per-event count. When the program is run against a + perf.data file, each time a particular event is encountered, + a tally is incremented for that event. For example: + + def net__netif_rx(event_name, context, common_cpu, + common_secs, common_nsecs, common_pid, common_comm, + skbaddr, len, name): + inc_counts(event_name) + + Each event handler function in the generated code is modified + to do this. For convenience, we define a common function called + inc_counts() that each handler calls; inc_counts() simply tallies + a count for each event using the 'counts' hash, which is a + specialized hash function that does Perl-like autovivification, a + capability that's extremely useful for kinds of multi-level + aggregation commonly used in processing traces (see perf's + documentation on the Python language binding for details): + + counts = autodict() + + def inc_counts(event_name): + try: + counts[event_name] += 1 + except TypeError: + counts[event_name] = 1 + + Finally, at the end of the trace processing run, we want to + print the result of all the per-event tallies. For that, we + use the special 'trace_end()' function: + + def trace_end(): + for event_name, count in counts.iteritems(): + print "%-40s %10s\n" % (event_name, count) + + The end result is a summary of all the events recorded in the + trace: + + skb__skb_copy_datagram_iovec 13148 + irq__softirq_entry 4796 + irq__irq_handler_exit 3805 + irq__softirq_exit 4795 + syscalls__sys_enter_write 8990 + net__net_dev_xmit 652 + skb__kfree_skb 4047 + sched__sched_wakeup 1155 + irq__irq_handler_entry 3804 + irq__softirq_raise 4799 + net__net_dev_queue 652 + syscalls__sys_enter_read 17599 + net__netif_receive_skb 1743 + syscalls__sys_exit_read 17598 + net__netif_rx 2 + napi__napi_poll 1877 + syscalls__sys_exit_write 8990 + + Note that this is pretty much exactly the same information we get + from 'perf stat', which goes a little way to support the idea + mentioned previously that given the right kind of trace data, + higher-level profiling-type summaries can be derived from it. + + + + Documentation on using the + 'perf script' python binding. + +
+ +
+ System-Wide Tracing and Profiling + + + The examples so far have focused on tracing a particular program or + workload - in other words, every profiling run has specified the + program to profile in the command-line e.g. 'perf record wget ...'. + + + + It's also possible, and more interesting in many cases, to run a + system-wide profile or trace while running the workload in a + separate shell. + + + + To do system-wide profiling or tracing, you typically use + the -a flag to 'perf record'. + + + + To demonstrate this, open up one window and start the profile + using the -a flag (press Ctrl-C to stop tracing): + + root@crownbay:~# perf record -g -a + ^C[ perf record: Woken up 6 times to write data ] + [ perf record: Captured and wrote 1.400 MB perf.data (~61172 samples) ] + + In another window, run the wget test: + + root@crownbay:~# wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |*******************************| 41727k 0:00:00 ETA + + Here we see entries not only for our wget load, but for other + processes running on the system as well: + + + + + + + + In the snapshot above, we can see callchains that originate in + libc, and a callchain from Xorg that demonstrates that we're + using a proprietary X driver in userspace (notice the presence + of 'PVR' and some other unresolvable symbols in the expanded + Xorg callchain). + + + + Note also that we have both kernel and userspace entries in the + above snapshot. We can also tell perf to focus on userspace but + providing a modifier, in this case 'u', to the 'cycles' hardware + counter when we record a profile: + + root@crownbay:~# perf record -g -a -e cycles:u + ^C[ perf record: Woken up 2 times to write data ] + [ perf record: Captured and wrote 0.376 MB perf.data (~16443 samples) ] + + + + + + + + + Notice in the screenshot above, we see only userspace entries ([.]) + + + + Finally, we can press 'enter' on a leaf node and select the 'Zoom + into DSO' menu item to show only entries associated with a + specific DSO. In the screenshot below, we've zoomed into the + 'libc' DSO which shows all the entries associated with the + libc-xxx.so DSO. + + + + + + + + We can also use the system-wide -a switch to do system-wide + tracing. Here we'll trace a couple of scheduler events: + + root@crownbay:~# perf record -a -e sched:sched_switch -e sched:sched_wakeup + ^C[ perf record: Woken up 38 times to write data ] + [ perf record: Captured and wrote 9.780 MB perf.data (~427299 samples) ] + + We can look at the raw output using 'perf script' with no + arguments: + + root@crownbay:~# perf script + + perf 1383 [001] 6171.460045: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + perf 1383 [001] 6171.460066: sched_switch: prev_comm=perf prev_pid=1383 prev_prio=120 prev_state=R+ ==> next_comm=kworker/1:1 next_pid=21 next_prio=120 + kworker/1:1 21 [001] 6171.460093: sched_switch: prev_comm=kworker/1:1 prev_pid=21 prev_prio=120 prev_state=S ==> next_comm=perf next_pid=1383 next_prio=120 + swapper 0 [000] 6171.468063: sched_wakeup: comm=kworker/0:3 pid=1209 prio=120 success=1 target_cpu=000 + swapper 0 [000] 6171.468107: sched_switch: prev_comm=swapper/0 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/0:3 next_pid=1209 next_prio=120 + kworker/0:3 1209 [000] 6171.468143: sched_switch: prev_comm=kworker/0:3 prev_pid=1209 prev_prio=120 prev_state=S ==> next_comm=swapper/0 next_pid=0 next_prio=120 + perf 1383 [001] 6171.470039: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + perf 1383 [001] 6171.470058: sched_switch: prev_comm=perf prev_pid=1383 prev_prio=120 prev_state=R+ ==> next_comm=kworker/1:1 next_pid=21 next_prio=120 + kworker/1:1 21 [001] 6171.470082: sched_switch: prev_comm=kworker/1:1 prev_pid=21 prev_prio=120 prev_state=S ==> next_comm=perf next_pid=1383 next_prio=120 + perf 1383 [001] 6171.480035: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + + + +
+ Filtering + + + Notice that there are a lot of events that don't really have + anything to do with what we're interested in, namely events + that schedule 'perf' itself in and out or that wake perf up. + We can get rid of those by using the '--filter' option - + for each event we specify using -e, we can add a --filter + after that to filter out trace events that contain fields + with specific values: + + root@crownbay:~# perf record -a -e sched:sched_switch --filter 'next_comm != perf && prev_comm != perf' -e sched:sched_wakeup --filter 'comm != perf' + ^C[ perf record: Woken up 38 times to write data ] + [ perf record: Captured and wrote 9.688 MB perf.data (~423279 samples) ] + + + root@crownbay:~# perf script + + swapper 0 [000] 7932.162180: sched_switch: prev_comm=swapper/0 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/0:3 next_pid=1209 next_prio=120 + kworker/0:3 1209 [000] 7932.162236: sched_switch: prev_comm=kworker/0:3 prev_pid=1209 prev_prio=120 prev_state=S ==> next_comm=swapper/0 next_pid=0 next_prio=120 + perf 1407 [001] 7932.170048: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + perf 1407 [001] 7932.180044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + perf 1407 [001] 7932.190038: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + perf 1407 [001] 7932.200044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + perf 1407 [001] 7932.210044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + perf 1407 [001] 7932.220044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + swapper 0 [001] 7932.230111: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001 + swapper 0 [001] 7932.230146: sched_switch: prev_comm=swapper/1 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/1:1 next_pid=21 next_prio=120 + kworker/1:1 21 [001] 7932.230205: sched_switch: prev_comm=kworker/1:1 prev_pid=21 prev_prio=120 prev_state=S ==> next_comm=swapper/1 next_pid=0 next_prio=120 + swapper 0 [000] 7932.326109: sched_wakeup: comm=kworker/0:3 pid=1209 prio=120 success=1 target_cpu=000 + swapper 0 [000] 7932.326171: sched_switch: prev_comm=swapper/0 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/0:3 next_pid=1209 next_prio=120 + kworker/0:3 1209 [000] 7932.326214: sched_switch: prev_comm=kworker/0:3 prev_pid=1209 prev_prio=120 prev_state=S ==> next_comm=swapper/0 next_pid=0 next_prio=120 + + In this case, we've filtered out all events that have 'perf' + in their 'comm' or 'comm_prev' or 'comm_next' fields. Notice + that there are still events recorded for perf, but notice + that those events don't have values of 'perf' for the filtered + fields. To completely filter out anything from perf will + require a bit more work, but for the purpose of demonstrating + how to use filters, it's close enough. + + + + Tying it Together: These are exactly the same set of event + filters defined by the trace event subsystem. See the + ftrace/tracecmd/kernelshark section for more discussion about + these event filters. + + + + Tying it Together: These event filters are implemented by a + special-purpose pseudo-interpreter in the kernel and are an + integral and indispensable part of the perf design as it + relates to tracing. kernel-based event filters provide a + mechanism to precisely throttle the event stream that appears + in user space, where it makes sense to provide bindings to real + programming languages for postprocessing the event stream. + This architecture allows for the intelligent and flexible + partitioning of processing between the kernel and user space. + Contrast this with other tools such as SystemTap, which does + all of its processing in the kernel and as such requires a + special project-defined language in order to accommodate that + design, or LTTng, where everything is sent to userspace and + as such requires a super-efficient kernel-to-userspace + transport mechanism in order to function properly. While + perf certainly can benefit from for instance advances in + the design of the transport, it doesn't fundamentally depend + on them. Basically, if you find that your perf tracing + application is causing buffer I/O overruns, it probably + means that you aren't taking enough advantage of the + kernel filtering engine. + +
+
+ +
+ Using Dynamic Tracepoints + + + perf isn't restricted to the fixed set of static tracepoints + listed by 'perf list'. Users can also add their own 'dynamic' + tracepoints anywhere in the kernel. For instance, suppose we + want to define our own tracepoint on do_fork(). We can do that + using the 'perf probe' perf subcommand: + + root@crownbay:~# perf probe do_fork + Added new event: + probe:do_fork (on do_fork) + + You can now use it in all perf tools, such as: + + perf record -e probe:do_fork -aR sleep 1 + + Adding a new tracepoint via 'perf probe' results in an event + with all the expected files and format in + /sys/kernel/debug/tracing/events, just the same as for static + tracepoints (as discussed in more detail in the trace events + subsystem section: + + root@crownbay:/sys/kernel/debug/tracing/events/probe/do_fork# ls -al + drwxr-xr-x 2 root root 0 Oct 28 11:42 . + drwxr-xr-x 3 root root 0 Oct 28 11:42 .. + -rw-r--r-- 1 root root 0 Oct 28 11:42 enable + -rw-r--r-- 1 root root 0 Oct 28 11:42 filter + -r--r--r-- 1 root root 0 Oct 28 11:42 format + -r--r--r-- 1 root root 0 Oct 28 11:42 id + + root@crownbay:/sys/kernel/debug/tracing/events/probe/do_fork# cat format + name: do_fork + ID: 944 + format: + field:unsigned short common_type; offset:0; size:2; signed:0; + field:unsigned char common_flags; offset:2; size:1; signed:0; + field:unsigned char common_preempt_count; offset:3; size:1; signed:0; + field:int common_pid; offset:4; size:4; signed:1; + field:int common_padding; offset:8; size:4; signed:1; + + field:unsigned long __probe_ip; offset:12; size:4; signed:0; + + print fmt: "(%lx)", REC->__probe_ip + + We can list all dynamic tracepoints currently in existence: + + root@crownbay:~# perf probe -l + probe:do_fork (on do_fork) + probe:schedule (on schedule) + + Let's record system-wide ('sleep 30' is a trick for recording + system-wide but basically do nothing and then wake up after + 30 seconds): + + root@crownbay:~# perf record -g -a -e probe:do_fork sleep 30 + [ perf record: Woken up 1 times to write data ] + [ perf record: Captured and wrote 0.087 MB perf.data (~3812 samples) ] + + Using 'perf script' we can see each do_fork event that fired: + + root@crownbay:~# perf script + + # ======== + # captured on: Sun Oct 28 11:55:18 2012 + # hostname : crownbay + # os release : 3.4.11-yocto-standard + # perf version : 3.4.11 + # arch : i686 + # nrcpus online : 2 + # nrcpus avail : 2 + # cpudesc : Intel(R) Atom(TM) CPU E660 @ 1.30GHz + # cpuid : GenuineIntel,6,38,1 + # total memory : 1017184 kB + # cmdline : /usr/bin/perf record -g -a -e probe:do_fork sleep 30 + # event : name = probe:do_fork, type = 2, config = 0x3b0, config1 = 0x0, config2 = 0x0, excl_usr = 0, excl_kern + = 0, id = { 5, 6 } + # HEADER_CPU_TOPOLOGY info available, use -I to display + # ======== + # + matchbox-deskto 1197 [001] 34211.378318: do_fork: (c1028460) + matchbox-deskto 1295 [001] 34211.380388: do_fork: (c1028460) + pcmanfm 1296 [000] 34211.632350: do_fork: (c1028460) + pcmanfm 1296 [000] 34211.639917: do_fork: (c1028460) + matchbox-deskto 1197 [001] 34217.541603: do_fork: (c1028460) + matchbox-deskto 1299 [001] 34217.543584: do_fork: (c1028460) + gthumb 1300 [001] 34217.697451: do_fork: (c1028460) + gthumb 1300 [001] 34219.085734: do_fork: (c1028460) + gthumb 1300 [000] 34219.121351: do_fork: (c1028460) + gthumb 1300 [001] 34219.264551: do_fork: (c1028460) + pcmanfm 1296 [000] 34219.590380: do_fork: (c1028460) + matchbox-deskto 1197 [001] 34224.955965: do_fork: (c1028460) + matchbox-deskto 1306 [001] 34224.957972: do_fork: (c1028460) + matchbox-termin 1307 [000] 34225.038214: do_fork: (c1028460) + matchbox-termin 1307 [001] 34225.044218: do_fork: (c1028460) + matchbox-termin 1307 [000] 34225.046442: do_fork: (c1028460) + matchbox-deskto 1197 [001] 34237.112138: do_fork: (c1028460) + matchbox-deskto 1311 [001] 34237.114106: do_fork: (c1028460) + gaku 1312 [000] 34237.202388: do_fork: (c1028460) + + And using 'perf report' on the same file, we can see the + callgraphs from starting a few programs during those 30 seconds: + + + + + + + + Tying it Together: The trace events subsystem accommodate static + and dynamic tracepoints in exactly the same way - there's no + difference as far as the infrastructure is concerned. See the + ftrace section for more details on the trace event subsystem. + + + + Tying it Together: Dynamic tracepoints are implemented under the + covers by kprobes and uprobes. kprobes and uprobes are also used + by and in fact are the main focus of SystemTap. + +
+
+ +
+ Documentation + + + Online versions of the man pages for the commands discussed in this + section can be found here: + + The 'perf stat' manpage. + + The 'perf record' manpage. + + The 'perf report' manpage. + + The 'perf probe' manpage. + + The 'perf script' manpage. + + Documentation on using the + 'perf script' python binding. + + The top-level + perf(1) manpage. + + + + + + Normally, you should be able to invoke the man pages via perf + itself e.g. 'perf help' or 'perf help record'. + + + + However, by default Yocto doesn't install man pages, but perf + invokes the man pages for most help functionality. This is a bug + and is being addressed by a Yocto bug: + Bug 3388 - perf: enable man pages for basic 'help' functionality. + + + + The man pages in text form, along with some other files, such as + a set of examples, can be found in the 'perf' directory of the + kernel tree: + + tools/perf/Documentation + + There's also a nice perf tutorial on the perf wiki that goes + into more detail than we do here in certain areas: + Perf Tutorial + +
+
+ +
+ ftrace + + + 'ftrace' literally refers to the 'ftrace function tracer' but in + reality this encompasses a number of related tracers along with + the infrastructure that they all make use of. + + +
+ Setup + + + For this section, we'll assume you've already performed the basic + setup outlined in the General Setup section. + + + + ftrace, trace-cmd, and kernelshark run on the target system, + and are ready to go out-of-the-box - no additional setup is + necessary. For the rest of this section we assume you've ssh'ed + to the host and will be running ftrace on the target. kernelshark + is a GUI application and if you use the '-X' option to ssh you + can have the kernelshark GUI run on the target but display + remotely on the host if you want. + +
+ +
+ Basic ftrace usage + + + 'ftrace' essentially refers to everything included in + the /tracing directory of the mounted debugfs filesystem + (Yocto follows the standard convention and mounts it + at /sys/kernel/debug). Here's a listing of all the files + found in /sys/kernel/debug/tracing on a Yocto system: + + root@sugarbay:/sys/kernel/debug/tracing# ls + README kprobe_events trace + available_events kprobe_profile trace_clock + available_filter_functions options trace_marker + available_tracers per_cpu trace_options + buffer_size_kb printk_formats trace_pipe + buffer_total_size_kb saved_cmdlines tracing_cpumask + current_tracer set_event tracing_enabled + dyn_ftrace_total_info set_ftrace_filter tracing_on + enabled_functions set_ftrace_notrace tracing_thresh + events set_ftrace_pid + free_buffer set_graph_function + + The files listed above are used for various purposes - + some relate directly to the tracers themselves, others are + used to set tracing options, and yet others actually contain + the tracing output when a tracer is in effect. Some of the + functions can be guessed from their names, others need + explanation; in any case, we'll cover some of the files we + see here below but for an explanation of the others, please + see the ftrace documentation. + + + + We'll start by looking at some of the available built-in + tracers. + + + + cat'ing the 'available_tracers' file lists the set of + available tracers: + + root@sugarbay:/sys/kernel/debug/tracing# cat available_tracers + blk function_graph function nop + + The 'current_tracer' file contains the tracer currently in + effect: + + root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer + nop + + The above listing of current_tracer shows that + the 'nop' tracer is in effect, which is just another + way of saying that there's actually no tracer + currently in effect. + + + + echo'ing one of the available_tracers into current_tracer + makes the specified tracer the current tracer: + + root@sugarbay:/sys/kernel/debug/tracing# echo function > current_tracer + root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer + function + + The above sets the current tracer to be the + 'function tracer'. This tracer traces every function + call in the kernel and makes it available as the + contents of the 'trace' file. Reading the 'trace' file + lists the currently buffered function calls that have been + traced by the function tracer: + + root@sugarbay:/sys/kernel/debug/tracing# cat trace | less + + # tracer: function + # + # entries-in-buffer/entries-written: 310629/766471 #P:8 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + <idle>-0 [004] d..1 470.867169: ktime_get_real <-intel_idle + <idle>-0 [004] d..1 470.867170: getnstimeofday <-ktime_get_real + <idle>-0 [004] d..1 470.867171: ns_to_timeval <-intel_idle + <idle>-0 [004] d..1 470.867171: ns_to_timespec <-ns_to_timeval + <idle>-0 [004] d..1 470.867172: smp_apic_timer_interrupt <-apic_timer_interrupt + <idle>-0 [004] d..1 470.867172: native_apic_mem_write <-smp_apic_timer_interrupt + <idle>-0 [004] d..1 470.867172: irq_enter <-smp_apic_timer_interrupt + <idle>-0 [004] d..1 470.867172: rcu_irq_enter <-irq_enter + <idle>-0 [004] d..1 470.867173: rcu_idle_exit_common.isra.33 <-rcu_irq_enter + <idle>-0 [004] d..1 470.867173: local_bh_disable <-irq_enter + <idle>-0 [004] d..1 470.867173: add_preempt_count <-local_bh_disable + <idle>-0 [004] d.s1 470.867174: tick_check_idle <-irq_enter + <idle>-0 [004] d.s1 470.867174: tick_check_oneshot_broadcast <-tick_check_idle + <idle>-0 [004] d.s1 470.867174: ktime_get <-tick_check_idle + <idle>-0 [004] d.s1 470.867174: tick_nohz_stop_idle <-tick_check_idle + <idle>-0 [004] d.s1 470.867175: update_ts_time_stats <-tick_nohz_stop_idle + <idle>-0 [004] d.s1 470.867175: nr_iowait_cpu <-update_ts_time_stats + <idle>-0 [004] d.s1 470.867175: tick_do_update_jiffies64 <-tick_check_idle + <idle>-0 [004] d.s1 470.867175: _raw_spin_lock <-tick_do_update_jiffies64 + <idle>-0 [004] d.s1 470.867176: add_preempt_count <-_raw_spin_lock + <idle>-0 [004] d.s2 470.867176: do_timer <-tick_do_update_jiffies64 + <idle>-0 [004] d.s2 470.867176: _raw_spin_lock <-do_timer + <idle>-0 [004] d.s2 470.867176: add_preempt_count <-_raw_spin_lock + <idle>-0 [004] d.s3 470.867177: ntp_tick_length <-do_timer + <idle>-0 [004] d.s3 470.867177: _raw_spin_lock_irqsave <-ntp_tick_length + . + . + . + + Each line in the trace above shows what was happening in + the kernel on a given cpu, to the level of detail of + function calls. Each entry shows the function called, + followed by its caller (after the arrow). + + + + The function tracer gives you an extremely detailed idea + of what the kernel was doing at the point in time the trace + was taken, and is a great way to learn about how the kernel + code works in a dynamic sense. + + + + Tying it Together: The ftrace function tracer is also + available from within perf, as the ftrace:function tracepoint. + + + + It is a little more difficult to follow the call chains than + it needs to be - luckily there's a variant of the function + tracer that displays the callchains explicitly, called the + 'function_graph' tracer: + + root@sugarbay:/sys/kernel/debug/tracing# echo function_graph > current_tracer + root@sugarbay:/sys/kernel/debug/tracing# cat trace | less + + tracer: function_graph + + CPU DURATION FUNCTION CALLS + | | | | | | | + 7) 0.046 us | pick_next_task_fair(); + 7) 0.043 us | pick_next_task_stop(); + 7) 0.042 us | pick_next_task_rt(); + 7) 0.032 us | pick_next_task_fair(); + 7) 0.030 us | pick_next_task_idle(); + 7) | _raw_spin_unlock_irq() { + 7) 0.033 us | sub_preempt_count(); + 7) 0.258 us | } + 7) 0.032 us | sub_preempt_count(); + 7) + 13.341 us | } /* __schedule */ + 7) 0.095 us | } /* sub_preempt_count */ + 7) | schedule() { + 7) | __schedule() { + 7) 0.060 us | add_preempt_count(); + 7) 0.044 us | rcu_note_context_switch(); + 7) | _raw_spin_lock_irq() { + 7) 0.033 us | add_preempt_count(); + 7) 0.247 us | } + 7) | idle_balance() { + 7) | _raw_spin_unlock() { + 7) 0.031 us | sub_preempt_count(); + 7) 0.246 us | } + 7) | update_shares() { + 7) 0.030 us | __rcu_read_lock(); + 7) 0.029 us | __rcu_read_unlock(); + 7) 0.484 us | } + 7) 0.030 us | __rcu_read_lock(); + 7) | load_balance() { + 7) | find_busiest_group() { + 7) 0.031 us | idle_cpu(); + 7) 0.029 us | idle_cpu(); + 7) 0.035 us | idle_cpu(); + 7) 0.906 us | } + 7) 1.141 us | } + 7) 0.022 us | msecs_to_jiffies(); + 7) | load_balance() { + 7) | find_busiest_group() { + 7) 0.031 us | idle_cpu(); + . + . + . + 4) 0.062 us | msecs_to_jiffies(); + 4) 0.062 us | __rcu_read_unlock(); + 4) | _raw_spin_lock() { + 4) 0.073 us | add_preempt_count(); + 4) 0.562 us | } + 4) + 17.452 us | } + 4) 0.108 us | put_prev_task_fair(); + 4) 0.102 us | pick_next_task_fair(); + 4) 0.084 us | pick_next_task_stop(); + 4) 0.075 us | pick_next_task_rt(); + 4) 0.062 us | pick_next_task_fair(); + 4) 0.066 us | pick_next_task_idle(); + ------------------------------------------ + 4) kworker-74 => <idle>-0 + ------------------------------------------ + + 4) | finish_task_switch() { + 4) | _raw_spin_unlock_irq() { + 4) 0.100 us | sub_preempt_count(); + 4) 0.582 us | } + 4) 1.105 us | } + 4) 0.088 us | sub_preempt_count(); + 4) ! 100.066 us | } + . + . + . + 3) | sys_ioctl() { + 3) 0.083 us | fget_light(); + 3) | security_file_ioctl() { + 3) 0.066 us | cap_file_ioctl(); + 3) 0.562 us | } + 3) | do_vfs_ioctl() { + 3) | drm_ioctl() { + 3) 0.075 us | drm_ut_debug_printk(); + 3) | i915_gem_pwrite_ioctl() { + 3) | i915_mutex_lock_interruptible() { + 3) 0.070 us | mutex_lock_interruptible(); + 3) 0.570 us | } + 3) | drm_gem_object_lookup() { + 3) | _raw_spin_lock() { + 3) 0.080 us | add_preempt_count(); + 3) 0.620 us | } + 3) | _raw_spin_unlock() { + 3) 0.085 us | sub_preempt_count(); + 3) 0.562 us | } + 3) 2.149 us | } + 3) 0.133 us | i915_gem_object_pin(); + 3) | i915_gem_object_set_to_gtt_domain() { + 3) 0.065 us | i915_gem_object_flush_gpu_write_domain(); + 3) 0.065 us | i915_gem_object_wait_rendering(); + 3) 0.062 us | i915_gem_object_flush_cpu_write_domain(); + 3) 1.612 us | } + 3) | i915_gem_object_put_fence() { + 3) 0.097 us | i915_gem_object_flush_fence.constprop.36(); + 3) 0.645 us | } + 3) 0.070 us | add_preempt_count(); + 3) 0.070 us | sub_preempt_count(); + 3) 0.073 us | i915_gem_object_unpin(); + 3) 0.068 us | mutex_unlock(); + 3) 9.924 us | } + 3) + 11.236 us | } + 3) + 11.770 us | } + 3) + 13.784 us | } + 3) | sys_ioctl() { + + As you can see, the function_graph display is much easier to + follow. Also note that in addition to the function calls and + associated braces, other events such as scheduler events + are displayed in context. In fact, you can freely include + any tracepoint available in the trace events subsystem described + in the next section by simply enabling those events, and they'll + appear in context in the function graph display. Quite a + powerful tool for understanding kernel dynamics. + + + + Also notice that there are various annotations on the left + hand side of the display. For example if the total time it + took for a given function to execute is above a certain + threshold, an exclamation point or plus sign appears on the + left hand side. Please see the ftrace documentation for + details on all these fields. + +
+ +
+ The 'trace events' Subsystem + + + One especially important directory contained within + the /sys/kernel/debug/tracing directory is the 'events' + subdirectory, which contains representations of every + tracepoint in the system. Listing out the contents of + the 'events' subdirectory, we see mainly another set of + subdirectories: + + root@sugarbay:/sys/kernel/debug/tracing# cd events + root@sugarbay:/sys/kernel/debug/tracing/events# ls -al + drwxr-xr-x 38 root root 0 Nov 14 23:19 . + drwxr-xr-x 5 root root 0 Nov 14 23:19 .. + drwxr-xr-x 19 root root 0 Nov 14 23:19 block + drwxr-xr-x 32 root root 0 Nov 14 23:19 btrfs + drwxr-xr-x 5 root root 0 Nov 14 23:19 drm + -rw-r--r-- 1 root root 0 Nov 14 23:19 enable + drwxr-xr-x 40 root root 0 Nov 14 23:19 ext3 + drwxr-xr-x 79 root root 0 Nov 14 23:19 ext4 + drwxr-xr-x 14 root root 0 Nov 14 23:19 ftrace + drwxr-xr-x 8 root root 0 Nov 14 23:19 hda + -r--r--r-- 1 root root 0 Nov 14 23:19 header_event + -r--r--r-- 1 root root 0 Nov 14 23:19 header_page + drwxr-xr-x 25 root root 0 Nov 14 23:19 i915 + drwxr-xr-x 7 root root 0 Nov 14 23:19 irq + drwxr-xr-x 12 root root 0 Nov 14 23:19 jbd + drwxr-xr-x 14 root root 0 Nov 14 23:19 jbd2 + drwxr-xr-x 14 root root 0 Nov 14 23:19 kmem + drwxr-xr-x 7 root root 0 Nov 14 23:19 module + drwxr-xr-x 3 root root 0 Nov 14 23:19 napi + drwxr-xr-x 6 root root 0 Nov 14 23:19 net + drwxr-xr-x 3 root root 0 Nov 14 23:19 oom + drwxr-xr-x 12 root root 0 Nov 14 23:19 power + drwxr-xr-x 3 root root 0 Nov 14 23:19 printk + drwxr-xr-x 8 root root 0 Nov 14 23:19 random + drwxr-xr-x 4 root root 0 Nov 14 23:19 raw_syscalls + drwxr-xr-x 3 root root 0 Nov 14 23:19 rcu + drwxr-xr-x 6 root root 0 Nov 14 23:19 rpm + drwxr-xr-x 20 root root 0 Nov 14 23:19 sched + drwxr-xr-x 7 root root 0 Nov 14 23:19 scsi + drwxr-xr-x 4 root root 0 Nov 14 23:19 signal + drwxr-xr-x 5 root root 0 Nov 14 23:19 skb + drwxr-xr-x 4 root root 0 Nov 14 23:19 sock + drwxr-xr-x 10 root root 0 Nov 14 23:19 sunrpc + drwxr-xr-x 538 root root 0 Nov 14 23:19 syscalls + drwxr-xr-x 4 root root 0 Nov 14 23:19 task + drwxr-xr-x 14 root root 0 Nov 14 23:19 timer + drwxr-xr-x 3 root root 0 Nov 14 23:19 udp + drwxr-xr-x 21 root root 0 Nov 14 23:19 vmscan + drwxr-xr-x 3 root root 0 Nov 14 23:19 vsyscall + drwxr-xr-x 6 root root 0 Nov 14 23:19 workqueue + drwxr-xr-x 26 root root 0 Nov 14 23:19 writeback + + Each one of these subdirectories corresponds to a + 'subsystem' and contains yet again more subdirectories, + each one of those finally corresponding to a tracepoint. + For example, here are the contents of the 'kmem' subsystem: + + root@sugarbay:/sys/kernel/debug/tracing/events# cd kmem + root@sugarbay:/sys/kernel/debug/tracing/events/kmem# ls -al + drwxr-xr-x 14 root root 0 Nov 14 23:19 . + drwxr-xr-x 38 root root 0 Nov 14 23:19 .. + -rw-r--r-- 1 root root 0 Nov 14 23:19 enable + -rw-r--r-- 1 root root 0 Nov 14 23:19 filter + drwxr-xr-x 2 root root 0 Nov 14 23:19 kfree + drwxr-xr-x 2 root root 0 Nov 14 23:19 kmalloc + drwxr-xr-x 2 root root 0 Nov 14 23:19 kmalloc_node + drwxr-xr-x 2 root root 0 Nov 14 23:19 kmem_cache_alloc + drwxr-xr-x 2 root root 0 Nov 14 23:19 kmem_cache_alloc_node + drwxr-xr-x 2 root root 0 Nov 14 23:19 kmem_cache_free + drwxr-xr-x 2 root root 0 Nov 14 23:19 mm_page_alloc + drwxr-xr-x 2 root root 0 Nov 14 23:19 mm_page_alloc_extfrag + drwxr-xr-x 2 root root 0 Nov 14 23:19 mm_page_alloc_zone_locked + drwxr-xr-x 2 root root 0 Nov 14 23:19 mm_page_free + drwxr-xr-x 2 root root 0 Nov 14 23:19 mm_page_free_batched + drwxr-xr-x 2 root root 0 Nov 14 23:19 mm_page_pcpu_drain + + Let's see what's inside the subdirectory for a specific + tracepoint, in this case the one for kmalloc: + + root@sugarbay:/sys/kernel/debug/tracing/events/kmem# cd kmalloc + root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# ls -al + drwxr-xr-x 2 root root 0 Nov 14 23:19 . + drwxr-xr-x 14 root root 0 Nov 14 23:19 .. + -rw-r--r-- 1 root root 0 Nov 14 23:19 enable + -rw-r--r-- 1 root root 0 Nov 14 23:19 filter + -r--r--r-- 1 root root 0 Nov 14 23:19 format + -r--r--r-- 1 root root 0 Nov 14 23:19 id + + The 'format' file for the tracepoint describes the event + in memory, which is used by the various tracing tools + that now make use of these tracepoint to parse the event + and make sense of it, along with a 'print fmt' field that + allows tools like ftrace to display the event as text. + Here's what the format of the kmalloc event looks like: + + root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# cat format + name: kmalloc + ID: 313 + format: + field:unsigned short common_type; offset:0; size:2; signed:0; + field:unsigned char common_flags; offset:2; size:1; signed:0; + field:unsigned char common_preempt_count; offset:3; size:1; signed:0; + field:int common_pid; offset:4; size:4; signed:1; + field:int common_padding; offset:8; size:4; signed:1; + + field:unsigned long call_site; offset:16; size:8; signed:0; + field:const void * ptr; offset:24; size:8; signed:0; + field:size_t bytes_req; offset:32; size:8; signed:0; + field:size_t bytes_alloc; offset:40; size:8; signed:0; + field:gfp_t gfp_flags; offset:48; size:4; signed:0; + + print fmt: "call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s", REC->call_site, REC->ptr, REC->bytes_req, REC->bytes_alloc, + (REC->gfp_flags) ? __print_flags(REC->gfp_flags, "|", {(unsigned long)(((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | (( + gfp_t)0x20000u) | (( gfp_t)0x02u) | (( gfp_t)0x08u)) | (( gfp_t)0x4000u) | (( gfp_t)0x10000u) | (( gfp_t)0x1000u) | (( gfp_t)0x200u) | (( + gfp_t)0x400000u)), "GFP_TRANSHUGE"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | (( gfp_t)0x20000u) | (( + gfp_t)0x02u) | (( gfp_t)0x08u)), "GFP_HIGHUSER_MOVABLE"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | (( + gfp_t)0x20000u) | (( gfp_t)0x02u)), "GFP_HIGHUSER"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | (( + gfp_t)0x20000u)), "GFP_USER"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | (( gfp_t)0x80000u)), GFP_TEMPORARY"}, + {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u)), "GFP_KERNEL"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u)), + "GFP_NOFS"}, {(unsigned long)((( gfp_t)0x20u)), "GFP_ATOMIC"}, {(unsigned long)((( gfp_t)0x10u)), "GFP_NOIO"}, {(unsigned long)(( + gfp_t)0x20u), "GFP_HIGH"}, {(unsigned long)(( gfp_t)0x10u), "GFP_WAIT"}, {(unsigned long)(( gfp_t)0x40u), "GFP_IO"}, {(unsigned long)(( + gfp_t)0x100u), "GFP_COLD"}, {(unsigned long)(( gfp_t)0x200u), "GFP_NOWARN"}, {(unsigned long)(( gfp_t)0x400u), "GFP_REPEAT"}, {(unsigned + long)(( gfp_t)0x800u), "GFP_NOFAIL"}, {(unsigned long)(( gfp_t)0x1000u), "GFP_NORETRY"}, {(unsigned long)(( gfp_t)0x4000u), "GFP_COMP"}, + {(unsigned long)(( gfp_t)0x8000u), "GFP_ZERO"}, {(unsigned long)(( gfp_t)0x10000u), "GFP_NOMEMALLOC"}, {(unsigned long)(( gfp_t)0x20000u), + "GFP_HARDWALL"}, {(unsigned long)(( gfp_t)0x40000u), "GFP_THISNODE"}, {(unsigned long)(( gfp_t)0x80000u), "GFP_RECLAIMABLE"}, {(unsigned + long)(( gfp_t)0x08u), "GFP_MOVABLE"}, {(unsigned long)(( gfp_t)0), "GFP_NOTRACK"}, {(unsigned long)(( gfp_t)0x400000u), "GFP_NO_KSWAPD"}, + {(unsigned long)(( gfp_t)0x800000u), "GFP_OTHER_NODE"} ) : "GFP_NOWAIT" + + The 'enable' file in the tracepoint directory is what allows + the user (or tools such as trace-cmd) to actually turn the + tracepoint on and off. When enabled, the corresponding + tracepoint will start appearing in the ftrace 'trace' + file described previously. For example, this turns on the + kmalloc tracepoint: + + root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 1 > enable + + At the moment, we're not interested in the function tracer or + some other tracer that might be in effect, so we first turn + it off, but if we do that, we still need to turn tracing on in + order to see the events in the output buffer: + + root@sugarbay:/sys/kernel/debug/tracing# echo nop > current_tracer + root@sugarbay:/sys/kernel/debug/tracing# echo 1 > tracing_on + + Now, if we look at the the 'trace' file, we see nothing + but the kmalloc events we just turned on: + + root@sugarbay:/sys/kernel/debug/tracing# cat trace | less + # tracer: nop + # + # entries-in-buffer/entries-written: 1897/1897 #P:8 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + dropbear-1465 [000] ...1 18154.620753: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL + <idle>-0 [000] ..s3 18154.621640: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + <idle>-0 [000] ..s3 18154.621656: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + matchbox-termin-1361 [001] ...1 18154.755472: kmalloc: call_site=ffffffff81614050 ptr=ffff88006d5f0e00 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_KERNEL|GFP_REPEAT + Xorg-1264 [002] ...1 18154.755581: kmalloc: call_site=ffffffff8141abe8 ptr=ffff8800734f4cc0 bytes_req=168 bytes_alloc=192 gfp_flags=GFP_KERNEL|GFP_NOWARN|GFP_NORETRY + Xorg-1264 [002] ...1 18154.755583: kmalloc: call_site=ffffffff814192a3 ptr=ffff88001f822520 bytes_req=24 bytes_alloc=32 gfp_flags=GFP_KERNEL|GFP_ZERO + Xorg-1264 [002] ...1 18154.755589: kmalloc: call_site=ffffffff81419edb ptr=ffff8800721a2f00 bytes_req=64 bytes_alloc=64 gfp_flags=GFP_KERNEL|GFP_ZERO + matchbox-termin-1361 [001] ...1 18155.354594: kmalloc: call_site=ffffffff81614050 ptr=ffff88006db35400 bytes_req=576 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_REPEAT + Xorg-1264 [002] ...1 18155.354703: kmalloc: call_site=ffffffff8141abe8 ptr=ffff8800734f4cc0 bytes_req=168 bytes_alloc=192 gfp_flags=GFP_KERNEL|GFP_NOWARN|GFP_NORETRY + Xorg-1264 [002] ...1 18155.354705: kmalloc: call_site=ffffffff814192a3 ptr=ffff88001f822520 bytes_req=24 bytes_alloc=32 gfp_flags=GFP_KERNEL|GFP_ZERO + Xorg-1264 [002] ...1 18155.354711: kmalloc: call_site=ffffffff81419edb ptr=ffff8800721a2f00 bytes_req=64 bytes_alloc=64 gfp_flags=GFP_KERNEL|GFP_ZERO + <idle>-0 [000] ..s3 18155.673319: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + dropbear-1465 [000] ...1 18155.673525: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL + <idle>-0 [000] ..s3 18155.674821: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + <idle>-0 [000] ..s3 18155.793014: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + dropbear-1465 [000] ...1 18155.793219: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL + <idle>-0 [000] ..s3 18155.794147: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + <idle>-0 [000] ..s3 18155.936705: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + dropbear-1465 [000] ...1 18155.936910: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL + <idle>-0 [000] ..s3 18155.937869: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + matchbox-termin-1361 [001] ...1 18155.953667: kmalloc: call_site=ffffffff81614050 ptr=ffff88006d5f2000 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_KERNEL|GFP_REPEAT + Xorg-1264 [002] ...1 18155.953775: kmalloc: call_site=ffffffff8141abe8 ptr=ffff8800734f4cc0 bytes_req=168 bytes_alloc=192 gfp_flags=GFP_KERNEL|GFP_NOWARN|GFP_NORETRY + Xorg-1264 [002] ...1 18155.953777: kmalloc: call_site=ffffffff814192a3 ptr=ffff88001f822520 bytes_req=24 bytes_alloc=32 gfp_flags=GFP_KERNEL|GFP_ZERO + Xorg-1264 [002] ...1 18155.953783: kmalloc: call_site=ffffffff81419edb ptr=ffff8800721a2f00 bytes_req=64 bytes_alloc=64 gfp_flags=GFP_KERNEL|GFP_ZERO + <idle>-0 [000] ..s3 18156.176053: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + dropbear-1465 [000] ...1 18156.176257: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL + <idle>-0 [000] ..s3 18156.177717: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + <idle>-0 [000] ..s3 18156.399229: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + dropbear-1465 [000] ...1 18156.399434: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_http://rostedt.homelinux.com/kernelshark/req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL + <idle>-0 [000] ..s3 18156.400660: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC + matchbox-termin-1361 [001] ...1 18156.552800: kmalloc: call_site=ffffffff81614050 ptr=ffff88006db34800 bytes_req=576 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_REPEAT + + To again disable the kmalloc event, we need to send 0 to the + enable file: + + root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 0 > enable + + You can enable any number of events or complete subsystems + (by using the 'enable' file in the subsystem directory) and + get an arbitrarily fine-grained idea of what's going on in the + system by enabling as many of the appropriate tracepoints + as applicable. + + + + A number of the tools described in this HOWTO do just that, + including trace-cmd and kernelshark in the next section. + + + + Tying it Together: These tracepoints and their representation + are used not only by ftrace, but by many of the other tools + covered in this document and they form a central point of + integration for the various tracers available in Linux. + They form a central part of the instrumentation for the + following tools: perf, lttng, ftrace, blktrace and SystemTap + + + + Tying it Together: Eventually all the special-purpose tracers + currently available in /sys/kernel/debug/tracing will be + removed and replaced with equivalent tracers based on the + 'trace events' subsystem. + +
+ +
+ trace-cmd/kernelshark + + + trace-cmd is essentially an extensive command-line 'wrapper' + interface that hides the details of all the individual files + in /sys/kernel/debug/tracing, allowing users to specify + specific particular events within the + /sys/kernel/debug/tracing/events/ subdirectory and to collect + traces and avoid having to deal with those details directly. + + + + As yet another layer on top of that, kernelshark provides a GUI + that allows users to start and stop traces and specify sets + of events using an intuitive interface, and view the + output as both trace events and as a per-CPU graphical + display. It directly uses 'trace-cmd' as the plumbing + that accomplishes all that underneath the covers (and + actually displays the trace-cmd command it uses, as we'll see). + + + + To start a trace using kernelshark, first start kernelshark: + + root@sugarbay:~# kernelshark + + Then bring up the 'Capture' dialog by choosing from the + kernelshark menu: + + Capture | Record + + That will display the following dialog, which allows you to + choose one or more events (or even one or more complete + subsystems) to trace: + + + + + + + + Note that these are exactly the same sets of events described + in the previous trace events subsystem section, and in fact + is where trace-cmd gets them for kernelshark. + + + + In the above screenshot, we've decided to explore the + graphics subsystem a bit and so have chosen to trace all + the tracepoints contained within the 'i915' and 'drm' + subsystems. + + + + After doing that, we can start and stop the trace using + the 'Run' and 'Stop' button on the lower right corner of + the dialog (the same button will turn into the 'Stop' + button after the trace has started): + + + + + + + + Notice that the right-hand pane shows the exact trace-cmd + command-line that's used to run the trace, along with the + results of the trace-cmd run. + + + + Once the 'Stop' button is pressed, the graphical view magically + fills up with a colorful per-cpu display of the trace data, + along with the detailed event listing below that: + + + + + + + + Here's another example, this time a display resulting + from tracing 'all events': + + + + + + + + The tool is pretty self-explanatory, but for more detailed + information on navigating through the data, see the + kernelshark website. + +
+ +
+ Documentation + + + The documentation for ftrace can be found in the kernel + Documentation directory: + + Documentation/trace/ftrace.txt + + The documentation for the trace event subsystem can also + be found in the kernel Documentation directory: + + Documentation/trace/events.txt + + There is a nice series of articles on using + ftrace and trace-cmd at LWN: + + Debugging the kernel using Ftrace - part 1 + + Debugging the kernel using Ftrace - part 2 + + Secrets of the Ftrace function tracer + + trace-cmd: A front-end for Ftrace + + + + + + There's more detailed documentation kernelshark usage here: + KernelShark + + + + An amusing yet useful README (a tracing mini-HOWTO) can be + found in /sys/kernel/debug/tracing/README. + +
+
+ +
+ systemtap + + + SystemTap is a system-wide script-based tracing and profiling tool. + + + + SystemTap scripts are C-like programs that are executed in the + kernel to gather/print/aggregate data extracted from the context + they end up being invoked under. + + + + For example, this probe from the + SystemTap tutorial + simply prints a line every time any process on the system open()s + a file. For each line, it prints the executable name of the + program that opened the file, along with its PID, and the name + of the file it opened (or tried to open), which it extracts + from the open syscall's argstr. + + probe syscall.open + { + printf ("%s(%d) open (%s)\n", execname(), pid(), argstr) + } + + probe timer.ms(4000) # after 4 seconds + { + exit () + } + + Normally, to execute this probe, you'd simply install + systemtap on the system you want to probe, and directly run + the probe on that system e.g. assuming the name of the file + containing the above text is trace_open.stp: + + # stap trace_open.stp + + What systemtap does under the covers to run this probe is 1) + parse and convert the probe to an equivalent 'C' form, 2) + compile the 'C' form into a kernel module, 3) insert the + module into the kernel, which arms it, and 4) collect the data + generated by the probe and display it to the user. + + + + In order to accomplish steps 1 and 2, the 'stap' program needs + access to the kernel build system that produced the kernel + that the probed system is running. In the case of a typical + embedded system (the 'target'), the kernel build system + unfortunately isn't typically part of the image running on + the target. It is normally available on the 'host' system + that produced the target image however; in such cases, + steps 1 and 2 are executed on the host system, and steps + 3 and 4 are executed on the target system, using only the + systemtap 'runtime'. + + + + The systemtap support in Yocto assumes that only steps + 3 and 4 are run on the target; it is possible to do + everything on the target, but this section assumes only + the typical embedded use-case. + + + + So basically what you need to do in order to run a systemtap + script on the target is to 1) on the host system, compile the + probe into a kernel module that makes sense to the target, 2) + copy the module onto the target system and 3) insert the + module into the target kernel, which arms it, and 4) collect + the data generated by the probe and display it to the user. + + +
+ Setup + + + Those are a lot of steps and a lot of details, but + fortunately Yocto includes a script called 'crosstap' + that will take care of those details, allowing you to + simply execute a systemtap script on the remote target, + with arguments if necessary. + + + + In order to do this from a remote host, however, you + need to have access to the build for the image you + booted. The 'crosstap' script provides details on how + to do this if you run the script on the host without having + done a build: + + SystemTap, which uses 'crosstap', assumes you can establish an + ssh connection to the remote target. + Please refer to the crosstap wiki page for details on verifying + ssh connections at + . + Also, the ability to ssh into the target system is not enabled + by default in *-minimal images. + + + $ crosstap root@192.168.1.88 trace_open.stp + + Error: No target kernel build found. + Did you forget to create a local build of your image? + + 'crosstap' requires a local sdk build of the target system + (or a build that includes 'tools-profile') in order to build + kernel modules that can probe the target system. + + Practically speaking, that means you need to do the following: + - If you're running a pre-built image, download the release + and/or BSP tarballs used to build the image. + - If you're working from git sources, just clone the metadata + and BSP layers needed to build the image you'll be booting. + - Make sure you're properly set up to build a new image (see + the BSP README and/or the widely available basic documentation + that discusses how to build images). + - Build an -sdk version of the image e.g.: + $ bitbake core-image-sato-sdk + OR + - Build a non-sdk image but include the profiling tools: + [ edit local.conf and add 'tools-profile' to the end of + the EXTRA_IMAGE_FEATURES variable ] + $ bitbake core-image-sato + + Once you've build the image on the host system, you're ready to + boot it (or the equivalent pre-built image) and use 'crosstap' + to probe it (you need to source the environment as usual first): + + $ source oe-init-build-env + $ cd ~/my/systemtap/scripts + $ crosstap root@192.168.1.xxx myscript.stp + + So essentially what you need to do is build an SDK image or + image with 'tools-profile' as detailed in the + "General Setup" + section of this manual, and boot the resulting target image. + + + + If you have a build directory containing multiple machines, + you need to have the MACHINE you're connecting to selected + in local.conf, and the kernel in that machine's build + directory must match the kernel on the booted system exactly, + or you'll get the above 'crosstap' message when you try to + invoke a script. + +
+ +
+ Running a Script on a Target + + + Once you've done that, you should be able to run a systemtap + script on the target: + + $ cd /path/to/yocto + $ source oe-init-build-env + + ### Shell environment set up for builds. ### + + You can now run 'bitbake target' + + Common targets are: + 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' + + Once you've done that, you can cd to whatever directory + contains your scripts and use 'crosstap' to run the script: + + $ cd /path/to/my/systemap/script + $ crosstap root@192.168.7.2 trace_open.stp + + If you get an error connecting to the target e.g.: + + $ crosstap root@192.168.7.2 trace_open.stp + error establishing ssh connection on remote 'root@192.168.7.2' + + Try ssh'ing to the target and see what happens: + + $ ssh root@192.168.7.2 + + A lot of the time, connection problems are due specifying a + wrong IP address or having a 'host key verification error'. + + + + If everything worked as planned, you should see something + like this (enter the password when prompted, or press enter + if it's set up to use no password): + + $ crosstap root@192.168.7.2 trace_open.stp + root@192.168.7.2's password: + matchbox-termin(1036) open ("/tmp/vte3FS2LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600) + matchbox-termin(1036) open ("/tmp/vteJMC7LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600) + + +
+ +
+ Documentation + + + The SystemTap language reference can be found here: + SystemTap Language Reference + + + + Links to other SystemTap documents, tutorials, and examples can be + found here: + SystemTap documentation page + +
+
+ +
+ oprofile + + + oprofile itself is a command-line application that runs on the + target system. + + +
+ Setup + + + For this section, we'll assume you've already performed the + basic setup outlined in the + "General Setup" + section. + + + + 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. + + + + 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. + +
+ +
+ Basic Usage + + + 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. + + + + It consists of a kernel module that collects samples and a + userspace daemon that writes the sample data to disk. + + + + 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. + + + + 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: + + 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. + + You can check if vmlinux file: is set using opcontrol --status: + + root@crownbay:~# opcontrol --status + Daemon paused: pid 1334 + Separate options: library + vmlinux file: none + Image filter: none + Call-graph depth: 6 + + If it's not, you need to shutdown the daemon, add the setting + and restart the daemon: + + 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. + + If we check the status again we now see our updated settings: + + 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 + + We're now in a position to run a profile. For that we use + 'opcontrol --start': + + root@crownbay:~# opcontrol --start + Profiler running. + + In another window, run our wget workload: + + root@crownbay:~# rm linux-2.6.19.2.tar.bz2; wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2; sync + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |*******************************| 41727k 0:00:00 ETA + + To stop the profile we use 'opcontrol --shutdown', which not + only stops the profile but shuts down the daemon as well: + + root@crownbay:~# opcontrol --shutdown + Stopping profiling. + Killing daemon. + + 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. + + + + 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: + + 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 + + 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. + + + + 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: + + 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 + . + . + . + + 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: + + 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 + + Notice that above we see an entry for the __copy_to_user_ll() + function that we've looked at with other profilers as well. + + + + Here's what we get when we do the same thing for the + busybox executable: + + 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 + . + . + . + + 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: + + 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 + + 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: + + root@crownbay:~# opcontrol --reset + + +
+ +
+ OProfileUI - A GUI for OProfile + + + 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: + + [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 + + 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: + + + + First, on the target, check if vmlinux file: is set: + + root@crownbay:~# opcontrol --status + + If not: + + root@crownbay:~# opcontrol --shutdown + root@crownbay:~# opcontrol --vmlinux=/boot/vmlinux-`uname -r` + root@crownbay:~# opcontrol --start-daemon + + Now, start the oprofile UI on the host system: + + [trz@empanada oprofileui]$ oprofile-viewer + + 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). + + + + 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: + + root@crownbay:~# oprofile-server + + Or, to specify a specific port: + + root@crownbay:~# oprofile-server --port 8888 + + Once connected, press the 'Start' button and then run the + wget workload on the remote system: + + root@crownbay:~# rm linux-2.6.19.2.tar.bz2; wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2; sync + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |*******************************| 41727k 0:00:00 ETA + + 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: + + + + + + + + Once the profile files have been retrieved, you should see a + list of the processes that were profiled: + + + + + + + + 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(): + + + + + + + + As another example, we can look at the busybox process and see + that the progress meter made a system call: + + + + + +
+ +
+ Documentation + + + 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 + "Profiling with OProfile" + section in the Yocto Project Development Manual + + + + The OProfile manual can be found here: + OProfile manual + + + + The OProfile website contains links to the above manual and + bunch of other items including an extensive set of examples: + About OProfile + +
+
+ +
+ Sysprof + + + Sysprof is a very easy to use system-wide profiler that consists + of a single window with three panes and a few buttons which allow + you to start, stop, and view the profile from one place. + + +
+ Setup + + + For this section, we'll assume you've already performed the + basic setup outlined in the General Setup section. + + + + Sysprof is a GUI-based application that runs on the target + system. For the rest of this document we assume you've + ssh'ed to the host and will be running Sysprof on the + target (you can use the '-X' option to ssh and have the + Sysprof GUI run on the target but display remotely on the + host if you want). + +
+ +
+ Basic Usage + + + To start profiling the system, you simply press the 'Start' + button. To stop profiling and to start viewing the profile data + in one easy step, press the 'Profile' button. + + + + Once you've pressed the profile button, the three panes will + fill up with profiling data: + + + + + + + + The left pane shows a list of functions and processes. + Selecting one of those expands that function in the right + pane, showing all its callees. Note that this caller-oriented + display is essentially the inverse of perf's default + callee-oriented callchain display. + + + + In the screenshot above, we're focusing on __copy_to_user_ll() + and looking up the callchain we can see that one of the callers + of __copy_to_user_ll is sys_read() and the complete callpath + between them. Notice that this is essentially a portion of the + same information we saw in the perf display shown in the perf + section of this page. + + + + + + + + Similarly, the above is a snapshot of the Sysprof display of a + copy-from-user callchain. + + + + Finally, looking at the third Sysprof pane in the lower left, + we can see a list of all the callers of a particular function + selected in the top left pane. In this case, the lower pane is + showing all the callers of __mark_inode_dirty: + + + + + + + + Double-clicking on one of those functions will in turn change the + focus to the selected function, and so on. + + + + Tying it Together: If you like sysprof's 'caller-oriented' + display, you may be able to approximate it in other tools as + well. For example, 'perf report' has the -g (--call-graph) + option that you can experiment with; one of the options is + 'caller' for an inverted caller-based callgraph display. + +
+ +
+ Documentation + + + There doesn't seem to be any documentation for Sysprof, but + maybe that's because it's pretty self-explanatory. + The Sysprof website, however, is here: + Sysprof, System-wide Performance Profiler for Linux + +
+
+ +
+ LTTng (Linux Trace Toolkit, next generation) + +
+ Setup + + + For this section, we'll assume you've already performed the + basic setup outlined in the General Setup section. + + + + LTTng is run on the target system by ssh'ing to it. + However, if you want to see the traces graphically, + install Eclipse as described in section + "Manually copying a trace to the host and viewing it in Eclipse (i.e. using Eclipse without network support)" + and follow the directions to manually copy traces to the host and + view them in Eclipse (i.e. using Eclipse without network support). + + + + Be sure to download and install/run the 'SR1' or later Juno release + of eclipse e.g.: + http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR1/eclipse-cpp-juno-SR1-linux-gtk-x86_64.tar.gz + +
+ +
+ Collecting and Viewing Traces + + + Once you've applied the above commits and built and booted your + image (you need to build the core-image-sato-sdk image or use one of the + other methods described in the General Setup section), you're + ready to start tracing. + + +
+ Collecting and viewing a trace on the target (inside a shell) + + + First, from the host, ssh to the target: + + $ ssh -l root 192.168.1.47 + The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established. + RSA key fingerprint is 23:bd:c8:b1:a8:71:52:00:ee:00:4f:64:9e:10:b9:7e. + Are you sure you want to continue connecting (yes/no)? yes + Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts. + root@192.168.1.47's password: + + Once on the target, use these steps to create a trace: + + root@crownbay:~# lttng create + Spawning a session daemon + Session auto-20121015-232120 created. + Traces will be written in /home/root/lttng-traces/auto-20121015-232120 + + Enable the events you want to trace (in this case all + kernel events): + + root@crownbay:~# lttng enable-event --kernel --all + All kernel events are enabled in channel channel0 + + Start the trace: + + root@crownbay:~# lttng start + Tracing started for session auto-20121015-232120 + + And then stop the trace after awhile or after running + a particular workload that you want to trace: + + root@crownbay:~# lttng stop + Tracing stopped for session auto-20121015-232120 + + You can now view the trace in text form on the target: + + root@crownbay:~# lttng view + [23:21:56.989270399] (+?.?????????) sys_geteuid: { 1 }, { } + [23:21:56.989278081] (+0.000007682) exit_syscall: { 1 }, { ret = 0 } + [23:21:56.989286043] (+0.000007962) sys_pipe: { 1 }, { fildes = 0xB77B9E8C } + [23:21:56.989321802] (+0.000035759) exit_syscall: { 1 }, { ret = 0 } + [23:21:56.989329345] (+0.000007543) sys_mmap_pgoff: { 1 }, { addr = 0x0, len = 10485760, prot = 3, flags = 131362, fd = 4294967295, pgoff = 0 } + [23:21:56.989351694] (+0.000022349) exit_syscall: { 1 }, { ret = -1247805440 } + [23:21:56.989432989] (+0.000081295) sys_clone: { 1 }, { clone_flags = 0x411, newsp = 0xB5EFFFE4, parent_tid = 0xFFFFFFFF, child_tid = 0x0 } + [23:21:56.989477129] (+0.000044140) sched_stat_runtime: { 1 }, { comm = "lttng-consumerd", tid = 1193, runtime = 681660, vruntime = 43367983388 } + [23:21:56.989486697] (+0.000009568) sched_migrate_task: { 1 }, { comm = "lttng-consumerd", tid = 1193, prio = 20, orig_cpu = 1, dest_cpu = 1 } + [23:21:56.989508418] (+0.000021721) hrtimer_init: { 1 }, { hrtimer = 3970832076, clockid = 1, mode = 1 } + [23:21:56.989770462] (+0.000262044) hrtimer_cancel: { 1 }, { hrtimer = 3993865440 } + [23:21:56.989771580] (+0.000001118) hrtimer_cancel: { 0 }, { hrtimer = 3993812192 } + [23:21:56.989776957] (+0.000005377) hrtimer_expire_entry: { 1 }, { hrtimer = 3993865440, now = 79815980007057, function = 3238465232 } + [23:21:56.989778145] (+0.000001188) hrtimer_expire_entry: { 0 }, { hrtimer = 3993812192, now = 79815980008174, function = 3238465232 } + [23:21:56.989791695] (+0.000013550) softirq_raise: { 1 }, { vec = 1 } + [23:21:56.989795396] (+0.000003701) softirq_raise: { 0 }, { vec = 1 } + [23:21:56.989800635] (+0.000005239) softirq_raise: { 0 }, { vec = 9 } + [23:21:56.989807130] (+0.000006495) sched_stat_runtime: { 1 }, { comm = "lttng-consumerd", tid = 1193, runtime = 330710, vruntime = 43368314098 } + [23:21:56.989809993] (+0.000002863) sched_stat_runtime: { 0 }, { comm = "lttng-sessiond", tid = 1181, runtime = 1015313, vruntime = 36976733240 } + [23:21:56.989818514] (+0.000008521) hrtimer_expire_exit: { 0 }, { hrtimer = 3993812192 } + [23:21:56.989819631] (+0.000001117) hrtimer_expire_exit: { 1 }, { hrtimer = 3993865440 } + [23:21:56.989821866] (+0.000002235) hrtimer_start: { 0 }, { hrtimer = 3993812192, function = 3238465232, expires = 79815981000000, softexpires = 79815981000000 } + [23:21:56.989822984] (+0.000001118) hrtimer_start: { 1 }, { hrtimer = 3993865440, function = 3238465232, expires = 79815981000000, softexpires = 79815981000000 } + [23:21:56.989832762] (+0.000009778) softirq_entry: { 1 }, { vec = 1 } + [23:21:56.989833879] (+0.000001117) softirq_entry: { 0 }, { vec = 1 } + [23:21:56.989838069] (+0.000004190) timer_cancel: { 1 }, { timer = 3993871956 } + [23:21:56.989839187] (+0.000001118) timer_cancel: { 0 }, { timer = 3993818708 } + [23:21:56.989841492] (+0.000002305) timer_expire_entry: { 1 }, { timer = 3993871956, now = 79515980, function = 3238277552 } + [23:21:56.989842819] (+0.000001327) timer_expire_entry: { 0 }, { timer = 3993818708, now = 79515980, function = 3238277552 } + [23:21:56.989854831] (+0.000012012) sched_stat_runtime: { 1 }, { comm = "lttng-consumerd", tid = 1193, runtime = 49237, vruntime = 43368363335 } + [23:21:56.989855949] (+0.000001118) sched_stat_runtime: { 0 }, { comm = "lttng-sessiond", tid = 1181, runtime = 45121, vruntime = 36976778361 } + [23:21:56.989861257] (+0.000005308) sched_stat_sleep: { 1 }, { comm = "kworker/1:1", tid = 21, delay = 9451318 } + [23:21:56.989862374] (+0.000001117) sched_stat_sleep: { 0 }, { comm = "kworker/0:0", tid = 4, delay = 9958820 } + [23:21:56.989868241] (+0.000005867) sched_wakeup: { 0 }, { comm = "kworker/0:0", tid = 4, prio = 120, success = 1, target_cpu = 0 } + [23:21:56.989869358] (+0.000001117) sched_wakeup: { 1 }, { comm = "kworker/1:1", tid = 21, prio = 120, success = 1, target_cpu = 1 } + [23:21:56.989877460] (+0.000008102) timer_expire_exit: { 1 }, { timer = 3993871956 } + [23:21:56.989878577] (+0.000001117) timer_expire_exit: { 0 }, { timer = 3993818708 } + . + . + . + + You can now safely destroy the trace session (note that + this doesn't delete the trace - it's still there + in ~/lttng-traces): + + root@crownbay:~# lttng destroy + Session auto-20121015-232120 destroyed at /home/root + + Note that the trace is saved in a directory of the same + name as returned by 'lttng create', under the ~/lttng-traces + directory (note that you can change this by supplying your + own name to 'lttng create'): + + root@crownbay:~# ls -al ~/lttng-traces + drwxrwx--- 3 root root 1024 Oct 15 23:21 . + drwxr-xr-x 5 root root 1024 Oct 15 23:57 .. + drwxrwx--- 3 root root 1024 Oct 15 23:21 auto-20121015-232120 + + +
+ +
+ Collecting and viewing a userspace trace on the target (inside a shell) + + + For LTTng userspace tracing, you need to have a properly + instrumented userspace program. For this example, we'll use + the 'hello' test program generated by the lttng-ust build. + + + + The 'hello' test program isn't installed on the rootfs by + the lttng-ust build, so we need to copy it over manually. + First cd into the build directory that contains the hello + executable: + + $ cd build/tmp/work/core2_32-poky-linux/lttng-ust/2.0.5-r0/git/tests/hello/.libs + + Copy that over to the target machine: + + $ scp hello root@192.168.1.20: + + You now have the instrumented lttng 'hello world' test + program on the target, ready to test. + + + + First, from the host, ssh to the target: + + $ ssh -l root 192.168.1.47 + The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established. + RSA key fingerprint is 23:bd:c8:b1:a8:71:52:00:ee:00:4f:64:9e:10:b9:7e. + Are you sure you want to continue connecting (yes/no)? yes + Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts. + root@192.168.1.47's password: + + Once on the target, use these steps to create a trace: + + root@crownbay:~# lttng create + Session auto-20190303-021943 created. + Traces will be written in /home/root/lttng-traces/auto-20190303-021943 + + Enable the events you want to trace (in this case all + userspace events): + + root@crownbay:~# lttng enable-event --userspace --all + All UST events are enabled in channel channel0 + + Start the trace: + + root@crownbay:~# lttng start + Tracing started for session auto-20190303-021943 + + Run the instrumented hello world program: + + root@crownbay:~# ./hello + Hello, World! + Tracing... done. + + And then stop the trace after awhile or after running a + particular workload that you want to trace: + + root@crownbay:~# lttng stop + Tracing stopped for session auto-20190303-021943 + + You can now view the trace in text form on the target: + + root@crownbay:~# lttng view + [02:31:14.906146544] (+?.?????????) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 0, intfield2 = 0x0, longfield = 0, netintfield = 0, netintfieldhex = 0x0, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 } + [02:31:14.906170360] (+0.000023816) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 1, intfield2 = 0x1, longfield = 1, netintfield = 1, netintfieldhex = 0x1, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 } + [02:31:14.906183140] (+0.000012780) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 2, intfield2 = 0x2, longfield = 2, netintfield = 2, netintfieldhex = 0x2, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 } + [02:31:14.906194385] (+0.000011245) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 3, intfield2 = 0x3, longfield = 3, netintfield = 3, netintfieldhex = 0x3, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 } + . + . + . + + You can now safely destroy the trace session (note that + this doesn't delete the trace - it's still + there in ~/lttng-traces): + + root@crownbay:~# lttng destroy + Session auto-20190303-021943 destroyed at /home/root + + +
+ +
+ Manually copying a trace to the host and viewing it in Eclipse (i.e. using Eclipse without network support) + + + If you already have an LTTng trace on a remote target and + would like to view it in Eclipse on the host, you can easily + copy it from the target to the host and import it into + Eclipse to view it using the LTTng Eclipse plug-in already + bundled in the Eclipse (Juno SR1 or greater). + + + + Using the trace we created in the previous section, archive + it and copy it to your host system: + + root@crownbay:~/lttng-traces# tar zcvf auto-20121015-232120.tar.gz auto-20121015-232120 + auto-20121015-232120/ + auto-20121015-232120/kernel/ + auto-20121015-232120/kernel/metadata + auto-20121015-232120/kernel/channel0_1 + auto-20121015-232120/kernel/channel0_0 + + $ scp root@192.168.1.47:lttng-traces/auto-20121015-232120.tar.gz . + root@192.168.1.47's password: + auto-20121015-232120.tar.gz 100% 1566KB 1.5MB/s 00:01 + + Unarchive it on the host: + + $ gunzip -c auto-20121015-232120.tar.gz | tar xvf - + auto-20121015-232120/ + auto-20121015-232120/kernel/ + auto-20121015-232120/kernel/metadata + auto-20121015-232120/kernel/channel0_1 + auto-20121015-232120/kernel/channel0_0 + + We can now import the trace into Eclipse and view it: + + First, start eclipse and open the + 'LTTng Kernel' perspective by selecting the following + menu item: + + Window | Open Perspective | Other... + + In the dialog box that opens, select + 'LTTng Kernel' from the list. + Back at the main menu, select the + following menu item: + + File | New | Project... + + In the dialog box that opens, select + the 'Tracing | Tracing Project' wizard and press + 'Next>'. + Give the project a name and press + 'Finish'. + In the 'Project Explorer' pane under + the project you created, right click on the + 'Traces' item. + Select 'Import..." and in the dialog + that's displayed: + Browse the filesystem and find the + select the 'kernel' directory containing the trace + you copied from the target + e.g. auto-20121015-232120/kernel + 'Checkmark' the directory in the tree + that's displayed for the trace + Below that, select 'Common Trace Format: + Kernel Trace' for the 'Trace Type' + Press 'Finish' to close the dialog + + Back in the 'Project Explorer' pane, + double-click on the 'kernel' item for the + trace you just imported under 'Traces' + + + You should now see your trace data displayed graphically + in several different views in Eclipse: + + + + + + + + You can access extensive help information on how to use + the LTTng plug-in to search and analyze captured traces via + the Eclipse help system: + + Help | Help Contents | LTTng Plug-in User Guide + + +
+ +
+ Collecting and viewing a trace in Eclipse + + + This section on collecting traces remotely doesn't currently + work because of Eclipse 'RSE' connectivity problems. Manually + tracing on the target, copying the trace files to the host, + and viewing the trace in Eclipse on the host as outlined in + previous steps does work however - please use the manual + steps outlined above to view traces in Eclipse. + + + + In order to trace a remote target, you also need to add + a 'tracing' group on the target and connect as a user + who's part of that group e.g: + + # adduser tomz + # groupadd -r tracing + # usermod -a -G tracing tomz + + + First, start eclipse and open the + 'LTTng Kernel' perspective by selecting the following + menu item: + + Window | Open Perspective | Other... + + In the dialog box that opens, select + 'LTTng Kernel' from the list. + Back at the main menu, select the + following menu item: + + File | New | Project... + + In the dialog box that opens, select + the 'Tracing | Tracing Project' wizard and + press 'Next>'. + Give the project a name and press + 'Finish'. That should result in an entry in the + 'Project' subwindow. + In the 'Control' subwindow just below + it, press 'New Connection'. + Add a new connection, giving it the + hostname or IP address of the target system. + + Provide the username and password + of a qualified user (a member of the 'tracing' group) + or root account on the target system. + + Provide appropriate answers to whatever + else is asked for e.g. 'secure storage password' + can be anything you want. + If you get an 'RSE Error' it may be due to proxies. + It may be possible to get around the problem by + changing the following setting: + + Window | Preferences | Network Connections + + Switch 'Active Provider' to 'Direct' + + + +
+
+ +
+ Documentation + + + You can find the primary LTTng Documentation on the + LTTng Documentation + site. + The documentation on this site is appropriate for intermediate to + advanced software developers who are working in a Linux environment + and are interested in efficient software tracing. + + + + For information on LTTng in general, visit the + LTTng Project + site. + You can find a "Getting Started" link on this site that takes + you to an LTTng Quick Start. + + + + Finally, you can access extensive help information on how to use + the LTTng plug-in to search and analyze captured traces via the + Eclipse help system: + + Help | Help Contents | LTTng Plug-in User Guide + + +
+
+ +
+ blktrace + + + blktrace is a tool for tracing and reporting low-level disk I/O. + blktrace provides the tracing half of the equation; its output can + be piped into the blkparse program, which renders the data in a + human-readable form and does some basic analysis: + + +
+ Setup + + + For this section, we'll assume you've already performed the + basic setup outlined in the + "General Setup" + section. + + + + blktrace is an application that runs on the target system. + You can run the entire blktrace and blkparse pipeline on the + target, or you can run blktrace in 'listen' mode on the target + and have blktrace and blkparse collect and analyze the data on + the host (see the + "Using blktrace Remotely" + section below). + For the rest of this section we assume you've ssh'ed to the + host and will be running blkrace on the target. + +
+ +
+ Basic Usage + + + To record a trace, simply run the 'blktrace' command, giving it + the name of the block device you want to trace activity on: + + root@crownbay:~# blktrace /dev/sdc + + In another shell, execute a workload you want to trace. + + root@crownbay:/media/sdc# rm linux-2.6.19.2.tar.bz2; wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2; sync + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |*******************************| 41727k 0:00:00 ETA + + Press Ctrl-C in the blktrace shell to stop the trace. It will + display how many events were logged, along with the per-cpu file + sizes (blktrace records traces in per-cpu kernel buffers and + simply dumps them to userspace for blkparse to merge and sort + later). + + ^C=== sdc === + CPU 0: 7082 events, 332 KiB data + CPU 1: 1578 events, 74 KiB data + Total: 8660 events (dropped 0), 406 KiB data + + If you examine the files saved to disk, you see multiple files, + one per CPU and with the device name as the first part of the + filename: + + root@crownbay:~# ls -al + drwxr-xr-x 6 root root 1024 Oct 27 22:39 . + drwxr-sr-x 4 root root 1024 Oct 26 18:24 .. + -rw-r--r-- 1 root root 339938 Oct 27 22:40 sdc.blktrace.0 + -rw-r--r-- 1 root root 75753 Oct 27 22:40 sdc.blktrace.1 + + To view the trace events, simply invoke 'blkparse' in the + directory containing the trace files, giving it the device name + that forms the first part of the filenames: + + root@crownbay:~# blkparse sdc + + 8,32 1 1 0.000000000 1225 Q WS 3417048 + 8 [jbd2/sdc-8] + 8,32 1 2 0.000025213 1225 G WS 3417048 + 8 [jbd2/sdc-8] + 8,32 1 3 0.000033384 1225 P N [jbd2/sdc-8] + 8,32 1 4 0.000043301 1225 I WS 3417048 + 8 [jbd2/sdc-8] + 8,32 1 0 0.000057270 0 m N cfq1225 insert_request + 8,32 1 0 0.000064813 0 m N cfq1225 add_to_rr + 8,32 1 5 0.000076336 1225 U N [jbd2/sdc-8] 1 + 8,32 1 0 0.000088559 0 m N cfq workload slice:150 + 8,32 1 0 0.000097359 0 m N cfq1225 set_active wl_prio:0 wl_type:1 + 8,32 1 0 0.000104063 0 m N cfq1225 Not idling. st->count:1 + 8,32 1 0 0.000112584 0 m N cfq1225 fifo= (null) + 8,32 1 0 0.000118730 0 m N cfq1225 dispatch_insert + 8,32 1 0 0.000127390 0 m N cfq1225 dispatched a request + 8,32 1 0 0.000133536 0 m N cfq1225 activate rq, drv=1 + 8,32 1 6 0.000136889 1225 D WS 3417048 + 8 [jbd2/sdc-8] + 8,32 1 7 0.000360381 1225 Q WS 3417056 + 8 [jbd2/sdc-8] + 8,32 1 8 0.000377422 1225 G WS 3417056 + 8 [jbd2/sdc-8] + 8,32 1 9 0.000388876 1225 P N [jbd2/sdc-8] + 8,32 1 10 0.000397886 1225 Q WS 3417064 + 8 [jbd2/sdc-8] + 8,32 1 11 0.000404800 1225 M WS 3417064 + 8 [jbd2/sdc-8] + 8,32 1 12 0.000412343 1225 Q WS 3417072 + 8 [jbd2/sdc-8] + 8,32 1 13 0.000416533 1225 M WS 3417072 + 8 [jbd2/sdc-8] + 8,32 1 14 0.000422121 1225 Q WS 3417080 + 8 [jbd2/sdc-8] + 8,32 1 15 0.000425194 1225 M WS 3417080 + 8 [jbd2/sdc-8] + 8,32 1 16 0.000431968 1225 Q WS 3417088 + 8 [jbd2/sdc-8] + 8,32 1 17 0.000435251 1225 M WS 3417088 + 8 [jbd2/sdc-8] + 8,32 1 18 0.000440279 1225 Q WS 3417096 + 8 [jbd2/sdc-8] + 8,32 1 19 0.000443911 1225 M WS 3417096 + 8 [jbd2/sdc-8] + 8,32 1 20 0.000450336 1225 Q WS 3417104 + 8 [jbd2/sdc-8] + 8,32 1 21 0.000454038 1225 M WS 3417104 + 8 [jbd2/sdc-8] + 8,32 1 22 0.000462070 1225 Q WS 3417112 + 8 [jbd2/sdc-8] + 8,32 1 23 0.000465422 1225 M WS 3417112 + 8 [jbd2/sdc-8] + 8,32 1 24 0.000474222 1225 I WS 3417056 + 64 [jbd2/sdc-8] + 8,32 1 0 0.000483022 0 m N cfq1225 insert_request + 8,32 1 25 0.000489727 1225 U N [jbd2/sdc-8] 1 + 8,32 1 0 0.000498457 0 m N cfq1225 Not idling. st->count:1 + 8,32 1 0 0.000503765 0 m N cfq1225 dispatch_insert + 8,32 1 0 0.000512914 0 m N cfq1225 dispatched a request + 8,32 1 0 0.000518851 0 m N cfq1225 activate rq, drv=2 + . + . + . + 8,32 0 0 58.515006138 0 m N cfq3551 complete rqnoidle 1 + 8,32 0 2024 58.516603269 3 C WS 3156992 + 16 [0] + 8,32 0 0 58.516626736 0 m N cfq3551 complete rqnoidle 1 + 8,32 0 0 58.516634558 0 m N cfq3551 arm_idle: 8 group_idle: 0 + 8,32 0 0 58.516636933 0 m N cfq schedule dispatch + 8,32 1 0 58.516971613 0 m N cfq3551 slice expired t=0 + 8,32 1 0 58.516982089 0 m N cfq3551 sl_used=13 disp=6 charge=13 iops=0 sect=80 + 8,32 1 0 58.516985511 0 m N cfq3551 del_from_rr + 8,32 1 0 58.516990819 0 m N cfq3551 put_queue + + CPU0 (sdc): + Reads Queued: 0, 0KiB Writes Queued: 331, 26,284KiB + Read Dispatches: 0, 0KiB Write Dispatches: 485, 40,484KiB + Reads Requeued: 0 Writes Requeued: 0 + Reads Completed: 0, 0KiB Writes Completed: 511, 41,000KiB + Read Merges: 0, 0KiB Write Merges: 13, 160KiB + Read depth: 0 Write depth: 2 + IO unplugs: 23 Timer unplugs: 0 + CPU1 (sdc): + Reads Queued: 0, 0KiB Writes Queued: 249, 15,800KiB + Read Dispatches: 0, 0KiB Write Dispatches: 42, 1,600KiB + Reads Requeued: 0 Writes Requeued: 0 + Reads Completed: 0, 0KiB Writes Completed: 16, 1,084KiB + Read Merges: 0, 0KiB Write Merges: 40, 276KiB + Read depth: 0 Write depth: 2 + IO unplugs: 30 Timer unplugs: 1 + + Total (sdc): + Reads Queued: 0, 0KiB Writes Queued: 580, 42,084KiB + Read Dispatches: 0, 0KiB Write Dispatches: 527, 42,084KiB + Reads Requeued: 0 Writes Requeued: 0 + Reads Completed: 0, 0KiB Writes Completed: 527, 42,084KiB + Read Merges: 0, 0KiB Write Merges: 53, 436KiB + IO unplugs: 53 Timer unplugs: 1 + + Throughput (R/W): 0KiB/s / 719KiB/s + Events (sdc): 6,592 entries + Skips: 0 forward (0 - 0.0%) + Input file sdc.blktrace.0 added + Input file sdc.blktrace.1 added + + The report shows each event that was found in the blktrace data, + along with a summary of the overall block I/O traffic during + the run. You can look at the + blkparse + manpage to learn the + meaning of each field displayed in the trace listing. + + +
+ Live Mode + + + blktrace and blkparse are designed from the ground up to + be able to operate together in a 'pipe mode' where the + stdout of blktrace can be fed directly into the stdin of + blkparse: + + root@crownbay:~# blktrace /dev/sdc -o - | blkparse -i - + + This enables long-lived tracing sessions to run without + writing anything to disk, and allows the user to look for + certain conditions in the trace data in 'real-time' by + viewing the trace output as it scrolls by on the screen or + by passing it along to yet another program in the pipeline + such as grep which can be used to identify and capture + conditions of interest. + + + + There's actually another blktrace command that implements + the above pipeline as a single command, so the user doesn't + have to bother typing in the above command sequence: + + root@crownbay:~# btrace /dev/sdc + + +
+ +
+ Using blktrace Remotely + + + Because blktrace traces block I/O and at the same time + normally writes its trace data to a block device, and + in general because it's not really a great idea to make + the device being traced the same as the device the tracer + writes to, blktrace provides a way to trace without + perturbing the traced device at all by providing native + support for sending all trace data over the network. + + + + To have blktrace operate in this mode, start blktrace on + the target system being traced with the -l option, along with + the device to trace: + + root@crownbay:~# blktrace -l /dev/sdc + server: waiting for connections... + + On the host system, use the -h option to connect to the + target system, also passing it the device to trace: + + $ blktrace -d /dev/sdc -h 192.168.1.43 + blktrace: connecting to 192.168.1.43 + blktrace: connected! + + On the target system, you should see this: + + server: connection from 192.168.1.43 + + In another shell, execute a workload you want to trace. + + root@crownbay:/media/sdc# rm linux-2.6.19.2.tar.bz2; wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2; sync + Connecting to downloads.yoctoproject.org (140.211.169.59:80) + linux-2.6.19.2.tar.b 100% |*******************************| 41727k 0:00:00 ETA + + When it's done, do a Ctrl-C on the host system to + stop the trace: + + ^C=== sdc === + CPU 0: 7691 events, 361 KiB data + CPU 1: 4109 events, 193 KiB data + Total: 11800 events (dropped 0), 554 KiB data + + On the target system, you should also see a trace + summary for the trace just ended: + + server: end of run for 192.168.1.43:sdc + === sdc === + CPU 0: 7691 events, 361 KiB data + CPU 1: 4109 events, 193 KiB data + Total: 11800 events (dropped 0), 554 KiB data + + The blktrace instance on the host will save the target + output inside a hostname-timestamp directory: + + $ ls -al + drwxr-xr-x 10 root root 1024 Oct 28 02:40 . + drwxr-sr-x 4 root root 1024 Oct 26 18:24 .. + drwxr-xr-x 2 root root 1024 Oct 28 02:40 192.168.1.43-2012-10-28-02:40:56 + + cd into that directory to see the output files: + + $ ls -l + -rw-r--r-- 1 root root 369193 Oct 28 02:44 sdc.blktrace.0 + -rw-r--r-- 1 root root 197278 Oct 28 02:44 sdc.blktrace.1 + + And run blkparse on the host system using the device name: + + $ blkparse sdc + + 8,32 1 1 0.000000000 1263 Q RM 6016 + 8 [ls] + 8,32 1 0 0.000036038 0 m N cfq1263 alloced + 8,32 1 2 0.000039390 1263 G RM 6016 + 8 [ls] + 8,32 1 3 0.000049168 1263 I RM 6016 + 8 [ls] + 8,32 1 0 0.000056152 0 m N cfq1263 insert_request + 8,32 1 0 0.000061600 0 m N cfq1263 add_to_rr + 8,32 1 0 0.000075498 0 m N cfq workload slice:300 + . + . + . + 8,32 0 0 177.266385696 0 m N cfq1267 arm_idle: 8 group_idle: 0 + 8,32 0 0 177.266388140 0 m N cfq schedule dispatch + 8,32 1 0 177.266679239 0 m N cfq1267 slice expired t=0 + 8,32 1 0 177.266689297 0 m N cfq1267 sl_used=9 disp=6 charge=9 iops=0 sect=56 + 8,32 1 0 177.266692649 0 m N cfq1267 del_from_rr + 8,32 1 0 177.266696560 0 m N cfq1267 put_queue + + CPU0 (sdc): + Reads Queued: 0, 0KiB Writes Queued: 270, 21,708KiB + Read Dispatches: 59, 2,628KiB Write Dispatches: 495, 39,964KiB + Reads Requeued: 0 Writes Requeued: 0 + Reads Completed: 90, 2,752KiB Writes Completed: 543, 41,596KiB + Read Merges: 0, 0KiB Write Merges: 9, 344KiB + Read depth: 2 Write depth: 2 + IO unplugs: 20 Timer unplugs: 1 + CPU1 (sdc): + Reads Queued: 688, 2,752KiB Writes Queued: 381, 20,652KiB + Read Dispatches: 31, 124KiB Write Dispatches: 59, 2,396KiB + Reads Requeued: 0 Writes Requeued: 0 + Reads Completed: 0, 0KiB Writes Completed: 11, 764KiB + Read Merges: 598, 2,392KiB Write Merges: 88, 448KiB + Read depth: 2 Write depth: 2 + IO unplugs: 52 Timer unplugs: 0 + + Total (sdc): + Reads Queued: 688, 2,752KiB Writes Queued: 651, 42,360KiB + Read Dispatches: 90, 2,752KiB Write Dispatches: 554, 42,360KiB + Reads Requeued: 0 Writes Requeued: 0 + Reads Completed: 90, 2,752KiB Writes Completed: 554, 42,360KiB + Read Merges: 598, 2,392KiB Write Merges: 97, 792KiB + IO unplugs: 72 Timer unplugs: 1 + + Throughput (R/W): 15KiB/s / 238KiB/s + Events (sdc): 9,301 entries + Skips: 0 forward (0 - 0.0%) + + You should see the trace events and summary just as + you would have if you'd run the same command on the target. + +
+ +
+ Tracing Block I/O via 'ftrace' + + + It's also possible to trace block I/O using only + trace events subsystem, + which can be useful for casual tracing + if you don't want to bother dealing with the userspace tools. + + + + To enable tracing for a given device, use + /sys/block/xxx/trace/enable, where xxx is the device name. + This for example enables tracing for /dev/sdc: + + root@crownbay:/sys/kernel/debug/tracing# echo 1 > /sys/block/sdc/trace/enable + + Once you've selected the device(s) you want to trace, + selecting the 'blk' tracer will turn the blk tracer on: + + root@crownbay:/sys/kernel/debug/tracing# cat available_tracers + blk function_graph function nop + + root@crownbay:/sys/kernel/debug/tracing# echo blk > current_tracer + + Execute the workload you're interested in: + + root@crownbay:/sys/kernel/debug/tracing# cat /media/sdc/testfile.txt + + And look at the output (note here that we're using + 'trace_pipe' instead of trace to capture this trace - + this allows us to wait around on the pipe for data to + appear): + + root@crownbay:/sys/kernel/debug/tracing# cat trace_pipe + cat-3587 [001] d..1 3023.276361: 8,32 Q R 1699848 + 8 [cat] + cat-3587 [001] d..1 3023.276410: 8,32 m N cfq3587 alloced + cat-3587 [001] d..1 3023.276415: 8,32 G R 1699848 + 8 [cat] + cat-3587 [001] d..1 3023.276424: 8,32 P N [cat] + cat-3587 [001] d..2 3023.276432: 8,32 I R 1699848 + 8 [cat] + cat-3587 [001] d..1 3023.276439: 8,32 m N cfq3587 insert_request + cat-3587 [001] d..1 3023.276445: 8,32 m N cfq3587 add_to_rr + cat-3587 [001] d..2 3023.276454: 8,32 U N [cat] 1 + cat-3587 [001] d..1 3023.276464: 8,32 m N cfq workload slice:150 + cat-3587 [001] d..1 3023.276471: 8,32 m N cfq3587 set_active wl_prio:0 wl_type:2 + cat-3587 [001] d..1 3023.276478: 8,32 m N cfq3587 fifo= (null) + cat-3587 [001] d..1 3023.276483: 8,32 m N cfq3587 dispatch_insert + cat-3587 [001] d..1 3023.276490: 8,32 m N cfq3587 dispatched a request + cat-3587 [001] d..1 3023.276497: 8,32 m N cfq3587 activate rq, drv=1 + cat-3587 [001] d..2 3023.276500: 8,32 D R 1699848 + 8 [cat] + + And this turns off tracing for the specified device: + + root@crownbay:/sys/kernel/debug/tracing# echo 0 > /sys/block/sdc/trace/enable + + +
+
+ +
+ Documentation + + + Online versions of the man pages for the commands discussed + in this section can be found here: + + http://linux.die.net/man/8/blktrace + + http://linux.die.net/man/1/blkparse + + http://linux.die.net/man/8/btrace + + + + + + The above manpages, along with manpages for the other + blktrace utilities (btt, blkiomon, etc) can be found in the + /doc directory of the blktrace tools git repo: + + $ git clone git://git.kernel.dk/blktrace.git + + +
+
+
+ diff --git a/documentation/profile-manual/profile-manual.xml b/documentation/profile-manual/profile-manual.xml new file mode 100644 index 0000000000..335457816f --- /dev/null +++ b/documentation/profile-manual/profile-manual.xml @@ -0,0 +1,105 @@ + %poky; ] > + + + + + + + + + + + + Yocto Project Profiling and Tracing Manual + + + + + Tom Zanussi + + Intel Corporation + + tom.zanussi@intel.com + + + + + + 1.4 + April 2013 + Released with the Yocto Project 1.4 Release. + + + 1.5 + October 2013 + Released with the Yocto Project 1.5 Release. + + + 1.5.1 + January 2014 + Released with the Yocto Project 1.5.1 Release. + + + 1.6 + April 2014 + Released with the Yocto Project 1.6 Release. + + + 1.7 + October 2014 + Released with the Yocto Project 1.7 Release. + + + 1.7.1 + January 2015 + Released with the Yocto Project 1.7.1 Release. + + + 1.7.2 + June 2015 + Released with the Yocto Project 1.7.2 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the + Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by + Creative Commons. + + + + For the latest version of this manual associated with this + Yocto Project release, see the + Yocto Project Profiling and Tracing Manual + from the Yocto Project website. + + + + + + + + + + + + + + + diff --git a/documentation/ref-manual/TODO b/documentation/ref-manual/TODO new file mode 100644 index 0000000000..ee0db977cc --- /dev/null +++ b/documentation/ref-manual/TODO @@ -0,0 +1,11 @@ +Handbook Todo List: + + * Document adding a new IMAGE_FEATURE to the customising images section + * Add instructions about using zaurus/openmoko emulation + * Add component overview/block diagrams + * Software Deevelopment intro should mention its software development for + intended target and could be a different arch etc and thus special case. + * Expand insane.bbclass documentation to cover tests + * Document remaining classes (see list in ref-classes) + * Document formfactor + diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml new file mode 100644 index 0000000000..c0c0d619a4 --- /dev/null +++ b/documentation/ref-manual/closer-look.xml @@ -0,0 +1,1304 @@ + %poky; ] > + + +A Closer Look at the Yocto Project Development Environment + + + This chapter takes a more detailed look at the Yocto Project + development environment. + The following diagram represents the development environment at a + high level. + The remainder of this chapter expands on the fundamental input, output, + process, and + Metadata) blocks + in the Yocto Project development environment. + + + + + + + + The generalized Yocto Project Development Environment consists of + several functional areas: + + User Configuration: + Metadata you can use to control the build process. + + Metadata Layers: + Various layers that provide software, machine, and + distro Metadata. + Source Files: + Upstream releases, local projects, and SCMs. + Build System: + Processes under the control of + BitBake. + This block expands on how BitBake fetches source, applies + patches, completes compilation, analyzes output for package + generation, creates and tests packages, generates images, and + generates cross-development tools. + Package Feeds: + Directories containing output packages (RPM, DEB or IPK), + which are subsequently used in the construction of an image or + SDK, produced by the build system. + These feeds can also be copied and shared using a web server or + other means to facilitate extending or updating existing + images on devices at runtime if runtime package management is + enabled. + Images: + Images produced by the development process. + + Application Development SDK: + Cross-development tools that are produced along with an image + or separately with BitBake. + + + +
+ User Configuration + + + User configuration helps define the build. + Through user configuration, you can tell BitBake the + target architecture for which you are building the image, + where to store downloaded source, and other build properties. + + + + The following figure shows an expanded representation of the + "User Configuration" box of the + general Yocto Project Development Environment figure: + + + + + + + + BitBake needs some basic configuration files in order to complete + a build. + These files are *.conf files. + The minimally necessary ones reside as example files in the + Source Directory. + For simplicity, this section refers to the Source Directory as + the "Poky Directory." + + + + When you clone the poky Git repository or you + download and unpack a Yocto Project release, you can set up the + Source Directory to be named anything you want. + For this discussion, the cloned repository uses the default + name poky. + + The Poky repository is primarily an aggregation of existing + repositories. + It is not a canonical upstream source. + + + + + The meta-yocto layer inside Poky contains + a conf directory that has example + configuration files. + These example files are used as a basis for creating actual + configuration files when you source the build environment + script + (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + Sourcing the build environment script creates a + Build Directory + if one does not already exist. + BitBake uses the Build Directory for all its work during builds. + The Build Directory has a conf directory that + contains default versions of your local.conf + and bblayers.conf configuration files. + These default configuration files are created only if versions + do not already exist in the Build Directory at the time you + source the build environment setup script. + + + + Because the Poky repository is fundamentally an aggregation of + existing repositories, some users might be familiar with running + the &OE_INIT_FILE; or + oe-init-build-env-memres script in the context + of separate OpenEmbedded-Core and BitBake repositories rather than a + single Poky repository. + This discussion assumes the script is executed from within a cloned + or unpacked version of Poky. + + + + Depending on where the script is sourced, different sub-scripts + are called to set up the Build Directory (Yocto or OpenEmbedded). + Specifically, the script + scripts/oe-setup-builddir inside the + poky directory sets up the Build Directory and seeds the directory + (if necessary) with configuration files appropriate for the + Yocto Project development environment. + + The scripts/oe-setup-builddir script + uses the $TEMPLATECONF variable to + determine which sample configuration files to locate. + + + + + The local.conf file provides many + basic variables that define a build environment. + Here is a list of a few. + To see the default configurations in a local.conf + file created by the build environment script, see the + local.conf.sample in the + meta-yocto layer: + + Parallelism Options: + Controlled by the + BB_NUMBER_THREADS + and + PARALLEL_MAKE + variables. + Target Machine Selection: + Controlled by the + MACHINE + variable. + Download Directory: + Controlled by the + DL_DIR + variable. + Shared State Directory: + Controlled by the + SSTATE_DIR + variable. + Build Output: + Controlled by the + TMPDIR + variable. + + + Configurations set in the conf/local.conf + file can also be set in the + conf/site.conf and + conf/auto.conf configuration files. + + + + + The bblayers.conf file tells BitBake what + layers you want considered during the build. + By default, the layers listed in this file include layers + minimally needed by the build system. + However, you must manually add any custom layers you have created. + You can find more information on working with the + bblayers.conf file in the + "Enabling Your Layer" + section in the Yocto Project Development Manual. + + + + The files site.conf and + auto.conf are not created by the environment + initialization script. + If you want these configuration files, you must create them + yourself: + + site.conf: + You can use the conf/site.conf + configuration file to configure multiple build directories. + For example, suppose you had several build environments and + they shared some common features. + You can set these default build properties here. + A good example is perhaps the level of parallelism you want + to use through the + BB_NUMBER_THREADS + and + PARALLEL_MAKE + variables. + One useful scenario for using the + conf/site.conf file is to extend your + BBPATH + variable to include the path to a + conf/site.conf. + Then, when BitBake looks for Metadata using + BBPATH, it finds the + conf/site.conf file and applies your + common configurations found in the file. + To override configurations in a particular build directory, + alter the similar configurations within that build + directory's conf/local.conf file. + + auto.conf: + This file is not hand-created. + Rather, 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 conf/local.conf + or the conf/site.conf files. + + + + + + You can edit all configuration files to further define + any particular build environment. + This process is represented by the "User Configuration Edits" + box in the figure. + + + + When you launch your build with the + bitbake target command, BitBake + sorts out the configurations to ultimately define your build + environment. + +
+ +
+ Metadata, Machine Configuration, and Policy Configuration + + + The previous section described the user configurations that + define BitBake's global behavior. + This section takes a closer look at the layers the build system + uses to further control the build. + These layers provide Metadata for the software, machine, and + policy. + + + + In general, three types of layer input exist: + + Policy Configuration: + Distribution Layers provide top-level or general + policies for the image or SDK being built. + For example, this layer would dictate whether BitBake + produces RPM or IPK packages. + Machine Configuration: + Board Support Package (BSP) layers provide machine + configurations. + This type of information is specific to a particular + target architecture. + Metadata: + Software layers contain user-supplied recipe files, + patches, and append files. + + + + + + The following figure shows an expanded representation of the + Metadata, Machine Configuration, and Policy Configuration input + (layers) boxes of the + general Yocto Project Development Environment figure: + + + + + + + + In general, all layers have a similar structure. + They all contain a licensing file + (e.g. COPYING) if the layer is to be + distributed, a README file as good practice + and especially if the layer is to be distributed, a + configuration directory, and recipe directories. + + + + The Yocto Project has many layers that can be used. + You can see a web-interface listing of them on the + Source Repositories + page. + The layers are shown at the bottom categorized under + "Yocto Metadata Layers." + These layers are fundamentally a subset of the + OpenEmbedded Metadata Index, + which lists all layers provided by the OpenEmbedded community. + + Layers exist in the Yocto Project Source Repositories that + cannot be found in the OpenEmbedded Metadata Index. + These layers are either deprecated or experimental in nature. + + + + + BitBake uses the conf/bblayers.conf file, + which is part of the user configuration, to find what layers it + should be using as part of the build. + + + + For more information on layers, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Manual. + + +
+ Distro Layer + + + The distribution layer provides policy configurations for your + distribution. + Best practices dictate that you isolate these types of + configurations into their own layer. + Settings you provide in + conf/distro/distro.conf override + similar + settings that BitBake finds in your + conf/local.conf file in the Build + Directory. + + + + The following list provides some explanation and references + for what you typically find in the distribution layer: + + classes: + Class files (.bbclass) hold + common functionality that can be shared among + recipes in the distribution. + When your recipes inherit a class, they take on the + settings and functions for that class. + You can read more about class files in the + "Classes" section. + + conf: + This area holds configuration files for the + layer (conf/layer.conf), + the distribution + (conf/distro/distro.conf), + and any distribution-wide include files. + + recipes-*: + Recipes and append files that affect common + functionality across the distribution. + This area could include recipes and append files + to add distribution-specific configuration, + initialization scripts, custom image recipes, + and so forth. + + +
+ +
+ BSP Layer + + + The BSP Layer provides machine configurations. + Everything in this layer is specific to the machine for which + you are building the image or the SDK. + A common structure or form is defined for BSP layers. + You can learn more about this structure in the + Yocto Project Board Support Package (BSP) Developer's Guide. + + In order for a BSP layer to be considered compliant with the + Yocto Project, it must meet some structural requirements. + + + + + The BSP Layer's configuration directory contains + configuration files for the machine + (conf/machine/machine.conf) and, + of course, the layer (conf/layer.conf). + + + + The remainder of the layer is dedicated to specific recipes + by function: recipes-bsp, + recipes-core, + recipes-graphics, and + recipes-kernel. + Metadata can exist for multiple formfactors, graphics + support systems, and so forth. + + While the figure shows several recipes-* + directories, not all these directories appear in all + BSP layers. + + +
+ +
+ Software Layer + + + The software layer provides the Metadata for additional + software packages used during the build. + This layer does not include Metadata that is specific to the + distribution or the machine, which are found in their + respective layers. + + + + This layer contains any new recipes that your project needs + in the form of recipe files. + +
+
+ +
+ Sources + + + In order for the OpenEmbedded build system to create an image or + any target, it must be able to access source files. + The + general Yocto Project Development Environment figure + represents source files using the "Upstream Project Releases", + "Local Projects", and "SCMs (optional)" boxes. + The figure represents mirrors, which also play a role in locating + source files, with the "Source Mirror(s)" box. + + + + The method by which source files are ultimately organized is + a function of the project. + For example, for released software, projects tend to use tarballs + or other archived files that can capture the state of a release + guaranteeing that it is statically represented. + On the other hand, for a project that is more dynamic or + experimental in nature, a project might keep source files in a + repository controlled by a Source Control Manager (SCM) such as + Git. + Pulling source from a repository allows you to control + the point in the repository (the revision) from which you want to + build software. + Finally, a combination of the two might exist, which would give the + consumer a choice when deciding where to get source files. + + + + BitBake uses the + SRC_URI + variable to point to source files regardless of their location. + Each recipe must have a SRC_URI variable + that points to the source. + + + + Another area that plays a significant role in where source files + come from is pointed to by the + DL_DIR + variable. + This area is a cache that can hold previously downloaded source. + You can also instruct the OpenEmbedded build system to create + tarballs from Git repositories, which is not the default behavior, + and store them in the DL_DIR by using the + BB_GENERATE_MIRROR_TARBALLS + variable. + + + + Judicious use of a DL_DIR directory can + save the build system a trip across the Internet when looking + for files. + A good method for using a download directory is to have + DL_DIR point to an area outside of your + Build Directory. + Doing so allows you to safely delete the Build Directory + if needed without fear of removing any downloaded source file. + + + + The remainder of this section provides a deeper look into the + source files and the mirrors. + Here is a more detailed look at the source file area of the + base figure: + + + +
+ Upstream Project Releases + + + Upstream project releases exist anywhere in the form of an + archived file (e.g. tarball or zip file). + These files correspond to individual recipes. + For example, the figure uses specific releases each for + BusyBox, Qt, and Dbus. + An archive file can be for any released product that can be + built using a recipe. + +
+ +
+ Local Projects + + + Local projects are custom bits of software the user provides. + These bits reside somewhere local to a project - perhaps + a directory into which the user checks in items (e.g. + a local directory containing a development source tree + used by the group). + + + + The canonical method through which to include a local project + is to use the + externalsrc + class to include that local project. + You use either the local.conf or a + recipe's append file to override or set the + recipe to point to the local directory on your disk to pull + in the whole source tree. + + + + For information on how to use the + externalsrc class, see the + "externalsrc.bbclass" + section. + +
+ +
+ Source Control Managers (Optional) + + + Another place the build system can get source files from is + through an SCM such as Git or Subversion. + In this case, a repository is cloned or checked out. + The + do_fetch + task inside BitBake uses + the SRC_URI + variable and the argument's prefix to determine the correct + fetcher module. + + + + For information on how to have the OpenEmbedded build system + generate tarballs for Git repositories and place them in the + DL_DIR + directory, see the + BB_GENERATE_MIRROR_TARBALLS + variable. + + + + When fetching a repository, BitBake uses the + SRCREV + variable to determine the specific revision from which to + build. + +
+ +
+ Source Mirror(s) + + + Two kinds of mirrors exist: pre-mirrors and regular mirrors. + The PREMIRRORS + and + MIRRORS + variables point to these, respectively. + BitBake checks pre-mirrors before looking upstream for any + source files. + Pre-mirrors are appropriate when you have a shared directory + that is not a directory defined by the + DL_DIR + variable. + A Pre-mirror typically points to a shared directory that is + local to your organization. + + + + Regular mirrors can be any site across the Internet that is + used as an alternative location for source code should the + primary site not be functioning for some reason or another. + +
+
+ +
+ Package Feeds + + + When the OpenEmbedded build system generates an image or an SDK, + it gets the packages from a package feed area located in the + Build Directory. + The + general Yocto Project Development Environment figure + shows this package feeds area in the upper-right corner. + + + + This section looks a little closer into the package feeds area used + by the build system. + Here is a more detailed look at the area: + + + + + Package feeds are an intermediary step in the build process. + BitBake generates packages whose types are defined by the + PACKAGE_CLASSES + variable. + Before placing the packages into package feeds, + the build process validates them with generated output quality + assurance checks through the + insane + class. + + + + The package feed area resides in + tmp/deploy of the Build Directory. + Folders are created that correspond to the package type + (IPK, DEB, or RPM) created. + Further organization is derived through the value of the + PACKAGE_ARCH + variable for each package. + For example, packages can exist for the i586 or qemux86 + architectures. + The package files themselves reside within the appropriate + architecture folder. + + + + BitBake uses the do_package_write_* tasks to + place generated packages into the package holding area (e.g. + do_package_write_ipk for IPK packages). + See the + "do_package_write_deb", + "do_package_write_ipk", + "do_package_write_rpm", + and + "do_package_write_tar" + sections for additional information. + +
+ +
+ BitBake + + + The OpenEmbedded build system uses + BitBake + to produce images. + You can see from the + general Yocto Project Development Environment figure, + the BitBake area consists of several functional areas. + This section takes a closer look at each of those areas. + + + + Separate documentation exists for the BitBake tool. + See the + BitBake User Manual + for reference material on BitBake. + + +
+ Source Fetching + + + The first stages of building a recipe are to fetch and unpack + the source code: + + + + + The + do_fetch + and + do_unpack + tasks fetch the source files and unpack them into the work + directory. + + For every local file (e.g. file://) + that is part of a recipe's + SRC_URI + statement, the OpenEmbedded build system takes a checksum + of the file for the recipe and inserts the checksum into + the signature for the do_fetch. + If any local file has been modified, the + do_fetch task and all tasks that + depend on it are re-executed. + + By default, everything is accomplished in the + Build Directory, + which has a defined structure. + For additional general information on the Build Directory, + see the + "build/" + section. + + + + Unpacked source files are pointed to by the + S variable. + Each recipe has an area in the Build Directory where the + unpacked source code resides. + The name of that directory for any given recipe is defined from + several different variables. + You can see the variables that define these directories + by looking at the figure: + + TMPDIR - + The base directory where the OpenEmbedded build system + performs all its work during the build. + + PACKAGE_ARCH - + The architecture of the built package or packages. + + TARGET_OS - + The operating system of the target device. + + PN - + The name of the built package. + + PV - + The version of the recipe used to build the package. + + PR - + The revision of the recipe used to build the package. + + WORKDIR - + The location within TMPDIR where + a specific package is built. + + S - + Contains the unpacked source files for a given recipe. + + + +
+ +
+ Patching + + + Once source code is fetched and unpacked, BitBake locates + patch files and applies them to the source files: + + + + + The + do_patch + task processes recipes by + using the + SRC_URI + variable to locate applicable patch files, which by default + are *.patch or + *.diff files, or any file if + "apply=yes" is specified for the file in + SRC_URI. + + + + BitBake finds and applies multiple patches for a single recipe + in the order in which it finds the patches. + Patches are applied to the recipe's source files located in the + S directory. + + + + For more information on how the source directories are + created, see the + "Source Fetching" + section. + +
+ +
+ Configuration and Compilation + + + After source code is patched, BitBake executes tasks that + configure and compile the source code: + + + + + This step in the build process consists of three tasks: + + do_configure: + This task configures the source by enabling and + disabling any build-time and configuration options for + the software being built. + Configurations can come from the recipe itself as well + as from an inherited class. + Additionally, the software itself might configure itself + depending on the target for which it is being built. + + + The configurations handled by the + do_configure + task are specific + to source code configuration for the source code + being built by the recipe. + + If you are using the + autotools + class, + you can add additional configuration options by using + the EXTRA_OECONF + variable. + For information on how this variable works within + that class, see the + meta/classes/autotools.bbclass file. + + do_compile: + Once a configuration task has been satisfied, BitBake + compiles the source using the + do_compile + task. + Compilation occurs in the directory pointed to by the + B + variable. + Realize that the B directory is, by + default, the same as the + S + directory. + do_install: + Once compilation is done, BitBake executes the + do_install + task. + This task copies files from the B + directory and places them in a holding area pointed to + by the + D + variable. + + +
+ +
+ Package Splitting + + + After source code is configured and compiled, the + OpenEmbedded build system analyzes + the results and splits the output into packages: + + + + + The + do_package + and + do_packagedata + tasks combine to analyze + the files found in the + D directory + and split them into subsets based on available packages and + files. + The analyzing process involves the following as well as other + items: splitting out debugging symbols, + looking at shared library dependencies between packages, + and looking at package relationships. + The do_packagedata task creates package + metadata based on the analysis such that the + OpenEmbedded build system can generate the final packages. + Working, staged, and intermediate results of the analysis + and package splitting process use these areas: + + PKGD - + The destination directory for packages before they are + split. + + PKGDATA_DIR - + A shared, global-state directory that holds data + generated during the packaging process. + + PKGDESTWORK - + A temporary work area used by the + do_package task. + + PKGDEST - + The parent directory for packages after they have + been split. + + + The FILES + variable defines the files that go into each package in + PACKAGES. + If you want details on how this is accomplished, you can + look at the + package + class. + + + + Depending on the type of packages being created (RPM, DEB, or + IPK), the do_package_write_* task + creates the actual packages and places them in the + Package Feed area, which is + ${TMPDIR}/deploy. + You can see the + "Package Feeds" + section for more detail on that part of the build process. + + Support for creating feeds directly from the + deploy/* directories does not exist. + Creating such feeds usually requires some kind of feed + maintenance mechanism that would upload the new packages + into an official package feed (e.g. the + Ångström distribution). + This functionality is highly distribution-specific + and thus is not provided out of the box. + + +
+ +
+ Image Generation + + + Once packages are split and stored in the Package Feeds area, + the OpenEmbedded build system uses BitBake to generate the + root filesystem image: + + + + + The image generation process consists of several stages and + depends on many variables. + The + do_rootfs + task uses these key variables + to help create the list of packages to actually install: + + IMAGE_INSTALL: + Lists out the base set of packages to install from + the Package Feeds area. + PACKAGE_EXCLUDE: + Specifies packages that should not be installed. + + IMAGE_FEATURES: + Specifies features to include in the image. + Most of these features map to additional packages for + installation. + PACKAGE_CLASSES: + Specifies the package backend to use and consequently + helps determine where to locate packages within the + Package Feeds area. + IMAGE_LINGUAS: + Determines the language(s) for which additional + language support packages are installed. + + + + + + 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. + + + + 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. + If you are using a + read-only root filesystem, + all the post installation scripts must succeed during the + package installation phase since the root filesystem is + read-only. + + + + During Optimization, optimizing processes are run across + the image. + These processes include mklibs and + prelink. + The mklibs process optimizes the size + of the libraries. + A prelink process optimizes the dynamic + linking of shared libraries to reduce start up time of + executables. + + + + Along with writing out the root filesystem image, the + do_rootfs task creates a manifest file + (.manifest) 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 + testimage + class, for example, to determine whether or not to run + specific tests. + See the + IMAGE_MANIFEST + variable for additional information. + + + + 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. + + + + After the root filesystem has been constructed, the image + generation process turns everything into an image file or + a set of image files. + The formats used for the root filesystem depend on the + IMAGE_FSTYPES + variable. + + + + The entire image generation process is run under Pseudo. + Running under Pseudo ensures that the files in the root + filesystem have correct ownership. + +
+ +
+ SDK Generation + + + The OpenEmbedded build system uses BitBake to generate the + Software Development Kit (SDK) installer script: + + + + + For more information on the cross-development toolchain + generation, see the + "Cross-Development Toolchain Generation" + section. + For information on advantages gained when building a + cross-development toolchain using the + do_populate_sdk + task, see the + "Optionally Building a Toolchain Installer" + section in the Yocto Project Application Developer's Guide. + + + + Like image generation, the SDK script process consists of + several stages and depends on many variables. + The do_populate_sdk task uses these + key variables to help create the list of packages to actually + install. + For information on the variables listed in the figure, see the + "Application Development SDK" + section. + + + + The do_populate_sdk task 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 + SDKMACHINE. + + + + Once both parts are constructed, the + do_populate_sdk 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 final output of the task is the Cross-development + toolchain installation script (.sh file), + which includes the environment setup script. + +
+
+ +
+ Images + + + The images produced by the OpenEmbedded build system + are compressed forms of the + root filesystem that are ready to boot on a target device. + You can see from the + general Yocto Project Development Environment figure + that BitBake output, in part, consists of images. + This section is going to look more closely at this output: + + + + + For a list of example images that the Yocto Project provides, + see the + "Images" chapter. + + + + Images are written out to the + Build Directory + inside the tmp/deploy/images/machine/ + folder as shown in the figure. + This folder contains any files expected to be loaded on the + target device. + The + DEPLOY_DIR + variable points to the deploy directory, + while the + DEPLOY_DIR_IMAGE + variable points to the appropriate directory containing images for + the current configuration. + + kernel-image: + A kernel binary file. + The KERNEL_IMAGETYPE + variable setting determines the naming scheme for the + kernel image file. + Depending on that variable, the file could begin with + a variety of naming strings. + The deploy/images/machine + directory can contain multiple image files for the + machine. + root-filesystem-image: + Root filesystems for the target device (e.g. + *.ext3 or *.bz2 + files). + The IMAGE_FSTYPES + variable setting determines the root filesystem image + type. + The deploy/images/machine + directory can contain multiple root filesystems for the + machine. + kernel-modules: + Tarballs that contain all the modules built for the kernel. + Kernel module tarballs exist for legacy purposes and + can be suppressed by setting the + MODULE_TARBALL_DEPLOY + variable to "0". + The deploy/images/machine + directory can contain multiple kernel module tarballs + for the machine. + bootloaders: + Bootloaders supporting the image, if applicable to the + target machine. + The deploy/images/machine + directory can contain multiple bootloaders for the + machine. + symlinks: + The deploy/images/machine + folder contains + a symbolic link that points to the most recently built file + for each machine. + These links might be useful for external scripts that + need to obtain the latest version of each file. + + + +
+ +
+ Application Development SDK + + + In the + general Yocto Project Development Environment figure, + the output labeled "Application Development SDK" represents an + SDK. + This section is going to take a closer look at this output: + + + + + The specific form of this output is a self-extracting + SDK installer (*.sh) that, when run, + installs the SDK, which consists of a cross-development + toolchain, a set of libraries and headers, and an SDK + environment setup script. + Running this installer essentially sets up your + cross-development environment. + You can think of the cross-toolchain as the "host" + 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 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. + + + + For background information on cross-development toolchains + in the Yocto Project development environment, see the + "Cross-Development Toolchain Generation" + section. + For information on setting up a cross-development + environment, see the + "Installing the ADT and Toolchains" + section in the Yocto Project Application Developer's Guide. + + + + + Once built, the SDK installers are written out to the + deploy/sdk folder inside the + Build Directory + as shown in the figure at the beginning of this section. + Several variables exist that help configure these files: + + DEPLOY_DIR: + Points to the deploy + directory. + SDKMACHINE: + Specifies the architecture of the machine + on which the cross-development tools are run to + create packages for the target hardware. + + SDKIMAGE_FEATURES: + Lists the features to include in the "target" part + of the SDK. + + TOOLCHAIN_HOST_TASK: + Lists packages that make up the host + part of the SDK (i.e. the part that runs on + the SDKMACHINE). + When you use + bitbake -c populate_sdk imagename + to create the SDK, a set of default packages + apply. + This variable allows you to add more packages. + + TOOLCHAIN_TARGET_TASK: + Lists packages that make up the target part + of the SDK (i.e. the part built for the + target hardware). + + SDKPATH: + Defines the default SDK installation path offered by the + installation script. + + + +
+ +
+ diff --git a/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb new file mode 100644 index 0000000000..5dfb0b30cf --- /dev/null +++ b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb @@ -0,0 +1,8 @@ +DESCRIPTION = "GNU Helloworld application" +SECTION = "examples" +LICENSE = "GPLv3" +LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010" + +SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2" + +inherit autotools diff --git a/documentation/ref-manual/examples/hello-single/files/helloworld.c b/documentation/ref-manual/examples/hello-single/files/helloworld.c new file mode 100644 index 0000000000..fc7169b7b8 --- /dev/null +++ b/documentation/ref-manual/examples/hello-single/files/helloworld.c @@ -0,0 +1,8 @@ +#include + +int main(void) +{ + printf("Hello world!\n"); + + return 0; +} diff --git a/documentation/ref-manual/examples/hello-single/hello.bb b/documentation/ref-manual/examples/hello-single/hello.bb new file mode 100644 index 0000000000..0812743e39 --- /dev/null +++ b/documentation/ref-manual/examples/hello-single/hello.bb @@ -0,0 +1,17 @@ +DESCRIPTION = "Simple helloworld application" +SECTION = "examples" +LICENSE = "MIT" +LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" + +SRC_URI = "file://helloworld.c" + +S = "${WORKDIR}" + +do_compile() { + ${CC} helloworld.c -o helloworld +} + +do_install() { + install -d ${D}${bindir} + install -m 0755 helloworld ${D}${bindir} +} diff --git a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb new file mode 100644 index 0000000000..b58d4d7bd1 --- /dev/null +++ b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb @@ -0,0 +1,14 @@ +require xorg-lib-common.inc + +DESCRIPTION = "X11 Pixmap library" +LICENSE = "X-BSD" +LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" +DEPENDS += "libxext" +PR = "r2" +PE = "1" + +XORG_PN = "libXpm" + +PACKAGES =+ "sxpm cxpm" +FILES_cxpm = "${bindir}/cxpm" +FILES_sxpm = "${bindir}/sxpm" diff --git a/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb new file mode 100644 index 0000000000..5d05a437a4 --- /dev/null +++ b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb @@ -0,0 +1,15 @@ +DESCRIPTION = "Tools for managing memory technology devices." +SECTION = "base" +DEPENDS = "zlib" +HOMEPAGE = "http://www.linux-mtd.infradead.org/" +LICENSE = "GPLv2" +LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ + file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" + +SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz" + +CFLAGS_prepend = "-I ${S}/include " + +do_install() { + oe_runmake install DESTDIR=${D} +} diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml new file mode 100644 index 0000000000..da6ce20eef --- /dev/null +++ b/documentation/ref-manual/faq.xml @@ -0,0 +1,799 @@ + %poky; ] > + + +FAQ + + + + + How does Poky differ from OpenEmbedded? + + + + + The term "Poky" + refers to the specific reference build system that + the Yocto Project provides. + Poky is based on OE-Core + and BitBake. + Thus, the generic term used here for the build system is + the "OpenEmbedded build system." + Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with + changes always being merged to OE-Core or BitBake first before being pulled back + into Poky. + This practice benefits both projects immediately. + + + + + + + + My development system does not meet the + required Git, tar, and Python versions. + In particular, I do not have Python 2.7.3 or greater, or + I do have Python 3.x, which is specifically not supported by + the Yocto Project. + Can I still use the Yocto Project? + + + + + You can get the required tools on your host development + system a couple different ways (i.e. building a tarball or + downloading a tarball). + See the + "Required Git, tar, and Python Versions" + section for steps on how to update your build tools. + + + + + + + + How can you claim Poky / OpenEmbedded-Core is stable? + + + + + There are three areas that help with stability; + + The Yocto Project team keeps + OE-Core small + and focused, containing around 830 recipes as opposed to the thousands + available in other OpenEmbedded community layers. + Keeping it small makes it easy to test and maintain. + The Yocto Project team runs manual and automated tests + using a small, fixed set of reference hardware as well as emulated + targets. + The Yocto Project uses an autobuilder, + which provides continuous build and integration tests. + + + + + + + + + How do I get support for my board added to the Yocto Project? + + + + + Support for an additional board is added by creating a + Board Support Package (BSP) layer for it. + For more information on how to create a BSP layer, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Manual and the + Yocto Project Board Support Package (BSP) Developer's Guide. + + + Usually, if the board is not completely exotic, adding support in + the Yocto Project is fairly straightforward. + + + + + + + + Are there any products built using the OpenEmbedded build system? + + + + + The software running on the Vernier LabQuest + is built using the OpenEmbedded build system. + See the Vernier LabQuest + website for more information. + There are a number of pre-production devices using the OpenEmbedded build system + and the Yocto Project team + announces them as soon as they are released. + + + + + + + + What does the OpenEmbedded build system produce as output? + + + + + Because you can use the same set of recipes to create output of + various formats, the output of an OpenEmbedded build depends on + how you start it. + Usually, the output is a flashable image ready for the target + device. + + + + + + + + How do I add my package to the Yocto Project? + + + + + To add a package, you need to create a BitBake recipe. + For information on how to create a BitBake recipe, see the + "Writing a New Recipe" + in the Yocto Project Development Manual. + + + + + + + + Do I have to reflash my entire board with a new Yocto Project image when recompiling + a package? + + + + + The OpenEmbedded build system can build packages in various + formats such as IPK for OPKG, Debian package + (.deb), or RPM. + You can then upgrade the packages using the package tools on + the device, much like on a desktop distribution such as + Ubuntu or Fedora. + However, package management on the target is entirely optional. + + + + + + + + What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? + + + + + GNOME Mobile is a subset of the GNOME + platform targeted at mobile and embedded devices. + The main difference between GNOME Mobile and standard GNOME is that + desktop-orientated libraries have been removed, along with deprecated libraries, + creating a much smaller footprint. + + + + + + + + I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'. + What is wrong? + + + + + You are probably running the build on an NTFS filesystem. + Use ext2, ext3, or ext4 instead. + + + + + + + + + + I see lots of 404 responses for files on + &YOCTO_HOME_URL;/sources/*. Is something wrong? + + + + + Nothing is wrong. + The OpenEmbedded build system checks any configured source mirrors before downloading + from the upstream sources. + The build system does this searching for both source archives and + pre-checked out versions of SCM-managed software. + These checks help in large installations because it can reduce load on the SCM servers + themselves. + The address above is one of the default mirrors configured into the + build system. + Consequently, if an upstream source disappears, the team + can place sources there so builds continue to work. + + + + + + + + I have machine-specific data in a package for one machine only but the package is + being marked as machine-specific in all cases, how do I prevent this? + + + + + Set SRC_URI_OVERRIDES_PACKAGE_ARCH + = "0" in the .bb file but make sure the package is + manually marked as + machine-specific for the case that needs it. + The code that handles + SRC_URI_OVERRIDES_PACKAGE_ARCH is in + the meta/classes/base.bbclass file. + + + + + + + + I'm behind a firewall and need to use a proxy server. How do I do that? + + + + + Most source fetching by the OpenEmbedded build system is done by wget + and you therefore need to specify the proxy settings in a + .wgetrc file in your home directory. + Here are some example settings: + + http_proxy = http://proxy.yoyodyne.com:18023/ + ftp_proxy = http://proxy.yoyodyne.com:18023/ + + The Yocto Project also includes a + site.conf.sample file that shows how to + configure CVS and Git proxy servers if needed. + + + + + + + + What’s the difference between target and target-native? + + + + + The *-native targets are designed to run on the system + being used for the build. + These are usually tools that are needed to assist the build in some way such as + quilt-native, which is used to apply patches. + The non-native version is the one that runs on the target device. + + + + + + + + I'm seeing random build failures. Help?! + + + + + If the same build is failing in totally different and random + ways, the most likely explanation is: + + The hardware you are running the build on + has some problem. + You are running the build under + virtualization, in which case the virtualization + probably has bugs. + + The OpenEmbedded build system processes a massive amount of + data that causes lots of network, disk and CPU activity and + is sensitive to even single-bit failures in any of these areas. + True random failures have always been traced back to hardware + or virtualization issues. + + + + + + + + What do we need to ship for license compliance? + + + + + This is a difficult question and you need to consult your lawyer + for the answer for your specific case. + It is worth bearing in mind that for GPL compliance, there needs + to be enough information shipped to allow someone else to + rebuild and produce the same end result you are shipping. + This means sharing the source code, any patches applied to it, + and also any configuration information about how that package + was configured and built. + + + + You can find more information on licensing in the + "Licensing" + and "Maintaining Open Source License Compliance During Your Product's Lifecycle" + sections, both of which are in the Yocto Project Development + Manual. + + + + + + + + How do I disable the cursor on my touchscreen device? + + + + + You need to create a form factor file as described in the + "Miscellaneous BSP-Specific Recipe Files" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide. + Set the HAVE_TOUCHSCREEN variable equal to + one as follows: + + HAVE_TOUCHSCREEN=1 + + + + + + + + + How do I make sure connected network interfaces are brought up by default? + + + + + The default interfaces file provided by the netbase recipe does not + automatically bring up network interfaces. + Therefore, you will need to add a BSP-specific netbase that includes an interfaces + file. + See the "Miscellaneous BSP-Specific Recipe Files" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide for information on creating these types of + miscellaneous recipe files. + + + For example, add the following files to your layer: + + meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces + meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend + + + + + + + + + How do I create images with more free space? + + + + + By default, the OpenEmbedded build system creates images + that are 1.3 times the size of the populated root filesystem. + To affect the image size, you need to set various + configurations: + + Image Size: + The OpenEmbedded build system uses the + IMAGE_ROOTFS_SIZE + variable to define the size of the image in Kbytes. + The build system determines the size by taking into + account the initial root filesystem size before any + modifications such as requested size for the image and + any requested additional free disk space to be + added to the image. + Overhead: + Use the + IMAGE_OVERHEAD_FACTOR + variable to define the multiplier that the build system + applies to the initial image size, which is 1.3 by + default. + Additional Free Space: + Use the + IMAGE_ROOTFS_EXTRA_SPACE + variable to add additional free space to the image. + The build system adds this space to the image after + it determines its + IMAGE_ROOTFS_SIZE. + + + + + + + + + + Why don't you support directories with spaces in the pathnames? + + + + + The Yocto Project team has tried to do this before but too + many of the tools the OpenEmbedded build system depends on, + such as autoconf, break when they find + spaces in pathnames. + Until that situation changes, the team will not support spaces + in pathnames. + + + + + + + + How do I use an external toolchain? + + + + + The toolchain configuration is very flexible and customizable. + It is primarily controlled with the + TCMODE + variable. + This variable controls which tcmode-*.inc + file to include from the + meta/conf/distro/include directory within + the + Source Directory. + + + + The default value of TCMODE is "default", + which tells the OpenEmbedded build system to use its internally + built toolchain (i.e. tcmode-default.inc). + However, other patterns are accepted. + In particular, "external-*" refers to external toolchains. + One example is the Sourcery G++ Toolchain. + The support for this toolchain resides in the separate + meta-sourcery layer at + . + + + + In addition to the toolchain configuration, you also need a + corresponding toolchain recipe file. + This recipe file needs to package up any pre-built objects in + the toolchain such as libgcc, + libstdcc++, any locales, and + libc. + + + + + + + + How does the OpenEmbedded build system obtain source code and + will it work behind my firewall or proxy server? + + + + + The way the build system obtains source code is highly + configurable. + You can setup the build system to get source code in most + environments if HTTP transport is available. + + + When the build system searches for source code, it first + tries the local download directory. + If that location fails, Poky tries + PREMIRRORS, + the upstream source, and then + MIRRORS + in that order. + + + Assuming your distribution is "poky", the OpenEmbedded build + system uses the Yocto Project source + PREMIRRORS by default for SCM-based + sources, upstreams for normal tarballs, and then falls back + to a number of other mirrors including the Yocto Project + source mirror if those fail. + + + As an example, you could add a specific server for the + build system to attempt before any others by adding something + like the following to the local.conf + configuration file: + + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + + + + These changes cause the build system to intercept Git, FTP, + HTTP, and HTTPS requests and direct them to the + http:// sources mirror. + You can use file:// URLs to point to + local directories or network shares as well. + + + Aside from the previous technique, these options also exist: + + BB_NO_NETWORK = "1" + + This statement tells BitBake to issue an error instead of + trying to access the Internet. + This technique is useful if you want to ensure code builds + only from local sources. + + + Here is another technique: + + BB_FETCH_PREMIRRORONLY = "1" + + This statement limits the build system to pulling source + from the PREMIRRORS only. + Again, this technique is useful for reproducing builds. + + + Here is another technique: + + BB_GENERATE_MIRROR_TARBALLS = "1" + + This statement tells the build system to generate mirror + tarballs. + This technique is useful if you want to create a mirror server. + If not, however, the technique can simply waste time during + the build. + + + Finally, consider an example where you are behind an + HTTP-only firewall. + You could make the following changes to the + local.conf configuration file as long as + the PREMIRRORS server is current: + + PREMIRRORS_prepend = "\ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + BB_FETCH_PREMIRRORONLY = "1" + + These changes would cause the build system to successfully + fetch source over HTTP and any network accesses to anything + other than the PREMIRRORS would fail. + + + The build system also honors the standard shell environment + variables http_proxy, + ftp_proxy, + https_proxy, and + all_proxy to redirect requests through + proxy servers. + + + You can find more information on the + "Working Behind a Network Proxy" + Wiki page. + + + + + + + + Can I get rid of build output so I can start over? + + + + + Yes - you can easily do this. + When you use BitBake to build an image, all the build output + goes into the directory created when you run the + build environment setup script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + By default, this Build Directory + is named build but can be named + anything you want. + + + + Within the Build Directory, is the tmp + directory. + To remove all the build output yet preserve any source code or + downloaded files from previous builds, simply remove the + tmp directory. + + + + + + + + Why do ${bindir} and ${libdir} have strange values for -native recipes? + + + + + Executables and libraries might need to be used from a + directory other than the directory into which they were + initially installed. + Complicating this situation is the fact that sometimes these + executables and libraries are compiled with the expectation + of being run from that initial installation target directory. + If this is the case, moving them causes problems. + + + + This scenario is a fundamental problem for package maintainers + of mainstream Linux distributions as well as for the + OpenEmbedded build system. + As such, a well-established solution exists. + Makefiles, Autotools configuration scripts, and other build + systems are expected to respect environment variables such as + bindir, libdir, + and sysconfdir that indicate where + executables, libraries, and data reside when a program is + actually run. + They are also expected to respect a + DESTDIR environment variable, which is + prepended to all the other variables when the build system + actually installs the files. + It is understood that the program does not actually run from + within DESTDIR. + + + + When the OpenEmbedded build system uses a recipe to build a + target-architecture program (i.e. one that is intended for + inclusion on the image being built), that program eventually + runs from the root file system of that image. + Thus, the build system provides a value of "/usr/bin" for + bindir, a value of "/usr/lib" for + libdir, and so forth. + + + + Meanwhile, DESTDIR is a path within the + Build Directory. + However, when the recipe builds a native program (i.e. one + that is intended to run on the build machine), that program + is never installed directly to the build machine's root + file system. + Consequently, the build system uses paths within the Build + Directory for DESTDIR, + bindir and related variables. + To better understand this, consider the following two paths + where the first is relatively normal and the second is not: + + Due to these lengthy examples, the paths are artificially + broken across lines for readability. + + + /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ + 1.2.8-r0/sysroot-destdir/usr/bin + + /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ + zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ + build/tmp/sysroots/x86_64-linux/usr/bin + + Even if the paths look unusual, they both are correct - + the first for a target and the second for a native recipe. + These paths are a consequence of the + DESTDIR mechanism and while they + appear strange, they are correct and in practice very effective. + + + + + + + + The files provided by my -native recipe do + not appear to be available to other recipes. + Files are missing from the native sysroot, my recipe is + installing to the wrong place, or I am getting permissions + errors during the do_install task in my recipe! What is wrong? + + + + + This situation results when a build system does + not recognize the environment variables supplied to it by + BitBake. + The incident that prompted this FAQ entry involved a Makefile + that used an environment variable named + BINDIR instead of the more standard + variable bindir. + The makefile's hardcoded default value of "/usr/bin" worked + most of the time, but not for the recipe's + -native variant. + For another example, permissions errors might be caused + by a Makefile that ignores DESTDIR or uses + a different name for that environment variable. + Check the the build system to see if these kinds of + issues exist. + + + + + + + diff --git a/documentation/ref-manual/figures/analysis-for-package-splitting.png b/documentation/ref-manual/figures/analysis-for-package-splitting.png new file mode 100644 index 0000000000..04f2794ea9 Binary files /dev/null and b/documentation/ref-manual/figures/analysis-for-package-splitting.png differ diff --git a/documentation/ref-manual/figures/buildhistory-web.png b/documentation/ref-manual/figures/buildhistory-web.png new file mode 100644 index 0000000000..f6db86c977 Binary files /dev/null and b/documentation/ref-manual/figures/buildhistory-web.png differ diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png new file mode 100644 index 0000000000..9a77bde68b Binary files /dev/null and b/documentation/ref-manual/figures/buildhistory.png differ diff --git a/documentation/ref-manual/figures/configuration-compile-autoreconf.png b/documentation/ref-manual/figures/configuration-compile-autoreconf.png new file mode 100644 index 0000000000..a07464f04c Binary files /dev/null and b/documentation/ref-manual/figures/configuration-compile-autoreconf.png differ diff --git a/documentation/ref-manual/figures/cross-development-toolchains.png b/documentation/ref-manual/figures/cross-development-toolchains.png new file mode 100644 index 0000000000..d36670a198 Binary files /dev/null and b/documentation/ref-manual/figures/cross-development-toolchains.png differ diff --git a/documentation/ref-manual/figures/image-generation.png b/documentation/ref-manual/figures/image-generation.png new file mode 100644 index 0000000000..ab962580c3 Binary files /dev/null and b/documentation/ref-manual/figures/image-generation.png differ diff --git a/documentation/ref-manual/figures/images.png b/documentation/ref-manual/figures/images.png new file mode 100644 index 0000000000..d99eac1fbf Binary files /dev/null and b/documentation/ref-manual/figures/images.png differ diff --git a/documentation/ref-manual/figures/layer-input.png b/documentation/ref-manual/figures/layer-input.png new file mode 100644 index 0000000000..0a4f2e74f3 Binary files /dev/null and b/documentation/ref-manual/figures/layer-input.png differ diff --git a/documentation/ref-manual/figures/package-feeds.png b/documentation/ref-manual/figures/package-feeds.png new file mode 100644 index 0000000000..4bc311f3d6 Binary files /dev/null and b/documentation/ref-manual/figures/package-feeds.png differ diff --git a/documentation/ref-manual/figures/patching.png b/documentation/ref-manual/figures/patching.png new file mode 100644 index 0000000000..8ecd018502 Binary files /dev/null and b/documentation/ref-manual/figures/patching.png differ diff --git a/documentation/ref-manual/figures/poky-title.png b/documentation/ref-manual/figures/poky-title.png new file mode 100644 index 0000000000..2893d84620 Binary files /dev/null and b/documentation/ref-manual/figures/poky-title.png differ diff --git a/documentation/ref-manual/figures/sdk-generation.png b/documentation/ref-manual/figures/sdk-generation.png new file mode 100644 index 0000000000..c37e2748ca Binary files /dev/null and b/documentation/ref-manual/figures/sdk-generation.png differ diff --git a/documentation/ref-manual/figures/sdk.png b/documentation/ref-manual/figures/sdk.png new file mode 100644 index 0000000000..a539cc52f0 Binary files /dev/null and b/documentation/ref-manual/figures/sdk.png differ diff --git a/documentation/ref-manual/figures/source-fetching.png b/documentation/ref-manual/figures/source-fetching.png new file mode 100644 index 0000000000..26aefb50c2 Binary files /dev/null and b/documentation/ref-manual/figures/source-fetching.png differ diff --git a/documentation/ref-manual/figures/source-input.png b/documentation/ref-manual/figures/source-input.png new file mode 100644 index 0000000000..f7515058ef Binary files /dev/null and b/documentation/ref-manual/figures/source-input.png differ diff --git a/documentation/ref-manual/figures/user-configuration.png b/documentation/ref-manual/figures/user-configuration.png new file mode 100644 index 0000000000..f2b3f8e7fe Binary files /dev/null and b/documentation/ref-manual/figures/user-configuration.png differ diff --git a/documentation/ref-manual/figures/yocto-environment-ref.png b/documentation/ref-manual/figures/yocto-environment-ref.png new file mode 100644 index 0000000000..650c6c8030 Binary files /dev/null and b/documentation/ref-manual/figures/yocto-environment-ref.png differ diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml new file mode 100644 index 0000000000..19e9895ee6 --- /dev/null +++ b/documentation/ref-manual/introduction.xml @@ -0,0 +1,572 @@ + %poky; ] > + + +Introduction + +
+ Introduction + + + 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 + Yocto Project Quick Start. + For task-based information using the Yocto Project, see the + Yocto Project Development Manual + and the Yocto Project Linux Kernel Development Manual. + For Board Support Package (BSP) structure information, see the + Yocto Project Board Support Package (BSP) Developer's Guide. + You can find information on tracing and profiling in the + Yocto Project Profiling and Tracing Manual. + For information on BitBake, which is the task execution tool the + OpenEmbedded build system is based on, see the + BitBake User Manual. + Finally, you can also find lots of Yocto Project information on the + Yocto Project website. + +
+ +
+ Documentation Overview + + This reference manual consists of the following: + + + Using the Yocto Project: + Provides an overview of the components that make up the Yocto Project + followed by information about debugging images created in the Yocto Project. + + + A Closer Look at the Yocto Project Development Environment: + Provides a more detailed look at the Yocto Project development + environment within the context of development. + + + Technical Details: + Describes fundamental Yocto Project components as well as an explanation + behind how the Yocto Project uses shared state (sstate) cache to speed build time. + + + Migrating to a Newer Yocto Project Release: + Describes release-specific information that helps you move from + one Yocto Project Release to another. + + + Directory Structure: + Describes the + Source Directory created + either by unpacking a released Yocto Project tarball on your host development system, + or by cloning the upstream + Poky Git repository. + + + Classes: + Describes the classes used in the Yocto Project. + + Tasks: + Describes the tasks defined by the OpenEmbedded build system. + + + QA Error and Warning Messages: + Lists and describes QA warning and error messages. + + + Images: + Describes the standard images that the Yocto Project supports. + + + Features: + Describes mechanisms for creating distribution, machine, and image + features during the build process using the OpenEmbedded build system. + + Variables Glossary: + Presents most variables used by the OpenEmbedded build system, which + uses BitBake. + Entries describe the function of the variable and how to apply them. + + + Variable Context: + Provides variable locality or context. + + FAQ: + Provides answers for commonly asked questions in the Yocto Project + development environment. + + Contributing to the Yocto Project: + Provides guidance on how you can contribute back to the Yocto + Project. + + +
+ + +
+System Requirements + + For general Yocto Project system requirements, see the + "What You Need and How You Get It" section + in the Yocto Project Quick Start. + The remainder of this section provides details on system requirements + not covered in the Yocto Project Quick Start. + + +
+ Supported Linux Distributions + + + Currently, the Yocto Project is supported on the following + distributions: + + + Yocto Project releases are tested against the stable Linux + distributions in the following list. + The Yocto Project should work on other distributions but + validation is not performed against them. + + + + In particular, the Yocto Project does not support + and currently has no plans to support + rolling-releases or development distributions due to their + constantly changing nature. + We welcome patches and bug reports, but keep in mind that + our priority is on the supported platforms listed below. + + + + If you encounter problems, please go to + Yocto Project Bugzilla + and submit a bug. + We are interested in hearing about your experience. + + + + + Ubuntu 12.04 (LTS) + Ubuntu 13.10 + Ubuntu 14.04 (LTS) + + Fedora release 19 (Schrödinger's Cat) + Fedora release 20 (Heisenbug) + + CentOS release 6.4 + CentOS release 6.5 + + Debian GNU/Linux 7.0 (Wheezy) + Debian GNU/Linux 7.1 (Wheezy) + Debian GNU/Linux 7.2 (Wheezy) + Debian GNU/Linux 7.3 (Wheezy) + Debian GNU/Linux 7.4 (Wheezy) + Debian GNU/Linux 7.5 (Wheezy) + Debian GNU/Linux 7.6 (Wheezy) + + openSUSE 12.2 + openSUSE 12.3 + openSUSE 13.1 + + + + + While the Yocto Project Team attempts to ensure all Yocto Project + releases are one hundred percent compatible with each officially + 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 + Hob. + +
+ +
+ Required Packages for the Host Development System + + + The list of packages you need on the host development system can + be large when covering all build scenarios using the Yocto Project. + This section provides required packages according to + Linux distribution and function. + + +
+ Ubuntu and Debian + + + The following list shows the required packages by function + given a supported Ubuntu or Debian Linux distribution: + + Essentials: + Packages needed to build an image on a headless + system: + + $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo apt-get install libsdl1.2-dev xterm + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto + + ADT Installer Extras: + Packages needed if you are going to be using the + Application Development Toolkit (ADT) Installer: + + $ sudo apt-get install autoconf automake libtool libglib2.0-dev + + + +
+ +
+ Fedora Packages + + + The following list shows the required packages by function + given a supported Fedora Linux distribution: + + Essentials: + Packages needed to build an image for a headless + system: + + $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo yum install SDL-devel xterm perl-Thread-Queue + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt dblatex xmlto + + ADT Installer Extras: + Packages needed if you are going to be using the + Application Development Toolkit (ADT) Installer: + + $ sudo yum install autoconf automake libtool glib2-devel + + + +
+ +
+ openSUSE Packages + + + The following list shows the required packages by function + given a supported openSUSE Linux distribution: + + Essentials: + Packages needed to build an image for a headless + system: + + $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo zypper install libSDL-devel xterm + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo zypper install make fop xsltproc dblatex xmlto + + ADT Installer Extras: + Packages needed if you are going to be using the + Application Development Toolkit (ADT) Installer: + + $ sudo zypper install autoconf automake libtool glib2-devel + + + +
+ +
+ CentOS Packages + + + The following list shows the required packages by function + given a supported CentOS Linux distribution: + + 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 + "Required Git, Tar, and Python Versions" + section. + + + Essentials: + Packages needed to build an image for a headless + system: + + $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo yum install SDL-devel xterm + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt dblatex xmlto + + ADT Installer Extras: + Packages needed if you are going to be using the + Application Development Toolkit (ADT) Installer: + + $ sudo yum install autoconf automake libtool glib2-devel + + + +
+
+ +
+ Required Git, tar, and Python Versions + + + In order to use the build system, your host development system + must meet the following version requirements for Git, tar, and + Python: + + Git 1.7.8 or greater + tar 1.24 or greater + Python 2.7.3 or greater not including + Python 3.x, which is not supported. + + + + + If your host development system does not meet all these requirements, + you can resolve this by installing a buildtools + tarball that contains these tools. + You can get the tarball one of two ways: download a pre-built + tarball or use BitBake to build the tarball. + + +
+ Downloading a Pre-Built <filename>buildtools</filename> Tarball + + + Downloading and running a pre-built buildtools installer is + the easiest of the two methods by which you can get these tools: + + + Locate and download the *.sh at + . + + + Execute the installation script. + Here is an example: + + $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh + + During execution, a prompt appears that allows you to + choose the installation directory. + For example, you could choose the following: + + /home/your-username/buildtools + + + + Source the tools environment setup script by using a + command like the following: + + $ source /home/your-username/buildtools/environment-setup-i586-poky-linux + + Of course, you need to supply your installation directory and be + sure to use the right file (i.e. i585 or x86-64). + + + After you have sourced the setup script, + the tools are added to PATH + and any other environment variables required to run the + tools are initialized. + The results are working versions versions of Git, tar, + Python and chrpath. + + + +
+ +
+ Building Your Own <filename>buildtools</filename> Tarball + + + Building and running your own buildtools installer applies + only when you have a build host that can already run BitBake. + In this case, you use that machine to build the + .sh file and then + take steps to transfer and run it on a + machine that does not meet the minimal Git, tar, and Python + requirements. + + + + Here are the steps to take to build and run your own + buildtools installer: + + + On the machine that is able to run BitBake, + be sure you have set up your build environment with + the setup script + (&OE_INIT_FILE; + or + oe-init-build-env-memres). + + + Run the BitBake command to build the tarball: + + $ bitbake buildtools-tarball + + + The + SDKMACHINE + variable in your local.conf file + determines whether you build tools for a 32-bit + or 64-bit system. + + Once the build completes, you can find the + .sh file that installs + the tools in the tmp/deploy/sdk + subdirectory of the + Build Directory. + The installer file has the string "buildtools" + in the name. + + + Transfer the .sh file from the + build host to the machine that does not meet the + Git, tar, or Python requirements. + + + On the machine that does not meet the requirements, + run the .sh file + to install the tools. + Here is an example: + + $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh + + During execution, a prompt appears that allows you to + choose the installation directory. + For example, you could choose the following: + + /home/your-username/buildtools + + + + Source the tools environment setup script by using a + command like the following: + + $ source /home/your-username/buildtools/environment-setup-i586-poky-linux + + Of course, you need to supply your installation directory and be + sure to use the right file (i.e. i585 or x86-64). + + + After you have sourced the setup script, + the tools are added to PATH + and any other environment variables required to run the + tools are initialized. + The results are working versions versions of Git, tar, + Python and chrpath. + + + +
+
+
+ +
+ Obtaining the Yocto Project + + The Yocto Project development team makes the Yocto Project available through a number + of methods: + + Source Repositories: + Working from a copy of the upstream + poky repository is the + preferred method for obtaining and using a Yocto Project + release. + You can view the Yocto Project Source Repositories at + . + In particular, you can find the + poky repository at + . + + Releases: Stable, tested + releases are available as tarballs through + . + Nightly Builds: These + tarball releases are available at + . + These builds include Yocto Project releases, meta-toolchain + tarball installation scripts, and experimental builds. + + Yocto Project Website: You can + find tarball releases of the Yocto Project and supported BSPs + at the + Yocto Project website. + Along with these downloads, you can find lots of other + information at this site. + + + +
+ +
+ Development Checkouts + + Development using the Yocto Project requires a local + Source Directory. + You can set up the Source Directory by cloning a copy of the upstream + poky Git repository. + For information on how to do this, see the + "Getting Set Up" + section in the Yocto Project Development Manual. + +
+ +
+ diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml new file mode 100644 index 0000000000..d072ecfa0e --- /dev/null +++ b/documentation/ref-manual/migration.xml @@ -0,0 +1,2019 @@ + %poky; ] > + + +Migrating to a Newer Yocto Project Release + + + This chapter provides information you can use to migrate work to a + newer Yocto Project release. You can find the same information in the + release notes for a given release. + + +
+ General Migration Considerations + + + Some considerations are not tied to a specific Yocto Project + release. + This section presents information you should consider when + migrating to any new Yocto Project release. + + Dealing with Customized Recipes: + Issues could arise if you take older recipes that contain + customizations and simply copy them forward expecting them + to work after you migrate to new Yocto Project metadata. + For example, suppose you have a recipe in your layer that is + a customized version of a core recipe copied from the earlier + release, rather than through the use of an append file. + When you migrate to a newer version of Yocto Project, the + metadata (e.g. perhaps an include file used by the recipe) + could have changed in a way that would break the build. + Say, for example, a function is removed from an include file + and the customized recipe tries to call that function. + + + You could "forward-port" all your customizations in your + recipe so that everything works for the new release. + However, this is not the optimal solution as you would have + to repeat this process with each new release if changes + occur that give rise to problems. + + The better solution (where practical) is to use append + files (*.bbappend) to capture any + customizations you want to make to a recipe. + Doing so, isolates your changes from the main recipe making + them much more manageable. + However, sometimes it is not practical to use an append + file. + A good example of this is when introducing a newer or older + version of a recipe in another layer. + + Updating Append Files: + Since append files generally only contain your customizations, + they often do not need to be adjusted for new releases. + However, if the .bbappend file is + specific to a particular version of the recipe (i.e. its + name does not use the % wildcard) and the version of the + recipe to which it is appending has changed, then you will + at a minimum need to rename the append file to match the + name of the recipe file. + A mismatch between an append file and its corresponding + recipe file (.bb) will + trigger an error during parsing. + Depending on the type of customization the append file + applies, other incompatibilities might occur when you + upgrade. + For example, if your append file applies a patch and the + recipe to which it is appending is updated to a newer + version, the patch might no longer apply. + If this is the case and assuming the patch is still needed, + you must modify the patch file so that it does apply. + + + +
+ +
+ Moving to the Yocto Project 1.3 Release + + + This section provides migration information for moving to the + Yocto Project 1.3 Release from the prior release. + + +
+ Local Configuration + + + Differences include changes for + SSTATE_MIRRORS + and bblayers.conf. + + +
+ SSTATE_MIRRORS + + + The shared state cache (sstate-cache), as pointed to by + SSTATE_DIR, 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 + 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 + SSTATE_MIRRORS, + you need to append "PATH" to the end of the mirror URL so that + the path used by BitBake before the mirror substitution is + appended to the path used to access the mirror. + Here is an example: + + SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" + + +
+ +
+ bblayers.conf + + + The meta-yocto layer consists of two parts + that correspond to the Poky reference distribution and the + reference hardware Board Support Packages (BSPs), respectively: + meta-yocto and + meta-yocto-bsp. + When running BitBake or Hob for the first time after upgrading, + your conf/bblayers.conf file will be + updated to handle this change and you will be asked to + re-run or restart for the changes to take effect. + +
+
+ +
+ Recipes + + + Differences include changes for the following: + + Python function whitespace + proto= in SRC_URI + nativesdk + Task recipes + IMAGE_FEATURES + Removed recipes + + + +
+ Python Function Whitespace + + + All Python functions must now use four spaces for indentation. + Previously, an inconsistent mix of spaces and tabs existed, + which made extending these functions using + _append or _prepend + complicated given that Python treats whitespace as + syntactically significant. + If you are defining or extending any Python functions (e.g. + populate_packages, do_unpack, + do_patch and so forth) in custom recipes + or classes, you need to ensure you are using consistent + four-space indentation. + +
+ +
+ proto= in SRC_URI + + + Any use of proto= in + SRC_URI + needs to be changed to protocol=. + In particular, this applies to the following URIs: + + svn:// + bzr:// + hg:// + osc:// + + Other URIs were already using protocol=. + This change improves consistency. + +
+ +
+ nativesdk + + + The suffix nativesdk is now implemented + as a prefix, which simplifies a lot of the packaging code for + nativesdk recipes. + All custom nativesdk recipes and any + references need to be updated to use + nativesdk-* instead of + *-nativesdk. + +
+ +
+ Task Recipes + + + "Task" recipes are now known as "Package groups" and have + been renamed from task-*.bb to + packagegroup-*.bb. + Existing references to the previous task-* + names should work in most cases as there is an automatic + upgrade path for most packages. + However, you should update references in your own recipes and + configurations as they could be removed in future releases. + You should also rename any custom task-* + recipes to packagegroup-*, and change + them to inherit packagegroup instead of + task, as well as taking the opportunity + to remove anything now handled by + packagegroup.bbclass, such as providing + -dev and -dbg + packages, setting + LIC_FILES_CHKSUM, + and so forth. + See the + "packagegroup.bbclass" + section for further details. + +
+ +
+ IMAGE_FEATURES + + + Image recipes that previously included "apps-console-core" + in IMAGE_FEATURES + should now include "splash" instead to enable the boot-up + splash screen. + Retaining "apps-console-core" will still include the splash + screen but generates a warning. + The "apps-x11-core" and "apps-x11-games" + IMAGE_FEATURES features have been removed. + +
+ +
+ Removed Recipes + + + The following recipes have been removed. + For most of them, it is unlikely that you would have any + references to them in your own + Metadata. + However, you should check your metadata against this list to be sure: + + libx11-trim: + Replaced by libx11, which has a negligible + size difference with modern Xorg. + xserver-xorg-lite: + Use xserver-xorg, which has a negligible + size difference when DRI and GLX modules are not installed. + xserver-kdrive: + Effectively unmaintained for many years. + mesa-xlib: + No longer serves any purpose. + galago: + Replaced by telepathy. + gail: + Functionality was integrated into GTK+ 2.13. + eggdbus: + No longer needed. + gcc-*-intermediate: + The build has been restructured to avoid the need for + this step. + libgsmd: + Unmaintained for many years. + Functionality now provided by + ofono instead. + contacts, dates, tasks, eds-tools: + Largely unmaintained PIM application suite. + It has been moved to meta-gnome + in meta-openembedded. + + In addition to the previously listed changes, the + meta-demoapps directory has also been removed + because the recipes in it were not being maintained and many + had become obsolete or broken. + Additionally, these recipes were not parsed in the default configuration. + Many of these recipes are already provided in an updated and + maintained form within the OpenEmbedded community layers such as + meta-oe and meta-gnome. + For the remainder, you can now find them in the + meta-extras repository, which is in the + Yocto Project + Source Repositories. + +
+
+ +
+ Linux Kernel Naming + + + The naming scheme for kernel output binaries has been changed to + now include + PE as part of the + filename: + + KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" + + + + + Because the PE variable is not set by default, + these binary files could result with names that include two dash + characters. + Here is an example: + + bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin + + +
+
+ +
+ Moving to the Yocto Project 1.4 Release + + + This section provides migration information for moving to the + Yocto Project 1.4 Release from the prior release. + + +
+ BitBake + + + Differences include the following: + + Comment Continuation: + If a comment ends with a line continuation (\) character, + then the next line must also be a comment. + Any instance where this is not the case, now triggers + a warning. + You must either remove the continuation character, or be + sure the next line is a comment. + + Package Name Overrides: + The runtime package specific variables + RDEPENDS, + RRECOMMENDS, + RSUGGESTS, + RPROVIDES, + RCONFLICTS, + RREPLACES, + FILES, + ALLOW_EMPTY, + and the pre, post, install, and uninstall script functions + pkg_preinst, + pkg_postinst, + pkg_prerm, and + pkg_postrm should always have a + package name override. + For example, use RDEPENDS_${PN} for + the main package instead of RDEPENDS. + BitBake uses more strict checks when it parses recipes. + + + +
+ +
+ Build Behavior + + + Differences include the following: + + Shared State Code: + The shared state code has been optimized to avoid running + unnecessary tasks. + For example, the following no longer populates the target + sysroot since that is not necessary: + + $ bitbake -c rootfs some-image + + Instead, the system just needs to extract the output + package contents, re-create the packages, and construct + the root filesystem. + This change is unlikely to cause any problems unless + you have missing declared dependencies. + + Scanning Directory Names: + When scanning for files in + SRC_URI, + the build system now uses + FILESOVERRIDES + instead of OVERRIDES + for the directory names. + In general, the values previously in + OVERRIDES are now in + FILESOVERRIDES as well. + However, if you relied upon an additional value + you previously added to OVERRIDES, + you might now need to add it to + FILESOVERRIDES unless you are already + adding it through the + MACHINEOVERRIDES + or DISTROOVERRIDES + variables, as appropriate. + For more related changes, see the + "Variables" + section. + + + +
+ + +
+ Proxies and Fetching Source + + + A new oe-git-proxy script has been added to + replace previous methods of handling proxies and fetching source + from Git. + See the meta-yocto/conf/site.conf.sample file + for information on how to use this script. + +
+ +
+ Custom Interfaces File (netbase change) + + + If you have created your own custom + etc/network/interfaces file by creating + an append file for the netbase recipe, + you now need to create an append file for the + init-ifupdown recipe instead, which you can + find in the + Source Directory + at meta/recipes-core/init-ifupdown. + For information on how to use append files, see the + "Using .bbappend Files" + in the Yocto Project Development Manual. + +
+ +
+ Remote Debugging + + + Support for remote debugging with the Eclipse IDE is now + separated into an image feature + (eclipse-debug) that corresponds to the + packagegroup-core-eclipse-debug package group. + Previously, the debugging feature was included through the + tools-debug image feature, which corresponds + to the packagegroup-core-tools-debug + package group. + +
+ +
+ Variables + + + The following variables have changed: + + SANITY_TESTED_DISTROS: + This variable now uses a distribution ID, which is composed + of the host distributor ID followed by the release. + Previously, + SANITY_TESTED_DISTROS + was composed of the description field. + For example, "Ubuntu 12.10" becomes "Ubuntu-12.10". + You do not need to worry about this change if you are not + specifically setting this variable, or if you are + specifically setting it to "". + + SRC_URI: + The ${PN}, + ${PF}, + ${P}, + and FILE_DIRNAME directories have been + dropped from the default value of the + FILESPATH + variable, which is used as the search path for finding files + referred to in + SRC_URI. + If you have a recipe that relied upon these directories, + which would be unusual, then you will need to add the + appropriate paths within the recipe or, alternatively, + rearrange the files. + The most common locations are still covered by + ${BP}, ${BPN}, + and "files", which all remain in the default value of + FILESPATH. + + + +
+ +
+ Target Package Management with RPM + + + If runtime package management is enabled and the RPM backend + is selected, Smart is now installed for package download, dependency + resolution, and upgrades instead of Zypper. + For more information on how to use Smart, run the following command + on the target: + + smart --help + + +
+ +
+ Recipes Moved + + + The following recipes were moved from their previous locations + because they are no longer used by anything in + the OpenEmbedded-Core: + + clutter-box2d: + Now resides in the meta-oe layer. + + evolution-data-server: + Now resides in the meta-gnome layer. + + gthumb: + Now resides in the meta-gnome layer. + + gtkhtml2: + Now resides in the meta-oe layer. + + gupnp: + Now resides in the meta-multimedia layer. + + gypsy: + Now resides in the meta-oe layer. + + libcanberra: + Now resides in the meta-gnome layer. + + libgdata: + Now resides in the meta-gnome layer. + + libmusicbrainz: + Now resides in the meta-multimedia layer. + + metacity: + Now resides in the meta-gnome layer. + + polkit: + Now resides in the meta-oe layer. + + zeroconf: + Now resides in the meta-networking layer. + + + +
+ +
+ Removals and Renames + + + The following list shows what has been removed or renamed: + + evieext: + Removed because it has been removed from + xserver since 2008. + + Gtk+ DirectFB: + Removed support because upstream Gtk+ no longer supports it + as of version 2.18. + + libxfontcache / xfontcacheproto: + Removed because they were removed from the Xorg server in 2008. + + libxp / libxprintapputil / libxprintutil / printproto: + Removed because the XPrint server was removed from + Xorg in 2008. + + libxtrap / xtrapproto: + Removed because their functionality was broken upstream. + + linux-yocto 3.0 kernel: + Removed with linux-yocto 3.8 kernel being added. + The linux-yocto 3.2 and linux-yocto 3.4 kernels remain + as part of the release. + + lsbsetup: + Removed with functionality now provided by + lsbtest. + + matchbox-stroke: + Removed because it was never more than a proof-of-concept. + + matchbox-wm-2 / matchbox-theme-sato-2: + Removed because they are not maintained. + However, matchbox-wm and + matchbox-theme-sato are still + provided. + + mesa-dri: + Renamed to mesa. + + mesa-xlib: + Removed because it was no longer useful. + + mutter: + Removed because nothing ever uses it and the recipe is + very old. + + orinoco-conf: + Removed because it has become obsolete. + + update-modules: + Removed because it is no longer used. + The kernel module postinstall and + postrm scripts can now do the same + task without the use of this script. + + web: + Removed because it is not maintained. Superseded by + web-webkit. + + xf86bigfontproto: + Removed because upstream it has been disabled by default + since 2007. + Nothing uses xf86bigfontproto. + + xf86rushproto: + Removed because its dependency in + xserver was spurious and it was + removed in 2005. + + zypper / libzypp / sat-solver: + Removed and been functionally replaced with Smart + (python-smartpm) when RPM packaging + is used and package management is enabled on the target. + + + +
+
+ +
+ Moving to the Yocto Project 1.5 Release + + + This section provides migration information for moving to the + Yocto Project 1.5 Release from the prior release. + + +
+ Host Dependency Changes + + + The OpenEmbedded build system now has some additional requirements + on the host system: + + Python 2.7.3+ + Tar 1.24+ + Git 1.7.8+ + Patched version of Make if you are using + 3.82. + Most distributions that provide Make 3.82 use the patched + version. + + If the Linux distribution you are using on your build host + does not provide packages for these, you can install and use + the Buildtools tarball, which provides an SDK-like environment + containing them. + + + + For more information on this requirement, see the + "Required Git, tar, and Python Versions" + section. + +
+ +
+ <filename>atom-pc</filename> Board Support Package (BSP) + + + The atom-pc hardware reference BSP has been + replaced by a genericx86 BSP. + This BSP is not necessarily guaranteed to work on all x86 + hardware, but it will run on a wider range of systems than the + atom-pc did. + + Additionally, a genericx86-64 BSP has + been added for 64-bit Atom systems. + + +
+ +
+ BitBake + + + The following changes have been made that relate to BitBake: + + + BitBake now supports a _remove + operator. + The addition of this operator means you will have to + rename any items in recipe space (functions, variables) + whose names currently contain + _remove_ or end with + _remove to avoid unexpected behavior. + + + BitBake's global method pool has been removed. + This method is not particularly useful and led to clashes + between recipes containing functions that had the + same name. + + The "none" server backend has been removed. + The "process" server backend has been serving well as the + default for a long time now. + + The bitbake-runtask script has been + removed. + + ${P} + and + ${PF} + are no longer added to + PROVIDES + by default in bitbake.conf. + These version-specific PROVIDES + items were seldom used. + Attempting to use them could result in two versions being + built simultaneously rather than just one version due to + the way BitBake resolves dependencies. + + +
+ +
+ QA Warnings + + + The following changes have been made to the package QA checks: + + + If you have customized + ERROR_QA + or WARN_QA + values in your configuration, check that they contain all of + the issues that you wish to be reported. + Previous Yocto Project versions contained a bug that meant + that any item not mentioned in ERROR_QA + or WARN_QA would be treated as a + warning. + Consequently, several important items were not already in + the default value of WARN_QA. + All of the possible QA checks are now documented in the + "insane.bbclass" + section. + + An additional QA check has been added to check if + /usr/share/info/dir is being installed. + Your recipe should delete this file within + do_install + if "make install" is installing it. + + + If you are using the buildhistory class, the check for the + package version going backwards is now controlled using a + standard QA check. + Thus, if you have customized your + ERROR_QA or + WARN_QA values and still wish to have + this check performed, you should add + "version-going-backwards" to your value for one or the + other variables depending on how you wish it to be handled. + See the documented QA checks in the + "insane.bbclass" + section. + + + +
+ +
+ Directory Layout Changes + + + The following directory changes exist: + + + Output SDK installer files are now named to include the + image name and tuning architecture through the + SDK_NAME + variable. + + Images and related files are now installed into a directory + that is specific to the machine, instead of a parent + directory containing output files for multiple machines. + The + DEPLOY_DIR_IMAGE + variable continues to point to the directory containing + images for the current + MACHINE + and should be used anywhere there is a need to refer to + this directory. + The runqemu script now uses this + variable to find images and kernel binaries and will use + BitBake to determine the directory. + Alternatively, you can set the + DEPLOY_DIR_IMAGE variable in the + external environment. + + When buildhistory is enabled, its output is now written + under the + Build Directory + rather than + TMPDIR. + Doing so makes it easier to delete + TMPDIR and preserve the build history. + Additionally, data for produced SDKs is now split by + IMAGE_NAME. + + + The pkgdata directory produced as + part of the packaging process has been collapsed into a + single machine-specific directory. + This directory is located under + sysroots and uses a machine-specific + name (i.e. + tmp/sysroots/machine/pkgdata). + + + +
+ +
+ Shortened Git <filename>SRCREV</filename> Values + + + BitBake will now shorten revisions from Git repositories from the + normal 40 characters down to 10 characters within + SRCPV + for improved usability in path and file names. + This change should be safe within contexts where these revisions + are used because the chances of spatially close collisions + is very low. + Distant collisions are not a major issue in the way + the values are used. + +
+ +
+ <filename>IMAGE_FEATURES</filename> + + + The following changes have been made that relate to + IMAGE_FEATURES: + + + The value of + IMAGE_FEATURES + is now validated to ensure invalid feature items are not + added. + Some users mistakenly add package names to this variable + instead of using + IMAGE_INSTALL + in order to have the package added to the image, which does + not work. + This change is intended to catch those kinds of situations. + Valid IMAGE_FEATURES are drawn from + PACKAGE_GROUP + definitions, + COMPLEMENTARY_GLOB + and a new "validitems" varflag on + IMAGE_FEATURES. + The "validitems" varflag change allows additional features + to be added if they are not provided using the previous + two mechanisms. + + + The previously deprecated "apps-console-core" + IMAGE_FEATURES item is no longer + supported. + Add "splash" to IMAGE_FEATURES if you + wish to have the splash screen enabled, since this is + all that apps-console-core was doing. + + +
+ +
+ <filename>/run</filename> + + + The /run directory from the Filesystem + Hierarchy Standard 3.0 has been introduced. + You can find some of the implications for this change + here. + The change also means that recipes that install files to + /var/run must be changed. + You can find a guide on how to make these changes + here. + +
+ +
+ Removal of Package Manager Database Within Image Recipes + + + The image core-image-minimal no longer adds + remove_packaging_data_files to + ROOTFS_POSTPROCESS_COMMAND. + This addition is now handled automatically when "package-management" + is not in + IMAGE_FEATURES. + If you have custom image recipes that make this addition, + you should remove the lines, as they are not needed and might + interfere with correct operation of postinstall scripts. + +
+ +
+ Images Now Rebuild Only on Changes Instead of Every Time + + + The + do_rootfs + and other related image + construction tasks are no longer marked as "nostamp". + Consequently, they will only be re-executed when their inputs have + changed. + Previous versions of the OpenEmbedded build system always rebuilt + the image when requested rather when necessary. + +
+ +
+ Task Recipes + + + The previously deprecated task.bbclass has + now been dropped. + For recipes that previously inherited from this class, you should + rename them from task-* to + packagegroup-* and inherit packagegroup + instead. + + + + For more information, see the + "packagegroup.bbclass" + section. + +
+ +
+ BusyBox + + + By default, we now split BusyBox into two binaries: + one that is suid root for those components that need it, and + another for the rest of the components. + Splitting BusyBox allows for optimization that eliminates the + tinylogin recipe as recommended by upstream. + You can disable this split by setting + BUSYBOX_SPLIT_SUID + to "0". + +
+ +
+ Automated Image Testing + + + A new automated image testing framework has been added + through the + testimage*.bbclass + class. + This framework replaces the older + imagetest-qemu framework. + + + + You can learn more about performing automated image tests in the + "Performing Automated Runtime Testing" + section. + +
+ +
+ Build History + + + Following are changes to Build History: + + + Installed package sizes: + installed-package-sizes.txt for an + image now records the size of the files installed by each + package instead of the size of each compressed package + archive file. + + The dependency graphs (depends*.dot) + now use the actual package names instead of replacing + dashes, dots and plus signs with underscores. + + + The buildhistory-diff and + buildhistory-collect-srcrevs + utilities have improved command-line handling. + Use the ‐‐help option for + each utility for more information on the new syntax. + + + For more information on Build History, see the + "Maintaining Build Output Quality" + section. + +
+ +
+ <filename>udev</filename> + + + Following are changes to udev: + + + udev no longer brings in + udev-extraconf automatically + through + RRECOMMENDS, + since this was originally intended to be optional. + If you need the extra rules, then add + udev-extraconf to your image. + + + udev no longer brings in + pciutils-ids or + usbutils-ids through + RRECOMMENDS. + These are not needed by udev itself + and removing them saves around 350KB. + + + +
+ +
+ Removed and Renamed Recipes + + + + The linux-yocto 3.2 kernel has been + removed. + + libtool-nativesdk has been renamed to + nativesdk-libtool. + + tinylogin has been removed. + It has been replaced by a suid portion of Busybox. + See the + "BusyBox" section + for more information. + + external-python-tarball has been renamed + to buildtools-tarball. + + + web-webkit has been removed. + It has been functionally replaced by + midori. + + imake has been removed. + It is no longer needed by any other recipe. + + + transfig-native has been removed. + It is no longer needed by any other recipe. + + + anjuta-remote-run has been removed. + Anjuta IDE integration has not been officially supported for + several releases. + +
+ +
+ Other Changes + + + Following is a list of short entries describing other changes: + + + run-postinsts: Make this generic. + + + base-files: Remove the unnecessary + media/xxx directories. + + + alsa-state: Provide an empty + asound.conf by default. + + + classes/image: Ensure + BAD_RECOMMENDATIONS + supports pre-renamed package names. + + classes/rootfs_rpm: Implement + BAD_RECOMMENDATIONS + for RPM. + + systemd: Remove + systemd_unitdir if + systemd is not in + DISTRO_FEATURES. + + + systemd: Remove + init.d dir if + systemd unit file is present and + sysvinit is not a distro feature. + + + libpam: Deny all services for the + OTHER entries. + + + image.bbclass: Move + runtime_mapping_rename to avoid + conflict with multilib. + See + YOCTO #4993 + in Bugzilla for more information. + + + linux-dtb: Use kernel build system + to generate the dtb files. + + + kern-tools: Switch from guilt to + new kgit-s2q tool. + + + +
+
+ +
+ Moving to the Yocto Project 1.6 Release + + + This section provides migration information for moving to the + Yocto Project 1.6 Release from the prior release. + + + +
+ <filename>archiver</filename> Class + + + The + archiver + class has been rewritten and its configuration has been simplified. + For more details on the source archiver, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" + section in the Yocto Project Development Manual. + +
+ +
+ Packaging Changes + + + The following packaging changes have been made: + + + The binutils recipe no longer produces + a binutils-symlinks package. + update-alternatives is now used to + handle the preferred binutils + variant on the target instead. + + + The tc (traffic control) utilities have been split out of + the main iproute2 package and put + into the iproute2-tc package. + + + The gtk-engines schemas have been + moved to a dedicated + gtk-engines-schemas package. + + + The armv7a with thumb package + architecture suffix has changed. + The suffix for these packages with the thumb + optimization enabled is "t2" as it should be. + Use of this suffix was not the case in the 1.5 release. + Architecture names will change within package feeds as a + result. + + + +
+ +
+ BitBake + + + The following changes have been made to + BitBake. + + +
+ Matching Branch Requirement for Git Fetching + + + When fetching source from a Git repository using + SRC_URI, + BitBake will now validate the + SRCREV + value against the branch. + You can specify the branch using the following form: + + SRC_URI = "git://server.name/repository;branch=branchname" + + If you do not specify a branch, BitBake looks + in the default "master" branch. + + + + Alternatively, if you need to bypass this check (e.g. + if you are fetching a revision corresponding to a tag that + is not on any branch), you can add ";nobranch=1" to + the end of the URL within SRC_URI. + +
+ +
+ Python Definition substitutions + + + BitBake had some previously deprecated Python definitions + within its bb module removed. + You should use their sub-module counterparts instead: + + bb.MalformedUrl: + Use bb.fetch.MalformedUrl. + + bb.fetch.encodeurl: + Use bb.fetch.encodeurl. + + bb.decodeurl: + Use bb.fetch.decodeurl + + bb.mkdirhier: + Use bb.utils.mkdirhier. + + bb.movefile: + Use bb.utils.movefile. + + bb.copyfile: + Use bb.utils.copyfile. + + bb.which: + Use bb.utils.which. + + bb.vercmp_string: + Use bb.utils.vercmp_string. + + bb.vercmp: + Use bb.utils.vercmp. + + + +
+ +
+ SVK Fetcher + + + The SVK fetcher has been removed from BitBake. + +
+ +
+ Console Output Error Redirection + + + The BitBake console UI will now output errors to + stderr instead of + stdout. + Consequently, if you are piping or redirecting the output of + bitbake to somewhere else, and you wish + to retain the errors, you will need to add + 2>&1 (or something similar) to the + end of your bitbake command line. + +
+ +
+ <filename>task-</filename><replaceable>taskname</replaceable> Overrides + + + task-taskname overrides have been + adjusted so that tasks whose names contain underscores have the + underscores replaced by hyphens for the override so that they + now function properly. + For example, the task override for + do_populate_sdk + is task-populate-sdk. + +
+
+ +
+ Changes to Variables + + + The following variables have changed. + For information on the OpenEmbedded build system variables, see the + "Variables Glossary" Chapter. + + +
+ <filename>TMPDIR</filename> + + + TMPDIR + can no longer be on an NFS mount. + NFS does not offer full POSIX locking and inode consistency + and can cause unexpected issues if used to store + TMPDIR. + + + + The check for this occurs on startup. + If TMPDIR is detected on an NFS mount, + an error occurs. + +
+ +
+ <filename>PRINC</filename> + + + The + PRINC + variable has been deprecated and triggers a warning if + detected during a build. + For + PR + increments on changes, use the PR service instead. + You can find out more about this service in the + "Working With a PR Service" + section in the Yocto Project Development Manual. + +
+ +
+ <filename>IMAGE_TYPES</filename> + + + The "sum.jffs2" option for + IMAGE_TYPES + has been replaced by the "jffs2.sum" option, which fits the + processing order. + +
+ +
+ <filename>COPY_LIC_MANIFEST</filename> + + + The + COPY_LIC_MANIFEST + variable must + now be set to "1" rather than any value in order to enable + it. + +
+ +
+ <filename>COPY_LIC_DIRS</filename> + + + The + COPY_LIC_DIRS + variable must + now be set to "1" rather than any value in order to enable + it. + +
+ +
+ <filename>PACKAGE_GROUP</filename> + + + The + PACKAGE_GROUP + variable has been renamed to + FEATURE_PACKAGES + to more accurately reflect its purpose. + You can still use PACKAGE_GROUP but + the OpenEmbedded build system produces a warning message when + it encounters the variable. + +
+
+ +
+ Directory Layout Changes + + + The meta-hob layer has been removed from + the top-level of the + Source Directory. + The contents of this layer are no longer needed by the Hob + user interface for building images and toolchains. + +
+ +
+ Package Test (ptest) + + + Package Tests (ptest) are built but not installed by default. + For information on using Package Tests, see the + "Setting up and running package test (ptest)" + section in the Yocto Project Development Manual. + For information on the ptest class, see the + "ptest.bbclass" + section. + +
+ +
+ Build Changes + + + Separate build and source directories have been enabled + by default for selected recipes where it is known to work + (a whitelist) and for all recipes that inherit the + cmake + class. + In future releases the + autotools + class will enable a separate build directory by default as + well. + Recipes building Autotools-based + software that fails to build with a separate build directory + should be changed to inherit from the + autotools-brokensep + class instead of the autotools class. + +
+ +
+ <filename>qemu-native</filename> + + + qemu-native now builds without + SDL-based graphical output support by default. + The following additional lines are needed in your + local.conf to enable it: + + PACKAGECONFIG_pn-qemu-native = "sdl" + ASSUME_PROVIDED += "libsdl-native" + + + The default local.conf + contains these statements. + Consequently, if you are building a headless system and using + a default local.conf file, you will need + comment these two lines out. + + +
+ +
+ <filename>core-image-basic</filename> + + + core-image-basic has been renamed to + core-image-full-cmdline. + + + + In addition to core-image-basic being renamed, + packagegroup-core-basic has been renamed to + packagegroup-core-full-cmdline to match. + +
+ +
+ Licensing + + + The top-level LICENSE file has been changed + to better describe the license of the various components of + OE-Core. + However, the licensing itself remains unchanged. + + + + Normally, this change would not cause any side-effects. + However, some recipes point to this file within + LIC_FILES_CHKSUM + (as ${COREBASE}/LICENSE) and thus the + accompanying checksum must be changed from + 3f40d7994397109285ec7b81fdeb3b58 to + 4d92cd373abda3937c2bc47fbc49d690. + A better alternative is to have + LIC_FILES_CHKSUM point to a file + describing the license that is distributed with the source + that the recipe is building, if possible, rather than pointing + to ${COREBASE}/LICENSE. + +
+ +
+ <filename>CFLAGS</filename> Options + + + The "-fpermissive" option has been removed from the default + CFLAGS + value. + You need to take action on individual recipes that fail when + building with this option. + You need to either patch the recipes to fix the issues reported by + the compiler, or you need to add "-fpermissive" to + CFLAGS in the recipes. + +
+ +
+ Custom Image Output Types + + + Custom image output types, as selected using + IMAGE_FSTYPES, + must declare their dependencies on other image types (if any) using + a new + IMAGE_TYPEDEP + variable. + +
+ +
+ Tasks + + + The do_package_write task has been removed. + The task is no longer needed. + +
+ +
+ <filename>update-alternative</filename> Provider + + + The default update-alternatives provider has + been changed from opkg to + opkg-utils. + This change resolves some troublesome circular dependencies. + The runtime package has also been renamed from + update-alternatives-cworth + to update-alternatives-opkg. + +
+ +
+ <filename>virtclass</filename> Overrides + + + The virtclass overrides are now deprecated. + Use the equivalent class overrides instead (e.g. + virtclass-native becomes + class-native.) + +
+ +
+ Removed and Renamed Recipes + + + The following recipes have been removed: + + packagegroup-toolset-native - + This recipe is largely unused. + + linux-yocto-3.8 - + Support for the Linux yocto 3.8 kernel has been dropped. + Support for the 3.10 and 3.14 kernels have been added + with the linux-yocto-3.10 and + linux-yocto-3.14 recipes. + + ocf-linux - + This recipe has been functionally replaced using + cryptodev-linux. + + genext2fs - + genext2fs is no longer used by the + build system and is unmaintained upstream. + + js - + This provided an ancient version of Mozilla's javascript + engine that is no longer needed. + + zaurusd - + The recipe has been moved to the + meta-handheld layer. + + eglibc 2.17 - + Replaced by the eglibc 2.19 + recipe. + + gcc 4.7.2 - + Replaced by the now stable + gcc 4.8.2. + + external-sourcery-toolchain - + this recipe is now maintained in the + meta-sourcery layer. + + linux-libc-headers-yocto 3.4+git - + Now using version 3.10 of the + linux-libc-headers by default. + + meta-toolchain-gmae - + This recipe is obsolete. + + packagegroup-core-sdk-gmae - + This recipe is obsolete. + + packagegroup-core-standalone-gmae-sdk-target - + This recipe is obsolete. + + + +
+ +
+ Removed Classes + + + The following classes have become obsolete and have been removed: + + module_strip + + pkg_metainfo + + pkg_distribute + + image-empty + + + +
+ +
+ Reference Board Support Packages (BSPs) + + + The following reference BSPs changes occurred: + + The BeagleBoard + (beagleboard) ARM reference hardware + has been replaced by the BeagleBone + (beaglebone) hardware. + + The RouterStation Pro + (routerstationpro) MIPS reference + hardware has been replaced by the EdgeRouter Lite + (edgerouter) hardware. + + + The previous reference BSPs for the + beagleboard and + routerstationpro machines are still available + in a new meta-yocto-bsp-old layer in the + Source Repositories + at + http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/. + +
+
+ +
+ Moving to the Yocto Project 1.7 Release + + + This section provides migration information for moving to the + Yocto Project 1.7 Release from the prior release. + + +
+ Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename> + + + The QEMU recipe now uses a number of + PACKAGECONFIG + options to enable various optional features. + The method used to set defaults for these options means that + existing + local.conf files will need to be be + modified to append to PACKAGECONFIG for + qemu-native and + nativesdk-qemu instead of setting it. + In other words, to enable graphical output for QEMU, you should + now have these lines in local.conf: + + PACKAGECONFIG_append_pn-qemu-native = " sdl" + PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" + + +
+ +
+ Minimum Git version + + + The minimum + Git version required + on the build host is now 1.7.8 because the + ‐‐list option is now required by + BitBake's Git fetcher. + As always, if your host distribution does not provide a version of + Git that meets this requirement, you can use the + buildtools-tarball that does. + See the + "Required Git, tar, and Python Versions" + section for more information. + +
+ +
+ Autotools Class Changes + + + The following + autotools + class changes occurred: + + + A separate build directory is now used by default: + The autotools class has been changed + to use a directory for building + (B), + which is separate from the source directory + (S). + This is commonly referred to as + B != S, or an out-of-tree build. + If the software being built is already capable of + building in a directory separate from the source, you + do not need to do anything. + However, if the software is not capable of being built + in this manner, you will + need to either patch the software so that it can build + separately, or you will need to change the recipe to + inherit the + autotools-brokensep + class instead of the autotools class. + + + The ‐‐foreign option is + no longer passed to automake when + running autoconf: + This option tells automake that a + particular software package does not follow the GNU + standards and therefore should not be expected + to distribute certain files such as + ChangeLog, + AUTHORS, and so forth. + Because the majority of upstream software packages already + tell automake to enable foreign mode + themselves, the option is mostly superfluous. + However, some recipes will need patches for this change. + You can easily make the change by patching + configure.ac so that it passes + "foreign" to AM_INIT_AUTOMAKE(). + See + this commit + for an example showing how to make the patch. + + + +
+ +
+ Binary Configuration Scripts Disabled + + + Some of the core recipes that package binary configuration scripts + now disable the scripts due to the + scripts previously requiring error-prone path substitution. + Software that links against these libraries using these scripts + should use the much more robust pkg-config + instead. + The list of recipes changed in this version (and their + configuration scripts) is as follows: + + directfb (directfb-config) + freetype (freetype-config) + gpgme (gpgme-config) + libassuan (libassuan-config) + libcroco (croco-6.0-config) + libgcrypt (libgcrypt-config) + libgpg-error (gpg-error-config) + libksba (ksba-config) + libpcap (pcap-config) + libpcre (pcre-config) + libpng (libpng-config, libpng16-config) + libsdl (sdl-config) + libusb-compat (libusb-config) + libxml2 (xml2-config) + libxslt (xslt-config) + ncurses (ncurses-config) + neon (neon-config) + npth (npth-config) + pth (pth-config) + taglib (taglib-config) + + Additionally, support for pkg-config has been + added to some recipes in the previous list in the rare cases + where the upstream software package does not already provide + it. + +
+ +
+ <filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename> + + + Because eglibc and + glibc were already fairly close, this + replacement should not require any significant changes to other + software that links to eglibc. + However, there were a number of minor changes in + glibc 2.20 upstream that could require + patching some software (e.g. the removal of the + _BSD_SOURCE feature test macro). + + + + glibc 2.20 requires version 2.6.32 or greater + of the Linux kernel. + Thus, older kernels will no longer be usable in conjunction with it. + + + + For full details on the changes in glibc 2.20, + see the upstream release notes + here. + +
+ +
+ Kernel Module Autoloading + + + The + module_autoload_* + variable is now deprecated and a new + KERNEL_MODULE_AUTOLOAD + variable should be used instead. + Also, + module_conf_* + must now be used in conjunction with a new + KERNEL_MODULE_PROBECONF + variable. + The new variables no longer require you to specify the module name + as part of the variable name. + This change not only simplifies usage but also allows the values + of these variables to be appropriately incorporated into task + signatures and thus trigger the appropriate tasks to re-execute + when changed. + You should replace any references to + module_autoload_* with + KERNEL_MODULE_AUTOLOAD, and add any modules + for which module_conf_* is specified to + KERNEL_MODULE_PROBECONF. + + + + For more information, see the + KERNEL_MODULE_AUTOLOAD + and + KERNEL_MODULE_PROBECONF + variables. + +
+ +
+ QA Check Changes + + + The following changes have occurred to the QA check process: + + + Additional QA checks file-rdeps + and build-deps have been added in + order to verify that file dependencies are satisfied + (e.g. package contains a script requiring + /bin/bash) and build-time dependencies + are declared, respectively. + For more information, please see the + "QA Error and Warning Messages" + chapter. + + + Package QA checks are now performed during a new + do_package_qa + task rather than being part of the + do_package + task. + This allows more parallel execution. + This change is unlikely to be an issue except for highly + customized recipes that disable packaging tasks themselves + by marking them as noexec. + For those packages, you will need to disable the + do_package_qa task as well. + + + Files being overwritten during the + do_populate_sysroot + task now trigger an error instead of a warning. + Recipes should not be overwriting files written to the + sysroot by other recipes. + If you have these types of recipes, you need to alter them + so that they do not overwrite these files. + You might now receive this error after changes in + configuration or metadata resulting in orphaned files + being left in the sysroot. + If you do receive this error, the way to resolve the issue + is to delete your + TMPDIR + or to move it out of the way and then re-start the build. + Anything that has been fully built up to that point and + does not need rebuilding will be restored from the shared + state cache and the rest of the build will be able to + proceed as normal. + + + +
+ +
+ Removed Recipes + + + The following recipes have been removed: + + + x-load: + This recipe has been superseded by + U-boot SPL for all Cortex-based TI SoCs. + For legacy boards, the meta-ti + layer, which contains a maintained recipe, should be used + instead. + + + ubootchart: + This recipe is obsolete. + A bootchart2 recipe has been added + to functionally replace it. + + + linux-yocto 3.4: + Support for the linux-yocto 3.4 kernel has been dropped. + Support for the 3.10 and 3.14 kernels remains, while + support for version 3.17 has been added. + + + eglibc has been removed in favor of + glibc. + See the + "eglibc 2.19 Replaced with glibc 2.20" + section for more information. + + + +
+ +
+ Miscellaneous Changes + + + The following miscellaneous change occurred: + + + The build history feature now writes + build-id.txt instead of + build-id. + Additionally, build-id.txt + now contains the full build header as printed by + BitBake upon starting the build. + You should manually remove old "build-id" files from your + existing build history repositories to avoid confusion. + For information on the build history feature, see the + "Maintaining Build Output Quality" + section. + + + +
+
+ +
+ diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml new file mode 100644 index 0000000000..30aff6431f --- /dev/null +++ b/documentation/ref-manual/ref-bitbake.xml @@ -0,0 +1,472 @@ + %poky; ] > + + + + BitBake + + + BitBake is a program written in Python that interprets the + Metadata used by + the OpenEmbedded build system. + At some point, developers wonder what actually happens when you enter: + + $ bitbake core-image-sato + + + + + This chapter provides an overview of what happens behind the scenes from BitBake's perspective. + + + + BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships. + As such, it has no real knowledge of what the tasks being executed actually do. + BitBake just considers a list of tasks with dependencies and handles + Metadata + consisting of variables in a certain format that get passed to the tasks. + + +
+ Parsing + + + BitBake parses configuration files, classes, and .bb files. + + + + The first thing BitBake does is look for the bitbake.conf file. + This file resides in the + Source Directory + within the meta/conf/ directory. + BitBake finds it by examining its + BBPATH environment + variable and looking for the meta/conf/ + directory. + + + + The bitbake.conf file lists other configuration + files to include from a conf/ + directory below the directories listed in BBPATH. + In general, the most important configuration file from a user's perspective + is local.conf, which contains a user's customized + settings for the OpenEmbedded build environment. + Other notable configuration files are the distribution + configuration file (set by the + DISTRO variable) + and the machine configuration file + (set by the + MACHINE variable). + The DISTRO and MACHINE BitBake environment + variables are both usually set in + the local.conf file. + Valid distribution + configuration files are available in the meta/conf/distro/ directory + and valid machine configuration + files in the meta/conf/machine/ directory. + Within the meta/conf/machine/include/ + directory are various tune-*.inc configuration files that provide common + "tuning" settings specific to and shared between particular architectures and machines. + + + + After the parsing of the configuration files, some standard classes are included. + The base.bbclass file is always included. + Other classes that are specified in the configuration using the + INHERIT + variable are also included. + Class files are searched for in a classes subdirectory + under the paths in BBPATH in the same way as + configuration files. + + + + After classes are included, the variable + BBFILES + is set, usually in + local.conf, and defines the list of places to search for + .bb files. + By default, the BBFILES variable specifies the + meta/recipes-*/ directory within Poky. + Adding extra content to BBFILES is best achieved through the use of + BitBake layers as described in the + "Understanding and + Creating Layers" section of the Yocto Project Development Manual. + + + + BitBake parses each .bb file in BBFILES and + stores the values of various variables. + In summary, for each .bb + file the configuration plus the base class of variables are set, followed + by the data in the .bb file + itself, followed by any inherit commands that + .bb file might contain. + + + + Because parsing .bb files is a time + consuming process, a cache is kept to speed up subsequent parsing. + This cache is invalid if the timestamp of the .bb + file itself changes, or if the timestamps of any of the include, + configuration files or class files on which the + .bb file depends change. + + + + + You need to be aware of how BitBake parses curly braces. + If a recipe uses a closing curly brace within the function and + the character has no leading spaces, BitBake produces a parsing + error. + If you use a pair of curly brace in a shell function, the + closing curly brace must not be located at the start of the line + without leading spaces. + + + + Here is an example that causes BitBake to produce a parsing + error: + + fakeroot create_shar() { + cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh + usage() + { + echo "test" + ###### The following "}" at the start of the line causes a parsing error ###### + } + EOF + } + + Writing the recipe this way avoids the error: + + fakeroot create_shar() { + cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh + usage() + { + echo "test" + ######The following "}" with a leading space at the start of the line avoids the error ###### + } + EOF + } + + + +
+ +
+ Preferences and Providers + + + Once all the .bb files have been + parsed, BitBake starts to build the target (core-image-sato + in the previous section's example) and looks for providers of that target. + Once a provider is selected, BitBake resolves all the dependencies for + the target. + In the case of core-image-sato, it would lead to + packagegroup-core-x11-sato, + which in turn leads to recipes like matchbox-terminal, + pcmanfm and gthumb. + These recipes in turn depend on glibc and the toolchain. + + + + Sometimes a target might have multiple providers. + A common example is "virtual/kernel", which is provided by each kernel package. + Each machine often selects the best kernel provider by using a line similar to the + following in the machine configuration file: + + + + PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" + + + + The default PREFERRED_PROVIDER + is the provider with the same name as the target. + + + + Understanding how providers are chosen is made complicated by the fact + that multiple versions might exist. + BitBake defaults to the highest version of a provider. + Version comparisons are made using the same method as Debian. + You can use the + PREFERRED_VERSION + variable to specify a particular version (usually in the distro configuration). + You can influence the order by using the + DEFAULT_PREFERENCE + variable. + By default, files have a preference of "0". + Setting the DEFAULT_PREFERENCE to "-1" makes the + package unlikely to be used unless it is explicitly referenced. + Setting the DEFAULT_PREFERENCE to "1" makes it likely the package is used. + PREFERRED_VERSION overrides any DEFAULT_PREFERENCE setting. + DEFAULT_PREFERENCE is often used to mark newer and more experimental package + versions until they have undergone sufficient testing to be considered stable. + + + + In summary, BitBake has created a list of providers, which is prioritized, for each target. + +
+ +
+ Dependencies + + + Each target BitBake builds consists of multiple tasks such as + fetch, unpack, + patch, configure, + and compile. + For best performance on multi-core systems, BitBake considers each task as an independent + entity with its own set of dependencies. + + + + Dependencies are defined through several variables. + You can find information about variables BitBake uses in the BitBake documentation, + which is found in the bitbake/doc/manual directory within the + Source Directory. + At a basic level, it is sufficient to know that BitBake uses the + DEPENDS and + RDEPENDS variables when + calculating dependencies. + +
+ +
+ The Task List + + + Based on the generated list of providers and the dependency information, + BitBake can now calculate exactly what tasks it needs to run and in what + order it needs to run them. + The build now starts with BitBake forking off threads up to the limit set in the + BB_NUMBER_THREADS variable. + BitBake continues to fork threads as long as there are tasks ready to run, + those tasks have all their dependencies met, and the thread threshold has not been + exceeded. + + + + It is worth noting that you can greatly speed up the build time by properly setting + the BB_NUMBER_THREADS variable. + See the + "Building an Image" + section in the Yocto Project Quick Start for more information. + + + + As each task completes, a timestamp is written to the directory specified by the + STAMP variable. + On subsequent runs, BitBake looks within the build/tmp/stamps + directory and does not rerun + tasks that are already completed unless a timestamp is found to be invalid. + Currently, invalid timestamps are only considered on a per + .bb file basis. + So, for example, if the configure stamp has a timestamp greater than the + compile timestamp for a given target, then the compile task would rerun. + Running the compile task again, however, has no effect on other providers + that depend on that target. + This behavior could change or become configurable in future versions of BitBake. + + + + Some tasks are marked as "nostamp" tasks. + No timestamp file is created when these tasks are run. + Consequently, "nostamp" tasks are always rerun. + +
+ +
+ Running a Task + + + Tasks can either be a shell task or a Python task. + For shell tasks, BitBake writes a shell script to + ${WORKDIR}/temp/run.do_taskname.pid and then executes the script. + The generated shell script contains all the exported variables, and the shell functions + with all variables expanded. + Output from the shell script goes to the file ${WORKDIR}/temp/log.do_taskname.pid. + Looking at the expanded shell functions in the run file and the output in the log files + is a useful debugging technique. + + + + For Python tasks, BitBake executes the task internally and logs information to the + controlling terminal. + Future versions of BitBake will write the functions to files similar to the way + shell tasks are handled. + Logging will be handled in a way similar to shell tasks as well. + + + + Once all the tasks have been completed BitBake exits. + + + + When running a task, BitBake tightly controls the execution environment + of the build tasks to make sure unwanted contamination from the build machine + cannot influence the build. + Consequently, if you do want something to get passed into the build + task's environment, you must take a few steps: + + Tell BitBake to load what you want from the environment + into the data store. + You can do so through the BB_ENV_EXTRAWHITE + variable. + For example, assume you want to prevent the build system from + accessing your $HOME/.ccache directory. + The following command tells BitBake to load + CCACHE_DIR from the environment into the data + store: + + export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" + + Tell BitBake to export what you have loaded into the + environment store to the task environment of every running task. + Loading something from the environment into the data store + (previous step) only makes it available in the datastore. + To export it to the task environment of every running task, + use a command similar to the following in your + local.conf or distro configuration file: + + export CCACHE_DIR + + + + + + A side effect of the previous steps is that BitBake records the variable + as a dependency of the build process in things like the shared state + checksums. + If doing so results in unnecessary rebuilds of tasks, you can whitelist the + variable so that the shared state code ignores the dependency when it creates + checksums. + For information on this process, see the BB_HASHBASE_WHITELIST + example in the "Checksums (Signatures)" section. + +
+ +
+ BitBake Command Line + + + Following is the BitBake help output: + + + +$ bitbake --help +Usage: bitbake [options] [recipename/target ...] + + Executes the specified task (default is 'build') for a given set of target recipes (.bb files). + It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which + will provide the layer, BBFILES and other configuration information. + +Options: + --version show program's version number and exit + -h, --help show this help message and exit + -b BUILDFILE, --buildfile=BUILDFILE + Execute tasks from a specific .bb recipe directly. + WARNING: Does not handle any dependencies from other + recipes. + -k, --continue Continue as much as possible after an error. While the + target that failed and anything depending on it cannot + be built, as much as possible will be built before + stopping. + -a, --tryaltconfigs Continue with builds by trying to use alternative + providers where possible. + -f, --force Force the specified targets/task to run (invalidating + any existing stamp file). + -c CMD, --cmd=CMD Specify the task to execute. The exact options + available depend on the metadata. Some examples might + be 'compile' or 'populate_sysroot' or 'listtasks' may + give a list of the tasks available. + -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP + Invalidate the stamp for the specified task such as + 'compile' and then run the default task for the + specified target(s). + -r PREFILE, --read=PREFILE + Read the specified file before bitbake.conf. + -R POSTFILE, --postread=POSTFILE + Read the specified file after bitbake.conf. + -v, --verbose Output more log message data to the terminal. + -D, --debug Increase the debug level. You can specify this more + than once. + -n, --dry-run Don't execute, just go through the motions. + -S, --dump-signatures + Don't execute, just dump out the signature + construction information. + -p, --parse-only Quit after parsing the BB recipes. + -s, --show-versions Show current and preferred versions of all recipes. + -e, --environment Show the global or per-package environment complete + with information about where variables were + set/changed. + -g, --graphviz Save dependency tree information for the specified + targets in the dot syntax. + -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED + Assume these dependencies don't exist and are already + provided (equivalent to ASSUME_PROVIDED). Useful to + make dependency graphs more appealing + -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). + -t SERVERTYPE, --servertype=SERVERTYPE + Choose which server to use, process or xmlrpc. + --revisions-changed Set the exit code depending on whether upstream + floating revisions have changed or not. + --server-only Run bitbake without a UI, only starting a server + (cooker) process. + -B BIND, --bind=BIND The name/address for the bitbake server to bind to. + --no-setscene Do not run any setscene tasks. sstate will be ignored + and everything needed, built. + --remote-server=REMOTE_SERVER + Connect to the specified server. + -m, --kill-server Terminate the remote server. + --observe-only Connect to a server as an observing-only client. + +
+ +
+ Fetchers + + + BitBake also contains a set of "fetcher" modules that allow + retrieval of source code from various types of sources. + For example, BitBake can get source code from a disk with the metadata, from websites, + from remote shell accounts, or from Source Code Management (SCM) systems + like cvs/subversion/git. + + + + Fetchers are usually triggered by entries in + SRC_URI. + You can find information about the options and formats of entries for specific + fetchers in the BitBake manual located in the + bitbake/doc/manual directory of the + Source Directory. + + + + One useful feature for certain Source Code Manager (SCM) fetchers is the ability to + "auto-update" when the upstream SCM changes version. + Since this ability requires certain functionality from the SCM, not all + systems support it. + Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". + This feature works using the SRCREV + variable. + See the + "Using an External SCM" section + in the Yocto Project Development Manual for more information. + + +
+ +
+ diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml new file mode 100644 index 0000000000..f60b907e85 --- /dev/null +++ b/documentation/ref-manual/ref-classes.xml @@ -0,0 +1,3489 @@ + %poky; ] > + + +Classes + + + Class files are used to abstract common functionality and share it amongst + multiple recipe (.bb) files. + To use a class file, you simply make sure the recipe inherits the class. + In most cases, when a recipe inherits a class it is enough to enable its + features. + There are cases, however, where in the recipe you might need to set + variables or override some default behavior. + + + + Any Metadata usually + found in a recipe can also be placed in a class file. + Class files are identified by the extension .bbclass + and are usually placed in a classes/ directory beneath + the meta*/ directory found in the + Source Directory. + Class files can also be pointed to by + BUILDDIR + (e.g. build/) in the same way as + .conf files in the conf directory. + Class files are searched for in + BBPATH + using the same method by which .conf files are + searched. + + + + This chapter discusses only the most useful and important classes. + Other classes do exist within the meta/classes + directory in the + Source Directory. + You can reference the .bbclass files directly + for more information. + + +
+ <filename>allarch.bbclass</filename> + + + The allarch class is inherited + by recipes that do not produce architecture-specific output. + The class disables functionality that is normally needed for recipes + that produce executable binaries (such as building the cross-compiler + and a C library as pre-requisites, and splitting out of debug symbols + during packaging). + + + + By default, all recipes inherit the + base and + package + classes, which enable functionality + needed for recipes that produce executable output. + If your recipe, for example, only produces packages that contain + configuration files, media files, or scripts (e.g. Python and Perl), + then it should inherit the allarch class. + +
+ +
+ <filename>archiver.bbclass</filename> + + + The archiver class supports releasing + source code and other materials with the binaries. + + + + For more details on the source archiver, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" + section in the Yocto Project Development Manual. + +
+ +
+ <filename>autotools.bbclass</filename> + + + The autotools class supports Autotooled + packages. + + + + The autoconf, automake, + and libtool bring standardization. + This class defines a set of tasks (configure, compile etc.) that + work for all Autotooled packages. + It should usually be enough to define a few standard variables + and then simply inherit autotools. + This class can also work with software that emulates Autotools. + For more information, see the + "Autotooled Package" + section in the Yocto Project Development Manual. + + + + By default, the autotools class + uses out-of-tree builds + (B != + S). + If the software being built by a recipe does not support + using out-of-tree builds, you should have the recipe inherit the + autotools-brokensep + class. + + + + It's useful to have some idea of how the tasks defined by this class work + and what they do behind the scenes. + + do_configure ‐ + Regenerates the + configure script (using autoreconf) and then launches it + with a standard set of arguments used during cross-compilation. + You can pass additional parameters to configure through the + EXTRA_OECONF variable. + + do_compile ‐ Runs make with + arguments that specify the compiler and linker. + You can pass additional arguments through + the EXTRA_OEMAKE variable. + + do_install ‐ Runs make install + and passes in + ${D} + as DESTDIR. + + + +
+ +
+ <filename>autotools-brokensep.bbclass</filename> + + + The autotools-brokensep class behaves the same + as the + autotools + class but builds with + B == + S. + This method is useful when out-of-tree build support is either not + present or is broken. + + It is recommended that out-of-tree support be fixed and used + if at all possible. + + +
+ +
+ <filename>base.bbclass</filename> + + + The base class is special in that every + .bb file implicitly inherits the class. + This class contains definitions for standard basic + tasks such as fetching, unpacking, configuring (empty by default), + compiling (runs any Makefile present), installing + (empty by default) and packaging (empty by default). + These classes are often overridden or extended by other classes + such as the + autotools + class or the + package + class. + The class also contains some commonly used functions such as + oe_runmake. + +
+ +
+ <filename>bin_package.bbclass</filename> + + + The bin_package class is a + helper class for recipes that extract the contents of a binary package + (e.g. an RPM) and install those contents rather than building the + binary from source. + The binary package is extracted and new packages in the configured + output package format are created. + Extraction and installation of proprietary binaries is a good example + use for this class. + + For RPMs and other packages that do not contain a subdirectory, + you should specify a "subdir" parameter. + Here is an example where ${BP} is used so that + the files are extracted into the subdirectory expected by the + default value of + S: + + SRC_URI = "http://example.com/downloads/somepackage.rpm;subdir=${BP}" + + + +
+ +
+ <filename>binconfig.bbclass</filename> + + + The binconfig class helps to correct paths in + shell scripts. + + + + Before pkg-config had become widespread, libraries + shipped shell scripts to give information about the libraries and + include paths needed to build software (usually named + LIBNAME-config). + This class assists any recipe using such scripts. + + + + During staging, the OpenEmbedded build system installs such scripts + into the sysroots/ directory. + Inheriting this class results in all paths in these scripts being + changed to point into the sysroots/ directory so + that all builds that use the script use the correct directories + for the cross compiling layout. + See the + BINCONFIG_GLOB + variable for more information. + +
+ +
+ <filename>binconfig-disabled.bbclass</filename> + + + An alternative version of the + binconfig + class, which disables binary configuration scripts by making them + return an error in favor of using pkg-config + to query the information. + The scripts to be disabled should be specified using the + BINCONFIG + variable within the recipe inheriting the class. + +
+ +
+ <filename>blacklist.bbclass</filename> + + + The blacklist class prevents + the OpenEmbedded build system from building specific recipes + (blacklists them). + To use this class, inherit the class globally and set + PNBLACKLIST + for each recipe you wish to blacklist. + Specify the PN + value as a variable flag (varflag) and provide a reason, which is + reported, if the package is requested to be built as the value. + For example, if you want to blacklist a recipe called "exoticware", + you add the following to your local.conf + or distribution configuration: + + INHERIT += "blacklist" + PNBLACKLIST[exoticware] = "Not supported by our organization." + + +
+ +
+ <filename>boot-directdisk.bbclass</filename> + + + The boot-directdisk class + creates an image that can be placed directly onto a hard disk using + dd and then booted. + The image uses SYSLINUX. + + + + 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 ext2 and ext3 + root filesystems. + +
+ +
+ <filename>bootimg.bbclass</filename> + + + The bootimg class creates a bootable + image using SYSLINUX, your kernel, and an optional initial RAM disk + (initrd). + + + + When you use this class, two things happen: + + + A .hddimg file is created. + This file is an MSDOS filesystem that contains SYSLINUX, + a kernel, an initrd, 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 dd. + + + A CD .iso image is created. + When this file is booted, the initrd + boots and processes the label selected in SYSLINUX. + Actions based on the label are then performed (e.g. installing + to a hard drive). + + + + + The bootimg class supports the + INITRD, + NOISO, + NOHDD, and + ROOTFS + variables. + +
+ +
+ <filename>bugzilla.bbclass</filename> + + + The bugzilla class supports setting up an + instance of Bugzilla in which you can automatically files bug reports + in response to build failures. + For this class to work, you need to enable the XML-RPC interface in + the instance of Bugzilla. + +
+ +
+ <filename>buildhistory.bbclass</filename> + + + The buildhistory class records a + history of build output metadata, which can be used to detect possible + regressions as well as used for analysis of the build output. + For more information on using Build History, see the + "Maintaining Build Output Quality" + section. + +
+ +
+ <filename>buildstats.bbclass</filename> + + + The buildstats class records + performance statistics about each task executed during the build + (e.g. elapsed time, CPU usage, and I/O usage). + + + + When you use this class, the output goes into the + BUILDSTATS_BASE + directory, which defaults to ${TMPDIR}/buildstats/. + You can analyze the elapsed time using + scripts/pybootchartgui/pybootchartgui.py, which + produces a cascading chart of the entire build process and can be + useful for highlighting bottlenecks. + + + + Collecting build statistics is enabled by default through the + USER_CLASSES + variable from your local.conf file. + Consequently, you do not have to do anything to enable the class. + However, if you want to disable the class, simply remove "buildstats" + from the USER_CLASSES list. + +
+ +
+ <filename>buildstats-summary.bbclass</filename> + + + When inherited globally, prints statistics at the end of the build + on sstate re-use. + In order to function, this class requires the + buildstats + class be enabled. + +
+ +
+ <filename>ccache.bbclass</filename> + + + The ccache class enables the + C/C++ Compiler Cache + for the build. + This class is used to give a minor performance boost during the build. + However, using the class can lead to unexpected side-effects. + Thus, it is recommended that you do not use this class. + See for information on + the C/C++ Compiler Cache. + +
+ +
+ <filename>chrpath.bbclass</filename> + + + The chrpath class + is a wrapper around the "chrpath" utility, which is used during the + build process for nativesdk, + cross, and + cross-canadian recipes to change + RPATH records within binaries in order to make + them relocatable. + +
+ +
+ <filename>clutter.bbclass</filename> + + + The clutter class consolidates the + major and minor version naming and other common items used by Clutter + and related recipes. + + Unlike some other classes related to specific libraries, recipes + building other software that uses Clutter do not need to + inherit this class unless they use the same recipe versioning + scheme that the Clutter and related recipes do. + + +
+ +
+ <filename>cmake.bbclass</filename> + + + The cmake class allows for + recipes that need to build software using the CMake build system. + You can use the + EXTRA_OECMAKE + variable to specify additional configuration options to be passed on + the cmake command line. + +
+ +
+ <filename>cml1.bbclass</filename> + + + The cml1 class provides basic support for the + Linux kernel style build configuration system. + +
+ +
+ <filename>compress_doc.bbclass</filename> + + + Enables compression for man pages and info pages. + This class is intended to be inherited globally. + The default compression mechanism is gz (gzip) but you can + select an alternative mechanism by setting the + DOC_COMPRESS + variable. + +
+ +
+ <filename>copyleft_compliance.bbclass</filename> + + + The copyleft_compliance class + preserves source code for the purposes of license compliance. + This class is an alternative to the archiver + class and is still used by some users even though it has been + deprecated in favor of the + archiver + class. + +
+ +
+ <filename>copyleft_filter.bbclass</filename> + + + A class used by the + archiver + and + copyleft_compliance + classes for filtering licenses. + The copyleft_filter class is an internal class + and is not intended to be used directly. + +
+ +
+ <filename>core-image.bbclass</filename> + + + The core-image class + provides common definitions for the + core-image-* image recipes, such as support for + additional + IMAGE_FEATURES. + +
+ +
+ <filename>cpan.bbclass</filename> + + + The cpan class supports Perl modules. + + + + Recipes for Perl modules are simple. + These recipes usually only need to point to the source's archive and + then inherit the proper class file. + Building is split into two methods depending on which method the module + authors used. + + Modules that use old + Makefile.PL-based build system require + cpan.bbclass in their recipes. + + Modules that use + Build.PL-based build system require + using cpan_build.bbclass in their recipes. + + + +
+ +
+ <filename>cross.bbclass</filename> + + + The cross class provides support for the recipes + that build the cross-compilation tools. + +
+ +
+ <filename>cross-canadian.bbclass</filename> + + + The cross-canadian class + provides support for the recipes that build the Canadian + Cross-compilation tools for SDKs. + See the + "Cross-Development Toolchain Generation" + section for more discussion on these cross-compilation tools. + +
+ +
+ <filename>crosssdk.bbclass</filename> + + + The crosssdk class + provides support for the recipes that build the cross-compilation + tools used for building SDKs. + See the + "Cross-Development Toolchain Generation" + section for more discussion on these cross-compilation tools. + +
+ +
+ <filename>debian.bbclass</filename> + + + The debian class renames output packages so that + they follow the Debian naming policy (i.e. glibc + becomes libc6 and glibc-devel + becomes libc6-dev.) + Renaming includes the library name and version as part of the package + name. + + + + If a recipe creates packages for multiple libraries + (shared object files of .so type), use the + LEAD_SONAME + variable in the recipe to specify the library on which to apply the + naming scheme. + +
+ +
+ <filename>deploy.bbclass</filename> + + + The deploy class handles deploying files + to the + DEPLOY_DIR_IMAGE + directory. + The main function of this class is to allow the deploy step to be + accelerated by shared state. + Recipes that inherit this class should define their own + do_deploy + function to copy the files to be deployed to + DEPLOYDIR, + and use addtask to add the task at the appropriate + place, which is usually after + do_compile + or + do_install. + The class then takes care of staging the files from + DEPLOYDIR to + DEPLOY_DIR_IMAGE. + +
+ +
+ <filename>devshell.bbclass</filename> + + + The devshell class adds the + do_devshell task. + Distribution policy dictates whether to include this class. + See the + "Using a Development Shell" section + in the Yocto Project Development Manual for more information about + using devshell. + +
+ +
+ <filename>distro_features_check.bbclass</filename> + + + The distro_features_check class + allows individual recipes to check for required and conflicting + DISTRO_FEATURES. + + + + This class provides support for the + REQUIRED_DISTRO_FEATURES + and + CONFLICT_DISTRO_FEATURES + variables. + If any conditions specified in the recipe using the above variables are + not met, the recipe will be skipped. + +
+ +
+ <filename>distrodata.bbclass</filename> + + + The distrodata class + 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 do_distrodata and + do_distro_check tasks, which do upstream checking + and also verify if a package is used in multiple major distributions. + + + + The class is not included by default. + To use it, you must include the following files and set the + INHERIT + variable: + + include conf/distro/include/distro_alias.inc + include conf/distro/include/recipe_color.inc + include conf/distro/include/maintainers.inc + include conf/distro/include/upstream_tracking.inc + include conf/distro/include/package_regex.inc + INHERIT+= "distrodata" + + +
+ +
+ <filename>distutils.bbclass</filename> + + + The distutils class supports recipes for Python + version 2.x extensions, which are simple. + These recipes usually only need to point to the source's archive and + then inherit the proper class. + Building is split into two methods depending on which method the + module authors used. + + Extensions that use an Autotools-based build system + require Autotools and + distutils-based classes in their recipes. + + Extensions that use build systems based on + distutils require + the distutils class in their recipes. + + Extensions that use build systems based on + setuptools require the + setuptools + class in their recipes. + + + +
+ +
+ <filename>distutils3.bbclass</filename> + + + The distutils3 class supports recipes for Python + version 3.x extensions, which are simple. + These recipes usually only need to point to the source's archive and + then inherit the proper class. + Building is split into two methods depending on which method the + module authors used. + + Extensions that use an Autotools-based build system + require Autotools and + distutils-based classes in their recipes. + + Extensions that use + distutils-based build systems require + the distutils class in their recipes. + + Extensions that use build systems based on + setuptools3 require the + setuptools3 + class in their recipes. + + + +
+ +
+ <filename>externalsrc.bbclass</filename> + + + The externalsrc class supports building software + from source code that is external to the OpenEmbedded build system. + Building software from an external source tree means that the build + system's normal fetch, unpack, and patch process is not used. + + + + By default, the OpenEmbedded build system uses the + S and + B variables to + locate unpacked recipe source code and to build it, respectively. + When your recipe inherits the externalsrc class, + you use the + EXTERNALSRC + and + EXTERNALSRC_BUILD + variables to ultimately define S and + B. + + + + By default, this class expects the source code to support recipe builds + that use the B + variable to point to the directory in which the OpenEmbedded build + system places the generated objects built from the recipes. + By default, the B directory is set to the + following, which is separate from the source directory + (S): + + ${WORKDIR}/${BPN}/{PV}/ + + See these variables for more information: + WORKDIR, + BPN, and + PV, + + + + For more information on the + externalsrc class, see the comments in + meta/classes/externalsrc.bbclass in the + Source Directory. + For information on how to use the externalsrc + class, see the + "Building Software from an External Source" + section in the Yocto Project Development Manual. + +
+ +
+ <filename>extrausers.bbclass</filename> + + + The extrausers class allows + additional user and group configuration to be applied at the image + level. + Inheriting this class either globally or from an image recipe allows + additional user and group operations to be performed using the + EXTRA_USERS_PARAMS + variable. + + The user and group operations added using the + extrausers class are not tied to a specific + recipe outside of the recipe for the image. + Thus, the operations can be performed across the image as a whole. + Use the + useradd + class to add user and group configuration to a specific recipe. + + Here is an example that uses this class in an image recipe: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -p '' tester; \ + groupadd developers; \ + userdel nobody; \ + groupdel -g video; \ + groupmod -g 1020 developers; \ + usermod -s /bin/sh tester; \ + " + + Here is an example that adds two users named "tester-jim" and + "tester-sue" and assigns passwords: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -P tester01 tester-jim; \ + useradd -P tester01 tester-sue; \ + " + + Finally, here is an example that sets the root password to + "1876*18": + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -P 1876*18 root; \ + " + + +
+ +
+ <filename>fontcache.bbclass</filename> + + + The fontcache class generates the + proper post-install and post-remove (postinst and postrm) + scriptlets for font packages. + These scriptlets call fc-cache (part of + Fontconfig) to add the fonts to the font + information cache. + Since the cache files are architecture-specific, + fc-cache runs using QEMU if the postinst + scriptlets need to be run on the build host during image creation. + + + + If the fonts being installed are in packages other than the main + package, set + FONT_PACKAGES + to specify the packages containing the fonts. + +
+ +
+ <filename>gconf.bbclass</filename> + + + The gconf class provides common + functionality for recipes that need to install GConf schemas. + The schemas will be put into a separate package + (${PN}-gconf) + that is created automatically when this class is inherited. + This package uses the appropriate post-install and post-remove + (postinst/postrm) scriptlets to register and unregister the schemas + in the target image. + +
+ +
+ <filename>gettext.bbclass</filename> + + + The gettext class provides support for + building software that uses the GNU gettext + internationalization and localization system. + All recipes building software that use + gettext should inherit this class. + +
+ +
+ <filename>gnome.bbclass</filename> + + + The gnome class supports recipes that + build software from the GNOME stack. + This class inherits the + gnomebase, + gtk-icon-cache, + gconf and + mime classes. + The class also disables GObject introspection where applicable. + +
+ +
+ <filename>gnomebase.bbclass</filename> + + + The gnomebase class is the base + class for recipes that build software from the GNOME stack. + This class sets + SRC_URI to + download the source from the GNOME mirrors as well as extending + FILES + with the typical GNOME installation paths. + +
+ +
+ <filename>grub-efi.bbclass</filename> + + + The grub-efi + class provides grub-efi-specific functions for + building bootable images. + + + + This class supports several variables: + + + INITRD: + Indicates list of filesystem images to concatenate and use + as an initial RAM disk (initrd) (optional). + + + ROOTFS: + Indicates a filesystem image to include as the root filesystem + (optional). + + GRUB_GFXSERIAL: + Set this to "1" to have graphics and serial in the boot menu. + + + LABELS: + A list of targets for the automatic configuration. + + + APPEND: + An override list of append strings for each + LABEL. + + + GRUB_OPTS: + Additional options to add to the configuration (optional). + Options are delimited using semi-colon characters + (;). + + GRUB_TIMEOUT: + Timeout before executing the default LABEL + (optional). + + + +
+ +
+ <filename>gsettings.bbclass</filename> + + + The gsettings class + provides common functionality for recipes that need to install + GSettings (glib) schemas. + The schemas are assumed to be part of the main package. + Appropriate post-install and post-remove (postinst/postrm) + scriptlets are added to register and unregister the schemas in the + target image. + +
+ +
+ <filename>gtk-doc.bbclass</filename> + + + The gtk-doc class + is a helper class to pull in the appropriate + gtk-doc dependencies and disable + gtk-doc. + +
+ +
+ <filename>gtk-icon-cache.bbclass</filename> + + + The gtk-icon-cache class + generates the proper post-install and post-remove (postinst/postrm) + scriptlets for packages that use GTK+ and install icons. + These scriptlets call gtk-update-icon-cache to add + the fonts to GTK+'s icon cache. + Since the cache files are architecture-specific, + gtk-update-icon-cache is run using QEMU if the + postinst scriptlets need to be run on the build host during image + creation. + +
+ +
+ <filename>gtk-immodules-cache.bbclass</filename> + + + The gtk-immodules-cache class + generates the proper post-install and post-remove (postinst/postrm) + scriptlets for packages that install GTK+ input method modules for + virtual keyboards. + These scriptlets call gtk-update-icon-cache to add + the input method modules to the cache. + Since the cache files are architecture-specific, + gtk-update-icon-cache is run using QEMU if the + postinst scriptlets need to be run on the build host during image + creation. + + + + If the input method modules being installed are in packages other than + the main package, set + GTKIMMODULES_PACKAGES + to specify the packages containing the modules. + +
+ +
+ <filename>gummiboot.bbclass</filename> + + + The gummiboot class provides functions specific + to the gummiboot bootloader for building bootable images. + This is an internal class and is not intended to be + used directly. + Set the + EFI_PROVIDER + variable to "gummiboot" to use this class. + + + + For information on more variables used and supported in this class, + see the + GUMMIBOOT_CFG, + GUMMIBOOT_ENTRIES, + and + GUMMIBOOT_TIMEOUT + variables. + + + + You can also see the + Gummiboot documentation + for more information. + +
+ +
+ <filename>gzipnative.bbclass</filename> + + + The gzipnative + class enables the use of native versions of gzip + and pigz rather than the versions of these tools + from the build host. + +
+ +
+ <filename>icecc.bbclass</filename> + + + The icecc class supports + Icecream, which + facilitates taking compile jobs and distributing them among remote + machines. + + + + The class stages directories with symlinks from gcc + and g++ to icecc, for both + native and cross compilers. + Depending on each configure or compile, the OpenEmbedded build system + adds the directories at the head of the PATH list + and then sets the ICECC_CXX and + ICEC_CC variables, which are the paths to the + g++ and gcc compilers, + respectively. + + + + For the cross compiler, the class creates a tar.gz + file that contains the Yocto Project toolchain and sets + ICECC_VERSION, which is the version of the + cross-compiler used in the cross-development toolchain, accordingly. + + + + The class handles all three different compile stages + (i.e native ,cross-kernel and target) and creates the necessary + environment tar.gz file to be used by the remote + machines. + The class also supports SDK generation. + + + + If ICECC_PATH + is not set in your local.conf file, then the + class tries to locate the icecc binary + using which. + + If + ICECC_ENV_EXEC + is set in your local.conf file, the variable should + point to the icecc-create-env script + provided by the user. + If you do not point to a user-provided script, the build system + uses the default script provided by the recipe + icecc-create-env-native.bb. + + This script is a modified version and not the one that comes with + icecc. + + + + + If you do not want the Icecream distributed compile support to apply + to specific recipes or classes, you can effectively "blacklist" them + by listing the recipes and classes using the + ICECC_USER_PACKAGE_BL + and + ICECC_USER_CLASS_BL, + variables, respectively, in your local.conf file. + Doing so causes the OpenEmbedded build system to handle these + compilations locally. + + + + Additionally, you can list recipes using the + ICECC_USER_PACKAGE_WL + variable in your local.conf file to force + icecc to be enabled for recipes using an empty + PARALLEL_MAKE + variable. + + + + Inheriting the icecc class changes all sstate + signatures. + Consequently, if a development team has a dedicated build system + that populates + STATE_MIRRORS + and they want to reuse sstate from + STATE_MIRRORS, then all developers and the + build system need to either inherit the icecc + class or nobody should. + + + + At the distribution level, you can inherit the + icecc class to be sure that all builders start + with the same sstate signatures. + After inheriting the class, you can then disable the feature by setting + the + ICECC_DISABLED + variable to "1" as follows: + + INHERIT_DISTRO_append = " icecc" + ICECC_DISABLED ??= "1" + + This practice makes sure everyone is using the same signatures but also + requires individuals that do want to use Icecream to enable the feature + individually as follows in your local.conf file: + + ICECC_DISABLED = "" + + +
+ +
+ <filename>image.bbclass</filename> + + + The image class helps support creating images + in different formats. + First, the root filesystem is created from packages using + one of the rootfs*.bbclass + files (depending on the package format used) and then one or more image + files are created. + + The + IMAGE_FSTYPES + variable controls the types of images to generate. + + The + IMAGE_INSTALL + variable controls the list of packages to install into the + image. + + For information on customizing images, see the + "Customizing Images" + section in the Yocto Project Development Manual. + For information on how images are created, see the + "Images" section elsewhere + in this manual. + +
+ +
+ <filename>image_types.bbclass</filename> + + + The image_types class defines all of + the standard image output types that you can enable through the + IMAGE_FSTYPES + variable. + You can use this class as a reference on how to add support for custom + image output types. + + + + By default, this class is enabled through the + IMAGE_CLASSES + variable in + image.bbclass. + If you define your own image types using a custom BitBake class and + then use IMAGE_CLASSES to enable it, the custom + class must either inherit image_types or + image_types must also appear in + IMAGE_CLASSES. + +
+ +
+ <filename>image_types_uboot.bbclass</filename> + + + The image_types_uboot class + defines additional image types specifically for the U-Boot bootloader. + +
+ +
+ <filename>image-live.bbclass</filename> + + + The image-live class supports building "live" + images. + + + + Normally, you do not use this class directly. + Instead, you add "live" to + IMAGE_FSTYPES. + For example, if you were building an ISO image, you would add "live" + to IMAGE_FSTYPES, set the + NOISO variable to + "0" and the build system would use the image-live + class to build the ISO image. + +
+ +
+ <filename>image-mklibs.bbclass</filename> + + + The image-mklibs class + enables the use of the mklibs utility during the + do_rootfs + task, which optimizes the size of + libraries contained in the image. + + + + By default, the class is enabled in the + local.conf.template using the + USER_CLASSES + variable as follows: + + USER_CLASSES ?= "buildstats image-mklibs image-prelink" + + +
+ + + +
+ <filename>image-swab.bbclass</filename> + + + The image-swab class enables the + Swabber + tool in order to detect and log accesses to the host system during + the OpenEmbedded build process. + + This class is currently unmaintained. + + +
+ +
+ <filename>image-vmdk.bbclass</filename> + + + The image-vmdk class supports building VMware + VMDK images. + Normally, you do not use this class directly. + Instead, you add "vmdk" to + IMAGE_FSTYPES. + +
+ +
+ <filename>insane.bbclass</filename> + + + The insane class adds a step to the package + generation process so that output quality assurance checks are + generated by the OpenEmbedded build system. + A range of checks are performed that check the build's output + for common problems that show up during runtime. + Distribution policy usually dictates whether to include this class. + + + + You can configure the sanity checks so that specific test failures + either raise a warning or an error message. + Typically, failures for new tests generate a warning. + Subsequent failures for the same test would then generate an error + message once the metadata is in a known and good condition. + See the + "QA Error and Warning Messages" + Chapter for a list of all the warning and error messages + you might encounter using a default configuration. + + + + Use the + WARN_QA and + ERROR_QA + variables to control the behavior of + these checks at the global level (i.e. in your custom distro + configuration). + However, to skip one or more checks in recipes, you should use + INSANE_SKIP. + For example, to skip the check for symbolic link + .so files in the main package of a recipe, + add the following to the recipe. + You need to realize that the package name override, in this example + ${PN}, must be used: + + INSANE_SKIP_${PN} += "dev-so" + + Please keep in mind that the QA checks exist in order to detect real + or potential problems in the packaged output. + So exercise caution when disabling these checks. + + + + The following list shows the tests you can list with the + WARN_QA and ERROR_QA + variables: + + already-stripped: + Checks that produced binaries have not already been + stripped prior to the build system extracting debug symbols. + It is common for upstream software projects to default to + stripping debug symbols for output binaries. + In order for debugging to work on the target using + -dbg packages, this stripping must be + disabled. + + arch: + Checks the Executable and Linkable Format (ELF) type, bit size, + and endianness of any binaries to ensure they match the target + architecture. + This test fails if any binaries do not match the type since + there would be an incompatibility. + The test could indicate that the + wrong compiler or compiler options have been used. + Sometimes software, like bootloaders, might need to bypass + this check. + + buildpaths: + Checks for paths to locations on the build host inside the + output files. + Currently, this test triggers too many false positives and + thus is not normally enabled. + + build-deps: + Determines if a build-time dependency that is specified through + DEPENDS, + explicit + RDEPENDS, + or task-level dependencies exists to match any runtime + dependency. + This determination is particularly useful to discover where + runtime dependencies are detected and added during packaging. + If no explicit dependency has been specified within the + metadata, at the packaging stage it is too late to ensure that + the dependency is built, and thus you can end up with an + error when the package is installed into the image during the + do_rootfs + task because the auto-detected dependency was not satisfied. + An example of this would be where the + update-rc.d + class automatically adds a dependency on the + initscripts-functions package to packages + that install an initscript that refers to + /etc/init.d/functions. + The recipe should really have an explicit + RDEPENDS for the package in question on + initscripts-functions so that the + OpenEmbedded build system is able to ensure that the + initscripts recipe is actually built and + thus the initscripts-functions package is + made available. + + compile-host-path: + Checks the + do_compile + log for indications + that paths to locations on the build host were used. + Using such paths might result in host contamination of the + build output. + + debug-deps: + Checks that all packages except -dbg + packages do not depend on -dbg + packages, which would cause a packaging bug. + + debug-files: + Checks for .debug directories in anything but the + -dbg package. + The debug files should all be in the -dbg package. + Thus, anything packaged elsewhere is incorrect packaging. + dep-cmp: + Checks for invalid version comparison statements in runtime + dependency relationships between packages (i.e. in + RDEPENDS, + RRECOMMENDS, + RSUGGESTS, + RPROVIDES, + RREPLACES, + and + RCONFLICTS + variable values). + Any invalid comparisons might trigger failures or undesirable + behavior when passed to the package manager. + + desktop: + Runs the desktop-file-validate program + against any .desktop files to validate + their contents against the specification for + .desktop files. + dev-deps: + Checks that all packages except -dev + or -staticdev packages do not depend on + -dev packages, which would be a + packaging bug. + dev-so: + Checks that the .so symbolic links are in the + -dev package and not in any of the other packages. + In general, these symlinks are only useful for development purposes. + Thus, the -dev package is the correct location for + them. + Some very rare cases do exist for dynamically loaded modules where + these symlinks are needed instead in the main package. + + file-rdeps: + Checks that file-level dependencies identified by the + OpenEmbedded build system at packaging time are satisfied. + For example, a shell script might start with the line + #!/bin/bash. + This line would translate to a file dependency on + /bin/bash. + Of the three package managers that the OpenEmbedded build + system supports, only RPM directly handles file-level + dependencies, resolving them automatically to packages + providing the files. + However, the lack of that functionality in the other two + package managers does not mean the dependencies do not still + need resolving. + This QA check attempts to ensure that explicitly declared + RDEPENDS + exist to handle any file-level dependency detected in + packaged files. + + files-invalid: + Checks for + FILES + variable values that contain "//", which is invalid. + + incompatible-license: + Report when packages are excluded from being created due to + being marked with a license that is in + INCOMPATIBLE_LICENSE. + + install-host-path: + Checks the + do_install + log for indications + that paths to locations on the build host were used. + Using such paths might result in host contamination of the + build output. + + installed-vs-shipped: + Reports when files have been installed within + do_install but have not been included in + any package by way of the + FILES + variable. + Files that do not appear in any package cannot be present in + an image later on in the build process. + Ideally, all installed files should be packaged or not + installed at all. + These files can be deleted at the end of + do_install if the files are not + needed in any package. + + la: + Checks .la files for any TMPDIR + paths. + Any .la file containing these paths is incorrect since + libtool adds the correct sysroot prefix when using the + files automatically itself. + ldflags: + Ensures that the binaries were linked with the + LDFLAGS + options provided by the build system. + If this test fails, check that the LDFLAGS variable + is being passed to the linker command. + libdir: + Checks for libraries being installed into incorrect + (possibly hardcoded) installation paths. + For example, this test will catch recipes that install + /lib/bar.so when + ${base_libdir} is "lib32". + Another example is when recipes install + /usr/lib64/foo.so when + ${libdir} is "/usr/lib". + + libexec: + Checks if a package contains files in + /usr/libexec. + This check is not performed if the + libexecdir variable has been set + explicitly to /usr/libexec. + + packages-list: + Checks for the same package being listed multiple times through + the PACKAGES + variable value. + Installing the package in this manner can cause errors during + packaging. + + perm-config: + Reports lines in fs-perms.txt that have + an invalid format. + + perm-line: + Reports lines in fs-perms.txt that have + an invalid format. + + perm-link: + Reports lines in fs-perms.txt that + specify 'link' where the specified target already exists. + + perms: + Currently, this check is unused but reserved. + + pkgconfig: + Checks .pc files for any + TMPDIR/WORKDIR + paths. + Any .pc file containing these paths is incorrect + since pkg-config itself adds the correct sysroot prefix + when the files are accessed. + pkgname: + Checks that all packages in + PACKAGES + have names that do not contain invalid characters (i.e. + characters other than 0-9, a-z, ., +, and -). + + pkgv-undefined: + Checks to see if the PKGV variable + is undefined during + do_package. + + pkgvarcheck: + Checks through the variables + RDEPENDS, + RRECOMMENDS, + RSUGGESTS, + RCONFLICTS, + RPROVIDES, + RREPLACES, + FILES, + ALLOW_EMPTY, + pkg_preinst, + pkg_postinst, + pkg_prerm + and pkg_postrm, and reports if there are + variable sets that are not package-specific. + Using these variables without a package suffix is bad practice, + and might unnecessarily complicate dependencies of other packages + within the same recipe or have other unintended consequences. + + pn-overrides: + Checks that a recipe does not have a name + (PN) value + that appears in + OVERRIDES. + If a recipe is named such that its PN + value matches something already in + OVERRIDES (e.g. PN + happens to be the same as + MACHINE + or + DISTRO), + it can have unexpected consequences. + For example, assignments such as + FILES_${PN} = "xyz" effectively turn into + FILES = "xyz". + + rpaths: + Checks for rpaths in the binaries that contain build system paths such + as TMPDIR. + If this test fails, bad -rpath options are being + passed to the linker commands and your binaries have potential security + issues. + split-strip: + Reports that splitting or stripping debug symbols from binaries + has failed. + + staticdev: + Checks for static library files (*.a) in + non-staticdev packages. + + symlink-to-sysroot: + Checks for symlinks in packages that point into + TMPDIR + on the host. + Such symlinks will work on the host, but are clearly invalid + when running on the target. + + textrel: + Checks for ELF binaries that contain relocations in their + .text sections, which can result in a + performance impact at runtime. + unsafe-references-in-binaries: + Reports when a binary installed in + ${base_libdir}, + ${base_bindir}, or + ${base_sbindir}, depends on another + binary installed under ${exec_prefix}. + This dependency is a concern if you want the system to remain + basically operable if /usr is mounted + separately and is not mounted. + + Defaults for binaries installed in + ${base_libdir}, + ${base_bindir}, and + ${base_sbindir} are + /lib, /bin, and + /sbin, respectively. + The default for a binary installed + under ${exec_prefix} is + /usr. + + + unsafe-references-in-scripts: + Reports when a script file installed in + ${base_libdir}, + ${base_bindir}, or + ${base_sbindir}, depends on files + installed under ${exec_prefix}. + This dependency is a concern if you want the system to remain + basically operable if /usr is mounted + separately and is not mounted. + + Defaults for binaries installed in + ${base_libdir}, + ${base_bindir}, and + ${base_sbindir} are + /lib, /bin, and + /sbin, respectively. + The default for a binary installed + under ${exec_prefix} is + /usr. + + + useless-rpaths: + Checks for dynamic library load paths (rpaths) in the binaries that + by default on a standard system are searched by the linker (e.g. + /lib and /usr/lib). + While these paths will not cause any breakage, they do waste space and + are unnecessary. + var-undefined: + Reports when variables fundamental to packaging (i.e. + WORKDIR, + DEPLOY_DIR, + D, + PN, and + PKGD) are + undefined during + do_package. + + version-going-backwards: + If Build History is enabled, reports when a package + being written out has a lower version than the previously + written package under the same name. + If you are placing output packages into a feed and + upgrading packages on a target system using that feed, the + version of a package going backwards can result in the target + system not correctly upgrading to the "new" version of the + package. + + If you are not using runtime package management on your + target system, then you do not need to worry about + this situation. + + + xorg-driver-abi: + Checks that all packages containing Xorg drivers have ABI + dependencies. + The xserver-xorg recipe provides driver + ABI names. + All drivers should depend on the ABI versions that they have + been built against. + Driver recipes that include + xorg-driver-input.inc + or xorg-driver-video.inc will + automatically get these versions. + Consequently, you should only need to explicitly add + dependencies to binary driver recipes. + + + +
+ +
+ <filename>insserv.bbclass</filename> + + + The insserv class + uses the insserv utility to update the order of + symbolic links in /etc/rc?.d/ within an image + based on dependencies specified by LSB headers in the + init.d scripts themselves. + +
+ +
+ <filename>kernel.bbclass</filename> + + + The kernel class handles building Linux kernels. + The class contains code to build all kernel trees. + All needed headers are staged into the + STAGING_KERNEL_DIR + directory to allow out-of-tree module builds using + the + module + class. + + + + This means that each built kernel module is packaged separately and inter-module + dependencies are created by parsing the modinfo output. + If all modules are required, then installing the kernel-modules + package installs all packages with modules and various other kernel packages + such as kernel-vmlinux. + + + + Various other classes are used by the kernel + and module classes internally including the + kernel-arch, + module-base, + and + linux-kernel-base + classes. + +
+ +
+ <filename>kernel-arch.bbclass</filename> + + + The kernel-arch class + sets the ARCH environment variable for Linux + kernel compilation (including modules). + +
+ +
+ <filename>kernel-module-split.bbclass</filename> + + + The kernel-module-split class + provides common functionality for splitting Linux kernel modules into + separate packages. + +
+ +
+ <filename>kernel-yocto.bbclass</filename> + + + The kernel-yocto class + provides common functionality for building from linux-yocto style + kernel source repositories. + +
+ +
+ <filename>lib_package.bbclass</filename> + + + The lib_package class + supports recipes that build libraries and produce executable + binaries, where those binaries should not be installed by default + along with the library. + Instead, the binaries are added to a separate + ${PN}-bin + package to make their installation optional. + +
+ +
+ <filename>license.bbclass</filename> + + + The license class provides license + manifest creation and license exclusion. + This class is enabled by default using the default value for the + INHERIT_DISTRO + variable. + +
+ +
+ <filename>linux-kernel-base.bbclass</filename> + + + The linux-kernel-base class + provides common functionality for recipes that build out of the Linux + kernel source tree. + These builds goes beyond the kernel itself. + For example, the Perf recipe also inherits this class. + +
+ +
+ <filename>logging.bbclass</filename> + + + The logging class provides the standard + shell functions used to log messages for various BitBake severity levels + (i.e. bbplain, bbnote, + bbwarn, bberror, + bbfatal, and bbdebug). + + + + This class is enabled by default since it is inherited by + the base class. + +
+ +
+ <filename>meta.bbclass</filename> + + + The meta class is inherited by recipes + that do not build any output packages themselves, but act as a "meta" + target for building other recipes. + +
+ +
+ <filename>metadata_scm.bbclass</filename> + + + The metadata_scm class provides functionality for + querying the branch and revision of a Source Code Manager (SCM) + repository. + + + + The base + class uses this class to print the revisions of each layer before + starting every build. + The metadata_scm class is enabled by default + because it is inherited by the base class. + +
+ +
+ <filename>mime.bbclass</filename> + + + The mime class generates the proper + post-install and post-remove (postinst/postrm) scriptlets for packages + that install MIME type files. + These scriptlets call update-mime-database to add + the MIME types to the shared database. + +
+ +
+ <filename>mirrors.bbclass</filename> + + + The mirrors class sets up some standard + MIRRORS entries + for source code mirrors. + These mirrors provide a fall-back path in case the upstream source + specified in + SRC_URI + within recipes is unavailable. + + + + This class is enabled by default since it is inherited by the + base class. + +
+ +
+ <filename>module.bbclass</filename> + + + The module class provides support for building + out-of-tree Linux kernel modules. + The class inherits the + module-base + and + kernel-module-split + classes, and implements the + do_compile + and + do_install + tasks. + The class provides everything needed to build and package a kernel + module. + + + + For general information on out-of-tree Linux kernel modules, see the + "Incorporating Out-of-Tree Modules" + section in the Yocto Project Linux Kernel Development Manual. + +
+ +
+ <filename>module-base.bbclass</filename> + + + The module-base class provides the base + functionality for building Linux kernel modules. + Typically, a recipe that builds software that includes one or + more kernel modules and has its own means of building + the module inherits this class as opposed to inheriting the + module + class. + +
+ +
+ <filename>multilib*.bbclass</filename> + + + The multilib* classes provide support + for building libraries with different target optimizations or target + architectures and installing them side-by-side in the same image. + + + + For more information on using the Multilib feature, see the + "Combining Multiple Versions of Library Files into One Image" + section in the Yocto Project Development Manual. + +
+ +
+ <filename>native.bbclass</filename> + + + The native class provides common + functionality for recipes that wish to build tools to run on the build + host (i.e. tools that use the compiler or other tools from the + build host). + + + + You can create a recipe that builds tools that run natively on the + host a couple different ways: + + Create a myrecipe-native.bb + that inherits the native class. + If you use this method, you must order the inherit statement + in the recipe after all other inherit statements so that the + native class is inherited last. + + Create or modify a target recipe that contains + the following: + + BBCLASSEXTEND = "native" + + Inside the recipe, use _class-native and + _class-target overrides to specify any + functionality specific to the respective native or target + case. + + + + + Although applied differently, the native class is + used with both methods. + The advantage of the second method is that you do not need to have two + separate recipes (assuming you need both) for native and target. + All common parts of the recipe are automatically shared. + +
+ +
+ <filename>nativesdk.bbclass</filename> + + + The nativesdk class provides common + functionality for recipes that wish to build tools to run as part of + an SDK (i.e. tools that run on + SDKMACHINE). + + + + You can create a recipe that builds tools that run on the SDK machine + a couple different ways: + + Create a myrecipe-nativesdk.bb + recipe that inherits the nativesdk class. + If you use this method, you must order the inherit statement + in the recipe after all other inherit statements so that the + nativesdk class is inherited last. + + Create a nativesdk variant + of any recipe by adding the following: + + BBCLASSEXTEND = "nativesdk" + + Inside the recipe, use _class-nativesdk and + _class-target overrides to specify any + functionality specific to the respective SDK machine or target + case. + + + + + Although applied differently, the nativesdk class + is used with both methods. + The advantage of the second method is that you do not need to have two + separate recipes (assuming you need both) for the SDK machine and the + target. + All common parts of the recipe are automatically shared. + +
+ +
+ <filename>oelint.bbclass</filename> + + + The oelint class is an + obsolete lint checking tool that exists in + meta/classes in the + Source Directory. + + + + A number of classes exist that are could be generally useful in + OE-Core but are never actually used within OE-Core itself. + The oelint class is one such example. + However, being aware of this class can reduce the proliferation of + different versions of similar classes across multiple layers. + +
+ +
+ <filename>own-mirrors.bbclass</filename> + + + The own-mirrors class makes it + easier to set up your own + PREMIRRORS + from which to first fetch source before attempting to fetch it from the + upstream specified in + SRC_URI + within each recipe. + + + + To use this class, inherit it globally and specify + SOURCE_MIRROR_URL. + Here is an example: + + INHERIT += "own-mirrors" + SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" + + You can specify only a single URL in + SOURCE_MIRROR_URL. + +
+ +
+ <filename>package.bbclass</filename> + + + The package class supports generating + packages from a build's output. + The core generic functionality is in + package.bbclass. + The code specific to particular package types resides in these + package-specific classes: + package_deb, + package_rpm, + package_ipk, + and + package_tar. + + + + You can control the list of resulting package formats by using the + PACKAGE_CLASSES + variable defined in your conf/local.conf + configuration file, which is located in the + Build Directory. + When defining the variable, you can specify one or more package types. + Since images are generated from packages, a packaging class is + needed to enable image generation. + The first class listed in this variable is used for image generation. + + + + If you take the optional step to set up a repository (package feed) + on the development host that can be used by Smart, you can + install packages from the feed while you are running the image + on the target (i.e. runtime installation of packages). + For more information, see the + "Using Runtime Package Management" + section in the Yocto Project Development Manual. + + + + The package-specific class you choose can affect build-time performance + and has space ramifications. + In general, building a package with IPK takes about thirty percent less + time as compared to using RPM to build the same or similar package. + This comparison takes into account a complete build of the package with + all dependencies previously built. + The reason for this discrepancy is because the RPM package manager + creates and processes more + Metadata than the + IPK package manager. + Consequently, you might consider setting + PACKAGE_CLASSES to "package_ipk" if you are + building smaller systems. + + + + Before making your package manager decision, however, you should + consider some further things about using RPM: + + + RPM starts to provide more abilities than IPK due to + the fact that it processes more Metadata. + For example, this information includes individual file types, + file checksum generation and evaluation on install, sparse file + support, conflict detection and resolution for Multilib systems, + ACID style upgrade, and repackaging abilities for rollbacks. + + + For smaller systems, the extra space used for the Berkeley + Database and the amount of metadata when using RPM can affect + your ability to perform on-device upgrades. + + + + + + You can find additional information on the effects of the package + class at these two Yocto Project mailing list links: + + + https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html + + https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html + + +
+ +
+ <filename>package_deb.bbclass</filename> + + + The package_deb class + provides support for creating packages that use the + .deb file format. + The class ensures the packages are written out to the + ${DEPLOY_DIR}/deb + directory in a .deb file format. + + + + This class inherits the + package + class and is enabled through the + PACKAGE_CLASSES + variable in the local.conf file. + +
+ +
+ <filename>package_ipk.bbclass</filename> + + + The package_ipk class + provides support for creating packages that use the + .ipk file format. + The class ensures the packages are written out to the + ${DEPLOY_DIR}/ipk + directory in a .ipk file format. + + + + This class inherits the + package + class and is enabled through the + PACKAGE_CLASSES + variable in the local.conf file. + +
+ +
+ <filename>package_rpm.bbclass</filename> + + + The package_rpm class + provides support for creating packages that use the + .rpm file format. + The class ensures the packages are written out to the + ${DEPLOY_DIR}/rpm + directory in a .rpm file format. + + + + This class inherits the + package + class and is enabled through the + PACKAGE_CLASSES + variable in the local.conf file. + +
+ +
+ <filename>package_tar.bbclass</filename> + + + The package_tar + class provides support for creating packages that use the + .tar file format. + The class ensures the packages are written out to the + ${DEPLOY_DIR}/tar + directory in a .tar file format. + + + + This class inherits the + package + class and is enabled through the + PACKAGE_CLASSES + variable in the local.conf file. + + You cannot specify the package_tar class + first using the PACKAGE_CLASSES variable. + You must use .deb, + .ipk, or .rpm file + formats for your image or SDK. + + +
+ +
+ <filename>packagedata.bbclass</filename> + + + The packagedata class provides + common functionality for reading pkgdata files + found in + PKGDATA_DIR. + These files contain information about each output package produced by + the OpenEmbedded build system. + + + + This class is enabled by default because it is inherited by the + package + class. + +
+ +
+ <filename>packagegroup.bbclass</filename> + + + The packagegroup class sets default values + appropriate for package group recipes (e.g. + PACKAGES, + PACKAGE_ARCH, + ALLOW_EMPTY, + and so forth). + It is highly recommended that all package group recipes inherit this class. + + + + For information on how to use this class, see the + "Customizing Images Using Custom Package Groups" + section in the Yocto Project Development Manual. + + + + Previously, this class was called the task class. + +
+ +
+ <filename>packageinfo.bbclass</filename> + + + The packageinfo class + gives a BitBake user interface the ability to retrieve information + about output packages from the pkgdata files. + + + + This class is enabled automatically when using the + Hob + user interface. + +
+ +
+ <filename>patch.bbclass</filename> + + + The patch class provides all functionality for + applying patches during the + do_patch + task. + + + + This class is enabled by default because it is inherited by the + base + class. + +
+ +
+ <filename>perlnative.bbclass</filename> + + + When inherited by a recipe, the perlnative class + supports using the native version of Perl built by the build system + rather than using the version provided by the build host. + +
+ +
+ <filename>pixbufcache.bbclass</filename> + + + The pixbufcache class generates the proper + post-install and post-remove (postinst/postrm) scriptlets for packages + that install pixbuf loaders, which are used with + gdk-pixbuf. + These scriptlets call update_pixbuf_cache + to add the pixbuf loaders to the cache. + Since the cache files are architecture-specific, + update_pixbuf_cache is run using QEMU if the + postinst scriptlets need to be run on the build host during image + creation. + + + + If the pixbuf loaders being installed are in packages other + than the recipe's main package, set + PIXBUF_PACKAGES + to specify the packages containing the loaders. + +
+ +
+ <filename>pkgconfig.bbclass</filename> + + + The pkg-config class provides a standard way to get + header and library information. + This class aims to smooth integration of + pkg-config into libraries that use it. + + + + During staging, BitBake installs pkg-config data into the + sysroots/ directory. + By making use of sysroot functionality within pkg-config, + this class no longer has to manipulate the files. + +
+ +
+ <filename>populate_sdk.bbclass</filename> + + + The populate_sdk class provides support for + SDK-only recipes. + For information on advantages gained when building a cross-development + toolchain using the + do_populate_sdk + task, see the + "Optionally Building a Toolchain Installer" + section in the Yocto Project Application Developer's Guide. + +
+ +
+ <filename>populate_sdk_*.bbclass</filename> + + + The populate_sdk_* classes support SDK creation + and consist of the following classes: + + populate_sdk_base: + The base class supporting SDK creation under all package + managers (i.e. DEB, RPM, and opkg). + populate_sdk_deb: + Supports creation of the SDK given the Debian package manager. + + populate_sdk_rpm: + Supports creation of the SDK given the RPM package manager. + + populate_sdk_ipk: + Supports creation of the SDK given the opkg (IPK format) + package manager. + + + + + + The populate_sdk_base class inherits the + appropriate populate_sdk_* (i.e. + deb, rpm, and + ipk) based on + IMAGE_PKGTYPE. + + + + The base class ensures all source and destination directories are + established and then populates the SDK. + After populating the SDK, the populate_sdk_base + class constructs two sysroots: + ${SDK_ARCH}-nativesdk, + which contains the cross-compiler and associated tooling, and the + target, which contains a target root filesystem that is configured for + the SDK usage. + These two images reside in + SDK_OUTPUT, + which consists of the following: + + ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs + ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs + + + + + Finally, the base populate SDK class creates the toolchain + environment setup script, the tarball of the SDK, and the installer. + + + + The respective populate_sdk_deb, + populate_sdk_rpm, and + populate_sdk_ipk classes each support the + specific type of SDK. + These classes are inherited by and used with the + populate_sdk_base class. + + + + For more information on the cross-development toolchain + generation, see the + "Cross-Development Toolchain Generation" + section. + For information on advantages gained when building a + cross-development toolchain using the + do_populate_sdk + task, see the + "Optionally Building a Toolchain Installer" + section in the Yocto Project Application Developer's Guide. + +
+ +
+ <filename>prexport.bbclass</filename> + + + The prexport class provides functionality for + exporting + PR values. + + This class is not intended to be used directly. + Rather, it is enabled when using + "bitbake-prserv-tool export". + + +
+ +
+ <filename>primport.bbclass</filename> + + + The primport class provides functionality for + importing + PR values. + + This class is not intended to be used directly. + Rather, it is enabled when using + "bitbake-prserv-tool import". + + +
+ +
+ <filename>prserv.bbclass</filename> + + + The prserv class provides functionality for + using a + PR service + in order to automatically manage the incrementing of the + PR variable for + each recipe. + + + + This class is enabled by default because it is inherited by the + package + class. + However, the OpenEmbedded build system will not enable the + functionality of this class unless + PRSERV_HOST + has been set. + +
+ +
+ <filename>ptest.bbclass</filename> + + + The ptest class provides functionality for + packaging and installing runtime tests for recipes that build software + that provides these tests. + + + + This class is intended to be inherited by individual recipes. + However, the class' functionality is largely disabled unless "ptest" + appears in + DISTRO_FEATURES. + See the + "Testing Packages With ptest" + section in the Yocto Project Development Manual for more information + on ptest. + +
+ +
+ <filename>ptest-gnome.bbclass</filename> + + + Enables package tests (ptests) specifically for GNOME packages, + which have tests intended to be executed with + gnome-desktop-testing. + + + + For information on setting up and running ptests, see the + "Testing Packages With ptest" + section in the Yocto Project Development Manual. + +
+ +
+ <filename>python-dir.bbclass</filename> + + + The python-dir class provides the base version, + location, and site package location for Python. + +
+ +
+ <filename>pythonnative.bbclass</filename> + + + When inherited by a recipe, the pythonnative class + supports using the native version of Python built by the build system + rather than using the version provided by the build host. + +
+ +
+ <filename>qemu.bbclass</filename> + + + The qemu class provides functionality for recipes + that either need QEMU or test for the existence of QEMU. + Typically, this class is used to run programs for a target system on + the build host using QEMU's application emulation mode. + +
+ +
+ <filename>qmake*.bbclass</filename> + + + The qmake* classes support recipes that + need to build software that uses Qt's qmake + build system and are comprised of the following: + + qmake_base: + Provides base functionality for all versions of + qmake. + qmake2: + Extends base functionality for qmake 2.x as + used by Qt 4.x. + + + + + If you need to set any configuration variables or pass any options to + qmake, you can add these to the + EXTRA_QMAKEVARS_PRE + or + EXTRA_QMAKEVARS_POST + variables, depending on whether the arguments need to be before or + after the .pro file list on the command line, + respectively. + + + + By default, all .pro files are built. + If you want to specify your own subset of .pro + files to be built, specify them in the + QMAKE_PROFILES + variable. + +
+ +
+ <filename>qt4*.bbclass</filename> + + + The qt4* classes support recipes that need to + build software that uses the Qt development framework version 4.x + and consist of the following: + + qt4e: + Supports building against Qt/Embedded, which uses the + framebuffer for graphical output. + qt4x11: + Supports building against Qt/X11. + + + + + The classes inherit the + qmake2 + class. + +
+ +
+ <filename>relocatable.bbclass</filename> + + + The relocatable class enables relocation of + binaries when they are installed into the sysroot. + + + + This class makes use of the + chrpath + class and is used by both the + cross + and + native + classes. + +
+ +
+ <filename>report-error.bbclass</filename> + + + The report-error class supports enabling the + error reporting tool, + which allows you to submit build error information to a central + database. + + + + The class collects debug information for recipe, recipe version, task, + machine, distro, build system, target system, host distro, branch, + commit, and log. + From the information, report files using a JSON format are created and + stored in + ${LOG_DIR}/error-report. + +
+ +
+ <filename>rm_work.bbclass</filename> + + + The rm_work class supports deletion of temporary + workspace, which can ease your hard drive demands during builds. + + + + The OpenEmbedded build system can use a substantial amount of disk + space during the build process. + A portion of this space is the work files under the + ${TMPDIR}/work directory for each recipe. + Once the build system generates the packages for a recipe, the work + files for that recipe are no longer needed. + However, by default, the build system preserves these files + for inspection and possible debugging purposes. + If you would rather have these files deleted to save disk space + as the build progresses, you can enable rm_work + by adding the following to your local.conf file, + which is found in the + Build Directory. + + INHERIT += "rm_work" + + If you are modifying and building source code out of the work directory + for a recipe, enabling rm_work will potentially + result in your changes to the source being lost. + To exclude some recipes from having their work directories deleted by + rm_work, you can add the names of the recipe or + recipes you are working on to the RM_WORK_EXCLUDE + variable, which can also be set in your local.conf + file. + Here is an example: + + RM_WORK_EXCLUDE += "busybox glibc" + + +
+ +
+ <filename>rootfs*.bbclass</filename> + + + The rootfs* classes support creating + the root filesystem for an image and consist of the following classes: + + + The rootfs_deb class, which supports + creation of root filesystems for images built using + .deb packages. + + The rootfs_rpm class, which supports + creation of root filesystems for images built using + .rpm packages. + + The rootfs_ipk class, which supports + creation of root filesystems for images built using + .ipk packages. + + + + + The root filesystem is created from packages using one of the + rootfs*.bbclass files as determined by the + PACKAGE_CLASSES + variable. + + + + For information on how root filesystem images are created, see the + "Image Generation" + section. + +
+ +
+ <filename>sanity.bbclass</filename> + + + The sanity class checks to see if prerequisite + software is present on the host system so that users can be notified + of potential problems that might affect their build. + The class also performs basic user configuration checks from + the local.conf configuration file to + prevent common mistakes that cause build failures. + Distribution policy usually determines whether to include this class. + +
+ +
+ <filename>scons.bbclass</filename> + + + The scons class supports recipes that need to + build software that uses the SCons build system. + You can use the + EXTRA_OESCONS + variable to specify additional configuration options you want to pass + SCons command line. + +
+ +
+ <filename>sdl.bbclass</filename> + + + The sdl class supports recipes that need to build + software that uses the Simple DirectMedia Layer (SDL) library. + +
+ +
+ <filename>setuptools.bbclass</filename> + + + The setuptools class supports Python + version 2.x extensions that use build systems based on + setuptools. + If your recipe uses these build systems, the recipe needs to + inherit the setuptools class. + +
+ +
+ <filename>setuptools3.bbclass</filename> + + + The setuptools3 class supports Python + version 3.x extensions that use build systems based on + setuptools3. + If your recipe uses these build systems, the recipe needs to + inherit the setuptools3 class. + +
+ +
+ <filename>sip.bbclass</filename> + + + The sip class + supports recipes that build or package SIP-based Python bindings. + +
+ +
+ <filename>siteconfig.bbclass</filename> + + + The siteconfig class + provides functionality for handling site configuration. + The class is used by the + autotools + class to accelerate the + do_configure + task. + +
+ +
+ <filename>siteinfo.bbclass</filename> + + + The siteinfo class provides information about + the targets that might be needed by other classes or recipes. + + + + As an example, consider Autotools, which can require tests that must + execute on the target hardware. + Since this is not possible in general when cross compiling, site + information is used to provide cached test results so these tests can + be skipped over but still make the correct values available. + The + meta/site directory + contains test results sorted into different categories such as + architecture, endianness, and the libc used. + Site information provides a list of files containing data relevant to + the current build in the + CONFIG_SITE variable + that Autotools automatically picks up. + + + + The class also provides variables like + SITEINFO_ENDIANNESS + and SITEINFO_BITS + that can be used elsewhere in the metadata. + + + + Because the + base class + includes the siteinfo class, it is always active. + +
+ +
+ <filename>spdx.bbclass</filename> + + + The spdx class integrates real-time license + scanning, generation of SPDX standard output, and verification + of license information during the build. + + This class is currently at the prototype stage in the 1.6 + release. + + +
+ +
+ <filename>sstate.bbclass</filename> + + + The sstate class provides support for Shared + State (sstate). + By default, the class is enabled through the + INHERIT_DISTRO + variable's default value. + + + + For more information on sstate, see the + "Shared State Cache" + section. + +
+ +
+ <filename>staging.bbclass</filename> + + + The staging class provides support for staging + files into the sysroot during the + do_populate_sysroot + task. + The class is enabled by default because it is inherited by the + base + class. + +
+ +
+ <filename>syslinux.bbclass</filename> + + + The syslinux class provides syslinux-specific + functions for building bootable images. + + + + The class supports the following variables: + + INITRD: + Indicates list of filesystem images to concatenate and use as + an initial RAM disk (initrd). + This variable is optional. + ROOTFS: + Indicates a filesystem image to include as the root filesystem. + This variable is optional. + AUTO_SYSLINUXMENU: + Enables creating an automatic menu when set to "1". + + LABELS: + Lists targets for automatic configuration. + + APPEND: + Lists append string overrides for each label. + + SYSLINUX_OPTS: + Lists additional options to add to the syslinux file. + Semicolon characters separate multiple options. + + SYSLINUX_SPLASH: + Lists a background for the VGA boot menu when you are using the + boot menu. + SYSLINUX_DEFAULT_CONSOLE: + Set to "console=ttyX" to change kernel boot default console. + + SYSLINUX_SERIAL: + Sets an alternate serial port. + Or, turns off serial when the variable is set with an + empty string. + SYSLINUX_SERIAL_TTY: + Sets an alternate "console=tty..." kernel boot argument. + + + +
+ +
+ <filename>systemd.bbclass</filename> + + + The systemd class provides support for recipes + that install systemd unit files. + + + + The functionality for this class is disabled unless you have "systemd" + in + DISTRO_FEATURES. + + + + Under this class, the recipe or Makefile (i.e. whatever the recipe is + calling during the + do_install + task) installs unit files into + ${D}${systemd_unitdir}/system. + If the unit files being installed go into packages other than the + main package, you need to set + SYSTEMD_PACKAGES + in your recipe to identify the packages in which the files will be + installed. + + + + You should set + SYSTEMD_SERVICE + to the name of the service file. + You should also use a package name override to indicate the package + to which the value applies. + If the value applies to the recipe's main package, use + ${PN}. + Here is an example from the connman recipe: + + SYSTEMD_SERVICE_${PN} = "connman.service" + + Services are set up to start on boot automatically unless + you have set + SYSTEMD_AUTO_ENABLE + to "disable". + + + + For more information on systemd, see the + "Selecting an Initialization Manager" + section in the Yocto Project Development Manual. + +
+ +
+ <filename>terminal.bbclass</filename> + + + The terminal class provides support for starting + a terminal session. + The + OE_TERMINAL + variable controls which terminal emulator is used for the session. + + + + Other classes use the terminal class anywhere a + separate terminal session needs to be started. + For example, the + patch + class assuming + PATCHRESOLVE + is set to "user", the + cml1 + class, and the + devshell + class all use the terminal class. + +
+ +
+ <filename>testimage.bbclass</filename> + + + The testimage class supports running automated + tests against images using QEMU and on actual hardware. + The class handles loading the tests and starting the image. + + + + To use the class, you need to perform steps to set up the + environment. + The tests are commands that run on the target system over + ssh. + they are written in Python and make use of the + unittest module. + + + + For information on how to enable, run, and create new tests, see the + "Performing Automated Runtime Testing" + section. + +
+ +
+ <filename>texinfo.bbclass</filename> + + + This class should be inherited by recipes whose upstream packages + invoke the texinfo utilities at build-time. + Native and cross recipes are made to use the dummy scripts provided + by texinfo-dummy-native, for improved performance. + Target architecture recipes use the genuine + Texinfo utilities. + By default, they use the Texinfo utilities on the host system. + + If you want to use the Texinfo recipe shipped with the build + system, you can remove "texinfo-native" from + ASSUME_PROVIDED + and makeinfo from + SANITY_REQUIRED_UTILITIES. + + +
+ +
+ <filename>tinderclient.bbclass</filename> + + + The tinderclient class submits build results to + an external Tinderbox instance. + + This class is currently unmaintained. + + +
+ +
+ <filename>toaster.bbclass</filename> + + + The toaster class collects information about + packages and images and sends them as events that the BitBake + user interface can receive. + The class is enabled when the Toaster user interface is running. + + + + This class is not intended to be used directly. + +
+ +
+ <filename>toolchain-scripts.bbclass</filename> + + + The toolchain-scripts class provides the scripts + used for setting up the environment for installed SDKs. + +
+ +
+ <filename>typecheck.bbclass</filename> + + + The typecheck class provides support for + validating the values of variables set at the configuration level + against their defined types. + The OpenEmbedded build system allows you to define the type of a + variable using the "type" varflag. + Here is an example: + + IMAGE_FEATURES[type] = "list" + + +
+ +
+ <filename>uboot-config.bbclass</filename> + + + The uboot-config class provides support for + U-Boot configuration for a machine. + Specify the machine in your recipe as follows: + + UBOOT_CONFIG ??= <default> + UBOOT_CONFIG[foo] = "config,images" + + You can also specify the machine using this method: + + UBOOT_MACHINE = "config" + + See the + UBOOT_CONFIG + and + UBOOT_MACHINE + variables for additional information. + +
+ +
+ <filename>uninative.bbclass</filename> + + + Provides a means of reusing native/cross over + multiple distros. + + Currently, the method used by the uninative + class is experimental. + + For more information, see the commit message + here. + +
+ +
+ <filename>update-alternatives.bbclass</filename> + + + The update-alternatives class helps the + alternatives system when multiple sources provide the same command. + This situation occurs when several programs that have the same or + similar function are installed with the same name. + For example, the ar command is available from the + busybox, binutils and + elfutils packages. + The update-alternatives class handles + renaming the binaries so that multiple packages can be installed + without conflicts. + The ar command still works regardless of which + packages are installed or subsequently removed. + The class renames the conflicting binary in each package and symlinks + the highest priority binary during installation or removal of packages. + + + + To use this class, you need to define a number of variables: + + ALTERNATIVE + + ALTERNATIVE_LINK_NAME + + ALTERNATIVE_TARGET + + ALTERNATIVE_PRIORITY + + + These variables list alternative commands needed by a package, + provide pathnames for links, default links for targets, and + so forth. + For details on how to use this class, see the comments in the + update-alternatives.bbclass. + + + + You can use the update-alternatives command + directly in your recipes. + However, this class simplifies things in most cases. + +
+ +
+ <filename>update-rc.d.bbclass</filename> + + + The update-rc.d class uses + update-rc.d to safely install an + initialization script on behalf of the package. + The OpenEmbedded build system takes care of details such as making + sure the script is stopped before a package is removed and started when + the package is installed. + + + + Three variables control this class: + INITSCRIPT_PACKAGES, + INITSCRIPT_NAME and + INITSCRIPT_PARAMS. + See the variable links for details. + +
+ +
+ <filename>useradd.bbclass</filename> + + + The useradd class supports the addition of users + or groups for usage by the package on the target. + For example, if you have packages that contain system services that + should be run under their own user or group, you can use this class to + enable creation of the user or group. + The meta-skeleton/recipes-skeleton/useradd/useradd-example.bb + recipe in the Source Directory + provides a simple example that shows how to add three + users and groups to two packages. + See the useradd-example.bb recipe for more + information on how to use this class. + + + + The useradd class supports the + USERADD_PACKAGES, + USERADD_PARAM, + GROUPADD_PARAM, + and + GROUPMEMS_PARAM + variables. + +
+ +
+ <filename>useradd-staticids.bbclass</filename> + + + The useradd-staticids class supports the addition + of users or groups that have static user identification + (uid) and group identification + (gid) values. + + + + The default behavior of the OpenEmbedded build system for assigning + uid and gid values when + packages add users and groups during package install time is to + add them dynamically. + This works fine for programs that do not care what the values of the + resulting users and groups become. + In these cases, the order of the installation determines the final + uid and gid values. + However, if non-deterministic + uid and gid values are a + problem, you can override the default, dynamic application of these + values by setting static values. + When you set static values, the OpenEmbedded build system looks in + BBPATH for + files/passwd and files/group + files for the values. + + + + To use static uid and gid + values, you need to set some variables. + See the + USERADDEXTENSION, + USERADD_UID_TABLES, + USERADD_GID_TABLES, + and + USERADD_ERROR_DYNAMIC + variables. + You can also see the + useradd + class for additional information. + + + Notes + You do not use this class directly. + You either enable or disable the class by setting the + USERADDEXTENSION variable. + If you enable or disable the class in a configured system, + TMPDIR + might contain incorrect uid and + gid values. + Deleting the TMPDIR directory + will correct this condition. + +
+ +
+ <filename>utility-tasks.bbclass</filename> + + + The utility-tasks class provides support for + various "utility" type tasks that are applicable to all recipes, + such as + do_clean and + do_listtasks. + + + + This class is enabled by default because it is inherited by + the + base + class. + +
+ +
+ <filename>utils.bbclass</filename> + + + The utils class provides some useful Python + functions that are typically used in inline Python expressions + (e.g. ${@...}). + One example use is for bb.utils.contains(). + + + + This class is enabled by default because it is inherited by the + base + class. + +
+ +
+ <filename>vala.bbclass</filename> + + + The vala class supports recipes that need to + build software written using the Vala programming language. + +
+ +
+ <filename>waf.bbclass</filename> + + + The waf class supports recipes that need to build + software that uses the Waf build system. + You can use the + EXTRA_OECONF + variable to specify additional configuration options to be passed on + the Waf command line. + +
+ + + + +
+ diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml new file mode 100644 index 0000000000..230cabd155 --- /dev/null +++ b/documentation/ref-manual/ref-features.xml @@ -0,0 +1,420 @@ + %poky; ] > + + + Features + + + This chapter provides a reference of shipped machine and distro features + you can include as part of your image, a reference on image features you can + select, and a reference on feature backfilling. + + + + Features provide a mechanism for working out which packages + should be included in the generated images. + Distributions can select which features they want to support through the + DISTRO_FEATURES + variable, which is set or appended to in a distribution's configuration file such as + poky.conf, + poky-tiny.conf, + poky-lsb.conf and so forth. + Machine features are set in the + MACHINE_FEATURES + variable, which is set in the machine configuration file and + specifies the hardware features for a given machine. + + + + These two variables combine to work out which kernel modules, + utilities, and other packages to include. + A given distribution can support a selected subset of features so some machine features might not + be included if the distribution itself does not support them. + + + + One method you can use to determine which recipes are checking to see if a + particular feature is contained or not is to grep through + the Metadata + for the feature. + Here is an example that discovers the recipes whose build is potentially + changed based on a given feature: + + $ cd poky + $ git grep 'contains.*MACHINE_FEATURES.*feature' + + + +
+ Machine Features + + + The items below are features you can use with + MACHINE_FEATURES. + Features do not have a one-to-one correspondence to packages, and they can + go beyond simply controlling the installation of a package or packages. + Sometimes a feature can influence how certain recipes are built. + For example, a feature might determine whether a particular configure option + is specified within the + do_configure + task for a particular recipe. + + + + This feature list only represents features as shipped with the Yocto Project metadata: + + acpi: Hardware has ACPI (x86/x86_64 only) + + alsa: Hardware has ALSA audio drivers + + apm: Hardware uses APM (or APM emulation) + + bluetooth: Hardware has integrated BT + + efi: Support for booting through EFI + + ext2: Hardware HDD or Microdrive + + irda: Hardware has IrDA support + + keyboard: Hardware has a keyboard + + pcbios: Support for booting through BIOS + + pci: Hardware has a PCI bus + + pcmcia: Hardware has PCMCIA or CompactFlash sockets + + phone: Mobile phone (voice) support + + qvga: Machine has a QVGA (320x240) display + + rtc: Machine has a Real-Time Clock + + screen: Hardware has a screen + + serial: Hardware has serial support (usually RS232) + + touchscreen: Hardware has a touchscreen + + usbgadget: Hardware is USB gadget device capable + + usbhost: Hardware is USB Host capable + + vfat: FAT file system support + + wifi: Hardware has integrated WiFi + + + +
+ +
+ Distro Features + + + The items below are features you can use with + DISTRO_FEATURES + to enable features across your distribution. + Features do not have a one-to-one correspondence to packages, + and they can go beyond simply controlling the installation of a + package or packages. + In most cases, the presence or absence of a feature translates to + the appropriate option supplied to the configure script during the + do_configure + task for the recipes that optionally + support the feature. + + + + Some distro features are also machine features. + These select features make sense to be controlled both at + the machine and distribution configuration level. + See the + COMBINED_FEATURES + variable for more information. + + + + This list only represents features as shipped with the Yocto Project metadata: + + alsa: Include ALSA support + (OSS compatibility kernel modules installed if available). + + bluetooth: Include + bluetooth support (integrated BT only). + cramfs: Include CramFS + support. + directfb: + Include DirectFB support. + + ext2: Include tools for + supporting for devices with internal HDD/Microdrive for + storing files (instead of Flash only devices). + + ipsec: Include IPSec + support. + ipv6: Include IPv6 support. + + irda: Include IrDA support. + + keyboard: Include keyboard + support (e.g. keymaps will be loaded during boot). + + nfs: Include NFS client + support (for mounting NFS exports on device). + + opengl: + Include the Open Graphics Library, which is a + cross-language, multi-platform application programming + interface used for rendering two and three-dimensional + graphics. + pci: Include PCI bus + support. + pcmcia: Include + PCMCIA/CompactFlash support. + ppp: Include PPP dialup + support. + smbfs: Include SMB networks + client support (for mounting Samba/Microsoft Windows shares + on device). + systemd: Include support + for this init manager, which is a full + replacement of for init with parallel + starting of services, reduced shell overhead, and other + features. + This init manager is used by many + distributions. + usbgadget: Include USB + Gadget Device support (for USB networking/serial/storage). + + usbhost: Include USB Host + support (allows to connect external keyboard, mouse, + storage, network etc). + wayland: Include the + Wayland display server protocol and the library that + supports it. + wifi: Include WiFi support + (integrated only). + x11: Include the X server + and libraries. + + +
+ +
+ Image Features + + + The contents of images generated by the OpenEmbedded build system + can be controlled by the + IMAGE_FEATURES + and + EXTRA_IMAGE_FEATURES + variables that you typically configure in your image recipes. + Through these variables, you can add several different + predefined packages such as development utilities or packages with + debug information needed to investigate application problems or + profile applications. + + + + The following image features are available for all images: + + dbg-pkgs: + Installs debug symbol packages for all packages installed + in a given image. + + debug-tweaks: + Makes an image suitable for development (e.g. + allows root logins without passwords). + + dev-pkgs: + Installs development packages (headers and extra library + links) for all packages installed in a given image. + + doc-pkgs: Installs + documentation packages for all packages installed in a + given image. + + package-management: + Installs package management tools and preserves the package + manager database. + + ptest-pkgs: + Installs ptest packages for all ptest-enabled recipes. + + read-only-rootfs: + Creates an image whose root filesystem is read-only. + See the + "Creating a Read-Only Root Filesystem" + section in the Yocto Project Development Manual for more + information. + + splash: + Enables showing a splash screen during boot. + By default, this screen is provided by + psplash, which does allow + customization. + If you prefer to use an alternative splash screen package, + you can do so by setting the SPLASH + variable to a different package name (or names) within the + image recipe or at the distro configuration level. + + staticdev-pkgs: + Installs static development packages, which are + static libraries (i.e. *.a files), for + all packages installed in a given image. + + + + + + Some image features are available only when you inherit the + core-image + class. + The current list of these valid features is as follows: + + eclipse-debug: Provides + Eclipse remote debugging support. + + hwcodecs: Installs + hardware acceleration codecs. + + nfs-server: + Installs an NFS server. + + qt4-pkgs: + Supports Qt4/X11 and demo applications. + + ssh-server-dropbear: + Installs the Dropbear minimal SSH server. + + ssh-server-openssh: + Installs the OpenSSH SSH server, which is more + full-featured than Dropbear. + Note that if both the OpenSSH SSH server and the Dropbear + minimal SSH server are present in + IMAGE_FEATURES, then OpenSSH will take + precedence and Dropbear will not be installed. + + tools-debug: + Installs debugging tools such as + strace and gdb. + For information on GDB, see the + "Debugging With the GNU Project Debugger (GDB) Remotely" + section in the Yocto Project Development Manual. + For information on tracing and profiling, see the + Yocto Project Profiling and Tracing Manual. + + tools-profile: + Installs profiling tools such as + oprofile, exmap, + and LTTng. + For general information on user-space tools, see the + "User-Space Tools" + section in the Yocto Project Application Developer's + Guide. + + tools-sdk: + Installs a full SDK that runs on the device. + + tools-testapps: + Installs device testing tools (e.g. touchscreen debugging). + + x11: + Installs the X server. + + x11-base: + Installs the X server with a minimal environment. + + x11-sato: + Installs the OpenedHand Sato environment. + + + + +
+ +
+ Feature Backfilling + + + Sometimes it is necessary in the OpenEmbedded build system to extend + MACHINE_FEATURES + or DISTRO_FEATURES + to control functionality that was previously enabled and not able + to be disabled. + For these cases, we need to add an + additional feature item to appear in one of these variables, + but we do not want to force developers who have existing values + of the variables in their configuration to add the new feature + in order to retain the same overall level of functionality. + Thus, the OpenEmbedded build system has a mechanism to + automatically "backfill" these added features into existing + distro or machine configurations. + You can see the list of features for which this is done by + finding the + DISTRO_FEATURES_BACKFILL + and MACHINE_FEATURES_BACKFILL + variables in the meta/conf/bitbake.conf file. + + + + Because such features are backfilled by default into all + configurations as described in the previous paragraph, developers + who wish to disable the new features need to be able to selectively + prevent the backfilling from occurring. + They can do this by adding the undesired feature or features to the + DISTRO_FEATURES_BACKFILL_CONSIDERED + or MACHINE_FEATURES_BACKFILL_CONSIDERED + variables for distro features and machine features respectively. + + + + Here are two examples to help illustrate feature backfilling: + + The "pulseaudio" distro feature option: + Previously, PulseAudio support was enabled within the Qt and + GStreamer frameworks. + Because of this, the feature is backfilled and thus + enabled for all distros through the + DISTRO_FEATURES_BACKFILL + variable in the meta/conf/bitbake.conf file. + However, your distro needs to disable the feature. + You can disable the feature without affecting + other existing distro configurations that need PulseAudio support + by adding "pulseaudio" to + DISTRO_FEATURES_BACKFILL_CONSIDERED + in your distro's .conf file. + Adding the feature to this variable when it also + exists in the DISTRO_FEATURES_BACKFILL + variable prevents the build system from adding the feature to + your configuration's DISTRO_FEATURES, effectively disabling + the feature for that particular distro. + The "rtc" machine feature option: + Previously, real time clock (RTC) support was enabled for all + target devices. + Because of this, the feature is backfilled and thus enabled + for all machines through the MACHINE_FEATURES_BACKFILL + variable in the meta/conf/bitbake.conf file. + However, your target device does not have this capability. + You can disable RTC support for your device without + affecting other machines that need RTC support + by adding the feature to your machine's + MACHINE_FEATURES_BACKFILL_CONSIDERED + list in the machine's .conf file. + Adding the feature to this variable when it also + exists in the MACHINE_FEATURES_BACKFILL + variable prevents the build system from adding the feature to + your configuration's MACHINE_FEATURES, effectively + disabling RTC support for that particular machine. + + +
+
+ + diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml new file mode 100644 index 0000000000..d15ca5b93a --- /dev/null +++ b/documentation/ref-manual/ref-images.xml @@ -0,0 +1,169 @@ + %poky; ] > + + + Images + + + The OpenEmbedded build system provides several example + images to satisfy different needs. + When you issue the bitbake command you provide a “top-level” recipe + that essentially begins the build for the type of image you want. + + + + Building an image without GNU General Public License Version 3 (GPLv3), + GNU Lesser General Public License Version 3 (LGPLv3), and the + GNU Affero General Public License Version 3 (AGPL-3.0) components + is only supported for minimal and base images. + Furthermore, if you are going to build an image using non-GPLv3 and + similarly licensed components, you must make the following changes in + the local.conf file before using the BitBake + command to build the minimal or base image: + + 1. Comment out the EXTRA_IMAGE_FEATURES line + 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" + + + + + From within the poky Git repository, you can use + the following command to display the list of directories within the + Source Directory + that containe image recipe files: + + $ ls meta*/recipes*/images/*.bb + + + + + Following is a list of supported recipes: + + build-appliance-image: + An example virtual machine that contains all the pieces required to + run builds using the build system as well as the build system itself. + You can boot and run the image using either the + VMware Player + or VMware Workstation. + For more information on this image, see the + Build Appliance page on + the Yocto Project website. + core-image-base: + A console-only image that fully supports the target device hardware. + core-image-clutter: + An image with support for the Open GL-based toolkit Clutter, which enables development of + rich and animated graphical user interfaces. + core-image-directfb: + An image that uses directfb instead of X11. + + core-image-full-cmdline: + A console-only image with more full-featured Linux system + functionality installed. + core-image-lsb: + An image that conforms to the Linux Standard Base (LSB) + specification. + This image requires a distribution configuration that + enables LSB compliance (e.g. poky-lsb). + If you build core-image-lsb without that + configuration, the image will not be LSB-compliant. + + core-image-lsb-dev: + A core-image-lsb image that is suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + This image requires a distribution configuration that + enables LSB compliance (e.g. poky-lsb). + If you build core-image-lsb-dev without that + configuration, the image will not be LSB-compliant. + + core-image-lsb-sdk: + A core-image-lsb that includes everything in + meta-toolchain but also includes development headers and libraries + to form a complete standalone SDK. + This image requires a distribution configuration that + enables LSB compliance (e.g. poky-lsb). + If you build core-image-lsb-sdk without that + configuration, the image will not be LSB-compliant. + This image is suitable for development using the target. + core-image-minimal: + A small image just capable of allowing a device to boot. + core-image-minimal-dev: + A core-image-minimal image suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + + core-image-minimal-initramfs: + A core-image-minimal image that has the Minimal RAM-based + Initial Root Filesystem (initramfs) as part of the kernel, + which allows the system to find the first “init” program more efficiently. + See the + PACKAGE_INSTALL + variable for additional information helpful when working with + initramfs images. + + core-image-minimal-mtdutils: + A core-image-minimal image that has support + for the Minimal MTD Utilities, which let the user interact with the + MTD subsystem in the kernel to perform operations on flash devices. + + core-image-rt: + A core-image-minimal image plus a real-time test suite and + tools appropriate for real-time use. + core-image-rt-sdk: + A core-image-rt image that includes everything in + meta-toolchain. + The image also includes development headers and libraries to form a complete + stand-alone SDK and is suitable for development using the target. + + core-image-sato: + An image with Sato support, a mobile environment and visual style that works well + with mobile devices. + The image supports X11 with a Sato theme and applications such as + a terminal, editor, file manager, media player, and so forth. + + core-image-sato-dev: + A core-image-sato image suitable for development + using the host. + The image includes libraries needed to build applications on the device itself, + testing and profiling tools, and debug symbols. + This image was formerly core-image-sdk. + + core-image-sato-sdk: + A core-image-sato image that includes everything in meta-toolchain. + The image also includes development headers and libraries to form a complete standalone SDK + and is suitable for development using the target. + core-image-testmaster: + A "master" image designed to be used for automated runtime testing. + Provides a "known good" image that is deployed to a separate + partition so that you can boot into it and use it to deploy a + second image to be tested. + You can find more information about runtime testing in the + "Performing Automated Runtime Testing" + section in the Yocto Project Development Manual. + + core-image-testmaster-initramfs: + A RAM-based Initial Root Filesystem (initramfs) image tailored for + use with the core-image-testmaster image. + + core-image-weston: + A very basic Wayland image with a terminal. + This image provides the Wayland protocol libraries and the + reference Weston compositor. + For more information, see the + "Wayland" section. + + core-image-x11: + A very basic X11 image with a terminal. + + qt4e-demo-image: + An image that launches into the demo application for the embedded + (not based on X11) version of Qt. + + + + diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl new file mode 100644 index 0000000000..1bee3bd5d3 --- /dev/null +++ b/documentation/ref-manual/ref-manual-customization.xsl @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/ref-manual/ref-manual-eclipse-customization.xsl b/documentation/ref-manual/ref-manual-eclipse-customization.xsl new file mode 100644 index 0000000000..4e6b7997b8 --- /dev/null +++ b/documentation/ref-manual/ref-manual-eclipse-customization.xsl @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + A + + + diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml new file mode 100644 index 0000000000..bf9f65fb5e --- /dev/null +++ b/documentation/ref-manual/ref-manual.xml @@ -0,0 +1,160 @@ + %poky; ] > + + + + + + + + + + + + Yocto Project Reference Manual + + + + + Richard Purdie + + Linux Foundation + + richard.purdie@linuxfoundation.org + + + + + + + 4.0+git + 24 November 2010 + Released with the Yocto Project 0.9 Release + + + 1.0 + 6 April 2011 + Released with the Yocto Project 1.0 Release. + + + 1.0.1 + 23 May 2011 + Released with the Yocto Project 1.0.1 Release. + + + 1.1 + 6 October 2011 + Released with the Yocto Project 1.1 Release. + + + 1.2 + April 2012 + Released with the Yocto Project 1.2 Release. + + + 1.3 + October 2012 + Released with the Yocto Project 1.3 Release. + + + 1.4 + April 2013 + Released with the Yocto Project 1.4 Release. + + + 1.5 + October 2013 + Released with the Yocto Project 1.5 Release. + + + 1.5.1 + January 2014 + Released with the Yocto Project 1.5.1 Release. + + + 1.6 + April 2014 + Released with the Yocto Project 1.6 Release. + + + 1.7 + October 2014 + Released with the Yocto Project 1.7 Release. + + + 1.7.1 + January 2015 + Released with the Yocto Project 1.7.1 Release. + + + 1.7.2 + June 2015 + Released with the Yocto Project 1.7.2 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons. + + + For the latest version of this manual associated with this + Yocto Project release, see the + Yocto Project Reference Manual + from the Yocto Project website. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml new file mode 100644 index 0000000000..871cd294f6 --- /dev/null +++ b/documentation/ref-manual/ref-qa-checks.xml @@ -0,0 +1,1217 @@ + %poky; ] > + + +QA Error and Warning Messages + +
+ Introduction + + + When building a recipe, the OpenEmbedded build system performs + various QA checks on the output to ensure that common issues are + detected and reported. + Sometimes when you create a new recipe to build new software, + it will build with no problems. + When this is not the case, or when you have QA issues building any + software, it could take a little time to resolve them. + + + + While it is tempting to ignore a QA message or even to + disable QA checks, it is best to try and resolve any + reported QA issues. + This chapter provides a list of the QA messages and brief explanations + of the issues you could encounter so that you can properly resolve + problems. + + + + The next section provides a list of all QA error and warning + messages based on a default configuration. + Each entry provides the message or error form along with an + explanation. + + Notes + + + At the end of each message, the name of the associated + QA test (as listed in the + "insane.bbclass" + section) appears within square brackets. + + + As mentioned, this list of error and warning messages is for + QA checks only. + The list does not cover all possible build errors or + warnings you could encounter. + + + Because some QA checks are disabled by default, this list + does not include all possible QA check errors and warnings. + + + + +
+ +
+ Errors and Warnings + + + + + + + + + <packagename>: <path> is using libexec please relocate to <libexecdir> [libexec] + + + + + The specified package contains files in + /usr/libexec. + By default, libexecdir is set to + "${libdir}/${BPN}" rather than to "/usr/libexec". + Thus, installing to /usr/libexec + is likely not desirable. + + + +   + + + + + + + + + + + package <packagename> contains bad RPATH <rpath> in file <file> [rpaths] + + + + + The specified binary produced by the recipe contains dynamic + library load paths (rpaths) that contain build system paths + such as + TMPDIR, + which are incorrect for the target and could potentially + be a security issue. + Check for bad -rpath options being + passed to the linker in your + do_compile + log. + Depending on the build system used by the software being + built, there might be a configure option to disable rpath + usage completely within the build of the software. + + + +   + + + + + + + + + + + <packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths] + + + + + The specified binary produced by the recipe contains dynamic + library load paths (rpaths) that on a standard system are + searched by default by the linker (e.g. + /lib and /usr/lib). + While these paths will not cause any breakage, they do waste + space and are unnecessary. + Depending on the build system used by the software being + built, there might be a configure option to disable rpath + usage completely within the build of the software. + + + +   + + + + + + + + + + + <packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps] + + + + + A file-level dependency has been identified from the + specified package on the specified files, but there is + no explicit corresponding entry in + RDEPENDS. + If particular files are required at runtime then + RDEPENDS should be declared in the + recipe to ensure the packages providing them are built. + + + +   + + + + + + + + + + + <packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps] + + + + + A runtime dependency exists between the two specified + packages, but there is nothing explicit within the recipe + to enable the OpenEmbedded build system to ensure that + dependency is satisfied. + This condition is usually triggered by an + RDEPENDS + value being added at the packaging stage rather than up + front, which is usually automatic based on the contents of + the package. + In most cases, you should change the recipe to add an + explicit RDEPENDS for the dependency. + + + +   + + + + + + + + + + + non -dev/-dbg/-nativesdk package contains symlink .so: <packagename> path '<path>' [dev-so] + + + + + Symlink .so files are for development + only, and should therefore go into the + -dev package. + This situation might occur if you add + *.so* rather than + *.so.* to a non-dev package. + Change + FILES + (and possibly + PACKAGES) + such that the specified .so file goes + into an appropriate -dev package. + + + +   + + + + + + + + + + + non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev] + + + + + Static .a library files should go into + a -staticdev package. + Change + FILES + (and possibly + PACKAGES) + such that the specified .a file goes + into an appropriate -staticdev package. + + + +   + + + + + + + + + + + <packagename>: found library in wrong location [libdir] + + + + + The specified file may have been installed into an incorrect + (possibly hardcoded) installation path. + For example, this test will catch recipes that install + /lib/bar.so when + ${base_libdir} is "lib32". + Another example is when recipes install + /usr/lib64/foo.so when + ${libdir} is "/usr/lib". + False positives occasionally exist. + For these cases add "libdir" to + INSANE_SKIP + for the package. + + + +   + + + + + + + + + + + non debug package contains .debug directory: <packagename> path <path> [debug-files] + + + + + The specified package contains a + .debug directory, which should not + appear in anything but the -dbg + package. + This situation might occur if you add a path which contains + a .debug directory and do not + explicitly add the .debug directory + to the -dbg package. + If this is the case, add the .debug + directory explicitly to + FILES_${PN}-dbg. + See + FILES + for additional information on FILES. + + + +   + + + + + + + + + + + Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch] + + + + + By default, the OpenEmbedded build system checks the + Executable and Linkable Format (ELF) type, bit size, and + endianness of any binaries to ensure they match the + target architecture. + This test fails if any binaries do not match the type since + there would be an incompatibility. + The test could indicate that the wrong compiler or compiler + options have been used. + Sometimes software, like bootloaders, might need to + bypass this check. + If the file you receive the error for is firmware + that is not intended to be executed within the target + operating system or is intended to run on a separate + processor within the device, you can add "arch" to + INSANE_SKIP + for the package. + Another option is to check the + do_compile + log and verify that the compiler options being used + are correct. + + + +   + + + + + + + + + + + Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch] + + + + + By default, the OpenEmbedded build system checks + the Executable and Linkable Format (ELF) type, + bit size, and endianness of any binaries to ensure + they match the target architecture. + This test fails if any binaries do not match the type since + there would be an incompatibility. + The test could indicate that the wrong compiler or compiler + options have been used. + Sometimes software, like bootloaders, might need to + bypass this check. + If the file you receive the error for is firmware that + is not intended to be executed within the target + operating system or is intended to run on a separate + processor within the device, you can add "arch" to + INSANE_SKIP + for the package. + Another option is to check the + do_compile + log and verify that the compiler options being used are + correct. + + + +   + + + + + + + + + + + Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch] + + + + + By default, the OpenEmbedded build system checks + the Executable and Linkable Format (ELF) type, bit + size, and endianness of any binaries to ensure they + match the target architecture. + This test fails if any binaries do not match the type since + there would be an incompatibility. + The test could indicate that the wrong compiler or compiler + options have been used. + Sometimes software, like bootloaders, might need to + bypass this check. + If the file you receive the error for is firmware + that is not intended to be executed within the target + operating system or is intended to run on a separate + processor within the device, you can add "arch" to + INSANE_SKIP + for the package. + Another option is to check the + do_compile + log and verify that the compiler options being used + are correct. + + + +   + + + + + + + + + + + ELF binary '<file>' has relocations in .text [textrel] + + + + + The specified ELF binary contains relocations in its + .text sections. + This situation can result in a performance impact + at runtime. + + + +   + + + + + + + + + + + No GNU_HASH in the elf binary: '<file>' [ldflags] + + + + + This indicates that binaries produced when building the + recipe have not been linked with the + LDFLAGS + options provided by the build system. + Check to be sure that the LDFLAGS + variable is being passed to the linker command. + A common workaround for this situation is to pass in + LDFLAGS using + TARGET_CC_ARCH + within the recipe as follows: + + TARGET_CC_ARCH += "${LDFLAGS}" + + + + +   + + + + + + + + + + + Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi] + + + + + The specified package contains an Xorg driver, but does not + have a corresponding ABI package dependency. + The xserver-xorg recipe provides driver ABI names. + All drivers should depend on the ABI versions that they have + been built against. + Driver recipes that include + xorg-driver-input.inc or + xorg-driver-video.inc will + automatically get these versions. + Consequently, you should only need to explicitly add + dependencies to binary driver recipes. + + + +   + + + + + + + + + + + The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir] + + + + + The /usr/share/info/dir should not be + packaged. + Add the following line to your + do_install + task or to your do_install_append + within the recipe as follows: + + rm ${D}${infodir}/dir + + + + +   + + + + + + + + + + + Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot] + + + + + The specified symlink points into + TMPDIR + on the host. + Such symlinks will work on the host. + However, they are clearly invalid when running on + the target. + You should either correct the symlink to use a relative + path or remove the symlink. + + + +   + + + + + + + + + + + <file> failed sanity test (workdir) in path <path> [la] + + + + + The specified .la file contains + TMPDIR + paths. + Any .la file containing these paths + is incorrect since libtool adds the + correct sysroot prefix when using the files automatically + itself. + + + +   + + + + + + + + + + + <file> failed sanity test (tmpdir) in path <path> [pkgconfig] + + + + + The specified .pc file contains + TMPDIR/WORKDIR + paths. + Any .pc file containing these paths is + incorrect since pkg-config itself adds + the correct sysroot prefix when the files are accessed. + + + +   + + + + + + + + + + + <packagename> rdepends on <debug_packagename> [debug-deps] + + + + + A dependency exists between the specified non-dbg package + (i.e. a package whose name does not end in + -dbg) and a package that is a + dbg package. + The dbg packages contain + debug symbols and are brought in using several + different methods: + + + Using the dbg-pkgs + IMAGE_FEATURES + value. + + + Using + IMAGE_INSTALL. + + + As a dependency of another + dbg package that was brought + in using one of the above methods. + + + The dependency might have been automatically added + because the dbg package erroneously + contains files that it should not contain (e.g. a + non-symlink .so file) or it might + have been added manually (e.g. by adding to + RDEPENDS). + + + +   + + + + + + + + + + + <packagename> rdepends on <dev_packagename> [dev-deps] + + + + + A dependency exists between the specified non-dev package + (a package whose name does not end in + -dev) and a package that is a + dev package. + The dev packages contain development + headers and are usually brought in using several different + methods: + + + Using the dev-pkgs + IMAGE_FEATURES + value. + + + Using + IMAGE_INSTALL. + + + As a dependency of another + dev package that was brought + in using one of the above methods. + + + The dependency might have been automatically added (because + the dev package erroneously contains + files that it should not have (e.g. a non-symlink + .so file) or it might have been added + manually (e.g. by adding to + RDEPENDS). + + + +   + + + + + + + + + + + <var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp] + + + + + If you are adding a versioned dependency relationship to one + of the dependency variables + (RDEPENDS, + RRECOMMENDS, + RSUGGESTS, + RPROVIDES, + RREPLACES, + or + RCONFLICTS), + you must only use the named comparison operators. + Change the versioned dependency values you are adding + to match those listed in the message. + + + +   + + + + + + + + + + + <recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path] + + + + + The log for the + do_compile + task indicates that paths on the host were searched + for files, which is not appropriate when cross-compiling. + Look for "is unsafe for cross-compilation" or "CROSS COMPILE + Badness" in the specified log file. + + + +   + + + + + + + + + + + <recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path] + + + + + The log for the + do_install + task indicates that paths on the host were searched + for files, which is not appropriate when cross-compiling. + Look for "is unsafe for cross-compilation" + or "CROSS COMPILE Badness" in the specified log file. + + + +   + + + + + + + + + + + This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>' + + + + + The log for the + do_configure + task indicates that paths on the host were searched + for files, which is not appropriate when cross-compiling. + Look for "is unsafe for cross-compilation" or + "CROSS COMPILE Badness" in the specified log file. + + + +   + + + + + + + + + + + <packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname] + + + + + The convention within the OpenEmbedded build system + (sometimes enforced by the package manager itself) is to + require that package names are all lower case + and to allow a restricted set of characters. + If your recipe name does not match this, or you add + packages to + PACKAGES + that do not conform to the convention, then you + will receive this error. + Rename your recipe. + Or, if you have added a non-conforming package name to + PACKAGES, change the package name + appropriately. + + + +   + + + + + + + + + + + <recipe>: configure was passed unrecognized options: <options> [unknown-configure-option] + + + + + The configure script is reporting that the specified + options are unrecognized. + This situation could be because the options + were previously valid but have been removed from the + configure script. + Or, there was a mistake when the options were added + and there is another option that should be used instead. + If you are unsure, consult the upstream build + documentation, the + ./configure ‐‐help output, + and the upstream change log or release notes. + Once you have worked out what the appropriate + change is, you can update + EXTRA_OECONF + or the individual + PACKAGECONFIG + option values accordingly. + + + +   + + + + + + + + + + + Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides] + + + + + The specified recipe has a name + (PN) + value that appears in + OVERRIDES. + If a recipe is named such that its PN + value matches something already in + OVERRIDES (e.g. PN + happens to be the same as + MACHINE + or + DISTRO), + it can have unexpected consequences. + For example, assignments such as + FILES_${PN} = "xyz" effectively + turn into FILES = "xyz". + Rename your recipe (or if PN is being + set explicitly, change the PN value) so + that the conflict does not occur. + See + FILES + for additional information. + + + +   + + + + + + + + + + + <recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck] + + + + + Certain variables + (RDEPENDS, + RRECOMMENDS, + RSUGGESTS, + RCONFLICTS, + RPROVIDES, + RREPLACES, + FILES, + pkg_preinst, + pkg_postinst, + pkg_prerm, + pkg_postrm, and + ALLOW_EMPTY) + should always be set specific to a package (i.e. they + should be set with a package name override such as + RDEPENDS_${PN} = "value" rather than + RDEPENDS = "value"). + If you receive this error, correct any assignments to these + variables within your recipe. + + + +   + + + + + + + + + + + File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped] + + + + + Produced binaries have already been stripped prior to the + build system extracting debug symbols. + It is common for upstream software projects to default to + stripping debug symbols for output binaries. + In order for debugging to work on the target using + -dbg packages, this stripping must be + disabled. + + + + Depending on the build system used by the software being + built, disabling this stripping could be as easy as + specifying an additional configure option. + If not, disabling stripping might involve patching + the build scripts. + In the latter case, look for references to "strip" or + "STRIP", or the "-s" or "-S" command-line options being + specified on the linker command line (possibly + through the compiler command line if preceded with "-Wl,"). + + Disabling stripping here does not mean that the final + packaged binaries will be unstripped. + Once the OpenEmbedded build system splits out debug + symbols to the -dbg package, + it will then strip the symbols from the binaries. + + + + +   + + + + + + + + + + + <packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list] + + + + + Package names must appear only once in the + PACKAGES + variable. + You might receive this error if you are attempting to add a + package to PACKAGES that is + already in the variable's value. + + + +   + + + + + + + + + + + FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid] + + + + + The string "//" is invalid in a Unix path. + Correct all occurrences where this string appears in a + FILES + variable so that there is only a single "/". + + + +   + + + + + + + + + + + <recipename>: Files/directories were installed but not shipped [installed-vs-shipped] + + + + + Files have been installed within the + do_install + task but have not been included in any package by way of the + FILES + variable. + Files that do not appear in any package cannot be present in + an image later on in the build process. + You need to do one of the following: + + + Add the files to FILES for the + package you want them to appear in (e.g. + FILES_${PN} for the main + package). + + + Delete the files at the end of the + do_install task if the files + are not needed in any package. + + + + + +   + + + + + + + + + + + <oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later + + + + + This message means that both + <oldpackage> and + <newpackage> provide the specified + shared library. + You can expect this message when a recipe has been renamed. + However, if that is not the case, the message might indicate + that a private version of a library is being erroneously + picked up as the provider for a common library. + If that is the case, you should add the library's + .so file name to + PRIVATE_LIBS + in the recipe that provides + the private version of the library. + + + + + + +
+ +
+ Configuring and Disabling QA Checks + + + You can configure the QA checks globally so that specific check + failures either raise a warning or an error message, using the + WARN_QA and + ERROR_QA + variables, respectively. + You can also disable checks within a particular recipe using + INSANE_SKIP. + For information on how to work with the QA checks, see the + "insane.bbclass" + section. + Tip + Please keep in mind that the QA checks exist in order to + detect real or potential problems in the packaged output. + So exercise caution when disabling these checks. + + +
+
+ diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml new file mode 100644 index 0000000000..e7ca7b334b --- /dev/null +++ b/documentation/ref-manual/ref-structure.xml @@ -0,0 +1,1129 @@ + %poky; ] > + + + +Source Directory Structure + + + The Source Directory consists of several components. + Understanding them and knowing where they are located is key to using the Yocto Project well. + This chapter describes the Source Directory and gives information about the various + files and directories. + + + + For information on how to establish a local Source Directory on your development system, see the + "Getting Set Up" + section in the Yocto Project Development Manual. + + + + The OpenEmbedded build system does not support file or directory names that + contain spaces. + Be sure that the Source Directory you use does not contain these types + of names. + + +
+ Top-Level Core Components + + + This section describes the top-level components of the + Source Directory. + + +
+ <filename>bitbake/</filename> + + + This directory includes a copy of BitBake for ease of use. + The copy usually matches the current stable BitBake release from + the BitBake project. + BitBake, a + Metadata + interpreter, reads the Yocto Project Metadata and runs the tasks + defined by that data. + Failures are usually from the Metadata and not from BitBake itself. + Consequently, most users do not need to worry about BitBake. + + + + When you run the bitbake command, the + main BitBake executable, which resides in the + bitbake/bin/ directory, starts. + Sourcing an environment setup script (e.g. + &OE_INIT_FILE; + or + oe-init-build-env-memres) + places the scripts and + bitbake/bin directories (in that order) into + the shell's PATH environment variable. + + + + For more information on BitBake, see the + BitBake User Manual. + +
+ +
+ <filename>build/</filename> + + + This directory contains user configuration files and the output + generated by the OpenEmbedded build system in its standard configuration where + the source tree is combined with the output. + The Build Directory + is created initially when you source + the OpenEmbedded build environment setup script + (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + It is also possible to place output and configuration + files in a directory separate from the + Source Directory + by providing a directory name when you source + the setup script. + For information on separating output from your local + Source Directory files, see the + "&OE_INIT_FILE; + and + "oe-init-build-env-memres" + sections. + +
+ +
+ <filename>documentation/</filename> + + + This directory holds the source for the Yocto Project documentation + as well as templates and tools that allow you to generate PDF and HTML + versions of the manuals. + Each manual is contained in a sub-folder. + For example, the files for this manual reside in + the ref-manual/ directory. + +
+ +
+ <filename>meta/</filename> + + + This directory contains the OpenEmbedded Core metadata. + The directory holds recipes, common classes, and machine + configuration for emulated targets (qemux86, + qemuarm, and so forth.) + +
+ +
+ <filename>meta-yocto/</filename> + + + This directory contains the configuration for the Poky + reference distribution. + +
+ +
+ <filename>meta-yocto-bsp/</filename> + + + This directory contains the Yocto Project reference + hardware Board Support Packages (BSPs). + For more information on BSPs, see the + Yocto Project Board Support + Package (BSP) Developer's Guide. + +
+ +
+ <filename>meta-selftest/</filename> + + + This directory adds additional recipes and append files + used by the OpenEmbedded selftests to verify the behavior + of the build system. + + + + You do not have to add this layer to your + bblayers.conf file unless you want to run the + selftests. + +
+ +
+ <filename>meta-skeleton/</filename> + + + This directory contains template recipes for BSP and kernel development. + +
+ +
+ <filename>scripts/</filename> + + + This directory contains various integration scripts that implement + extra functionality in the Yocto Project environment (e.g. QEMU scripts). + The &OE_INIT_FILE; + and + oe-init-build-env-memres + scripts append this directory to the shell's + PATH environment variable. + + + + The scripts directory has useful scripts that assist in contributing + back to the Yocto Project, such as create-pull-request and + send-pull-request. + +
+ +
+ <filename>&OE_INIT_FILE;</filename> + + + This script is one of two scripts that set up the OpenEmbedded build + environment. + For information on the other script, see the + "oe-init-build-env-memres" + section. + + + + Running this script with the source command in + a shell makes changes to PATH and sets other + core BitBake variables based on the current working directory. + You need to run an environment setup script before running BitBake + commands. + The script uses other scripts within the + scripts directory to do the bulk of the work. + + + + When you run this script, your Yocto Project environment is set + up, a + Build Directory + is created, your working directory becomes the Build Directory, + and you are presented with a list of common BitBake targets. + Here is an example: + + $ source oe-init-build-env + + ### Shell environment set up for builds. ### + + You can now run 'bitbake <target>' + + Common targets are: + 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' + + The script gets its default list of common targets from the + conf-notes.txt file, which is found in the + meta-yocto directory within the + Source Directory. + Should you have custom distributions, it is very easy to modify + this configuration file to include your targets for your + distribution. + See the + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. + + + + By default, running this script without a + Build Directory + argument creates the build directory + in your current working directory. + If you provide a Build Directory argument when you + source the script, you direct the OpenEmbedded + build system to create a Build Directory of your choice. + For example, the following command creates a Build Directory named + mybuilds that is outside of the + Source Directory: + + $ source &OE_INIT_FILE; ~/mybuilds + + The OpenEmbedded build system uses the template configuration + files, which are found by default in the + meta-yocto/conf directory in the + Source Directory. + See the + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. + + The OpenEmbedded build system does not support file or directory names that + contain spaces. + If you attempt to run the &OE_INIT_FILE; script + from a Source Directory that contains spaces in either the filenames + or directory names, the script returns an error indicating no such + file or directory. + Be sure to use a Source Directory free of names containing spaces. + + +
+ +
+ <filename>oe-init-build-env-memres</filename> + + + This script is one of two scripts that set up the OpenEmbedded + build environment. + Aside from setting up the environment, this script starts a + memory-resident BitBake server. + For information on the other setup script, see the + "&OE_INIT_FILE;" + section. + + + + Memory-resident BitBake resides in memory until you specifically + remove it using the following BitBake command: + + $ bitbake -m + + + + + Running this script with the source command in + a shell makes changes to PATH and sets other + core BitBake variables based on the current working directory. + One of these variables is the + BBSERVER + variable, which allows the OpenEmbedded build system to locate + the server that is running BitBake. + + + + You need to run an environment setup script before using BitBake + commands. + Following is the script syntax: + + $ source oe-init-build-env-memres port_number build_dir + + The script uses other scripts within the + scripts directory to do the bulk of the work. + + + + If you do not provide a port number with the script, the + BitBake server at port "12345" is started. + + + + When you run this script, your Yocto Project environment is set + up, a + Build Directory + is created, your working directory becomes the Build Directory, + and you are presented with a list of common BitBake targets. + Here is an example: + + $ source oe-init-build-env-memres + No port specified, using dynamically selected port + + ### Shell environment set up for builds. ### + + You can now run 'bitbake <target>' + + Common targets are: + 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' + Bitbake server started on demand as needed, use bitbake -m to shut it down + + The script gets its default list of common targets from the + conf-notes.txt file, which is found in the + meta-yocto directory within the + Source Directory. + Should you have custom distributions, it is very easy to modify + this configuration file to include your targets for your + distribution. + See the + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. + + + + By default, running this script without a + Build Directory + argument creates a build directory named + build. + If you provide a Build Directory argument when you + source the script, the Build Directory is + created using that name. + For example, the following command starts the BitBake server using + the default port "12345" and creates a Build Directory named + mybuilds that is outside of the + Source Directory: + + $ source oe-init-build-env-memres ~/mybuilds + + The OpenEmbedded build system uses the template configuration + files, which are found by default in the + meta-yocto/conf directory in the + Source Directory. + See the + "Creating a Custom Template Configuration Directory" + section in the Yocto Project Development Manual for more + information. + + The OpenEmbedded build system does not support file or + directory names that contain spaces. + If you attempt to run the + oe-init-build-env-memres script + from a Source Directory that contains spaces in either the + filenames or directory names, the script returns an error + indicating no such file or directory. + Be sure to use a Source Directory free of names containing + spaces. + + +
+ +
+ <filename>LICENSE, README, and README.hardware</filename> + + + These files are standard top-level files. + +
+
+ +
+ The Build Directory - <filename>build/</filename> + + + The OpenEmbedded build system creates the + Build Directory + when you run one of the build environment setup scripts (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + If you do not give the Build Directory a specific name when you run + a setup script, the name defaults to build. + + + + The + TOPDIR variable + points to the Build Directory. + + +
+ <filename>build/buildhistory</filename> + + + The OpenEmbedded build system creates this directory when you + enable the build history feature. + The directory tracks build information into image, packages, and + SDK subdirectories. + For information on the build history feature, see the + "Maintaining Build Output Quality" + section. + +
+ +
+ <filename>build/conf/local.conf</filename> + + + This configuration file contains all the local user configurations + for your build environment. + The local.conf file contains documentation on + the various configuration options. + Any variable set here overrides any variable set elsewhere within + the environment unless that variable is hard-coded within a file + (e.g. by using '=' instead of '?='). + Some variables are hard-coded for various reasons but these + variables are relatively rare. + + + + Edit this file to set the + MACHINE + for which you want to build, which package types you wish to use + (PACKAGE_CLASSES), + the location from which you want to access downloaded files + (DL_DIR), + and how you want your host machine to use resources + (BB_NUMBER_THREADS + and + PARALLEL_MAKE). + + + + If local.conf is not present when you + start the build, the OpenEmbedded build system creates it from + local.conf.sample when + you source the top-level build environment + setup script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + The source local.conf.sample file used + depends on the $TEMPLATECONF script variable, + which defaults to meta-yocto/conf + when you are building from the Yocto Project development + environment and defaults to meta/conf when + you are building from the OpenEmbedded Core environment. + Because the script variable points to the source of the + local.conf.sample file, this implies that + you can configure your build environment from any layer by setting + the variable in the top-level build environment setup script as + follows: + + TEMPLATECONF=your_layer/conf + + Once the build process gets the sample file, it uses + sed to substitute final + ${OEROOT} + values for all ##OEROOT## values. + + You can see how the TEMPLATECONF variable + is used by looking at the + scripts/oe-setup-builddir script in the + Source Directory. + You can find the Yocto Project version of the + local.conf.sample file in the + meta-yocto/conf directory. + + +
+ +
+ <filename>build/conf/bblayers.conf</filename> + + + This configuration file defines + layers, + which are directory trees, traversed (or walked) by BitBake. + The bblayers.conf file uses the + BBLAYERS + variable to list the layers BitBake tries to find, and uses the + BBLAYERS_NON_REMOVABLE + variable to list layers that must not be removed. + + + + If bblayers.conf is not present when you + start the build, the OpenEmbedded build system creates it from + bblayers.conf.sample when + you source the top-level build environment + setup script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + The source bblayers.conf.sample file used + depends on the $TEMPLATECONF script variable, + which defaults to meta-yocto/conf + when you are building from the Yocto Project development + environment and defaults to meta/conf when + you are building from the OpenEmbedded Core environment. + Because the script variable points to the source of the + bblayers.conf.sample file, this implies that + you can base your build from any layer by setting the variable in + the top-level build environment setup script as follows: + + TEMPLATECONF=your_layer/conf + + Once the build process gets the sample file, it uses + sed to substitute final + ${OEROOT} + values for all ##OEROOT## values. + + You can see how the TEMPLATECONF variable + scripts/oe-setup-builddir script in the + Source Directory. + You can find the Yocto Project version of the + bblayers.conf.sample file in the + meta-yocto/conf directory. + + +
+ +
+ <filename>build/conf/sanity_info</filename> + + + This file indicates the state of the sanity checks and is created + during the build. + +
+ +
+ <filename>build/downloads/</filename> + + + This directory contains downloaded upstream source tarballs. + You can reuse the directory for multiple builds or move + the directory to another location. + You can control the location of this directory through the + DL_DIR variable. + +
+ +
+ <filename>build/sstate-cache/</filename> + + + This directory contains the shared state cache. + You can reuse the directory for multiple builds or move + the directory to another location. + You can control the location of this directory through the + SSTATE_DIR variable. + +
+ +
+ <filename>build/tmp/</filename> + + + The OpenEmbedded build system creates and uses this directory + for all the build system's output. + The + TMPDIR + variable points to this directory. + + + + BitBake creates this directory if it does not exist. + As a last resort, to clean up a build and start it from scratch + (other than the downloads), you can remove everything in the + tmp directory or get rid of the + directory completely. + If you do, you should also completely remove the + build/sstate-cache directory. + +
+ +
+ <filename>build/tmp/buildstats/</filename> + + + This directory stores the build statistics. + +
+ +
+ <filename>build/tmp/cache/</filename> + + + When BitBake parses the metadata, it creates a cache file of the result that can + be used when subsequently running commands. + BitBake stores these results here on a per-machine basis. + +
+ +
+ <filename>build/tmp/deploy/</filename> + + + This directory contains any "end result" output from the + OpenEmbedded build process. + The DEPLOY_DIR + variable points to this directory. + For more detail on the contents of the deploy + directory, see the + "Images" and + "Application Development SDK" + sections. + +
+ +
+ <filename>build/tmp/deploy/deb/</filename> + + + This directory receives any .deb packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + +
+ +
+ <filename>build/tmp/deploy/rpm/</filename> + + + This directory receives any .rpm packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + +
+ +
+ <filename>build/tmp/deploy/ipk/</filename> + + + This directory receives .ipk packages produced by + the build process. + +
+ +
+ <filename>build/tmp/deploy/licenses/</filename> + + + This directory receives package licensing information. + For example, the directory contains sub-directories for bash, + busybox, and glibc (among others) that in turn + contain appropriate COPYING license files with other licensing information. + For information on licensing, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" + section. + +
+ +
+ <filename>build/tmp/deploy/images/</filename> + + + This directory receives complete filesystem images. + If you want to flash the resulting image from a build onto a device, look here for the image. + + + + Be careful when deleting files in this directory. + You can safely delete old images from this directory (e.g. + core-image-*, hob-image-*, + etc.). + However, the kernel (*zImage*, *uImage*, etc.), + bootloader and other supplementary files might be deployed here prior to building an + image. + Because these files are not directly produced from the image, if you + delete them they will not be automatically re-created when you build the image again. + + + + If you do accidentally delete files here, you will need to force them to be + re-created. + In order to do that, you will need to know the target that produced them. + For example, these commands rebuild and re-create the kernel files: + + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + + +
+ +
+ <filename>build/tmp/deploy/sdk/</filename> + + + The OpenEmbedded build system creates this directory to hold + toolchain installer scripts, which when executed, install the + sysroot that matches your target hardware. + You can find out more about these installers in the + "Optionally Building a Toolchain Installer" + section in the Yocto Project Application Developer's Guide. + +
+ +
+ <filename>build/tmp/sstate-control/</filename> + + + The OpenEmbedded build system uses this directory for the + shared state manifest files. + The shared state code uses these files to record the files + installed by each sstate task so that the files can be removed + when cleaning the recipe or when a newer version is about to + be installed. + The build system also uses the manifests to detect and produce + a warning when files from one task are overwriting those from + another. + +
+ +
+ <filename>build/tmp/sysroots/</filename> + + + This directory contains shared header files and libraries as well as other shared + data. + Packages that need to share output with other packages do so within this directory. + The directory is subdivided by architecture so multiple builds can run within + the one Build Directory. + +
+ +
+ <filename>build/tmp/stamps/</filename> + + + This directory holds information that BitBake uses for accounting purposes + to track what tasks have run and when they have run. + The directory is sub-divided by architecture, package name, and + version. + Following is an example: + + stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do + + Although the files in the directory are empty of data, + BitBake uses the filenames and timestamps for tracking purposes. + +
+ +
+ <filename>build/tmp/log/</filename> + + + This directory contains general logs that are not otherwise placed using the + package's WORKDIR. + Examples of logs are the output from the + do_check_pkg or + do_distro_check tasks. + Running a build does not necessarily mean this directory is created. + +
+ +
+ <filename>build/tmp/work/</filename> + + + This directory contains architecture-specific work sub-directories + for packages built by BitBake. + All tasks execute from the appropriate work directory. + For example, the source for a particular package is unpacked, + patched, configured and compiled all within its own work directory. + Within the work directory, organization is based on the package group + and version for which the source is being compiled + as defined by the + WORKDIR. + + + + It is worth considering the structure of a typical work directory. + As an example, consider linux-yocto-kernel-3.0 + on the machine qemux86 + built within the Yocto Project. + For this package, a work directory of + tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>, + referred to as the + WORKDIR, is created. + Within this directory, the source is unpacked to + linux-qemux86-standard-build and then patched by Quilt. + (See the + "Using a Quilt Flow" + section in the Yocto Project Development Manual for more information.) + Within the linux-qemux86-standard-build directory, + standard Quilt directories linux-3.0/patches + and linux-3.0/.pc are created, + and standard Quilt commands can be used. + + + + There are other directories generated within WORKDIR. + The most important directory is WORKDIR/temp/, + which has log files for each task (log.do_*.pid) + and contains the scripts BitBake runs for each task + (run.do_*.pid). + The WORKDIR/image/ directory is where "make + install" places its output that is then split into sub-packages + within WORKDIR/packages-split/. + +
+ +
+ <filename>build/tmp/work-shared/</filename> + + + For efficiency, the OpenEmbedded build system creates and uses + this directory to hold recipes that share a work directory with + other recipes. + In practice, this is only used for gcc + and its variants (e.g. gcc-cross, + libgcc, gcc-runtime, + and so forth). + +
+
+ +
+ The Metadata - <filename>meta/</filename> + + + As mentioned previously, + Metadata is the core + of the Yocto Project. + Metadata has several important subdivisions: + + +
+ <filename>meta/classes/</filename> + + + This directory contains the *.bbclass files. + Class files are used to abstract common code so it can be reused by multiple + packages. + Every package inherits the base.bbclass file. + Examples of other important classes are autotools.bbclass, which + in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. + Another example is kernel.bbclass that contains common code and functions + for working with the Linux kernel. + Functions like image generation or packaging also have their specific class files + such as image.bbclass, rootfs_*.bbclass and + package*.bbclass. + + + + For reference information on classes, see the + "Classes" chapter. + +
+ +
+ <filename>meta/conf/</filename> + + + This directory contains the core set of configuration files that start from + bitbake.conf and from which all other configuration + files are included. + See the include statements at the end of the + bitbake.conf file and you will note that even + local.conf is loaded from there. + While bitbake.conf sets up the defaults, you can often override + these by using the (local.conf) file, machine file or + the distribution configuration file. + +
+ +
+ <filename>meta/conf/machine/</filename> + + + This directory contains all the machine configuration files. + If you set MACHINE = "qemux86", + the OpenEmbedded build system looks for a qemux86.conf file in this + directory. + The include directory contains various data common to multiple machines. + If you want to add support for a new machine to the Yocto Project, look in this directory. + +
+ +
+ <filename>meta/conf/distro/</filename> + + + The contents of this directory controls any distribution-specific + configurations. + For the Yocto Project, the defaultsetup.conf is the main file here. + This directory includes the versions and the + SRCDATE definitions for applications that are configured here. + An example of an alternative configuration might be poky-bleeding.conf. + Although this file mainly inherits its configuration from Poky. + +
+ +
+ <filename>meta/conf/machine-sdk/</filename> + + + The OpenEmbedded build system searches this directory for + configuration files that correspond to the value of + SDKMACHINE. + By default, 32-bit and 64-bit x86 files ship with the Yocto + Project that support some SDK hosts. + However, it is possible to extend that support to other SDK hosts + by adding additional configuration files in this subdirectory + within another layer. + +
+ +
+ <filename>meta/files/</filename> + + + This directory contains common license files and several text files + used by the build system. + The text files contain minimal device information and + lists of files and directories with known permissions. + +
+ +
+ <filename>meta/lib/</filename> + + + This directory contains OpenEmbedded Python library code + used during the build process. + +
+ +
+ <filename>meta/recipes-bsp/</filename> + + + This directory contains anything linking to specific hardware or hardware + configuration information such as "u-boot" and "grub". + +
+ +
+ <filename>meta/recipes-connectivity/</filename> + + + This directory contains libraries and applications related to communication with other devices. + +
+ +
+ <filename>meta/recipes-core/</filename> + + + This directory contains what is needed to build a basic working Linux image + including commonly used dependencies. + +
+ +
+ <filename>meta/recipes-devtools/</filename> + + + This directory contains tools that are primarily used by the build system. + The tools, however, can also be used on targets. + +
+ +
+ <filename>meta/recipes-extended/</filename> + + + This directory contains non-essential applications that add features compared to the + alternatives in core. + You might need this directory for full tool functionality or for Linux Standard Base (LSB) + compliance. + +
+ +
+ <filename>meta/recipes-gnome/</filename> + + + This directory contains all things related to the GTK+ application framework. + +
+ +
+ <filename>meta/recipes-graphics/</filename> + + + This directory contains X and other graphically related system libraries + +
+ +
+ <filename>meta/recipes-kernel/</filename> + + + This directory contains the kernel and generic applications and libraries that + have strong kernel dependencies. + +
+ +
+ <filename>meta/recipes-lsb4/</filename> + + + This directory contains recipes specifically added to support + the Linux Standard Base (LSB) version 4.x. + +
+ +
+ <filename>meta/recipes-multimedia/</filename> + + + This directory contains codecs and support utilities for audio, images and video. + +
+ +
+ <filename>meta/recipes-qt/</filename> + + + This directory contains all things related to the Qt application framework. + +
+ +
+ <filename>meta/recipes-rt/</filename> + + + This directory contains package and image recipes for using and testing + the PREEMPT_RT kernel. + +
+ +
+ <filename>meta/recipes-sato/</filename> + + + This directory contains the Sato demo/reference UI/UX and its associated applications + and configuration data. + +
+ +
+ <filename>meta/recipes-support/</filename> + + + This directory contains recipes used by other recipes, but that are + not directly included in images (i.e. dependencies of other + recipes). + +
+ +
+ <filename>meta/site/</filename> + + + This directory contains a list of cached results for various architectures. + Because certain "autoconf" test results cannot be determined when cross-compiling due to + the tests not able to run on a live system, the information in this directory is + passed to "autoconf" for the various architectures. + +
+ +
+ <filename>meta/recipes.txt</filename> + + + This file is a description of the contents of recipes-*. + +
+
+ +
+ diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css new file mode 100644 index 0000000000..e04b5006b4 --- /dev/null +++ b/documentation/ref-manual/ref-style.css @@ -0,0 +1,985 @@ +/* + 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/poky-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-image: url("figures/poky-title.png"); + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml new file mode 100644 index 0000000000..f325f0e233 --- /dev/null +++ b/documentation/ref-manual/ref-tasks.xml @@ -0,0 +1,695 @@ + %poky; ] > + + +Tasks + + + Tasks are units of execution for BitBake. + Recipes (.bb files) use tasks to complete + configuring, compiling, and packaging software. + This chapter provides a reference of the tasks defined in the + OpenEmbedded build system. + + +
+ Normal Recipe Build Tasks + + + The following sections describe normal tasks associated with building + a recipe. + + +
+ <filename>do_build</filename> + + + The default task for all recipes. + This task depends on all other normal tasks + required to build a recipe. + +
+ +
+ <filename>do_compile</filename> + + + Compiles the source in the compilation directory, which is pointed + to by the + B variable. + +
+ +
+ <filename>do_compile_ptest_base</filename> + + + Compiles the runtime test suite included in the software being + built. + +
+ +
+ <filename>do_configure</filename> + + + Configures the source by enabling and disabling any build-time and + configuration options for the software being built. + +
+ +
+ <filename>do_configure_ptest_base</filename> + + + Configures the runtime test suite included in the software being + built. + +
+ +
+ <filename>do_deploy</filename> + + + Writes output files that are to be deployed to the deploy + directory, which is defined by the + DEPLOYDIR + variable. + + + + The do_deploy task is a + shared state (sstate) task, which means that the task can + be accelerated through sstate use. + Realize also that if the task is re-executed, any previous output + is removed (i.e. "cleaned"). + +
+ +
+ <filename>do_fetch</filename> + + + Fetches the source code. + This task uses the + SRC_URI + variable and the argument's prefix to determine the correct + fetcher module. + +
+ +
+ <filename>do_install</filename> + + + Copies files from the compilation directory, which is defined by + the + B variable, + to a holding area defined by the + D variable. + +
+ +
+ <filename>do_install_ptest_base</filename> + + + Copies the runtime test suite files from the compilation directory + to a holding area. + +
+ +
+ <filename>do_package</filename> + + + Analyzes the content of the holding area and splits it into subsets + based on available packages and files. + +
+ +
+ <filename>do_package_qa</filename> + + + Runs QA checks on packaged files. + For more information on these checks, see the + insane + class. + +
+ +
+ <filename>do_package_write_deb</filename> + + + Creates the actual DEB packages and places them in the + Package Feeds + area. + +
+ +
+ <filename>do_package_write_ipk</filename> + + + Creates the actual IPK packages and places them in the + Package Feeds + area. + +
+ +
+ <filename>do_package_write_rpm</filename> + + + Creates the actual RPM packages and places them in the + Package Feeds + area. + +
+ +
+ <filename>do_package_write_tar</filename> + + + Creates tar archives for packages and places them in the + Package Feeds + area. + +
+ +
+ <filename>do_packagedata</filename> + + + Creates package metadata used by the build system to generate the + final packages. + +
+ +
+ <filename>do_patch</filename> + + + Locates patch files and applies them to the source code. + See the + "Patching" + section for more information. + +
+ +
+ <filename>do_populate_lic</filename> + + + Writes license information for the recipe that is collected later + when the image is constructed. + +
+ +
+ <filename>do_populate_sdk</filename> + + + Creates the file and directory structure for an installable SDK. + See the + "SDK Generation" + section for more information. + +
+ +
+ <filename>do_populate_sysroot</filename> + + + Copies a subset of files installed by the + do_install + task into the sysroot in order to make them available to other + recipes. + + + + The do_populate_sysroot task is a + shared state (sstate) task, which means that the task can + be accelerated through sstate use. + Realize also that if the task is re-executed, any previous output + is removed (i.e. "cleaned"). + +
+ +
+ <filename>do_rm_work</filename> + + + Removes work files after the OpenEmbedded build system has + finished with them. + You can learn more by looking at the + "rm_work.bbclass" + section. + +
+ +
+ <filename>do_rm_work_all</filename> + + + Top-level task for removing work files after the build system has + finished with them. + +
+ +
+ <filename>do_unpack</filename> + + + Unpacks the source code into a working directory pointed to + by + ${WORKDIR}. + The + S variable also + plays a role in where unpacked source files ultimately reside. + For more information on how source files are unpacked, see the + "Source Fetching" + section and the WORKDIR and + S variable descriptions. + +
+
+ +
+ Manually Called Tasks + + + These tasks are typically manually triggered (e.g. by using the + bitbake -c command-line option): + + +
+ <filename>do_checkuri</filename> + + + Validates the + SRC_URI + value. + +
+ +
+ <filename>do_checkuriall</filename> + + + Validates the + SRC_URI + value for all recipes required to build a target. + +
+ +
+ <filename>do_clean</filename> + + + Removes all output files for a target from the + do_unpack + task forward (i.e. + do_unpack, + do_configure, + do_compile, + do_install, + and + do_package). + + + + You can run this task using BitBake as follows: + + $ bitbake -c clean recipe + + + + + Running this task does not remove the + sstate) cache + files. + Consequently, if no changes have been made and the recipe is + rebuilt after cleaning, output files are simply restored from the + sstate cache. + If you want to remove the sstate cache files for the recipe, + you need to use the + do_cleansstate + task instead (i.e. bitbake -c cleansstate recipe). + +
+ +
+ <filename>do_cleanall</filename> + + + Removes all output files, shared state + (sstate) cache, and + downloaded source files for a target (i.e. the contents of + DL_DIR). + Essentially, the do_cleanall task is + identical to the + do_cleansstate + task with the added removal of downloaded source files. + + + + You can run this task using BitBake as follows: + + $ bitbake -c cleanall recipe + + + + + Typically, you would not normally use the + cleanall task. + Do so only if you want to start fresh with the + do_fetch + task. + +
+ +
+ <filename>do_cleansstate</filename> + + + Removes all output files and shared state + (sstate) + cache for a target. + Essentially, the do_cleansstate task is + identical to the + do_clean + task with the added removal of shared state + (sstate) cache. + + + + You can run this task using BitBake as follows: + + $ bitbake -c cleansstate recipe + + + + + When you run the do_cleansstate task, + the OpenEmbedded build system no longer uses any + sstate. + Consequently, building the recipe from scratch is guaranteed. + + The do_cleansstate task cannot remove + sstate from a remote sstate mirror. + If you need to build a target from scratch using remote + mirrors, use the "-f" option as follows: + + $ bitbake -f -c do_cleansstate target + + + +
+ +
+ <filename>do_devshell</filename> + + + Starts a shell whose environment is set up for + development, debugging, or both. + See the + "Using a Development Shell" + section in the Yocto Project Development Manual for more + information about using devshell. + +
+ +
+ <filename>do_fetchall</filename> + + + Fetches all remote sources required to build a target. + +
+ +
+ <filename>do_listtasks</filename> + + + Lists all defined tasks for a target. + +
+ +
+ <filename>do_package_index</filename> + + + Creates or updates the index in the + Package Feeds + area. + + This task is not triggered with the + bitbake -c command-line option as + are the other tasks in this section. + Because this task is specifically for the + package-index recipe, + you run it using + bitbake package-index. + + +
+
+ + + + + +
+ Miscellaneous Tasks + + + The following sections describe miscellaneous tasks. + + +
+ <filename>do_generate_qt_config_file</filename> + + + Writes a qt.conf configuration + file used for building a Qt-based application. + +
+ +
+ <filename>do_spdx</filename> + + + A build stage that takes the source code and scans it on a remote + FOSSOLOGY server in order to produce an SPDX document. + This task applies only to the + spdx + class. + +
+
+ +
+ diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml new file mode 100644 index 0000000000..576c91f29a --- /dev/null +++ b/documentation/ref-manual/ref-variables.xml @@ -0,0 +1,10284 @@ + %poky; ] > + + + + +Variables Glossary + + + This chapter lists common variables used in the OpenEmbedded build system and gives an overview + of their function and contents. + + + + + + + A + B + C + D + E + F + G + H + I + + K + L + M + + O + P + Q + R + S + T + U + + W + + + + + + A + + ABIEXTENSION + + + Extension to the Application Binary Interface (ABI) + field of the GNU canonical architecture name + (e.g. "eabi"). + + + + ABI extensions are set in the machine include files. + For example, the + meta/conf/machine/include/arm/arch-arm.inc + file sets the following extension: + + ABIEXTENSION = "eabi" + + + + + + ALLOW_EMPTY + + + Specifies if an output package should still be produced if it is empty. + By default, BitBake does not produce empty packages. + This default behavior can cause issues when there is an + RDEPENDS or + some other hard runtime requirement on the existence of the package. + + + + Like all package-controlling variables, you must always use them in + conjunction with a package name override, as in: + + ALLOW_EMPTY_${PN} = "1" + ALLOW_EMPTY_${PN}-dev = "1" + ALLOW_EMPTY_${PN}-staticdev = "1" + + + + + + ALTERNATIVE + + + Lists commands in a package that need an alternative + binary naming scheme. + Sometimes the same command is provided in multiple packages. + When this occurs, the OpenEmbedded build system needs to + use the alternatives system to create a different binary + naming scheme so the commands can co-exist. + + + + To use the variable, list out the package's commands + that also exist as part of another package. + For example, if the busybox package + has four commands that also exist as part of another + package, you identify them as follows: + + ALTERNATIVE_busybox = "sh sed test bracket" + + For more information on the alternatives system, see the + "update-alternatives.bbclass" + section. + + + + + ALTERNATIVE_LINK_NAME + + + Used by the alternatives system to map duplicated commands + to actual locations. + For example, if the bracket command + provided by the busybox package is + duplicated through another package, you must use the + ALTERNATIVE_LINK_NAME variable to + specify the actual location: + + ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" + + In this example, the binary for the + bracket command (i.e. + [) from the + busybox package resides in + /usr/bin/. + + If ALTERNATIVE_LINK_NAME is not + defined, it defaults to + ${bindir}/name. + + + + + For more information on the alternatives system, see the + "update-alternatives.bbclass" + section. + + + + + ALTERNATIVE_PRIORITY + + + Used by the alternatives system to create default + priorities for duplicated commands. + You can use the variable to create a single default + regardless of the command name or package, a default for + specific duplicated commands regardless of the package, or + a default for specific commands tied to particular packages. + Here are the available syntax forms: + + ALTERNATIVE_PRIORITY = "priority" + ALTERNATIVE_PRIORITY[name] = "priority" + ALTERNATIVE_PRIORITY_pkg[name] = "priority" + + + + + For more information on the alternatives system, see the + "update-alternatives.bbclass" + section. + + + + + ALTERNATIVE_TARGET + + + Used by the alternatives system to create default link + locations for duplicated commands. + You can use the variable to create a single default + location for all duplicated commands regardless of the + command name or package, a default for + specific duplicated commands regardless of the package, or + a default for specific commands tied to particular packages. + Here are the available syntax forms: + + ALTERNATIVE_TARGET = "target" + ALTERNATIVE_TARGET[name] = "target" + ALTERNATIVE_TARGET_pkg[name] = "target" + + + + If ALTERNATIVE_TARGET is not + defined, it inherits the value from the + ALTERNATIVE_LINK_NAME + variable. + + + + If ALTERNATIVE_LINK_NAME and + ALTERNATIVE_TARGET are the + same, the target for + ALTERNATIVE_TARGET + has ".{BPN}" appended to it. + + + + Finally, if the file referenced has not been + renamed, the alternatives system will rename it to + avoid the need to rename alternative files in the + do_install + task while + retaining support for the command if necessary. + + + + + + For more information on the alternatives system, see the + "update-alternatives.bbclass" + section. + + + + + APPEND + + + An override list of append strings for each + LABEL. + + + + See the + grub-efi + class for more information on how this variable is used. + + + + + ASSUME_PROVIDED + + + Lists recipe names + (PN + values) BitBake does not attempt to build. + Instead, BitBake assumes these recipes have already been + built. + + + + In OpenEmbedded Core, ASSUME_PROVIDED + mostly specifies native tools that should not be built. + An example is git-native, which when + specified, allows for the Git binary from the host to be + used rather than building git-native. + + + + + AUTHOR + + The email address used to contact the original author + or authors in order to send patches and forward bugs. + + + + AUTO_SYSLINUXMENU + + + Enables creating an automatic menu. + You must set this in your recipe. + The + syslinux + class checks this variable. + + + + + AUTOREV + + When SRCREV + is set to the value of this variable, it specifies to use the latest + source revision in the repository. + Here is an example: + + SRCREV = "${AUTOREV}" + + + + + + AVAILTUNES + + + The list of defined CPU and Application Binary Interface + (ABI) tunings (i.e. "tunes") available for use by the + OpenEmbedded build system. + + + + The list simply presents the tunes that are available. + Not all tunes may be compatible with a particular + machine configuration, or with each other in a + Multilib + configuration. + + + + To add a tune to the list, be sure to append it with + spaces using the "+=" BitBake operator. + Do not simply replace the list by using the "=" operator. + See the + "Basic Syntax" + section in the BitBake User Manual for more information. + + + + + + + + B + + B + + + The directory within the + Build Directory + in which the OpenEmbedded build system places generated + objects during a recipe's build process. + By default, this directory is the same as the S + directory, which is defined as: + + S = "${WORKDIR}/${BP}/" + + You can separate the (S) directory + and the directory pointed to by the B + variable. + Most Autotools-based recipes support separating these + directories. + The build system defaults to using separate directories for + gcc and some kernel recipes. + + + + + BAD_RECOMMENDATIONS + + + Lists "recommended-only" packages to not install. + Recommended-only packages are packages installed only + through the + RRECOMMENDS + variable. + You can prevent any of these "recommended" packages from + being installed by listing them with the + BAD_RECOMMENDATIONS variable: + + BAD_RECOMMENDATIONS = "package_name package_name package_name ..." + + You can set this variable globally in your + local.conf file or you can attach it to + a specific image recipe by using the recipe name override: + + BAD_RECOMMENDATIONS_pn-target_image = "package_name" + + + + + It is important to realize that if you choose to not install + packages using this variable and some other packages are + dependent on them (i.e. listed in a recipe's + RDEPENDS + variable), the OpenEmbedded build system ignores your + request and will install the packages to avoid dependency + errors. + + + + Support for this variable exists only when using the + IPK and RPM packaging backend. + Support does not exist for DEB. + + + + See the + NO_RECOMMENDATIONS + and the + PACKAGE_EXCLUDE + variables for related information. + + + + + BASE_LIB + + + The library directory name for the CPU or Application + Binary Interface (ABI) tune. + The BASE_LIB applies only in the + Multilib context. + See the + "Combining Multiple Versions of Library Files into One Image" + section in the Yocto Project Development Manual for + information on Multilib. + + + + The BASE_LIB variable is defined in + the machine include files in the + Source Directory. + If Multilib is not being used, the value defaults to "lib". + + + + + BB_DANGLINGAPPENDS_WARNONLY + + + Defines how BitBake handles situations where an append + file (.bbappend) has no + corresponding recipe file (.bb). + This condition often occurs when layers get out of sync + (e.g. oe-core bumps a + recipe version and the old recipe no longer exists and the + other layer has not been updated to the new version + of the recipe yet). + + + + The default fatal behavior is safest because it is + the sane reaction given something is out of sync. + It is important to realize when your changes are no longer + being applied. + + + + You can change the default behavior by setting this + variable to "1", "yes", or "true" + in your local.conf file, which is + located in the + Build Directory: + Here is an example: + + BB_DANGLINGAPPENDS_WARNONLY = "1" + + + + + + BB_DISKMON_DIRS + + + Monitors disk space and available inodes during the build + and allows you to control the build based on these + parameters. + + + + Disk space monitoring is disabled by default. + To enable monitoring, add the BB_DISKMON_DIRS + variable to your conf/local.conf file found in the + Build Directory. + Use the following form: + + BB_DISKMON_DIRS = "action,dir,threshold [...]" + + where: + + action is: + ABORT: Immediately abort the build when + a threshold is broken. + STOPTASKS: Stop the build after the currently + executing tasks have finished when + a threshold is broken. + WARN: Issue a warning but continue the + build when a threshold is broken. + Subsequent warnings are issued as + defined by the + BB_DISKMON_WARNINTERVAL variable, + which must be defined in the + conf/local.conf file. + + dir is: + Any directory you choose. You can specify one or + more directories to monitor by separating the + groupings with a space. If two directories are + on the same device, only the first directory + is monitored. + + threshold is: + Either the minimum available disk space, + the minimum number of free inodes, or + both. You must specify at least one. To + omit one or the other, simply omit the value. + Specify the threshold using G, M, K for Gbytes, + Mbytes, and Kbytes, respectively. If you do + not specify G, M, or K, Kbytes is assumed by + default. Do not use GB, MB, or KB. + + + + + Here are some examples: + + BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" + BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" + + The first example works only if you also provide + the BB_DISKMON_WARNINTERVAL variable + in the conf/local.conf. + This example causes the build system to immediately + abort when either the disk space in ${TMPDIR} drops + below 1 Gbyte or the available free inodes drops below + 100 Kbytes. + Because two directories are provided with the variable, the + build system also issue a + warning when the disk space in the + ${SSTATE_DIR} directory drops + below 1 Gbyte or the number of free inodes drops + below 100 Kbytes. + Subsequent warnings are issued during intervals as + defined by the BB_DISKMON_WARNINTERVAL + variable. + + + + The second example stops the build after all currently + executing tasks complete when the minimum disk space + in the ${TMPDIR} + directory drops below 1 Gbyte. + No disk monitoring occurs for the free inodes in this case. + + + + The final example immediately aborts the build when the + number of free inodes in the ${TMPDIR} directory + drops below 100 Kbytes. + No disk space monitoring for the directory itself occurs + in this case. + + + + + BB_DISKMON_WARNINTERVAL + + + Defines the disk space and free inode warning intervals. + To set these intervals, define the variable in your + conf/local.conf file in the + Build Directory. + + + + If you are going to use the + BB_DISKMON_WARNINTERVAL variable, you must + also use the + BB_DISKMON_DIRS variable + and define its action as "WARN". + During the build, subsequent warnings are issued each time + disk space or number of free inodes further reduces by + the respective interval. + + + + If you do not provide a BB_DISKMON_WARNINTERVAL + variable and you do use BB_DISKMON_DIRS with + the "WARN" action, the disk monitoring interval defaults to + the following: + + BB_DISKMON_WARNINTERVAL = "50M,5K" + + + + + When specifying the variable in your configuration file, + use the following form: + + BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval" + + where: + + disk_space_interval is: + An interval of memory expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + disk_inode_interval is: + An interval of free inodes expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + + + + Here is an example: + + BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_WARNINTERVAL = "50M,5K" + + These variables cause the OpenEmbedded build system to + issue subsequent warnings each time the available + disk space further reduces by 50 Mbytes or the number + of free inodes further reduces by 5 Kbytes in the + ${SSTATE_DIR} directory. + Subsequent warnings based on the interval occur each time + a respective interval is reached beyond the initial warning + (i.e. 1 Gbytes and 100 Kbytes). + + + + + BB_GENERATE_MIRROR_TARBALLS + + + Causes tarballs of the Git repositories, including the + Git metadata, to be placed in the + DL_DIR + directory. + + + + For performance reasons, creating and placing tarballs of + the Git repositories is not the default action by the + OpenEmbedded build system. + + BB_GENERATE_MIRROR_TARBALLS = "1" + + Set this variable in your local.conf + file in the + Build Directory. + + + + + BB_NUMBER_THREADS + + + The maximum number of tasks BitBake should run in parallel + at any one time. + If your host development system supports multiple cores, + a good rule of thumb is to set this variable to twice the + number of cores. + + + + The default value for BB_NUMBER_THREADS + is equal to the number of cores your build system has. + + + + + BBCLASSEXTEND + + + Allows you to extend a recipe so that it builds variants of the software. + Common variants for recipes exist such as "natives" like quilt-native, + which is a copy of Quilt built to run on the build system; + "crosses" such as gcc-cross, + which is a compiler built to run on the build machine but produces binaries + that run on the target MACHINE; + "nativesdk", which targets the SDK machine instead of MACHINE; + and "mulitlibs" in the form "multilib:multilib_name". + + + + To build a different variant of the recipe with a minimal amount of code, it usually + is as simple as adding the following to your recipe: + + BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:multilib_name" + + + + + + BBFILE_COLLECTIONS + + Lists the names of configured layers. + These names are used to find the other BBFILE_* + variables. + Typically, each layer will append its name to this variable in its + conf/layer.conf file. + + + + + BBFILE_PATTERN + + Variable that expands to match files from + BBFILES + in a particular layer. + This variable is used in the conf/layer.conf file and must + be suffixed with the name of the specific layer (e.g. + BBFILE_PATTERN_emenlow). + + + + BBFILE_PRIORITY + + Assigns the priority for recipe files in each layer. + This variable is useful in situations where the same recipe appears in + more than one layer. + Setting this variable allows you to prioritize a + layer against other layers that contain the same recipe - effectively + letting you control the precedence for the multiple layers. + The precedence established through this variable stands regardless of a + recipe's version + (PV variable). + For example, a layer that has a recipe with a higher PV value but for + which the BBFILE_PRIORITY is set to have a lower precedence still has a + lower precedence. + A larger value for the BBFILE_PRIORITY variable results in a higher + precedence. + For example, the value 6 has a higher precedence than the value 5. + If not specified, the BBFILE_PRIORITY variable is set based on layer + dependencies (see the + LAYERDEPENDS variable for + more information. + The default priority, if unspecified + for a layer with no dependencies, is the lowest defined priority + 1 + (or 1 if no priorities are defined). + + You can use the command bitbake-layers show-layers to list + all configured layers along with their priorities. + + + + + BBFILES + + List of recipe files used by BitBake to build software. + + + + BBINCLUDELOGS + + Variable that controls how BitBake displays logs on build failure. + + + + BBLAYERS + + Lists the layers to enable during the build. + This variable is defined in the bblayers.conf configuration + file in the Build Directory. + Here is an example: + + 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 \ + " + + This example enables four layers, one of which is a custom, user-defined layer + named meta-mykernel. + + + + + BBLAYERS_NON_REMOVABLE + + Lists core layers that cannot be removed from the + bblayers.conf file during a build + using the + Hob. + + When building an image outside of Hob, this variable + is ignored. + + In order for BitBake to build your image using Hob, your + bblayers.conf file must include the + meta and meta-yocto + core layers. + Here is an example that shows these two layers listed in + the BBLAYERS_NON_REMOVABLE statement: + + 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 \ + " + + + + + + BBMASK + + + Prevents BitBake from processing recipes and recipe + append files. + Use the BBMASK variable from within the + conf/local.conf file found + in the + Build Directory. + + + + You can use the BBMASK variable + to "hide" these .bb and + .bbappend files. + BitBake ignores any recipe or recipe append files that + match the expression. + It is as if BitBake does not see them at all. + Consequently, matching files are not parsed or otherwise + used by BitBake. + + The value you provide is passed to Python's regular + expression compiler. + The expression is compared against the full paths to + the files. + For complete syntax information, see Python's + documentation at + . + + + + The following example uses a complete regular expression + to tell BitBake to ignore all recipe and recipe append + files in the meta-ti/recipes-misc/ + directory: + + BBMASK = "meta-ti/recipes-misc/" + + If you want to mask out multiple directories or recipes, + use the vertical bar to separate the regular expression + fragments. + This next example masks out multiple directories and + individual recipes: + + BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/" + BBMASK .= "|.*meta-oe/recipes-support/" + BBMASK .= "|.*openldap" + BBMASK .= "|.*opencv" + BBMASK .= "|.*lzma" + + Notice how the vertical bar is used to append the fragments. + + When specifying a directory name, use the trailing + slash character to ensure you match just that directory + name. + + + + + + BBPATH + + + Used by BitBake to locate + .bbclass and configuration files. + This variable is analogous to the + PATH variable. + + If you run BitBake from a directory outside of the + Build Directory, + you must be sure to set + BBPATH to point to the + Build Directory. + Set the variable as you would any environment variable + and then run BitBake: + + $ BBPATH = "build_directory" + $ export BBPATH + $ bitbake target + + + + + + + BBSERVER + + + Points to the server that runs memory-resident BitBake. + This variable is set by the + oe-init-build-env-memres + setup script and should not be hand-edited. + The variable is only used when you employ memory-resident + BitBake. + The setup script exports the value as follows: + + export BBSERVER=localhost:$port + + For more information on how the + BBSERVER is used, see the + oe-init-build-env-memres script, which + is located in the + Source Directory. + + + + + BINCONFIG + + + When inheriting the + binconfig-disabled + class, this variable specifies binary configuration + scripts to disable in favor of using + pkg-config to query the information. + The binconfig-disabled class will + modify the specified scripts to return an error so that + calls to them can be easily found and replaced. + + + + To add multiple scripts, separate them by spaces. + Here is an example from the libpng + recipe: + + BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" + + + + + + BINCONFIG_GLOB + + + When inheriting the + binconfig + class, this variable specifies a wildcard for + configuration scripts that need editing. + The scripts are edited to correct any paths that have been + set up during compilation so that they are correct for + use when installed into the sysroot and called by the + build processes of other recipes. + + + + For more information on how this variable works, see + meta/classes/binconfig.bbclass in the + Source Directory. + You can also find general information on the class in the + "binconfig.bbclass" + section. + + + + + BP + + The base recipe name and version but without any special + recipe name suffix (i.e. -native, lib64-, + and so forth). + BP is comprised of the following: + + ${BPN}-${PV} + + + + + BPN + + The bare name of the recipe. + This variable is a version of the PN variable + but removes common suffixes such as "-native" and "-cross" as well + as removes common prefixes such as multilib's "lib64-" and "lib32-". + The exact list of suffixes removed is specified by the + SPECIAL_PKGSUFFIX variable. + The exact list of prefixes removed is specified by the + MLPREFIX variable. + Prefixes are removed for multilib + and nativesdk cases. + + + + BUGTRACKER + + + Specifies a URL for an upstream bug tracking website for + a recipe. + The OpenEmbedded build system does not use this variable. + Rather, the variable is a useful pointer in case a bug + in the software being built needs to be manually reported. + + + + + BUILD_CFLAGS + + + Specifies the flags to pass to the C compiler when building + for the build host. + When building in the -native context, + CFLAGS + is set to the value of this variable by default. + + + + + BUILD_CPPFLAGS + + + 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 native context, + CPPFLAGS + is set to the value of this variable by default. + + + + + BUILD_CXXFLAGS + + + Specifies the flags to pass to the C++ compiler when + building for the build host. + When building in the native context, + CXXFLAGS + is set to the value of this variable by default. + + + + + BUILD_LDFLAGS + + + Specifies the flags to pass to the linker when building + for the build host. + When building in the -native context, + LDFLAGS + is set to the value of this variable by default. + + + + + BUILD_OPTIMIZATION + + + Specifies the optimization flags passed to the C compiler + when building for the build host or the SDK. + The flags are passed through the + BUILD_CFLAGS + and + BUILDSDK_CFLAGS + default values. + + + + The default value of the + BUILD_OPTIMIZATION variable is + "-O2 -pipe". + + + + + BUILDDIR + + + Points to the location of the + Build Directory. + You can define this directory indirectly through the + &OE_INIT_FILE; + and + oe-init-build-env-memres + scripts by passing in a Build Directory path when you run + the scripts. + If you run the scripts and do not provide a Build Directory + path, the BUILDDIR defaults to + build in the current directory. + + + + + BUILDHISTORY_COMMIT + + + When inheriting the + buildhistory + class, this variable specifies whether or not to commit the + build history output in a local Git repository. + If set to "1", this local repository will be maintained + automatically by the + buildhistory + class and a commit will be created on every + build for changes to each top-level subdirectory of the + build history output (images, packages, and sdk). + If you want to track changes to build history over + time, you should set this value to "1". + + + + By default, the buildhistory class + does not commit the build history output in a local + Git repository: + + BUILDHISTORY_COMMIT ?= "0" + + + + + + BUILDHISTORY_COMMIT_AUTHOR + + + When inheriting the + buildhistory + class, this variable specifies the author to use for each + Git commit. + In order for the BUILDHISTORY_COMMIT_AUTHOR + variable to work, the + BUILDHISTORY_COMMIT + variable must be set to "1". + + + + Git requires that the value you provide for the + BUILDHISTORY_COMMIT_AUTHOR variable + takes the form of "name <email@host>". + Providing an email address or host that is not valid does + not produce an error. + + + + By default, the buildhistory class + sets the variable as follows: + + BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" + + + + + + BUILDHISTORY_DIR + + + When inheriting the + buildhistory + class, this variable specifies the directory in which + build history information is kept. + For more information on how the variable works, see the + buildhistory.class. + + + + By default, the buildhistory class + sets the directory as follows: + + BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" + + + + + + BUILDHISTORY_FEATURES + + + When inheriting the + buildhistory + class, this variable specifies the build history features + to be enabled. + For more information on how build history works, see the + "Maintaining Build Output Quality" + section. + + + + You can specify three features in the form of a + space-separated list: + + image: + Analysis of the contents of images, which + includes the list of installed packages among other + things. + + package: + Analysis of the contents of individual packages. + + sdk: + Analysis of the contents of the software + development kit (SDK). + + + + + + By default, the buildhistory class + enables all three features: + + BUILDHISTORY_FEATURES ?= "image package sdk" + + + + + + BUILDHISTORY_IMAGE_FILES + + + When inheriting the + buildhistory + class, this variable specifies a list of paths to files + copied from the + image contents into the build history directory under + an "image-files" directory in the directory for + the image, so that you can track the contents of each file. + The default is to copy /etc/passwd + and /etc/group, which allows you to + monitor for changes in user and group entries. + You can modify the list to include any file. + Specifying an invalid path does not produce an error. + Consequently, you can include files that might + not always be present. + + + + By default, the buildhistory class + provides paths to the following files: + + BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" + + + + + + BUILDHISTORY_PUSH_REPO + + + When inheriting the + buildhistory + class, this variable optionally specifies a remote + repository to which build history pushes Git changes. + In order for BUILDHISTORY_PUSH_REPO + to work, + BUILDHISTORY_COMMIT + must be set to "1". + + + + The repository should correspond to a remote + address that specifies a repository as understood by + Git, or alternatively to a remote name that you have + set up manually using git remote + within the local repository. + + + + By default, the buildhistory class + sets the variable as follows: + + BUILDHISTORY_PUSH_REPO ?= "" + + + + + + BUILDSDK_CFLAGS + + + Specifies the flags to pass to the C compiler when building + for the SDK. + When building in the nativesdk + context, + CFLAGS + is set to the value of this variable by default. + + + + + BUILDSDK_CPPFLAGS + + + 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 nativesdk + context, + CPPFLAGS + is set to the value of this variable by default. + + + + + BUILDSDK_CXXFLAGS + + + Specifies the flags to pass to the C++ compiler when + building for the SDK. + When building in the nativesdk + context, + CXXFLAGS + is set to the value of this variable by default. + + + + + BUILDSDK_LDFLAGS + + + Specifies the flags to pass to the linker when building + for the SDK. + When building in the nativesdk- + context, + LDFLAGS + is set to the value of this variable by default. + + + + + BUILDSTATS_BASE + + + Points to the location of the directory that holds build + statistics when you use and enable the + buildstats + class. + The BUILDSTATS_BASE directory defaults + to + ${TMPDIR}/buildstats/. + + + + + BUSYBOX_SPLIT_SUID + + + For the BusyBox recipe, specifies whether to split the + output executable file into two parts: one for features + that require setuid root, and one for + the remaining features (i.e. those that do not require + setuid root). + + + + The BUSYBOX_SPLIT_SUID variable + defaults to "1", which results in a single output + executable file. + Set the variable to "0" to split the output file. + + + + + + + C + + CFLAGS + + + Specifies the flags to pass to the C compiler. + This variable is exported to an environment + variable and thus made visible to the software being + built during the compilation step. + + + + Default initialization for CFLAGS + varies depending on what is being built: + + + TARGET_CFLAGS + when building for the target + + + BUILD_CFLAGS + when building for the build host (i.e. + -native) + + + BUILDSDK_CFLAGS + when building for an SDK (i.e. + nativesdk-) + + + + + + + CLASSOVERRIDE + + + An internal variable specifying the special class override + that should currently apply (e.g. "class-target", + "class-native", and so forth). + The classes that use this variable set it to + appropriate values. + + + + You do not normally directly interact with this variable. + The value for the CLASSOVERRIDE + variable goes into + OVERRIDES + and then can be used as an override. + Here is an example where "python-native" is added to + DEPENDS + only when building for the native case: + + DEPENDS_append_class-native = " python-native" + + + + + + COMBINED_FEATURES + + + Provides a list of hardware features that are enabled in + both + MACHINE_FEATURES + and + DISTRO_FEATURES. + This select list of features contains features that make + sense to be controlled both at the machine and distribution + configuration level. + For example, the "bluetooth" feature requires hardware + support but should also be optional at the distribution + level, in case the hardware supports Bluetooth but you + do not ever intend to use it. + + + + For more information, see the + MACHINE_FEATURES + and DISTRO_FEATURES + variables. + + + + + COMMON_LICENSE_DIR + + + Points to meta/files/common-licenses + in the + Source Directory, + which is where generic license files reside. + + + + + COMPATIBLE_HOST + + A regular expression that resolves to one or more hosts + (when the recipe is native) or one or more targets (when + the recipe is non-native) with which a recipe is compatible. + The regular expression is matched against + HOST_SYS. + You can use the variable to stop recipes from being built + for classes of systems with which the recipes are not + compatible. + Stopping these builds is particularly useful with kernels. + The variable also helps to increase parsing speed + since the build system skips parsing recipes not + compatible with the current system. + + + + COMPATIBLE_MACHINE + + A regular expression that resolves to one or more + target machines with which a recipe is compatible. + The regular expression is matched against + MACHINEOVERRIDES. + You can use the variable to stop recipes from being built + for machines with which the recipes are not compatible. + Stopping these builds is particularly useful with kernels. + The variable also helps to increase parsing speed + since the build system skips parsing recipes not + compatible with the current machine. + + + + COMPLEMENTARY_GLOB + + + Defines wildcards to match when installing a list of + complementary packages for all the packages explicitly + (or implicitly) installed in an image. + The resulting list of complementary packages is associated + with an item that can be added to + IMAGE_FEATURES. + An example usage of this is the "dev-pkgs" item that when + added to IMAGE_FEATURES will + install -dev packages (containing headers and other + development files) for every package in the image. + + + + To add a new feature item pointing to a wildcard, use a + variable flag to specify the feature item name and + use the value to specify the wildcard. + Here is an example: + + COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' + + + + + + CONFFILES + + + Identifies editable or configurable files that are part of a package. + If the Package Management System (PMS) is being used to update + packages on the target system, it is possible that + configuration files you have changed after the original installation + and that you now want to remain unchanged are overwritten. + In other words, editable files might exist in the package that you do not + want reset as part of the package update process. + You can use the CONFFILES variable to list the files in the + package that you wish to prevent the PMS from overwriting during this update process. + + + + To use the CONFFILES variable, provide a package name + override that identifies the resulting package. + Then, provide a space-separated list of files. + Here is an example: + + CONFFILES_${PN} += "${sysconfdir}/file1 \ + ${sysconfdir}/file2 ${sysconfdir}/file3" + + + + + A relationship exists between the CONFFILES and + FILES variables. + The files listed within CONFFILES must be a subset of + the files listed within FILES. + Because the configuration files you provide with CONFFILES + are simply being identified so that the PMS will not overwrite them, + it makes sense that + the files must already be included as part of the package through the + FILES variable. + + + + When specifying paths as part of the CONFFILES variable, + it is good practice to use appropriate path variables. + For example, ${sysconfdir} rather than + /etc or ${bindir} rather + than /usr/bin. + You can find a list of these variables at the top of the + meta/conf/bitbake.conf file in the + Source Directory. + + + + + CONFIG_INITRAMFS_SOURCE + + + Identifies the initial RAM disk (initramfs) source files. + The OpenEmbedded build system receives and uses + this kernel Kconfig variable as an environment variable. + By default, the variable is set to null (""). + + + + The CONFIG_INITRAMFS_SOURCE can be + either a single cpio archive with a + .cpio suffix or a + space-separated list of directories and files for building + the initramfs image. + A cpio archive should contain a filesystem archive + to be used as an initramfs image. + Directories should contain a filesystem layout to be + included in the initramfs image. + Files should contain entries according to the format + described by the + usr/gen_init_cpio program in the + kernel tree. + + + + If you specify multiple directories and files, the + initramfs image will be the aggregate of all of them. + + + + + CONFIG_SITE + + + A list of files that contains autoconf test results relevant + to the current build. + This variable is used by the Autotools utilities when running + configure. + + + + + CONFLICT_DISTRO_FEATURES + + + When inheriting the + distro_features_check + class, this + variable identifies distribution features that would + be in conflict should the recipe + be built. + In other words, if the + CONFLICT_DISTRO_FEATURES variable + lists a feature that also appears in + DISTRO_FEATURES within the + current configuration, an error occurs and the + build stops. + + + + + COPY_LIC_DIRS + + + If set to "1" along with the + COPY_LIC_MANIFEST + variable, the OpenEmbedded build system copies + into the image the license files, which are located in + /usr/share/common-licenses, + for each package. + The license files are placed + in directories within the image itself. + + + + + COPY_LIC_MANIFEST + + + If set to "1", the OpenEmbedded build system copies + the license manifest for the image to + /usr/share/common-licenses/license.manifest + within the image itself. + + + + + CORE_IMAGE_EXTRA_INSTALL + + + Specifies the list of packages to be added to the image. + You should only set this variable in the + local.conf configuration file found + in the + Build Directory. + + + + This variable replaces POKY_EXTRA_INSTALL, which is no longer supported. + + + + + COREBASE + + + Specifies the parent directory of the OpenEmbedded + Core Metadata layer (i.e. meta). + + + + It is an important distinction that + COREBASE points to the parent of this + layer and not the layer itself. + Consider an example where you have cloned the Poky Git + repository and retained the poky + name for your local copy of the repository. + In this case, COREBASE points to + the poky folder because it is the + parent directory of the poky/meta + layer. + + + + + CPPFLAGS + + + Specifies the flags to pass to the C pre-processor + (i.e. to both the C and the C++ compilers). + This variable is exported to an environment + variable and thus made visible to the software being + built during the compilation step. + + + + Default initialization for CPPFLAGS + varies depending on what is being built: + + + TARGET_CPPFLAGS + when building for the target + + + BUILD_CPPFLAGS + when building for the build host (i.e. + -native) + + + BUILDSDK_CPPFLAGS + when building for an SDK (i.e. + nativesdk-) + + + + + + + CXXFLAGS + + + Specifies the flags to pass to the C++ compiler. + This variable is exported to an environment + variable and thus made visible to the software being + built during the compilation step. + + + + Default initialization for CXXFLAGS + varies depending on what is being built: + + + TARGET_CXXFLAGS + when building for the target + + + BUILD_CXXFLAGS + when building for the build host (i.e. + -native) + + + BUILDSDK_CXXFLAGS + when building for an SDK (i.e. + nativesdk) + + + + + + + + + D + + D + + + The destination directory. + The location in the Build Directory + where components are installed by the + do_install + task. + This location defaults to: + + ${WORKDIR}/image + + + + + + DATETIME + + + The date and time on which the current build started. + The format is suitable for timestamps. + + + + + DEBUG_BUILD + + + Specifies to build packages with debugging information. + This influences the value of the + SELECTED_OPTIMIZATION + variable. + + + + + DEBUG_OPTIMIZATION + + + The options to pass in + TARGET_CFLAGS + and CFLAGS when compiling + a system for debugging. + This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". + + + + + DEFAULT_PREFERENCE + + + Specifies a weak bias for recipe selection priority. + + + The most common usage of this is variable is to set + it to "-1" within a recipe for a development version of a + piece of software. + Using the variable in this way causes the stable version + of the recipe to build by default in the absence of + PREFERRED_VERSION + being used to build the development version. + + + The bias provided by DEFAULT_PREFERENCE + is weak and is overridden by + BBFILE_PRIORITY + if that variable is different between two layers + that contain different versions of the same recipe. + + + + + DEFAULTTUNE + + + The default CPU and Application Binary Interface (ABI) + tunings (i.e. the "tune") used by the OpenEmbedded build + system. + The DEFAULTTUNE helps define + TUNE_FEATURES. + + + + The default tune is either implicitly or explicitly set + by the machine + (MACHINE). + However, you can override the setting using available tunes + as defined with + AVAILTUNES. + + + + + DEPENDS + + + Lists a recipe's build-time dependencies + (i.e. other recipe files). + The system ensures that all the dependencies listed + have been built and have their contents in the appropriate + sysroots before the recipe's configure task is executed. + + + + Consider this simple example for two recipes named "a" and + "b" that produce similarly named packages. + In this example, the DEPENDS + statement appears in the "a" recipe: + + DEPENDS = "b" + + Here, the dependency is such that the + do_configure + task for recipe "a" depends on the + do_populate_sysroot + task of recipe "b". + This means anything that recipe "b" puts into sysroot + is available when recipe "a" is configuring itself. + + + + For information on runtime dependencies, see the + RDEPENDS + variable. + + + + + DEPLOY_DIR + + + Points to the general area that the OpenEmbedded build + system uses to place images, packages, SDKs and other output + files that are ready to be used outside of the build system. + By default, this directory resides within the + Build Directory + as ${TMPDIR}/deploy. + + + + For more information on the structure of the Build + Directory, see + "The Build Directory - build/" + section. + For more detail on the contents of the + deploy directory, see the + "Images" and + "Application Development SDK" + sections. + + + + + DEPLOY_DIR_IMAGE + + + Points to the area that the OpenEmbedded build system uses + to place images and other associated output files that are + ready to be deployed onto the target machine. + The directory is machine-specific as it contains the + ${MACHINE} name. + By default, this directory resides within the + Build Directory + as ${DEPLOY_DIR}/images/${MACHINE}/. + + + + For more information on the structure of the Build + Directory, see + "The Build Directory - build/" + section. + For more detail on the contents of the + deploy directory, see the + "Images" and + "Application Development SDK" + sections. + + + + + DEPLOYDIR + + + When inheriting the + deploy + class, the DEPLOYDIR points to a + temporary work area for deployed files that is set in the + deploy class as follows: + + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + + Recipes inheriting the deploy class + should copy files to be deployed into + DEPLOYDIR, and the class will take + care of copying them into + DEPLOY_DIR_IMAGE + afterwards. + + + + + DESCRIPTION + + The package description used by package managers. + If not set, DESCRIPTION takes + the value of the + SUMMARY + variable. + + + + + DISK_SIGNATURE + + + A 32-bit MBR disk signature used by + directdisk images. + + + + By default, the signature is set to an automatically + generated random value that allows the OpenEmbedded + build system to create a boot loader. + You can override the signature in the image recipe + by setting DISK_SIGNATURE to an + 8-digit hex string. + You might want to override + DISK_SIGNATURE if you want the disk + signature to remain constant between image builds. + + + + When using Linux 3.8 or later, you can use + DISK_SIGNATURE to specify the root + by UUID to allow the kernel to locate the root device + even if the device name changes due to differences in + hardware configuration. + By default, SYSLINUX_ROOT is set + as follows: + + SYSLINUX_ROOT = "root=/dev/sda2" + + However, you can change this to locate the root device + using the disk signature instead: + + SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02" + + + + + As previously mentioned, it is possible to set the + DISK_SIGNATURE variable in your + local.conf file to a fixed + value if you do not want syslinux.cfg + changing for each build. + You might find this useful when you want to upgrade the + root filesystem on a device without having to recreate or + modify the master boot record. + + + + + DISTRO + + + The short name of the distribution. + This variable corresponds to a distribution + configuration file whose root name is the same as the + variable's argument and whose filename extension is + .conf. + For example, the distribution configuration file for the + Poky distribution is named poky.conf + and resides in the + meta-yocto/conf/distro directory of + the + Source Directory. + + + + Within that poky.conf file, the + DISTRO variable is set as follows: + + DISTRO = "poky" + + + + + Distribution configuration files are located in a + conf/distro directory within the + Metadata + that contains the distribution configuration. + The value for DISTRO must not contain + spaces, and is typically all lower-case. + + If the DISTRO variable is blank, a set + of default configurations are used, which are specified + within + meta/conf/distro/defaultsetup.conf + also in the Source Directory. + + + + + + DISTRO_EXTRA_RDEPENDS + + + Specifies a list of distro-specific packages to add to all images. + This variable takes affect through + packagegroup-base so the + variable only really applies to the more full-featured + images that include packagegroup-base. + You can use this variable to keep distro policy out of + generic images. + As with all other distro variables, you set this variable + in the distro .conf file. + + + + + DISTRO_EXTRA_RRECOMMENDS + + + Specifies a list of distro-specific packages to add to all images + if the packages exist. + The packages might not exist or be empty (e.g. kernel modules). + The list of packages are automatically installed but you can + remove them. + + + + + DISTRO_FEATURES + + + The software support you want in your distribution for + various features. + You define your distribution features in the distribution + configuration file. + + + + In most cases, the presence or absence of a feature in + DISTRO_FEATURES is translated to the + appropriate option supplied to the configure script + during the + do_configure + task for recipes that optionally support the feature. + For example, specifying "x11" in + DISTRO_FEATURES, causes + every piece of software built for the target that can + optionally support X11 to have its X11 support enabled. + + + + Two more examples are Bluetooth and NFS support. + For a more complete list of features that ships with the + Yocto Project and that you can provide with this variable, + see the + "Distro Features" + section. + + + + + DISTRO_FEATURES_BACKFILL + + Features to be added to + DISTRO_FEATURES + if not also present in + DISTRO_FEATURES_BACKFILL_CONSIDERED. + + + + This variable is set in the meta/conf/bitbake.conf file. + It is not intended to be user-configurable. + It is best to just reference the variable to see which distro features are + being backfilled for all distro configurations. + See the Feature backfilling section for + more information. + + + + + DISTRO_FEATURES_BACKFILL_CONSIDERED + + Features from + DISTRO_FEATURES_BACKFILL + that should not be backfilled (i.e. added to + DISTRO_FEATURES) + during the build. + See the "Feature Backfilling" section for + more information. + + + + + DISTRO_NAME + + The long name of the distribution. + + + + DISTRO_PN_ALIAS + + Alias names used for the recipe in various Linux distributions. + See the + "Handling + a Package Name Alias" section in the Yocto Project Development + Manual for more information. + + + + DISTRO_VERSION + + The version of the distribution. + + + + DISTROOVERRIDES + + + This variable lists overrides specific to the current + distribution. + By default, the variable list includes the value of the + DISTRO + variable. + You can extend the variable to apply any variable overrides + you want as part of the distribution and are not + already in OVERRIDES through + some other means. + + + + + DL_DIR + + + The central download directory used by the build process to + store downloads. + By default, DL_DIR gets files + suitable for mirroring for everything except Git + repositories. + If you want tarballs of Git repositories, use the + BB_GENERATE_MIRROR_TARBALLS + variable. + + + + You can set this directory by defining the + DL_DIR variable in the + conf/local.conf file. + This directory is self-maintaining and you should not have + to touch it. + By default, the directory is downloads + in the + Build Directory. + + #DL_DIR ?= "${TOPDIR}/downloads" + + To specify a different download directory, simply remove + the comment from the line and provide your directory. + + + + During a first build, the system downloads many different + source code tarballs from various upstream projects. + Downloading can take a while, particularly if your network + connection is slow. + Tarballs are all stored in the directory defined by + DL_DIR and the build system looks there + first to find source tarballs. + + When wiping and rebuilding, you can preserve this + directory to speed up this part of subsequent + builds. + + + + + You can safely share this directory between multiple builds + on the same development machine. + For additional information on how the build process gets + source files when working behind a firewall or proxy server, + see this specific question in the + "FAQ" + chapter. + + + + + DOC_COMPRESS + + + When inheriting the + compress_doc + class, this variable sets the compression policy used when + the OpenEmbedded build system compresses man pages and info + pages. + By default, the compression method used is gz (gzip). + Other policies available are xz and bz2. + + + + For information on policies and on how to use this + variable, see the comments in the + meta/classes/compress_doc.bbclass file. + + + + + + + E + + EFI_PROVIDER + + + When building bootable images (i.e. where + hddimg or vmdk + is in + IMAGE_FSTYPES), + The EFI_PROVIDER variable specifies + the EFI bootloader to use. + The default is "grub-efi", but "gummiboot" can be used + instead. + + + + See the + gummiboot + class for more information. + + + + + ENABLE_BINARY_LOCALE_GENERATION + + Variable that controls which locales for + glibc are generated during the + build (useful if the target device has 64Mbytes + of RAM or less). + + + + ERROR_QA + + + Specifies the quality assurance checks whose failures are + reported as errors by the OpenEmbedded build system. + You set this variable in your distribution configuration + file. + For a list of the checks you can control with this variable, + see the + "insane.bbclass" + section. + + + + + ERR_REPORT_DIR + + + When used with the + report-error + class, specifies the path used for storing the debug files + created by the + error reporting tool, + which allows you to submit build errors you encounter to a + central database. + By default, the value of this variable is + ${LOG_DIR}/error-report. + + + + You can set ERR_REPORT_DIR to the path + you want the error reporting tool to store the debug files + as follows in your local.conf file: + + ERR_REPORT_DIR = "path" + + + + + + EXCLUDE_FROM_WORLD + + + Directs BitBake to exclude a recipe from world builds (i.e. + bitbake world). + During world builds, BitBake locates, parses and builds all + recipes found in every layer exposed in the + bblayers.conf configuration file. + + + + To exclude a recipe from a world build using this variable, + set the variable to "1" in the recipe. + + + + Recipes added to EXCLUDE_FROM_WORLD + may still be built during a world build in order to satisfy + dependencies of other recipes. + Adding a recipe to EXCLUDE_FROM_WORLD + only ensures that the recipe is not explicitly added + to the list of build targets in a world build. + + + + + EXTENDPE + + + Used with file and pathnames to create a prefix for a recipe's + version based on the recipe's + PE value. + If PE is set and greater than zero for a recipe, + EXTENDPE becomes that value (e.g if + PE is equal to "1" then EXTENDPE + becomes "1_"). + If a recipe's PE is not set (the default) or is equal to + zero, EXTENDPE becomes "". + See the STAMP + variable for an example. + + + + + EXTENDPKGV + + + The full package version specification as it appears on the + final packages produced by a recipe. + The variable's value is normally used to fix a runtime + dependency to the exact same version of another package + in the same recipe: + + RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" + + + + + The dependency relationships are intended to force the + package manager to upgrade these types of packages in + lock-step. + + + + + EXTERNALSRC + + + When inheriting the + externalsrc + class, this variable points to the source tree, which is + outside of the OpenEmbedded build system. + When set, this variable sets the + S + variable, which is what the OpenEmbedded build system uses + to locate unpacked recipe source code. + + + + For more information on + externalsrc.bbclass, see the + "externalsrc.bbclass" + section. + You can also find information on how to use this variable + in the + "Building Software from an External Source" + section in the Yocto Project Development Manual. + + + + + EXTERNALSRC_BUILD + + + When inheriting the + externalsrc + class, this variable points to the directory in which the + recipe's source code is built, which is outside of the + OpenEmbedded build system. + When set, this variable sets the + B + variable, which is what the OpenEmbedded build system uses + to locate the Build Directory. + + + + For more information on + externalsrc.bbclass, see the + "externalsrc.bbclass" + section. + You can also find information on how to use this variable + in the + "Building Software from an External Source" + section in the Yocto Project Development Manual. + + + + + EXTRA_IMAGE_FEATURES + + + The list of additional features to include in an image. + Typically, you configure this variable in your + local.conf file, which is found in the + Build Directory. + Although you can use this variable from within a recipe, + best practices dictate that you do not. + + To enable primary features from within the image + recipe, use the + IMAGE_FEATURES + variable. + + + + + Here are some examples of features you can add: + +"dbg-pkgs" - Adds -dbg packages for all installed packages + including symbol information for debugging and + profiling. + +"debug-tweaks" - Makes an image suitable for development. + For example, ssh root access has a blank + password. You should remove this feature + before you produce a production image. + +"dev-pkgs" - Adds -dev packages for all installed packages. + This is useful if you want to develop against + the libraries in the image. + +"read-only-rootfs" - Creates an image whose root + filesystem is read-only. See the + "Creating a Read-Only Root Filesystem" + section in the Yocto Project + Development Manual for more + information + +"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. + +"tools-testapps" - Adds useful testing tools such as + ts_print, aplay, arecord and so + forth. + + + + + + For a complete list of image features that ships with the + Yocto Project, see the + "Image Features" + section. + + + + For an example that shows how to customize your image by + using this variable, see the + "Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES" + section in the Yocto Project Development Manual. + + + + + EXTRA_IMAGECMD + + + Specifies additional options for the image + creation command that has been specified in + IMAGE_CMD. + When setting this variable, you should + use an override for the associated type. + Here is an example: + + EXTRA_IMAGECMD_ext3 ?= "-i 4096" + + + + + + EXTRA_IMAGEDEPENDS + + A list of recipes to build that do not provide packages + for installing into the root filesystem. + + Sometimes a recipe is required to build the final image but is not + needed in the root filesystem. + You can use the EXTRA_IMAGEDEPENDS variable to + list these recipes and thus specify the dependencies. + A typical example is a required bootloader in a machine configuration. + + + To add packages to the root filesystem, see the various + *RDEPENDS + and *RRECOMMENDS + variables. + + + + + EXTRA_OECMAKE + + Additional cmake options. + + + + EXTRA_OECONF + + Additional configure script options. + + + + EXTRA_OEMAKE + + Additional GNU make options. + + + + EXTRA_OESCONS + + + When inheriting the + scons + class, this variable specifies additional configuration + options you want to pass to the + scons command line. + + + + + EXTRA_QMAKEVARS_POST + + + Configuration variables or options you want to pass to + qmake. + Use this variable when the arguments need to be after the + .pro file list on the command line. + + + + This variable is used with recipes that inherit the + qmake_base + class or other classes that inherit + qmake_base. + + + + + EXTRA_QMAKEVARS_PRE + + + Configuration variables or options you want to pass to + qmake. + Use this variable when the arguments need to be before the + .pro file list on the command line. + + + + This variable is used with recipes that inherit the + qmake_base + class or other classes that inherit + qmake_base. + + + + + EXTRA_USERS_PARAMS + + + When inheriting the + extrausers + class, this variable provides image level user and group + operations. + This is a more global method of providing user and group + configuration as compared to using the + useradd + class, which ties user and group configurations to a + specific recipe. + + + + The set list of commands you can configure using the + EXTRA_USERS_PARAMS is shown in the + extrausers class. + These commands map to the normal Unix commands of the same + names: + + # EXTRA_USERS_PARAMS = "\ + # useradd -p '' tester; \ + # groupadd developers; \ + # userdel nobody; \ + # groupdel -g video; \ + # groupmod -g 1020 developers; \ + # usermod -s /bin/sh tester; \ + # " + + + + + + + + F + + FEATURE_PACKAGES + + + Defines one or more packages to include in an image when + a specific item is included in + IMAGE_FEATURES. + When setting the value, FEATURE_PACKAGES + should have the name of the feature item as an override. + Here is an example: + + FEATURE_PACKAGES_widget = "package1 package2" + + In this example, if "widget" were added to + IMAGE_FEATURES, package1 and + package2 would be included in the image. + + Packages installed by features defined through + FEATURE_PACKAGES are often package + groups. + While similarly named, you should not confuse the + FEATURE_PACKAGES variable with + package groups, which are discussed elsewhere in the + documentation. + + + + + + FEED_DEPLOYDIR_BASE_URI + + + Points to the base URL of the server and location within + the document-root that provides the metadata and + packages required by OPKG to support runtime package + management of IPK packages. + You set this variable in your + local.conf file. + + + + Consider the following example: + + FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" + + This example assumes you are serving your packages over + HTTP and your databases are located in a directory + named BOARD-dir, which is underneath + your HTTP server's document-root. + In this case, the OpenEmbedded build system generates a set + of configuration files for you in your target that work + with the feed. + + + + + FILES + + + The list of directories or files that are placed in packages. + + + + To use the FILES variable, provide a + package name override that identifies the resulting package. + Then, provide a space-separated list of files or paths + that identify the files you want included as part of the + resulting package. + Here is an example: + + FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" + + + + + When specifying paths as part of the + FILES variable, it is good practice + to use appropriate path variables. + For example, use ${sysconfdir} rather + than /etc, or + ${bindir} rather than + /usr/bin. + You can find a list of these variables at the top of the + meta/conf/bitbake.conf file in the + Source Directory. + + + + If some of the files you provide with the + FILES variable are editable and you + know they should not be overwritten during the package + update process by the Package Management System (PMS), you + can identify these files so that the PMS will not + overwrite them. + See the + CONFFILES + variable for information on how to identify these files to + the PMS. + + + + + + FILESEXTRAPATHS + + + Extends the search path the OpenEmbedded build system uses + when looking for files and patches as it processes recipes + and append files. + The default directories BitBake uses when it processes + recipes are initially defined by the + FILESPATH + variable. + You can extend FILESPATH variable + by using FILESEXTRAPATHS. + + + + Best practices dictate that you accomplish this by using + FILESEXTRAPATHS from within a + .bbappend file and that you prepend + paths as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + In the above example, the build system first looks for files + in a directory that has the same name as the corresponding + append file. + + When extending FILESEXTRAPATHS, + be sure to use the immediate expansion + (:=) operator. + Immediate expansion makes sure that BitBake evaluates + THISDIR + at the time the directive is encountered rather than at + some later time when expansion might result in a + directory that does not contain the files you need. + + Also, include the trailing separating colon + character if you are prepending. + The trailing colon character is necessary because you + are directing BitBake to extend the path by prepending + directories to the search path. + + Here is another common use: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + + In this example, the build system extends the + FILESPATH variable to include a + directory named files that is in the + same directory as the corresponding append file. + + + + Here is a final example that specifically adds three paths: + + FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" + + + + + By prepending paths in .bbappend + files, you allow multiple append files that reside in + different layers but are used for the same recipe to + correctly extend the path. + + + + + FILESOVERRIDES + + + A subset of OVERRIDES + used by the OpenEmbedded build system for creating + FILESPATH. + You can find more information on how overrides are handled + in the + BitBake Manual. + + + + By default, the FILESOVERRIDES + variable is defined as: + + FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" + + + + Do not hand-edit the FILESOVERRIDES + variable. + The values match up with expected overrides and are + used in an expected manner by the build system. + + + + + + FILESPATH + + + The default set of directories the OpenEmbedded build system + uses when searching for patches and files. + During the build process, BitBake searches each directory in + FILESPATH in the specified order when + looking for files and patches specified by each + file:// URI in a recipe. + + + + The default value for the FILESPATH + variable is defined in the base.bbclass + class found in meta/classes in the + Source Directory: + + FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ + "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" + + + Do not hand-edit the FILESPATH + variable. + If you want the build system to look in directories + other than the defaults, extend the + FILESPATH variable by using the + FILESEXTRAPATHS + variable. + + Be aware that the default FILESPATH + directories do not map to directories in custom layers + where append files (.bbappend) + are used. + If you want the build system to find patches or files + that reside with your append files, you need to extend + the FILESPATH variable by using + the + FILESEXTRAPATHS + variable. + + + + + FILESYSTEM_PERMS_TABLES + + Allows you to define your own file permissions settings table as part of + your configuration for the packaging process. + For example, suppose you need a consistent set of custom permissions for + a set of groups and users across an entire work project. + It is best to do this in the packages themselves but this is not always + possible. + + + By default, the OpenEmbedded build system uses the fs-perms.txt, which + is located in the meta/files folder in the + Source Directory. + If you create your own file permissions setting table, you should place it in your + layer or the distro's layer. + + + You define the FILESYSTEM_PERMS_TABLES variable in the + conf/local.conf file, which is found in the + Build Directory, to + point to your custom fs-perms.txt. + You can specify more than a single file permissions setting table. + The paths you specify to these files must be defined within the + BBPATH variable. + + + For guidance on how to create your own file permissions settings table file, + examine the existing fs-perms.txt. + + + + + FONT_PACKAGES + + + When inheriting the + fontcache + class, this variable identifies packages containing font + files that need to be cached by Fontconfig. + By default, the fontcache class assumes + that fonts are in the recipe's main package + (i.e. ${PN}). + Use this variable if fonts you need are in a package + other than that main package. + + + + + FULL_OPTIMIZATION + + + The options to pass in + TARGET_CFLAGS + and CFLAGS + when compiling an optimized system. + This variable defaults to + "-O2 -pipe ${DEBUG_FLAGS}". + + + + + + G + + GLIBC_GENERATE_LOCALES + + + Specifies the list of GLIBC locales to generate should you + not wish generate all LIBC locals, which can be time + consuming. + + If you specifically remove the locale + en_US.UTF-8, you must set + IMAGE_LINGUAS + appropriately. + + You can set GLIBC_GENERATE_LOCALES + in your local.conf file. + By default, all locales are generated. + + GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" + + + + + + GROUPADD_PARAM + + + When inheriting the + useradd + class, this variable + specifies for a package what parameters should be passed + to the groupadd command + if you wish to add a group to the system when the package + is installed. + + + + Here is an example from the dbus + recipe: + + GROUPADD_PARAM_${PN} = "-r netdev" + + For information on the standard Linux shell command + groupadd, see + . + + + + + GROUPMEMS_PARAM + + + When inheriting the + useradd + class, this variable + specifies for a package what parameters should be passed + to the groupmems command + if you wish to modify the members of a group when the + package is installed. + + + + For information on the standard Linux shell command + groupmems, see + . + + + + + GRUB_GFXSERIAL + + + Configures the GNU GRand Unified Bootloader (GRUB) to have + graphics and serial in the boot menu. + Set this variable to "1" in your + local.conf or distribution + configuration file to enable graphics and serial + in the menu. + + + + See the + grub-efi + class for more information on how this variable is used. + + + + + GRUB_OPTS + + + Additional options to add to the GNU GRand Unified + Bootloader (GRUB) configuration. + Use a semi-colon character (;) to + separate multiple options. + + + + The GRUB_OPTS variable is optional. + See the + grub-efi + class for more information on how this variable is used. + + + + + GRUB_TIMEOUT + + + Specifies the timeout before executing the default + LABEL in the GNU GRand Unified + Bootloader (GRUB). + + + + The GRUB_TIMEOUT variable is optional. + See the + grub-efi + class for more information on how this variable is used. + + + + + GTKIMMODULES_PACKAGES + + + When inheriting the + gtk-immodules-cache + class, this variable specifies the packages that contain the + GTK+ input method modules being installed when the modules + are in packages other than the main package. + + + + + GUMMIBOOT_CFG + + + When + EFI_PROVIDER + is set to "gummiboot", the + GUMMIBOOT_CFG variable specifies the + configuration file that should be used. + By default, the + gummiboot + class sets the GUMMIBOOT_CFG as + follows: + + GUMMIBOOT_CFG ?= "${S}/loader.conf" + + + + + For information on Gummiboot, see the + Gummiboot documentation. + + + + + GUMMIBOOT_ENTRIES + + + When + EFI_PROVIDER + is set to "gummiboot", the + GUMMIBOOT_ENTRIES variable specifies + a list of entry files + (*.conf) to be installed + containing one boot entry per file. + By default, the + gummiboot + class sets the GUMMIBOOT_ENTRIES as + follows: + + GUMMIBOOT_ENTRIES ?= "" + + + + + For information on Gummiboot, see the + Gummiboot documentation. + + + + + GUMMIBOOT_TIMEOUT + + + When + EFI_PROVIDER + is set to "gummiboot", the + GUMMIBOOT_TIMEOUT variable specifies + the boot menu timeout in seconds. + By default, the + gummiboot + class sets the GUMMIBOOT_TIMEOUT as + follows: + + GUMMIBOOT_TIMEOUT ?= "10" + + + + + For information on Gummiboot, see the + Gummiboot documentation. + + + + + + + H + + HOMEPAGE + + Website where more information about the software the recipe is building + can be found. + + + + HOST_CC_ARCH + + + Specifies architecture-specific compiler flags that are + passed to the C compiler. + + + + Default initialization for HOST_CC_ARCH + varies depending on what is being built: + + + TARGET_CC_ARCH + when building for the target + + + BUILD_CC_ARCH + when building for the build host (i.e. + native) + + + BUILDSDK_CC_ARCH + when building for an SDK (i.e. + nativesdk) + + + + + + + HOST_SYS + + + Specifies the system, including the architecture and the + operating system, for with the build is occurring + in the context of the current + recipe. + The OpenEmbedded build system automatically sets this + variable. + You do not need to set the variable yourself. + + + + Here are two examples: + + Given a native recipe on a 32-bit + x86 machine running Linux, the value is + "i686-linux". + + Given a recipe being built for a + little-endian MIPS target running Linux, + the value might be "mipsel-linux". + + + + + + + + + I + + ICECC_DISABLED + + + Disables or enables the icecc + (Icecream) function. + For more information on this function and best practices + for using this variable, see the + "icecc.bbclass" + section. + + + + Setting this variable to "1" in your + local.conf disables the function: + + ICECC_DISABLED ??= "1" + + To enable the function, set the variable as follows: + + ICECC_DISABLED = "" + + + + + + ICECC_ENV_EXEC + + + Points to the icecc-create-env script + that you provide. + This variable is used by the + icecc + class. + You set this variable in your + local.conf file. + + + + If you do not point to a script that you provide, the + OpenEmbedded build system uses the default script provided + by the icecc-create-env.bb recipe, + which is a modified version and not the one that comes with + icecc. + + + + + ICECC_PARALLEL_MAKE + + + Extra options passed to the make + command during the + do_compile + task that specify parallel compilation. + This variable usually takes the form of + -j 4, where the number + represents the maximum number of parallel threads + make can run. + + The options passed affect builds on all enabled + machines on the network, which are machines running the + iceccd daemon. + + + + + If your enabled machines support multiple cores, + coming up with the maximum number of parallel threads + that gives you the best performance could take some + experimentation since machine speed, network lag, + available memory, and existing machine loads can all + affect build time. + Consequently, unlike the + PARALLEL_MAKE + variable, there is no rule-of-thumb for setting + ICECC_PARALLEL_MAKE to achieve + optimal performance. + + + + If you do not set ICECC_PARALLEL_MAKE, + the build system does not use it (i.e. the system does + not detect and assign the number of cores as is done with + PARALLEL_MAKE). + + + + + ICECC_PATH + + + The location of the icecc binary. + You can set this variable in your + local.conf file. + If your local.conf file does not define + this variable, the + icecc + class attempts to define it by locating + icecc using which. + + + + + ICECC_USER_CLASS_BL + + + Identifies user classes that you do not want the + Icecream distributed compile support to consider. + This variable is used by the + icecc + class. + You set this variable in your + local.conf file. + + + + When you list classes using this variable, you are + "blacklisting" them from distributed compilation across + remote hosts. + Any classes you list will be distributed and compiled + locally. + + + + + ICECC_USER_PACKAGE_BL + + + Identifies user recipes that you do not want the + Icecream distributed compile support to consider. + This variable is used by the + icecc + class. + You set this variable in your + local.conf file. + + + + When you list packages using this variable, you are + "blacklisting" them from distributed compilation across + remote hosts. + Any packages you list will be distributed and compiled + locally. + + + + + ICECC_USER_PACKAGE_WL + + + Identifies user recipes that use an empty + PARALLEL_MAKE + variable that you want to force remote distributed + compilation on using the Icecream distributed compile + support. + This variable is used by the + icecc + class. + You set this variable in your + local.conf file. + + + + + IMAGE_BASENAME + + + The base name of image output files. + This variable defaults to the recipe name + (${PN}). + + + + + IMAGE_BOOT_FILES + + + A space-separated list of files installed into the + boot partition when preparing an image. + By default, the files are installed under the same name as + the source files. + To change the installed name, separate it from the + original name with a semi-colon (;). + Source files need to be located in + DEPLOY_DIR_IMAGE. + Here are two examples: + + + IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" + IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" + + + + + IMAGE_CLASSES + + + A list of classes that all images should inherit. + You typically use this variable to specify the list of + classes that register the different types of images + the OpenEmbedded build system creates. + + + + The default value for IMAGE_CLASSES is + image_types. + You can set this variable in your + local.conf or in a distribution + configuration file. + + + + For more information, see + meta/classes/image_types.bbclass in the + Source Directory. + + + + + IMAGE_CMD + + + Specifies the command to create the image file for a + specific image type, which corresponds to the value set + set in + IMAGE_FSTYPES, + (e.g. ext3, + btrfs, and so forth). + When setting this variable, you should use + an override for the associated type. + Here is an example: + + IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ + --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ + ${EXTRA_IMAGECMD}" + + You typically do not need to set this variable unless + you are adding support for a new image type. + For more examples on how to set this variable, see the + image_types + class file, which is + meta/classes/image_types.bbclass. + + + + + IMAGE_DEVICE_TABLES + + + Specifies one or more files that contain custom device + tables that are passed to the + makedevs command as part of creating + an image. + These files list basic device nodes that should be + created under /dev within the image. + If IMAGE_DEVICE_TABLES is not set, + files/device_table-minimal.txt is + used, which is located by + BBPATH. + For details on how you should write device table files, + see meta/files/device_table-minimal.txt + as an example. + + + + + IMAGE_FEATURES + + + The primary list of features to include in an image. + Typically, you configure this variable in an image recipe. + Although you can use this variable from your + local.conf file, which is found in the + Build Directory, + best practices dictate that you do not. + + To enable extra features from outside the image recipe, + use the + EXTRA_IMAGE_FEATURES variable. + + For a list of image features that ships with the Yocto + Project, see the + "Image Features" + section. + + + + For an example that shows how to customize your image by + using this variable, see the + "Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES" + section in the Yocto Project Development Manual. + + + + + IMAGE_FSTYPES + + + Specifies the formats the OpenEmbedded build system uses + during the build when creating the root filesystem. + For example, setting IMAGE_FSTYPES + as follows causes the build system to create root + filesystems using two formats: .ext3 + and .tar.bz2: + + IMAGE_FSTYPES = "ext3 tar.bz2" + + For the complete list of supported image formats from which + you can choose, see + IMAGE_TYPES. + + + + If you add "live" to IMAGE_FSTYPES + inside an image recipe, be sure that you do so prior to the + "inherit image" line of the recipe or the live image will + not build. + + + + Due to the way this variable is processed, it is not + possible to update its contents using + _append or + _prepend. To add one or more + additional options to this variable the + += operator must be used. + + + + + IMAGE_INSTALL + + + Specifies the packages to install into an image. + The IMAGE_INSTALL variable is a + mechanism for an image recipe and you should use it + with care to avoid ordering issues. + + When working with an + core-image-minimal-initramfs + image, do not use the IMAGE_INSTALL + variable to specify packages for installation. + Instead, use the + PACKAGE_INSTALL + variable, which allows the initial RAM disk (initramfs) + recipe to use a fixed set of packages and not be + affected by IMAGE_INSTALL. + + + + + Image recipes set IMAGE_INSTALL + to specify the packages to install into an image through + image.bbclass. + Additionally, "helper" classes exist, such as + core-image.bbclass, that can take + IMAGE_FEATURES + lists and turn these into auto-generated entries in + IMAGE_INSTALL in addition to its + default contents. + + + + Using IMAGE_INSTALL with the + += operator from the + /conf/local.conf file or from within + an image recipe is not recommended as it can cause ordering + issues. + Since core-image.bbclass sets + IMAGE_INSTALL to a default value using + the ?= operator, using a + += operation against + IMAGE_INSTALL will result in + unexpected behavior when used in + conf/local.conf. + Furthermore, the same operation from within an image + recipe may or may not succeed depending on the specific + situation. + In both these cases, the behavior is contrary to how most + users expect the += operator to work. + + + + When you use this variable, it is best to use it as follows: + + IMAGE_INSTALL_append = " package-name" + + Be sure to include the space between the quotation character + and the start of the package name or names. + + + + + IMAGE_LINGUAS + + + Specifies the list of locales to install into the image + during the root filesystem construction process. + The OpenEmbedded build system automatically splits locale + files, which are used for localization, into separate + packages. + Setting the IMAGE_LINGUAS variable + ensures that any locale packages that correspond to packages + already selected for installation into the image are also + installed. + Here is an example: + + IMAGE_LINGUAS = "pt-br de-de" + + In this example, the build system ensures any Brazilian + Portuguese and German locale files that correspond to + packages in the image are installed (i.e. + *-locale-pt-br + and *-locale-de-de as well as + *-locale-pt + and *-locale-de, since some software + packages only provide locale files by language and not by + country-specific language). + + + + See the + GLIBC_GENERATE_LOCALES + variable for information on generating GLIBC locales. + + + + + IMAGE_MANIFEST + + + The manifest file for the image. + This file lists all the installed packages that make up + the image. + The file contains package information on a line-per-package + basis as follows: + + packagename packagearch version + + + + + The + image + class defines the manifest file as follows: + + IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" + + The location is derived using the + DEPLOY_DIR_IMAGE + and + IMAGE_NAME + variables. + You can find information on how the image + is created in the + "Image Generation" + section. + + + + + IMAGE_NAME + + + The name of the output image files minus the extension. + This variable is derived using the + IMAGE_BASENAME, + MACHINE, + and + DATETIME + variables: + + IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}" + + + + + + IMAGE_OVERHEAD_FACTOR + + + Defines a multiplier that the build system applies to the initial image + size for cases when the multiplier times the returned disk usage value + for the image is greater than the sum of + IMAGE_ROOTFS_SIZE + and + IMAGE_ROOTFS_EXTRA_SPACE. + The result of the multiplier applied to the initial image size creates + free disk space in the image as overhead. + By default, the build process uses a multiplier of 1.3 for this variable. + This default value results in 30% free disk space added to the image when this + method is used to determine the final generated image size. + You should be aware that post install scripts and the package management + system uses disk space inside this overhead area. + Consequently, the multiplier does not produce an image with + all the theoretical free disk space. + See IMAGE_ROOTFS_SIZE + for information on how the build system determines the overall image size. + + + + The default 30% free disk space typically gives the image enough room to boot + and allows for basic post installs while still leaving a small amount of + free disk space. + If 30% free space is inadequate, you can increase the default value. + For example, the following setting gives you 50% free space added to the image: + + IMAGE_OVERHEAD_FACTOR = "1.5" + + + + + Alternatively, you can ensure a specific amount of free disk space is added + to the image by using the + IMAGE_ROOTFS_EXTRA_SPACE + variable. + + + + + IMAGE_PKGTYPE + + + Defines the package type (DEB, RPM, IPK, or TAR) used + by the OpenEmbedded build system. + The variable is defined appropriately by the + package_deb, + package_rpm, + package_ipk, + or + package_tar + class. + + + + The + package_sdk_base + and + image + classes use the IMAGE_PKGTYPE for + packaging up images and SDKs. + + + + You should not set the IMAGE_PKGTYPE + manually. + Rather, the variable is set indirectly through the + appropriate + package_* + class using the + PACKAGE_CLASSES + variable. + The OpenEmbedded build system uses the first package type + (e.g. DEB, RPM, or IPK) that appears with the variable + + Files using the .tar format are + never used as a substitute packaging format for DEB, + RPM, and IPK formatted files for your image or SDK. + + + + + + IMAGE_POSTPROCESS_COMMAND + + + Added by classes to run post processing commands once the + OpenEmbedded build system has created the image. + You can specify shell commands separated by semicolons: + + IMAGE_POSTPROCESS_COMMAND += "shell_command; ... " + + If you need to pass the path to the root filesystem within + the command, you can use + ${IMAGE_ROOTFS}, which points to + the root filesystem image. + + + + + IMAGE_ROOTFS + + + The location of the root filesystem while it is under + construction (i.e. during the + do_rootfs + task). + This variable is not configurable. + Do not change it. + + + + + IMAGE_ROOTFS_ALIGNMENT + + + Specifies the alignment for the output image file in + Kbytes. + If the size of the image is not a multiple of + this value, then the size is rounded up to the nearest + multiple of the value. + The default value is "1". + See + IMAGE_ROOTFS_SIZE + for additional information. + + + + + IMAGE_ROOTFS_EXTRA_SPACE + + + Defines additional free disk space created in the image in Kbytes. + By default, this variable is set to "0". + This free disk space is added to the image after the build system determines + the image size as described in + IMAGE_ROOTFS_SIZE. + + + + This variable is particularly useful when you want to ensure that a + specific amount of free disk space is available on a device after an image + is installed and running. + For example, to be sure 5 Gbytes of free disk space is available, set the + variable as follows: + + IMAGE_ROOTFS_EXTRA_SPACE = "5242880" + + + + + For example, the Yocto Project Build Appliance specifically requests 40 Gbytes + of extra space with the line: + + IMAGE_ROOTFS_EXTRA_SPACE = "41943040" + + + + + + IMAGE_ROOTFS_SIZE + + + Defines the size in Kbytes for the generated image. + The OpenEmbedded build system determines the final size for the generated + image using an algorithm that takes into account the initial disk space used + for the generated image, a requested size for the image, and requested + additional free disk space to be added to the image. + Programatically, the build system determines the final size of the + generated image as follows: + + if (image-du * overhead) < rootfs-size: + internal-rootfs-size = rootfs-size + xspace + else: + internal-rootfs-size = (image-du * overhead) + xspace + + where: + + image-du = Returned value of the du command on + the image. + + overhead = IMAGE_OVERHEAD_FACTOR + + rootfs-size = IMAGE_ROOTFS_SIZE + + internal-rootfs-size = Initial root filesystem + size before any modifications. + + xspace = IMAGE_ROOTFS_EXTRA_SPACE + + See the IMAGE_OVERHEAD_FACTOR + and IMAGE_ROOTFS_EXTRA_SPACE + variables for related information. + + + + + + IMAGE_TYPEDEP + + + Specifies a dependency from one image type on another. + Here is an example from the + image-live + class: + + IMAGE_TYPEDEP_live = "ext3" + + In the previous example, the variable ensures that when + "live" is listed with the + IMAGE_FSTYPES + variable, the OpenEmbedded build system produces an + ext3 image first since one of the + components of the live + image is an ext3 + formatted partition containing the root + filesystem. + + + + + IMAGE_TYPES + + + Specifies the complete list of supported image types + by default: + + jffs2 + jffs2.sum + cramfs + ext2 + ext2.gz + ext2.bz2 + ext3 + ext3.gz + ext2.lzma + btrfs + live + squashfs + squashfs-xz + ubi + ubifs + tar + tar.gz + tar.bz2 + tar.xz + cpio + cpio.gz + cpio.xz + cpio.lzma + vmdk + elf + + For more information about these types of images, see + meta/classes/image_types*.bbclass + in the + Source Directory. + + + + + INC_PR + + Helps define the recipe revision for recipes that share + a common include file. + You can think of this variable as part of the recipe revision + as set from within an include file. + Suppose, for example, you have a set of recipes that + are used across several projects. + And, within each of those recipes the revision + (its PR + value) is set accordingly. + In this case, when the revision of those recipes changes, + the burden is on you to find all those recipes and + be sure that they get changed to reflect the updated + version of the recipe. + In this scenario, it can get complicated when recipes + that are used in many places and provide common functionality + are upgraded to a new revision. + A more efficient way of dealing with this situation is + to set the INC_PR variable inside + the include files that the recipes + share and then expand the INC_PR + variable within the recipes to help + define the recipe revision. + + + The following provides an example that shows how to use + the INC_PR variable + given a common include file that + defines the variable. + Once the variable is defined in the + include file, you can use the + variable to set the PR values in + each recipe. + You will notice that when you set a recipe's + PR you can provide more granular + revisioning by appending values to the + INC_PR variable: + +recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" +recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" +recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" +recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + + The first line of the example establishes the baseline + revision to be used for all recipes that use the + include file. + The remaining lines in the example are from individual + recipes and show how the PR value + is set. + + + + INCOMPATIBLE_LICENSE + + + Specifies a space-separated list of license names + (as they would appear in + LICENSE) + that should be excluded from the build. + Recipes that provide no alternatives to listed incompatible + licenses are not built. + Packages that are individually licensed with the specified + incompatible licenses will be deleted. + + + + This functionality is only regularly tested using + the following setting: + + INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" + + Although you can use other settings, you might be required + to remove dependencies on or provide alternatives to + components that are required to produce a functional system + image. + + + + + INHIBIT_DEFAULT_DEPS + + + Prevents the default dependencies, namely the C compiler + and standard C library (libc), from being added to + DEPENDS. + This variable is usually used within recipes that do not + require any compilation using the C compiler. + + + + Set the variable to "1" to prevent the default dependencies + from being added. + + + + + INHIBIT_PACKAGE_DEBUG_SPLIT + + + + Prevents the OpenEmbedded build system from splitting + out debug information during packaging. + By default, the build system splits out debugging + information during the + do_package + task. + For more information on how debug information is split out, + see the + PACKAGE_DEBUG_SPLIT_STYLE + variable. + + + + To prevent the build system from splitting out + debug information during packaging, set the + INHIBIT_PACKAGE_DEBUG_SPLIT variable + as follows: + + INHIBIT_PACKAGE_DEBUG_SPLIT = "1" + + + + + + INHIBIT_PACKAGE_STRIP + + + If set to "1", causes the build to not strip binaries in resulting packages. + + + + + INHERIT + + + Causes the named class to be inherited at + this point during parsing. + The variable is only valid in configuration files. + + + + + INHERIT_DISTRO + + + Lists classes that will be inherited at the + distribution level. + It is unlikely that you want to edit this variable. + + + + The default value of the variable is set as follows in the + meta/conf/distro/defaultsetup.conf + file: + + INHERIT_DISTRO ?= "debian devshell sstate license" + + + + + + INITRAMFS_FSTYPES + + + Defines the format for the output image of an initial + RAM disk (initramfs), which is used during boot. + Supported formats are the same as those supported by the + IMAGE_FSTYPES + variable. + + + + + INITRAMFS_IMAGE + + + Causes the OpenEmbedded build system to build an additional + recipe as a dependency to your root filesystem recipe + (e.g. core-image-sato). + The additional recipe is used to create an initial RAM disk + (initramfs) that might be needed during the initial boot of + the target system to accomplish such things as loading + kernel modules prior to mounting the root file system. + + + + When you set the variable, specify the name of the + initramfs you want created. + The following example, which is set in the + local.conf configuration file, causes + a separate recipe to be created that results in an + initramfs image named + core-image-sato-initramfs.bb to be + created: + + INITRAMFS_IMAGE = "core-image-minimal-initramfs" + + By default, the + kernel + class sets this variable to a null string as follows: + + INITRAMFS_IMAGE = "" + + + + + See the + local.conf.sample.extended + file for additional information. + You can also reference the + kernel.bbclass + file to see how the variable is used. + + + + + INITRAMFS_IMAGE_BUNDLE + + + Controls whether or not the image recipe specified by + INITRAMFS_IMAGE + is run through an extra pass during kernel compilation + in order to build a single binary that contains both the + kernel image and the initial RAM disk (initramfs). + Using an extra compilation pass ensures that when a kernel + attempts to use an initramfs, it does not encounter + circular dependencies should the initramfs include kernel + modules. + + + + The combined binary is deposited into the + tmp/deploy directory, which is part + of the + Build Directory. + + + + Setting the variable to "1" in a configuration file causes + the OpenEmbedded build system to make the extra pass during + kernel compilation: + + INITRAMFS_IMAGE_BUNDLE = "1" + + By default, the + kernel + class sets this variable to a null string as follows: + + INITRAMFS_IMAGE_BUNDLE = "" + + + You must set the + INITRAMFS_IMAGE_BUNDLE variable in + a configuration file. + You cannot set the variable in a recipe file. + + See the + local.conf.sample.extended + file for additional information. + + + + + INITRD + + + Indicates list of filesystem images to concatenate and use + as an initial RAM disk (initrd). + + + + The INITRD variable is an optional + variable used with the + bootimg + class. + + + + + INITRD_IMAGE + + + When building a "live" bootable image (i.e. when + IMAGE_FSTYPES + contains "live"), INITRD_IMAGE + specifies the image recipe that should be built + to provide the initial RAM disk image. + The default value is "core-image-minimal-initramfs". + + + + See the + image-live + class for more information. + + + + + INITSCRIPT_NAME + + + The filename of the initialization script as installed to + ${sysconfdir}/init.d. + + + This variable is used in recipes when using update-rc.d.bbclass. + The variable is mandatory. + + + + + INITSCRIPT_PACKAGES + + + A list of the packages that contain initscripts. + If multiple packages are specified, you need to append the package name + to the other INITSCRIPT_* as an override. + + This variable is used in recipes when using update-rc.d.bbclass. + The variable is optional and defaults to the + PN variable. + + + + + INITSCRIPT_PARAMS + + + Specifies the options to pass to update-rc.d. + Here is an example: + + INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." + + In this example, the script has a runlevel of 99, + starts the script in initlevels 2 and 5, and + stops the script in levels 0, 1 and 6. + + + The variable's default value is "defaults", which is + set in the + update-rc.d + class. + + + The value in + INITSCRIPT_PARAMS is passed through + to the update-rc.d command. + For more information on valid parameters, please see the + update-rc.d manual page at + . + + + + + INSANE_SKIP + + + Specifies the QA checks to skip for a specific package + within a recipe. + For example, to skip the check for symbolic link + .so files in the main package of a + recipe, add the following to the recipe. + The package name override must be used, which in this + example is ${PN}: + + INSANE_SKIP_${PN} += "dev-so" + + + + See the "insane.bbclass" + section for a list of the valid QA checks you can + specify using this variable. + + + + + IPK_FEED_URIS + + + When the IPK backend is in use and package management + is enabled on the target, you can use this variable to + set up opkg in the target image + to point to package feeds on a nominated server. + Once the feed is established, you can perform + installations or upgrades using the package manager + at runtime. + + + + + + + + + + + + K + + KARCH + + + Defines the kernel architecture used when assembling + the configuration. + Architectures supported for this release are: + + powerpc + i386 + x86_64 + arm + qemu + mips + + + + + You define the KARCH variable in the + BSP Descriptions. + + + + + KBRANCH + + + A regular expression used by the build process to explicitly + identify the kernel branch that is validated, patched + and configured during a build. + The KBRANCH variable is optional. + You can use it to trigger checks to ensure the exact kernel + branch you want is being used by the build process. + + + + Values for this variable are set in the kernel's recipe + file and the kernel's append file. + For example, if you are using the Yocto Project kernel that + is based on the Linux 3.10 kernel, the kernel recipe file + is the + meta/recipes-kernel/linux/linux-yocto_3.10.bb + file. + Following is the default value for KBRANCH + and the default override for the architectures the Yocto + Project supports: + + KBRANCH_DEFAULT = "standard/base" + KBRANCH = "${KBRANCH_DEFAULT}" + + This branch exists in the linux-yocto-3.10 + kernel Git repository + . + + + + This variable is also used from the kernel's append file + to identify the kernel branch specific to a particular + machine or target hardware. + The kernel's append file is located in the BSP layer for + a given machine. + For example, the kernel append file for the Crown Bay BSP is in the + meta-intel Git repository and is named + meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend. + Here are the related statements from the append file: + + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/crownbay" + KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb" + + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" + KMACHINE_crownbay-noemgd = "crownbay" + KBRANCH_crownbay-noemgd = "standard/crownbay" + KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb" + + The KBRANCH_* statements identify + the kernel branch to use when building for the Crown + Bay BSP. + In this case there are two identical statements: one + for each type of Crown Bay machine. + + + + + KBRANCH_DEFAULT + + + Defines the Linux kernel source repository's default + branch used to build the Linux kernel. + The KBRANCH_DEFAULT value is + the default value for + KBRANCH. + Unless you specify otherwise, + KBRANCH_DEFAULT initializes to + "master". + + + + + KERNEL_EXTRA_ARGS + + + Specifies additional make + command-line arguments the OpenEmbedded build system + passes on when compiling the kernel. + + + + + KERNEL_FEATURES + + Includes additional metadata from the Yocto Project kernel Git repository. + In the OpenEmbedded build system, the default Board Support Packages (BSPs) + Metadata + is provided through + the KMACHINE + and KBRANCH variables. + You can use the KERNEL_FEATURES variable to further + add metadata for all BSPs. + The metadata you add through this variable includes config fragments and + features descriptions, + which usually includes patches as well as config fragments. + You typically override the KERNEL_FEATURES variable + for a specific machine. + In this way, you can provide validated, but optional, sets of kernel + configurations and features. + For example, the following adds netfilter to all + the Yocto Project kernels and adds sound support to the qemux86 + machine: + + # Add netfilter to all linux-yocto kernels + KERNEL_FEATURES="features/netfilter" + + # Add sound support to the qemux86 machine + KERNEL_FEATURES_append_qemux86=" cfg/sound" + + + + + KERNEL_IMAGE_BASE_NAME + + + The base name of the kernel image. + This variable is set in the + kernel class + as follows: + + KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" + + See the + KERNEL_IMAGETYPE, + PKGE, + PKGV, + PKGR, + MACHINE, + and + DATETIME + variables for additional information. + + + + + KERNEL_IMAGETYPE + + The type of kernel to build for a device, usually set by the + machine configuration files and defaults to "zImage". + This variable is used + when building the kernel and is passed to make as the target to + build. + + + + KERNEL_MODULE_AUTOLOAD + + + Lists kernel modules that need to be auto-loaded during + boot. + + This variable replaces the deprecated + module_autoload + variable. + + + + + You can use the KERNEL_MODULE_AUTOLOAD + variable anywhere that it can be + recognized by the kernel recipe or by an out-of-tree kernel + module recipe (e.g. a machine configuration file, a + distribution configuration file, an append file for the + recipe, or the recipe itself). + + + + Specify it as follows: + + KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" + + + + + Including KERNEL_MODULE_AUTOLOAD causes + the OpenEmbedded build system to populate the + /etc/modules-load.d/modname.conf + file with the list of modules to be auto-loaded on boot. + The modules appear one-per-line in the file. + Here is an example of the most common use case: + + KERNEL_MODULE_AUTOLOAD += "module_name" + + + + + For information on how to populate the + modname.conf file with + modprobe.d syntax lines, see the + KERNEL_MODULE_PROBECONF + variable. + + + + + KERNEL_MODULE_PROBECONF + + + Provides a list of modules for which the OpenEmbedded + build system expects to find + module_conf_modname + values that specify configuration for each of the modules. + For information on how to provide those module + configurations, see the + module_conf_* + variable. + + + + + KERNEL_PATH + + + The location of the kernel sources. + This variable is set to the value of the + STAGING_KERNEL_DIR + within the + module + class. + For information on how this variable is used, see the + "Incorporating Out-of-Tree Modules" + section. + + + + To help maximize compatibility with out-of-tree drivers + used to build modules, the OpenEmbedded build system also + recognizes and uses the + KERNEL_SRC + variable, which is identical to the + KERNEL_PATH variable. + Both variables are common variables used by external + Makefiles to point to the kernel source directory. + + + + + KERNEL_SRC + + + The location of the kernel sources. + This variable is set to the value of the + STAGING_KERNEL_DIR + within the + module + class. + For information on how this variable is used, see the + "Incorporating Out-of-Tree Modules" + section. + + + + To help maximize compatibility with out-of-tree drivers + used to build modules, the OpenEmbedded build system also + recognizes and uses the + KERNEL_PATH + variable, which is identical to the + KERNEL_SRC variable. + Both variables are common variables used by external + Makefiles to point to the kernel source directory. + + + + + KFEATURE_DESCRIPTION + + + Provides a short description of a configuration fragment. + You use this variable in the .scc + file that describes a configuration fragment file. + Here is the variable used in a file named + smp.scc to describe SMP being + enabled: + + define KFEATURE_DESCRIPTION "Enable SMP" + + + + + + KMACHINE + + + The machine as known by the kernel. + Sometimes the machine name used by the kernel does not match the machine name + used by the OpenEmbedded build system. + For example, the machine name that the OpenEmbedded build system understands as + qemuarm goes by a different name in the Linux Yocto kernel. + The kernel understands that machine as arm_versatile926ejs. + For cases like these, the KMACHINE variable maps the + kernel machine name to the OpenEmbedded build system machine name. + + + + Kernel machine names are initially defined in the + Yocto Linux Kernel's meta branch. + From the meta branch, look in + the meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc file. + For example, from the meta branch in the + linux-yocto-3.0 kernel, the + meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc file + has the following: + + define KMACHINE cedartrail + define KTYPE standard + define KARCH i386 + + include ktypes/standard + branch cedartrail + + include cedartrail.scc + + You can see that the kernel understands the machine name for + the Cedar Trail Board Support Package (BSP) as + cedartrail. + + + + If you look in the Cedar Trail BSP layer in the + meta-intel + Source Repositories + at meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend, + you will find the following statements among others: + + COMPATIBLE_MACHINE_cedartrail = "cedartrail" + KMACHINE_cedartrail = "cedartrail" + KBRANCH_cedartrail = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" + KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" + + COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" + KMACHINE_cedartrail-nopvr = "cedartrail" + KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" + + The KMACHINE statements in the kernel's append file make sure that + the OpenEmbedded build system and the Yocto Linux kernel understand the same machine + names. + + + + This append file uses two KMACHINE statements. + The first is not really necessary but does ensure that the machine known to the + OpenEmbedded build system as cedartrail maps to the machine + in the kernel also known as cedartrail: + + KMACHINE_cedartrail = "cedartrail" + + + + + The second statement is a good example of why the KMACHINE variable + is needed. + In this example, the OpenEmbedded build system uses the cedartrail-nopvr + machine name to refer to the Cedar Trail BSP that does not support the proprietary + PowerVR driver. + The kernel, however, uses the machine name cedartrail. + Thus, the append file must map the cedartrail-nopvr machine name to + the kernel's cedartrail name: + + KMACHINE_cedartrail-nopvr = "cedartrail" + + + + + BSPs that ship with the Yocto Project release provide all mappings between the Yocto + Project kernel machine names and the OpenEmbedded machine names. + Be sure to use the KMACHINE if you create a BSP and the machine + name you use is different than that used in the kernel. + + + + + KTYPE + + + Defines the kernel type to be used in assembling the + configuration. + The linux-yocto recipes define "standard", "tiny", + and "preempt-rt" kernel types. + See the + "Kernel Types" + section in the Yocto Project Linux Kernel Development + Manual for more information on kernel types. + + + + You define the KTYPE variable in the + BSP Descriptions. + The value you use must match the value used for the + LINUX_KERNEL_TYPE + value used by the kernel recipe. + + + + + + L + + LABELS + + + Provides a list of targets for automatic configuration. + + + + See the + grub-efi + class for more information on how this variable is used. + + + + + LAYERDEPENDS + + Lists the layers that this recipe depends upon, separated by spaces. + Optionally, you can specify a specific layer version for a dependency + by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" + to be compared against + LAYERVERSION_anotherlayer + in this case). + An error will be produced if any dependency is missing or + the version numbers do not match exactly (if specified). + This variable is used in the conf/layer.conf file + and must be suffixed with the name of the specific layer (e.g. + LAYERDEPENDS_mylayer). + + + + LAYERDIR + + When used inside the layer.conf configuration + file, this variable provides the path of the current layer. + This variable is not available outside of layer.conf + and references are expanded immediately when parsing of the file completes. + + + + LAYERVERSION + + Optionally specifies the version of a layer as a single number. + You can use this within + LAYERDEPENDS + for another layer in order to depend on a specific version + of the layer. + This variable is used in the conf/layer.conf file + and must be suffixed with the name of the specific layer (e.g. + LAYERVERSION_mylayer). + + + + LDFLAGS + + + Specifies the flags to pass to the linker. + This variable is exported to an environment + variable and thus made visible to the software being + built during the compilation step. + + + + Default initialization for LDFLAGS + varies depending on what is being built: + + + TARGET_LDFLAGS + when building for the target + + + BUILD_LDFLAGS + when building for the build host (i.e. + -native) + + + BUILDSDK_LDFLAGS + when building for an SDK (i.e. + nativesdk-) + + + + + + + LEAD_SONAME + + + Specifies the lead (or primary) compiled library file + (.so) that the + debian + class applies its naming policy to given a recipe that + packages multiple libraries. + + + + This variable works in conjunction with the + debian class. + + + + + LIC_FILES_CHKSUM + + Checksums of the license text in the recipe source code. + This variable tracks changes in license text of the source + code files. + If the license text is changed, it will trigger a build + failure, which gives the developer an opportunity to review any + license change. + + This variable must be defined for all recipes (unless + LICENSE + is set to "CLOSED"). + For more information, see the + " + Tracking License Changes" section. + + + + LICENSE + + + The list of source licenses for the recipe. + Follow these rules: + + Do not use spaces within individual + license names. + Separate license names using + | (pipe) when there is a choice between licenses. + + Separate license names using + & (ampersand) when multiple licenses exist + that cover different parts of the source. + + You can use spaces between license + names. + For standard licenses, use the names + of the files in + meta/files/common-licenses/ + or the + SPDXLICENSEMAP + flag names defined in + meta/conf/licenses.conf. + + + + + + Here are some examples: + + LICENSE = "LGPLv2.1 | GPLv3" + LICENSE = "MPL-1 & LGPLv2.1" + LICENSE = "GPLv2+" + + The first example is from the recipes for Qt, which the user + may choose to distribute under either the LGPL version + 2.1 or GPL version 3. + The second example is from Cairo where two licenses cover + different parts of the source code. + The final example is from sysstat, + which presents a single license. + + + + You can also specify licenses on a per-package basis to + handle situations where components of the output have + different licenses. + For example, a piece of software whose code is + licensed under GPLv2 but has accompanying documentation + licensed under the GNU Free Documentation License 1.2 could + be specified as follows: + + LICENSE = "GFDL-1.2 & GPLv2" + LICENSE_${PN} = "GPLv2" + LICENSE_${PN}-doc = "GFDL-1.2" + + + + + + LICENSE_FLAGS + + + Specifies additional flags for a recipe you must + whitelist through + LICENSE_FLAGS_WHITELIST + in order to allow the recipe to be built. + When providing multiple flags, separate them with + spaces. + + + + This value is independent of + LICENSE + and is typically used to mark recipes that might + require additional licenses in order to be used in a + commercial product. + For more information, see the + "Enabling Commercially Licensed Recipes" + section. + + + + + LICENSE_FLAGS_WHITELIST + + + Lists license flags that when specified in + LICENSE_FLAGS + within a recipe should not prevent that recipe from being + built. + This practice is otherwise known as "whitelisting" + license flags. + For more information, see the + Enabling Commercially Licensed Recipes" + section. + + + + + LICENSE_PATH + + Path to additional licenses used during the build. + By default, the OpenEmbedded build system uses COMMON_LICENSE_DIR + to define the directory that holds common license text used during the build. + The LICENSE_PATH variable allows you to extend that + location to other areas that have additional licenses: + + LICENSE_PATH += "path-to-additional-common-licenses" + + + + + LINUX_KERNEL_TYPE + + + Defines the kernel type to be used in assembling the + configuration. + The linux-yocto recipes define "standard", "tiny", and + "preempt-rt" kernel types. + See the + "Kernel Types" + section in the Yocto Project Linux Kernel Development + Manual for more information on kernel types. + + + + If you do not specify a + LINUX_KERNEL_TYPE, it defaults to + "standard". + Together with + KMACHINE, + the LINUX_KERNEL_TYPE variable + defines the search + arguments used by the kernel tools to find the appropriate + description within the kernel + Metadata + with which to build out the sources and configuration. + + + + + LINUX_VERSION + + The Linux version from kernel.org + on which the Linux kernel image being built using the + OpenEmbedded build system is based. + You define this variable in the kernel recipe. + For example, the linux-yocto-3.4.bb + kernel recipe found in + meta/recipes-kernel/linux + defines the variables as follows: + + LINUX_VERSION ?= "3.4.24" + + The LINUX_VERSION variable is used to + define PV + for the recipe: + + PV = "${LINUX_VERSION}+git${SRCPV}" + + + + + LINUX_VERSION_EXTENSION + + A string extension compiled into the version + string of the Linux kernel built with the OpenEmbedded + build system. + You define this variable in the kernel recipe. + For example, the linux-yocto kernel recipes all define + the variable as follows: + + LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" + + Defining this variable essentially sets the + Linux kernel configuration item + CONFIG_LOCALVERSION, which is visible + through the uname command. + Here is an example that shows the extension assuming it + was set as previously shown: + + $ uname -r + 3.7.0-rc8-custom + + + + + + LOG_DIR + + + Specifies the directory to which the OpenEmbedded build + system writes overall log files. + The default directory is ${TMPDIR}/log. + + + For the directory containing logs specific to each task, + see the T + variable. + + + + + + + M + + MACHINE + + + Specifies the target device for which the image is built. + You define MACHINE in the + local.conf file found in the + Build Directory. + By default, MACHINE is set to + "qemux86", which is an x86-based architecture machine to + be emulated using QEMU: + + MACHINE ?= "qemux86" + + The variable corresponds to a machine configuration file of the + same name, through which machine-specific configurations are set. + Thus, when MACHINE is set to "qemux86" there + exists the corresponding qemux86.conf machine + configuration file, which can be found in the + Source Directory + in meta/conf/machine. + + + + The list of machines supported by the Yocto Project as + shipped include the following: + + MACHINE ?= "qemuarm" + MACHINE ?= "qemumips" + MACHINE ?= "qemuppc" + MACHINE ?= "qemux86" + MACHINE ?= "qemux86-64" + MACHINE ?= "genericx86" + MACHINE ?= "genericx86-64" + MACHINE ?= "beaglebone" + MACHINE ?= "mpc8315e-rdb" + MACHINE ?= "edgerouter" + + The last five are Yocto Project reference hardware boards, which + are provided in the meta-yocto-bsp layer. + Adding additional Board Support Package (BSP) layers + to your configuration adds new possible settings for + MACHINE. + + + + + + MACHINE_ARCH + + + Specifies the name of the machine-specific architecture. + This variable is set automatically from + MACHINE + or + TUNE_PKGARCH. + You should not hand-edit the + MACHINE_ARCH variable. + + + + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS + + + A list of required machine-specific packages to install as part of + the image being built. + The build process depends on these packages being present. + Furthermore, because this is a "machine essential" variable, the list of + packages are essential for the machine to boot. + The impact of this variable affects images based on + packagegroup-core-boot, + including the core-image-minimal image. + + + This variable is similar to the + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + + + As an example, suppose the machine for which you are building requires + example-init to be run during boot to initialize the hardware. + In this case, you would use the following in the machine's + .conf configuration file: + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" + + + + + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS + + + A list of recommended machine-specific packages to install as part of + the image being built. + The build process does not depend on these packages being present. + However, because this is a "machine essential" variable, the list of + packages are essential for the machine to boot. + The impact of this variable affects images based on + packagegroup-core-boot, + including the core-image-minimal image. + + + This variable is similar to the + MACHINE_ESSENTIAL_EXTRA_RDEPENDS + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will still build if a package in this list is not found. + Typically, this variable is used to handle essential kernel modules, whose + functionality may be selected to be built into the kernel rather than as a module, + in which case a package will not be produced. + + + Consider an example where you have a custom kernel where a specific touchscreen + driver is required for the machine to be usable. + However, the driver can be built as a module or + into the kernel depending on the kernel configuration. + If the driver is built as a module, you want it to be installed. + But, when the driver is built into the kernel, you still want the + build to succeed. + This variable sets up a "recommends" relationship so that in the latter case, + the build will not fail due to the missing package. + To accomplish this, assuming the package for the module was called + kernel-module-ab123, you would use the + following in the machine's .conf configuration + file: + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" + + + + Some examples of these machine essentials are flash, screen, keyboard, mouse, + or touchscreen drivers (depending on the machine). + + + + + MACHINE_EXTRA_RDEPENDS + + + A list of machine-specific packages to install as part of the + image being built that are not essential for the machine to boot. + However, the build process for more fully-featured images + depends on the packages being present. + + + This variable affects all images based on + packagegroup-base, which does not include the + core-image-minimal or core-image-full-cmdline + images. + + + The variable is similar to the + MACHINE_EXTRA_RRECOMMENDS + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + + + An example is a machine that has WiFi capability but is not + essential for the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + the WiFi. + The package containing the firmware for the WiFi hardware is always + expected to exist, so it is acceptable for the build process to depend upon + finding the package. + In this case, assuming the package for the firmware was called + wifidriver-firmware, you would use the following in the + .conf file for the machine: + + MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" + + + + + + MACHINE_EXTRA_RRECOMMENDS + + + A list of machine-specific packages to install as part of the + image being built that are not essential for booting the machine. + The image being built has no build dependency on this list of packages. + + + This variable affects only images based on + packagegroup-base, which does not include the + core-image-minimal or core-image-full-cmdline + images. + + + This variable is similar to the + MACHINE_EXTRA_RDEPENDS + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will build if a file in this list is not found. + + + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + WiFi. + In this case, the package containing the WiFi kernel module will not be produced + if the WiFi driver is built into the kernel, in which case you still want the + build to succeed instead of failing as a result of the package not being found. + To accomplish this, assuming the package for the module was called + kernel-module-examplewifi, you would use the + following in the .conf file for the machine: + + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" + + + + + + MACHINE_FEATURES + + + Specifies the list of hardware features the + MACHINE is capable + of supporting. + For related information on enabling features, see the + DISTRO_FEATURES, + COMBINED_FEATURES, + and + IMAGE_FEATURES + variables. + + + + For a list of hardware features supported by the Yocto + Project as shipped, see the + "Machine Features" + section. + + + + + MACHINE_FEATURES_BACKFILL + + Features to be added to + MACHINE_FEATURES + if not also present in + MACHINE_FEATURES_BACKFILL_CONSIDERED. + + + + This variable is set in the meta/conf/bitbake.conf file. + It is not intended to be user-configurable. + It is best to just reference the variable to see which machine features are + being backfilled for all machine configurations. + See the "Feature backfilling" section for + more information. + + + + + MACHINE_FEATURES_BACKFILL_CONSIDERED + + Features from + MACHINE_FEATURES_BACKFILL + that should not be backfilled (i.e. added to + MACHINE_FEATURES) + during the build. + See the "Feature backfilling" section for + more information. + + + + + MACHINEOVERRIDES + + + Lists overrides specific to the current machine. + By default, this list includes the value + of MACHINE. + You can extend the list to apply variable overrides for + classes of machines. + For example, all QEMU emulated machines (e.g. qemuarm, + qemux86, and so forth) include a common file named + meta/conf/machine/include/qemu.inc + that prepends MACHINEOVERRIDES with + the following variable override: + + MACHINEOVERRIDES =. "qemuall:" + + Applying an override like qemuall + affects all QEMU emulated machines elsewhere. + Here is an example from the + connman-conf recipe: + + SRC_URI_append_qemuall = "file://wired.config \ + file://wired-setup \ + " + + + + + + MAINTAINER + + The email address of the distribution maintainer. + + + + MIRRORS + + + Specifies additional paths from which the OpenEmbedded + build system gets source code. + When the build system searches for source code, it first + tries the local download directory. + If that location fails, the build system tries locations + defined by + PREMIRRORS, + the upstream source, and then locations specified by + MIRRORS in that order. + + + + Assuming your distribution + (DISTRO) + is "poky", the default value for + MIRRORS is defined in the + conf/distro/poky.conf file in the + meta-yocto Git repository. + + + + + MLPREFIX + + + Specifies a prefix has been added to + PN to create a special version + of a recipe or package, such as a Multilib version. + The variable is used in places where the prefix needs to be + added to or removed from a the name (e.g. the + BPN variable). + MLPREFIX gets set when a prefix has been + added to PN. + + + + + module_autoload + + + This variable has been replaced by the + KERNEL_MODULE_AUTOLOAD variable. + You should replace all occurrences of + module_autoload with additions to + KERNEL_MODULE_AUTOLOAD, for example: + + module_autoload_rfcomm = "rfcomm" + + should now be replaced with: + + KERNEL_MODULE_AUTOLOAD += "rfcomm" + + See the + KERNEL_MODULE_AUTOLOAD + variable for more information. + + + + + module_conf + + + Specifies + modprobe.d + syntax lines for inclusion in the + /etc/modprobe.d/modname.conf file. + + + + You can use this variable anywhere that it can be + recognized by the kernel recipe or out-of-tree kernel + module recipe (e.g. a machine configuration file, a + distribution configuration file, an append file for the + recipe, or the recipe itself). + If you use this variable, you must also be sure to list + the module name in the + KERNEL_MODULE_AUTOLOAD + variable. + + + + Here is the general syntax: + + module_conf_module_name = "modprobe.d-syntax" + + You must use the kernel module name override. + + + + Run man modprobe.d in the shell to + find out more information on the exact syntax + you want to provide with module_conf. + + + + Including module_conf causes the + OpenEmbedded build system to populate the + /etc/modprobe.d/modname.conf + file with modprobe.d syntax lines. + Here is an example that adds the options + arg1 and arg2 + to a module named mymodule: + + module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" + + + + + For information on how to specify kernel modules to + auto-load on boot, see the + KERNEL_MODULE_AUTOLOAD + variable. + + + + + MODULE_IMAGE_BASE_NAME + + + The base name of the kernel modules tarball. + This variable is set in the + kernel class + as follows: + + MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" + + See the + PKGE, + PKGV, + PKGR, + MACHINE, + and + DATETIME + variables for additional information. + + + + + MODULE_TARBALL_DEPLOY + + + Controls creation of the modules-*.tgz + file. + Set this variable to "0" to disable creation of this + file, which contains all of the kernel modules resulting + from a kernel build. + + + + + MULTIMACH_TARGET_SYS + + + Separates files for different machines such that you can build + for multiple target machines using the same output directories. + See the STAMP variable + for an example. + + + + + + + N + + NATIVELSBSTRING + + + A string identifying the host distribution. + Strings consist of the host distributor ID + followed by the release, as reported by the + lsb_release tool + or as read from /etc/lsb-release. + For example, when running a build on Ubuntu 12.10, the value + is "Ubuntu-12.10". + If this information is unable to be determined, the value + resolves to "Unknown". + + + This variable is used by default to isolate native shared + state packages for different distributions (e.g. to avoid + problems with glibc version + incompatibilities). + Additionally, the variable is checked against + SANITY_TESTED_DISTROS + if that variable is set. + + + + + NO_RECOMMENDATIONS + + + Prevents installation of all "recommended-only" packages. + Recommended-only packages are packages installed only + through the + RRECOMMENDS + variable). + Setting the NO_RECOMMENDATIONS variable + to "1" turns this feature on: + + NO_RECOMMENDATIONS = "1" + + You can set this variable globally in your + local.conf file or you can attach it to + a specific image recipe by using the recipe name override: + + NO_RECOMMENDATIONS_pn-target_image = "package_name" + + + + + It is important to realize that if you choose to not install + packages using this variable and some other packages are + dependent on them (i.e. listed in a recipe's + RDEPENDS + variable), the OpenEmbedded build system ignores your + request and will install the packages to avoid dependency + errors. + + Some recommended packages might be required for certain + system functionality, such as kernel modules. + It is up to you to add packages with the + IMAGE_INSTALL + variable. + + + + + Support for this variable exists only when using the + IPK and RPM packaging backend. + Support does not exist for DEB. + + + + See the + BAD_RECOMMENDATIONS + and the + PACKAGE_EXCLUDE + variables for related information. + + + + + NOHDD + + + Causes the OpenEmbedded build system to skip building the + .hddimg image. + The NOHDD variable is used with the + bootimg + class. + Set the variable to "1" to prevent the + .hddimg image from being built. + + + + + NOISO + + + Causes the OpenEmbedded build system to skip building the + ISO image. + The NOISO variable is used with the + bootimg + class. + Set the variable to "1" to prevent the ISO image from + being built. + To enable building an ISO image, set the variable to "0". + + + + + + + O + + OE_BINCONFIG_EXTRA_MANGLE + + + When inheriting the + binconfig + class, this variable + specifies additional arguments passed to the "sed" command. + The sed command alters any paths in configuration scripts + that have been set up during compilation. + Inheriting this class results in all paths in these scripts + being changed to point into the + sysroots/ directory so that all builds + that use the script will use the correct directories + for the cross compiling layout. + + + + See the meta/classes/binconfig.bbclass + in the + Source Directory + for details on how this class applies these additional + sed command arguments. + For general information on the + binconfig.bbclass class, see the + "Binary Configuration Scripts - binconfig.bbclass" + section. + + + + + OE_IMPORTS + + + An internal variable used to tell the OpenEmbedded build + system what Python modules to import for every Python + function run by the system. + + + + Do not set this variable. + It is for internal use only. + + + + + OE_TERMINAL + + + Controls how the OpenEmbedded build system spawns + interactive terminals on the host development system + (e.g. using the BitBake command with the + -c devshell command-line option). + For more information, see the + "Using a Development Shell" section + in the Yocto Project Development Manual. + + + + You can use the following values for the + OE_TERMINAL variable: + + auto + gnome + xfce + rxvt + screen + konsole + none + + Konsole support only works for KDE 3.x. + Also, "auto" is the default behavior for + OE_TERMINAL + + + + + OEROOT + + + The directory from which the top-level build environment + setup script is sourced. + The Yocto Project makes two top-level build environment + setup scripts available: + &OE_INIT_FILE; + and + oe-init-build-env-memres. + When you run one of these scripts, the + OEROOT variable resolves to the + directory that contains the script. + + + + For additional information on how this variable is used, + see the initialization scripts. + + + + + OLDEST_KERNEL + + + Declares the oldest version of the Linux kernel that the + produced binaries must support. + This variable is passed into the build of the Embedded + GNU C Library (glibc). + + + + The default for this variable comes from the + meta/conf/bitbake.conf configuration + file. + You can override this default by setting the variable + in a custom distribution configuration file. + + + + + OVERRIDES + + + BitBake uses OVERRIDES to control + what variables are overridden after BitBake parses + recipes and configuration files. + You can find more information on how overrides are handled + in the + "Conditional Syntax (Overrides)" + section of the BitBake User Manual. + + + + + + P + + P + + The recipe name and version. + P is comprised of the following: + + ${PN}-${PV} + + + + + PACKAGE_ARCH + + + The architecture of the resulting package or packages. + + + + By default, the value of this variable is set to + TUNE_PKGARCH + when building for the target, + BUILD_ARCH when building for the + build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building + for the SDK. + However, if your recipe's output packages are built + specific to the target machine rather than general for + the architecture of the machine, you should set + PACKAGE_ARCH to the value of + MACHINE_ARCH + in the recipe as follows: + + PACKAGE_ARCH = "${MACHINE_ARCH}" + + + + + + PACKAGE_ARCHS + + + Specifies a list of architectures compatible with + the target machine. + This variable is set automatically and should not + normally be hand-edited. + Entries are separated using spaces and listed in order + of priority. + The default value for + PACKAGE_ARCHS is "all any noarch + ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". + + + + + + + PACKAGE_BEFORE_PN + + Enables easily adding packages to + PACKAGES + before ${PN} + so that those added packages can pick up files that would normally be + included in the default package. + + + + PACKAGE_CLASSES + + + This variable, which is set in the + local.conf configuration file found in + the conf folder of the + Build Directory, + specifies the package manager the OpenEmbedded build system + uses when packaging data. + + + + You can provide one or more of the following arguments for + the variable: + + PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar" + + The build system uses only the first argument in the list + as the package manager when creating your image or SDK. + However, packages will be created using any additional + packaging classes you specify. + For example, if you use the following in your + local.conf file: + + PACKAGE_CLASSES ?= "package_ipk package_tar" + + The OpenEmbedded build system uses the IPK package manager + to create your image or SDK as well as generating + TAR packages. + + + + You cannot specify the + package_tar + class first in the list. + Files using the .tar format cannot + be used as a substitute packaging format + for DEB, RPM, and IPK formatted files for your image or SDK. + + + + For information on packaging and build performance effects + as a result of the package manager in use, see the + "package.bbclass" + section. + + + + + PACKAGE_DEBUG_SPLIT_STYLE + + + + Determines how to split up the binary and debug information + when creating *-dbg packages to be + used with the GNU Project Debugger (GDB). + + + + With the + PACKAGE_DEBUG_SPLIT_STYLE variable, + you can control where debug information, which can include + or exclude source files, is stored: + + + ".debug": Debug symbol files are placed next + to the binary in a .debug + directory on the target. + For example, if a binary is installed into + /bin, the corresponding debug + symbol files are installed in + /bin/.debug. + Source files are placed in + /usr/src/debug. + This is the default behavior. + + + "debug-file-directory": Debug symbol files are + placed under /usr/lib/debug + on the target, and separated by the path from where + the binary is installed. + For example, if a binary is installed in + /bin, the corresponding debug + symbols are installed in + /usr/lib/debug/bin. + Source files are placed in + /usr/src/debug. + + + "debug-without-src": The same behavior as + ".debug" previously described with the exception + that no source files are installed. + . + + + + + You can find out more about debugging using GDB by reading + the + "Debugging With the GNU Project Debugger (GDB) Remotely" + section in the Yocto Project Development Manual. + + + + + PACKAGE_EXCLUDE + + + Lists packages that should not be installed into an image. + For example: + + PACKAGE_EXCLUDE = "package_name package_name package_name ..." + + You can set this variable globally in your + local.conf file or you can attach it to + a specific image recipe by using the recipe name override: + + PACKAGE_EXCLUDE_pn-target_image = "package_name" + + + + + If you choose to not install + a package using this variable and some other package is + dependent on it (i.e. listed in a recipe's + RDEPENDS + variable), the OpenEmbedded build system generates a fatal + installation error. + Because the build system halts the process with a fatal + error, you can use the variable with an iterative + development process to remove specific components from a + system. + + + + Support for this variable exists only when using the + IPK and RPM packaging backend. + Support does not exist for DEB. + + + + See the + NO_RECOMMENDATIONS + and the + BAD_RECOMMENDATIONS + variables for related information. + + + + + PACKAGE_EXTRA_ARCHS + + Specifies the list of architectures compatible with the device CPU. + This variable is useful when you build for several different devices that use + miscellaneous processors such as XScale and ARM926-EJS). + + + + PACKAGE_GROUP + + + + The PACKAGE_GROUP variable has been + renamed to + FEATURE_PACKAGES. + See the variable description for + FEATURE_PACKAGES for information. + + + + If if you use the PACKAGE_GROUP + variable, the OpenEmbedded build system issues a warning + message. + + + + + PACKAGE_INSTALL + + + The final list of packages passed to the package manager + for installation into the image. + + + + Because the package manager controls actual installation + of all packages, the list of packages passed using + PACKAGE_INSTALL is not the final list + of packages that are actually installed. + This variable is internal to the image construction + code. + Consequently, in general, you should use the + IMAGE_INSTALL + variable to specify packages for installation. + The exception to this is when working with + the + core-image-minimal-initramfs + image. + When working with an initial RAM disk (initramfs) + image, use the PACKAGE_INSTALL + variable. + + + + + PACKAGE_PREPROCESS_FUNCS + + + Specifies a list of functions run to pre-process the + PKGD + directory prior to splitting the files out to individual + packages. + + + + + PACKAGECONFIG + + + This variable provides a means of enabling or disabling + features of a recipe on a per-recipe basis. + PACKAGECONFIG blocks are defined + in recipes when you specify features and then arguments + that define feature behaviors. + Here is the basic block structure: + + PACKAGECONFIG ??= "f1 f2 f3 ..." + PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1" + PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2" + PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3" + + The PACKAGECONFIG + variable itself specifies a space-separated list of the + features to enable. + Following the features, you can determine the behavior of + each feature by providing up to four order-dependent + arguments, which are separated by commas. + You can omit any argument you like but must retain the + separating commas. + The order is important and specifies the following: + + Extra arguments + that should be added to the configure script + argument list + (EXTRA_OECONF) + if the feature is enabled. + Extra arguments + that should be added to EXTRA_OECONF + if the feature is disabled. + + Additional build dependencies + (DEPENDS) + that should be added if the feature is enabled. + + Additional runtime dependencies + (RDEPENDS) + that should be added if the feature is enabled. + + + + + + Consider the following + PACKAGECONFIG block taken from the + librsvg recipe. + In this example the feature is croco, + which has three arguments that determine the feature's + behavior. + + PACKAGECONFIG ??= "croco" + PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" + + The --with-croco and + libcroco arguments apply only if + the feature is enabled. + In this case, --with-croco is + added to the configure script argument list and + libcroco is added to + DEPENDS. + On the other hand, if the feature is disabled say through + a .bbappend file in another layer, then + the second argument --without-croco is + added to the configure script rather than + --with-croco. + + + + The basic PACKAGECONFIG structure + previously described holds true regardless of whether you + are creating a block or changing a block. + When creating a block, use the structure inside your + recipe. + + + + If you want to change an existing + PACKAGECONFIG block, you can do so + one of two ways: + + Append file: + Create an append file named + recipename.bbappend + in your layer and override the value of + PACKAGECONFIG. + You can either completely override the variable: + + PACKAGECONFIG="f4 f5" + + Or, you can just append the variable: + + PACKAGECONFIG_append = " f4" + + Configuration file: + This method is identical to changing the block + through an append file except you edit your + local.conf or + mydistro.conf file. + As with append files previously described, + you can either completely override the variable: + + PACKAGECONFIG_pn-recipename="f4 f5" + + Or, you can just amend the variable: + + PACKAGECONFIG_append_pn-recipename = " f4" + + + + + + + PACKAGES + + The list of packages to be created from the recipe. + The default value is the following: + + ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} + + + + + PACKAGESPLITFUNCS + + + Specifies a list of functions run to perform additional + splitting of files into individual packages. + Recipes can either prepend to this variable or prepend + to the populate_packages function + in order to perform additional package splitting. + In either case, the function should set + PACKAGES, + FILES, + RDEPENDS + and other packaging variables appropriately in order to + perform the desired splitting. + + + + + PACKAGES_DYNAMIC + + + A promise that your recipe satisfies runtime dependencies + for optional modules that are found in other recipes. + PACKAGES_DYNAMIC + does not actually satisfy the dependencies, it only states that + they should be satisfied. + For example, if a hard, runtime dependency + (RDEPENDS) + of another package is satisfied + at build time through the PACKAGES_DYNAMIC + variable, but a package with the module name is never actually + produced, then the other package will be broken. + Thus, if you attempt to include that package in an image, + you will get a dependency failure from the packaging system + during the + do_rootfs + task. + + + Typically, if there is a chance that such a situation can + occur and the package that is not created is valid + without the dependency being satisfied, then you should use + RRECOMMENDS + (a soft runtime dependency) instead of + RDEPENDS. + + + + For an example of how to use the PACKAGES_DYNAMIC + variable when you are splitting packages, see the + "Handling Optional Module Packaging" section + in the Yocto Project Development Manual. + + + + + PARALLEL_MAKE + + + Extra options passed to the make + command during the + do_compile + task in order to specify parallel compilation on the local + build host. + This variable is usually in the form "-j <x>", + where x represents the maximum number of parallel threads + make can run. + + + + If your development host supports multiple cores, a good + rule of thumb is to set this variable to twice the number + of cores on the host. + If you do not set PARALLEL_MAKE, it + defaults to the number of cores your build system has. + + Individual recipes might clear out this variable if + the software being built has problems running its + make process in parallel. + + + + + + PARALLEL_MAKEINST + + + Extra options passed to the + make install command during the + do_install + task in order to specify parallel installation. + This variable defaults to the value of + PARALLEL_MAKE. + + Individual recipes might clear out this variable if + the software being built has problems running its + make install process in parallel. + + + + + + PATCHRESOLVE + + + Determines the action to take when a patch fails. + You can set this variable to one of two values: "noop" and + "user". + + + + The default value of "noop" causes the build to simply fail + when the OpenEmbedded build system cannot successfully + apply a patch. + Setting the value to "user" causes the build system to + launch a shell and places you in the right location so that + you can manually resolve the conflicts. + + + + Set this variable in your + local.conf file. + + + + + PATCHTOOL + + + Specifies the utility used to apply patches for a recipe + during the + do_patch + task. + You can specify one of three utilities: "patch", "quilt", or + "git". + The default utility used is "quilt" except for the + quilt-native recipe itself. + Because the quilt tool is not available at the + time quilt-native is being patched, it uses "patch". + + + + If you wish to use an alternative patching tool, set the + variable in the recipe using one of the following: + + PATCHTOOL = "patch" + PATCHTOOL = "quilt" + PATCHTOOL = "git" + + + + + + PE + + + The epoch of the recipe. + By default, this variable is unset. + The variable is used to make upgrades possible when the + versioning scheme changes in some backwards incompatible + way. + + + + + PF + + Specifies the recipe or package name and includes all version and revision + numbers (i.e. glibc-2.13-r20+svnr15508/ and + bash-4.2-r1/). + This variable is comprised of the following: + + ${PN}-${EXTENDPE}${PV}-${PR} + + + + + PIXBUF_PACKAGES + + + When inheriting the + pixbufcache + class, this variable identifies packages that contain + the pixbuf loaders used with + gdk-pixbuf. + By default, the pixbufcache class + assumes that the loaders are in the recipe's main package + (i.e. ${PN}). + Use this variable if the loaders you need are in a package + other than that main package. + + + + + PKG + + + The name of the resulting package created by the + OpenEmbedded build system. + + When using the PKG variable, you + must use a package name override. + + For example, when the + debian + class renames the output package, it does so by setting + PKG_packagename. + + + + + PKGD + + + Points to the destination directory for files to be + packaged before they are split into individual packages. + This directory defaults to the following: + + ${WORKDIR}/package + + Do not change this default. + + + + + PKGDATA_DIR + + + Points to a shared, global-state directory that holds data + generated during the packaging process. + During the packaging process, the + do_packagedata + task packages data for each recipe and installs it into + this temporary, shared area. + This directory defaults to the following: + + ${STAGING_DIR_HOST}/pkgdata + + Do not change this default. + + + + + PKGDEST + + + Points to the parent directory for files to be packaged + after they have been split into individual packages. + This directory defaults to the following: + + ${WORKDIR}/packages-split + + Under this directory, the build system creates + directories for each package specified in + PACKAGES. + Do not change this default. + + + + + PKGDESTWORK + + + Points to a temporary work area used by the + do_package + task to write output from the + do_packagedata + task. + The PKGDESTWORK location defaults to + the following: + + ${WORKDIR}/pkgdata + + The do_packagedata task then packages + the data in the temporary work area and installs it into a + shared directory pointed to by + PKGDATA_DIR. + + + + Do not change this default. + + + + + PKGE + + + The epoch of the output package built by the + OpenEmbedded build system. + By default, PKGE is set to + PE. + + + + + PKGR + + + The revision of the output package built by the + OpenEmbedded build system. + By default, PKGR is set to + PR. + + + + + PKGV + + + The version of the output package built by the + OpenEmbedded build system. + By default, PKGV is set to + PV. + + + + + PN + + This variable can have two separate functions depending on the context: a recipe + name or a resulting package name. + PN refers to a recipe name in the context of a file used + by the OpenEmbedded build system as input to create a package. + The name is normally extracted from the recipe file name. + For example, if the recipe is named + expat_2.0.1.bb, then the default value of PN + will be "expat". + + The variable refers to a package name in the context of a file created or produced by the + OpenEmbedded build system. + If applicable, the PN variable also contains any special + suffix or prefix. + For example, using bash to build packages for the native + machine, PN is bash-native. + Using bash to build packages for the target and for Multilib, + PN would be bash and + lib64-bash, respectively. + + + + + PNBLACKLIST + + + Lists recipes you do not want the OpenEmbedded build system + to build. + This variable works in conjunction with the + blacklist + class, which the recipe must inherit globally. + + + + To prevent a recipe from being built, inherit the class + globally and use the variable in your + local.conf file. + Here is an example that prevents + myrecipe from being built: + + INHERIT += "blacklist" + PNBLACKLIST[myrecipe] = "Not supported by our organization." + + + + + + PR + + + The revision of the recipe. + The default value for this variable is "r0". + + + + + PREFERRED_PROVIDER + + + If multiple recipes provide an item, this variable + determines which recipe should be given preference. + You should always suffix the variable with the name of the + provided item, and you should set it to the + PN + of the recipe to which you want to give precedence. + Some examples: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" + PREFERRED_PROVIDER_virtual/libgl ?= "mesa" + + + + + + PREFERRED_VERSION + + + If there are multiple versions of recipes available, this + variable determines which recipe should be given preference. + You must always suffix the variable with the + PN + you want to select, and you should set the + PV + accordingly for precedence. + You can use the "%" character as a + wildcard to match any number of characters, which can be + useful when specifying versions that contain long revision + numbers that could potentially change. + Here are two examples: + + PREFERRED_VERSION_python = "2.7.3" + PREFERRED_VERSION_linux-yocto = "3.10%" + + + + + + PREMIRRORS + + + Specifies additional paths from which the OpenEmbedded + build system gets source code. + When the build system searches for source code, it first + tries the local download directory. + If that location fails, the build system tries locations + defined by PREMIRRORS, the upstream + source, and then locations specified by + MIRRORS + in that order. + + + + Assuming your distribution + (DISTRO) + is "poky", the default value for + PREMIRRORS is defined in the + conf/distro/poky.conf file in the + meta-yocto Git repository. + + + + Typically, you could add a specific server for the + build system to attempt before any others by adding + something like the following to the + local.conf configuration file in the + Build Directory: + + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + + These changes cause the build system to intercept + Git, FTP, HTTP, and HTTPS requests and direct them to + the http:// sources mirror. + You can use file:// URLs to point + to local directories or network shares as well. + + + + + PRINC + + + + The PRINC variable has been deprecated + and triggers a warning if detected during a build. + For + PR + increments on changes, use the PR service instead. + You can find out more about this service in the + "Working With a PR Service" + section in the Yocto Project Development Manual. + + + + + + PRIVATE_LIBS + + + Specifies libraries installed within a recipe that + should be ignored by the OpenEmbedded build system's + shared library resolver. + This variable is typically used when software being + built by a recipe has its own private versions of a + library normally provided by another recipe. + In this case, you would not want the package containing + the private libraries to be set as a dependency on other + unrelated packages that should instead depend on the + package providing the standard version of the library. + + + + Libraries specified in this variable should be specified + by their file name. + For example, from the Firefox recipe in meta-browser: + + PRIVATE_LIBS = "libmozjs.so \ + libxpcom.so \ + libnspr4.so \ + libxul.so \ + libmozalloc.so \ + libplc4.so \ + libplds4.so" + + + + + + PROVIDES + + + A list of aliases by which a particular recipe can be + known. + By default, a recipe's own + PN + is implicitly already in its PROVIDES + list. + If a recipe uses PROVIDES, the + additional aliases are synonyms for the recipe and can + be useful satisfying dependencies of other recipes during + the build as specified by + DEPENDS. + + + + Consider the following example + PROVIDES statement from a recipe + file libav_0.8.11.bb: + + PROVIDES += "libpostproc" + + The PROVIDES statement results in + the "libav" recipe also being known as "libpostproc". + + + + + PRSERV_HOST + + + The network based + PR + service host and port. + + + + The conf/local.conf.sample.extended + configuration file in the + Source Directory + shows how the PRSERV_HOST variable is + set: + + PRSERV_HOST = "localhost:0" + + You must set the variable if you want to automatically + start a local + PR service. + You can set PRSERV_HOST to other + values to use a remote PR service. + + + + + PTEST_ENABLED + + + Specifies whether or not + Package Test + (ptest) functionality is enabled when building a recipe. + You should not set this variable directly. + Enabling and disabling building Package Tests + at build time should be done by adding "ptest" to (or + removing it from) + DISTRO_FEATURES. + + + + + PV + + + The version of the recipe. + The version is normally extracted from the recipe filename. + For example, if the recipe is named + expat_2.0.1.bb, then the default value of PV + will be "2.0.1". + PV is generally not overridden within + a recipe unless it is building an unstable (i.e. development) version from a source code repository + (e.g. Git or Subversion). + + + + + PYTHON_ABI + + + When used by recipes that inherit the + distutils3, + setuptools3, + distutils, + or + setuptools + classes, denotes the Application Binary Interface (ABI) + currently in use for Python. + By default, the ABI is "m". + You do not have to set this variable as the OpenEmbedded + build system sets it for you. + + + + The OpenEmbedded build system uses the ABI to construct + directory names used when installing the Python headers + and libraries in sysroot + (e.g. .../python3.3m/...). + + + + Recipes that inherit the + distutils + class during cross-builds also use this variable to + locate the headers and libraries of the appropriate Python + that the extension is targeting. + + + + + PYTHON_PN + + + When used by recipes that inherit the + distutils3, + setuptools3, + distutils, + or + setuptools + classes, specifies the major Python version being built. + For Python 2.x, PYTHON_PN would + be "python2". For Python 3.x, the variable would be + "python3". + You do not have to set this variable as the + OpenEmbedded build system automatically sets it for you. + + + + The variable allows recipes to use common infrastructure + such as the following: + + DEPENDS += "${PYTHON_PN}-native" + + In the previous example, the version of the dependency + is PYTHON_PN. + + + + + + + Q + + QMAKE_PROFILES + + + Specifies your own subset of .pro + files to be built for use with + qmake. + If you do not set this variable, all + .pro files in the directory pointed to + by S + will be built by default. + + + + This variable is used with recipes that inherit the + qmake_base + class or other classes that inherit + qmake_base. + + + + + + + R + + RCONFLICTS + + + The list of packages that conflict with packages. + Note that packages will not be installed if conflicting + packages are not first removed. + + + + Like all package-controlling variables, you must always use + them in conjunction with a package name override. + Here is an example: + + RCONFLICTS_${PN} = "another-conflicting-package-name" + + + + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned dependencies. + Although the syntax varies depending on the packaging + format, BitBake hides these differences from you. + Here is the general syntax to specify versions with + the RCONFLICTS variable: + + RCONFLICTS_${PN} = "package (operator version)" + + For operator, you can specify the + following: + + = + < + > + <= + >= + + For example, the following sets up a dependency on version + 1.2 or greater of the package foo: + + RCONFLICTS_${PN} = "foo (>= 1.2)" + + + + + + RDEPENDS + + + Lists a package's runtime dependencies (i.e. other packages) + that must be installed in order for the built package to run + correctly. + If a package in this list cannot be found during the build, + you will get a build error. + + + + When you use the RDEPENDS variable + in a recipe, you are essentially stating that the recipe's + do_build + task depends on the existence of a specific package. + Consider this simple example for two recipes named "a" and + "b" that produce similarly named IPK packages. + In this example, the RDEPENDS + statement appears in the "a" recipe: + + RDEPENDS_${PN} = "b" + + Here, the dependency is such that the + do_build task for recipe "a" depends + on the + do_package_write_ipk + task of recipe "b". + This means the package file for "b" must be available when + the output for recipe "a" has been completely built. + More importantly, package "a" will be marked as depending + on package "b" in a manner that is understood by the + package manager. + + + + The names of the packages you list within + RDEPENDS must be the names of other + packages - they cannot be recipe names. + Although package names and recipe names usually match, + the important point here is that you are + providing package names within the + RDEPENDS variable. + For an example of the default list of packages created from + a recipe, see the + PACKAGES + variable. + + + + Because the RDEPENDS variable applies + to packages being built, you should always use the variable + in a form with an attached package name. + For example, suppose you are building a development package + that depends on the perl package. + In this case, you would use the following + RDEPENDS statement: + + RDEPENDS_${PN}-dev += "perl" + + In the example, the development package depends on + the perl package. + Thus, the RDEPENDS variable has the + ${PN}-dev package name as part of the + variable. + + + + The package name you attach to the + RDEPENDS variable must appear + as it would in the PACKAGES + namespace before any renaming of the output package by + classes like + debian. + + + + In many cases you do not need to explicitly add + runtime dependencies using + RDEPENDS since some automatic + handling occurs: + + shlibdeps: If + a runtime package contains a shared library + (.so), the build + processes the library in order to determine other + libraries to which it is dynamically linked. + The build process adds these libraries to + RDEPENDS when creating the runtime + package. + pcdeps: If + the package ships a pkg-config + information file, the build process uses this file + to add items to the RDEPENDS + variable to create the runtime packages. + + + + + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned dependencies. + Although the syntax varies depending on the packaging + format, BitBake hides these differences from you. + Here is the general syntax to specify versions with + the RDEPENDS variable: + + RDEPENDS_${PN} = "package (operator version)" + + For operator, you can specify the + following: + + = + < + > + <= + >= + + For example, the following sets up a dependency on version + 1.2 or greater of the package foo: + + RDEPENDS_${PN} = "foo (>= 1.2)" + + + + + For information on build-time dependencies, see the + DEPENDS + variable. + + + + + REQUIRED_DISTRO_FEATURES + + + When inheriting the + distro_features_check + class, this + variable identifies distribution features that must + exist in the current configuration in order for the + OpenEmbedded build system to build the recipe. + In other words, if the + REQUIRED_DISTRO_FEATURES variable + lists a feature that does not appear in + DISTRO_FEATURES within the + current configuration, an error occurs and the + build stops. + + + + + RM_OLD_IMAGE + + + Reclaims disk space by removing previously built + versions of the same image from the + images directory pointed to by the + DEPLOY_DIR + variable. + + + + Set this variable to "1" in your + local.conf file to remove these + images. + + + + + RM_WORK_EXCLUDE + + + With rm_work enabled, this + variable specifies a list of recipes whose work directories + should not be removed. + See the "rm_work.bbclass" + section for more details. + + + + + ROOT_HOME + + + Defines the root home directory. + By default, this directory is set as follows in the + BitBake configuration file: + + ROOT_HOME ??= "/home/root" + + + This default value is likely used because some + embedded solutions prefer to have a read-only root + filesystem and prefer to keep writeable data in one + place. + + + + + You can override the default by setting the variable + in any layer or in the local.conf file. + Because the default is set using a "weak" assignment + (i.e. "??="), you can use either of the following forms + to define your override: + + ROOT_HOME = "/root" + ROOT_HOME ?= "/root" + + These override examples use /root, + which is probably the most commonly used override. + + + + + ROOTFS + + + Indicates a filesystem image to include as the root + filesystem. + + + + The ROOTFS variable is an optional + variable used with the + bootimg + class. + + + + + ROOTFS_POSTPROCESS_COMMAND + + + Added by classes to run post processing commands once the + OpenEmbedded build system has created the root filesystem. + You can specify shell commands separated by semicolons: + + ROOTFS_POSTPROCESS_COMMAND += "shell_command; ... " + + If you need to pass the path to the root filesystem within + the command, you can use + ${IMAGE_ROOTFS}, which points to + the root filesystem image. + See the + IMAGE_ROOTFS + variable for more information. + + + + + RPROVIDES + + + A list of package name aliases that a package also provides. + These aliases are useful for satisfying runtime dependencies + of other packages both during the build and on the target + (as specified by + RDEPENDS). + + A package's own name is implicitly already in its + RPROVIDES list. + + + + As with all package-controlling variables, you must always + use the variable in conjunction with a package name override. + Here is an example: + + RPROVIDES_${PN} = "widget-abi-2" + + + + + + RRECOMMENDS + + + A list of packages that extends the usability of a package + being built. + The package being built does not depend on this list of + packages in order to successfully build, but rather + uses them for extended usability. + To specify runtime dependencies for packages, see the + RDEPENDS + variable. + + + + The package manager will automatically install the + RRECOMMENDS list of packages when + installing the built package. + However, you can prevent listed packages from being + installed by using the + BAD_RECOMMENDATIONS, + NO_RECOMMENDATIONS, + and + PACKAGE_EXCLUDE + variables. + + + + Packages specified in + RRECOMMENDS need not actually be + produced. + However, a recipe must exist that provides each package, + either through the + PACKAGES + or + PACKAGES_DYNAMIC + variables or the + RPROVIDES + variable, or an error will occur during the build. + If such a recipe does exist and the package is not produced, + the build continues without error. + + + + Because the RRECOMMENDS variable + applies to packages being built, you should always attach + an override to the variable to specify the particular + package whose usability is being extended. + For example, suppose you are building a development package + that is extended to support wireless functionality. + In this case, you would use the following: + + RRECOMMENDS_${PN}-dev += "wireless_package_name" + + In the example, the package name + (${PN}-dev) + must appear as it would in the + PACKAGES + namespace before any renaming of the output package by + classes such as debian.bbclass. + + + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned recommends. + Although the syntax varies depending on the packaging + format, BitBake hides these differences from you. + Here is the general syntax to specify versions with + the RRECOMMENDS variable: + + RRECOMMENDS_${PN} = "package (operator version)" + + For operator, you can specify the + following: + + = + < + > + <= + >= + + For example, the following sets up a recommend on version + 1.2 or greater of the package foo: + + RRECOMMENDS_${PN} = "foo (>= 1.2)" + + + + + + RREPLACES + + + A list of packages replaced by a package. + The package manager uses this variable to determine which + package should be installed to replace other package(s) + during an upgrade. + In order to also have the other package(s) removed at the + same time, you must add the name of the other + package to the + RCONFLICTS variable. + + + As with all package-controlling variables, you must use + this variable in conjunction with a package name + override. + Here is an example: + + RREPLACES_${PN} = "other-package-being-replaced" + + + + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned replacements. + Although the syntax varies depending on the packaging + format, BitBake hides these differences from you. + Here is the general syntax to specify versions with + the RREPLACES variable: + + RREPLACES_${PN} = "package (operator version)" + + For operator, you can specify the + following: + + = + < + > + <= + >= + + For example, the following sets up a replacement using + version 1.2 or greater of the package + foo: + + RREPLACES_${PN} = "foo (>= 1.2)" + + + + + + RSUGGESTS + + + A list of additional packages that you can suggest for + installation by the package manager at the time a package + is installed. + Not all package managers support this functionality. + + + As with all package-controlling variables, you must always + use this variable in conjunction with a package name + override. + Here is an example: + + RSUGGESTS_${PN} = "useful-package another-package" + + + + + + + + S + + S + + + The location in the + Build Directory + where unpacked recipe source code resides. + This location is within the work directory + (WORKDIR), + which is not static. + The unpacked source location depends on the recipe name + (PN) and + recipe version + (PV) as + follows: + + ${WORKDIR}/${PN}-${PV} + + As an example, assume a + Source Directory + top-level folder named poky and a + default Build Directory at poky/build. + In this case, the work directory the build system uses + to keep the unpacked recipe for db + is the following: + + poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 + + + + + + SANITY_REQUIRED_UTILITIES + + + Specifies a list of command-line utilities that should be + checked for during the initial sanity checking process when + running BitBake. + If any of the utilities are not installed on the build host, + then BitBake immediately exits with an error. + + + + + SANITY_TESTED_DISTROS + + + A list of the host distribution identifiers that the + build system has been tested against. + Identifiers consist of the host distributor ID + followed by the release, + as reported by the lsb_release tool + or as read from /etc/lsb-release. + Separate the list items with explicit newline + characters (\n). + If SANITY_TESTED_DISTROS is not empty + and the current value of + NATIVELSBSTRING + does not appear in the list, then the build system reports + a warning that indicates the current host distribution has + not been tested as a build host. + + + + + SDK_ARCH + + + The target architecture for the SDK. + Typically, you do not directly set this variable. + Instead, use + SDKMACHINE. + + + + + SDK_DEPLOY + + + The directory set up and used by the + populate_sdk_base + to which the SDK is deployed. + The populate_sdk_base class defines + SDK_DEPLOY as follows: + + SDK_DEPLOY = "${TMPDIR}/deploy/sdk" + + + + + + SDK_DIR + + + The parent directory used by the OpenEmbedded build system + when creating SDK output. + The + populate_sdk_base + class defines the variable as follows: + + SDK_DIR = "${WORKDIR}/sdk" + + + The SDK_DIR directory is a + temporary directory as it is part of + WORKDIR. + The final output directory is + SDK_DEPLOY. + + + + + + SDK_NAME + + + The base name for SDK output files. + The name is derived from the + DISTRO, + TCLIBC, + SDK_ARCH, + IMAGE_BASENAME, + and + TUNE_PKGARCH + variables: + + SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" + + + + + + SDK_OUTPUT + + + The location used by the OpenEmbedded build system when + creating SDK output. + The + populate_sdk_base + class defines the variable as follows: + + SDK_OUTPUT = "${SDK_DIR}/image" + + + The SDK_OUTPUT directory is a + temporary directory as it is part of + WORKDIR by way of + SDK_DIR. + The final output directory is + SDK_DEPLOY. + + + + + + + SDK_PACKAGE_ARCHS + + + Specifies a list of architectures compatible with + the SDK machine. + This variable is set automatically and should not + normally be hand-edited. + Entries are separated using spaces and listed in order + of priority. + The default value for + SDK_PACKAGE_ARCHS is "all any noarch + ${SDK_ARCH}-${SDKPKGSUFFIX}". + + + + + SDKIMAGE_FEATURES + + Equivalent to + IMAGE_FEATURES. + However, this variable applies to the SDK generated from an + image using the following command: + + $ bitbake -c populate_sdk imagename + + + + + + SDKMACHINE + + + 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 + runs on the target you specify with the + SDKMACHINE value. + The value points to a corresponding + .conf file under + conf/machine-sdk/. + + + + You can use "i686" and "x86_64" as possible values + for this variable. The variable defaults to "i686" + and is set in the local.conf file in the Build Directory. + + SDKMACHINE ?= "i686" + + + You cannot set the SDKMACHINE + variable in your distribution configuration file. + If you do, the configuration will not take affect. + + + + + + SDKPATH + + + Defines the path offered to the user for installation + of the SDK that is generated by the OpenEmbedded build + system. + The path appears as the default location for installing + the SDK when you run the SDK's installation script. + You can override the offered path when you run the + script. + + + + + SECTION + + The section in which packages should be categorized. + Package management utilities can make use of this variable. + + + + SELECTED_OPTIMIZATION + + + Specifies the optimization flags passed to the C compiler + when building for the target. + The flags are passed through the default value of the + TARGET_CFLAGS + variable. + + + + The SELECTED_OPTIMIZATION variable + takes the value of + FULL_OPTIMIZATION + unless DEBUG_BUILD = "1". + If that is the case, the value of + DEBUG_OPTIMIZATION is used. + + + + + SERIAL_CONSOLE + + + Defines a serial console (TTY) to enable using getty. + Provide a value that specifies the baud rate followed by + the TTY device name separated by a space. + You cannot specify more than one TTY device: + + SERIAL_CONSOLE = "115200 ttyS0" + + + The SERIAL_CONSOLE variable + is deprecated. + Please use the + SERIAL_CONSOLES + variable. + + + + + + SERIAL_CONSOLES + + + Defines the serial consoles (TTYs) to enable using getty. + Provide a value that specifies the baud rate followed by + the TTY device name separated by a semicolon. + Use spaces to separate multiple devices: + + SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" + + + + + + SERIAL_CONSOLES_CHECK + + + Similar to + SERIAL_CONSOLES + except the device is checked for existence before attempting + to enable it. + This variable is currently only supported with SysVinit + (i.e. not with systemd). + + + + + SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS + + + A list of recipe dependencies that should not be used to + determine signatures of tasks from one recipe when they + depend on tasks from another recipe. + For example: + + SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" + + In this example, intone depends on + mplayer2. + + + + Use of this variable is one mechanism to remove dependencies + that affect task signatures and thus force rebuilds when a + recipe changes. + Caution + If you add an inappropriate dependency for a recipe + relationship, the software might break during + runtime if the interface of the second recipe was + changed after the first recipe had been built. + + + + + + SIGGEN_EXCLUDERECIPES_ABISAFE + + + A list of recipes that are completely stable and will + never change. + The ABI for the recipes in the list are presented by + output from the tasks run to build the recipe. + Use of this variable is one way to remove dependencies from + one recipe on another that affect task signatures and + thus force rebuilds when the recipe changes. + Caution + If you add an inappropriate variable to this list, + the software might break at runtime if the + interface of the recipe was changed after the other + had been built. + + + + + + SITEINFO_BITS + + + Specifies the number of bits for the target system CPU. + The value should be either "32" or "64". + + + + + SITEINFO_ENDIANNESS + + + Specifies the endian byte order of the target system. + The value should be either "le" for little-endian or "be" for big-endian. + + + + + SOC_FAMILY + + + Groups together machines based upon the same family + of SOC (System On Chip). + You typically set this variable in a common + .inc file that you include in the + configuration files of all the machines. + + You must include + conf/machine/include/soc-family.inc + for this variable to appear in + MACHINEOVERRIDES. + + + + + + SOLIBS + + + Defines the suffix for shared libraries used on the + target platform. + By default, this suffix is ".so.*" for all Linux-based + systems and is defined in the + meta/conf/bitbake.conf configuration + file. + + + + You will see this variable referenced in the default values + of FILES_${PN}. + + + + + SOLIBSDEV + + + Defines the suffix for the development symbolic link + (symlink) for shared libraries on the target platform. + By default, this suffix is ".so" for Linux-based + systems and is defined in the + meta/conf/bitbake.conf configuration + file. + + + + You will see this variable referenced in the default values + of FILES_${PN}-dev. + + + + + SOURCE_MIRROR_URL + + + Defines your own + PREMIRRORS + from which to first fetch source before attempting to fetch + from the upstream specified in + SRC_URI. + + + + To use this variable, you must globally inherit the + own-mirrors + class and then provide the URL to your mirrors. + Here is an example: + + INHERIT += "own-mirrors" + SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" + + + You can specify only a single URL in + SOURCE_MIRROR_URL. + + + + + + SPDXLICENSEMAP + + + Maps commonly used license names to their SPDX counterparts + found in meta/files/common-licenses/. + For the default SPDXLICENSEMAP + mappings, see the + meta/conf/licenses.conf file. + + + + For additional information, see the + LICENSE + variable. + + + + + SPECIAL_PKGSUFFIX + + + A list of prefixes for PN used by the + OpenEmbedded build system to create variants of recipes or packages. + The list specifies the prefixes to strip off during certain circumstances + such as the generation of the BPN variable. + + + + + SRC_URI + + The list of source files - local or remote. + This variable tells the OpenEmbedded build system which bits + to pull in for the build and how to pull them in. + For example, if the recipe or append file only needs to + fetch a tarball from the Internet, the recipe or + append file uses a single SRC_URI + entry. + On the other hand, if the recipe or append file needs to + fetch a tarball, apply two patches, and include a custom + file, the recipe or append file would include four + instances of the variable. + The following list explains the available URI protocols: + + file:// - + Fetches files, which are usually files shipped with + the + Metadata, + from the local machine. + The path is relative to the + FILESPATH + variable. + Thus, the build system searches, in order, from the + following directories, which are assumed to be a + subdirectories of the directory in which the + recipe file (.bb) or + append file (.bbappend) + resides: + + ${BPN} - + The base recipe name without any special + suffix or version numbers. + + ${BP} - + ${BPN}-${PV}. + The base recipe name and version but without + any special package name suffix. + + files - + Files within a directory, which is named + files and is also + alongside the recipe or append file. + + + + If you want the build system to pick up files + specified through a + SRC_URI + statement from your append file, you need to be + sure to extend the + FILESPATH + variable by also using the + FILESEXTRAPATHS + variable from within your append file. + + + bzr:// - Fetches files from a + Bazaar revision control repository. + git:// - Fetches files from a + Git revision control repository. + osc:// - Fetches files from + an OSC (OpenSUSE Build service) revision control repository. + repo:// - Fetches files from + a repo (Git) repository. + ccrc:// - + Fetches files from a ClearCase repository. + + http:// - Fetches files from + the Internet using http. + https:// - Fetches files + from the Internet using https. + ftp:// - Fetches files + from the Internet using ftp. + cvs:// - Fetches files from + a CVS revision control repository. + hg:// - Fetches files from + a Mercurial (hg) revision control repository. + p4:// - Fetches files from + a Perforce (p4) revision control repository. + ssh:// - Fetches files from + a secure shell. + svn:// - Fetches files from + a Subversion (svn) revision control repository. + + + Standard and recipe-specific options for SRC_URI exist. + Here are standard options: + + apply - Whether to apply + the patch or not. + The default action is to apply the patch. + striplevel - Which + striplevel to use when applying the patch. + The default level is 1. + patchdir - Specifies + the directory in which the patch should be applied. + The default is ${S}. + + + + Here are options specific to recipes building code from a revision control system: + + mindate - + Apply the patch only if + SRCDATE + is equal to or greater than mindate. + + maxdate - + Apply the patch only if SRCDATE + is not later than mindate. + + minrev - + Apply the patch only if SRCREV + is equal to or greater than minrev. + + maxrev - + Apply the patch only if SRCREV + is not later than maxrev. + + rev - + Apply the patch only if SRCREV + is equal to rev. + + notrev - + Apply the patch only if SRCREV + is not equal to rev. + + + + Here are some additional options worth mentioning: + + unpack - Controls + whether or not to unpack the file if it is an archive. + The default action is to unpack the file. + subdir - Places the file + (or extracts its contents) into the specified + subdirectory of WORKDIR. + This option is useful for unusual tarballs or other archives that + do not have their files already in a subdirectory within the archive. + + name - Specifies a + name to be used for association with SRC_URI checksums + when you have more than one file specified in SRC_URI. + + downloadfilename - Specifies + the filename used when storing the downloaded file. + + + + + + SRC_URI_OVERRIDES_PACKAGE_ARCH + + + By default, the OpenEmbedded build system automatically detects whether + SRC_URI + contains files that are machine-specific. + If so, the build system automatically changes + PACKAGE_ARCH. + Setting this variable to "0" disables this behavior. + + + + + SRCDATE + + + The date of the source code used to build the package. + This variable applies only if the source was fetched from a Source Code Manager (SCM). + + + + + SRCPV + + + Returns the version string of the current package. + This string is used to help define the value of + PV. + + + + The SRCPV variable is defined in the + meta/conf/bitbake.conf configuration + file in the + Source Directory + as follows: + + SRCPV = "${@bb.fetch2.get_srcrev(d)}" + + + + + Recipes that need to define PV do so + with the help of the SRCPV. + For example, the ofono recipe + (ofono_git.bb) located in + meta/recipes-connectivity in the + Source Directory defines PV as + follows: + + PV = "0.12-git${SRCPV}" + + + + + + SRCREV + + + The revision of the source code used to build the package. + This variable applies to Subversion, Git, Mercurial and Bazaar + only. + Note that if you wish to build a fixed revision and you wish + to avoid performing a query on the remote repository every time + BitBake parses your recipe, you should specify a SRCREV that is a + full revision identifier and not just a tag. + + + + + SSTATE_DIR + + The directory for the shared state cache. + + + + SSTATE_MIRROR_ALLOW_NETWORK + + + If set to "1", allows fetches from + mirrors that are specified in + SSTATE_MIRRORS + to work even when fetching from the network has been + disabled by setting BB_NO_NETWORK + to "1". + Using the + SSTATE_MIRROR_ALLOW_NETWORK + variable is useful if you have set + SSTATE_MIRRORS to point to an + internal server for your shared state cache, but + you want to disable any other fetching from the network. + + + + + SSTATE_MIRRORS + + + Configures the OpenEmbedded build system to search other + mirror locations for prebuilt cache data objects before + building out the data. + This variable works like fetcher + MIRRORS + and PREMIRRORS + and points to the cache locations to check for the shared + objects. + + + + You can specify a filesystem directory or a remote URL such + as HTTP or FTP. + The locations you specify need to contain the shared state + cache (sstate-cache) results from previous builds. + The sstate-cache you point to can also be from builds on + other machines. + + + + If a mirror uses the same structure as + SSTATE_DIR, + you need to add + "PATH" at the end as shown in the examples below. + The build system substitutes the correct path within the + directory structure. + + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some-local-dir/sstate/PATH" + + + + + + STAGING_BASE_LIBDIR_NATIVE + + + Specifies the path to the /lib + subdirectory of the sysroot directory for the + build host. + + + + + STAGING_BASELIBDIR + + + Specifies the path to the /lib + subdirectory of the sysroot directory for the target + for which the current recipe is being built + (STAGING_DIR_HOST). + + + + + STAGING_BINDIR + + + Specifies the path to the + /usr/bin subdirectory of the + sysroot directory for the target for which the current + recipe is being built + (STAGING_DIR_HOST). + + + + + STAGING_BINDIR_CROSS + + + Specifies the path to the directory containing binary + configuration scripts. + These scripts provide configuration information for + other software that wants to make use of libraries or + include files provided by the software associated with + the script. + + This style of build configuration has been largely + replaced by pkg-config. + Consequently, if pkg-config + is supported by the library to which you are linking, + it is recommended you use + pkg-config instead of a + provided configuration script. + + + + + + STAGING_BINDIR_NATIVE + + + Specifies the path to the + /usr/bin subdirectory of the + sysroot directory for the build host. + + + + + STAGING_DATADIR + + + Specifies the path to the /usr/share + subdirectory of the sysroot directory for the target + for which the current recipe is being built + (STAGING_DIR_HOST). + + + + + STAGING_DIR + + + Specifies the path to the top-level sysroots directory + (i.e. + ${TMPDIR}/sysroots). + + Recipes should never write files directly under + this directory because the OpenEmbedded build system + manages the directory automatically. + Instead, files should be installed to + ${D} + within your recipe's + do_install + task and then the OpenEmbedded build system will + stage a subset of those files into the sysroot. + + + + + + STAGING_DIR_HOST + + + Specifies the path to the primary sysroot directory for + which the target is being built. + Depending on the type of recipe and the build target, the + recipe's value is as follows: + + For recipes building for the target + machine, the value is "${STAGING_DIR}/${MACHINE}". + + For native + recipes building + for the build host, the value is empty given the + assumption that when building for the build host, + the build host's own directories should be used. + + For nativesdk + recipes that Build for the SDK, the value is + "${STAGING_DIR}/${MULTIMACH_HOST_SYS}". + + + + + + + STAGING_DATADIR_NATIVE + + + Specifies the path to the /usr/share + subdirectory of the sysroot directory for the build host. + + + + + + + STAGING_DIR_NATIVE + + + Specifies the path to the sysroot directory for the + build host. + + + + + STAGING_DIR_TARGET + + + Specifies the path to the sysroot directory for the + target for which the current recipe is being built. + In most cases, this path is the + STAGING_DIR_HOST. + + + + Some recipes build binaries that can run on the target + system but those binaries in turn generate code for + another different system (e.g. cross-canadian recipes). + Using terminology from GNU, the primary system is referred + to as the "HOST" and the secondary, or different, system is + referred to as the "TARGET". + Thus, the binaries run on the "HOST" system and + and generate binaries for the "TARGET" system. + STAGING_DIR_TARGET points to the + sysroot used for the "TARGET" system. + + + + + STAGING_ETCDIR_NATIVE + + + Specifies the path to the /etc + subdirectory of the sysroot directory for the + build host. + + + + + STAGING_EXECPREFIXDIR + + + Specifies the path to the /usr + subdirectory of the sysroot directory for the target + for which the current recipe is being built + (STAGING_DIR_HOST). + + + + + STAGING_INCDIR + + + Specifies the path to the + /usr/include subdirectory of the + sysroot directory for the target for which the current + recipe being built + (STAGING_DIR_HOST). + + + + + STAGING_INCDIR_NATIVE + + + Specifies the path to the /usr/include + subdirectory of the sysroot directory for the build host. + + + + + STAGING_LIBDIR + + + Specifies the path to the /usr/lib + subdirectory of the sysroot directory for the target for + which the current recipe is being built + (STAGING_DIR_HOST). + + + + + STAGING_LIBDIR_NATIVE + + + Specifies the path to the /usr/lib + subdirectory of the sysroot directory for the build host. + + + + + STAGING_KERNEL_DIR + + + The directory with kernel headers that are required to build out-of-tree + modules. + + + + + STAMP + + + Specifies the base path used to create recipe stamp files. + The path to an actual stamp file is constructed by evaluating this + string and then appending additional information. + Currently, the default assignment for STAMP + as set in the meta/conf/bitbake.conf file + is: + + STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" + + See STAMPS_DIR, + MULTIMACH_TARGET_SYS, + PN, + EXTENDPE, + PV, and + PR for related variable + information. + + + + + STAMPS_DIR + + + Specifies the base directory in which the OpenEmbedded + build system places stamps. + The default directory is + ${TMPDIR}/stamps. + + + + + SUMMARY + + The short (72 characters or less) summary of the binary package for packaging + systems such as opkg, rpm or + dpkg. + By default, SUMMARY is used to define + the DESCRIPTION + variable if DESCRIPTION is not set + in the recipe. + + + + + SYSLINUX_DEFAULT_CONSOLE + + + Specifies the kernel boot default console. + If you want to use a console other than the default, + set this variable in your recipe as follows where "X" is + the console number you want to use: + + SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" + + + + + The + syslinux + class initially sets this variable to null but then checks + for a value later. + + + + + SYSLINUX_OPTS + + + Lists additional options to add to the syslinux file. + You need to set this variable in your recipe. + If you want to list multiple options, separate the options + with a semicolon character (;). + + + + The + syslinux + class uses this variable to create a set of options. + + + + + SYSLINUX_SERIAL + + + Specifies the alternate serial port or turns it off. + To turn off serial, set this variable to an empty string + in your recipe. + The variable's default value is set in the + syslinux + as follows: + + SYSLINUX_SERIAL ?= "0 115200" + + The class checks for and uses the variable as needed. + + + + SYSLINUX_SPLASH + + + An .LSS file used as the background + for the VGA boot menu when you are using the boot menu. + You need to set this variable in your recipe. + + + + The + syslinux + class checks for this variable and if found, the + OpenEmbedded build system installs the splash screen. + + + + + SYSLINUX_SERIAL_TTY + + + Specifies the alternate console=tty... kernel boot argument. + The variable's default value is set in the + syslinux + as follows: + + SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" + + The class checks for and uses the variable as needed. + + + + + SYSROOT_PREPROCESS_FUNCS + + + A list of functions to execute after files are staged into + the sysroot. + These functions are usually used to apply additional + processing on the staged files, or to stage additional + files. + + + + + SYSTEMD_AUTO_ENABLE + + + When inheriting the + systemd + class, this variable specifies whether the service you have + specified in + SYSTEMD_SERVICE + should be started automatically or not. + By default, the service is enabled to automatically start + at boot time. + The default setting is in the + systemd + class as follows: + + SYSTEMD_AUTO_ENABLE ??= "enable" + + You can disable the service by setting the variable to + "disable". + + + + + SYSTEMD_PACKAGES + + + When inheriting the + systemd + class, this variable locates the systemd unit files when + they are not found in the main recipe's package. + By default, the + SYSTEMD_PACKAGES variable is set + such that the systemd unit files are assumed to reside in + the recipes main package: + + SYSTEMD_PACKAGES ?= "${PN}" + + If these unit files are not in this recipe's main + package, you need to use + SYSTEMD_PACKAGES to list the package + or packages in which the build system can find the systemd + unit files. + + + + + SYSTEMD_SERVICE + + + When inheriting the + systemd + class, this variable specifies the systemd service name for + a package. + + + + When you specify this file in your recipe, use a package + name override to indicate the package to which the value + applies. + Here is an example from the connman recipe: + + SYSTEMD_SERVICE_${PN} = "connman.service" + + + + + + SYSVINIT_ENABLED_GETTYS + + + When using + SysVinit, + specifies a space-separated list of the virtual terminals + that should be running a + getty + (allowing login), assuming + USE_VT + is not set to "0". + + + + The default value for + SYSVINIT_ENABLED_GETTYS is "1" + (i.e. only run a getty on the first virtual terminal). + + + + + + + T + + T + + This variable points to a directory were BitBake places + temporary files, which consist mostly of task logs and + scripts, when building a particular recipe. + The variable is typically set as follows: + + T = "${WORKDIR}/temp" + + The WORKDIR + is the directory into which BitBake unpacks and builds the + recipe. + The default bitbake.conf file sets this variable. + The T variable is not to be confused with + the TMPDIR variable, + which points to the root of the directory tree where BitBake + places the output of an entire build. + + + + + TARGET_ARCH + + + The target machine's architecture. + The OpenEmbedded build system supports many + architectures. + Here is an example list of architectures supported. + This list is by no means complete as the architecture + is configurable: + + arm + i586 + x86_64 + powerpc + powerpc64 + mips + mipsel + + For additional information on machine architectures, see + the + TUNE_ARCH + variable. + + + + + TARGET_AS_ARCH + + + Specifies architecture-specific assembler flags for the + target system. + TARGET_AS_ARCH is initialized from + TUNE_ASARGS + by default in the BitBake configuration file + (meta/conf/bitbake.conf): + + TARGET_AS_ARCH = "${TUNE_ASARGS}" + + + + + + TARGET_CC_ARCH + + + Specifies architecture-specific C compiler flags for the + target system. + TARGET_CC_ARCH is initialized from + TUNE_CCARGS + by default. + + It is a common workaround to append + LDFLAGS + to TARGET_CC_ARCH + in recipes that build software for the target that + would not otherwise respect the exported + LDFLAGS variable. + + + + + + TARGET_CC_KERNEL_ARCH + + + This is a specific kernel compiler flag for a CPU or + Application Binary Interface (ABI) tune. + The flag is used rarely and only for cases where a + userspace + TUNE_CCARGS + is not compatible with the kernel compilation. + The TARGET_CC_KERNEL_ARCH variable + allows the kernel (and associated modules) to use a + different configuration. + See the + meta/conf/machine/include/arm/feature-arm-thumb.inc + file in the + Source Directory + for an example. + + + + + TARGET_CFLAGS + + + Specifies the flags to pass to the C compiler when building + for the target. + When building in the target context, + CFLAGS + is set to the value of this variable by default. + + + + Additionally, the SDK's environment setup script sets + the + CFLAGS + variable in the environment to the + TARGET_CFLAGS value so that + executables built using the SDK also have the flags + applied. + + + + + TARGET_CPPFLAGS + + + Specifies the flags to pass to the C pre-processor + (i.e. to both the C and the C++ compilers) when building + for the target. + When building in the target context, + CPPFLAGS + is set to the value of this variable by default. + + + + Additionally, the SDK's environment setup script sets + the + CPPFLAGS + variable in the environment to the + TARGET_CPPFLAGS value so that + executables built using the SDK also have the flags + applied. + + + + + TARGET_CXXFLAGS + + + Specifies the flags to pass to the C++ compiler when + building for the target. + When building in the target context, + CXXFLAGS + is set to the value of this variable by default. + + + + Additionally, the SDK's environment setup script sets + the + CXXFLAGS + variable in the environment to the + TARGET_CXXFLAGS value so that + executables built using the SDK also have the flags + applied. + + + + + TARGET_FPU + + Specifies the method for handling FPU code. + For FPU-less targets, which include most ARM CPUs, the variable must be + set to "soft". + If not, the kernel emulation gets used, which results in a performance penalty. + + + + TARGET_LD_ARCH + + + Specifies architecture-specific linker flags for the + target system. + TARGET_LD_ARCH is initialized from + TUNE_LDARGS + by default in the BitBake configuration file + (meta/conf/bitbake.conf): + + TARGET_LD_ARCH = "${TUNE_LDARGS}" + + + + + + TARGET_LDFLAGS + + + Specifies the flags to pass to the linker when building + for the target. + When building in the target context, + LDFLAGS + is set to the value of this variable by default. + + + + Additionally, the SDK's environment setup script sets + the + LDFLAGS + variable in the environment to the + TARGET_LDFLAGS value so that + executables built using the SDK also have the flags + applied. + + + + + TARGET_OS + + Specifies the target's operating system. + The variable can be set to "linux" for glibc-based systems and + to "linux-uclibc" for uclibc. + For ARM/EABI targets, there are also "linux-gnueabi" and + "linux-uclibc-gnueabi" values possible. + + + + TCLIBC + + + Specifies the GNU standard C library (libc) + variant to use during the build process. + This variable replaces POKYLIBC, which is no longer + supported. + + + You can select "glibc" or "uclibc". + + + + + TCMODE + + + Specifies the toolchain selector. + TCMODE controls the characteristics + of the generated packages and images by telling the + OpenEmbedded build system which toolchain profile to use. + By default, the OpenEmbedded build system builds its own + internal toolchain. + The variable's default value is "default", which uses + that internal toolchain. + + If TCMODE is set to a value + other than "default", then it is your responsibility + to ensure that the toolchain is compatible with the + default toolchain. + Using older or newer versions of these components + might cause build problems. + See the + Release Notes + for the specific components with which the toolchain + must be compatible. + + + + + With additional layers, it is possible to use a pre-compiled + external toolchain. + One example is the Sourcery G++ Toolchain. + The support for this toolchain resides in the separate + meta-sourcery layer at + . + You can use meta-sourcery as a + template for adding support for other external toolchains. + + + + The TCMODE variable points the build + system to a file in + conf/distro/include/tcmode-${TCMODE}.inc. + Thus, for meta-sourcery, + which has conf/distro/include/tcmode-external-sourcery.inc, + you would set the variable as follows: + + TCMODE ?= "external-sourcery" + + + + + The variable is similar to + TCLIBC, + which controls the variant of the GNU standard C library + (libc) used during the build process: + glibc or uclibc. + + + + + TEST_EXPORT_DIR + + + The location the OpenEmbedded build system uses to export + tests when the + TEST_EXPORT_ONLY + variable is set to "1". + + + + The TEST_EXPORT_DIR variable defaults + to "${TMPDIR}/testimage/${PN}". + + + + + TEST_EXPORT_ONLY + + + Specifies to export the tests only. + Set this variable to "1" if you do not want to run the + tests but you want them to be exported in a manner that + you to run them outside of the build system. + + + + + TEST_IMAGE + + + Automatically runs the series of automated tests for + images when an image is successfully built. + + + + These tests are written in Python making use of the + unittest module, and the majority of + them run commands on the target system over + ssh. + You can set this variable to "1" in your + local.conf file in the + Build Directory + to have the OpenEmbedded build system automatically run + these tests after an image successfully builds: + + TEST_IMAGE = "1" + + For more information on enabling, running, and writing + these tests, see the + "Performing Automated Runtime Testing" + section in the Yocto Project Development Manual and the + "testimage.bbclass" + section. + + + + + TEST_LOG_DIR + + + Holds the SSH log and the boot log for QEMU machines. + The TEST_LOG_DIR variable defaults + to "${WORKDIR}/testimage". + + Actual test results reside in the task log + (log.do_testimage), which is in + the ${WORKDIR}/temp/ directory. + + + + + + TEST_POWERCONTROL_CMD + + + For automated hardware testing, specifies the command to + use to control the power of the target machine under test. + Typically, this command would point to a script that + performs the appropriate action (e.g. interacting + with a web-enabled power strip). + The specified command should expect to receive as the last + argument "off", "on" or "cycle" specifying to power off, + on, or cycle (power off and then power on) the device, + respectively. + + + + + TEST_POWERCONTROL_EXTRA_ARGS + + + For automated hardware testing, specifies additional + arguments to pass through to the command specified in + TEST_POWERCONTROL_CMD. + Setting TEST_POWERCONTROL_EXTRA_ARGS + is optional. + You can use it if you wish, for example, to separate the + machine-specific and non-machine-specific parts of the + arguments. + + + + + TEST_QEMUBOOT_TIMEOUT + + + The time in seconds allowed for an image to boot before + automated runtime tests begin to run against an + image. + The default timeout period to allow the boot process to + reach the login prompt is 500 seconds. + You can specify a different value in the + local.conf file. + + + + For more information on testing images, see the + "Performing Automated Runtime Testing" + section in the Yocto Project Development Manual. + + + + + TEST_SERIALCONTROL_CMD + + + For automated hardware testing, specifies the command + to use to connect to the serial console of the target + machine under test. + This command simply needs to connect to the serial console + and forward that connection to standard input and output + as any normal terminal program does. + + + + For example, to use the Picocom terminal program on + serial device /dev/ttyUSB0 at + 115200bps, you would set the variable as follows: + + TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" + + + + + + TEST_SERIALCONTROL_EXTRA_ARGS + + + For automated hardware testing, specifies additional + arguments to pass through to the command specified in + TEST_SERIALCONTROL_CMD. + Setting TEST_SERIALCONTROL_EXTRA_ARGS + is optional. + You can use it if you wish, for example, to separate the + machine-specific and non-machine-specific parts of the + command. + + + + + TEST_SERVER_IP + + + The IP address of the build machine (host machine). + This IP address is usually automatically detected. + However, if detection fails, this variable needs to be set + to the IP address of the build machine (i.e. where + the build is taking place). + + The TEST_SERVER_IP variable + is only used for a small number of tests such as + the "smart" test suite, which needs to download + packages from DEPLOY_DIR/rpm. + + + + + + TEST_TARGET + + + Specifies the target controller to use when running tests + against a test image. + The default controller to use is "qemu": + + TEST_TARGET = "qemu" + + A target controller is a class that defines how an + image gets deployed on a target and how a target is started. + A layer can extend the controllers by adding a module + in the layer's /lib/oeqa/controllers + directory and by inheriting the + BaseTarget class, which is an abstract + class that cannot be used as a value of + TEST_TARGET. + + + + You can provide the following arguments with + TEST_TARGET: + + "qemu" and "QemuTarget": + Boots a QEMU image and runs the tests. + See the + "Enabling Runtime Tests on QEMU" + section in the Yocto Project Development Manual for + more information. + + "simpleremote" and "SimpleRemoteTarget": + Runs the tests on target hardware that is already + up and running. + The hardware can be on the network or it can be + a device running an image on QEMU. + You must also set + TEST_TARGET_IP + when you use "simpleremote" or "SimpleRemoteTarget". + + This argument is defined in + meta/lib/oeqa/targetcontrol.py. + The small caps names are kept for compatibility + reasons. + + + "GummibootTarget": + Automatically deploys and runs tests on an + EFI-enabled machine that has a master image + installed. + + This argument is defined in + meta/lib/oeqa/controllers/masterimage.py. + + + + + + + For information on running tests on hardware, see the + "Enabling Runtime Tests on Hardware" + section in the Yocto Project Development Manual. + + + + + TEST_TARGET_IP + + + The IP address of your hardware under test. + The TEST_TARGET_IP variable has no + effect when + TEST_TARGET + is set to "qemu". + + + + When you specify the IP address, you can also include a + port. + Here is an example: + + TEST_TARGET_IP = "192.168.1.4:2201" + + Specifying a port is useful when SSH is started on a + non-standard port or in cases when your hardware under test + is behind a firewall or network that is not directly + accessible from your host and you need to do port address + translation. + + + + + TEST_SUITES + + + An ordered list of tests (modules) to run against + an image when performing automated runtime testing. + + + + The OpenEmbedded build system provides a core set of tests + that can be used against images. + + Currently, there is only support for running these tests + under QEMU. + + Tests include ping, + ssh, df among + others. + You can add your own tests to the list of tests by + appending TEST_SUITES as follows: + + TEST_SUITES_append = " mytest" + + Alternatively, you can provide the "auto" option to + have all applicable tests run against the image. + + TEST_SUITES_append = " auto" + + Using this option causes the build system to automatically + run tests that are applicable to the image. + Tests that are not applicable are skipped. + + + + The order in which tests are run is important. + Tests that depend on another test must appear later in the + list than the test on which they depend. + For example, if you append the list of tests with two + tests (test_A and + test_B) where + test_B is dependent on + test_A, then you must order the tests + as follows: + + TEST_SUITES = " test_A test_B" + + + + + For more information on testing images, see the + "Performing Automated Runtime Testing" + section in the Yocto Project Development Manual. + + + + + THISDIR + + + The directory in which the file BitBake is currently + parsing is located. + Do not manually set this variable. + + + + + TMPDIR + + + This variable is the base directory the OpenEmbedded + build system uses for all build output and intermediate + files (other than the shared state cache). + By default, the TMPDIR variable points + to tmp within the + Build Directory. + + + + If you want to establish this directory in a location other + than the default, you can uncomment and edit the following + statement in the + conf/local.conf file in the + Source Directory: + + #TMPDIR = "${TOPDIR}/tmp" + + An example use for this scenario is to set + TMPDIR to a local disk, which does + not use NFS, while having the Build Directory use NFS. + + + + The filesystem used by TMPDIR must + have standard filesystem semantics (i.e. mixed-case files + are unique, POSIX file locking, and persistent inodes). + Due to various issues with NFS and bugs in some + implementations, NFS does not meet this minimum + requirement. + Consequently, TMPDIR cannot be on + NFS. + + + + + TOOLCHAIN_HOST_TASK + + + This variable lists packages the OpenEmbedded build system + uses when building an SDK, which contains a + cross-development environment. + The packages specified by this variable are part of the + toolchain set that runs on the + SDKMACHINE, + and each package should usually have the prefix + "nativesdk-". + When building an SDK using + bitbake -c populate_sdk <imagename>, + a default list of packages is set in this variable, but + you can add additional packages to the list. + + + + For background information on cross-development toolchains + in the Yocto Project development environment, see the + "Cross-Development Toolchain Generation" + section. + For information on setting up a cross-development + environment, see the + "Installing the ADT and Toolchains" + section in the Yocto Project Application Developer's Guide. + + + + + TOOLCHAIN_TARGET_TASK + + + This variable lists packages the OpenEmbedded build system + uses when it creates the target part of an SDK + (i.e. the part built for the target hardware), which + includes libraries and headers. + + + + For background information on cross-development toolchains + in the Yocto Project development environment, see the + "Cross-Development Toolchain Generation" + section. + For information on setting up a cross-development + environment, see the + "Installing the ADT and Toolchains" + section in the Yocto Project Application Developer's Guide. + + + + + TOPDIR + + + The top-level + Build Directory. + BitBake automatically sets this variable when you + initialize your build environment using either + &OE_INIT_FILE; + or + oe-init-build-env-memres. + + + + + TRANSLATED_TARGET_ARCH + + + A sanitized version of + TARGET_ARCH. + This variable is used where the architecture is needed in + a value where underscores are not allowed, for example + within package filenames. + In this case, dash characters replace any underscore + characters used in TARGET_ARCH. + + + + Do not edit this variable. + + + + + TUNE_ARCH + + + The GNU canonical architecture for a specific architecture + (i.e. arm, + armeb, + mips, + mips64, and so forth). + BitBake uses this value to setup configuration. + + + + TUNE_ARCH definitions are specific to + a given architecture. + The definitions can be a single static definition, or + can be dynamically adjusted. + You can see details for a given CPU family by looking at + the architecture's README file. + For example, the + meta/conf/machine/include/mips/README + file in the + Source Directory + provides information for TUNE_ARCH + specific to the mips architecture. + + + + TUNE_ARCH is tied closely to + TARGET_ARCH, + which defines the target machine's architecture. + The BitBake configuration file + (meta/conf/bitbake.conf) sets + TARGET_ARCH as follows: + + TARGET_ARCH = "${TUNE_ARCH}" + + + + + The following list, which is by no means complete since + architectures are configurable, shows supported machine + architectures: + + arm + i586 + x86_64 + powerpc + powerpc64 + mips + mipsel + + + + + + TUNE_ASARGS + + + Specifies architecture-specific assembler flags for + the target system. + The set of flags is based on the selected tune features. + TUNE_ASARGS is set using + the tune include files, which are typically under + meta/conf/machine/include/ and are + influenced through TUNE_FEATURES. + For example, the + meta/conf/machine/include/x86/arch-x86.inc + file defines the flags for the x86 architecture as follows: + + TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" + + + Board Support Packages (BSPs) can supply their own + set of flags. + + + + + + TUNE_CCARGS + + + Specifies architecture-specific C compiler flags for + the target system. + The set of flags is based on the selected tune features. + TUNE_CCARGS is set using + the tune include files, which are typically under + meta/conf/machine/include/ and are + influenced through TUNE_FEATURES. + + Board Support Packages (BSPs) can supply their own + set of flags. + + + + + + TUNE_LDARGS + + + Specifies architecture-specific linker flags for + the target system. + The set of flags is based on the selected tune features. + TUNE_LDARGS is set using + the tune include files, which are typically under + meta/conf/machine/include/ and are + influenced through TUNE_FEATURES. + For example, the + meta/conf/machine/include/x86/arch-x86.inc + file defines the flags for the x86 architecture as follows: + + TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" + + + Board Support Packages (BSPs) can supply their own + set of flags. + + + + + + TUNE_FEATURES + + + Features used to "tune" a compiler for optimal use + given a specific processor. + The features are defined within the tune files and allow + arguments (i.e. TUNE_*ARGS) to be + dynamically generated based on the features. + + + + The OpenEmbedded build system verifies the features + to be sure they are not conflicting and that they are + supported. + + + + The BitBake configuration file + (meta/conf/bitbake.conf) defines + TUNE_FEATURES as follows: + + TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" + + See the + DEFAULTTUNE + variable for more information. + + + + + TUNE_PKGARCH + + + The package architecture understood by the packaging + system to define the architecture, ABI, and tuning of + output packages. + + + + + TUNE_PKGARCH_tune + + + The CPU or Application Binary Interface (ABI) specific + tuning of the + TUNE_PKGARCH. + + + + These tune-specific package architectures are defined in + the machine include files. + Here is an example of the "core2-32" tuning as used + in the + meta/conf/machine/include/tune-core2.inc + file: + + TUNE_PKGARCH_tune-core2-32 = "core2-32" + + + + + + TUNEABI + + + An underlying Application Binary Interface (ABI) used by + a particular tuning in a given toolchain layer. + Providers that use prebuilt libraries can use the + TUNEABI, + TUNEABI_OVERRIDE, + and + TUNEABI_WHITELIST + variables to check compatibility of tunings against their + selection of libraries. + + + + If TUNEABI is undefined, then every + tuning is allowed. + See the + sanity + class to see how the variable is used. + + + + + TUNEABI_OVERRIDE + + + If set, the OpenEmbedded system ignores the + TUNEABI_WHITELIST + variable. + Providers that use prebuilt libraries can use the + TUNEABI_OVERRIDE, + TUNEABI_WHITELIST, + and + TUNEABI + variables to check compatibility of a tuning against their + selection of libraries. + + + + See the + sanity + class to see how the variable is used. + + + + + TUNEABI_WHITELIST + + + A whitelist of permissible + TUNEABI + values. + If TUNEABI_WHITELIST is not set, + all tunes are allowed. + Providers that use prebuilt libraries can use the + TUNEABI_WHITELIST, + TUNEABI_OVERRIDE, + and TUNEABI variables to check + compatibility of a tuning against their selection of + libraries. + + + + See the + sanity + class to see how the variable is used. + + + + + TUNECONFLICT[feature] + + + Specifies CPU or Application Binary Interface (ABI) + tuning features that conflict with feature. + + + + Known tuning conflicts are specified in the machine include + files in the + Source Directory. + Here is an example from the + meta/conf/machine/include/mips/arch-mips.inc + include file that lists the "o32" and "n64" features as + conflicting with the "n32" feature: + + TUNECONFLICTS[n32] = "o32 n64" + + + + + + TUNEVALID[feature] + + + Specifies a valid CPU or Application Binary Interface (ABI) + tuning feature. + The specified feature is stored as a flag. + Valid features are specified in the machine include files + (e.g. meta/conf/machine/include/arm/arch-arm.inc). + Here is an example from that file: + + TUNEVALID[bigendian] = "Enable big-endian mode." + + See the machine include files in the + Source Directory + for these features. + + + + + + + U + + UBOOT_CONFIG + + + Configures the + UBOOT_MACHINE + and can also define + IMAGE_FSTYPES + for individual cases. + + + + Following is an example from the + meta-fsl-arm layer. + + UBOOT_CONFIG ??= "sd" + UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" + UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" + UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" + UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" + + In this example, "sd" is selected as the configuration + of the possible four for the + UBOOT_MACHINE. + The "sd" configuration defines "mx6qsabreauto_config" + as the value for UBOOT_MACHINE, while + the "sdcard" specifies the + IMAGE_FSTYPES to use for the U-boot + image. + + + + For more information on how the + UBOOT_CONFIG is handled, see the + uboot-config + class. + + + + + UBOOT_ENTRYPOINT + + + Specifies the entry point for the U-Boot image. + During U-Boot image creation, the + UBOOT_ENTRYPOINT variable is passed + as a command-line parameter to the + uboot-mkimage utility. + + + + + UBOOT_LOADADDRESS + + + Specifies the load address for the U-Boot image. + During U-Boot image creation, the + UBOOT_LOADADDRESS variable is passed + as a command-line parameter to the + uboot-mkimage utility. + + + + + UBOOT_LOCALVERSION + + + Appends a string to the name of the local version of the + U-Boot image. + For example, assuming the version of the U-Boot image + built was "2013.10, the full version string reported by + U-Boot would be "2013.10-yocto" given the following + statement: + + UBOOT_LOCALVERSION = "-yocto" + + + + + + UBOOT_MACHINE + + + Specifies the value passed on the + make command line when building + a U-Boot image. + The value indicates the target platform configuration. + You typically set this variable from the machine + configuration file (i.e. + conf/machine/machine_name.conf). + + + + Please see the "Selection of Processor Architecture and + Board Type" section in the U-Boot README for valid values + for this variable. + + + + + UBOOT_MAKE_TARGET + + + Specifies the target called in the + Makefile. + The default target is "all". + + + + + UBOOT_SUFFIX + + + Points to the generated U-Boot extension. + For example, u-boot.sb has a + .sb extension. + + + + The default U-Boot extension is + .bin + + + + + UBOOT_TARGET + + + Specifies the target used for building U-Boot. + The target is passed directly as part of the "make" command + (e.g. SPL and AIS). + If you do not specifically set this variable, the + OpenEmbedded build process passes and uses "all" for the + target during the U-Boot building process. + + + + + USE_VT + + + When using + SysVinit, + determines whether or not to run a + getty + on any virtual terminals in order to enable logging in + through those terminals. + + + + The default value used for USE_VT + is "1" when no default value is specifically set. + Typically, you would set USE_VT + to "0" in the machine configuration file for machines + that do not have a graphical display attached and + therefore do not need virtual terminal functionality. + + + + + USER_CLASSES + + + A list of classes to globally inherit. + These classes are used by the OpenEmbedded build system + to enable extra features (e.g. + buildstats, + image-mklibs, and so forth). + + + + The default list is set in your + local.conf file: + + USER_CLASSES ?= "buildstats image-mklibs image-prelink" + + For more information, see + meta-yocto/conf/local.conf.sample in + the + Source Directory. + + + + + USERADD_ERROR_DYNAMIC + + + Forces the OpenEmbedded build system to produce an error + if the user identification (uid) and + group identification (gid) values + are not defined in files/passwd + and files/group files. + + + + The default behavior for the build system is to dynamically + apply uid and + gid values. + Consequently, the USERADD_ERROR_DYNAMIC + variable is by default not set. + If you plan on using statically assigned + gid and uid + values, you should set + the USERADD_ERROR_DYNAMIC variable in + your local.conf file as + follows: + + USERADD_ERROR_DYNAMIC = "1" + + Overriding the default behavior implies you are going to + also take steps to set static uid and + gid values through use of the + USERADDEXTENSION, + USERADD_UID_TABLES, + and + USERADD_GID_TABLES + variables. + + + + + USERADD_GID_TABLES + + + Specifies a password file to use for obtaining static + group identification (gid) values + when the OpenEmbedded build system adds a group to the + system during package installation. + + + + When applying static group identification + (gid) values, the OpenEmbedded build + system looks in + BBPATH + for a files/group file and then applies + those uid values. + Set the variable as follows in your + local.conf file: + + USERADD_GID_TABLES = "files/group" + + + + + Setting the + USERADDEXTENSION + variable to "useradd-staticids" causes the build system + to use static gid values. + + + + + USERADD_UID_TABLES + + + Specifies a password file to use for obtaining static + user identification (uid) values + when the OpenEmbedded build system adds a user to the + system during package installation. + + + + When applying static user identification + (uid) values, the OpenEmbedded build + system looks in + BBPATH + for a files/passwd file and then applies + those uid values. + Set the variable as follows in your + local.conf file: + + USERADD_UID_TABLES = "files/passwd" + + + + + Setting the + USERADDEXTENSION + variable to "useradd-staticids" causes the build system + to use static uid values. + + + + + USERADD_PACKAGES + + + When inheriting the + useradd + class, this variable + specifies the individual packages within the recipe that + require users and/or groups to be added. + + + + You must set this variable if the recipe inherits the + class. + For example, the following enables adding a user for the + main package in a recipe: + + USERADD_PACKAGES = "${PN}" + + + If follows that if you are going to use the + USERADD_PACKAGES variable, + you need to set one or more of the + USERADD_PARAM, + GROUPADD_PARAM, + or + GROUPMEMS_PARAM + variables. + + + + + + + USERADD_PARAM + + + When inheriting the + useradd + class, this variable + specifies for a package what parameters should be passed + to the useradd command + if you wish to add a user to the system when the package + is installed. + + + + Here is an example from the dbus + recipe: + + USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ + --no-create-home --shell /bin/false \ + --user-group messagebus" + + For information on the standard Linux shell command + useradd, see + . + + + + + USERADDEXTENSION + + + When set to "useradd-staticids", causes the + OpenEmbedded build system to base all user and group + additions on a static + passwd and + group files found in + BBPATH. + + + + To use static user identification (uid) + and group identification (gid) + values, set the variable + as follows in your local.conf file: + + USERADDEXTENSION = "useradd-staticids" + + + Setting this variable to use static + uid and gid + values causes the OpenEmbedded build system to employ + the + useradd-staticids + class. + + + + + If you use static uid and + gid information, you must also + specify the files/passwd and + files/group files by setting the + USERADD_UID_TABLES + and + USERADD_GID_TABLES + variables. + Additionally, you should also set the + USERADD_ERROR_DYNAMIC + variable. + + + + + + + + + + W + + WARN_QA + + + Specifies the quality assurance checks whose failures are + reported as warnings by the OpenEmbedded build system. + You set this variable in your distribution configuration + file. + For a list of the checks you can control with this variable, + see the + "insane.bbclass" + section. + + + + + WORKDIR + + + The pathname of the work directory in which the OpenEmbedded + build system builds a recipe. + This directory is located within the + TMPDIR + directory structure and is specific to the recipe being + built and the system for which it is being built. + + + + The WORKDIR directory is defined as + follows: + + ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + + The actual directory depends on several things: + + TMPDIR: + The top-level build output directory + MULTIMACH_TARGET_SYS: + The target system identifier + PN: + The recipe name + EXTENDPE: + The epoch - (if + PE + is not specified, which is usually the case for most + recipes, then EXTENDPE is blank) + PV: + The recipe version + PR: + The recipe revision + + + + + As an example, assume a Source Directory top-level folder + name poky, a default Build Directory at + poky/build, and a + qemux86-poky-linux machine target + system. + Furthermore, suppose your recipe is named + foo_1.3.0-r0.bb. + In this case, the work directory the build system uses to + build the package would be as follows: + + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + + + + + + + + + + + + + + + + + + + diff --git a/documentation/ref-manual/ref-varlocality.xml b/documentation/ref-manual/ref-varlocality.xml new file mode 100644 index 0000000000..d3f873298d --- /dev/null +++ b/documentation/ref-manual/ref-varlocality.xml @@ -0,0 +1,196 @@ + %poky; ] > + + + Variable Context + + + While you can use most variables in almost any context such as + .conf, .bbclass, + .inc, and .bb files, + some variables are often associated with a particular locality or context. + This chapter describes some common associations. + + +
+ Configuration + + + The following subsections provide lists of variables whose context is + configuration: distribution, machine, and local. + + +
+ Distribution (Distro) + + + This section lists variables whose configuration context is the + distribution, or distro. + + DISTRO + DISTRO_NAME + + DISTRO_VERSION + + MAINTAINER + + PACKAGE_CLASSES + + TARGET_OS + + TARGET_FPU + + TCMODE + + TCLIBC + + + +
+ +
+ Machine + + + This section lists variables whose configuration context is the + machine. + + TARGET_ARCH + + SERIAL_CONSOLES + + PACKAGE_EXTRA_ARCHS + + IMAGE_FSTYPES + + MACHINE_FEATURES + + MACHINE_EXTRA_RDEPENDS + + MACHINE_EXTRA_RRECOMMENDS + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS + + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS + + +
+ +
+ Local + + + This section lists variables whose configuration context is the + local configuration through the local.conf + file. + + DISTRO + + MACHINE + + DL_DIR + + BBFILES + + EXTRA_IMAGE_FEATURES + + PACKAGE_CLASSES + + BB_NUMBER_THREADS + + BBINCLUDELOGS + + + ENABLE_BINARY_LOCALE_GENERATION + + +
+
+ +
+ Recipes + + + The following subsections provide lists of variables whose context is + recipes: required, dependencies, path, and extra build information. + + +
+ Required + + + This section lists variables that are required for recipes. + + LICENSE + + LIC_FILES_CHKSUM + + SRC_URI - used + in recipes that fetch local or remote files. + + + +
+ +
+ Dependencies + + + This section lists variables that define recipe dependencies. + + DEPENDS + + RDEPENDS + + RRECOMMENDS + + RCONFLICTS + + RREPLACES + + + +
+ +
+ Paths + + + This section lists variables that define recipe paths. + + WORKDIR + + S + + FILES + + + +
+ +
+ Extra Build Information + + + This section lists variables that define extra build information for recipes. + + EXTRA_OECMAKE + + EXTRA_OECONF + + EXTRA_OEMAKE + + PACKAGES + + DEFAULT_PREFERENCE + + + +
+
+
+ diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml new file mode 100644 index 0000000000..17b8e97145 --- /dev/null +++ b/documentation/ref-manual/resources.xml @@ -0,0 +1,130 @@ + %poky; ] > + + +Contributing to the Yocto Project + +
+ Introduction + + The Yocto Project team is happy for people to experiment with the Yocto Project. + A number of places exist to find help if you run into difficulties or find bugs. + To find out how to download source code, + see the "Yocto Project Release" + section in the Yocto Project Development Manual. + +
+ +
+ Tracking Bugs + + + If you find problems with the Yocto Project, you should report them using the + Bugzilla application at . + +
+ +
+ Mailing lists + + + A number of mailing lists maintained by the Yocto Project exist + as well as related OpenEmbedded mailing lists for discussion, + patch submission and announcements. + To subscribe to one of the following mailing lists, click on the + appropriate URL in the following list and follow the instructions: + + - + General Yocto Project discussion mailing list. + - + Discussion mailing list about OpenEmbedded-Core (the core metadata). + - + Discussion mailing list about OpenEmbedded. + - + Discussion mailing list about the + BitBake + build tool. + - + Discussion mailing list about + Poky. + + - + Mailing list to receive official Yocto Project release and milestone + announcements. + + + For more Yocto Project-related mailing lists, see the Yocto Project community mailing lists page + here. +
+ +
+ Internet Relay Chat (IRC) + + + Two IRC channels on freenode are available for the Yocto Project and Poky discussions: + + #yocto + #poky + + +
+ + + +
+ Contributions + + + The Yocto Project gladly accepts contributions. + You can submit changes to the project either by creating and sending + pull requests, + or by submitting patches through email. + For information on how to do both as well as information on how + to identify the maintainer for each area of code, see the + "How to Submit a Change" + section in the Yocto Project Development Manual. + +
+ +
+ diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml new file mode 100644 index 0000000000..2df36521c2 --- /dev/null +++ b/documentation/ref-manual/technical-details.xml @@ -0,0 +1,1421 @@ + %poky; ] > + + +Technical Details + + + This chapter provides technical details for various parts of the + Yocto Project. + Currently, topics include Yocto Project components, + cross-toolchain generation, shared state (sstate) cache, + x32, Wayland support, and Licenses. + + +
+ Yocto Project Components + + + The + BitBake + task executor together with various types of configuration files form + the OpenEmbedded Core. + This section overviews these components by describing their use and + how they interact. + + + + BitBake handles the parsing and execution of the data files. + The data itself is of various types: + + Recipes: Provides details + about particular pieces of software. + + Class Data: Abstracts + common build information (e.g. how to build a Linux kernel). + + Configuration Data: Defines + machine-specific settings, policy decisions, and so forth. + Configuration data acts as the glue to bind everything + together. + + + + + + BitBake knows how to combine multiple data sources together and refers + to each data source as a layer. + For information on layers, see the + "Understanding and + Creating Layers" section of the Yocto Project Development Manual. + + + + Following are some brief details on these core components. + For additional information on how these components interact during + a build, see the + "A Closer Look at the Yocto Project Development Environment" + Chapter. + + +
+ BitBake + + + BitBake is the tool at the heart of the OpenEmbedded build system + and is responsible for parsing the + Metadata, + generating a list of tasks from it, and then executing those tasks. + + + + This section briefly introduces BitBake. + If you want more information on BitBake, see the + BitBake User Manual. + + + + To see a list of the options BitBake supports, use either of + the following commands: + + $ bitbake -h + $ bitbake --help + + + + + The most common usage for BitBake is bitbake packagename, where + packagename is the name of the package you want to build + (referred to as the "target" in this manual). + The target often equates to the first part of a recipe's filename + (e.g. "foo" for a recipe named + foo_1.3.0-r0.bb). + So, to process the matchbox-desktop_1.2.3.bb recipe file, you + might type the following: + + $ bitbake matchbox-desktop + + Several different versions of matchbox-desktop might exist. + BitBake chooses the one selected by the distribution configuration. + You can get more details about how BitBake chooses between different + target versions and providers in the + "Preferences" + section of the BitBake User Manual. + + + + BitBake also tries to execute any dependent tasks first. + So for example, before building matchbox-desktop, BitBake + would build a cross compiler and glibc if they had not already + been built. + + + + A useful BitBake option to consider is the -k or + --continue option. + This option instructs BitBake to try and continue processing the job + as long as possible even after encountering an error. + When an error occurs, the target that + failed and those that depend on it cannot be remade. + However, when you use this option other dependencies can still be + processed. + +
+ +
+ Metadata (Recipes) + + + Files that have the .bb suffix are "recipes" + files. + In general, a recipe contains information about a single piece of + software. + This information includes the location from which to download the + unaltered source, any source patches to be applied to that source + (if needed), which special configuration options to apply, + how to compile the source files, and how to package the compiled + output. + + + + The term "package" is sometimes used to refer to recipes. However, + since the word "package" is used for the packaged output from the OpenEmbedded + build system (i.e. .ipk or .deb files), + this document avoids using the term "package" when referring to recipes. + +
+ +
+ Classes + + + Class files (.bbclass) contain information that + is useful to share between + Metadata files. + An example is the + autotools + class, which contains common settings for any application that + Autotools uses. + The "Classes" chapter provides + details about classes and how to use them. + +
+ +
+ Configuration + + + The configuration files (.conf) define various configuration variables + that govern the OpenEmbedded build process. + These files fall into several areas that define machine configuration options, + distribution configuration options, compiler tuning options, general common configuration + options, and user configuration options in local.conf, which is found + in the + Build Directory. + +
+
+ +
+ Cross-Development Toolchain Generation + + + The Yocto Project does most of the work for you when it comes to + creating + cross-development toolchains. + 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 + Yocto Project Application Developer's Guide. + + + + In the Yocto Project development environment, cross-development + toolchains are used to build the image and applications that run on the + target hardware. + With just a few commands, the OpenEmbedded build system creates + these necessary toolchains for you. + + + + The following figure shows a high-level build environment regarding + toolchain construction and use. + + + + + + + + Most of the work occurs on the Build Host. + This is the machine used to build images and generally work within the + the Yocto Project environment. + When you run BitBake to create an image, the OpenEmbedded build system + uses the host gcc compiler to bootstrap a + cross-compiler named gcc-cross. + The gcc-cross compiler is what BitBake uses to + compile source files when creating the target image. + You can think of gcc-cross simply as an + automatically generated cross-compiler that is used internally within + BitBake only. + + + + The chain of events that occurs when gcc-cross is + bootstrapped is as follows: + + gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime + + + gcc: + The build host's GNU Compiler Collection (GCC). + + binutils-cross: + The bare minimum binary utilities needed in order to run + the gcc-cross-initial phase of the + bootstrap operation. + + gcc-cross-initial: + An early stage of the bootstrap process for creating + the cross-compiler. + This stage builds enough of the gcc-cross, + the C library, and other pieces needed to finish building the + final cross-compiler in later stages. + This tool is a "native" package (i.e. it is designed to run on + the build host). + + linux-libc-headers: + Headers needed for the cross-compiler. + + glibc-initial: + An initial version of the Embedded GLIBC needed to bootstrap + glibc. + + gcc-cross: + The final stage of the bootstrap process for the + cross-compiler. + This stage results in the actual cross-compiler that + BitBake uses when it builds an image for a targeted + device. + + If you are replacing this cross compiler toolchain + with a custom version, you must replace + gcc-cross. + + This tool is also a "native" package (i.e. it is + designed to run on the build host). + + gcc-runtime: + Runtime libraries resulting from the toolchain bootstrapping + process. + This tool produces a binary that consists of the + runtime libraries need for the targeted device. + + + + + + You can use the OpenEmbedded build system to build an installer for + the relocatable SDK used to develop applications. + When you run the installer, it installs the toolchain, which contains + the development tools (e.g., the + gcc-cross-canadian), + binutils-cross-canadian, and other + nativesdk-* tools 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 + SDKMACHINE, + which might or might not be the same + machine as the Build Host. + + If your target architecture is supported by the Yocto Project, + you can take advantage of pre-built images that ship with the + Yocto Project and already contain cross-development toolchain + installers. + + + + + Here is the bootstrap process for the relocatable toolchain: + + gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> + glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian + + + gcc: + The build host's GNU Compiler Collection (GCC). + + binutils-crosssdk: + The bare minimum binary utilities needed in order to run + the gcc-crosssdk-initial phase of the + bootstrap operation. + + gcc-crosssdk-initial: + An early stage of the bootstrap process for creating + the cross-compiler. + This stage builds enough of the + gcc-crosssdk and supporting pieces so that + the final stage of the bootstrap process can produce the + finished cross-compiler. + This tool is a "native" binary that runs on the build host. + + linux-libc-headers: + Headers needed for the cross-compiler. + + glibc-initial: + An initial version of the Embedded GLIBC needed to bootstrap + nativesdk-glibc. + + nativesdk-glibc: + The Embedded GLIBC needed to bootstrap the + gcc-crosssdk. + + gcc-crosssdk: + The final stage of the bootstrap process for the + relocatable cross-compiler. + The gcc-crosssdk is a transitory compiler + and never leaves the build host. + Its purpose is to help in the bootstrap process to create the + eventual relocatable gcc-cross-canadian + compiler, which is relocatable. + This tool is also a "native" package (i.e. it is + designed to run on the build host). + + gcc-cross-canadian: + The final relocatable cross-compiler. + When run on the + SDKMACHINE, + this tool + produces executable code that runs on the target device. + Only one cross-canadian compiler is produced per architecture + since they can be targeted at different processor optimizations + using configurations passed to the compiler through the + compile commands. + This circumvents the need for multiple compilers and thus + reduces the size of the toolchains. + + + + + + For information on advantages gained when building a + cross-development toolchain installer, see the + "Optionally Building a Toolchain Installer" + section in the Yocto Project Application Developer's Guide. + +
+ +
+ Shared State Cache + + + By design, the OpenEmbedded build system builds everything from scratch unless + BitBake can determine that parts do not need to be rebuilt. + Fundamentally, building from scratch is attractive as it means all parts are + built fresh and there is no possibility of stale data causing problems. + When developers hit problems, they typically default back to building from scratch + so they know the state of things from the start. + + + + Building an image from scratch is both an advantage and a disadvantage to the process. + As mentioned in the previous paragraph, building from scratch ensures that + everything is current and starts from a known state. + However, building from scratch also takes much longer as it generally means + rebuilding things that do not necessarily need to be rebuilt. + + + + The Yocto Project implements shared state code that supports incremental builds. + The implementation of the shared state code answers the following questions that + were fundamental roadblocks within the OpenEmbedded incremental build support system: + + What pieces of the system have changed and what pieces have + not changed? + How are changed pieces of software removed and replaced? + How are pre-built components that do not need to be rebuilt from scratch + used when they are available? + + + + + For the first question, the build system detects changes in the "inputs" to a given task by + creating a checksum (or signature) of the task's inputs. + If the checksum changes, the system assumes the inputs have changed and the task needs to be + rerun. + For the second question, the shared state (sstate) code tracks which tasks add which output + to the build process. + This means the output from a given task can be removed, upgraded or otherwise manipulated. + The third question is partly addressed by the solution for the second question + assuming the build system can fetch the sstate objects from remote locations and + install them if they are deemed to be valid. + + + + The OpenEmbedded build system does not maintain + PR information + as part of the shared state packages. + Consequently, considerations exist that affect maintaining shared + state feeds. + For information on how the OpenEmbedded build system + works with packages and can + track incrementing PR information, see the + "Incrementing a Package Revision Number" + section. + + + + The rest of this section goes into detail about the overall incremental build + architecture, the checksums (signatures), shared state, and some tips and tricks. + + +
+ Overall Architecture + + + When determining what parts of the system need to be built, BitBake + works on a per-task basis rather than a per-recipe basis. + You might wonder why using a per-task basis is preferred over a per-recipe basis. + To help explain, consider having the IPK packaging backend enabled and then switching to DEB. + In this case, the + do_install + and + do_package + task outputs are still valid. + However, with a per-recipe approach, the build would not include the + .deb files. + Consequently, you would have to invalidate the whole build and rerun it. + Rerunning everything is not the best solution. + Also, in this case, the core must be "taught" much about specific tasks. + This methodology does not scale well and does not allow users to easily add new tasks + in layers or as external recipes without touching the packaged-staging core. + +
+ +
+ Checksums (Signatures) + + + The shared state code uses a checksum, which is a unique signature of a task's + inputs, to determine if a task needs to be run again. + Because it is a change in a task's inputs that triggers a rerun, the process + needs to detect all the inputs to a given task. + For shell tasks, this turns out to be fairly easy because + the build process generates a "run" shell script for each task and + it is possible to create a checksum that gives you a good idea of when + the task's data changes. + + + + 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 WORKDIR. + 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 WORKDIR. + The simplistic approach for excluding the work directory is to set + WORKDIR to some fixed value and create the checksum + for the "run" script. + + + + Another problem results from the "run" scripts containing functions that + might or might not get called. + The incremental build solution contains code that figures out dependencies + between shell functions. + This code is used to prune the "run" scripts down to the minimum set, + thereby alleviating this problem and making the "run" scripts much more + readable as a bonus. + + + + So far we have solutions for shell scripts. + What about Python tasks? + The same approach applies even though these tasks are more difficult. + The process needs to figure out what variables a Python function accesses + and what functions it calls. + Again, the incremental build solution contains code that first figures out + the variable and function dependencies, and then creates a checksum for the data + used as the input to the task. + + + + Like the WORKDIR case, situations exist where dependencies + should be ignored. + For these cases, you can instruct the build process to ignore a dependency + by using a line like the following: + + PACKAGE_ARCHS[vardepsexclude] = "MACHINE" + + This example ensures that the + PACKAGE_ARCHS + variable does not + depend on the value of + MACHINE, + even if it does reference it. + + + + Equally, there are cases where we need to add dependencies BitBake is not able to find. + You can accomplish this by using a line like the following: + + PACKAGE_ARCHS[vardeps] = "MACHINE" + + This example explicitly adds the MACHINE variable as a + dependency for PACKAGE_ARCHS. + + + + Consider a case with in-line Python, for example, where BitBake is not + able to figure out dependencies. + When running in debug mode (i.e. using -DDD), BitBake + produces output when it discovers something for which it cannot figure out + dependencies. + The Yocto Project team has currently not managed to cover those dependencies + in detail and is aware of the need to fix this situation. + + + + Thus far, this section has limited discussion to the direct inputs into a task. + Information based on direct inputs is referred to as the "basehash" in the + code. + However, there is still the question of a task's indirect inputs - the + things that were already built and present in the + Build Directory. + The checksum (or signature) for a particular task needs to add the hashes + of all the tasks on which the particular task depends. + Choosing which dependencies to add is a policy decision. + However, the effect is to generate a master checksum that combines the basehash + and the hashes of the task's dependencies. + + + + At the code level, there are a variety of ways both the basehash and the + dependent task hashes can be influenced. + Within the BitBake configuration file, we can give BitBake some extra information + to help it construct the basehash. + The following statement effectively results in a list of global variable + dependency excludes - variables never included in any checksum: + + BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ + SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ + USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ + PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ + CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" + + The previous example excludes + WORKDIR + since that variable is actually constructed as a path within + TMPDIR, which is on + the whitelist. + + + + The rules for deciding which hashes of dependent tasks to include through + dependency chains are more complex and are generally accomplished with a + Python function. + The code in meta/lib/oe/sstatesig.py shows two examples + of this and also illustrates how you can insert your own policy into the system + if so desired. + This file defines the two basic signature generators OE-Core + uses: "OEBasic" and "OEBasicHash". + By default, there is a dummy "noop" signature handler enabled in BitBake. + This means that behavior is unchanged from previous versions. + OE-Core uses the "OEBasicHash" signature handler by default + through this setting in the bitbake.conf file: + + BB_SIGNATURE_HANDLER ?= "OEBasicHash" + + The "OEBasicHash" BB_SIGNATURE_HANDLER is the same as the + "OEBasic" version but adds the task hash to the stamp files. + This results in any + Metadata + change that changes the task hash, automatically + causing the task to be run again. + This removes the need to bump PR + values, and changes to Metadata automatically ripple across the build. + + + + It is also worth noting that the end result of these signature generators is to + make some dependency and hash information available to the build. + This information includes: + + BB_BASEHASH_task-taskname: + The base hashes for each task in the recipe. + + BB_BASEHASH_filename:taskname: + The base hashes for each dependent task. + + BBHASHDEPS_filename:taskname: + The task dependencies for each task. + + BB_TASKHASH: + The hash of the currently running task. + + + +
+ +
+ Shared State + + + Checksums and dependencies, as discussed in the previous section, solve half the + problem of supporting a shared state. + The other part of the problem is being able to use checksum information during the build + and being able to reuse or rebuild specific components. + + + + The + sstate + class is a relatively generic implementation of how to "capture" + a snapshot of a given task. + The idea is that the build process does not care about the source of a task's output. + Output could be freshly built or it could be downloaded and unpacked from + somewhere - the build process does not need to worry about its origin. + + + + There are two types of output, one is just about creating a directory + in WORKDIR. + A good example is the output of either + do_install + or + do_package. + The other type of output occurs when a set of data is merged into a shared directory + tree such as the sysroot. + + + + The Yocto Project team has tried to keep the details of the + implementation hidden in sstate class. + From a user's perspective, adding shared state wrapping to a task + is as simple as this + do_deploy + example taken from the + deploy + class: + + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-name] = "deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + do_deploy[dirs] = "${DEPLOYDIR} ${B}" + + In this example, we add some extra flags to the task, a name field ("deploy"), an + input directory where the task sends data, and the output + directory where the data from the task should eventually be copied. + We also add a _setscene variant of the task and add the task + name to the SSTATETASKS list. + + + + If you have a directory whose contents you need to preserve, you can do this with + a line like the following: + + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + + This method, as well as the following example, also works for multiple directories. + + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + do_package[sstate-lockfile] = "${PACKAGELOCK}" + + These methods also include the ability to take a lockfile when manipulating + shared state directory structures since some cases are sensitive to file + additions or removals. + + + + Behind the scenes, the shared state code works by looking in + SSTATE_DIR and + SSTATE_MIRRORS + for shared state files. + Here is an example: + + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + + + The shared state directory (SSTATE_DIR) is + organized into two-character subdirectories, where the subdirectory + names are based on the first two characters of the hash. + If the shared state directory structure for a mirror has the + same structure as SSTATE_DIR, you must + specify "PATH" as part of the URI to enable the build system + to map to the appropriate subdirectory. + + + + + The shared state package validity can be detected just by looking at the + filename since the filename contains the task checksum (or signature) as + described earlier in this section. + If a valid shared state package is found, the build process downloads it + and uses it to accelerate the task. + + + + The build processes use the *_setscene tasks + for the task acceleration phase. + BitBake goes through this phase before the main execution code and tries + to accelerate any tasks for which it can find shared state packages. + If a shared state package for a task is available, the shared state + package is used. + This means the task and any tasks on which it is dependent are not + executed. + + + + As a real world example, the aim is when building an IPK-based image, + only the + do_package_write_ipk + tasks would have their + shared state packages fetched and extracted. + Since the sysroot is not used, it would never get extracted. + This is another reason why a task-based approach is preferred over a + recipe-based approach, which would have to install the output from every task. + +
+ +
+ Tips and Tricks + + + The code in the build system that supports incremental builds is not + simple code. + This section presents some tips and tricks that help you work around + issues related to shared state code. + + +
+ Debugging + + + When things go wrong, debugging needs to be straightforward. + Because of this, the Yocto Project includes strong debugging + tools: + + Whenever a shared state package is written out, so is a + corresponding .siginfo 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. + If you run BitBake with the --dump-signatures + (or -S) option, BitBake dumps out + .siginfo files in + the stamp directory for every task it would have executed instead of + building the specified target package. + There is a bitbake-diffsigs command that + can process .siginfo 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?" + + +
+ +
+ Invalidating Shared State + + + The OpenEmbedded build system uses checksums and shared state + cache to avoid unnecessarily rebuilding tasks. + Collectively, this scheme is known as "shared state code." + + + + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes to your + code that the checksum calculations do not take into + account. + These implicit changes affect a task's output but do not trigger + the shared state code into rebuilding a recipe. + Consider an example during which a tool changes its output. + Assume that the output of rpmdeps changes. + The result of the change should be that all the + package and + package_write_rpm shared state cache + items become invalid. + However, because the change to the output is + external to the code and therefore implicit, + the associated shared state cache items do not become + invalidated. + In this case, the build process uses the cached items rather + than running the task again. + Obviously, these types of implicit changes can cause problems. + + + + To avoid these problems during the build, you need to + understand the effects of any changes you make. + Realize that changes you make directly to a function + are automatically factored into the checksum calculation. + Thus, these explicit changes invalidate the associated area of + shared state cache. + However, you need to be aware of any implicit changes that + are not obvious changes to the code and could affect the output + of a given task. + + + + When you identify an implicit change, you can easily take steps + to invalidate the cache and force the tasks to run. + The steps you can take are as simple as changing a function's + comments in the source code. + For example, to invalidate package shared state files, change + the comment statements of + do_package + or the comments of one of the functions it calls. + Even though the change is purely cosmetic, it causes the + checksum to be recalculated and forces the OpenEmbedded build + system to run the task again. + + + + For an example of a commit that makes a cosmetic change to + invalidate shared state, see this + commit. + +
+
+
+ +
+ x32 + + + x32 is a processor-specific Application Binary Interface (psABI) for x86_64. + An ABI defines the calling conventions between functions in a processing environment. + The interface determines what registers are used and what the sizes are for various C data types. + + + + Some processing environments prefer using 32-bit applications even when running + on Intel 64-bit platforms. + Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms. + The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources, + leaving the system underutilized. + Now consider the x86_64 psABI. + This ABI is newer and uses 64-bits for data sizes and program pointers. + The extra bits increase the footprint size of the programs, libraries, + and also increases the memory and file system size requirements. + Executing under the x32 psABI enables user programs to utilize CPU and system resources + more efficiently while keeping the memory footprint of the applications low. + Extra bits are used for registers but not for addressing mechanisms. + + +
+ Support + + + This Yocto Project release supports the final specifications of x32 + psABI. + Support for x32 psABI exists as follows: + + You can create packages and images in x32 psABI format on x86_64 architecture targets. + + You can successfully build many recipes with the x32 toolchain. + You can create and boot core-image-minimal and + core-image-sato images. + + +
+ +
+ Completing x32 + + + Future Plans for the x32 psABI in the Yocto Project include the following: + + Enhance and fix the few remaining recipes so they + work with and support x32 toolchains. + Enhance RPM Package Manager (RPM) support for x32 binaries. + Support larger images. + + +
+ +
+ Using x32 Right Now + + + Follow these steps to use the x32 spABI: + + Enable the x32 psABI tuning file for x86_64 + machines by editing the conf/local.conf like this: + + MACHINE = "qemux86-64" + DEFAULTTUNE = "x86-64-x32" + baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \ + or 'INVALID'), True) or 'lib'}" + #MACHINE = "genericx86" + #DEFAULTTUNE = "core2-64-x32" + + As usual, use BitBake to build an image that supports the x32 psABI. + Here is an example: + + $ bitbake core-image-sato + + As usual, run your image using QEMU: + + $ runqemu qemux86-64 core-image-sato + + + +
+
+ +
+ Wayland + + + Wayland + is a computer display server protocol that + provides a method for compositing window managers to communicate + directly with applications and video hardware and expects them to + communicate with input hardware using other libraries. + Using Wayland with supporting targets can result in better control + over graphics frame rendering than an application might otherwise + achieve. + + + + The Yocto Project provides the Wayland protocol libraries and the + reference + Weston + compositor as part of its release. + This section describes what you need to do to implement Wayland and + use the compositor when building an image for a supporting target. + + +
+ Support + + + The Wayland protocol libraries and the reference Weston compositor + ship as integrated packages in the meta layer + of the + Source Directory. + Specifically, you can find the recipes that build both Wayland + and Weston at meta/recipes-graphics/wayland. + + + + You can build both the Wayland and Weston packages for use only + with targets that accept the + Mesa 3D and Direct Rendering Infrastructure, + which is also known as Mesa DRI. + This implies that you cannot build and use the packages if your + target uses, for example, the + Intel Embedded Media and + Graphics Driver (Intel + EMGD) that overrides Mesa DRI. + + + + Due to lack of EGL support, Weston 1.0.3 will not run directly on + the emulated QEMU hardware. + However, this version of Weston will run under X emulation without + issues. + +
+ +
+ Enabling Wayland in an Image + + + To enable Wayland, you need to enable it to be built and enable + it to be included in the image. + + +
+ Building + + + To cause Mesa to build the wayland-egl + platform and Weston to build Wayland with Kernel Mode + Setting + (KMS) + support, include the "wayland" flag in the + DISTRO_FEATURES + statement in your local.conf file: + + DISTRO_FEATURES_append = " wayland" + + + + + If X11 has been enabled elsewhere, Weston will build Wayland + with X11 support + +
+ +
+ Installing + + + To install the Wayland feature into an image, you must + include the following + CORE_IMAGE_EXTRA_INSTALL + statement in your local.conf file: + + CORE_IMAGE_EXTRA_INSTALL += "wayland weston" + + +
+
+ +
+ Running Weston + + + To run Weston inside X11, enabling it as described earlier and + building a Sato image is sufficient. + If you are running your image under Sato, a Weston Launcher appears + in the "Utility" category. + + + + Alternatively, you can run Weston through the command-line + interpretor (CLI), which is better suited for development work. + To run Weston under the CLI, you need to do the following after + your image is built: + + Run these commands to export + XDG_RUNTIME_DIR: + + mkdir -p /tmp/$USER-weston + chmod 0700 /tmp/$USER-weston + export XDG_RUNTIME_DIR=/tmp/$USER-weston + + Launch Weston in the shell: + + weston + + + +
+
+ +
+ Licenses + + + This section describes the mechanism by which the OpenEmbedded build system + tracks changes to licensing text. + The section also describes how to enable commercially licensed recipes, + which by default are disabled. + + + + For information that can help you maintain compliance with various open + source licensing during the lifecycle of the product, see the + "Maintaining Open Source License Compliance During Your Project's Lifecycle" section + in the Yocto Project Development Manual. + + +
+ Tracking License Changes + + + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + LIC_FILES_CHKSUM + variable tracks changes to the license text. The checksums are validated at the end of the + configure step, and if the checksums do not match, the build will fail. + + +
+ Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable + + + The LIC_FILES_CHKSUM + variable contains checksums of the license text in the source code for the recipe. + Following is an example of how to specify LIC_FILES_CHKSUM: + + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + + + + + The build system uses the + S variable as + the default directory when searching files listed in + LIC_FILES_CHKSUM. + The previous example employs the default directory. + + + + Consider this next example: + + LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + + + + + The first line locates a file in + ${S}/src/ls.c. + The second line refers to a file in + WORKDIR. + + + Note that LIC_FILES_CHKSUM variable is + mandatory for all recipes, unless the + LICENSE variable is set to "CLOSED". + +
+ +
+ Explanation of Syntax + + As mentioned in the previous section, the + LIC_FILES_CHKSUM variable lists all the + important files that contain the license text for the source code. + It is possible to specify a checksum for an entire file, or a specific section of a + file (specified by beginning and ending line numbers with the "beginline" and "endline" + parameters, respectively). + The latter is useful for source files with a license notice header, + README documents, and so forth. + If you do not use the "beginline" parameter, then it is assumed that the text begins on the + first line of the file. + Similarly, if you do not use the "endline" parameter, it is assumed that the license text + ends with the last line of the file. + + + + The "md5" parameter stores the md5 checksum of the license text. + If the license text changes in any way as compared to this parameter + then a mismatch occurs. + This mismatch triggers a build failure and notifies the developer. + Notification allows the developer to review and address the license text changes. + Also note that if a mismatch occurs during the build, the correct md5 + checksum is placed in the build log and can be easily copied to the recipe. + + + + There is no limit to how many files you can specify using the + LIC_FILES_CHKSUM variable. + Generally, however, every project requires a few specifications for license tracking. + Many projects have a "COPYING" file that stores the license information for all the source + code files. + This practice allows you to just track the "COPYING" file as long as it is kept up to date. + + + + If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match + error and displays the correct "md5" parameter value during the build. + The correct parameter is also captured in the build log. + + + + If the whole file contains only license text, you do not need to use the "beginline" and + "endline" parameters. + +
+
+ +
+ Enabling Commercially Licensed Recipes + + + By default, the OpenEmbedded build system disables + components that have commercial or other special licensing + requirements. + Such requirements are defined on a + recipe-by-recipe basis through the + LICENSE_FLAGS + variable definition in the affected recipe. + For instance, the + poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + recipe contains the following statement: + + LICENSE_FLAGS = "commercial" + + Here is a slightly more complicated example that contains both an + explicit recipe name and version (after variable expansion): + + LICENSE_FLAGS = "license_${PN}_${PV}" + + In order for a component restricted by a LICENSE_FLAGS + definition to be enabled and included in an image, it + needs to have a matching entry in the global + LICENSE_FLAGS_WHITELIST + variable, which is a variable + typically defined in your local.conf file. + For example, to enable + the poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to LICENSE_FLAGS_WHITELIST. + See the + "License Flag Matching" section + for a full explanation of how LICENSE_FLAGS matching works. + Here is the example: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + + Likewise, to additionally enable the package built from the recipe containing + LICENSE_FLAGS = "license_${PN}_${PV}", and assuming + that the actual recipe name was emgd_1.10.bb, + the following string would enable that package as well as + the original gst-plugins-ugly package: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + + As a convenience, you do not need to specify the complete license string + in the whitelist for every package. + You can use an abbreviated form, which consists + of just the first portion or portions of the license string before + the initial underscore character or characters. + A partial string will match + any license that contains the given string as the first + portion of its license. + For example, the following + whitelist string will also match both of the packages + previously mentioned as well as any other packages that have + licenses starting with "commercial" or "license". + + LICENSE_FLAGS_WHITELIST = "commercial license" + + + +
+ License Flag Matching + + + License flag matching allows you to control what recipes the + OpenEmbedded build system includes in the build. + Fundamentally, the build system attempts to match + LICENSE_FLAGS + strings found in recipes against + LICENSE_FLAGS_WHITELIST + strings found in the whitelist. + A match causes the build system to include a recipe in the + build, while failure to find a match causes the build system to + exclude a recipe. + + + + In general, license flag matching is simple. + However, understanding some concepts will help you + correctly and effectively use matching. + + + + Before a flag + defined by a particular recipe is tested against the + contents of the whitelist, the expanded string + _${PN} is appended to the flag. + This expansion makes each LICENSE_FLAGS + value recipe-specific. + After expansion, the string is then matched against the + whitelist. + Thus, specifying + LICENSE_FLAGS = "commercial" + in recipe "foo", for example, results in the string + "commercial_foo". + And, to create a match, that string must appear in the + whitelist. + + + + Judicious use of the LICENSE_FLAGS + strings and the contents of the + LICENSE_FLAGS_WHITELIST variable + allows you a lot of flexibility for including or excluding + recipes based on licensing. + For example, you can broaden the matching capabilities by + using license flags string subsets in the whitelist. + When using a string subset, be sure to use the part of + the expanded string that precedes the appended underscore + character (e.g. usethispart_1.3, + usethispart_1.4, and so forth). + + For example, simply specifying the string "commercial" in + the whitelist matches any expanded + LICENSE_FLAGS definition that starts with + the string "commercial" such as "commercial_foo" and + "commercial_bar", which are the strings the build system + automatically generates for hypothetical recipes named + "foo" and "bar" assuming those recipes simply specify the + following: + + LICENSE_FLAGS = "commercial" + + Thus, you can choose to exhaustively + enumerate each license flag in the whitelist and + allow only specific recipes into the image, or + you can use a string subset that causes a broader range of + matches to allow a range of recipes into the image. + + + + This scheme works even if the + LICENSE_FLAGS string already + has _${PN} appended. + For example, the build system turns the license flag + "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would + match both the general "commercial" and the specific + "commercial_1.2_foo" strings found in the whitelist, as + expected. + + + + Here are some other scenarios: + + You can specify a versioned string in the + recipe such as "commercial_foo_1.2" in a "foo" recipe. + The build system expands this string to + "commercial_foo_1.2_foo". + Combine this license flag with a whitelist that has + the string "commercial" and you match the flag along + with any other flag that starts with the string + "commercial". + Under the same circumstances, you can + use "commercial_foo" in the whitelist and the + build system not only matches "commercial_foo_1.2" but + also matches any license flag with the string + "commercial_foo", regardless of the version. + + You can be very specific and use both the + package and version parts in the whitelist (e.g. + "commercial_foo_1.2") to specifically match a + versioned recipe. + + +
+ + +
+
+
+ diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml new file mode 100644 index 0000000000..2116852163 --- /dev/null +++ b/documentation/ref-manual/usingpoky.xml @@ -0,0 +1,915 @@ + %poky; ] > + + +Using the Yocto Project + + + This chapter describes common usage for the Yocto Project. + The information is introductory in nature as other manuals in the Yocto Project + documentation set provide more details on how to use the Yocto Project. + + +
+ Running a Build + + + This section provides a summary of the build process and provides information + for less obvious aspects of the build process. + For general information on how to build an image using the OpenEmbedded build + system, see the + "Building an Image" + section of the Yocto Project Quick Start. + + +
+ Build Overview + + + The first thing you need to do is set up the OpenEmbedded build + environment by sourcing an environment setup script + (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + Here is an example: + + $ source &OE_INIT_FILE; [build_dir] + + + + + The build_dir argument is optional and specifies the directory the + OpenEmbedded build system uses for the build - + the Build Directory. + If you do not specify a Build Directory, it defaults to a directory + named build in your current working directory. + A common practice is to use a different Build Directory for different targets. + For example, ~/build/x86 for a qemux86 + target, and ~/build/arm for a qemuarm target. + + + + Once the build environment is set up, you can build a target using: + + $ bitbake target + + + + + The target is the name of the recipe you want to build. + Common targets are the images in meta/recipes-core/images, + meta/recipes-sato/images, etc. all found in the + Source Directory. + Or, the target can be the name of a recipe for a specific piece of software such as + BusyBox. + For more details about the images the OpenEmbedded build system supports, see the + "Images" chapter. + + + + Building an image without GNU General Public License Version + 3 (GPLv3), or similarly licensed, components is supported for + only minimal and base images. + See the "Images" chapter for more information. + +
+ +
+ Building an Image Using GPL Components + + + When building an image using GPL components, you need to maintain your original + settings and not switch back and forth applying different versions of the GNU + General Public License. + If you rebuild using different versions of GPL, dependency errors might occur + due to some components not being rebuilt. + +
+
+ +
+ Installing and Using the Result + + + Once an image has been built, it often needs to be installed. + The images and kernels built by the OpenEmbedded build system are placed in the + Build Directory in + tmp/deploy/images. + For information on how to run pre-built images such as qemux86 + and qemuarm, see the + "Using Pre-Built Binaries and QEMU" + section in the Yocto Project Quick Start. + For information about how to install these images, see the documentation for your + particular board or machine. + +
+ +
+ Debugging Build Failures + + + The exact method for debugging build failures depends on the nature of + the problem and on the system's area from which the bug originates. + Standard debugging practices such as comparison against the last + known working version with examination of the changes and the + re-application of steps to identify the one causing the problem are + valid for the Yocto Project just as they are for any other system. + Even though it is impossible to detail every possible potential failure, + this section provides some general tips to aid in debugging. + + + + A useful feature for debugging is the error reporting tool. + Configuring the Yocto Project to use this tool causes the + OpenEmbedded build system to produce error reporting commands as + part of the console output. + You can enter the commands after the build completes + to log error information + into a common database, that can help you figure out what might be + going wrong. + For information on how to enable and use this feature, see the + "Using the Error Reporting Tool" + section in the Yocto Project Development Manual. + + + + For discussions on debugging, see the + "Debugging With the GNU Project Debugger (GDB) Remotely" + and + "Working within Eclipse" + sections in the Yocto Project Development Manual. + + + + The remainder of this section presents many examples of the + bitbake command. + You can learn about BitBake by reading the + BitBake User Manual. + + + +
+ Task Failures + + The log file for shell tasks is available in + ${WORKDIR}/temp/log.do_taskname.pid. + For example, the do_compile task for the QEMU minimal image for the x86 + machine (qemux86) might be + tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830. + To see what + BitBake + runs to generate that log, look at the corresponding + run.do_taskname.pid file located in the same directory. + + + + Presently, the output from Python tasks is sent directly to the console. + +
+ +
+ Running Specific Tasks + + + Any given package consists of a set of tasks. + The standard BitBake behavior in most cases is: + do_fetch, + do_unpack, + do_patch, do_configure, + do_compile, do_install, + do_package, + do_package_write_*, and + do_build. + The default task is do_build and any tasks + on which it depends build first. + Some tasks, such as do_devshell, are not part + of the default build chain. + If you wish to run a task that is not part of the default build + chain, you can use the -c option in BitBake. + Here is an example: + + $ bitbake matchbox-desktop -c devshell + + + + + If you wish to rerun a task, use the -f force + option. + For example, the following sequence forces recompilation after + changing files in the work directory. + + $ bitbake matchbox-desktop + . + . + make some changes to the source code in the work directory + . + . + $ bitbake matchbox-desktop -c compile -f + $ bitbake matchbox-desktop + + + + + This sequence first builds and then recompiles + matchbox-desktop. + The last command reruns all tasks (basically the packaging tasks) + after the compile. + BitBake recognizes that the do_compile + task was rerun and therefore understands that the other tasks + also need to be run again. + + + + You can view a list of tasks in a given package by running the + do_listtasks task as follows: + + $ bitbake matchbox-desktop -c listtasks + + The results appear as output to the console and are also in the + file ${WORKDIR}/temp/log.do_listtasks. + +
+ +
+ Dependency Graphs + + + Sometimes it can be hard to see why BitBake wants to build + other packages before building a given package you have specified. + The bitbake -g targetname command + creates the pn-buildlist, + pn-depends.dot, + package-depends.dot, and + task-depends.dot files in the current + directory. + These files show what will be built and the package and task + dependencies, which are useful for debugging problems. + You can use the + bitbake -g -u depexp targetname + command to display the results in a more human-readable form. + +
+ +
+ General BitBake Problems + + + You can see debug output from BitBake by using the -D option. + The debug output gives more information about what BitBake + is doing and the reason behind it. + Each -D option you use increases the logging level. + The most common usage is -DDD. + + + + The output from bitbake -DDD -v targetname can reveal why + BitBake chose a certain version of a package or why BitBake + picked a certain provider. + This command could also help you in a situation where you think BitBake did something + unexpected. + +
+ +
+ Development Host System Issues + + + Sometimes issues on the host development system can cause your + build to fail. + Following are known, host-specific problems. + Be sure to always consult the + Release Notes + for a look at all release-related issues. + + glibc-initial fails to build: + If your development host system has the unpatched + GNU Make 3.82, + the + do_install + task fails for glibc-initial during + the build. + Typically, every distribution that ships + GNU Make 3.82 as + the default already has the patched version. + However, some distributions, such as Debian, have + GNU Make 3.82 as an option, which + is unpatched. + You will see this error on these types of distributions. + Switch to GNU Make 3.81 or patch + your make to solve the problem. + + + +
+ +
+ Building with No Dependencies + + To build a specific recipe (.bb file), + you can use the following command form: + + $ bitbake -b somepath/somerecipe.bb + + This command form does not check for dependencies. + Consequently, you should use it + only when you know existing dependencies have been met. + + You can also specify fragments of the filename. + In this case, BitBake checks for a unique match. + + +
+ +
+ Variables + + You can use the -e BitBake option to + display the parsing environment for a configuration. + The following displays the general parsing environment: + + $ bitbake -e + + This next example shows the parsing environment for a specific + recipe: + + $ bitbake -e recipename + + +
+ +
+ Recipe Logging Mechanisms + + Best practices exist while writing recipes that both log build progress and + act on build conditions such as warnings and errors. + Both Python and Bash language bindings exist for the logging mechanism: + + Python: For Python functions, BitBake + supports several loglevels: bb.fatal, + bb.error, bb.warn, + bb.note, bb.plain, + and bb.debug. + Bash: For Bash functions, the same set + of loglevels exist and are accessed with a similar syntax: + bbfatal, bberror, + bbwarn, bbnote, + bbplain, and bbdebug. + + + + + For guidance on how logging is handled in both Python and Bash recipes, see the + logging.bbclass file in the + meta/classes folder of the + Source Directory. + + +
+ Logging With Python + + When creating recipes using Python and inserting code that handles build logs, + keep in mind the goal is to have informative logs while keeping the console as + "silent" as possible. + Also, if you want status messages in the log, use the "debug" loglevel. + + + + Following is an example written in Python. + The code handles logging for a function that determines the + number of tasks needed to be run. + See the + "do_listtasks" + section for additional information: + + python do_listtasks() { + bb.debug(2, "Starting to figure out the task list") + if noteworthy_condition: + bb.note("There are 47 tasks to run") + bb.debug(2, "Got to point xyz") + if warning_trigger: + bb.warn("Detected warning_trigger, this might be a problem later.") + if recoverable_error: + bb.error("Hit recoverable_error, you really need to fix this!") + if fatal_error: + bb.fatal("fatal_error detected, unable to print the task list") + bb.plain("The tasks present are abc") + bb.debug(2, "Finished figuring out the tasklist") + } + + +
+ +
+ Logging With Bash + + When creating recipes using Bash and inserting code that handles build + logs, you have the same goals - informative with minimal console output. + The syntax you use for recipes written in Bash is similar to that of + recipes written in Python described in the previous section. + + + + Following is an example written in Bash. + The code logs the progress of the do_my_function function. + + do_my_function() { + bbdebug 2 "Running do_my_function" + if [ exceptional_condition ]; then + bbnote "Hit exceptional_condition" + fi + bbdebug 2 "Got to point xyz" + if [ warning_trigger ]; then + bbwarn "Detected warning_trigger, this might cause a problem later." + fi + if [ recoverable_error ]; then + bberror "Hit recoverable_error, correcting" + fi + if [ fatal_error ]; then + bbfatal "fatal_error detected" + fi + bbdebug 2 "Completed do_my_function" + } + + +
+
+ +
+ Other Tips + + + Here are some other tips that you might find useful: + + When adding new packages, it is worth watching for + undesirable items making their way into compiler command lines. + For example, you do not want references to local system files like + /usr/lib/ or /usr/include/. + + If you want to remove the psplash + boot splashscreen, + add psplash=false to the kernel command line. + Doing so prevents psplash from loading + and thus allows you to see the console. + It is also possible to switch out of the splashscreen by + switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). + + + +
+
+ +
+ Maintaining Build Output Quality + + + Many factors can influence the quality of a build. + For example, if you upgrade a recipe to use a new version of an upstream software + package or you experiment with some new configuration options, subtle changes + can occur that you might not detect until later. + Consider the case where your recipe is using a newer version of an upstream package. + In this case, a new version of a piece of software might introduce an optional + dependency on another library, which is auto-detected. + If that library has already been built when the software is building, + the software will link to the built library and that library will be pulled + into your image along with the new software even if you did not want the + library. + + + + The + buildhistory + class exists to help you maintain + the quality of your build output. + You can use the class to highlight unexpected and possibly unwanted + changes in the build output. + When you enable build history, it records information about the contents of + each package and image and then commits that information to a local Git + repository where you can examine the information. + + + + The remainder of this section describes the following: + + How you can enable and disable + build history + How to understand what the build history contains + + How to limit the information used for build history + + How to examine the build history from both a + command-line and web interface + + + +
+ Enabling and Disabling Build History + + + Build history is disabled by default. + To enable it, add the following INHERIT + statement and set the + BUILDHISTORY_COMMIT + variable to "1" at the end of your + conf/local.conf file found in the + Build Directory: + + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + + Enabling build history as previously described + causes the build process to collect build + output information and commit it to a local + Git repository. + + Enabling build history increases your build times slightly, + particularly for images, and increases the amount of disk + space used during the build. + + + + + You can disable build history by removing the previous statements + from your conf/local.conf file. + +
+ +
+ Understanding What the Build History Contains + + + Build history information is kept in + ${TOPDIR}/buildhistory + in the Build Directory as defined by the + BUILDHISTORY_DIR + variable. + The following is an example abbreviated listing: + + + + + At the top level, there is a metadata-revs file + that lists the revisions of the repositories for the layers enabled + when the build was produced. + The rest of the data splits into separate + packages, images and + sdk directories, the contents of which are + described below. + + +
+ Build History Package Information + + + The history for each package contains a text file that has + name-value pairs with information about the package. + For example, buildhistory/packages/i586-poky-linux/busybox/busybox/latest + contains the following: + + PV = 1.22.1 + PR = r32 + RPROVIDES = + RDEPENDS = glibc (>= 2.20) update-alternatives-opkg + RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d + PKGSIZE = 540168 + FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \ + /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \ + /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \ + /usr/share/pixmaps /usr/share/applications /usr/share/idl \ + /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers + FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \ + /etc/busybox.links.nosuid /etc/busybox.links.suid + + Most of these name-value pairs correspond to variables used + to produce the package. + The exceptions are FILELIST, which is the + actual list of files in the package, and + PKGSIZE, which is the total size of files + in the package in bytes. + + + + There is also a file corresponding to the recipe from which the + package came (e.g. + buildhistory/packages/i586-poky-linux/busybox/latest): + + PV = 1.22.1 + PR = r32 + DEPENDS = initscripts kern-tools-native update-rc.d-native \ + virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \ + virtual/libc virtual/update-alternatives + PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \ + busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \ + busybox-staticdev busybox-dev busybox-doc busybox-locale busybox + + + + + Finally, for those recipes fetched from a version control + system (e.g., Git), a file exists that lists source revisions + that are specified in the recipe and lists the actual revisions + used during the build. + Listed and actual revisions might differ when + SRCREV + is set to + ${AUTOREV}. + Here is an example assuming + buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev): + + # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" + SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" + # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" + SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" + + You can use the buildhistory-collect-srcrevs + command with the -a option to + collect the stored SRCREV values + from build history and report them in a format suitable for + use in global configuration (e.g., + local.conf or a distro include file) to + override floating AUTOREV values to a + fixed set of revisions. + Here is some example output from this command: + + $ buildhistory-collect-srcrevs -a + # i586-poky-linux + SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072" + SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072" + SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a" + SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" + # x86_64-linux + SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa" + SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf" + SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11" + SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072" + SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3" + SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca" + SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a" + SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff" + SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" + # qemux86-poky-linux + SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" + SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f" + # all-poky-linux + SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11" + + + Here are some notes on using the + buildhistory-collect-srcrevs command: + + By default, only values where the + SRCREV was + not hardcoded (usually when AUTOREV + was used) are reported. + Use the -a option to see all + SRCREV values. + + The output statements might not have any effect + if overrides are applied elsewhere in the build system + configuration. + Use the -f option to add the + forcevariable override to each output line + if you need to work around this restriction. + + The script does apply special handling when + building for multiple machines. + However, the script does place a + comment before each set of values that specifies + which triplet to which they belong as shown above + (e.g., i586-poky-linux). + + + + +
+ +
+ Build History Image Information + + + The files produced for each image are as follows: + + image-files: + A directory containing selected files from the root + filesystem. + The files are defined by + BUILDHISTORY_IMAGE_FILES. + + build-id.txt: + Human-readable information about the build configuration + and metadata source revisions. + This file contains the full build header as printed + by BitBake. + *.dot: + Dependency graphs for the image that are + compatible with graphviz. + + files-in-image.txt: + A list of files in the image with permissions, + owner, group, size, and symlink information. + + image-info.txt: + A text file containing name-value pairs with information + about the image. + See the following listing example for more information. + + installed-package-names.txt: + A list of installed packages by name only. + installed-package-sizes.txt: + A list of installed packages ordered by size. + + installed-packages.txt: + A list of installed packages with full package + filenames. + + + Installed package information is able to be gathered and + produced even if package management is disabled for the final + image. + + + + + Here is an example of image-info.txt: + + DISTRO = poky + DISTRO_VERSION = 1.7 + USER_CLASSES = buildstats image-mklibs image-prelink + IMAGE_CLASSES = image_types + IMAGE_FEATURES = debug-tweaks + IMAGE_LINGUAS = + IMAGE_INSTALL = packagegroup-core-boot run-postinsts + BAD_RECOMMENDATIONS = + NO_RECOMMENDATIONS = + PACKAGE_EXCLUDE = + ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \ + write_image_manifest ; buildhistory_list_installed_image ; \ + buildhistory_get_image_installed ; ssh_allow_empty_password; \ + postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ; + IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; + IMAGESIZE = 6900 + + Other than IMAGESIZE, which is the + total size of the files in the image in Kbytes, the + name-value pairs are variables that may have influenced the + content of the image. + This information is often useful when you are trying to determine + why a change in the package or file listings has occurred. + +
+ +
+ Using Build History to Gather Image Information Only + + + As you can see, build history produces image information, + including dependency graphs, so you can see why something + was pulled into the image. + If you are just interested in this information and not + interested in collecting specific package or SDK information, + you can enable writing only image information without + any history by adding the following to your + conf/local.conf file found in the + Build Directory: + + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "0" + BUILDHISTORY_FEATURES = "image" + + Here, you set the + BUILDHISTORY_FEATURES + variable to use the image feature only. + +
+ +
+ Build History SDK Information + + Build history collects similar information on the contents + of SDKs (e.g. meta-toolchain + or bitbake -c populate_sdk imagename) + as compared to information it collects for images. + The following list shows the files produced for each SDK: + + files-in-sdk.txt: + A list of files in the SDK with permissions, + owner, group, size, and symlink information. + This list includes both the host and target parts + of the SDK. + + sdk-info.txt: + A text file containing name-value pairs with information + about the SDK. + See the following listing example for more information. + + The following information appears under + each of the host + and target directories + for the portions of the SDK that run on the host and + on the target, respectively: + + depends.dot: + Dependency graph for the SDK that is + compatible with graphviz. + + installed-package-names.txt: + A list of installed packages by name only. + + installed-package-sizes.txt: + A list of installed packages ordered by size. + + installed-packages.txt: + A list of installed packages with full package + filenames. + + + + + + + Here is an example of sdk-info.txt: + + DISTRO = poky + DISTRO_VERSION = 1.3+snapshot-20130327 + SDK_NAME = poky-glibc-i686-arm + SDK_VERSION = 1.3+snapshot + SDKMACHINE = + SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs + BAD_RECOMMENDATIONS = + SDKSIZE = 352712 + + Other than SDKSIZE, which is the + total size of the files in the SDK in Kbytes, the + name-value pairs are variables that might have influenced the + content of the SDK. + This information is often useful when you are trying to + determine why a change in the package or file listings + has occurred. + +
+ +
+ Examining Build History Information + + + You can examine build history output from the command line or + from a web interface. + + + + To see any changes that have occurred (assuming you have + BUILDHISTORY_COMMIT = "1"), + you can simply + use any Git command that allows you to view the history of + a repository. + Here is one method: + + $ git log -p + + You need to realize, however, that this method does show + changes that are not significant (e.g. a package's size + changing by a few bytes). + + + + A command-line tool called buildhistory-diff + does exist, though, that queries the Git repository and prints just + the differences that might be significant in human-readable form. + Here is an example: + + $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ + Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt): + /etc/anotherpkg.conf was added + /sbin/anotherpkg was added + * (installed-package-names.txt): + * anotherpkg was added + Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt): + anotherpkg was added + packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" + * PR changed from "r0" to "r1" + * PV changed from "0.1.10" to "0.1.12" + packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%) + * PR changed from "r0" to "r1" + * PV changed from "0.1.10" to "0.1.12" + + + + + To see changes to the build history using a web interface, follow + the instruction in the README file here. + . + + + + Here is a sample screenshot of the interface: + + +
+
+
+ +
+ diff --git a/documentation/template/Vera.ttf b/documentation/template/Vera.ttf new file mode 100644 index 0000000000..58cd6b5e61 Binary files /dev/null and b/documentation/template/Vera.ttf differ diff --git a/documentation/template/Vera.xml b/documentation/template/Vera.xml new file mode 100644 index 0000000000..3c82043e35 --- /dev/null +++ b/documentation/template/Vera.xml @@ -0,0 +1 @@ +BitstreamVeraSans729546928-235-183-23512879283200TYPE0CIDFontType20 \ No newline at end of file diff --git a/documentation/template/VeraMoBd.ttf b/documentation/template/VeraMoBd.ttf new file mode 100644 index 0000000000..9be6547ed6 Binary files /dev/null and b/documentation/template/VeraMoBd.ttf differ diff --git a/documentation/template/VeraMoBd.xml b/documentation/template/VeraMoBd.xml new file mode 100644 index 0000000000..9b33107a44 --- /dev/null +++ b/documentation/template/VeraMoBd.xml @@ -0,0 +1 @@ +BitstreamVeraSansMono-BoldBitstream Vera Sans Mono BoldBitstream Vera Sans Mono729546759-240-19-2356059283400TYPE0CIDFontType20 \ No newline at end of file diff --git a/documentation/template/VeraMono.ttf b/documentation/template/VeraMono.ttf new file mode 100644 index 0000000000..139f0b4311 Binary files /dev/null and b/documentation/template/VeraMono.ttf differ diff --git a/documentation/template/VeraMono.xml b/documentation/template/VeraMono.xml new file mode 100644 index 0000000000..3a0a86659c --- /dev/null +++ b/documentation/template/VeraMono.xml @@ -0,0 +1 @@ +BitstreamVeraSansMono-RomanBitstream Vera Sans MonoBitstream Vera Sans Mono729546759-240-4-2356059283400TYPE0CIDFontType20 \ No newline at end of file diff --git a/documentation/template/component.title.xsl b/documentation/template/component.title.xsl new file mode 100644 index 0000000000..ee21d59ad5 --- /dev/null +++ b/documentation/template/component.title.xsl @@ -0,0 +1,39 @@ + + + + + + + + + + + 6 + 5 + 4 + 3 + 2 + 1 + + + + title + + + + + + + + + + + + + + + diff --git a/documentation/template/division.title.xsl b/documentation/template/division.title.xsl new file mode 100644 index 0000000000..6c265970d5 --- /dev/null +++ b/documentation/template/division.title.xsl @@ -0,0 +1,24 @@ + + + + + +

+ title + + + + + + + + + + +

+
+
diff --git a/documentation/template/draft.png b/documentation/template/draft.png new file mode 100644 index 0000000000..53051a9ddd Binary files /dev/null and b/documentation/template/draft.png differ diff --git a/documentation/template/fop-config.xml b/documentation/template/fop-config.xml new file mode 100644 index 0000000000..09cc5ca0f5 --- /dev/null +++ b/documentation/template/fop-config.xml @@ -0,0 +1,58 @@ + + + + true + + + true + + + ../template + ../template + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/template/formal.object.heading.xsl b/documentation/template/formal.object.heading.xsl new file mode 100644 index 0000000000..1a5e697808 --- /dev/null +++ b/documentation/template/formal.object.heading.xsl @@ -0,0 +1,21 @@ + + + + + + + + + +

+ + + + +

+
+
diff --git a/documentation/template/gloss-permalinks.xsl b/documentation/template/gloss-permalinks.xsl new file mode 100644 index 0000000000..6bf58116f6 --- /dev/null +++ b/documentation/template/gloss-permalinks.xsl @@ -0,0 +1,14 @@ + + + + + + + + + + + diff --git a/documentation/template/ohand-color.svg b/documentation/template/ohand-color.svg new file mode 100644 index 0000000000..e42ff9c6fc --- /dev/null +++ b/documentation/template/ohand-color.svg @@ -0,0 +1,150 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/template/permalinks.xsl b/documentation/template/permalinks.xsl new file mode 100644 index 0000000000..d2a1c14524 --- /dev/null +++ b/documentation/template/permalinks.xsl @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/template/poky-db-pdf.xsl b/documentation/template/poky-db-pdf.xsl new file mode 100644 index 0000000000..f8a3df103d --- /dev/null +++ b/documentation/template/poky-db-pdf.xsl @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + 1 10 1 + + + + + + 0.5pt + solid + #999999 + + + + + + 0.5pt + solid + #999999 + + + + + #999999 + + + + #999999 + + + + + + + + + + + + + diff --git a/documentation/template/poky-ref-manual.png b/documentation/template/poky-ref-manual.png new file mode 100644 index 0000000000..2085edb467 Binary files /dev/null and b/documentation/template/poky-ref-manual.png differ diff --git a/documentation/template/poky.svg b/documentation/template/poky.svg new file mode 100644 index 0000000000..a4ea5e2f45 --- /dev/null +++ b/documentation/template/poky.svg @@ -0,0 +1,163 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/documentation/template/qa-code-permalinks.xsl b/documentation/template/qa-code-permalinks.xsl new file mode 100644 index 0000000000..a309095c60 --- /dev/null +++ b/documentation/template/qa-code-permalinks.xsl @@ -0,0 +1,23 @@ + + + + + + + + + + + + diff --git a/documentation/template/section.title.xsl b/documentation/template/section.title.xsl new file mode 100644 index 0000000000..5c6ff9a96e --- /dev/null +++ b/documentation/template/section.title.xsl @@ -0,0 +1,55 @@ + + + + + + + + 1 + 2 + 3 + 4 + 5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/template/titlepage.templates.xml b/documentation/template/titlepage.templates.xml new file mode 100644 index 0000000000..f53f147002 --- /dev/null +++ b/documentation/template/titlepage.templates.xml @@ -0,0 +1,1227 @@ + + + + + + + + + + + + +]> + + + + + + + + + + + + + + + <subtitle param:node="ancestor-or-self::article[1]" + keep-with-next="always" + font-size="&hsize3;" + font-weight="bold" + space-after="0.8em"/> + + <corpauthor space-before="0.5em" + font-size="&hsize3;"/> + <authorgroup space-before="0.5em" + font-size="&hsize2;"/> + <author space-before="0.5em" + font-size="&hsize2;" + space-after="0.8em"/> + + <email font-size="&hsize2;"/> + + <othercredit space-before="0.5em"/> + <releaseinfo space-before="0.5em"/> + <copyright space-before="0.5em"/> + <legalnotice text-align="start" + margin-left="0.5in" + margin-right="0.5in" + font-family="{$body.fontset}"/> + <pubdate space-before="0.5em"/> + <para></para> + <revision space-before="0.5em"/> + <revhistory space-before="0.5em"/> + <abstract space-before="0.5em" + text-align="start" + margin-left="0.5in" + margin-right="0.5in" + font-family="{$body.fontset}"/> + + <para></para> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="set" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:named-template="division.title" + param:node="ancestor-or-self::set[1]" + text-align="center" + font-size="&hsize5;" + space-before="&hsize5space;" + font-weight="bold" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}" + text-align="center"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="book" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + + <mediaobject/> + + <subtitle + text-align="center" + font-size="&hsize4;" + space-before="&hsize4space;" + font-family="{$title.fontset}"/> + <corpauthor font-size="&hsize3;" + keep-with-next="always" + space-before="2in"/> + <authorgroup space-before="2in"/> + <author font-size="&hsize3;" + space-before="&hsize2space;" + keep-with-next="always"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + <corpauthor/> + <authorgroup t:named-template="verso.authorgroup"/> + <author/> + <othercredit/> + <pubdate space-before="1em"/> + <copyright/> + <abstract/> + <legalnotice font-size="8pt"/> + </t:titlepage-content> + + <t:titlepage-separator> + <fo:block break-after="page"/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + <fo:block break-after="page"/> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="part" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:named-template="division.title" + param:node="ancestor-or-self::part[1]" + text-align="center" + font-size="&hsize5;" + space-before="&hsize5space;" + font-weight="bold" + font-family="{$title.fontset}"/> + <subtitle + text-align="center" + font-size="&hsize4;" + space-before="&hsize4space;" + font-weight='bold' + font-style='italic' + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="partintro" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + text-align="center" + font-size="&hsize5;" + font-weight="bold" + space-before="1em" + font-family="{$title.fontset}"/> + <subtitle + text-align="center" + font-size="&hsize2;" + font-weight="bold" + font-style="italic" + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="reference" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:named-template="division.title" + param:node="ancestor-or-self::reference[1]" + text-align="center" + font-size="&hsize5;" + space-before="&hsize5space;" + font-weight="bold" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}" + text-align="center"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="refsynopsisdiv" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="refsection" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="refsect1" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="refsect2" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="refsect3" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="dedication" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::dedication[1]" + margin-left="{$title.margin.left}" + font-size="&hsize5;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="preface" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::preface[1]" + margin-left="{$title.margin.left}" + font-size="&hsize5;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="chapter" t:wrapper="fo:block" + font-family="{$title.fontset}"> + <t:titlepage-content t:side="recto" margin-left="{$title.margin.left}"> + <title t:named-template="component.title" + param:node="ancestor-or-self::chapter[1]" + font-size="&hsize5;" + font-weight="bold"/> + + <subtitle space-before="0.5em" + font-style="italic" + font-size="&hsize2;" + font-weight="bold"/> + + <corpauthor space-before="0.5em" + space-after="0.5em" + font-size="&hsize2;"/> + + <authorgroup space-before="0.5em" + space-after="0.5em" + font-size="&hsize2;"/> + + <author space-before="0.5em" + space-after="0.5em" + font-size="&hsize2;"/> + + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="appendix" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:named-template="component.title" + param:node="ancestor-or-self::appendix[1]" + margin-left="{$title.margin.left}" + font-size="&hsize5;" + font-weight="bold" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="section" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + margin-left="{$title.margin.left}" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect1" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + margin-left="{$title.margin.left}" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect2" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + margin-left="{$title.margin.left}" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect3" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + margin-left="{$title.margin.left}" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect4" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + margin-left="{$title.margin.left}" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect5" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + margin-left="{$title.margin.left}" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="simplesect" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + margin-left="{$title.margin.left}" + font-family="{$title.fontset}"/> + <subtitle + font-family="{$title.fontset}"/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="bibliography" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::bibliography[1]" + margin-left="{$title.margin.left}" + font-size="&hsize5;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="bibliodiv" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title t:named-template="component.title" + param:node="ancestor-or-self::bibliodiv[1]" + margin-left="{$title.margin.left}" + font-size="&hsize4;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="glossary" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::glossary[1]" + margin-left="{$title.margin.left}" + font-size="&hsize5;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="glossdiv" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title t:named-template="component.title" + param:node="ancestor-or-self::glossdiv[1]" + margin-left="{$title.margin.left}" + font-size="&hsize4;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="index" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::index[1]" + param:pagewide="1" + margin-left="0pt" + font-size="&hsize5;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + + <!-- The indexdiv.title template is used so that manual and --> + <!-- automatically generated indexdiv titles get the same --> + <!-- formatting. --> + + <t:titlepage t:element="indexdiv" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title t:force="1" + t:named-template="indexdiv.title" + param:title="title"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="setindex" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::setindex[1]" + param:pagewide="1" + margin-left="0pt" + font-size="&hsize5;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="colophon" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::colophon[1]" + margin-left="{$title.margin.left}" + font-size="&hsize5;" + font-family="{$title.fontset}" + font-weight="bold"/> + <subtitle + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="table.of.contents" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="gentext" + param:key="'TableofContents'" + space-before.minimum="1em" + space-before.optimum="1.5em" + space-before.maximum="2em" + space-after="0.5em" + margin-left="{$title.margin.left}" + font-size="&hsize3;" + font-weight="bold" + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + + <t:titlepage t:element="list.of.tables" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="gentext" + param:key="'ListofTables'" + space-before.minimum="1em" + space-before.optimum="1.5em" + space-before.maximum="2em" + space-after="0.5em" + margin-left="{$title.margin.left}" + font-size="&hsize3;" + font-weight="bold" + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + + <t:titlepage t:element="list.of.figures" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="gentext" + param:key="'ListofFigures'" + space-before.minimum="1em" + space-before.optimum="1.5em" + space-before.maximum="2em" + space-after="0.5em" + margin-left="{$title.margin.left}" + font-size="&hsize3;" + font-weight="bold" + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + + <t:titlepage t:element="list.of.examples" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="gentext" + param:key="'ListofExamples'" + space-before.minimum="1em" + space-before.optimum="1.5em" + space-before.maximum="2em" + space-after="0.5em" + margin-left="{$title.margin.left}" + font-size="&hsize3;" + font-weight="bold" + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + + <t:titlepage t:element="list.of.equations" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="gentext" + param:key="'ListofEquations'" + space-before.minimum="1em" + space-before.optimum="1.5em" + space-before.maximum="2em" + space-after="0.5em" + margin-left="{$title.margin.left}" + font-size="&hsize3;" + font-weight="bold" + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + + <t:titlepage t:element="list.of.procedures" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="gentext" + param:key="'ListofProcedures'" + space-before.minimum="1em" + space-before.optimum="1.5em" + space-before.maximum="2em" + space-after="0.5em" + margin-left="{$title.margin.left}" + font-size="&hsize3;" + font-weight="bold" + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + + <t:titlepage t:element="list.of.unknowns" t:wrapper="fo:block"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="gentext" + param:key="'ListofUnknown'" + space-before.minimum="1em" + space-before.optimum="1.5em" + space-before.maximum="2em" + space-after="0.5em" + margin-left="{$title.margin.left}" + font-size="&hsize3;" + font-weight="bold" + font-family="{$title.fontset}"/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + +</t:templates> diff --git a/documentation/template/yocto-project-qs.png b/documentation/template/yocto-project-qs.png new file mode 100644 index 0000000000..333442e0d6 Binary files /dev/null and b/documentation/template/yocto-project-qs.png differ diff --git a/documentation/tools/eclipse-help.sed b/documentation/tools/eclipse-help.sed new file mode 100644 index 0000000000..38690bc938 --- /dev/null +++ b/documentation/tools/eclipse-help.sed @@ -0,0 +1,18 @@ +# Processes poky-ref-manual and yocto-project-qs manual (<word>-<word>-<word> style) +# For example: +# "ulink" href="http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#faq" +# -> "link" href="../poky-ref-manual/faq.html" +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*-[a-z]*\)\/[a-z]*-[a-z]*-[a-z]*.html#\([^\"]*\)\"/\"link\" href=\"\.\.\/\1\/\2.html\"/g + +# Processes all other manuals (<word>-<word> style) +# For example: +# "ulink" href="http://www.yoctoproject.org/docs/1.3/kernel-manual/kernel-manual.html#faq" +# -> "link" href="../kernel-manual/faq.html" +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*\)\/[a-z]*-[a-z]*.html#\([^\"]*\)\"/\"link\" href=\"\.\.\/\1\/\2.html\"/g + +# Process cases where just an external manual is referenced without an id anchor +# For example: +# "ulink" href="http://www.yoctoproject.org/docs/1.3/kernel-manual/kernel-manual.html +# -> "link" href="../kernel-manual/index.html" +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*-[a-z]*\)\/[a-z]*-[a-z]*-[a-z]*.html\"/\"link\" href=\"\.\.\/\1\/index.html\"/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*\)\/[a-z]*-[a-z]*.html\"/\"link\" href=\"\.\.\/\1\/index.html\"/g diff --git a/documentation/tools/mega-manual.sed b/documentation/tools/mega-manual.sed new file mode 100644 index 0000000000..9f3a7ecbeb --- /dev/null +++ b/documentation/tools/mega-manual.sed @@ -0,0 +1,31 @@ +# Processes poky-ref-manual and yocto-project-qs manual (<word>-<word>-<word> style). +# This style is for manual folders like "yocto-project-qs" and "poky-ref-manual". +# This is the old way that did it. Can't do that now that we have "bitbake-user-manual" strings +# in the mega-manual. +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g + +# Processes all other manuals (<word>-<word> style) except for the BitBake User Manual because +# it is not included in the mega-manual. +# This style is for manual folders that use two word, which is the standard now (e.g. "ref-manual"). +# This was the one-liner that worked before we introduced the BitBake User Manual, which is +# not in the mega-manual. +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g + +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/adt-manual\/adt-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g + +# Process cases where just an external manual is referenced without an id anchor +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/yocto-project-qs\/yocto-project-qs.html\" target=\"_top\">Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/dev-manual\/dev-manual.html\" target=\"_top\">Yocto Project Development Manual<\/a>/Yocto Project Development Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/adt-manual\/adt-manual.html\" target=\"_top\">Yocto Project Application Developer's Guide<\/a>/Yocto Project Application Developer's Guide/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/bsp-guide\/bsp-guide.html\" target=\"_top\">Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/profile-manual\/profile-manual.html\" target=\"_top\">Yocto Project Profiling and Tracing Manual<\/a>/Yocto Project Profiling and Tracing Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/kernel-dev\/kernel-dev.html\" target=\"_top\">Yocto Project Linux Kernel Development Manual<\/a>/Yocto Project Linux Kernel Development Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.2\/ref-manual\/ref-manual.html\" target=\"_top\">Yocto Project Reference Manual<\/a>/Yocto Project Reference Manual/g diff --git a/documentation/tools/poky-docbook-to-pdf b/documentation/tools/poky-docbook-to-pdf new file mode 100755 index 0000000000..f55fd278af --- /dev/null +++ b/documentation/tools/poky-docbook-to-pdf @@ -0,0 +1,51 @@ +#!/bin/sh + +if [ -z "$1" -o -z "$2" ]; then + echo "usage: [-v] $0 <docbook file> <templatedir>" + echo + echo "*NOTE* you need xsltproc, fop and nwalsh docbook stylesheets" + echo " installed for this to work!" + echo + exit 0 +fi + +FO=`echo $1 | sed s/.xml/.fo/` || exit 1 +PDF=`echo $1 | sed s/.xml/.pdf/` || exit 1 +TEMPLATEDIR=$2 + +## +# These URI should be rewritten by your distribution's xml catalog to +# match your localy installed XSL stylesheets. +XSL_BASE_URI="http://docbook.sourceforge.net/release/xsl/current" + +# Creates a temporary XSL stylesheet based on titlepage.xsl +xsltproc -o /tmp/titlepage.xsl \ + --xinclude \ + $XSL_BASE_URI/template/titlepage.xsl \ + $TEMPLATEDIR/titlepage.templates.xml || exit 1 + +# Creates the file needed for FOP +xsltproc --xinclude \ + --stringparam hyphenate false \ + --stringparam formal.title.placement "figure after" \ + --stringparam ulink.show 1 \ + --stringparam body.font.master 9 \ + --stringparam title.font.master 11 \ + --stringparam draft.watermark.image "$TEMPLATEDIR/draft.png" \ + --stringparam chapter.autolabel 1 \ + --stringparam appendix.autolabel A \ + --stringparam section.autolabel 1 \ + --stringparam section.label.includes.component.label 1 \ + --output $FO \ + $TEMPLATEDIR/poky-db-pdf.xsl \ + $1 || exit 1 + +# Invokes the Java version of FOP. Uses the additional configuration file common/fop-config.xml +fop -c $TEMPLATEDIR/fop-config.xml -fo $FO -pdf $PDF || exit 1 + +rm -f $FO +rm -f /tmp/titlepage.xsl + +echo +echo " #### Success! $PDF ready. ####" +echo diff --git a/documentation/yocto-project-qs/figures/building-an-image.png b/documentation/yocto-project-qs/figures/building-an-image.png new file mode 100755 index 0000000000..1fbea5ab00 Binary files /dev/null and b/documentation/yocto-project-qs/figures/building-an-image.png differ diff --git a/documentation/yocto-project-qs/figures/using-a-pre-built-image.png b/documentation/yocto-project-qs/figures/using-a-pre-built-image.png new file mode 100644 index 0000000000..b03130d123 Binary files /dev/null and b/documentation/yocto-project-qs/figures/using-a-pre-built-image.png differ diff --git a/documentation/yocto-project-qs/figures/yocto-environment.png b/documentation/yocto-project-qs/figures/yocto-environment.png new file mode 100644 index 0000000000..82b7a55a35 Binary files /dev/null and b/documentation/yocto-project-qs/figures/yocto-environment.png differ diff --git a/documentation/yocto-project-qs/figures/yocto-project-transp.png b/documentation/yocto-project-qs/figures/yocto-project-transp.png new file mode 100755 index 0000000000..31d2b147fd Binary files /dev/null and b/documentation/yocto-project-qs/figures/yocto-project-transp.png differ diff --git a/documentation/yocto-project-qs/qs-style.css b/documentation/yocto-project-qs/qs-style.css new file mode 100644 index 0000000000..235c85a1ba --- /dev/null +++ b/documentation/yocto-project-qs/qs-style.css @@ -0,0 +1,983 @@ +/* + 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-position: top; + margin-top: -256px; + padding-right: 50px; + margin-left: 50px; + text-align: center; + width: 600px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/yocto-project-qs/yocto-project-qs-customization.xsl b/documentation/yocto-project-qs/yocto-project-qs-customization.xsl new file mode 100644 index 0000000000..3dad6b96c5 --- /dev/null +++ b/documentation/yocto-project-qs/yocto-project-qs-customization.xsl @@ -0,0 +1,15 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> + <xsl:import href="yocto-project-qs-titlepage.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="generate.toc" select="'article nop'"></xsl:param> + <xsl:param name="html.stylesheet" select="'qs-style.css'" /> +</xsl:stylesheet> diff --git a/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl b/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl new file mode 100644 index 0000000000..f8f8930f27 --- /dev/null +++ b/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl @@ -0,0 +1,25 @@ +<?xml version='1.0'?> +<xsl:stylesheet + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns="http://www.w3.org/1999/xhtml" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + + <xsl:import + href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + <xsl:import href="yocto-project-qs-titlepage.xsl"/> + + <xsl:param name="chunker.output.indent" select="'yes'"/> + <xsl:param name="chunk.quietly" select="1"/> + <xsl:param name="use.id.as.filename" select="1"/> + <xsl:param name="ulink.target" select="'_self'" /> + <xsl:param name="base.dir" select="'html/yocto-project-qs/'"/> + <xsl:param name="chunk.section.depth" select="0"/> + <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="generate.toc" select="'article nop'"></xsl:param> + <xsl:param name="html.stylesheet" select="'style.css'" /> +</xsl:stylesheet> diff --git a/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl b/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl new file mode 100644 index 0000000000..a435ac77ab --- /dev/null +++ b/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl @@ -0,0 +1,3820 @@ +<?xml version="1.0"?> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:exsl="http://exslt.org/common" version="1.0" exclude-result-prefixes="exsl"> + +<!-- This stylesheet was created by template/titlepage.xsl--> + +<xsl:template name="article.titlepage.recto"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/abstract"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/abstract"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/abstract"/> + <xsl:choose> + <xsl:when test="articleinfo/title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/title"/> + </xsl:when> + <xsl:when test="artheader/title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="articleinfo/subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/subtitle"/> + </xsl:when> + <xsl:when test="artheader/subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/corpauthor"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/corpauthor"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/authorgroup"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/authorgroup"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/author"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/author"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/othercredit"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/othercredit"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/releaseinfo"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/releaseinfo"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/copyright"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/copyright"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/legalnotice"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/legalnotice"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/pubdate"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/pubdate"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/revision"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/revision"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/revhistory"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/revhistory"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/revhistory"/> +</xsl:template> + +<xsl:template name="article.titlepage.verso"> +</xsl:template> + +<xsl:template name="article.titlepage.separator"><hr/> +</xsl:template> + +<xsl:template name="article.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="article.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="article.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="article.titlepage.before.recto"/> + <xsl:call-template name="article.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="article.titlepage.before.verso"/> + <xsl:call-template name="article.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="article.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="article.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="article.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="abstract" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> + <xsl:call-template name="anchor"/> + <xsl:apply-templates/> +<!-- orignally generated content --> +<!-- <xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> --> +</div> +</xsl:template> + +<xsl:template match="title" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="article.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="set.titlepage.recto"> + <xsl:choose> + <xsl:when test="setinfo/title"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="setinfo/subtitle"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/corpauthor"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/authorgroup"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/author"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/othercredit"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/releaseinfo"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/copyright"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/legalnotice"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/pubdate"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/revision"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/revhistory"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/abstract"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="set.titlepage.verso"> +</xsl:template> + +<xsl:template name="set.titlepage.separator"><hr/> +</xsl:template> + +<xsl:template name="set.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="set.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="set.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="set.titlepage.before.recto"/> + <xsl:call-template name="set.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="set.titlepage.before.verso"/> + <xsl:call-template name="set.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="set.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="set.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="set.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="set.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="book.titlepage.recto"> + <xsl:choose> + <xsl:when test="bookinfo/title"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="bookinfo/subtitle"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/corpauthor"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/authorgroup"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/author"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/othercredit"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/releaseinfo"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/copyright"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/legalnotice"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/pubdate"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/revision"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/revhistory"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/abstract"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="book.titlepage.verso"> +</xsl:template> + +<xsl:template name="book.titlepage.separator"><hr/> +</xsl:template> + +<xsl:template name="book.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="book.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="book.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="book.titlepage.before.recto"/> + <xsl:call-template name="book.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="book.titlepage.before.verso"/> + <xsl:call-template name="book.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="book.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="book.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="book.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="book.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="part.titlepage.recto"> + <div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:call-template name="division.title"> +<xsl:with-param name="node" select="ancestor-or-self::part[1]"/> +</xsl:call-template></div> + <xsl:choose> + <xsl:when test="partinfo/subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/corpauthor"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/authorgroup"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/author"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/othercredit"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/releaseinfo"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/copyright"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/legalnotice"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/pubdate"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/revision"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/revhistory"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/abstract"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="part.titlepage.verso"> +</xsl:template> + +<xsl:template name="part.titlepage.separator"> +</xsl:template> + +<xsl:template name="part.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="part.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="part.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="part.titlepage.before.recto"/> + <xsl:call-template name="part.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="part.titlepage.before.verso"/> + <xsl:call-template name="part.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="part.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="part.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="part.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="part.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="part.titlepage.recto.style"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="partintro.titlepage.recto"> + <xsl:choose> + <xsl:when test="partintroinfo/title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="partintroinfo/subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/corpauthor"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/authorgroup"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/author"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/othercredit"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/releaseinfo"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/copyright"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/legalnotice"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/pubdate"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/revision"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/revhistory"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/abstract"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="partintro.titlepage.verso"> +</xsl:template> + +<xsl:template name="partintro.titlepage.separator"> +</xsl:template> + +<xsl:template name="partintro.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="partintro.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="partintro.titlepage"> + <div> + <xsl:variable name="recto.content"> + <xsl:call-template name="partintro.titlepage.before.recto"/> + <xsl:call-template name="partintro.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="partintro.titlepage.before.verso"/> + <xsl:call-template name="partintro.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="partintro.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="partintro.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="partintro.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="partintro.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="reference.titlepage.recto"> + <xsl:choose> + <xsl:when test="referenceinfo/title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="referenceinfo/subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/corpauthor"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/authorgroup"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/author"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/othercredit"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/releaseinfo"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/copyright"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/legalnotice"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/pubdate"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/revision"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/revhistory"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/abstract"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="reference.titlepage.verso"> +</xsl:template> + +<xsl:template name="reference.titlepage.separator"><hr/> +</xsl:template> + +<xsl:template name="reference.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="reference.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="reference.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="reference.titlepage.before.recto"/> + <xsl:call-template name="reference.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="reference.titlepage.before.verso"/> + <xsl:call-template name="reference.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="reference.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="reference.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="reference.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="reference.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="refentry.titlepage.recto"> +</xsl:template> + +<xsl:template name="refentry.titlepage.verso"> +</xsl:template> + +<xsl:template name="refentry.titlepage.separator"> +</xsl:template> + +<xsl:template name="refentry.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="refentry.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="refentry.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="refentry.titlepage.before.recto"/> + <xsl:call-template name="refentry.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="refentry.titlepage.before.verso"/> + <xsl:call-template name="refentry.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="refentry.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="refentry.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="refentry.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template name="dedication.titlepage.recto"> + <div xsl:use-attribute-sets="dedication.titlepage.recto.style"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::dedication[1]"/> +</xsl:call-template></div> + <xsl:choose> + <xsl:when test="dedicationinfo/subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="dedicationinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="dedication.titlepage.verso"> +</xsl:template> + +<xsl:template name="dedication.titlepage.separator"> +</xsl:template> + +<xsl:template name="dedication.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="dedication.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="dedication.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="dedication.titlepage.before.recto"/> + <xsl:call-template name="dedication.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="dedication.titlepage.before.verso"/> + <xsl:call-template name="dedication.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="dedication.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="dedication.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="dedication.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="dedication.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="dedication.titlepage.recto.style"> +<xsl:apply-templates select="." mode="dedication.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="acknowledgements.titlepage.recto"> + <div xsl:use-attribute-sets="acknowledgements.titlepage.recto.style"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::acknowledgements[1]"/> +</xsl:call-template></div> + <xsl:choose> + <xsl:when test="acknowledgementsinfo/subtitle"> + <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="acknowledgementsinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="acknowledgements.titlepage.verso"> +</xsl:template> + +<xsl:template name="acknowledgements.titlepage.separator"> +</xsl:template> + +<xsl:template name="acknowledgements.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="acknowledgements.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="acknowledgements.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="acknowledgements.titlepage.before.recto"/> + <xsl:call-template name="acknowledgements.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="acknowledgements.titlepage.before.verso"/> + <xsl:call-template name="acknowledgements.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="acknowledgements.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="acknowledgements.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="acknowledgements.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="acknowledgements.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="acknowledgements.titlepage.recto.style"> +<xsl:apply-templates select="." mode="acknowledgements.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="preface.titlepage.recto"> + <xsl:choose> + <xsl:when test="prefaceinfo/title"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="prefaceinfo/subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/corpauthor"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/authorgroup"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/author"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/othercredit"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/releaseinfo"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/copyright"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/legalnotice"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/pubdate"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/revision"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/revhistory"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/abstract"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="preface.titlepage.verso"> +</xsl:template> + +<xsl:template name="preface.titlepage.separator"> +</xsl:template> + +<xsl:template name="preface.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="preface.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="preface.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="preface.titlepage.before.recto"/> + <xsl:call-template name="preface.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="preface.titlepage.before.verso"/> + <xsl:call-template name="preface.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="preface.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="preface.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="preface.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="preface.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="chapter.titlepage.recto"> + <xsl:choose> + <xsl:when test="chapterinfo/title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="chapterinfo/subtitle"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/corpauthor"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/authorgroup"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/author"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/othercredit"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/releaseinfo"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/copyright"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/legalnotice"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/pubdate"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/revision"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/revhistory"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/abstract"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="chapter.titlepage.verso"> +</xsl:template> + +<xsl:template name="chapter.titlepage.separator"> +</xsl:template> + +<xsl:template name="chapter.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="chapter.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="chapter.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="chapter.titlepage.before.recto"/> + <xsl:call-template name="chapter.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="chapter.titlepage.before.verso"/> + <xsl:call-template name="chapter.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="chapter.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="chapter.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="chapter.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="chapter.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="appendix.titlepage.recto"> + <xsl:choose> + <xsl:when test="appendixinfo/title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="appendixinfo/subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/corpauthor"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/authorgroup"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/author"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/othercredit"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/releaseinfo"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/copyright"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/legalnotice"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/pubdate"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/revision"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/revhistory"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/abstract"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="appendix.titlepage.verso"> +</xsl:template> + +<xsl:template name="appendix.titlepage.separator"> +</xsl:template> + +<xsl:template name="appendix.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="appendix.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="appendix.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="appendix.titlepage.before.recto"/> + <xsl:call-template name="appendix.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="appendix.titlepage.before.verso"/> + <xsl:call-template name="appendix.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="appendix.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="appendix.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="appendix.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="appendix.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="section.titlepage.recto"> + <xsl:choose> + <xsl:when test="sectioninfo/title"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sectioninfo/subtitle"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/corpauthor"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/authorgroup"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/author"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/othercredit"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/releaseinfo"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/copyright"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/legalnotice"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/pubdate"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/revision"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/revhistory"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/abstract"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="section.titlepage.verso"> +</xsl:template> + +<xsl:template name="section.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if> +</xsl:template> + +<xsl:template name="section.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="section.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="section.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="section.titlepage.before.recto"/> + <xsl:call-template name="section.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="section.titlepage.before.verso"/> + <xsl:call-template name="section.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="section.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="section.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="section.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="section.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="sect1.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect1info/title"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect1info/subtitle"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/corpauthor"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/authorgroup"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/author"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/othercredit"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/releaseinfo"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/copyright"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/legalnotice"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/pubdate"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/revision"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/revhistory"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/abstract"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect1.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect1.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if> +</xsl:template> + +<xsl:template name="sect1.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect1.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect1.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect1.titlepage.before.recto"/> + <xsl:call-template name="sect1.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect1.titlepage.before.verso"/> + <xsl:call-template name="sect1.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="sect1.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="sect1.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect1.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="sect1.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="sect2.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect2info/title"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect2info/subtitle"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/corpauthor"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/authorgroup"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/author"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/othercredit"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/releaseinfo"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/copyright"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/legalnotice"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/pubdate"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/revision"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/revhistory"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/abstract"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect2.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect2.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if> +</xsl:template> + +<xsl:template name="sect2.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect2.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect2.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect2.titlepage.before.recto"/> + <xsl:call-template name="sect2.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect2.titlepage.before.verso"/> + <xsl:call-template name="sect2.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="sect2.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="sect2.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect2.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="sect2.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="sect3.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect3info/title"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect3info/subtitle"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/corpauthor"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/authorgroup"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/author"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/othercredit"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/releaseinfo"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/copyright"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/legalnotice"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/pubdate"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/revision"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/revhistory"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/abstract"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect3.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect3.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if> +</xsl:template> + +<xsl:template name="sect3.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect3.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect3.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect3.titlepage.before.recto"/> + <xsl:call-template name="sect3.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect3.titlepage.before.verso"/> + <xsl:call-template name="sect3.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="sect3.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="sect3.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect3.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="sect3.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="sect4.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect4info/title"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect4info/subtitle"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/corpauthor"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/authorgroup"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/author"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/othercredit"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/releaseinfo"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/copyright"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/legalnotice"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/pubdate"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/revision"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/revhistory"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/abstract"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect4.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect4.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if> +</xsl:template> + +<xsl:template name="sect4.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect4.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect4.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect4.titlepage.before.recto"/> + <xsl:call-template name="sect4.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect4.titlepage.before.verso"/> + <xsl:call-template name="sect4.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="sect4.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="sect4.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect4.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="sect4.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="sect5.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect5info/title"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect5info/subtitle"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/corpauthor"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/authorgroup"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/author"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/othercredit"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/releaseinfo"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/copyright"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/legalnotice"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/pubdate"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/revision"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/revhistory"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/abstract"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect5.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect5.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if> +</xsl:template> + +<xsl:template name="sect5.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect5.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect5.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect5.titlepage.before.recto"/> + <xsl:call-template name="sect5.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect5.titlepage.before.verso"/> + <xsl:call-template name="sect5.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="sect5.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="sect5.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect5.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="sect5.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="simplesect.titlepage.recto"> + <xsl:choose> + <xsl:when test="simplesectinfo/title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="simplesectinfo/subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/corpauthor"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/authorgroup"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/author"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/othercredit"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/releaseinfo"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/copyright"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/legalnotice"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/pubdate"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/revision"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/revhistory"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/abstract"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="simplesect.titlepage.verso"> +</xsl:template> + +<xsl:template name="simplesect.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if> +</xsl:template> + +<xsl:template name="simplesect.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="simplesect.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="simplesect.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="simplesect.titlepage.before.recto"/> + <xsl:call-template name="simplesect.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="simplesect.titlepage.before.verso"/> + <xsl:call-template name="simplesect.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="simplesect.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="simplesect.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="simplesect.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="corpauthor" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="authorgroup" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="author" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="othercredit" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="releaseinfo" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="copyright" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="legalnotice" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="pubdate" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revision" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="revhistory" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template match="abstract" mode="simplesect.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="bibliography.titlepage.recto"> + <div xsl:use-attribute-sets="bibliography.titlepage.recto.style"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::bibliography[1]"/> +</xsl:call-template></div> + <xsl:choose> + <xsl:when test="bibliographyinfo/subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="bibliographyinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="bibliography.titlepage.verso"> +</xsl:template> + +<xsl:template name="bibliography.titlepage.separator"> +</xsl:template> + +<xsl:template name="bibliography.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="bibliography.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="bibliography.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="bibliography.titlepage.before.recto"/> + <xsl:call-template name="bibliography.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="bibliography.titlepage.before.verso"/> + <xsl:call-template name="bibliography.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="bibliography.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="bibliography.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="bibliography.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="bibliography.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="bibliography.titlepage.recto.style"> +<xsl:apply-templates select="." mode="bibliography.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="glossary.titlepage.recto"> + <div xsl:use-attribute-sets="glossary.titlepage.recto.style"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::glossary[1]"/> +</xsl:call-template></div> + <xsl:choose> + <xsl:when test="glossaryinfo/subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="glossaryinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="glossary.titlepage.verso"> +</xsl:template> + +<xsl:template name="glossary.titlepage.separator"> +</xsl:template> + +<xsl:template name="glossary.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="glossary.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="glossary.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="glossary.titlepage.before.recto"/> + <xsl:call-template name="glossary.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="glossary.titlepage.before.verso"/> + <xsl:call-template name="glossary.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="glossary.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="glossary.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="glossary.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="glossary.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="glossary.titlepage.recto.style"> +<xsl:apply-templates select="." mode="glossary.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="index.titlepage.recto"> + <div xsl:use-attribute-sets="index.titlepage.recto.style"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::index[1]"/> +</xsl:call-template></div> + <xsl:choose> + <xsl:when test="indexinfo/subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="indexinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="index.titlepage.verso"> +</xsl:template> + +<xsl:template name="index.titlepage.separator"> +</xsl:template> + +<xsl:template name="index.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="index.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="index.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="index.titlepage.before.recto"/> + <xsl:call-template name="index.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="index.titlepage.before.verso"/> + <xsl:call-template name="index.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="index.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="index.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="index.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="index.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="index.titlepage.recto.style"> +<xsl:apply-templates select="." mode="index.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="setindex.titlepage.recto"> + <div xsl:use-attribute-sets="setindex.titlepage.recto.style"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::setindex[1]"/> +</xsl:call-template></div> + <xsl:choose> + <xsl:when test="setindexinfo/subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="setindexinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="setindex.titlepage.verso"> +</xsl:template> + +<xsl:template name="setindex.titlepage.separator"> +</xsl:template> + +<xsl:template name="setindex.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="setindex.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="setindex.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="setindex.titlepage.before.recto"/> + <xsl:call-template name="setindex.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="setindex.titlepage.before.verso"/> + <xsl:call-template name="setindex.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="setindex.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="setindex.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="setindex.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="setindex.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="setindex.titlepage.recto.style"> +<xsl:apply-templates select="." mode="setindex.titlepage.recto.mode"/> +</div> +</xsl:template> + +<xsl:template name="sidebar.titlepage.recto"> + <xsl:choose> + <xsl:when test="sidebarinfo/title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="sidebarinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sidebarinfo/subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="sidebarinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="sidebar.titlepage.verso"> +</xsl:template> + +<xsl:template name="sidebar.titlepage.separator"> +</xsl:template> + +<xsl:template name="sidebar.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sidebar.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sidebar.titlepage"> + <div class="titlepage"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sidebar.titlepage.before.recto"/> + <xsl:call-template name="sidebar.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <div><xsl:copy-of select="$recto.content"/></div> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sidebar.titlepage.before.verso"/> + <xsl:call-template name="sidebar.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <div><xsl:copy-of select="$verso.content"/></div> + </xsl:if> + <xsl:call-template name="sidebar.titlepage.separator"/> + </div> +</xsl:template> + +<xsl:template match="*" mode="sidebar.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sidebar.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sidebar.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sidebar.titlepage.recto.style"> +<xsl:call-template name="formal.object.heading"> +<xsl:with-param name="object" select="ancestor-or-self::sidebar[1]"/> +</xsl:call-template> +</div> +</xsl:template> + +<xsl:template match="subtitle" mode="sidebar.titlepage.recto.auto.mode"> +<div xsl:use-attribute-sets="sidebar.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sidebar.titlepage.recto.mode"/> +</div> +</xsl:template> + +</xsl:stylesheet> + diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml new file mode 100644 index 0000000000..d0f0d113da --- /dev/null +++ b/documentation/yocto-project-qs/yocto-project-qs.xml @@ -0,0 +1,968 @@ +<!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; ] > + +<article id='intro'> + <articleinfo> + <title>Yocto Project Quick Start + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons. + + + For the latest version of this manual associated with this + Yocto Project release, see the + Yocto Project Quick Start + from the Yocto Project website. + + + + + + + + + +
+ Welcome! + + Welcome to the Yocto Project! + The Yocto Project is an open-source collaboration project focused on + embedded Linux developers. + Among other things, the Yocto Project uses a build system based on the + OpenEmbedded (OE) project, which uses the + BitBake + tool, to construct complete Linux images. + The BitBake and OE components are combined together to form + Poky, + a reference build system. + + + + If you don't have a system that runs Linux and you want to give the Yocto Project a test run, + you might consider using the Yocto Project Build Appliance. + The Build Appliance allows you to build and boot a custom embedded Linux image with the Yocto + Project using a non-Linux development system. + See the Yocto + Project Build Appliance for more information. + + + + On the other hand, if you know all about open-source development, Linux development environments, + Git source repositories and the like and you just want some quick information that lets you try out + the Yocto Project on your Linux system, skip right to the + "Super User" section at the end of this quick start. + + + + For the rest of you, this short document will give you some basic information about the environment and + let you experience it in its simplest form. + After reading this document, you will have a basic understanding of what the Yocto Project is + and how to use some of its core components. + This document steps you through a simple example showing you how to build a small image + and run it using the Quick EMUlator (QEMU emulator). + + + + For more detailed information on the Yocto Project, you should check out these resources: + + Website: The Yocto Project Website + provides the latest builds, breaking news, full development documentation, and a rich Yocto + Project Development Community into which you can tap. + + FAQs: Lists commonly asked Yocto Project questions and answers. + You can find two FAQs: Yocto Project FAQ on + a wiki, and the + "FAQ" chapter in + the Yocto Project Reference Manual. + + Developer Screencast: The + Getting Started with the Yocto Project - New Developer Screencast Tutorial + provides a 30-minute video created for users unfamiliar with + the Yocto Project but familiar with Linux build systems. + While this screencast is somewhat dated, the introductory + and fundamental concepts are useful for the beginner. + + + +
+ +
+ Introducing the Yocto Project Development Environment + + The Yocto Project through the OpenEmbedded build system provides an open source development + environment targeting the ARM, MIPS, PowerPC and x86 architectures for a variety of + platforms including x86-64 and emulated ones. + You can use components from the Yocto Project to design, develop, build, debug, simulate, + and test the complete software stack using Linux, the X Window System, GNOME Mobile-based + application frameworks, and Qt frameworks. + + + + + + + + The Yocto Project Development Environment + + + + + Here are some highlights for the Yocto Project: + + + + + Provides a recent Linux kernel along with a set of system commands and libraries suitable for the embedded environment. + + + Makes available system components such as X11, GTK+, Qt, Clutter, and SDL + (among others) so you can create a rich user experience on devices + that have display hardware. + For devices that do not have a display or where you wish to use alternative UI + frameworks, these components need not be installed. + + + Creates a focused and stable core compatible with the OpenEmbedded + project with which you can easily and reliably build and develop. + + + Fully supports a wide range of hardware and device emulation through the QEMU + Emulator. + + + + + The Yocto Project can generate images for many kinds of devices. + However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS, + and PPC-based architectures as well as specific hardware such as the + Intel Desktop Board DH55TC. + Because an image developed with the Yocto Project can boot inside a QEMU emulator, the + development environment works nicely as a test platform for developing embedded software. + + + + Another important Yocto Project feature is the Sato reference User Interface. + This optional GNOME mobile-based UI, which is intended for devices with + restricted screen sizes, sits neatly on top of a device using the + GNOME Mobile Stack and provides a well-defined user experience. + Implemented in its own layer, it makes it clear to developers how they can implement + their own user interface on top of a Linux image created with the Yocto Project. + +
+ +
+ What You Need and How You Get It + + + You need these things to develop projects in the Yocto Project + environment: + + + + + A host system with a minimum of 50 Gbytes of free disk space that + is running a supported Linux distribution (i.e. recent releases + of Fedora, openSUSE, CentOS, Debian, or Ubuntu). + If the host system supports multiple cores and threads, you can + configure the Yocto Project build system to significantly + decrease the time needed to build images. + + + Appropriate packages installed on the system you are using for + builds. + + + A release of the Yocto Project. + + + +
+ The Linux Distribution + + + The Yocto Project team is continually verifying more and more Linux + distributions with each release. + In general, if you have the current release minus one of the following + distributions you should have no problems. + + Ubuntu + Fedora + openSUSE + CentOS + Debian + + For a more detailed list of distributions that support the Yocto Project, + see the + "Supported Linux Distributions" section + in the Yocto Project Reference Manual. + + + The OpenEmbedded build system should be able to run on any modern + distribution that has the following versions for Git, tar, and + Python. + + Git 1.7.8 or greater + tar 1.24 or greater + Python 2.7.3 or greater excluding Python + 3.x, which is not supported. + + Earlier releases of Python are known to not work and the + system does not support Python 3 at this time. + If your system does not meet any of these three listed + version requirements, you can + take steps to prepare the system so that you can still use the build + system. + See the + "Required Git, tar, and Python Versions" + section in the Yocto Project Reference Manual for information. + + + This document assumes you are running one of the previously noted + distributions on your Linux-based host systems. + + + + If you attempt to use a distribution not in the above list, + you may or may not have success. + Yocto Project releases are tested against the stable Linux + distributions listed in the + "Supported Linux Distributions" + section of the Yocto Project Reference Manual. + If you encounter problems, please go to + Yocto Project Bugzilla + and submit a bug. + We are interested in hearing about your experience. + + +
+ +
+ The Packages + + + Packages and package installation vary depending on your development system + and on your intent. + For example, if you want to build an image that can run + on QEMU in graphical mode (a minimal, basic build + requirement), then the number of packages is different than if you want to + build an image on a headless system or build out the Yocto Project + documentation set. + Collectively, the number of required packages is large + if you want to be able to cover all cases. + In general, you need to have root access and then install the + required packages. + Thus, the commands in the following section may or may not work + depending on whether or not your Linux distribution has + sudo installed. + + + + The next few sections list, by supported Linux Distributions, the required + packages needed to build an image that runs on QEMU in graphical mode + (e.g. essential plus graphics support). + + + + For lists of required packages for other scenarios, see the + "Required Packages for the Host Development System" + section in the Yocto Project Reference Manual. + + +
+ Ubuntu and Debian + + + The essential and graphical support packages you need for a + supported Ubuntu or Debian distribution are shown in the + following command: + + $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm + + +
+ +
+ Fedora + + + The essential and graphical packages you need for a supported + Fedora distribution are shown in the following command: + + $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm + + +
+ +
+ OpenSUSE + + + The essential and graphical packages you need for a supported + OpenSUSE distribution are shown in the following command: + + $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm + + +
+ +
+ CentOS + + + The essential and graphical packages you need for a supported + CentOS distribution are shown in the following command: + + $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm + + Depending on the CentOS version you are using, other requirements + and dependencies might exist. + For details, you should look at the CentOS sections on the + Poky/GettingStarted/Dependencies + wiki page. + +
+
+ +
+ Yocto Project Release + + + It is recommended that you get the latest Yocto Project files + by setting up (cloning in + Git terms) a local + copy of the + poky Git repository on your host development + system. + Doing so allows you to contribute back to the Yocto Project project. + For information on how to get set up using this method, see the + "Yocto + Project Release" item in the Yocto Project Development Manual. + + + + You can also get the Yocto Project Files by downloading + Yocto Project releases from the + Yocto Project website. + From the website, you just click "Downloads" in the navigation pane + to the left to display all Yocto Project downloads. + Current and archived releases are available for download. + Nightly and developmental builds are also maintained at + . + However, for this document a released version of Yocto Project is used. + + +
+
+ +
+ A Quick Test Run + + + Now that you have your system requirements in order, you can give the Yocto Project a try. + This section presents some steps that let you do the following: + + + + + + Build an image and run it in the QEMU emulator. + + + + + Use a pre-built image and run it in the QEMU emulator. + + + + +
+ Building an Image + + + In the development environment you will need to build an image whenever you change hardware + support, add or change system libraries, or add or change services that have dependencies. + + + + + + + + Building an Image + + + + + Use the following commands to build your image. + The OpenEmbedded build process creates an entire Linux + distribution, including the toolchain, from source. + Note about Network Proxies + + By default, the build process searches for source code + using a pre-determined order through a set of locations. + If you are working behind a firewall and your build system + is not set up for proxies, you could encounter problems + with the build process when fetching source code (e.g. + fetcher failures or Git failures). + + + + If you do not know your proxy settings, consult your + local network infrastructure resources and get that + information. + A good starting point could also be to check your web + browser settings. + Finally, you can find more information on using the Yocto + Project behind a firewall in the Yocto Project Reference + Manual + FAQ + and on the + "Working Behind a Network Proxy" + wiki page. + + + + + + + $ git clone &YOCTO_GIT_URL;/git/poky + $ cd poky + $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; + $ source &OE_INIT_FILE; + + + + + + To help conserve disk space during builds, you can add the + following statement to your project's configuration file, + which for this example is + poky/build/conf/local.conf. + Adding this statement deletes the work directory used for + building a package once the package is built. + + INHERIT += "rm_work" + + + + + + In the previous example, the first command uses + Git to create + a local repository named poky that is a + clone of the upstream Yocto Project + poky repository. + The third command checks out a local branch and + names it &DISTRO_NAME;. + The local branch tracks the upstream branch of the same name. + Creating your own branch based on the released branch ensures + you are using the latest files for that release. + + + The final command runs the Yocto Project + &OE_INIT_FILE; + environment setup script. + Running this script defines OpenEmbedded build environment + settings needed to complete the build. + The script also creates the + Build Directory, + which is build in this case and is located + in the + Source Directory. + After the script runs, your current working directory is set + to the Build Directory. + Later, when the build completes, the Build Directory contains + all the files created during the build. + + For information on running a memory-resident + BitBake, + see the + oe-init-build-env-memres + setup script. + + + + Take some time to examine your local.conf file + in your project's configuration directory, which is found in the Build Directory. + The defaults in that file should work fine. + However, there are some variables of interest at which you might look. + + + + By default, the target architecture for the build is qemux86, + which produces an image that can be used in the QEMU emulator and is targeted at an + Intel 32-bit based architecture. + To change this default, edit the value of the + MACHINE + variable in the configuration file before launching the build. + + + + Another couple of variables of interest are the + BB_NUMBER_THREADS and the + PARALLEL_MAKE variables. + By default, these variables are set to the number of processor + cores your build host uses. + However, if your build host uses multiple processor cores, + you should increase these settings to twice the number of + cores used. + Doing so can significantly shorten your build time. + + + + Another consideration before you build is the package manager used when creating + the image. + By default, the OpenEmbedded build system uses the RPM package manager. + You can control this configuration by using the + PACKAGE_CLASSES variable. + For additional package manager selection information, see the + "package*.bbclass" + section in the Yocto Project Reference Manual. + + + + Continue with the following command to build an OS image for the target, which is + core-image-sato in this example. + For information on the -k option use the + bitbake --help command, see the + "BitBake" + section in the Yocto Project Reference Manual, or see the + "BitBake Command" + section in the BitBake User Manual. + + $ bitbake -k core-image-sato + + + BitBake requires Python 2.6 or 2.7. For more information on + this requirement, see the + "Required Git, tar, and Python" + section in the Yocto Project Reference Manual. + + The final command runs the image using the QEMU emulator: + + $ runqemu qemux86 + + + + Depending on the number of processors and cores, the amount + of RAM, the speed of your Internet connection and other + factors, the build process could take several hours the + first time you run it. + Subsequent builds run much faster since parts of the build + are cached. + + + +
+ +
+ Using Pre-Built Binaries and QEMU + + + If hardware, libraries and services are stable, you can get started by using a pre-built binary + of the filesystem image, kernel, and toolchain and run it using the QEMU emulator. + This scenario is useful for developing application software. + + + + + + + + Using a Pre-Built Image + + + + + For this scenario, you need to do several things: + + + + Install the appropriate stand-alone toolchain tarball. + Download the pre-built image that will boot with QEMU. + You need to be sure to get the QEMU image that matches your target machine’s + architecture (e.g. x86, ARM, etc.). + Download the filesystem image for your target machine's architecture. + + Set up the environment to emulate the hardware and then start the QEMU emulator. + + + +
+ Installing the Toolchain + + + You can download a tarball installer, which includes the + pre-built toolchain, the runqemu + script, and support files from the appropriate directory under + . + Toolchains are available for 32-bit and 64-bit x86 development + systems from the i686 and + x86_64 directories, respectively. + The toolchains the Yocto Project provides are based off the + core-image-sato image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. + + + + 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. + + + + poky-glibc-host_system-image_type-arch-toolchain-release_version.sh + + Where: + host_system is a string representing your development system: + + i686 or x86_64. + + image_type is a string representing the image you wish to + develop a Software Development Toolkit (SDK) for use against. + The Yocto Project builds toolchain installers using the + following BitBake command: + + bitbake core-image-sato -c populate_sdk + + arch is a string representing the tuned target architecture: + + i586, x86_64, powerpc, mips, armv7a or armv5te + + release_version is a string representing the release number of the + Yocto Project: + + &DISTRO;, &DISTRO;+snapshot + + + + 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 core-image-sato: + + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + + + + + Toolchains are self-contained and by default are installed into + /opt/poky. + However, when you run the toolchain installer, you can choose an + installation directory. + + + + 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. + You must change the permissions on the toolchain + installer script so that it is executable. + + + + The example assumes the toolchain installer is located in ~/Downloads/. + + If you do not have write permissions for the directory into which you are installing + the toolchain, the toolchain installer notifies you and exits. + Be sure you have write permissions in the directory and run the installer again. + + + + + + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + + + + + For more information on how to install tarballs, see the + "Using a Cross-Toolchain Tarball" and + "Using BitBake and the Build Directory" sections in the Yocto Project Application Developer's Guide. + +
+ +
+ Downloading the Pre-Built Linux Kernel + + + You can download the pre-built Linux kernel suitable for running in the QEMU emulator from + . + Be sure to use the kernel that matches the architecture you want to simulate. + Download areas exist for the five supported machine architectures: + qemuarm, qemumips, qemuppc, + qemux86, and qemux86-64. + + + + Most kernel files have one of the following forms: + + *zImage-qemuarch.bin + vmlinux-qemuarch.bin + + Where: + arch is a string representing the target architecture: + x86, x86-64, ppc, mips, or arm. + + + + + You can learn more about downloading a Yocto Project kernel in the + "Yocto Project Kernel" + bulleted item in the Yocto Project Development Manual. + +
+ +
+ Downloading the Filesystem + + + You can also download the filesystem image suitable for your target architecture from + . + Again, be sure to use the filesystem that matches the architecture you want + to simulate. + + + + The filesystem image has two tarball forms: ext3 and + tar. + You must use the ext3 form when booting an image using the + QEMU emulator. + The tar form can be flattened out in your host development system + and used for build purposes with the Yocto Project. + + core-image-profile-qemuarch.ext3 + core-image-profile-qemuarch.tar.bz2 + + Where: + profile is the filesystem image's profile: + lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, + sato-dev, or sato-sdk. For information on these types of image + profiles, see the "Images" + chapter in the Yocto Project Reference Manual. + + arch is a string representing the target architecture: + x86, x86-64, ppc, mips, or arm. + + +
+ +
+ Setting Up the Environment and Starting the QEMU Emulator + + + Before you start the QEMU emulator, you need to set up the emulation environment. + The following command form sets up the emulation environment. + + $ source &YOCTO_ADTPATH_DIR;/environment-setup-arch-poky-linux-if + + Where: + arch is a string representing the target architecture: + i586, x86_64, ppc603e, mips, or armv5te. + + if is a string representing an embedded application binary interface. + Not all setup scripts include this string. + + + + + Finally, this command form invokes the QEMU emulator + + $ runqemu qemuarch kernel-image filesystem-image + + Where: + qemuarch is a string representing the target architecture: qemux86, qemux86-64, + qemuppc, qemumips, or qemuarm. + + kernel-image is the architecture-specific kernel image. + + filesystem-image is the .ext3 filesystem image. + + + + + + Continuing with the example, the following two commands setup the emulation + environment and launch QEMU. + This example assumes the root filesystem (.ext3 file) and + the pre-built kernel image file both reside in your home directory. + The kernel and filesystem are for a 32-bit target architecture. + + $ cd $HOME + $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux + $ runqemu qemux86 bzImage-qemux86.bin \ + core-image-sato-qemux86.ext3 + + + + + The environment in which QEMU launches varies depending on the filesystem image and on the + target architecture. + For example, if you source the environment for the ARM target + architecture and then boot the minimal QEMU image, the emulator comes up in a new + shell in command-line mode. + However, if you boot the SDK image, QEMU comes up with a GUI. + Booting the PPC image results in QEMU launching in the same shell in + command-line mode. + +
+
+
+ +
+ Super User + + + + This section + + + Kudos and thanks to Robert P. J. Day of + CrashCourse for providing the basis + for this "expert" section with information from one of his + wiki + pages. + + + gives you a minimal description of how to use the Yocto Project to build + images for Beaglebone hardware starting from scratch. + The steps were performed on a 64-bit Ubuntu 12.04 system that + has four cores. + + +
+ Getting the Yocto Project + + + Set up your + Source Directory + by using Git to clone the poky + repository and then check out the release branch: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; + + +
+ +
+ Setting Up Your Host + + + You need some packages for everything to work. + Rather than duplicate them here, look at the + "The Packages" + section earlier in this quick start. + +
+ +
+ Initializing the Build Environment + + + From the root directory of your + Source Directory, + initialize your environment and provide a meaningful + Build Directory + name: + + $ source &OE_INIT_FILE; mybuilds + + At this point, the mybuilds directory has + been created for you and it is now your current working directory. + If you do not provide your own directory name, + it defaults to build, + which is inside the Source Directory. + +
+ +
+ Configuring the local.conf File + + + Initializing the build environment creates a + conf/local.conf configuration file + in the Build Directory. + You need to manually edit this file to specify the machine you + are building and to optimize your build time. + Here are the minimal changes to make: + + BB_NUMBER_THREADS = "8" + PARALLEL_MAKE = "-j 8" + MACHINE ?= "beaglebone" + + Briefly, set + BB_NUMBER_THREADS + and + PARALLEL_MAKE to + twice your host processor's number of cores. + + + + A good deal that goes into a Yocto Project build is simply + downloading all of the source tarballs. + Steps exist that can help you be more efficient with gathering + source files. + For example, you can set up local mirrors that hold your + source tarballs or you can pre-fetch all your source without + initiating a build until later. + For more information, see the + "Working with Source Files" + section in the Yocto Project Development Manual. + +
+ +
+ Building the Image + + + At this point, you need to select an image to build for the + Beaglebone hardware. + If this is your first build using the Yocto Project, you should try + the smallest and simplest image: + + $ bitbake core-image-minimal + + Now you just wait for the build to finish. + + + + By default, BitBake aborts when it encounters an error during + the build. + If you want to make sure the build continues even when BitBake + encounters an error, use this variation: + + $ bitbake -k core-image-minimal + + + + + Once you have your image, you can take steps to load and boot it on + the target hardware. + + + + You can learn about BitBake in general by reading the + BitBake User Manual. + +
+
+ + + -- cgit v1.2.3-54-g00ecf