Build System

Overview

The build system uses the GNU Autotools and libtool. All platform-/compiler-dependent parameters should go into the configure.ac file that is processed by Autoconf. The configure script accepts a few non-standard arguments. The most interesting ones to non-developers are:

• --enable-backend = {auto, nonvector, none, mmx, sse, sse2, ssse3, altivec, vadmx, vadmx2, loongson2e, loongson2f, neon, vis}
  Use the specified SIMD backend. The compiler will be asked to enable the named SIMD extension. The nonvector value will disable all vector implementations. The none value will disable all vector implementations and all tuning. The default is auto, equal to --enable-backend=yes and plain --enable-backend. This setting will detect the SIMD backend automatically from the C compiler characteristics. Preprocessor macros expected to be predefined by the compiler are inspected, and determine which backend to use. The macros __MMX__, __SSE__, __mips_loongson_vector_rev, __ARM_NEON__, __SSE2__, __SSSE3__, __VEC__, __ALTIVEC__, __VADMX__, and __VADMX2__ are checked in that order, and the last one in that list found to be defined, wins. If no backend is found, no vector implementation is used. This is a bit different from naming a specific backend, where required SIMD-enabling compiler options are passed automatically.

• --enable-tune-cache
  Use the pre-tuned cached configuration file if it exists. This has no effect if the SIMD backend is none. The default is yes, unless the pre-tuned file is out-of-date.

• --with-doxygen
  Generate doxygen documentation. The default is yes, if the doxygen program is present.

• --enable-debug
  Build in debug mode (default no). This enables asserts and debugging information, and disables optimization. The default is no. There is an optional argument, which can be one of yes, no, and asserted-returns. The latter value is like yes, but also forces each function in the RAPP API to call abort() instead of returning an error code, if a parameter is found to be erroneous. This may be helpful when debugging upper-layer code, particularly when poor error handling is suspected. Don't use it for regular development, as the test-suite is deliberately not adopted to its use and will fail early. (Error handling can't be properly tested with asserted returns anyway, so better to not add any related complexity at all.)

• --enable-logging
  Enable code that logs each call to every function in the RAPP API, appending a line for each call to a file. The file is settable using the environment variable RAPP_LOGFILE, default "rapp_log.txt". If RAPP_LOGFILE does not start with a "/", the standard environment variable TMPDIR (in turn defaulting to "/tmp") is prepended to its value with a "/" delimiter. On systems where symbols in the application override library symbols (most Unix-like systems), the actual logging can be specialized in the application or the calling library: just add to it an overriding definition of the logging function, rapp_log_rappcall. It has the following prototype:

           void rapp_log_rappcall(const char fname[], const struct timeval tv[],
                                  const char retformat[], const char argformats[],
                                  ...)
           

  where fname is the name of the called function as a string, e.g. "rapp_initialize", tv is a vector of two struct timeval values, filled in by RAPP by calls to gettimeofday before (tv[0]) and after (tv[1]) the call to the proper function. The parameter retformat contains a printf-format string for the return-value, e.g. "%d" for functions returning int and the empty string "" for void functions. Similarly, the parameter argformats holds a format string for the parameters, delimited by a single comma and space, ", " and the empty string for functions without parameters. Finally the parameters to the proper function, followed by the return value after the call (for non-void functions) are passed as the variable arguments represented by the ellipsis. Beware: the RAPP library does not declare this function in the installed headers, nor is it part of the versioned API. The semantics of rapp_log_rappcall only apply when RAPP is configured with --enable-logging.

For the full set of options, use configure --help.

Structure

Each directory with source files has its own Makefile.am file that is processed by Automake. All local variables defined in these files are prefixed with RB_ for RAPP Build, to avoid accidental clashes with Automake variables.

When the RAPP library is built, several convenience libraries are built and merged to form the final library. The compute/vector directory is a bit special. It is built two times from the same sources, resulting in two different convenience libraries. The first time it is built with no extra flags, producing an implementation using the SWAR vector backend. The second time we define RAPP_USE_SIMD to build a version with the SIMD backend instead. At the top level of the Compute layer, all three implementations (generic, SWAR and SIMD) are combined into the Compute layer convenience library. The function selection mechanism guarantees, if used correctly, that a function is only implemented once.

The build system in the compute/tune and benchmark directories are a bit special. When the configure script is run, it will check for the presence of an up-to-date pre-tuned configuration file directory. If found, a symbolic link compute/tune/rapptune.h is created to this file. During build time, this symbolic link will be used for selecting the appropriate implementations. The file benchmarkplot-<host>-<backend>-<wordsize>.html in the benchmark/arch directory is handled analogously. The symbolic links are only removed on distclean. The -<wordsize> part, corresponding to the word size used by the platform, is empty for the default size for the platform.

If the pre-tuned rapptune-<host>-<backend>-<wordsize>.h is present but the set of tuned functions has changed since it was generated, the default build behaviour is to generate a new tuning. Alternatively, with an explicit --enable-tune-cache option, untuned fallback values will be used to fill in the missing tuning numbers, but compiler warnings will be emitted for each such untuned function when building RAPP. This is of course not recommended, but may be useful e.g. when cross-compiling and the target system is not available for tuning at the time RAPP is built.

Next section: Tuning System