Abstract

This 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 determines which of these libraries are present on the user’s machine and compiles and links GNU APL accordingly. The multitude of available 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. On Windows the user has to install a suitable APL font to display APL characters and have a way to enter them from the keyboard. Both are handled by the Windows installer: it installs the GNU_APL font and provides built-in Right Alt (AltGr) keyboard support directly in apl.exe. Pressing Right Alt + key produces the corresponding APL character, so no additional keyboard software needs to be installed.

Two Ways to Get GNU APL on Windows

There are two distinct paths to GNU APL on Windows, depending on whether you just want to use it or want to build it yourself:

GNU APL on Windows: which path do you need?
│
├─ Build it yourself
│  │
│  ▼
│  ┌─────────────────────────────────────────────┐
│  │ Fetch the source from Savannah (svn or git) │
│  └─────────────────────────────────────────────┘
│  │
│  ▼
│  ./configure --with-mingw && make && make install
│  (cross-compiles apl.exe from Linux; see "For developers" below)
│
└─ Run a pre-built copy (no build tools needed)
   │
   ▼
   ┌──────────────────────────────────────┐
   │ Fetch an installer from a GNU mirror │
   └──────────────────────────────────────┘
   │
   ├─ Need everything (apl.exe + font + library directories)
   │  │
   │  ▼
   │  GNU_APL_2_0_Setup.exe   (the full installer)
   │
   └─ Already have apl.exe, just need the font
      │
      ▼
      GNU_APL_Font_Setup.exe   (GUI installer), or
      install_GNU_APL_font.bat (no-GUI script)

For Windows users: install a pre-built release

