Documents/README.Windows

~~~~~~~~~~~~~~~~~
BRLTTY on Windows
~~~~~~~~~~~~~~~~~

.. include:: prologue.rst
.. _Cygwin's Web Site: http://www.cygwin.com/
.. _MinGW's Web Site: http://mingw.sourceforge.net/
.. _LibUSB-Win32's Web Site: http://libusb-win32.sourceforge.net/
.. _LibUSB-1.0's Web Site: http://www.libusb.org/wiki/windows_backend
.. _Cygwin Ports: http://cygwinports.org/
.. _Cygwin java-ecj jar: ftp://sourceware.org/pub/java/ecj-4.5.jar

Building BRLTTY
===============

System Requirements
-------------------

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

Pre-built versions of BRLTTY are available for download on
`BRLTTY's Web Site`_. Their names begin with ``brltty-win-``. Those with the
``.zip`` extension are archives, and those with the ``.exe`` extension are
installers.

In order to build BRLTTY yourself from a prepared source tarball, you'll need
Cygwin (see `Cygwin's Web Site`_) and/or MinGW (see `MinGW's Web Site`_).
You'll 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 prepared source tarballs) then you'll also need these packages:

*  autoconf
*  tcltk

If you'd like to prepare the documentation (by doing ``make`` within the
``Documents/`` subdirectory) then you'll need these packages:

*  linuxdoc-tools (not pre-packaged in Cygwin)
*  doxygen

If you're using MSYS (the MinGW command shell) for running ``configure`` and
``make``, you should always use Windows-like paths (e.g. ``c:/brltty``) rather
than MSYS paths (e.g. ``/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 console that you're currently using as you switch between them.
This isn't possible on earlier versions. One way to still achieve this
functionality, though, is to run one BRLTTY on the root window that directly
accesses your braille device, and another one on each console that indirectly
accesses your braille device via BrlAPI. This scheme may sound complicated,
but it can be set up to run automatically.

The first (or root) BRLTTY should be run as part of Windows startup. It must be
run with the options that are necessary for it to access your braille device,
e.g. ``-b`` (to specify the driver), ``-d`` (to specify the device), and
(maybe) ``-B`` (to specify driver-sspecific parameters). It must also be given
the ``-Xroot=yes`` option (which attaches it to the root window).

An additional BRLTTY must then be run for each new console. 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 (non-root) BRLTTYs can be started automatically by, for example, invoking
them from your ``.bashrc`` script. Each of these BRLTTYs only reviews the
console it's running within, and connects, via BrlAPI, to the root BRLTTY in
order to access your braille device.

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
that starts 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.

Package Management via the Command Line
---------------------------------------

Managing Cygwin Packages
~~~~~~~~~~~~~~~~~~~~~~~~

A convenient way to manage Cygwin packages from the command line
is to use the ``apt-cyg`` command.
It's 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'll 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 shown 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:

.. parsed-literal:: apt-cyg find *pattern*

To install a package, you can do:

.. parsed-literal:: apt-cyg install *name*

For full details, you can do:

.. parsed-literal:: apt-cyg help

Managing MinGW Packages
~~~~~~~~~~~~~~~~~~~~~~~

A convenient way to manage MinGW packages from the command line
is to use the ``mingw-get`` command.
Be sure to invoke it with arguments because
when invoked with no arguments its graphical interface is used.

To list all of the packages, you can do:

.. parsed-literal:: mingw-get list

To install a package, you can do:

.. parsed-literal:: mingw-get install *name*

For full details, you can do:

.. parsed-literal:: mingw-get -h

USB Support
-----------

USB devices are supported thanks to the ``LibUSB-Win32`` and the ``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
Windows drivers are also included, so you just need to let the installer set
them up.

In order to build BRLTTY yourself with USB support enabled, you'll need to
**first** install at least one of LibUSB-Win32 or LibUSB-1.0.

LibUSB-Win32
~~~~~~~~~~~~

At the time of this writing, LibUSB-Win32 binaries can be found on
`LibUSB-Win32's Web Site`_. They'll be named something like
``libusb-win32-bin-<version>.exe``, and should be available on
``http://sourceforge.net/project/showfiles.php?group_id=78138``.

*  On Cygwin:

   1) Install the ``libusb-win32`` package.

*  On MinGW:

   1) Unpack the archive somewhere.

   2) Symlink the header and library files into your MinGW
      installation::

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

In order to be able to use the LibUSB-Win32 driver, you'll need to copy its
run-time files into BRLTTY's source tree::

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

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

