Chapter 35. Common Variables

This is a complete list of the variables that are currently used inside Aap, except the variables specifically used for porting, see Chapter 22, Porting an Application for that.

This list will be extended when more features are being added. To avoid the problem that your own variables interfere with the use of common Aap variables, do not use variable names with only upper case letters. Suggested scheme:

Table 35.1. Naming scheme for variables

$STANDARD_VARIABLEglobal variable defined by Aap
$YourVariableglobal variable used in your recipe(s)
$local_variablelocal variable used in build commands


The following table lists the predefined variables. These types are used:

Aapset by Aap and mostly not changed by the user
confset depending on the configuration of the system, may be modified by the user
userset by the user
autovalue updated when using commands (e.g., :program), may also be appended to by the user

Table 35.2. Standard Variables

nametype  description
$# Aap A single #. OBSOLETE, use $(#)
$$ Aap A single $. OBSOLETE, use $($)
$AAP Aap Command that was used to start Aap, including the Python interpreter used. Example:
    :asroot $AAP install
Note that this can be a command and an argument, e.g.: "/usr/local/bin/python1.5 /usr/local/share/aap/Main.py".
$AAPSYSDIR conf List of system directories to search for startup recipes, modules and tools. Default value is /usr/local/share/aap, although this may be different on some systems. When the directory doesn't exist the default is empty.
$AAPVERSION Aap Version number of Aap. E.g., 31 (version 0.031) or 1003 (version 1.003). Also see $VERSIONSTR.
$AR conf Name of archiver program: combines object files into a static libray.
$ARFLAGS user Arguments for $AR (default: "r" or "/nologo").
$BDIR conf Directory to write build files in. Modified by the :variant command.
$BR Aap A line break.
$BROWSER conf HTML browser to be used for the "view" action for HTML, XML and PHP files. The default value comes from the "BROWSER" environment variable or a list of known browser commands (netscape mozilla konquerer grail iexplore mosaic lynx w3m).
$BUILD_ACTION conf When not empty, specifies the action name to be executed for building. Usually for building a program from object files with a specific tool. A "buildaction" attribute on one of the object files is used before $BUILD_ACTION. See Chapter 30, Customizing Default Tools.
$BUILDDLL_ACTION conf When not empty, specifies the action name to be executed for building a dynamic (shared) library. A "buildaction" attribute on one of the object files should be respected by the action specified with $BUILDDLL_ACTION. See Chapter 30, Customizing Default Tools.
$BUILDLIB_ACTION conf When not empty, specifies the action name to be executed for building a static library. A "buildaction" attribute on one of the object files should be respected by the action specified with $BUILDLIB_ACTION. See Chapter 30, Customizing Default Tools.
$BUNZIP2 conf Program to use for ".bz2" compressed files. Default value is "bunzip2".
$C_COMPILE_ACTION conf When not empty, specifies the action name to be executed for compiling a C file into an object, dllobject, libobject or ltobject file. See Chapter 30, Customizing Default Tools.
$CXX_COMPILE_ACTION conf When not empty, specifies the action name to be executed for compiling a C++ file into an object, dllobject, libobject or ltobject file. See Chapter 30, Customizing Default Tools.
$CACHEPATH conf List of directories to search for cached downloaded files. Default for Unix:

    /var/aap/cache
    ~/.aap/cache
    aap/cache

For MS-Windows, OS/2:

    $HOME/aap/cache
    aap/cache

Directories that don't exist are skipped. When using a relative name, it is relative to the current recipe. Thus the recipe specified with :child dir/main.aap uses a different cache directory. When this variable is set, currently cached files are flushed. Otherwise this only happens when exiting. Thus this command can be used to flush the cache:
    CACHEPATH = $CACHEPATH
