Next Previous Contents

2. The Build Procedure

BRLTTY can be downloaded from its web site (see section Contact Information for its location). All releases are provided as compressed tar balls. Newer releases are also provided as RPM (RedHat Package Manager) files.

That tidbit of information has probably peaked your curiosity, and now you just can't wait to get started. It's a good idea, though, to first become familiar with the files which will ultimately be installed.

2.1 Installed File Hierarchy

The build procedure should result in the installation of the following files:

/bin/

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 the build options you select (see Build Options).

*.conf

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

*.ctb

Contraction tables (see section Contracted Braille for details). Their names look like language-country-level.ctb.

*.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

Translation tables (see section Translation Tables for details). 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 the build options you select (see Build Options).

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. It's created by the system administrator. See The Configuration File for details.

/etc/brltty-driver.prefs

The saved preferences settings file (driver is a two-letter driver identification code). It's created by the PREFSAVE command. See Preferences Settings for details.

2.2 Installing from a TAR Ball

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

  1. Download the source. It'll be 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, configure, compile, and install BRLTTY.
    cd brltty-release
    ./configure
    make install
    This should be done as root.

To uninstall BRLTTY, do:

cd brltty-release
make uninstall

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

Build Options

The first step in building BRLTTY is to configure it for your system and/or for your personal needs. This is done by running the configure script in BRLTTY's top-level directory. 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 do anything more complicated than invoke this script without specifying any options at all.

./configure
If, however, you have some special requirements, or even if you're just adventurous, you should find out what your choices are.
./configure --help
You should also check out the README file in the subdirectory containing the driver for your braille display for any additional display-specific instructions.

System Defaults

--with-braille-driver=driver

Specify the braille display driver. Either a two-letter driver identification code or the proper name (full or abbreviated) of the driver may be used. If this option isn't specified, 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 it is specified, then only that driver is compiled, and statically linked into the BRLTTY binary. See the braille-driver configuration file directive and the -b command line option for run-time selection.

--with-braille-device=device

Specify the device to which the braille display is connected. If a relative path is supplied, then it's anchored at /dev. If this option isn't specified, then an operating system appropriate path for the primary serial port is assumed. See the braille-device configuration file directive and the -d command line option for run-time selection.

--with-text-table=file

Specify the text translation table (see section Translation Tables for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). If this option isn't specified, then a commonly (in North America) used 8-dot variant of the North American Braille Computer Code is assumed. See the text-table configuration file directive and the -t command line option for run-time selection. This setting can be changed with the Text Table preference.

--with-attributes-table=file

Specify the attributes translation table (see section Translation Tables for details). If a relative path is supplied, then it's anchored at /etc/brltty (see the --sysconfdir and the --with-execute-root build options for more details). If this option isn't specified, then attributes.tbl is assumed. Change it to attrib.tbl if you'd like it done the old way. See the attributes-table configuration file directive and the -a command line option for run-time selection. This setting can be changed with the Attributes Table preference.

--with-speech-driver=driver

Specify the speech synthesizer driver. Either a two-letter driver identification code or the proper name (full or abbreviated) of the driver may be used. If this option isn't specified, 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 it is specified, then only that driver is compiled, and statically linked into the BRLTTY binary. See the speech-driver configuration file directive and the -s command line option for run-time selection.

--with-screen-driver=driver

Specify the screen driver. It may be one of the following:

linux

This driver provides direct access to the Linux console screen. It's only selectable, and is the default, on Linux systems.

shm

This driver provides access to the screen program. It's selectable on all systems, and is the default on most. The patch for screen which we provide (see the Patches subdirectory) must be applied. Use of this driver, due to the fact that screen must be concurrently running, makes BRLTTY effectively useful only after the user has logged in.

If this option isn't specified, then an operating system appropriate selection is made. If a specific driver for the current operating system is available, then it's used. If not, then shm is used.

Directory Specification

--with-execute-root=directory

Specify the directory at which the installed file hierarchy is to be rooted at run-time. The absolute path should be supplied. If this option isn't specified, then the system's root directory is assumed. Use this option 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 version of BRLTTY installed at the same time (see section Installing Multiple Versions for an example of how to do this).

--with-install-root=directory

Specify the directory beneath which the installed file hierarchy is to be installed. The absolute path should be supplied. If this option isn't specified, then the run-time package root (see the --with-execute-root build option) is assumed. This directory is only used by make install and make uninstall. Use this option if you need to install BRLTTY in a different location than the one from which it'll ultimately be executed. You need to use this feature, for example, if you're building BRLTTY on one system for use on another.

--prefix=directory

Specify the directory within the installed file hierarchy where the default directories for the architecture-independent files are to be rooted. These directories include:

The absolute path should be supplied. If this option isn't specified, then the system's root directory is assumed. This directory is rooted at the directory specified by the --with-execute-root build option.

--exec-prefix=directory

Specify the directory within the installed file hierarchy where the default directories for the architecture-dependent files are to be rooted. These directories include:

The absolute path should be supplied. If this option isn't specified, then the directory specified via the --prefix build option is assumed. This directory is rooted at the directory specified by the --with-execute-root build option.

--bindir=directory

Specify the directory within the installed file hierarchy where the runnable programs (binaries, executables) are to be installed. The absolute path should be supplied. If this option isn't specified, then /bin, rooted at the directory specified by the --exec-prefix build option, is assumed.

--libdir=directory

Specify the directory within the installed file hierarchy where the drivers and other architecture-dependent files are to be installed. The absolute path should be supplied. If this option isn't specified, then /lib, rooted at the directory specified by the --exec-prefix build option, is assumed. The files themselves are installed within this directory's brltty subdirectory (which is created if necessary).

