README.RedHat.fd

Adding BRLTTY to a Red Hat Linux Install Floppy
===============================================

Written on April 7, 2002

Here is an outline of a procedure for adapting the RedHat (or similar)
installation boot disk so that BRLTTY can be used during the installation
process.

History:
-Initial draft from Stéphane Doyon <s.doyon@videotron.ca>
-Additions from Nicolas Pitre <nico@fluxnic.net>
-April 7, 2002: Mostly rewritten by Stéphane Doyon to take into account
   the INIT_PATH hack
-September 26, 2002: Amended by Dave Mielke <dave@mielke.cc> due to change from
   make file editing to autoconf in 3.1.

TODO:
-Figure out how to use shared libraries from a statically linked
   executable, when the lib references symbols from the main
   program. With that we could do generic bootdisk with dynamic selection
   of braille driver.
-Give working instructions on how to make higher sized floppies for a
   one-floppy solution.

You need an already working Linux station to perform this. A certain
level of Linux/Unix expertise is also required. Please read to the end
before doing anything. You'll probably end up asking for sighted help at
some point (such as to know why it won't boot, or to help install BRLTTY
on the new machine), but if you can get this to work then you'll be free
to spend an hour on your own choosing which packages you want installed.

This was last tried with RedHat 7.2.

First step is compiling BRLTTY. The bootdisk will use one and only one
BRLTTY driver, so you must choose wich. Do:

make distclean
./configure --enable-standalone-programs --with-init-path
            --with-braille-driver=<driver> --with-text-table=<table> 
make
where <driver> is the driver to build into BRLTTY (one of the possible values
listed under --with-braille-driver in the output from ./configure --help) and
<table> is the text translation table to use (such as text.french.tbl,
text.german.tbl, ...) (see the the BrailleTables/ subdirectory).

This will build BRLTTY with the chosen display driver built-in, and will
link the BRLTTY executable statically so that it doesn't depend on any
shared libraries.

If your display is on the second serial port instead of the first,
you will need to add "--with-braille-device=/dev/ttyS1".

You should get an executable called "brltty" (in the "Programs/"  subdirectory)
whose size is around 570K, depending on the driver you chose. If you do:

	file Programs/brltty

it should say, among other things, "statically linked".

The Red Hat installation boot disk is a DOS disk that contains a boot
loader (called syslinux), a kernel (called vmlinuz), and an initial ramdisk
(called initrd.img). This initial ramdisk is the initial root filesystem
containing a bootstrap installation program: /sbin/init. We'll just put
brltty on that ramdisk image and make sure it is started before anything
else. However, because the statically linked brltty executable is so
large, we will have to put the ramdisk image on a second floppy, because
it won't fit on the original single boot floppy (with the kernel).

So now we must hack floppies. Make a temporary work directory. We will
call it ".../work", could be "~/work".

mkdir .../work
mkdir .../work/etcbrltty

Now copy relevant files from your BRLTTY build. Copy the executable, the
translation table, the contraction table (if you want it), and the help file(s)
to your work directory.

