1**********************************************************************
2* 	INSTALL file for STLport                                         *
3*                                                                    *
4**********************************************************************
5
6STLport is a full ANSI C++ Standard library.
7
8This distribution contains STLport sources only, no binaries.
9To use STLport iostreams, locale and complex numbers, you have to build STLport
10library from sources in "build/lib" directory and link your programs with it.
11
12Starting with 5.0 the 'wrapper' mode is not supported anymore. You cannot use native
13compiler iostreams implementation with STLport STL (see doc/FAQ for explanations).
14Now you have to choose between STLport iostreams or no iostreams.
15
16==== Unpacking and installing STLport ==========
17
181) Unpack STLport archive to a directory accessible during compilation.
19   NOTE: DO NOT overwrite header files coming with the compiler, even if you made
20   a backup - this won't work! Most probably, you've already unpacked the archive before
21   reading this file though ;)
22
232) Make sure "stlport" directory of this distribution comes before compiler's one 
24   in your include paths when you compile the project.
25
26   Note: for SunPro CC 5.0 and higher, there used to be special directory "stlport/SC5"
27	 this is now obsolete, please make sure you do not use it anymore.
28
293) Make sure you do not rename this "stlport" subdirectory -
30   that may result in compilation errors.
31
32   NOTE:  Your compiler should be recognized by STLport source code with no configuring.
33          Please edit appropriate configuration header for your compiler
34          directly if you have to make compiler-specific configuration changes
35          (see stlport/stl/config). 
36
374)  Run:
38
39    configure --help
40
41    Depending on your environment, Windows command shell or Unix like shell,
42    configure.bat or configure script will be run respectively. For Windows users
43    running configure script is mandatory in order to declare the compiler you are
44    going to use.
45
465)  Go to "build/lib" subdirectory. It contains various makefiles for different
47    compilers and 'make' utilities (GNU Make and Microsoft's nmake supported).
48
49    Verify you can do command line compiles. IDE users may have to do something 
50    special, like add environment variables (for Microsoft) or install 
51    additional compiler components (for Metrowerks), before they can use their 
52    command line compilers (see doc/README.xxxx for additionnal information).
53
54    configure script should have already created a Makefile file so that you only
55    have to call 'make' or 'nmake' (for some platforms GNU make might be hidden
56    behind 'gmake').
57
58    IMPORTANT:
59
60    If you DO NOT plan to use STLport iostreams and/or locale implementation but just
61    the STL, you do not have to build the library.
62 
63    If you have decided to disable STLport iostreams and locale using _STLP_NO_IOSTREAMS
64    configuration macro in stlport/stl/config/user_config.h, you may stop reading here.
65
66
67==== Building STLport iostreams library ==========
68
69Below are step-by-step instructions to build STLport streams library. This is a general
70build process description, for a more detailed one check README files in the doc folder:
71
725)  Using appropriate make command (make or nmake), do
73
74      make clean install
75
76    to build the STLport libraries. Make files are set up to build several different
77    flavors - debug/nondebug, static/dynamic versions. But not all flavors will be build
78    by default. See build/lib/README for other make targets.
79
80    Note: 'install' target work slightly different than usual - it installs libraries into
81    <STLport root dir>/lib and bin catalogs, NOT IN SYSTEM CATALOG. You can do the system
82    install by just copying stlport and lib folder to the destination of your choise. For
83    example on UNIX-like platforms this can be done with the following commands:
84
85      su
86      tar cf - stlport | (cd /usr/local/include; tar xf -)
87      chmod -R a+r /usr/local/include/stlport
88      chown -R root:root /usr/local/include/stlport
89      (cd lib; tar cf - --exclude=CVS --exclude=.cvsignore .) | (cd /usr/local/lib; tar xf -)
90      chown -R root:root /usr/local/lib/libstlport*
91      exit
92
93    Note: System install is optional, most of compilers/linkers support searching for includes
94    and libs throught out the whole filesystem, just check your documentation on how to achieve
95    this.
96
97    If you use cross-compiler, you can find libraries in the <STLport root dir>/lib/<target platform>
98    catalog.
99
1006)  If build fails, you may choose to :
101     - try fixing the build ;)
102     - wait until somebody else will submit corresponding changes to be incorporated in next STLport 
103       release/snapshot.
104
105    In case you do patch STLport, please submit your patches to
106    https://sourceforge.net/tracker/?atid=766246&group_id=146814&func=browse
107
108==== Linking your application with STLport library ==========
109
1107) Check the build:
111
112    Example:
113    
114    - under Linux and other Unixes:
115
116    cd build/test/unit
117    make install
118    ../../../bin/stl_unit_test
119    ../../../bin-g/stl_unit_test
120
121    - under Windows:
122
123    cd build\test\unit
124    nmake install
125    cd ..\..\..\bin
126    stl_unit_test
127    stl_unit_testd
128    stl_unit_teststld
129
1308) Supply the "lib" subdirectory to the library search path and add desired 
131   library to the list of libraries to link with.
132   Examples (imagine you have mytest.cpp in the same directory as this file is):
133	With GCC     : g++ -pthread -I./stlport mytest.cpp -L./lib/ -lstlport
134	With DEC CC  : cxx -I./stlport mytest.cpp -L./lib/ -lstlport
135	With SUN CC  : CC -mt -I./stlport mytest.cpp -L./lib/ -lstlport
136	.....
137   For several compilers supporting auto linking feature (VC++, Borland, DMC),
138   you do not have to specify "stlport.M.m.lib" explicitly, as it is being choosen
139   and forced to link automatically by "#pragma"'s in compiler config files 
140   Appropriate version is being selected based on compiler options and _STLP_DEBUG
141   setting. All you have to do is to set library search path for the linker.
142
143	Example :
144           cl.exe /I.\stlport mytest.cpp /link /libpath:.\lib /MD
145
1469) If you linked your application with shared STLport library (.so or .dll), please 
147   make suze that your .so or .dll can be found by the dynamic linker. 
148   Under Windows, the paths searched depend on the particular flavor, see the MSDN 
149   documentation for LoadLibrary at http://msdn.microsoft.com. The easiest ways are to
150   either modify the PATH environment variable or copy all .dll's next to the 
151   executable like it is done per default when unit tests executable are put next
152   to dlls. 
153   Under Linux, the environment variable LD_LIBRARY_PATH can be adjusted to point
154   to the dir containing .so. See the manpage for ld.so for more info.
155
15610) STLport builds only multithreaded libraries, so your application should be compiled
157   as multithreaded, too. Use -pthread (or -pthreads on Solaris) option for GCC, -mt for SunPro,
158   /MT for VC, and so on. Sometimes you should define _REENTRANT or something else, depends
159   upon platform/compiler. See compiler's and linker's options on command line when you build
160   unit tests (build/test/unit) for reference. The last is useful for ANY platform.
161
16211) Don't hesitate to read READMEs (doc/README*, build/lib/README*, build/test/unit/README*)
163   and doc/FAQ.
164
16512) Have fun!
166
167