Q1.0 What is STLport?

A1.0 STLport is implementation of C++ Standard Library, as described in the INTERNATIONAL STANDARD ISO/IEC 14882:1998(E) and latest ISO/IEC 14882:2003(E).

Q1.1 What is benefits from using STLport?

A1.1

• For multiplatform/multicompilers project a coherent Standard library implementation.
• An easy to use STL safe mode detecting bad use of containers and iterators.
• Some original optimizations: template expression for string concatenation, short string optimization, move semantic for STL containers combination like vector of vector, an efficient std::allocator.

Q1.2 What versions of STLport available?

A1.2 Special notes about STLport 4.6.x: this is result of bad intercommunication between developers few years ago; it has a lot of bugs and problems, codebase of any 4.6.x absent in version control system; really it should never appear. The huge problem with this version is that it mentioned as LAST release on DIED site www.stlport.org (the same as www.stlport.com). Tarballs of STLport 4.6.x pesent at SF downloads only for reference. Code from STLport 4.6.x NOT MAINTAINED AND NOT SUPPORTED. Even compare with STLport 4.6.x undesirable: we don't want to see into this code at all.

STLport major releases before 5.x are archived and closed. You can still download this releases as tarballs from SF. Version control system cover STLport sources since 1999, so only 4.x and newer are present under SCM. See STLport story here.

If you need STL implementation for old operational environment and/or old compiler, and you has troubles with 5.x releases of STLport because of removed ancient workarounds, you can try to use release 4.5.3. Release 4.5.3 not conform to C++ standard, but, from other side, it very tolerant to compilers with poor C++ implementation. It is the last stable, clean and best release among STLport 4.x family.

• STLport 5.0.x. First release based on clean sources under version control. It derived from 4.5.x. Branch 5.0.x is 'closed'. Nevertheless, bugfixes possible here, but only if you suggest patches. Notes about changes against 4.x you can find at News page.
• STLport 5.1.x. Previous stable branch. No new features planned here, only bugfixes. Release notes available at News page.
• STLport 5.2.x. Last stable branch. This is a STLport-5.2 branch. This is the best candidate if you consider contribution like new platform support.
• STLport 5.3 or even 6.0. Current development. This is a master branch. Performance, coming standard C++ 0x, etc. is here. The real development has switched to Git SCM. See STLport's SCM page.

Q1.3 Where is the user guide?

A1.3 There is no real user guide for the moment. You can find some information in README files in doc folder. As STLport is a C++ Standard library implementation you might find information you need at the following locations:

• The ISO/IEC 14882:2003 document you can buy for a very cheap price.
• For STL containers you can use SGI documentation. Beware however, STL described in this document is not identical to the Standardized version described in ISO/IEC. This documentation can be very useful for STLport extensions like hash containers (hash_map, hash_set...)
• You can also use the documentation coming with your compiler as most of the information will also apply to STLport. Take care to description reported as 'implementation specific'.

Q1.4 What is the version policy?

A1.4 STLport version information contains three numbers like '5.1.0'. '5' is the major version number, '1' is the minor and '0' is the patch level. Policy for this numbers are:

• changes in major version number: radical modification, new era.
• changes in minor version number: significant changes, new features, changes in interface part; switching to an STLport library with a different minor version require recompilation of all modules depending on it.
• changes in patch level: bugfixes; we keep in mind binary compatibility, but really can't strongly guarantee it; switching to an STLport library with different patch level do not require rebuild of modules---rebuilding and installing the STLport libraries should work; however, as STLport contains a lot of template code, you should pay attention to fact that all you modules was build with SAME STLport headers---otherwise problems possible; recompilation of one part with only rebuilding STLport might not be enough to get all the fixes in your application so even in this case rebuilding your modules is advised.

Q2.0 Do I need a C++ compiler?

A2.0 STLport is a C++ library. So answer is 'yes, you need'.

Q2.1 Do I need runtime libraries from C++ compiler?

A2.1 In any case C++ language support from compiler is required for STLport (operators new, delete, RTTI, exceptions support). That's why in most cases you need some runtime libraries from C++ compiler.

Q2.2 Can I use containers and algorithms from STLport and iostreams from library that shipout with compiler?

A2.2 This is a case of STL implementations mix. See A2.3 below.

Q2.3 Can I mix STL implementations in my project?

A2.3 The short answer is 'No'.

Indeed co-existence of two implementations possible, but this required a lot of knowledge as about both implementations, as about compiler and linkage. This issues should be taken into account both within STL library and during library usage. In common you can't use both implementation in the same namespace. So you should separate STL implementations into different namespaces. But due to absent of compilers that has full-featured support of Argument Dependent Lookup (ADL) (aka Koenig Lookup), you have no possibilty to select one or another implementation.

In wrapper mode, all std references are replaced, thanks a simple macro, by the stlp_std namespace. Everything from the native compiler std namespace is injected to the stlp_std namespace with many using std::* directives.