cp Programs/brltty .../work
cp BrailleTables/*.tbl .../work/etcbrltty
cp ContractionTables/*.ctb .../work/etcbrltty
cp help/* .../work/etcbrltty

(You can also copy alternative translation tables from BrailleTables/
to .../work/etcbrltty. These CAN be loaded dynamically.)

Now change to the work directory:

cd .../work

The executable is way too large for a boot disk because it contains lots of
unneeded symbol table and debugging information.  Remove this excess data in
order to make the executable as small as possible.

strip brltty

Next step is to select an installation boot floppy image from your
distribution. This could be images/boot.img or images/bootnet.img from an
RH CDROM. Consider checking the updates site for your distribution in
case they have updated installation disk images. If what you have is an
actual floppy, use "dd if=/dev/fd0 of=boot.img bs=512" to make an image
file from it.

Copy the chosen image to your work directory and if necessary rename it
to boot.img.

So now the current directory should contain boot.img, brltty, and
etcbrltty/.

Now run the rhmkbot script (which is located in the same directory as this
README). It will copy boot.img to myboot.img, and it will modify the
syslinux.cfg: it will add a new boot entry called "brltty". That entry will
have options to cause syslinux to load a ramdisk from a second floppy, instead
of using the initrd.img on the first floppy. The brltty entry has the "text"
keyword parameter to trigger the text-mode install. rhmkbot also makes this new
entry the default boot entry.

Now run the rhmkroot script. It will get initrd.img (the initial ramdisk)
from boot.img and call it myroot.img. It will modify that image:
-Rename /sbin/init to /sbin/init_real,
-Copy brltty to /sbin/brltty,
-Link /sbin/init to /sbin/brltty
-Copy files from etcbrltty to /etc/brltty,
-Try to make sure necessary devices such as vcsa, serial ports, and
   console device exist in /dev. (vcsa is usually missing.)

If it turns out that the brltty executable is too large, do "./configure
--help" and check out the various "--disable-..." options. Each removes a
specific feature from BRLTTY, and results in a corresponding decrease in the
size of the executable. Recommended possibilities include:

   --disable-table-selection --disable-learn-mode --disable-contracted-braille
   --disable-pcm-support --disable-midi-support --disable-fm-support
   --disable-api --disable-gpm
   --disable-speech-support --without-x

If building the Papenmeier driver, then also consider:

   --disable-pm-configfile

Remember to do "make distclean" if you need to reconfigure BRLTTY.

Assuming there are no errors, the next step is to actually write the
floppies.

So get two formatted floppies. One will be the boot floppy, the other the
ramdisk floppy. To write the boot floppy do:

dd if=myboot.img of=/dev/fd0 bs=512

To write the ramdisk floppy do:

dd if=myroot.img of=/dev/fd0 bs=512

That's it!

So now boot the boot floppy on the machine you want to install. At the
prompt you can press ENTER to choose the brltty entry. 

If you want to specify boot parameters, remember to use the label
"brltty" instead of "linux".

You can pass options to BRLTTY from the boot prompt by using option names
similar to those in the brltty.conf file: use only uppercase, use underscores
instead of minus signs, and prefix with BRLTTY_. For example:

brltty BRLTTY_BRAILLE_DEVICE=/dev/ttyS1

When you press ENTER, syslinux will load the kernel. When the floppy
stops spinning the kernel will start to run and will prompt you for the
ramdisk floppy. Put the second floppy in and press ENTER. The kernel will
load the ramdisk. When the floppy stops spinning, BRLTTY SHOULD
(hopefullY) come on and the installation program should start.

One of the problems you may have during the installation process is that
some autoconfiguration programs may play around with the serial ports to
try to autodetect hardware, thereby upsetting them and causing BRLTTY to
stop working. This can also occur when the system itself boots. More
recent RedHat versions are less aggressive though. Two tricks if you have
problems:
-If kudzu runs when your system boots and upsets BRLTTY, either disable
that service (using chkconfig or ntsysv) or modify /etc/sysconfig/kudzu
or the script that uses kudzu to make it use the --safe option.
-To get the installation program to leave a serial port alone, you might
try to modify the ramdisk to change /dev/ttyS0 to say /dev/ttySmyown, and
tell BRLTTY to use that as it's serial port. This might have the effect
of hiding the serial port from bad applications.

Note that you must also install BRLTTY on your new machine. When it will boot
Linux after the installation, BRLTTY will not be installed and the machine will
be inaccessible. One way to simplify things is to use the statically linked
brltty you compiled for the installation disk, as it is fairly self-contained.
Once it's running, then you can build yourself a shared version and modify your
boot scripts or inittab to have BRLTTY start automatically. A nice way to get
brltty onto your new machine is this: during the installation process, after
your target partition has been formatted, it is (at least with the current RH
installation program) mounted under /mnt/sysimage. You can temporarily put
aside the installation program and get a shell by going to the second virtual
console (alt-F2). There you can do:

cp /sbin/brltty /mnt/sysimage/bin/

I am not sure if at that point it is possible to edit inittab or startup
scripts. Otherwise on your first boot, you just have to log in as root
(without braille support) and type "/bin/brltty" and if all went well
BRLTTY should come on.

Good luck!