WebSVN – gelsvn – Diff – /trunk/README/

+GEL README, Andreas Bærentzen, February 2006.
+==========
- GEL README, Andreas Bærentzen, March 05
+This README describes the GEL project. GEL stands for Geometry and Linear
+Algebra which are the constituents we will mostly put into this library.
- This README describes the GEL project. GEL stands for Geometry and Linear
+There are a good many tools for computational geometry processing: A
- Algebra which are the constituents we will mostly put into this library.
+voxel grid and a simple triangle mesh data structure. There is also a
+more advanced triangle mesh data structure called IMesh and a halfedge
+based polygonal mesh data structure called HMesh. There is a very
+useful data structure known as a k-D tree and many other things.
- This is a complex source tree which is intended for use both under a
+Also found are two packages for linear algebra: CGLA is strictly for
- variety of unix platforms and under windows. This README is mostly for
+small vectors and matrices. LinAlg is a Lapack wrapper for slightly
- unix users. Windows users should also consult README_MSVC
+larger problems. At this point, it is fairly simple.
+Finally there are some utilities in Util: Getting command line
+arguments, hash table classes, 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 the Developers Image Library DevIL,
+Lapack, and OpenGL and GLUT. However, most of GEL does not require
+these dependencies. In particular, you do not need DevIL except if you
+want the OBJ viewer example program.
+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.
 ----------------------------------------------------------------------
 . 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.
 ----------------------------------------------------------------------
 . 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.
 ----------------------------------------------------------------------
 . FILE NAMES
 ----------------------------------------------------------------------
 source files are *.c or *.cpp depending on whether it is C or C++
 header files are named *.h
 ----------------------------------------------------------------------
 . 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.
 ----------------------------------------------------------------------
 . 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
 ----------------------------------------------------------------------
 . 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)
 ----------------------------------------------------------------------
 . TODO
 ----------------------------------------------------------------------
 - No real testing of blended C and C++.
 - No dependency computation for .c

Subversion Repositories gelsvn

(root)/trunk/README/ – Rev 178 → 209