BRLTTY: The Build Procedure

Next Previous Contents

## 2. The Build Procedure

Here's what to do if you trust that all of our defaults are correct, and just want to install BRLTTY as quickly as possible.

1. Download the source from BRLTTY's web site (see Contact Information for its location). You should end up with a file named `brltty-release.tar.gz`, e.g. `brltty-3.0.tar.gz`.
2. Unpack the source into its native hierarchical structure.

   > `tar xzf brltty-release.tar.gz`

   This should create the directory `brltty-`release.
3. Change to the source directory, and compile and install BRLTTY.

   > `cd brltty-release
   > make install`

   This should be done as rot.
4. Start BRLTTY.

   > `brltty -bdriver -ddevice`

   For driver, specify the two-letter driver identification code corresponding to your braille display. For device, specify the full path for the device to which your braille display is connected.

If you don't want to explicitly identify the driver and device each time you start BRLTTY, then you can take two approaches. You can establish system defaults via the braille-driver and the braille-device configuration file directives, and/or compile your needs right into BRLTTY via the BRL_TARGET and the BRLDEV make file variables.

That's all there's to it. If you'd like to uninstall BRLTTY, then just do:

> `cd brltty-release
> make uninstall`

Now, for those who really want to know what's going on, here are the details.

## 2.1 Installed File Hierarchy

It's probably helpful to start with a brief overview of what the result of the build procedure should be. It should install the following files:

/sbin/

  brltty

    The BRLTTY program.

  install-brltty

    A utility for copying BRLTTY's installed file hierarchy from one location to another.

/etc/brltty/

  Your installation of BRLTTY may not have all of the following types of files. They're only created as needed based on your customization of the make file (see Make File Customization).

  *.conf

    Driver-specific configuration data. Their names look more or less like `brltty-`driver`.conf`, where driver is the two-letter driver identification code.

  *.hlp

    Driver-specific help pages. Their names look more or less like `brltty-`driver`.hlp`, where driver is the two-letter driver identification code.

  *.tbl

    Dot translation tables. Their names look like `text.`language`.tbl`. Tables designed for use with character sets other than `iso-8859-1` have names which indicate this fact. There are also a couple of special tables which map character highlighting attributes to braille dots: `attrib.tbl` does it the original way, and `attributes.tbl` does it the current way.

/lib/brltty/

  Your installation of BRLTTY may not have all of the following types of files. They're only created as needed based on your customization of the make file (see Make File Customization).

  brltty-brl.lst

    A list of the braille display drivers which have been built as dynamically loadable shared objects, and, therefore, which can be selected at run time. Each line consists of the two-letter identification code for a driver, a tab character, and a description of the braille display which that driver is for.

  libbrlttybdriver.so.1

    The dynamically loadable driver for a braille display, where driver is the two-letter driver identification code.

  brltty-spk.lst

    A list of the speech synthesizer drivers which have been built as dynamically loadable shared objects, and, therefore, which can be selected at run time. Each line consists of the two-letter identification code for a driver, a tab character, and a description of the speech synthesizer which that driver is for.

  libbrlttysdriver.so.1

    The dynamically loadable driver for a speech synthesizer, where driver is the two-letter driver identification code.

Some optional files which you should be aware of, although they aren't part of the installed file hierarchy, are:

/etc/brltty.conf

  The system defaults configuration file. See The Configuration File for details.

/etc/brltty-driver.prefs

  The saved preferences settings file (driver is a two-letter driver identification code). See Preferences Settings for details.

## 2.2 Make File Customization

Before compiling BRLTTY, you should check to see if it requires any special configuration for your system and/or your needs. To do this, read the comments at the top of the file `Makefile` in the top-level directory, and, following the instructions contained therein, make any needed changes. Then read the `README` file in the subdirectory containing the driver for your braille display to check for any additional display-specific instructions. We've tried to make the defaults fit the most common case, so, assuming that you're not attempting to do anything out of the ordinary, you may not need to make any changes at all.

The variables within the make file which you may wish to set and/or alter include:

BRL_TARGET

  There's one commented out assignment to this variable for each supported braille display. If you don't uncomment any of them, then all of the braille display drivers are built as dynamically loadable shared objects, and the needed one can be selected at run time. If you do uncomment one of them, then ohly that driver is compiled, and statically linked into the BRLTTY binary. Don't uncomment more than one of them.

BRLDEV

  This variable specifies the path to the special file for the device to which the braille display is connected. It's initially set to `/dev/ttyS0` (the primary serial port).

SPK_TARGET

  There's one commented out assignment to this variable for each supported speech synthesizer. If you don't uncomment any of them, then all of the speech synthesizer drivers are built as dynamically loadable shared objects, and the needed one can be selected at run time. If you do uncomment one of them, then ohly that driver is compiled, and statically linked into the BRLTTY binary. Don't uncomment more than one of them.

TEXTTRANS

  There's one commented out assignment to this variable for each provided text translation table. If you don't uncomment any of them, then a commonly (in North America) used 8-dot variant of the North American Braille Computer Code is assumed. Don't uncomment more than one of them. This specification only establishes a default text translation table; the needed one can always be selected at run time.

ATTRTRANS

  This variable specifies the attributes translation table which is to be used. It's initially set to `attributes.tbl`. Change it to `attrib.tbl` if you'd like it done the old way. This specification only establishes a default attributes translation table; the needed one can always be selected at run time.

INSTALL_ROOT

  Set this variable if you need to install BRLTTY in a different location than the one from which it'll ultimately be used. You need to use this feature, for example, if you're building BRLTTY on one system for use on another. If this variable is set, then the installed file hierarchy is anchored at the directory which it specifies. If it isn't set, then the installed file hierarchy is anchored at the system's root directory. It only applies to `make install` and `make uninstall`.

PREFIX

  Set this variable if you need to install BRLTTY's run-time files in a non-standard location. You need to use this feature, for example, if you'd like to have more than one release of BRLTTY installed at the same time. If this variable is set, then the installed file hierarchy is anchored at the directory which it specifies. If it isn't set, then the installed file hierarchy is anchored at the system's root directory. Even though its sole purpose is to determine where the run-time files are to be installed, it must be set (or not set) throughout the whole build process since certain components of BRLTTY need to know exactly where to find others.

PROG_DIR

  This variable specifies the directory into which the binaries are installed. It's initially set to `/sbin`.

DATA_DIR

  This variable specifies the directory into which the tables, help pages, and other data files are installed. It's initially set to `/etc/brltty`.

LIB_DIR

  This variable specifies the directory into which the drivers and other architecture-dependent files are installed. It's initially set to `/lib/brltty`.

INSTALL_USER

  This variable specifies the user which is to own the binaries and the drivers. It's initially set to `root`.

INSTALL_GRUOP

  This variable specifies the group which is to own the binaries and the drivers. It's initially set to `root`.

INSTALL_MODE

  This variable specifies the file permissions for the binaries and the drivers. It's initially set to `744` (see the man page for `chmod(1)`).

SCR_O

  This variable specifies which screen driver is to be used. It's initially set to `scr_linux.o`. Another screen driver, `scr_shm.o`, may also be used in conjunction with the patch we provide for the `screen` program (see the `Patches` subdirectory).

VCSADEV

  This variable tells the Linux screen driver what all the possible paths to the screen content inspection device are. It's initially set to `/dev/vcsa /dev/vcsa0 /dev/vcc/a`.

CROSSCOMP

  Set this variable if you're cross-compiling for a different architecture. This feature assumes that all of the commands within the cross-compile suite for that architecrue have the same prefix, and this variable should be set to that common prefix.

## 2.3 Make File Targets

BRLTTY's make file supports most of the common application maintenance targets. They include:

make

  A shortcut for `make all`.

make all

  Compile and link the BRLTTY executable, its drivers and their help pages, its test programs, and a few other small utilities.

make install

  Complete the compile and link phase (see `make all`), and then install the BRLTTY executable, its data files, drivers, and help pages, in the correct places and with the correct permissions. The screen content inspection device (`/dev/vcsa` or equivalent) is created if it doesn't already exist.

