GNU APL

is a free version of the programming language APL and is intended to
be a full implementation of what is known as "Programming Language APL,
Extended", "APL with nested arrays", or "ISO/IEC13751".

GNU APL is distributed under the terms of the GPL, see file "COPYING"
for details.

More information about the installation of GNU APL can be found in the
following files in the same directory as this file:

INSTALL:		     general installation information (aka. ./configure)
README-1-prerequisites:      what else is needed to install GNU APL
README-2-configure:          GNU APL specific ./configure options
README-3-keyboard:           how to set up your keyboard for APL characters
README-4-compliance:         compliance information
README-5-WINDOWS:            notes for Windows users
README-6-porting:            notes for various operating systems
README-7-more-info:          some pointers to other information related to APL
README-8-parallel:           notes for parallel (multi-core) execution
README-9-post-installation:  things to do after GNU APL was installed

Before you can build GNU APL, make sure that the following
libraries/packages have been installed:

gcc/g++		from a GNU mirror (directory: gcc, file: gcc-?.?.?.tar.gz)
make		from a GNU mirror (directory: gcc, file: make-?.?.tar.gz)

If you are using Ubuntu, then the following commands may do the trick:

    apt-get install g++

For Fedora:

    dnf -y group install  "C Development Tools and Libraries"

For Centos replace dnf by yum

On Linux Mint 16 (and possibly some other GNU/Linux distributions) you may
need to install package ncurses-dev in order to uses curses functions,
for example:

    apt-get install libncurses-dev

On Linux Mint 14.1, GNU APL compiled out-of--the-box.
On Fedora 25, GNU APL compiled out-of-the-box.

GNU APL can be compiled as a Python module.
The basic build procedure is this:

    configure --with-libpython_apl [ other ./configure optionsi ...]
    make
    sudo make install

This installs a shared object file named 'libgnu_apl.so' in the place where
GNU APL installs its libraries (typically /usr/local/lib/apl or
/usr/lib/apl)

The shared object file must then be copied to the directory where Python
keeps its libraries (e.g. /usr/lib/python3.4/lib-dynload/). For example (if
your Python version is 3.4, and NOTICE THE DIFFERENT NAME OF THE .so FILE):

    sudo cp /usr/local/lib/apl/lib_gnu_apl.so \
            /usr/lib/python3.4/lib-dynload/gnu_apl.cpython-34m.so

After that, one can import GNU APL in Python and call Python functions
provided by gnu_apl:

>>> import gnu_apl
>>> gnu_apl.exec("4 4⍴1+2")
3 3 3 3
3 3 3 3
3 3 3 3
3 3 3 3
0
>>> gnu_apl.command(")WSID")
'IS CLEAR WS\n'


The output above is a mix of APL output and Python output, which is more often
than not a bad idea. A better approach is to generate no APL output (i,e, the
results of APL computations should be assigned to variables and variables ⎕
and ⍞ should not be used). Alternatively, you can change the default print
behaviour in Python with gnu_apl.set_display(mode). See, for example,
gnu_apl.help('set_display').

After a sucessful installation you can display the documentation of all Python
functions in an interactive Python session like this:

>>> import gnu_apl
>>> gnu_apl.help('all')

The GNU APL interpreter can be configured by means of ./configure options.
The standard ./configure options are described in file INSTALL in this directory.
In addition to the standard options provided by ./configure the following GNU
APL specific ./configure options are recognized. If an option is NOT given
on the ./configure command line, then either the default value for the option
is used (if the option has one), or else the behavior described below for
the option will not occur.

--with-android
   This option prevents the instantiation of CIN, COUT, and CERR. This may
   be needed when GNU APL is compiled for Android, since Android applications
   are using a different I/O model than are standard C++ programs.

--with-libapl
   This option builds GNU APL as a shared library (libapl.so) rather than an
   integrated executable. This option is often combined with option
   --with-android, and is automatically set by option --with-Eng. The
   --with-libapl option not only builds approproate Makefiles, but it also
   changes the GNU APL code in some places.


--with-sqlite3=[ARG]
   Build the native function for SQL using sqlite3. ARG may provide the
   non-default location of the sqlite3 library.

--with-postgresql=[ARG]
   Build the native function for SQL using PostgreSQL. ARG may provide the
   non-default location of the postgresql library.

ASSERT_LEVEL_WANTED=n
   There are numerous Assert() and Assert1() macros in the source code of the
   APL interpreter. These macros check more (Assert1) or less (Assert)
   obvious assumptions that throw exceptions if they turn out to be wrong.
   Like for dynamic logging, these macros have negative performance impacts
   and they can be disabled.

   By default, ASSERT_LEVEL_WANTED=1 and that disables the Assert1() macro
   and enables the Assert() macro

   ASSERT_LEVEL_WANTED=2 enables both macros.
   ASSERT_LEVEL_WANTED=1 (default) enable Assert(), but disable Assert1().
   ASSERT_LEVEL_WANTED=0 disable both macros; this gives the maximum
   performance, but at the same time bears the risk that internal errors
   of the APL interpreter are not being detected. Example:

    ./configure ASSERT_LEVEL_WANTED=2

SECURITY_LEVEL_WANTED=n
   Some capabilities of the APL intepreter can be disabled in order to improve
   the security of, for example, a web server that uses CGI scripts written
   in APL.
   SECURITY_LEVEL_WANTED=2 disables all capabilities that can be disabled
   SECURITY_LEVEL_WANTED=1 disables those capabilities that are configured in
                           one of the preferences files.
   SECURITY_LEVEL_WANTED=0 enables all capabilities. This level is the default
                           and gives the maximum performance of the interpreter.

APSERVER_TRANSPORT
APSERVER_PORT
APSERVER_PATH
   APserver is a program that is needed to support shared variables. APserver
   is started automatically and has a communication channel to every APL
   interpreter instance and to every AP started (manually or automatically
   by an APL interpreter instance). The communication channel can be TCP,
   abstract Unix domain sockets, or normal Unix domain sockets.

   1. TCP communication is the default communication channel that is also
      use when APSERVER_TRANSPORT is not ./configured. APserver listens on
      port number 16366 by default; this can be changed via APSERVER_PORT
      like this:

      ./configure APSERVER_TRANSPORT=TCP   APSERVER_PORT=40000

   2. Abstract Unix domain sockets are a GNU/linux specific variant that
      allows for sockets without a corresponding file in the file system.
      APserver listens on socket named "/tmp/GNU-APL/APserver" by default;
      the name can be changed with APSERVER_PATH like this:

      ./configure APSERVER_TRANSPORT=LINUX   APSERVER_PATH=my-APserver-path

   3. Normal Unix domain sockets are a GNU/linux specific variant that requires
      a file in the file system to work. The permissions of that file control
      which programs can connect to APserver (BUT MAY ALSO PREVENT APserver
      FROM OPERATING PROPERLY!). Due to the many different possibilities for
      the ownership and permissions for the file, GNU APL does not create the
      file but leaves that to the user. By default APserver listens on the
      socket named "/tmp/GNU-APL/APserver" (and a file with that name
      should exist before APL is started); the name can be changed with
      APSERVER_PATH like this:

      ./configure APSERVER_TRANSPORT=UNIX   APSERVER_PATH=my-APserver-path

CORE_COUNT_WANTED
   This experimental option specifies the number of CPU cores the
   intepreter is to use. The value is a number, 'all', 'argv', or 'syl'.
   The interpreter has sequential code and parallel code which is selected
    as follows:

   value    code
         0  sequential  (default, one core is used)
         1  parallel    one core is used
         N  parallel    N > 0 cores are used
   all  -1  parallel    all existing cores are being used,
   argv -2  parallel    the number of cores can be set by command line option
                        -cc N (same as all if -cc is not given).
   syl  -3  parallel    the number of cores can be changed in APL via ⎕SYL,
                        initially 1.

   Example:

   ./configure CORE_COUNT_WANTED=4


   CIN_COLOR_WANTED
  CERR_COLOR_WANTED
  COUT_COLOR_WANTED
RESET_COLORS_WANTED
   CLEAR_EOL_WANTED
   These options were used in GNU APL 1.0 to configure output coloring.
   Output coloring can now specified in GNU APL's preference file. This
   is more flexible than configuring the colors at compile time.

DYNAMIC_LOG_WANTED=yes
    The APL interpreter has more than 30 log categories. Each log category can
    be turned on or off if needed in order to troubleshoot the APL interpreter.
    There are two ways to control the logging categories: statically or
    dynamically.

    Statically means that it is decided at compile time if a log category
    shall be on or off. Dynamically means that a log category can be turned
    on and off at run-time (with the command ]LOG).

    Dynamic logging has a performance penalty since every potential log
    printout has an if () statement that checks if the log category is turned
    on or off. With static logging this if () statement has a constant value
    that will be optimized away by the C++ compiler. Dynamic logging also
    slightly increases the size of the APL interpreter.

   In both cases (static or dynamic logging), the file src/Logging.def defines
   the logging categories at start-up of the APL interpreter. If the first
   argument of the log_def() macro is 0 then the log category is initially
   disabled (and remains disabled if static logging is used); if it is 1
   then the log category is initially enabled. The default for this option
   is static logging. Example:

    ./configure DYNAMIC_LOG_WANTED=yes

CXX_WERROR=yes/no
    Do (not) add -Werror to the compiler flags. By default GNU APL is being
    compiled with -Werror, which turns compiler warnings into compiler errors
    so that the  build fails if the compiler issues warnings. However, some
    older compilers produce lots of bogus warnings that cannot be fixed in a
    reasonable way. In such cases you can, for example:

    ./configure CXX_WERROR=no

DEVELOP_WANTED
    This option enables a number of internal checks in the GNU APL interpreter
    that are useful for maintainers of GNU APL.

    Example:
    ./configure DEVELOP_WANTED=yes

MAX_RANK_WANTED=n
    Set the maximum rank of APL values to n. The default value is 8. Ranks
    smaller than 4 should be avoided. There is no performance penalty for
    increasing the max. rank, but every additional dimension takes 4-8 bytes
    of memory for every APL value (even those with a smaller rank), Example:

    ./configure MAX_RANK_WANTED=10


PRINT_SEMA_WANTED=yes
   This option is now obsolete.


VALUE_CHECK_WANTED=yes
    There is a function called check_value() that checks every new APL value
    for completeness. This check helps finding faults in the interpreter, but
    decreases the performance of the interpreter. Example:

    ./configure VALUE_CHECK_WANTED=yes

