1 ********************************************************************** 2 * INSTALL file for STLport * 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/stl/config). 36 37 4) 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 46 5) 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 69 Below are step-by-step instructions to build STLport streams library. This is a general 70 build process description, for a more detailed one check README files in the doc folder: 71 72 5) 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 100 6) 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 110 7) 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 130 8) 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 146 9) 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 156 10) 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 162 11) Don't hesitate to read READMEs (doc/README*, build/lib/README*, build/test/unit/README*) 163 and doc/FAQ. 164 165 12) Have fun! 166 167
