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