|
1 ********************************************************************** |
|
2 * INSTALL file for STLport 5.0 * |
|
3 * * |
|
4 ********************************************************************** |
|
5 |
|
6 STLport is a full ANSI C++ Standard library. |
|
7 |
|
8 This distribution contains STLport sources only, no binaries. |
|
9 To use STLport iostreams, locale and complex numbers, you have to build STLport |
|
10 library from sources in "build/lib" directory and link your programs with it. |
|
11 |
|
12 Starting with 5.0 the 'wrapper' mode is not supported anymore. You cannot use native |
|
13 compiler iostreams implementation with STLport STL (see doc/FAQ for explanations). |
|
14 Now you have to choose between STLport iostreams or no iostreams. |
|
15 |
|
16 ==== Unpacking and installing STLport ========== |
|
17 |
|
18 1) 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 |
|
23 2) 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 |
|
29 3) 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/config). |
|
36 |
|
37 |
|
38 4) Go to "build/lib" subdirectory. It contains various makefiles for different |
|
39 compilers and 'make' utilities (GNU Make and Microsoft's nmake supported). |
|
40 If you are not able to find makefile for your particular |
|
41 compiler, please use one that looks most similar to your make engine to |
|
42 create your own. |
|
43 |
|
44 Verify you can do command line compiles. IDE users may have to do something |
|
45 special, like add environment variables (for Microsoft) or install |
|
46 additional compiler components (for Metrowerks), before they can use their |
|
47 command line compilers (see doc/README.xxxx for additionnal inrformation). |
|
48 |
|
49 IMPORTANT: |
|
50 |
|
51 If you DO NOT plan to use STLport iostreams and/or locale implementation but just |
|
52 the STL, you do not have to build the library. |
|
53 |
|
54 If you have decided to disable STLport iostreams and locale using _STLP_NO_IOSTREAMS |
|
55 configuration macro in stlport/stl/config/user_config.h, you may stop reading here. |
|
56 |
|
57 |
|
58 ==== Building STLport iostreams library ========== |
|
59 |
|
60 Below are step-by-step instructions to build STLport streams library. This is a general |
|
61 build process description, for a more detailed one check README files in the doc folder: |
|
62 |
|
63 5) Using appropriate makefile, do |
|
64 |
|
65 make -f <compiler name>.mak clean |
|
66 make -f <compiler name>.mak install |
|
67 |
|
68 to build the STLport libraries. Makefiles are set up to build several different |
|
69 flavors - debug/nondebug, static/dynamic versions. But not all flavors will be build |
|
70 by default. See build/lib/README and build/lib/README.options for other make tagets. |
|
71 |
|
72 Note: your "make" program may have different name, like "nmake" for Visual C++. |
|
73 |
|
74 Examples : |
|
75 1. If you are building STLport for just one compiler, you may do something like that |
|
76 (DOS syntax for Visual C++ below): |
|
77 nmake /fnmake-vc6.mak clean |
|
78 nmake /fnmake-vc6.mak install |
|
79 |
|
80 2. If you plan to build STLport with multiple compilers, use "make -f" : |
|
81 make -f gcc.mak clean install |
|
82 make -f sunpro.mak clean install |
|
83 |
|
84 |
|
85 Note: 'install' target work slightly different than usual - it installs libraries into |
|
86 <STLport root dir>/lib and bin catalog, NOT IN SYSTEM CATALOG. You can do the system |
|
87 install by just copying stlport and lib folder to the destination of your choise. For |
|
88 example on UNIX-like platforms this can be done with the following commands: |
|
89 |
|
90 su |
|
91 tar cf - stlport | (cd /usr/local/include; tar xf -) |
|
92 chmod -R a+r /usr/local/include/stlport |
|
93 chown -R root:root /usr/local/include/stlport |
|
94 (cd lib; tar cf - --exclude=CVS --exclude=.cvsignore .) | (cd /usr/local/lib; tar xf -) |
|
95 chown -R root:root /usr/local/lib/libstlport* |
|
96 exit |
|
97 |
|
98 Note: System install is optional, most of compilers/linkers support searching for includes |
|
99 and libs throught out the whole filesystem, just check your documentation on how to achieve |
|
100 this. |
|
101 |
|
102 If you use cross-compiler, you can find libraries in the <STLport root dir>/lib/<target platform> |
|
103 catalog. |
|
104 |
|
105 6) If build fails, you may choose to : |
|
106 - try fixing the build ;) |
|
107 - wait until somebody else will submit corresponding changes to be incorporated in next STLport |
|
108 release/snapshot. |
|
109 |
|
110 In case you do patch STLport, please submit your patches to |
|
111 https://sourceforge.net/tracker/?atid=766246&group_id=146814&func=browse |
|
112 |
|
113 ==== Linking your application with STLport library ========== |
|
114 |
|
115 7) Check the build: |
|
116 |
|
117 Example: |
|
118 |
|
119 - under Linux and other Unixes: |
|
120 |
|
121 cd build/test/unit |
|
122 make -f <compiler name>.mak install |
|
123 ../../../bin/stl_unit_test |
|
124 ../../../bin-g/stl_unit_test |
|
125 |
|
126 - under Windows: |
|
127 |
|
128 cd build\test\unit |
|
129 nmake /fnmake-<compiler name>.mak install |
|
130 cd ..\..\..\bin |
|
131 stl_unit_test_r50 |
|
132 stl_unit_test_d50 |
|
133 stl_unit_test_stld50 |
|
134 |
|
135 8) Supply the "lib" subdirectory to the library search path and add desired |
|
136 library to the list of libraries to link with. |
|
137 Examples (imagine you have mytest.cpp in the same directory as this file is): |
|
138 With GCC : g++ -pthread -I./stlport mytest.cpp -L./lib/ -lstlport |
|
139 With DEC CC : cxx -I./stlport mytest.cpp -L./lib/ -lstlport |
|
140 With SUN CC : CC -mt -I./stlport mytest.cpp -L./lib/ -lstlport |
|
141 ..... |
|
142 [ Visual C++ specific ] For (embedded) VC++, you do not have to specify |
|
143 "stlport_XXX.lib" explicitly, as it is being choosen and forced to link |
|
144 automatically by "#pragma"'s in compiler config file in |
|
145 stlport/config/stl_msvc.h. Appropriate version is being selected based on |
|
146 /MD[d] vs /MT[d] options and _STLP_DEBUG setting. All you have to do is |
|
147 to set library search path for the linker. |
|
148 Example : |
|
149 cl.exe /I.\stlport mytest.cpp /link /libpath:.\lib /MD |
|
150 |
|
151 9) If you linked your application with shared STLport library (.so or .dll), please |
|
152 make your .so or .dll can be found by the dynamic linker. |
|
153 Under Windows, the paths searched depend on the particular flavor, see the MSDN |
|
154 documentation for LoadLibrary at http://msdn.microsoft.com. Easiest ways are to |
|
155 either modify the PATH environment variable or copy all .dll's next to the |
|
156 executable. |
|
157 Under Linux, the environment variable LD_LIBRARY_PATH can be adjusted to point |
|
158 to the dir containing. See the manpage for ld.so for more info. |
|
159 |
|
160 10) STLport builds only multithreaded libraries, so your application should be compiled |
|
161 as multithreaded, too. Use -pthread (or -pthreads on Solaris) option for GCC, -mt for SunPro, |
|
162 /MT for VC, and so on. Sometimes you should define _REENTRANT or something else, depends |
|
163 upon platform/compiler. See compiler's and linker's options on command line when you build |
|
164 unit tests (build/test/unit) for reference. The last is useful for ANY platform (special |
|
165 attention for Windows users). |
|
166 |
|
167 11) Don't hesitate to read READMEs (doc/README*, build/lib/README*, build/test/unit/README*) |
|
168 and doc/FAQ. |
|
169 |
|
170 12) Have fun! |
|
171 |