1**********************************************************************
2* 	INSTALL file for STLport 5.2                                 *
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
10to build STLport library from sources and link your programs with it.
11
12Starting with 5.0 the 'wrapper' mode is not supported anymore.
13You cannot use native compiler iostreams implementation with STLport STL
14(see doc/FAQ for explanations).
15
16==== Installing STLport ==========
17
180) DO NOT overwrite/move/rename header files coming with the compiler,
19   even if you made a backup---STLport need this headers and don't
20   override ones.
21
221) Run
23
24   ./configure --help
25
26   read options description; if you use compiler
27   different from gcc, pay attention to --use-compiler-family= option.
28
292) Run
30
31   ./configure <option>
32
33   Options here more-or-less traditional.
34
35   Note: ./configure give hints only for library build, it dosen't
36   create/edit any headers, check you system etc. This is simple way
37   to store custom options, not more. If you want to change default
38   behaviour of STLport, see stlport/stl/config/user_config.h and
39   stlport/stl/config/host.h; read the comments in this files!
40   Not all combinations of options healthy, you should understand
41   what you do. If not, keep all unchanged.
42
43   Note: you can find all recognised 'settings' in the file
44   build/Makefiles/gmake/config.mak
45
46   This is generated file, but only ./configure will rewrite one.
47
483) Run
49
50   make && make check
51
52   Only GNU Make supported! Preferred verion of GNU Make >= 3.81;
53   never use GNU Make before 3.79 --- build not work properly;
54   GNU makes >= 3.79  and < 3.81 may fail to build library/tests
55   properly, due to bugs; but the real results depends upon
56   platform.
57
584) If build fine, become superuser and run
59
60   make install
61
62   Note: you can use --prefix= to change installation path
63   (or macro DESTDIR, as usual), or even skip installation and use
64   STLport in-place.
65
66==== Usage STLport ==========
67
681) The best way to understand how to use it, is to see on compilation,
69   linking, running unit tests, i.e. see on options when you do
70
71   (cd build/test/unit; make check)
72
732) Make sure "stlport" directory of this distribution comes before
74   compiler's one in your include paths (something like
75   -I<base install path>/stlport); never rename 'stlport' part of path!
76
77   Compilation:
78
79   c++ -pthread -fexceptions -O2 -I/usr/local/include/stlport -c -o test.o test.cc
80
81   In case of gcc, libstlport replace libstdc++ (not in all cases!)
82
83   Link, variant 1:
84
85   c++ -pthread -fexceptions -O2 -I/usr/local/include/stlport -nostdlib -o mytest \
86   /usr/lib/gcc/i686-pc-linux-gnu/4.2.4/../../../crt1.o \
87   /usr/lib/gcc/i686-pc-linux-gnu/4.2.4/../../../crti.o \
88   /usr/lib/gcc/i686-pc-linux-gnu/4.2.4/crtbegin.o \
89   test.o \
90   -lstlport \
91   -lgcc_s -lpthread -lc -lm \
92   /usr/lib/gcc/i686-pc-linux-gnu/4.2.4/crtend.o \
93   /usr/lib/gcc/i686-pc-linux-gnu/4.2.4/../../../crtn.o
94
95   Of cause, names of start/stop files not hardcoded, you can locate it with
96
97   c++ -print-file-name=crt1.o
98
99   Link, variant 2:
100
101   gcc -pthread -fexceptions -O2 -I/usr/local/include/stlport -o mytest \
102   test.o -lstlport
103
104   If you use gcc before 3.3, you must link with libstdc++, because
105   language-support library (libsupc++.a) don't contain necessary
106   functions.
107
1083) STLport builds only multithreaded libraries (by default), so your
109   application should be compiled as multithreaded, too. Use -pthread
110   (or -pthreads on Solaris) option for GCC, -mt for SunPro and so on.
111   Sometimes you should define _REENTRANT or something else, depends
112   upon platform/compiler. See compiler's and linker's options
113   on command line when you build unit tests (build/test/unit)
114   for reference. The last is useful for ANY platform (special
115   attention for Windows users).
116
1174) Don't hesitate to read READMEs (doc/README*, build/lib/README*,
118   build/test/unit/README*) and doc/FAQ.
119
1205) Have fun!
121