GNU APL 1.7 README (copy)

README

			    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-1-prerequisites

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++

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.

README-2-configure

The APL interpreter can be configured by means of ./configure options (see
also file INSTALL in this directory). In addition to the standard options
provided by ./configure (that are described in file INSTALL),
the following GNU APL specific ./configure options are recognized:

--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 standard C++ programs.

--with-libapl
   This option builds GNU APL as a shared library (libapl.so) rather than an
   executable. This option is often combined with option --with-android even
   though the library is not built for Android, but because the executable
   that is linked with libapl.so) has its own I/O channels.

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

--with-postgresql=[ARG]
   Build the native function for SQL using PostgreSQL. ARG may provide a
   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=0 disables both macros; this gives the maximum
   performance, but at the same time bears the risk that internal errors
   of the APL interpreter are not detected. Example:

    ./configure ASSERT_LEVEL_WANTED=2


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
      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 to be used.
   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 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. Example:

    ./configure DYNAMIC_LOG_WANTED=yes


MAKE_J
    Set the -j command line option for make that shall be used when GNU APL
    is being built. The default is 4 which causes make to be called
    as make -j 4. In that case up to 4 files can be compiled in parallel which
    is good when your build machine has 4 cores and sufficient memory. If the
    machine has fewer cores, then -j 4 normally does no harm, except if the
    machine is severly limited, like, for instance, a virtual machine with
    little memory. In that case MAKE_J=1 is a better choice. On the other
    side, if your machine has more cores then larger values for MAKE_J will
    speed up the build process. Example:

    ./configure MAKE_J=8

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 -pg flags to CXXFLAGS and LDFLAGS and that
   enables support for gprof profiling of the apl interpreter. Example:

    ./configure GPROF_WANTED=yes

VISIBLE_MARKERS_WANTED=yes
   GNU APL uses a handful of Unicode characters as internal pad characters
   when formatting 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, characters ⁰, ¹, ... are used
   as internal pad (and these characters will display as spaces when displayed.

    ./configure VISIBLE_MARKERS_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.

README-3-keyboard

In addition to ASCII characters found on most keyboards,
APL needs additional "APL characters". In this file
we explain 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 what you type on your keyboard) on 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 idea what a keyboard is, nor is
it concerned with fonts and the like on output. All it 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 bytes 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 look like. This includes
all APL characters used by GNU APL. Normally Unicode characters are UTF8 encoded
when transmitted over serial lines, files descriptors, in IP packets, or when
displayed on web pages.

There are many advantages of 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 gives
  you 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 standard way of setting things up for GNU APL. The rest of this
file describes a number of different methods enabling APL characters on your
machine that have made GNU APL work on most (but nor all) machines and
operating systems around. These methods may conflict with each other, so use
only one of them at a time.

GNU APL comes with 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 is on the input
side (from the keyboard to GNU APL). The output side is most often already
working (thanks to Unicode).

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

Initially 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 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 layout,
currently Dirk, Dyalog-Keyboard, old-Keyboard, OS-X-Keyboard, 
Unicomp-Keyboard, and WASD-Keyboard.

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

    support-files/apl.xmodmap

is the generic name (and no file with that name exist anymore) while

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

are the different instances of .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 also that not all support files are fully tested - 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 in is quite simple to make your keyboard produce
APL characters.

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

The file support-files/apl.xmodmap (that comes with GNU APL) provides such
a mapping; the normal keys produce ASCII characters while the Alt
(and Shift-Alt) plane 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/apl.xmodmap

After that your keyboard will produce APL characters when the "Alt" key is
held down. The keyboard layout defined in file "apl.xmodmap" is roughly this:

╔════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦════╦═════════╗
║ ~  ║ !⌶ ║ @⍫ ║ #⍒ ║ $⍋ ║ %⌽ ║ ^⍉ ║ &⊖ ║ *⍟ ║ (⍱ ║ )⍲ ║ _! ║ +⌹ ║         ║
║ `◊ ║ 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 files support-files/keyboard.txt and support-files/keyboard1.txt contain
this mapping 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


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/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 like:

    $ xkbcomp support-files/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 needs the Alt keys for other purposes.

More recent GNU/Linux versions come with a working APL keymap already;
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/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.

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, which lets you
pick APL characters from a menu inside vim is here:

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


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

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

    https://github.com/TieDyedDevil/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 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 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_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 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 just wrong for APL before running xmodmap.


10.2 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.3 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


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

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

The same is true 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 machine A, then make sure 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 om its
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 ./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 will 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 get a quote).
b. www.unicomp.com seems to have APL keyboards every now and then.
c. www.wasdkeyboards.com

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

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

README-4-compliance

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)

* 3 ⎕TF        (⎕TF with CDR format)

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

* 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

README-5-WINDOWS

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 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.

README-6-porting

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
alphabetical order of the OSs)

===============================================================================
====									   ====
====			    CYGWIN 5.1 (Windows)			   ====
====									   ====
===============================================================================

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


===============================================================================
====									   ====
====			    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'


===============================================================================
====									   ====
====			    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).

README-7-more-info

If you have reached this file, then GNU APL is hopefully running well for
you and 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 on the web. 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

README-8-parallel

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.

INSTALL

Installation Instructions
*************************

Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
2006, 2007, 2008, 2009 Free Software Foundation, Inc.

   Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without warranty of any kind.

Basic Installation
==================

   Briefly, the shell commands `./configure; make; make install' should
configure, build, and install this package.  The following
more-detailed instructions are generic; see the `README' file for
instructions specific to this package.  Some packages provide this
`INSTALL' file but do not implement all of the features documented
below.  The lack of an optional feature in a given package is not
necessarily a bug.  More recommendations for GNU packages can be found
in *note Makefile Conventions: (standards)Makefile Conventions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').

   It can also use an optional file (typically called `config.cache'
and enabled with `--cache-file=config.cache' or simply `-C') that saves
the results of its tests to speed up reconfiguring.  Caching is
disabled by default to prevent problems with accidental use of stale
cache files.

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If you are using the cache, and at
some point `config.cache' contains results you don't want to keep, you
may remove or edit it.

   The file `configure.ac' (or `configure.in') is used to create
`configure' by a program called `autoconf'.  You need `configure.ac' if
you want to change it or regenerate `configure' using a newer version
of `autoconf'.

   The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.

     Running `configure' might take a while.  While running, it prints
     some messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package, generally using the just-built uninstalled binaries.

  4. Type `make install' to install the programs and any data files and
     documentation.  When installing into a prefix owned by root, it is
     recommended that the package be configured and built as a regular
     user, and only the `make install' phase executed with root
     privileges.

  5. Optionally, type `make installcheck' to repeat any self-tests, but
     this time using the binaries in their final installed location.
     This target does not install anything.  Running this target as a
     regular user, particularly if the prior `make install' required
     root privileges, verifies that the installation completed
     correctly.

  6. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

  7. Often, you can also type `make uninstall' to remove the installed
     files again.  In practice, not all packages have tested that
     uninstallation works correctly, even though it is required by the
     GNU Coding Standards.

  8. Some packages, particularly those that use Automake, provide `make
     distcheck', which can by used by developers to test that all other
     targets like `make install' and `make uninstall' work correctly.
     This target is generally not run by end users.

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  Run `./configure --help'
for details on some of the pertinent environment variables.

   You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment.  Here
is an example:

     ./configure CC=c99 CFLAGS=-g LIBS=-lposix

   *Note Defining Variables::, for more details.

Compiling For Multiple Architectures
====================================

   You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you can use GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.  This
is known as a "VPATH" build.

   With a non-GNU `make', it is safer to compile the package for one
architecture at a time in the source code directory.  After you have
installed the package for one architecture, use `make distclean' before
reconfiguring for another architecture.

   On MacOS X 10.5 and later systems, you can create libraries and
executables that work on multiple system types--known as "fat" or
"universal" binaries--by specifying multiple `-arch' options to the
compiler but only a single `-arch' option to the preprocessor.  Like
this:

     ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                 CPP="gcc -E" CXXCPP="g++ -E"

   This is not guaranteed to produce working output in all cases, you
may have to build one architecture at a time and combine the results
using the `lipo' tool if you have problems.

Installation Names
==================

   By default, `make install' installs the package's commands under
`/usr/local/bin', include files under `/usr/local/include', etc.  You
can specify an installation prefix other than `/usr/local' by giving
`configure' the option `--prefix=PREFIX', where PREFIX must be an
absolute file name.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
pass the option `--exec-prefix=PREFIX' to `configure', the package uses
PREFIX as the prefix for installing programs and libraries.
Documentation and other data files still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=DIR' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.  In general, the
default for these options is expressed in terms of `${prefix}', so that
specifying just `--prefix' will affect all of the other directory
specifications that were not explicitly provided.

   The most portable way to affect installation locations is to pass the