$CACHEUPDATE user Timeout after which cached files may be downloaded again. For the possible values see the explanation in the user manual.
$CC conf Command to execute the C compiler (default: "cc").
$CFLAGS user Arguments always used for $CC. NOTE: it's not $CCFLAGS! This is inconsistent, used for historic reasons.
$CHILDDIR Aap In a child recipe: The directory of the child recipe relative to the parent recipe. When using: :child subdir/main.aap $CHILDDIR will be "subdir" in the child recipe.
$CLEANDIRS auto Names of directories that the "clean" target should remove.
$CLEANFILES auto Names of files that the "clean" target should remove. The :program command adds files to this.
$CLEANMOREDIRS user Names of directories that the "cleanmore" target should remove.
$CLEANMOREFILES user Names of files that the "cleanmore" target should remove.
$COMPILE_ACTION conf Obsolete. See $C_COMPILE_ACTION and $CXX_COMPILE_ACTION.
$CONFDIR Aap Sub-directory to install configuration files into. Default value: "etc/".
$CONFMODE Aap Mode to use for installed configuration files. Default value: "0644" (read/write for the user, readable for the group and others).
$CPPFLAGS user Arguments for $CC when compiling sources (not when linking objects). These are raw arguments, not always portable. Use $INCLUDE and $DEFINE when possible.
$CVS conf Cvs program to use. No arguments are allowed. May include spaces. When not set "cvs" is used.
$CVSCMD user Cvs command to use. This overrules $CVS and may include arguments. E.g. "cvs -z 9". Spaces in the program name must be escaped as expected for the shell. When not set $CVS is used.
$CXX conf Command for compiling C++ files
$CXXFLAGS user Arguments always used for $CXX.
$CXXSHLINK conf Name of linker used to combine object files from C++ sources into a shared (dynamic) library. Default value: "$CXX" for Unix, not used for MS-Windows.
$CXXSHLINKFLAGS user Arguments for $CXXSHLINK. Default value: "-shared" for Unix, not used for MS-Windows.
$DATADIR Aap Sub-directory to install data files into. Default value: "share/".
$DATAMODE Aap Mode to use for installed data files. Default value: "0644" (read/write for the user, readable for the group and others).
$DATESTR Aap Date as a string in the form "2002 Month 11". This does not change while Aap is running. Also see $TIMESTR and $GMTIME.
$DEBUG user The kind of debugging to be done. "yes" means debugging is enabled. The variable is not set by default. For an example see the tutorial.
$DEFAULTCHECK Aap Check to use when none is speficied. Defaults to "md5", can be set to "time" or "newer". "time" means that a file is outdated when its timestamp is different from when it was last used. "newer" means a target is outdated when one of the source files has a more recent timestamp. Also see the check attribute.
$DEFER_ACTION_NAME Aap Only available in the commands of an action: the name the action to which the work should be deferred.
$DEFINE user Preprocessor symbols. Used in the same place as $CPPFLAGS. Form: "-DNAME" or "-DNAME=value". The tools will convert this to the argument the compiler actually uses.
$DESTDIR user Directory used to install in a different root directory. Useful for a "fake" install. Also see $PREFIX.
$DISTDIRS Aap Names of directories that should be distributed as a whole. If there is one file in this directory that should not be distributed use $DISTFILES.
$DISTFILES auto Names of files that are used as a source in the recipe and should be distributed. The :program command adds files to this.
$DLLCFLAGS user Extra arguments to compile a C program into a dynamic (shared) object file. The default is currently "-fPIC", but since that only works with gcc it will soon be changed.
$DLLCXXFLAGS user Extra arguments to compile a C++ program into a dynamic (shared) object file. The default is currently "-fPIC", but since that only works with gcc it will soon be changed.
$DLLDIR Aap Sub-directory to install shared (dynamic) library files into. Default value: "lib/".
$DLLMODE Aap Mode to use for installed shared (dynamic) library files. Default value: "0755" (readable and executable for everybody, writable for the user).
$DLLOBJSUF Aap Suffix for an object file to be included in a dynamic (shared) library. Default: ".o" for Unix, ".obj" for MS-Windows.
$DLLPRE conf Prefix for a dynamic (shared) library. Default: "lib" for Unix, empty for others.
$DLLSUF conf Suffix for a dynamic (shared) library. Default: ".dll" for MS-Windows, ".so" for Unix.
$EDITOR conf Editor to be used for the "edit" action. The default value comes from the "VISUAL" or "EDITOR" environment variable. When these are not defined it falls back to "vi" On Unix and "notepad" otherwise.
$EXECDIR Aap Sub-directory to install programs files into. Default value is "bin/".
$EXECMODE Aap Mode to use for installed programs. Default value: "0755" (readable and executable for everybody, writable for the user).
$EXESUF conf Suffix for an executable file. Default value: ".exe" for MS-Windows, empty for others.
$GMTIME Aap Time in seconds since 1970 Jan 1. This always uses GMT, it ignores time zones and daylight saving. But it depends on the system time to be set correctly! The value does not change while Aap is running, it is the time when Aap was started. Also see $TIMESTR and $DATESTR.
$GROUPCOUNT Aap Number of files handled at a time for uploading, downloading and version control commands. The default value is 20. Set it to a smaller number when using big files. Set it to a large number when you need to enter a password every time.
$HASGCC conf Indicates whether gcc can be used to scan C sources for dependencies. It is initialized empty. When dependency scanning is to be done a configure check is run to see if $CC can be used for dependency checking. $HASGCC is then set to "yes" or "no". You can set $HASGCC to empty to force running the check again, set it to "no" to avoid using $CC for dependency checking or set it to "yes" to skip the configure check and use $CC for dependency checking.
$HASGCCXX conf Indicates whether gcc can be used to scan C++ sources for dependencies. Just like $HASGCC does this for C.
$INCLUDE user Directories to find include files. Used in the same place as $CPPFLAGS. Form: "-Ipath". The tools will convert this to the argument the compiler actually uses.
$INCLUDEDIR Aap Sub-directory to install include files into. Default value: "include/".
$INCLUDEMODE Aap Mode to use for installed include files. Default value: "0644" (read/write for the user, readable for the group and others).
$INFODIR Aap Sub-directory to install info files into. Default value: "info/".
$INFOMODE Aap Mode to use for installed info files. Default value: "0644" (read/write for the user, readable for the group and others).
$LD conf Command to execute the linker. The default is empty, in which case $CC is used. But for C++ object files (cxx_build action) the default is $CXX.
$LDFLAGS user Arguments for linking, before the object files. The default is empty.
$LEX Aap Program to turn a lex file into C. The default is empty. When the "lex" action is invoked Aap will search for "flex" and "lex" and set $LEX to the found program.
$LEXFLAGS user Flags for $LEX. There is no default value.
$LEXPP Aap Program to turn a lex++ file into C++. The default is empty. When the "lexpp" action is invoked Aap will search for "flex++", "lex++", "flex" and "lex" and set $LEX to the found program.
$LEXPPFLAGS user Flags for $LEXPP. There is no default value.
$LIBDIR Aap Sub-directory to install static library files into. Default value: "lib/".
$LIBMODE Aap Mode to use for installed static library files. Default value: "0644" (read/write for the user, readable for the group and others).
$LIBOBJSUF conf Suffix for an object file to be included in a static library. Default value: ".o" for Unix, ".obj" for MS-Windows.
$LIBPRE conf Prefix for static library. The default is empty on MS-Windows, "lib" on Unix.
$LIBS user Arguments for linking, after the object files. Convention: Always use "-lname", the tools will translate it into the flags that the linker actually uses. Also see $LTLIBS
$LIBSUF conf Suffix for a static library. Default value: ".lib" for MS-Windows, ".a" for Unix.
$LIBTOOL conf Actual name of the "libtool" program, used to build libtool libraries and for building programs that use libtool libraries. Default value: "libtool --silent".
$LNKSUF conf Suffix for a (symbolic) link. Default is empty.
$LOGENTRY user Default message for the version control change log. Used when a file is committed (also when it was deleted and the delete is committed).
$LTOBJSUF conf Suffix for an object file to be included in a libtool library. Default value: ".lo".
$LTLIBPRE conf Prefix for libtool library. The default is "lib".
$LTLIBS user Arguments for linking, after the object files but before $LIBS. When $LTLIBS is set "libtool" will be used for building, see $LIBTOOL (when the platform supports it). Convention: Always use "-lname", the tools will translate it into the flags that the linker actually uses.
$LTLIBSUF conf Suffix for a libtool library. Default value: ".la".
$MANDIR Aap Sub-directory to install man pages into. Default value: "man/". Note that Aap will append "man1", "man2", etc. when installing manual pages.
$MANMODE Aap Mode to use for installed man pages. Default value: "0644" (read/write for the user, readable for the group and others).
$MESSAGE user