LibUSB-1.0
~~~~~~~~~~

As of the time of this writing, LibUSB-1.0 binary snapshots can be found on
`LibUSB-1.0's Web Site`_. They'll be named something like
``libusb_<date>.7z``.

*  On Cygwin:

   1) Install the ``libusb1.0-devel`` package.

*  On MinGW:

   1) Unpack the archive somewhere.

   2) Symlink the header and library files into your MinGW
      installation::

         ln -s LibUSB-1.0/include/libusbx-1.0 /mingw/include/libusb-1.0
         ln -s LibUSB-1.0/MinGW32/dll/libusb-1.0.dll.a /mingw/lib/
         ln -s LibUSB-1.0/MinGW32/dll/libusb-1.0.dll /mingw/bin/

   3) 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.

In order to be able to use the LibUSB-1.0 driver, you'll need to either
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 a BRLTTY Build
--------------------------

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's entirely self-contained. This enables it to be
   installed into an arbitrary directory, and to be moved around thereafter at
   well. This option builds BRLTTY such that relative paths are used.

Missing Java Class Definitions on Cygwin
----------------------------------------

You may get a Java failure that looks something 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 `Cygwin java-ecj jar`_, and installing it into ``/usr/share/java/ecj.jar``.

Using BRLTTY
============

Windows Scripts for Managing BRLTTY
-----------------------------------

These ``.bat`` scripts are in the top-level folder where BRLTTY has been installed.
They should be run by a user that has administrative privileges.

``run-brltty.bat``
~~~~~~~~~~~~~~~~~~

Manually run BRLTTY with a log level of ``info``.
Logs are written to the file ``brltty.log``
in the top-level folder where BRLTTY has been installed.
All arguments are passed through to BRLTTY.

``debug-brltty.bat``
~~~~~~~~~~~~~~~~~~~~

Manually run BRLTTY, via the ``run-brltty.bat`` script, with options that
set the log level to ``debug`` and enable several useful log categories.
All arguments are passed through to the ``run-brltty.bat`` script.

``kill-brltty.bat``
~~~~~~~~~~~~~~~~~~~

Forceably terminate the manually-run BRLTTY process.

``enable-brlapi.bat``
~~~~~~~~~~~~~~~~~~~~~~

Install the BrlAPI service and start it.

``disable-brlapi.bat``
~~~~~~~~~~~~~~~~~~~~~~~~

Stop the BrlAPI service and uninstall it.

Sticking to a Console
---------------------

It may be useful to have BRLTTY only review the console that it's started in,
i.e.  for it not to follow the keyboard focus. To achieve this, set the
``FollowFocus`` parameter of BRLTTY's ``Windows`` screen driver to ``no``. This
can be done:

On the Command Line:
   ``-Xwn:FollowFocus=no``

In ``brltty.conf``:
   ``screen-parameter wn:FollowFocus=no``

Sharing the Braille Device with Other Screen Readers
----------------------------------------------------

When you're not on a window that BRLTTY can handle, its default action is to
retain control of the braille device and to present a short 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 device.

BRLTTY can be instructed to share the braille device via its
``--release-device`` option (the short form of this option is ``-r``). When
this option is in effect, BRLTTY releases the braille device when you move onto
a window that it can't handle, and then tries to regain control of the braille
device when you move onto a window that 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 with JAWS
~~~~~~~~~~~~~~~~~

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

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

.. topic:: What is a Window Title?

   Every window in Windows has a title bar that contains the name of the
   application that's running in it, as well as some controls to do things like
   move and resize the window. BRLTTY doesn't 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. You must, therefore, tell JAWS within the window title that this is
   a Cygwin window.

.. topic:: Setting the Window Title

   JAWS uses one of the words in the window title as the name of the
   configuration file set 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.

   As of 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 file set.

   2) If there's 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 file set.

.. topic:: 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 in the title will be ``Cygwin`` (the last word), and JAWS,
   therefore, 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, because it contains escape sequences that overwrite
   the title with ``$PWD``, renders the window unrecognizable by JAWS.

.. topic:: 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>`` (rather than
      like ``< >``). 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.

.. topic:: Putting JAWS Speech to Sleep

   If you'd like 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.

.. topic:: Known Problem

   You'll always be able to switch to Cygwin, and BRLTTY (if it's running) will
   take control of the braille device automatically. Switching back to Windows
   and JAWS, however, may be problematic. The degree of success seems to depend
   on the type of braille device being used. It usually works properly.
   Sometimes, however, when using a USB device, the cable needs to be
   unplugged/replugged to allow JAWS to regain control. In extreme cases, you
   may need to exit BRLTTY before going to Windows.

