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 -Additions from Nicolas Pitre -April 7, 2002: Mostly rewritten by Stéphane Doyon to take into account the INIT_PATH hack -September 26, 2002: Amended by Dave Mielke 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= --with-text-table= make where is the driver to build into BRLTTY (one of the possible values listed under --with-braille-driver in the output from ./configure --help) and
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!