Comma separated list of message types which are printed. Possible values:

    note             note message
    warning       warning message
    error            error message
    system         executed system command
    result           result of :sys command
    info              informational message
    extra            extra informational message
    changedir    changing directories
    depend        message about dependencies
    all                all messages

Default value: "error,warning,system,info". When the -s or --silent option is used: "error". When the -v or --verbose option is used: all possible values.

Instead of removing "print" from $MESSAGE it is possible to use the :log command to write text to the log file.

$OBJSUF Aap Suffix for an object file. Default value: ".o" for Unix, ".obj" for MS-Windows.
$OPTIMIZE user A number from zero to nine. Zero means no optimization, nine means maximum optimization. The default is two. For an example see the tutorial.
$OSNAME Aap The name of the operating system and its version (on systems that support it). For instance, FreeBSD 4.9 gives $OSNAME the value FreeBSD4_9_STABLE. Systems that do not support name and version yield what Python's os.name yields - usually the same as $OSTYPE except for MS-Windows and MS-DOS. This name is usually incorporated in $BDIR as well, as build-OSNAME.
$OSTYPE Aap Type of operating system used:

    posix             Unix-like (Linux, BSD)
    mswin           MS-Windows (98, XP)
    msdos           MS-DOS (not MS-Windows)
    os2                OS/2
    mac               Macintosh (OS X gives "posix")
    java               Java OS
    riscos            Risc OS
    ce                  MS-Windows CE

