Lesson 0: Installing GLOW


Contents
Lesson 1

Code Reference Sidebars
testglow.cpp
Makefile 		Compiler compatibility
Preprocessor symbols 		Makefile customization

Introduction

This lesson covers the basics of installing GLOW and building a program using GLOW. It is geared primarily towards users of a unix-based operating system such as Linux or SGI IRIX, but an experienced user should be able to glean enough information to install on a Macintosh, Windows PC, or other type of workstation. The goal of this lesson is to install the GLOW source on your machine, and to successfully compile and run a simple GLOW-based program.

Installing

System requirements

GLOW's main system requirement is a good, up-to-date C++ compiler. Specifically, it should adequately support the November 1997 ANSI/ISO standard for C++, including such features as exceptions, namespacees, STL, new casting operators, RTTI, and new keywords such as bool, typename, explicit and mutable. As of the end of 1999, most compilers are still lacking in a few areas, so GLOW does provide facilities for getting around a few of the common omissions in compiler technology. In general, you should try to have the most recent version of your compiler installed.

I've successfully built GLOW with the following compilers:

I primarily use gcc under Linux for developing and testing GLOW, so that development system is currently the best supported. However, as other compilers converge on supporting the ANSI/ISO C++ standard, they should work better with GLOW's code over time.

GLOW also requires OpenGL and GLUT to be installed. I have also successfully used it with Mesa. If you don't know what OpenGL is, then you don't need to read any further because GLOW probably won't interest you.

A source code library

GLOW is a source code library. This means it is distributed as C++ source code, not as a compiled library file. I do this for two reasons: First, so that it can be used regardless of the platform you're running, and second, so you can choose which parts of GLOW you want to use, and so that you can modify it if you feel the need. You may choose to use GLOW directly in its source code form, by adding the GLOW sources to your projects. The lessons in this tutorial demonstrate the technique of using GLOW sources directly. However, if you use GLOW often, you may wish to make a library archive (libglow.a) or a shared library (libglow.so) for it. The section "Building a GLOW library" at the end of this lesson gives some details on how to build GLOW as a library.

Directories

The GLOW source is contained in the directory called "glow_src." Your first task is to copy this directory to a reasonable place in your file system. I keep it with the rest of my source code, but you may want to put it in /usr/lib or some other canonical location.

* IRIX/MIPSPro note

MISPPro 7.3 is missing some of the standard C++ headers, particularly the new-style names for the old C standard headers (such as <cmath>). I've provided a set of compatibility headers in the directory "Compat-SGI." MIPSPro users should also install these headers. I keep the entire Compat-SGI directory with the rest of my source code, and point to it with a -I directive to the compiler. You may choose to install them directly in your /usr/include/CC directory, but make sure you don't replace any files already there with the same names.

If you're using an IDE...

...such as Metrowerks Codewarrior or Microsoft Visual C++, then some of the information in this tutorial won't apply to you. However, you should still attempt to compile lesson 0 with your compiler, and make sure you know what compiler switches and libraries are necessary. The compiler section of the reference gives some hints on getting those two development systems to work.

Link toReference: Compiler compatibility

Makefiles

I provide a makefile for each program in this series of lessons. You do not need to use these makefiles if you don't want to-- they're just my personal makefiles-- and indeed if you are using an IDE such as Codewarrior or Microsoft Visual Dev Studio, you'll need to set up a project instead. The makefiles are designed to work on IRIX/MIPSPro and Linux/gcc, but they shouldn't be difficult to adapt to other unix systems. The only caveat is that they require a recent version of GNU-make, which you can download from the software section of the GNU home page if you don't have it. I recommend version 3.77 or later.

The makefiles provided with each lesson contain only a description of the program, the locations of the files needed, and the compile options. The actual "meat" of the makefile is in the file "glow_base.Makefile", which is located in the glow_src directory. The provided makefiles include this file automatically.

The makefiles as I provide them may work without modification if you are using a system configuration similar to mine, and you don't move any of the directories from the GLOW distribution. However, you'll probably want to install some of the directories, such as the glow_src directory, someplace canonical; in this case, for each makefile, you'll need to change a few variables to match your configuration and installation locations. Specifically, you need to set SRCDIR to the location of the source files for the current program. If you like to build in the same directory that your source lives, you can set this variable to "." the current directory. However, you can also set it to a different directory if you want to keep source and object separate (which I like to do). You also need to set GLOWDIR to point to your glow_src directory. You may also need to alter or remove the -I and -L directives in the CFLAGS and LDFLAGS symbols.

The other symbols should be pretty straightforward. MODULES should be set to the names of the source files (minus the .cpp extension). GLOWMODULES should be set to the names of the GLOW modules needed (again, without the .cpp extension). The other symbols are platform-specific and describe the compiler and compiler flags to be used. If you're running a system other than IRIX or Linux, you may need to alter these values, particularly LIBS and CFLAGS. If you really want to know the nuts and bolts of customizing my makefiles, or if you think it's cool and want to use it for your own projects, see the Makefiles sidebar.

