Documents/README.OpenBSD

~~~~~~~~~~~~~~~~~
BRLTTY on OpenBSD
~~~~~~~~~~~~~~~~~
:Author: Mario Lang <mlang@delysid.org>

.. include:: prologue.rst

This document describes how to get BRLTTY working on a recent OpenBSD system.
It assumes that you're working with a recent OpenBSD installation (e.g. 3.4).

Setting up BRLTTY
=================

Patching ``screen``
-------------------

Since OpenBSD doesn't have a way for user-space applications to access the
contents of the virtual consoles, we have to use ``screen`` to make this
information available to BRLTTY. This also means that you can't use BRLTTY with
the OpenBSD virtual consoles directly - you must start ``screen`` first on some
virtual terminal in order to be able to use BRLTTY.

You need to patch ``screen`` to enable the ``IPC_SHARED_IMAGE`` functionality
that BRLTTY relies on. Assuming your ports tree is in ``/usr/ports``, you'll
need to copy the appropriate patch from ``brltty/Patches`` into
``/usr/ports/misc/screen/patches``.

OpenBSD 3.4 comes with screen-4.0.1. You can check the ``screen`` version by
looking in ``/usr/ports/misc/screen/Makefile``.

The patch file should be named with the prefix ``patch-`` so that the
``screen`` build process will find it.

Now change into ``/usr/ports/misc/screen`` and run::

   make
   sudo make install

If you've successfully managed to compile and install the ``screen`` package,
you can proceed to building BRLTTY.

There's a simple test you can use to verify if your ``screen`` installation
does support the ``IPC_SHARED_IMAGE`` feature. Start ``screen``, and then
execute the command::

   ipcs -m

You should see output that looks roughly like this::

   Shared Memory:
   T       ID     KEY        MODE       OWNER    GROUP
   m    65536 -1160968401 --rwa------     root     root

If you do, then ``screen`` seems to have been compiled with the
``IPC_SHARED_IMAGE`` feature.

Note that proper integration of the ``IPC_SHARED_IMAGE`` functionality via an
additional "flavor" for the ``screen`` port has recently been submitted to the
OpenBSD ports mailing list. If you're working with the CVS ports tree, it might
be worthwhile to check if the ``shm`` flavor has already been checked in by
invoking the following command when in ``/usr/ports/misc/screen``::

   make show=FLAVORS

If you see ``shm`` listed as a choosable flavor, simply build ``screen`` with
the ``FLAVOR`` environment variable set to ``shm`` - don't bother copying the
patch from BRLTTY's source tree.

Compiling BRLTTY
================

To compile BRLTTY, do the following::

   ./configure
   gmake
   sudo gmake install

Note that ``gmake`` should be used in order to avoid a problem related to BSD
and GNU Make incompatibilities.

Running BRLTTY
==============

You need to have ``screen`` started before you try to run BRLTTY. Inside
``screen``, simply invoke BRLTTY as you would on other systems. Note that the
first serial port is ``/dev/cua00``.

A typical invocation could look like this::

   brltty -b ts -d serial:cua00