Abstract

Ths document contains hints for installing GNU APL under Windows 11.

Introduction

GNU APL has to be compiled from the GNU APL source code (in directory src). Many system functions of GNU APL depend on external libraries that may or may not be installed on the user’s machine. The ./configure script of GNU APL determins which of these libraries are present on the user’s machine and compiles and links GNU APL accordingly. The multitude of avilable or not available libraries on a Windows machine makes it unfeasible to generate a single binary GNU APL version that accommodates all possible combinations of libraries.

On the GNU/Linux operating system, compiling GNU APL is relatively easy. The requirements of GNU APL on its environment - the display of APL characters on the screen and the generation of APL characters by the keyboard - are already satisfied by almost all modern GNU/Linux distribution and the missing pieces can easily be added via the package manager of the linux distribution.

Even for the latest Windows version - Windows 11 as of this writing - the situation is more complicated. When it comes to APL, Windows 11 still has limitations that make the installation of GNU APL on Windows more complicated than on GNU/Linux. On Windows 11 the user needs to fetch different components from different places on the internet. Under GNU/Linux the display of APL characters works out-of-the box and the generation of APL characters on the keyboard can be dome with typically a single configurastion file (shipped with GNU APL; see file README-3-keyboard and directory support-files). On Windows the user has to install a suitable APL font to display APL characters and a keyboard mapping for the keyboard. While installing an APL font is relatively easy, the installation of a keyboard mapping has become more and more difficult form one Windows version to the next. In older Windows versions one could "hack" the Windows registry to make Windows produce APL characters with the keyboard, but this does not work anymore under Windows 11. Microsoft provides alternatives like the Keyboard Manager in their PowerTools, or the Input Mode Editor (IME), but both seem not to work for terminal applications like GNU APL. To adress this issue, GNU APL comes with a built-in keyboard mapper that allows the user to toggle the keyboard between ASCII and APL.

Top-level Installation Procedure

A full installation of GNU APL on Windows 11 requires essentially 3 sub-installations:

  1. Installation of a development environment (compiler, linker, make),

  2. Installation of an APL font. This step is needed for the WSL environment, but not for Cygwin.

  3. Installation of a keyboard mapping. This step is needed for the WSL environment, but not for Cygwin.

These 3 sub-installations are independent of each other and the third is somewhat optional (and likely to fail).

Installation of a development environment

GNU APL is a standard C++ program. In theory there are 3 development environments that could be used to compile GNU APL:

  1. A native Microsoft C++ compiler (Visual Studio, Visual C++, etc.), or

  2. the Cygwin Environment, or

  3. the Microsoft WSL (aka. Windows Subsystem for Linux) Environment.

The author has tested all these environments with the following results.

  1. The Microsoft C++ compiler failed completely. The compiler emitted thousands of warnings and errors, most of them bogus. The sheer amount of warnings made it impossible to get GNU APL compiled with a native C++ compiler under Windows.

  2. The Cygwin environment works well these days. There was a short period when GNU APL had problems being compiled in Cygwin, but these problems seem to no longer exists. Whether the problems were related to the Windows version or to the Cygwin versio is not known.

  3. The WSL environment also works quite well. Some things that work in Cygwin out-of-the-box need to be fixed in WSL, in particular the APL font and the keyboard mapping.

So the user has to choose between Cygwin and WSL. In the arguable opinion of the author:

  1. WSL seems to be a little more lightweight than Cygwin. If the user has already installed one of them then she should go for it.

  2. Cygwin is a little harder to install than WSL. Also, the addition of packages is a little more cumbersome in Cygwin than in WSL.

  3. Cygwin is fine-grained and lets you choose the version of each package that you install. WSL coarse-grained and lets you only choose the GNU/Linux distribution that it tries to emulate. After that it is up to the package manager of the chosen distribution to handle package versions.

  4. On the other hand seems Cygwin to be a little closer to GNU/Linux than WSL. In particular the fonts shipped with Cygwin support APL out-of-the-box while in WSL they need to be installed and enabled in the terminal emulator in which GNU APL runs.

  5. In older Windows and/or Cygwin versions the usual keyboard mapping programs like xmodmap or compxkb also worked out-of-the-box. In the current Windows 11/Cygwin they do not. For example, xmodmap reports an error xmodmap: unable to open display. xmodmap and compxkb also fail in WSL. The reason might be the same (lack of an X server).

  6. Interestingly, WSL lets you choose the GNU/Linux version that it emulates. But then the same GNU/Linux version that works fine on a true GNU/Linux version fails under WSL. IOW WSL seems to be somewhat half-hearted

Cygwin Installation

  1. Visit https://cygwin.org/ and follow the steps under Installing Cygwin. Make sure that you enable the placement of icons on your desktop so that you do not need to search for them later on.

  2. Then open the Cygwin setup program and install the following packages:

    1. subversion (for fetching the GNU APL sources)

    2. make (for building GNU APL).

    3. g (the C compiler for compiling and linking GNU APL)

WSL Installation

  1. Open the Windows Command Prompt (i.e. cmd.exe) and enter wsl --install. That should install the WSL.

  2. Enter bash. That should enter the WSL environment.

  3. Install the tools needed for fetching and compiling GNU APL:

    1. apt install subversion # for fetching the GNU APL source code

    2. apt install make # for building GNU APL

    3. apt install g++ # for compiling and linking GNU APL

  4. Close the Windows Command Prompt: exit.

After having installed WSL, GNU APL can be compiled as usual:

  1. Open the Windows Command Prompt (cmd.exe) and enter bash. That should enter the WSL.

    1. svn co http://svn.savannah.gnu.org/svn/apl/trunk apl-2.0 # fetch GNU APL

    2. cd apl-2.0

    3. ./configure ALT_MAP_WANTED=1

    4. make

    5. make install

