diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 1173 |
1 files changed, 691 insertions, 482 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 524c607855..7a28176ce0 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -273,29 +273,17 @@ the included file, use the path relative to the original layer directory to refer to the file. For example, use - <filename>require recipes-core/somepackage/somefile.inc</filename> - instead of <filename>require somefile.inc</filename>. + <filename>require recipes-core/</filename><replaceable>package</replaceable><filename>/</filename><replaceable>file</replaceable><filename>.inc</filename> + instead of <filename>require </filename><replaceable>file</replaceable><filename>.inc</filename>. If you're finding you have to overlay the include file, it could indicate a deficiency in the include file in the layer to which it originally belongs. - If this is the case, you need to address that deficiency - instead of overlaying the include file. - </para> - - <para> - For example, consider how support plug-ins for the Qt 4 - database are configured. - The Source Directory does not have MySQL or PostgreSQL. - However, OpenEmbedded's layer <filename>meta-oe</filename> - does. - Consequently, <filename>meta-oe</filename> uses - append files to modify the - <filename>QT_SQL_DRIVER_FLAGS</filename> variable to - enable the appropriate plug-ins. - This variable was added to the <filename>qt4.inc</filename> - include file in the Source Directory specifically to allow - the <filename>meta-oe</filename> layer to be able to control - which plug-ins are built. + If this is the case, you should try to address that + deficiency instead of overlaying the include file. + For example, you could address this by getting the + maintainer of the include file to add a variable or + variables to make it easy to override the parts needing + to be overridden. </para> </section> @@ -460,11 +448,6 @@ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-yocto \ - " </literallayout> </para> @@ -567,8 +550,8 @@ <para> Following is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the - Crown Bay BSP Layer named - <filename>meta-intel/meta-crownbay</filename>. + Emenlow BSP Layer named + <filename>meta-intel/meta-emenlow</filename>. The file is in <filename>recipes-bsp/formfactor</filename>: <literallayout class='monospaced'> FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -594,7 +577,7 @@ which resolves to a directory named <filename>formfactor</filename> in the same directory in which the append file resides (i.e. - <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>. + <filename>meta-intel/meta-emenlow/recipes-bsp/formfactor/formfactor</filename>. This implies that you must have the supporting directory structure set up that will contain any files or patches you will be including from the layer. @@ -611,16 +594,18 @@ BitBake automatically defines the <filename>THISDIR</filename> variable. You should never set this variable yourself. - Using "_prepend" ensures your path will - be searched prior to other paths in the final list. + Using "_prepend" as part of the + <filename>FILESEXTRAPATHS</filename> ensures your path + will be searched prior to other paths in the final + list. </para> <para> Also, not all append files add extra files. Many append files simply exist to add build options (e.g. <filename>systemd</filename>). - For these cases, it is not necessary to use the - "_prepend" part of the statement. + For these cases, your append file would not even + use the <filename>FILESEXTRAPATHS</filename> statement. </para> </note> </para> @@ -705,6 +690,12 @@ Lists dependency relationships between recipes that cross layer boundaries. </para></listitem> + <listitem><para><filename><emphasis>add-layer:</emphasis></filename> + Adds a layer to <filename>bblayers.conf</filename>. + </para></listitem> + <listitem><para><filename><emphasis>remove-layer:</emphasis></filename> + Removes a layer from <filename>bblayers.conf</filename> + </para></listitem> <listitem><para><filename><emphasis>flatten:</emphasis></filename> Flattens the layer configuration into a separate output directory. @@ -745,13 +736,13 @@ ... DESCRIPTION = "A useful utility" ... - EXTRA_OECONF = "‐‐enable-something" + EXTRA_OECONF = "--enable-something" ... #### bbappended from meta-anotherlayer #### DESCRIPTION = "Customized utility" - EXTRA_OECONF += "‐‐enable-somethingelse" + EXTRA_OECONF += "--enable-somethingelse" </literallayout> Ideally, you would tidy up these utilities as follows: @@ -759,7 +750,7 @@ ... DESCRIPTION = "Customized utility" ... - EXTRA_OECONF = "‐‐enable-something ‐‐enable-somethingelse" + EXTRA_OECONF = "--enable-something --enable-somethingelse" ... </literallayout></para></listitem> </itemizedlist></para></listitem> @@ -883,11 +874,6 @@ /usr/local/src/yocto/meta-yocto-bsp \ /usr/local/src/yocto/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ - " </literallayout> Adding the layer to this file enables the build system to locate the layer during the build. @@ -990,11 +976,20 @@ <para> To understand how these features work, the best reference is <filename>meta/classes/core-image.bbclass</filename>. + This class lists out the available + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> + of which most map to package groups while some, such as + <filename>debug-tweaks</filename> and + <filename>read-only-rootfs</filename>, resolve as general + configuration settings. + </para> + + <para> In summary, the file looks at the contents of the <filename>IMAGE_FEATURES</filename> variable and then maps - those contents into a set of package groups. + or configures the feature accordingly. Based on this information, the build system automatically - adds the appropriate packages to the + adds the appropriate packages or configurations to the <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> variable. Effectively, you are enabling extra features by extending the @@ -1071,7 +1066,7 @@ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename> variable. You must use the OpenEmbedded notation and not the Debian notation for the names - (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>). + (e.g. <filename>glibc-dev</filename> instead of <filename>libc6-dev</filename>). </para> <para> @@ -1094,18 +1089,27 @@ an image is to create a custom package group recipe that is used to build the image or images. A good example of a package group recipe is - <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>. - The + <filename>meta/recipes-core/packagegroups/packagegroup-base.bb</filename>. + </para> + + <para> + If you examine that recipe, you see that the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> - variable lists the package group packages you wish to produce. - <filename>inherit packagegroup</filename> sets appropriate - default values and automatically adds <filename>-dev</filename>, - <filename>-dbg</filename>, and <filename>-ptest</filename> - complementary packages for every package specified in - <filename>PACKAGES</filename>. - Note that the inherit line should be towards - the top of the recipe, certainly before you set - <filename>PACKAGES</filename>. + variable lists the package group packages to produce. + The <filename>inherit packagegroup</filename> statement + sets appropriate default values and automatically adds + <filename>-dev</filename>, <filename>-dbg</filename>, and + <filename>-ptest</filename> complementary packages for each + package specified in the <filename>PACKAGES</filename> + statement. + <note> + The <filename>inherit packages</filename> should be + located near the top of the recipe, certainly before + the <filename>PACKAGES</filename> statement. + </note> + </para> + + <para> For each package you specify in <filename>PACKAGES</filename>, you can use <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename> @@ -1113,7 +1117,13 @@ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename> entries to provide a list of packages the parent task package should contain. - Following is an example: + You can see examples of these further down in the + <filename>packagegroup-base.bb</filename> recipe. + </para> + + <para> + Here is a short, fabricated example showing the same basic + pieces: <literallayout class='monospaced'> DESCRIPTION = "My Custom Package Groups" @@ -1132,8 +1142,7 @@ RDEPENDS_packagegroup-custom-tools = "\ oprofile \ oprofileui-server \ - lttng-control \ - lttng-viewer" + lttng-tools" RRECOMMENDS_packagegroup-custom-tools = "\ kernel-module-oprofile" @@ -1151,6 +1160,63 @@ For other forms of image dependencies see the other areas of this section. </para> </section> + + <section id='usingpoky-extend-customimage-image-name'> + <title>Customizing an Image Hostname</title> + + <para> + By default, the configured hostname (i.e. + <filename>/etc/hostname</filename>) in an image is the + same as the machine name. + For example, if + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + equals "qemux86", the configured hostname written to + <filename>/etc/hostname</filename> is "qemux86". + </para> + + <para> + You can customize this name by altering the value of the + "hostname" variable in the + <filename>base-files</filename> recipe using either + an append file or a configuration file. + Use the following in an append file: + <literallayout class='monospaced'> + hostname="myhostname" + </literallayout> + Use the following in a configuration file: + <literallayout class='monospaced'> + hostname_pn-base-files = "myhostname" + </literallayout> + </para> + + <para> + Changing the default value of the variable "hostname" can be + useful in certain situations. + For example, suppose you need to do extensive testing on an + image and you would like to easily identify the image + under test from existing images with typical default + hostnames. + In this situation, you could change the default hostname to + "testme", which results in all the images using the name + "testme". + Once testing is complete and you do not need to rebuild the + image for test any longer, you can easily reset the default + hostname. + </para> + + <para> + Another point of interest is that if you unset the variable, + the image will have no default hostname in the filesystem. + Here is an example that unsets the variable in a + configuration file: + <literallayout class='monospaced'> + hostname_pn-base-files = "" + </literallayout> + Having no default hostname in the filesystem is suitable for + environments that use dynamic hostnames such as virtual + machines. + </para> + </section> </section> <section id='new-recipe-writing-a-new-recipe'> @@ -1182,61 +1248,167 @@ </para> </section> - <section id='new-recipe-locate-a-base-recipe'> - <title>Locate a Base Recipe</title> + <section id='new-recipe-locate-or-automatically-create-a-base-recipe'> + <title>Locate or Automatically Create a Base Recipe</title> <para> - Before writing a recipe from scratch, it is often useful to - discover whether someone else has already written one that - meets (or comes close to meeting) your needs. - The Yocto Project and OpenEmbedded communities maintain many - recipes that might be candidates for what you are doing. - You can find a good central index of these recipes in the - <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>. + You can always write a recipe from scratch. + However, two choices exist that can help you quickly get a + start on a new recipe: + <itemizedlist> + <listitem><para><emphasis><filename>recipetool</filename>:</emphasis> + A tool provided by the Yocto Project that automates + creation of a base recipe based on the source + files. + </para></listitem> + <listitem><para><emphasis>Existing Recipes:</emphasis> + Location and modification of an existing recipe that is + similar in function to the recipe you need. + </para></listitem> + </itemizedlist> </para> - <para> - Working from an existing recipe or a skeleton recipe is the - best way to get started. - Here are some points on both methods: - <itemizedlist> - <listitem><para><emphasis>Locate and modify a recipe that - is close to what you want to do:</emphasis> - This method works when you are familiar with the - current recipe space. - The method does not work so well for those new to - the Yocto Project or writing recipes.</para> - <para>Some risks associated with this method are - using a recipe that has areas totally unrelated to - what you are trying to accomplish with your recipe, - not recognizing areas of the recipe that you might - have to add from scratch, and so forth. - All these risks stem from unfamiliarity with the - existing recipe space.</para></listitem> - <listitem><para><emphasis>Use and modify the following - skeleton recipe:</emphasis> - <literallayout class='monospaced'> - SUMMARY = "" + <section id='new-recipe-creating-the-base-recipe-using-recipetool'> + <title>Creating the Base Recipe Using <filename>recipetool</filename></title> + + <para> + <filename>recipetool</filename> automates creation of + a base recipe given a set of source code files. + As long as you can extract or point to the source files, + the tool will construct a recipe and automatically + configure all pre-build information into the recipe. + For example, suppose you have an application that builds + using Autotools. + Creating the base recipe using + <filename>recipetool</filename> results in a recipe + that has the pre-build dependencies, license requirements, + and checksums configured. + </para> + + <para> + To run the tool, you just need to be in your + <link linkend='build-directory'>Build Directory</link> + and have sourced the build environment setup script + (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). + Here is the basic <filename>recipetool</filename> syntax: + <note> + Running <filename>recipetool -h</filename> or + <filename>recipetool create -h</filename> produces the + Python-generated help, which presented differently + than what follows here. + </note> + <literallayout class='monospaced'> + recipetool -h + recipetool create [-h] + recipetool [-d] [-q] [--color auto | always | never ] create -o <replaceable>OUTFILE</replaceable> [-m] [-x <replaceable>EXTERNALSRC</replaceable>] <replaceable>source</replaceable> + + -d Enables debug output. + -q Outputs only errors (quiet mode). + --color Colorizes the output automatically, always, or never. + -h Displays Python generated syntax for recipetool. + create Causes recipetool to create a base recipe. The create + command is further defined with these options: + + -o <replaceable>OUTFILE</replaceable> Specifies the full path and filename for the generated + recipe. + -m Causes the recipe to be machine-specific rather than + architecture-specific (default). + -x <replaceable>EXTERNALSRC</replaceable> Fetches and extracts source files from <replaceable>source</replaceable> + and places them in <replaceable>EXTERNALSRC</replaceable>. + <replaceable>source</replaceable> must be a URL. + -h Displays Python-generated syntax for create. + <replaceable>source</replaceable> Specifies the source code on which to base the + recipe. + </literallayout> + </para> + + <para> + Running <filename>recipetool create -o</filename> <replaceable>OUTFILE</replaceable> + creates the base recipe and locates it properly in the + layer that contains your source files. + Following are some syntax examples: + </para> + + <para> + Use this syntax to generate a recipe based on <replaceable>source</replaceable>. + Once generated, the recipe resides in the existing source + code layer: + <literallayout class='monospaced'> + recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable> + </literallayout> + Use this syntax to generate a recipe using code that you + extract from <replaceable>source</replaceable>. + The extracted code is placed in its own layer defined + by <replaceable>EXTERNALSRC</replaceable>. + <literallayout class='monospaced'> + recipetool create -o <replaceable>OUTFILE</replaceable> -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable> + </literallayout> + Use this syntax to generate a recipe based on <replaceable>source</replaceable>. + The options direct <filename>recipetool</filename> to + run in "quiet mode" and to generate debugging information. + Once generated, the recipe resides in the existing source + code layer: + <literallayout class='monospaced'> + recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable> + </literallayout> + </para> + </section> + + <section id='new-recipe-locating-and-using-a-similar-recipe'> + <title>Locating and Using a Similar Recipe</title> + + <para> + Before writing a recipe from scratch, it is often useful to + discover whether someone else has already written one that + meets (or comes close to meeting) your needs. + The Yocto Project and OpenEmbedded communities maintain many + recipes that might be candidates for what you are doing. + You can find a good central index of these recipes in the + <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>. + </para> + + <para> + Working from an existing recipe or a skeleton recipe is the + best way to get started. + Here are some points on both methods: + <itemizedlist> + <listitem><para><emphasis>Locate and modify a recipe that + is close to what you want to do:</emphasis> + This method works when you are familiar with the + current recipe space. + The method does not work so well for those new to + the Yocto Project or writing recipes.</para> + <para>Some risks associated with this method are + using a recipe that has areas totally unrelated to + what you are trying to accomplish with your recipe, + not recognizing areas of the recipe that you might + have to add from scratch, and so forth. + All these risks stem from unfamiliarity with the + existing recipe space.</para></listitem> + <listitem><para><emphasis>Use and modify the following + skeleton recipe:</emphasis> + If for some reason you do not want to use + <filename>recipetool</filename> and you cannot + find an existing recipe that is close to meeting + your needs, you can use the following structure to + provide the fundamental areas of a new recipe. + <literallayout class='monospaced'> + DESCRIPTION = "" HOMEPAGE = "" LICENSE = "" - + SECTION = "" + DEPENDS = "" LIC_FILES_CHKSUM = "" SRC_URI = "" - SRC_URI[md5sum] = "" - SRC_URI[sha256sum] = "" - - S = "${WORKDIR}/${PN}-${PV}" - - inherit <replaceable>stuff</replaceable> - </literallayout> - Modifying this recipe is the recommended method for - creating a new recipe. - The recipe provides the fundamental areas that you need - to include, exclude, or alter to fit your needs. - </para></listitem> - </itemizedlist> - </para> + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> </section> <section id='new-recipe-storing-and-naming-the-recipe'> @@ -1810,8 +1982,9 @@ <para> If no <filename>SRC_URI</filename> checksums are specified - when you attempt to build the recipe, the build will produce - an error for each missing checksum. + when you attempt to build the recipe, or you provide an + incorrect checksum, the build will produce an error for each + missing or incorrect checksum. As part of the error message, the build system provides the checksum string corresponding to the fetched file. Once you have the correct checksums, you can copy and paste @@ -1858,8 +2031,11 @@ <para> The previous example also specifies a patch file. - Patch files are files whose names end in - <filename>.patch</filename> or <filename>.diff</filename>. + Patch files are files whose names usually end in + <filename>.patch</filename> or <filename>.diff</filename> but + can end with compressed suffixes such as + <filename>diff.gz</filename> and + <filename>patch.bz2</filename>, for example. The build system automatically applies patches as described in the "<link linkend='new-recipe-patching-code'>Patching Code</link>" section. @@ -1905,7 +2081,9 @@ fetched. Any files mentioned in <filename>SRC_URI</filename> whose names end in <filename>.patch</filename> or - <filename>.diff</filename> are treated as patches. + <filename>.diff</filename> or compressed versions of these + suffixes (e.g. <filename>diff.gz</filename> are treated as + patches. The <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> task automatically applies these patches. @@ -1929,7 +2107,9 @@ using <filename>file://</filename>, you should place patch files in a directory next to the recipe either named the same as the base name of the recipe - (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>), + (<ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>) or "files". </para> </section> @@ -2142,7 +2322,7 @@ configure script with the appropriate options.</para> <para>For the case involving a custom configure script, you would run - <filename>./configure ‐‐help</filename> and look for + <filename>./configure --help</filename> and look for the options you need to set.</para></listitem> </itemizedlist> </para> @@ -2165,7 +2345,7 @@ configure script as needed. For reference information on configure options specific to the software you are building, you can consult the output of the - <filename>./configure ‐‐help</filename> command within + <filename>./configure --help</filename> command within <filename>${S}</filename> or consult the software's upstream documentation. </para> @@ -2630,7 +2810,6 @@ A post-installation function has the following structure: <literallayout class='monospaced'> pkg_postinst_PACKAGENAME() { - #!/bin/sh -e # Commands to carry out } </literallayout> @@ -2653,7 +2832,6 @@ structure in the post-installation script: <literallayout class='monospaced'> pkg_postinst_PACKAGENAME() { - #!/bin/sh -e if [ x"$D" = "x" ]; then # Actions to carry out on the device go here else @@ -2889,11 +3067,10 @@ <literallayout class='monospaced'> require xorg-lib-common.inc - SUMMARY = "X11 Pixmap library" - LICENSE = "X-BSD" - LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" + SUMMARY = "Xpm: X Pixmap extension library" + LICENSE = "BSD" + LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" DEPENDS += "libxext libsm libxt" - PR = "r3" PE = "1" XORG_PN = "libXpm" @@ -3027,7 +3204,7 @@ <note> Although well within the capabilities of the Yocto Project, adding a totally new architecture might require - changes to <filename>gcc/eglibc</filename> and to the site + changes to <filename>gcc/glibc</filename> and to the site information, which is beyond the scope of this manual. </note> </para> @@ -3611,12 +3788,6 @@ development host system. </para></listitem> <listitem><para> - The - <ulink url='http://www.gnu.org/software/parted/'>GNU Parted</ulink> - package must be installed on your development host - system. - </para></listitem> - <listitem><para> You need to have the build artifacts already available, which typically means that you must have already created an image using the @@ -3629,6 +3800,12 @@ in the form generated by the build system. </para></listitem> <listitem><para> + You must build several native tools: + <literallayout class='monospaced'> + $ bitbake parted-native dosfstools-native mtools-native + </literallayout> + </para></listitem> + <listitem><para> You must have sourced one of the build environment setup scripts (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> @@ -3650,7 +3827,7 @@ or by entering the command with a help argument as follows: <literallayout class='monospaced'> $ wic -h - $ wic ‐‐help + $ wic --help </literallayout> </para> @@ -3666,7 +3843,7 @@ <para> You can also get detailed help on a number of topics from the help system. - The output of <filename>wic ‐‐help</filename> + The output of <filename>wic --help</filename> displays a list of available help topics under a "Help topics" heading. You can have the help system display the help text for @@ -3736,38 +3913,38 @@ your own custom file or use a file from a set of existing files as described by further options. - -o <replaceable>OUTDIR</replaceable>, ‐‐outdir=<replaceable>OUTDIR</replaceable> + -o <replaceable>OUTDIR</replaceable>, --outdir=<replaceable>OUTDIR</replaceable> The name of a directory in which to create image. - -i <replaceable>PROPERTIES_FILE</replaceable>, ‐‐infile=<replaceable>PROPERTIES_FILE</replaceable> + -i <replaceable>PROPERTIES_FILE</replaceable>, --infile=<replaceable>PROPERTIES_FILE</replaceable> The name of a file containing the values for image properties as a JSON file. - -e <replaceable>IMAGE_NAME</replaceable>, ‐‐image-name=<replaceable>IMAGE_NAME</replaceable> + -e <replaceable>IMAGE_NAME</replaceable>, --image-name=<replaceable>IMAGE_NAME</replaceable> The name of the image from which to use the artifacts (e.g. <filename>core-image-sato</filename>). - -r <replaceable>ROOTFS_DIR</replaceable>, ‐‐rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> + -r <replaceable>ROOTFS_DIR</replaceable>, --rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> The path to the <filename>/rootfs</filename> directory to use as the <filename>.wks</filename> rootfs source. - -b <replaceable>BOOTIMG_DIR</replaceable>, ‐‐bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> + -b <replaceable>BOOTIMG_DIR</replaceable>, --bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> The path to the directory containing the boot artifacts (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg source. - -k <replaceable>KERNEL_DIR</replaceable>, ‐‐kernel-dir=<replaceable>KERNEL_DIR</replaceable> + -k <replaceable>KERNEL_DIR</replaceable>, --kernel-dir=<replaceable>KERNEL_DIR</replaceable> The path to the directory containing the kernel to use in the <filename>.wks</filename> boot image. - -n <replaceable>NATIVE_SYSROOT</replaceable>, ‐‐native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> + -n <replaceable>NATIVE_SYSROOT</replaceable>, --native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> The path to the native sysroot containing the tools to use to build the image. - -s, ‐‐skip-build-check + -s, --skip-build-check Skips the build check. - -D, ‐‐debug + -D, --debug Output debug information. </literallayout> <note> @@ -3977,13 +4154,13 @@ </literallayout> Next, the example modifies the <filename>directdisksdb.wks</filename> file and changes all - instances of "<filename>‐‐ondisk sda</filename>" - to "<filename>‐‐ondisk sdb</filename>". + instances of "<filename>--ondisk sda</filename>" + to "<filename>--ondisk sdb</filename>". The example changes the following two lines and leaves the remaining lines untouched: <literallayout class='monospaced'> - part /boot ‐‐source bootimg-pcbios ‐‐ondisk sdb ‐‐label boot ‐‐active ‐‐align 1024 - part / ‐‐source rootfs ‐‐ondisk sdb ‐‐fstype=ext3 ‐‐label platform ‐‐align 1024 + part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 + part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 </literallayout> Once the lines are changed, the example generates the <filename>directdisksdb</filename> image. @@ -4070,11 +4247,11 @@ somewhere other than the default <filename>/var/tmp/wic</filename> directory: <literallayout class='monospaced'> - $ wic create ~/test.wks -o /home/trz/testwic ‐‐rootfs-dir \ + $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ - ‐‐bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ - ‐‐kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ - ‐‐native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + --bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ + --kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ + --native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux Creating image(s)... @@ -4117,7 +4294,7 @@ partitions. The plugins provide a mechanism for mapping values specified in <filename>.wks</filename> files using the - <filename>‐‐source</filename> keyword to a + <filename>--source</filename> keyword to a particular plugin implementation that populates a corresponding partition. </para> @@ -4146,11 +4323,11 @@ When the <filename>wic</filename> implementation needs to invoke a partition-specific implementation, it looks for the plugin that has the same name as the - <filename>‐‐source</filename> parameter given to + <filename>--source</filename> parameter given to that partition. For example, if the partition is set up as follows: <literallayout class='monospaced'> - part /boot ‐‐source bootimg-pcbios ... + part /boot --source bootimg-pcbios ... </literallayout> The methods defined as class members of the plugin having the matching <filename>bootimg-pcbios.name</filename> @@ -4160,7 +4337,7 @@ <para> To be more concrete, here is the plugin definition that matches a - <filename>‐‐source bootimg-pcbios</filename> usage, + <filename>--source bootimg-pcbios</filename> usage, along with an example method called by the <filename>wic</filename> implementation when it needs to invoke an implementation-specific @@ -4182,7 +4359,7 @@ The <filename>SourcePlugin</filename> class defines the following methods, which is the current set of methods that can be implemented or overridden by - <filename>‐‐source</filename> plugins. + <filename>--source</filename> plugins. Any methods not implemented by a <filename>SourcePlugin</filename> subclass inherit the implementations present in the @@ -4314,13 +4491,13 @@ <para> Following are the supported options: <itemizedlist> - <listitem><para><emphasis><filename>‐‐size</filename>:</emphasis> + <listitem><para><emphasis><filename>--size</filename>:</emphasis> The minimum partition size in MBytes. Specify an integer value such as 500. Do not append the number with "MB". You do not need this option if you use - <filename>‐‐source</filename>.</para></listitem> - <listitem><para><emphasis><filename>‐‐source</filename>:</emphasis> + <filename>--source</filename>.</para></listitem> + <listitem><para><emphasis><filename>--source</filename>:</emphasis> This option is a <filename>wic</filename>-specific option that names the source of the data that populates @@ -4332,7 +4509,7 @@ "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" section.</para> <para>If you use - <filename>‐‐source rootfs</filename>, + <filename>--source rootfs</filename>, <filename>wic</filename> creates a partition as large as needed and to fill it with the contents of the root filesystem pointed to by the @@ -4342,14 +4519,14 @@ option. The filesystem type used to create the partition is driven by the value of the - <filename>‐‐fstype</filename> option + <filename>--fstype</filename> option specified for the partition. See the entry on - <filename>‐‐fstype</filename> that + <filename>--fstype</filename> that follows for more information. </para> <para>If you use - <filename>‐‐source <replaceable>plugin-name</replaceable></filename>, + <filename>--source <replaceable>plugin-name</replaceable></filename>, <filename>wic</filename> creates a partition as large as needed and fills it with the contents of the partition that is generated by the @@ -4362,10 +4539,10 @@ filesystem type end up being are dependent on the given plugin implementation. </para></listitem> - <listitem><para><emphasis><filename>‐‐ondisk</filename> or <filename>‐‐ondrive</filename>:</emphasis> + <listitem><para><emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> Forces the partition to be created on a particular disk.</para></listitem> - <listitem><para><emphasis><filename>‐‐fstype</filename>:</emphasis> + <listitem><para><emphasis><filename>--fstype</filename>:</emphasis> Sets the file system type for the partition. Valid values are: <itemizedlist> @@ -4382,7 +4559,7 @@ <listitem><para><filename>swap</filename> </para></listitem> </itemizedlist></para></listitem> - <listitem><para><emphasis><filename>‐‐fsoptions</filename>:</emphasis> + <listitem><para><emphasis><filename>--fsoptions</filename>:</emphasis> Specifies a free-form string of options to be used when mounting the filesystem. This string will be copied into the @@ -4392,15 +4569,15 @@ If not specified, the default string is "defaults". </para></listitem> - <listitem><para><emphasis><filename>‐‐label label</filename>:</emphasis> + <listitem><para><emphasis><filename>--label label</filename>:</emphasis> Specifies the label to give to the filesystem to be made on the partition. If the given label is already in use by another filesystem, a new label is created for the partition.</para></listitem> - <listitem><para><emphasis><filename>‐‐active</filename>:</emphasis> + <listitem><para><emphasis><filename>--active</filename>:</emphasis> Marks the partition as active.</para></listitem> - <listitem><para><emphasis><filename>‐‐align (in KBytes)</filename>:</emphasis> + <listitem><para><emphasis><filename>--align (in KBytes)</filename>:</emphasis> This option is a <filename>wic</filename>-specific option that says to start a partition on an x KBytes boundary.</para></listitem> @@ -4417,17 +4594,17 @@ <note> Bootloader functionality and boot partitions are implemented by the various - <filename>‐‐source</filename> + <filename>--source</filename> plugins that implement bootloader functionality. The bootloader command essentially provides a means of modifying bootloader configuration. </note> <itemizedlist> - <listitem><para><emphasis><filename>‐‐timeout</filename>:</emphasis> + <listitem><para><emphasis><filename>--timeout</filename>:</emphasis> Specifies the number of seconds before the bootloader times out and boots the default option. </para></listitem> - <listitem><para><emphasis><filename>‐‐append</filename>:</emphasis> + <listitem><para><emphasis><filename>--append</filename>:</emphasis> Specifies kernel parameters. These parameters will be added to the syslinux <filename>APPEND</filename> or @@ -4579,8 +4756,10 @@ placed where the OpenEmbedded build system can find and apply them. Syntactically, the configuration statement is identical to what would appear in the <filename>.config</filename> file, which is in the - <link linkend='build-directory'>Build Directory</link> in - <filename>tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></filename>. + <link linkend='build-directory'>Build Directory</link>: + <literallayout class='monospaced'> + tmp/work/<replaceable>arch</replaceable>-poky-linux/linux-yocto-<replaceable>release_specific_string</replaceable>/linux-<replaceable>arch</replaceable>-<replaceable>build_type</replaceable> + </literallayout> </para> <para> @@ -4807,7 +4986,7 @@ <literallayout class='monospaced'> ${S}/linux </literallayout> - See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" + See the "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>" section and the <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable for more information about where source is kept during a build. @@ -4826,8 +5005,8 @@ <para> Two methods exist by which you can create the patch: - <link linkend='using-a-git-workflow'>Git workflow</link> and - <link linkend='using-a-quilt-workflow'>Quilt workflow</link>. + <link linkend='using-devtool-in-your-workflow'><filename>devtool</filename></link> and + <link linkend='using-a-quilt-workflow'>Quilt</link>. For kernel patches, the Git workflow is more appropriate. This section assumes the Git workflow and shows the steps specific to this example. @@ -4983,11 +5162,6 @@ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-yocto \ - " </literallayout></para></listitem> </itemizedlist> </para> @@ -5089,8 +5263,7 @@ by Jake Edge </para></listitem> <listitem><para><emphasis> - "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security -Gateways via their Web Interfaces</ulink>"</emphasis> + "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security Gateways via their Web Interfaces</ulink>"</emphasis> by Ben Williams </para></listitem> </itemizedlist> @@ -5911,10 +6084,10 @@ Gateways via their Web Interfaces</ulink>"</emphasis> described here combined with experimentation and iteration. Here are a couple of areas to experiment with: <itemizedlist> - <listitem><para><filename>eglibc</filename>: + <listitem><para><filename>glibc</filename>: In general, follow this process: <orderedlist> - <listitem><para>Remove <filename>eglibc</filename> + <listitem><para>Remove <filename>glibc</filename> features from <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> that you think you do not need.</para></listitem> @@ -5928,7 +6101,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> support wide character support as is done for <filename>ncurses</filename>. Or, if support for those characters is needed, - determine what <filename>eglibc</filename> + determine what <filename>glibc</filename> features provide the support and restore the configuration. </para></listitem> @@ -5937,7 +6110,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </orderedlist></para></listitem> <listitem><para><filename>busybox</filename>: For BusyBox, use a process similar as described for - <filename>eglibc</filename>. + <filename>glibc</filename>. A difference is you will need to boot the resulting system to see if you are able to do everything you expect from the running system. @@ -5973,6 +6146,192 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> + <section id='building-images-for-more-than-one-machine'> + <title>Building Images for More than One Machine</title> + + <para> + A common scenario developers face is creating images for several + different machines that use the same software environment. + In this situation, it is tempting to set the + tunings and optimization flags for each build specifically for + the targeted hardware (i.e. "maxing out" the tunings). + Doing so can considerably add to build times and package feed + maintenance collectively for the machines. + For example, selecting tunes that are extremely specific to a + CPU core used in a system might enable some micro optimizations + in GCC for that particular system but would otherwise not gain + you much of a performance difference across the other systems + as compared to using a more general tuning across all the builds + (e.g. setting + <ulink url='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink> + specifically for each machine's build). + Rather than "max out" each build's tunings, you can take steps that + cause the OpenEmbedded build system to reuse software across the + various machines where it makes sense. + </para> + <para> + If build speed and package feed maintenance are considerations, + you should consider the points in this section that can help you + optimize your tunings to best consider build times and package + feed maintenance. + <itemizedlist> + <listitem><para><emphasis>Share the Build Directory:</emphasis> + If at all possible, share the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> + across builds. + The Yocto Project supports switching between different + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + values in the same <filename>TMPDIR</filename>. + This practice is well supported and regularly used by + developers when building for multiple machines. + When you use the same <filename>TMPDIR</filename> for + multiple machine builds, the OpenEmbedded build system can + reuse the existing native and often cross-recipes for + multiple machines. + Thus, build time decreases. + <note> + If + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> + settings change or fundamental configuration settings + such as the filesystem layout, you need to work with + a clean <filename>TMPDIR</filename>. + Sharing <filename>TMPDIR</filename> under these + circumstances might work but since it is not + guaranteed, you should use a clean + <filename>TMPDIR</filename>. + </note> + </para></listitem> + <listitem><para><emphasis>Enable the Appropriate Package Architecture:</emphasis> + By default, the OpenEmbedded build system enables three + levels of package architectures: "all", "tune" or "package", + and "machine". + Any given recipe usually selects one of these package + architectures (types) for its output. + Depending for what a given recipe creates packages, making + sure you enable the appropriate package architecture can + directly impact the build time.</para> + <para>A recipe that just generates scripts can enable + "all" architecture because there are no binaries to build. + To specifically enable "all" architecture, be sure your + recipe inherits the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink> + class. + This class is useful for "all" architectures because it + configures many variables so packages can be used across + multiple architectures.</para> + <para>If your recipe needs to generate packages that are + machine-specific or when one of the build or runtime + dependencies is already machine-architecture dependent, + which makes your recipe also machine-architecture dependent, + make sure your recipe enables the "machine" package + architecture through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink> + variable: + <literallayout class='monospaced'> + PACKAGE_ARCH = "${MACHINE_ARCH}" + </literallayout> + When you do not specifically enable a package + architecture through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>, + The OpenEmbedded build system defaults to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink> + setting: + <literallayout class='monospaced'> + PACKAGE_ARCH = "${TUNE_PKGARCH}" + </literallayout> + </para></listitem> + <listitem><para><emphasis>Choose a Generic Tuning File if Possible:</emphasis> + Some tunes are more generic and can run on multiple targets + (e.g. an <filename>armv5</filename> set of packages could + run on <filename>armv6</filename> and + <filename>armv7</filename> processors in most cases). + Similarly, <filename>i486</filename> binaries could work + on <filename>i586</filename> and higher processors. + You should realize, however, that advances on newer + processor versions would not be used.</para> + <para>If you select the same tune for several different + machines, the OpenEmbedded build system reuses software + previously built, thus speeding up the overall build time. + Realize that even though a new sysroot for each machine is + generated, the software is not recompiled and only one + package feed exists. + </para></listitem> + <listitem><para><emphasis>Manage Granular Level Packaging:</emphasis> + Sometimes cases exist where injecting another level + of package architecture beyond the three higher levels + noted earlier can be useful. + For example, consider the <filename>emgd</filename> + graphics stack in the + <filename>meta-intel</filename> layer. + In this layer, a subset of software exists that is + compiled against something different from the rest of the + generic packages. + You can examine the key code in the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink> + "daisy" branch in + <filename>classes/emgd-gl.bbclass</filename>. + For a specific set of packages, the code redefines + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>. + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXTRA_ARCHS'><filename>PACKAGE_EXTRA_ARCHS</filename></ulink> + is then appended with this extra tune name in + <filename>meta-intel-emgd.inc</filename>. + The result is that when searching for packages, the + build system uses a four-level search and the packages + in this new level are preferred as compared to the standard + tune. + The overall result is that the build system reuses most + software from the common tune except for specific cases + as needed. + </para></listitem> + <listitem><para><emphasis>Use Tools to Debug Issues:</emphasis> + Sometimes you can run into situations where software is + being rebuilt when you think it should not be. + For example, the OpenEmbedded build system might not be + using shared state between machines when you think it + should be. + These types of situations are usually due to references + to machine-specific variables such as + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>, + and so forth in code that is supposed to only be + tune-specific or when the recipe depends + (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>, + and so forth) on some other recipe that already has + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> + defined as "${MACHINE_ARCH}". + <note> + Patches to fix any issues identified are most welcome + as these issues occasionally do occur. + </note></para> + <para>For such cases, you can use some tools to help you + sort out the situation: + <itemizedlist> + <listitem><para><emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis> + You can find this tool in the + <filename>scripts</filename> directory of the + Source Repositories. + See the comments in the script for information on + how to use the tool. + </para></listitem> + <listitem><para><emphasis>BitBake's "-S printdiff" Option:</emphasis> + Using this option causes BitBake to try to + establish the closest signature match it can + (e.g. in the shared state cache) and then run + <filename>bitbake-diffsigs</filename> over the + matches to determine the stamps and delta where + these two stamp trees diverge. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + </para> + </section> + <section id='working-with-packages'> <title>Working with Packages</title> @@ -5986,9 +6345,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link> </para></listitem> <listitem><para> - <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link> - </para></listitem> - <listitem><para> <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link> </para></listitem> <listitem><para> @@ -6173,7 +6529,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> For this scenario, you need to start the PR Service using the <filename>bitbake-prserv</filename> command: <literallayout class='monospaced'> - bitbake-prserv ‐‐host <replaceable>ip</replaceable> ‐‐port <replaceable>port</replaceable> ‐‐start + bitbake-prserv --host <replaceable>ip</replaceable> --port <replaceable>port</replaceable> --start </literallayout> In addition to hand-starting the service, you need to update the <filename>local.conf</filename> file of each @@ -6274,53 +6630,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> - <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> - <title>Handling a Package Name Alias</title> - <para> - Sometimes a package name you are using might exist under - an alias or as a similarly named package in a different - distribution. - The OpenEmbedded build system implements a - <filename>do_distro_check</filename> - task that automatically connects to major distributions - and checks for these situations. - If the package exists under a different name in a different - distribution, you get a <filename>distro_check</filename> - mismatch. - You can resolve this problem by defining a per-distro recipe - name alias using the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename> - variable. - </para> - - <para> - Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename> - variable: - <literallayout class='monospaced'> - DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ - distro2=package_name_alias2 \ - distro3=package_name_alias3 \ - ..." - </literallayout> - </para> - - <para> - If you have more than one distribution alias, separate them with a space. - Note that the build system currently automatically checks the - Fedora, OpenSUSE, Debian, Ubuntu, - and Mandriva distributions for source package recipes without having to specify them - using the <filename>DISTRO_PN_ALIAS</filename> variable. - For example, the following command generates a report that lists the Linux distributions - that include the sources for each of the recipes. - <literallayout class='monospaced'> - $ bitbake world -f -c distro_check - </literallayout> - The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> - file found in the - <link linkend='source-directory'>Source Directory</link>. - </para> - </section> - <section id='handling-optional-module-packaging'> <title>Handling Optional Module Packaging</title> @@ -6872,9 +7181,9 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Given this example, issue the following commands on the target: <literallayout class='monospaced'> - # smart channel ‐‐add all type=rpm-md baseurl=http://server.name/rpm/all - # smart channel ‐‐add i585 type=rpm-md baseurl=http://server.name/rpm/i586 - # smart channel ‐‐add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86 + # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all + # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586 + # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86 </literallayout> Also from the target machine, fetch the repository information using this command: @@ -7375,6 +7684,114 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> + <section id="selecting-dev-manager"> + <title>Selecting a Device Manager</title> + + <para> + The Yocto Project provides multiple ways to manage the device + manager (<filename>/dev</filename>): + <itemizedlist> + <listitem><para><emphasis>Persistent and Pre-Populated<filename>/dev</filename>:</emphasis> + For this case, the <filename>/dev</filename> directory + is persistent and the required device nodes are created + during the build. + </para></listitem> + <listitem><para><emphasis>Use <filename>devtmpfs</filename> with a Device Manager:</emphasis> + For this case, the <filename>/dev</filename> directory + is provided by the kernel as an in-memory file system and + is automatically populated by the kernel at runtime. + Additional configuration of device nodes is done in user + space by a device manager like + <filename>udev</filename> or + <filename>busybox-mdev</filename>. + </para></listitem> + </itemizedlist> + </para> + + <section id="static-dev-management"> + <title>Using Persistent and Pre-Populated<filename>/dev</filename></title> + + <para> + To use the static method for device population, you need to + set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-USE_DEVFS'><filename>USE_DEVFS</filename></ulink> + variable to "0" as follows: + <literallayout class='monospaced'> + USE_DEVFS = "0" + </literallayout> + </para> + + <para> + The content of the resulting <filename>/dev</filename> + directory is defined in a Device Table file. + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_DEVICE_TABLES'><filename>IMAGE_DEVICE_TABLES</filename></ulink> + variable defines the Device Table to use and should be set + in the machine or distro configuration file. + Alternatively, you can set this variable in your + <filename>local.conf</filename> configuration file. + </para> + + <para> + If you do not define the + <filename>IMAGE_DEVICE_TABLES</filename> variable, the default + <filename>device_table-minimal.txt</filename> is used: + <literallayout class='monospaced'> + IMAGE_DEVICE_TABLES = "device_table-mymachine.txt" + </literallayout> + </para> + + <para> + The population is handled by the <filename>makedevs</filename> + utility during image creation: + </para> + </section> + + <section id="devtmpfs-dev-management"> + <title>Using <filename>devtmpfs</filename> and a Device Manager</title> + + <para> + To use the dynamic method for device population, you need to + use (or be sure to set) the + <ulink url='&YOCTO_DOCS_REF_URL;#var-USE_DEVFS'><filename>USE_DEVFS</filename></ulink> + variable to "1", which is the default: + <literallayout class='monospaced'> + USE_DEVFS = "1" + </literallayout> + With this setting, the resulting <filename>/dev</filename> + directory is populated by the kernel using + <filename>devtmpfs</filename>. + Make sure the corresponding kernel configuration variable + <filename>CONFIG_DEVTMPFS</filename> is set when building + you build a Linux kernel. + </para> + + <para> + All devices created by <filename>devtmpfs</filename> will be + owned by <filename>root</filename> and have permissions + <filename>0600</filename>. + </para> + + <para> + To have more control over the device nodes, you can use a + device manager like <filename>udev</filename> or + <filename>busybox-mdev</filename>. + You choose the device manager by defining the + <filename>VIRTUAL-RUNTIME_dev_manager</filename> variable + in your machine or distro configuration file. + Alternatively, you can set this variable in your + <filename>local.conf</filename> configuration file: + <literallayout class='monospaced'> + VIRTUAL-RUNTIME_dev_manager = "udev" + + # Some alternative values + # VIRTUAL-RUNTIME_dev_manager = "busybox-mdev" + # VIRTUAL-RUNTIME_dev_manager = "systemd" + </literallayout> + </para> + </section> + </section> + <section id="platdev-appdev-srcrev"> <title>Using an External SCM</title> @@ -7397,7 +7814,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>. Here is an example: <literallayout class='monospaced'> - PV = "1.2.3+git${SRCPV} + PV = "1.2.3+git${SRCPV}" </literallayout> Then, you can add the following to your <filename>local.conf</filename>: @@ -8001,7 +8418,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> EdgeRouterTarget, and GrubTarget), you need to specify a command to use to connect to the serial console of the target machine by using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></ulink> variable and optionally the <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_EXTRA_ARGS'><filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename></ulink> variable. @@ -8216,13 +8633,13 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Consequently, running the tests on other machine means that you have to move the contents and call <filename>runexported.py</filename> with - "‐‐deploy-dir <replaceable>path</replaceable>" as + "--deploy-dir <replaceable>path</replaceable>" as follows: <literallayout class='monospaced'> - ./runexported.py ‐‐deploy-dir /new/path/on/this/machine testdata.json + ./runexported.py --deploy-dir /new/path/on/this/machine testdata.json </literallayout> <filename>runexported.py</filename> accepts other arguments - as well as described using <filename>‐‐help</filename>. + as well as described using <filename>--help</filename>. </para> </section> @@ -8304,7 +8721,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> "ps" (busybox). </para></listitem> <listitem><para><emphasis><filename>tc</filename>:</emphasis> - The called text context, which gives access to the + The called test context, which gives access to the following attributes: <itemizedlist> <listitem><para><emphasis><filename>d</filename>:</emphasis> @@ -8682,7 +9099,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] | DEBUG: Executing shell function do_compile | NOTE: make -j 16 - | make ‐‐no-print-directory all-am + | make --no-print-directory all-am | /bin/mkdir -p include/near | /bin/mkdir -p include/near | /bin/mkdir -p include/near @@ -8723,7 +9140,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h - | i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ + | i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/ yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/ @@ -8798,7 +9215,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Here is some abbreviated, sample output with the missing dependency clearly visible at the end: <literallayout class='monospaced'> - i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/scott-lenovo/...... + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... . . . @@ -8830,7 +9247,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> File Makefile.am added to patch patches/parallelmake.patch </literallayout> For more information on using Quilt, see the - "<link linkend='using-a-quilt-workflow'>Using a Quilt Workflow</link>" + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" section. </para> @@ -8921,217 +9338,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> - <section id="examining-builds-using-toaster"> - <title>Examining Builds Using the Toaster API</title> - - <para> - Toaster is an Application Programming Interface (API) and - web-based interface to the OpenEmbedded build system, which uses - BitBake. - Both interfaces are based on a Representational State Transfer - (REST) API that queries for and returns build information using - <filename>GET</filename> and <filename>JSON</filename>. - These types of search operations retrieve sets of objects from - a datastore used to collect build information. - The results contain all the data for the objects being returned. - You can order the results of the search by key and the search - parameters are consistent for all object types. - </para> - - <para> - Using the interfaces you can do the following: - <itemizedlist> - <listitem><para>See information about the tasks executed - and reused during the build.</para></listitem> - <listitem><para>See what is built (recipes and - packages) and what packages were installed into the final - image.</para></listitem> - <listitem><para>See performance-related information such - as build time, CPU usage, and disk I/O.</para></listitem> - <listitem><para>Examine error, warning and trace messages - to aid in debugging.</para></listitem> - </itemizedlist> - </para> - - <note> - <para>This release of Toaster provides you with information - about a BitBake run. - The tool does not allow you to configure and launch a build. - However, future development includes plans to integrate the - configuration and build launching capabilities of - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>. - </para> - <para>For more information on using Hob to build an image, - see the - "<link linkend='image-development-using-hob'>Image Development Using Hob</link>" - section.</para> - </note> - - <para> - The remainder of this section describes what you need to have in - place to use Toaster, how to start it, use it, and stop it. - For additional information on installing and running Toaster, see the - "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>" - section of the "Toaster" wiki page. - For complete information on the API and its search operation - URI, parameters, and responses, see the - <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> - Wiki page. - </para> - - <section id='starting-toaster'> - <title>Starting Toaster</title> - - <para> - Getting set up to use and start Toaster is simple. - First, be sure you have met the following requirements: - <itemizedlist> - <listitem><para>You have set up your - <link linkend='source-directory'>Source Directory</link> - by cloning the upstream <filename>poky</filename> - repository. - See the - <link linkend='local-yp-release'>Yocto Project Release</link> - item for information on how to set up the Source - Directory.</para></listitem> - <listitem><para>Be sure your build machine has - <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink> - version 1.5 installed.</para></listitem> - <listitem><para>Make sure that port 8000 and 8200 are - free (i.e. they have no servers on them). - </para></listitem> - </itemizedlist> - </para> - - <para> - Once you have met the requirements, follow these steps to - start Toaster running in the background of your shell: - <orderedlist> - <listitem><para><emphasis>Set up your build environment:</emphasis> - Source a build environment script (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). - </para></listitem> - <listitem><para><emphasis>Start Toaster:</emphasis> - Start the Toaster service using this - command from within your - <link linkend='build-directory'>Build Directory</link>: - <literallayout class='monospaced'> - $ source toaster start - </literallayout></para></listitem> - <note> - The Toaster must be started and running in order - for it to collect data. - </note> - </orderedlist> - </para> - - <para> - When Toaster starts, it creates some additional files in your - Build Directory. - Deleting these files will cause you to lose data or interrupt - Toaster: - <itemizedlist> - <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis> - Toaster's database file.</para></listitem> - <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis> - The log file of the web server.</para></listitem> - <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis> - The log file of the user interface component. - </para></listitem> - <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis> - The PID of the web server.</para></listitem> - <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis> - The PID of the DSI data bridge.</para></listitem> - <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis> - The BitBake server's log file.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='using-toaster'> - <title>Using Toaster</title> - - <para> - Once Toaster is running, it logs information for any BitBake - run from your Build Directory. - This logging is automatic. - All you need to do is access and use the information. - </para> - - <para> - You access the information one of two ways: - <itemizedlist> - <listitem><para>Open a Browser and enter - <filename>http://localhost:8000</filename> - for the URL. - </para></listitem> - <listitem><para>Use the <filename>xdg-open</filename> - tool from the shell and pass it the same URL. - </para></listitem> - </itemizedlist> - Either method opens the home page for the Toaster interface. - </para> - - <note><title>Notes</title> - <itemizedlist> - <listitem><para> - For information on how to delete information from the - Toaster database, see the - <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink> - wiki page. - </para></listitem> - <listitem><para> - For information on how to set up an instance of Toaster - on a remote host, see the - <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink> - wiki page. - </para></listitem> - </itemizedlist> - </note> - </section> - - <section id='examining-toaster-data'> - <title>Examining Toaster Data</title> - - <para> - The Toaster database is persistent regardless of whether you - start or stop the service. - </para> - - <para> - Toaster's interface shows you a list of builds - (successful and unsuccessful) for which it has data. - You can click on any build to see related information. - This information includes configuration details, information - about tasks, all recipes and packages built and their - dependencies, packages and their directory structure as - installed in your final image, - execution time, CPU usage and disk I/O per task. - </para> - - <para> - For details on the interface, see the - <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>. - </para> - </section> - - <section id='stopping-toaster'> - <title>Stopping Toaster</title> - - <para> - Stop the Toaster service with the following command - from with the - <link linkend='build-directory'>Build Directory</link>: - <literallayout class='monospaced'> - $ source toaster stop - </literallayout> - The service stops but the Toaster database remains persistent. - </para> - </section> - </section> - <section id="platdev-oprofile"> <title>Profiling with OProfile</title> @@ -9193,14 +9399,14 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <para> <literallayout class='monospaced'> - # opcontrol ‐‐reset - # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 + # opcontrol --reset + # opcontrol --start --separate=lib --no-vmlinux -c 5 . . [do whatever is being profiled] . . - # opcontrol ‐‐stop + # opcontrol --stop $ opreport -cl </literallayout> </para> @@ -9213,7 +9419,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> five levels deep. <note> To profile the kernel, you would specify the - <filename>‐‐vmlinux=/path/to/vmlinux</filename> option. + <filename>--vmlinux=/path/to/vmlinux</filename> option. The <filename>vmlinux</filename> file is usually in the source directory in the <filename>/boot/</filename> directory and must match the running kernel. </note> @@ -9276,7 +9482,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> With this connection, you just need to run "oprofile-server" on the device. By default, OProfile listens on port 4224. <note> - You can change the port using the <filename>‐‐port</filename> command-line + You can change the port using the <filename>--port</filename> command-line option. </note> </para> @@ -9366,14 +9572,14 @@ Gateways via their Web Interfaces</ulink>"</emphasis> If network access to the target is unavailable, you can generate an archive for processing in <filename>oprofile-viewer</filename> as follows: <literallayout class='monospaced'> - # opcontrol ‐‐reset - # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 + # opcontrol --reset + # opcontrol --start --separate=lib --no-vmlinux -c 5 . . [do whatever is being profiled] . . - # opcontrol ‐‐stop + # opcontrol --stop # oparchive -o my_archive </literallayout> </para> @@ -9608,11 +9814,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> ##OEROOT##/meta-yocto-bsp \ ##OEROOT##/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - ##OEROOT##/meta \ - ##OEROOT##/meta-yocto \ - " </literallayout> Creating and providing an archive of the <link linkend='metadata'>Metadata</link> layers @@ -9678,28 +9879,36 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </literallayout> Enabling error reporting causes the build process to collect the errors and store them in a file as previously described. - When the build system encounters an error, it includes a command - as part of the console output. + When the build system encounters an error, it includes a + command as part of the console output. You can run the command to send the error file to the server. - For example, the following command sends the errors to an upstream - server: + For example, the following command sends the errors to an + upstream server: + <literallayout class='monospaced'> + $ send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt + </literallayout> + In the previous example, the errors are sent to a public + database available at + <ulink url='http://errors.yoctoproject.org'></ulink>, which is + used by the entire community. + If you specify a particular server, you can send the errors + to a different database. + Use the following command for more information on available + options: <literallayout class='monospaced'> - send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server] + $ send-error-report --help </literallayout> - In the above example, the <filename>server</filename> parameter is - optional. - By default, the errors are sent to a database used by the entire - community. - If you specify a particular server, you can send them to a different - database. </para> <para> - When sending the error file, you receive a link that corresponds - to your entry in the database. + When sending the error file, you are prompted to review the + data being sent as well as to provide a name and optional + email address. + Once you satisfy these prompts, the command returns a link + from the server that corresponds to your entry in the database. For example, here is a typical link: <literallayout class='monospaced'> - http://localhost:8000/Errors/Search/1/158 + http://errors.yoctoproject.org/Errors/Details/9522/ </literallayout> Following the link takes you to a web interface where you can browse, query the errors, and view statistics. |