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 _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.
| 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.
| 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