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 ant properties.
The following interface variables are available to build items of all target types:
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.
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.
The platform type of the platform on behalf of which this interface is being read
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.
The target type of the current build item
The name of the current build item
The following interface variables are available for object-code build items:
For object-code items, this variable contains the
COMPILER field of the platform (see Section 5.2, “Object-Code Platforms”).
For object-code items, this variable contains the
CPU field of the platform (see Section 5.2, “Object-Code Platforms”).
For object-code items, this variable contains the
OPTION field of the platform if present or
the empty string otherwise (see Section 5.2, “Object-Code Platforms”).
For object-code items, this variable contains the
OS field of the platform (see Section 5.2, “Object-Code Platforms”).
For object-code items, this variable contains the
TOOLSET field of the platform (see Section 5.2, “Object-Code Platforms”).
This variable is to contain directories that users of this build item should add to their include paths.
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.
This variable is to contain the names of libraries (without any prefixes, suffixes, or command-line flags) that this build item provides.
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.
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 18.3, “Dependency on a Make Variable”.
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.
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.
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 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 15.2.1, “C and C++: ccxx Rules” for details.
The following variables are used by java build items:
This variable is to contain generated JAR files to add to
the classpath. This is the variable that the most ordinary
Java build items will assign to. Its value will typically
be
$(ABUILD_DIR_OUTPUT)/dist/,
where JarFile.jarJarFile.jar is the name of
the JAR file you placed in the
abuild.jar-name property in your
Abuild-ant.properties file. Note that
although Java allows both files (whose names end with
.jar or .zip) and
directories to be added to your classpath, adding
directories to the abuild.classpath
variable will not work properly in some cases with
abuild's ant rules and should therefore be avoided.
This variable is to contain externally supplied JAR files to
add to the classpath. This variable is intended to be used
for third-party JAR files. The difference between it and
abuild.classpath is that JAR files listed
here are not added to EAR and WAR files while those in
abuild.classpath are.