Portage is the build and packaging system used on CrOS Core. Portage was originally developed as part of the Gentoo Linux Distribution.
CrOS Core uses Portage with certain customizations to support building multiple targets (OS system images) across different hardware architectures from a shared set of sources.
Upstream portage documentation can be found here. Below, we describe some basic terminology that will be useful while working with CrOS Core.
A board defines a target type. For example, ‘beaglebone’ is a target type for a CrOS Core system image that runs on beaglebone.
Each board has a corresponding overlay that defines the configuration for it. This includes details like CPU architecture, kernel configuration, as well as additional packages and USE flags (see below).
Example: overlay-beaglebone defines configuration for the beaglebone target.
An overlay can also act as parent of other derivative boards. The derivative overlays or variants share configuration from the base board/overlay.
Example: beaglebone_servo is a variant board (and overlay-beaglebone-servo, the corresponding overlay) that derives from the base beaglebone (overlay-beaglebone) configuration).
Note: Currently variant boards share the CPU architecture. This is just by convention. More flexible support for sharing overlay configurations is on the roadmap for Q2 2014.
A CrOS Core operating system image is a collection of packages (along with any required dependencies). These can be upstream third party software (e.g. openssl) or your own custom libraries and applications.
Each package is defined by an ebuild file that describes how the software is built and installed. It can define (amongst other things):
USE flags define and control optional system and package features.
For example: USE=udev controls whether udev support is built-in to the system or now.
A DEPEND for a package defines all its build time dependencies.
For example: The vboot_reference package requires the trousers libraries (app-crypt/trousers) to build.
A RDEPEND for a package defines its run time dependencies.
For example: The vboot_reference package requires openssl to be present at run time.
Emerge is a portage tool that’s used to build and install a package. On CrOS Core, you will typically use your board-specific wrapper.
Example: emerge-beaglebone is the emerge wrapper to use when working on the beaglebone board/overlay.
Portage provides many others tools that are useful in working with packages and ebuilds. Here are two we find very useful:
Note: For both of these, you’d probably want to be using your board/overlay specific version. e.g. qlist-beaglebone, equery-beaglebone, etc.