The problem arise when you specialized a standard class for one of your user types. You do it within the std namespace that, in wrapper mode becomes the stlp_std namespace. Then this specialization is just invisible from the native std namespace and won't be used.

Things are somewhat worse: the problem arises even without any explicit specializations. It is not a bug, but the fact that old compilers just did not tried to find functions in the namespaces where arguments' classes are defined (indeed no compilers with full-featured support of ADL yet).

Let's reduce all the complexity of STLport to some very simple example:

namespace std {

class string
{
  public:
    class iterator { };

    iterator begin();
    iterator end();
};

template <class I, class T>
void find(I begin, I end, T value);

} // namespace std

namespace stlport {

using std::string;

template <class I, class T>
void find(I begin, I end, T value);

void gee()
{
  string s;
  find(s.begin(), s.end(), 10);
}

} // namespace stlport
    

When a compiler supporting ADL finds the call to `find' within gee() function it should examine both namespace `stlport' and namespace `std' for the presence of `find'. It is caused by the fact that s.begin() returns object of type `std::string::iterator' which obviously defined in namespace `std' and the heart of ADL is finding functions not only within namespaces where the call is being made but also in the namespaces where the classes of arguments are defined...

So, in our example compiler ends with two templates satisfying the call `find(s.begin(), s.end(), 10)': `std::find' and `stlport::find'. Since compiler can not choose any one of them it reports ambiguity.

There is another aspect of mix implementations. Let's consider following code:

a.h:

#include <string>

class A {
  public:
    A() {}

    void push( const string s );

    string _str;
};
    

a.cpp:

#include "a.h"

void A::push( const string s )
{
  _str = s;
}
    

b.cpp:

#include "a.h"

string s;
A a;

void gee()
{
   a.push( s );
}
    

Now build library from a.cpp with string implementation Impl1; then build application with b.cpp that use string implementation Impl2, and link with mentioned above library. Compiler will pass. Linker may pass too. But your application will crash (or randomly crash) either on call a.push, or on assignment _str = s. This is evident here, but not evident in real applications.

The conclusion is: "Using Wrapper mode is very hard and we remove support for it".

Q2.4 When I switch to STLport in my application, I get errors. Is STLport so bad?

A2.4 Before you post such message, please, check the STLport WHITHOUT YOUR errors:

• build STLport library
• build STLport unit tests
• run STLport unit tests

If any of above steps fail, please, check you carefully follow build instructions report (in most cases you definitely should reread instructions and check that you correctly unpack archive in case you see 'file not found' message). Build instructions you can found in files INSTALL, doc/README.*, build/README*, build/test/unit/README*. If you sure, submit bug report here: https://sourceforge.net/projects/stlport Don't forget to describe you operational environment, compiler version and STLport version.

Q3.0 On my XXXX Linux n.n g++ headers are in /usr/include/g++, but they are looked for in /usr/include/3.3.1. Is it a STLport bug?

A3.0 Path to native compiler headers for gcc correspond to default path after build/install compiler (i.e. pathes from compiler origo). Package maintainers can use any path by own taste---we can't satisfy variety of distributions/packages.

So you can:

• fix path in stlport administration config file stlport/stl/_site_config.h, see _STLP_NATIVE_INCLUDE_PATH macro and related.
• make request to package maintainer
• build and install compiler

Q3.1 Do I need to build library to use STLport?

A3.1 You may omit usage (and, thus building) STLport library, but in this case you can't use iostreams, locale, complex.

Q3.2 During library compilation with MS VC++ 6.0 I see following error report:

C:\Program Files\Microsoft SDK\Include\.\winbase.h(1123) :
 error C2733: second C linkage of overloaded function
 'InterlockedIncrement' not allowed
C:\Program Files\Microsoft SDK\Include\.\winbase.h(1121) :
 see declaration of 'InterlockedIncrement'
C:\Program Files\Microsoft SDK\Include\.\winbase.h(1130) :
 error C2733: second C linkage of overloaded function
 'InterlockedDecrement' not allowed
C:\Program Files\Microsoft SDK\Include\.\winbase.h(1128) :
 see declaration of 'InterlockedDecrement'
C:\Program Files\Microsoft SDK\Include\.\winbase.h(1138) :
 error C2733: second C linkage of overloaded function
 'InterlockedExchange' not allowed
C:\Program Files\Microsoft SDK\Include\.\winbase.h(1135) :
 see declaration of 'InterlockedExchange'
        

A3.2 You have a Platform SDK installed. Uncomment line

#define _STLP_NEW_PLATFORM_SDK 1
    

in the file stlport/stl_user_config.h. There is no way to detect SDK presence during preprocessor stage.

Q3.3 Does anybody success in building STLport on OS S with compiler K n.n?

A3.3 See report about results of regression tests here: build/test/unit/STATUS.