VALUE_HISTORY_WANTED=yes
    There is a macro called ADD_EVENT that records the history of APL values.
    This history helps finding faults in the interpreter, but
    decreases the performance of the interpreter. Example:

    ./configure VALUE_HISTORY_WANTED=yes


PERFORMANCE_COUNTERS_WANTED=yes
    GNU APL has some build-in counters for performace measurements. These counters
    are normally disabled, but can be enabled via this option. Example:

    ./configure PERFORMANCE_COUNTERS_WANTED=yes


VF_TRACING_WANTED=yes
   You can enable tracing of changes to value flags. This creates a lot of
   debug output and consequently has considerable performance impacts. Example:

    ./configure VF_TRACING_WANTED=yes


SHORT_VALUE_LENGTH_WANTED=12
   The interpreter distinguishes long values and short APL values. Short values
   are allocated with a single call to "new" that allocates the Shape of the
   value and its ravel. Long values allocate the value header with one call to
   "new" and then the ravel with another call to "new". Long values are
   therefore a little slower than short values. By increasing
   SHORT_VALUE_LENGTH_WANTED you get fewer new calls (and consequently better
   performance) at the cost of more memory. Example:

    ./configure SHORT_VALUE_LENGTH_WANTED=42


GPROF_WANTED=yes
   Setting GPROF_WANTED adds the flag -pg to CXXFLAGS and LDFLAGS and that
   enables support for gprof profiling of the apl interpreter. Example:

    ./configure GPROF_WANTED=yes

GCOV_WANTED=yes
   Setting GCOV_WANTED adds the flags -fprofile-arcs and -ftest-coverage flags
   to CXXFLAGS and that enables support for gcov coverage testing of the apl
   interpreter. Example:

    ./configure GCOV_WANTED=yes

VISIBLE_MARKERS_WANTED=yes
   GNU APL uses a handful of Unicode characters as internal pad characters
   when formatting its output. Normally these pad characters are in a private
   Unicode range in order to minimize the chance that they are output on
   purpose. Unfortunately that makes debugging of the output formatting
   difficult. With VISIBLE_MARKERS_WANTED=yes, visible characters ⁰, ¹, ...
   are used as internal pad characters. The internal pad characters are always
   replaced by blanks in normal APL output, but using visible pad characters
   simplifies the debugging of the internal APL formatting considerably.

    ./configure VISIBLE_MARKERS_WANTED=yes

RATIONAL_NUMBERS_WANTED=yes
   This enables support for rational numbers in GNU APL. The precision of some
   computations is increased while the performance is normally impacted
   negatively. This feature is currently experimental. Example:

    ./configure RATIONAL_NUMBERS_WANTED=yes

-------------------------------------------------------------------------------

The typical setting for users not interested in troubleshooting the APL
interpreter is to not use any options, i.e:

    ./configure


The typical setting for software development of the APL interpreter is:

    ./configure DEVELOP_WANTED=yes

which is a shortcut for:

    ./configure VALUE_CHECK_WANTED=yes          \
                VALUE_HISTORY_WANTED=yes        \
		PERFORMANCE_COUNTERS_WANTED=yes	\
                DYNAMIC_LOG_WANTED=yes          \
                ASSERT_LEVEL_WANTED=2

After the first ./configure run (which creates the top level Makefile)
you can do:

    make develop

which runs ./configure with the typical development options above.

About APL
=========

In addition to ASCII characters found on most keyboards,
APL needs additional "APL characters". This README file
explains how GNU APL works and how to enable APL characters on
a number of different machines.


1. How GNU APL works
====================

The GNU APL binary is a standard process that receives its input (normally,
but not necessarily from what you type on your keyboard). It reads a file descriptor
called "standard input (stdin) and prints its output on two other file
descriptors called standard output (stdout) for normal APL output, and
standard error (stderr) for additional diagnostic output.

This means that the GNU APL binary has no concept of what a keyboard is,
nor, on output is it concerned with fonts and the like. All the binary sees is a byte
stream on input and all it produces is a bytes stream out its output
channels stdout and stderr.

GNU APL expects that the byte sequences on stdin, stdout, and stderr are
"UTF8-encoded". UTF8-encoding is an extension of ASCII encoding that is used
in many places, including most Web pages. It is defined in the international
standard STD 63 (aka. "RFC 3629 - UTF-8, a transformation format of ISO 10646")
and is supported on most operating systems.

A second standard - Unicode - describes how characters will appear on the
terminal.  This standard includes all the APL characters used by GNU APL.
Normally Unicode  characters are UTF8 encoded when transmitted over serial lines,
file descriptors, in IP packets, or when displayed on web pages.

There are many advantages to using UTF8-encoded Unicodes for APL:

- You can copy/paste APL programs and expressions from web pages,
- You can print them on modern printers,
- You can telnet or ssh to remote computers that run APL,
- You can redirect UTF8 encoded files into the APL interpreter, This redirection
  gives you access to scripts written in APL.
- You can exchange such files with APL users using APL interpreters from other
  vendors, or copy APL code snippets into documents.

The downside of UTF8-encoded Unicodes is that GNU APL can not (and will not)
take care of how your keyboard, screen, and printers work. You have to set that
up yourself and outside GNU APL.

There is no single standard way of setting things up for GNU APL. The rest of
this README file describes a number of different methods to enable APL characters
on your machine. The information that follows has made GNU APL work on most
(but nor all) machines and operating systems around. As different approaches were
used these methods may conflict with each other. Use only one of them at a time.

GNU APL includes a directory called "support-files". This directory
contains various configuration files needed by the methods described below.

Most of the problems in getting UTF8-encoded Unicodes working with the APL interpretor
is with the input side (from the keyboard to GNU APL). The output side from APL
is most often already working (thanks to Unicode).


2. Structure of the support-files directory
===========================================

At one time, there was only one keyboard layout assumed for GNU APL. At that
time all support files for this keyboard layout (now called "old") were
located in the included support-files directory.

Then a number of different keyboard layouts were contributed by GNU APL users.

As of GNU APL 1.4 there is now one directory for every keyboard interface
option, currently:

    support-files/Dirk,
    support-files/Dyalog-Keyboard,
    support-files/Jürgen-Mint-19,
    support-files/old-Keyboard,
    support-files/OS-X-Keyboard,
    support-files/Unicomp-Keyboard, and
    support-files/WASD-Keyboard

The file names mentioned in the following are generic (independent of a
particular keyboard layout) whereas the support files provided, live in
one or more of the keyboard layout directories. For example:

    support-files/old-Keyboard/apl.xmodmap and
    support-files/Dyalog-Keyboard/apl.xmodmap

are the different instances of apl.xmodmap files for different keyboard
layouts.

If no support file exists for your actual combination of keyboard layout
and method, then usually the support file of some other layout works or
can be made working easily. If you adapt support files, feel free
to mail the changed file to bug-apl@gnu.org so that we can include it.

Note: Not all support files are fully tested - they should work. The layouts
change from time to time and given the number of methods and the number
of layouts there is no easy way to track these changes for all methods and layout

The standard layout assumed for GNU APL is that of the APL keyboards shipped
by Dyalog. The standard method assumed for GNU APL is xmodmap.


3. xmodmap
==========

If your operating system runs X (which is the case for most "Desktop"
variants of GNU/Linux) then it is quite simple to make your keyboard produce
APL characters.


The program xmodmap comes with X, and is already installed on your machine.
It defines a mapping between the keys you type and the character
that is being produced (taking into account modifiers like Shift or Alt).

There are two common physical hardware keyboards in common use. One is titled
pc104 and the other, pc105. The pc104 is the standard USA keyboard.
The pc105 has two additional keys and may contain more characters than are
found on the pc104 keyboard.The pc105 has a font selection key.
The APL character placement for the respective keyboard is shown below.

There are four character cases with your X system. Lower case, Upper case,
alt (ALT) case and shift-alt (shift-ALT) case. Usually the alt key is the one
to the right of the space bar. However, depending on the keyboard
xmod interface, the alt key may be the one to the left of the space bar.

The file "support-files/Dyalog-Keyboard/apl.xmodmap" (that comes with GNU APL)
provides such a mapping; the normal keys produce ASCII characters while the ALT
(and Shift-ALT) cases contains all APL character used by GNU APL. The
mapping is enabled with the following command (we use "$ " to indicate the
prompt of your shell):

    $ xmodmap support-files/Dyalog-Keyboard/apl.xmodmap

After that execution, your keyboard will produce APL characters when
the "Alt" key is held down. The keyboard layout defined in file
"apl.xmodmap" is similar to the following for pc104 and pc105 layouts:

PC104 USA Domestic APL Keyboard Layout
=====================================
╔════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦═════════╗
║ ~  ║ !⌶ ║ @⍫ ║ #⍒ ║ $⍋ ║ %⌽ ║ ^⍉ ║ &⊖ ║ *⍟ ║ (⍱ ║ )⍲ ║ _! ║ +⌹ ║         ║
║ `◊ ║ 1¨ ║ 2¯ ║ 3< ║ 4≤ ║ 5= ║ 6≥ ║ 7> ║ 8≠ ║ 9∨ ║ 0∧ ║ -× ║ =÷ ║ BACKSP  ║
╠════╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦══════╣
║       ║ Q  ║ W⍹ ║ E⋸ ║ R  ║ T⍨ ║ Y¥ ║ U  ║ I⍸ ║ O⍥ ║ P⍣ ║ {⍞ ║ }⍬ ║  |⊣  ║
║  TAB  ║ q? ║ w⍵ ║ e∈ ║ r⍴ ║ t∼ ║ y↑ ║ u↓ ║ i⍳ ║ o○ ║ p⋆ ║ [← ║ ]→ ║  \⊢  ║
╠═══════╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩══════╣
║ (CAPS   ║ A⍶ ║ S  ║ D  ║ F  ║ G  ║ H⍙ ║ J⍤ ║ K  ║ L⌷ ║ :≡ ║ "≢ ║         ║
║  LOCK)  ║ a⍺ ║ s⌈ ║ d⌊ ║ f_ ║ g∇ ║ h∆ ║ j∘ ║ k' ║ l⎕ ║ ;⍎ ║ '⍕ ║ RETURN  ║
╠═════════╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═════════╣
║             ║ Z  ║ Xχ ║ C¢ ║ V  ║ B£ ║ N  ║ M  ║ <⍪ ║ >⍙ ║ ?⍠ ║          ║
║  SHIFT      ║ z⊂ ║ x⊃ ║ c∩ ║ v∪ ║ b⊥ ║ n⊤ ║ m| ║ ,⍝ ║ .⍀ ║ /⌿ ║  SHIFT   ║
╚═════════════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩══════════╝

PC105 USA and International Keyboards
=====================================
╔════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════════════╗
║ ~  ║ !⌶ ║ @⍫ ║ #⍒ ║ $⍋ ║ %⌽ ║ ^⍉ ║ &⊖ ║ *⍟ ║ (⍱ ║ )⍲ ║ _! ║ +⌹ ║            ║
║ `◊ ║ 1¨ ║ 2¯ ║ 3< ║ 4≤ ║ 5= ║ 6≥ ║ 7> ║ 8≠ ║ 9∨ ║ 0∧ ║ -× ║ =÷ ║ BACKSP     ║
╠════╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═════════╣
║       ║ Q  ║ W⍹ ║ E⍷ ║ R  ║ T⍨ ║ Y¥ ║ U€ ║ I⍸ ║ O⍥ ║ P⍣ ║ {⍞ ║ }⍬ ║         ║
║  TAB  ║ q? ║ w⍵ ║ e∈ ║ r⍴ ║ t∼ ║ y↑ ║ u↓ ║ i⍳ ║ o○ ║ p⋆ ║ [← ║ ]→ ║ RETURN  ║
╠═══════╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╗       ║
║ (CAPS   ║ A⍶ ║ S  ║ D  ║ F  ║ G  ║ H  ║ J⍤ ║ K⌸ ║ L⌷ ║ :≡ ║ "≢ ║ |⊣ ║       ║
║  LOCK)  ║ a⍺ ║ s⌈ ║ d⌊ ║ f_ ║ g∇ ║ h∆ ║ j∘ ║ k' ║ l⎕ ║ ;⍎ ║ '⍕ ║ \⊢ ║       ║
╠════════╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩════╩═══════╣
║        ║ < ¦║ Z  ║ Xχ ║ C¢ ║ V  ║ B£ ║ N  ║ M  ║ <⍪ ║ >⍙ ║ ?⍠ ║             ║
║  SHIFT ║ > °║ z⊂ ║ x⊃ ║ c∩ ║ v∪ ║ b⊥ ║ n⊤ ║ m| ║ ,⍝ ║ .⍀ ║ /⌿ ║  SHIFT      ║
╚════════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩═════════════╝

Three files within "support-files/Dyalog-Keyboard/", keyboard.txt, keyboard1.txt
and pc105.txt contain the above images. If you want to print it
(keyboard1 is < 80 characters wide).

If you don't like this particular layout, then you can modify "apl.xmodmap"
to fit your preferences.

If you are Finnish then you may want to have a look here:

  http://www.oksman.eu/apl/gnu_apl_installation_with_finnish_keyboard_layout.txt

LATEST NEWS: as of Mint-19 xmodmap is no longer working (at least with the
GNOME desktop). For those who used xmodmap with a Dyalog keyboard layout,
a 1:1 replacement based on setxkbmap exists, see file README in directory
support-files/Jürgen-Mint-19. This file is a hack that is somewhat easier
to use than "proper" setxkbmap/xkbcomp setup explained in the next section.

4. setxkbmap/xkbcomp
====================

Another program that can be used to make your keyboard produce APL
characters is setxkbmap. Like xmodmap it requires that you are running X,
and setxkbmap should not be mixed with xmodmap.

setxkbmap is more modern and more powerful than xmodmap, but we had some
problems with older GNU/Linux versions (an setxkbmap config file produced
on a newer GNU/Linux did fix these problems).

The file support-files/old-Keyboard/apl.xkm provides such a mapping (the
file was kindly provided by David De La Harpe and produced with the command
xkbcomp on his machine).

The mapping is installed as follows:

    $ xkbcomp support-files/old-Keyboard/apl.xkm :0

Unlike the xmodmap approach, the APL characters are now produced with
the AltGr modifier key but not with the Alt modifier key. This was to
better support emacs which uses the Alt keys for other purposes.

on those systems one of the following command may do (the syntax and file names
of setxkbmap appear to have changed over time):

    $ setxkbmap -layout "apl(sax)"
    $ setxkbmap -layout "apl" -variant ",sax"
    $ setxkbmap -layout "apl" -variant "sax"

The file support-files/apl.xkb is the text file from which apl.xkm was
generated. If you modify apl.xkb according to your preferences then you
can generate your own apl.xkm file (see man pages for setxkbmap and xkbcomp).

See also Blake's notes in support-files/Unicomp-Keyboard/apl.unicomp.xkb.txt

Another description (also using setxkbmap) and files supporting it was kindly
provided by Dirk Laurie and is contained in directory support-files/Dirk.

WARNING: the description above is merely the "Theory of Operation" for
setxkbmap and friends (according to their man pages). Over the years, window
managers have become increasingly intrusive (some call it "convenient")
into the keyboard setup. There exist a number of description below the
directory support-files/ that may look contradictory and/or may not work on
a given platform. These descriptions were, to the best of our knowledge,
valid and working at the time when they were contributed, but may have stopped
working on some platforms in the meantime. Therefore please consider them as
mere ideas how keyboard layouts could be adapted to APL rather than fool-proof
recipies.

5. loadkeys
===========

If you are not running X then the above methods will complain about
"unable to open display". In that case you can use command "loadkeys" to
set up the keyboard layout, and command "unicode_start" to set up an APL
font.

    $ sudo loadkeys support-files/old-Keyboard/apl.loadkeys
    $ unicode_start Unifont-APL8x16.psf

The console font Unifont-APL8x16.psf will be contained in the next official
release of GNU Unifont (maintained by Paul Hardy). In the meantime it can
be downloaded from:

    http://unifoundry.com


6. Editing APL files
====================

Instead of using APL interactively, you may, like the author, find it more
convenient to write a text file (an APL script) with all APL function
definitions and variable assignments and to then run "apl -f" or "apl -s"
with that file.

The editor of choice for editing such files is vi (actually, vim). Recent
versions of vim come with Unicode support and require no further changes
to work with APL characters (assuming, of course, that one of the methods
above is in place to make the keyboard generate APL characters).

To further improve on that, there is a syntax file support-files/apl.vim
that supports syntax coloring of vim.


7. Emacs Mode
=============

Unlike vim, which runs out-of-the-box with APL characters, emacs needs
a little more setup work. We cannot describe this here but would like to
refer you to the web page of Elias Mårtenson who has put a lot of effort
into developing an emacs mode for GNU APL. This is a must for every
emacs user:

    https://github.com/lokedhs/gnu-apl-mode


8. Vim Plugins
==============

If your favorite editor is vim, then you will like the following plugin
for vim, written by Thomas Baruchel:

    http://www.vim.org/scripts/script.php?script_id=4887

Another useful vim plugin, also written by Thomas Baruchel, lets you
pick APL characters from a menu inside vim. It is here:

    http://apl-adventures.tumblr.com/post/76528148239/an-apl-character-picker-for-vim


9. The APL Keyboard Translator (akt)
=====================================

David Lamkins has written a keyboard translator called akt. You can
use it for generating APL characters with your keyboard. In contrast to e,g.
the xmodmap method, the mapping is on a per program basis so that other
programs are not affected. Obtain a copy from:

    https://github.com/TieDyedDevil/akt

David's akt program is simple to use. In its most useful form the line is

   akt apl <optional-apl-parameters>

If you would like to write APL code using vim, doing so with akt is
as simple as:

    akt vi        or   akt vi your-apltext

The left alt key is used to provide the apl characters.

Certain older terminal emulators may offer an "Alt sets MSB" option. This
is incompatible with `akt`.



10. Keyboard Wrapper
====================

If the methods described above cannot be used for whatever reason then
you can write your own program that reads keystrokes from the keyboard
and produces UTF8 bytes sequences on its stdout. The program can then
be 'piped' into GNU APL, We refer to such a program as a 'keyboard wrapper'.

This technique is demonstrated by 3 programs called APL_keyboard_show,
APL_keyboard_learn, and APL_keyboard, which are all located in the 'tools'
subdirectory.

10.1 Introduction to Defining your own layout.
=============================================
When you wish to use APL with your own keyboard and/or keyboard arrangement.

Use these programs as in succession as follows:

o   APL_keyboard_show   to  display the keycodes

o  APL_keyboard_learn   to   create a file with the keycodes

o  APL_keyboard         to use the file from APL_keyboard_learn

o  make                 to transform output from learn to program

Details follow in sections 10.2 through 10.4 below.

10.2 APL_keyboard_show
----------------------

APL_keyboard_show is a simple program that displays the byte sequences
produced by your keyboard. The following sequences are, as an example,
sent by an Ubuntu system without having xmodmap or any other method applied.
The characters typed were 'qwerty' and then 'qwerty' with ALT held down:

$ ./APL_keyboard_show

hit key ^C to quit...

key_seq_1(0x71))
key_seq_1(0x77))
key_seq_1(0x65))
key_seq_1(0x72))
key_seq_1(0x74))
key_seq_1(0x79))
key_seq_2(0xC3, 0xB1))
key_seq_2(0xC3, 0xB7))
key_seq_2(0xC3, 0xA5))
key_seq_2(0xC3, 0xB2))
key_seq_2(0xC3, 0xB4))
key_seq_2(0xC3, 0xB9))

After running support-files/Dyalog/apl.xmodmap the following byte
sequences are sent:

hit keys, ESC to quit...

key_seq_1(0x71))
key_seq_1(0x77))
key_seq_1(0x65))
key_seq_1(0x72))
key_seq_1(0x74))
key_seq_1(0x79))
key_seq_1(0x3F))
key_seq_3(0xE2, 0x8D, 0xB5))
key_seq_3(0xE2, 0x88, 0x88))
key_seq_3(0xE2, 0x8D, 0xB4))
key_seq_3(0xE2, 0x88, 0xBC))
key_seq_3(0xE2, 0x86, 0x91))

The alert reader will have noticed that in both cases UTF8 encoded characters
were sent; they were different and just wrong for APL before running xmodmap.


10.3 APL_keyboard_learn
-----------------------

The next program is APL_keyboard_learn which is derived from APL_keyboard_show.

APL_keyboard_learn asks you to hit the keys for all APL characters and writes
them into file APL_keyboard.def. For example:

