29.4. Adding Toolchains

For a compiler to be used by abuild, it must be named in an
abuild platform. The platform can be added using either the
platform or native-compiler
directive as appropriate in the output of a
list_platforms command.

To add a new compiler toolchain to abuild, in addition to
declaring the native compiler or platform to make abuild try to
use it, you must create a file file called
compiler.mk where
compiler is the name of the compiler
that is being added, and place this file in the
toolchains directory of a plugin.
Abuild's internal toolchains are under
make/toolchains. The best way to learn how
to write a toolchain is to read existing ones. Most compiler
toolchains will be designed to support C and C++ compilation and
are therefore used by the ccxx rules.
Details on the requirements for such toolchains can be found in
rules/object-code/ccxx.mk in the
abuild distribution (Appendix I, The ccxx.mk File).

Abuild has some rudimentary support for allowing you to force
compilation to generate 32-bit code or 64-bit code on systems
that can generate both types of code. As of abuild 1.1, this
functionality is only supported for the gcc
compiler. If you are writing a plugin for a native compiler, you
can check for the value of the variables
ABUILD_FORCE_32BIT or
ABUILD_FORCE_62BIT and adjust your compilation
commands as necessary. You can find an example of doing this in
make/toolchains/gcc.mk in the abuild
distribution. On Linux-based Intel and Power PC platforms,
abuild will also use these variables to change the platform
string, which makes it possible to use 64-bit systems to build
32-bit code that can be used natively without any special steps
by 32-bit systems. With an appropriate configured toolchain, you
can also build 64-bit code on a 32-bit system, though such code
would most likely not be able to be run natively on the 32-bit
system.

Once you have written a support file for a new compiler, you will
need to verify to make sure that it is working properly. A
verification program is included with abuild: the program
misc/compiler-verification/verify-compiler
can be run to verify your compiler. This program creates a build
tree that contains a mixture of static libraries, shared
libraries, and executables and puts those items in the platform
type of your choice. It then builds them with the specified
compiler. You provide the path to the build tree containing the
plugin, the name of the plugin, the platform type, and the
compiler. The program can be used with either native compilers
or non-native compilers. It also makes it very clear whether
everything is working or not. Please run
verify-compiler --help and see
misc/compiler-verification/README.txt for
additional details.

Ordinarily, a toolchain in platform type native is a
native compiler, and a toolchain in a platform type other than
native is a cross-compiler. There are, however,
some instances in which it may make sense to have something in
platform type native be treated as a cross compiler:
specifically, you will want to do this when the compiler cannot
create executables that run on your current platform. Here are
some examples of where this may occur:

You are writing a compiler plugin for a static analyzer that
is a drop-in replacement for the compiler but that produces
reports instead of actual executables

You are building 64-bit executables on a 32-bit system

You are cross-compiling for a different architecture of the
same operating system or at least of an operating system that
is essentially compatible with your code base and could just
as well support a native compiler; e.g.
executables for a low-memory or slow embedded Linux without a
native development toolchain might be built using a regular
desktop Linux environment and a cross compiler

Most of abuild will work just fine if the compiler you add to
the native platform type is actually a cross
compiler, but there are two notable exceptions: the
autoconf rules, and the
verify-compiler program. For the
autoconf rules, you just need to make sure
./configure gets executed with some
--host option. This can be done by simply
adding this single line:

CONFIGURE_ARGS += --host=non-native

to your
compiler.mk file.
Passing some value to --host that doesn't match
what autoconf determines your current host to be tells autoconf
that you are cross compiling. There's nothing special about the
specific value “non-native”. When
running verify-compiler, you will have to pass
the --cross option to the
verify-compiler command so that it will ask
you to run the test executables instead of running them itself.
The --cross option is not required if your new
compiler is not in the native platform type. In
this case, abuild will automatically figure out that it is a
cross compiler, just as it does in the
autoconf rules. Although these are the only
cases within abuild that care whether the compiler can create
native executables, you may run into others (such as ability to
run test suites), so just keep this in mind when using a
non-native compiler in the native platform type.