Debian Codegraph @

HOWTOs/GNU-APL-Windows-11.asciidoc

raw
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