* INSTALL file for STLport 4.6.0 *
STLport-4.6 is a full ANSI C++ Standard library.
This distribution contains STLport sources only, no binaries.
To use STLport iostreams, you have to build STLport library from sources in "src"
directory and link your programs with it.
This is major change since pre-4.0 releases, please read the instructions carefully.
==== Unpacking and installing STLport ==========
1) Unpack STLport archive to a directory accessible during compilation.
NOTE : DO NOT overwrite header files coming with the compiler, even if you made
a backup - this won't work ! Most probably, you've already unpacked the archive before
reading this file though ;)
2) Make sure "stlport" directory of this distribution comes before compiler's one
in your search path when you compile the project;
Note: for SunPro CC 5.0 and higher, there used to be special directory "stlport/SC5"
this is now obsolete, please make sure you do not use it anymore.
3) Make sure you do not rename this "stlport" subdirectory -
that may result in compilation errors.
NOTE : Do NOT attempt to run "configure" ! It is deprecated, moved to safe standalone folder
and should be used as a helper to create initial config for a new compiler only.
Your compiler should be recognized by STLport source code with no configuring.
Please edit appropriate configuration header for your compiler
directly if you have to make compiler-specific configuration changes.
4) Go to "src" subdirectory. It contains various makefiles for different
compilers. If you are not able to find makefile for your particular
compiler, please use one that looks most similar to your make engine to
create your own.
Verify you can do command line compiles. IDE users may have to do something
special, like add environment variables (for Microsoft) or install
additional compiler components (for Metrowerks), before they can use their
command line compilers.
If you DO NOT plan to use STLport iostreams implementation, you do not have to build the library.
Please do this instead :
4-1) Using appropriate makefile, do "make -f <your compiler name>.mak prepare".
Please do not skip this! On some platforms, it creates necessary symbolic links.
If you do build STLport iostream, this step is performed automatically when you do "make all".
4-2) uncomment _STLP_NO_OWN_IOSTREAMS setting in "stlport/stl_user_config.h" to disable use
of STLport iostreams and to use wrappers around your existing iostreams.
After disabling STLport iostreams, you will use wrappers around your compiler's iostreams
libabry, as in previous STLport releases.
No binary library for STLport needs to be built in this case.
Note though :
- new-style ANSI iostreams may not be available on your system;
- compiler's iostreams are most likely slower than STLport version.
If you have decided to disable STLport iostreams, you may stop reading here.
==== Building STLport iostreams library ==========
Below are step-by-step instructions to build STLport streams library:
5) Using appropriate makefile, do "make clean all" to build the STLport libraries
(makefiles are set up to build several different flavors - debug/nondebug,
Optionally, do "make install" to copy STLport headers and libraries to shared location.
Note : your "make" program may have different name, like "nmake" for Visual C++.
1. If you are building STLport for just one compiler, you may do something like that
(DOS syntax for Visual C++ below):
copy vc6.mak makefile
nmake clean all
2. If you plan to build STLport with multiple compilers, use "make -f" :
make -f gcc.mak clean install
make -f sunpro.mak clean install
This will build and install STLport for gcc & SUN CC.
"install" target works on most platforms.
On Win32, it does the following :
- copies STLport headers in "stlport" subdirectory of your compiler's INCLUDE directory;
- copies STLport .lib files in your compiler's LIB directory;
- copies STLport DLLs to Windows system directory so they can be found at runtime.
On UNIX, it does the following :
- copies STLport headers in "stlport" subdirectory of system's local include directory (default is /usr/local/include);
- copies STLport .a and .so files to system local library directory (default is /usr/local/lib);
6) If build fails, you may choose to :
- try fixing the build ;
- wait until somebody else will submit corresponding changes to be incorporated in next STLport
release/snapshot. To use STLport w/o its own iostreams, please do step 3a).
In case you do patch STLport, please submit your patches to firstname.lastname@example.org or (better)
to STLport Forum (http://www.stlport.com/cgi-bin/forum/dcboard.cgi)
7) Do "make install" to install resulting libraries into "./lib" subdirectory.
==== Linking your application with STLport library ==========
8) Supply the "lib" subdirectory to the library search path and add desired
library to the list of libraries to link with.
Examples (imagine you have mytest.cpp in the same directory as this file is):
With gcc : gcc -I./stlport mytest.cpp -L./lib/ -lstlport_gcc
With DEC CC : cxx -I./stlport mytest.cpp -L./lib/ -lstlport_deccxx
With SUN CC : CC -I./stlport mytest.cpp -L./lib/ -lstlport_sunpro
[ Visual C++ specific ] For VC++, you do not have to specify "stlport-msvc-XXX.lib" explicitly,
as it is being choosen and forced to link automatically by "#pragma"'s in stlport/config/stl_select_lib.h.
Appropriate version is being selected based on /MD[d] vs /MT[d] options and __STL_DEBUG setting.
All you have to do is to set library search path for the linker.
cl.exe /I.\stlport mytest.cpp /link /libpath:.\lib /MD
9) If you linked your application with shared STLport library (.so or .dll), please make your .so or
.dll's to be found in PATH at runtime. On Windows, the simplest way to do it
is to copy all .dll's to Windows system directory. Or, you might choose to add directory
containing STLport to the PATH environment string.
10) Have fun !
10/31/03, Boris Fomitchev.