MinGW Scripts for Building BRLTTY
=================================

The ``mkwin`` Script
--------------------

The ``mkwin`` script,
which can be found in the ``Windows/`` subdirectory of BRLTTY's source tree,
builds the Windows archive and installer for BRLTTY.

Software Components Required by ``mkwin``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Links to the pages where we found these
installers, components, and files are listed.
In case any of these links becomes out-of-date, however,
copies of some of them have been preserived at
`<http://BRLTTY.app/archive/Windows/>`_.

The following software components should already be installed:

*  ``MinGW`` [32-bit] (from `<http://mingw.org/>`_)

The following ``MinGW`` packages may still need to be installed:

*  ``msys-bison``
*  ``msys-dos2unix``
*  ``msys-groff``
*  ``msys-m4``
*  ``msys-tar``
*  ``msys-unzip``
*  ``msys-wget``
*  ``msys-zip``
*  ``mingw32-libpdcurses``
*  ``mingw32-pthreads-w32``
*  ``mingw32-tcl``

The following packages should also be installed:

*  ``AutoHotkey`` (from `<http://www.autohotkey.com/>`_)

   The ``mkwin`` script assumes that it has been installed in
   ``C:\Program Files (x86)\AutoHotkey``.
   The ``-A`` (AutoHotkey) option can be used to specify another location.
   The installer currently being used is named ``AutoHotkey104805_Install.exe``.

*  ``NSIS`` (from `<http://nsis.sourceforge.net/>`_)

   The ``mkwin`` script assumes that it has been installed in
   ``C:\Program Files (x86)\NSIS``.
   The ``-N`` (NSIS) option can be used to specify another location.
   The installer currently being used is named ``nsis-3.0b0-setup.exe``.

*  ``Python`` (from `<http://www.python.org/>`_)

   The 32-bit variants are required. Version 2 or 3 may be used. If the
   ``python`` command isn't in your command search path, or if you'd 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. Install ``Cython`` with the command::

      pip install cython

   Some systems, either in addition to or in place of the ``pip`` command,
   have the ``pip2`` and/or the ``pip3`` command. As you might have guessed,
   ``pip2`` corresponds to ``Python2`` and ``pip3`` corresponds to ``Python3``.
   It's best to use the one with the most explicit version suffix.

   If the ``pip`` command isn't already included within  the version of
   ``Python`` that you're using (usually within its ``scripts`` subdirectory)
   then you can install it from `<https://pip.pypa.io/en/stable/installing/>`_.

   Copies of the files mentioned below are at
   `<http://BRLTTY.app/archive/Windows/Cython/>`_:

   +  To force use of MinGW's (rather than Microsoft's) C compiler,
      add ``distutils.cfg`` to the ``Python/lib/distutils/`` directory.
      It should contain these lines::

         [build]
         compiler = mingw32

   +  If you get a message like "Unknown MS Compiler version 1900"
      then you'll probably need to apply the patch ``patch1``
      (from `<https://bugs.python.org/file40608/patch.diff>`_)
      when within the ``Python/lib/distutils/`` directory::

         cd Python/lib/distutils
         patch patch1

   +  If you get a message like "cannot find -lvcruntime140"
      then you'll need to add the 32-bit version of ``vcruntime140.dll``
      (from `<http://www.dll-files.com/>`_)
      to the ``Python/libs/`` directory.
      You can verify that you have the 32-bit version with the ``file`` command::

         file vcruntime140.dll
         vcruntime140.dll: PE32 executable (DLL) (console) Intel 80386, for MS Windows

      A message like "vcruntime140.dll: file not recognized: File format not recognized"
      probably means that you don't have the 32-bit version of the DLL.

*  ``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.
   The archive currently being used is named ``libusb-win32-bin-1.2.6.0.zip``.
   Our copy of this archive has a top-level directory named ``libusb-win32-bin-1.2.6.0``.

*  ``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.
   The archive currently being used is named ``libusbx-1.0.18-win.7z``.
   Our copy of this archive doesn't have a top-level directory.
   We have an alternate copy of this archive named ``libusbx-1.0.18-win.tar.gz``.

*  ``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.
   The archive currently being used is named ``winusb.zip``.
   Our copy of this archive doesn't have a top-level directory.

*  ``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 currently being used is named ``icu4c-53_1-Win32-msvc10.zip``.
   Our copy of this archive has a top-level directory named ``icu``.
   Since Windows file systems don't have case sensitive names,
   renaming it from ``icu`` to ``ICU`` is optional.

*  ``pkg-config`` (from `<http://gtk.org/download/win32.php>`_)

   The archive currently being used is named ``pkg-config_0.28-1_win32.zip``.
   Our copy of this archive doesn't have a top-level directory.
   It should be unpacked when in MinGW's ``/mingw/`` directory.

*  ``Glib`` (from `<http://gtk.org/download/win32.php>`_)

   The archive currently being used is named ``glib_2.34.3-1_win32.zip``.
   Our copy of this archive doesn't have a top-level directory.
   It should be unpacked when in MinGW's ``/mingw/`` directory.

*  ``gettext-runtime`` (from `<http://gtk.org/download/win32.php>`_)

   Only install it if your MinGW installation doesn't 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 don't have it then you'll need to get
the following files from someone who does.
Copies of them are at `<http://BRLTTY.app/archive/Windows/MSVC/>`_.

*  lib.exe
*  link.exe
*  mspdb100.dll
*  msvcr100.dll

All of them should be placed within the same directory
(MinGW's ``/usr/local/bin/`` directory may be a good place).
Either add this directory to your command search path
or use the ``-M`` (MSVC) option to specify its location.

If you'd like to have USB support then create the symbolic links as described
within the MinGW instructions for using `LibUSB-Win32`_ and/or `LibUSB-1.0`_.
You'll also need to create ``.pc`` (pkg-config) files for them within MinGW's
``/mingw/lib/pkgconfig>`` directory. The ones we've created are at
`<http://BRLTTY.app/archive/Windows/pkgconfig/>`_.

If you'd like to have Bluetooth support then you'll need to add
the files listed below to MinGW's ``/mingw/include/`` directory.
Copies of them are at `<http://BRLTTY.app/archive/Windows/Bluetooth/>`_.

*  ws2bth.h
*  bthdef.h
*  bthsdpdef.h

More ``mkwin`` Options
~~~~~~~~~~~~~~~~~~~~~~

``-u`` (USB)
   Specify which USB package is to be used. The following USB packages are
   supported:

   *  libusb (for LibUSB-Win32)
   *  libusb-1.0 (for LibUSB-1.0 + WinUSB)

``-C`` (Cygwin)
   Specify the root (top-level) directory of a Cygwin installation.
   If it isn't specified then ``/cygwin`` (if it exists) is assumed.
   Cygwin's ``bin/`` directory is added to the end of the command search path
   as a last resort for finding needed commands that MinGW may not have.

``-s`` (shell)
   Invoke an interactive shell 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.

``-t`` (temporary directory)
   Specify the temporary directory that is to be used for the build.
   It must not already exist.
   If it isn't specified then an internally generated path is used.

``-k`` (keep)
   Don't remove the temporary directory
   at the end of a successful build.
   It isn't removed if the build fails
   so that you can have a look at what went wrong.

.. include:: common-options.rst

``mkwin`` Parameters
~~~~~~~~~~~~~~~~~~~~

The ``mkwin`` script accepts two parameters:

1) The path to the top-level directory of BRLTTY's source tree.
   It may be either relative or absolute.
   This parameter is required.

2) The build revision.
   It may be any character sequence that doesn't include whitespace.
   It is appended, with a prepended dash (``-``), to
   BRLTTY's version number in order to construct the build version.
   This parameter is optional - if it isn't specified then
   the revision number part of the build identifier is used.

The build name is used as:

*  the name of the top-level directory within the archive
*  the file name of the archive (which has the ``.zip`` extension)
*  the file name of the installer (which has the ``.exe`` extension)

It has the following form::

   brltty-win-buildVersion-buildRevision-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.zip (the archive)
*  brltty-win-5.2-4-libusb.exe (the installer)

The ``winsetup`` Script
-----------------------

The ``winsetup`` script,
which can be found in the ``Windows/`` subdirectory of BRLTTY's source tree,
ensures that all needed components are installed on your system
so that `the mkwin script`_ can successfully build BRLTTY.

``winsetup`` Options
~~~~~~~~~~~~~~~~~~~~

``-a`` (archive URL)
   Specify the location for BRLTTY's Windows archive.

``-d`` (dry run)
  Don't actually install anything.

``-k`` (keep)
   Don't remove the temporary directory.

``-p`` (Python directory)
   Specify the location where Python has been installed.

``-t`` (temporary directory)
   Specify the temporary directory that is to be used for the installs.
   It must not already exist.
   If it isn't specified then an internally generated path is used.

.. include:: common-options.rst