Subversion Repositories gelsvn

GEL README, Andreas Bærentzen, February 2006.

==========

This README describes the GEL project. GEL stands for Geometry and Linear 

Algebra which are the constituents we will mostly put into this library. It is

intended as a library for computer graphics and computer vision tasks with a

strong emphasis on the handling of shape and geometry. 

GEL is broken down into a number of libraries, and the overall structure is as

follows:

- CGLA is a library targeted at vectors and matrices of dimensions 2,3, and

  4. CGLA is useful in computer graphics where small efficient vectors are

	everywhere.

- LinAlg is a very simple Lapack wrapper which simplifies solving (large)

  linear systems. 

- Geometry contains (mostly) Spatial data structures. There are voxel grid

	class templates and a K-D tree template. There is also a triangle mesh class

	useful for real time rendering.

- HMesh is a half edge based polygonal mesh data structure. This is useful for

	algorithms which change mesh connectivity.

- GLGraphics contains Tools for visualization. There is a trackball and some

	other OpenGL compatible tools.

- Util contains various utilities such as hash table classes, a tool for

	command line arguments, a 2D grid class, a resource manager and other

	miscellany.  

GEL is intended for use both under a variety of unix platforms (Linux

and OSX in particular) and  under windows. This README is mostly for

unix users. Windows users should also consult README_MSVC

Dependencies: GEL depends on Lapack/BLAS, and OpenGL and GLUT. However, the applications have more dependencies.

Who made GEL

==========

GEL is mostly the work of Andreas Bærentzen, but other people

contribute. In particular, Jeppe Frisvad, Bjarke Jakobsen, Henrik

Aanæs, and Bent D. Larsen. We are all from Informatics and

Mathematical Modelling, a department of the Technical University of

Denmark. 

Regarding LICENSE.

==========

I was considering putting GEL under the LGPL. But it is a long complex

text. The longer any kind of document, the more chances for loopholes

in my opinion. Instead, I list a few simple rules below. The most

important one is that if you want to use GEL for some purpose, and it

is not crystal clear whether it is against the rules, contact me. As

for the rules:

You are allowed to use GEL for academic or commercial purposes. In

particular, you are welcome to give GEL to students as a basis for 

academic work or to use it for your own applications.

The biggest limitation that I want to impose is that you cannot repackage

GEL in any way. You are not allowed to distribute another library which

contains GEL or parts of GEL unless you make it clear that this other

library contains GEL. You are also not allowed to redistribute GEL in a

changed form. If you want changes to be made, contact me.

Of course, neither I nor my employer will give you any money or be

held responsible in any way, under any circumstances what so ever - no

matter what sort of damage GEL might inflict upon you. Not that I can

foresee GEL causing you any damage :-) 

If anything is unclear, please contact me. In fact, if you want to use

GEL for a bigger project, I'd appreciate an email to jab@imm.dtu.dk

In a project such as this, it is almost impossible to completely avoid

building upon fragments of other peoples source code. GEL includes an

obj loader based on work by Nate Robins. Some pieces of source code

from Graphics Gems have also been used. All of this amounts to only a

small fraction of the GEL source code and it should not be in

violation of any license. Should you disagree, contact me, and I will

rectify the situation.

----------------------------------------------------------------------

1. INTRODUCTION

----------------------------------------------------------------------

In the following, I discuss the structure of the source code and how to

add new directories to the framework. 

The idea is that this framework should be a) simple to use and b) let 

people easily compile the same source code under various unix platforms.

A seperate configuration is kept for each combination of OS, architecture, 

and compiler. It is possible to specify targets release or debug.

Source files are compiled in build directories, and separate build 

directories are kept for each unique combination of 

os architecture compiler target

such as

Linux_i686_g++3_debug

this makes it easier to work in a heterogenous environment or to 

experiment with seperate compilers or just to switch between debug mode 

and optimized.

To see how to use the framework, you may skip to section 5.

----------------------------------------------------------------------

2. DIRECTORY STRUCTURE

----------------------------------------------------------------------

The directories under the root of the source tree (where you find this 

README) are

src        - Source code for GEL libraries

apps       - Source code for applications

apps       - Source code for test programs

doc        - Documentation

bin        - Executables

lib        - Libraries

makefiles  - As the name suggests, makefiles

src contains a number of subdirectories each of which represents a 

link library. apps  also contains subdirectories, however each of these

is supposed to contain source code for an executable.

----------------------------------------------------------------------

3. FILE NAMES

----------------------------------------------------------------------

source files are *.c or *.cpp depending on whether it is C or C++

header files are named *.h

