System Requirements
===================

The earliest release of Windows which is supported by BRLTTY is Windows 98.

Pre-built versions of brltty are available for download on
http://mielke.cc/brltty or on http://youpibouh.thefreecat.org/brltty/

In order to build BRLTTY yourself from a supplied tarball, you
need either Cygwin (see [http://www.cygwin.com/]) or MinGW (see
[http://mingw.sourceforge.net/]). In both cases, you also need the following
additional packages:
*  gcc
*  make
*  w32api (version 3.6 or later)

If you'd like to build BRLTTY from its source repository rather than from one
of the supplied tarballs then you'll also need these additional packages:
*  autoconf
*  tcltk

If you'd like to prepare the documentation (do make within the Documents/
subdirectory) you'll need these packages:
*  linuxdoc-tools (not pre-packaged in cygwin unfortunately)
*  doxygen

If you are using MSYS for running configure and make, you should always use
Windows paths (like c:/brltty), not MSYS paths (like /c/brltty), because brltty
does _not_ understand MSYS paths.

------------------------------------------------------------------------------


Windows 98 and Me Limitation
============================

On Windows versions 2000, XP, 2003, and later, BRLTTY automatically accesses
the Windows terminal which you're currently using as you switch between them.
This isn't possible on earlier versions. One way to still achieve this
functionality, however, is to run one BRLTTY (which directly accesses your
braille display) on the root window and another one (which indirectly accesses
your braille display via BrlAPI) on each terminal. This scheme may sound
complicated, but it can be easily set up to run automatically.

The first (or root) BRLTTY should be run as part of Windows startup. It must be
given those options which are necessary to access your braille display, e.g.
-b, -d, and all other options you'd normally specify. It must also be given the
-Xroot=yes option, which attaches it to the root window. 

An additional BRLTTY should then be run for each new terminal. It should be
invoked like this:

   brltty -bba -N

The -bba option tells it to access the root BRLTTY via BrlAPI, and the -N
option tells it not to start a BrlAPI server of its own.

These BRLTTYs can be started automatically by, for example, adding this line to
your .bashrc script. Each of these BRLTTYs takes care of the terminal it's
running in, and connects, via BrlAPI, to the root BRLTTY in order to access
your braille display.

If you're not concerned with security, and would rather not fiddle with the
brlapi.key file, then add the -Aauth=none option to the command line which
invokes the root BRLTTY. You don't need to worry about unauthorized access over
the network since the default is that only locally running programs can connect
to BrlAPI.

------------------------------------------------------------------------------


Cygwin Package Management from the Cygwin Command Line
======================================================

A convenient way to manage Cygwin packages from the Cygwin command line is to 
use the "apt-cyg" tool. It is similar to the "apt-get" command which some Linux 
distributions use. As of the time of this writing, this is how you can install 
it:

   svn --force export http://apt-cyg.googlecode.com/svn/trunk/ /usr/local/bin/
   chmod +x /usr/local/bin/apt-cyg

If you're using the 64-bit Cygwin platform, then, after installing apt-cyg, you
will need to make a couple of simple modifications to it. Using your favourite
text editor, and remembering that the actual line numbers within your version
may differ from those quoted below, edit /usr/local/bin/apt-cyg and make the
following changes:

1) On line 98, change "$mirror/setup.bz2" to "$mirror/x86_64/setup.bz2".
2) On line 105, change "$mirror/setup.ini" to "$mirror/x86_64/setup.ini".

To search for a package, you can do:

   apt-cyg find pattern

To install a package, you can do:

   apt-cyg install name

For full details, you can do:

   apt-cyg help

------------------------------------------------------------------------------


USB Support
===========

USB devices are supported thanks to the libusb-win32 or libusb-1.0
packages. If both are installed, preferrence is given to libusb-1.0.

Pre-built versions of brltty have USB support compiled in, and the required
drivers are shipped, you just need to let the installer set them up.

In order to build BRLTTY yourself with USB support enabled, _before_ compiling
BRLTTY, you need to install at least one of libusb-win32 or libusb-1.0.

