Doozer

Getting Started

The best way to get started with Doozer is to copy the template makefile found in /home/vr/apps/mk on the VRAC UNIX systems. The file is Makefile.template, and it contains an empty canvas for your application's Doozer makefile. We recommend that you copy it into your application source directory and name it Makefile. This will make it the default makefile used by GNU make when you build your application.

What follows is a description of the various parts of the template makefile. Detailed information about what each of the variables and the targets mean and how they are used by Doozer is provided. In this documentation, bold text indicates the variable or target being discussed, and italicized text represents what is to be filled in by the programmer.

Quick List of Topics

1. Heading Comments
2. Default Target
3. Application Name
4. Source Directory
5. Debugging vs. Optimized Applications
6. Extra Compiler Flags
7. Overriding Debugging and Optimization Flags
8. Source File List
9. Extra Libraries
10. Additional Source Directories
11. Alternate Object File Extension
12. Alternate Object Directory
13. Files and Directories to Clean Up
14. Including the Doozer .mk File
15. Application Targets
16. Automatically Generated Dependency Files

Heading Comments

The first thing to note in the template makefile is the heading comments. In particular, all important notes for users are listed in these comments. These comments are not listed here but should be looked over before beginning to fill in the template.

Default Target

Next is the default target for the makefile. This must be listed before anything else to ensure that the application is built properly. Whatever target is named as the default is what is built when GNU make is run with no arguments. The current default target is `all', and it is set as follows:

    default: all

Application Name

The first of the application-specific variables comes next. It is the name of your application, and it is crucial that a value be set. The value is set as in the following example:

    APP_NAME = nexus

The $(APP_NAME) variable is used by the makefile when building the application binary. Without a value for this variable, GNU make will fail when trying to do anything with your makefile. If you are writing your application so that it may be part of the Performer or OpenGL switcher applications, Doozer will use this variable internally to compile your application into the switcher.

Source Directory

The next variable is one that is not typically changed but is provided for flexibility user makefiles. It tells Doozer where to find the sources for your application which is usually the same directory as where the makefile is located. That is, it is usually set to `.' in most makefiles as follows:

    srcdir = .

It can, of course, be set to whatever is appropriate.

Debugging vs. Optimized Applications

Applications can be compiled with debugging symbols or with optimization but not both. (Most compilers favor one over the other if both sets of options are specified, so Doozer favors one set of options over another.) To choose one, set either the $(DEBUG_APP) or the $(OPTIM_APP) variable to TRUE. For example, to compile an application with debugging symbols:

    DEBUG_APP = TRUE
    OPTIM_APP = FALSE

To compile an optimized application, reverse the settings. If both variables are set to TRUE, debugging will be favored over optimized. If both are set to FALSE or neither are defined, then neither debugging nor optimization will be enabled when the application is compiled.

Extra Compiler Flags

Several variables are provided for extending the default set of C and C++ compiler options used by Doozer. These settings are appended to the corresponding default values. This is the place to put options needed for compiling against third-party libraries and anything else that the compiler and linker need to know about. For example, the include path for VTK headers would be put in $(EXTRA_INCLUDES). The variables are as follows:

EXTRA_CFLAGS

Extra application-specific flags used only by the C compiler when compiling the object files.

EXTRA_CXXFLAGS

Extra application-specific flags used only by the C++ compiler when compiling the object files.

EXTRA_DEBUG_FLAGS

Extra application-specific debugging flags used by the C compiler and the C++ compiler when compiling the object files.

EXTRA_INCLUDES

Extra directories that extend the default include path so that header files outside of the current directory and the VR Juggler directory can be found.

EXTRA_LDFLAGS

Extra application-specific flags used by the linker when linking the final application binary.

EXTRA_OPTIM_FLAGS

Extra application-specific optimization flags used by the C compiler and the C++ compiler when compiling the object files.

These variables are set in the same was as normal makefile variables.

Overriding Debugging and Optimization Flags