If you only want to run GNU APL and do not need to compile it yourself, fetch a pre-built installer from a GNU mirror (the canonical location is https://ftp.gnu.org/gnu/apl/; see https://www.gnu.org/prep/ftp.html for the full mirror list). Two installers are provided:

  1. GNU_APL_2_0_Setup.exe - the full installer (the 2.0 is the GNU APL version, so that installers for different releases can coexist on the mirror). It installs apl.exe, the library directory structure (workspaces and wslib1 to wslib5), the default preferences file, and the GNU_APL font, all under %USERPROFILE%\gnu-apl.d. No administrator rights are required.

  2. GNU_APL_Font_Setup.exe - installs only the GNU_APL font. Use this one instead of the full installer if you already have an apl.exe from elsewhere (e.g. copied from another machine, or built yourself) and just need the font.

Note
 As explained in the Introduction above, apl.exe is built against whatever optional libraries happen to be available in the (cross-) compilation environment used to build it. The pre-built apl.exe on the GNU mirror is unlikely to have been linked against all of them, so some ⎕-functions that depend on an optional library - for example ⎕SQL (needs SQLite/PostgreSQL), ⎕GTK and ⎕PLOT (need GTK), or ⎕FFT (needs FFTW) - may not be available in it, even though the same functions work fine in a GNU/Linux build where those libraries are routinely installed. If you need one of these, you will have to build GNU APL yourself with that library available; see "For developers" below.

The full installer creates a GNU APL shortcut in the Start Menu that launches apl.exe with its working directory set to the install location. This matters: apl.exe currently looks for its library directories (workspaces, wslib1, etc.) relative to its current working directory, not relative to the location of the .exe file itself, so launching apl.exe directly from a different working directory will not find them.

The GNU_APL font installer can also be fetched directly from the GNU Savannah Subversion repository with a plain web browser, without needing an SVN or git client:

http://svn.savannah.gnu.org/viewvc/apl/trunk

Look under support-files/fonts/ for the font installer (NOTE: like any public server, this one occasionally returns a temporary error - e.g. a 503 - under heavy load; if that happens, just retry later or use the GNU mirror above instead).

For developers: build from source

If you want to modify GNU APL, or simply prefer to build it yourself, fetch the sources from Savannah (Subversion is preferred; Git is also available) and build as usual:

svn co http://svn.savannah.gnu.org/svn/apl/trunk apl-2.0

or

git clone https://git.savannah.gnu.org/git/apl.git apl-2.0

then:

cd apl-2.0
./configure
make
make install

This is the same procedure used on GNU/Linux, and is also what you would use to build and run GNU APL on Windows itself (via Cygwin or WSL); see the rest of this document for the additional steps needed for that.

To instead cross-compile a native Windows apl.exe from a GNU/Linux machine (e.g. to produce the pre-built binary mentioned above), use --with-mingw instead of a plain ./configure:

./configure --with-mingw
make

This presets the MinGW-w64 cross-compiler (x86_64-w64-mingw32-g++) and related flags, and disables libraries that are impractical to cross-compile (e.g. SQLite/PostgreSQL, hence no ⎕SQL - see the NOTE above). make install does not apply when cross-compiling; the build just leaves a working src/apl.exe. To turn that into a release artifact for the GNU mirror, use one of:

  1. make -C src windows-release - copies apl.exe to apl-2.0.exe (the 2.0 is the GNU APL version, so that mirrored binaries from different releases do not overwrite each other).

  2. make windows-installer (run from the top-level source directory, after placing the cross-compiled apl.exe into support-files/windows-installer/) - packages apl.exe together with the font and library directories into GNU_APL_2_0_Setup.exe, see the top-level Makefile.am for details.

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 (the pre-built apl.exe already has Right Alt keyboard support built in, so no separate keyboard mapping step is needed when using the installer).

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 exist. Whether the problems were related to the Windows version or to the Cygwin version 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 is 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, Cygwin seems 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 recommended font for GNU APL on Windows is GNU_APL, a TrueType font covering all APL characters in their standard Unicode positions. It is a derivative of the open-source BQN386 Unicode font (originally designed for the BQN programming language; see support-files/fonts/COPYRIGHT_NOTICE for attribution and licensing) with added glyphs (e.g. ∈ and ⊗) and fixed display-width bugs for several characters that rendered too wide in the Windows console with the original font.

Step 1: Install the font

Use one of the two GNU_APL font installers described in "Two Ways to Get GNU APL on Windows" above (GNU_APL_Font_Setup.exe or install_GNU_APL_font.bat). Both install the font for the current user only, without requiring administrator privileges.

Step 2: Register the font for use in the Windows console

Windows only allows a short pre-approved list of fonts in the cmd.exe font picker. GNU_APL must be added to a registry key before it appears there (the font installers above do not do this automatically). This step requires administrator privileges.

Note
 The Console\TrueTypeFont registry key often does not exist on a fresh Windows installation. The reg add command below creates it automatically if it is absent.

Open a Command Prompt as administrator (search for cmd, right-click → Run as administrator) and run:

reg add "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Console\TrueTypeFont" /v 0 /t REG_SZ /d "GNU_APL" /f

Step 3: Select the font in cmd.exe

  1. Open a cmd.exe window (Win+R → type cmd → Enter).

  2. Right-click the title bar and choose Properties.

  3. Select the Font tab.

  4. In the font list, choose GNU_APL.

  5. Choose a size large enough to distinguish APL characters - 14pt is the minimum for that, 18pt is more comfortable.

  6. Click OK.

To make the selection permanent for all future cmd.exe windows, use Defaults instead of Properties in step 2, or when prompted choose Modify shortcut that started this window.

Note
 An index of alternative APL fonts (in case GNU_APL does not suit your needs) is maintained at https://sigapl.org/fonts/FontsIndex.php

Installation of a keyboard mapping

At this point you have a working GNU APL interpreter. APL characters can be entered in several ways:

  1. Right Alt + key (the primary method in the pre-built apl.exe). The Right Alt key (sometimes labelled AltGr on European keyboards) is used as the APL shift key. Holding Right Alt and pressing a letter or punctuation key produces the corresponding APL character. For example, Right Alt + r gives ⍴, Right Alt + i gives ⍳, and so on. The layout follows the standard GNU APL keyboard (see ]KEYB inside APL). This mapping is built into apl.exe itself and requires no additional software or administrator rights.

  2. Copying and pasting APL characters (Ctrl+C / Ctrl+V). The command ]KEYB inside APL displays the keyboard layout; you can copy characters from it. The command ]AV prints the entire APL character set (⎕AV) and is useful for characters not shown by ]KEYB.

  3. Running APL scripts or workspaces. The )LOAD, )COPY, and OFF commands need no APL characters and work without any keyboard mapping.

  4. The built-in Ctrl+O / Ctrl+N mapper (secondary method, described below).

