During the configuration stage, we determine what tools are available that meet a given set of needs. Typically, this means finding suitable compilers and determining what options the compilers support. Of course, most projects have more complicated needs than this. For example, VR Juggler can be compiled with several different versions of GCC (2.95.3 through 3.1 as of this writing). When moving between platforms, the GCC C++ compiler will almost always be called g++, but it may not always be the same version^[2]. For that reason, it may be necessary to perform several version-specific detection steps, including, but not limited to, the following:

Moving beyond compiler-specific issues, it may be necessary to detect the installation of third-party libraries or programs. Often times, simply finding an installation is not sufficient. The version of the installation must also be checked to ensure compatibility with the user's project.

This all boils down to one thing: automation. The job of the configuration step is to automate as much as possible. In so doing, the code used to write the compilation can be simplified. In effect, the compilation step becomes a very generic process that is configured based on many platform-, compiler-, and site-specific details that cannot be detected easily by a tool designed for compiling.

As we just described in the preceding section, the compilation step should be a very generic process. Compiling software tends to be a very serialized or step-by-step process. Subsequent steps depending on proper completion of preceding steps. Nothing in particular about compiling software (or code generation in general) has to be tied to a specific set of tools. The process should depend more on the source code and what steps are necessary to generate the desired outcome.

While it is possible to construct build system software that does everything in the compilation step (a la Doozer proper), such systems tend to be very inflexible. Everything that could provided more generically through the configuration phase must be defined statically in makefiles (or whatever specification file is being used to direct the build process) and in the code. For example, consider the following C++ code:

#if defined(HAVE_HASH_MAP)
#include <hash_map>
#elif defined(HAVE_EXT_HASH_MAP)
#include <ext/hash_map>
#elif defined(HAVE_HASH_MAP_H)
#include <hash_map.h>
#else
#error "std::hash_map is not available with this compiler"
#endif

The code above is not tied to any specific compiler or any specific compiler version. Now, consider the following code that achieves the same result:

#if defined(__GNUC__)
#  if __GNUC__ < 3 && __GNUC__ >= 2 && __GNUC_MINOR__ >= 95
#     include <hash_map>
#  elif __GNUC__ >= 3
#     include <ext/hash_map>
#  else
#     include <hash_map.h>
#  endif
#elif defined(__MSVC_VER__)
#  if __MSVC_VER__ >= 7
#     include <hash_map>
#  else
#     error "std::hash_map is not available with this compiler"
#  endif
#elif defined(__sgi__)
#  include <hash_map>
#else
#  error "std::hash_map is not available with this compiler"
#endif

The former is much shorter and hides all the platform- and compiler-specific details in the definition of the various HAVE_* symbols. The latter code is clearly much more complicated and only supports three compilers: GCC, Visual C++, and MIPSpro. (The latter example may also have inaccuracies. Think of it more as pseudo-code than something taken from real C++ code.) Certainly, the latter could be simplified by adding command-line options defined in platform- and compiler-specific makefile stubs (-DHAVE_HASH_MAP and so on), but such options would have to be provided for all possible cases. That method has obvious scalability problems, however.

Many other projects provide a variety of platform- and tool-specific makefile stubs that set up a build environment at the time of compilation. This inevitably leads to an ever growing number of stubs as the software becomes more portable or as external tools (especially compilers) evolve. For example, omniORB 3.0 (an excellent, freely available ORB implementation) has forty makefile stubs, four of which are for use on varying configurations Linux/i386. The upcoming omniORB 4.0, on the other hand, uses Autoconf to separate the platform-specific pieces from the generic, platform-independent compilation work.

There are a number of targets required by the global build. Some of these were listed above. The following sub-subsections give a complete list of all targets that must be implemented by a module's glue makefile. The targets are grouped by the task they perform.

There are certain naming conventions for files and directories that must be followed in order to ensure consistency among all the modules in the Juggler Project. Not all of these relate directly to the build system, but the names may be influenced by the way the build system works.

#include <defines.h>
#include <vpr/Sync/Mutex.h>
#include <vrj/Kernel/Kernel.h>

The structure of an installation hierarchy is fairly open, but there are several basic requirements. They are as follows:

Before explaining how configure.pl manages its dependencies, it will be helpful to understand the role played by the configuration file from which the dependencies are read. In the VR Juggler build system, the file is called juggler.cfg, and it is located in the top-level source directory. At a very high level, the configuration file defines one or more modules that must be configured and compiled. The modules may be independent of each other, or they may form a dependency graph. In the latter case, one module states that it depends on one or more other modules. The following code block shows an example of this:

module VPR                                                 
{
   external;                                               
   modules/vapor;                                          
}

module Tweek                                               
{
   depend VPR;                                             
   modules/tweek;                                          
}

Going deeper into the module definition, we find that environment variables can be set with each directory listing using a comma-separated list. These variables provide extra information about the configuration environment after the configure script has completed successfully. To illustrate this, we extend the above example as follows:

module VPR
{
   external;
   modules/vapor: VPR_CONFIG=vpr-config, VPR_BASE_DIR=instlinks;          
}

module Tweek
{
   depend VPR;
   modules/tweek: TWEEK_CONFIG=tweek-config, TWEEK_BASE_DIR=instlinks;    
}

While any environment variable can be set in the configuration file, those shown above have special significance^[3]. Those variables ending in _CONFIG set the corresponding environment variable to include the full path to the named file (despite the fact that the full path is not given in the assignment). The path is constructed using the associated directory dependency. This directory is also added to the script's execution path. This extra little bit is needed so that a given -config script can be executed by another -config script if necessary. (The details about why all of this is necessary are discussed in the section called “The *-config Scripts and the *.m4 Macro Files”.)

Those variables ending in _BASE_DIR define the installation directory for the given module. In the VR Juggler build system, this is necessary for dependent modules to find the headers and libraries they need to compile. (Again, more information about this is given in the section called “The *-config Scripts and the *.m4 Macro Files”.) Once again, the value being assigned has special significance. If the value is the token instlinks, it is taken to mean that the full path to the installed module is in a directory relative to the current directory called instlinks. Any other value is used verbatim as the value of the environment variable.

Dependencies within modules are maintained using a simple Perl data structure in the JugglerModule class. Parsing the configuration file results in instantiation of this data structure. There is one such instance for each module defined. Each instance contains an array of ModuleDependecy objects. Steps are taken to ensure that there is no duplication of dependencies within a single JugglerModule instance.

We will now examine a typical -config script. We will not focus on any script in particular, but instead, we will describe the fundamental concepts and requirements shared by all implementations. Readers interested in implementations to use as references should consider the following:

To proceed with the abstract discussion, we will now describe the job that must be performed by all -config scripts. We then explain how external dependencies are managed. We conclude with a discussion of how a -config script is generated as part of the configuration process.

With an understanding of what information a -config file provides, we can move on to the m4 macros that make use of those files at configuration time. Each module in the Juggler Project has a corresponding m4 macro suitable for use within an Autoconf configure.in file. For example, Gadgeteer has a macro called GADGETEER_PATH. This macro is used in VR Juggler's configure.in to find a usable Gadgeteer installation.

The basic concept behind all these macros is the same: provide a way for a configure script to detect a usable installation. The way this is done is fairly straightforward. The basic step-by-step process is as follows:

We now proceed into the details of a typical .m4 file. First, we will cover the mechanism used to deal with paths to installations. Then, we explain what variables must be set by a module's m4 macro.

Within this subsection, we present the full list of targets that must be implemented for correct operation within the documentation build. As a reference, refer to the file juggler/Makefile.docs. This list, containing all of two targets, is as follows:

Targets such as 'clean' and 'clobber' are needed as well, but those makefiles that include docbook.mk get them for free. If a documentation generating makefile is not using docbook.mk, it must make its own 'clean' and 'clobber' targets.

The individual documentation building makefiles are expected to behave when installing the generated documentation. That is, they should install to a subdirectory of $(webroot) that reflects the appropriate project. In many cases, the installation hierarchy should also reflect the version of the software against which the documentation was written.

Each makefile is responsible for creating its own installation hierarchy and for installing any related, external files. The documentation build offers some automation to help with this, but its abilities are limited. At this time, the documentation build can be directed to install the image files that come with the DocBook style sheets and any local images that the documentation needs.

