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 :

1. 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.
2. 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 _STLP_USE_EXCEPTIONS macro to 1, then turning exception handling off with -D_STLP_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
_STLP_NO_OWN_IOSTREAMS | This switch is used to select one from two major STLport iostream modes. Please visit "Getting Started" section for details.
_STLP_NO_NEW_IOSTREAMS | Suppress using new-style iostreams even if they are available.
_STLP_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.

_STLP_NO_CUSTOM_IO

This switch is experimental. Define this if you do not instantiate basic_xxx iostream classes with custom types (which is most likely the case). "Custom" means types other than char, wchar and char_traits<>, like basic_ostream<my_char_type, my_traits<my_char_type> >. When this option is on, most non-inline template functions definitions for iostreams are not seen by the client. Default is off, just not to break compilation for those who do use those types. When on, it saves a lot of compile time for most compilers, also object and executable size for some. That also guarantees that you still use optimized standard i/o when you compile your program without optimization and link with optimized library. Option does not affect STLport library build; you may use the same binary library with and without this option, on per-project basis.

_STLP_USE_DEBUG_LIB

(Windows compilers only) Normally, optimized STLport library is being automatically linked in even when you compile your project with _DEBUG set (Debug build). If you wish to use debug build of STLport library for your debug builds, define this option (you will also have to build STLport library with debug flags, via additional "make debug_static debug_dynamic" command, as "make all" only builds "release" and "stldebug" versions of the libraries).

_STLP_USE_STATIC_LIB, _STLP_USE_STATICX_LIB, _STLP_USE_DYNAMIC_LIB

(Windows compilers only) Normally, a version of STLport library iwhich corresponds to your RTL library setting is being automatically linked in (if you use dynamic RTL DLL, dynamic STLport DLL is being used, and vice versa). If you wish to force use of particular (static, dynamic, or "staticx" which is static STLport lib built with dynamic RTL) STLport lib, please make use one of those options.

_STLP_NO_OWN_NAMESPACE | Suppresses STLport use of namespace _STL:: 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.
_STLP_USE_OWN_NAMESPACE | Forces STLport to use _STL:: namespace instead of std:: STLport sets this flag automatically if _STLP_USE_NAMESPACES is set.
_STLP_DONT_RENAME_STD | Precludes STLport from redefining std:: to _STL::. Define it only if renaming scheme does not work for you for some reason.
_STLP_DEBUG | Turns the Debug Mode on. That gets you checked iterators and ranges. Thread-safe.
_STLP_USE_SYSTEM_ASSERT | use the system-defined assert instead of fprintf to stderr
_STLP_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.

_STLP_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 _STLP_NO_DEBUG_EXCEPTIONS is not set, calls abort() otherwise.
Note : If you set this macro, you must supply __stl_debug_terminate function definition somewhere.