./APL_keyboard_learn

hit keys, ESC to quit...

hit key (0 of 94) for APL character ◊ :  0xC3 0xA0 (2 bytes)
hit key (1 of 94) for APL character ¨ :  0xC2 0xB1 (2 bytes)
hit key (2 of 94) for APL character ¯ :  0xC2 0xB2 (2 bytes)
hit key (3 of 94) for APL character < :  0xC2 0xB3 (2 bytes)
hit key (4 of 94) for APL character ≤ :  0xC2 0xB4 (2 bytes)
hit key (5 of 94) for APL character = :  0xC2 0xB5 (2 bytes)
hit key (6 of 94) for APL character ≥ :

...

If a key shall produce the same APL character regardless of the state of
the SHIFT key, then you will be asked twice:

hit key (0 of 94) for APL character ◊ :  0xC3 0xA0 (2 bytes)
hit key (13 of 94) for APL character ◊ (shift):  0xC3 0xBE (2 bytes)

APL_keyboard_learn writes a file APL_keyboard.def which is needed by the
third program, APL_keyboard. The order of the keys that you are asked for
is defined in file APL_keyboard.orig.def (which is identical to
APL_keyboard.def when GNU APL is installed).

After running APL_keyboard_learn, you should do 'make' in the tools directory,
in order incorporate the newly created APL_keyboard.def into the program
APL_keyboard.


10.4 APL_keyboard
-----------------

The keyboard wrapper itself is APL_keyboard. The file APL_keyboard.def is
#included by APL_keyboard.cc and defines the mapping from bytes sequences
produced by you keyboard to UTF8 sequenced to be fed into GNU APL.

Once APL_keyboard is made, you can start GNU APL like this:

$ APL_keyboard | apl



11. aplwrap
===========

There  is a cool GTK-based keyboard wrapper written by Chris Moller.
You can reach it via the GNU APL Community web page:

     http://www.gnu.org/software/apl/Community.html

When invoked, it opens the apl interpretor in a window. The left alt key
is used to provide the apl characters.

12. Remote Login
================

Suppose GNU APL is started on machine A and you connect to it by means
of ssh or telnet from machine B. In that case the keyboard setup
discussed above is only needed on machine B,  and not on machine A.

The same applies if machine A is a web server using APL for CGI scripting;
in this case machine B does not normally need the above setup because these
days, browsers are aware of UTF8 encoding (which is a standard encoding for
HTML pages).

If you telnet to a machine A, then verify that 8-bit operation is enabled
(-8 command line option) or else UTF8 encoding will not work.

If you ssh, make sure that the TERM variable is properly set on machine A
or else output coloring of GNU APL may send incorrect ESC sequences for
switching between colors (or use apl -noColor).


13. Pitfalls and Troubleshooting
================================

There are other pieces of software that may intercept the byte stream on its
way from the keyboard, via GNU APL, to the screen (or printer). A prime
example is "locales" that can change the encoding of the byte streams involved.

Locales interfere with APL characters in multiple ways: they can install new
keyboard mappings, change encoding to something other than UTF8, and currently
also impact the file format of saved workspaces, for example by changing the
decimal point from . to , in the printf() functions. One thing to avoid the
latter is to run ./configure with --disable-nls.

If you need to troubleshoot APL characters, proceed as follows:

1. determine if the problem is on input (between the keyboard and GNU APL),
   or on output (between GNU APL and the screen (or printer), or both.

2. To check the output, start GNU APL and issue the debug command:

   ]KEYB

   In GNU APL there are the classical APL commands starting with ) like
   )FNS or )VARS, and debug commands starting with ] instead of ).
   If ]KEYB shows a keyboard layout like the one in the xmodmap section
   above, then the output is working. If not then something is wrong with
   either the encoding, or with your fonts.

3. For the input you can use commands like "xev" to see which Unicodes are
   sent when you press a key. If the wrong Unicode is shown then your
   key mapping is wrong; otherwise the encoding is more likely to be
   the problem.


14. APL Keyboards
=================

If you are new to APL or use it only infrequently, then you may have
problems remembering the locations of all the APL characters on your
keyboard. In that situation an APL keyboard may be a great help.

Technically, an APL keyboard is not different from a normal keyboard. It
produces the same keycodes as a normal keyboard. It does therefore not
replace the methods for setting up your keyboard that were discussed above.

However, it has the common APL symbols engraved on its keycaps in addition to
the normal ASCII characters. There are not many vendors around that sell APL
keyboards (it took a while for the author to find one). Therefore it may be
worthwhile to mention a few:

a. www.dyalog.com (send an email to sales@dyalog.com to obtain a quote).
b. www.wasdkeyboards.com
c. www.unicomp.com seems to have APL keyboards every now and then.

An inquiry sent to a. was answered promptly; an inquiry sent to c. never.

Blake McBride has contributed a few files and installation instructions
for c. (WASD keyboards) which are contained in the support-files/WASD
directory.

Stickers
==========
Stickers may be created by printing the keyboard1.txt onto a
gummed paper, and subsequently cutting the sticker and peeling it
to the keytop. This is not a durable solution, but would help you
to remember the APL key locations.

Another help for those that keep forgetting the APL key locations of their
keyboard is the ]KEYB command of GNU APL. It displays the layout of a standard
US keyboard with APL characters. Under X, if your keyboard is not yet up
and running properly got APL, you can run the ]KEYB command in one window and
then copy-and-paste APL characters from that window to another one running APL
with your mouse.  This approach is not useful for normal programming work, but
can be handy in special situations.

The following features are NOT planned to be supported
------------------------------------------------------

* ⎕NLT


The following features MAY be added (if requested):
---------------------------------------------------

* more shared variables / auxiliary processors

* ⎕NA

* more ⎕L and ⎕R testcases


The following features are planned or will be investigated:
-----------------------------------------------------------

* Support for SCAR format (to exchange data with Dyalog APL and APL2000).

* operators from NARS2000 (email from Bob Smith, Dec-14-2013)

* versioning of .so files


The following issues are known and maybe fixed mid-term:
--------------------------------------------------------


The following extensions are provided:
--------------------------------------

* various debug commands, see )HELP

* dyadic ⎕CR   (DISPLAY-like value output,
                several conversions of bytes and characters).
                Canonical Representation)

