summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-03-16 17:36:57 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-03-25 09:41:12 +0100
commita2ed012df785b5fb81946fc26923a0759088e8fa (patch)
tree3fb598ecd40692989ea5110af796c4f9621359b6 /documentation
parented80131abfd17ede1b93b23e4e84af198cac500d (diff)
downloadpoky-a2ed012df785b5fb81946fc26923a0759088e8fa.tar.gz
ref-manual: Updated the IMAGE_INSTALL variable description.
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>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/ref-manual/ref-variables.xml86
1 files changed, 50 insertions, 36 deletions
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 09eb9b9dfc..705b1977d8 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -5951,28 +5951,15 @@
5951 class. 5951 class.
5952 You should use the <filename>IMAGE_INSTALL</filename> 5952 You should use the <filename>IMAGE_INSTALL</filename>
5953 variable with care to avoid ordering issues. 5953 variable with care to avoid ordering issues.
5954 <note>
5955 When working with an
5956 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5957 image, do not use the <filename>IMAGE_INSTALL</filename>
5958 variable to specify packages for installation.
5959 Instead, use the
5960 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
5961 variable, which allows the initial RAM filesystem
5962 (initramfs) recipe to use a fixed set of packages and
5963 not be affected by <filename>IMAGE_INSTALL</filename>.
5964 For information on creating an initramfs, see the
5965 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
5966 section in the Yocto Project Development Tasks Manual.
5967 </note>
5968 </para> 5954 </para>
5969 5955
5970 <para> 5956 <para>
5971 Image recipes set <filename>IMAGE_INSTALL</filename> 5957 Image recipes set <filename>IMAGE_INSTALL</filename>
5972 to specify the packages to install into an image through 5958 to specify the packages to install into an image through
5973 <filename>image.bbclass</filename>. 5959 <filename>image.bbclass</filename>.
5974 Additionally, "helper" classes exist, such as 5960 Additionally, "helper" classes exist, such as the
5975 <filename>core-image.bbclass</filename>, that can take 5961 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>,
5962 class that can take
5976 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> 5963 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
5977 lists and turn these into auto-generated entries in 5964 lists and turn these into auto-generated entries in
5978 <filename>IMAGE_INSTALL</filename> in addition to its 5965 <filename>IMAGE_INSTALL</filename> in addition to its
@@ -5980,32 +5967,59 @@
5980 </para> 5967 </para>
5981 5968
5982 <para> 5969 <para>
5983 Using <filename>IMAGE_INSTALL</filename> with the
5984 <filename>+=</filename> operator from the
5985 <filename>/conf/local.conf</filename> file or from within
5986 an image recipe is not recommended as it can cause ordering
5987 issues.
5988 Since <filename>core-image.bbclass</filename> sets
5989 <filename>IMAGE_INSTALL</filename> to a default value using
5990 the <filename>?=</filename> operator, using a
5991 <filename>+=</filename> operation against
5992 <filename>IMAGE_INSTALL</filename> will result in
5993 unexpected behavior when used in
5994 <filename>conf/local.conf</filename>.
5995 Furthermore, the same operation from within an image
5996 recipe may or may not succeed depending on the specific
5997 situation.
5998 In both these cases, the behavior is contrary to how most
5999 users expect the <filename>+=</filename> operator to work.
6000 </para>
6001
6002 <para>
6003 When you use this variable, it is best to use it as follows: 5970 When you use this variable, it is best to use it as follows:
6004 <literallayout class='monospaced'> 5971 <literallayout class='monospaced'>
6005 IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>" 5972 IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
6006 </literallayout> 5973 </literallayout>
6007 Be sure to include the space between the quotation character 5974 Be sure to include the space between the quotation character
6008 and the start of the package name or names. 5975 and the start of the package name or names.
5976 <note><title>Caution</title>
5977 <itemizedlist>
5978 <listitem><para>
5979 When working with a
5980 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5981 image, do not use the
5982 <filename>IMAGE_INSTALL</filename> variable to
5983 specify packages for installation.
5984 Instead, use the
5985 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
5986 variable, which allows the initial RAM
5987 filesystem (initramfs) recipe to use a fixed
5988 set of packages and not be affected by
5989 <filename>IMAGE_INSTALL</filename>.
5990 For information on creating an initramfs, see
5991 the
5992 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
5993 section in the Yocto Project Development Tasks
5994 Manual.
5995 </para></listitem>
5996 <listitem><para>
5997 Using <filename>IMAGE_INSTALL</filename> with
5998 the
5999 <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
6000 BitBake operator within the
6001 <filename>/conf/local.conf</filename> file or
6002 from within an image recipe is not recommended.
6003 Use of this operator in these ways can cause
6004 ordering issues.
6005 Since <filename>core-image.bbclass</filename>
6006 sets <filename>IMAGE_INSTALL</filename> to a
6007 default value using the
6008 <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
6009 operator, using a <filename>+=</filename>
6010 operation against
6011 <filename>IMAGE_INSTALL</filename> results in
6012 unexpected behavior when used within
6013 <filename>conf/local.conf</filename>.
6014 Furthermore, the same operation from within
6015 an image recipe may or may not succeed
6016 depending on the specific situation.
6017 In both these cases, the behavior is contrary
6018 to how most users expect the
6019 <filename>+=</filename> operator to work.
6020 </para></listitem>
6021 </itemizedlist>
6022 </note>
6009 </para> 6023 </para>
6010 </glossdef> 6024 </glossdef>
6011 </glossentry> 6025 </glossentry>