The GNU APL Built-in ASCII to APL Mapper

In addition to the Right Alt mapping above, GNU APL provides a second mechanism based on ASCII control characters, recalling how APL characters were entered on 1970s terminals:

  1. Typing ^O (Windows) or ^A (Linux/macOS) maps the next character typed to APL.

  2. Typing ^N toggles a permanent APL mode: all subsequent characters are mapped to APL until ^N is typed again.

Note
 On Windows, ^O is used as the single-character trigger instead of ^A, because the Windows 10/11 console intercepts ^A as "select all" before GNU APL sees it.

Both the Right Alt mapping and the ^O/^N mapper are enabled in the pre-built apl.exe (compiled with ALT_MAP_WANTED=1). They use profile 1, which maps a US keyboard to the standard GNU APL layout (map r to ⍴, i to ⍳, and so on). To build with a different profile or to define your own mapping, see src/LineInput.cc and search for cfg_ALT_MAP_WANTED.

When building from source, enable the mapper with:

./configure ALT_MAP_WANTED=1

Appendix A: Building the Windows Installer

This appendix is for GNU APL maintainers who need to cross-compile the Windows installer on a Linux host using MinGW.

The build uses two SVN working copies side by side:

  • LEFT window: ~/apl-2.0/ — source edits, SVN commits

  • RIGHT window: ~/mingw-apl/ — MinGW cross-compilation, installer build

The binary is cross-compiled in the RIGHT window. The workspace library and NSIS script live in the LEFT window. make windows-release in the RIGHT window drives the whole process.

apl.exe links statically against libgcc/libstdc++ but requires libwinpthread-1.dll at runtime (bundled by the installer). Windows system DLLs (KERNEL32, WS2_32, msvcrt) are always present.

Step 1 — Commit changes (LEFT window, only when code was changed)

Step 2 — Update and reconfigure (RIGHT window, only after Step 1)

ALT_MAP_WANTED=1 enables the ^O (map next char) / ^N (toggle map-all) APL keyboard input shortcuts.

The two sed lines fix libtool 2.4.6 cross-compilation bugs:

  1. The lt-wrapper template does not include <process.h>/<io.h> for \__MINGW32__ (only for _MSC_VER), causing _P_WAIT undeclared errors.

  2. The wrapper is compiled with $LTCC (native gcc) instead of $CC (the cross-compiler), so Windows-specific headers are not found.

Both must be re-applied after every ./configure run.

Step 3 — Force relink (RIGHT window, only after configure changes)

make only relinks when source files change, not when linker flags change. Removing src/.libs/apl.exe forces the full libtool link step; without it libtool may skip relinking and src/apl-2.0.exe (the file copied into the installer) will never be created. Skip this step if only APL workspace files were edited.

Step 4 — Build the installer (RIGHT window)

This does everything automatically:

  • compiles src/apl.exe and src/apl-2.0.exe

  • copies src/apl-2.0.exe into support-files/windows-installer/

  • stages workspaces, runs makensis, and copies the finished installer here as GNU_APL_2_0_Setup.exe

Step 5 — Transfer and test (Windows)

Copy ~/mingw-apl/GNU_APL_2_0_Setup.exe to Windows and run it. The installer requires no administrator rights and installs to %USERPROFILE%\gnu-apl.d\.

Quick smoke test in the APL session:

)lib should list wslib1 through wslib9; )copy 3 meta tests the library path via wslib3/meta.apl; the last line reads back system variables.