README

    This directory contains board and variant overlays.  When a board is
configured using "setup_board --board <board>" the following overlays are added
to the make.conf PORTDIR_OVERLAY if they exist:

    src/overlays/overlay-<board>
    src/private-overlays/overlay-<board>-private

    When a board is configured using "setup_board --board <board> --variant
<variant>" or "setup_board --board <board>_<variant>" the following overlays
are added if they exist:

    src/overlays/overlay-<board>
    src/overlays/overlay-variant-<board>-<variant>
    src/private-overlays/overlay-<board>-private
    src/private-overlays/overlay-variant-<board>-<variant>-private

    If --variant is supplied to setup_board or the <board>_<variant> version
of --board is supplied to setup_board then the primary variant overlay must
exist.

    A private board overlay can augment an existing non-private board overlay,
or can serve as the primary board overlay for a board with no non-private board
overlay.

    All board overlays (including variants) should contain a make.conf.  If
this file exists it will be sourced in the order that the overlays and variants
are listed above.

    All board overlays should contain a toolchain.conf, specifying the
toolchains required to build that board.  Variants can inherit toolchain.conf
from their primary board overlay.

    The board and variant names can not have underscores or spaces in them.


PROFILES
--------
    All overlays must contain a profiles directory with a repo_name file
therein.  The repo_name file provides a unique name Portage uses to identify
each overlay or variant.

    Overlays and variants can also contain named profiles as subdirectories of
the profiles directory.  If the board overlay contains a "base" profile,
Portage will use that by default for the board; otherwise, Portage will use a
profile from chromiumos-overlay.

    Within a profile, a board overlay will most commonly want to specify
package-specific USE flags via package.use, mask or unmask package versions via
package.mask and package.unmask, or mask or unmask keywords via
package.keywords.  See "man portage" in the chroot for full details on those
and other files that can appear in a profile.

    Profiles in a board overlay must have a file "parent", containing the full
path of one of the profiles from chromiumos-overlay, as seen from the build
chroot; /usr/local/portage/chromiumos/profiles in the chroot maps to
src/third_party/chromiumos-overlay/profiles in the source tree.  The parent
must point to an architecture-appropriate profile, typically
/usr/local/portage/chromiumos/profiles/default/linux/$arch/$version/chromeos.
Profiles can use another profile from the same board as their parent, as long
as the chain of parent profiles eventually leads to an architecture-appropriate
profile from chromiumos-overlay.

    Adding a base profile to a board overlay that did not previously have a
profile will require re-running setup_board with --force.


LAYOUT.CONF
-----------
    Overlays should contain a metadata directory with a layout.conf file
therein.  The layout.conf file specifies the "masters" list.  This is a list of
repository names, taken from the repo_name files in the overlays.  This list
disambiguates the selection of ebuilds.  When two overlays supply the same
ebuild the overlay whose repo_name is listed later in the masters list will be
used.  The masters list also effects the way that portage searches for
eclasses.  By having the repo_name "chromiumos" as the last entry in the
masters list portage will correctly find the chromiumos specific eclasses.


BOARD-SPECIFIC PACKAGES
-----------------------
    A board overlay will typically want to provide additional packages to
install.  ChromiumOS builds install the chromeos/chromeos package by default,
whose RDEPEND brings in all the packages installed by default.
chromeos/chromeos RDEPENDs on the virtual package virtual/chromeos-bsp, which
exists for board overlays to override.  chromiumos-overlay provides a default
version of virtual/chromeos-bsp which RDEPENDs on the empty package
chromeos-base/chromeos-bsp-null.  Board overlays should provide a
virtual/chromeos-bsp package that RDEPENDs on
chromeos-base/chromeos-bsp-boardname, and a
chromeos-base/chromeos-bsp-boardname package that RDEPENDs on any desired
board-specific packages.

    A board overlay can also provide additional packages to install in dev
builds only, via similar packages virtual/chromeos-bsp-dev and
chromeos-base/chromeos-bsp-dev-boardname.  ChromiumOS dev builds install
chromeos-base/chromeos-dev by default, which RDEPENDs on
virtual/chromeos-bsp-dev.

    Note that a board overlay cannot specify package-specific USE flags by
using an RDEPEND with a use flag, such as section/package[useflag]; instead,
add "section/package useflag" to package.use in a profile.


PRIVATE HOST OVERLAYS
---------------------

    The host (non-cross-compiling) build environment will use the following
overlay if it exists:

    src/private-overlays/chromeos-overlay

    This overlay contains private packages needed on the host system to compile
target packages used in a private overlay.  Packages only needed on the target
system should appear in a private board overlay.  The packages in a private
host overlay should typically all appear in the dependency chain of
chromeos-base/hard-host-depends so that the build process will install them on
the host system at the appropriate time.  chromeos-base/hard-host-depends
depends on the virtual package virtual/hard-host-depends-bsp to allow a private
host overlay to extend the host dependencies; a private host overlay can
provide a version 2 ebuild for virtual/hard-host-depends-bsp, and list any
additional host dependencies in the RDEPEND of that package.

    Like a board overlay, a private host overlay must include a layout.conf
with "masters" set, so that the packages within that host overlay can reference
eclasses from the parent overlays chromiumos-overlay or portage-stable.