NAME
	install.sh - Auto-Installer for Debian on the Openmoko Neo phones (GTA01 and GTA02) v3.1

SYNOPSIS
	[variable1=value1 variable2 ...] install.sh [options] all
	[variable1=value1 variable2 ...] install.sh [options] 

DESCRIPTION

	This script is to be executed on an OpenMoko Neo devices
	(either 1973 or FreeRunner), two openly designed telephones,
	to install the Debian operating system on an SD card. The
	system goes through multiple stages, and can be modified to
	adapt to local preferences.

	The individual stages are described below. The script uses
	cdebootstrap or debootstrap to prepare a directory to which
	it can chroot(8) and complete the configuration. 

ENVIRONMENT

	To influence the program's behaviour, set the following
	environment variables or leave the default values.

	APT_OPTIONS  extra parameters sent to apt for installing packages (set
                     to ' --yes').
	HOSTNAME     the name of the machine (set to 'moszumanska').
	SD_DEVICE    the character device to access the microSD card (set to
                     '/dev/mmcblk0').
	SD_SYS_BLK   the directory under /sys/block that refers to the microSD
                     card (set to '/sys/block/mmcblk0', or derived from the
                     value of SD_DEVICE).
	SD_PART1_FS  the filesystem for the first microSD card partition, i.e.
                     the one containing the uImage.bin (set to 'ext2', possible
                     values are ext2/vfat, also ext3 when using Qi as
                     bootloader).
	SD_PART1_SIZE
                     number of megabytes for first partition (set to '8').
	SD_SWAP_SIZE
                     number of megabytes of swap partition (set to '0').
	INST_DIR     the directory where the microSD card partitions will be
                     mounted to (set to '/mnt/debian').
	INST_MIRROR  the Debian mirror used during installation, it should be
                     set to a mirror nearby that carries armel binaries for
                     unstable and experimental (set to
                     'http://ftp2.de.debian.org/debian').
	LOCALEPURGE  set this to true, if you want to install the package of the
                     same name. It reduces disk space enormously, but needs user
                     interaction for the install (set to '').
	APT_RECOMMENDS
                     control if APT should install recommends by default (set to
                     'false', possible values are false/true).
	BOOTSTRAPPER determines the bootstrapper to use, should be set to
                     deboostrap or cdebootstrap - cdebootstrap is somewhat
                     faster and you may have to "opkg install perl", but it
                     seems to work less reliably (set to 'cdebootstrap').
                     For debootstrap please do not run anything besides
                     install.sh as you will need all your memory.
	CDEBOOTSTRAP_EXTRA_FLAGS
                     parameters to be added to invocation of cdebootstrap, only
                     active if BOOTSTRAPPER is not set to debootstrap.
	DASH_BINSH   configure dash as default /bin/sh (set to 'true', possible
                     values are true/false).
	DEBOOTSTRAP_EXTRA_FLAGS
                     parameters to be added to invocation of debootstrap, only
                     active if BOOTSTRAPPER is not set to cdebootstrap.
	FSO_MIRROR   the Debian freesmartphone.org repository (set to
                     'http://pkg-fso.alioth.debian.org/debian').
	FSO_DEVICE   the device the installation is being performed on (set to
                     '', default to autodetection, possible values are
                     gta01/gta02).
	QI           if you use Qi bootloader set this to true (set to 'false').
	QI_VERBOSE_BOOT
                     set this to true if you want to see the kernel messages; do
                     this only when QI=true (set to 'false').
	RDATEHOST    machine with which to sync against with ntp (set to
                     'ntp.fu-berlin.de').
	SINGLE_PART  set this to true if only one partition should be created;
                     this is true by default for QI=true and false if
                     SD_PART1_FS=vfat (set to 'false').
	TRAYER       name of package to fill the menu bar, supported are
	             'trayer' and 'stalonetray' (set to 'trayer').
	TESTHOST     name of machine that should be tested for availability
                     (set to 'www.debian.org').
	VERBOSE      increase amount of information that is forwarded to stdout
                     (set to '').
	DISPLAY_MANAGER
                     choose the Display Manager to be installed (default to
                     'nodm', possible values are any *dm package in the Debian
                     archive, which could require a LOT of disk space; set this
                     to none if you do not want a Display Manager).
	ZHONE        set this to true to install the Zhone GUI (set to 'true').
	ROOT_PASSWORD
                     the password for the root account (set to 'changeme').

    Stages:

	all          Runs all the stages in the following order:
                                testing time partition format mount
                                debian apt fso configuration tasks
                                kernel cleanup unmount
	testing      Verifys that everything is in place for this
                     installer to work
	time         Fetches the current time from ntp.fu-berlin.de via rdate
	partition    Partitions the microSD card found in /dev/mmcblk0
                     (WARNING, this will destroy all the data on the
                     microSD card unless the partioning is the same as
                     used before; this can be used to recover a broken
                     partiton table due to the suspend/resume problem)
	format       Formats the microSD card found in '/dev/mmcblk0'
                     (WARNING, this will destroy all the data on the
                     microSD card)
	mount        Mounts microSD card partitions under '/mnt/debian'
	debian       Installs a basic Debian system, including an SSH server
	apt          Configure APT
	fso          Install freesmartphone.org packages (by default this
                     also include the Zhone GUI, see the ZHONE variable)
	tasks        Installs packages for a series of tasks. Supported are
                       AUDIO  (intone)
                       COM    software supporting the communication of
                              users (zhone pidgin).  zhone is always
                              installed.
                       GAMES  installs games that were designed with
                              FreeRunner-like devices in mind or that have
                              been found compatible (mokomaze sgt-puzzles)
                       GPS    software for GPS, geocaching and navigation
                              (tangogps navit)
                       NET    software that is beneficial to investigate
                              the network setup and/or forward traffic
                              to USB-attached devices, e.g. to connect a
                              a laptop to the internet via the freephone's
                              internet connection (GPRS or Wifi).  See
                              http://wiki.openmoko.org/wiki/Tethering for
                              the setup (inetutils-ping host iptables).
                       TEXT   allows improved handling of text
                              (less)
                       WEB    (midori epdfview)
                       WIFI   (dhcp3-client wpasupplicant wireless-tools)
                       UTILS  whatever was wanted that does not belong to the
                              other classes (scrot debfoster)
                       ALL    Selection of all the tasks listed above.

                     To specify the tasks shall be assigned to the TASKS
                     environment variable as a comma separated list (set to
                     '').
	configuration    Configures various parts of the system, such as
                     the X server
	kernel       Downloads and installs the Debian kernel package (only
                     when SD_PART1_FS is set to ext2, now 'ext2')
	cleanup      Remove unnecessary package and clean APT cache
	unmount      Unmounts the Debian filesystem mounted at '/mnt/debian'

    Unsupported or buggy stages, use at your own risk:

	uboot	     Configures the U-Boot environment to boot Debian (it
                     needs to run between the debian and the unmount stage,
                     only when SD_PART1_FS is set to ext2, now 'ext2')

