mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-18 03:32:13 +02:00
Code Issues Packages Projects Releases Wiki Activity

ref-manual: Updated the IMAGE_INSTALL variable description.

Browse Source 
I created a two-bullet "Caution" note to highlight the stuff a
user needs to be aware of that can cause problems.

(From yocto-docs rev: 553bc13e5fd350adb15400afe170e587965929db)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2018-03-16 17:36:57 -07:00
committed by Richard Purdie
parent ed80131abf
commit a2ed012df7
1 changed files with 50 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
documentation/ref-manual/ref-variables.xml
View File

@@ -5951,54 +5951,21 @@
class.
You should use the <filename>IMAGE_INSTALL</filename>
variable with care to avoid ordering issues.
<note>
When working with an
<link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
image, do not use the <filename>IMAGE_INSTALL</filename>
variable to specify packages for installation.
Instead, use the
<link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
variable, which allows the initial RAM filesystem
(initramfs) recipe to use a fixed set of packages and
not be affected by <filename>IMAGE_INSTALL</filename>.
For information on creating an initramfs, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
section in the Yocto Project Development Tasks Manual.
</note>
</para>
<para>
Image recipes set <filename>IMAGE_INSTALL</filename>
to specify the packages to install into an image through
<filename>image.bbclass</filename>.
Additionally, "helper" classes exist, such as
<filename>core-image.bbclass</filename>, that can take
Additionally, "helper" classes exist, such as the
<link linkend='ref-classes-core-image'><filename>core-image</filename></link>,
class that can take
<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
lists and turn these into auto-generated entries in
<filename>IMAGE_INSTALL</filename> in addition to its
default contents.
</para>
<para>
Using <filename>IMAGE_INSTALL</filename> with the
<filename>+=</filename> operator from the
<filename>/conf/local.conf</filename> file or from within
an image recipe is not recommended as it can cause ordering
issues.
Since <filename>core-image.bbclass</filename> sets
<filename>IMAGE_INSTALL</filename> to a default value using
the <filename>?=</filename> operator, using a
<filename>+=</filename> operation against
<filename>IMAGE_INSTALL</filename> will result in
unexpected behavior when used in
<filename>conf/local.conf</filename>.
Furthermore, the same operation from within an image
recipe may or may not succeed depending on the specific
situation.
In both these cases, the behavior is contrary to how most
users expect the <filename>+=</filename> operator to work.
</para>
<para>
When you use this variable, it is best to use it as follows:
<literallayout class='monospaced'>
@@ -6006,6 +5973,53 @@
</literallayout>
Be sure to include the space between the quotation character
and the start of the package name or names.
<note><title>Caution</title>
<itemizedlist>
<listitem><para>
When working with a
<link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
image, do not use the
<filename>IMAGE_INSTALL</filename> variable to
specify packages for installation.
Instead, use the
<link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
variable, which allows the initial RAM
filesystem (initramfs) recipe to use a fixed
set of packages and not be affected by
<filename>IMAGE_INSTALL</filename>.
For information on creating an initramfs, see
the
"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
section in the Yocto Project Development Tasks
Manual.
</para></listitem>
<listitem><para>
Using <filename>IMAGE_INSTALL</filename> with
the
<ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
BitBake operator within the
<filename>/conf/local.conf</filename> file or
from within an image recipe is not recommended.
Use of this operator in these ways can cause
ordering issues.
Since <filename>core-image.bbclass</filename>
sets <filename>IMAGE_INSTALL</filename> to a
default value using the
<ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
operator, using a <filename>+=</filename>
operation against
<filename>IMAGE_INSTALL</filename> results in
unexpected behavior when used within
<filename>conf/local.conf</filename>.
Furthermore, the same operation from within
an image recipe may or may not succeed
depending on the specific situation.
In both these cases, the behavior is contrary
to how most users expect the
<filename>+=</filename> operator to work.
</para></listitem>
</itemizedlist>
</note>
</para>
</glossdef>
</glossentry>