Installation of an APL font

This step is only needed for WSL and not for Cygwin.

The installation of an APL font is the simplest step. The APL vendor Dyalog offers suitable APL fonts for download.

  1. Visit https://www.dyalog.com/apl-font-keyboard.htmC.

  2. On that page click on the APL385 font (which downloads a file named setup-fonts.msi). This file is a microsoft installer.

  3. In your Downloads directory, execute the setuo-fonts.msi file. This installs a file named Apl385.ttf. This is a True-type font.

  4. Right-click on that Apl385.ttf file and press install.

Later on you will run GNU APL in a Windows shell such as cmd.exe. The installed font must be enabled in that shall to be operational.

Installation of a keyboard mapping

At this point you have a working GNU APL interpreter. What is missing is a way to interactively enter APL characters. What should already work at this point is:

  1. Copying APL characters (^C and ^V). If you start GNU APL and enter the command ]KEYB then you should get the display of a keyboard layout that you could copy from (with ^C) and then paste into the GNU APL window (with ^V).

  2. Running APL scripts or workspaces. The )LOAD, )COPY, and OFF commands need no APL characters and can therefore be entered even if no APL keyboard mapping is installed.

  3. Last but not least there is the built-in ASCII-to-APL mapping of GNU APL which is decribed in more detail gurther down.

There are a number of different options that you can choose from. Many of them work only on true GNU/Linux systems, though. GNU APL is shipped with a separate file README-3-keyboard that discusses some of the methods. The author has spent quite some time to find a method that works reliably under Windows 11, but to no avail.

Keyboard mappings in Windows 11 are, simply speaking, a mess. The author has tried the following.

  1. The Keyboard Manager (which is a component in the PowerTools) offered by Microsoft free of charge. One can indeed map keys to APL characters with the Keyboard Manager. However, the mapping works in some Micorsoft applications, but not in others. When the Keyboard Manager is running (and if tan APL font is installed and selected) then you can edit APL scripts in Microsoft’s Notepad, but if you open Microsoft’s Windows Command Prompt cmd.exe in another window then the mapping provided by the Keyboard Manager does not apply in that window.

  2. Microsoft provides a thing called Input Method Editor (IME) that should provide arbitrary keyboard mappings. In dact there are hundreds of such mappings provided by Microsoft, but none of them is suitable for APL. The IMEs are not configurable in any way, so if you need Chinese characters then you are fine because Microsoft provides a Chinese IME, but for APL you are out of luck. Also there are several defailed instruction how to add IMEs under Windows 11 on the internet, but all of them fail in the first or second step because the Windows 11 of the author was different from the Windows 11 in these instructions. The instructions referred to items in the Windows 11 Control Panel that simply did not exist.

  3. Dyalog (a prominent APL vendor) offers an IME for APL. However, the author (who is using an original Dyalog keyboard with APL caps) was not able to make it work under Windows 11. The IME installs without any error messages on Windows 11. According to Dyalog’s installation instructions, after running the installer for that IME (and rebooting the machine) that IME was supposed to show up in the Windows registry, but it did not. As a consequence, no key was mapped to APL.

  4. There are a number keyboard mappers offered on the internet, both commercial and free ones. The author has not tried any of those because most looked like mere convenience front-ends to Windows 11 components above that did not work. If a GNU APL user should find a mapping that works with GNU APL then please report that to the mailing list bug-apl@gnu.org!

The GNU APL Built-in ASCII to APL Mapper

As a consequence of all the failed attempts to find a working keyboard mapping outside of GNU ASPL (where it belongs) the author vaguely remembered how APL characters were entered in the 1970s. At that time keyboards had no ALT keys. Instead, some keyboards could be switched between an ASCII mode and an APL mode with the ASCII control characters SI and SO (aka, ^O and \^N). One of them (the author has forgotten which in the meantime) would select the ASCII mode (and all subsequently typed characters were ASCII characters) and the other would select the APL mode (not to be confused with the APL overstrike method of that time) which would operate in parallel when in APL mode). Technically speaking these mappings were made in the keyboard driver of the operating systenm and not in the keyboards themselves.

The built-in ASCII to APL mapper of GNU APL has adopted this old mechanism as follows:

  1. Typing \^A, i.e. holding down the CRTL key and typing A, will map the next character typed to APL, and

  2. Typing ^N will map all subsequent characters typed to APL (until \^N is typed again.

The built-in ASCII to APL mapper of GNU APL is disabled by default because all platforms other than Windows 11 have no problems generating APL characters. To enable the mapper one has to ./configure GNU APL with the option ALT_MAP_WANTED=1 as it was done in the examples above. The parameter 1 of ALT_MAP_WANTED=1 specifies a mapping profile to be used; the mapping profile to be used, where the profile defines the control codes (^A and \^N for profile 1) and the details of the mapping (map r to ⍴, i to ⍳, …). Currently two such profiles are defined:

  1. ALT_MAP_WANTED=0 (or omitting the ALT_MAP_WANTED option disables the mapper.

  2. ALT_MAP_WANTED=1 maps an US-keyboard to the standard GNU APL keyboard layout (which, by chance is also the layout of the Dyalog US keyboard).

Unlike in Windows 11 (which is closed source and prevents the user from defining her own layout), GNU APL is free software that allows the user to modify it to suit her needs. To construct your own mapping, have a look at file src/src/LineInput.cc and search for all occurences of cfg_ALT_MAP_WANTED.