Setting up a VMake project (-depricated)

If you want to build your own isolated binary or module, one needs to create a project. Essentially all this means is that a configure and make phase exists, and that the project is named. The configure phase serves the purpose of eliminating the need to manually edit makefiles for any given machine (and for the most part this is true).

Step 1 - get a local copy of VMake

By convention, we unpack or checkout VMake in the root directory of the project. The VMake package is needed because it contains all the configure and make code, and unlike autoconf, these are not locally rendered within the project. For example, by checkout: 

svn co https://csd.vpac.org/svn/VMake/trunk VMake

Then we softlink the important files (the configure executable, the make rules and generic shell functions). 

ln -s VMake/configure.sh
ln -s VMake/Makefile.vmake
ln -s VMake/build-functions.sh

Step 2 - establishing the project specifics

The configure system is implemented with shell. Hence the way to configure the configure, is also by shell. This is done by having a file by the name of project-config.sh. By convention, the first part is for portability (assume Bourne compatibity). 

#!/bin/sh
# Be Bourne compatible
if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then
emulate sh
NULLCMD=:
elif test -n "${BASH_VERSION+set}" && (set -o posix) >/dev/null 2>&1; then
set -o posix
fi

The second step is to import in the generic VMake shell functions. 

. './build-functions.sh'

Then theres only two things one needs to do: set the project name and the required packages. Setting the required packages is as simple as listing the packages required, from the list provided by VMake. For example, for a project called NewProject that requires StgDomain. 

setValue PROJECT 'NewProject'

# Setup Makefile shortcuts
. ./VMake/Config/makefile-shortcuts.sh

. ./VMake/Config/compiler-config.sh
. ./VMake/Config/math-config.sh
. ./VMake/Config/mpi-config.sh
. ./VMake/Config/xml-config.sh
. ./VMake/Config/StGermain-config.sh
. ./VMake/Config/StgDomain-config.sh

When configure.sh is run, some initialisation activity occours, then project-config.sh is called. The output of this is Config.log, makefile.system and a snapshot version of makfile.system into the build directory. The file makefile.system stores the result of the configure activity for the project in a makefile format.

Step 3 - describe what to build

As VMake uses GNU make, per directory, all that is needed is a file by the name of makefile. This makefile needs to find the configure status of the project, declare what to do, and then call the VMake build rules that trigger the actual build. By convention, to source the configure status in a path independant manner we do: 

#Finds the Absolute path to the Project Root directory
SHELL := /bin/bash
PROJ_ROOT := $(shell until test -r ./Makefile.system ; do cd .. ; done ; echo `pwd`)
include ${PROJ_ROOT}/Makefile.system

The very last thing that is required is to call the VMake build rules. 

include ${PROJ_ROOT}/Makefile.vmake

In between these two parts, we define what to build. These are examples for sub-projects, sub-directorys, librarys, modules, and executables.

Step 3a - Building an executable

This is triggered by having a bin definition. For example to build an executable of the same name as the project, from the source file main.c, that uses StgDomain. 

bin = ${PROJECT}

SRCS = main.c

packages = STGDOMAIN STGERMAIN MPI XML MATH