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.


