| 1 |
|
| 2 |
// vim: et:ts=4:sw=4 |
| 3 |
|
| 4 |
= GNU APL on Windows 11 |
| 5 |
:toc: |
| 6 |
:toclevels: 4 |
| 7 |
|
| 8 |
== Abstract |
| 9 |
|
| 10 |
Ths document contains hints for installing GNU APL under Windows 11. |
| 11 |
|
| 12 |
== Introduction |
| 13 |
|
| 14 |
GNU APL has to be compiled from the GNU APL source code (in directory *src*). |
| 15 |
Many system functions of GNU APL depend on external libraries that may |
| 16 |
or may not be installed on the user's machine. The *./configure* script of |
| 17 |
GNU APL determins which of these libraries are present on the user's machine |
| 18 |
and compiles and links GNU APL accordingly. The multitude of avilable or not |
| 19 |
available libraries on a Windows machine makes it unfeasible to generate a |
| 20 |
single binary GNU APL version that accommodates all possible combinations of |
| 21 |
libraries. |
| 22 |
|
| 23 |
On the GNU/Linux operating system, compiling GNU APL is relatively easy. The |
| 24 |
requirements of GNU APL on its environment - the display of APL characters |
| 25 |
on the screen and the generation of APL characters by the keyboard - are |
| 26 |
already satisfied by almost all modern GNU/Linux distribution and the missing |
| 27 |
pieces can easily be added via the package manager of the linux distribution. |
| 28 |
|
| 29 |
Even for the latest Windows version - Windows 11 as of this writing - |
| 30 |
the situation is more complicated. When it comes to APL, Windows 11 still has |
| 31 |
limitations that make the installation of GNU APL on Windows more complicated |
| 32 |
than on GNU/Linux. On Windows 11 the user needs to fetch different components |
| 33 |
from different places on the internet. Under GNU/Linux the display of APL |
| 34 |
characters works out-of-the box and the generation of APL characters on the |
| 35 |
keyboard can be dome with typically a single configurastion file |
| 36 |
(shipped with GNU APL; see file *README-3-keyboard* and directory |
| 37 |
*support-files*). On Windows the user has to install a suitable APL font to |
| 38 |
display APL characters and a keyboard mapping for the keyboard. While |
| 39 |
installing an APL font is relatively easy, the installation of a keyboard |
| 40 |
mapping has become more and more difficult form one Windows version to the |
| 41 |
next. In older Windows versions one could "hack" the Windows registry to make |
| 42 |
Windows produce APL characters with the keyboard, but this does not work |
| 43 |
anymore under Windows 11. Microsoft provides alternatives like the Keyboard |
| 44 |
Manager in their PowerTools, or the Input Mode Editor (IME), but both seem |
| 45 |
not to work for terminal applications like GNU APL. To adress this issue, GNU |
| 46 |
APL comes with a built-in keyboard mapper that allows the user to toggle the |
| 47 |
keyboard between ASCII and APL. |
| 48 |
|
| 49 |
== Top-level Installation Procedure |
| 50 |
|
| 51 |
A full installation of GNU APL on Windows 11 requires essentially 3 |
| 52 |
sub-installations: |
| 53 |
|
| 54 |
. Installation of a development environment (compiler, linker, make), |
| 55 |
. Installation of an APL font. This step is needed for the WSL environment, |
| 56 |
but not for Cygwin. |
| 57 |
. Installation of a keyboard mapping. This step is needed for the WSL |
| 58 |
environment, but not for Cygwin. |
| 59 |
|
| 60 |
These 3 sub-installations are independent of each other and the third is |
| 61 |
somewhat optional (and likely to fail). |
| 62 |
|
| 63 |
=== Installation of a development environment |
| 64 |
|
| 65 |
GNU APL is a standard C++ program. In theory there are 3 development |
| 66 |
environments that could be used to compile GNU APL: |
| 67 |
|
| 68 |
. A native Microsoft C\++ compiler (Visual Studio, Visual C++, etc.), or |
| 69 |
. the *Cygwin* Environment, or |
| 70 |
. the Microsoft *WSL* (aka. **W**indows **S**ubsystem for **L**inux) |
| 71 |
Environment. |
| 72 |
|
| 73 |
The author has tested all these environments with the following results. |
| 74 |
|
| 75 |
. The Microsoft C\++ compiler failed completely. The compiler emitted thousands |
| 76 |
of warnings and errors, most of them bogus. The sheer amount of warnings |
| 77 |
made it impossible to get GNU APL compiled with a native C++ compiler under |
| 78 |
Windows. |
| 79 |
|
| 80 |
. The *Cygwin* environment works well these days. There was a short period |
| 81 |
when GNU APL had problems being compiled in Cygwin, but these problems seem |
| 82 |
to no longer exists. Whether the problems were related to the Windows |
| 83 |
version or to the Cygwin versio is not known. |
| 84 |
|
| 85 |
. The *WSL* environment also works quite well. Some things that work in |
| 86 |
*Cygwin* out-of-the-box need to be fixed in *WSL*, in particular the APL |
| 87 |
font and the keyboard mapping. |
| 88 |
|
| 89 |
So the user has to choose between *Cygwin* and *WSL*. In the arguable |
| 90 |
opinion of the author: |
| 91 |
|
| 92 |
. *WSL* seems to be a little more lightweight than *Cygwin*. If the user has |
| 93 |
already installed one of them then she should go for it. |
| 94 |
|
| 95 |
. *Cygwin* is a little harder to install than *WSL*. Also, the addition of |
| 96 |
packages is a little more cumbersome in *Cygwin* than in *WSL*. |
| 97 |
|
| 98 |
. *Cygwin* is fine-grained and lets you choose the version of each package |
| 99 |
that you install. *WSL* coarse-grained and lets you only choose the |
| 100 |
GNU/Linux distribution that it tries to emulate. After that it is up to |
| 101 |
the package manager of the chosen distribution to handle package versions. |
| 102 |
|
| 103 |
. On the other hand seems *Cygwin* to be a little closer to GNU/Linux than |
| 104 |
*WSL*. In particular the fonts shipped with *Cygwin* support APL |
| 105 |
out-of-the-box while in *WSL* they need to be installed and enabled in the |
| 106 |
terminal emulator in which GNU APL runs. |
| 107 |
|
| 108 |
. In older Windows and/or *Cygwin* versions the usual keyboard mapping |
| 109 |
programs like *xmodmap* or *compxkb* also worked out-of-the-box. In the |
| 110 |
current Windows 11/*Cygwin* they do not. For example, *xmodmap* reports |
| 111 |
an error _xmodmap: unable to open display_. *xmodmap* and *compxkb* also |
| 112 |
fail in *WSL*. The reason might be the same (lack of an X server). |
| 113 |
|
| 114 |
. Interestingly, *WSL* lets you choose the GNU/Linux version that it emulates. |
| 115 |
But then the same GNU/Linux version that works fine on a true GNU/Linux |
| 116 |
version fails under *WSL*. IOW *WSL* seems to be somewhat half-hearted |
| 117 |
|
| 118 |
==== Cygwin Installation |
| 119 |
|
| 120 |
. Visit https://cygwin.org/ and follow the steps under _Installing Cygwin_. |
| 121 |
Make sure that you enable the placement of icons on your desktop so that |
| 122 |
you do not need to search for them later on. |
| 123 |
|
| 124 |
. Then open the *Cygwin* setup program and install the following packages: |
| 125 |
.. *subversion* (for fetching the GNU APL sources) |
| 126 |
.. *make* (for building GNU APL). |
| 127 |
.. *g++* (the C++ compiler for compiling and linking GNU APL) |
| 128 |
|
| 129 |
==== WSL Installation |
| 130 |
|
| 131 |
. Open the Windows Command Prompt (i.e. *cmd.exe*) and enter *wsl --install*. |
| 132 |
That should install the *WSL*. |
| 133 |
. Enter *bash*. That should enter the *WSL* environment. |
| 134 |
. Install the tools needed for fetching and compiling GNU APL: |
| 135 |
.. *apt install subversion* # for fetching the GNU APL source code |
| 136 |
.. *apt install make* # for building GNU APL |
| 137 |
.. *apt install g++* # for compiling and linking GNU APL |
| 138 |
. Close the Windows Command Prompt: *exit*. |
| 139 |
|
| 140 |
After having installed *WSL*, GNU APL can be compiled as usual: |
| 141 |
|
| 142 |
. Open the Windows Command Prompt (*cmd.exe*) and enter *bash*. |
| 143 |
That should enter the *WSL*. |
| 144 |
.. *svn co http://svn.savannah.gnu.org/svn/apl/trunk apl-2.0* # fetch GNU APL |
| 145 |
.. *cd apl-2.0* |
| 146 |
.. *./configure ALT_MAP_WANTED=1* |
| 147 |
.. *make* |
| 148 |
.. *make install* |
| 149 |
|
| 150 |
=== Installation of an APL font |
| 151 |
|
| 152 |
This step is only needed for *WSL* and not for *Cygwin*. |
| 153 |
|
| 154 |
The installation of an APL font is the simplest step. The APL vendor Dyalog |
| 155 |
offers suitable APL fonts for download. |
| 156 |
|
| 157 |
. Visit https://www.dyalog.com/apl-font-keyboard.htmC. |
| 158 |
. On that page click on the *APL385* font (which downloads a file |
| 159 |
named *setup-fonts.msi*). This file is a microsoft installer. |
| 160 |
|
| 161 |
. In your *Downloads* directory, execute the *setuo-fonts.msi* file. This |
| 162 |
installs a file named *Apl385.ttf*. This is a True-type font. |
| 163 |
. Right-click on that *Apl385.ttf* file and press *install*. |
| 164 |
|
| 165 |
Later on you will run GNU APL in a Windows shell such as *cmd.exe*. The |
| 166 |
installed font must be enabled in that shall to be operational. |
| 167 |
|
| 168 |
=== Installation of a keyboard mapping |
| 169 |
|
| 170 |
At this point you have a working GNU APL interpreter. What is missing is |
| 171 |
a way to interactively enter APL characters. What should already work at |
| 172 |
this point is: |
| 173 |
|
| 174 |
. Copying APL characters (\^C and \^V). If you start GNU APL and enter |
| 175 |
the command *]KEYB* then you should get the display of a keyboard |
| 176 |
layout that you could copy from (with \^C) and then paste into the |
| 177 |
GNU APL window (with ^V). |
| 178 |
. Running APL scripts or workspaces. The *)LOAD*, *)COPY*, and *OFF* |
| 179 |
commands need no APL characters and can therefore be entered even if no |
| 180 |
APL keyboard mapping is installed. |
| 181 |
. Last but not least there is the built-in ASCII-to-APL mapping of GNU APL |
| 182 |
which is decribed in more detail gurther down. |
| 183 |
|
| 184 |
There are a number of different options that you can choose from. Many |
| 185 |
of them work only on true GNU/Linux systems, though. GNU APL is shipped with |
| 186 |
a separate file *README-3-keyboard* that discusses some of the methods. |
| 187 |
The author has spent quite some time to find a method that works reliably |
| 188 |
under Windows 11, but to no avail. |
| 189 |
|
| 190 |
Keyboard mappings in Windows 11 are, simply speaking, a mess. The author |
| 191 |
has tried the following. |
| 192 |
|
| 193 |
. The *Keyboard Manager* (which is a component in the *PowerTools*) offered |
| 194 |
by Microsoft free of charge. One can indeed map keys to APL characters |
| 195 |
with the *Keyboard Manager*. However, the mapping works in some Micorsoft |
| 196 |
applications, but not in others. When the *Keyboard Manager* is running |
| 197 |
(and if tan APL font is installed and selected) then you can edit APL |
| 198 |
scripts in Microsoft's *Notepad*, but if you open Microsoft's Windows |
| 199 |
Command Prompt *cmd.exe* in another window then the mapping provided by |
| 200 |
the *Keyboard Manager* does not apply in that window. |
| 201 |
|
| 202 |
. Microsoft provides a thing called *Input Method Editor* (*IME*) that should |
| 203 |
provide arbitrary keyboard mappings. In dact there are hundreds of such |
| 204 |
mappings provided by Microsoft, but none of them is suitable for APL. |
| 205 |
The IMEs are not configurable in any way, so if you need Chinese characters |
| 206 |
then you are fine because Microsoft provides a Chinese IME, but for APL |
| 207 |
you are out of luck. Also there are several defailed instruction how to |
| 208 |
add IMEs under Windows 11 on the internet, but all of them fail in the first |
| 209 |
or second step because the Windows 11 of the author was different from the |
| 210 |
Windows 11 in these instructions. The instructions referred to items |
| 211 |
in the Windows 11 *Control Panel* that simply did not exist. |
| 212 |
|
| 213 |
. Dyalog (a prominent APL vendor) offers an IME for APL. However, the author |
| 214 |
(who is using an original Dyalog keyboard with APL caps) was not able to |
| 215 |
make it work under Windows 11. The IME installs without any error messages |
| 216 |
on Windows 11. According to Dyalog's installation instructions, after |
| 217 |
running the installer for that IME (and rebooting the machine) that IME |
| 218 |
was supposed to show up in the Windows registry, but it did not. As a |
| 219 |
consequence, no key was mapped to APL. |
| 220 |
|
| 221 |
. There are a number keyboard mappers offered on the internet, both commercial |
| 222 |
and free ones. The author has not tried any of those because most looked |
| 223 |
like mere convenience front-ends to Windows 11 components above that did |
| 224 |
not work. If a GNU APL user should find a mapping that works with GNU APL |
| 225 |
then please report that to the mailing list [email protected]! |
| 226 |
|
| 227 |
|
| 228 |
=== The GNU APL Built-in ASCII to APL Mapper |
| 229 |
|
| 230 |
As a consequence of all the failed attempts to find a working keyboard |
| 231 |
mapping outside of GNU ASPL (where it belongs) the author vaguely |
| 232 |
remembered how APL characters were entered in the 1970s. At that time |
| 233 |
keyboards had no *ALT* keys. Instead, some keyboards could be switched |
| 234 |
between an ASCII mode and an APL mode with the ASCII control characters |
| 235 |
*SI* and *SO* (aka, \^O and \^N). One of them (the author has forgotten |
| 236 |
which in the meantime) would select the ASCII mode (and all subsequently |
| 237 |
typed characters were ASCII characters) and the other would select the |
| 238 |
APL mode (not to be confused with the APL overstrike method of that time) |
| 239 |
which would operate in parallel when in APL mode). Technically speaking |
| 240 |
these mappings were made in the keyboard driver of the operating systenm |
| 241 |
and not in the keyboards themselves. |
| 242 |
|
| 243 |
The built-in ASCII to APL mapper of GNU APL has adopted this old mechanism |
| 244 |
as follows: |
| 245 |
|
| 246 |
. Typing \^A, i.e. holding down the CRTL key and typing A, will map the |
| 247 |
next character typed to APL, and |
| 248 |
. Typing \^N will map all subsequent characters typed to APL (until |
| 249 |
\^N is typed again. |
| 250 |
|
| 251 |
The built-in ASCII to APL mapper of GNU APL is disabled by default because |
| 252 |
all platforms other than Windows 11 have no problems generating APL |
| 253 |
characters. To enable the mapper one has to *./configure* GNU APL with |
| 254 |
the option *ALT_MAP_WANTED=1* as it was done in the examples above. |
| 255 |
The parameter *1* of *ALT_MAP_WANTED=1* specifies a mapping profile |
| 256 |
to be used; the mapping profile to be used, where the profile defines |
| 257 |
the control codes (\^A and \^N for profile 1) and the details of the |
| 258 |
mapping (map *r* to *⍴*, i to *⍳*, ...). Currently two such profiles |
| 259 |
are defined: |
| 260 |
|
| 261 |
. *ALT_MAP_WANTED=0* (or omitting the *ALT_MAP_WANTED* option disables |
| 262 |
the mapper. |
| 263 |
. *ALT_MAP_WANTED=1* maps an US-keyboard to the standard GNU APL keyboard |
| 264 |
layout (which, by chance is also the layout of the Dyalog US keyboard). |
| 265 |
|
| 266 |
Unlike in Windows 11 (which is closed source and prevents the user from |
| 267 |
defining her own layout), GNU APL is free software that allows the user |
| 268 |
to modify it to suit her needs. To construct your own mapping, |
| 269 |
have a look at file *src/src/LineInput.cc* and search for all occurences of |
| 270 |
*cfg_ALT_MAP_WANTED*. |
| 271 |
|