* ⎕DLT         (Knuth's Dancing links algorithm, aka Algorithm X)

* ⎕ENV B       (environment variables)
               return the values of environment variables whose names starts
               with B. The result is a N by 2 matrix, with column 1 containing
               environment variable names and column 2 their values.

* ⎕FIO         (several FILE I/O functions)

* ⎕SQL         (access to SQL databases)

* 3 ⎕TF        (⎕TF with CDR format)

* APL scripting
    text files beginning with:

    #!apl

    run the interpreter as a shell with the subsequent lines as input.

* ⎕INP
     HERE-document like input for long texts

* Native APL functions
    User defined APL functions written in C++

* )DUMP command (save workspace in a format that can be read back with apl -f

You can run GNU APL on windows by means of CYGWIN:

1. install CYGWIN (see http://www.cygwin.org)

2. Install additional libraries as needed (look for error messages in 3. below)

3. Follow the standard installation procedure for GNU APL in INSTALL,
  README-2-configure, and README-3-keyboard.

WARNING: If you are not familiar with CYGWIN (which provides a GNU/Linux look
         and feel on WINDOWS) then your health is at risk! You may suffer
         serious depressions after returning to WINDOWS. The only known cure
         is to permanently stay away from WINDOWs.

The procedure above has been tested with WINDOWS XP and a CYGWIN version
that has identified itself (via uname -a) as:

	CYGWIN_NT-5.1 Server 1.7.25(0.270/5/3) 2013-08-31 20:39 i686 Cygwin


LIMITATIONS: backtraces (Stack dumps after fatal errors) may not work
because they use a GNU extension that may or may not be supported on CYGWIN.

NOTE: The procedure described in README-3-keyboard uses the program xmodmap,
 which only works when xmodmap and GNU APL are started under X (which is
normally the case for Desktop GNU/Linux distributions). In CYGWIN you can
start a "Cygwin Terminal" which does NOT run under X. If you run xmodmap
in the Cygwin Terminal then it complains like this:

 xmodmap: unable to open display ''

This is an indication that X is not running and that your keyboard will
not produce APL characters. You can still start GNU APL (to check that it
has compiled properly), but you will be lacking almost all functions.

A case where it makes sense to run GNU APL without X is APL scripts,
for example CGI scripts for web servers written in APL. These scripts do
not read input from the keyboard, so it does not matter that the keyboard
setup is wrong.

Another case is a remote login from machine A to machine B using ssh. In this
case X should run on machine A (so that the keyboard on A works), but a GNU
APL on machine B can run without X.


Yet another possibility for Windows users is to install some GNU/Linux
distribution, for example Ubuntu or Linux Mint, in a virtual machine.
Installing virtual machines as well as installing GNU/Linux on a virtual
machine has become rather simple these days. Needless to say that the
WARNING above also applies in thius case!

GNU APL has been compiled successfully on non-GNU/Linux systems.
Some of these systems may require additional settings.

Below are notes from GNU APL users with non-GNU/Linux systems (in
almost alphabetical order of the OSs)

===============================================================================
====									   ====
====			    BSD (FreeBSD)				   ====
====									   ====
===============================================================================

We have the following problem building GNU APL in FreeBSD.
It can be solved by ./configure'ing GNU APL as shown below.

1. Non-standard library locations. Some of the libraries used by GNU APL.
   for example libexecinfo, live in /usr/local/lib and not in /usr/lib and
   may not be found by ./configure. This can be solved by setting LDFLAGS
   BEFORE running ./configure.

After compiling GNU APL you may want to enable UTF-8 encoding for your
terminal. For example, in xterm you need enable UTF-8 encoding and
UTF-8 Fonts in xterm's VT menu (Ctrl + right mouse). It may be possible
to set this permanently in your terminal's configuration file(s).

Freebsd 8.4
-------------------------------------------------------------------------------

Many thanks to Sam Sirlin for providing this!

for configure:
--------------

setenv CC gcc46
setenv CXX g++46
setenv LDFLAGS '-L/usr/local/lib -L/usr/local/lib/gcc46 -R/usr/local/lib -R/usr/local/lib/gcc46'
setenv LIBS ' -lexecinfo '

Freebsd 9
-------------------------------------------------------------------------------

setenv LDFLAGS '-L/usr/local/lib'


===============================================================================
====									   ====
====			    BSD (OpenBSD)				   ====
====									   ====
===============================================================================

Giuseppe Cocomazzi has created an open BSD port of GNU APL. See:

http://sbudella.altervista.org/blog/20170821-apl-openbsd.html


===============================================================================
====									   ====
====			    CYGWIN 5.1 (aka. Windows)			   ====
====									   ====
===============================================================================

GNU APL compiles on CYGWIN, see README-5-WINDOWS for details


===============================================================================
====									   ====
====			    OS-X					   ====
====									   ====
===============================================================================

The latest version (SVN) of GNU APL was reported to compile and run on OS-X
without special measures.

For Macintosh users, Peter Teeson has contributed a very nice installation
instructions that can be found in the doc/ subdirectory (file
APL-on-Macintosh.pdf).

If you have reached this file, then GNU APL is hopefully running well for
you. You may have more questions that are related to APL in general
rather than to GNU APL in particular.

The following is a list of web links that may be used as starting points
for more information about APL. This list is admittedly rather arbitrary
and by no means complete.


ISO Standard 13751
------------------

The ISO standard implemented by GNU APL can be found here:

    www.math.uwaterloo.ca/~ljdickey/apl-rep/docs/is13751.pdf

Note that this file is, despite of its .pdf extension, a gzip compressed
PDF file. You have to fetch it, rename it, and then gunzip it:

    wget www.math.uwaterloo.ca/~ljdickey/apl-rep/docs/is13751.pdf
    mv is13751.pdf is13751.pdf.gz
    gunzip is13751.pdf.gz


IBM Documentation
-----------------

In cases where the ISO 13751 standard was not clear, the IBM documents
for APL2 were consulted as a second opinion:

    www.catpad.net/michael/apl/ibmapl2/apl2lrm.pdf


Dyalog APL Manual
-----------------

Dyalog Ltd. a commercial APL vendor, has published a book describing
their APL in great detail. Not all features described there are implemented
in GNU APL, but this book is a good starting point for beginners.

    www.dyalog.com/mastering-dyalog-apl.htm


comp.lang.apl
-------------

An always interesting APL related newsgroup which has been around for
many years is:

    groups.google.com/forum/#!forum/comp.lang.apl


Sam Sirlin's FAQ
----------------

Much more information about APL can be found at Sam Sirlin's APL FAQ at:

    home.earthlink.net/~swsirlin/apl.faq.html


The doc directory in the GNU APL package
----------------------------------------
The doc directory contains some more files in different formats. Most of them
are installed in other places, for example in the info system, or (in HTML) at:
https://www.gnu.org/software/apl/apl.html.  Some of the filesin the doc
directory are targeting specific platforms, for example the file
APL-on-Macintosh.pdf written by Peter Teeson.

The GNU APL info
----------------

GNU APL installs an info file which can be viewed with:

info apl

The GNU APL )HELP command output
--------------------------------
)HELP
APL Commands:
      )CHECK
      )CLEAR
      )CONTINUE
      )COPY [lib] wsname [object ...]
      )DROP [[lib] wsname]
      )ERASE symbol ...
      )DUMP-HTML [[lib] wsname]
      )DUMPV [[lib] wsname]
      )DUMP [[lib] wsname]
      )FNS [from-to]
      )HELP
      )HIST [CLEAR]
      )HOST command
      )IN filename [object ...]
      )LIBS [[lib] path]
      )LIB [lib|path]
      )LOAD [lib] wsname
      )MORE
      )NMS [from-to]
      )OFF
      )OPS [from-to]
      )OUT filename [object ...]
      )PCOPY [lib] wsname [object ...]
      )PIN filename [object ...]
      )QLOAD [lib] wsname
      )RESET
      )SAVE [[lib] wsname]
      )SIC
      )SINL
      )SIS
      )SI
      )SYMBOLS [count]
      )VALUES
      )VARS [from-to]
      )WSID [wsname]
      ]BOXING [OFF|2|3|4|7|8|9]
      ]COLOR [ON|OFF]
      ]NEXTFILE
      ]EXPECT error_count
      ]HELP
      ]KEYB
      ]LIB [lib|path]
      ]LOG [facility [ON|OFF]]
      ]OWNERS
      ]PSTAT [CLEAR|SAVE]
      ]SIS
      ]SI
      ]SVARS
      ]SYMBOL symbol
      ]USERCMD [ ]ucmd APL_fun [mode]
               | ]ucmd { ... }
               | REMOVE ]ucmd
               | REMOVE-ALL
               ]
      ]XTERM [ON|OFF]

System variables:
      ⎕AI     Account Information
      ⎕ARG    command line ARGuments of the interpreter
      ⎕AV     Atomic Vector
      ⎕CT     Comparison Tolerance
      ⎕EM     Event Message
      ⎕ET     Event Type
      ⎕FC     Format Control
      ⎕IO     Index Origin
      ⎕L      Left Argument
      ⎕LC     Line Counters
      ⎕LX     Latent Expression
      ⎕PP     Printing Precision
      ⎕PR     Prompt Replacement
      ⎕PS     Print Style
      ⎕PW     Print Width
      ⎕R      Right Argment
      ⎕RL     Random Link
      ⎕SVE    Shared Variable Event
      ⎕SYL    SYstem Limits
      ⎕TC     Terminal Control characters
      ⎕TS     Time Stamp
      ⎕TZ     Time Zone
      ⎕UL     User Load
      ⎕X      aXis Argument
      ⎕WA     Workspace Available
      λ       { ... } result
      ⍺       { ... } left value argument
      ⍵       { ... } right value argument
      χ       { ... } axis argument
      ⍶       { ... } left function argument
      ⍹       { ... } right function argument

System functions:
      ⎕AF     Atomic Function
      ⎕AT     Attributes
      ⎕CR     Character Representation
      ⎕DL     Delay
      ⎕DLX    D. Knuth's Dancing Links
      ⎕EA     Execute Alternate
      ⎕EB     Execute Both
      ⎕EC     Execute Controlled
      ⎕ENV    ENvironment Variables
      ⎕ES     Event Simulate
      ⎕EX     EXpunge
      ⎕FIO    File I/O
      ⎕FX     FiX
      ⎕INP    INPut from script
      ⎕NA     Name Association
      ⎕NC     Name Class
      ⎕NL     Name List
      ⎕SI     State Indicator
      ⎕SQL    SQL functions
      ⎕SVC    Shared Variable Control
      ⎕SVO    Shared Variable Offer
      ⎕SVQ    Shared Variable Query
      ⎕SVR    Shared Variable Retraction
      ⎕SVS    Shared Variable State
      ⎕STOP   STOP vector
      ⎕TF     Transfer Form
      ⎕TRACE  TRACE vector
      ⎕UCS    Universal Character Set (aka. Unicode)

Other Documentation
-------------------
The distribution has a doc subdirectory in which you will find
html formatted documentation and *.info documentation.

GNU APL supports, to some extent, execution of APL programs on multiple
CPU cores in parallel.

1. Supported Platforms
======================

As of SVN 484 parallel execution in GNU APL requires the following:

a.	POSIX thread (pthread) support

b.	functions pthread_getaffinity_np() and pthread_setaffinity_np() to
	set core affinities (i.e. which thread runs on which CPU core) of the
	threads created by GNU APL for parallel execution.

c.	an atomic fetch-and-add function

While a. is normally available on all platforms supported by GNU APL, b. and
c. may not be available. Recent Linux versions provide a., b., and c., Other
platforms may be added later.

2. ./configure Options
======================

Parallel execution is currently experimental and must be ./configure'd
explicitly (see also README-2-configure). There are two ./configure options
related to parallel execution:

   CORE_COUNT_WANTED and
   PERFORMANCE_COUNTERS_WANTED

The first option, CORE_COUNT_WANTED, controls how many cores shall be used
for parallel execution, while the second option, PERFORMANCE_COUNTERS_WANTED,
enables performance counters in GNU APL. Performance counters are needed for
fine-tuning the parallelism as explained in the following.

There are also two top-level make targets called 'parallel' and 'parallel1'
'make parallel' calls ./configure with CORE_COUNT_WANTED=syl while
'make parallel1 calls ./configure with CORE_COUNT_WANTED=syl and
PERFORMANCE_COUNTERS_WANTED=yes.

3. Parallelized Functions
=========================

As of SVN 484 the following APL functions were parallelized:

a. all monadic and dyadic scalar functions
b. inner products of all dyadic scalar functions
c. outer products of all dyadic scalar functions

More APL functions may be parallelized later.


4. Performance measurements and Fine-tuning
===========================================

The first benchmarks performed with the parallelized scalar functions have
shown that 'light-weight' scalar functions such as + , -, or ⌈ may execute
faster than their sequential counterparts on one platform but slower on another
platform. The difference between platforms can be dramatic.

For that reason there is a possibility to fine-tune the break-even points
where parallel execution is performed in favor of sequential execution.
There is a break-even point for every monadic and for every dyadic scalar
function.


4.1 Theory
-----------

The sequential execution time of a scalar function is:

	A0 + (B0 × N) cycles,

where A0 is the 'start-up time' for the function, B0 is the 'per-item time
for the function, and N is the vector length. The actual shape does not matter
for scalar functions, so adding 1 2 3 4 to itself takes the same time as
adding 2 2⍴1 2 3 4 to itself.

The sequential start-up time A0 is the same for all monadic scalar functions
and for all dyadic scalar functions; the start-up time for dyadic functions
is a little longer than for monadic scalar functions.

Now let c be the number of cores. The parallel execution time on c cores
is then:

	Ac + (Bc × N) cycles,

at least when N is a multiple of c. The difference when N is a not a multiple
of c can be neglected. Again the parallel start-up time Ac is the same for
all monadic scalar functions and for all dyadic scalar functions. And Ac ≥ A0;
the difference (Ac - A0) is the additional start-up and join time for the
thread pool computing the function in parallel.

From the 4 numbers A0, B0, Ac, and Bc one can compute the break-even point BE,
which is the vector length at which parallel execution becomes faster than
sequential execution. The break-even point is:

	BE ← (Ac - A0) ÷ (B0 - Bc)

The break-even point only exists if Bc < B0, that is if the parallel per-item
cost Bc is smaller than than the sequential per-item cost B0. On some
architectures Bc = B0 ÷ c (and then (Ac - A0) is the only concern) but
unfortunately for multi-core CPUs with a shared memory this is not the case.

