Contents
Introduction About STLport SGI STL Base STLport Story STLport Features Portability Debug Mode Thread Safety Exception Safety Getting Started Download and Install Select Streams Mode Compiling with STLport White Papers Release Notes READMEs Interface with std:: Wrappers Config manual Regression Test Exception Test Feedback Bug Reports Forum Appendix Acknowledgements Your Free Licence
| # STLport Configuration Manual by Boris Fomitchev ### Parameters There are two major categories of STLport configuration parameters: User-definable preferences Parameters describing compiler bugs and misfeatures The former class lets you set some specific preferences. Switches controlling these preferences are located in <stl_use_config.h> header, which is self-documented. This manual provide some additional info on them. For the latter, STLport comes preconfigured for a wide variety of compilers. See list for a complete list of compilers that STLport automatically recognizes. If your compiler is not being recognized properly, this document will help you to fix the problem. ### User-defined preferences You may specify some user-defined preferences for STLport. There are two ways to set the options up : Setting corresponding #define in <stl_user_config.h> . This is the preferred method. You can also use different <stl_user_config.h> headers for different projects. Specifying corresponding flag on compiler command-line. Some options also may be suppressed. For example, you may configure the distribution to exploit exception handling with setting __STL_USE_EXCEPTIONS macro to 1, then turning exception handling off with -D__STL_NO_EXCEPTIONS command-line option for particular project Below is a stable set of of user-defined options with description. If not indicated otherwise, default for these options is that they are undefined.

#### User-defined options for STLport

