Installing Syllable

1. About the Install

To install the current version you must download and write the "syllable-#.#.#.boot.##" and "syllable-#.#.#.data.##" floppy images on a set of floppies and boot Syllable from there. After booting from the floppies you will have a shell (BASH) in a terminal emulator. From the shell you can mount existing FAT and AFS partitions, create AFS filesystems, and unpack the install archive with the "tar" and "gzip" tools included on the floppies. Here is a step-by-step description on how to make the partition and install the OS.

2. Preperation

First you have to write the (currently 3) floppy images to a set of floppy disks. From Linux, Unix, BeOS, Syllable, and most other OS's you can do this with "dd" command from a shell. On Windows you will need a special program that can write a raw disk image to a floppy. There is a free utility named "rawrite" that can be used to create the bootable format floppies under Windows. On OS/2 you can also use rawrite.
For Unix/Linux it would be something like this (however, slightly different syntax bettween different Unix OSes might needed - consult your 'man dd'):
dd if=syllable-#.#.#.boot.## of=/dev/fd0 bs=1024 skip=20
For BeOS it would be something like this:
dd if=syllable-#.#.#.boot.## of=/dev/disk/floppy/raw bs=1024 skip=20

Do the same for the three floppies required, changing each time the # symbols with the appropriate numbers.
After creating the boot-floppies you should be able to boot Syllable from them and continue with the installation.

3. Partitioning

If you don't already have a partition ready for the AFS filesystem you must first create one with the "DiskManager" tool that is included on the boot floppies. Just run "DiskManager &" from the shell. The partition editor has a fairly self-explanatory GUI where you first select the disk to edit and then edit the partitions either graphically by dragging the partition indicators or by explicitly typing start and end positions for each partition.

Then you must get access to the archive containing the installation. There are several ways to do this. If possible, the best way to achieve this is to put the base-syllable-#.#.#.tgz file on a FAT partition before booting Syllable and then mount that partition under Syllable. If you don't have a FAT partition and are not able to create one you must resort to (many) floppy disks. You must then split the archive into files that can fit on a floppy. The simplest way to do this is probably to write the segments to raw floppies, but you can also make a FAT filesystem on the floppy and put each segment as a normal file inside that FS (it will be annoying to mount/copy/unmount all the floppies under Syllable though).

To mount a FAT partition you must first make a mount-point and then mount the right partition. A mount-point is simply a directory and can be made with "mkdir". To mount the partition you must first figure out what the path is for that partition inside the /dev/ directory hierarchy and then mount it with the "mount" command.

The /dev/ directory in Syllable is not flat like for example under Linux but hierarchical, and the disk block-devices are located under /dev/disk/.

Currently the only driver available is the BIOS disk-device so all disks are located under /dev/disk/bios/ and are named hda, hdb, hdc, etc etc. These disk-names are themselves directories that contain the actual device nodes. Under each drive you will find at least one node named "raw" that represent the whole disk and if the disk has a valid partition table you will find one node for each partition named "0", "1", etc etc. So to get the second partition on the third drive you will have to write /dev/disk/bios/hdc/1 (partition numbers start at 0). The disks are listed in the order they were reported by the BIOS so drive 0x80 is hda, 0x81 is hdb and so on.

In the following example we will assume that the base archive is located at /download/syllable-base-0.3.0.tgz on a FAT partition on the first partition (0) on the first drive (hda) and that we want to install the OS on the second partition (1) on the first drive (which is still part of 'hda').

4. Installing the OS Files

First we make a mount-point for the FAT partition and mount it:

bash-2.03$ mkdir dos
bash-2.03$ mount /dev/disk/bios/hda/0 dos

Then we must create and mount the native FS, be 100% sure you select the right partition before formatting it (see the fsprobe and devstat notes below):

bash-2.03$ format /dev/disk/bios/hda/1 afs MySyllablePartition
bash-2.03$ mkdir afs
bash-2.03$ mount /dev/disk/bios/hda/1 afs

Now we are ready to unpack the base archive to install the FS:

bash-2.03$ cd /afs
bash-2.03$ tar -xvpzf /dos/download/syllable-base-0.3.0.tgz

This should create an "syllable" directory containing well... Syllable and a "boot" directory containing the GRUB bootloader inside the /afs/ mount-point.

5. Configuring the GRUB Bootloader

Next step is to configure and install the bootloader.

First you must tell GRUB where to find the kernel and the required disk/FS drivers to load before booting Syllable. This information is found in "/afs/boot/grub/menu.lst" (this is an L in the '.lst' as in "list"). If you have other OS's installed on the machine you must either configure GRUB as a boot-manager or install another boot-manager that can "chainload" GRUB from the AFS partition.

The menu.lst file should look something like this to boot Syllable from the installation described above:

title Syllable
root (hd0,1)
kernel /atheos/sys/kernel.so root=/dev/disk/bios/hda/1
module /atheos/sys/drivers/fs/afs
module /atheos/sys/drivers/dev/disk/bios