4.2 Measuring A0, Ac, B0, and Bc
--------------------------------

There is a workspace 'ScalarBenchmark.apl' shipped with GNU APL that measures
the parameters A0, Ac, B0, and Bc and writes a file 'parallel_thresholds; that
can be fed back to GNU APL in order to set the break-even points for all
scalar functions. The workspace can also plot the results using aplplot.

The workspace is used as  follows:

a.	'make parallel1' as discussed above
b.	adjust some parameters at the beginning of ScalarBenchmark.apl (number
	of cores, plotting yes/no, and loop counts.
c.	run, e.g.: src/apl -f workspaces/ScalarBenchmark.apl

The last step c. creates a file 'parallel_thresholds' in the current directory.
If that file is placed in one of the directories used for the 'preferences'
file (/etc/gnu-apl.d/ or /usr/local/etc/gnu-apl.d/ depending on ./configure
prefix, or $HOME/.gnu-apl.d, or $HOME/.config/gnu-apl.d) the GNU APL reads
it on start-up and sets the break-even points for the scalar functions
accordingly.

The 'ScalarBenchmark.apl' first determines A0 and Ac using small vector
lengths N. With today's CPUs the measurement results vary considerably,
Therefore several iterations are performed for each vector length and the
minimum of all iterations is taken. From these minimums the least-square
regression line for all lengths is computed.

Then 'ScalarBenchmark.apl' determines the per-item costs B0 and Bc using a
fairly large vector length N.

4.3 Example 1: Intel 4-core i5-4570 CPU using 3 cores on 64-bit linux
---------------------------------------------------------------------

We discuss only two dyadic functions, + and ⋆. + is 'light-weight' and ⋆
is not. The summary shown by 'ScalarBenchmark.apl' for + and ⋆ is:

-------------- + Mix_IRC --------------
average sequential startup cost:      58 cycles
average parallel startup cost:       690 cycles
per item cost sequential:             61 cycles
per item cost parallel:               95 cycles
parallel break-even length:          not reached

The good news is that the extra cost for parallel start-up and join of
(690 - 58) = 632 cycles are fairly low. We had earlier made benchmarks with
other parallel libraries which were semaphore based and showed start-up cost
in the 10000-20000 cycle ballpark.

The bad news is that the parallel per-item cost for + are higher than the
sequential per-item cost and therefore there is no break-even point for +.
The per-item cost of 61 cycles is rather close to the values of a separate
benchmark that measured the main memory access times alone (see
tools/memory_benchmark). Our best explanation for not reaching a break-even
for + (on this machine) is that there are more extra cycles caused by
main-memory access conflicts of the different cores than cycles saved
by parallelizing +.

For ⋆ the result is different because ⋆ is not as light-weight as +:

-------------- ⋆ Mix_IRC --------------
average sequential startup cost:      58 cycles
average parallel startup cost:       690 cycles
per item cost sequential:            147 cycles
per item cost parallel:               91 cycles
parallel break-even length:           12


4.4 Example 2: Intel 2-core E6550 CPU using 2 cores on 32-bit linux
-------------------------------------------------------------------

On this older machine the results were rather different:

-------------- Mix_IRC + Mix1_IRC --------------
average sequential startup cost:    2027 cycles
average parallel startup cost:      2340 cycles
per item cost sequential:            362 cycles
per item cost parallel:              210 cycles
parallel break-even length:            3

-------------- Mix_IRC ⋆ Mix_IRC --------------
average sequential startup cost:    2027 cycles
average parallel startup cost:      2340 cycles
per item cost sequential:            647 cycles
per item cost parallel:              340 cycles
parallel break-even length:            2

All functions were faster when executed parallel. The per-item cost were
considerably higher (in part due to the 32-bit linux) but the parallel
start-up penalty (2340 - 2027) = 313 was smaller.

Note that the start up cost vary considerably between different runs of
the same benchmark on the same machine. Therefore you should run several
measurements before trusting the result.

4.5 Other observations
----------------------

Another, somewhat unexpected observation made when looking at several
benchmarks is that the optimal number of cores seems to be N-1 (i.e. not N)
on an N-core CPU.

The reason is that other regular operating system activities such
as timer interrupts occur during the APL execution. The threads used by GNU
APL get an almost even amount of work and the threads are running at 100%
load unless the interpreter is blocked on user input. [This is a consequence
of using a fetch-and-add function instead of semaphores for synchronizing the
threads.]

If all N cores of a CPU are used by APL then the CPU schedules its activities
on one of the busy cores (and most likely the same core all the time).
That core then takes more time than the others and the entire computation\
of the APL function is delayed accordingly.

If, however, only N-1 of N cores are used then the OS sees an idle core and
will most likely perform its activities on that core. These effects are best
visualized when using the plotting option of ScalarBenchmark.apl.

5. Summary
==========

The above discussion shows that some speedup can be achieved by parallelizing
scalar APL functions. However the speedup is not as significant as a naive
observer might expect (i.e. B0÷Bc = c) and varies considerably between OS
variants and hardware platforms.

While the start-up cost of the current implementation in GNU APL look good
compared to other approaches, the per-item cost are somewhat disappointing
on some machines (and this is due to effects outside GNU APL). A corollary
of this could be that APL operations with little computational complexity
(such as A⍴B) will suffer as well and will not show good speedups when
executed in parallel.

In any case is it worthwhile to fine-tune the break-even points of the
different scalar functions.

Post Installation Setup
=======================

by Leslie S. Satenstein

1.0   Introduction
==================
Following the execution of GNU-APL's "make install" (which is conceptually
performed by a system administrator with access permissions to directories like
/etc or /usr/), some additional setup activities by the user are normally
required. The user can try out GNU APL before this additional setup, but some
APL commands such as )SAVE will not work because the creation and specification
of directories that are used for storing for files created by the user are the
responsibility of the user and not of the system administrator.

The description below assume that ./configure of GNU APL was executed without a
prefix= option. If the prefix option was used then some of the paths further
down in this document may differ accordingly.

The "make install" procedure should have created a directory

        /usr/local/etc/gnu-apl.d

        or

        /etc/gnu-apl.d


This directory contains:

        keyboard1.txt           a default USA PC104 keyboard layout
        keyboard2.txt           a default International PC105 layout
        parallel_thresholds     a presentation settings for apl  multitasking
        preferences             a file to tailor apl for your system

This next section describes configuring GNU-APL using the preferences file.
The preference file comes pre-configured, but in some instances, the
global contents may not suit your requirements. One example, is that
you need to maintain a private copy of some workspaces, or modify apl actions.

In this situation you may choose to create a directory with a copy of above
directory contents below your home directory. If so, then the name of that
directory should be $(HOME)/.config/gnu-apl/. The easiest way of creating
this directory and its initial content is the shell command:

    cp -dR /etc/gnu-apl.d $HOME/.config/gnu-apl

The command may be somewhat different, for example if you used non-default
directories in your ./configure command.


1.1   KEYBOARDS
===============
There are two physical keyboards predominately in use. One is the popular
American  keyboard layout, model pc104, shown below as Keyboard1.txt:

PC104 USA Standard Keyboard:
===========================
╔════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦═════════╗
║ ~  ║ !⌶ ║ @⍫ ║ #⍒ ║ $⍋ ║ %⌽ ║ ^⍉ ║ &⊖ ║ *⍟ ║ (⍱ ║ )⍲ ║ _! ║ +⌹ ║         ║
║ `◊ ║ 1¨ ║ 2¯ ║ 3< ║ 4≤ ║ 5= ║ 6≥ ║ 7> ║ 8≠ ║ 9∨ ║ 0∧ ║ -× ║ =÷ ║ BACKSP  ║
╠════╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦══════╣
║       ║ Q  ║ W⍹ ║ E⍷ ║ R  ║ T⍨ ║ Y¥ ║ U  ║ I⍸ ║ O⍥ ║ P⍣ ║ {⍞ ║ }⍬ ║  |⊣  ║
║  TAB  ║ q? ║ w⍵ ║ e∈ ║ r⍴ ║ t∼ ║ y↑ ║ u↓ ║ i⍳ ║ o○ ║ p⋆ ║ [← ║ ]→ ║  \⊢  ║
╠═══════╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩══════╣
║ (CAPS   ║ A⍶ ║ S  ║ D  ║ F  ║ G  ║ H  ║ J⍤ ║ K  ║ L⌷ ║ :≡ ║ "≢ ║         ║
║  LOCK)  ║ a⍺ ║ s⌈ ║ d⌊ ║ f_ ║ g∇ ║ h∆ ║ j∘ ║ k' ║ l⎕ ║ ;⍎ ║ '⍕ ║ RETURN  ║
╠═════════╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═════════╣
║             ║ Z  ║ Xχ ║ C¢ ║ V  ║ B£ ║ N  ║ M  ║ <⍪ ║ >⍙ ║ ?⍠ ║          ║
║  SHIFT      ║ z⊂ ║ x⊃ ║ c∩ ║ v∪ ║ b⊥ ║ n⊤ ║ m| ║ ,⍝ ║ .⍀ ║ /⌿ ║  SHIFT   ║
╚═════════════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩══════════╝

The second physical layout, based on the international keyboard layout pc105
is the following, shown as keyboard2.txt

PC105 International standard Keyboard
=====================================
╔════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════════════╗
║ ~  ║ !⌶ ║ @⍫ ║ #⍒ ║ $⍋ ║ %⌽ ║ ^⍉ ║ &⊖ ║ *⍟ ║ (⍱ ║ )⍲ ║ _! ║ +⌹ ║            ║
║ `◊ ║ 1¨ ║ 2¯ ║ 3< ║ 4≤ ║ 5= ║ 6≥ ║ 7> ║ 8≠ ║ 9∨ ║ 0∧ ║ -× ║ =÷ ║ BACKSP     ║
╠════╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═╩══╦═════════╣
║       ║ Q  ║ W⍹ ║ E⍷ ║ R  ║ T⍨ ║ Y¥ ║ U  ║ I⍸ ║ O⍥ ║ P⍣ ║ {⍞ ║ }⍬ ║         ║
║  TAB  ║ q? ║ w⍵ ║ e∈ ║ r⍴ ║ t∼ ║ y↑ ║ u↓ ║ i⍳ ║ o○ ║ p⋆ ║ [← ║ ]→ ║ RETURN  ║
╠═══════╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╦══╩═╗       ║
║ (CAPS   ║ A⍶ ║ S  ║ D  ║ F  ║ G  ║ H  ║ J⍤ ║ K⌸ ║ L⌷ ║ :≡ ║ "≢ ║ |⊣ ║       ║
║  LOCK)  ║ a⍺ ║ s⌈ ║ d⌊ ║ f_ ║ g∇ ║ h∆ ║ j∘ ║ k' ║ l⎕ ║ ;⍎ ║ '⍕ ║ \⊢ ║       ║
╠════════╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩═══╦╩════╩═══════╣
║        ║ < ¦║ Z  ║ Xχ ║ C¢ ║ V  ║ B£ ║ N  ║ M  ║ <⍪ ║ >⍙ ║ ?⍠ ║             ║
║  SHIFT ║ > °║ z⊂ ║ x⊃ ║ c∩ ║ v∪ ║ b⊥ ║ n⊤ ║ m| ║ ,⍝ ║ .⍀ ║ /⌿ ║  SHIFT      ║
╚════════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩════╩═════════════╝

