sl@0: ********************************************************************** sl@0: * INSTALL file for STLport 5.0 * sl@0: * * sl@0: ********************************************************************** sl@0: sl@0: STLport is a full ANSI C++ Standard library. sl@0: sl@0: This distribution contains STLport sources only, no binaries. sl@0: To use STLport iostreams, locale and complex numbers, you have to build STLport sl@0: library from sources in "build/lib" directory and link your programs with it. sl@0: sl@0: Starting with 5.0 the 'wrapper' mode is not supported anymore. You cannot use native sl@0: compiler iostreams implementation with STLport STL (see doc/FAQ for explanations). sl@0: Now you have to choose between STLport iostreams or no iostreams. sl@0: sl@0: ==== Unpacking and installing STLport ========== sl@0: sl@0: 1) Unpack STLport archive to a directory accessible during compilation. sl@0: NOTE: DO NOT overwrite header files coming with the compiler, even if you made sl@0: a backup - this won't work! Most probably, you've already unpacked the archive before sl@0: reading this file though ;) sl@0: sl@0: 2) Make sure "stlport" directory of this distribution comes before compiler's one sl@0: in your include paths when you compile the project. sl@0: sl@0: Note: for SunPro CC 5.0 and higher, there used to be special directory "stlport/SC5" sl@0: this is now obsolete, please make sure you do not use it anymore. sl@0: sl@0: 3) Make sure you do not rename this "stlport" subdirectory - sl@0: that may result in compilation errors. sl@0: sl@0: NOTE: Your compiler should be recognized by STLport source code with no configuring. sl@0: Please edit appropriate configuration header for your compiler sl@0: directly if you have to make compiler-specific configuration changes sl@0: (see stlport/config). sl@0: sl@0: sl@0: 4) Go to "build/lib" subdirectory. It contains various makefiles for different sl@0: compilers and 'make' utilities (GNU Make and Microsoft's nmake supported). sl@0: If you are not able to find makefile for your particular sl@0: compiler, please use one that looks most similar to your make engine to sl@0: create your own. sl@0: sl@0: Verify you can do command line compiles. IDE users may have to do something sl@0: special, like add environment variables (for Microsoft) or install sl@0: additional compiler components (for Metrowerks), before they can use their sl@0: command line compilers (see doc/README.xxxx for additionnal inrformation). sl@0: sl@0: IMPORTANT: sl@0: sl@0: If you DO NOT plan to use STLport iostreams and/or locale implementation but just sl@0: the STL, you do not have to build the library. sl@0: sl@0: If you have decided to disable STLport iostreams and locale using _STLP_NO_IOSTREAMS sl@0: configuration macro in stlport/stl/config/user_config.h, you may stop reading here. sl@0: sl@0: sl@0: ==== Building STLport iostreams library ========== sl@0: sl@0: Below are step-by-step instructions to build STLport streams library. This is a general sl@0: build process description, for a more detailed one check README files in the doc folder: sl@0: sl@0: 5) Using appropriate makefile, do sl@0: sl@0: make -f <compiler name>.mak clean sl@0: make -f <compiler name>.mak install sl@0: sl@0: to build the STLport libraries. Makefiles are set up to build several different sl@0: flavors - debug/nondebug, static/dynamic versions. But not all flavors will be build sl@0: by default. See build/lib/README and build/lib/README.options for other make tagets. sl@0: sl@0: Note: your "make" program may have different name, like "nmake" for Visual C++. sl@0: sl@0: Examples : sl@0: 1. If you are building STLport for just one compiler, you may do something like that sl@0: (DOS syntax for Visual C++ below): sl@0: nmake /fnmake-vc6.mak clean sl@0: nmake /fnmake-vc6.mak install sl@0: sl@0: 2. If you plan to build STLport with multiple compilers, use "make -f" : sl@0: make -f gcc.mak clean install sl@0: make -f sunpro.mak clean install sl@0: sl@0: sl@0: Note: 'install' target work slightly different than usual - it installs libraries into sl@0: <STLport root dir>/lib and bin catalog, NOT IN SYSTEM CATALOG. You can do the system sl@0: install by just copying stlport and lib folder to the destination of your choise. For sl@0: example on UNIX-like platforms this can be done with the following commands: sl@0: sl@0: su sl@0: tar cf - stlport | (cd /usr/local/include; tar xf -) sl@0: chmod -R a+r /usr/local/include/stlport sl@0: chown -R root:root /usr/local/include/stlport sl@0: (cd lib; tar cf - --exclude=CVS --exclude=.cvsignore .) | (cd /usr/local/lib; tar xf -) sl@0: chown -R root:root /usr/local/lib/libstlport* sl@0: exit sl@0: sl@0: Note: System install is optional, most of compilers/linkers support searching for includes sl@0: and libs throught out the whole filesystem, just check your documentation on how to achieve sl@0: this. sl@0: sl@0: If you use cross-compiler, you can find libraries in the <STLport root dir>/lib/<target platform> sl@0: catalog. sl@0: sl@0: 6) If build fails, you may choose to : sl@0: - try fixing the build ;) sl@0: - wait until somebody else will submit corresponding changes to be incorporated in next STLport sl@0: release/snapshot. sl@0: sl@0: In case you do patch STLport, please submit your patches to sl@0: https://sourceforge.net/tracker/?atid=766246&group_id=146814&func=browse sl@0: sl@0: ==== Linking your application with STLport library ========== sl@0: sl@0: 7) Check the build: sl@0: sl@0: Example: sl@0: sl@0: - under Linux and other Unixes: sl@0: sl@0: cd build/test/unit sl@0: make -f <compiler name>.mak install sl@0: ../../../bin/stl_unit_test sl@0: ../../../bin-g/stl_unit_test sl@0: sl@0: - under Windows: sl@0: sl@0: cd build\test\unit sl@0: nmake /fnmake-<compiler name>.mak install sl@0: cd ..\..\..\bin sl@0: stl_unit_test_r50 sl@0: stl_unit_test_d50 sl@0: stl_unit_test_stld50 sl@0: sl@0: 8) Supply the "lib" subdirectory to the library search path and add desired sl@0: library to the list of libraries to link with. sl@0: Examples (imagine you have mytest.cpp in the same directory as this file is): sl@0: With GCC : g++ -pthread -I./stlport mytest.cpp -L./lib/ -lstlport sl@0: With DEC CC : cxx -I./stlport mytest.cpp -L./lib/ -lstlport sl@0: With SUN CC : CC -mt -I./stlport mytest.cpp -L./lib/ -lstlport sl@0: ..... sl@0: [ Visual C++ specific ] For (embedded) VC++, you do not have to specify sl@0: "stlport_XXX.lib" explicitly, as it is being choosen and forced to link sl@0: automatically by "#pragma"'s in compiler config file in sl@0: stlport/config/stl_msvc.h. Appropriate version is being selected based on sl@0: /MD[d] vs /MT[d] options and _STLP_DEBUG setting. All you have to do is sl@0: to set library search path for the linker. sl@0: Example : sl@0: cl.exe /I.\stlport mytest.cpp /link /libpath:.\lib /MD sl@0: sl@0: 9) If you linked your application with shared STLport library (.so or .dll), please sl@0: make your .so or .dll can be found by the dynamic linker. sl@0: Under Windows, the paths searched depend on the particular flavor, see the MSDN sl@0: documentation for LoadLibrary at http://msdn.microsoft.com. Easiest ways are to sl@0: either modify the PATH environment variable or copy all .dll's next to the sl@0: executable. sl@0: Under Linux, the environment variable LD_LIBRARY_PATH can be adjusted to point sl@0: to the dir containing. See the manpage for ld.so for more info. sl@0: sl@0: 10) STLport builds only multithreaded libraries, so your application should be compiled sl@0: as multithreaded, too. Use -pthread (or -pthreads on Solaris) option for GCC, -mt for SunPro, sl@0: /MT for VC, and so on. Sometimes you should define _REENTRANT or something else, depends sl@0: upon platform/compiler. See compiler's and linker's options on command line when you build sl@0: unit tests (build/test/unit) for reference. The last is useful for ANY platform (special sl@0: attention for Windows users). sl@0: sl@0: 11) Don't hesitate to read READMEs (doc/README*, build/lib/README*, build/test/unit/README*) sl@0: and doc/FAQ. sl@0: sl@0: 12) Have fun! sl@0: