summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml396
1 files changed, 198 insertions, 198 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 07e01f0f25..6734b1f4b9 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5947,6 +5947,204 @@
5947 </para> 5947 </para>
5948 </section> 5948 </section>
5949 </section> 5949 </section>
5950
5951 <section id='building-images-for-more-than-one-machine'>
5952 <title>Building Images for More than One Machine</title>
5953
5954 <para>
5955 A common scenario developers face is creating images for several
5956 different machines that use the same software environment.
5957 In this situation, it is tempting to set the
5958 tunings and optimization flags for each build specifically for
5959 the targeted hardware (i.e. "maxing out" the tunings).
5960 Doing so can considerably add to build times and package feed
5961 maintenance collectively for the machines.
5962 For example, selecting tunes that are extremely specific to a
5963 CPU core used in a system might enable some micro optimizations
5964 in GCC for that particular system but would otherwise not gain
5965 you much of a performance difference across the other systems
5966 as compared to using a more general tuning across all the builds
5967 (e.g. setting
5968 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>
5969 specifically for each machine's build).
5970 Rather than "max out" each build's tunings, you can take steps that
5971 cause the OpenEmbedded build system to reuse software across the
5972 various machines where it makes sense.
5973 </para>
5974
5975 <para>
5976 If build speed and package feed maintenance are considerations,
5977 you should consider the points in this section that can help you
5978 optimize your tunings to best consider build times and package
5979 feed maintenance.
5980 <itemizedlist>
5981 <listitem><para>
5982 <emphasis>Share the Build Directory:</emphasis>
5983 If at all possible, share the
5984 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
5985 across builds.
5986 The Yocto Project supports switching between different
5987 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
5988 values in the same <filename>TMPDIR</filename>.
5989 This practice is well supported and regularly used by
5990 developers when building for multiple machines.
5991 When you use the same <filename>TMPDIR</filename> for
5992 multiple machine builds, the OpenEmbedded build system can
5993 reuse the existing native and often cross-recipes for
5994 multiple machines.
5995 Thus, build time decreases.
5996 <note>
5997 If
5998 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5999 settings change or fundamental configuration settings
6000 such as the filesystem layout, you need to work with
6001 a clean <filename>TMPDIR</filename>.
6002 Sharing <filename>TMPDIR</filename> under these
6003 circumstances might work but since it is not
6004 guaranteed, you should use a clean
6005 <filename>TMPDIR</filename>.
6006 </note>
6007 </para></listitem>
6008 <listitem><para>
6009 <emphasis>Enable the Appropriate Package Architecture:</emphasis>
6010 By default, the OpenEmbedded build system enables three
6011 levels of package architectures: "all", "tune" or "package",
6012 and "machine".
6013 Any given recipe usually selects one of these package
6014 architectures (types) for its output.
6015 Depending for what a given recipe creates packages, making
6016 sure you enable the appropriate package architecture can
6017 directly impact the build time.</para>
6018
6019 <para>A recipe that just generates scripts can enable
6020 "all" architecture because there are no binaries to build.
6021 To specifically enable "all" architecture, be sure your
6022 recipe inherits the
6023 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
6024 class.
6025 This class is useful for "all" architectures because it
6026 configures many variables so packages can be used across
6027 multiple architectures.</para>
6028
6029 <para>If your recipe needs to generate packages that are
6030 machine-specific or when one of the build or runtime
6031 dependencies is already machine-architecture dependent,
6032 which makes your recipe also machine-architecture dependent,
6033 make sure your recipe enables the "machine" package
6034 architecture through the
6035 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>
6036 variable:
6037 <literallayout class='monospaced'>
6038 PACKAGE_ARCH = "${MACHINE_ARCH}"
6039 </literallayout>
6040 When you do not specifically enable a package
6041 architecture through the
6042 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
6043 The OpenEmbedded build system defaults to the
6044 <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink>
6045 setting:
6046 <literallayout class='monospaced'>
6047 PACKAGE_ARCH = "${TUNE_PKGARCH}"
6048 </literallayout>
6049 </para></listitem>
6050 <listitem><para>
6051 <emphasis>Choose a Generic Tuning File if Possible:</emphasis>
6052 Some tunes are more generic and can run on multiple targets
6053 (e.g. an <filename>armv5</filename> set of packages could
6054 run on <filename>armv6</filename> and
6055 <filename>armv7</filename> processors in most cases).
6056 Similarly, <filename>i486</filename> binaries could work
6057 on <filename>i586</filename> and higher processors.
6058 You should realize, however, that advances on newer
6059 processor versions would not be used.</para>
6060
6061 <para>If you select the same tune for several different
6062 machines, the OpenEmbedded build system reuses software
6063 previously built, thus speeding up the overall build time.
6064 Realize that even though a new sysroot for each machine is
6065 generated, the software is not recompiled and only one
6066 package feed exists.
6067 </para></listitem>
6068 <listitem><para>
6069 <emphasis>Manage Granular Level Packaging:</emphasis>
6070 Sometimes cases exist where injecting another level of
6071 package architecture beyond the three higher levels noted
6072 earlier can be useful.
6073 For example, consider how NXP (formerly Freescale) allows
6074 for the easy reuse of binary packages in their layer
6075 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/'><filename>meta-freescale</filename></ulink>.
6076 In this example, the
6077 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/classes/fsl-dynamic-packagearch.bbclass'><filename>fsl-dynamic-packagearch</filename></ulink>
6078 class shares GPU packages for i.MX53 boards because
6079 all boards share the AMD GPU.
6080 The i.MX6-based boards can do the same because all boards
6081 share the Vivante GPU.
6082 This class inspects the BitBake datastore to identify if
6083 the package provides or depends on one of the
6084 sub-architecture values.
6085 If so, the class sets the
6086 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
6087 value based on the <filename>MACHINE_SUBARCH</filename>
6088 value.
6089 If the package does not provide or depend on one of the
6090 sub-architecture values but it matches a value in the
6091 machine-specific filter, it sets
6092 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>.
6093 This behavior reduces the number of packages built and
6094 saves build time by reusing binaries.
6095 </para></listitem>
6096 <listitem><para>
6097 <emphasis>Use Tools to Debug Issues:</emphasis>
6098 Sometimes you can run into situations where software is
6099 being rebuilt when you think it should not be.
6100 For example, the OpenEmbedded build system might not be
6101 using shared state between machines when you think it
6102 should be.
6103 These types of situations are usually due to references
6104 to machine-specific variables such as
6105 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
6106 <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>,
6107 <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>,
6108 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>,
6109 and so forth in code that is supposed to only be
6110 tune-specific or when the recipe depends
6111 (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
6112 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
6113 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
6114 <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>,
6115 and so forth) on some other recipe that already has
6116 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
6117 defined as "${MACHINE_ARCH}".
6118 <note>
6119 Patches to fix any issues identified are most welcome
6120 as these issues occasionally do occur.
6121 </note></para>
6122
6123 <para>For such cases, you can use some tools to help you
6124 sort out the situation:
6125 <itemizedlist>
6126 <listitem><para>
6127 <emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis>
6128 You can find this tool in the
6129 <filename>scripts</filename> directory of the
6130 Source Repositories.
6131 See the comments in the script for information on
6132 how to use the tool.
6133 </para></listitem>
6134 <listitem><para>
6135 <emphasis>BitBake's "-S printdiff" Option:</emphasis>
6136 Using this option causes BitBake to try to
6137 establish the closest signature match it can
6138 (e.g. in the shared state cache) and then run
6139 <filename>bitbake-diffsigs</filename> over the
6140 matches to determine the stamps and delta where
6141 these two stamp trees diverge.
6142 </para></listitem>
6143 </itemizedlist>
6144 </para></listitem>
6145 </itemizedlist>
6146 </para>
6147 </section>
5950 </section> 6148 </section>
5951 6149
5952 6150
@@ -8246,204 +8444,6 @@
8246 </para> 8444 </para>
8247 </section> 8445 </section>
8248 8446
8249 <section id='building-images-for-more-than-one-machine'>
8250 <title>Building Images for More than One Machine</title>
8251
8252 <para>
8253 A common scenario developers face is creating images for several
8254 different machines that use the same software environment.
8255 In this situation, it is tempting to set the
8256 tunings and optimization flags for each build specifically for
8257 the targeted hardware (i.e. "maxing out" the tunings).
8258 Doing so can considerably add to build times and package feed
8259 maintenance collectively for the machines.
8260 For example, selecting tunes that are extremely specific to a
8261 CPU core used in a system might enable some micro optimizations
8262 in GCC for that particular system but would otherwise not gain
8263 you much of a performance difference across the other systems
8264 as compared to using a more general tuning across all the builds
8265 (e.g. setting
8266 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>
8267 specifically for each machine's build).
8268 Rather than "max out" each build's tunings, you can take steps that
8269 cause the OpenEmbedded build system to reuse software across the
8270 various machines where it makes sense.
8271 </para>
8272
8273 <para>
8274 If build speed and package feed maintenance are considerations,
8275 you should consider the points in this section that can help you
8276 optimize your tunings to best consider build times and package
8277 feed maintenance.
8278 <itemizedlist>
8279 <listitem><para>
8280 <emphasis>Share the Build Directory:</emphasis>
8281 If at all possible, share the
8282 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
8283 across builds.
8284 The Yocto Project supports switching between different
8285 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
8286 values in the same <filename>TMPDIR</filename>.
8287 This practice is well supported and regularly used by
8288 developers when building for multiple machines.
8289 When you use the same <filename>TMPDIR</filename> for
8290 multiple machine builds, the OpenEmbedded build system can
8291 reuse the existing native and often cross-recipes for
8292 multiple machines.
8293 Thus, build time decreases.
8294 <note>
8295 If
8296 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
8297 settings change or fundamental configuration settings
8298 such as the filesystem layout, you need to work with
8299 a clean <filename>TMPDIR</filename>.
8300 Sharing <filename>TMPDIR</filename> under these
8301 circumstances might work but since it is not
8302 guaranteed, you should use a clean
8303 <filename>TMPDIR</filename>.
8304 </note>
8305 </para></listitem>
8306 <listitem><para>
8307 <emphasis>Enable the Appropriate Package Architecture:</emphasis>
8308 By default, the OpenEmbedded build system enables three
8309 levels of package architectures: "all", "tune" or "package",
8310 and "machine".
8311 Any given recipe usually selects one of these package
8312 architectures (types) for its output.
8313 Depending for what a given recipe creates packages, making
8314 sure you enable the appropriate package architecture can
8315 directly impact the build time.</para>
8316
8317 <para>A recipe that just generates scripts can enable
8318 "all" architecture because there are no binaries to build.
8319 To specifically enable "all" architecture, be sure your
8320 recipe inherits the
8321 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
8322 class.
8323 This class is useful for "all" architectures because it
8324 configures many variables so packages can be used across
8325 multiple architectures.</para>
8326
8327 <para>If your recipe needs to generate packages that are
8328 machine-specific or when one of the build or runtime
8329 dependencies is already machine-architecture dependent,
8330 which makes your recipe also machine-architecture dependent,
8331 make sure your recipe enables the "machine" package
8332 architecture through the
8333 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>
8334 variable:
8335 <literallayout class='monospaced'>
8336 PACKAGE_ARCH = "${MACHINE_ARCH}"
8337 </literallayout>
8338 When you do not specifically enable a package
8339 architecture through the
8340 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
8341 The OpenEmbedded build system defaults to the
8342 <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink>
8343 setting:
8344 <literallayout class='monospaced'>
8345 PACKAGE_ARCH = "${TUNE_PKGARCH}"
8346 </literallayout>
8347 </para></listitem>
8348 <listitem><para>
8349 <emphasis>Choose a Generic Tuning File if Possible:</emphasis>
8350 Some tunes are more generic and can run on multiple targets
8351 (e.g. an <filename>armv5</filename> set of packages could
8352 run on <filename>armv6</filename> and
8353 <filename>armv7</filename> processors in most cases).
8354 Similarly, <filename>i486</filename> binaries could work
8355 on <filename>i586</filename> and higher processors.
8356 You should realize, however, that advances on newer
8357 processor versions would not be used.</para>
8358
8359 <para>If you select the same tune for several different
8360 machines, the OpenEmbedded build system reuses software
8361 previously built, thus speeding up the overall build time.
8362 Realize that even though a new sysroot for each machine is
8363 generated, the software is not recompiled and only one
8364 package feed exists.
8365 </para></listitem>
8366 <listitem><para>
8367 <emphasis>Manage Granular Level Packaging:</emphasis>
8368 Sometimes cases exist where injecting another level of
8369 package architecture beyond the three higher levels noted
8370 earlier can be useful.
8371 For example, consider how NXP (formerly Freescale) allows
8372 for the easy reuse of binary packages in their layer
8373 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/'><filename>meta-freescale</filename></ulink>.
8374 In this example, the
8375 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/classes/fsl-dynamic-packagearch.bbclass'><filename>fsl-dynamic-packagearch</filename></ulink>
8376 class shares GPU packages for i.MX53 boards because
8377 all boards share the AMD GPU.
8378 The i.MX6-based boards can do the same because all boards
8379 share the Vivante GPU.
8380 This class inspects the BitBake datastore to identify if
8381 the package provides or depends on one of the
8382 sub-architecture values.
8383 If so, the class sets the
8384 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
8385 value based on the <filename>MACHINE_SUBARCH</filename>
8386 value.
8387 If the package does not provide or depend on one of the
8388 sub-architecture values but it matches a value in the
8389 machine-specific filter, it sets
8390 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>.
8391 This behavior reduces the number of packages built and
8392 saves build time by reusing binaries.
8393 </para></listitem>
8394 <listitem><para>
8395 <emphasis>Use Tools to Debug Issues:</emphasis>
8396 Sometimes you can run into situations where software is
8397 being rebuilt when you think it should not be.
8398 For example, the OpenEmbedded build system might not be
8399 using shared state between machines when you think it
8400 should be.
8401 These types of situations are usually due to references
8402 to machine-specific variables such as
8403 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
8404 <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>,
8405 <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>,
8406 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>,
8407 and so forth in code that is supposed to only be
8408 tune-specific or when the recipe depends
8409 (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
8410 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
8411 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
8412 <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>,
8413 and so forth) on some other recipe that already has
8414 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
8415 defined as "${MACHINE_ARCH}".
8416 <note>
8417 Patches to fix any issues identified are most welcome
8418 as these issues occasionally do occur.
8419 </note></para>
8420
8421 <para>For such cases, you can use some tools to help you
8422 sort out the situation:
8423 <itemizedlist>
8424 <listitem><para>
8425 <emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis>
8426 You can find this tool in the
8427 <filename>scripts</filename> directory of the
8428 Source Repositories.
8429 See the comments in the script for information on
8430 how to use the tool.
8431 </para></listitem>
8432 <listitem><para>
8433 <emphasis>BitBake's "-S printdiff" Option:</emphasis>
8434 Using this option causes BitBake to try to
8435 establish the closest signature match it can
8436 (e.g. in the shared state cache) and then run
8437 <filename>bitbake-diffsigs</filename> over the
8438 matches to determine the stamps and delta where
8439 these two stamp trees diverge.
8440 </para></listitem>
8441 </itemizedlist>
8442 </para></listitem>
8443 </itemizedlist>
8444 </para>
8445 </section>
8446
8447 <section id='working-with-packages'> 8447 <section id='working-with-packages'>
8448 <title>Working with Packages</title> 8448 <title>Working with Packages</title>
8449 8449
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 03:46:28 +0000