Adding new QUDA features

Whenever a significant new feature is added to QUDA, e.g., a new fermion type, that adds a significant overhead to the compilation and library size, the policy is to make this a configurable option so as to not affect the compilation and link time for all users of QUDA.

Updating configure / make

To make a feature user enabled through configure, i.e., ./configure --enable-feature, where feature is shorthand for the feature that is to be enabled, the configure.ac file must be updated.

First the argument option has to be added to the command line:

AC_ARG_ENABLE(feature,
  AC_HELP_STRING([--enable-feature], [ Build fancy new feature (default: disabled)]),
  [ build_feature=${enableval} ], 
  [ build_feature="no" ]
)

Here we're adding the option for enabling "feature", with the default that it is disabled.

Second, we add a check to ensure that a valid value is passed to this option.

dnl Build Feature
case ${build_feature} in
yes|no);;
*) 
  AC_MSG_ERROR([ invalid value for --enable-feature ])
  ;;
esac

Third, we need to tell configure to do something if this option is enabled

AC_MSG_NOTICE([Setting BUILD_FEATURE = ${build_feature} ] )
AC_SUBST( BUILD_FEATURE, [${build_feature}])

Here, what this means is that if --enable-feature is set, then the variable BUILD_FEATURE will be defined to equal yes, else it will be no.

Now in make.inc.in, which is the makefile input to configure we need to use this variable and act accordingly:

BUILD_FEATURE = @BUILD_FEATURE@				# build code for fancy new feature?

ifeq ($(strip $(BUILD_FEATURE)), yes)
  NVCCOPT += -DGPU_FEATURE
  COPT += -DGPU_FEATURE
  FEATURE_TEST=feature_test
endif

So this is saying that if BUILD_FEATURE=yes then the macro GPU_FEATURE and the feature_test program will be built. For the latter we also need to add FEATURE_TEST to the list of tests to build in tests/Makefile.

After all these changes have been made, all that remains is to run autoconf to create the new configure and make.inc files.

Conditional compilation

In the source code for the algorithms that are to be built conditionally, we use the C-preprocessor macro defined by the makefile. We do so in such a way such that if the routine is called without being built, e.g., through use of a stale makefile, then a sensible run-time error message will be thrown.

#ifdef GPU_FEATURE
 // GPU kernel code and Tunable derived class go here
#endif

void newFeature(...) {
#ifdef GPU_FEATURE
  // call above code
#else
  errorQuda("GPU feature has not been built");
#endif
}