17.5. Predefined Abuild.interface Variables

Before abuild reads any Abuild.interface
files, it provides certain predefined variables. We divide them
into categories based on target type.

The variables mentioned here, along with any additional variables
that are declared in Abuild.interface files,
are made available to the backends in the form of identically
named make variables or Groovy framework definitions and ant
properties.

17.5.1. Interface Variables Available to All Items

The following interface variables are available to build items
of all target types:

ABUILD_ITEM_NAME

The name of the current build item

ABUILD_OUTPUT_DIR

The output directory in which this item's products are
generated for this platform. This is the most often
referenced abuild interface variable as it is normal
practice to expand this variable when setting the names of
library directories, classpaths, or anything else that
references generated targets.

ABUILD_PLATFORM

The name of the platform on behalf of which this interface
is being read. This variable is not used very often. When
referring to the output directory, always use
$(ABUILD_OUTPUT_DIR) instead of writing
something in terms of this variable.

ABUILD_PLATFORM_TYPE

The platform type of the platform on behalf of which this
interface is being read

ABUILD_STDOUT_IS_TTY

A Boolean variable indicate whether abuild's standard output
is a terminal. It can be useful to know this so that this
information can be passed to other programs invoked by
backends, particularly those (like ant) which redirect output
through a pipe that ultimately goes to abuild's standard
output.

ABUILD_TARGET_TYPE

The target type of the current build item

ABUILD_THIS

The obsolete variable ABUILD_THIS
contains the name of the current build item. It would have
been deprecated in abuild version 1.1, but there is no
reliable way to deprecate an interface variable since
abuild can't detect its use in backend build files. New
code should not use ABUILD_THIS, but
should use ABUILD_ITEM_NAME instead.

ABUILD_TREE_NAME

The name of the current build item's tree

17.5.2. Interface Variables for Object-Code Items

The following interface variables are available for object-code
build items:

This variable is to contain directories that users of this
build item should add to their include paths.

LIBDIRS

This variable is to contain directories that users linking
with this build item's libraries should add to their library
search paths. Typically, this is just set to
$(ABUILD_OUTPUT_DIR) since this is where
abuild creates library files.

LIBS

This variable is to contain the names of libraries (without
any prefixes, suffixes, or command-line flags) that this
build item provides.

XCFLAGS

This variable is to contain additional flags, beyond those
in $(XCPPFLAGS) to be passed to the
compiler when compiling C code. This variable will be used
very infrequently.

XCPPFLAGS

This variable is to contain additional preprocessor flags
that must be added when using this item. This flag should
be used very sparingly as changing the value of this
variable does not cause things to automatically recompile.
It is here primarily to support third-party libraries that
only work if a certain flag is defined. If you are using
this to change the configuration of a build item, please
consider using another method instead, such as defining
symbols in a header file or using runtime configuration.
For an example of how to do this based on the value of a
variable, see Section 22.5, “Dependency on a Make Variable”.

XCXXFLAGS

This variable is to contain additional flags, beyond those
in $(XCFLAGS) and
$(XCPPFLAGS) to be passed to the compiler
when compiling C++ code. This variable will be used very
infrequently.

XLINKFLAGS

This variable is to contain additional flags to be added to
the command-line when linking. The most common use for this
would be to pass flags to the linker that are other than
libraries or library paths. For linking with libraries,
whether they are your own libraries or third-party
libraries, you are better off using
$(LIBDIRS) and $(LIBS)
instead.

SYSTEM_INCLUDES

This variable, introduced in abuild 1.1.6, may contain a
list of directories that contain system include files. For
compilers that support this, any directory mentioned in the
INCLUDES directory that starts with any
of the paths mentioned in the
SYSTEM_INCLUDES directory will be
specified to the compiler using a flag that indicates that
it's a system include directory. Some compilers treat
system include directories differently, such as suppressing
most compiler warnings. For gcc, this causes
-isystem to be used rather than
-I when specifying the include directory.
Note that directories must still be added to
INCLUDES to be searched. A typical use
of this would be for build items that are providing
interfaces to third-party libraries. Those build items'
Abuild.interface files may add the
directory to both INCLUDES and
SYSTEM_INCLUDES to prevent users from
having to look at warning messages generated by incorrect
code in the third-party library.

Warning

Although abuild allows you to do so, it is strongly
recommended that you avoid using these variables to configure
your build items by passing preprocessor symbol definitions on
the command line. There are some times when passing
preprocessor symbols on the command line is okay, such as when
you're passing a parameter required by a third-party library or
passing in some truly static value such as the name of the
operating system, but passing dynamic configuration information
this way is dangerous. A significant reason for this is that
make's entire dependency system is
based on file modification times. If you change a preprocessor
symbol in an Abuild.mk or
Abuild.interface file, there is nothing
that triggers anything to get rebuilt. The result is that you
can end up with items that build inconsistently with respect to
that symbol. Furthermore, abuild has no way to perform its
integrity checks relative to the values of compiler flags in
build and interface files. If you need to have
preprocessor-based static configuration of your code, a better
way to handle it is by creating a header file and putting your
#defines there. That way, when you modify
the header file, anything that depends upon that file will
rebuild automatically.

Note that the various FLAGS variables above
can also be set (or, more likely, appended to) in
Abuild.mk files, as can additional
variables to control flags on a per-file basis. Please run
abuild rules-help in a C/C++ build item or
see Section 18.2.1, “C and C++: ccxx Rules” for details.

17.5.3. Interface Variables for Java Items

The following variables are used by java build
items, described here from the context of the item assigning to
them:

abuild.classpath

This variable is to contain generated JAR files to add to
the compile-time classpath and to include by default in
higher level archives. Most ordinary Java build items that
create JAR files will assign to this variable. Its value
will typically be
$(ABUILD_DIR_OUTPUT)/dist/JarFile.jar,
where JarFile.jar is the name of
the JAR file you placed in the
java.jarName property in your
Abuild.groovy file. See also
abuild.classpath.manifest below.

abuild.classpath.manifest

This variable is to contain JAR files whose names should be
listed in the Class-Path key of the
manifest of JAR files that depend on it directly. In most
cases, anything that is assigned to
abuild.classpath must also be assigned to
abuild.classpath.manifest. The
abuild.classpath.manifest variable is
declared as non-recursive, so assignments made
to it are visible only to items that depend directly on the
item making the assignment. This is appropriate because
Java handles indirect dependencies on its own.

abuild.classpath.external

This variable is to contain externally supplied JAR files to
add to the compile-time classpath. Unlike JARs added to
abuild.classpath, JAR files placed here
will not be included in higher level archives by default.
Whether you assign a JAR to
abuild.classpath or
abuild.classpath.external depends on the
nature of your runtime environment. Java SE applications
probably don't need to use this variable at all. Java EE
applications should use this primarily for JAR files that
are required at compile time by are provided by default by
the application server or runtime environment. As with
abuild.classpath, Values assigned to
abuild.classpath.external will usually
also have to be assigned to
abuild.classpath.manifest.

For additional discussion of how these are used by the Groovy
backend, please see Section 19.4, “Class Paths and Class Path Variables”. In that section, we
discuss the variables from the context of the item that is using
them rather than the item that is assigning to them.