_STLP_NO_DEBUG_EXCEPTIONS | Comment this out to enable throwing unique exceptions from default __stl_debug_terminate() instead of calling abort().
_STLP_NO_EXCEPTIONS | Disables exception handling code.
_STLP_NO_NAMESPACES | Puts STLport into global namespace, even if the compiler supports namespaces.
_STLP_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.
_STLP_NO_NEW_C_HEADERS | If defined, STLport don't use native new-style C headers even if they are available.
_STLP_USE_RAW_SGI_ALLOCATORS | Force STLport to use older SGI-style allocators as default ones for containers, instead of standard-conforming allocator<>.
_STLP_USE_MALLOC | This makes allocator<> to do plain malloc() calls instead of using SGI optimized node allocator engine.
_STLP_USE_NEWALLOC | This makes allocator<> to do plain new() calls instead of using SGI optimized node allocator engine.
_STLP_DEBUG_ALLOC | This makes allocator<> to perform memory debugging, such as padding/checking for memory consistency.
_STLP_DEBUG_UNINITIALIZED | Use this option to catch uninitialized members in your classes. When it is set, construct() and destroy() fill the class storage with _STLP_SHRED_BYTE (see below). Note : _STLP_DEBUG and _STLP_DEBUG_ALLOC don't set this option automatically
_STLP_SHRED_BYTE | Provides a definition for the byte with which raw memory will be filled if _STLP_DEBUG_ALLOC or _STLP_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
_STLP_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.
_STLP_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.
_STLP_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
_STLP_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 _STLP_LIMITED_DEFAULT_TEMPLATES is on.
_STLP_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.
_STLP_USE_ABBREVS | Use abbreviated class names internally for linker benefit (don't affect interface). This option is obsolete, but should work in this release.

_STLP_USE_DECLSPEC

(Obsolete, Windows only) This switch makes STLport symbols exported from DLL. To use export feature, you should define this macro for all compilation units and also define _STLP_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, and do not use STLport iostreams. Defined automatically if you use STLport iostreams and compile with /MD flag.

_STLP_DESIGNATED_DLL

(Obsolete, Windows only) Designed to be used together with _STLP_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. Normally you should not be using this, it is 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 _STLP_USE_MALLOC` or `_STLP_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
_STLP_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.
_STLP_UINT32_T | Unsigned 32-bit integral type | unsigned long
_STLP_LONG_LONG | Defined if compiler supports non-standard long long type | Off
_STLP_NO_WCHAR_T | Defined if compiler does not support wchar_t type | Off
_STLP_WCHAR_T_IS_USHORT | wchar_t is not a unique type, and is actually a typedef to unsigned short | Off
_STLP_NO_LONG_DOUBLE | Defined if compiler does not support long double type | Off
_STLP_NO_TYPENAME | Defined if your compiler does not support typename keyword | Off
_STLP_NO_EXPLICIT | Defined if your compiler does not support explicit keyword | Off
_STLP_NO_MUTABLE | Defined if your compiler does not support mutable keyword | Off
_STLP_NO_NEW_STYLE_CASTS | Defined if compiler does not support new-style const_cast<> | Off
_STLP_NO_BOOL | Defined if the compiler does not support bool | Off
_STLP_DONT_USE_BOOL_TYPEDEF | Bool not supported, but keyword is reserved for future use | Off
_STLP_YVALS_H | true/false defined in <yvals.h> header ( Visual C++ 4.2) | Off
_STLP_DEFAULT_TEMPLATE_PARAM | Defined if compiler does not support default template parameters | Off
_STLP_DEFAULT_TYPE_PARAM | Defined if compiler support only complete types as default parameters | Off
_STLP_LIMITED_DEFAULT_TEMPLATES | Defined if the compiler cannot handle default non-type template parameters | Off
_STLP_NON_TYPE_TMPL_PARAM_BUG | Defined if compiler has trouble with functions getting non-type-parameterized classes as parameters | Off
_STLP_NO_STATIC_TEMPLATE_DATA | Defined if compiler does not support static class data template definition | Off
_STLP_STATIC_CONST_INIT_BUG | Defined if compiler does not support initialization of const static class data template members within class. | Off
_STLP_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
_STLP_HAS_NO_NAMESPACES | Defined if your compiler does not support namespaces | Off
_STLP_BROKEN_USING_DIRECTIVE | "using" keyword does not work with template types | Off
_STLP_HAS_NO_EXCEPTIONS | Defined if your compiler does not support exception-handling | Off
_STLP_NO_EXCEPTION_SPEC | Defined if your compiler does not support exception specifications | Off
_STLP_THROW_RETURN_BUG | Compiler requires return statement after throw() | Off
_STLP_NO_BAD_ALLOC | Header <new> that comes with the compiler does not define bad_alloc exception | Off
_STLP_NO_MEMBER_TEMPLATES | Defined if compiler does not support member templates | Off
_STLP_NO_MEMBER_TEMPLATE_CLASSES | Defined if compiler does not support member template classes | Off
_STLP_NO_FRIEND_TEMPLATES | Defined if compiler does not support friend templates | Off
_STLP_NO_QUALIFIED_FRIENDS | Compiler does not accept friend declaration qualified with namespace name. | Off
_STLP_NO_CLASS_PARTIAL_SPECIALIZATION | Defined if compiler does not support partial template class specialization | Off
_STLP_PARTIAL_SPEC_NEEDS_TEMPLATE_ARGS | Class being partially specialized require full name (template parameters) of itself for method declarations | Off
_STLP_PARTIAL_SPECIALIZATION_BUG | Partial specialization has bugs that prevent you from using new-style reverse_iterator | Off
_STLP_MEMBER_SPECIALIZATION_BUG | Compiler has problems specializing members of partially specialized class | Off
_STLP_NO_METHOD_SPECIALIZATION | Defined if the compiler does not support specializations of single template method. | Off
_STLP_NO_FUNC_PARTIAL_ORDERING | Defined if compiler does not support partial template functions ordering | Off
_STLP_NO_PARTIAL_SPECIALIZATION_SYNTAX | Defined if compiler does not support full template specialization syntax | Off
_STLP_NO_EXPLICIT_FUNCTION_TMPL_ARGS | Compiler does not support explicit template arguments for functions | Off
_STLP_AUTOMATIC_TYPE_TRAITS | Defined if the compiler specializes predefined class type_traits<T> for every type. This is an extension | Off
_STLP_LOOP_INLINE_PROBLEMS | Defined if your compiler can't inline while(), for() | Off
_STLP_BASE_MATCH_BUG | Defined if the compiler fails to match a template function argument of base type | Off
_STLP_NONTEMPL_BASE_MATCH_BUG | Defined if the compiler fails to match a template function argument of base (non-template) type | Off
_STLP_NESTED_TYPE_PARAM_BUG | Defined if the compiler rejects outline method definition explicitly taking nested types/typedefs | Off
_STLP_TYPENAME_ON_RETURN_TYPE | Compiler requires typename keyword on outline method definition explicitly taking nested types/typedefs | Off
_STLP_BASE_TYPEDEF_BUG | Defined if your compiler have serious problems with typedefs | Off
_STLP_BASE_TYPEDEF_OUTSIDE_BUG | Defined if the baseclass typedefs not visible from outside | Off
_STLP_MEMBER_POINTER_PARAM_BUG | Defined if the compiler can't handle pointer-to-member type as function parameter | Off
_STLP_UNINITIALIZABLE_PRIVATE | Defined if the compiler has problems with static private data members initialization | Off
_STLP_STATIC_ARRAY_BUG | Defined if the compiler has trouble instantiating static array members with dimension defined as enum. | Off
_STLP_DEFAULT_CONSTRUCTOR_BUG | Defined if default constructor for builtin integer type fails to initialize it to 0 | Off
_STLP_CONST_CONSTRUCTOR_BUG | Defined if constructor required to explicitly call member's default constructors for const objects | Off
_STLP_TRIVIAL_CONSTRUCTOR_BUG | Defined if the compiler has trouble calling POD-types constructors | Off
_STLP_TRIVIAL_DESTRUCTOR_BUG | Defined if the compiler has trouble calling POD-types destructors | Off
_STLP_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
_STLP_NO_AT_MEMBER_FUNCTION | Disables at() member functions for containers | Off
_STLP_HAS_NO_NEW_IOSTREAMS | Native C++ library does not provide new-style templatized iostreams | Off
_STLP_NO_EXCEPTION_HEADER | compiler lacks <exception> header | Off
_STLP_HAS_NO_NEW_C_HEADERS | Native library does not provide new-style headers like <cstddef>, only old-style like: <stddef.h> | Off
_STLP_NO_NEW_NEW_HEADER | Native library does not provide new-style like <new> header. | Off
_STLP_VENDOR_GLOBAL_STD | compiler-supplied standard library resides in global namespace, not std:: | std::
_STLP_VENDOR_GLOBAL_CSTD | compiler-supplied <cstdio> and the like put stuff in global namespace, not std:: | Off
_STLP_RAND48 | Defined if C library has lrand48() function | Off
_STLP_NATIVE_INCLUDE_PATH | Path to get native compiler headers included. May be relative or absolute. | ../include
_STLP_NATIVE_C_INCLUDE_PATH | Path to get native compiler's old-style C headers (like stdio.h) included. May be relative or absolute. | ../include
_STLP_NATIVE_CPP_C_INCLUDE_PATH | Path to get native compiler new-style C headers (like cstdio) included. May be relative or absolute. | ../include
_STLP_MAKE_HEADER | This macro constructs header path from directory and name. You may change it if your compiler does not understand "/". | <path/header>
_STLP_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
_STLP_NATIVE_C_HEADER(header) | Same for old-style C headers | See stl_config.h
_STLP_NATIVE_CPP_C_HEADER(header) | Same for new-style C headers | See stl_config.h
_STLP_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

####

| Table of Contents
| Copyright 2001 by STLport