The 'preference' file will have a parameter setting to select one or other
layout. More about this later.


2.0 The preferences file(s)
===========================

2.1  Introduction
=================
The 'preferences' files contain parameters settings that control the behavior
of the GNU APL interpreter. Most of the setting can also be controlled by
corresponding command line options, but for most settings it is more convenient
to specify them once in one of the preferences files than by command line
options in every invocation of GNU APL.

The settings will allow you to:

    o   set text and background colors,
    o   assign directories and workspace locations,
    o   location of logs and history file(s), and
    o   other operational parameters.


The 'preferences' file should reside:

 (1) in directory GNU-APL.d of the system configuration directory. or
 (2) in directory .GNU-APL in the user's home directory.
 (3) in both mentioned directories (see below)

 In both cases the configuration file name within each must be 'preferences'

The system configuration directory is usually for GNU/Linux is /usr/local/etc/
or  /etc. During the setup of GNU-APL (refer to README-2-configuration) you have
the  opportunity to choose a different location. It can be overridden at compile
time by

  (a)  ./configure --sysconfdir=somewhere-else
  (b)  ./configure --sysconfdir=/home(yourlogon)/.GNU-APL


2.2 Local version of preferences.
=================================
To create your own preference file, create the following directory.

     /home(yourlogon)/.gnu-apl

copy the system installed /usr/local/etc/gnu-apl.d  to

     /home(yourlogon)/.gnu-apl


If both your own preference file and the "gnu-apl.d" are present
in their respective directories then the local copy overrides
the settings common to both files.

Command line options take precedence over settings made in any of these files.

The initial content of this 'preference. file contains a commented list of all
possible settings. You should not remove parameter setting lines but rather
comment or uncomment them.

The balance of this README-9 file describes the parameter setting for GNU-APL.

3.0   WELCOME MESSAGE
=====================
By default GNU-APL displays a welcome message on start-up.
Usually you will set it once and forget about it.

The corresponding command line option for no welcome message is --silent.

The default setting in the preferences file(s) is:
#
  Welcome       Yes     (default)
# Welcome       No
#


3.1   OUTPUT COLORING
======================
The default GNU-APL configuration as delivered, is tailored for terminals
displaying a white background. The background colors that APL will use can be
overwritten.

There are options to switch to black background, to no colors,
or to even allow coloring of GNU-APL displayed output.

Output coloring will cause problems when, for example:

 (a) you run GNU APL as script
 (b) you use a black background
 (c) you run GNU APL from emacs
 (d) you run GNU APL from a different terminal than color xterm

In case (a) you should use the --script command line option and
leave the Color setting as defaulted (see #2 below).

In cases (b), (c), and (d) you can uncomment the 'Color No' line below.
This only affects the initial state of output coloring; you can
re-enable colors later with APL command ]XTERM ON.

The corresponding command line options are --Color and --noColor

If your terminal does not understand the ANSI escape sequences,
or if you prefer not to provide escape sequences, then you can set the
color parameter to CURSES. and set color numbers to escape sequences as shown
below.  This setting  requires that certain environment variables (e.g. TERM)
are set properly and that your system's terminfo database contains correct
terminal type definitions for  your choice.

The default setting in the preferences file(s) is:
#
  Color         ANSI (default)
# Color         CURSES
# Color         No
#


After starting APL you may want to disable coloring initially, but switch
to curses the command ]COLOR  can be given later on. you can enter the
color command twice:

        ]color
        ]COLOR ON
        ]color off
        ]color
        ]COLOR/XTERM OFF


3.2  GNU-APL Terminal handling
==============================
GNU-APL has one input and 4 output channels called CIN, COUT, CERR, and UERR

 -  CIN  is the input channel and output. It echos the input typed by the user,
 -  COUT is the normal output of the APL interpreter,
 -  CERR is additional error information, in particular logging.
 -  UERR is output of the APL interpreter containing error messages,

CIN, COUT, and UERR write to default stdout while CERR writes to stderr.
Normally stdout and stderr are both displayed on the same terminal,
but output redirection as shown can make a difference. An example
of CERR redirection is:

           apl 2>MyErrorLog.txt


When the interpreter changes from one output channel to another, for
instance from CIN to COUT after the user has entered a line, then an
escape sequence (actually, any short sequence of characters) is sent
to the real output channel (i,e. stdout or stderr). The new channel
determines which sequence is sent:

 -  CIN:   CIN-SEQUENCE  CLEAR-EOL
 -  COUT:  COUT-SEQUENCE CLEAR-EOL
 -  CERR:  CERR-SEQUENCE CLEAR-EOL
 - UCERR:  UERR-SEQUENCE CLEAR-EOL



3.3   OUTPUT COLOR ESCAPE SEQUENCES FOR ANSI TERMINALS
======================================================

Output coloring is implemented as described below,
When the interpreter exists, then the sequence

        RESET-SEQUENCE CLEAR-EOL

is sent to the terminal to cause it to set its the display colors
to their initial state.

The reason for sending CLEAR-EOL (i.e. clear to end of line) is to color
the entire next line not only the chars printed on the next line.

Unfortunately it is difficult, if not impossible, to read the current
color setting from the terminal. Therefore the following is assumed:

GNU-APL is started in a color xterm with white background".

Color xterm is a VT100 (or ANSI) compatible terminal emulation.
If this assumption is correct, then everything should be fine. Otherwise
you may want to change the escape sequence sent to the terminal.

The numbers below are the hexadecimal values of the bytes sent to the terminal;
27 (hexadecimal 1b) is the escape character, for example. In order to
change some or all sequences, uncomment the corresponding line
and change the hex numbers (most likely the columns background
and foreground).  Each sequence can be up to 20 characters long.
By the way  // refers to the start of comments placed to the right
of the terminal control sequence. The octothorpe (#) is the
character placed at the left margin.

The default setting in the preferences file(s) is:
#
#               VT100:          foreground        background
#                               color    |        |    color
#                                        V        V
# //                    ESC  [  0  ;  3 fg  ;  4 bg  m
# CIN-SEQUENCE           1b 5b 30 3b 33 30 3b 34 37 6d    // ESC [0;30;47m
# COUT-SEQUENCE          1b 5b 30 3b 33 30 3b 34 38 6d    // ESC [0;30;48m
# CERR-SEQUENCE          1b 5b 30 3b 33 35 3b 34 38 6d    // ESC [0;35;48m
# UERR-SEQUENCE          1b 5b 30 3b 33 35 3b 34 38 6d    // ESC [0;35;48m
# RESET-SEQUENCE         1b 5b 30 3b 33 39 3b 34 39 6d    // ESC [0;39;49m
# CLEAR-EOL-SEQUENCE     1b 5b 4B                         // ESC [K
# CLEAR-EOS-SEQUENCE     1b 5b 4A                         // ESC [J
#
# On a black background (still assuming VT100 so that the CLEAR-EOL-SEQUENCE
# does not need to be re-defined), the following may be more suitable:
#
# CIN-SEQUENCE           1b 5b 30 3b 33 32 3b 34 30 6d    // ESC [0;32;40m
# COUT-SEQUENCE          1b 5b 30 3b 33 37 3b 34 30 6d    // ESC [0;37;40m
# CERR-SEQUENCE          1b 5b 30 3b 33 31 3b 34 30 6d    // ESC [0;31;40m
# UERR-SEQUENCE          1b 5b 30 3b 33 31 3b 34 30 6d    // ESC [0;31;40m
# RESET-SEQUENCE         1b 5b 30 3b 33 37 3b 34 30 6d    // ESC [0;37;48m
#
#
Since all lines are commented out, the ESC sequences assumed by the interpreter
are used. The lines are only shown as template the ESC sequences of the actual
terminal.


3.4   OUTPUT COLOR NUMBER FOR CURSES
====================================
There is second way of specifying colors that uses the curses library.
Instead of specifying the escape sequences sent to the terminal you
only need to specify the colors wanted and curses will provide the escape
sequences needed.

The default setting in the preferences file(s) is:
# Numbers for colors seem to be (nota bene: the author is color-blind):
#
# 0: black
# 1: blue
# 2: green
# 3: cyan
# 4: red
# 5: magenta
# 6: yellow
# 7: white
#
# The colors are specified as numbers like this:
#
# CIN-FOREGROUND  0
# CIN-BACKGROUND  7
# COUT-FOREGROUND 2
# COUT-BACKGROUND 7
# CERR-FOREGROUND 5
# CERR-BACKGROUND 8
# UERR-FOREGROUND 5
# UERR-BACKGROUND 8
#
# or, for dark background:
#
# CIN-FOREGROUND  2
# CIN-BACKGROUND  0
# COUT-FOREGROUND 7
# COUT-BACKGROUND 0
# CERR-FOREGROUND 5
# CERR-BACKGROUND 0
# UERR-FOREGROUND 5
# UERR-BACKGROUND 0
#

Do not mix the two methods (escape sequences vs. color numbers).
If they are mixed then the last entry processed in this file determines
which method will be used. Also, the numbers for colors are different
in each method.


3.5   INPUT ESC SEQUENCES
=========================

Below is a brief explanation of how you can configure the ESC (escape or other)
sequence sent by the terminal's  cursor-up,  cursor-down, cursor-left,
cursor-right, Home, End, Ins, and Del keys.

The sequences can be set explicitly (in the following) or via CURSES
The latter (CURSES) may fail to work because the sequences reported by
CURSES may be different from the sequences sent by the keyboard.

The default setting in the preferences file(s) is:
#
  Keyboard      NOCURSES (default)
# Keyboard      CURSES
#
# KEY-CURSOR-UP          1b 5b 41
# KEY-CURSOR-DOWN        1b 5b 42
# KEY-CURSOR-RIGHT       1b 5b 43
# KEY-CURSOR-LEFT        1b 5b 44
# KEY-CURSOR-END         1b 5b 46
# KEY-CURSOR-HOME        1b 5b 48
# KEY-INSMODE            1b 5b 32 7e
# KEY-DELETE             1b 5b 33 7e
#


3.6   SHARED VARIABLES
======================
Shared variables are perhaps a feature with which you may not be familiar.
To work with certain software packages on the host computer, your program
must follow a discipline. The variables involved with this discipline are
listed below.

Shared variables are represented by:
offer to share          (⎕SVO),
share var retraction    (⎕SVR),
shared variable Control (⎕SVC),
shared variable Query   (⎕SVQ),
shared variable State   (⎕SVS)

Using 'Shared variables' starts (forks) an independent helper process (APserver)
to communicate with other APL processors.

If you do not need all the above functions then you can (and should) prevent
accidental starting of the APserver by setting SharedVars to Disabled. If
SharedVars are disabled  then GNU APL starts a little faster and, of course,
⎕SVO and friends won't work.

The default setting in the preferences file(s) is:
# The corresponding command line options are --SV and --noSV
#
  SharedVars    Enabled     (default)
# SharedVars    Disabled



3.7   LOGGING FACILITIES
=========================
By default, dynamic logging is disabled and the following settings have no
effect.

Logging is a facility that is occasionally used for debugging purposes. As
a regular user, you should have no requirement to make use of dynamic logging.

To enable dynamic logging, you must recompile the interpreter,specifying
dynamic logging. The following three steps are required.

  ./configure DYNAMIC_LOG_WANTED=yes <... other configure options>
   make
   make install (or try: src/apl)

Otherwise you can specify the Logging facilities (numbered 1-43 or more)
that can be enabled when the APL interpreter starts, This option can
be used several times.

Checkout the GNU-APL command ]LOG for available logging facilities

