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.
The following interface variables are available to build items of all target types:
The name of the current build item
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 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.
The name of the current build item's tree
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 22.5, “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.
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.
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.
The following variables are used by java build items, described here from the context of the item assigning to them:
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/,
where JarFile.jarJarFile.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.
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.
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.