WebSVN – gelsvn – Diff – /branches/SPD/README


 
 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 is a complex source tree which is intended for use both under a 
 variety of unix platforms and under windows. This README is mostly for
 unix users. Windows users should also consult README_MSVC
 
======================================================================
 
----------------------------------------------------------------------
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 
 
 
 
 
 
 
 

Subversion Repositories gelsvn

(root)/branches/SPD/README – Rev 178 → 207

Rev 178		Rev 207
1		1
2	`GEL README, Andreas Bærentzen, March 05`	2	`GEL README, Andreas Bærentzen, March 05`
3		3
4	`This README describes the GEL project. GEL stands for Geometry and Linear`	4	`This README describes the GEL project. GEL stands for Geometry and Linear`
5	`Algebra which are the constituents we will mostly put into this library.`	5	`Algebra which are the constituents we will mostly put into this library.`
6		6
7	`This is a complex source tree which is intended for use both under a`	7	`This is a complex source tree which is intended for use both under a`
8	`variety of unix platforms and under windows. This README is mostly for`	8	`variety of unix platforms and under windows. This README is mostly for`
9	`unix users. Windows users should also consult README_MSVC`	9	`unix users. Windows users should also consult README_MSVC`
10		10
11	`======================================================================`	11	`======================================================================`
12		12
13	`----------------------------------------------------------------------`	13	`----------------------------------------------------------------------`
14	`1. INTRODUCTION`	14	`1. INTRODUCTION`
15	`----------------------------------------------------------------------`	15	`----------------------------------------------------------------------`
16		16
17	`In the following, I discuss the structure of the source code and how to`	17	`In the following, I discuss the structure of the source code and how to`
18	`add new directories to the framework.`	18	`add new directories to the framework.`
19		19
20	`The idea is that this framework should be a) simple to use and b) let`	20	`The idea is that this framework should be a) simple to use and b) let`
21	`people easily compile the same source code under various unix platforms.`	21	`people easily compile the same source code under various unix platforms.`
22	`A seperate configuration is kept for each combination of OS, architecture,`	22	`A seperate configuration is kept for each combination of OS, architecture,`
23	`and compiler. It is possible to specify targets release or debug.`	23	`and compiler. It is possible to specify targets release or debug.`
24		24
25	`Source files are compiled in build directories, and separate build`	25	`Source files are compiled in build directories, and separate build`
26	`directories are kept for each unique combination of`	26	`directories are kept for each unique combination of`
27		27
28	`os architecture compiler target`	28	`os architecture compiler target`
29		29
30	`such as`	30	`such as`
31		31
32	`Linux_i686_g++3_debug`	32	`Linux_i686_g++3_debug`
33		33
34	`this makes it easier to work in a heterogenous environment or to`	34	`this makes it easier to work in a heterogenous environment or to`
35	`experiment with seperate compilers or just to switch between debug mode`	35	`experiment with seperate compilers or just to switch between debug mode`
36	`and optimized.`	36	`and optimized.`
37		37
38	`To see how to use the framework, you may skip to section 5.`	38	`To see how to use the framework, you may skip to section 5.`
39		39
40	`----------------------------------------------------------------------`	40	`----------------------------------------------------------------------`
41	`2. DIRECTORY STRUCTURE`	41	`2. DIRECTORY STRUCTURE`
42	`----------------------------------------------------------------------`	42	`----------------------------------------------------------------------`
43		43
44	`The directories under the root of the source tree (where you find this`	44	`The directories under the root of the source tree (where you find this`
45	`README) are`	45	`README) are`
46		46
47	`src - Source code for GEL libraries`	47	`src - Source code for GEL libraries`
48	`apps - Source code for applications`	48	`apps - Source code for applications`
49	`apps - Source code for test programs`	49	`apps - Source code for test programs`
50	`doc - Documentation`	50	`doc - Documentation`
51	`bin - Executables`	51	`bin - Executables`
52	`lib - Libraries`	52	`lib - Libraries`
53	`makefiles - As the name suggests, makefiles`	53	`makefiles - As the name suggests, makefiles`
54		54
55	`src contains a number of subdirectories each of which represents a`	55	`src contains a number of subdirectories each of which represents a`
56	`link library. apps also contains subdirectories, however each of these`	56	`link library. apps also contains subdirectories, however each of these`
57	`is supposed to contain source code for an executable.`	57	`is supposed to contain source code for an executable.`
58		58
59	`----------------------------------------------------------------------`	59	`----------------------------------------------------------------------`
60	`3. FILE NAMES`	60	`3. FILE NAMES`
61	`----------------------------------------------------------------------`	61	`----------------------------------------------------------------------`
62		62
63	`source files are .c or .cpp depending on whether it is C or C++`	63	`source files are .c or .cpp depending on whether it is C or C++`
64	`header files are named *.h`	64	`header files are named *.h`
65		65
66	`----------------------------------------------------------------------`	66	`----------------------------------------------------------------------`
67	`4. MAKEFILES`	67	`4. MAKEFILES`
68	`----------------------------------------------------------------------`	68	`----------------------------------------------------------------------`
69		69
70	`Some defintions:`	70	`Some defintions:`
71	`----------------`	71	`----------------`
72		72
73	`The PLATFORM is a string concatenation of the os cpu and compiler, e.g.`	73	`The PLATFORM is a string concatenation of the os cpu and compiler, e.g.`
74		74
75	`Linux_i686_g++`	75	`Linux_i686_g++`
76		76
77	The TARGET is either `debug' or `release'. By default it is debug. It is	77	The TARGET is either `debug' or `release'. By default it is debug. It is
78	`recommended that you do _not_ hardwire your own default into the makefiles`	78	`recommended that you do _not_ hardwire your own default into the makefiles`
79	`as I did for many years. It seems better to define the variable when running`	79	`as I did for many years. It seems better to define the variable when running`
80	`make, using "make TARGET=release" or by setting the target variable in the`	80	`make, using "make TARGET=release" or by setting the target variable in the`
81	`environment.`	81	`environment.`
82		82
83		83
84	`Make'ing from the source root`	84	`Make'ing from the source root`
85	`-----------------------------`	85	`-----------------------------`
86		86
87	`Just typing`	87	`Just typing`
88	`> make`	88	`> make`
89		89
90	`from the root of the source tree will cause first every library and`	90	`from the root of the source tree will cause first every library and`
91	`then every application to be remade. However, there are several`	91	`then every application to be remade. However, there are several`
92	`targets.`	92	`targets.`
93		93
94	`make all - equivalent to "make lib shared test app"`	94	`make all - equivalent to "make lib shared test app"`
95		95
96	`make lib - make all libraries`	96	`make lib - make all libraries`
97		97
98	`make shared - For the current target platform combination, a shared library`	98	`make shared - For the current target platform combination, a shared library`
99	`is created by stringing together the compiled static libraries`	99	`is created by stringing together the compiled static libraries`
100		100
101	`make app - make all applications`	101	`make app - make all applications`
102		102
103	`make clean - clean all library directories and app directories.`	103	`make clean - clean all library directories and app directories.`
104	`this removes only files pertaining to the current`	104	`this removes only files pertaining to the current`
105	`platform and target (release/debug). This also`	105	`platform and target (release/debug). This also`
106	`removes generated libraries.`	106	`removes generated libraries.`
107		107
108	`make distclean - cleans and completely removes all build directories.`	108	`make distclean - cleans and completely removes all build directories.`
109		109
110	`make platform - copies a template to OS_CPU_COMPILER.mk in the`	110	`make platform - copies a template to OS_CPU_COMPILER.mk in the`
111	`makefiles directory. Use this only if you know what you`	111	`makefiles directory. Use this only if you know what you`
112	`are doing.`	112	`are doing.`
113		113
114	`make install - Copies header files and libraries to the appropriate place`	114	`make install - Copies header files and libraries to the appropriate place`
115	`which is PREFIX=/usr/local by default. The libraries which`	115	`which is PREFIX=/usr/local by default. The libraries which`
116	`are copied are either the debug or release versions depending`	116	`are copied are either the debug or release versions depending`
117	`on the active target.`	117	`on the active target.`
118		118
119	`Install does not install applications since many are little`	119	`Install does not install applications since many are little`
120	`test programs that do not belong in your path.`	120	`test programs that do not belong in your path.`
121		121
122		122
123	`Make'ing in subdirectories`	123	`Make'ing in subdirectories`
124	`--------------------------`	124	`--------------------------`
125		125
126	`Go to a subdirectory of src, say src/somedir.`	126	`Go to a subdirectory of src, say src/somedir.`
127	`Here you have the following options:`	127	`Here you have the following options:`
128		128
129	`make`	129	`make`
130	`make lib`	130	`make lib`
131	`make clean`	131	`make clean`
132		132
133	`The first two invocations are identical and will rebuild all sourcefiles and`	133	`The first two invocations are identical and will rebuild all sourcefiles and`
134	`put them in a library directory. The latter will remove all object and`	134	`put them in a library directory. The latter will remove all object and`
135	`dependency files (but only for the current platform`	135	`dependency files (but only for the current platform`
136	`(e.g. Linux_i686_g++_debug) The default target is lib.`	136	`(e.g. Linux_i686_g++_debug) The default target is lib.`
137		137
138	`Go to a subdirectory of apps, say apps/somedir.`	138	`Go to a subdirectory of apps, say apps/somedir.`
139	`Here you have the following options:`	139	`Here you have the following options:`
140		140
141	`make`	141	`make`
142		142
143	`or`	143	`or`
144		144
145	`make app`	145	`make app`
146		146
147	`will recompile the source files in the current directory and build the`	147	`will recompile the source files in the current directory and build the`
148	`programs. This is the default target. When compiled, the application is`	148	`programs. This is the default target. When compiled, the application is`
149	`moved to wherever/GEL/bin`	149	`moved to wherever/GEL/bin`
150		150
151	`make force`	151	`make force`
152		152
153	`does the same but tries first to recompile all libraries that the`	153	`does the same but tries first to recompile all libraries that the`
154	`applications in somedir depend on. This is the safe way to recompile,`	154	`applications in somedir depend on. This is the safe way to recompile,`
155	`but it takes a few seconds more, so if you are sure the libraries are`	155	`but it takes a few seconds more, so if you are sure the libraries are`
156	`up to date, just go make.`	156	`up to date, just go make.`
157		157
158	`make clean`	158	`make clean`
159		159
160	`works like above.`	160	`works like above.`
161		161
162	`Makefiles in subdirectories under apps should generally be edited.`	162	`Makefiles in subdirectories under apps should generally be edited.`
163	When create by `make makefiles' the Makefile in apps/somedir looks	163	When create by `make makefiles' the Makefile in apps/somedir looks
164	`like this`	164	`like this`
165		165
166	`PROGRAMS = prog1 prog2`	166	`PROGRAMS = prog1 prog2`
167	`OWN_LIBS = Lib1 Lib2`	167	`OWN_LIBS = Lib1 Lib2`
168	`LIBS = ${GLLIBS} ${XLIBS} -lm -lz -lexpat`	168	`LIBS = ${GLLIBS} ${XLIBS} -lm -lz -lexpat`
169		169
170	`Add something like this`	170	`Add something like this`
171		171
172	`PROGRAMS = prog1 prog2`	172	`PROGRAMS = prog1 prog2`
173	`OWN_LIBS = Lib1 Lib2`	173	`OWN_LIBS = Lib1 Lib2`
174	`LIBS = ${GLLIBS} ${XLIBS} -lm -lz -lexpat`	174	`LIBS = ${GLLIBS} ${XLIBS} -lm -lz -lexpat`
175		175
176	`where prog1 and prog2 are programs you wish to create. These must`	176	`where prog1 and prog2 are programs you wish to create. These must`
177	`correspond to source files with the same name and suffix .cpp. In`	177	`correspond to source files with the same name and suffix .cpp. In`
178	`other words,`	178	`other words,`
179		179
180	`prog1.cpp`	180	`prog1.cpp`
181	`prog2.cpp`	181	`prog2.cpp`
182		182
183	`must exist (and contain a main function)`	183	`must exist (and contain a main function)`
184		184
185	`Lib1 and Lib2 are libraries that must also be in the directory structure,`	185	`Lib1 and Lib2 are libraries that must also be in the directory structure,`
186	`i.e. under src there are subdirectories`	186	`i.e. under src there are subdirectories`
187		187
188	`src/Lib1`	188	`src/Lib1`
189	`src/Lib2`	189	`src/Lib2`
190		190
191	`the files in these subdirectories will be compiled and put in library`	191	`the files in these subdirectories will be compiled and put in library`
192	`files named libLib1.a under lib. More precisely it will be put here:`	192	`files named libLib1.a under lib. More precisely it will be put here:`
193		193
194	`lib/PLATFORM_TARGET/`	194	`lib/PLATFORM_TARGET/`
195		195
196	`PLATFORM and TARGET are defined above. Another library directory are for`	196	`PLATFORM and TARGET are defined above. Another library directory are for`
197	`precompiled libraries whose source code is not a part of this tree. Put`	197	`precompiled libraries whose source code is not a part of this tree. Put`
198	`such libraries here:`	198	`such libraries here:`
199		199
200	`lib/PLATFORM/`	200	`lib/PLATFORM/`
201		201
202	`this directory is created by`	202	`this directory is created by`
203		203
204	`make platform from the source root.`	204	`make platform from the source root.`
205		205
206	`----------------------------------------------------------------------`	206	`----------------------------------------------------------------------`
207	`5. CONFIGURATION`	207	`5. CONFIGURATION`
208	`----------------------------------------------------------------------`	208	`----------------------------------------------------------------------`
209		209
210	`When you add a new project to this framework, you should go through`	210	`When you add a new project to this framework, you should go through`
211	`the following steps:`	211	`the following steps:`
212		212
213	`Add directories for libraries under src. E.g. add`	213	`Add directories for libraries under src. E.g. add`
214		214
215	`mkdir src/somelib`	215	`mkdir src/somelib`
216		216
217	`Then add directories for applications:`	217	`Then add directories for applications:`
218		218
219	`mkdir apps/someapp`	219	`mkdir apps/someapp`
220		220
221	`Copy appropriate source files to these directories and then edit`	221	`Copy appropriate source files to these directories and then edit`
222		222
223	`makefiles/config.mk`	223	`makefiles/config.mk`
224		224
225	`to tell us which compiler to use (leave blank to use default)`	225	`to tell us which compiler to use (leave blank to use default)`
226		226
227	`Finally, from the source root type`	227	`Finally, from the source root type`
228		228
229	`make platform`	229	`make platform`
230		230
231	`Depending on your compiler you may now have to edit the makefile called`	231	`Depending on your compiler you may now have to edit the makefile called`
232		232
233	`makefiles/PLATFORM.mk`	233	`makefiles/PLATFORM.mk`
234		234
235	`to set special compile flags. No go`	235	`to set special compile flags. No go`
236		236
237	`make makefiles`	237	`make makefiles`
238		238
239	`Finally you are all set. Go`	239	`Finally you are all set. Go`
240		240
241	`make`	241	`make`
242		242
243		243
244	`----------------------------------------------------------------------`	244	`----------------------------------------------------------------------`
245	`6. DEPENDENCIES IN GEL`	245	`6. DEPENDENCIES IN GEL`
246	`----------------------------------------------------------------------`	246	`----------------------------------------------------------------------`
247		247
248	`Each directory under src represents a library. There are some dependencies`	248	`Each directory under src represents a library. There are some dependencies`
249	`between these libraries.`	249	`between these libraries.`
250		250
251		251
252		252
253	`lib depends on`	253	`lib depends on`
254	`-----------------------------------`	254	`-----------------------------------`
255	`CGLA nothing`	255	`CGLA nothing`
256		256
257	`Util CGLA`	257	`Util CGLA`
258		258
259	`LinAlg CGLA`	259	`LinAlg CGLA`
260		260
261	`Geometry LinAlg, CGLA`	261	`Geometry LinAlg, CGLA`
262		262
263	`HMesh CGLA, Util, Geometry, LinAlg (indirectly)`	263	`HMesh CGLA, Util, Geometry, LinAlg (indirectly)`
264		264
265	`GLGraphics Everything (since it contains general rendering`	265	`GLGraphics Everything (since it contains general rendering`
266	`facilities)`	266	`facilities)`
267		267
268		268
269	`----------------------------------------------------------------------`	269	`----------------------------------------------------------------------`
270	`7. TODO`	270	`7. TODO`
271	`----------------------------------------------------------------------`	271	`----------------------------------------------------------------------`
272		272
273	`- No real testing of blended C and C++.`	273	`- No real testing of blended C and C++.`
274	`- No dependency computation for .c`	274	`- No dependency computation for .c`
275		275
276		276
277		277
278		278
279		279
280		280
281		281