Controlling Macro | Description
__SGI_STL_OWN_IOSTREAMS | This switch is used to select one from two major STLport iostream modes. Please visit "Getting Started" section for details.
__STL_NO_NEW_IOSTREAMS | Suppress using new-style iostreams even if they are available.
__STL_NO_IOSTREAMS | This switch is experimental and is intended to be used in embedded environments. It makes STLport assume that no iostreams are available at all.
__STL_NO_OWN_NAMESPACE | Suppresses STLport use of namespace stlport:: even if it is recommended, forces STLport to use std::. Normally, STLport uses _STL:: namespace instead of std::, to prevent clashes with iostreams/string stuff that comes with the compiler.
__STL_USE_OWN_NAMESPACE | Forces STLport to use _STL:: namespace instead of std:: STLport sets this flag automatically if __STL_USE_NAMESPACES is set.
__STL_DONT_RENAME_STD | Precludes STLport from redefining std:: to _STL::. Define it only if renaming scheme does not work for you for some reason.
__STLPORT_NAMESPACE | This is the namespace STLport uses in the above case. Default is _STL. Do NOT try to change it to std.
__STL_USE_SGI_STRING | Forces use of SGI string even if you share namespace std:: with native C++ library and use new <iostream>. IMPORTANT: DO NOT use SGI <string> with native <iostream> unless you recompile standard C++ runtime library with STLport installed, or (better) define __STL_USE_OWN_NAMESPACE
__STL_NATIVE_INCLUDE_PATH | The path where native compiler headers are located. STLport uses this information to import std:: names into _STL:: namespace. Default is ../include. Hint : never install STLport headers in the directory that ends with include.
__STL_DEBUG | Turns the Debug Mode on. That gets you checked iterators and ranges. Thread-safe.
__STL_USE_SYSTEM_ASSERT | use the system-defined assert instead of fprintf to stderr
__STL_DEBUG_MESSAGE | Uncomment this to force all failed assertions to be directed through a user-defined global function: void __stl_debug_message(const char * format_str, ...). This allows you to take control of assertions for debugging purposes. Note : If you set this macro, you must supply __stl_debug_message function definition somewhere.
__STL_DEBUG_TERMINATE | Uncomment this to force all failed assertions to be executed through user-defined global function: void __stl_debug_terminate(void). This allows you to take control of assertion behaviour for debugging purposes. Default routine throws unique exception if __STL_NO_DEBUG_EXCEPTIONS is not set, calls abort() otherwise. Note : If you set this macro, you must supply __stl_debug_terminate function definition somewhere.
__STL_NO_DEBUG_EXCEPTIONS | Comment this out to enable throwing unique exceptions from default __stl_debug_terminate() instead of calling abort().
__STL_NO_EXCEPTIONS | Disables exception handling code.
__STL_NO_NAMESPACES | Puts STLport into global namespace, even if the compiler supports namespaces.
__STL_NO_RELOPS_NAMESPACE | if defined, don't put the relational operators in namespace std::rel_ops.
_REENTRANT | Define this if your project is multithreaded. STLport uses MT-safe allocator support then.
_NOTHREADS | If defined, STLport don't use any multithreading support.
__STL_NO_NEW_C_HEADERS | If defined, STLport don't use native new-style C headers even if they are available.
__STL_USE_SGI_ALLOCATORS | Force STLport to use older SGI-style allocators as default ones for containers, instead of standard-conforming allocator<>.
__STL_USE_MALLOC | This makes allocator<> to do plain malloc() calls instead of using SGI optimized node allocator engine.
__STL_USE_NEWALLOC | This makes allocator<> to do plain new() calls instead of using SGI optimized node allocator engine.
__STL_DEBUG_ALLOC | This makes allocator<> to perform memory debugging, such as padding/checking for memory consistency.
__STL_DEBUG_UNINITIALIZED | Use this option to catch uninitialized members in your classes. When it is set, construct() and destroy() fill the class storage with __STL_SHRED_BYTE (see below). Note : __STL_DEBUG and __STL_DEBUG_ALLOC don't set this option automatically
__STL_SHRED_BYTE | Provides a definition for the byte with which raw memory will be filled if __STL_DEBUG_ALLOC or __STL_DEBUG_UNINITIALIZED is defined. Choose a value which is likely to cause a noticeable problem if dereferenced or otherwise abused. A good value may already be defined for your platform; see stldebug.h
__STL_DONT_THROW_RANGE_ERRORS | This macro prevents instantiation of at() member function for containers (vector and deque). We do not instantiate at() that does not throw range errors - if this macro is defined, at() method is not defined.
__STL_MSVC50_COMPATIBILITY | This definition makes SGI reverse_iterator to be compatible with other parts of MSVC library. (With partial specialization, it just has no effect). Its use is strongly discouraged - for MSVC5.0 configuration, it is being set automatically.
__STL_USE_MFC | You should define this macro if compiling with MFC - STLport <stl/_config.h> then include <afx.h> instead of <windows.h> to get synchronisation primitives
__STL_MINIMUM_DEFAULT _TEMPLATE_PARAMS | Use minimum set of default arguments on template classes that have more than one - for example map<>, set<>. This has effect only if __STL_LIMITED_DEFAULT_TEMPLATES is on.
__STL_NO_PROXY_ARROW_OPERATOR | By default, STLport uses proxy technique to enable operator -> for iterators even for those compilers that check the return type of unused instantiations. If this causes problems for your project, turn this switch on to disable proxy ->() operators.
__STL_USE_ABBREVS | Use abbreviated class names internally for linker benefit (don't affect interface). This option is obsolete, but should work in this release.
__STL_USE_DECLSPEC | (Windows only) This switch makes some STLport symbols exported from DLL. To use export feature, you should define this macro for all compilation units and also define __STL_DESIGNATED_DLL macro for one of your DLL's which is supposed to export all STLport symbols. You must use this feature if you use default node allocator and pass objects across DLL boundaries. Defined automatically if you use STLport/SGI iostreams and compile with /MD flag.
__STL_DESIGNATED_DLL | (Windows only) Designed to be used together with __STL_USE_DECLSPEC switch to make one of your DLL's to export STLport symbols for other modules. The library which is designated to export DLL symbols, must have both of those switches defined for compilation and it should include at least <string> header from at least one source file. Used by STLport internally to build STLport DLL.
Notes: When using tools like Purify (c), Codeguard (c) or BoundsChecker (c), it is advised to `#define __STL_USE_MALLOC` or `__STL_USE_NEWALLOC`, otherwise pointer checking will generally not be available on most STL internal structures, thus defeating the purpose of those tools. ### Compiler-specific switches Compiler-specific switches are STLport macros describing compiler (mis)features/bugs.Below is the table describing them. They are designed in such a way that the compiler that implements complete set of ANSI C++ features and has no bugs ;) would have empty configuration file. STLport also provides a script that is designed to help you setting those numerous switches. Please read Running configure chapter to learn more about this tool. Note : do not expect STLport to be configured just by running "configure". It is provided only as a tool to help in the initial configuration phase.

#### STLport macros describing compiler features

Controlling macro name | Description | Default
__STL_UINT32_T | Unsigned 32-bit integral type | unsigned long
__STL_LONG_LONG | Defined if compiler supports non-standard long long type | Off
__STL_NO_WCHAR_T | Defined if compiler does not support wchar_t type | Off
__STL_WCHAR_T_IS_USHORT | wchar_t is not a unique type, and is actually a typedef to unsigned short | Off
__STL_NO_LONG_DOUBLE | Defined if compiler does not support long double type | Off
__STL_NO_TYPENAME | Defined if your compiler does not support typename keyword | Off
__STL_NO_EXPLICIT | Defined if your compiler does not support explicit keyword | Off
__STL_NO_MUTABLE | Defined if your compiler does not support mutable keyword | Off
__STL_NO_NEW_STYLE_CASTS | Defined if compiler does not support new-style const_cast<> | Off
__STL_NO_BOOL | Defined if the compiler does not support bool | Off
__STL_DONT_USE_BOOL_TYPEDEF | Bool not supported, but keyword is reserved for future use | Off
__STL_YVALS_H | true/false defined in <yvals.h> header ( Visual C++ 4.2) | Off
__STL_DEFAULT_TEMPLATE_PARAM | Defined if compiler does not support default template parameters | Off
__STL_DEFAULT_TYPE_PARAM | Defined if compiler support only complete types as default parameters | Off
__STL_LIMITED_DEFAULT_TEMPLATES | Defined if the compiler cannot handle default non-type template parameters | Off
__STL_NON_TYPE_TMPL_PARAM_BUG | Defined if compiler has trouble with functions getting non-type-parameterized classes as parameters | Off
__STL_NO_STATIC_TEMPLATE_DATA | Defined if compiler does not support static class data template definition | Off
__STL_STATIC_CONST_INIT_BUG | Defined if compiler does not support initialization of const static class data template members within class. | Off
__STL_WEAK_ATTRIBUTE | Defined if your compiler provides __attribute((weak))__ construct as extension. Only needed if the compiler can't handle static template data members (gcc 2.7.2) | Off
__STL_HAS_NO_NAMESPACES | Defined if your compiler does not support namespaces | Off
__STL_BROKEN_USING_DIRECTIVE | "using" keyword does not work with template types | Off
__STL_HAS_NO_EXCEPTIONS | Defined if your compiler does not support exception-handling | Off
__STL_NO_EXCEPTION_SPEC | Defined if your compiler does not support exception specifications | Off
__STL_THROW_RETURN_BUG | Compiler requires return statement after throw() | Off
__STL_NO_BAD_ALLOC | Header <new> that comes with the compiler does not define bad_alloc exception | Off
__STL_NO_MEMBER_TEMPLATES | Defined if compiler does not support member templates | Off
__STL_NO_MEMBER_TEMPLATE_CLASSES | Defined if compiler does not support member template classes | Off
__STL_NO_FRIEND_TEMPLATES | Defined if compiler does not support friend templates | Off
__STL_NO_QUALIFIED_FRIENDS | Compiler does not accept friend declaration qualified with namespace name. | Off
__STL_NO_CLASS_PARTIAL_SPECIALIZATION | Defined if compiler does not support partial template class specialization | Off
__STL_PARTIAL_SPEC_NEEDS_TEMPLATE_ARGS | Class being partially specialized require full name (template parameters) of itself for method declarations | Off
__STL_PARTIAL_SPECIALIZATION_BUG | Partial specialization has bugs that prevent you from using new-style reverse_iterator | Off
__STL_MEMBER_SPECIALIZATION_BUG | Compiler has problems specializing members of partially specialized class | Off
__STL_NO_METHOD_SPECIALIZATION | Defined if the compiler does not support specializations of single template method. | Off
__STL_NO_FUNC_PARTIAL_ORDERING | Defined if compiler does not support partial template functions ordering | Off
__STL_NO_PARTIAL_SPECIALIZATION_SYNTAX | Defined if compiler does not support full template specialization syntax | Off
__STL_NO_EXPLICIT_FUNCTION_TMPL_ARGS | Compiler does not support explicit template arguments for functions | Off
__STL_AUTOMATIC_TYPE_TRAITS | Defined if the compiler specializes predefined class type_traits<T> for every type. This is an extension | Off
__STL_LOOP_INLINE_PROBLEMS | Defined if your compiler can't inline while(), for() | Off
__STL_BASE_MATCH_BUG | Defined if the compiler fails to match a template function argument of base type | Off
__STL_NONTEMPL_BASE_MATCH_BUG | Defined if the compiler fails to match a template function argument of base (non-template) type | Off
__STL_NESTED_TYPE_PARAM_BUG | Defined if the compiler rejects outline method definition explicitly taking nested types/typedefs | Off
__STL_TYPENAME_ON_RETURN_TYPE | Compiler requires typename keyword on outline method definition explicitly taking nested types/typedefs | Off
__STL_BASE_TYPEDEF_BUG | Defined if your compiler have serious problems with typedefs | Off
__STL_BASE_TYPEDEF_OUTSIDE_BUG | Defined if the baseclass typedefs not visible from outside | Off
__STL_MEMBER_POINTER_PARAM_BUG | Defined if the compiler can't handle pointer-to-member type as function parameter | Off
__STL_UNINITIALIZABLE_PRIVATE | Defined if the compiler has problems with static private data members initialization | Off
__STL_STATIC_ARRAY_BUG | Defined if the compiler has trouble instantiating static array members with dimension defined as enum. | Off
__STL_DEFAULT_CONSTRUCTOR_BUG | Defined if default constructor for builtin integer type fails to initialize it to 0 | Off
__STL_CONST_CONSTRUCTOR_BUG | Defined if constructor required to explicitly call member's default constructors for const objects | Off
__STL_TRIVIAL_CONSTRUCTOR_BUG | Defined if the compiler has trouble calling POD-types constructors | Off
__STL_TRIVIAL_DESTRUCTOR_BUG | Defined if the compiler has trouble calling POD-types destructors | Off
__STL_MULTI_CONST_TEMPLATE_ARG_BUG | problems specializing maps/sets with key type being const | Off
__SGI_STL_NO_ARROW_OPERATOR | Compiler has deficiencie compiling -> operators for iterators. STLport provides proxy workaround for those. | Off
__STL_NO_AT_MEMBER_FUNCTION | Disables at() member functions for containers | Off
__STL_HAS_NO_NEW_IOSTREAMS | Native C++ library does not provide new-style templatized iostreams | Off
__STL_NO_EXCEPTION_HEADER | compiler lacks <exception> header | Off
__STL_HAS_NO_NEW_C_HEADERS | Native library does not provide new-style headers like <cstddef>, only old-style like: <stddef.h> | Off
__STL_HAS_NO_NEW_NEW_HEADER | Native library does not provide new-style like <new> header. | Off
__STL_VENDOR_GLOBAL_STD | compiler-supplied standard library resides in global namespace, not std:: | std::
__STL_VENDOR_GLOBAL_CSTD | compiler-supplied <cstdio> and the like put stuff in global namespace, not std:: | Off
__STL_RAND48 | Defined if C library has lrand48() function | Off
__STL_NATIVE_INCLUDE_PATH | Path to get native compiler headers included. May be relative or absolute. | ../include
__STL_NATIVE_C_INCLUDE_PATH | Path to get native compiler's old-style C headers (like stdio.h) included. May be relative or absolute. | ../include
__STL_NATIVE_CPP_C_INCLUDE_PATH | Path to get native compiler new-style C headers (like cstdio) included. May be relative or absolute. | ../include
__STL_MAKE_HEADER | This macro constructs header path from directory and name. You may change it if your compiler does not understand "/". | <path/header>
__STL_NATIVE_HEADER(header) | This macro constructs native include header path from include path and name. You may have do define it if experiencing problems with preprocessor | See stl_config.h
__STL_NATIVE_C_HEADER(header) | Same for old-style C headers | See stl_config.h
__STL_NATIVE_CPP_C_HEADER(header) | Same for new-style C headers | See stl_config.h
__STL_LINK_TIME_INSTANTIATION | This switch should be set on if the compiler supports separate template compilation model, with non-inlined functions and methods being defined in implementation .c file. | Off
#### ### Modifying the configuration engine Don't edit the "configure" script directly, use config/configure.in source + GNU autoconf instead.