This will tell GRUB to boot partition number 2 on the first drive through the "root (hd0,1)" command and where to find the kernel, the boot block-device driver and the boot-FS driver on that partition. The "root=/dev/disk/bios/hda/1" string after the kernel-path is a parameter that is passed to the kernel and tells what partition to mount as /boot/ before continue to boot. The kernel can also take a number of other parameters (listed below) that are given in the same manner after the "root" param.

If you install Syllable on the second partition on the first drive the default config-file is ok. otherwise you must edit the "root (disk,partition) line to fit your setup. If you want to boot other OS's with GRUB you must add them to the config file as well. For example to boot BeOS, or Windows, or most other OS's that have a bootblock you can use the "chainloader" command like this:

title BeOS
chainloader (hd0,3)+1

This will add a menu entry titled BeOS that will boot the OS found on the fourth partition on the first disk.

You can also set a timeout for when to boot the first OS in the list (or the default as set by the "default" command) with the "timeout" command:

timeout 5

6. Installing the GRUB Bootloader

When done editing the config file you must reboot the computer by pressing <CTRL>, <ALT>, and <DEL> simultanously.
Warning: Do not hit the RESET or Power button. This will cause cashed data that has not yet been written to the disk to be lost and the installation will be corrupted.

Boot from the floppy disk again to install the bootloader.

This time you should abort GRUB before it boot Syllable by hitting <ESC> and then hit "C" to enter the GRUB shell from which you can finish the install. Now you must decide whether you want to install GRUB in the MBR (Master Boot Record) of the first drive and use it as a boot-manager (or if Syllable is the only OS on the machine) or if you want to install it on the AFS partition only and use another bootmanager select what OS to boot.

In either case you must tell GRUB where to find the config file and the second-stage loader by setting a "root" partition:

root (hd0,1)

If you did not install Syllable on the second partition on the first disk you must change the parameters accordingly.

Then you must install the boot-loader with the "setup" command.

To install on a MBR of the first drive run:

setup (hd0)

To install it on the AFS partition only run:

setup (hd0,1) (again change the parameters according to your setup)

Now it should be possible to boot Syllable off the native partition.
Note: GRUB 'understands' the AFS filesystem and can boot any kernel located on an AFS partition by changing the "kernel" line in the config file or by manually loading the kernel and required modules from the GRUB shell. There is no need to run any tools to update block-lists or anything like that after installing new kernels. Read the GRUB documentation and use the "help" command in the GRUB shell for more information on the bootloader.

To edit the config file you can use "jed" from the terminal, which is a easy-to-use text editor included on the boot-floppies.

Important: There are a couple of tools on the floppy that can help you find the right partition. To find an existing filesystem you can use "fsprobe". "fsprobe" takes a block-device path as it's only parameter and will ask each filesystem driver if they recognize the partition and, if one of them do, it will print the FS-type, the volume label and some size/usage stats. The other tool is "devstat" that also takes a block-device path and prints the size and geometry of the disk/partition. This can be useful to verify that the partition you are about to format is really the one you intend to nuke.

7. How to Log In and how to add new Users

Syllable is a multiuser OS. Before you are able to do anything you will have to log in using a user-name and a password. The base-installation comes with two predefined users. "root" with the password "root" is the super-user and has unrestricted access to the system. The other user is "guest" with the password "guest". This is a normal user.

To add a or modify a user, you should use the "user" application, which is included with Syllable

8. Installing Optional Software Packages

When you get the thing to boot, you can start installing the different optional packages. To install a package you simply start a shell, become root (su -l) and go into the /usr/ directory and unpack the tarball with a command like this:

tar -xvpzf /atheos/packages/emacs-19.34.bin.tgz

Then you must run "pkgmanager -a /usr/packagedir" to register the package with the system. To register emacs run the following:

pkgmanager -a /usr/emacs

This will make a bunch of symlinks in various subdirectories of /syllable/autolnk/ to make it possible for the system to find executables and other files belonging to the package.

Voila you should now have the new package installed.

If you want to uninstall the package again you should clean out the symbolic links from /atheos/autolnk/ by running:

pkgmanager -r /usr/emacs

before deleting the actual package directory itself:

rm -R /usr/emacs

Warning:Please note that this way of installing software should ONLY BE USED FOR COMMAND LINE APPLICATIONS AND APPLICATIONs PORTED TO SYLLABLE FROM UNIX AND OTHER OS's USING A UNIX LIKE FILESYSTEM. Native applications should use the various mechanism available in Syllable for making the application "position independent" so it can be installed anywhere on the HD. This mechanism include the option of opening files using paths relative to the location of the executable file (and to obtain the path to the directory where the binary lives) and the ability to embed resources within the executable image itself.

Remember that Syllable is a multiuser OS and that you often must be "root" in order to install new software packages. You become root by typing "su -l" in a shell and then type the "root" password (Default password is "root").

If you want a backdrop image on your desktops you can put a jpeg image at: /system/backdrop.jpg (This will soon be configurable) and restart the desktop manager (kill_all -TERM desktop; desktop &). The image will be tiled if it is smaller than the desktop, and clipped if it is larger.

If you have problems with the installation you might want to take a look at the FAQ or subscribe to the mailing-list and/or read the list-archive. Both an FAQ and a mailing-list are available.

Good luck with the installation.