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


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


   CIN_COLOR_WANTED=0
  CERR_COLOR_WANTED=0
  COUT_COLOR_WANTED=0
RESET_COLORS_WANTED=0
   CLEAR_EOL_WANTED=0
   CLEAR_EOL_WANTED=27,4B
   CIN_COLOR_WANTED=27,91,48,59,51,48,59,52,55,109
  CERR_COLOR_WANTED=27,91,48,59,51,53,59,52,56,109
  COUT_COLOR_WANTED=27,91,48,59,51,48,59,52,56,109
RESET_COLORS_WANTED=27,91,48,59,51,56,59,52,56,109
                                   ^^       ^^
   The APL interpreter uses different colors for the cin (standard input),
   cout (standard output) and cerr (standard error) channels. Setting all
   colors to 0 disables color support. Setting some (but not all) colors to 0
   is a bad idea. Setting all colors changes the colors being used to your
   favorite colors. The above numbers are escape sequences for ANSI terminals
   (CERR = red on white background, CIN = black on dark white background, and
   COUT = black on white background on GNU/Linux xterms).

   After every color seqence, an clear to end of line sequence is sent to
   the terminal so that the entire line gets the desired color (otherwise
   only the output itself would be coloured and the rest of the line would
   remain in the background color). Set this to 0 if you disable colors.

  When the interpreter is finished, then the reset colors sequence is sent,
  followed by the clear to end of line sequence. Set this to 0 if you
  disable colors. Example (disable colors):

    ./configure CIN_COLOR_WANTED=0 CERR_COLOR_WANTED=0 COUT_COLOR_WANTED=0 RESET_COLORS_WANTED=0 CLEAR_EOL_WANTED=0


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


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
   If the APL interpreter starts new processes for shared variables (for
   example AP100, AP210, or APnnn) then these processes use the same output
   channels (cout and cerr) as the interpreter, and the garbled output can
   be difficult to read. With PRINT_SEMA_WANTED=yes, a semaphore makes sure
   that output lines from different sources are not mixed. The downside of
   this is a lower performance on output. Example:

    ./configure PRINT_SEMA_WANTED=yes


VALUE_CHECK_WANTED=yes
    There is a macro called CHECK that checks every new APL value for
    consistency. This check helps finding faults in the interpreter, but
    decreases the performance of the interpreter. Example:

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


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

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 VALUE_CHECK_WANTED=yes \
                DYNAMIC_LOG_WANTED=yes \
                ASSERT_LEVEL_WANTED=2  \
                PRINT_SEMA_WANTED=yes

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

    make develop

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