As stated above, this package contains a single subroutine: parseConfigFile(). This parses a user-specified configuration file in the format described in the section called “Build Configuration File”. If the config file is parsed correctly, a hash named %MODULES is returned to the caller. This hash, indexed by module name, provides references to JugglerModule instances.

The parsing code is fairly straightforward. There are only three keywords in the configuration file format: module, depend, and Default. The basic concepts used in the format are similar to those for the C grammar. In other words, curly braces denote blocks, semi-colons denote the end of a declaration, and all code is case-sensitive. The following provides the grammar for the configuration file:

DOCUMENT   ::= COMMENT DEFAULT MODULE
DEFAULT    ::= 'Default:' NAME | ε
MODULE     ::= NAME '{' COMMENT DEPENDENCY '}' COMMENT MODULE | ε
NAME       ::= ([A-Za-z0-9_][A-Za-z0-9_]* + λ)[A-Za-z0-9_]
DEPENDENCY ::= DIR ';' DEPENDENCY | MODDEP ';' DEPENDENCY | ε
DIR        ::= <valid-path> | <valid-path> ':' ENVVAR
ENVVAR     ::= NAME '=' <text> | NAME '=' <text> ',' ENVVAR
MODDEP     ::= 'depend' NAME
COMMENT    ::= '#' <text> | '//' <text> | '/*' <text> '*/' | ε

The structure of this grammar should be reflected in the parsing code. Differences between strict regular expressions (used above, more or less) and Perl regular expressions may muddy the correlation.

The JugglerModule package defines a class containing two “data members”: name and deps. These are actually keys of the blessed hash returned by the new() subroutine. The name member is just a string that contains the unique name of the module. The deps member is more interesting. Indeed, the main purpose of the JugglerModule package is to maintain the list of dependencies.

The deps member is a reference to an array of ModuleDependency objects (see the section called “ModuleDependency”). An array is used to preserve the ordering read from the configuration file. All dependencies given in the configuration file appear in the array. This includes those “inherited” from another module through the use of the depend keyword.

Duplication of dependencies is avoided by performing a check whenever a new dependency is added using addDependency(). The hasDependency() method encapsulates the process of making the check. The dependencies of two modules can be merged using the addDependencies() method.

The ModuleDependency package defines a class containing two “data members”: path and env. The first is a simple string, and the second is a reference to a hash where the keys are environment variable names. The values for these are extracted from the DIR rule in the above grammar. More specifically, the terminal <valid-path> in DIR rule corresponds to the path member, and the ENVVAR rule defines the hash of environment variable mappings.

Access to a given JugglerModule object's dependencies happens entirely through the API of that class. This class is provided as a convenient abstraction around the information provided through each DIR parser rule expansion.

The handling of command-line arguments in configure.pl is rather unique. To function correctly as a wrapper around multiple Autoconf-based build systems, this script must be capable of passing the correct arguments to the individual configure scripts. In other words, when the user executes the following:

configure.pl --module=VPR --enable-subsystem=NSPR --with-nspr=$HOME/nspr-4.2

the argument --module must be handled by configure.pl while the other two are passed through to VPR's configure script. Luckily, the Perl module Getopt::Long provides a mechanism for doing just that. The module is configured to allow unrecognized arguments to be passed through so that, after the execution of GetOptions(), @ARGV will contain what GetOptions() did not handle. When the time comes to execute a module's configure script, @ARGV is passed to the script as normal arguments.

This usage of Getopt::Long is not without a drawback or two. Allowing the pass through of unrecognized arguments means that GetOptions() is not performing robust error checking on user input. What if --module were spelled as --mdoule accidentally? GetOptions() would not recognize it, and the execution of configure.pl would not proceed the way the user had intended. Because of this, it is important for users to be especially careful with the options they give when running configure.pl.

Two types of output can be printed by configure.pl: usage for configure.pl and usage for all the known configure scripts. The first is done quite simply. The Pod::Usage module is used to render the internal POD as usage output^[6]. This output is printed when the user passes --help on the command line.