Should it be necessary to override the default flags for debugging and optimization, a simple facility is provided for doing this. Doozer uses two variables internally for adding debugging and optimization flags to the set of compiler flags depending upon the settings for $(DEBUG_APP) and $(OPTIM_APP) (see above). They are $(DEBUG_FLAGS) and $(OPTIM_FLAGS). If values for either or both of these are set in the user's makefile, then Doozer will use those values rather than its internal defaults as long as the user settings are done prior to including a Doozer .mk file. In other words, to override the defaults, set values for the variables with the rest of the extra compiler flags. For example, to set special, application-specific optimization flags that completely override Doozer's defaults, the following could be done:

    OPTIM_FLAGS = -O2 -opt:ptr-alias

It is important to note that this overriding mechanism can tie a makefile to a specific compiler and possibly to a specific platform. Therefore, these options are used at your own risk.

Source File List

The next variable, $(SRCS), is the heart of the entire build process. It lists the source files (but not the header files) that are compiled to create your application. It can contain both C and C++ headers--Doozer takes care of using the right compiler and linking them properly. A number of file extensions are supported by Doozer, and more can be added upon request (as long as the request is reasonable). Files with different exentions can be mixed in the list of sources. Currently, the list of supported extensions is as follows:

.c

C source files only.

.C, .CC, .cc, .cpp, .c++, .cxx

C++ source files.

An example of setting the $(SRCS) variable is:

    SRCS = main.cpp	\
           math.c	\
	   graphics.C	\
	   misc.cxx

In this example, there are three C++ source files and one C source file. The four files will be compiled into object files and linked into the final application binary.

Extra Libraries

Many applications need extra libraries beyond the standard list of VR Juggler libraries and graphics API-specifc libraries. To handle this, Doozer provides users with two variables for extending the library list: $(EXTRA_LIBS) and $(EXTRA_SYS_LIBS). The first of these is for third-party, non-system libraries such as the VTK libraries or libraries of your own that are required for linking and running the application. All libraries listed in this variable are added to the link line before any of the basic libraries and the default system libraries. For example, to link in a custom library called libhelpers with some helper functions you have written, do the following:

    EXTRA_LIBS = -L/path/to/lib -lhelpers

The second of these is for system libraries that your application needs. These are libraries that are part of the operating system and are usually found in /usr/lib or an equivalent location. Any libraries listed in this variable are added to the link line after all the basic libraries and all the default system libraries. An example of a system library is the POSIX threads library, libpthread on most UNIX-based systems. To include it in your application's system library list, do the following:

    EXTRA_SYS_LIBS = -lpthread

The default system libraries on UNIX-based platforms are libX11 and libXext. In addition to this, the math, OpenGL, Performer libraries are linked when they are needed. The appropriate VR Juggler libraries are of course always linked in since these are VR Juggler applications. It is very important to use these two variables properly. In particular, if your program is to be compiled into an application switcher, the $(EXTRA_LIBS) variable is used by Doozer to get the list of third-party, non-system libraries your application needs. It will use its own set of system libraries.

Additional Source Directories

In some cases, source files compiled into your application may be in other directories besides $(srcdir) (see above). In such a situation, the other directories must be listed in the $(EXTRA_PATH_FOR_SOURCES) variable so that Doozer can find them when it is compiling the object files. This variable is used typically in more advanced appliations and need not be a major concern for most users. Should it be necessary, however, an example of its use is as follows:

    EXTRA_PATH_FOR_SOURCES = /another/dir \
                             /yet/another/dir

Note that the paths must be absolute, especially if your application is being compiled into one of the switchers.

Alternate Object File Extension

Some compilers, most notably Microsoft Visual C++, require or at least expect a specific file extension on object files. For this reason, it is possible to override the default object file extension, though it is typically not necessary to do so since Doozer knows which compilers expect which extensions. However, in such as case where it is necessary, the override is done as follows:

    OBJECT_EXT = extension

