11 Command Line Reference

Here we present the syntax of the Wafl command line interpreter. This document is generated automatically. To get the current command line options, please run:

clwafl -help

11.1 Command Line Options

Usage: 
  to run a program:
    clwafl [<options>] <program-file-name> [<arguments>]

  to run inline source code:
    clwafl [<options>] -code "<source-code>" [-args <arguments>]

  to apply some tools:
    clwafl [<options>] [<program-or-library-file-name>]

where <options> is a space separated list that can contain 
the following options:

  Program arguments and environment:
    -code "<source-code>"
                  Specify the Wafl program code inline, as a part of the
                  command line. Quotes are strongly recommended.
    -args <args>  Specify Wafl program command line arguments.
                  Allowed only if inline source code is used.
    -dir:<app-directory>
                  Specify the application directory.
                  Default is the path of the program file, or '.'.
    -workdir:<working-directory>
                  Specify the working directory.
                  Default is program file path, or '.'.
    -libdir:<lib-directory>
                  Specify a library search directory.
    -lib:<name>:<file>
                  Load Wafl library <file> as parameterized library <name>.
    -env:<env-var-name>=<env-var-value>
                  Define an environment variable.

  Database access:
    -db:<database-driver>:<database-alias>
                  Specify the database driver and database alias.
    -db:<database-alias>
                  Specify the database alias.
    -dbdriver:<database-driver>
                  Specify the database driver.
    -user:<database-connection-username>:<password>
                  Specify the database user and password.
    -user:<database-connection-username>
                  Specify the database user.
    -pwd:<database-connection-password>
                  Specify the database user's password.

  Runtime options:
    -repeat:<n>   Run the program <n> times.
    -memory       Print the memory report.
    -timer        Measure execution time.
    -title:<a-title>
                  Set the title of the console window.
    -nocolors     Disable using terminal ANSI color codes.
    -wait         Wait for a key after execution.

  Optimization and evaluation mode options:
    -stack-std, -stdstack
                  Use standard stack.
    -stack-ext, -extstack
                  Use extendable stack (default).
    -stack-size:<n>
                  Initial stack size in KiB [0-1000000].
                  For extendable stack, the size of the first segment.
                  For standard stack, this is the stack size.
                  The default is 0, which means OS defined.
    -stack-blocksize:<n>
                  Single extendable stack block size in KiB [250-100000].
                  Only applies to extendable stack. The default is 1024KiB.
    -stack-limit:<n>
                  Total stack space limit for all threads together in MiB.
                  Only applies to extendable stack. Range is [0-100000].
                  The default is 0, which means unlimited.
    -stack-threadlimit:<n>
                  Maximum permitted stack size in MiB [0-100000].
                  Only applies to extendable stack.
                  The default is 0, which means unlimited.
    -jit          JIT optimization [experimental].
    -jit-rebuild  JIT optimization with module rebuild [experimental].
    -jit-ast      JIT optimization on AST [experimental].
    -jit-aeg      JIT optimization on AEG [experimental].
    -dis-tailcalls  
                  Disable tail calls optimization.

  Parallelization options:
    -pd, -parallel-disable
                  Disable implicit parallelization (default).
    -pa, -parallel-auto
                  Enable implicit parallelization.
    -ps, -parallel
                  Suggest the implicit parallelization. Like auto,
                  but biased more towards parallelization.
    -pf, -parallel-force
                  Use parallelization wherever possible.

  Debugging and testing options:
    -debug        Use the debug mode.
    -silent-echo  Disable echo output.
    -silent       Disable all console output.
    -options      Print all selected options.
    -msgs         Print the compilation messages.
    -segvcatch    Use `segvcatch` library to catch system signals.
    -nornd        Run without initialization of random number generator.
                  The same random number sequence is generated each time,
                  except when parallel functions are used.
    -short        Print only a short preview of the program result.

  Tools:
    -check        Check whether a program or library is correct.
    -checkdir     Check whether all programs in the current directory
                  are correct.
    -checkdir:<dir>
                  Check whether all programs in <dir> are correct.
    -checkapp     Check whether all programs in the current directory
                  and its subdirectories are correct.
    -checkapp:<dir>
                  Check whether all programs in the directory <dir> 
                  and its subdirectories are correct.
    -parserast    Print the abstract syntax tree generated by parser.
    -parsersrc    Print the source code generated from the AST
    -builderaeg   Print the abs. evaluation graph generated by the builder.
    -buildersrc   Print the 'meta' source code generated from the AEG.
    -doc:<format> Generate documentation based on the program comments.
                  Works for programs and Wafl libraries.
                  Formats include `markdown`, `text` and `text-colors`.
    -doc          Generate documentation. Default format is `text-colors`,
                  but if output is redirected, default is `markdown`.
    -create-ini-file 
                  Generates `wafl.ini` file in the working directory.
    -listlib      List the system library contents.
                  Binary libraries are excluded.
    -listlib:<w>  List the system library elements with names containing <w>,
                  or the content of a binary library with filename <w>.
        ? <w>     Same as `-listlib:<w>`.
        ?? <w>    Same as `-verbose -listlib:<w>`.

  Additional options:
    -help         Print this usage description.
    -version      Print version description.
    -verbose      Print more details on `-listlib`, `-version` and `-memory`.

11.2 Configuration Files

Configuration files are defined at three basic levels:

• Global configuration defines options that apply to all users and all Wafl programs, until overridden. Global configuration is specified in the file C:\ProgramData\wafl.ini for Windows, or /etc/wafl.ini for Linux.

• User configuration defines options that are specific to a user. These can override global options and apply to all programs run by the user, unless overridden by local configuration. User configuration is specified in the file %USERPROFILE%\.wafl.ini (usually C:\Users\<username>\.wafl.ini) for Windows or ${HOME}/.wafl.ini (usually /home/<username>/.wafl.ini) for Linux.

• Local configuration defines options that are specific to an application. They can override global and user configurations. Local configuration is specified in the wafl.ini file in the working directory. It is used only for command line programs.

When a Wafl program is run from the command line, configuration files are processed (global, user and local) and used to set the default values of the program’s options. If an option is explicitly specified using the command-line options, then it overrides the default values set in the configuration files.

Similarly, for non-command-line Wafl programs (like Web service, Jupyter and others) the service configuration file can override some of the more generally defined configuration parameters. For such programs, local configuration files are not used.

Wafl configuration files use the usual ini-file syntax.

[section-name-1]
par-name-1 = value-1
par-name-2 = value-2
# comment

[section-name-2]
par-name-3 = value-1
par-name-4 = value-2
# comment
...

Sections and Parameters

The following sections are defined:

• command-line - defines the parameters that correspond to command line options, and represent their default values;
• jit-g++ - defines the parameters for JIT compilation and linking using g++ tools;
• jit-msvc - defines the parameters for JIT compilation and linking using MS Visual Studio.
• database - defines some default database parameters.

Other sections can be defined in future.

Section command-line

For each command line option -option and parameter -param:value there is a corresponding parameter in the command-line section:

• To define an option -option to be set by default, specify the parameter option = 1.
• To define an option -option to be reset by default, specify the parameter option = 0.
• If there is a set of mutually exclusive options, select the default one option-mode = name (see parallel or stack).
• To define a default parameter value, specify param = value.
• If a parameter can be used multiple times, add -NN to its name. Such parameters are used in a lexical order.

Here is an example configuration for command-line section, with all applicable parameters:

[command-line]
# This section defines the default command line program options.
# For each parameter, the corresponding command line option 
# is specified in the comment.

# DB connection username and password 
# must not be specified in configuration file!

# Set environmet variables 
#   -env:<name>=<value>
env-01 = DATA_PATH = /data
env-02 = MEDIA_PATH = /data/media

# Default system library directory 
# Cannot be overriden by command line options!
# The default is `${WAFL_PATH}/lib`, but if another version
# of the system library is used (e.g. during the development)
# then it can be specified here. 
libdir-system = /dev/Wafl/lib
# Default application library directory 
#   -libdir:<value>
libdir = ~/mywafllibs
# Load a parametrized library by default
#   -lib:<name>:<file>
lib-01 = libOs = myoslib
lib-02 = libDb = mydblib

# Set parallelization mode [auto, disable, suggest, force]
#   -pa, -pd, -ps, -pf
parallel-mode = auto