make uninstall

  Remove the BRLTTY executable, its data files, drivers, and help pages, from the system.

make clean

  Ensure that the next compile and link (see `make all`) will be done from scratch by removing the results of compiling, linking, and testing from the source directory structure. This includes the removal of object files, executables, dynamically loadable shared objects, driver lists, help pages, temporary header files, and core files.

make distclean

  In addition to removing the results of a build (see `make clean`), also remove other files from the source directory structure which tend to accumulate over time but which don't belong there. This includes the removal of editor backup files, test case results, rejected patch hunks, and copies of original source files.

## 2.4 Testing the Build

After compiling, linking, and installing BRLTTY, it's a good idea to give it a quick test before activating it permanently. To do so, invoke it with the command:

> `brltty -bdriver -ddevice`

For driver, specify the two-letter driver identification code corresponding to your braille display. For device, specify the full path for the device to which your braille display is connected.

If all is well, BRLTTY's version identification message should appear on the braille display for a few seconds. After it goes away (which you can hasten by pressing any key on the display), the area of the screen where the cursor is should appear. This means that you should expect to see your shell's command prompt. Then, as you enter your next command, each character should appear on the display as it's typed on the keyboard.

If this is your experience, then leave BRLTTY running, and enjoy it. If this isn't your experience, then it may be necessary to test each driver separately in order to isolate the source of the probledm. The screen driver can be tested with scrtest, and the braille display driver can be tested with brltest.

If you experience a problem which requires a lot of digging, then you may wish to use the following `brltty` command line options:

- -ldebug to log lots of diagnostic messages.
- -n to keep BRLTTY in the foreground.
- -e to direct diagnostic messages to standard error rather than to the system log.

## 2.5 Starting BRLTTY

BRLTTY, when properly installed, is invoked with the single command `brltty`. A configuration file (see section The Configuration File for details) can be created in order to establish system defaults for such things as the location of the preferences file, the braille display driver to be used, the device to which the braille display is connected, and the text translation table to be used. Many options (see section Command Line Options for details) allow explicit run-time specification of such things as the location of the configuration file, any defaults established within the configuration file, and some characteristics which have reasonable defaults but which those who think they know what they're doing may wish to play with. The -h option displays a summary of all the options. The -v option displays the current version of the program and the selected drivers.

It's probably best to have the system automatically start BRLTTY as part of the boot sequence so that the braille display is already up and running when the login prompt appears. Most (probably all) distributions provide a script wherein user-supplied applications can be safely started near the end of the boot sequence. The name of this script is distribution-dependent. Here are the ones we know about so far:

Red Hat

  `/etc/rc.d/rc.local`

Starting BRLTTY from this script is a good approach (especially for new users). Just add a set of lines like these:

> `

>     if [ -x /sbin/brltty ]
>     then
>        /sbin/brltty
>     fi

> `

This can usually be abbreviated to the somewhat less readable form:

> `

>     [ -x /sbin/brltty ] && /sbin/brltty

> `

Don't add these lines before the first line (which usually looks like `#!/bin/sh`).

If the braille display is to be used by a system administrator, then it should probably be started as early as possible during the boot sequence (like before the file systems are checked) so that the display is usable in the event that something goes wrong during these checks and the system drops into single user mode. Again, exactly where it's best to do this is distribution-dependent. Here are the places we know about so far:

Debian

  `/etc/init.d/boot` for older releases, and `/etc/init.d/rcS` for newer releases.

RedHat

  `/etc/rc.d/rc.sysinit` Beware that later releases, in order to support a more user-oriented system initialization procedure, have this script reinvoke itself such that it's under the control of `initlog`. Look, probably right up near the top, for a set of lines like these:

  > `

  >         # Rerun ourselves through initlog
  >         if [ -z "$IN_INITLOG" ]; then
  >          [ -f /sbin/initlog ] && exec /sbin/initlog $INITLOG_ARGS -r /etc/rc.sysinit
  >         fi

  > `

  Starting BRLTTY before this reinvocation results in two BRLTTY processes running at the same time, and that'll give you no end of problems. If your version of this script has this feature, then make sure you start BRLTTY after the lines which implement it.