correct locations to `configure'; however, many packages provide one or
both of the following shortcuts of passing variable assignments to the
`make install' command line to change installation locations without
having to reconfigure or recompile.

   The first method involves providing an override variable for each
affected directory.  For example, `make install
prefix=/alternate/directory' will choose an alternate location for all
directory configuration variables that were expressed in terms of
`${prefix}'.  Any directories that were specified during `configure',
but not in terms of `${prefix}', must each be overridden at install
time for the entire installation to be relocated.  The approach of
makefile variable overrides for each directory variable is required by
the GNU Coding Standards, and ideally causes no recompilation.
However, some platforms have known limitations with the semantics of
shared libraries that end up requiring recompilation when using this
method, particularly noticeable in packages that use GNU Libtool.

   The second method involves providing the `DESTDIR' variable.  For
example, `make install DESTDIR=/alternate/directory' will prepend
`/alternate/directory' before all installation names.  The approach of
`DESTDIR' overrides is not required by the GNU Coding Standards, and
does not work on platforms that have drive letters.  On the other hand,
it does better at avoiding recompilation issues, and works well even
when some directory options were not specified in terms of `${prefix}'
at `configure' time.

Optional Features
=================

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

   Some packages offer the ability to configure how verbose the
execution of `make' will be.  For these packages, running `./configure
--enable-silent-rules' sets the default to minimal output, which can be
overridden with `make V=1'; while running `./configure
--disable-silent-rules' sets the default to verbose, which can be
overridden with `make V=0'.

Particular systems
==================

   On HP-UX, the default C compiler is not ANSI C compatible.  If GNU
CC is not installed, it is recommended to use the following options in
order to use an ANSI C compiler:

     ./configure CC="cc -Ae -D_XOPEN_SOURCE=500"

and if that doesn't work, install pre-built binaries of GCC for HP-UX.

   On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
parse its `<wchar.h>' header file.  The option `-nodtk' can be used as
a workaround.  If GNU CC is not installed, it is therefore recommended
to try

     ./configure CC="cc"

and if that doesn't work, try

     ./configure CC="cc -nodtk"

   On Solaris, don't put `/usr/ucb' early in your `PATH'.  This
directory contains several dysfunctional programs; working variants of
these programs are available in `/usr/bin'.  So, if you need `/usr/ucb'
in your `PATH', put it _after_ `/usr/bin'.

   On Haiku, software installed for all users goes in `/boot/common',
not `/usr/local'.  It is recommended to use the following options:

     ./configure --prefix=/boot/common

Specifying the System Type
==========================

   There may be some features `configure' cannot figure out
automatically, but needs to determine by the type of machine the package
will run on.  Usually, assuming the package is built to be run on the
_same_ architectures, `configure' can figure that out, but if it prints
a message saying it cannot guess the machine type, give it the
`--build=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:

     CPU-COMPANY-SYSTEM

where SYSTEM can have one of these forms:

     OS
     KERNEL-OS

   See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the machine type.

   If you are _building_ compiler tools for cross-compiling, you should
use the option `--target=TYPE' to select the type of system they will
produce code for.

   If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Defining Variables
==================

   Variables not defined in a site shell script can be set in the
environment passed to `configure'.  However, some packages may run
configure again during the build, and the customized values of these
variables may be lost.  In order to avoid this problem, you should set
them in the `configure' command line, using `VAR=value'.  For example:

     ./configure CC=/usr/local2/bin/gcc

causes the specified `gcc' to be used as the C compiler (unless it is
overridden in the site shell script).

Unfortunately, this technique does not work for `CONFIG_SHELL' due to
an Autoconf bug.  Until the bug is fixed you can use this workaround:

     CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash

`configure' Invocation
======================

   `configure' recognizes the following options to control how it
operates.

`--help'
`-h'
     Print a summary of all of the options to `configure', and exit.

`--help=short'
`--help=recursive'
     Print a summary of the options unique to this package's
     `configure', and exit.  The `short' variant lists options used
     only in the top level, while the `recursive' variant lists options
     also present in any nested packages.

`--version'
`-V'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--cache-file=FILE'
     Enable the cache: use and save the results of the tests in FILE,
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
     disable caching.

`--config-cache'
`-C'
     Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--prefix=DIR'
     Use DIR as the installation prefix.  *note Installation Names::
     for more details, including other options available for fine-tuning
     the installation locations.

`--no-create'
`-n'
     Run the configure checks, but stop before creating any output
     files.

`configure' also accepts some other, not widely useful, options.  Run
`configure --help' for more details.