# Use extendable stack [extendable, standard]
#   -stack-ext, -stack-std
stack-mode = extendable
# Initial steck size in MiB
#   -stack-size:<value>
stack-size = 10
# Size of individual stack blocks in KiB
#   -stack-blocksize:<value>
stack-blocksize = 1000
# Total stack limit for all threads together in GiB
#   -stack-limit:<value>
stack-limit = 0
# Stack limit for individual threads in MiB
#   -stack-threadlimit:<value>
stack-threadlimit = 1000

# Use JIT
#   -jit
jit = 0
# Default JIT mode [aeg, ast]
# NOTE: This option does not turn JIT on!
#   -jit-aeg, -jit-ast
jit-mode = aeg
# Set JIT rebuild by default
# NOTE: This option does not turn JIT on!
#   -jit-rebuild
jit-rebuild = 0

# The other aplicable parameters 
# Please see command line options for details
title = My Wafl command line window title
timer = 0
wait = 0
debug = 0
segvcatch = 0
dis-tailcalls = 0
nornd = 0

Section jit-g++

Here is a complete example, for Ubuntu Linux 24.10, g++ and appropriate Wafl Core:

[jit-g++]
include-path-1 = /home/smalkov/dev/WaflLocal/bld/debug/_install/waflcore/GNU_12.4.0_uxmkfl_x86_64_8_1_CPP20_Debug/include

compiler-options-1 = -std=c++20 -fpic -ldl -shared 
compiler-options-release = -O3 -DNDEBUG

link-options-1 = ~/dev/WaflLocal/bld/debug/_install/waflcore/GNU_12.4.0_uxmkfl_x86_64_8_1_CPP20_Debug/lib/libWaflCore.a;

#keep-source = 1

Please see JIT documentation for details.

Section jit-msvc

Here is a complete example, for VS 2022, Windows 10 and appropriate Wafl Core:

[jit-msvc]
tools-path = C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.42.34433\bin\Hostx64\x64

include-path-1 = C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.42.34433\include
include-path-2 = C:\Program Files (x86)\Windows Kits\10\include\10.0.22621.0\ucrt
include-path-3 = E:\Wafl\bld\vs17_release\_install\waflcore\MSVC_143_win64_AMD64_8_1_CPP20_Release\include

lib-path-1 = C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.42.34433\lib\x64
lib-path-2 = C:\Program Files (x86)\Windows Kits\10\lib\10.0.22621.0\ucrt\x64
lib-path-3 = C:\Program Files (x86)\Windows Kits\10\lib\10.0.22621.0\um\x64
lib-path-4 = E:\Wafl\bld\vs17_release\_install\waflcore\MSVC_143_win64_AMD64_8_1_CPP20_Release\lib

compiler-options-1 = /nologo /std:c++20 /EHsc /Gd /MP
compiler-options-2 = /Fo: "%TEMP%"
compiler-options-3 = /D _WINDLL /D _ITERATOR_DEBUG_LEVEL=0 /D WIN32 /D _WINDOWS /D _WIN32_WINNT=0x0A00
# compiler-options-debug = /MTd /Od /Ob0
compiler-options-release = /MT /O2

link-options-1 = /NOLOGO /DLL /DYNAMICBASE /MACHINE:X64 /LTCG /NOIMPLIB /NOEXP
link-options-2 = libWaflCore.lib 
link-options-3 = kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib oleaut32.lib uuid.lib comdlg32.lib advapi32.lib

#keep-source = 1

Section database

Here is an example:

[database]
# Default database driver, can be overridden by: -dbdriver:<value>
default-driver = Db2v11
# Default database, can be overridden by: -db:<value>
default-db = Test
default-query-type = untyped

Please see Configuration File Database Parameters for details.

11.3 ANSI Control Codes

Wafl supports ANSI console control codes, often referred to as ANSI escape sequences. The control sequences are printed to the console like ordinary text, but allow control of color, font, cursor position and other options.

The Wafl library Console.wlib contains many predefined sequences. It can be used to write more readable Wafl code. For example, the following two code segments generate and output the same result:

"Regular\e[34mBlue\e[0mRegular"

"Regular"
+ con::colorFgBlue + "Blue" + con::resetColor
+ "Regular"

where {
  con = library file 'Console.wlib';
}