Slackware

  `/etc/rc.d/rc.S`

SuSE

  `/sbin/init.d/boot`

An alternative is to start BRLTTY from `/etc/inittab`. You have two choices if you choose this route.

- If you want it to be started really early but don't need it to be automatially restarted if it dies, then add a line like this before the first `:sysinit:` line which is already in there.

  > `bt::sysinit:/sbin/brltty`

- If you don't mind it being started later but do want it to be automatially restarted if it dies, then add a line like this anywhere within the file.

  > `bt:12345:respawn:/sbin/brltty -n`

  The -n (`--nodaemon`) option is very important when running BRLTTY with init's `respawn` facility. You'll end up with hundreds of BRLTTY processes all running at the same time if you forget to specify it.

Check that the identifier (`bt` in these examples) isn't already being used by another entry, and, if it is, choose a different one which isn't.

Note that a command like `kill -TERM` is sufficient to stop BRLTTY in its tracks. If it dies during entry into single user mode, for example, it may well be due to a problem of this nature.

Some systems experience problems if an application tries to use the kernel's sound subsystem before it has been initialized. If your system is one of them, then you may need to disable the automatic starting of the speech synthesizer driver with the -N option.

Some systems, as part of the boot sequence, probe the serial ports (usually in order to automatically find the mouse and deduce its type). If your braille display is using a serial port, this kind of probing may be enough to get it confused. If this happens to you, then try restarting the braille driver (see the RESTARTBRL command). Better yet, turn off the serial port probing. Here's what we know so far about how to do this:

Red Hat

  The probing is done by a service named `kudzu`. Use the command

  > `chkconfig --list kudzu`

  to see if it's been enabled. Use the command

  > `chkconfig kudzu off`

  to disable it. Later releases allow you to let `kudzu` run without probing the serial ports. To do this, edit the file `/etc/sysconfig/kudzu`, and set `SAFE` to `yes`.

If you want to start BRLTTY before any file systems are mounted, then ensure that all of its components are installed within the root file system. See the PREFIX, PROG_DIR, DATA_DIR, LIB_DIR, and VCSADEV make file variables.

## 2.6 Security Considerations

