Installation Instructions

23rd June 2003

*** The stuff below this line refers to the old way of installing intimate designed to be run from inside familiar 0.5. There is a new way to install now using the boot-from-vfat functionality in the newer bootloaders. Details of this new install procedure can be found on the News page.

25th January 2002

*** Do not use the intimateboot package from the familiar 0.5 feed (intimateboot_2.2). It does not work with the 2.4.16 series bootloaders. Instead, you should use http://intimate.handhelds.org/installer/intimateboot_0.5-1_arm.ipk which will work correctly.

4th January 2002

This install procedure will fetch and install the latest version of intimate from the intimate servers and place it onto your microdrive/CF card or a preconfigured NFS mount.

This installation procedure will not turn your iPAQ into a brick. This procedure makes no attempt to write to, or modify the bootldr in any way, and therefore, you can rest assured that if something goes horribly wrong, your iPAQ will be OK.

Pre-Requisites

You _must_ be running the release version (got that.. release version.. not a pre-0.5 or anything like that) of familiar 0.5 on your iPAQ. The installer has not been tested on any other platform, and makes assumptions about what packages will be available for use. Specifically, it assumes that you will be running a 2.4.7-rmk3-np1-hh12 kernel, and fetches and installs matching modules for reiserfs.

When the iPAQ boots up, the bootloader passes it the location of the first file to execute using the init=/linuxrc part of the linuxargs in the bootloader. This linuxrc file normally sets up a ramdisk etc, and then executes /sbin/init from flash. The intimate boot process hijacks the /linuxrc before we execute init from flash and probes around for CF cards or NFS mounts to boot from. If it finds an alternative root filesystem, it will pivot_root to there, and execute /sbin/init from the new root filesystem.

Due to the convenience of journalling filesystems, and it's inclusion within the kernel, reiserfs is the default throughtout the installation procedure. (7 mins to fsck a full 1Gb ext2 udrive is just not acceptable)

Install procedure

1. Boot up as normal with familiar 0.5, log in and do whatever you normally do to establish an IP connection to the Internet. (USB, PPP, IRDA.. We just don't care). This part is very important. There isn't some convenient .tgz that you can download at the moment. Your iPAQ will need to be able to talk to intimate.handhelds.org and debian.org during the install procedure. (If you're behind a firewall, then you need to open up ports TCP80(http) and TCP873(rsync) in order for the installer to work properly. When the project is out of beta stage, then there'll be a .tgz available for download.

2. Plug in the microdrive. Do not mount it.

3. Paste the following line....

mkdir -p /tmp/intimate && cd /tmp/intimate && wget http://intimate.handhelds.org/installer/installer && sh installer

This will fetch the latest version of the installer script to /tmp, and execute it. The first thing that this command does is to delete everything in /tmp. Until I get around to making this a little cleaner, you'll just have to make sure that you don't have anything you want in /tmp

The script will start up and check it's MD5sum with the server to ensure that the installer script has transferred correctly, and then fetch some required binaries. Once it's got itself started up, we're on to the install procedure propper.

4. The installer will ask you about the following things... It's all fairly obvious what's going on, but here's a description of each...

4a.) Would you like music? [Y/n] -- A selection of old C64 classics to sooth you while your iPAQ downloads and installs megabytes of files. These tunes are very very small (about 1KB per minute of music) It's worthwhile even if you're downloading on a modem... just to ease the boredom.

4b.) Would you like to run fdisk? [y/N] -- If you need to partition your drive.. Intimate expects /=/dev/hda1 swap=/dev/hda2. If that's not what you've got, then you'll need to repartition.. sorry :(. Having done lots of experiments with swap sizes and stability, it appears that having slightly less than 32MB of swap space is optimal.. Too much swap and the iPAQ locks up for some reason.

4c.) Would you like to run mkreiserfs /dev/hda1 [y/N]? -- Format the newly created partition or blank off an existing one (The music will skip during a mkreiserfs.. not enough CPU power to go around... Don't worry.. That's normal)

4d.) Would you like to run mkswap /dev/hda2 [y/N]? -- Does just what it says on the box....

4e.) Would you like to install reiserfs-module? [y/N]? -- If you don't already have it, then you'll need the reiserfs module to be able to mount the drive. This script just fetches the module, and then runs 'ipkg install ./reiserfs-module.x.x.x'. If it's the first time you've used reiserfs on your iPAQ, then you'll need to say 'y' here. If you have already installed this package in the past, then you don't need to do it again.

4f.) Would you like to mount the drive? [y/N] -- The drive needs to be mounted before we can rsync with the server. This will mount the drive on /mnt/hda1 which is the default mount point used by intimate.

4g.) Would you like to sync with the server? -- rsync /dev/hda1 with the current release version from the intimate servers. This will copy the latest base image onto the microdrive from the intimate.handhelds.org rsync server. It appears from early experience that rsync is almost totally bulletproof at getting files onto the iPAQ. It doesn't seem to mind loosing internet connections for 5 mins at a time.. it just kicks back in when the net's back up. It's progressive, so if you do abort at some stage, it'll just carry on where it left off, and it uses timestamps to make sure you always have the latest. This stage should be smooth... even if you have an ISP who drops the line every 20 mins etc...

4h.) Would you like to install .debs [y/N]? -- You need to do this step if you want the base to boot. This installs libmodules, X server, Dev environemnt and basically, all the stuff that you need to make something worthwhile on top of a Debian base.

There's several parts to this qustion, but you can generally just keep on hitting return for each part.. Here's what happens in order.

tzconfig is run from the newly installed intimate base image to configure the timezone for the base

Network config snarfing --- Due to the marvels of grep and awk, the intimate installer will autodetect your current net settings and let you autoconfigure the intiamte base image to bring up the interfaces on boot.

apt-get update --- Fetch the latest lists of available packages from the intimate and debian servers.

apt-get dist-upgrade --- Bring the debian base image bang up to date with debian unstable, and install the kernel modules

apt-get install menu--- Install the debian menu package <kludge.. this'll go when things get turned into task-xxx packages>

apt-get install <gcc + loads of stuff> --- Install the development tools onto the base image *** IMPORTANT *** if you are running the install script inside an ssh session then you must answer 'n' to the upgrade to ssh2 question or you will loose your session ***

apt-get install <xserver + loads of stuff> --- Install the Xserver, window manager and other assorted base X packages

apt-get install <wmsmixer + more X apps> --- Install some pointless X apps so that there's something to play with.

4i.) Would you like to install the intimateboot package [y/N] ? -- The intimate boot package contains a modified linuxrc script which probes for alternative root filesystems and preferrentially boots them before booting from flash. It also contains a utility which can set your linuxargs in the bootloader params block if required.

5.) That's it.. Install completed.. just type reboot end enjoy.

What next?

Well... you could try...

'apt-get install lxdoom-x11 lxdoom-sndserv doom-wad' and play doom for a while

'apt-get wmcube wmfishtime wmmatrix' and play with some silly wm toys

'apt-get install icewm' if blackbox doesn't suit you.

'apt-get install task-kde' if you've got the space(~200MB)

'apt-get install xrixk snex9x' for some more games

'apt-get install emacs' if you hate vi

Play.. compile.. make sutff... make packages.. send them to us.... enjoy! :)