path: root/doc/README

olpc-os-builder is an application to generate OS images for XO
laptops.  It is the successor to pilgrim and fedora-xo which were used
to generate prior OLPC OS releases.


Quick Start:

    1.  install Fedora 14,

    2.  install the build package:

        yum install olpc-os-builder

    3.  produce a build:

        olpc-os-builder /usr/share/doc/olpc-os-builder-*/examples/f14-xo1.5.ini

    4.  view or use the build result files:

        ls -l /var/tmp/olpc-os-builder


Description:

The build is made based from a build configuration, which selects a
series of modules which were installed by olpc-os-builder.  These
modules (and the configuration you provide) control the outcome of the
build process.

olpc-os-builder lets you build your own OLPC OS builds, with your own
customizations.  In fact, one of the design goals is to make it easier
for OLPC deployments to make their own customizations.  In this case,
the general usage model is to take one of the example configurations
which corresponds to the OLPC OS that you want to ship, and then make
a handful of modifications according to your local requirements.
These example configurations exactly match the build configurations
that OLPC used to make the published OS release.

When using olpc-os-builder in this fashion, you should take care to
match your runtime environment with the one that OLPC used when the
base OS image was originally released.  For example, if OLPC OS
release 10.2.0 was built with olpc-os-builder-1.0.3 on Fedora 11, and
you want to modify this particular release but you are using
olpc-os-builder-1.2.0 on Fedora 12 then the output images may differ
significantly from the official OLPC OS release 10.2.0, which is
probably not what you want.

The example build configurations encode the version of olpc-os-builder
which was used by OLPC at the time that each build was made.  With
this information, olpc-os-builder will warn you at the start of a
build when you attempt to build such an image on a configuration that
differs from the environment where the corresponding official OLPC OS
release was made.


Usage:
	olpc-os-builder [options] <path to build config> [path to build config...]


Offline use:

olpc-os-builder naturally involves a fair amount of downloading in its work.
These downloads are cached, meaning that while the first run will do a lot
of downloading, subsequent runs will reuse the locally cached content.

However, those subsequent runs will still go online in order to check that
cached content is up-to-date. This can be time consuming, especially
on slow connections.

If you want olpc-os-builder to trust its local caches, and not even go
online to check that they are current, you can provide the --cache-only
command-line option.

For obvious reasons, cache-only mode requires you to have previously run
the same build configuration in "normal" mode beforehand (i.e. without
--cache-only specified), so that caches are populated.

Be aware that less cache validation is performed during --cache-only runs.
This means that corrupt caches or truncated files could be treated as good
in cache-only mode, whereas such problems are generally detected and
corrected when connectivity is used.


Configuration:

Various build configurations can be found in the examples directory
included with the distribution, including configurations used to build
OLPC OS releases.

Build configuration files specify a series of modules, each module
title being enclosed by square brackets.  Inside each module, there are
options.  For example, "mymodule" below has one option, named
"option1" with value "myvalue":

	[mymodule]
	option1=myvalue

Options can reside on multiple lines, provided that all lines beyond
the first one are indented, e.g.:

	[mymodule]
	option1=this is
		an option
		that spans 4 lines
		but lines 2 through 4 must be indented
	option2=foo

The modules selected by your build configuration file correspond to modules
shipped by olpc-os-builder. A module is loaded simply by specifying it in
the build configuration. You do not have to specify any options in the cases
when the default settings meet your needs, or when the module has no options,
e.g.:

	[sugar]
	[gnome]

Multiple configuration files can be specified. They will be parsed in the
order provided (i.e. later config files can override values from earlier
ones).

Interpolation (basic assignment and use of variables) can be used, according
to Python's SafeConfigParser documentation.

Default variables automatically provided:

oob_config_dir

	The directory where the first specified config file resides

In general, each section that can exist in the configuration file
corresponds to a specific module.  The section name is the same as the
module name.  The options that can exist in these sections are
documented in the individual module documentation files.

There is one exception: the [global] section does not belong to any
module.  So we'll document it here, according to each possible
setting:

fedora_release

    The numeric release number of the Fedora operating system to base
    the OLPC OS build on.  For example, 11 for Fedora 11.

fedora_arch

    The processor architecture to use for Fedora package selection.
    See http://mirrors.fedoraproject.org/ for the available values.

olpc_version_major

    The major version component of the OLPC version tag to include in
    the OS image.  For example, in the OLPC OS 10.1.0 release, this
    would be 10.

olpc_version_minor

    The minor version component of the OLPC version tag to include in
    the OS image.  For example, in the OLPC OS 10.1.0 release, this
    would be 1.

olpc_version_release

    The release version component of the OLPC version tag to include
    in the OS image.  For example, in the OLPC OS 10.1.0 release, this
    would be 0.

customization_info

    This identifier will be displayed in the Sugar control panel and
    in other places on the system, to indicate the source of the OS
    build.

    Please set this to a string that indicates your identity, to make
    clear that the resultant build is a modified version of OLPC's
    official release.  For example, you could use something like
    "customized for Paraguay" when producing an OS build for OLPC's
    Paraguayan deployment.

customization_tag

    This tag will be included in the names of the output files, as a quick
    way of identifying origin. The default value is "xx".

    Please set this to a tag (one or two characters) representing your
    identity. Your two-letter country code may be a good choice here.
    For example, for the OLPC Paraguay project, "py" would be a sensible
    choice. "o" is used by OLPC.

target_platform

    A textual description of the target platform for the build, for
    example XO-1.5.

langs

    A set of languages to support in the resultant OS image.


In general, options need to be set with care.  Aim to stick with the
values shown in the examples where possible.  For example, if you were
to exclude the "base" module from the build then you will get strange
results.  Also, you cannot arbitrarily change fedora_release without
adapting all of the module code to work with the ever-changing
components of each official Fedora release.


Output:

At the end of the process, a series of filenames are saved in an output
directory. The path to this directory is printed at the end of the process.
Files within this directory are named according to a version scheme
encompassing the major and minor version number, the build numer, the target
laptop model, and the customisation tag. See
http://wiki.laptop.org/go/Release_Process#Version_numbering for more details
on this scheme.


Design goals:

 - revolve around Fedora's image-creator infrastructure, meaning that
   we use a lot of Fedora's official build infrastructure

 - allow XO-1 and XO-1.5 builds from the codebase

 - limit all configuration to a single INI-style text file

 - through the configuration file, allow common deployment
   modifications to be made without too much technical know-how

 - copy elements of dracut's modular design to achieve the above

 - eliminate the need for image-builder, which had the undesirable
   effect of replicating some of the build infrastructure in 2 places

 - avoid any 'difficult' system requirements so that this can be
   packaged into official Fedora and hence easily installed and used
   by deployments


Development:
	See README.devel


Contact:
	devel@lists.laptop.org
	http://lists.laptop.org/listinfo/devel