1The STLport build system
2========================
3
4This is a basic overview of the STLport build system. At the moment, I'm only familiar 
5with the working of the nmake variant, i.e. for MSVC, eVC and ICC/win32, other variants
6may differ.
7
8Overview:
9----------
10
11
12There are three basic classes to consider while building:
131. The used make tool (currently that is make (GNU make) an nmake (Microsoft)).
142. The used compiler
153. The target type, either application or library
16
17Other than that, there are three different settings corresponding to the three different 
18STLport modes, 'release', 'debug' and 'STLdebug' and each one has two modes for either
19static or dynamic linking.
20
21The whole build system lies under the build/ dir of the source tree. There, it first 
22branches to Makefiles/ (which contains the base of the build system) and to lib/ (which 
23contains files to build the STLport library) and test/ (which contains files to build
24tests) (TODO: what is the misc/ folder for?).
25
26Under Makefiles/, you see the initially mentioned branching according to the build tool.
27Here is also where the configure.bat file puts the generated config.mak file. (TODO:
28what are the other files in that folder?)
29
30nmake:
31-------
32
33Under nmake/, you then find the common support files for the different compilers and 
34files that define generic rules. Here, it then splits into app/ and lib/, which are 
35structured similar to each other and to the common nmake/ dir. In each dir you have
36files for the different compilers that are used to make application specific or library
37specific settings.
38
39The branching in the three STLport modes and the static/dynamic linking is not visible
40in the file structure but only in the used nmake variables.
41
42In order to make clear which file includes which other file, here an example when 
43compiling the STLport library for eVC4. The call issued is 'nmake /f evc4.mak' in the
44build/lib folder. From there, the following include tree is created:
45
46build/lib/evc.mak
47  build/Makefiles/config.mak ; generated by configure.bat
48  build/Makefiles/nmake/top.mak
49    build/Makefiles/config.mak
50    build/Makefiles/nmake/sysid.mak
51    build/Makefiles/nmake/sys.mak
52      build/Makefiles/nmake/evc4.mak ; evc4 from config
53        build/Makefiles/nmake/evc-common.mak
54    build/Makefiles/nmake/targetdirs.mak
55    build/Makefiles/nmake/extern.mak
56    build/Makefiles/nmake/targets.mak
57      build/Makefiles/nmake/rules-o.mak
58    build/Makefiles/nmake/clean.mak
59    build/Makefiles/nmake/lib/top.mak ; would be app/top.mak when building an application
60      build/Makefiles/nmake/lib/macro.mak
61      build/Makefiles/nmake/lib/evc4.mak ; evc4 from config
62        build/Makefiles/nmake/lib/evc-common.mak
63      build/Makefiles/nmake/lib/rules-so.mak
64      build/Makefiles/nmake/lib/rules-a.mak
65      build/Makefiles/nmake/lib/rules-install-so.mak
66      build/Makefiles/nmake/lib/rules-install-a.mak
67      build/Makefiles/nmake/lib/clean.mak
68
69TODO: build/Makefiles/config.mak is included both by build/lib/evc.mak and by 
70build/Makefiles/nmake/top.mak.
71
72Known issues:
73--------------
74
75- nmake: MSC doesn't support generating dependency information for makefiles. So, unless
76you modify the direct source file for an object file, no recompilation is triggered! You 
77need to either delete all object files that need to be recompiled or 'make clean'
78
79- There are targets to only install e.g. the shared STLdebug version but there is no 
80such thing for making clean. This would be useful in the context of above issue for 
81making a selective clean only.
82
83