Current File : //usr/share/doc/brltty/English/BRLTTY-3.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>BRLTTY Reference Manual: The Build Procedure</TITLE>
<LINK HREF="BRLTTY-4.html" REL=next>
<LINK HREF="BRLTTY-2.html" REL=previous>
<LINK HREF="BRLTTY.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="BRLTTY-4.html">Next</A>
<A HREF="BRLTTY-2.html">Previous</A>
<A HREF="BRLTTY.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3.</A> <A HREF="BRLTTY.html#toc3">The Build Procedure</A></H2>
<P>BRLTTY can be downloaded from its web site
(see section
<A HREF="BRLTTY-1.html#contact">Contact Information</A> for its location).
All releases are provided as compressed
<A HREF="#tar">tar balls</A>.
Newer releases are also provided as
<A HREF="#rpm">RPM</A> (RedHat Package Manager) files.</P>
<P>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.</P>
<H2><A NAME="hierarchy"></A> <A NAME="ss3.1">3.1</A> <A HREF="BRLTTY.html#toc3.1">Installed File Hierarchy</A>
</H2>
<P>The build procedure should result in the installation of the following files:
<DL>
<DT><B>/bin/</B><DD>
<P>
<DL>
<DT><B>brltty</B><DD>
<P>The BRLTTY program.</P>
<DT><B>
<A HREF="#utility-brltty-install">brltty-install</A></B><DD>
<P>A utility for copying BRLTTY's
<A HREF="#hierarchy">installed file hierarchy</A>
from one location to another.</P>
<DT><B>
<A HREF="#utility-brltty-config">brltty-config</A></B><DD>
<P>A utility which sets a number of environment variables to values
which reflect the current installation of BRLTTY.</P>
</DL>
</P>
<DT><B>/lib/</B><DD>
<P>
<DL>
<DT><B>libbrlapi.a</B><DD>
<P>Static archive of the Application Programming Interface.</P>
<DT><B>libbrlapi.so</B><DD>
<P>Dynamically loadable object for the Application Programming Interface.</P>
</DL>
</P>
<DT><B>/lib/brltty/</B><DD>
<P>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
<A HREF="#build">Build Options</A>).
<DL>
<DT><B>brltty-brl.lst</B><DD>
<P>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.</P>
<DT><B>libbrlttyb<EM>driver</EM>.so.1</B><DD>
<P>The dynamically loadable driver for a braille display,
where <EM>driver</EM> is the two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>.</P>
<DT><B>brltty-spk.lst</B><DD>
<P>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.</P>
<DT><B>libbrlttys<EM>driver</EM>.so.1</B><DD>
<P>The dynamically loadable driver for a speech synthesizer,
where <EM>driver</EM> is the two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>.</P>
</DL>
</P>
<DT><B>/lib/brltty/rw/</B><DD>
<P>Files created at run-time, e.g. needed but missing system resources.</P>
<DT><B>/etc/</B><DD>
<P>
<DL>
<DT><B>brltty.conf</B><DD>
<P>System defaults for BRLTTY.</P>
<DT><B>brlapi.key</B><DD>
<P>The access key for BrlAPI.</P>
</DL>
</P>
<DT><B>/etc/brltty/</B><DD>
<P>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
<A HREF="#build">Build Options</A>).
<DL>
<DT><B>*.conf</B><DD>
<P>Driver-specific configuration data.
Their names look more or less like <CODE>brltty-</CODE><EM>driver</EM><CODE>.conf</CODE>,
where <EM>driver</EM> is the two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>.</P>
<DT><B>*.atb</B><DD>
<P>Attributes tables
(see section
<A HREF="BRLTTY-6.html#table-attributes">Attributes Tables</A> for details).
Their names look like <EM>name</EM><CODE>.atb</CODE>.</P>
<DT><B>*.ati</B><DD>
<P>Include files for attributes tables.</P>
<DT><B>*.ctb</B><DD>
<P>Contraction tables
(see section
<A HREF="BRLTTY-6.html#table-contraction">Contraction Tables</A> for details).
Their names look like <EM>language</EM><CODE>-</CODE><EM>country</EM><CODE>-</CODE><EM>level</EM><CODE>.ctb</CODE>.</P>
<DT><B>*.cti</B><DD>
<P>Include files for contraction tables.</P>
<DT><B>*.ktb</B><DD>
<P>Key tables
(see section
<A HREF="BRLTTY-6.html#table-key">Key Tables</A> for details).
Their names look like <EM>name</EM><CODE>.ktb</CODE>.</P>
<DT><B>*.kti</B><DD>
<P>Include files for key tables.</P>
<DT><B>*.ttb</B><DD>
<P>Text tables
(see section
<A HREF="BRLTTY-6.html#table-text">Text Tables</A> for details).
Their names look like <EM>language</EM><CODE>.ttb</CODE>.</P>
<DT><B>*.tti</B><DD>
<P>Include files for text tables.</P>
<DT><B>*.hlp</B><DD>
<P>Driver-specific help pages.
Their names look more or less like <CODE>brltty-</CODE><EM>driver</EM><CODE>.hlp</CODE>,
where <EM>driver</EM> is the two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>.</P>
</DL>
</P>
<DT><B>/var/lib/BrlAPI/</B><DD>
<P>Local sockets for connecting to the Application Programming Interface.</P>
<DT><B>/include/</B><DD>
<P>C header files for the Application Programming Interface.
Their names look like <CODE>brlapi-</CODE><EM>function</EM><CODE>.h</CODE>.
The main header is <CODE>brlapi.h</CODE>.</P>
<DT><B>/include/brltty/</B><DD>
<P>C header files for accessing braille hardware.
Their names look like <CODE>brldefs-</CODE><EM>driver</EM><CODE>.h</CODE>
(where <EM>driver</EM> is the two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>).
The headers <CODE>brldefs.h</CODE> and <CODE>api.h</CODE> are provided
for backward compatibility and shouldn't be used.</P>
<DT><B>/man/</B><DD>
<P>Man pages.
<DL>
<DT><B>man1/<EM>name</EM>.1</B><DD>
<P>Man pages for BRLTTY-related user commands.</P>
<DT><B>man3/<EM>name</EM>.3</B><DD>
<P>Man pages for Application Programming Interface library routines.</P>
</DL>
</P>
</DL>
</P>
<P>Some optional files which you should be aware of,
although they aren't part of the installed file hierarchy, are:
<DL>
<DT><B>/etc/brltty.conf</B><DD>
<P>The system defaults configuration file.
It's created by the system administrator.
See
<A HREF="BRLTTY-4.html#configure">The Configuration File</A> for details.</P>
<DT><B>/etc/brltty-<EM>driver</EM>.prefs</B><DD>
<P>The saved preferences settings file
(<EM>driver</EM> is a two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>).
It's created by the
<A HREF="BRLTTY-4.html#command-PREFSAVE">PREFSAVE</A> command.
See
<A HREF="BRLTTY-5.html#preferences">Preferences Settings</A> for details.</P>
</DL>
</P>
<H2><A NAME="tar"></A> <A NAME="ss3.2">3.2</A> <A HREF="BRLTTY.html#toc3.2">Installing from a TAR Ball</A>
</H2>
<P>Here's what to do if you just want to install BRLTTY as quickly as possible,
trusting that all of our defaults are correct.
<OL>
<LI>Download the source.
It'll be a file named
<CODE>brltty-</CODE><EM>release</EM><CODE>.tar.gz</CODE>,
e.g. <CODE>brltty-3.0.tar.gz</CODE>.</LI>
<LI>Unpack the source into its native hierarchical structure.
<BLOCKQUOTE><CODE>
tar xzf brltty-<EM>release</EM>.tar.gz
</CODE></BLOCKQUOTE>
This should create the directory <CODE>brltty-</CODE><EM>release</EM>.</LI>
<LI>Change to the source directory, configure, compile, and install BRLTTY.
<BLOCKQUOTE><CODE>
cd brltty-<EM>release</EM><BR>
./configure<BR>
make install
</CODE></BLOCKQUOTE>
This should be done as <B>root</B>.</LI>
</OL>
</P>
<P>To uninstall BRLTTY, do:
<BLOCKQUOTE><CODE>
cd brltty-<EM>release</EM><BR>
make uninstall
</CODE></BLOCKQUOTE>
</P>
<P>That's all there's to it.
Now, for those who really want to know what's going on, here are the details.</P>
<H3><A NAME="build"></A> Build Options</H3>
<P>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 <CODE>configure</CODE> 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.
<BLOCKQUOTE><CODE>
./configure
</CODE></BLOCKQUOTE>
If, however, you have some special requirements,
or even if you're just adventurous,
you should find out what your choices are.
<BLOCKQUOTE><CODE>
./configure --help
</CODE></BLOCKQUOTE>
You should also check out the <CODE>README</CODE> file in the subdirectory
containing the driver for your braille display
for any additional display-specific instructions.</P>
<H3><A NAME="build-defaults"></A> System Defaults</H3>
<P>
<DL>
<DT><B><CODE>--with-braille-driver=</CODE><EM>driver</EM>
<A NAME="build-braille-driver"></A> </B><DD>
<P>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
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>
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 (<CODE>-</CODE>),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>all</B><DD>
<P>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 default driver when all the drivers are to be linked in.</P>
<DT><B>-all</B><DD>
<P>Only build those drivers which have been explicitly included via this option.</P>
<DT><B>no</B><DD>
<P>Don't build any drivers at all.
This is equivalent to specifying <CODE>--without-braille-driver</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying <CODE>--with-braille-driver</CODE>.</P>
</DL>
See the
<A HREF="BRLTTY-4.html#configure-braille-driver">braille-driver</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-braille-driver">-b</A> command line option
for run-time selection.</P>
<DT><B><CODE>--with-braille-parameters=</CODE>[<EM>driver</EM><CODE>:</CODE>]<EM>name</EM><CODE>=</CODE><EM>value</EM><CODE>,</CODE>...
<A NAME="build-braille-parameters"></A> </B><DD>
<P>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
<A HREF="BRLTTY-10.html#drivers">Driver Identification Codes</A>)
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
<A HREF="BRLTTY-4.html#configure-braille-parameters">braille-parameters</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-braille-parameters">-B</A> command line option
for run-time selection.</P>
<DT><B><CODE>--with-braille-device=</CODE><EM>device</EM><CODE>,</CODE>...
<A NAME="build-braille-device"></A> </B><DD>
<P>Specify the default device to which the braille display is connected
(see section
<A HREF="BRLTTY-12.html#operand-braille-device">Braille Device Specification</A>).
If this option isn't specified then
<CODE>usb:</CODE> is assumed if USB support is available,
<CODE>bluetooth:</CODE> is assumed if Bluetooth support is available,
and <CODE>usb:,bluetooth:</CODE> is assumed if both are available.
If neither USB nor Bluetooth support is available then
an operating system appropriate path
for the primary (first) serial port (device) is assumed.
See the
<A HREF="BRLTTY-4.html#configure-braille-device">braille-device</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-braille-device">-d</A> command line option
for run-time selection.</P>
<DT><B><CODE>--with-libbraille=</CODE><EM>directory</EM>
<A NAME="build-libbraille"></A> </B><DD>
<P>Specify the installed location of the Libbraille package,
and build the Libbraille braille display driver
(see
<A HREF="#restrictions-libbraille">Build Restrictions</A>).
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>no</B><DD>
<P>Don't build the driver.
This is equivalent to specifying <CODE>--without-libbraille</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build the driver if the package can be found in
<CODE>/usr</CODE>,
<CODE>/usr/local</CODE>,
<CODE>/usr/local/Libbraille</CODE>,
<CODE>/usr/local/libbraille</CODE>,
<CODE>/opt/Libbraille</CODE>,
or <CODE>/opt/libbraille</CODE>.
This is equivalent to specifying <CODE>--with-libbraille</CODE>.</P>
</DL>
</P>
<DT><B><CODE>--with-text-table=</CODE><EM>file</EM>
<A NAME="build-text-table"></A> </B><DD>
<P>Specify the built-in (fallback) text table
(see section
<A HREF="BRLTTY-6.html#table-text">Text Tables</A> 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 <CODE>.ttb</CODE> extension is optional.
If this option isn't specified,
then <CODE>en-nabcc</CODE>,
a commonly (in North America) used 8-dot variant of the
<A HREF="BRLTTY-14.html#nabcc">North American Braille Computer Code</A>,
is assumed.
See the
<A HREF="BRLTTY-4.html#configure-text-table">text-table</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-text-table">-t</A> command line option
for run-time selection.
This setting can be changed with the
<A HREF="BRLTTY-5.html#preference-text-table">Text Table</A> preference.</P>
<DT><B><CODE>--with-attributes-table=</CODE><EM>file</EM>
<A NAME="build-attributes-table"></A> </B><DD>
<P>Specify the built-in (fallback) attributes table
(see section
<A HREF="BRLTTY-6.html#table-attributes">Attributes Translation</A> 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 <CODE>.atb</CODE> extension is optional.
If this option isn't specified,
then <CODE>left_right</CODE> is assumed.
Change it to <CODE>invleft_right</CODE> if you'd like it done the old way.
See the
<A HREF="BRLTTY-4.html#configure-attributes-table">attributes-table</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-attributes-table">-a</A> command line option
for run-time selection.
This setting can be changed with the
<A HREF="BRLTTY-5.html#preference-attributes-table">Attributes Table</A> preference.</P>
<DT><B><CODE>--with-speech-driver=</CODE><EM>driver</EM>
<A NAME="build-speech-driver"></A> </B><DD>
<P>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
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>
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 (<CODE>-</CODE>),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>all</B><DD>
<P>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 default driver when all the drivers are to be linked in.</P>
<DT><B>-all</B><DD>
<P>Only build those drivers which have been explicitly included via this option.</P>
<DT><B>no</B><DD>
<P>Don't build any drivers at all.
This is equivalent to specifying <CODE>--without-speech-driver</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying <CODE>--with-speech-driver</CODE>.</P>
</DL>
See the
<A HREF="BRLTTY-4.html#configure-speech-driver">speech-driver</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-speech-driver">-s</A> command line option
for run-time selection.</P>
<DT><B><CODE>--with-speech-parameters=</CODE>[<EM>driver</EM><CODE>:</CODE>]<EM>name</EM><CODE>=</CODE><EM>value</EM><CODE>,</CODE>...
<A NAME="build-speech-parameters"></A> </B><DD>
<P>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
<A HREF="BRLTTY-10.html#drivers">Driver Identification Codes</A>)
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
<A HREF="BRLTTY-4.html#configure-speech-parameters">speech-parameters</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-speech-parameters">-S</A> command line option
for run-time selection.</P>
<DT><B><CODE>--with-flite=</CODE><EM>directory</EM>
<A NAME="build-flite"></A> </B><DD>
<P>Specify the installed location of the FestivalLite text-to-speech package,
and build the FestivalLite speech synthesizer driver
(see
<A HREF="#restrictions-flite">Build Restrictions</A>).
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>no</B><DD>
<P>Don't build the driver.
This is equivalent to specifying <CODE>--without-flite</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build the driver if the package can be found in
<CODE>/usr</CODE>,
<CODE>/usr/local</CODE>,
<CODE>/usr/local/FestivalLite</CODE>,
<CODE>/usr/local/flite</CODE>,
<CODE>/opt/FestivalLite</CODE>,
or <CODE>/opt/flite</CODE>.
This is equivalent to specifying <CODE>--with-flite</CODE>.</P>
</DL>
</P>
<DT><B><CODE>--with-flite-language=</CODE><EM>language</EM>
<A NAME="build-flite-language"></A> </B><DD>
<P>Specify the language which the FestivalLite text to speech engine is to use.
The default language is <CODE>usenglish</CODE>.</P>
<DT><B><CODE>--with-flite-lexicon=</CODE><EM>lexicon</EM>
<A NAME="build-flite-lexicon"></A> </B><DD>
<P>Specify the lexicon which the FestivalLite text to speech engine is to use.
The default lexicon is <CODE>cmulex</CODE>.</P>
<DT><B><CODE>--with-flite-voice=</CODE><EM>voice</EM>
<A NAME="build-flite-voice"></A> </B><DD>
<P>Specify the voice which the FestivalLite text to speech engine is to use.
The default voice is <CODE>cmu_us_kal16</CODE>.</P>
<DT><B><CODE>--with-mikropuhe=</CODE><EM>directory</EM>
<A NAME="build-mikropuhe"></A> </B><DD>
<P>Specify the installed location of the Mikropuhe text-to-speech package,
and build the Mikropuhe speech synthesizer driver
(see
<A HREF="#restrictions-mikropuhe">Build Restrictions</A>).
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>no</B><DD>
<P>Don't build the driver.
This is equivalent to specifying <CODE>--without-mikropuhe</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build the driver if the package can be found in
<CODE>/usr</CODE>,
<CODE>/usr/local</CODE>,
<CODE>/usr/local/Mikropuhe</CODE>,
<CODE>/usr/local/mikropuhe</CODE>,
<CODE>/opt/Mikropuhe</CODE>,
or <CODE>/opt/mikropuhe</CODE>.
This is equivalent to specifying <CODE>--with-mikropuhe</CODE>.</P>
</DL>
</P>
<DT><B><CODE>--with-speechd=</CODE><EM>directory</EM>
<A NAME="build-speechd"></A> </B><DD>
<P>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:
<DL>
<DT><B>no</B><DD>
<P>Don't build the driver.
This is equivalent to specifying <CODE>--without-speechd</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build the driver if the package can be found in
<CODE>/usr</CODE>,
<CODE>/usr/local</CODE>,
<CODE>/usr/local/speech-dispatcher</CODE>,
<CODE>/usr/local/speechd</CODE>,
<CODE>/opt/speech-dispatcher</CODE>,
or <CODE>/opt/speechd</CODE>.
This is equivalent to specifying <CODE>--with-speechd</CODE>.</P>
</DL>
</P>
<DT><B><CODE>--with-swift=</CODE><EM>directory</EM>
<A NAME="build-swift"></A> </B><DD>
<P>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:
<DL>
<DT><B>no</B><DD>
<P>Don't build the driver.
This is equivalent to specifying <CODE>--without-swift</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build the driver if the package can be found in
<CODE>/usr</CODE>,
<CODE>/usr/local</CODE>,
<CODE>/usr/local/Swift</CODE>,
<CODE>/usr/local/swift</CODE>,
<CODE>/opt/Swift</CODE>,
or <CODE>/opt/swift</CODE>.
This is equivalent to specifying <CODE>--with-swift</CODE>.</P>
</DL>
</P>
<DT><B><CODE>--with-theta=</CODE><EM>directory</EM>
<A NAME="build-theta"></A> </B><DD>
<P>Specify the installed location of the Theta text-to-speech package,
and build the Theta speech synthesizer driver
(see
<A HREF="#restrictions-theta">Build Restrictions</A>).
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>no</B><DD>
<P>Don't build the driver.
This is equivalent to specifying <CODE>--without-theta</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build the driver if the package can be found in
<CODE>/usr</CODE>,
<CODE>/usr/local</CODE>,
<CODE>/usr/local/Theta</CODE>,
<CODE>/usr/local/theta</CODE>,
<CODE>/opt/Theta</CODE>,
or <CODE>/opt/theta</CODE>.
This is equivalent to specifying <CODE>--with-theta</CODE>.</P>
</DL>
</P>
<DT><B><CODE>--with-screen-driver=</CODE><EM>driver</EM>
<A NAME="build-screen-driver"></A> </B><DD>
<P>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
<A HREF="BRLTTY-11.html#screen">Supported Screen Drivers</A>)
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 (<CODE>-</CODE>),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>all</B><DD>
<P>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 default driver when all the drivers are to be linked in.</P>
<DT><B>-all</B><DD>
<P>Only build those drivers which have been explicitly included via this option.</P>
<DT><B>no</B><DD>
<P>Don't build any drivers at all.
This is equivalent to specifying <CODE>--without-screen-driver</CODE>.</P>
<DT><B>yes</B><DD>
<P>Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying <CODE>--with-screen-driver</CODE>.</P>
</DL>
The first non-excluded driver becomes the default driver.
If this option isn't specified,
or if no driver is specifically included,
then an operating system appropriate default is selected.
If a native driver for the current operating system is available,
then that driver is selected;
if not, then <CODE>sc</CODE> is selected.
See the
<A HREF="BRLTTY-4.html#configure-screen-driver">screen-driver</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-screen-driver">-x</A> command line option
for run-time selection.</P>
<DT><B><CODE>--with-screen-parameters=</CODE>[<EM>driver</EM><CODE>:</CODE>]<EM>name</EM><CODE>=</CODE><EM>value</EM><CODE>,</CODE>...
<A NAME="build-screen-parameters"></A> </B><DD>
<P>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
<A HREF="BRLTTY-11.html#screen">Supported Screen Drivers</A>)
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
<A HREF="BRLTTY-4.html#configure-screen-parameters">screen-parameters</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-screen-parameters">-X</A> command line option
for run-time selection.</P>
<DT><B><CODE>--with-usb-package=</CODE><EM>package</EM><CODE>,</CODE>...
<A NAME="build-usb-package"></A> </B><DD>
<P>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:
<OL>
<LI>libusb</LI>
<LI>libusb-1.0</LI>
</OL>
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>no</B><DD>
<P>Don't support USB I/O.
This is equivalent to specifying <CODE>--without-usb-package</CODE>.</P>
<DT><B>yes</B><DD>
<P>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 <CODE>--with-usb-package</CODE>.</P>
</DL>
</P>
<DT><B><CODE>--with-bluetooth-package=</CODE><EM>package</EM><CODE>,</CODE>...
<A NAME="build-bluetooth-package"></A> </B><DD>
<P>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:
<OL>
<LI>(no packages are currently supported)</LI>
</OL>
Any of the following words can also be used as the operand of this option:
<DL>
<DT><B>no</B><DD>
<P>Don't support Bluetooth I/O.
This is equivalent to specifying <CODE>--without-bluetooth-package</CODE>.</P>
<DT><B>yes</B><DD>
<P>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 <CODE>--with-bluetooth-package</CODE>.</P>
</DL>
</P>
</DL>
</P>
<H3><A NAME="build-directoreis"></A> Directory Specification</H3>
<P>
<DL>
<DT><B><CODE>--with-execute-root=</CODE><EM>directory</EM>
<A NAME="build-execute-root"></A> </B><DD>
<P>Specify the directory at which the
<A HREF="#hierarchy">installed file hierarchy</A>
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
<A HREF="BRLTTY-7.html#multiple">Installing Multiple Versions</A>
for an example of how to do this).</P>
<DT><B><CODE>--with-install-root=</CODE><EM>directory</EM>
<A NAME="build-install-root"></A> </B><DD>
<P>Specify the directory beneath which the
<A HREF="#hierarchy">installed file hierarchy</A>
is to be installed.
The absolute path should be supplied.
If this option isn't specified,
then the run-time package root
(see the
<A HREF="#build-execute-root">--with-execute-root</A> build option)
is assumed.
This directory is only used by
<A HREF="#make-install">make install</A>
and
<A HREF="#make-uninstall">make uninstall</A>.
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.</P>
<DT><B><CODE>--prefix=</CODE><EM>directory</EM>
<A NAME="build-portable-root"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
where the default directories for the architecture-independent files
are to be rooted.
These directories include:
<UL>
<LI>the
<A HREF="#build-writable-directory">writable directory</A></LI>
<LI>the
<A HREF="#build-data-directory">data directory</A></LI>
<LI>the
<A HREF="#build-configuration-directory">configuration directory</A></LI>
<LI>the
<A HREF="#build-manpage-directory">manpage directory</A></LI>
<LI>the
<A HREF="#build-include-directory">include directory</A></LI>
</UL>
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
<A HREF="#build-execute-root">--with-execute-root</A> build option.</P>
<DT><B><CODE>--exec-prefix=</CODE><EM>directory</EM>
<A NAME="build-architecture-root"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
where the default directories for the architecture-dependent files
are to be rooted.
These directories include:
<UL>
<LI>the
<A HREF="#build-program-directory">program directory</A></LI>
<LI>the
<A HREF="#build-library-directory">library directory</A></LI>
<LI>the
<A HREF="#build-api-directory">API directory</A></LI>
</UL>
The absolute path should be supplied.
If this option isn't specified,
then the directory specified via the
<A HREF="#build-portable-root">--prefix</A>
build option is assumed.
This directory is rooted at the directory specified by the
<A HREF="#build-execute-root">--with-execute-root</A> build option.</P>
<DT><B><CODE>--libdir=</CODE><EM>directory</EM>
<A NAME="build-api-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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 <CODE>--libdir</CODE>
(which defaults to <CODE>/lib</CODE> rooted at the directory specified by the
<A HREF="#build-architecture-root">--exec-prefix</A> build option)
is assumed.
The directory is created if it doesn't exist.</P>
<DT><B><CODE>--sysconfdir=</CODE><EM>directory</EM>
<A NAME="build-configuration-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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 <CODE>--sysconfdir</CODE>
(which defaults to <CODE>/etc</CODE> rooted at the directory specified by the
<A HREF="#build-portable-root">--prefix</A> build option)
is assumed.
The directory is created if it doesn't exist.</P>
<DT><B><CODE>--with-program-directory=</CODE><EM>directory</EM>
<A NAME="build-program-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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 <CODE>--bindir</CODE>
(which defaults to <CODE>/bin</CODE> rooted at the directory specified by the
<A HREF="#build-architecture-root">--exec-prefix</A> build option)
is assumed.
The directory is created if it doesn't exist.</P>
<DT><B><CODE>--with-library-directory=</CODE><EM>directory</EM>
<A NAME="build-library-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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 <CODE>brltty</CODE> subdirectory of the directory
specified via the standard configure option <CODE>--libdir</CODE>
(which defaults to <CODE>/lib</CODE> rooted at the directory specified by the
<A HREF="#build-architecture-root">--exec-prefix</A> build option)
is assumed.
The directory is created if it doesn't exist.</P>
<DT><B><CODE>--with-writable-directory=</CODE><EM>directory</EM>
<A NAME="build-writable-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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:
<DL>
<DT><B>no</B><DD>
<P>Don't define a writable directory.
This is equivalent to specifying <CODE>--without-writable-directory</CODE>.</P>
<DT><B>yes</B><DD>
<P>Use the default location.
This is equivalent to specifying <CODE>--with-writable-directory</CODE>.</P>
</DL>
If this option isn't specified,
then the <CODE>rw</CODE> subdirectory of the directory specified via the
<A HREF="#build-library-directory">--with-library-directory</A> build option
is assumed.
The directory is created if it doesn't exist.</P>
<DT><B><CODE>--with-data-directory=</CODE><EM>directory</EM>
<A NAME="build-data-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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 <CODE>brltty</CODE> subdirectory of the directory
specified via the standard configure option <CODE>--sysconfdir</CODE>
(which defaults to <CODE>/etc</CODE> rooted at the directory specified by the
<A HREF="#build-portable-root">--prefix</A> build option)
is assumed.
The directory is created if it doesn't exist.</P>
<DT><B><CODE>--with-manpage-directory=</CODE><EM>directory</EM>
<A NAME="build-manpage-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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 <CODE>--mandir</CODE>
(which defaults to <CODE>/man</CODE> rooted at the directory specified by the
<A HREF="#build-portable-root">--prefix</A> build option)
is assumed.
The directory is created if it doesn't exist.</P>
<DT><B><CODE>--with-include-directory=</CODE><EM>directory</EM>
<A NAME="build-include-directory"></A> </B><DD>
<P>Specify the directory within the
<A HREF="#hierarchy">installed file hierarchy</A>
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 <CODE>brltty</CODE> subdirectory of the directory
specified via the standard configure option <CODE>--includedir</CODE>
(which defaults to <CODE>/include</CODE> rooted at the directory specified by the
<A HREF="#build-portable-root">--prefix</A> build option)
is assumed.
The directory is created if it doesn't exist.</P>
</DL>
</P>
<H3><A NAME="build-features"></A> Build Features</H3>
<P>These options are primarily useful when building BRLTTY for use on a boot disk.
<DL>
<DT><B><CODE>--enable-standalone-programs</CODE>
<A NAME="build-standalone-programs"></A> </B><DD>
<P>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
<A HREF="#build-braille-driver">--with-braille-driver</A>,
<A HREF="#build-speech-driver">--with-speech-driver</A>,
and
<A HREF="#build-screen-driver">--with-screen-driver</A>
build options) are compiled.</P>
<DT><B><CODE>--enable-relocatable-install</CODE>
<A NAME="build-relocatable-install"></A> </B><DD>
<P>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.</P>
<DT><B><CODE>--disable-stripping</CODE>
<A NAME="build-stripping"></A> </B><DD>
<P>Don't remove the symbol tables from executables and shared objects when installing them.</P>
<DT><B><CODE>--disable-learn-mode</CODE>
<A NAME="build-learn-mode"></A> </B><DD>
<P>Reduce program size by excluding command learn mode
(see section
<A HREF="BRLTTY-5.html#learn">Command Learn Mode</A>).</P>
<DT><B><CODE>--disable-contracted-braille</CODE>
<A NAME="build-contracted-braille"></A> </B><DD>
<P>Reduce program size by excluding support for contracted braille
(see section
<A HREF="BRLTTY-6.html#table-contraction">Contraction Tables</A>).</P>
<DT><B><CODE>--disable-speech-support</CODE>
<A NAME="build-speech-support"></A> </B><DD>
<P>Reduce program size by excluding support for speech synthesizers.</P>
<DT><B><CODE>--disable-iconv</CODE>
<A NAME="build-iconv"></A> </B><DD>
<P>Reduce program size by excluding support for
character set conversion.</P>
<DT><B><CODE>--disable-icu</CODE>
<A NAME="build-icu"></A> </B><DD>
<P>Reduce program size by excluding support for
Unicode-based internationalization.</P>
<DT><B><CODE>--disable-x</CODE>
<A NAME="build-x"></A> </B><DD>
<P>Reduce program size by excluding support for
X11.</P>
<DT><B><CODE>--disable-beeper-support</CODE>
<A NAME="build-beeper-support"></A> </B><DD>
<P>Reduce program size by excluding support for
the console tone generator.</P>
<DT><B><CODE>--disable-pcm-support</CODE>
<A NAME="build-pcm-support"></A> </B><DD>
<P>Reduce program size by excluding support for
the digital audio interface on the sound card.</P>
<DT><B><CODE>--enable-pcm-support=</CODE><EM>interface</EM></B><DD>
<P>If a platform provides more than one digital audio interface
then the one which is to be used may be specified.
<BR><CENTER>
<TABLE BORDER><TR><TD>
Platform</TD><TD>Interface</TD><TD>Description</TD></TR><TR><TD>
Linux</TD><TD>oss</TD><TD>Open Sound System</TD></TR><TR><TD>
</TD><TD>alsa</TD><TD>Advanced Linux Sound Architecture</TD></TR><TR><TD>
</TD></TR></TABLE>
</CENTER><BR>
</P>
<DT><B><CODE>--disable-midi-support</CODE>
<A NAME="build-midi-support"></A> </B><DD>
<P>Reduce program size by excluding support for
the Musical Instrument Digital Interface of the sound card.</P>
<DT><B><CODE>--enable-midi-support=</CODE><EM>interface</EM></B><DD>
<P>If a platform provides more than one Musical Instrument Digital Interface
then the one which is to be used may be specified.
<BR><CENTER>
<TABLE BORDER><TR><TD>
Platform</TD><TD>Interface</TD><TD>Description</TD></TR><TR><TD>
Linux</TD><TD>oss</TD><TD>Open Sound System</TD></TR><TR><TD>
</TD><TD>alsa</TD><TD>Advanced Linux Sound Architecture</TD></TR><TR><TD>
</TD></TR></TABLE>
</CENTER><BR>
</P>
<DT><B><CODE>--disable-fm-support</CODE>
<A NAME="build-fm-support"></A> </B><DD>
<P>Reduce program size by excluding support for
the FM synthesizer on an AdLib, OPL3, Sound Blaster, or equivalent sound card.</P>
<DT><B><CODE>--disable-pm-configfile</CODE>
<A NAME="build-pm-configfile"></A> </B><DD>
<P>Reduce program size by excluding support for
the Papenmeier driver's configuration file.</P>
<DT><B><CODE>--disable-gpm</CODE>
<A NAME="build-gpm"></A> </B><DD>
<P>Reduce program size by excluding
the interface to the <CODE>gpm</CODE> application
which allows BRLTTY to interact with the pointer (mouse) device
(see section
<A HREF="BRLTTY-5.html#gpm">Pointer (Mouse) Support via GPM</A>).</P>
<DT><B><CODE>--disable-api</CODE>
<A NAME="build-api"></A> </B><DD>
<P>Reduce program size by excluding
the Application Programming Interface.</P>
<DT><B><CODE>--with-api-parameters=</CODE><EM>name</EM><CODE>=</CODE><EM>value</EM><CODE>,</CODE>...
<A NAME="build-api-parameters"></A> </B><DD>
<P>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 <B>BrlAPI</B> reference manual.
See the
<A HREF="BRLTTY-4.html#configure-api-parameters">api-parameters</A> configuration file directive
and the
<A HREF="BRLTTY-4.html#options-api-parameters">-A</A> command line option
for run-time selection.</P>
<DT><B><CODE>--disable-caml-bindings</CODE>
<A NAME="build-caml-bindings"></A> </B><DD>
<P>Don't build the Caml bindings for the Application Programming Interface.</P>
<DT><B><CODE>--disable-java-bindings</CODE>
<A NAME="build-java-bindings"></A> </B><DD>
<P>Don't build the Java bindings for the Application Programming Interface.</P>
<DT><B><CODE>--disable-lisp-bindings</CODE>
<A NAME="build-lisp-bindings"></A> </B><DD>
<P>Don't build the Lisp bindings for the Application Programming Interface.</P>
<DT><B><CODE>--disable-python-bindings</CODE>
<A NAME="build-python-bindings"></A> </B><DD>
<P>Don't build the Python bindings for the Application Programming Interface.</P>
<DT><B><CODE>--disable-tcl-bindings</CODE>
<A NAME="build-tcl-bindings"></A> </B><DD>
<P>Don't build the Tcl bindings for the Application Programming Interface.</P>
<DT><B><CODE>--with-tcl-config=</CODE><EM>path</EM>
<A NAME="build-tcl-config"></A> </B><DD>
<P>Specify the location of the Tcl configuration script (<CODE>tclConfig.sh</CODE>).
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:
<DL>
<DT><B>no</B><DD>
<P>Use other means to guess if Tcl is available, and, if so, where it has been installed.
This is equivalent to specifying <CODE>--without-tcl-config</CODE>.</P>
<DT><B>yes</B><DD>
<P>Search for the script in a few commonly used directories.
This is equivalent to specifying <CODE>--with-tcl-config</CODE>.</P>
</DL>
</P>
</DL>
</P>
<H3><A NAME="build-miscellaneous"></A> Miscellaneous Options</H3>
<P>
<DL>
<DT><B><CODE>--with-init-path=</CODE><EM>path</EM>
<A NAME="build-init-path"></A> </B><DD>
<P>Specify the path to the real <CODE>init</CODE> program for the system.
The absolute path should be supplied.
If this option is specified, then:
<OL>
<LI>The <CODE>init</CODE> program should be moved to a new location.</LI>
<LI><CODE>brltty</CODE> should be moved to the <CODE>init</CODE> program's original location.</LI>
<LI>When the system runs <CODE>init</CODE> at startup,
<CODE>brltty</CODE> is actually run.
It puts itself into the background,
and runs the real <CODE>init</CODE> 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.</LI>
</OL>
If this option isn't specified, then this feature isn't activated.
This option is primarily intended for building a braillified installer image.</P>
<DT><B><CODE>--with-stderr-path=</CODE><EM>path</EM>
<A NAME="build-stderr-path"></A> </B><DD>
<P>Specify the path to the file or device where standard error 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.</P>
</DL>
</P>
<H3><A NAME="make"></A> Make File Targets</H3>
<P>Once BRLTTY has been configured,
the next steps are to compile and to install it.
These are done by applying the system's <CODE>make</CODE> command
to BRLTTY's main make file (<CODE>Makefile</CODE> in the top-level directory).
BRLTTY's make file supports most of the common application maintenance targets.
They include:
<DL>
<DT><B>make</B><DD>
<P>A shortcut for <CODE>make all</CODE>.</P>
<DT><B>make all
<A NAME="make-all"></A> </B><DD>
<P>Compile and link the BRLTTY executable, its drivers and their help pages,
its test programs, and a few other small utilities.</P>
<DT><B>make install
<A NAME="make-install"></A> </B><DD>
<P>Complete the compile and link phase
(see
<A HREF="#make-all">make all</A>),
and then install the BRLTTY executable, its data files, drivers, and help pages,
in the correct places and with the correct permissions.</P>
<DT><B>make uninstall
<A NAME="make-uninstall"></A> </B><DD>
<P>Remove the BRLTTY executable, its data files, drivers, and help pages,
from the system.</P>
<DT><B>make clean
<A NAME="make-clean"></A> </B><DD>
<P>Ensure that the next compile and link
(see
<A HREF="#make-all">make all</A>)
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.</P>
<DT><B>make distclean
<A NAME="make-distclean"></A> </B><DD>
<P>In addition to removing the results of compiling and linking
(see
<A HREF="#make-clean">make clean</A>):
<UL>
<LI>Remove the results of BRLTTY configuration
(see
<A HREF="#build">Build Options</A>).
This includes the removal of
<CODE>config.mk</CODE>, <CODE>config.h</CODE>,
<CODE>config.cache</CODE>, <CODE>config.status</CODE>, and <CODE>config.log</CODE>.</LI>
<LI>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.</LI>
</UL>
</P>
</DL>
</P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="BRLTTY.html#toc3.3">Testing BRLTTY</A>
</H2>
<P>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:
<BLOCKQUOTE><CODE>
brltty -b<EM>driver</EM> -d<EM>device</EM>
</CODE></BLOCKQUOTE>
For <EM>driver</EM>, specify the two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>
corresponding to your braille display.
For <EM>device</EM>, specify the full path
for the device to which your braille display is connected.</P>
<P>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
<A HREF="BRLTTY-4.html#configure-braille-driver">braille-driver</A>
and the
<A HREF="BRLTTY-4.html#configure-braille-device">braille-device</A>
configuration file directives,
and/or compile your needs right into BRLTTY
via the
<A HREF="#build-braille-driver">--with-braille-driver</A>
and the
<A HREF="#build-braille-device">--with-braille-device</A>
build options.</P>
<P>If all is well, BRLTTY's version identification message
should appear on the braille display for a few seconds
(see the
<A HREF="BRLTTY-4.html#options-message-timeout">-M</A> 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.</P>
<P>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 problem.
The screen driver can be tested with
<A HREF="#utility-scrtest">scrtest</A>,
and the braille display driver can be tested with
<A HREF="#utility-brltest">brltest</A>.</P>
<P>If you experience a problem which requires a lot of digging,
then you may wish to use the following <CODE>brltty</CODE> command line options:
<UL>
<LI>
<A HREF="BRLTTY-4.html#options-log-level">-ldebug</A>
to log lots of diagnostic messages.</LI>
<LI>
<A HREF="BRLTTY-4.html#options-no-daemon">-n</A>
to keep BRLTTY in the foreground.</LI>
<LI>
<A HREF="BRLTTY-4.html#options-standard-error">-e</A>
to direct diagnostic messages to standard error
rather than to the system log.</LI>
</UL>
</P>
<H2><A NAME="ss3.4">3.4</A> <A HREF="BRLTTY.html#toc3.4">Starting BRLTTY</A>
</H2>
<P>BRLTTY, when properly installed, is invoked with the single command <CODE>brltty</CODE>.
A configuration file
(see section
<A HREF="BRLTTY-4.html#configure">The Configuration File</A> 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 table to be used.
Many options
(see section
<A HREF="BRLTTY-4.html#options">Command Line Options</A> 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
<A HREF="BRLTTY-4.html#options-help">-h</A> option
displays a summary of all the options.
The
<A HREF="BRLTTY-4.html#options-version">-V</A> option
displays the current version of the program, the API, and the selected drivers.
The
<A HREF="BRLTTY-4.html#options-verify">-v</A> option
displays the values of the options after all sources have been considered.</P>
<P>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:
<DL>
<DT><B>Red Hat</B><DD>
<P><CODE>/etc/rc.d/rc.local</CODE></P>
</DL>
</P>
<P>Starting BRLTTY from this script is a good approach (especially for new users).
Just add a set of lines like these:
<BLOCKQUOTE><CODE>
<PRE>
if [ -x /bin/brltty -a -f /etc/brltty.conf ]
then
/bin/brltty
fi
</PRE>
</CODE></BLOCKQUOTE>
This can usually be abbreviated to the somewhat less readable form:
<BLOCKQUOTE><CODE>
<PRE>
[ -x /bin/brltty -a -f /etc/brltty.conf ] && /bin/brltty
</PRE>
</CODE></BLOCKQUOTE>
Don't add these lines before the first line
(which usually looks like <CODE>#!/bin/sh</CODE>).</P>
<P>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:
<DL>
<DT><B>Debian</B><DD>
<P><CODE>/etc/init.d/boot</CODE> (for older releases)<BR>
<CODE>/etc/init.d/</CODE> (for newer releases)<BR>
A <CODE>brltty</CODE> package is provided
(see [
<A HREF="http://packages.debian.org/brltty">http://packages.debian.org/brltty</A>])
as of release <CODE>3.0</CODE> (<CODE>Woody</CODE>).
Since this package takes care of starting BRLTTY,
there's no need for user-supplied code to do so if it's installed.
If you need the daemon to run with some command-line options,
you can change the contents between quotes
on the directive <CODE>ARGUMENTS</CODE>
in the <CODE>/etc/default/brltty</CODE> file.</P>
<DT><B>RedHat</B><DD>
<P><CODE>/etc/rc.d/rc.sysinit</CODE><BR>
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 <CODE>initlog</CODE>.
Look, probably right up near the top, for a set of lines like these:
<BLOCKQUOTE><CODE>
<PRE>
# Rerun ourselves through initlog
if [ -z "$IN_INITLOG" ]; then
[ -f /sbin/initlog ] && exec /sbin/initlog $INITLOG_ARGS -r /etc/rc.sysinit
fi
</PRE>
</CODE></BLOCKQUOTE>
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.</P>
<DT><B>Slackware</B><DD>
<P><CODE>/etc/rc.d/rc.S</CODE></P>
<DT><B>SuSE</B><DD>
<P><CODE>/sbin/init.d/boot</CODE></P>
</DL>
</P>
<P>An alternative is to start BRLTTY from <CODE>/etc/inittab</CODE>.
You have two choices if you choose this route.
<UL>
<LI>If you want it to be started really early
but don't need it to be automatically restarted if it dies,
then add a line like this before the first <CODE>:sysinit:</CODE> line which is already in there.
<BLOCKQUOTE><CODE>
brl::sysinit:/bin/brltty
</CODE></BLOCKQUOTE>
</LI>
<LI>If you don't mind it being started later
but do want it to be automatically restarted if it dies,
then add a line like this anywhere within the file.
<BLOCKQUOTE><CODE>
brl:12345:respawn:/bin/brltty -n
</CODE></BLOCKQUOTE>
The
<A HREF="BRLTTY-4.html#options-no-daemon">-n</A> (<CODE>--nodaemon</CODE>) option is very
important when running BRLTTY with <B>init</B>'s <CODE>respawn</CODE> facility.
You'll end up with hundreds of BRLTTY processes all running at the same time
if you forget to specify it.</LI>
</UL>
Check that the identifier (<CODE>brl</CODE> in these examples)
isn't already being used by another entry,
and, if it is, choose a different one which isn't.</P>
<P>Note that a command like <CODE>kill -TERM</CODE>
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.</P>
<P>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
<A HREF="BRLTTY-4.html#command-RESTARTBRL">RESTARTBRL</A> command).
Better yet, turn off the serial port probing.
Here's what we know so far about how to do this:
<DL>
<DT><B>Red Hat</B><DD>
<P>The probing is done by a service named <CODE>kudzu</CODE>.
Use the command
<BLOCKQUOTE><CODE>
chkconfig --list kudzu
</CODE></BLOCKQUOTE>
to see if it's been enabled.
Use the command
<BLOCKQUOTE><CODE>
chkconfig kudzu off
</CODE></BLOCKQUOTE>
to disable it.
Later releases allow you to let <CODE>kudzu</CODE> run
without probing the serial ports.
To do this, edit the file <CODE>/etc/sysconfig/kudzu</CODE>,
and set <CODE>SAFE</CODE> to <CODE>yes</CODE>.</P>
</DL>
</P>
<P>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
<A HREF="#build-execute-root">--with-execute-root</A>,
<A HREF="#build-program-directory">--bindir</A>,
<A HREF="#build-library-directory">--libdir</A>,
<A HREF="#build-writable-directory">--with-writable-directory</A>,
and
<A HREF="#build-data-directory">--with-data-directory</A>
build options.</P>
<H2><A NAME="ss3.5">3.5</A> <A HREF="BRLTTY.html#toc3.5">Security Considerations</A>
</H2>
<P>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 <CODE>/dev/vcsa</CODE> 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.</P>
<H2><A NAME="ss3.6">3.6</A> <A HREF="BRLTTY.html#toc3.6">Build and Run-Time Restrictions</A>
</H2>
<P>
<DL>
<DT><B>Alert Tunes</B><DD>
<P>
<A NAME="restrictions-tunes"></A>
Some platforms don't support all of the tune devices.
See the
<A HREF="BRLTTY-5.html#preference-tune-device">Tune Device</A>
preference for details.</P>
<DT><B>FestivalLite Speech Synthesizer Driver</B><DD>
<P>
<A NAME="restrictions-flite"></A>
The driver for the FestivalLite text to speech engine
is only built if that package has been installed.</P>
<P>This driver and the driver for the Theta text to speech engine
(see the
<A HREF="#build-theta">--with-theta</A> build option)
cannot be simultaneously linked into the BRLTTY binary
(see the
<A HREF="#build-speech-driver">--with-speech-driver</A> build option)
because their run-time libraries contain conflicting symbols.</P>
<DT><B>Libbraille Braille Display Driver</B><DD>
<P>
<A NAME="restrictions-libbraille"></A>
The driver for the Libbraille package
is only built if that package has been installed.</P>
<DT><B>Mikropuhe Speech Synthesizer Driver</B><DD>
<P>
<A NAME="restrictions-mikropuhe"></A>
The driver for the Mikropuhe text to speech engine
is only built if that package has been installed.</P>
<P>This driver cannot be included if the BRLTTY binary is statically linked
(see the
<A HREF="#build-standalone-programs">--enable-standalone-programs</A> build option)
because a static archive isn't included with the package.</P>
<DT><B>Theta Speech Synthesizer Driver</B><DD>
<P>
<A NAME="restrictions-theta"></A>
The driver for the Theta text to speech engine
is only built if that package has been installed.</P>
<P>This driver and the driver for the FestivalLite text to speech engine
(see the
<A HREF="#build-flite">--with-flite</A> build option)
cannot be simultaneously linked into the BRLTTY binary
(see the
<A HREF="#build-speech-driver">--with-speech-driver</A> build option)
because their run-time libraries contain conflicting symbols.</P>
<P>If this driver is built as a dynamically loadable shared object
then <CODE>$THETA_HOME/lib</CODE> must be added
to the <CODE>LD_LIBRARY_PATH</CODE> environment variable
before BRLTTY is invoked
because the shared objects within the package don't contain
run-time search paths for their dependencies.</P>
<DT><B>ViaVoice Speech Synthesizer Driver</B><DD>
<P>
<A NAME="restrictions-viavoice"></A>
The driver for the ViaVoice text to speech engine
is only built if that package has been installed.</P>
<P>This driver cannot be included if the BRLTTY binary is statically linked
(see the
<A HREF="#build-standalone-programs">--enable-standalone-programs</A> build option)
because a static archive isn't included with the package.</P>
<DT><B>VideoBraille Braille Display Driver</B><DD>
<P>
<A NAME="restrictions-videobraille"></A>
The driver for the VideoBraille braille display is built on all systems,
but only works on Linux.</P>
</DL>
</P>
<H2><A NAME="rpm"></A> <A NAME="ss3.7">3.7</A> <A HREF="BRLTTY.html#toc3.7">Installing from an RPM File</A>
</H2>
<P>To install BRLTTY from an RPM (RedHat Package Manager) file, do the following:
<OL>
<LI>Download the binary package which corresponds to your hardware.
It'll be a file named
<CODE>brltty-</CODE><EM>release</EM><CODE>-</CODE><EM>version</EM><CODE>.</CODE><EM>architecture</EM><CODE>.rpm</CODE>,
e.g. <CODE>brltty-3.0-1.i386.rpm</CODE>.</LI>
<LI>Install the package.
<BLOCKQUOTE><CODE>
rpm -Uvh brltty-<EM>release</EM>-<EM>version</EM>.<EM>architecture</EM>.rpm
</CODE></BLOCKQUOTE>
This should be done as <B>root</B>.
Strictly speaking, the <CODE>-U</CODE> (update) option is the only one which is necessary.
The <CODE>-v</CODE> (verbose) option displays the name of the package as it's being installed.
The <CODE>-h</CODE> (hashes) option displays a progress meter (using hash signs).</LI>
</OL>
For the brave,
we also provide the source RPM (<CODE>.src.rpm</CODE>) file,
but that's beyond the scope of this document.</P>
<P>To uninstall BRLTTY, do:
<BLOCKQUOTE><CODE>
rpm -e brltty
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss3.8">3.8</A> <A HREF="BRLTTY.html#toc3.8">Other Utilities</A>
</H2>
<P>Building BRLTTY also results in the building of
a few small helper and diagnostic utilities.</P>
<H3><A NAME="utility-brltty-config"></A> brltty-config</H3>
<P>This utility sets a number of environment variables to values
which reflect the current installation of BRLTTY
(see
<A HREF="#build">Build Options</A>).
It should be executed within an existing shell environment,
i.e. not as a command in its own right,
and can only be used by scripts which support <B>Bourne Shell</B> syntax.
<BLOCKQUOTE><CODE>
. brltty-config
</CODE></BLOCKQUOTE>
</P>
<P>The following environment variables are set:
<DL>
<DT><B>BRLTTY_VERSION</B><DD>
<P>The version number of the BRLTTY package.</P>
<DT><B>BRLTTY_EXECUTE_ROOT</B><DD>
<P>Run-time root for the installed package.
Configured via the
<A HREF="#build-execute-root">--with-execute-root</A> build option.</P>
<DT><B>BRLTTY_PROGRAM_DIRECTORY</B><DD>
<P>Directory for runnable programs (binaries, executables).
Configured via the
<A HREF="#build-program-directory">--with-program-directory</A> build option.</P>
<DT><B>BRLTTY_LIBRARY_DIRECTORY</B><DD>
<P>Directory for drivers.
Configured via the
<A HREF="#build-library-directory">--with-library-directory</A> build option.</P>
<DT><B>BRLTTY_WRITABLE_DIRECTORY</B><DD>
<P>Directory which can be written to.
Configured via the
<A HREF="#build-writable-directory">--with-writable-directory</A> build option.</P>
<DT><B>BRLTTY_DATA_DIRECTORY</B><DD>
<P>Directory for tables and help pages.
Configured via the
<A HREF="#build-data-directory">--with-data-directory</A> build option.</P>
<DT><B>BRLTTY_MANPAGE_DIRECTORY</B><DD>
<P>Directory for manual pages.
Configured via the
<A HREF="#build-manpage-directory">--with-manpage-directory</A> build option.</P>
<DT><B>BRLTTY_INCLUDE_DIRECTORY</B><DD>
<P>Directory for BrlAPI's C header files.
Configured via the
<A HREF="#build-include-directory">--with-include-directory</A> build option.</P>
<DT><B>BRLAPI_VERSION</B><DD>
<P>The version number of BrlAPI (BRLTTY's Application Programming Interface).</P>
<DT><B>BRLAPI_RELEASE</B><DD>
<P>The full release number of BrlAPI.</P>
<DT><B>BRLAPI_AUTH</B><DD>
<P>The name of BrlAPI's key file.</P>
</DL>
</P>
<P>In addition, the following standard <B>autoconf</B> environment variables are also set:
<DL>
<DT><B>prefix</B><DD>
<P>Subroot for architecture-independent files.
Configured via the
<A HREF="#build-portable-root">--prefix</A> build option.</P>
<DT><B>exec_prefix</B><DD>
<P>Subroot for architecture-dependent files.
Configured via the
<A HREF="#build-architecture-root">--exec-prefix</A> build option.</P>
<DT><B>bindir</B><DD>
<P>Default location for
<A HREF="#build-program-directory">program directory</A>.
Configured via the <CODE>--bindir</CODE> build option.</P>
<DT><B>libdir</B><DD>
<P>Directory for BrlAPI's static archive and dynamically loadable object.
Default anchor for
<A HREF="#build-library-directory">library directory</A>.
Configured via the
<A HREF="#build-api-directory">--libdir</A> build option.</P>
<DT><B>sysconfdir</B><DD>
<P>Directory for configuration files.
Default anchor for
<A HREF="#build-data-directory">data directory</A>.
Configured via the
<A HREF="#build-configuration-directory">--sysconfdir</A> build option.</P>
<DT><B>mandir</B><DD>
<P>Default location for
<A HREF="#build-manpage-directory">manual pages directory</A>.
Configured via the <CODE>--mandir</CODE> build option.</P>
<DT><B>includedir</B><DD>
<P>Default anchor for
<A HREF="#build-include-directory">header files directory</A>.
Configured via the <CODE>--includedir</CODE> build option.</P>
</DL>
</P>
<H3><A NAME="utility-brltty-install"></A> brltty-install</H3>
<P>This utility copies BRLTTY's
<A HREF="#hierarchy">installed file hierarchy</A>
from one location to another.
<BLOCKQUOTE><CODE>
brltty-install <EM>to</EM> [<EM>from</EM>]
</CODE></BLOCKQUOTE>
<DL>
<DT><B><EM>to</EM></B><DD>
<P>The location to which the
<A HREF="#hierarchy">installed file hierarchy</A>
is to be copied.
It must be an existing directory.</P>
<DT><B><EM>from</EM></B><DD>
<P>The location from which the
<A HREF="#hierarchy">installed file hierarchy</A>
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.</P>
</DL>
</P>
<P>This utility can be used, for example, to copy BRLTTY to a root disk.
If a root floppy is mounted as <CODE>/mnt</CODE>,
and BRLTTY is installed on the main system,
then typing
<BLOCKQUOTE><CODE>
brltty-install /mnt
</CODE></BLOCKQUOTE>
copies BRLTTY, along with all of its data and library files,
to the root floppy.</P>
<P>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.</P>
<H3><A NAME="utility-brltest"></A> brltest</H3>
<P>This utility tests a braille display driver,
and also provides an interactive way to learn
what the keys on the braille display do.
It should be run as root.
<BLOCKQUOTE><CODE>
brltest -<EM>option</EM> ... [<EM>driver</EM> [<EM>name</EM>=<EM>value</EM> ...]]
</CODE></BLOCKQUOTE>
<DL>
<DT><B><EM>driver</EM></B><DD>
<P>The driver for the braille display.
It must be a two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>.
If it's not specified, then the first driver configured via the
<A HREF="#build-braille-driver">--with-braille-driver</A> build option
is assumed.</P>
<DT><B><EM>name</EM><CODE>=</CODE><EM>value</EM></B><DD>
<P>Set a braille display driver parameter.
For a description of the parameters accepted by a specific driver,
please see the documentation for that driver.</P>
<DT><B><CODE>-d</CODE><EM>device</EM> <CODE>--device=</CODE><EM>device</EM></B><DD>
<P>The absolute path for the device to which the braille display is connected.
If it's not specified, then the device configured via the
<A HREF="#build-braille-device">--with-braille-device</A> build option
is assumed.</P>
<DT><B><CODE>-D</CODE><EM>directory</EM> <CODE>--data-directory=</CODE><EM>directory</EM></B><DD>
<P>The absolute path for the directory wherein the driver data files reside.
If it's not specified, then the directory configured via the
<A HREF="#build-data-directory">--with-data-directory</A> build option
is assumed.</P>
<DT><B><CODE>-L</CODE><EM>directory</EM> <CODE>--library-directory=</CODE><EM>directory</EM></B><DD>
<P>The absolute path for the directory wherein the drivers reside.
If it's not specified, then the directory configured via the
<A HREF="#build-library-directory">--libdir</A> build option
is assumed.</P>
<DT><B><CODE>-W</CODE><EM>directory</EM> <CODE>--writable-directory=</CODE><EM>directory</EM></B><DD>
<P>The absolute path for a directory which can be written to.
If it's not specified, then the directory configured via the
<A HREF="#build-writable-directory">--with-writable-directory</A> build option
is assumed.</P>
<DT><B><CODE>-h</CODE> <CODE>--help</CODE></B><DD>
<P>Display a summary of the command line options, and then exit.</P>
</DL>
</P>
<P>This utility uses BRLTTY's
<A HREF="BRLTTY-5.html#learn">Command Learn Mode</A>.
The key press timeout
(after which this utility exits)
is <CODE>10</CODE> seconds.
The message hold time
(used for non-final segments of long messages)
is <CODE>4</CODE> seconds.</P>
<H3><A NAME="utility-spktest"></A> spktest</H3>
<P>This utility tests a speech synthesizer driver.
It may need to be run as root.
<BLOCKQUOTE><CODE>
spktest -<EM>option</EM> ... [<EM>driver</EM> [<EM>name</EM>=<EM>value</EM> ...]]
</CODE></BLOCKQUOTE>
<DL>
<DT><B><EM>driver</EM></B><DD>
<P>The driver for the speech synthesizer.
It must be a two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>.
If it's not specified, then the first driver configured via the
<A HREF="#build-speech-driver">--with-speech-driver</A> build option
is assumed.</P>
<DT><B><EM>name</EM><CODE>=</CODE><EM>value</EM></B><DD>
<P>Set a speech synthesizer driver parameter.
For a description of the parameters accepted by a specific driver,
please see the documentation for that driver.</P>
<DT><B><CODE>-t</CODE><EM>string</EM> <CODE>--text-string=</CODE><EM>string</EM></B><DD>
<P>The text to be spoken.
If it's not specified, then standard input is read.</P>
<DT><B><CODE>-D</CODE><EM>directory</EM> <CODE>--data-directory=</CODE><EM>directory</EM></B><DD>
<P>The absolute path for the directory wherein the driver data files reside.
If it's not specified, then the directory configured via the
<A HREF="#build-data-directory">--with-data-directory</A> build option
is assumed.</P>
<DT><B><CODE>-L</CODE><EM>directory</EM> <CODE>--library-directory=</CODE><EM>directory</EM></B><DD>
<P>The absolute path for the directory wherein the drivers reside.
If it's not specified, then the directory configured via the
<A HREF="#build-library-directory">--libdir</A> build option
is assumed.</P>
<DT><B><CODE>-h</CODE> <CODE>--help</CODE></B><DD>
<P>Display a summary of the command line options, and then exit.</P>
</DL>
</P>
<H3><A NAME="utility-scrtest"></A> scrtest</H3>
<P>This utility tests the screen driver.
It must be run as root.
<BLOCKQUOTE><CODE>
scrtest -<EM>option</EM> ... [<EM>name</EM>=<EM>value</EM> ...]
</CODE></BLOCKQUOTE>
<DL>
<DT><B><EM>name</EM><CODE>=</CODE><EM>value</EM></B><DD>
<P>Set a screen driver parameter.
For a description of the parameters accepted by a specific driver,
please see the documentation for that driver.</P>
<DT><B><CODE>-l</CODE><EM>column</EM> <CODE>--left=</CODE><EM>column</EM></B><DD>
<P>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.</P>
<DT><B><CODE>-c</CODE><EM>count</EM> <CODE>--columns=</CODE><EM>count</EM></B><DD>
<P>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.</P>
<DT><B><CODE>-t</CODE><EM>row</EM> <CODE>--top=</CODE><EM>row</EM></B><DD>
<P>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.</P>
<DT><B><CODE>-r</CODE><EM>count</EM> <CODE>--rows=</CODE><EM>count</EM></B><DD>
<P>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>
<DT><B><CODE>-h</CODE> <CODE>--help</CODE></B><DD>
<P>Display a summary of the command line options, and then exit.</P>
</DL>
</P>
<P>Notes:
<UL>
<LI>If neither a starting column nor a region width is specified,
then the region is horizontally-centred and starts at column 5.</LI>
<LI>If neither a starting row nor a region height is specified,
then the region is vertically-centred and starts at row 5.</LI>
</UL>
</P>
<P>The following is written to standard output:
<OL>
<LI>A line detailing the dimensions of the screen.
<BLOCKQUOTE><CODE>
Screen: <EM>width</EM>x<EM>height</EM>
</CODE></BLOCKQUOTE>
</LI>
<LI>A line detailing the position (zero-origin) of the cursor.
<BLOCKQUOTE><CODE>
Cursor: [<EM>column</EM>,<EM>row</EM>]
</CODE></BLOCKQUOTE>
</LI>
<LI>A line detailing the size of the selected screen region,
and the position (zero-origin) of its top-left corner.
<BLOCKQUOTE><CODE>
Region: <EM>width</EM>x<EM>height</EM>@[<EM>column</EM>,<EM>row</EM>]
</CODE></BLOCKQUOTE>
</LI>
<LI>The contents of the selected screen region.
Unprintable characters are written as blanks.</LI>
</OL>
</P>
<H3><A NAME="utility-ttbtest"></A> ttbtest</H3>
<P>This utility tests a text table
(see section
<A HREF="BRLTTY-6.html#table-text">Text Tables</A>).
<BLOCKQUOTE><CODE>
ttbtest -<EM>option</EM> ... <EM>input-table</EM> <EM>output-table</EM>
</CODE></BLOCKQUOTE>
<DL>
<DT><B><EM>input-table</EM></B><DD>
<P>The file system path to the input text table.
If it's relative then it's anchored at the directory configured via the
<A HREF="#build-data-directory">--with-data-directory</A> build option.</P>
<DT><B><EM>output-table</EM></B><DD>
<P>The file system path to the output text table.
If it's relative then it's anchored at the current working directory.
If this parameter isn't supplied then no output table is written.</P>
<DT><B><CODE>-i</CODE><EM>format</EM> <CODE>--input-format=</CODE><EM>format</EM></B><DD>
<P>Specify the format of the input table.
If this option isn't supplied then the format of the input table
is deduced from the extension of the input table's file name.</P>
<DT><B><CODE>-o</CODE><EM>format</EM> <CODE>--output-format=</CODE><EM>format</EM></B><DD>
<P>Specify the format of the output table.
If this option isn't supplied then the format of the output table
is deduced from the extension of the output table's file name.</P>
<DT><B><CODE>-c</CODE><EM>charset</EM> <CODE>--charset=</CODE><EM>charset</EM></B><DD>
<P>Specify the name of the 8-bit character set to use when interpreting the tables.
If this option isn't supplied then the host's character set is used.</P>
<DT><B><CODE>-e</CODE> <CODE>--edit</CODE></B><DD>
<P>Invoke the text table editor.
If the output table is specified then changes are written to it.
If not then the input table is rewritten.</P>
<DT><B><CODE>-h</CODE> <CODE>--help</CODE></B><DD>
<P>Display a summary of the command line options, and then exit.</P>
</DL>
</P>
<P>If no special action is requested then the output table is optional.
If it is not specified then the input table is checked.
If it is specified then the input table is converted.</P>
<P>The following table formats are supported:
<DL>
<DT><B>ttb</B><DD>
<P>BRLTTY</P>
<DT><B>sbl</B><DD>
<P>SuSE Blinux</P>
<DT><B>a2b</B><DD>
<P>Gnopernicus</P>
<DT><B>gnb</B><DD>
<P>Gnome Braille</P>
</DL>
</P>
<H3><A NAME="utility-ctbtest"></A> ctbtest</H3>
<P>This utility tests a contraction table
(see section
<A HREF="BRLTTY-6.html#table-contraction">Contraction Tables</A>).
The text read from the input files (or standard input)
is rewritten to standard output as contracted braille.
<BLOCKQUOTE><CODE>
ctbtest -<EM>option</EM> ... <EM>input-file</EM> ...
</CODE></BLOCKQUOTE>
<DL>
<DT><B><EM>input-file</EM></B><DD>
<P>The list of files to be processed.
Any number of files may be specified.
They're processed from left to right.
The special file name <CODE>-</CODE> is interpreted to mean standard input.
If no files are specified then standard input is processed.</P>
<DT><B><CODE>-c</CODE><EM>file</EM> <CODE>--contraction-table=</CODE><EM>file</EM></B><DD>
<P>The file system path to the contraction table.
If it's relative then it's anchored at the directory configured via the
<A HREF="#build-data-directory">--with-data-directory</A> build option.
The <CODE>.ctb</CODE> extension is optional.
If this option isn't supplied then <CODE>en-us-g2</CODE> is assumed.</P>
<DT><B><CODE>-t</CODE><EM>file</EM>|<CODE>auto</CODE> <CODE>--text-table=</CODE><EM>file</EM>|<CODE>auto</CODE></B><DD>
<P>Specify the text table
(see section
<A HREF="BRLTTY-6.html#table-text">Text Tables</A> for details).
If a relative path is supplied, then it's anchored at <CODE>/etc/brltty</CODE>
(see the
<A HREF="#build-data-directory">--with-data-directory</A>
and the
<A HREF="#build-execute-root">--with-execute-root</A>
build options for more details).
The <CODE>.ttb</CODE> extension is optional.
See the
<A HREF="BRLTTY-4.html#configure-text-table">text-table</A>
configuration file directive for the default run-time setting.
This setting can be changed with the
<A HREF="BRLTTY-5.html#preference-text-table">Text Table</A> preference.</P>
<DT><B><CODE>-w</CODE><EM>columns</EM> <CODE>--output-width=</CODE><EM>columns</EM></B><DD>
<P>The maximum length of an output line.
Each contracted input line is wrapped into as many output lines as necessary.
If this option isn't specified then there's no limit,
and there's a one-to-one correspondence between input and output lines.</P>
<DT><B><CODE>-h</CODE> <CODE>--help</CODE></B><DD>
<P>Display a summary of the command line options, and then exit.</P>
</DL>
</P>
<P>The text table is used:
<UL>
<LI>To define the output character set so that
the contracted braille will be displayed correctly.
The same table as will be used by BRLTTY when the output is read should be specified.</LI>
<LI>To define the braille representations of those characters
defined within the contraction table as <CODE>=</CODE>
(see section
<A HREF="BRLTTY-6.html#contraction-opcodes-translation">Character Translation</A>).</LI>
</UL>
</P>
<P>The <CODE>brf.ttb</CODE> text table is provided for use with this utility.
It defines the format used within <CODE>.brf</CODE> files.
This is also the preferred format used
by most braille printers
and within electronically distributed braille documents.
This table effectively allows this utility to be used as a text to braille translator.</P>
<H3><A NAME="utility-tunetest"></A> tunetest</H3>
<P>This utility tests the alert tunes facility,
and also provides an easy way to compose new tunes.
It may need to be run as root.
<BLOCKQUOTE><CODE>
tunetest -<EM>option</EM> ... {<EM>note</EM> <EM>duration</EM>} ...
</CODE></BLOCKQUOTE>
<DL>
<DT><B><EM>note</EM></B><DD>
<P>A standard <CODE>MIDI</CODE> note number.
It must be an integer from <CODE>1</CODE> through <CODE>127</CODE>,
with <CODE>60</CODE> representing <CODE>Middle C</CODE>.
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 (<CODE>1</CODE>) represents
the fifth <CODE>C-Sharp</CODE> below <CODE>Middle C</CODE>,
and the highest value (<CODE>127</CODE>) represents
the sixth <CODE>G</CODE> above <CODE>Middle C</CODE>.</P>
<DT><B><EM>duration</EM></B><DD>
<P>The duration of the note in milliseconds.
It must be an integer from <CODE>1</CODE> through <CODE>255</CODE>.</P>
<DT><B><CODE>-d</CODE><EM>device</EM> <CODE>--device=</CODE><EM>device</EM></B><DD>
<P>The device on which to play the tune.
<DL>
<DT><B>beeper</B><DD>
<P>The internal beeper (console tone generator).</P>
<DT><B>pcm</B><DD>
<P>The digital audio interface on the sound card.</P>
<DT><B>midi</B><DD>
<P>The Musical Instrument Digital Interface on the sound card.</P>
<DT><B>fm</B><DD>
<P>The FM synthesizer on an
AdLib, OPL3, Sound Blaster, or equivalent sound card.</P>
</DL>
The device name may be abbreviated.
See the
<A HREF="BRLTTY-5.html#preference-tune-device">Tune Device</A> preference
for details regarding the default device and platform restrictions.</P>
<DT><B><CODE>-v</CODE><EM>loudness</EM> <CODE>--volume=</CODE><EM>loudness</EM></B><DD>
<P>Specify the output volume (loudness) as a percentage of the maximum.
The default output volume is <CODE>50</CODE>.</P>
<DT><B><CODE>-p</CODE><EM>device</EM> <CODE>--pcm-device=</CODE><EM>device</EM></B><DD>
<P>Specify the device to use for digital audio
(see section
<A HREF="BRLTTY-12.html#operand-pcm-device">PCM Device Specification</A>).
This option isn't available if the
<A HREF="#build-pcm-support">--disable-pcm-support</A> build option was specified.</P>
<DT><B><CODE>-m</CODE><EM>device</EM> <CODE>--midi-device=</CODE><EM>device</EM></B><DD>
<P>Specify the device to use for the Musical Instrument Digital Interface
(see section
<A HREF="BRLTTY-12.html#operand-midi-device">MIDI Device Specification</A>).
This option isn't available if the
<A HREF="#build-midi-support">--disable-midi-support</A> build option was specified.</P>
<DT><B><CODE>-i</CODE><EM>instrument</EM> <CODE>--instrument=</CODE><EM>instrument</EM></B><DD>
<P>The instrument to use if the selected device is <CODE>midi</CODE>.
For the complete list of instruments,
see the
<A HREF="BRLTTY-15.html#midi">MIDI Instrument Table</A>.
The default instrument is an <CODE>acoustic grand piano</CODE>.
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 <CODE>acoustic grand piano</CODE>, for example, may be specified as <CODE>a-gra-pi</CODE>.</P>
<DT><B><CODE>-h</CODE> <CODE>--help</CODE></B><DD>
<P>Display a summary of the command line options, and then exit.</P>
</DL>
</P>
<HR>
<A HREF="BRLTTY-4.html">Next</A>
<A HREF="BRLTTY-2.html">Previous</A>
<A HREF="BRLTTY.html#toc3">Contents</A>
</BODY>
</HTML>
Mini Shell