BRLTTY needs to run with root privileges because it needs read and write access for the port to which the braille display is connected, read access to `/dev/vcsa` or equivalent (to query the screen dimensions and the cursor position, and to review the current screen content and highlighting), and read and write accesws to the system console (for arrow key entry during cursor routing, for input character insertion during paste, for special key simulation using keys on the braille display, for retrieving output character translation and screen font mapping tables, and for making the computer's speaker beep). Access to the needed devices can, of course, be granted to a non-root user by changing the file permissions associated with the devices. Merely having access to the console, however, isn't enough because making the speaker beep and simulating key strokes still require root privilege. So, if you're willing to give up cursor routing, cut&paste, beeps, and all that, you can run BRLTTY without root priviledge.

## 2.7 Other Utilities

Building BRLTTY also results in the building of a few small helper and diagnostic utilities.

### install-brltty

This utility copies BRLTTY's installed file hierarchy from one location to another.

> `install-brltty to [from]`

to

  The location to which the installed file hierarchy is to be copied. It must be an existing directory.

from

  The location from which the installed file hierarchy is to be taken. If it's specified, then it must be an existing directory. If it's not specified, then the location used for the build is assumed.

The screen content inspection device is also created (if it doesn't already exist) within the to hierarchy.

This utility can be used, for example, to copy BRLTTY to a root disk. If a root floppy is mounted as `/mnt`, and BRLTTY is installed on the main system, then typing

> `install-brltty /mnt`

copies BRLTTY, along with all of its data and library files, to the root floppy.

Some problems have been experienced when copying BRLTTY between systems with different versions of the shared C library. This is worth investigating if you have difficulties.

### txt2hlp

This is a helper utility which is used during the build procedure to prepare the help pages for the drivers.

> `txt2hlp output-file input-file ...`

output-file

  The file which is to contain all of the compiled help pages. The pages are numbered, starting from zero, in the same order as the input files are specified.

input-file

  At least one input file must be specified. Each is the source for a single help page, and should contain plain text.

### tbl2hex

This is a helper utility which is used during the build procedure to prepare the default text and attributes translation tables.

> `tbl2hex`

The translation table is read from standard input, and a set of hexadecimal constants suitable for inclusion within a C array initializer is written to standard output.

### brltest

This utility tests the braille display driver, and also provides an interactive way to learn what the keys on the braille display do. It must be run as root.

> `brltest -option ... [driver [name=value] ...]`

driver

  The driver for the braille display. It may be either a two-letter driver identification code or the absolute path to a dynamically loadable shared object. If it's not specified, then the driver configured within the make file is assumed.

name`=`value

  Set a braille display driver parameter. For a description of the parameters accepted by a specific driver, please see the documentation for that driver.

`-d`device `--device=`device

  The absolute path for the device to which the braille display is connected. If it's not specified, then the device configured within the make file is assumed.

This utility uses BRLTTY's Command Learn Mode. The key press timeout (after which this utility exits) is `10` seconds. The message hold time (used for non-final segments of long messages) is `4` seconds.

### scrtest

This utility tests the screen driver. It must be run as root.

> `scrtest -option ...`

`-c`column `--column=`column

  Specify the starting (left) column (zero-origin) of the region. If this value isn't supplied, then a default value, based on the specified width, is selected such that the region is horizontally centred.

`-h`rows `--height=`rows

  Specify the height of the region (in rows). If this value isn't supplied, then a default value, based on the specified starting row, is selected such that the region is vertically centred.

`-p`name`=`value `--parameter=`name`=`value

  Set a screen driver parameter. For a description of the parameters accepted by a specific driver, please see the documentation for that driver.

`-r`row `--row=`row

  Specify the starting (top) row (zero-origin) of the region. If this value isn't supplied, then a default value, based on the specified height, is selected such that the region is vertically centred.

`-w`columns `--width=`columns

  Specify the width of the region (in columns). If this value isn't supplied, then a default value, based on the specified starting column, is selected such that the region is horizontally centred.

Notes:

- If neither a starting column nor a region width is specified, then the region is horizontally-centred and starts at column 5.
- If neither a starting row nor a region height is specified, then the region is vertically-centred and starts at row 5.

The following is written to standard output:

1. A line detailing the dimensions of the screen.

   > `Screen: widthxheight`

2. A line detailing the position (zero-origin) of the cursor.

   > `Cursor: [column,row]`

3. A line detailing the size of the selected screen region, and the position (zero-origin) of its top-left corner.

   > `Region: widthxheight@[column,row]`

4. The contents of the selected screen region. Unprintable characters are written as blanks.

### tunetest

This utility tests the alert tunes facility, and also provides an easy way to compose new tunes.

> `tunetest -option ... {note duration} ...`

note

  A standard `MIDI` note number. It must be an integer from `1` through `127`, with `60` representing `Middle C`. Each value represents a standard chromatic semi-tone, with the next lower and higher values representing, respectively, the next lower and higher notes. The lowest value (`1`) represents the fifth `C-Sharp` below `Middle C`, and the highest value (`127`) represents the sixth `G` above `Middle C`.

duration

  The duration of the note in milliseconds. It must be an integer from `1` through `255`.

`-d`device `--device=`device

  The device on which to play the tune.

  speaker

    The built-in PC speaker.

  dac

    The Digital to Analog Converter on the sound card.

  midi

    The Musical Instrument Digital Interface on the sound card.

  fm

    The FM synthesizer on an AdLib, OPL3, Sound Blaster, or equivalent sound card.

  The device name may be abbreviated.
`-i`instrument `--instrument=`instrument

  The instrument to use if the selected device is `midi`. For the complete list of instruments, see the MIDI Instrument Table. The default instrument is an `acoustic grand piano`. The words comprising the instrument name must be separated from one another by a single minus sign rather than by spaces, and any of the words may be abbreviated. An `acoustic grand piano`, for example, may be specified as `a-gra-pi`.

Next Previous Contents