Usage information for the known configure scripts can be printed using the --all-help argument. This is provided so that users have a way to get a complete listing of all the command-line arguments that may be passed when running configure.pl. (The exact details of how this works were described in the previous subsection.) Only the relevant output is actually printed when this argument is passed. The meaning of “relevant” is tied to the module the user is configuring. For example, with an unmodified juggler.cfg, the default module is “VRJuggler” (sic). If the --module option is not specified in conjunction with --all-help, then the usage information for the VR Juggler configure script and the use information for the configure scripts of all of its dependencies are printed. If a different module is specified, the output will change based on the alternate module and its dependencies.

To print this information, each configure script is run by configure.pl with the --help command-line option. The output is collected and processed so that the arguments are printed to the screen in an orderly fashion. Duplicated output is discarded. The process of presenting the output to the user is very important because there exists the potential for a large amount of information.

Configuring a build tree involves several steps, and they are as follows:

Each of these steps will be discussed in turn in the following sub-subsections.

When an Autoconf-generated configure script is run successfully, a shell script called config.status is created. This script contains all the state information generated as a result of running configure. If there is a need to regenerate the files created by configure, config.status can do the job quickly because it reuses the static information from when it was created without re-running all the tests. There is no global config.status created by configure.pl, but an alternate method is provided through the --regen argument.

When --regen is passed on the command line, configure.pl iteratively executes the individual config.status scripts instead of the configure scripts. This allows users to regenerate files more quickly than by running all the configure scripts again. Deciding which config.status scripts to run is a somewhat difficult process, however.

In a normal situation when only one config.status exists, it is easy for a user to decide when (and how) to run it. In the context of the VR Juggler build system, there are many configure scripts, each having its own config.status script. Furthermore, some config.status scripts may not exist based on which module (in juggler.cfg) was configured. As with all other cases where configure.pl must decide what to execute, the requested module dictates the execution behavior. Thus, if the user did not configure the default module, the --module argument must be passed with --regen to ensure proper execution of the various config.status scripts.

Two types of comments can be used in configure.in. The first is the relatively standard “#” comment. Lines beginning with this character are copied into the final configure script generated by autoconf(1). The other type is the m4(1) comment. Lines commented in this way begin with dnl and are not copied into the configure script.

The scripting language used in configure.in is sh(1). All conditional statements must use the form:

if test "x$some_var" = "xsome_val" ; then
   ...
fi

rather than:

if [ "x$some_var" = "xsome_val" ] ; then
   ...
fi

The brackets are recognized as special characters by m4(1) and may not be copied into configure properly.

When performing tests, it is recommended that some extra character be used to avoid passing any empty strings to the test(1) command. Some implementations do not deal well with empty strings when performing comparisons. In the above code examples, the character 'x' was used at the beginning of the two strings. While there is still old code in various configure scripts that do not use this convention, it is recommended that all new code follow this rule. Furthermore, when editing legacy code that does not protect the string operands, it is recommended that the strings be updated accordingly.

When naming variables in configure.in, be sure to follow the following conventions:

Parameters spanning multiple lines may be passed to Autoconf macros without using backslashes through a special block recognized by m4(1). Simply enclose the parameter in []'s and it will be parsed as one parameter. Some macros require the use of backslashes, however. In these cases, the argument is taken as a literal list used by sh(1) code. One such macro is AC_CHECK_HEADERS().

Beyond multi-line arguments, the Autoconf documentation recommends that all parameters passed to macros be enclosed in square brackets. This is to protect the arguments so that m4(1) does not mangle anything in its expansion of the macros. Consider the following examples:

AC_CONFIG_HEADER([vpr/vprDefines.h])
DPP_PREREQ([1.4.107])

DPP_PERL_VER([5.004], , , [AC_MSG_ERROR([*** Perl is required ***])])

AC_CHECK_PROG([MTREE_CMD], [mtree], [mtree], [\$(PERL) \$(scriptdir)/mtree.pl])

DPP_HAVE_GNU_MAKE([3.78], ,
    [AC_MSG_ERROR([*** The build system requires GNU make 3.78 or newer ***])])
DPP_BASIC_PROGS([$PLATFORM], [$OS_TYPE])

While this does make the code harder to read, it saves a lot of headache, especially between two different versions of Autoconf. Unfortunately, not all macro calls are as well-protected as those in the above example. (Doozer++ has complete argument protection, so errors are usually caused by misuses in Juggler configure.in files.) It is recommended that all new code use square brackets. When editing exiting code, add brackets when necessary.