--sysconfdir=directory

Specify the directory within the installed file hierarchy where the configuration files, tables, help pages, and other architecture-dependent files are to be installed. The absolute path should be supplied. If this option isn't specified, then /etc, rooted at the directory specified by the --prefix build option, is assumed. The files themselves are installed within this directory's brltty subdirectory (which is created if necessary).

Build Features

These options are primarily useful when building BRLTTY for use on a boot disk.

--enable-standalone-programs

Create statically linked, rather than dynamically linked, programs. This option removes all dependencies on shared objects at run-time.

--disable-tainted-components

Exclude those components which have a build-time dependency beyond what a standard system is expected to provide. These include:

--disable-preferences-menu

Reduce program size by excluding the preferences menu (see section The Preferences Menu).

--disable-table-selection

Reduce program size by excluding the table selection entries from the preferences menu (see the Text Table, Attributes Table, and Contraction Table preferences).

--disable-learn-mode

Reduce program size by excluding command learn mode (see section Command Learn Mode).

--disable-contracted-braille

Reduce program size by excluding support for contracted braille (see section Contracted Braille).

--disable-speech-support

Reduce program size by excluding support for speech synthesizers.

--disable-beeper-tunes

Reduce program size by excluding support for the playing of alert tunes (see section Alert Tunes) via the internal beeper (console tone generator).

--disable-pcm-tunes

Reduce program size by excluding support for the playing of alert tunes (see section Alert Tunes) via the digital audio interface on the sound card.

--disable-midi-tunes

Reduce program size by excluding support for the playing of alert tunes (see section Alert Tunes) via the Musical Instrument Digital Interface on the sound card.

--disable-fm-tunes

Reduce program size by excluding support for the playing of alert tunes (see section Alert Tunes) via the FM synthesizer on an AdLib, OPL3, Sound Blaster, or equivalent sound card.

--disable-pm-configfile

Reduce program size by excluding support for the Papenmeier driver's configuration file.

--enable-gpm

Include an interface to the gpm application so that, on systems which support it, BRLTTY will interact with the pointer (mouse) device (see section Pointer (Mouse) Support via GPM).

Miscellaneous Options

--with-compiler-prefix=prefix

Specify the prefix (path and beginning of program name) for the suite of compile and link tools which are to be used. You may need to use this option if, for example, you're cross-compiling for a different architecture.

--with-init-path=path

Specify the path to the real init program for the system. The absolute path should be supplied. If this option is specified, then:

  1. The init program should be moved to a new location.
  2. brltty should be moved to the init program's original location.
  3. When the system runs init at startup, brltty is actually run. It puts itself into the background, and runs the real init in the foreground. This is one (somewhat sneaky) way to have braille right at the outset. It's especially useful for some install/rescue disks.
If this option isn't specified, then this feature isn't activated.

Make File Targets

Once BRLTTY has been configured, the next steps are to compile and to install it. These are done by applying the system's make command to BRLTTY's main make file (Makefile in the top-level directory). 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.

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 compiling and linking (see make clean):

2.3 Testing BRLTTY

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 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 --with-braille-driver and the --with-braille-device build options.

If all is well, BRLTTY's version identification message should appear on the braille display for a few seconds (see the -M command line option). 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:

2.4 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 /bin/brltty ]
then
   /bin/brltty
fi
This can usually be abbreviated to the somewhat less readable form:
[ -x /bin/brltty ] && /bin/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.

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 --with-execute-root, --bindir, --sysconfdir, and --libdir build options.

2.5 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 access 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 activation of the internal beeper). 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 activating the internal beeper 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.6 Build and Run-Time Restrictions

Alert Tunes

Some platforms don't support all of the tune devices. See the Tune Device preference for details.

ViaVoice Driver

The driver for the ViaVoice software speech synthesizer is only built if that package has been installed.

VideoBraille Driver

The driver for the VideoBraille braille display is built on all systems, but only works on Linux.

Voyager Driver

The driver for the Voyager braille display is only built on the Linux operating system.

2.7 Installing from an RPM File

To install BRLTTY from an RPM (RedHat Package Manager) file, do the following:

  1. Download the binary package which corresponds to your hardware. It'll be a file named brltty-release-version.architecture.rpm, e.g. brltty-3.0-1.i386.rpm.
  2. Install the package.
    rpm -Uvh brltty-release-version.architecture.rpm
    This should be done as root. Strictly speaking, the -U (update) option is the only one which is necessary. The -v (verbose) option displays the name of the package as it's being installed. The -h (hashes) option displays a progress meter (using hash signs).
For the brave, we also provide the source RPM (.src.rpm) file, but that's beyond the scope of this document.

To uninstall BRLTTY, do:

rpm -e brltty

2.8 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.

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 via the --with-braille-driver build option 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.

-ddevice --device=device

The absolute path for the device to which the braille display is connected. If it's not specified, then the device configured via the --with-braille-device build option is assumed.

-h --help

Display a summary of the command line options, and then exit.

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 ... [name=value ...]
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.

-lcolumn --left=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.

-ccount --columns=count

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.

-trow --top=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.

-rcount --rows=count

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.

-h --help

Display a summary of the command line options, and then exit.

Notes:

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.

-ddevice --device=device

The device on which to play the tune.

beeper

The internal beeper (console tone generator).

pcm

The digital audio interface 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. See the Tune Device preference for details regarding the default device and platform restrictions.

-iinstrument --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.

-h --help

Display a summary of the command line options, and then exit.


Next Previous Contents