----------------------------------------------------------------------

4. MAKEFILES

----------------------------------------------------------------------

Some defintions:

----------------

The PLATFORM is a string concatenation of the os cpu and compiler, e.g.

Linux_i686_g++

The TARGET is either `debug' or `release'. By default it is debug. It is

recommended that you do _not_ hardwire your own default into the makefiles

as I did for many years. It seems better to define the variable when running

make, using "make TARGET=release" or by setting the target variable in the

environment.

Make'ing from the source root

-----------------------------

Just typing

> make 

from the root of the source tree will cause first every library and

then every application to be remade. However, there are several

targets.

make all			 - equivalent to "make lib shared test app"

make lib       - make all libraries

make shared    - For the current target platform combination, a shared library

								 is created by stringing together the compiled static libraries

make app       - make all applications

make clean     - clean all library directories and app directories.

                 this removes only files pertaining to the current

                 platform and target (release/debug). This also

                 removes generated libraries. 

make distclean - cleans and completely removes all build directories. 

make platform  - copies a template to OS_CPU_COMPILER.mk in the

                 makefiles directory. Use this only if you know what you

								 are doing.

make install   - Copies header files and libraries to the appropriate place

							   which is PREFIX=/usr/local by default. The libraries which

								 are copied are either the debug or release versions depending

								 on the active target. 

								 Install does not install applications since many are little

								 test programs that do not belong in your path.

Make'ing in subdirectories

--------------------------

Go to a subdirectory of src, say src/somedir. 

Here you have the following options:

make

make lib

make clean

The first two invocations are identical and will rebuild all sourcefiles and

put them in a library directory. The latter will remove all object and

dependency files (but only for the current platform

(e.g. Linux_i686_g++_debug) The default target is lib.

Go to a subdirectory of apps, say apps/somedir. 

Here you have the following options:

make

or

make app

will recompile the source files in the current directory and build the 

programs. This is the default target. When compiled, the application is

moved to wherever/GEL/bin

make force

does the same but tries first to recompile all libraries that the 

applications in somedir depend on. This is the safe way to recompile,

but it takes a few seconds more, so if you are sure the libraries are

up to date, just go make.

make clean

works like above. 

Makefiles in subdirectories under apps should generally be edited.

When create by `make makefiles' the Makefile in apps/somedir looks

like this 

PROGRAMS 	= prog1 prog2

OWN_LIBS 	= Lib1 Lib2

LIBS			= ${GLLIBS} ${XLIBS} -lm -lz -lexpat

Add something like this

PROGRAMS 	= prog1 prog2

OWN_LIBS 	= Lib1 Lib2

LIBS			= ${GLLIBS} ${XLIBS} -lm -lz -lexpat

where prog1 and prog2 are programs you wish to create. These must 

correspond to source files with the same name and suffix .cpp. In

other words, 

prog1.cpp 

prog2.cpp

must exist (and contain a main function)

Lib1 and Lib2 are libraries that must also be in the directory structure,

i.e. under src there are subdirectories 

src/Lib1

src/Lib2

the files in these subdirectories will be compiled and put in library 

files named libLib1.a under lib. More precisely it will be put here:

lib/PLATFORM_TARGET/

PLATFORM and TARGET are defined above. Another library directory are for

precompiled libraries whose source code is not a part of this tree. Put

such libraries here:

lib/PLATFORM/

this directory is created by 

make platform from the source root.

----------------------------------------------------------------------

5. CONFIGURATION

----------------------------------------------------------------------

When you add a new project to this framework, you should go through

the following steps:

Add directories for libraries under src. E.g. add 

mkdir src/somelib

Then add directories for applications:

mkdir apps/someapp

Copy appropriate source files to these directories and then edit

makefiles/config.mk

to tell us which compiler to use (leave blank to use default) 

Finally, from the source root type 

make platform

Depending on your compiler you may now have to edit the makefile called

makefiles/PLATFORM.mk 

to set special compile flags. No go 

make makefiles

Finally you are all set. Go

make

----------------------------------------------------------------------

6. DEPENDENCIES IN GEL

----------------------------------------------------------------------

Each directory under src represents a library. There are some dependencies

between these libraries.

lib						depends on

-----------------------------------

CGLA 					nothing 

Util 					CGLA

LinAlg 				CGLA

Geometry 			LinAlg, CGLA

HMesh					CGLA, Util, Geometry, LinAlg (indirectly)

GLGraphics		Everything (since it contains general rendering

							facilities)

----------------------------------------------------------------------

7. TODO

----------------------------------------------------------------------

- No real testing of blended C and C++.

- No dependency computation for .c