Or it may be easier just to create your own makefile. The key here is to make sure that you compile the correct GLOW modules. It's easy to find out which ones a program needs-- just look at the value of the GLOWMODULES symbol, add ".cpp" to each name, and compile the appropriate files from your glow_src directory.

Finally, my makefile system provides what I call "file-options", which is a facility for customizing makefile options by the existence of files in the object directory. File-options are discussed in more detail in the sidebar, but there are two standard options that are of interest: DEBUG and STRIP. DEBUG turns on debug mode, which I recommend when compiling GLOW programs because it provides extended error checking, and also because if DEBUG isn't in effect, my makefile automatically defines NODEBUG. STRIP causes the binary to be stripped after it is linked. To activate a file-option, create a file called ".glowmake.<option_name>" in the directory you're building into. For example, to ensure that DEBUG mode is on, you can:

touch .glowmake.DEBUG

The reference document "Compiler compatibility" contains information on getting a GLOW program compiling with other compilers or other operating systems. Also see "Preprocessor symbols" for a list of symbols that you may need to use in your makefile for compatibility with older compilers that do not completely implement the ANSI C++ standard.

Link toReference: Compiler compatibility
Link toReference: Preprocessor symbols

Link toSidebar: Makefile customization

Building your first GLOW program

Now let's build your first GLOW program. First, download and unpack the GLOW distribution if you haven't already. Go into the directory tutorial/lesson0. If you have moved/installed the glow_src directory or the Compat-SGI directory, set up the Makefile as described above, paying close attention to the SRCDIR and GLOWDIR symbols. I also suggest creating a ".glowmake.DEBUG" file and a ".glowmake.STRIP" file. Finally, run gnu-make. Your compiler should build a program called "testglow". You can now run this program.

Did you have problems?

If the build wasn't succeessful, there are several different things that may have gone wrong. If you encountered an error message that looks something like this:

Symbols missing from makefile:
COMPILE DEPFLAGS

then most likely your problem is that you're running on an operating system other than IRIX or Linux. See the sidebar on customizing your makefile.

If you encountered an error like this:

No rule to make target `testglow.dep'

then you've likely set up your SRCDIR symbol incorrectly. Make sure it points to the directory in which your testglow.cpp source file resides. If it instead complains about not finding the file glow_base.Makefile, then your GLOWDIR symbol isn't pointing to your glow_src directory.

If the compiler complains:

The source file "csignal" is unavailable.

then you're running MIPSPro but don't have the MIPSPro compatibility headers in the Compat-SGI directory installed properly, or else your compiler does not support the new ANSI C++ header names.

Building a GLOW library

If you use GLOW often, you can build a library archive or a shared library. I have provided a makefile in the glow_src directory for that purpose. The makefile is designed for the IRIX and Linux operating systems, so if you are running under one of those systems, you should be able to build the libraries by simply running gnu-make. If you are running a different unix system, you'll need to make some changes to the makefile.

The makefile will generate four libraries:

The debug libraries are compiled with GLOW_OPTION_DEBUG. If you choose to use GLOW as a library, you should link with the library corresponding to the debug option you used to compile the rest of your program. (The makefiles provided with the tutorials choose the proper library automatically.)

To install the libraries, build them by making in the glow_src directory, then copy them to an appropriate directory such as /usr/lib. You should also rename the libraries to remove the version number, or create soft links without the version in the name. For example: 

ln -s libglow.so.1.0.1 libglow.so

What if I use Windows or Mac?

You should be able to build a Windows static library using MSVC++ 6.0. Just make sure you set up your project using the appropriate stationery to build a static library. More information on compiling GLOW sources using MSVC is available in the compiler compatibility section of the reference.

I don't think it's possible to build a DLL of GLOW using Microsoft's current tools. GLOW uses templates and STL containers fairly heavily, and MSVC has trouble dllexporting classes with lots of template activity. (However, I don't have a lot of experience with MSVC, so I'm not absolutely sure it's impossible. If you are able to build a DLL of GLOW, please let me know how you did it.)

I haven't tried building GLOW as a static or shared library on the Mac yet, but Metrowerks Codewarrior shouldn't have too much trouble with it.

Link toReference: Compiler compatibility

Where to go from here

Now that you've successfully built a GLOW program, we can start looking at how to use GLOW to build portable user interfaces for OpenGL programs. Lesson 1 starts this by introducing our tutorial project, a Mandelbrot set viewer. If you're adventurous, you can also look through the source code for testglow.cpp to get a preview of how GLOW programs are constructed.


Contents
Lesson 1

The GLOW Toolkit