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?

Q1.3 Where is the documentation or user guide?

Q1.4 What is the version policy?

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?

Q6.3 When running unit tests, I have errors in LocaleTest test fixture, how bad

is it?

Q6.4 set or multiset iterators are immutable like const_iterators, why ?

                           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

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

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 (http://www.sgi.com/tech/stl/).

    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 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 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.3 Can I mix STL implementations in my project?

A2.3 Yes you can but each implementations will rely in its own namespace

with no direct interaction between them. You will first need to correctly

configure STLport thanks to 2 macros in user_config.h file.

- _STLP_DONT_REDEFINE_STD tells STLport not to define the std macro that is

used to replace std reference in your code with STLport namespace.

- _STLP_WHOLE_NATIVE_STD tells STLport to always include native header each

time a Standard header is included in your code.

Here is a small code sample that do not require any modification in STLport

install:

#define _STLP_DONT_REDEFINE_STD

#define _STLP_WHOLE_NATIVE_STD

#include <string>

void foo()

{

   std::string std_str("std");

   stlport::string stlport_str("stlport");

   stlport_str.append(std_str.begin(), std_str.end());

   // Following is wrong because there is no assignment

   // operator for stlport::string on std::string.

   //std_str = stlport_str;

}

Note: You can use 'std' iterators from native implementation in STLport

template methods like in the 'stlport_str.append' method call above because

STLport is adding the necessary code to interpret native iterators like

STLport iterators. You won't be able however to do the opposite as native

implementation do not know anything about STLport iterators.

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

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 your 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

Note: Starting with version 5.2, STLport uses the include_next preprocessing

command to access native headers so you shouldn't experiment this problem

anymore when this feature is supported by your compiler preprocessor.

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

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:

  (./configure --target=${CROSSTARGET}; cd build/lib; \

     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 are using C++ ones or are refering

to the std namespace. That's why, if stddef was 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 consumption 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.

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

Q6.3 When running unit tests, I have errors in LocaleTest test fixture, how bad

is it?

A6.3 Failures in LocaleTest tests do not mean that your platform/compiler is not

fully supported by STLport. Platform independant localization tests are very hard

to write as Standard localization API has not been design to make unit test easy.

In STLport unit tests suite we have hard coded some expected values. Those values

depends on your OS configuration explaining why sometimes the tests are failing.

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

Q6.4 set or multiset iterators are immutable like const_iterators, why ?

A6.4 With set or multiset associative containers or even newly introduced

tr1::unordered_set and tr1::unordered_multiset key is confuse with data. It

means that modifying the data is also modifying the key. Modifying the key

might corrupt the container internal data structure so STLport prefer to

make this problem obvious and only return a const access to the key with

immutable iterators. Your solutions are:

- prefer map/multimap and split the key and the data

- use const_cast when you want to change a set/multiset element.