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.
The build procedure should result in the installation of the following files:
The BRLTTY program.
A utility for copying BRLTTY's installed file hierarchy from one location to another.
A utility which sets a number of environment variables to values which reflect the current installation of BRLTTY.
Static archive of the Application Programming Interface.
Dynamically loadable object for the Application Programming Interface.
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).
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.
The dynamically loadable driver for a braille display, where driver is the two-letter driver identification code.
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.
The dynamically loadable driver for a speech synthesizer, where driver is the two-letter driver identification code.
Files created at run-time, e.g. needed but missing system resources.
System defaults for BRLTTY.
The access key for BrlAPI.
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).
Driver-specific configuration data.
Their names look more or less like brltty-driver.conf,
where driver is the two-letter
driver identification code.
Attributes tables
(see section
Attributes Tables for details).
Their names look like name.atb.
Include files for attributes tables.
Contraction tables
(see section
Contraction Tables for details).
Their names look like language-country-level.ctb.
Include files for contraction tables.
Key tables
(see section
Key Tables for details).
Their names look like name.ktb.
Include files for key tables.
Text tables
(see section
Text Tables for details).
Their names look like language.ttb.
Include files for text tables.
Driver-specific help pages.
Their names look more or less like brltty-driver.hlp,
where driver is the two-letter
driver identification code.
Local sockets for connecting to the Application Programming Interface.
C header files for the Application Programming Interface.
Their names look like brlapi-function.h.
The main header is brlapi.h.
C header files for accessing braille hardware.
Their names look like brldefs-driver.h
(where driver is the two-letter
driver identification code).
The headers brldefs.h and api.h are provided
for backward compatibility and shouldn't be used.
Man pages.
Man pages for BRLTTY-related user commands.
Man pages for Application Programming Interface library routines.
Some optional files which you should be aware of, although they aren't part of the installed file hierarchy, are:
The system defaults configuration file. It's created by the system administrator. See The Configuration File for details.
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.
Here's what to do if you just want to install BRLTTY as quickly as possible, trusting that all of our defaults are correct.
brltty-release.tar.gz,
e.g. brltty-3.0.tar.gz.
tar xzf brltty-release.tar.gz
brltty-release.
cd brltty-release
./configure
make install
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.
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
./configure --help
README file in the subdirectory
containing the driver for your braille display
for any additional display-specific instructions.
--with-braille-driver=driver
Specify the braille display drivers
which are to be linked into the BRLTTY binary.
Those drivers which aren't listed via this option
are built as dynamically loadable shared objects
and can still be selected at run-time.
Each driver must be identified
either by its two-letter
driver identification code
or by its proper name (full or abbreviated).
The driver identifiers must be
separated from one another by a single comma.
If a driver identifier is prefixed by a minus sign (-),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
Link all of the drivers into the binary. Don't build any of them as dynamically loadable shared objects. This word may also be specified as the final element of a driver list. This is how to specify the dfault driver when all the drivers are to be linked in.
Only build those drivers which have been explicitly included via this option.
Don't build any drivers at all.
This is equivalent to specifying --without-braille-driver.
Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying --with-braille-driver.
--with-braille-parameters=[driver:]name=value,...
Specify the default parameter settings for the braille display drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Driver Identification Codes) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the braille-parameters configuration file directive and the -B command line option for run-time selection.
--with-braille-device=device,...
Specify the default device to which the braille display is connected
(see section
Braille Device Specification).
If this option isn't specified,
then usb: is assumed if USB support is available,
and an operating system appropriate path
for the primary (first) serial port (device) is assumed if not.
See the
braille-device configuration file directive
and the
-d command line option
for run-time selection.
--with-libbraille=directory
Specify the installed location of the Libbraille package, and build the Libbraille braille display driver (see Build Restrictions). Any of the following words can also be used as the operand of this option:
Don't build the driver.
This is equivalent to specifying --without-libbraille.
Build the driver if the package can be found in
/usr,
/usr/local,
/usr/local/Libbraille,
/usr/local/libbraille,
/opt/Libbraille,
or /opt/libbraille.
This is equivalent to specifying --with-libbraille.
--with-text-table=file
Specify the built-in (fallback) text table
(see section
Text Tables for details).
The specified table is linked into the BRLTTY binary, and is used
either if locale-based autoselection fails
or if the requested table can't be loaded.
The absolute path to a table outside the source tree may be specified.
The .ttb extension is optional.
If this option isn't specified,
then en-nabcc,
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 built-in (fallback) attributes table
(see section
Attributes Translation for details).
The specified table is linked into the BRLTTY binary, and is used
if the requested table can't be loaded.
The absolute path to a table outside the source tree may be specified.
The .atb extension is optional.
If this option isn't specified,
then attributes is assumed.
Change it to attrib 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 drivers
which are to be linked into the BRLTTY binary.
Those drivers which aren't listed via this option
are built as dynamically loadable shared objects
and can still be selected at run-time.
Each driver must be identified
either by its two-letter
driver identification code
or by its proper name (full or abbreviated).
The driver identifiers must be
separated from one another by a single comma.
If a driver identifier is prefixed by a minus sign (-),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
Link all of the drivers into the binary. Don't build any of them as dynamically loadable shared objects. This word may also be specified as the final element of a driver list. This is how to specify the dfault driver when all the drivers are to be linked in.
Only build those drivers which have been explicitly included via this option.
Don't build any drivers at all.
This is equivalent to specifying --without-speech-driver.
Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying --with-speech-driver.
--with-speech-parameters=[driver:]name=value,...
Specify the default parameter settings for the speech synthesizer drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Driver Identification Codes) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the speech-parameters configuration file directive and the -S command line option for run-time selection.
--with-flite=directory
Specify the installed location of the FestivalLite text-to-speech package, and build the FestivalLite speech synthesizer driver (see Build Restrictions). Any of the following words can also be used as the operand of this option:
Don't build the driver.
This is equivalent to specifying --without-flite.
Build the driver if the package can be found in
/usr,
/usr/local,
/usr/local/FestivalLite,
/usr/local/flite,
/opt/FestivalLite,
or /opt/flite.
This is equivalent to specifying --with-flite.
--with-flite-language=language
Specify the language which the FestivalLite text to speech engine is to use.
The default language is usenglish.
--with-flite-lexicon=lexicon
Specify the lexicon which the FestivalLite text to speech engine is to use.
The default lexicon is cmulex.
--with-flite-voice=voice
Specify the voice which the FestivalLite text to speech engine is to use.
The default voice is cmu_us_kal16.
--with-mikropuhe=directory
Specify the installed location of the Mikropuhe text-to-speech package, and build the Mikropuhe speech synthesizer driver (see Build Restrictions). Any of the following words can also be used as the operand of this option:
Don't build the driver.
This is equivalent to specifying --without-mikropuhe.
Build the driver if the package can be found in
/usr,
/usr/local,
/usr/local/Mikropuhe,
/usr/local/mikropuhe,
/opt/Mikropuhe,
or /opt/mikropuhe.
This is equivalent to specifying --with-mikropuhe.
--with-speechd=directory
Specify the installed location of the speech-dispatcher text-to-speech package, and build the speech-dispatcher speech synthesizer driver. Any of the following words can also be used as the operand of this option:
Don't build the driver.
This is equivalent to specifying --without-speechd.
Build the driver if the package can be found in
/usr,
/usr/local,
/usr/local/speech-dispatcher,
/usr/local/speechd,
/opt/speech-dispatcher,
or /opt/speechd.
This is equivalent to specifying --with-speechd.
--with-swift=directory
Specify the installed location of the Swift text-to-speech package, and build the Swift speech synthesizer driver. Any of the following words can also be used as the operand of this option:
Don't build the driver.
This is equivalent to specifying --without-swift.
Build the driver if the package can be found in
/usr,
/usr/local,
/usr/local/Swift,
/usr/local/swift,
/opt/Swift,
or /opt/swift.
This is equivalent to specifying --with-swift.
--with-theta=directory
Specify the installed location of the Theta text-to-speech package, and build the Theta speech synthesizer driver (see Build Restrictions). Any of the following words can also be used as the operand of this option:
Don't build the driver.
This is equivalent to specifying --without-theta.
Build the driver if the package can be found in
/usr,
/usr/local,
/usr/local/Theta,
/usr/local/theta,
/opt/Theta,
or /opt/theta.
This is equivalent to specifying --with-theta.
--with-viavoice=directory
Specify the installed location of the ViaVoice text-to-speech package, and build the ViaVoice speech synthesizer driver (see Build Restrictions). Any of the following words can also be used as the operand of this option:
Don't build the driver.
This is equivalent to specifying --without-viavoice.
Build the driver if the package can be found in
/usr,
/usr/local,
/usr/local/ViaVoice,
/usr/local/viavoice,
/opt/ViaVoice,
or /opt/viavoice.
This is equivalent to specifying --with-viavoice.
--with-screen-driver=driver
Specify the screen drivers
which are to be linked into the BRLTTY binary.
Those drivers which aren't listed via this option
are built as dynamically loadable shared objects
and can still be selected at run-time.
Each driver must be identified
either by its two-letter driver identification code
(see section
Supported Screen Drivers)
or by its proper name (full or abbreviated).
The driver identifiers must be
separated from one another by a single comma.
If a driver identifier is prefixed by a minus sign (-),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
Link all of the drivers into the binary. Don't build any of them as dynamically loadable shared objects. This word may also be specified as the final element of a driver list. This is how to specify the dfault driver when all the drivers are to be linked in.
Only build those drivers which have been explicitly included via this option.
Don't build any drivers at all.
This is equivalent to specifying --without-screen-driver.
Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying --with-screen-driver.
sc is selected.
See the
screen-driver configuration file directive
and the
-x command line option
for run-time selection.
--with-screen-parameters=[driver:]name=value,...
Specify the default parameter settings for the screen drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Supported Screen Drivers) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the screen-parameters configuration file directive and the -X command line option for run-time selection.
--with-usb-package=package,...
Specify the package which is to be used for USB I/O. The package names must be separated from one another by a single comma, and are processed from left to right. The first one which is installed on the system is selected. The following packages are supported:
Don't support USB I/O.
This is equivalent to specifying --without-usb-package.
Use native support for USB I/O.
If native support isn't available for the current platform
then use the first available supported package
(as per the order specified above).
This is equivalent to specifying --with-usb-package.
--with-bluetooth-package=package,...
Specify the package which is to be used for Bluetooth I/O. The package names must be separated from one another by a single comma, and are processed from left to right. The first one which is installed on the system is selected. The following packages are supported:
Don't support Bluetooth I/O.
This is equivalent to specifying --without-bluetooth-package.
Use native support for Bluetooth I/O.
If native support isn't available for the current platform
then use the first available supported package
(as per the order specified above).
This is equivalent to specifying --with-bluetooth-package.
--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:
--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:
--libdir=directory
Specify the directory within the
installed file hierarchy
where the static archive and the dynamically loadable object
for the Application Programming Interface are to be installed.
The absolute path should be supplied.
If this option isn't specified,
then the directory
specified via the standard configure option --libdir
(which defaults to /lib rooted at the directory specified by the
--exec-prefix build option)
is assumed.
The directory is created if it doesn't exist.
--sysconfdir=directory
Specify the directory within the
installed file hierarchy
where the configuration files are to be installed.
The absolute path should be supplied.
If this option isn't specified,
then the directory
specified via the standard configure option --sysconfdir
(which defaults to /etc rooted at the directory specified by the
--prefix build option)
is assumed.
The directory is created if it doesn't exist.
--with-program-directory=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 the directory
specified via the standard configure option --bindir
(which defaults to /bin rooted at the directory specified by the
--exec-prefix build option)
is assumed.
The directory is created if it doesn't exist.
--with-library-directory=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 the brltty subdirectory of the directory
specified via the standard configure option --libdir
(which defaults to /lib rooted at the directory specified by the
--exec-prefix build option)
is assumed.
The directory is created if it doesn't exist.
--with-writable-directory=directory
Specify the directory within the installed file hierarchy which may be written to. The absolute path should be supplied. Any of the following words can also be used as the operand of this option:
Don't define a writable directory.
This is equivalent to specifying --without-writable-directory.
Use the default location.
This is equivalent to specifying --with-writable-directory.
rw subdirectory of the directory specified via the
--with-library-directory build option
is assumed.
The directory is created if it doesn't exist.
--with-data-directory=directory
Specify the directory within the
installed file hierarchy
where the tables, help pages,
and other architecture-independent files are to be installed.
The absolute path should be supplied.
If this option isn't specified,
then the brltty subdirectory of the directory
specified via the standard configure option --sysconfdir
(which defaults to /etc rooted at the directory specified by the
--prefix build option)
is assumed.
The directory is created if it doesn't exist.
--with-manpage-directory=directory
Specify the directory within the
installed file hierarchy
where the man pages are to be installed.
The absolute path should be supplied.
If this option isn't specified,
then the directory
specified via the standard configure option --mandir
(which defaults to /man rooted at the directory specified by the
--prefix build option)
is assumed.
The directory is created if it doesn't exist.
--with-include-directory=directory
Specify the directory within the
installed file hierarchy
where the C header files for the Application Programming Interface
are to be installed.
The absolute path should be supplied.
If this option isn't specified,
then the brltty subdirectory of the directory
specified via the standard configure option --includedir
(which defaults to /include rooted at the directory specified by the
--prefix build option)
is assumed.
The directory is created if it doesn't exist.
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. Only the default drivers (see the --with-braille-driver, --with-speech-driver, and --with-screen-driver build options) are compiled.
--enable-relocatable-install
If this feature is enabled then all internal paths are recalculated to be relative to the program directory. If it's disabled then all internal paths are absolute. This feature allows the entire installed file hierarchy to be copied or moved, in tact, from one place to another, and is primarily intended for use on Windows platforms.
--disable-strippingl
Don't remove the symbol tables from executables and shared objects when installing them.
--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 Contraction Tables).
--disable-speech-support
Reduce program size by excluding support for speech synthesizers.
--disable-iconv
Reduce program size by excluding support for character set conversion.
--disable-icu
Reduce program size by excluding support for Unicode-based internationalization.
--disable-x
Reduce program size by excluding support for X11.
--disable-beeper-support
Reduce program size by excluding support for the console tone generator.
--disable-pcm-support
Reduce program size by excluding support for the digital audio interface on the sound card.
--enable-pcm-support=interfaceIf a platform provides more than one digital audio interface
then the one which is to be used may be specified.
| Platform | Interface | Description |
| Linux | oss | Open Sound System |
| alsa | Advanced Linux Sound Architecture | |
--disable-midi-support
Reduce program size by excluding support for the Musical Instrument Digital Interface of the sound card.
--enable-midi-support=interfaceIf a platform provides more than one Musical Instrument Digital Interface
then the one which is to be used may be specified.
| Platform | Interface | Description |
| Linux | oss | Open Sound System |
| alsa | Advanced Linux Sound Architecture | |
--disable-fm-support
Reduce program size by excluding support for 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.
--disable-gpm
Reduce program size by excluding
the interface to the gpm application
which allows BRLTTY to interact with the pointer (mouse) device
(see section
Pointer (Mouse) Support via GPM).
--disable-api
Reduce program size by excluding the Application Programming Interface.
--with-api-parameters=name=value,...
Specify the default parameter settings for the Application Programming Interface. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by the interface, please see the BrlAPI reference manual. See the api-parameters configuration file directive and the -A command line option for run-time selection.
--disable-caml-bindings
Don't build the Caml bindings for the Application Programming Interface.
--disable-java-bindings
Don't build the Java bindings for the Application Programming Interface.
--disable-lisp-bindings
Don't build the Lisp bindings for the Application Programming Interface.
--disable-python-bindings
Don't build the Python bindings for the Application Programming Interface.
--disable-tcl-bindings
Don't build the Tcl bindings for the Application Programming Interface.
--with-tcl-config=path
Specify the location of the Tcl configuration script (tclConfig.sh).
Either the path to the script itself
or to the directory containing it
may be supplied.
Any of the following words can also be used as the operand of this option:
Use other means to guess if Tcl is available, and, if so, where it has been installed.
This is equivalent to specifying --without-tcl-config.
Search for the script in a few commonly used directories.
This is equivalent to specifying --with-tcl-config.
--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:
init program should be moved to a new location.brltty should be moved to the init program's original location.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.--with-stderr-path=path
Specify the path to the file or device where standard erorr output is to be written. The absolute path should be supplied. If this option isn't specified, then this feature isn't activated. This option is primarily intended for building a braillified installer image.
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:
A shortcut for make all.
Compile and link the BRLTTY executable, its drivers and their help pages, its test programs, and a few other small utilities.
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.
Remove the BRLTTY executable, its data files, drivers, and help pages, from the system.
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.
In addition to removing the results of compiling and linking (see make clean):
config.mk, config.h,
config.cache, config.status, and config.log.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
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, a