summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-11-10 15:15:36 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-12-09 15:09:05 +0000
commit5f4050f73d760ccbae37b8a638e8708477e9bb89 (patch)
tree46563cb302f2fb19f1d075b8a25d902e2ac91415 /documentation/dev-manual/dev-manual-common-tasks.xml
parent146d4bb4ddd801580c27d38066a5ecbf508fc2ff (diff)
downloadpoky-5f4050f73d760ccbae37b8a638e8708477e9bb89.tar.gz
dev-manual: First draft of "multi-builds" section.
Fixes [YOCTO #5400] This is the first draft of a new section on multi-machine builds. (From yocto-docs rev: a47fd17295d943bff482a0747f3b2e69831aa985) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml174
1 files changed, 174 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 87f14a046e..a710efe6d5 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5973,6 +5973,180 @@ Gateways via their Web Interfaces</ulink>"</emphasis>
5973 </section> 5973 </section>
5974 </section> 5974 </section>
5975 5975
5976 <section id='building-images-for-more-than-one-machine'>
5977 <title>Building Images for More than One Machine</title>
5978
5979 <para>
5980 A common scenario developers face is creating images for several
5981 different machines that use the same software environment.
5982 In this situation, it is tempting to set the
5983 tunings and optimization flags for each build specifically for
5984 the targeted hardware (i.e. "maxing out" the tunings).
5985 Doing so can considerably add to build times and package feed
5986 maintenance collectively for the machines.
5987 For example, selecting tunes that are extremely specific to a
5988 CPU core used in a system might enable some micro optimizations
5989 in GCC for that particular system but would otherwise not gain
5990 you much of a performance difference across the other systems
5991 as compared to using a more general tuning across all the builds.
5992 Another example is setting
5993 <ulink url='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>
5994 specifically for each machine's build.
5995 Rather than "max out" each build's tunings, you can take steps that
5996 cause the OpenEmbedded build system to reuse software across the
5997 various machines where it makes sense.
5998 </para>
5999 <para>
6000 If build speed and package feed maintenance are considerations,
6001 you should consider the points in this section that can help you
6002 optimize your tunings to best consider build times and package
6003 feed maintenance.
6004 <itemizedlist>
6005 <listitem><para><emphasis>Share the Build Directory:</emphasis>
6006 If at all possible, share the
6007 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
6008 across builds.
6009 The Yocto Project supports switching between different
6010 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
6011 values in the same <filename>TMPDIR</filename>.
6012 This practice is well supported and regularly used by
6013 developers when building for multiple machines.
6014 When you use the same <filename>TMPDIR</filename> for
6015 multiple machine builds, the OpenEmbedded build system can
6016 reuse the existing native and often cross-recipes for
6017 multiple machines.
6018 Thus, build time decreases.
6019 <note>
6020 If
6021 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
6022 settings change or fundamental configuration settings
6023 such as the filesystem layout, you need to work with
6024 a clean <filename>TMPDIR</filename>.
6025 Sharing <filename>TMPDIR</filename> under these
6026 circumstances might work but since it is not
6027 guaranteed, you should use a clean
6028 <filename>TMPDIR</filename>.
6029 </note>
6030 </para></listitem>
6031 <listitem><para><emphasis>Enable the Appropriate Package Architecture:</emphasis>
6032 By default, the OpenEmbedded build system enables three
6033 levels of package architectures: "all", "tune" or "package",
6034 and "machine".
6035 Any given recipe usually selects one of these package
6036 architectures (types) for its output.
6037 Depending for what a given recipe creates packages, making
6038 sure you enable the appropriate package architecture can
6039 directly impact the build time.</para>
6040 <para>A recipe that just generates scripts can enable
6041 "all" architecture because there are no binaries to build.
6042 To specifically enable "all" architecture, be sure your
6043 recipe inherits the
6044 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
6045 class.
6046 This class is useful for "all" architectures because it
6047 contains many other variables that can be used across
6048 multiple architectures.</para>
6049 <para>If your recipe needs to generate packages that are
6050 machine-specific or when one of the build or runtime
6051 dependencies is already machine-architecture dependent,
6052 which makes your recipe also machine-architecture dependent,
6053 make sure your recipe enables the "machine" package
6054 architecture through the
6055 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>
6056 variable:
6057 <literallayout class='monospaced'>
6058 PACKAGE_ARCH = "${MACHINE_ARCH}"
6059 </literallayout>
6060 If you select a specific tuning for the recipe,
6061 the OpenEmbedded build system enables the package
6062 architecture defined by that tuning file.</para>
6063 <para>When you do not specifically enable a package
6064 architecture through the
6065 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
6066 The OpenEmbedded build system defaults to the
6067 <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_ARCH'><filename>TUNE_ARCH</filename></ulink>
6068 setting:
6069 <literallayout class='monospaced'>
6070 PACKAGE_ARCH == TUNE_ARCH
6071 </literallayout>
6072 </para></listitem>
6073 <listitem><para><emphasis>Choose a Generic Tuning File if Possible:</emphasis>
6074 Some tunes are more generic and can run on multiple targets
6075 (e.g. an <filename>armv5</filename> set of packages could
6076 run on <filename>armv6</filename> and
6077 <filename>armv7</filename> processors in most cases).
6078 Similarly, <filename>i486</filename> binaries could work
6079 on <filename>i586</filename> and higher processors.</para>
6080 <para>If you select the same tune for several different
6081 machines, the OpenEmbedded build system reuses software
6082 previously built, thus speeding up the overall build time.
6083 Realize that even though a new sysroot for each machine is
6084 generated, the software is not recompiled and only one
6085 package feed exists.
6086 </para></listitem>
6087 <listitem><para><emphasis>Manage Granular Level Packaging:</emphasis>
6088 Sometimes cases exist where where injecting another level
6089 of package architecture beyond the three higher levels
6090 noted earlier can be useful.
6091 For example, consider the <filename>emgd</filename>
6092 graphics stack in the
6093 <filename>meta-intel</filename> layer.
6094 In this layer, a subset of software exists that is
6095 compiled against something different from the rest of the
6096 generic packages.
6097 You can examine the key code in the
6098 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>
6099 in <filename>classes/emgd-gl.bbclass</filename>.
6100 For a specific set of packages, the code redefines
6101 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>.
6102 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXTRA_ARCHS'><filename>PACKAGE_EXTRA_ARCHS</filename></ulink>
6103 is then appended with this extra tune name in
6104 <filename>meta-intel-emgd.inc</filename>.
6105 The result is that when searching for packages, the
6106 build system uses a four-level search and the packages
6107 in this new level are preferred as compared to the standard
6108 tune.
6109 The overall result is that the build system reuses most
6110 software from the common tune except for specific cases
6111 as needed.
6112 </para></listitem>
6113 <listitem><para><emphasis>Use Tools to Debug Issues:</emphasis>
6114 Sometimes you can run into situations where software is
6115 being rebuilt when you think it should not be.
6116 For example, the OpenEmbedded build system might not be
6117 using shared state between machines when you think it
6118 should be.
6119 These types of situations are usually due to references
6120 to variables such as <filename>MACHINE</filename>
6121 in code that is supposed to only be "tune" specific.</para>
6122 <note>
6123 Patches to fix any issues identified are most welcome
6124 as these issues occasionally do occur.
6125 </note>
6126 <para>For such cases, you can use some tools to help you
6127 sort out the situation:
6128 <itemizedlist>
6129 <listitem><para><emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis>
6130 You can find this tool in the
6131 <filename>scripts</filename> directory of the
6132 Source Repositories.
6133 See the comments in the script for information on
6134 how to use the tool.
6135 </para></listitem>
6136 <listitem><para><emphasis>BitBake's "-S printdiff" Option:</emphasis>
6137 Using this option causes BitBake to try to
6138 establish the closest signature match it can
6139 (e.g. in the shared state cache) and then run
6140 <filename>bitbake-diffsigs</filename> over the
6141 matches to determine the stamps and delta where
6142 these two stamp trees diverge.
6143 </para></listitem>
6144 </itemizedlist>
6145 </para></listitem>
6146 </itemizedlist>
6147 </para>
6148 </section>
6149
5976 <section id='working-with-packages'> 6150 <section id='working-with-packages'>
5977 <title>Working with Packages</title> 6151 <title>Working with Packages</title>
5978 6152