+++ /dev/null
- Content\r
-\r
-Q1 About STLport and availability\r
-\r
-Q1.0 What is STLport?\r
-Q1.1 What are the benefits from using STLport?\r
-Q1.2 What versions of STLport are available?\r
-Q1.3 Where is the documentation or user guide?\r
-Q1.4 What is the version policy?\r
-\r
-Q2 General\r
-\r
-Q2.0 Do I need a C++ compiler?\r
-Q2.1 Do I need runtime libraries from C++ compiler?\r
-Q2.2 Can I use containers and algorithms from STLport and iostreams from\r
-library that ship with my compiler?\r
-Q2.3 Can I mix STL implementations in my project?\r
-Q2.4 When I switch to STLport in my application, I get errors. Is STLport\r
-so bad?\r
-\r
-Q3 Building\r
-\r
-Q3.0 On my XXXX Linux n.n g++ headers are in /usr/include/g++, but they\r
-are looked for in /usr/include/3.3.1. Is it a STLport bug?\r
-Q3.1 Do I need to build library to use STLport?\r
-Q3.2 During library compilation with MS VC++ 6.0 I see following error report:...\r
-Q3.3 Has anybody succeeded building STLport on OS Y with compiler K n.n?\r
-Q3.4 Does STLport support cross-compilation?\r
-\r
-Q4 Installation\r
-\r
-Q4.1 I tried "make -f gcc.mak install", but it install nothing into\r
-/usr/local/. How I can install headers into /usr/local/include and\r
-libs into /usr/local/lib?\r
-\r
-Q5 Bug report\r
-\r
-Q5.0 I found a bug, how can I report about it?\r
-\r
-Q6 Design\r
-\r
-Q6.0 In STLport, files like locale.h, setjmp.h, stdlib.h, etc.,\r
-do nothing except include native headers. Why are these files present in STLport?\r
-Q6.1 Is STLport a replacement for headers and libraries that shipout\r
-with compiler?\r
-Q6.2 My tool detects memory leaks in applications with STLport. Is this leak\r
-from STLport?\r
-Q6.3 When running unit tests, I have errors in LocaleTest test fixture, how bad\r
-is it?\r
-Q6.4 set or multiset iterators are immutable like const_iterators, why ?\r
-\r
- Answers\r
-\r
-========================================================================\r
-\r
-Q1.0 What is STLport?\r
-A1.0 STLport is an implementation of the C++ Standard Library, as described \r
-in the INTERNATIONAL STANDARD ISO/IEC 14882:1998(E) and latest\r
-ISO/IEC 14882:2003(E).\r
-\r
-========================================================================\r
-\r
-Q1.1 What are the benefits from using STLport?\r
-\r
-A1.1\r
- - For multiplatform/multicompilers project a coherent Standard Library\r
-implementation.\r
- - An easy to use STL safe mode detecting bad use of containers and\r
-iterators.\r
- - Some original optimizations: template expression for string\r
-concatenation, short string optimization, move semantic for STL containers\r
-combination like vector of vector, an efficient std::allocator.\r
-\r
-========================================================================\r
-\r
-Q1.2 What versions of STLport are available?\r
-\r
-A1.2\r
-\r
-========================================================================\r
-\r
-Q1.3 Where is the user guide?\r
-\r
-A1.3 There is no real user guide for the moment. You can find some information\r
-in README files in doc folder. As STLport is a C++ Standard library\r
-implementation you might find information you need at the following\r
-locations:\r
- - The ISO/IEC 14882:2003 document you can buy for a very cheap price.\r
- - For STL containers you can use SGI documentation (http://www.sgi.com/tech/stl/).\r
- Beware however, STL described in this document is not identical to the\r
- Standardized version described in ISO/IEC. This documentation can be very\r
- useful for STLport extensions like hash containers (hash_map, hash_set...)\r
- - You can also use the documentation coming with your compiler as most\r
- of the information will also apply to STLport. Take care to description\r
- reported as 'implementation specific'.\r
-\r
-========================================================================\r
-\r
-Q1.4 What is the version policy?\r
-\r
-A1.4 STLport version information contains three numbers like '5.1.0'. '5'\r
-is the major version number, '1' is the minor and '0' is the patch level.\r
-Policy for this numbers are:\r
- - changes in major version number: radical modification, new era.\r
- - changes in minor version number: significant changes, new features,\r
- changes in interface part; switching to an STLport library with a different\r
- minor version require recompilation of all modules depending on it.\r
- - changes in patch level: bugfixes; we keep in mind binary compatibility,\r
- but really can't strongly guarantee it; switching to an STLport library\r
- with different patch level do not require rebuild of modules---rebuilding and\r
- installing the STLport libraries should work; however, as STLport contains\r
- a lot of template code, you should pay attention to fact that all you modules\r
- was build with SAME STLport headers---otherwise problems possible;\r
- recompilation of one part with only rebuilding STLport might not be enough\r
- to get all the fixes in your application so even in this case rebuilding\r
- your modules is advised.\r
-\r
-========================================================================\r
-\r
-\r
-Q2.0 Do I need a C++ compiler?\r
-\r
-A2.0 STLport is a C++ library. So the answer is 'yes, you do'.\r
-\r
-========================================================================\r
-\r
-Q2.1 Do I need runtime libraries from C++ compiler?\r
-\r
-A2.1 In any case, the C++ language support from compiler is required\r
-for STLport (operators new, delete, RTTI, exceptions support). That's why\r
-in most cases you need some runtime libraries from the C++ compiler.\r
-\r
-========================================================================\r
-\r
-Q2.2 Can I use containers and algorithms from STLport and iostreams from\r
-the library that ships with my compiler?\r
-\r
-A2.2 The short answer is 'No'.\r
-\r
-Indeed co-existence of two implementations possible, but this required\r
-a lot of knowledge as about both implementations, as about compiler and\r
-linkage. This issues should be taken into account both within STL library and\r
-during library usage. In common you can't use both implementation\r
-in the same namespace. So you should separate STL implementations into\r
-different namespaces. But due to absent of compilers that has full-featured\r
-support of Argument Dependent Lookup (ADL) (aka Koenig Lookup), you have no\r
-possibilty to select one or another implementation.\r
-\r
-ADL problem.\r
-\r
-In wrapper mode, all std references are replaced, thanks a simple macro,\r
-by the stlp_std namespace. Everything from the native compiler std namespace\r
-is injected to the stlp_std namespace with many using std::* directives.\r
-\r
-The problem arise when you specialized a standard class for one of your\r
-user types. You do it within the std namespace that, in wrapper mode\r
-becomes the stlp_std namespace. Then this specialization is just invisible\r
-from the native std namespace and won't be used.\r
-\r
-Things are somewhat worse: the problem arises even without any explicit\r
-specializations. It is not a bug, but the fact that old compilers just\r
-did not tried to find functions in the namespaces where arguments' classes\r
-are defined (indeed no compilers with full-featured support of ADL yet).\r
-\r
-Mix implementation via library.\r
-\r
-Let's reduce all the complexity of STLport to some very simple example:\r
-\r
-namespace std {\r
-\r
-class string\r
-{\r
- public:\r
- class iterator { };\r
-\r
- iterator begin();\r
- iterator end();\r
-};\r
-\r
-template<class I, class T>\r
-void find(I begin, I end, T value);\r
-\r
-} // namespace std\r
-\r
-\r
-namespace stlport {\r
-\r
-using std::string;\r
-\r
-template<class I, class T>\r
-void find(I begin, I end, T value);\r
-\r
-void gee()\r
-{\r
- string s;\r
- find(s.begin(), s.end(), 10);\r
-}\r
-\r
-} // namespace stlport\r
-\r
-\r
-When a compiler supporting ADL finds the call to `find' within gee() function\r
-it should examine both namespace `stlport' and namespace `std' for\r
-the presence of `find'. It is caused by the fact that s.begin() returns\r
-object of type `std::string::iterator' which obviously defined in namespace\r
-`std' and the heart of ADL is finding functions not only within namespaces\r
-where the call is being made but also in the namespaces where the classes\r
-of arguments are defined...\r
-\r
-So, in our example compiler ends with two templates satisfying the call\r
-`find(s.begin(), s.end(), 10)': `std::find' and `stlport::find'.\r
-Since compiler can not choose any one of them it reports ambiguity.\r
-\r
-There is another aspect of mix implementations.\r
-Let's consider following code:\r
-\r
-a.h:\r
-\r
-#include <string>\r
-\r
-class A {\r
- public:\r
- A() {}\r
-\r
- void push( const string s );\r
- \r
- string _str;\r
-};\r
-\r
-a.cpp:\r
-\r
-#include "a.h"\r
-\r
-void A::push( const string s )\r
-{\r
- _str = s;\r
-}\r
-\r
-\r
-b.cpp:\r
-\r
-#include "a.h"\r
-\r
-string s;\r
-A a;\r
-\r
-void gee()\r
-{\r
- a.push( s );\r
-}\r
-\r
-Now build library from a.cpp with string implementation Impl1;\r
-then build application with b.cpp that use string implementation Impl2,\r
-and link with mentioned above library. Compiler will pass. Linker may \r
-pass too. But your application will crash (or randomly crash) either on\r
-call a.push, or on assignment _str = s. This is evident here, but not\r
-evident in real applications.\r
-\r
-The conclusion is: "Using Wrapper mode is very hard and we removed support\r
-for it".\r
-\r
-========================================================================\r
-\r
-Q2.3 Can I mix STL implementations in my project?\r
-\r
-A2.3 Yes you can but each implementations will rely in its own namespace\r
-with no direct interaction between them. You will first need to correctly\r
-configure STLport thanks to 2 macros in user_config.h file.\r
-- _STLP_DONT_REDEFINE_STD tells STLport not to define the std macro that is\r
-used to replace std reference in your code with STLport namespace.\r
-- _STLP_WHOLE_NATIVE_STD tells STLport to always include native header each\r
-time a Standard header is included in your code.\r
-\r
-Here is a small code sample that do not require any modification in STLport\r
-install:\r
-\r
-#define _STLP_DONT_REDEFINE_STD\r
-#define _STLP_WHOLE_NATIVE_STD\r
-\r
-#include <string>\r
-\r
-void foo()\r
-{\r
- std::string std_str("std");\r
- stlport::string stlport_str("stlport");\r
- stlport_str.append(std_str.begin(), std_str.end());\r
- // Following is wrong because there is no assignment\r
- // operator for stlport::string on std::string.\r
- //std_str = stlport_str;\r
-}\r
-\r
-Note: You can use 'std' iterators from native implementation in STLport\r
-template methods like in the 'stlport_str.append' method call above because\r
-STLport is adding the necessary code to interpret native iterators like\r
-STLport iterators. You won't be able however to do the opposite as native\r
-implementation do not know anything about STLport iterators.\r
-\r
-\r
-========================================================================\r
-\r
-Q2.4 When I switch to STLport in my application, I get errors. Is STLport\r
-so bad?\r
-\r
-A2.4 Before you post such message, please, check STLport WHITHOUT YOUR code:\r
- - build STLport library\r
- - build STLport unit tests\r
- - run STLport unit tests\r
-If any of above steps fail, please, make sure that you carefully followed\r
-build instructions (in most cases you definitely should reread\r
-instructions and check that you correctly unpack archive in case you see\r
-'file not found' message). Build instructions you can found in files\r
-INSTALL, doc/README.*, build/README*, build/test/unit/README*.\r
-If you are sure, submit bug report here:\r
-https://sourceforge.net/projects/stlport\r
-Don't forget to describe your operational environment, compiler version and\r
-STLport version.\r
-\r
-========================================================================\r
-\r
-Q3.0 On my XXXX Linux n.n g++ headers are in /usr/include/g++, but they\r
-are looked for in /usr/include/3.3.1. Is it a STLport bug?\r
-\r
-A3.0 Path to native compiler headers for GCC correspond to default path\r
-after build/install compiler (i.e. paths from compiler origo).\r
-Package maintainers can use any path by own taste---we can't satisfy\r
-variety of distributions/packages.\r
-\r
-So you can:\r
- - fix path in stlport administration config file stlport/stl/config/host.h, \r
- see _STLP_NATIVE_INCLUDE_PATH macro and related.\r
- - create a link to the native compiler headers like expected by STLport\r
- - make request to package maintainer\r
- - build and install compiler\r
-\r
-Note: Starting with version 5.2, STLport uses the include_next preprocessing\r
-command to access native headers so you shouldn't experiment this problem\r
-anymore when this feature is supported by your compiler preprocessor.\r
-\r
-========================================================================\r
-\r
-Q3.1 Do I need to build a library to use STLport?\r
-\r
-A3.1 You may omit usage (and, thus building) STLport library, but in this\r
-case you can't use iostreams, locale, complex.\r
-\r
-========================================================================\r
-\r
-Q3.2 During library compilation with MS VC++ 6.0 I see following error report:\r
-\r
-C:\Program Files\Microsoft SDK\Include\.\winbase.h(1123) : error C2733: second C linkage of overloaded function 'InterlockedIncrement' not allowed\r
- C:\Program Files\Microsoft SDK\Include\.\winbase.h(1121) : see declaration of 'InterlockedIncrement'\r
-C:\Program Files\Microsoft SDK\Include\.\winbase.h(1130) : error C2733: second C linkage of overloaded function 'InterlockedDecrement' not allowed\r
- C:\Program Files\Microsoft SDK\Include\.\winbase.h(1128) : see declaration of 'InterlockedDecrement'\r
-C:\Program Files\Microsoft SDK\Include\.\winbase.h(1138) : error C2733: second C linkage of overloaded function 'InterlockedExchange' not allowed\r
- C:\Program Files\Microsoft SDK\Include\.\winbase.h(1135) : see declaration of 'InterlockedExchange'\r
-\r
-A3.2 You have a Platform SDK installed. Uncomment line\r
-#define _STLP_NEW_PLATFORM_SDK 1\r
-in the file stlport/stl/config/user_config.h. There is no way to detect SDK\r
-presence during preprocessor stage, which is why you have to make this\r
-change manually.\r
-\r
-========================================================================\r
-\r
-Q3.3 Has anybody succeeded building STLport on OS S with compiler K n.n?\r
-\r
-A3.3 See report about results of regression tests here: build/test/unit/STATUS.\r
-\r
-========================================================================\r
-\r
-Q3.4 Does STLport support cross-compilation?\r
-\r
-A3.4 In case of GCC, use something like following sequence:\r
-\r
- (./configure --target=${CROSSTARGET}; cd build/lib; \\r
- export PATH=${BASECROSS}/bin:${PATH}; make -f gcc.mak install-release-shared)\r
-\r
-where CROSSTARGET is GCC's cross prefix (something like 'i586-pc-linux-gnu',\r
-if C++ cross compiler named as 'i586-pc-linux-gnu-c++'), BASECROSS is base of\r
-cross-compiler's location (i.e. ${BASECROSS}/bin in case above is a location\r
-of 'i586-pc-linux-gnu-c++').\r
-\r
-In case of non-GCC crossecompilers, we need hands-made target system identification.\r
-The sample of such compiler (supported by STLport) is MetroWerks Codewarrior\r
-for Novell Netware (mwccnlm).\r
-\r
-========================================================================\r
-\r
-Q4.1 I tried "make -f gcc.mak install", but it installs nothing into\r
-/usr/local/. How I can install headers into /usr/local/include and\r
-libs into /usr/local/lib?\r
-\r
-A4.1 Installation in any system-wide place is issue of either 'package builder'\r
-or system administrator. He/she should be familiar with building package\r
-procedure and/or understand where headers and libraries should be situated.\r
-The place choice not issue of STLport.\r
-\r
-You can just use\r
-\r
-(cd ${STLPORT_SRC}/lib; tar cf - . ) | (cd ${TARGET_LIB_DIR}; tar xf - ); \\r
- (cd ${STLPORT_SRC}; tar cf - stlport) | (cd ${TARGET_INCLUDE_DIR}; tar xf - )\r
-\r
-Sometimes we will think about 'make install', but not now.\r
-\r
-\r
-========================================================================\r
-\r
-Q5.0 I found a bug, how I can report about it?\r
-\r
-A5.0 \r
- 0. Ensure that this is really a bug (standard violation, incorrect\r
- behaviour with correct usage).\r
- 1. Ensure that bug is in STLport, not in your code (you can use _STLP_DEBUG\r
- for that, see stlport/stl/config/user_config.h).\r
- 2. Ensure that you correctly built STLport---build and run unit tests\r
- (build/test/unit) first with default settings, then with your settings\r
- (if you changed any).\r
- 3. Write a short test that demonstrates the bug.\r
- 4. Make sure that this test case is really new, i.e. not covered by unit \r
- tests (test/unit/*).\r
- 5. Compare your results with reported runs of unit tests (build/test/unit/STATUS).\r
- 6. Write bug description and test here\r
- \r
- https://sourceforge.net/projects/stlport\r
-\r
- DON'T FORGET TO DESCRIBE:\r
-\r
- - OPERATIONAL ENVIRONMENT\r
- - COMPILER VERSION\r
- - STLPORT VERSION\r
- - RESULT OF UNIT TESTS\r
-\r
- Keep in mind, that your bug MUST be reproduced by other people, so give\r
- enough information (but compactly, give only essential information).\r
-\r
-========================================================================\r
-\r
-Q6.0 In STLport files like locale.h, setjmp.h, stdlib.h, etc., do \r
-nothing except include native headers. Why are these files present in STLport?\r
-\r
-A6.0 Sometimes native C headers are using C++ ones or are refering\r
-to the std namespace. That's why, if stddef was absent in STLport, then\r
-\r
-#include <string>\r
-#include <stddef.h>\r
-\r
-may cause problem in following code, because std redefined in the end of\r
-<string> header, and std may be used in stddef.h:\r
-\r
-__BEGIN_NAMESPACE_STD\r
-....\r
-__END_NAMESPACE_STD\r
-\r
-where __BEGIN_NAMESPACE_STD is defined as 'namespace std {'.\r
-To avoid this, STLport has stddef.h header and provide correct masquerade\r
-for std.\r
-\r
-========================================================================\r
-\r
-Q6.1 Is STLport a replacement for headers and libraries that shipout\r
-with compiler?\r
-\r
-A6.1 In general no. In any case C++ language support from compiler is required\r
-for STLport (operators new, delete, RTTI, exceptions support). STLport also\r
-uses 'native' headers and libraries to take interface to system functions and\r
-variables.\r
-\r
-========================================================================\r
-\r
-Q6.2 My tool detects memory leaks in application with STLport. Is this leak\r
-from STLport?\r
-\r
-A6.2 In most cases these are 'pseudo memory leaks' that some tools \r
-wrongly detect.\r
-\r
-In the default compile of STLport, the node allocator is used to allocate\r
-internal memory. The node allocator works by pre-allocating a large chunk of\r
-memory and handing out small memory blocks. The memory chunk is not freed\r
-during running an application that uses STLport (i.e. it is not returned to \r
-the system, but reused inside application). \r
-See also http://www.sgi.com/tech/stl/alloc.html\r
-\r
-There are tools like BoundsChecker, Purify or Valgrind that check for memory\r
-leaks, for memory that isn't freed when no longer used. These tools may report\r
-false memory leaks when one uses STLport's node allocator. The memory chunk is\r
-normally freed at application end, but the memory checkers usually report memory\r
-leaks before that point. Another memory problem might be reported when you use\r
-shared libraries (e.g. DLL, this problem specific for Windows DLL model) that\r
-uses STLport internally and are statically link to it. If memory is allocated in\r
-a dll and released in an other then the STLport node allocator will keep the\r
-released memory for a future use. If you do not use this memory then your\r
-application global memory consumption will grow until the app crash even if there\r
-is no real memory leak. This is why you should always use a coherent configuration\r
-everything in dll or everything in static lib.\r
-\r
-There are ways to remove the pseudo memory leaks (since the memory is properly\r
-freed at the end of the program, the leaks are just pseudo-ones). You could use\r
-another allocator that is used in STLport. Open the file\r
-"./stlport/stl/config/host.h" and uncomment either one of the following:\r
-\r
-\r
- _STLP_USE_NEWALLOC enables a simple allocator that uses "new/delete"\r
- _STLP_USE_MALLOC enables a simple allocator that uses "malloc/free"\r
-\r
-The new/delete allocator has the advantage of giving an entry point to track\r
-memory starvation, see set_new_handler in your compiler doc or the C++ Standard\r
-for more information.\r
-\r
-Alternatively you can define the following symbol, just uncomment it in\r
-"./stlport/stl/config/host.h".\r
-\r
- _STLP_LEAKS_PEDANTIC\r
-\r
-The symbol forces freeing all memory chunks. Also see the comments around the\r
-symbol in the config file.\r
-\r
-Note that you have to recompile STLport AND your application and all of your\r
-dependent libraries if you make any change to the file!\r
-\r
-There are also some defines that help in debugging memory problems in STLport.\r
-In _STLP_DEBUG mode, just also define the following symbols, either in\r
-"./stlport/stl/config/user_config.h" or in your project settings:\r
-\r
- _STLP_DEBUG_ALLOC\r
- _STLP_DEBUG_UNINITIALIZED\r
-\r
-You don't need to rebuild STLport for these options, but you have to rebuild\r
-your application and all of your dependent libraries if you make any change to\r
-the file.\r
-\r
-========================================================================\r
-\r
-Q6.3 When running unit tests, I have errors in LocaleTest test fixture, how bad\r
-is it?\r
-\r
-A6.3 Failures in LocaleTest tests do not mean that your platform/compiler is not\r
-fully supported by STLport. Platform independant localization tests are very hard\r
-to write as Standard localization API has not been design to make unit test easy.\r
-In STLport unit tests suite we have hard coded some expected values. Those values\r
-depends on your OS configuration explaining why sometimes the tests are failing.\r
-\r
-========================================================================\r
-\r
-Q6.4 set or multiset iterators are immutable like const_iterators, why ?\r
-\r
-A6.4 With set or multiset associative containers or even newly introduced\r
-tr1::unordered_set and tr1::unordered_multiset key is confuse with data. It\r
-means that modifying the data is also modifying the key. Modifying the key\r
-might corrupt the container internal data structure so STLport prefer to\r
-make this problem obvious and only return a const access to the key with\r
-immutable iterators. Your solutions are:\r
-- prefer map/multimap and split the key and the data\r
-- use const_cast when you want to change a set/multiset element.\r
-\r
projects / reactos.git / blobdiff