Google Git
Sign in
apache / stdcxx / bcdd75c765493610ae8891a6fdad7c0135d4c0ef / . / README
blob: 6917ffec7b9a6101de4e783905fd74d58c948336 [file] [log] [blame]
$Id$
Apache C++ Standard Library (STDCXX) 4.2.2
------------------------------------------
0 Index
--------
Index ............................................................ 0
Contents ......................................................... 1
Compatibility ................................................ 1.1
Requirements ..................................................... 2
Unpacking Instructions ........................................... 3
Source Directory Structure ....................................... 4
Library Files ................................................ 4.1
Library Utilities ............................................ 4.2
Locales ...................................................... 4.3
Test Suite Files ............................................. 4.4
Examples and Tutorials ....................................... 4.5
Build Directory Structure .................................... 4.6
VisualStudio Build Directory Structure ................... 4.6.1
Library Build Instructions ....................................... 5
VisualStudio Setup Instructions .............................. 5.1
Library Installation ............................................. 6
Library Installation on UNIX Systems ......................... 6.1
Library Installation on Microsoft Windows .................... 6.2
Test Suite Build Instructions .................................... 7
VisualStudio Test Suite Build Instructions ................... 7.1
Library Configuration ............................................ 8
Header config.h (and config.log) ............................. 8.1
Headers rw/_config.h and rw/_defs.h .......................... 8.2
Configuration Macros ......................................... 8.3
Platform Identification Macros ........................... 8.3.1
Compiler Configuration Macros ............................ 8.3.2
Runtime Library Configuration Macros ..................... 8.3.3
C Library Configuration Macros ........................... 8.3.4
Macros Controlling Strings ............................... 8.3.5
Macros Controlling Iostreams ............................. 8.3.6
Macros Controlling Locale ................................ 8.3.7
Macros Controlling Implementation Properties ............. 8.3.8
Other Configuration Macros ............................... 8.3.9
Macros Controlling Extensions ........................... 8.3.10
Library Organization ............................................. 9
Organization of Headers ...................................... 9.1
Organization of Sources ...................................... 9.2
Platform Notes .................................................. 10
Apogee C++ .................................................. 10.1
Borland C++ ................................................. 10.2
Comeau C++ .................................................. 10.3
Compaq/HP C++ ............................................... 10.4
EDG eccp .................................................... 10.5
GNU gcc ..................................................... 10.6
HP aCC ...................................................... 10.7
IBM VisualAge C++ ........................................... 10.8
Intel C++ ................................................... 10.9
KAI C++ .................................................... 10.10
Metrowerks CodeWarrior ..................................... 10.11
Microsoft Visual Studio .................................... 10.12
SGI MIPSpro ................................................ 10.13
Siemens CDS++ .............................................. 10.14
Sun C++ .................................................... 10.15
1 Contents
-----------
This file is part of version 4.2.2 of the Apache C++ Standard
Library (STDCXX), an Open Source implementation of the C++ Standard
Library conforming to INCITS/ISO/IEC 14882-2003 Programming
Languages -- C++.
The distribution consists of this file and a compressed (gzipped)
tar file containing the header and source files comprising the
Apache implementation of the C++ Standard Library, the configuration
infrastructure required to characterize the platform on which the
library is to be built, and a set of scripts and makefiles to build
the library. In addition, a license (LICENSE.txt) and a notice
(NOTICE.txt) files are provided. Read LICENSE.txt to understand the
licensing requirements of the Apache C++ Standard Library. The
NOTICE.txt file contains a list of copyrights that apply to the
same.
In addition, the distribution also contains the Apache C++ Standard
Library test suite, a set of example programs demonstrating the use
of the library, plus scripts and makefiles to build and run the test
suite and the examples and report their results.
The primary audience targeted by this document is library
maintainers, developers, and those porting the library to new
platforms. The purpose of the document is to describe in detail the
process of unpacking, configuring, building, and testing the
library.
1.1 Compatibility
------------------
This version of the library is source as well as both backward and
forward binary compatible with all past or future 4.2.x releases.
Programs compiled and linked with other releases of the (shared)
library within the 4.2.x lineage will continue to link and work
correctly when linked with this version of the library, provided the
same compiler is used to compile both the programs and the library.
Changing the compiler, its version, or some compiler options may
have an impact on the binary compatibility of the generated object
code.
2 Requirements
---------------
The following utilities are required in addition to the standard set
of POSIX utilities in order to unpack and build the library, test
suite (*), and examples (*) on a UNIX system.
* Where available.
o GNU gunzip
o GNU make, version 3.70 or later (referred to as gmake here)
o C++ compiler and linker
3 Unpacking Instructions
-------------------------
The distribution consists entirely of a single file named either
stdcxx-X.Y.Z.tar.gz for a final release, or
stdcxx-X.Y.Z-YYYYMMDD.tar.gz for snapshots.
To unpack the tarball, execute the following command:
$ gunzip -c stdcxx-X.Y.Z.tar.gz | tar -xf -
Above, X, Y, and Z are the major, minor, and micro version number of
the library, respectively, and the optional -YYYYMMDD part is the
date of the snapshot. The date part of the file name will be missing
if the tarball is a final release rather than a snapshot.
The script above will expand the tarball and create a single
directory named stdcxx-X.Y.Z (or stdcxx-X.Y.Z-YYYYMMDD/ for a
snapshot). This directory is referred to a ${TOPDIR} throughout the
rest of this document.
4 Source Directory Structure
-----------------------------
The infrastructure described in this document expects that source
files and any support scripts are organized in a directory tree
described below. If the files are arranged otherwise you will need
to move them to the expected directories in order to accommodate
this requirement and use the infrastructure.
${TOPDIR}/bin/ executable scripts
| doc/index.html documentation index
| generate.bat (obsolete)
| configure.bat Windows configuration script
| ChangeLog log of changes
| GNUmakefile master makefile
| LICENSE.txt license file
| NOTICE.txt copyright notices
| README this file
|
+- etc/
| +- config/GNUmakefile.* makefiles
| | | /*.config compiler config files
| | | /makefile.* common definitions and rules
| | +- src/ configuration sources and
| | | scripts
| | +- windows/generate.wsf solution generation script
| | /configure.wsf configuration script
| | /build.wsf solution build script
| | /makelog.wsf log creation script
| | /runall.wsf testsuite run script
| | /*.js utility scripts
| | /*.config compiler config files
| +- nls/ locale definitions and
| | charmaps
| +- charmaps/ character set description files
| +- src/ locale definition files
+- examples/ set of examples and tutorials
| +- include/*.h common example headers
| +- manual/*.cpp example sources
| +- tutorial/*.cpp tutorial sources
+- include/* public library headers
| +- ansi/* C++ C library headers
| +- loc/_*.{h,c,cc} private locale headers
| +- rw/_*.{h,c,cc} other private library headers
+- src/*.cpp library sources
+- util/*.{h,c,cc,cpp} utility headers and sources
+- tests/ test suite files
| +- include/*.h common test headers
| +- */*.cpp test suite sources
+- ../rwtest test suite infrastructure
+- rw/
| +- rwtest/*.h test suite infrastructure
| headers
+- src/*.cpp test suite infrastructure
sources
4.1 Library Files
------------------
The public interface to the library consists of the following header
files specified by the C++ International Standard:
+------------+------------+------------+------------+------------+
|<algorithm> |<iomanip> |<list> |<ostream> |<streambuf> |
+------------+------------+------------+------------+------------+
|<bitset> |<ios> |<locale> |<queue> |<string> |
+------------+------------+------------+------------+------------+
|<complex> |<iosfwd> |<map> |<set> |<typeinfo> |
+------------+------------+------------+------------+------------+
|<deque> |<iostream> |<memory> |<sstream> |<utility> |
+------------+------------+------------+------------+------------+
|<exception> |<istream> |<new> |<stack> |<valarray> |
+------------+------------+------------+------------+------------+
|<fstream> |<iterator> |<numeric> |<stdexcept> |<vector> |
+------------+------------+------------+------------+------------+
|<functional>|<limits> | | | |
+------------+------------+------------+------------+------------+
These header files are contained in the ${TOPDIR}/include/
directory. Some of them have corresponding .cc and .c files in the
same directory. Those are private files that contain definitions of
out of line template functions, member functions of class templates,
or static data members of class templates.
The facilities of the Standard C library are exposed via the
following header files (along with their deprecated forms, i.e.,
files having the same name except for the leading letter 'c' and the
.h suffix) contained in the ${TOPDIR}/include/ansi/ directory:
+------------+------------+------------+------------+------------+
|<cassert> |<ciso646> |<csetjmp> |<cstdio> |<ctime> |
+------------+------------+------------+------------+------------+
|<cctype> |<climits> |<csignal> |<cstdlib> |<cwchar> |
+------------+------------+------------+------------+------------+
|<cerrno> |<clocale> |<cstdarg> |<cstring> |<cwctype> |
+------------+------------+------------+------------+------------+
|<cfloat> |<cmath> |<cstddef> | | |
+------------+------------+------------+------------+------------+
Any other header files not mandated by the C++ Standard are
contained in the include/rw/ or include/loc subdirectories. Their
names start with an underscore, to prevent potential clashes with
any user headers, and end in a .h suffix. Some of them may have
corresponding .c and .cc files.
In addition to header files, the library consists of a set of
private source files. Source files may have a .cpp, .s or .S
extension (for C++ or assembly source, respectively) and are
contained in the src/ subdirectory of the library source tree.
4.2 Library Utilities
----------------------
Several utility programs are provided in complete source form along
with the library sources. They are: exec, gencat, locale and
localedef. The header and source files for these utilities are
contained in the ${TOPDIR}/util/ directory. The exec and gencat
utilities are part of the test harness and are not intended to be
used directly. The localedef utility is used to build locales from
locale definition files and character set description files.
Locales generated by the utility can be read by the locale utility
and used by the Apache C++ Standard Library's localization library.
4.3 Locales
------------
Locale definition files suitable for processing by the localedef
utility are provided in the ${TOPDIR}/etc/nls/src/
directory. Character set description files that accompany the locale
definition files are provided in the ${TOPDIR}/etc/nls/charmaps/
directory. These files are copies of those distributed with GNU libc
2.2.
4.4 Test Suite Files
---------------------
The test suite consists of a set of three components: a makefile,
the exec test utility residing in ${BUILDDIR}/bin/exec, the test
driver library, rwtest, in ${TOPDIR}/tests/include/, and a large
number of test source files, residing in several subdirectories
under ${TOPDIR}/tests/.
Each test program links with the test driver library,
${BUILDDIR}/rwtest/librwtest.a, which contains code for command line
processing. When the tests are run by the test harness, they produce
output files which are then read and analyzed by the exec
utility. The utility writes the test results to stdandard output in
a tabular format, with columns indicating the exit status of each
test, the number of failed assertions, the total number of
assertions, the number of runtime warnings, and the amount of time
each test took to run. For more information refer to the help
output of the exec utility.
4.5 Examples and Tutorials
---------------------------
Two sets of example and tutorial programs are provided under the
${TOPDIR}/examples/ directory, in subdirectories manual/ and
tutorial/. The vast majority of example programs write their
results to standard output, and some of them also read their
standard input. When running the example programs via the test
harness, the standard input of each example is redirected from the
corresponding .in file (if one exists) in the in/ subdirectory, and
the standard output is compared with the corresponding .out file (if
it exists) in the out/ subdirectory to make sure the two match.
4.6 Build Directory Structure
------------------------------
The directory tree created and partially populated by the master
makefile, ${TOPDIR}/GNUmakefile, has the following structure (the ->
symbol indicates a symbolic link from the file on the left to the
one on the right):
${BUILDDIR}/GNUmakefile -> ${TOPDIR}/GNUmakefile
| /makefile.in generated makefile
| /makefile.common-> ${TOPDIR}/makefile.common
| /makefile.rules -> ${TOPDIR}/makefile.rules
+- bin/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.bin
| /*.{o,...} binaries and temporary files
| /.depend/*.d dependencies
| /run -> ${BUILDDIR}/bin/exec
| /run_utils -> ${TOPDIR}/etc/config/run_locale_utils.sh
+- examples/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.exm
| /run -> ${BUILDDIR}/bin/exec
| /*.{o,...} binaries and temporary files
| /.depend/*.d dependencies
+- include/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.cfg
| /config.h generated config header
| /*.{o,...} binaries and temporary files
| /.depend/*.d dependencies
+- lib/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.lib
| /*.{a,o,so,...} binaries and temporary files
| /.depend/*.d dependencies
+- nls/* -> binary locale files
+- rwtest/GNUmakefile.rwt->${TOPDIR}/etc/config/GNUmakefile.rwt
| /*.{a,o,so,...} binaries and temporary files
| /.depend/*.d dependencies
+- plumhall/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.ph
| /*.{d,o,...} binaries and temporary files
+- tests/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.tst
/*.{o,...} binaries and temporary files
/.depend/*.d dependencies
/*/run -> ${BUILDDIR}/bin/exec
4.6.1 VisualStudio Directory Structure
---------------------------------------
The directory tree created and partially populated by the configure
script, ${TOPDIR}/configure.bat, has the following structure:
${BUILDDIR}/build_${CONFIG}.bat Root build script
| /*.{html,...} Temporary files
+- ${CONFIG}/${CONFIG}.sln Root solution
| /${CONFIG}_ex.sln Examples solution
| /${CONFIG}_loc.sln Locales solution
| /${CONFIG}_run.sln Run examples/tests solution
| /${CONFIG}_tst.sln Tests solution
| /${CONFIG}_tstloc.sln Locales tests solution
| /${CONFIG}slngen.log Configuration log file
+- Projects/*.vcproj Project files
| /examples/*.vcproj Examples project files
| /locales/*.vcproj Locales project files
| /tests/*.vcproj Tests project files
| /util/*.vcproj Utilities project files
.
. ...${BUILDTYPE} directories generated by running build script
.
+- ${BUILDTYPE}/bin/*.{exe,...} Binaries and temporary files
/examples/*.{exe,...} Binaries and temporary files
/include/config.h Generated config header
/lib/*.{dll,lib,...} Binaries and temporary files
/src/*.{obj,...} Temporary files
/tests/*.{obj,...} Binaries and temporary files
/src/*.{obj,...} Temporary files
5 Library Build Instructions
-----------------------------
To build the library, test suite (*), and examples (*), perform the
following steps: (* Where available.)
o $ cd stdcxx-X.Y.Z/
$ ls # this is ${TOPDIR}
bin doc generate.bat LICENSE.txt src
ChangeLog etc GNUmakefile NOTICE.txt tests
configure.bat examples include README util
o $ gmake [ BUILDDIR=<build-dir> ] \
[ BUILDTYPE=<build-type> \
| BUILDMODE=<build-mode> ] \
[ CONFIG=<config-file> ]
<build-dir> is the pathname of the build directory where you want
to perform the build; the directory will be created
(as will all its required subdirectories)
Setting the BUILDDIR variable is optional. When not
specified the effect is the same as if
BUILLDDIR=${TOPDIR}/build had been specified instead.
<build-type> is one of {
8s, 8d, 11s, 11d, 12s, 12d, 15s, 15d,
8S, 8D, 11S, 11D, 12S, 12D, 15S, 15D
}
The numeric part of <build-type> determines the
presence or absence of support for debugging,
whether optimization is or isn't enabled, and the
thread safety level of the library, as follows:
-- optimization enabled: even numbers (i.e., 8 and
12)
-- debugging enabled: odd numbers (i.e., 11 and 15)
-- thread safe code: 12 and 15
The single letter following the numeric part of
<build-type> determines whether an archive or shared
library is built, and whether narrow (32-bit) code
or wide (64-bit) code should be generated:
-- s and S implies an archive library
-- d and D implies a shared library
-- lowercase letter implies narrow (32-bit) code
-- capital letter implies wide (64-bit) code
Setting the BUILDTYPE variable is optional. The
variable must not be defined when BUILDMODE is
defined.
<build-mode> is a comma-separated list of keywords describing how
to build the library and the rest of the
binaries. The following arguments are recognized:
archive - create an archive library (this is default)
dcethreads - create a thread-safe library, use DCE
threads
debug - include debugging information
optimized - optimized
pthreads - create a thread safe library, use POSIX
threads
shared - create a shared library (archive is default)
shared,archive - create an AIX shared archive
threads - create a thread-safe library, use Solaris
threads
narrow - generate narrow (32-bit) code
wide - generate wide (64-bit) code
Setting the BUILDMODE variable is optional. The
variable must not be defined when BUILDTYPE is
defined.
Note that at most one of BUILDTYPE and BUILDMODE must be
defined. When neither is specified, the effect is that of creating
a default configuration for the platform. This is typically an
archive library of the native word-width (narrow on 32-bit
platforms and wide on 64-bit platforms), with no debugging
information, no optimization, and no thread safety.
<config-file> name (not pathname) of a config file containing
compiler options; the available configuration files
are:
acc.config - for HP aCC
como.config - for Comeau C++
eccp.config - for EDG eccp
gcc.config - for gcc
icc.config - for Intel C++ on Linux
mipspro.config - for SGI MIPSpro
osf_cxx.config - for Compaq/HP C++
reliant_cds.config - for Siemens CDS++
sunpro.config - for Sun C++
vacpp.config - for IBM VisualAge C++ and XL C/C++
this argument is optional, the default is gcc.config
o Example:
$ gmake BUILDDIR=/tmp/g++-15d \
BUILDTYPE=15d \
CONFIG=gcc.config
or equivalently
$ gmake BUILDDIR=/tmp/g++-15d \
BUILDMODE=debug,shared,pthreads \
CONFIG=gcc.config
This command will create a build directory rooted at ${BUILDDIR},
run the configuration scripts, and build a thread-safe shared
library with debugging information included and debugging
facilities enabled. If the build is successful, the library will
be located in ${BUILDDIR}/lib/ and will be named
libstd${BUILDTYPE}.so.X.Y.Z (libstd${BUILDTYPE}.a if building an
archive). A symbolic link named libstd${BUILDTYPE}.so in the
same directory will also be created pointing to the shared
library. Public library headers are in ${TOPDIR}/include/ and its
subdirectories, the generated config.h is in
${BUILDDIR}/include/.
o To change preprocessor, compiler, or linker options you can
either set the make variables CPPOPTS, CXXOPTS, and LDOPTS on the
command line (recommended, except with HP aCC) or modify
${BUILDDIR}/makefile.in. The second option is recommended when
compiling with HP aCC (as the compiler looks for environment
variables with the same names).
o To reconfigure and/or rebuild the library (perhaps after changing
a preprocessor, compiler, or linker option), follow these steps:
$ cd ${BUILDDIR}
$ gmake -Cinclude [ config ] # configure
$ gmake config # same
$ gmake lib # build the library
$ gmake examples # build examples
$ gmake util # build utility programs
$ gmake rwtest # build the test driver
$ gmake tests # build tests
$ gmake locales # build locale databases
Alternatively, you can cd into the respective subdirectories and
just type gmake:
$ (cd ${BUILDDIR}/include && gmake) # configure
$ (cd ${BUILDDIR}/lib && gmake) # build the library
$ (cd ${BUILDDIR}/bin && gmake) # build utilities
$ (cd ${BUILDDIR}/examples && gmake) # build examples
$ (cd ${BUILDDIR}/tests && gmake) # build tests
$ (cd ${BUILDDIR}/bin && gmake locales) # build locale databases
Parallel builds (gmake -j[N]) are possible in any directory
except for ${BUILDDIR}/include/.
To remove intermediate files from the build directory, use one of
the following commands:
$ cd ${BUILDDIR}
$ gmake clean # remove all object files
$ gmake dependclean # remove .d files (dependencies)
$ gmake realclean # remove all temporary files
5.1 VisualStudio Setup Instructions
------------------------------------
To generate a Microsoft VisualStudio solution (for .NET 2003 or 2005
only) follow the step below.
o > CD stdlib-X.Y.Z\stdlib
> DIR /D # this is ${TOPDIR}
GNUmakefile etc examples configure.bat include src tests
If your distribution does not contain the test suite and/or the
examples, the output will look like so:
> DIR /D # this is ${TOPDIR}
GNUmakefile etc configure.bat include src
o > .\configure.bat [/BUILDDIR:<builddir>] [/CONFIG:<config>]
<builddir> is the pathname of the build directory where to create
the solution and projects; the directory will be
created (as will all its required subdirectories)
The <builddir> argument is optional. When not
specified a current directory is assumed.
<config> name (not pathname) of a config file containing
compiler options; the available configuration options
are:
icc-9.0 - for Intel C++ 9.0
icc-9.1 - for Intel C++ 9.1
icc-10.0 - for Intel C++ 10.0
icc-10.0-x64 - for Intel C++ 10.0 (x64 platform)
msvc-7.0 - for Microsoft Visual C++ .NET
msvc-7.1 - for Microsoft Visual C++ .NET 2003
msvc-8.0 - for Microsoft Visual C++ .NET 2005
msvc-8.0-x64 - for Microsoft Visual C++ .NET 2005
(x64 platform)
msvc-9.0 - for Microsoft Visual C++ .NET 2008
msvc-8.0-x64 - for Microsoft Visual C++ .NET 2008
(x64 platform)
msvcex-8.0 - for Microsoft Visual C++ Express
2005
The <config> argument is optional. When not
specified, the suitable config file will be selected
automatically.
o Example:
> configure.bat /BUILDDIR:C:\stdcxx /CONFIG:msvc-7.1
This command will create a build directory rooted at ${BUILDDIR},
the solution file ${BUILDDIR}\msvc-7.1\msvc-7.1.sln, the project
files in directory ${BUILDDIR}\msvc-7.1\Projects, and batch file
${BUILDDIR}\build_msvc-7.1.bat.
To build the library, test suite (*), and examples (*), perform the
following steps: (* Where available.)
o > cd ${BUILDDIR}
o > build_msvc-7.1.bat [<build-types>]
<build-types> is one or more of {
8s, 8d, 11s, 11d, 12s, 12d, 15s, 15d
}
The numeric part of <build-type> determines the
presence or absence of support for debugging,
whether optimization is or isn't enabled, and the
thread safety level of the library, as follows:
-- optimization enabled: even numbers (i.e., 8 and
12)
-- debugging enabled: odd numbers (i.e., 11 and 15)
-- thread safe code: 12 and 15
The single letter following the numeric part of
<build-type> determines whether a static or dynamic
library is built:
-- s implies an static library
-- d implies a dynamic library
The <build-types> argument is optional. When not
specified a build type of 11s is assumed.
o Example:
> build_msvc-7.1.bat 15d
run the configuration scripts, and build a thread-safe dynamic
library with debugging information included and debugging
facilities enabled. If the build is successful, the library will
be located in ${BUILDDIR}\msvc-7.1\${BUILDTYPE}\lib\ and will be
named libstd${BUILDTYPE}.dll (libstd${BUILDTYPE}.lib if building
a static library). Public library headers are in
${TOPDIR}\include\ and its subdirectories, the generated config.h
is in ${BUILDDIR}\msvc-7.1\${BUILDTYPE}\include\.
Alternatively, you can run Microsoft Visual Studio IDE, open the
generated solution file, select the desired solution configuration
and invoke "Build"->"Build Solution" command.
6 Library Installation
-----------------------
When using the installed library be sure to define any macros also
defined on the command line when building the library. These are:
_RWSTDDEBUG to enable debugging support in the library; when using
compilers that do not provide an option to enable thread safety or
to select a thread library, the following macros may also have to be
defined: _RWSTD_POSIX_THREADS, _RWSTD_SOLARIS_THREADS,
_RWSTD_DCE_THREADS, and _RWSTDDEBUG. Failing to do so, or failing
to specify the same compiler options that affect the binary
compatibility of the library leads to undefined behavior of the
produced executables.
6.1 Library Installation on UNIX Systems
-----------------------------------------
To install the library, including all required headers, the
utilities that are intended for distribution, and the full set of
locales, follow the following steps:
o $ cd ${BUILDDIR}
o $ gmake install PREFIX=<installation-directory>
The second command will build the library, the utilities, and the
full set of locales, create the specified installation directory if
it doesn't exist yet, and install in it the final product (including
library headers). The structure of the installation directory is as
follows:
${PREFIX}
|
+- bin/locale utility programs
| /localedef
+- etc/rwstderr.cat message catalog
+- include/*{,.cc} library headers
| /config.h generated configuration header
+- lib/libstd*.[a|so] archive or .so symbolic link
| libstd*.so.4.2.2 versioned shared library
+- nls/*/* codeset and locale databases
To specify a subset of locales to install instead of the full set,
define the LOCALES make variable to the desired set of locale
names. For example, to install only the en_US.ISO-8859-1 and
de_DE@UTF-8 locales, enter:
o $ cd ${BUILDDIR}
o $ gmake install PREFIX=<installation-directory> \
LOCALES="en_US.ISO-8859-1 de_DE@UTF-8"
To use the installed library to compile and link C++ programs, set
your compiler's preprocessor search path (typically via the -I
command line option) to point to ${PREFIX}/include, and the linker
search path (typically via the -L command line option) to point to
${PREFIX}/lib, and specify the base name of the library (typically
via the -l command line option).
For example, to compile a C++ program, t.cpp, in the current working
directory with Sun C++ using stdcxx instead of the compiler's native
C++ Standard Library, and link it with the stdcxx library named
libstd12d (i.e., a narrow or 32-bit, optimized, reentrant, shared
library), enter:
o CC -I${PREFIX}/include -mt -library=%none -c -o t.o t.cpp
o CC -L${PREFIX}/lib -mt -library=%none t.o -lstd12d -o prog
This will produce ane executable file named prog that depends on the
stdcxx shared library libstd12d.so. To run the executable, set your
runtime loader path to point to ${PREFIX}/lib before invoking prog.
This is typically done like so (the name of the envrionment variable
may be different depending on the operating system):
o LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${PREFIX}/lib ./prog
7 Test Suite Build Instructions
--------------------------------
The test suite along with the supplied set of example programs and
locales can be built and run or verified by executing the following
commands at the shell prompt:
o $ cd ${BUILDDIR}
$ gmake [ rwtest ][ tests ] [ examples ]
$ gmake runall
The rwtest library is a prerequisite for the test programs (gmake
rwtest).
From ${BUILDDIR}, you can proceed to build the tests and the
examples, either individually or all at the same time. You can
either navigate into the respective subdirectories (i.e.,
${BUILDDIR}/tests/, or ${BUILDDIR}/examples/) and type gmake [
target ] to build there or you can build directly from
${BUILDDIR} by typing gmake tests or gmake examples.
The library sources and headers are expected to reside in
${TOPDIR}/src/ and ${TOPDIR}/include/, respectively, tests in
${TOPDIR}/tests/ and examples in ${TOPDIR}/examples/. The .d
(dependencies) files are placed in the .depend/ subdirectory, and
.o (object) files and the executables are placed in the
respective subdirectories of ${BUILDDIR}.
To run all examples and compare their output with the expected
master output, all tests, and build and verify all locales, type
gmake run while in ${BUILDDIR}. To run the tests or examples
individually, cd into ${BUILDDIR}/tests/ or
${BUILDDIR}/examples/, respectively, and type gmake run.
7.1 VisualStudio Test Suite Build Instructions
-----------------------------------------------
When available, the test suite can be built by following the
following steps.
o Run Microsoft Visual Studio IDE, open the generated solution
file and select the desired solution configuration.
To build the examples select the .stdcxx_examples project and
invoke "Build"->"Build .stdcxx_examples" command.
To build the tests select the .stdcxx_tests project and invoke
"Build"->"Build .stdcxx_tests" command.
To run the examples select the .stdcxx_runexamples project and
invoke "Build"->"Build .stdcxx_runexamples" command.
To run the tests select the .stdcxx_runtests project and invoke
"Build"->"Build .stdcxx_runtests" command.
8 Library Configuration
------------------------
8.1 Heade config.h (and config.log)
------------------------------------
The library is configured (or reconfigured) for the platform (i.e.,
the compiler and operating system) it is to be built by executing
the following command in the ${BUILDDIR}/include/ directory:
$ gmake config
This command generates a new config.h header file in the
${BUILDDIR}/include/ directory (replacing an existing one only if
the new one differs) containing configuration macros describing to
the library the properties of the platform. Executing the config
target writes the details of the configuration, including the
executed commands, into a log file named config.log. This file is
helpful in detecting configuration problems when porting the library
to new environments.
8.2 rw/_config.h and rw/_defs.h
--------------------------------
The generated config.h header is #included by a single private
library header, ${TOPDIR}/include/rw/_config.h. The purpose of this
header is to provide a central place for the maintainers of the
project to manually override the configuration macros #defined in
the automatically generated config.h (e.g., by #undefining them when
they are #defined incorrectly or vice versa) based on their
knowledge of the platform.
The header is divided into three sets of sections: one for the
hardware architecture, one for each supported compiler, and one for
each supported operating system. Each section may #define or
#undefine object-like configuration macros. As a matter of
convention, function-like macros are not #defined in this header.
The ${TOPDIR}/rw/_config.h header is #included by a single library
header, ${TOPDIR}/include/rw/_defs.h. The purpose of this header is
to #define convenience function-like macros, typically based on the
value of one or more object-like configuration macros #defined in
${BUILDDIR}/include/config.h and/or ${TOPDIR}/include/rw/_config.h,
that can then be easily used in the library headers and sources
without the need for complicated, hard-to-read preprocessor
conditionals. The idea is that all the complicated, unsightly logic
is tucked away in one central place and the rest of the code is
clean, even if obfuscated by macros.
Every other library header, whether public or private, #includes the
${TOPDIR}/include/rw/_defs.h header.
8.3 Configuration Macros
-------------------------
The library and the testsuite make use of a large number of macros
to adjust their interface and behavior to the capabilities of the
compiler, the underlying C libraries, and the operating system.
Many of the macro definitions are generated during the
autoconfiguration of the library and placed in
${BUILDDIR}/include/config.h. Some (but not necessarily all) of the
important macros are described here. This list is intended as a
reference for maintainers or porters of the library.
The symbols in square brackets next to the macros below have the
following meaning:
- abi: Affects the binary (ABI or functional) compatibility of the
library. The macro must be consistently #defined to the same value
(or consistently #undefined) during the compilation of the library
as well while using it.
- auto: Automatically determined and #defined during configuration
- lib: Affects library builds. The macro is not to be set except
when building the library.
- over: May be #defined or overridden on the command line or by
editing one of the two config headers either when building the
library or when using it (except for those marked lib).
In addition, whenever a macro with the same root but a different
suffix appears in the description a modified regular expression
syntax has been used to abbreviate the list.
8.3.1 Platform Identification Macros
-------------------------------------
The configuration infrastructure #defines a number of macros some of
which can and should be used instead of similar such macros #defined
by some compilers.
o _RWSTD_OS_<os-name>
The name of the macro depends on the name of the operating system
typically reported by the uname utility:
_RWSTD_OS_AIX: AIX
_RWSTD_OS_DARWIN: Apple Darwin
_RWSTD_OS_FREEBSD: FreeBSD
_RWSTD_OS_HP_UX: HP-UX
_RWSTD_OS_IRIX64: IRIX
_RWSTD_OS_LINUX: Linux
_RWSTD_OS_NETBSD: NetBSD
_RWSTD_OS_OSF1: Tru64 UNIX
_RWSTD_OS_SUNOS: SunOS and Solaris
_RWSTD_OS_WINDOWS: Microsoft Windows
o _RWSTD_OS_SYSNAME
This macro expands to a string literal with the name of the
operating system (the output of uname).
o _RWSTD_OS_RELEASE
This macro expands to a string literal with the name of the
operating system release (the output of uname -r).
o _RWSTD_OS_VERSION
This macro expands to a string literal with the name of the
operating system version (the output of uname -v).
o _RWSTD_OS_MAJOR
This macro expands to the major operating system version as a
constant integer expressions suitable for use in #if
preprocessing directives.
o _RWSTD_OS_MINOR
This macro expands to the minor operating system version as a
constant integer expressions suitable for use in #if
preprocessing directives.
o _RWSTD_OS_MICRO
This macro expands to the micro operating system version as a
constant integer expressions suitable for use in #if
preprocessing directives.
8.3.2 Compiler Configuration Macros
------------------------------------
o _RWSTD_NO_CONST_CAST [auto, over]
o _RWSTD_NO_DYNAMIC_CAST [auto, over]
o _RWSTD_NO_REINTERPRET_CAST [auto, over]
o _RWSTD_NO_STATIC_CAST [auto, over]
#defined when the respective cast operator is not available or
does not function properly. In such cases, the ordinary
(C-style) cast is used instead.
o _RWSTD_NO_EXCEPTION_SPECIFICATION [auto]
#defined when function exception specification is not supported
or not functioning properly. All function exception
specifications in the source code are removed.
o _RWSTD_NO_EXPORT [auto, over]
#defined when the export keyword is not supported or when the
export feature does not work as expected.
o _RWSTD_NO_EXPORT_KEYWORD [auto, over]
#defined when the export keyword is not supported.
o _RWSTD_NO_FUNCTION_TRY_BLOCK [auto]
#defined when the function try block syntax is not supported.
o _RWSTD_NO_EXCEPTIONS [auto, lib]
#defined when exceptions are not supported or disabled. All try
keywords in the source code are removed, catch expands to while
(0) with the assumption that an optimizing compiler will remove
the block.
o _RWSTD_NO_EXPLICIT_INSTANTIATION [abi, auto, lib]
#defined when explicit template instantiation isn't supported.
o _RWSTD_NO_EXPLICIT_CTOR_INSTANTIATION [auto]
#defined when explicit template instantiation of constructors
isn't supported.
o _RWSTD_NO_EXPLICIT_FUNC_INSTANTIATION [abi, auto, lib]
#defined when explicit function template instantiation isn't
supported.
o _RWSTD_NO_EXPLICIT_INSTANTIATION_BEFORE_DEFINITION [auto, lib]
#defined when class templates cannot be explicitly instantiated
lexically before the definitions of all their members defined
outside their bodies.
o _RWSTD_NO_EXPLICIT_INSTANTIATION_WITH_IMPLICIT_INCLUSION [auto]
#defined when explicit template instantiation isn't supported in
conjunction with the implicit inclusion of template definition
files (i.e., the .c or .cc files).
o _RWSTD_NO_EXPLICIT_MEMBER_INSTANTIATION [auto]
#defined when the explicit instantiation of member functions of
class templates isn't supported.
o _RWSTD_NO_EXTERN_TEMPLATE [auto, over]
When #defined, the extern template C++ extension is not supported
by the compiler.
o _RWSTD_NO_IMPLICIT_INSTANTIATION [auto]
#defined when the explicit instantiation of a template that
references another template doesn't cause the implicit
instantiation of the other template.
o _RWSTD_NO_INSTANTIATE_DEFAULT_ARGS
#defined when the explicit instantiation of a function template
with a default argument causes the instantiation of the argument.
o _RWSTD_NO_HONOR_STD
#defined when namespace std is not completely honored. The macro
is typically only #defined when using gcc versions prior to 3.0
without the -fhonor-std compiler option.
o _RWSTD_NO_ICONV_CONST_CHAR [auto]
#defined at configuration time according to the declaration of
the POSIX function iconv().
o _RWSTD_NO_INSTANTIATE_DEFAULT_ARGS [auto, over]
#defined at configuration time for C++ implementations that
instantiate default arguments of function templates (or member
functions of class templates) that depend on a template
parameter.
o _RWSTD_NO_ISO_10646_WCHAR_T
#defined for libc implementations that do not represent values of
wchar_t type in the ISO 10646 encoding (essentially UCS-4, or
UNICODE).
o _RWSTD_NO_IMPLICIT_INCLUSION
#defined for the compilers that use the Borland instantiation
model. It is also defined in some tests and example programs
that have a code layout which is incompatible with using
implicit inclusion on AIX 5.1 with VisualAge for C++ 5.0.2.0.
o _RWSTD_NO_INSTANTIATE [abi, lib, over]
When #defined the library will not explicitly instantiate any
class or function templates.
o _RWSTD_NO_LIB_EXCEPTIONS [auto, lib]
#defined at configuration time when exceptions throws from a
library cannot be caught in a program that links with the
library.
o _RWSTD_NO_LIST_NODE_BUFFER [abi, over]
#defined to disable node buffer management of the class template
std::list.
o _RWSTD_NO_LONG_LONG [abi, auto]
#defined if the C99 type long long is not supported or disabled,
or when _RWSTD_STRICT_ANSI is #defined.
o _RWSTD_NO_MEMBER_EXPLICIT_INSTANTIATION [auto, over]
#defined when explicit instantiation of member templates is not
supported.
o _RWSTD_NO_MEMBER_TEMPLATES [abi, auto]
#defined when member templates are not supported. The library
tries to provide alternative solutions wherever possible. Some
loss of functionality is inevitable.
o _RWSTD_REENTRANT [abi, auto, lib]
#defined for multi-thread safe build types 12[sd] and 15[sd]
either automatically, when the library detects the usage of a
special compiler switch (e.g. -mt on HP-UX and Sun/Solaris), or
through the compiler configurations files in etc/config/
directory.
o _RWSTD_NO_MUTABLE [auto, over]
#defined at configuration time for C++ implementations that do
not recognize the word mutable as a valid keyword.
o _RWSTD_NO_NAMESPACE [abi, auto, lib]
#defined when namespaces are not supported or disabled. All
namespace-scope symbols defined in the sources are introduced to
the global namespace. All using declarations and directives are
removed.
o _RWSTD_NO_NATIVE_BOOL [abi, auto, lib]
#defined for C++ implementations that do not treat bool as a
distinct fundamental type (but perhaps provide a typedef).
o _RWSTD_NO_NATIVE_WCHAR_T
#defined for C++ implementations that do not treat wchar_t as a
distinct fundamental type (but perhaps provide a typedef).
o _RWSTD_NO_NEW_HEADER [auto, over]
When #defined, files will #include the deprecated C library
header files rather than the "new" C++ C library files (e.g.,
<string.h> rather than <cstring>).
o _RWSTD_NO_NEW_CLASS_TEMPLATE_SYNTAX
o _RWSTD_NO_NEW_FUNC_TEMPLATE_SYNTAX
o _RWSTD_NO_NEW_TEMPLATE_SYNTAX
o _RWSTD_NO_NONCLASS_ARROW_RETURN
o _RWSTD_NO_NONDEDUCED_CONTEXT
o _RWSTD_NO_NONTYPE_ARGS
o _RWSTD_NO_NONTYPE_ARGUMENT_DEDUCTION
o _RWSTD_NO_OBJECT_MANGLING [abi, auto, lib]
#defined when the compiler does not include (mangle) information
about the type of namespace-scope objects in their names.
o _RWSTD_NO_PARTIAL_CLASS_SPEC [abi, auto]
#defined when partial specialization of class templates isn't
supported or isn't functional.
o _RWSTD_NO_PART_SPEC_OVERLOAD
o _RWSTD_NO_PRAGMA_INSTANTIATE [lib, over]
#defined when the #pragma instantiate directive isn't supported.
o _RWSTD_NO_PRETTY_FUNCTION [auto, lib, over]
#defined when the __PRETTY_FUNCTION__ special identifier (a
common extension) is not supported.
o _RWSTD_NO_PTR_EXCEPTION_SPEC [auto, over]
#defined when declaring function pointers with exception
specification is not supported.
o _RWSTD_NO_PTR_VALUE_TEMPLATE_OVERLOAD
o _RWSTD_NO_REDUNDANT_DEFINITIONS
o _RWSTD_NO_REDUNDANT_DEFINITIONS [over]
When #defined, public library headers will #include only a
minimum set of other library headers necessary in order for the
definitions of templates contained therein to compile without
actually instantiating any of them. #defining the macro has the
potential to decrease compile times.
o _RWSTD_NO_SETLOCALE_ENVIRONMENT [auto, lib]
#defined when the C locale is not affected by the setting of the
LC_XXX environment variables.
o _RWSTD_NO_SIMPLE_DEFAULT_TEMPLATES
o _RWSTD_NO_SPECIALIZED_FRIEND
o _RWSTD_NO_STATIC_CONST_MEMBER_INIT
o _RWSTD_NO_STATIC_TEMPLATE_MEMBER_INIT
o _RWSTD_NO_STATIC_MUTEX_INIT [abi, auto, lib, over]
#defined when mutex objects with static storage duration cannot
be statically initialized (3.6.2 [basic.start.init]) but must be
initialized during dynamic initialization instead. The macro has
an impact on thread-safety of the library.
o _RWSTD_NO_TEMPLATE_DEFINITIONS [over]
When #defined, public library header files containing definitions
of iostream and locale templates do not explicitly #include the
corresponding implementation .cc files. This option considerably
decreases compile times on platforms that do not support implicit
file inclusion. The macro has no effect when explicit
instantiation is not supported. The macro must not be #defined
when specializations other than those provided by the library
binary are instantiated.
o _RWSTD_NO_TEMPLATE_TEMPLATE [auto]
#defined when template template arguments aren't supported.
o _RWSTD_NO_THROW_SPEC_ON_NEW
When #defined, overloads of operators new and delete declared in
the public library header <new> do not include the required
exception specifications.
o _RWSTD_NO_TYPENAME [auto]
#defined when they keyword typename isn't fully supported.
o _RWSTD_NO_COLLAPSE_STATIC_LOCALS [auto]
#defined when the compiler/linker fail to collapse static local
variables defined in a function template instantiated on the same
type in multiple translation units into one.
o _RWSTD_NO_COLLAPSE_TEMPLATE_LOCALS [auto]
#defined when the compiler/linker fail to collapse static local
variables whose type depends on a template parameter and that are
defined in a function template instantiated on the same type in
multiple translation units into one.
o _RWSTD_NO_COLLAPSE_TEMPLATE_STATICS [auto]
#defined when the compiler/linker fail to collapse static data
members of a class template instantiated on the same type in
multiple translation units into one.
o _RWSTD_NO_USING_LIBC_IN_STD
o _RWSTD_NO_VECTOR_BOOL
When #defined the vector<bool> partial specialization is disabled
and the primary template is used instead.
8.3.3 Runtime Library Configuration Macros
-------------------------------------------
o _RWSTD_NO_NEW_THROWS [auto]
When #defined, operator new doesn't throw an exception but
instead returns 0 on failure.
o _RWSTD_NO_{GLOBAL,STD}_BAD_{ALLOC,CAST,EXCEPTION,TYPEID}
o _RWSTD_NO_{GLOBAL,STD}_EXCEPTION
o _RWSTD_NO_{GLOBAL,STD}_NOTHROW[_T]
o _RWSTD_NO_{GLOBAL,STD}_SET_{NEW_HANDLER,TERMINATE,UNEXPECTED}
o _RWSTD_NO_{GLOBAL,STD}_TERMINATE
[abi, auto, lib]
The macros above are #defined at configuration time according to
which namespace (global or std) each type (or the object nothrow)
is defined in by the language runtime library.
o _RWSTD_NO_{BAD_ALLOC,BAD_CAST,BAD_EXCEPTION,BAD_TYPEID}_{ASSIGNMENT,
COPY_CTOR,DEFAULT_CTOR,DTOR,WHAT} [abi, auto, lib]
Each macro is #defined when the corresponding member of each
respective class is not defined in the language support library.
o _RWSTD_NO_OPERATOR_{DELETE,NEW}[_ARRAY][{_NOTHROW,_PLACEMENT}]
[auto, over]
#defined at configuration time when the definition of the
corresponding operator does not appear in the compiler support
library. The library will provide the missing definitions by
default. If any definition (except for the non-replaceable
placement forms) needs to be replaced, user code should either
#undefine the corresponding macro first or #define
_RWSTD_NO_EXT_OPERATOR_NEW to disable all definitions provided by
the library.
The library is autoconfigured to detect the level of support for
these operators provided by the compiler. The configuration
macros below are #defined if and only if the functions are not
found in the compiler support (a.k.a. language runtime)
library. For each #defined macro, the C++ Standard library
defines the corresponding function in header <new>.
[x] _RWSTD_NO_OPERATOR_DELETE_ARRAY
[x] _RWSTD_NO_OPERATOR_DELETE_ARRAY_NOTHROW
[ ] _RWSTD_NO_OPERATOR_DELETE_ARRAY_PLACEMENT
[x] _RWSTD_NO_OPERATOR_DELETE_NOTHROW
[ ] _RWSTD_NO_OPERATOR_DELETE_PLACEMENT
[x] _RWSTD_NO_OPERATOR_NEW_ARRAY
[x] _RWSTD_NO_OPERATOR_NEW_ARRAY_NOTHROW
[ ] _RWSTD_NO_OPERATOR_NEW_ARRAY_PLACEMENT
[x] _RWSTD_NO_OPERATOR_NEW_NOTHROW
[ ] _RWSTD_NO_OPERATOR_NEW_PLACEMENT
In addition, however, since the functions whose corresponding
config macros above are marked [x] must be replaceable, and since
it may not be possible to achieve the effect of replaceability
without compiler support, the user-controlled macro
_RWSTD_NO_EXT_OPERATOR_NEW may be manually #defined to prevent
the library from defining the functions if a program needs to
replace them.
Finally, the macro _RWSTD_NO_PLACEMENT_DELETE may be #defined
(either by the library headers or, if not, by a program) if it is
necessary to disable declarations and definitions of placement
forms of operator delete, e.g., due to a compiler limitation or a
bug.
o _RWSTD_NO_PLACEMENT_DELETE [auto, over]
When #defined, placement forms of ::operator delete() will not be
declared (or defined) by the header <new>. Provided in case their
declarations cause problems in user code.
8.3.4 C Library Configuration Macros
-------------------------------------
o _RWSTD_NO_EQUAL_CTYPE_MASK [auto, lib]
When #defined, the isxxx() and iswxxx() character classification
functions return different results for of the same arguments.
o _RWSTD_NO_LIBC_IN_STD [auto, over]
When #defined, the names defined by the C library are expected to
be found in namespace std. Otherwise they are expected to be
defined only in the global namespace.
o _RWSTD_NO_{CASSERT,CCTYPE,CERRNO,CFLOAT,CISO646,CLIMITS,CLOCALE,
CMATH,CSETJMP,CSIGNAL,CSTDARG,CSTDDEF,CSTDIO,CSTDLIB,
CSTRING,CTIME,CWCHAR,CWCTYPE} [auto]
#defined when the respective header is not found in the
preprocessor search path.
o _RWSTD_NO_${FUN}[_IN_LIBC] [auto]
#defined when the extern "C" function ${FUN} declaration is not
found in the expected C header, or if the extern "C" symbol
${FUN} is not found in the libc binary.
o _RWSTD_NO_{ABS,ACOS,ASIN,ATAN,ATAN2,CEIL,COS,COSH,EXP,FABS,FLOOR,
FMOD,FREXP,LDEXP,LOG,LOG10,MODF,POW,POW,SIN,SINH,SQRT,
TAN,TANH}{D,DBL,F,FLT,L,LDBL}[_IN_LIBM] [auto]
#defined when the respective functions are not found during
autoconfiguration in the <math.h> header or in the libm library
binary. For example, when the function extern "C" float
acosf(float) is not declared in <math.h> on a platform but the
symbol extern "C" acosf is found in the libm library binary, the
macro _RWSTD_NO_ACOSF will be #defined but the macro
_RWSTD_NO_ACOSF_IN_LIBM will be #undefined.
o _RWSTD_NO_PURE_C_HEADERS
#defined to disable the use of "pure" C++ Standard C library
headers. The pure headers expose only the set of symbols
specified by the C++ and C standards and nothing more.
o _RWSTD_NO_WCSFTIME_WCHAR_T_FMAT [auto]
8.3.5 Macros Controlling Strings
---------------------------------
o _RWSTD_NO_STRING_MUTEX [abi, lib, over]
When #defined std::basic_string objects are not reference counted.
o _RWSTD_ONE_STRING_MUTEX [abi, lib, over]
When #defined std::basic_string objects are reference counted. A
single per-process mutex object is used for thread safety.
o _RWSTD_USE_STRING_ATOMIC_OPS [abi, lib, over]
When #defined on Linux/x86_64 (AMD64 or EM64T), in wide (64-bit)
mode, std::basic_string objects use atomic operations for
reference counting instead of the default mutex. Using a mutex
in basic_string is suboptimal and is only done in this release of
the library to maintain binary compatibility with previous
versions. This macro is provided to allow users not constrained
by binary compatibility to make use of the more efficient
implementation of strings. The macro has no effect in the narrow
(32-bit) configuration on this platform or on any other
platforms.
8.3.6 Macros Controlling Iostreams
-----------------------------------
o _RWSTD_NO_IOSTREAM_OBJECT_REFS [abi, auto, lib, over]
When #defined while _RWSTD_NO_STATIC_IOSTREAM_INIT is not
#defined, the eight standard iostream objects (cout, etc.) are
declared in <iostream> to be of their respective types but
defined in the library binary to be of an unrelated POD type to
prevent their destruction during program lifetime. Since object
type isn't typically encoded in its name and the declaration and
definition isn't ever seen by the compiler in the same
translation unit this doesn't cause problems.
o _RWSTD_NO_NATIVE_IO [lib, over]
#defined to force file streams to use the facilities of libc
stdio as opposed to the POSIX I/O interface.
o _RWSTD_DEFAULT_BUFSIZE [lib, over]
#defined to the size of the character buffer used by objects of
std::basic_filebuf<>, in characters. The default value is 512.
o _RWSTD_PBACK_SIZE [lib, auto]
#defined to the size of the basic_streambuf putback area in
characters. The default value is 4.
o _RWSTD_NO_REENTRANT_IO [abi, lib, over]
#defined when the iostream library should not be thread-safe.
o _RWSTD_NO_REENTRANT_IO_DEFAULT [abi, lib, over]
#defined when the standard iostream objects should not be
thread-safe by default.
o _RWSTD_NO_STATIC_IOSTREAM_INIT [abi, auto, lib, over]
When #defined, the eight standard iostream objects (std::cin,
std::cout, etc.) are ordinary objects with static storage
duration and are destroyed during program lifetime (which
violates 27.3, p2).
8.3.7 Macros Controlling Locale
--------------------------------
o _RWSTD_NO_CAT_NAMES
When #defined, combined locale names do not include the names of
locale categories. For example, on Solaris, combined locale names
consist of the name of each category in a fixed order separated
by slashes. On Linux, combined locale names, however, include the
name of each category followed by the equals sign followed by the
name of the locale, with the categories separated from one
another by a semicolon. E.g., "LC_CTYPE=C;LC_TIME=en;..."
o _RWSTD_NO_INITIAL_CAT_SEP [auto, lib]
#defined at configuration time in environments where combined
libc locale names do not begin with the character used to
separate the names of individual locale categories. For example,
HP-UX 11.00 combined locale name has the form "C C C en C C" but
on Solaris, the equivalent name would be "/C/C/C/en/C/C". On
Solaris, then, the macro would be #defined.
o _RWSTD_CAT_SEP
Expands to a character string that separates locale categories in
combined locale names (such as " " on AIX and HP-UX, "/" on
Solaris, or ";" on Linux).
o _RWSTD_NO_CAT_EQ
When #defined, the names of locale categories in combined locale
names are not separated from the name of the locale by the
equals sign.
o _RWSTD_NO_CONDENSED_NAME
When #defined, locale names always include all locale
categories, even if they are all the same. This is true, for
example, on HP-UX when the name of the "C" locale returned from
setlocale (LC_ALL, 0) is "C C C C C C" and not just "C" as it is
on Solaris.
o _RWSTD_LDBL_PRINTF_PREFIX [auto, lib]
#defined the printf() format modifier as a string literal for
type long double, when supported. Typically, the value of the
macro is "L".
o _RWSTD_NO_LDBL_PRINTF_PREFIX [auto, lib]
#defined when no printf() format modifier for type long double is
known.
o _RWSTD_LLONG_PRINTF_PREFIX [auto]
#defined the printf() format modifier as a string literal for
type long long, when supported. Typically, the value of the macro
is "ll".
o _RWSTD_NO_LLONG_PRINTF_PREFIX [auto]
#defined when no printf() format modifier for type long long is
known.
o _RWSTD_EXPORT [auto]
_RWSTD_CLASS_EXPORT [auto]
_RWSTD_MEMBER_EXPORT [auto]
These three macros control the exporting of symbols from the
library; the latter two are used in selectively controlling the
exporting of symbols from classes that have member templates
(e.g. locale class).
o _RWSTD_NO_STRTOF_UFLOW [auto, lib]
_RWSTD_NO_STRTOD_UFLOW
_RWSTD_NO_STRTOLD_UFLOW
Each of these macros is #defined when the corresponding C library
function fails to set errno (usually to ERANGE) on underflow.
8.3.8 Macros Controlling Implementation Properties
---------------------------------------------------
o _RWSTD_BOOL_SIZE [abi, auto, lib]
_RWSTD_CHAR_SIZE
_RWSTD_SHRT_SIZE
_RWSTD_INT_SIZE
_RWSTD_LONG_SIZE
_RWSTD_LLONG_SIZE
_RWSTD_FLT_SIZE
_RWSTD_DBL_SIZE
_RWSTD_LDBL_SIZE
_RWSTD_WCHAR_T_SIZE
_RWSTD_PTR_SIZE
_RWSTD_FUNPTR_SIZE (function pointer)
_RWSTD_MEMPTR_SIZE (member pointer)
Each of the _RWSTD_<type>_SIZE macros above expands to the size
of the respective fundamental type (as returned by sizeof) as a
constant integer expressions suitable for use in #if
preprocessing directives. If no such type exists the
corresponding macros are not #defined.
o _RWSTD_CHAR_BIT
Expands to the value of CHAR_BIT as a constant integer
expressions suitable for use in #if preprocessing directives.
o _RWSTD_BOOL_{MAX,MIN} [abi, auto, lib]
_RWSTD_CHAR_{MAX,MIN}
_RWSTD_SCHAR_{MAX,MIN} (int)
_RWSTD_UCHAR_{MAX,MIN} (unsigned int)
_RWSTD_SHRT_{MAX,MIN} (int)
_RWSTD_USHRT_{MAX,MIN} (unsigned int)
_RWSTD_INT_{MAX,MIN}
_RWSTD_UINT_{MAX,MIN}
_RWSTD_LONG_{MAX,MIN}
_RWSTD_ULONG_{MAX,MIN}
_RWSTD_LLONG_{MAX,MIN}
_RWSTD_ULLONG_{MAX,MIN}
_RWSTD_WCHAR_T_{MAX,MIN} (int or long)
_RWSTD_SIZE_{MAX,MIN} (size_t)
_RWSTD_PTRDIFF_{MAX,MIN} (ptrdiff_t)
_RWSTD_WINT_{MAX,MIN} (wint_t)
Each of the _RWSTD_<type>_{MAX,MIN} macros above expands to the
maximum and minimum representable value in the respective integer
type as a constant integer expressions suitable for use in #if
preprocessing directives. Except as marked, the type of each
macro is the corresponding type promoted according to the integer
promotion rules. If no such type exists the corresponding macros
are not #defined.
o _RWSTD_INT8_T [abi, auto, lib]
_RWSTD_UINT8_T
_RWSTD_INT16_T
_RWSTD_UINT16_T
_RWSTD_INT32_T
_RWSTD_UINT32_T
_RWSTD_INT64_T
_RWSTD_UINT64_T
Each of the _RWSTD_INT<width>_T and _RWSTD_UINT<width>_T macros
above expands to the signed and unsigned, respectively, type T
for which (sizeof(T) * CHAR_BIT == width) holds. If no such type
exists the macro is not #defined. Note that each macro can expand
to two or more tokens.
o _RWSTD_{FLT,DBL,LDBL}_{INF,SNAN,QNAN}_BITS [auto, lib]
#defined at configuration time to be the byte representation of
infinity, signaling NaN and quiet NaN, respectively. The macros
are defined as brace-delimited arrays of chars.
o _RWSTD_{FLT,DBL,LDBL}_HAS_DENORM [auto, lib]
#defined to 1 when the corresponding floating point type supports
denormalized values and to 0 otherwise.
o _RWSTD_NO_DBL_TRAPS [auto, lib]
#defined when values of type double implement trapping for
certain arithmetic operations (such division by zero).
o _RWSTD_NO_IEC559 [auto, over]
#defined at configuration time if it is determined that the
environment fails to satisfy the requirements of the IEC 559
standard.
o _RWSTD_NO_IEEEFP_H
o _RWSTD_NO_INFINITY [auto]
#defined at configuration time for environments that do not
support the concept of a floating point infinity.
o _RWSTD_NO_INT_TRAPS [auto, lib]
#defined when values of type int implement trapping for certain
arithmetic operations (such division by zero).
o _RWSTD_NO_NAN_TRAPS [auto, lib]
#defined when the value NaN (Not a Number) causes a hardware trap
when used in arithmetic expressions.
o _RWSTD_NO_SIGNALING_NAN
8.3.9 Other Configuration Macros
---------------------------------
o _RWSTD_NO_OPTIMIZE_SPEED
8.3.10 Macros Controlling Extensions
-------------------------------------
The following options are provided to allow to disable various
library extensions. An extensions is defined as a library interface
or its behavior that is left unspecified by the standard or, in some
rare cases, that is specified by the standard but where this
implementation differs from the specification.
In addition to the symbols in square brackets defined above, the
symbol pure denotes an extension that is not conflict with the C++
standard:
o _RWSTD_NO_EXTENSIONS [over]
o _RWSTD_STRICT_ANSI [over]
When #defined, most library extensions are disabled by #defining
the various _RWSTD_NO_EXT_XXX macros documented below. The
_RWSTD_STRICT_ANSI macro is deprecated and should be avoided.
o _RWSTD_NO_EXT_DEQUE_ASSIGN_IN_PLACE [over]
o _RWSTD_NO_EXT_DEQUE_INSERT_IN_PLACE [over]
o _RWSTD_NO_EXT_VECTOR_ASSIGN_IN_PLACE [over]
o _RWSTD_NO_EXT_VECTOR_INSERT_IN_PLACE [over]
When #defined, the multi-element overloads of the member
functions assign() and insert() defined by the class templates
deque and vector provide the basic exception guarantee as
required by the C++ Standard. Otherwise, when (size() >= N) holds
for N being the number elements being assigned or inserted, and
value_type's assignment operator or iterator operations do not
throw, the functions provide the nothrow exception guarantee.
o _RWSTD_NO_EXT_FILEBUF [pure, over]
When #defined, extensions to the class template
std::basic_filebuf and the std::basic_fstream family of templates
are not available.
o _RWSTD_NO_EXT_DEEP_STRING_COPY [pure]
When #defined, the member function copy() of class template
basic_string which returns a deep copy of the string object is
not declared.
o _RWSTD_NO_EXT_FAILURE [lib, over, pure]
When #defined, disables extensions to the std::ios_base::failure
class (i.e., the classes std::ios_base::badbit_set, eofbit_set,
and failbit_set). #defining _RWSTD_STRICT_ANSI causes the
#definition of this macro as well.
o _RWSTD_NO_EXT_BITSET_CTOR_CHAR_ARRAY [over, pure]
When #defined, disable the declarations of the two std::bitset
constructor overloads that take const char* and const wchar_t*,
respectively, as their first argument. The purpose of this
extension is to make it possible to construct std::bitset objects
from string literals without dynamic memory allocation.
o _RWSTD_NO_EXT_BITSET_CTOR_STRING [over, pure]
When #defined, disable the declaration of the two std::bitset
constructor overloads that take std::string and std::wstring,
respectively, as their first argument. The purpose of this
extension is to make it possible to construct std::bitset objects
from string literals.
o _RWSTD_NO_EXT_BITSET_TO_STRING [over, pure]
When #defined, disables the declarations of the three overloads
of the const member function to_string() of the class template
std::bitset specified in LWG issue 434:
http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#434
o _RWSTD_NO_EXT_BIN_IO [over, pure]
When #defined, disables support for base 2 numerical input and
output in iostreams and the std::num_get<> and std::num_put<>
facets, and undefines the symbol std::ios_base::bin. #defining
_RWSTD_STRICT_ANSI causes the #definition of this macro as well.
o _RWSTD_NO_EXT_IOS_SAFE_CONVERSION [over]
When #defined, the const member function operator void*() of
the class template basic_ios is declared. Otherwise, the
resolution of the Library Working Group's issue 568 is
implemented instead. See
http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#468
o _RWSTD_NO_EXT_OPERATOR_NEW [auto, over]
When #defined, disables the replaceable definitions provided in
<new> for missing global operators new and delete, allowing them
to be defined by the user.
o _RWSTD_NO_EXT_PORTABLE_RANDOM_SEQUENCE [lib, pure]
When #defined, the random number generator used by this
implementation of the C++ Standard Library generates integer
values in the full range of the type size_t. Otherwise, the
generator is restricted to the range of unsigned 32-bit values
for data portability.
o _RWSTD_NO_EXT_REENTRANT_IO [over, pure]
When #defined, disables support for user-control of iostream and
streambuf locking, and undefines the symbols
std::ios_base::nolock and std::ios_base::nolockbuf. Only
relevant in thread-safe builds. #defining _RWSTD_STRICT_ANSI
causes the #definition of this macro as well.
o _RWSTD_NO_EXT_SETBASE
When #defined, the std::setbase manipulator accepts only the
required numeric bases (i.e., 0, 8, 10, 16, and 2 unless
_RWSTD_NO_EXT_BIN_IO is also #defined).
o _RWSTD_NO_EXT_VOID_COUNT [over, pure]
When #defined, disables the non-conforming versions of the
std::count() and std::count_if() algorithms that take four or
five arguments, respectively, and return void. The algorithms are
provided for backward compatibility or on platforms that cannot
handle partial specialization of class templates. The macro has
no effect if partial specialization is not supported.
o _RWSTD_NO_EXT_VOID_DISTANCE [over, pure]
When #defined, disables the non-conforming version of the
std::distance() algorithm that takes three arguments and returns
void. The algorithm is provided for backward compatibility or on
platforms that cannot handle partial specialization of class
templates. The macro has no effect if partial specialization is
not supported.
o _RWSTD_NO_REENTRANT_IO_DEFAULT [lib, over, pure]
When #defined in thread-safe builds, all newly constructed
iostream objects (i.e., other than the standard iostream objects
std::cin, std::cout, etc.) are created with the bits
std::ios_base::lock and std::ios_base::lockbuf set (i.e., the
same object will be safe to use across thread
boundaries). Otherwise, the are created with the bits set. Has
no effect if _RWSTD_NO_EXT_REENTRANT_IO is #defined or in
non-thread-safe builds.
o _RWSTD_NO_EXT_CHAR_TRAITS_PRIMARY [over, pure]
o _RWSTD_NO_EXT_CODECVT_PRIMARY [over, pure]
o _RWSTD_NO_EXT_CTYPE_PRIMARY [over, pure]
o _RWSTD_NO_EXT_COLLATE_PRIMARY [over, pure]
o _RWSTD_NO_EXT_MONEYPUNCT_PRIMARY [over, pure]
o _RWSTD_NO_EXT_NUMPUNCT_PRIMARY [over, pure]
o _RWSTD_NO_EXT_TIME_GET_PRIMARY [over, pure]
o _RWSTD_NO_EXT_TIME_PUT_PRIMARY [over, pure]
o _RWSTD_NO_EXT_MESSAGES_PRIMARY [over, pure]
When #defined, the corresponding primary template, which is
otherwise defined as an extension of this implementation, is not
defined by the library.
9 Library Organization
-----------------------
The symbols declared and defined by this implementation of the C++
Standard Library are organized in a number of public and private
headers, template implementation files, C++ source files, and
assembly files. The purpose of this section is to document the
conventions used in the organization of the symbols and their
declarations and definitions in the library files.
9.1 Organization of Headers
----------------------------
Every library header starts with a comment containing the relative
pathname of the file with respect to the ${TOPDIR}/include/
directory (such as iostream or rw/_config.h) along with a brief
description of the contents of the file and a copyright notice.
Below the comment is a header #inclusion guard that prevents the
contents of the same header file from being expanded more than once
in any translation unit from which the header might be included more
than once. The naming convention used for the guard is as follows:
#ifndef _RWSTD_<file-name>_INCLUDED
#define _RWSTD_<file-name>_INCLUDED
... /* contents of the file*/
#endif // _RWSTD_<file-name>_INCLUDED
Where <file-name> is the relative pathname of the header with
slashes replaced by underscores (e.g, _RWSTD_IOSTREAM_INCLUDE for
the header iostream or _RWSTD_RW_CONFIG_H_INCLUDED for
rw/_config.h).
In order to minimize the size of translation units and the namespace
pollution caused by #including library headers in programs (as well
as the library sources themselves) library headers #include only the
absolute minimum of other C++ Standard library headers, and only
those third party (such as libc or OS) headers that are absolutely
necessary and whose symbols cannot be forward-declared. This set of
third party headers is at this point limited to <cstring>, <cwchar>,
and <ctime>, and the appropriate threads header in thread-safe
configurations. Since no other headers are #included, common C
library symbols such as ptrdiff_t, size_t, or CHAR_MAX that are
declared in these headers are determined at library configuration
time and available under the appropriate configuration macros
(_RWSTD_PTRDIFF_T, _RWSTD_SIZE_T, and _RWSTD_CHAR_MAX in this
example). The C++ Standard library headers always use these macros
rather than their C library equivalents. In order to make sure these
macros are always available every library header must contain the
#include <rw/_defs.h> directive.
9.2 Organization of Sources
----------------------------
Every library source file starts with a comment containing name of
the file along with a brief description of the contents of the file
and a copyright notice.
Below the comment are any necessary #include directives, including
#include <rw/_defs.h>. Since namespace pollution is not a concern
for source files, the "deprecated" C library headers (such as
<stdio.h>) are always #included in favor of the "new" C++ C library
equivalents (i.e., <cstdio>) for portability. However, since the
size of library translation units has an effect on the size of the
library itself as well as on the size of executables linked with an
archive version of the library, each source file must include only
the bare minimum of the C++ Standard Library headers.
In order to minimize code bloat, library source files must take care
to instantiate only the barest minimum of templates defined by the
library. No source file instantiates any public templates unless
necessitated by the requirements of the C++ Standard. For instance,
while it isn't possible to avoid instantiating std::string (since
the type is used in locale and iostreams), instantiating any other
container is unnecessary and thus avoided.
In order to further minimize the size of programs that link with an
archive version of the library each library source file defines only
the smallest set of symbols that is to the maximum possible extent
independent of those defined in any other library source file.
10 Platform Notes
------------------
10.1 Apogee C++
----------------
Port not maintained.
10.2 Borland C++
-----------------
Not ported.
10.3 Comeau C++
----------------
Ported to Comeau C++ 4.2.42 or later on Solaris.
This release not tested.
10.4 Compaq/HP C++
-------------------
Ported to Compaq/HP C++ 6.2 or later for Tru64 UNIX.
This release tested with:
o Compaq/HP C++ 6.5 and 7.1 on Tru64 UNIX
o Compaq/HP C++ 7.1 on Tru64 UNIX
Shared library contains uresolved references that cause
linker errors in programs that link with it.
See http://issues.apache.org/jira/browse/STDCXX-406
10.5 EDG eccp
--------------
Ported to the EDG eccp demo 2.45.2 through 3.10 on Linux and
Solaris.
This release tested with:
o EDG eccp 3.9 on Red Hat Enterprise Linux 5.0, x86_64
o EDG eccp 3.9 on Solaris 9
10.6 GNU gcc
-------------
Ported to gcc 2.95.2 through 4.1.0 on a variety of operating
systems and architectures, including Darwin (Mac OS X), HP-UX,
Linux, and Solaris.
This release tested with:
o gcc 4.3.0, Fedora 8, x86_64
o gcc 4.2.1, Fedora 8, x86_64
o gcc 4.1.1, Solaris 10, SPARC
o gcc 4.1.0, SUSE Linux Enterprise Server 10, x86_64
o gcc 4.0.1, Mac OS X (Darwin), x86
o gcc 3.4.6, Red Hat Enterprise Linux 4, x86_64
o gcc 3.4.4, Cygwin on Windows XP, x86
o gcc 3.4.4, FreeBSD 6.2, x86
o gcc 3.4.4, Red Hat Enterprise Linux 4, IA64
o gcc 3.3.3, SUSE Linux Enterprise Server 9.1, x86_64
o gcc 3.2.3, Red Hat Enterprise Linux 3, x86_64
10.7 HP aCC
------------
Ported to HP aCC 3.13 and later for PA-RISC, and 5.36 and later,
and 6.0 and later for IPF.
This release tested with:
o aCC 6.15, HPUX 11.23, IPF
o aCC 6.15, HPUX 11.23, IPF
o aCC 6.00, HPUX 11.23, IPF
o aCC 5.57, HPUX 11.23, IPF
o aCC 3.73, HPUX 11.23, PA-RISC
o aCC 3.73, HPUX 11.11, PA-RISC
o aCC 3.63, HPUX 11.31, PA-RISC
o aCC 3.63, HPUX 11.23, PA-RISC
o aCC 3.63, HPUX 11.11, PA-RISC
10.8 IBM VisualAge C++
-----------------------
Ported to VisualAge C++ 5.0 on AIX 4.3, VisualAge C++ 6.0 on AIX
5.2, and XLC++ 7.0, 8.0, and 9.0 on AIX 5.2 and 5.3.
This release tested with:
o XLC++ 9.0, AIX 5.3, POWER
o XLC++ 8.0, AIX 5.3, POWER
o XLC++ 7.0, AIX 5.3, POWER
o VisualAge C++ 6.0, AIX 5.2, POWER
For builds with VisualAge C++ 5.0 and 6.0 there are some special
considerations when building programs that use the implicit
inclusion mechanism (i.e., the -qtempinc mode which is active by
default).
The mechanism imposes some restrictions on the way the source code
is structured: template declarations have to be present in header
files while corresponding .c source files must contain these
templates' implementations. Source code otherwise perfectly
correct, containing template classes or functions definitions or
definitions of types used in instantiations of templates in cpp
files, will not be able to benefit from this feature.
10.9 Intel C++
---------------
Ported to Intel C++ 7.0 through 9.0 on Linux and Windows (x86,
IA64, and x86_64).
This release tested with:
o Intel C++ 10.0 and 9.1, Red Hat Enterprise Linux 5 and 4, x86_64
o Intel C++ 10.0 and 9.1, SUSE Linux Enterprise Server 10 and 9, x86_64
o Intel C++ 10.0 and 9.1, Windows Vista, XP and 2003, x86_64 and x86
10.10 KAI C++
--------------
Port not maintained.
10.11 Metrowerks CodeWarrior
-----------------------------
Not ported.
10.12 Microsoft Visual Studio
------------------------------
Ported to Visual Studio .NET 2002 (AKA MSVC 7.0) through Visual
Studio .NET 2008 (AKA MSVC 9.0) on Windows (x86, IA64, and
x86_64).
This release tested with:
o Visual Studio 2008, Windows Vista, XP, and 2003, x86 and x86_64
o Visual Studio 2005, Windows Vista, XP, and 2003, x86 and x86_64
o Visual Studio 2003, Windows XP and 2003, x86
10.13 SGI MIPSpro
------------------
Ported to SGI MIPSpro 7.3 through 7.5 for IRIX 6.5.
This release tested with:
o SGI MIPSpro 7.41, IRIX 6.5, MIPS
10.14 Siemens CDS++
--------------------
Port not maintained.
10.15 Sun C++
--------------
Ported to Sun C++ 5.3 through 5.9 on Solaris and Linux (SPARC,
x86, and x86_64).
This release tested with:
o Sun C++ 5.9, Red Hat Enterprise Linux 4, Update 4, x86_64
o Sun C++ 5.9, SUSE Linux Enterprise Server 9.1, x86_64
o Sun C++ 5.9, Solaris 10, 9, 8, x86_64 and SPARC
o Sun C++ 5.8, Solaris 10, 9, 8, x86_64 and SPARC
o Sun C++ 5.7, Solaris 10, SPARC
o Sun C++ 5.6, Solaris 9, SPARC
o Sun C++ 5.3, Solaris 8, SPARC