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 void find(I begin, I end, T value); } // namespace std namespace stlport { using std::string; template 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 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 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 #include may cause problem in following code, because std redefined in the end of 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.