blob: 6c83186d7e7f8e16a0b1eb4607b18bd87701b45b [file] [log] [blame]
# Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
Chrome OS Factory Bundle Automation Script README
Usage documentation for
Table of Contents
Script Requirements
Getting Started
Script background
Notes on script behavior
Alternate bundle naming
Alternate tar file destination
Known Limitations
Common Errors and Exceptions
Script Requirements
-Chrome OS source code checkout, see Developer's Guide at
-uudecode utility found in package sharutils for used
in ssd image firmware extraction
-> manual install: sudo apt-get install sharutils
-pbzip2 utility for parllel bzip compression of factory bundle tar file
-> sudo apt-get install pbzip2
-chroot setup for default ssd conversion
-> Developer's Guide above
Note: For internal use please consult documentation for building Chrome OS
internally as it has differing instructions.
Getting Started
Convenience commands (assumed by all other examples)
in standard terminal:
>$ export CHROMEOS_ROOT=/home/$USER/chromiumos/
>$ cd $CHROMEOS_ROOT/src/scripts
>$ ln -s ../platform/factory-utils/ cros_bundle
View script options
>$ cd $CHROMEOS_ROOT/src/scripts
>$ python cros_bundle --help
Sample usage command:
This command will create an fsi bundle with two recovery and release images
using the default naming scheme factory_bundle_yyyy_mm_dd.tar.bz2. It will
use the previously named Chrome OS source tree root and will not upload the
bundle produced to GSD. Runs non-interactively forcing overwrite.
>$ export CHROMEOS_ROOT=/home/$USER/chromiumos/
>$ cd $CHROMEOS_ROOT/src/scripts
>$ python cros_bundle --board x86-alex --recovery 0.15.916.0/dev/mp
--board2 x86-alex-he --recovery2 0.15.916.0/dev/mp
--factory 0.15.916.0/dev --fsi --chromeos_root $CHROMEOS_ROOT
--no_upload --force
Verify bundle creation:
The script will output the directory where the factory bundle has been
placed, say /usr/local/google/cros_bundle/tmp/. We verify the bundle with
the following commands:
>$ cd /usr/local/google/cros_bundle/tmp
>$ ls -lR
# at this point, assuming default naming, we should see directory
# factory_bundle_yyyy_mm_dd containing bundle files and a matching tar.bz2
>$ pbzip2 -d factory_bundle_yyyy_mm_dd.tar.bz2
# by default the bundle files used are not cleaned away, so we make a
# scratch directory to verify the files are those pulled from the tar
>$ mkdir bundle_files
>$ mv factory_bundle_yyyy_mm_dd.tar bundle_files
>$ cd bundle_files
>$ tar -xvf factory_bundle_yyyy_mm_dd.tar
>$ ls -lR factory_bundle_yyyy_mm_dd
# a more thorough test would be to run through a factory install process
# on a test device using the factory bundle tar file produced.
Cleanup command:
The following command will delete all temporary bundle files from the
default working directory named WORKDIR in Presently the
only script action, including logging, which creates state outside of
WORKDIR is the --full_ssd option, which makes cgpt available outside chroot
in SUDO_DIR, a constant set in
>$ python --clean
Script background
Factory bundles are collections of Chrome OS images accompanied by extracted
image components and other scripts useful to factory partners in the
production of Chrome OS devices.
The process of creating bundles can be tedious, therefore an automated script
for their production lives in the Chrome OS source tree in the repository
Notes on script behavior
- This script runs outside the chroot environment in the
<ChromeOS_root>/src/scripts directory.
- The automated bundling script runs outside the chroot environment but
requires a chroot to be setup for default use converting recovery to ssd.
- By default it will not include a stateful partition in the release image.
- Assumes sufficient disk space in /usr partition, at least 20 GB free.
- Since default naming is unique up to the day a bundle is produced, when
making a second bundle in one day the first will be deleted by default.
Alternate bundle naming
To specify a non-default bundle name such as my_new_bundle, use the
--bundle_dir option. Note that the bundle_dir directory must be writable.
>$ python cros_bundle --board x86-alex --recovery 0.15.918.0/dev/mp
--board2 x86-alex-he --recovery2 0.15.918.0/dev/mp
--factory 0.15.918.0/dev --fsi --chromeos_root $CHROMEOS_ROOT
--no_upload -f --bundle_dir=/usr/local/.../my_new_bundle
# Bundle tar file my_new_bundle.tar.bz2 will be produced in default WORKDIR
# Bundle files will be stored for reference in /usr/local/.../my_new_bundle
# All other temporary files will remain in default WORKDIR
Alternate tar file destination
To specify a non-default destinaiton directory for the factory bundle tar
file use the --tar_dir option. Note the tar_dir directory must be writable.
>$ python cros_bundle --board x86-alex --recovery 0.15.918.0/dev/mp
--board2 x86-alex-he --recovery2 0.15.918.0/dev/mp
--factory 0.15.918.0/dev --fsi --chromeos_root $CHROMEOS_ROOT
--no_upload -f --tar_dir=/tmp
# Bundle tar file factory_bundle_yyyy_mm_dd.tar.bz2 will be produced in /tmp
# Bundle files will be stored for reference in default WORKDIR
# All other temporary files will remain in default WORKDIR
Known Limitations
Currently only supports Alex factory bundles.
Does not support download from GSD.
Does not support using local images unless valid md5 file is present and
image name can be fully resolved from chromeos-images webserver. This
limitation applies to all bundle files.
Functional testing assumes a default value of Chrome OS source tree root.
Common Errors and Exceptions
1.NameResolutionError when an exact image url cannot be resolved, it is
possible that the image is no longer posted on the chromeos-images
webserver. It is also possible that minor naming variations in index
pages derived from said images page have made some resources fail to be
An example:
Name resolution failed on:
Recovery image exact URL could not be determined given input:
Script exiting due to:
Failed to determine URL at which to fetch images, please check the logged
URLs attempted.
Go to http://chromeos-images/ and search for release 0.13.587.116,
examine URL for recovery image under Bin column
If the URL starts with”,
that means the image has been archived in GSD.
If the URL starts with http://chromeos-images/...”, navigate to the index
page for that particular build, e.g. if the image URL is
then the corresponding index page can be found @
Once on the index page, ensure that links for all required bundle inputs
are present.
The script does NOT currently support fetching images from GSD.
[Were hoping to leverage CPFE to avert this breakage in the future.]
Contact factory build and release team (scottz, djmm) asking that each
bundle component missing be brought out of archive storage - check all
links for necessary bundle components before running script again.
2.Script not run from <ChromeOS_root>/src/scripts
An example:
Script exiting due to:
ConvertRecoveryToSsd must be run from src/scripts.
>$ cd $CHROMEOS_ROOT/src/scripts
Then repeat bundling command.
3.Intended to request fsi bundle but requested non-fsi factory bundle
An example:
Script exiting due to:
Must specify install shim for non-fsi bundle.
Append --fsi to bundling command, retry.