[BRLTTY] Installing brltty on the Mac

Fri Oct 30 16:42:35 EDT 2015

I have known for quite a while that there should be a README that explains installing brltty on the Mac. Several years ago, when Dave worked to get brltty up and going on the Mac for the first time, I did such a document. The reason I have not done a new document is that there are so many variables. Which version of Mac OS is being run? Is Macports or Homebrew or some other package manager being used? Is the install going to be done in /usr/local or in the home directory? Does the person have experience with finding and compiling packages? Because of all of these variables, I have several times started to write something and have left the task unfinished.

Here I am simply going to explain how to install brltty and screen and get them up and running. I am running Mac OS 10.11 El capitan though I also have a 10.10 Yosemite installation. If you follow these instructions on your computer and have problems, please post to the list and somebody will help you deal with the specifics.

I almost always install brltty using the git repository and using the development version of brltty. No matter what you do, you must have the source for brltty available because you have to patch in order to run screen. For information about using git to obtain and manage brltty, go to

http://www.brltty.com/download.html#repository 
and read and follow those instructions. I usually place my source in /usr/local/src (I had to create the src folder) but doing this will probably mean you need to use the sudo command to compile and install packages. When you use sudo, you are asked for your password; this will only work if you are using and administrative account or have access to an administrative account and password; you cannot use sudo with a guest or standard account password.

Once you have downloaded from the repository, you must run the following:

./autogen

./configure (or ./cfg-darwin can be run)

make

make install
If needed, sudo should precede each of these commands.

It appears that in Mac OS 10.11 El Capitan the brltty executable cannot be installed in /bin. I have worked around this by running my ./configure or ./cfg-darwin with --prefix=/usr/local. This puts everything in /usr/local and the executable is in /usr/local/bin. This isn't the only option that could be used but it is what I am doing at present.

Working in terminal without brltty isn't the most user-friendly process on the Mac because voiceover doesn't necessarily tell you everything that has happened and finding your place in the compile information as it comes out can be confusing. If you already are running brltty on the Mac, of course you can do your upgrades and new installs using brltty. Another solution, if you have a linux machine running brltty, is to ssh into your Mac and compile and install that way. It isn't impossible to do with voiceover on the Mac but I find it more difficult even using a braille display with Apple's braille.

When you have brltty installed successfully, you cannot run it yet. First you must install screen. Brltty isn't able to tap into the Mac screen so it is necessary to use brltty within terminal using screen.

While there is a version of screen on the Mac, you must compile screen from source in order to patch it to work with brltty. There are currently two versions of screen that have patches for this purpose: 4.0.1 and 4.2.1. Probably you should download 4.2.1 since it is the later of the two versions and since 4.0.1 may no longer be available. This can be found at

screen-4.2.1.tar.gz <http://ftp.gnu.org/gnu/screen/screen-4.2.1.tar.gz>

Using this link should automatically download the file to Downloads on your Mac or whatever folder you have specified for downloads but if you have problems with this you can go to
http://ftp.gnu.org/gnu/screen/ <http://ftp.gnu.org/gnu/screen/>

and find the file. Using ctrl-option-shift-m on the file will bring up a menu and one of the choices is to download the linked file. Usually in downloading Mac OS will open it to a .tar file instead of a .tar.gz file.

Place the file in the folder where you want to open it; I usually use /usr/local/src as I stated above. Then do

sudo tar xvf
and the name of the file. If it is still a tar.gz file you would do
tar zxvf

Again, you will probably have to use the sudo command to do this.

Once this is done, cd into the folder. Now you need to apply the patch before you can compile. From inside the screen-4.2.1 folder, do

patch -p0 <
and then the path to the brlttyy patch. In my case this would be

sudo patch -p0 </usr/local/src/brltty/Patches/screen-4.2.1.patch

Notice that there is no space between the less than sign and the path.

Note that in this same folder there is a txt file called screen-4.0.1.txt. While it is for screen-4.0.1 it explains much of what i have written here and gives a brief explanation of what the screen program does.

When the patch has been applied, you can compile and install screen. I recommend installing in /usr/local unless you have a package manager such as homebrew or macports and want to install in those locations. Otherwise there can be conflicts with Mac OS's screen program which is located in /usr/bin.

./configure --prefix=/usr/local (though the default may be /usr/local)
make
make install

There is one more step I usually do though I don't know for sure if it is necessary any longer. I do:

chmod u-s /usr/local/bin/screen

Now you are ready to run brltty. First you must start screen. You will want to use the path so that Mac's screen program does not start instead.

/usr/local/bin/screen

Then you must turn voiceover off. and start brltty. I have not covered running brltty.conf or using command-line parameters here. Since i have set up my brltty.conf, I type

brltty

If everything is set up correctly, brltty should start.

nNote, though I have not always included sudo in front of commands, be aware that you may need to use sudo.

This has been a quick write-up which may be plenty for the experienced Unix user who has compiled and installed other programs but this is not meant to be definitive. Post to the list if you have questions and feel free to correct any mistakes I have made or obvious omissions.

-- 
Cheryl

May the words of my mouth
and the meditation of my heart
be acceptable to You, Lord,
my rock and my Redeemer.
(Psalm 19:14 HCSB)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mielke.cc/pipermail/brltty/attachments/20151030/4702028b/attachment.html>