
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.


