Content

Q1 About STLport and availability

Q1.0 What is STLport?
Q1.1 What are the benefits from using STLport?
Q1.2 What versions of STLport are available?

Q2 General

Q2.0 Do I need a C++ compiler?
Q2.1 Do I need runtime libraries from C++ compiler?
Q2.2 Can I use containers and algorithms from STLport and iostreams from
library that ship with my compiler?
Q2.3 Can I mix STL implementations in my project?
Q2.4 When I switch to STLport in my application, I get errors. Is STLport
so bad?

Q3 Building

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?
Q3.1 Do I need to build library to use STLport?
Q3.2 During library compilation with MS VC++ 6.0 I see following error report:...
Q3.3 Has anybody succeeded building STLport on OS Y with compiler K n.n?
Q3.4 Does STLport support cross-compilation?

Q4 Installation

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?

Q5 Bug report

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

Q6 Design

Q6.0 In STLport, files like locale.h, setjmp.h, stdlib.h, etc.,
do nothing except include native headers. Why are these files present in STLport?
Q6.1 Is STLport a replacement for headers and libraries that shipout
with compiler?
Q6.2 My tool detects memory leaks in applications with STLport. Is this leak
from STLport?

                           Answers

========================================================================

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

========================================================================

Q1.1 What are the 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 are available?

A1.2

========================================================================

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

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

========================================================================

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

A2.1 In any case, the 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 the C++ compiler.

========================================================================

Q2.2 Can I use containers and algorithms from STLport and iostreams from
the library that ships with my 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.

ADL problem.

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).

Mix implementation via library.

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 removed 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 STLport WHITHOUT YOUR code:
  - build STLport library
  - build STLport unit tests
  - run STLport unit tests
If any of above steps fail, please, make sure that you carefully followed
build instructions (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 are 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. paths 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/config/host.h, 
   see _STLP_NATIVE_INCLUDE_PATH macro and related.
 - create a link to the native compiler headers like expected by STLport
 - make request to package maintainer
 - build and install compiler

========================================================================

Q3.1 Do I need to build a 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/config/user_config.h. There is no way to detect SDK
presence during preprocessor stage, which is why you have to make this
change manually.

========================================================================

Q3.3 Has anybody succeeded 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++').

In case of non-GCC crossecompilers, 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 installs 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 
  0. Ensure that this is really a bug (standard violation, incorrect
     behaviour with correct usage).
  1. Ensure that bug is in STLport, not in your code (you can use _STLP_DEBUG
     for that, see stlport/stl/config/user_config.h).
  2. Ensure that you correctly built STLport---build and run unit tests
     (build/test/unit) first with default settings, then with your settings
     (if you changed any).
  3. Write a short test that demonstrates the bug.
  4. Make sure that this test case is really new, i.e. not covered by unit 
     tests (test/unit/*).
  5. Compare your results with reported runs of unit tests (build/test/unit/STATUS).
  6. Write bug description and test here
     
     https://sourceforge.net/projects/stlport

     DON'T FORGET TO DESCRIBE:

       - OPERATIONAL ENVIRONMENT
       - COMPILER VERSION
       - STLPORT VERSION
       - RESULT OF UNIT TESTS

     Keep in mind, that your bug MUST be reproduced by other people, so give
     enough information (but compactly, give only essential information).

========================================================================

Q6.0 In STLport files like locale.h, setjmp.h, stdlib.h, etc., do 
nothing except include native headers. Why are these 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
uses 'native' headers and libraries to take interface to system functions and
variables.

========================================================================

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

A6.2 In most cases these are 'pseudo memory leaks' that some tools 
wrongly detect.

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. The memory chunk is not freed
during running an application that uses STLport (i.e. it is not returned to 
the system, but reused inside application). 
See also http://www.sgi.com/tech/stl/alloc.html

There are tools like BoundsChecker, Purify or Valgrind that check for memory
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 app crash even if there
is no real 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/config/host.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/config/host.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/config/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.