At the time of this writing, libusb-win32 binaries can be found on
[http://libusb-win32.sourceforge.net/]. The file will be called something
like "libusb-win32-bin-<version>.exe", and should be available on
[http://sourceforge.net/project/showfiles.php?group_id=78138].
Unpack it in some place.

As of the time of this writing, the libusb-1.0 binary snapshots can be found on
[http://www.libusb.org/wiki/windows_backend]. The file will be called something
like "libusb_<date>.7z". Unpack it in some place.

The Cygwin or MinGW toolchain then needs to get aware of the presence of
libusb-win32 or libusb1.0-devel.

For Cygwin:

* Just install the libusb-win32 or libusb1.0-devel package.

For MinGW:

  For libusb-win32:

    Symlink the header and library files into MinGW installation, run:

       +  ln -s "/path/to/LibUSB-Win32/include/lusb0_usb.h" /mingw/include/usb.h
       +  ln -s "/path/to/LibUSB-Win32/lib/gcc/libusb.a" /mingw/lib/
       +  ln -s "/path/to/LibUSB-Win32/bin/x86/libusb0_x86.dll" /mingw/bin/libusb0.dll

    Then you can configure, compile, install, and run BRLTTY as usual.
  
  For libusb-1.0:

    1) Symlink the header and library files into MinGW installation, run:

       + ln -s "/path/to/Libusb-1.0/include/libusb-1.0" /mingw/include/
       + ln -s "/path/to/Libusb-1.0/MinGW32/dll/libusb-1.0.dll.a" /mingw/lib/
       + ln -s "/path/to/Libusb-1.0/MinGW32/dll/libusb-1.0.dll" /mingw/bin/

    2) Copy the file libusb-1.0.pc in the Windows/ subdirectory of BRLTTY's
       source tree into MinGW's /mingw/lib/pkgconfig/ directory. If the
       pkgconfig/ subdirectory doesn't already exist then create it.

    Then you can configure, compile, install, and run BRLTTY as usual.

To actually be able to use the libusb-win32 driver, you need to copy the
runtime files in the brltty source.

   +  cp "/path/to/LibUSB-Win32/bin/x86/libusb0.sys" brltty/hotplug/libusb0.sys
   +  cp "/path/to/LibUSB-Win32/bin/x86/libusb0_x86.dll" brltty/hotplug/libusb0.dll
   +  cp "/path/to/LibUSB-Win32/bin/amd64/libusb0.sys" brltty/hotplug/libusb0_x64.sys
   +  cp "/path/to/LibUSB-Win32/bin/amd64/libusb0.dll" brltty/hotplug/libusb0_x64.dll

and then right-click on brltty/hotplug/brltty.inf and select install, or on
braille device plug, point at the brltty/hotplug/brltty.inf file.

To actually be able to use the libusb-1.0 driver, right-click on
brltty/hotplug/brltty-libusb-1.0.inf and select install, or on braille
device plug, point at the brltty/hotplug/brltty-libusb-1.0.inf file.

------------------------------------------------------------------------------


Configuring BRLTTY
==================

Some of BRLTTY's configure options are of particular interest to users of the 
Windows platform:

--enable-relocatable-install: The default is for BRLTTY to refer to its
components via absolute paths. On the Windows platform, however, the convention
is for a package to use relative paths so that it can be installed into an
arbitrary directory and so that it can be moved around thereafter as well. This
option builds BRLTTY such that relative paths are used.

------------------------------------------------------------------------------


Missing Java Class Definitions on Cygwin
========================================

You may get a Java failure which looks like this:

   Exception in thread "main" java.lang.NoClassDefFoundError:
   org.eclipse.jdt.internal.compiler.batch.GCCMain
      at gnu.java.lang.MainThread.run(Unknown Source)
   Caused by: java.lang.ClassNotFoundException:
   org.eclipse.jdt.internal.compiler.batch.GCCMain
   not found in gnu.gcj.runtime.SystemClassLoader
   {urls=[], parent=gnu.gcj.runtime.ExtensionClassLoader{urls=[], parent=null}}

This problem occurs when the java-ecj package isn't installed. It can
be obtained from Cygwin Ports. You can also resolve the probem by
downloading the file "ftp://sourceware.org/pub/java/ecj-4.5.jar", and
installing it into "/usr/share/java/ecj.jar".

------------------------------------------------------------------------------


Sticking to a console
=====================

It may be useful to have BRLTTY only review the console it is started in, i.e. 
for it not to follow the keyboard focus. To achieve this, set the FollowFocus 
parameter of the Windows screen driver to no. This can be done either on the 
command line (-XFollowFocus=no) or in brltty.conf (screen-parameter 
FollowFocus=no).

------------------------------------------------------------------------------


Sharing the Braille Display with Other Screen Readers
=====================================================

When you're not on a window which BRLTTY can handle its default action is to
retain control of the braille display and to present a brief message explaining
the problem. If you have another braille-capable screen reader and would like
it to take over instead then both BRLTTY and that other screen reader must be
instructed to share the braille display.

BRLTTY can be instructed to share the braille display via its --release-device
option; the short form of this option is -r. When this option is in effect
BRLTTY releases the braille display when you move onto a window which it cannot
handle and tries to regain control of the braille display when you move onto a
window which it can handle. Note that these actions take a noticeable amount of
time so you should only use this option if it's actually needed.

------------------------------------------------------------------------------


Sharing BRLTTY with JAWS
========================

A common case wherein a JAWS user might want BRLTTY to be in control of the
braille display is when using Cygwin.

There are two phases to configuring JAWS to run in the background while BRLTTY
controls the braille display. First, the window title must be established and
stable. Second, JAWS braille must be put to sleep.

What is a window title?
-----------------------

Every window in Windows has a title bar that contains the name of the
application which is running in it as well as some controls to do things like
move and resize it. BRLTTY does not show this title bar.

For a program window, JAWS uses the name of the program's executable as the
name of the configuration files to load when that program gains focus. For a
console application such as Cygwin, however, it uses the title of the window
instead. We must, therefore, tell JAWS within the window title that this is a
Cygwin window.

Setting the Window Title
------------------------

JAWS uses one of the words in the window title as the name of the configuration
files to load. This file set is what tells JAWS the specifics of how to handle
the application. It is, therefore, where JAWS must be instructed to put its
braille component to sleep.

At this writing, it appears that JAWS uses the following algorithm for choosing
which word in the title to use as the name of the file set:
1) If there are no slashes (/) or backslashes (\) in the title then JAWS uses 
   the first word. Thus, if the title is "Cygwin Bash Shell" then JAWS will 
   load the Cygwin configuration files.