Anything that defines preprocessor macros other than those generated by the Autoconf macros must be defined in the module's acconfig.h. If they are not defined in this file, autoheader(1) will complain as it parses configure.in and finds these customizations. Follow the existing syntax and layout of acconfig.h when making additions to it. In general, additions only have to be made when a new AC_DEFINE(), AC_CHECK_TYPE(), etc. line is added to configure.in.

The first short block of configure.in performs some very basic initialization tasks. The RCS revision number of the script is maintained here so that the user can verify that s/he has the most recent version of the actual configure script. A check for one file in the source tree is also made to perform a very general, inexact verification that things are where they are supposed to be. For example, VR Juggler's configure script will do its sanity check based on the existence of vrj/vrjConfig.h. Next, the header file created when done with the configuration process is named. In VR Juggler, this file is called vrj/vrjDefines.h. Finally, Doozer++ initialization occurs using the DPP_INIT() macro.

In this block, the custom arguments for the configure script are defined. The first set defines the --with-package[=arg] and --without-package arguments. These are intended to be used for choosing some external software package to use at compile time. They are also used for providing a small level of customization to how the external software is found and/or used.

The second set defines the --enable-feature[=arg] and --disable-feature arguments that allow the user to choose which optional features can be built. From the Autoconf 2.12 documentation, “These options should never make a feature behave differently or cause one feature to replace another.”

For both sets of options, the AC_ARG_WITH() and AC_ARG_ENABLE() macros behave the same way. The first argument is the package/feature. The second argument is the description printed when the user runs configure with the --help option. The third argument sets a user-defined variable in the script to the contents of $withval or $enableval respectively. If no argument is given (e.g., the user specified --enable-opengl), the variable will get either “yes” or “no” as its value depending upon whether the user used the positive or negative form of the argument.

After the custom arguments are defined, some of the values that may be read are processed. In particular, the application binary interface (ABI) under which the module will be compiled is defined. This is done prior to the system-dependent section to reduce duplicated code even though the ABI is highly dependent upon the operating system and underlying computer architecture.

Here, a common set of script variables are given values that are usually dependent upon the system on which the script is being run. Except in VPR's configure script, there is little system-dependent code. Most of it is hidden by the Doozer++ DPP_SYSTEM_SETUP() macro. In the case of VPR's configure.in, however, a large conditional block compares the value in $target_os (obtained from the AC_CANONICAL_TARGET() macro) with known systems and sets values for the variables appropriately.

Some existing variables may be modified here as well. These often include $CFLAGS, $CXXFLAGS and $INCLUDES. Each of these could have been set as part of the user's environment variables or previously in the script as part of executing a macro. Thus, they should be treated carefully so as not to destroy any existing values that may be stored in them.

Besides setting values in variables, custom pre-processor macros are often defined here using the AC_DEFINE() macro. This macro takes two parameters:

To get something similar to:

#define VJ_DEF

use the following syntax:

AC_DEFINE([VJ_DEV],)

Defining macros that take parameters cannot be done with AC_DEFINE(). However, based on a check made for something (such as sginap(2)), such a macro can be defined at the bottom of acconfig.h or in the module's Config.h (vprConfig.h, tweekConfig.h, etc.) header after it includes the generated header.

This block is for standard program checks that configure does to ensure that software needed for compiling the package works. Using the values in several preset variables (including $CC for the C compiler and $CXX for the C++ compiler), it runs tests on the software and reports any problems it finds.

Checks for required external libraries are made here. In a configure script, a great deal of processing is often done in order to ensure that the source can be properly compiled and linked using certain external libraries. The basic process of checking for a library (say, the OpenGL library) involves first checking to see if the library can be linked. If the library can be linked, a check is then made for a standard header file associated with the library (in this case, GL/gl.h). In some cases, if a library cannot be found, a fallback check is provided. For example, in the case of the POSIX threads library, an attempt to link against libpthread is made. If that fails (as it will on HP-UX 10.20), a check is made to link against libcma.

Upon successfully finding a library and a needed header file, several variables are usually set that are used later in the makefile generation phase. If a library is not found, the script may simply issue a warning about the problem or it may exit altogether if the library's existence is crucial to the compiling process.

Adding new library checks can be complicated. The best method is to refer to the Autoconf documentation and the existing checks. All follow basically the same structure.

Checks for standard header files and user-specified header files are made here. The user-specified list is a space-separated list of header files that may not exist on all systems. If a header file is found, HAVE_FILENAME_H is defined in the module's definition header (vprDefines.h, tweekDefines.h, etc.) when it is generated.

Here, checks are made for any library and system functions (e.g., gettimeofday(3), gethostbyname(2), usleep(2)) that may not exist on all systems. As with other sections, the user-specified list of functions to check is the space-separated parameter passed to the AC_CHECK_FUNCS() macro. If found, HAVE_FUNCNAME will be defined in the generated definition header.

Within this block of configure.in, special symbols in the Makefile.in template files are slated for replacement with variable values. This is done through the AC_SUBST() macro, and it simply replaces a tag in a Makefile.in with the value stored in the corresponding configure script variable. The following example illustrates what happens during the file generation phase (discussed next). Say that some Makefile.in contains the following line:

CUSTOM_VAR = @CUSTOM_VAR@

The string enclosed by @'s is the tag that will be replaced when Makefile is generated. In configure.in, there following line must be present:

AC_SUBST(CUSTOM_VAR)

Note that the variable is not prepended by a `$' because variable interpolation should not be done here. Of course, $CUSTOM_VAR will generally have had some value set prior to this point. That is not required, however.

It is in this phase of configuration that most of the system-dependent build work is done. This is similar to what Imake template files do. Virtually everything preceding this point set variables to have values appropriate to the host machine, and now they are put into the makefiles to be used for compiling the code. There are several pre-defined variables that configure will substitute in the input template files. Refer to the section titled “Preset Output Variables” in the Autoconf 2.13 documentation for a list of these.

In this last block, file generation is performed using the AC_OUTPUT() macro. It iterates through its space-separated list of files and finds the associated .in template file. In general, this step is only used for generating makefiles (the module's definition header is added automatically due to the AC_CONFIG_HEADER() call at the top of configure.in). When a new directory and corresponding Makefile.in are added to the source tree, an entry for it must be added to this list.

Tweek is an interesting case because it contains two distinct yet interoperable components: a C++ API and a Java API. It is possible to use one without the other, and it is even possible to configure Tweek so that neither is compiled. Of course, the latter is a rather odd case that usually only occurs when something went wrong during the execution of the configure script. Furthermore, Tweek can be compiled against any Java or C++ CORBA 2.3 (or newer) implementation. This is the result of using high-level CORBA standards and interfaces that allow ORBs swapped and allow ORBs from different vendors to communicate with each other.

Due to Autoconf rules, all files that are to be generated by a configure script must have the suffix .in. Because of that, this is not so much a convention as it is a requirement. However, there are other files used in the build system, and their names are important.

Makefile stubs that make variable assignments have the string “defs” somewhere in their name. In general, such makefile stubs do not define any targets, though this may not always be the case. Examples are make.defs.mk, common.defs.mk (a Doozer++ file), and test.defs.mk.

In some cases, one makefile may include targets from another. The idea here is that the high-level tasks are defined in Makefile.in, and all the grunt work is done in the included file(s). Providing this separation can help casual viewers to understand the high-level tasks without worrying about all the behind-the-scenes details. The included files have the string “inc” in their name. The most common example seen in modules is Makefile.inc.in, though there could be files such as Makefile.inc0.in, Makefile.inc1.in, and so on. The use of numbering allows multiple files to be used for separating the tasks.

It is important to note that all of the makefiles named in the above examples begin with a capital letter. While it is often useful to include multiple makefiles in a single directory (of the Autoconf .in template variety and otherwise), there must never be a situation where a directory could contain the files Makefile and makefile. Win32 file systems cannot distinguish between the two, and only bad things can occur as a result.

Recently, there has been a shift in the style used to perform variable assignments. The new style is based on the formatting used in all FreeBSD system and ports makefiles. This style was adopted to make formatting makefiles easier and cleaner. It is shown below:

VAR=		value
OPT_VAR?=	default-setting
LIST_VAR=	item1	\
		item2	\
		item3

LIST_VAR+=	item4

The key is the whitespace around the assignment operators. On the left-hand side, there is no whitespace; on the right-hand side, there are one or more tabs. When using multiple lines, tabs are used for indentation. Spaces are never used. Because tabs must be used in makefile targets, it is convenient (with most editors) to use tabs for all formatting characters.

This convention is relatively new, and its adoption is not yet complete. Files that have not been updated should be reformatted when they are encountered.

Most implementations of make(1) allow the use of two variable reference styles. These are shown below:

VAR=	value

target:
	echo ${VAR}
	echo $(VAR)

In the first line of the target called 'target', curly braces are used. This is the same syntax used to clarify variable interpolations in most shell scripting languages. The second line uses parentheses.

In the Juggler Project, we prefer the use of parentheses over curly braces for the following reasons:

In all but one module in the Juggler Project, the basic structure of the glue makefile is the same: one makefile that defines high-level targets, and one included makefile that does all the work. In this subsection, we explain the way these two files work to make up the glue that holds a module's build system together. We begin with the simpler of the two: Makefile.in.

default: debug

DEFAULT_SET=	1

include @topdir@/make.defs.mk

include $(MKPATH)/dpp.subdir.mk
include Makefile.inc

STATICLIB_EXT=	@STATICLIB_EXT@
DYNAMICLIB_EXT=	@DYNAMICLIB_EXT@

LIBS=		$(MY_LIBRARY)
STATIC_LIBS=	$(LIBS)
DYNAMIC_LIBS=	$(LIBS)

MY_LIB_STATIC=		$(MY_LIBRARY).$(STATICLIB_EXT)
MY_LIB_DYNAMIC=		$(MY_LIBRARY).$(DYNAMICLIB_EXT)
MY_PROF_LIB_STATIC=	$(MY_LIBRARY)$(PROFLIB_EXT).$(STATICLIB_EXT)
MY_PROF_LIB_DYNAMIC=	$(MY_LIBRARY)$(PROFLIB_EXT).$(DYNAMICLIB_EXT)

$(LIBDIR)/$(MY_LIB_STATIC) $(LIBDIR)/$(MY_PROF_LIB_STATIC): $(OBJDIR)/*.$(OBJEXT)
	@$(SHELL) $(MKINSTALLDIRS) $(LIBDIR)                                        
	$(AR) $(AR_NAME_FLAG)$@ $(OBJDIR)/*.$(OBJEXT)                               
	$(RANLIB) $@                                                                
	cd $(LIBDIR_BASE) && $(RM_LN) $(notdir $@) && $(LN_S) $@ ./                 

$(LIBDIR)/$(MY_LIB_STATIC) $(LIBDIR)/$(MY_PROF_LIB_STATIC): $(OBJDIR)/*.$(OBJEXT)
ifneq (@OS_TYPE@, Win32)
	@$(SHELL) $(MKINSTALLDIRS) $(LIBDIR)
	$(AR) $(AR_NAME_FLAG)$@ $(OBJDIR)/*.$(OBJEXT)
	$(RANLIB) $@
	cd $(LIBDIR_BASE) && $(RM_LN) $(notdir $@) && $(LN_S) $@ ./
endif

DYLIB_DEPS=	@DYLIB_DEPS@                                                     
DYLIB_PROF_DEPS=	@DYLIB_PROF_DEPS@                                           

$(LIBDIR)/$(MY_LIB_DYNAMIC): $(OBJDIR)/*.$(OBJEXT)
	@$(SHELL) $(MKINSTALLDIRS) $(LIBDIR)
	$(LD) $(LDOPTS) $(DYLIB_NAME_FLAG) $(OBJDIR)/*.$(OBJEXT) $(DYLIB_DEPS)      
ifeq (@OS_TYPE@, Win32)
	cd $(LIBDIR_BASE) && cp $(LIBDIR)/* .                                       
else
	cd $(LIBDIR_BASE) && $(RM_LN) $(notdir $@) && $(LN_S) $@ ./                 
endif

$(LIBDIR)/$(MY_PROF_LIB_DYNAMIC): $(OBJDIR)/*.$(OBJEXT)
	@$(SHELL) $(MKINSTALLDIRS) $(LIBDIR)
	$(LD) $(LDOPTS) $(DYLIB_NAME_FLAG) $(OBJDIR)/*.$(OBJEXT) $(DYLIB_PROF_DEPS) 
ifeq (@OS_TYPE@, Win32)
	cd $(LIBDIR_BASE) && cp $(LIBDIR)/* .                                       
else
	cd $(LIBDIR_BASE) && $(RM_LN) $(notdir $@) && $(LN_S) $@ ./                 
endif

BEFOREINSTALL=	beforeinstall

beforeinstall:
	<create installation hierarchy>

PREINSTALL=	pre-install

pre-install:
	<perform steps immediately prior to library installation>

  1 instlinks=	$(topdir)/instlinks
    AFTERBUILD=	afterbuild
    
    afterbuild:
  5 	@$(MAKE) links
    
    links:
    ifdef BUILD_TYPE
    	$(MAKE) links-$(BUILD_TYPE)
 10 else
    	$(MAKE) links-all
    endif
    
    links-all:
 15 	@$(MAKE) EXTRA_INSTALL_ARGS=-l prefix="$(instlinks)" installworld
    
    links-dbg:
    	@$(MAKE) EXTRA_INSTALL_ARGS=-l prefix="$(instlinks)" install-debug
    
 20 links-opt:
    	@$(MAKE) EXTRA_INSTALL_ARGS=-l prefix="$(instlinks)" install-optim
    
    links-prof:
    	@$(MAKE) EXTRA_INSTALL_ARGS=-l prefix="$(instlinks)" install-profiled
 25 
    clean-links:
    ifndef GLOBAL_BUILD
    	rm -rf $(instlinks)
    endif

_clobber:                                                  
	@$(MAKE) cleandepend
	@$(MAKE) clean-links

_LOCAL_CLOBBER=	1                                          

include $(MKPATH)/dpp.libs.mk                              
include $(MKPATH)/dpp.clean.mk                             

CLEAN_DIRS+=	$(BUILDDIR_BASE) $(LIBDIR_NAME)               
CLOBBER_DIRS+=	$(BUILDDIR_BASE) $(LIBDIR_NAME)             

We now turn our attention to axillary files used by the glue makefile and the component makefiles (discussed in the section called “Individual Component Makefiles”). Most modules have only two axillary makefiles in their top-level directory: common.defs.mk.in and make.defs.mk.in. We discuss only those two files here; any extra files are project-specific and could probably be merged into make.defs.mk.in or Makefile.inc.in somehow.

include $(topdir)/common.defs.mk

topdir=	@topdir@

TWEEK_LIBRARY=	@LIB_PREFIX@tweek

Unless there are dramatic changes to the way Doozer++ does its job at the time of compilation, the file Makefile.in will remain fairly static. Extensions should almost always go in Makefile.inc.in or make.defs.mk.in, depending on the nature of the extensions. User changes should never be made to common.defs.mk.in. This file provides a reasonably complete set of variables for extending its behavior, and make.defs.mk.in serves as an ideal place to perform overrides to any settings made in common.defs.mk.in. The real problem occurs when it is necessary to copy a modified version of common.defs.mk.in from Doozer++. Merging local changes can be hard unless common.defs.mk.in is always imported onto a CVS vendor branch.

In the following sub-subsections, we examine the basic structure of a component makefile. This is almost a line-by-line examination of a given makefile. We concentrate our discussion on the compilation of C/C++ code since that makes up the majority of the Juggler Project. Java and IDL are handled somewhat differently, though the basic ideas are the same. The major difference is that no dependency files are generated for Java or IDL using Doozer++ 1.5.

include @topdir@/make.defs.mk

ifeq (@SOME_VAR@, "YES")
   SRCS+=	extra_src.cpp
endif

-include $(DEPEND_FILES)

ifndef DO_CLEANDEPEND
   -include $(DEPEND_FILES)
endif

Extension to a given component makefile is almost always done by adding more source files to the $(SRCS) variable assignment. Whether this is done using conditional constructs or extending the always-build list depends on the circumstances. Other extensions may come in the form of new files that may be generated from an IDL file or an extension to the list of files to be installed.