Note that extension does not include the period since that is always going to be the same. Two common values here are obj or o, and as mentioned, Doozer does its best to use the proper value for the compiler in use.

Alternate Object Directory

If you want to build the object files in a directory other than the current directory, you can tell Doozer to use an alternate directory. This is done as follows:

    OBJDIR = /some/other/dir

As with previous variables containing directory paths, this must be an absolute path so that Doozer can find the directory without any difficulty.

Files and Directories to Clean Up

In the course of developing and compiling software, plenty of junk files are left lying around. Those that can be removed safely by the Doozer `clean' target are listed in the $(CLEAN_FILES) variable. Directories that can be removed recursively are listed in $(CLEAN_DIRS). Many standard files and directories are already removed by the `clean' target, and the ones listed in this variable are removed in addition to the default list. The default list is the application binary named by $(APP_NAME) (see above), the object files constructed from $(SRCS) (see above), the dependency files (see below) and all core files. The default directory that is removed is ii_files (in the object directory).

Including the Doozer .mk File

The most important step of creating your application's Doozer makefile is to include a Doozer application .mk file. This is what actually incorporates Doozer into your application's build. There are a few basic .mk files from which to choose, and you should choose the one that is appropriate for your application. Only one of these files can be included, but it is possible to switch which file is being used at any time. The Doozer application .mk files are the following:

/home/vr/apps/mk/vrac.glapp.mk

This file is used by an ordinay OpenGL application with no fancy bells or whistles.

/home/vr/apps/mk/vrac.pfapp.mk

This file is used by an ordinay Performer-based application.

/home/vr/apps/mk/vrac.juggler.glapp.mk

This file is used by an ordinay OpenGL VR Juggler application with no extras.

/home/vr/apps/mk/vrac.juggler.pfapp.mk

This file is used by an ordinay Performer-based VR Juggler application application.

Besides the above files, several ``add-on'' files are available to extend the features of your application. These are to be included in addition to one of the above base files and should be included after the application .mk file. With these, it is possible to include more than one in your makefile.

/home/vr/apps/mk/vrac.aw.mk

Add the AudioWorks paths and libraries when compiling and linking the application. This is usable with all types of applications (VR Juggler and otherwise).

/home/vr/apps/mk/vrac.sl.mk

Add the SL paths and libraries to your application's build environment. As with the AudioWorks file, this is usable with all types of applications.

/home/vr/apps/mk/vrac.juggler.switcher.mk

Set up the options and add the targets necessary to incorporate your program into a VR Juggler application switcher. This should only be used with VR Juggler applictions (both OpenGL and Performer).

Application Targets

The application targets are what define what is built and how. The targets for the object files are controlled by Doozer, but the `all' target and the target for linking the application are in the user's makefile. It is not usually necessary to change the application link target, but it is possible. Just be sure you know what you are doing! The `all' target is defined as follows:

    all: $(APP_NAME)

That is, building `all' will build your application as named in the $(APP_NAME) variable (see above). This can of course be extended or otherwise changed as necessary, but this is usually sufficient.

The target for building the application is next. The dependency for the application is its list of object files which is in $(OBJS). This variable is constructed by Doozer from the $(SRCS) variable. To link the application binary, the command in the $(LINK) variable is used. This is another variable set internally by Doozer. The last such variable set by Doozer is $(LIBS) which is the complete list of libraries needed to link this application except what may have been set prior to this in $(EXTRA_LIBS) (see above).

Automatically Generated Dependency Files

Finally, Doozer automatically generates depenencies for the source files in your application (those files listed in $(SRCS) described above). You need never list any dependencies in your makefiles because they are all computed on the fly and stored in the .d files created before compiling begins. This is all done using a rather complicated but useful feature of GNU make. It is important to note that the messages saying ...: filename.d: No such file or directory are normal. They simply mean that GNU make cannot find a certain .d file and thus will create that file for you. While it is safe to remove the .d files (the `clean' target does just this in fact), you should never try to create them yourself.