2) If there is at least one slash (/) or backslash (\) in the title then JAWS 
   uses the last word. Thus, if the title is "$PWD - Cygwin" then JAWS will 
   similarly load the Cygwin configuration files.

Setting Cygwin's Window Title
-----------------------------

First, it is imperative that you replace, or at least modify, the default PS1
(primary shell prompt) setting. The default for this setting, as distributed by
Cygwin, places $PWD (the path to the current working directory) in the window
title, thus requiring you to have a separate JAWS configuration for every
directory on the system! One possible way to resolve this problem is to
uncomment the `settitle' function which can be found near the end of `.bashrc'.
This function allows you to place a string of your own choice in the title. You
can use this function, therefore, as follows:

   export PROMPT_COMMAND='settitle "$PWD - Cygwin"'
   export PS1='$ '

The first of these lines causes the window title to be set just before each
shell prompt. Since $PWD always contains at least one slash (/), the operative
word is `Cygwin' (the last word), and JAWS will load any Cygwin configuration
files that it finds. The second of these lines sets the primary shell prompt to
the customary dollar sign ($). More importantly, though, it replaces Cygwin's
default PS1 setting which contains escape sequences that overwrite the window
title with just $PWD thus not presenting any permanent text for JAWS to
recognize.

Putting JAWS Braille to Sleep
-----------------------------

Now that a stable window title has been established, JAWS braille can finally
be put to sleep. While in Cygwin and with BRLTTY not running, do the following:
1) Press Insert+F2 to bring up the Run JAWS Manager dialog.
2) Down-Arrow to Configuration Manager and press Enter. Verify that the title 
   on the top line contains "Cygwin.jcf".
3) Press Alt+S for Set Options.
4) Press B for Braille.
5) Press S for Braille Sleep Mode.
6) Verify that the box is checked (it should look like <x> instead of < >). 
   Press Space to toggle the setting if the x isn't there.
7) Press Enter to leave the menu.
8) Press Control+S to save the file.
9) Press Alt+F4 to exit the configuration manager.

Putting JAWS Speech to Sleep
----------------------------

If you want to use JAWS speech in Windows but not in Cygwin, you can do the
following:

1) Press Insert+F2 to bring up the Run JAWS Manager dialog.
2) Down-Arrow to Configuration Manager and press Enter. Verify that the title 
   on the top line contains "Cygwin.jcf".
3) Press Alt+S for Set Options.
4) Press A for Advanced.
5) You should be on an item labelled "Sleep Mode Enable" with an empty check
   box (< >). Press Space to check it (<x>). 
6) Press Enter to leave the menu.
7) Press Control+S to save the file.
8) Press Alt+F4 to exit the configuration manager.

Performance
-----------

You'll always be able to switch to Cygwin, and BRLTTY, if running, will take
control of the braille display automatically. Switching back to Windows and
JAWS may be a bit more problematic, though ... the degree of success seems to
depend on the type of braille display being used. Sometimes it works properly.
Sometimes, with a USB display, the cable must be unplugged/replugged to allow
JAWS to regain control. In extreme cases you may need to exit BRLTTY before
going to Windows.

------------------------------------------------------------------------------


Building the Installer and the Archive
======================================

The mkwin script, which can be found in the Windows/ subdirectory of BRLTTY's 
source tree, builds the installer and the archive for BRLTTY. It assumes that
the following software components have already been installed:

- MinGW [32-bit] (from http://mingw.org/). The following MinGW packages should
  be installed:
  * mingw32-pdcurses
  * mingw32-pthreads-w32
  * msys-bison
  * msys-dos2unix
  * msys-groff
  * msys-m4
  * msys-zip
- AutoHotkey (from http://www.autohotkey.com/). The mkwin script assumes that
  it has been installed in C:\Program Files\AutoHotkey. The -A (AutoHotkey)
  option can be used to specify another location.
- NSIS (from http://nsis.sourceforge.net/). The mkwin script assumes that it
  has been installed in C:\Program Files\NSIS. The -N (NSIS) option can be used
  to specify another location.
- Python (from www.python.org). The 32-bit variants are required. Version 2 or
  3 may be used. If the python command is not in your command search path, or
  if you would like to use a different version of Python, then use the -P
  (Python) option to specify the top-level directory of the desired Python
  version.
- Cython (from http://cython.org/). A corresponding version of Cython must be
  installed for each version of Python. Each Cython version is installed within
  the corresponding Python version's hierarchy.
- LibUSB-Win32 (from http://libusb-win32.sourceforge.net/). The mkwin script
  assumes that it has been installed in C:\LibUSB-Win32. The -U (LibUSB-Win32)
  option can be used to specify another location.
- LibUSB-1.0 (from http://www.libusb.org/wiki/windows_backend). The mkwin
  script assumes that it has been installed in C:\LibUSB-1.0. The -X (libusbx)
  option can be used to specify another location.
- WinUSB (from http://www.libusb.org/wiki/windows_backend). The mkwin script
  assumes that it has been installed in C:\WinUSB. The -W (WinUSB) option can
  be used to specify another location.
- ICU (from http://icu-project.org/). The mkwin script assumes that it has been
  installed in C:\ICU. The -I (ICU) option can be used to specify another
  location. The archive's only top-level directory is named icu, so unpack it
  when in MinGW's /c directory. Since Windows file systems are not case
  sensitive, renaming it from icu to ICU is optional.
- pkg-config (from http://gtk.org/download/win32.php). Its archive should be
  unpacked when in MinGW's /mingw directory.
- Glib (from http://gtk.org/download/win32.php). Its archive should be unpacked
  when in MinGW's /mingw directory.
- gettext-runtime (from http://gtk.org/download/win32.php). Its archive should
  be unpacked when in MinGW's /mingw directory. Only install it if your MinGW
  installation does not already have it. Check for the presence of a libintl
  DLL in MinGW's /mingw/bin directory.

The mkwin script uses the lib command, which belongs to MSVC (Microsoft Visual 
C++). On newer Windows systems, MSVC has become a component of Microsoft Visual 
Studio. If you do not have it then you will need to get the following files 
from someone who does:
- lib.exe
- link.exe
- mspdb100.dll
- msvcr100.dll
All of these files should be placed in the same directory. Either add this
directory to your command search path or use the -M (MSVC) option to specify
its location.

Use the -u (USB) option to specify which USB package is to be used. The
following packages are supported:
- libusb (for LibUSB-Win32). This is the default.
- libusb-1.0 (for LibUSB-1.0 + WinUSB).

The mkwin script requires two parameters:
1) The path to the top-level directory of BRLTTY's source tree. It may be
   either relative or absolute.
2) The build revision. It may be any character sequence which does not include
   white space. It is appended, with a prepended dash (-), to BRLTTY's version
   number in order to construct the build version.

The build name is used as:
- the file name of the installer (which has the extension .exe)
- the file name of the archive (which has the extension .zip)
- the name of the top-level directory within the archive
It has the following form:

   brltty-win-buildVersion-usbPackage

For example: If your current working directory is the Windows/ subdirectory of 
BRLTTY's source tree, if the current BRLTTY version is 5.2, and remembering
that the default USB package is libusb, then invoking the following command:

   ./mkwin .. 4

will create these files within the current working directory:
- brltty-win-5.2-4-libusb.exe (the installer)
- brltty-win-5.2-4-libusb.zip (the archive)

Use the -s (shell) option if you would like an interactive shell to be invoked
just before the archive is created so that you can have a look at and/or modify
what it will contain. If the SHELL environment variable is set then that shell
is used. If not, /bin/sh is assumed.

Use the -v (verbose) option to increase output verbosity, and/or the -q (quiet)
option to decrease output verbosity. These two options are complementary, and
both are cumulative - each may be specified any number of times.

Use the -t (temporary) option to explicitly specify the temporary directory 
which is to be used for the build. It must not already exist. If you do not 
specify it then an internally generated path is used.

Use the -k (keep) option to prevent the temporary directory from being removed 
at the end of a successful build.

Use the -h (help) option to view a brief command line usage summary.


------------------------------------------------------------------------------
