diff options
author | James Cameron <quozl@laptop.org> | 2010-01-05 02:43:02 (GMT) |
---|---|---|
committer | James Cameron <quozl@laptop.org> | 2010-01-05 02:43:02 (GMT) |
commit | d2ad260a27dd76efda4cfe9e1d44dfd0d63bee76 (patch) | |
tree | a9b79f8ca126b97dd69a42ea3d29db2f1676f589 /doc | |
parent | 6cc90b63ffe245e49adbad6725fed0746db5d96d (diff) |
add a Quick Start to README and reformat
Tested olpc-os-builder on Fedora 11, and documented the steps required
to produce a build in a Quick Start section of the README.
Reformatted the previous text.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/README | 210 |
1 files changed, 136 insertions, 74 deletions
@@ -1,32 +1,64 @@ -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. +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 11, + + 2. install the build dependencies: + + yum install zlib-devel libtomcrypt-devel glibc-headers + + 3. build the package: + + make install + + 4. install the run-time dependencies: -The build is made based from a build configuration, which selects a series -of modules which were installed by olpc-image-builder. These modules (and -the configuration you provide) control the outcome of the build process. + yum install python-imgcreate bitfrost + + 5. produce a build: + + olpc-os-builder examples/f11-xo1.5.ini + + 6. 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-image-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. +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: @@ -39,15 +71,17 @@ 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 have a series of sections, each section title is -enclosed in square brackets. Inside each section, there are options. -For example, "mysection" below has one option, named "option1" with value -"myvalue": +Build configuration files have a series of sections, each section +title is enclosed in square brackets. Inside each section, there are +options. For example, "mysection" below has one option, named +"option1" with value "myvalue": + [mysection] option1=myvalue -Options can reside on multiple lines, provided that all lines beyond the first -one are indented, e.g.: +Options can reside on multiple lines, provided that all lines beyond +the first one are indented, e.g.: + [mysection] option1=this is an option @@ -55,65 +89,94 @@ one are indented, e.g.: but lines 2 through 4 must be indented option2=foo -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. +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: +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. e.g. 11 for - Fedora 11 +fedora_release -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 + The numeric release number of the Fedora operating system to base + the OLPC OS build on. For example, 11 for Fedora 11. -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_major -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 + 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. -customization_info 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. +olpc_version_minor -target_platform A textual description of the target platform for the - build, e.g. XO-1.5 + 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. -langs A set of languages to support in the resultant OS image. +olpc_version_release -modules The selection of modules to include in the build. + 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 -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. + 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. +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. + +modules + + The selection of modules to include in the build. + + +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. Design goals: - - revolve around Fedora's image-creator infrastructure, meaning that we use a - lot of Fedora's official build infrastructure + + - 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 + + - 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 + + - 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 + + +Fedora 11 Dependencies: + + Build-Requires: zlib-devel libtomcrypt-devel glibc-headers + Requires: python-imgcreate bitfrost Development: @@ -123,4 +186,3 @@ Development: Contact: devel@lists.laptop.org http://lists.laptop.org/listinfo/devel - |