Installation Instructions for GAlib

The distribution comes in three flavors: UNIX, MacOS, and Windows. The source code for all flavors is the same. The UNIX version is tarred and compressed (.tar.gz), the MacOS version is a Stuffit self-extracting archive in HQX format (.sea.hqx), and the DOS version is in ZIP format (.zip). Included in the distribution is the complete documentation in html format.

There are two things to build: the library and the examples.

Be sure to read over the section about template instantiation if your compiler starts to choke and spew errors. Most errors people encounter are linker errors and are typically due to template instantiation problems. Apologies for all of the 'signed/unsigned' warnings - we'll clean all of that up one of these days.




Unix compilation:

Edit the file 'makevars'. This file contains the compiler flags that are unique for each cpu/os/compiler, as well as the destination directory for doing 'make install'.

To build the library and the non-graphic examples: 
  % make
To install GAlib on your system: 
  % make install
To build the graphic examples: 
  % cd examples/graphic; make

Depending on your compiler and operating system, you may have to edit the gaconfig.h header file in the ga directory. It has preprocessor directives set up for some of the compilers/OSes on which I have been able to test. First try compiling without editting gaconfig.h. If that does not work, then read the comments in gaconfig.h and adjust that file as needed.

If you are compiling the graphic examples or the parallel examples, take a look at the makefile for each one to make sure that it is configured appropriately for your system.

The GNU version of make uses a syntax different than that in the GAlib examples distribution. If you use GNU make, uncomment the GNU make section of the examples makefile and comment the corresponding section: 

       # Use this for gnu-make
       $(EXS): %: %.o
              $(C++C) $@.o -o $@ $(LIB_DIRS) -lga -lm

Many people using g++ have reported compiler errors that complain about memset not being declared properly. Typical error messages look like this: 

../ga/objective.h: In method `GAObjectiveVector::GAObjectiveVector(unsigned int, float (*)(const GAObjectiveVector &))':
In file included from ../ga/genome.h:33,
                 from ../ga/ga.h:99,
                 from ga.C:20:
../ga/objective.h:68: warning: ANSI C++ forbids implicit conversion from `void *' in assignment
../ga/objective.h:68: warning: implicit declaration of function `int memset(...)"
This seems to be due to an error in the string.h header file in the gnu installation, not a problem in galib. Evidently some versions of g++ have an incomplete string.h in the lib/g++-include directory. Try using the -I compiler flag to force g++ to use a valid string.h (or update your gnu installation to replace the bogus string.h file).

Some people with gnu installations and makedepend experience the following error/warning when makedepending GAlib: 

makedepend: warning:  error.C (reading /mit/gnu/lib/g++-include/libio.h, line 32): cannot find include file "_G_config.h"
        not in /mit/gnu/lib/g++-include/_G_config.h
        not in /mit/gnu/lib/g++-include/_G_config.h
        not in ../_G_config.h
        not in /usr/local/lib/gcc-include/_G_config.h
        not in /usr/include/_G_config.h
The problem is that makedepend does not know where to look to find the gnu private headers, in this case _G_config.h (you may see the warning refer to _IO_config.h). You can build GAlib despite this warning - makedepend is not critical to the compilation of the library. To fix the problem, add the path to the gnu header to the makedepend line in the makefile.




MacOS compilation:

Set the includes path so that the directory in which the GAlib headers are located is searched before the system includes. Set the compiler to use strict ANSI compilation. Set the development environment to use the C++ compiler on .C files.

Adding the string genome or real number genome source files to a project may cause the compilation to fail (depending on your compiler). They are designed to be included by other source files rather than being compiled themselves. They contain specializations of template classes.

The FTP site contains project files for some mac compilers. Each of these expands to a projects directory that contains stationery for creating the examples and a sample project for creating the library. You can either build the library then link to it from subsequent projects, or you can include specific GAlib files in each new project that you create.

If you cannot get the library to build right out-of-the-box, you may need to edit gaconfig.h to tailor GAlib to your OS/compiler configuration. When you edit gaconfig.h, use directives similar to those defined for __MWERKS__




Windows 9x/NT compilation:

Be sure to set the includes path so that the directory in which the GAlib headers are located is searched. Also, set the compiler to use strict ANSI compilation. Define the NO_STREAMS directive (do this in gaconfig.h) if you want to compile GAlib with no dependency upon the streams library. Set the development environment to use the C++ compiler on .C files (this is the /TP flag in MS Visual C++). Enable RTTI in Visual C++.

Adding the string genome or real number genome source files to a project may cause the compilation to fail (depending on your compiler). They are designed to be included by other source files rather than being compiled themselves. They contain specializations of template classes.

The FTP site contains project files for some PC compilers. You can either build the library then link to it from subsequent projects, or you can include specific GAlib files in each new project that you create.

Microsoft's Visual C++ compiler complains about statements such as float x = 0.0; To disable these warnings, insert the following into the gaconfig.h file: 

       #if defined(_MSC_VER)
       #pragma warning (disable : 4244)
       #pragma warning (disable : 4305)
       #endif
If you want to use GAlib with MFC, then be sure to turn off streams by defining NO_STREAMS in the gaconfig.h file: 
       #define NO_STREAMS

If you cannot get the library to build right out-of-the-box, first try changing your compiler settings (particularly if you are using VC++). Then edit gaconfig.h to tailor GAlib to your OS/compiler configuration.

I find it easiest to compile from the command line rather than using VC++ projects. On NT, use nmake to do the build like this: 

       nmake /nologo /f makefile.win32
Or, to make life easier, create a file called make.bat with the following in it and put it in your path: 
       nmake /nologo /f makefile.win32 %1 %2 %3
Then you can simply type 'make' or 'make install'.

If you want to build the graphic examples, be sure to download the windows-specific packages in addition to GAlib itself. They are called gademo.zip and tspdemo.zip.

If you prefer to compile GAlib using a project, then see the project_files directory on the ftp server for some examples. I no longer maintain these project files, but they will give you an idea of how to set things up.




DOS/Win compilation:

When compiling under DOS or Win3.1, use the large memory model. When you compile the library by itself, use a library page size of 32.

Be sure to set the includes path so that the directory in which the GAlib headers are located is searched. Also, set the compiler to use strict ANSI compilation. Define the NO_STREAMS directive (do this in gaconfig.h) if you want to compile GAlib with no dependency upon the streams library.

Adding the string genome or real number genome source files to a project may cause the compilation to fail (depending on your compiler). They are designed to be included by other source files rather than being compiled themselves. They contain specializations of template classes.

By default, the library is configured to use the system's 'rand' random number generator when compiled with the Borland compiler. This is because I've had problems with the better RNGs (ran2) in 16-bit mode. If you are compiling a 32-bit application and you're using a Borland compiler, you should edit gaconfig.h so that USE_RAND is not defined. In any event, be sure to check the integrity of the random number generator by building and running the randtest example as soon as you build the library.




Custom compilation:

Edit the gaconfig.h file. You should read the comments in gaconfig.h so that you know what the machine- and compiler-specific options are. You can set these options either by #define-ing the macros in gaconfig.h or by defining them using your compiler's pre-processor directives. I have put a few compiler-specific #defines in gaconfig.h, but I don't know the characteristics of all the compilers, nor do I know the compiler-specific preprocessor directives.

Be sure to set the includes path so that your compiler knows where to look for the GAlib header files. Also, be sure the compiler is using a strict ANSI compilation mode.

You can either compile a library or only the parts of GAlib that you need. In either case, see the listing below to determine which files you will need.




Template instantiation issues

If your compiler uses the Cfront automatic instantiation model (code repositories) you should not have to do anything special.

If your compiler uses the Borland automatic instantiation model (all template code must be in the header files), then define the BORLAND_INST macro. This will cause all of the header files with template classes to include the associated source files. If your compiler uses this method of template instantiation, you do not need to include any of the template source files in your project. These include GAAllele.C GA1DArrayGenome.C, GA2DArrayGenome.C, GA3DArrayGenome.C, GAListGenome.C, GAList.C, GATreeGenome.C, GATree.C)

If your compiler does not do automatic instantiation (for example, g++ 2.6.8) then define the NO_AUTO_INST macro. This will force an instantiation in the source files that specialize template classes (for example, the GAStringGenome). Note that there are (at least) two different syntaxes for forcing instantiation. The GNU compiler likes 'template class' before the forced instantiation, but the Borland compiler does not.

The symptoms of no automatic instantiation are linker warnings about member functions not being found (or defined) for template classes (e.g. GAAlleleSet when you're using real number genomes, or GAAlleleSet when you're using string genomes).

The string and real number genomes are treated differently than the other genomes in GAlib because they are specializations of template classes. They are not included in the ga.h header so that they will not force instantiations where they are not needed.

Do not explicitly compile GARealGenome.C or GAStringGenome.C! These are specializations of template classes and should be included once (and only once) in one of your source files. If you are using a real number genome, include GARealGenome.h in any file that refers to a real number genome and include GARealGenome.C in one (and only one) location in your code. GARealGenome.C contains a specialization of the one-dimensional array class, so by including it in a single location you will tell the compiler to use the specialization rather than the generic template code. The string genome is also a specialization of the one-dimensional array genome, so to use it you should follow the same guidelines (but include the string genome header and source rather than the real number genome header and source).




What to do if your compiler does not understand templates

If your compiler does not support templates, get one that does :)

You can compile the library by defining the NO_TEMPLATES preprocessor directive. If you do this, you can use only the BinaryString genomes (1D, 2D, and 3D). All of the other genomes are implemented as template classes. If you define the NO_TEMPLATES directive then you should not compile the following files:

GAAllele.C GA1DArrayGenome.C GA2DArrayGenome.C GA3DArrayGenome.C
GAListGenome.C GAListBASE.C GAList.C
GATreeGenome.C GATreeBASE.C GATree.C
If you need one of the template genome types but do not have a compiler that understands templates, you can modify the template files by hand. You will have to create a file for each type that you want to instantiate. If you will be instantiating only one type, remove <T> and replace T with the type you are going to instantiate. If you will be instantiating more than one type then you will have to replace <T> with an appropriate name and replace T with the type. For example, to create an instance of an 'int' version of the tree object, GATree<int> would become GATreeInt and any occurances of 'T * var' would be replaced with 'int * var'.

Matthew Wall, 12 November 1996, updated February 2000