[yocto] dev manual section on "customizing images" needs serious adjustment

[Robert P. J. Day]

  from here:

http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#usingpoky-extend-customimage-custombb

a couple gripes.

  end of 4.2.1 suggests

  IMAGE_INSTALL += "strace"

when creating a new image .bb file.  as i read it, the docs currently
suggest

  IMAGE_INSTALL_append = " strace"

when adding to your local.conf, and i don't think it's sufficiently
clear to the reader the distinction between "+=" and "_append", and
when to use one or the other.  and reading the source doesn't help
since it bounces back and forth constantly.  is this clarified
anywhere?

  a bigger gripe for me is this:

One way to get additional software into an image is to create a
custom image. The following example shows the form for the two lines
you need:

     IMAGE_INSTALL = "task-core-x11-base package1 package2"

     inherit core-image

no.  that is not a way to get "additional" software into an image, it
is a way to *override* core-image.bbclass's conditional setting of:

  IMAGE_INSTALL ?= "${CORE_IMAGE_BASE_INSTALL}"

which i think is overly confusing.  in general, i'm really unhappy
with the number of image definitions that explicitly set
IMAGE_INSTALL, *then* inherit core-image.  the potential to mislead
the reader as to what's happening is really overwhelming.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================