OPTIONS
	For users uncomfortable with setting environment variables, the following
	options have been implemented to be set as arguments:

        -h|--help    shows this information
	--verbose    same as invocation with VERBOSE=true as environment variable
	--apt-options 
                     sets the APT_OPTIONS variable
	--hostname 
                     sets the HOSTNAME variable
	--mount-proc
                     mounts /proc directory in Debian chroot
	-np|--no-partitioning
                     disable the partitioning when otherwise doing "all"
	--part1-fs 
                     sets the SD_PART1_FS variable
	--part1-size 
                     sets the SD_PART1_SIZE variable
	--swap-size 
                     sets the SD_SWAP_SIZE variable
	--with-tasks 
                     sets the TASKS variable
	--with-localepurge
                     will install the localepurge package
	--trayer 
                     sets the TRAYER variable
	--bootstrapper (debootstrap|cdebootstrap)
                     sets the BOOTSTRAPPER variable

EXAMPLE

	Next to your install.sh script you may want to create a file
	that remembers the parameters for you that you have chosen for
	your previous setup.

	./install.sh --part1-fs vfat --part1-size 16  all

	Performs a complete installation. Tasks would be addressed if the
	TASKS environment variable would have been set.

	TASKS="GAMES,GPS" ./install.sh --part1-fs vfat --part1-size 16  all

	As before, but now extra packages are installed (and configured)
	to prepare a selection of games and a reasonably complete utilisation
	of the GPS funcionality.

	TASKS="GAMES,GPS" ./install.sh --part1-fs vfat --part1-size 16  tasks

	This is the delta between the prior two examples.

	TASKS="GAMES,GPS" ./install.sh --part1-fs vfat --part1-size 16

	E: This does nothing since no install target is defined.

BUGS
	Only the current (second) generation of devices is fully supported.
	This script should be functional with the GTA01 except for the
	installation of the kernel.

	For comments or contributions, you can directly send emails
	to the list mentioned below. However, please be aware of the
	pkg-fso git repository that helps orchestrating our efforts. You
	can check it out with
	  git clone git://git.debian.org/pkg-fso/files.git
	perform your changes and prepare patches with
	  git format-patch origin/master
	to send to the authors or to the pkg-fso mailing list
	pkg-fso-maint@lists.alioth.debian.org .

AUTHORS
	Copyright 2008 Joachim Breitner 
	Copyright 2008 Luca Capello 
	Copyright 2009 Steffen Moeller 

	This program is licensed under the terms of GNU General Public
	License either version 2, or (at your option) any later version.

SEE ALSO
	This project's homepage: http://wiki.debian.org/DebianOnFreeRunner
	The OpenMoko project: http://www.openmoko.org