Q3.4 Does STLport support cross-compilation?

A3.4 In case of gcc, use something like following sequence:

(cd build/lib; ./configure --target=${CROSSTARGET}; \
  export PATH=${BASECROSS}/bin:${PATH}; \
  make -f gcc.mak install-release-shared)
        

where CROSSTARGET is gcc's cross prefix (something like 'i586-pc-linux-gnu', if C++ cross compiler named as 'i586-pc-linux-gnu-c++'), BASECROSS is base of cross-compiler's location (i.e. ${BASECROSS}/bin in case above is a location of 'i586-pc-linux-gnu-c++').

Don't forget 'clean' for other target (including native):

(cd build/lib; ./configure --clean)
        

In case of non-gcc crosses, we need hands-made target system identification. The sample of such compiler (supported by STLport) is MetroWerks Codewarrior for Novell Netware (mwccnlm).

Q4.1 I tried "make -f gcc.mak install", but it install nothing into /usr/local/. How I can install headers into /usr/local/include and libs into /usr/local/lib?

A4.1 Installation in any system-wide place is issue of either 'package builder' or system administrator. He/she should be familiar with building package procedure and/or understand where headers and libraries should be situated. The place choice not issue of STLport.

You can just use

(cd ${STLPORT_SRC}/lib; tar cf - . ) | \
   (cd ${TARGET_LIB_DIR}; tar xf - ); \
(cd ${STLPORT_SRC}; tar cf - stlport) | \
   (cd ${TARGET_INCLUDE_DIR}; tar xf - )
        

Sometimes we will think about 'make install', but not now.

Q5.0 I found a bug, how I can report about it?

A5.0 See answer here.

Q6.0 In STLport present files like locale.h, setjmp.h, stdlib.h, etc., that do nothing except include native headers. Why this files present in STLport?

A6.0 Sometimes native C headers was using C++ one or was refering to the std namespace. That's why, if stddef whould absent in STLport, then

#include <string>
#include <stddef.h>
        

may cause problem in following code, because std redefined in the end of <string> header, and std may be used in stddef.h:

__BEGIN_NAMESPACE_STD
....
__END_NAMESPACE_STD
        

where __BEGIN_NAMESPACE_STD is defined as 'namespace std {'. To avoid this, STLport has stddef.h header and provide correct masquerade for std.

Q6.1 Is STLport a replacement for headers and libraries that shipout with compiler?

A6.1 In general no. In any case C++ language support from compiler is required for STLport (operators new, delete, RTTI, exceptions support). STLport also use 'native' headers and libraries to take interface to system functions and variables.

Q6.2 My tool detect memory leaks in application with STLport. Is this leak from STLport?

A6.2 In most cases this are 'pseudo memory leaks' that some tools wrongly supports.

In the default compile of STLport, the node allocator is used to allocate internal memory. The node allocator works by pre-allocating a large chunk of memory and handing out small memory blocks out. The memory chunk is not freed during running an application that uses STLport (i.e. it don't returned to system, There are tools like BoundsChecker, Purify or Valgrind that check for memorytml leaks, for memory that isn't freed when no longer used. These tools may report false memory leaks when one uses STLport's node allocator. The memory chunk is normally freed at application end, but the memory checkers usually report memory leaks before that point. Another memory problem might be reported when you use shared libraries (e.g. DLL, this problem specific for Windows DLL model) that uses STLport internally and are statically link to it. If memory is allocated in a dll and released in an other then the STLport node allocator will keep the released memory for a future use. If you do not use this memory then your application global memory consumtion will grow until the appli crash even if there is no realy memory leak. This is why you should always use a coherent configuration everything in dll or everything in static lib.

There are ways to remove the pseudo memory leaks (since the memory is properly freed at the end of the program, the leaks are just pseudo-ones). You could use another allocator that is used in STLport. Open the file "stlport/stl/_site_config.h" and uncomment either one of the following:

_STLP_USE_NEWALLOC   enables a simple allocator that uses "new/delete"
_STLP_USE_MALLOC     enables a simple allocator that uses "malloc/free"
        

The new/delete allocator has the advantage of giving an entry point to track memory starvation, see set_new_handler in your compiler doc or the C++ Standard for more information.

Alternatively you can define the following symbol, just uncomment it in "stlport/stl/_site_config.h".

_STLP_LEAKS_PEDANTIC
        

The symbol forces freeing all memory chunks. Also see the comments around the symbol in the config file.

Note that you have to recompile STLport AND your application and all of your dependent libraries if you make any change to the file!

There are also some defines that help in debugging memory problems in STLport. In _STLP_DEBUG mode, just also define the following symbols, either in "./stlport/stl_user_config.h" or in your project settings:

_STLP_DEBUG_ALLOC
_STLP_DEBUG_UNINITIALIZED
        

You don't need to rebuild STLport for these options, but you have to rebuild your application and all of your dependent libraries if you make any change to the file.