WHAT IS GUACAMAYO?!
-------------------
Guacamayo is a customizable platform for multimedia appliances, based on the
Yocto framework (what else?).


HARDWARE
--------
At present images are known to work with Intel Atom based devices such as Zotac
ZBox, the Beagleboard/Beaglebone boards and Raspberry Pi (though not all image
types are available for all of these). Please see the board-specific READMEs in
the doc directory.


BUILDING IT
-----------

  git clone git://github.com/Guacamayo/meta-guacamayo.git
  cd meta-guacamayo
  git submodule update --init

  source init-build-env

  # Now edit build/conf/local.conf to suit your needs; among other things,
  # please pay attention to the LICENCSE_FLAGS_WHITELIST variable
  # discussed below.

  # Beagleboard: you will need to download Texas Instruments Code Generation
  # Tools: see meta-guacamayo/recipes-graphics/ti-appends/ti-cgt6x_*.bbappend
  # for details of what to do.

  bitbake guacamayo-image-<type>

  (For the image types, see below.)

The resulting images are located in the tmp/deploy/images directory; image type
and subsequent installation is, naturally, depended on the device.


PACKAGE LICENSES
----------------
By default, Guacamayo uses only packages with non-restrictive licenses, but some
useful packages do not fall into this category (e.g., codecs). You can enable
the use of these by appropriately setting the variable LICENSE_FLAGS_WHITELIST
in your local.conf. Currently two types of restrictions are in place:

'commercial':      packages with this license flag require the purchase of a
                   license for commercial deployment (e.g., Fluendo codecs for
                   GStreamer), but are free for non-commercial use.

'non-commercial':  packages in this category can *only* be used non-commercially
                   and must not be commercially deployed (e.g., the package
                   connman-guacamayo-ntp containing configuration for the NTP
                   pool, in this case commerical users must use their own NTP
                   pool).


TWEAKING IT
-----------
Documentation on working with Poky in general can be found at yocto-project.org;
the following is specific to Guacamayo:

Image Types
...........
Guacamayo provides several different image recipes aimed at different types
of appliance:

guacamayo-image-mediaserver: an image for network attached UPnP/DLNA media
                             server (no rendering capabilities); this is the
                             most minimal of Guacamayo images.

guacamayo-image-audioplayer: a small image for an audio player; works on Atom,
                             Raspberry Pi, Beaglebone and Beagleboard ; good
                             place to start at.

guacamayo-image-mex:         An image with MediaExplorer shell. Depending on
                             the machine, the shell is running under either
			     under X11 or under native EGL.

NB: The MEX elg and x11 packages sets are not parallel installable, use if you
    want to experiment with switching from the default for the given machine,
    make sure to build in a different tmp directory.


Audio Codecs
............
Out of the box you get support for Ogg and Flac; Mp3 support in Guacamayo images
is facilitated by the Fluendo GStreamer plugin, but as this requires a license
for commercial use, it is disabled by default; you can enable it by whitelisting
commercial licenses in your build/conf/local.conf as discussed above.


REPOSITORY LAYOUT
-----------------
The git repository contains the build system for the guacamayo images, with the
following sub directories:

meta-guacamayo: the Guacamayo layer for Poky; the aim is to keep this as thin
          as possible, using upstream Yocto packages where possible and
          appropriate.

upstream: this is where the upstream meta layers go; to add a new meta layer:
           1. add git submodule into a subdirectory of upstream
           2. link the meta-whatever directory into the layers directory
           3. update meta-guacamayo/conf/bblayers.conf.sample accordingly
           4. rm build/conf/bblayer.conf so it gets regenerate in the next step
           5. source init-build-env

layers:   this directory holds all the layers into a single whole; it should
          contain no real files, only symlinks