$PAINTER conf Graphical editor to be used for the "edit" action. The default value comes from the "PAINTER" environment variable.
$PREFIX user Directory normally used for the top directory to install to. When empty it defaults to "/usr/local". Use a single slash to install in the root directory. Also see $DESTDIR.
$RANLIB conf Program to run on created static library. Default is not set. When the "ranlib" action is invoked it will search for the "ranlib" program and set the $RANLIB variable.
$RANLIBFLAGS user Arguments for $RANLIB. The default is not set.
$RCP conf Remote copy program to use for rcp://. The default is not set, which means "rcp -p" is used. May also include arguments.
$RECIPEVERSION user Version of A-A-P the recipe was written for, set by the user. Uses the format "1.0", "1.3". Currently not used, but in a later version of Aap it can be use for backward compatible behavior.
$RSYNC user Remote sync program to use for rsync://. The default is not set, which means "rsync -p --rsh=ssh --copy-links" is used (preserve file attributes, use secure shell connection, copy what symbolic link points to).
$SBINDIR Aap Sub-directory to install "sbin" files into. Default value: "sbin/".
$SCP user Secure copy program to use for scp://. The default is not set, which means "scp -C -p" is used. May also include arguments, e.g.: "scp -i c:/private/keyfile".
$SHLINK conf Name of linker used to combine object files into a shared (dynamic) library. Default value: "ld" for Unix, "link" for MS-Windows.
$SHLINKFLAGS user Arguments for $SHLINK. Default value: "-shared" for Unix, "/nologo /dll" for MS-Windows.
$SOURCE user List of source files. OBSOLETE
$STRIP conf Program to run on installed program. Default is empty. When the "strip" action is involved Aap will search for the "strip" command and set $STRIP to the found program.
$STRIPFLAGS user Arguments for $STRIP. The default is not set.
$TAR conf Tar program to use. Default value is "tar".
$TARGET user List of target files, usually the name of the resulting program. OBSOLETE
$TARGETARG Aap Target(s) specified on the command line.
$TIMESTR Aap Time as a string in the form "23:11:09". This always uses GMT, it ignores time zones and daylight saving. But it depends on the system time to be set correctly! The value does not change while Aap is running, it is the time when Aap was started. Also see $GMTIME and $DATESTR.
$TOPDIR Aap In a child recipe: The directory of the child recipe relative to the toplevel recipe. When using: ":child subdir/main.aap" in the toplevel recipe, $TOPDIR will be "subdir" in the child recipe. In the toplevel recipe $TOPDIR is empty.
$UNZIP conf Unzip program to use for ".zip" archives. Default value is "unzip".
$VERSIONSTR Aap Version of A-A-P being used as a string, e.g., "0.100". Also see $AAPVERSION.
$YACC conf Program to turn a yacc file into C. The default value is empty. When the "yacc" action is invoked Aap will search for "yacc" and "bison" and set $YACC to the found program.
$YACCFLAGS user Flags for $YACC. The default value is not set.
$YACCPP Aap Program to turn a yacc++ file into C++. The default value is empty. When the "yaccpp" action is invoked Aap will search for "bison" and "yacc" and set $YACC to the found program.
$YACCPPFLAGS user Flags for $YACCPP. The default value is not set.
$bar Aap A single |. OBSOLETE, use $(|).
$br Aap A line break. OBSOLETE, use $BR
$empty Aap Empty. Can be used to get leading white space with :print. OBSOLETE, use $( )
$gt Aap A single >. OBSOLETE, use $(>).
$lt Aap A single <. OBSOLETE, use $(<).
$pipe Aap A single |. OBSOLETE, use $(|).