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:

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.