The corresponding command line option is -l <num>

 Logging 1
 Logging 2
 ...
 Logging 37


3.7    APL LIBRARIES
====================

GNU-APL uses library numbers from 0 to 9 in commands )LOAD, )SAVE, and )COPY,
library 0, if enabled (see below) refers to our own collection of apl
workspaces.

For
example 1:

 )LOAD 1 workspace

example 2:
  Interpreter commands )IN and )OUT use library number 0 implicitly;
  )LOAD, )SAVE, and )COPY use  library number 0 implicitly when no
  library number is given.

WARNING: Each library(directory) assigned to LIBREF-0 must be unshared and
unique.

For example, issuing the  ")CONTINUE" command, results in storing the CONTINUE
workspace therein. Storing CONTINUE will overwrite the previously one. Sharing
the default LIBREF-0 library among different users will likely to have
very undesirable effects.

Within the preferences file, the directories corresponding to the
library numbers can be configured as shown below.

Library numbers 3, 4, and 5 are used (and often overridden!) to store libraries
that are shipped with GNU APL. )SAVEing or )DUMPing workspaces into these
directories is therefore a bad idea.

If GNU APL is used by different programmers on the same machine, then the
following scheme for library reference numbers is recommended:

0  for workspaces that are only accessible by one user (or, in GNU/Linux terms,
   by the owner of the file), This directory typically exists somewhere below
   $HOME.

1  for workspaces that are only accessible by the group (normally the GNU/Linux
   group to which the user belongs).

2  for workspaces that are readable by every user on the machine.

In other words: the library numbers 0, 1, and 2 correspond to the 'owner',
'group', and 'all' permissions of the files respectively. However,
GNU APL does not set these permissions based on the library numbers (because
all this is only a recommended convention), and the users or group members
are responsible for setting permissions on workspace files or directories.

For GNU/Linux machines that are only used by a single user, the user may
set up the directories libraries 0-2 and 6-9 as needed.

The default setting in the preferences file(s) reflects the above scheme
(although commented out) and only sets up the directories for libraries that
are installed by GNU APL itself. For example (details may vary due to
./configure options):
#
# LIBREF-0 /home/xyz/my-own-libs
# LIBREF-1 /home/xyz/my-group-libs
# LIBREF-2 /group/abc/other-libs
  LIBREF-3 /usr/local/lib/apl/wslib3
  LIBREF-4 /usr/local/lib/apl/wslib4
  LIBREF-5 /usr/local/lib/apl/wslib5
# LIBREF-6 /usr/lib/gnu-apl/lib-6
# LIBREF-7 /usr/lib/gnu-apl/lib-7
# LIBREF-8 /usr/lib/gnu-apl/lib-8
# LIBREF-9 /usr/lib/gnu-apl/lib-9
#

3.8   READLINE HISTORY PARAMETERS
=================================

GNU APL can provide a history of lines entered by the user in immediate
execution mode and ∇-edit mode.

As shown below, the number of history lines and the location of the history
file can be configured. Some users prefer to have only one history file (and
in that case $HOME/.config/gnu-apl/apl.history might be a suitable file name).

Other users prefer to have a history file in the current directory so that they
can work in different APL projects in parallel and have separate histories,
one for each project. In that case, .apl.history is a better choice for the
file name, because the file is hidden and relative. This is also the
default in the poreference file(s):

READLINE_HISTORY_LEN  500
READLINE_HISTORY_PATH .apl.history


The history can serve two purposes: to recall lines that were previously
entered and to list what was recently done (with the apl )HISTORY command).
For the latter purpose it is normally convenient to show the new ⎕CR of a
function  that was edited instead of the command that started the editor.
The following  parameter controls whether the editor command (like ∇foo )
or the new ⎕CR of the function shall be inserted into the history.

3.9   EDITOR OPTIONS
====================
GNU-APL comes with a built-in editor. The following setting controls which
of the lines that were entered in function editing mode are being inserted
into the history.

The default ('Modified') line setting causes only modified lines to be inserted.
With that setting, one can cut-and-paste from a history file into an
interactive session in order to 'redo' a function modification. The 'Always'
setting restores the edited function regardless of its current state. The
'Never' setting is useful for automated test scripts because it avoids
redundancy in the log files produced.

was opened for editing, but not changed and the new ⎕CR if the function was
changed.

The default setting in the preferences file(s) is:
#
# NABLA-TO-HISTORY  Never
  NABLA-TO-HISTORY  Modified (default)
# NABLA-TO-HISTORY  Always
#


3.10   BACKUP OPERATIONS
========================
In general, if one is modifying a workspace, it is best to load it and
immediately resave it under a new name. The GNU-APL options available are to
create a backup before a )SAVE or )DUMP WORKSPACE command.
The workspace created by )CONTINUE is saved, but not backed up.

The default setting in the preferences file(s) is:
#
BACKUP_BEFORE_SAVE  yes
#

To recover a backup workspace, refer to the LIBREF-0 option chosen
Change to the directory indicated. Therein you will see the workspace
you were using and the same workspace with a .bak  appended
example: consider a recovery action for the 'meta' workspace
In the directory referred to by LIBREF-0 you would note

    meta.xml   meta.xml.bak

For example,  delete the meta.xml or rename it to something else.
Restore the original  meta.xml  rename the meta.xml.bak to meta.xml


3.11    KEYBOARD LAYOUT
=======================
GNU APL assumes a particular layout of your keyboard (and assumes that you
do your best to obtain that layout). That assumed layout is shown when you
give the ]KEYB command.

If your physical keyboard layout differs from the assumed keyboard for some
reason, then the ]KEYB command will show the wrong layout. You can correct
this difference providing your own keyboard file which (when specified) is
shown by the

     ]KEYB command instead of the assumed layout.

You can choose between one of the files called 'keyboard1.txt' or keyboard2.txt.
If your computer has a different keyboard layout, you may create your own
version as keyboard.txt and revise the parameter as shown in the following:

#
# KEYBOARD_LAYOUT_FILE  /etc/gnu-apl.d/keyboard1.txt
#

12.0  Abnormal Termination
==========================

Normally you exit GNU APL by issuing the command )OFF. Hitting ^D
(aka. end-of-input) once can be used to end the execution of most other
programs, but has no effect in GNU APL.

You can make GNU APL exit after a number of consecutive ^Ds  by specifying
a (small) positive number as shown below Note that the interpreter will always
exit if a large number of ^Ds (or EOFs) are read-in in rapid succession.
NB: ^Ds may exist within a script and need not be entered via the keyboard.
Setting the value to zero establishes the system default.

#CONTROL-Ds-TO-EXIT 7
 CONTROL-Ds-TO-EXIT 0

13.0    Default Print Width
===========================

GNU-APL defaults the ⎕PW to 80

If the terminal that you normally use has fewer or more columns, then you
may want to specify a different initial value for ⎕PW below. A further option
is the Windows Change (WINCH setting).

With the WINCH-Setting option, on startup you can cause the Window Change
(WINCH) signal (which is sent, for example, if the size of a window is
changed) to set ⎕PW to the terminal width setting contained in the WINCH signal.

The intended effect is that re-sizing of the terminal window will cause GNU-APL
to adapt itself to the new window size. This appears to work on  GNU/Linux but
may not work on other platforms! USE AT YOUR OWN RISK.

# INITIAL-⎕PW 80
# WINCH-SETS-⎕PW  Yes



14.0  Security Settings
=======================

Under certain circumstances, for example if GNU APL is used as a CGI script
for publicly accessible web pages, it may be desireable to disable certain
capabilities that could otherwise be abused to access system resources via
the GNU APL capabilities.

The following lines show examples of GNU APL capabilities that can be
disabled. The security settings are put into profile [1] which means that
they only have an effect if:

 (1) GNU APL was ./configured with SECURITY_LEVEL_WANTED=1, and
 (2) the profile (i.e the -p command line option) with which GNU APL was
     started matches the profile for which the setting was made (if any)

If a disabled capability is being used then it will throw a DOMAIN_ERROR
and the )MORE command will indicate a security violation. For example:

#
Profile 1
  disable_Quad_SQL          yes    # disable ⎕SQL
  disable_Quad_FIO          no     # do not disable ⎕FIO
  disable_native_functions  yes    # disable A ⎕FX B (native fnctions)