Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/libs/config/config.htm @ 35

Last change on this file since 35 was 29, checked in by landauf, 16 years ago
updated boost from 1_33_1 to 1_34_1
File size: 92.8 KB

Line
1	<html>
2	<head>
3	<title></title>
4	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5	<meta name="Template" content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
6	<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
7	</head>
8	<body bgcolor="#ffffff" link="#0000ff" vlink="#800080">
9	<p align="left"><img src="../../boost.png" alt="Boost" width="277" height="86"></p>
10	<h1 align="center">Boost Configuration Reference</h1>
11	<h2>Contents</h2>
12	<pre><a href="#configuring">Configuring Boost for Your Platform</a>
13	<a href="#default_config">Using the default boost configuration
14	</a> <a href="#header">The <boost/config.hpp> header</a>
15	<a href="#config_script">Using the configure script</a>
16	<a href="#user_settable">User settable options</a>
17	<a href="#advanced_config">Advanced configuration usage</a>
18	<a href="#testing">Testing the boost configuration</a>
19	<a href="#macro_ref">Boost Macro Reference</a>
20	<a href="#defects">Macros that describe defects</a>
21	<a href="#features">Macros that describe optional features</a>
22	<a href="#helpers">Boost Helper Macros</a>
23	<a href="#info_macros">Boost Informational Macros</a>
24	<a href="#source">Macros for libraries with separate source code</a>
25	<a href="#guidelines">Guidelines for Boost Authors</a>
26	<a href="#defect_guidelines">Adding New Defect Macros</a>
27	<a href="#feature_guidelines">Adding New Feature Test Macros</a>
28	<a href="#modify_guidelines">Modifying the Boost Configuration Headers</a>
29	<a href="#rationale">Rationale</a>
30	<a href="#Acknowledgements">Acknowledgements</a></pre>
31	<h2><a name="configuring"></a>Configuring Boost for Your Platform</h2>
32	<h4><a name="default_config"></a>Using the default boost configuration</h4>
33	<p>Boost comes already configured for most common compilers and platforms; you
34	should be able to use boost "as is". Since the compiler is configured
35	separately from the standard library, the default configuration should work
36	even if you replace the compiler's standard library with a third-party standard
37	library (like <a href="http://stlport.sourceforge.net">STLport</a>).
38	</p>
39	<p>Using boost "as is" without trying to reconfigure is the recommended method for
40	using boost. You can, however, run the configure script if you want to, and
41	there are regression tests provided that allow you to test the current boost
42	configuration with your particular compiler setup.</p>
43	<p>Boost library users can request support for additional compilers or platforms
44	by visiting our <a href="http://sourceforge.net/tracker/?group_id=7586">Tracker</a>
45	and submitting a support request.
46	</p>
47	<h4>The <a href="../../boost/config.hpp"><boost/config.hpp></a> <a name="header">
48	header</a></h4>
49	<p>Boost library implementations access configuration macros via <code>#include
50	<boost/config.hpp></code>.
51	</p>
52	<P>While Boost library users are not required to include that file directly, or
53	use those configuration macros, such use is acceptable.  The configuration
54	macros are documented as to their purpose, usage, and limitations which makes
55	them usable by both Boost library and user code.
56	</P>
57	<P>Boost <A href="#info_macros">informational</A> or <A href="#helpers">helper</A>
58	macros are designed for use by Boost users as well as for our own internal
59	use.  Note however, that the <A href="#features">feature test</A> and <A href="#defects">
60	defect test</A> macros were designed for internal use by Boost libraries,
61	not user code, so they can change at any time (though no gratuitous changes are
62	made to them). Boost library problems resulting from changes to the
63	configuration macros are caught by the Boost regression tests, so the Boost
64	libraries are updated to account for those changes. By contrast, Boost library
65	user code can be adversely affected by changes to the macros without warning.
66	The best way to keep abreast of changes to the macros used in user code is to
67	monitor the discussions on the Boost developers list.</P>
68	<h4><a name="config_script">Using the configure script</a></h4>
69	<P><STRONG>Note</STRONG>: this configure script only sets up the Boost headers for
70	use with a particular compiler.  <STRONG><EM>It has no effect on Boost.Build, or
71	how the libraries are built</EM></STRONG>.</P>
72	<p>If you know that boost is incorrectly configured for your particular setup, and
73	you are on a UNIX like platform, then you may want to try and improve things by
74	running the boost configure script. From a shell command prompt you will need
75	to cd into <boost-root>/libs/config/ and type:</p>
76	<pre>sh ./configure</pre>
77	<p>you will see a list of the items being checked as the script works its way
78	through the regression tests. Note that the configure script only really
79	auto-detects your compiler if it's called g++, c++ or CC. If you are using some
80	other compiler you will need to set one or more of the following environment
81	variables:</p>
82	<table border="1" cellpadding="7" cellspacing="1" width="624">
83	<tr>
84	<td valign="top" width="50%"><p align="center"><b>Variable</b></p>
85	</td>
86	<td valign="top" width="50%"><p align="center"><b>Description</b></p>
87	</td>
88	</tr>
89	<tr>
90	<td valign="top" width="50%">CXX</td>
91	<td valign="top" width="50%">The name of the compiler, for example "c++".</td>
92	</tr>
93	<tr>
94	<td valign="top" width="50%">CXXFLAGS</td>
95	<td valign="top" width="50%">The compiler flags to use, for example "-O2".</td>
96	</tr>
97	<tr>
98	<td valign="top" width="50%">LDFLAGS</td>
99	<td valign="top" width="50%">The linker flags to use, for example "-L/mypath".</td>
100	</tr>
101	<tr>
102	<td valign="top" width="50%">LIBS</td>
103	<td valign="top" width="50%">Any libraries to link in, for example -lpthread.</td>
104	</tr>
105	</table>
106	<p>For example to run the configure script with HP aCC, you might use something
107	like:</p>
108	<pre>export CXX="aCC"
109	export CXXFLAGS="-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE -DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE"
110	export LDFLAGS="-DAportable"
111	export LIBS="-lpthread"
112	sh ./configure</pre>
113	<p>However you run the configure script, when it finishes you will find a new
114	header - user.hpp - located in the <boost-root/libs/config/> directory. <b><i>Note
115	that configure does not install this header into your boost include path by
116	default.</i></b> This header contains all the options generated by the
117	configure script, plus a header-section that contains the user settable options
118	from the default version of <a href="../../boost/config/user.hpp">user.hpp</a> (located
119	under <boost-root>/boost/config/). There are two ways you can use this
120	header:</p>
121	<p>Option 1: copy the header into <boost-root>/boost/config/ so that it
122	replaces the default <a href="../../boost/config/user.hpp">user.hpp</a> provided
123	by boost. This option allows only one configure-generated setup; boost
124	developers should avoid this option, as it incurs the danger of accidentally
125	committing a configure-modified user.hpp to the cvs repository (something you
126	will not be thanked for!).</p>
127	<p>Option 2: give the header a more memorable name, and place it somewhere
128	convenient; then, define the macro BOOST_USER_CONFIG to point to it. For
129	example create a new sub-directory <boost-root>/boost/config/user/, and
130	copy the header there; for example as "multithread-gcc-config.hpp". Then, when
131	compiling add the command line option:
132	-DBOOST_USER_CONFIG="<boost/config/user/multithread-gcc-config.hpp>", and
133	boost will use the new configuration header. This option allows you to generate
134	more than one configuration header, and to keep them separate from the boost
135	source - so that updates to the source do not interfere with your
136	configuration.</p>
137	<h4><a name="user_settable"></a>User settable options</h4>
138	<p>There are some configuration-options that represent user choices, rather than
139	compiler defects or platform specific options. These are listed in
140	<boost/config/user.hpp> and at the start of a configure-generated
141	user.hpp header. You can define these on the command line, or by editing
142	<boost/config/user.hpp>, they are listed in the following table: </p>
143	<table border="1" cellpadding="7" cellspacing="1" width="100%">
144	<tr>
145	<td valign="top" width="48%"><p align="center"><b>Macro</b></p>
146	</td>
147	<td valign="top" width="52%"><p align="center"><b>Description</b></p>
148	</td>
149	</tr>
150	<tr>
151	<td valign="top" width="48%">BOOST_USER_CONFIG</td>
152	<td valign="top" width="52%">When defined, it should point to the name of the user
153	configuration file to include prior to any boost configuration files. When not
154	defined, defaults to <<a href="../../boost/config/user.hpp">boost/config/user.hpp</a>>.</td>
155	</tr>
156	<tr>
157	<td valign="top" width="48%">BOOST_COMPILER_CONFIG</td>
158	<td valign="top" width="52%">When defined, it should point to the name of the
159	compiler configuration file to use. Defining this cuts out the compiler
160	selection logic, and eliminates the dependency on the header containing that
161	logic. For example if you are using gcc, then you could define
162	BOOST_COMPILER_CONFIG to "<a href="../../boost/config/compiler/gcc.hpp">boost/config/compiler/gcc.hpp</a>".</td>
163	</tr>
164	<tr>
165	<td valign="top" width="48%">BOOST_STDLIB_CONFIG</td>
166	<td valign="top" width="52%">When defined, it should point to the name of the
167	standard library configuration file to use. Defining this cuts out the standard
168	library selection logic, and eliminates the dependency on the header containing
169	that logic. For example if you are using STLport, then you could define
170	BOOST_STDLIB_CONFIG to "<a href="../../boost/config/stdlib/stlport.hpp">boost/config/stdlib/stlport.hpp</a>".</td>
171	</tr>
172	<tr>
173	<td valign="top" width="48%">BOOST_PLATFORM_CONFIG</td>
174	<td valign="top" width="52%">When defined, it should point to the name of the
175	platform configuration file to use. Defining this cuts out the platform
176	selection logic, and eliminates the dependency on the header containing that
177	logic. For example if you are compiling on linux, then you could define
178	BOOST_PLATFORM_CONFIG to "<a href="../../boost/config/platform/linux.hpp">boost/config/platform/linux.hpp</a>".</td>
179	</tr>
180	<tr>
181	<td valign="top" width="48%">BOOST_NO_COMPILER_CONFIG</td>
182	<td valign="top" width="52%">When defined, no compiler configuration file is
183	selected or included, define when the compiler is fully conformant with the
184	standard, or where the user header (see BOOST_USER_CONFIG), has had any options
185	necessary added to it, for example by an autoconf generated configure script.</td>
186	</tr>
187	<tr>
188	<td valign="top" width="48%">BOOST_NO_STDLIB_CONFIG</td>
189	<td valign="top" width="52%">When defined, no standard library configuration file
190	is selected or included, define when the standard library is fully conformant
191	with the standard, or where the user header (see BOOST_USER_CONFIG), has had
192	any options necessary added to it, for example by an autoconf generated
193	configure script.</td>
194	</tr>
195	<tr>
196	<td valign="top" width="48%">BOOST_NO_PLATFORM_CONFIG</td>
197	<td valign="top" width="52%">When defined, no platform configuration file is
198	selected or included, define when the platform is fully conformant with the
199	standard (and has no useful extra features), or where the user header (see
200	BOOST_USER_CONFIG), has had any options necessary added to it, for example by
201	an autoconf generated configure script.</td>
202	</tr>
203	<tr>
204	<td valign="top" width="48%">BOOST_NO_CONFIG</td>
205	<td valign="top" width="52%">Equivalent to defining all of
206	BOOST_NO_COMPILER_CONFIG, BOOST_NO_STDLIB_CONFIG and BOOST_NO_PLATFORM_CONFIG.</td>
207	</tr>
208	<tr>
209	<td valign="top">BOOST_STRICT_CONFIG</td>
210	<td>The normal behavior for compiler versions that are newer than the last known
211	version, is to assume that they have all the same defects as the last known
212	version. By setting this define, then compiler versions that are newer than the
213	last known version are assumed to be fully conforming with the standard. This
214	is probably most useful for boost developers or testers, and for those who want
215	to use boost to test beta compiler versions.</td>
216	</tr>
217	<tr>
218	<td valign="top">BOOST_ASSERT_CONFIG</td>
219	<td>When this flag is set, if the config finds anything unknown, then it will stop
220	with a #error rather than continue. Boost regression testers should set this
221	define, as should anyone who wants to quickly check whether boost is supported
222	on their platform.</td>
223	</tr>
224	<tr>
225	<td valign="top" width="48%">BOOST_DISABLE_THREADS</td>
226	<td valign="top" width="52%">When defined, disables threading support, even if the
227	compiler in its current translation mode supports multiple threads.</td>
228	</tr>
229	<tr>
230	<td valign="top">BOOST_DISABLE_WIN32</td>
231	<td>When defined, disables the use of Win32 specific API's, even when these are
232	available. Also has the effect of setting BOOST_DISABLE_THREADS unless
233	BOOST_HAS_PTHREADS is set. This option may be set automatically by the config
234	system when it detects that the compiler is in "strict mode".</td>
235	</tr>
236	<TR>
237	<TD vAlign="top">BOOST_DISABLE_ABI_HEADERS</TD>
238	<TD>Stops boost headers from including any prefix/suffix headers that normally
239	control things like struct packing and alignment.</TD>
240	</TR>
241	<TR>
242	<TD vAlign="top">BOOST_ABI_PREFIX</TD>
243	<TD>A prefix header to include in place of whatever boost.config would normally
244	select, any replacement should set up struct packing and alignment options as
245	required.</TD>
246	</TR>
247	<TR>
248	<TD vAlign="top">BOOST_ABI_SUFFIX</TD>
249	<TD>A suffix header to include in place of whatever boost.config would normally
250	select, any replacement should undo the effects of the prefix header.</TD>
251	</TR>
252	<TR>
253	<TD vAlign="top">BOOST_ALL_DYN_LINK</TD>
254	<TD>
255	<P>Forces all libraries that have separate source, to be linked as dll's rather
256	than static libraries on Microsoft Windows (this macro is used to turn on
257	__declspec(dllimport) modifiers, so that the compiler knows which symbols to
258	look for in a dll rather than in a static library).
259	</P>
260	<P>Note that there may be some libraries that can only be statically linked
261	(Boost.Test for example) and others which may only be dynamically linked
262	(Boost.Threads for example), in these cases this macro has no effect.</P>
263	</TD>
264	</TR>
265	<TR>
266	<TD vAlign="top">BOOST_WHATEVER_DYN_LINK</TD>
267	<TD>
268	<P>Forces library "whatever" to be linked as a dll rather than a static library on
269	Microsoft Windows: replace the WHATEVER part of the macro name with the name of
270	the library that you want to dynamically link to, for example use
271	BOOST_DATE_TIME_DYN_LINK or BOOST_REGEX_DYN_LINK etc (this macro is used
272	to turn on __declspec(dllimport) modifiers, so that the compiler knows which
273	symbols to look for in a dll rather than in a static library).
274	</P>
275	<P>Note that there may be some libraries that can only be statically linked
276	(Boost.Test for example) and others which may only be dynamically linked
277	(Boost.Threads for example), in these cases this macro is unsupported.</P>
278	</TD>
279	</TR>
280	<TR>
281	<TD vAlign="top">BOOST_ALL_NO_LIB</TD>
282	<TD>
283	<P>Tells the config system not to automatically select which libraries to link
284	against.
285	</P>
286	<P>Normally if a compiler supports #pragma lib, then the correct library build
287	variant will be automatically selected and linked against, simply by the act of
288	including one of that library's headers.  This macro turns that feature
289	off.</P>
290	</TD>
291	</TR>
292	<TR>
293	<TD vAlign="top">BOOST_WHATEVER_NO_LIB</TD>
294	<TD>
295	<P>Tells the config system not to automatically select which library to link
296	against for library "whatever", replace WHATEVER in the macro name with the
297	name of the library; for example BOOST_DATE_TIME_NO_LIB or
298	BOOST_REGEX_NO_LIB.
299	</P>
300	<P>Normally if a compiler supports #pragma lib, then the correct library build
301	variant will be automatically selected and linked against, simply by the act of
302	including one of that library's headers.  This macro turns that feature
303	off.</P>
304	</TD>
305	</TR>
306	<TR>
307	<TD vAlign="top">BOOST_LIB_DIAGNOSTIC</TD>
308	<TD>Causes the auto-linking code to output diagnostic messages indicating the name
309	of the library that is selected for linking.</TD>
310	</TR>
311	<TR>
312	<TD vAlign="top">BOOST_LIB_TOOLSET</TD>
313	<TD>Overrides the name of the toolset part of the name of library being linked to;
314	note if defined this must be defined to a quoted string literal, for example
315	"abc".</TD>
316	</TR>
317	</table>
318	<h4><a name="advanced_config"></a>Advanced configuration usage</h4>
319	<p>By setting various macros on the compiler command line or by editing <<a href="../../boost/config/user.hpp">boost/config/user.hpp</a>>,
320	the boost configuration setup can be optimised in a variety of ways.
321	</p>
322	<p>Boost's configuration is structured so that the user-configuration is included
323	first (defaulting to <<a href="../../boost/config/user.hpp">boost/config/user.hpp</a>>
324	if BOOST_USER_CONFIG is not defined). This sets up any user-defined policies,
325	and gives the user-configuration a chance to influence what happens next.
326	</p>
327	<p>Next the compiler, standard library, and platform configuration files are
328	included. These are included via macros (BOOST_COMPILER_CONFIG etc, <a href="#user_settable">
329	see user settable macros</a>), and if the corresponding macro is undefined
330	then a separate header that detects which compiler/standard library/platform is
331	in use is included in order to set these. The config can be told to ignore
332	these headers altogether if the corresponding BOOST_NO_XXX macro is set (for
333	example BOOST_NO_COMPILER_CONFIG to disable including any compiler
334	configuration file - <a href="#user_settable">see user settable macros</a>).
335	</p>
336	<p>Finally the boost configuration header, includes <<a href="../../boost/config/suffix.hpp">boost/config/suffix.hpp</a>>;
337	this header contains any boiler plate configuration code - for example where
338	one boost macro being set implies that another must be set also.</p>
339	<p>The following usage examples represent just a few of the possibilities:</p>
340	<p><u>Example 1, creating our own frozen configuration.</u></p>
341	<p>Lets suppose that we're building boost with Visual C++ 6, and STLport 4.0. Lets
342	suppose also that we don't intend to update our compiler or standard library
343	any time soon. In order to avoid breaking dependencies when we update boost, we
344	may want to "freeze" our configuration headers, so that we only have to rebuild
345	our project if the boost code itself has changed, and not because the boost
346	config has been updated for more recent versions of Visual C++ or STLport.
347	We'll start by realising that the configuration files in use are: <<a href="../../boost/config/compiler/visualc.hpp">boost/config/compiler/visualc.hpp</a>>
348	for the compiler, <<a href="../../boost/config/stdlib/stlport.hpp">boost/config/stdlib/stlport.hpp</a>>
349	for the standard library, and <<a href="../../boost/config/platform/win32.hpp">boost/config/platform/win32.hpp</a>>
350	for the platform. Next we'll create our own private configuration directory:
351	boost/config/mysetup/, and copy the configuration files into there. Finally,
352	open up <<a href="../../boost/config/user.hpp">boost/config/user.hpp</a>>
353	and edit the following defines:</p>
354	<pre>#define BOOST_COMPILER_CONFIG "boost/config/mysetup/visualc.hpp"
355	#define BOOST_STDLIB_CONFIG "boost/config/mysetup/stlport.hpp"
356	#define BOOST_USER_CONFIG "boost/config/mysetup/win32.hpp"</pre>
357	<p>Now when you use boost, its configuration header will go straight to our
358	"frozen" versions, and ignore the default versions, you will now be insulated
359	from any configuration changes when you update boost. This technique is also
360	useful if you want to modify some of the boost configuration files; for example
361	if you are working with a beta compiler release not yet supported by boost.</p>
362	<p><u>Example 2: skipping files that you don't need.</u></p>
363	<p>Lets suppose that you're using boost with a compiler that is fully conformant
364	with the standard; you're not interested in the fact that older versions of
365	your compiler may have had bugs, because you know that your current version
366	does not need any configuration macros setting. In a case like this, you can
367	define BOOST_NO_COMPILER_CONFIG either on the command line, or in
368	<boost/config/user.hpp>, and miss out the compiler configuration header
369	altogether (actually you miss out two headers, one which works out what the
370	compiler is, and one that configures boost for it). This has two consequences:
371	the first is that less code has to be compiled, and the second that you have
372	removed a dependency on two boost headers.</p>
373	<p><u>Example 3: using configure script to freeze the boost configuration.</u></p>
374	<p>If you are working on a unix-like platform then you can use the configure
375	script to generate a "frozen" configuration based on your current compiler
376	setup - <a href="#config_script">see using the configure script</a> for more
377	details.</p>
378	<h4><a name="testing"></a>Testing the boost configuration</h4>
379	<p>The boost configuration library provides a full set of regression test programs
380	under the <boost-root>/libs/config/test/ sub-directory:</p>
381	<table border="1" cellpadding="7" cellspacing="1" width="100%">
382	<tr>
383	<td valign="top" width="50%"><p align="center"><b>File</b></p>
384	</td>
385	<td valign="top" width="50%"><p align="center"><b>Description</b></p>
386	</td>
387	</tr>
388	<tr>
389	<td valign="top" width="50%">config_info.cpp</td>
390	<td valign="top" width="50%">Prints out a detailed description of your
391	compiler/standard library/platform setup, plus your current boost
392	configuration. The information provided by this program useful in setting up
393	the boost configuration files. If you report that boost is incorrectly
394	configured for your compiler/library/platform then please include the output
395	from this program when reporting the changes required.</td>
396	</tr>
397	<tr>
398	<td valign="top" width="50%">config_test.cpp</td>
399	<td valign="top" width="50%">A monolithic test program that includes most of the
400	individual test cases. This provides a quick check to see if boost is correctly
401	configured for your compiler/library/platform.</td>
402	</tr>
403	<tr>
404	<td valign="top" width="50%">limits_test.cpp</td>
405	<td valign="top" width="50%">Tests your standard library's std::numeric_limits
406	implementation (or its boost provided replacement if BOOST_NO_LIMITS is
407	defined). This test file fails with most versions of numeric_limits, mainly due
408	to the way that some compilers treat NAN's and infinity.</td>
409	</tr>
410	<tr>
411	<td valign="top" width="50%">no_*pass.cpp</td>
412	<td valign="top" width="50%">Individual compiler defect test files. Each of these
413	should compile, if one does not then the corresponding BOOST_NO_XXX macro needs
414	to be defined - see each test file for specific details.</td>
415	</tr>
416	<tr>
417	<td valign="top" width="50%">no_*fail.cpp</td>
418	<td valign="top" width="50%">Individual compiler defect test files. Each of these
419	should <i>not</i> compile, if one does then the corresponding BOOST_NO_XXX
420	macro is defined when it need not be - see each test file for specific details.</td>
421	</tr>
422	<tr>
423	<td valign="top" width="50%">has_*pass.cpp</td>
424	<td valign="top" width="50%">Individual feature test files. If one of these does <i>not</i>
425	compile then the corresponding BOOST_HAS_XXX macro is defined when it should
426	not be - see each test file for specific details.</td>
427	</tr>
428	<tr>
429	<td valign="top" width="50%">has_*fail.cpp</td>
430	<td valign="top" width="50%">Individual feature test files. If one of these does
431	compile then the corresponding BOOST_HAS_XXX macro can be safely defined - see
432	each test file for specific details.</td>
433	</tr>
434	</table>
435	<p>Although you can run the configuration regression tests as individual test
436	files, there are rather a lot of them, so there are a couple of shortcuts to
437	help you out:</p>
438	<p>If you have built the <a href="../../more/regression.html">boost regression test
439	driver</a>, then you can use this to produce a nice html formatted report of
440	the results using the supplied test file.</p>
441	<p>Alternatively you can run the configure script like this:</p>
442	<pre>./configure --enable-test</pre>
443	<p>in which case the script will test the current configuration rather than
444	creating a new one from scratch.</p>
445	<p>If you are reporting the results of these tests for a new
446	platform/library/compiler then please include a log of the full compiler
447	output, the output from config_info.cpp, and the pass/fail test results.</p>
448	<h2><a name="macro_ref"></a>Boost Macro Reference</h2>
449	<h4><a name="defects"></a>Macros that describe defects:</h4>
450	<p>The following macros all describe features that are required by the C++
451	standard, if one of the following macros is defined, then it represents a
452	defect in the compiler's conformance with the standard.</p>
453	<table border="1" cellpadding="7" cellspacing="1" width="100%">
454	<tr>
455	<td valign="top" width="51%"><p align="center"><b>Macro</b></p>
456	</td>
457	<td valign="top" width="16%"><p align="center"><b>Section</b></p>
458	</td>
459	<td valign="top" width="33%"><p align="center"><b>Description</b></p>
460	</td>
461	</tr>
462	<tr>
463	<td>BOOST_BCB_PARTIAL_SPECIALIZATION_BUG</td>
464	<td>Compiler</td>
465	<td>The compiler exibits certain partial specialisation bug - probably Borland C++
466	Builder specific.</td>
467	</tr>
468	<TR>
469	<TD vAlign="top" width="51%">BOOST_FUNCTION_SCOPE_USING_DECLARATION_BREAKS_ADL</TD>
470	<TD vAlign="top" width="16%">Compiler</TD>
471	<TD vAlign="top" width="33%">Argument dependent lookup fails if there is a using
472	declaration for the symbol being looked up in the current scope.  For
473	example, <code>using boost::get_pointer;</code> prevents ADL from finding
474	overloads of <code>get_pointer</code> in namespaces nested inside boost (but
475	not elsewhere).  Probably Borland specific.</TD>
476	</TR>
477	<tr>
478	<td valign="top" width="51%">BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP</td>
479	<td valign="top" width="16%">Compiler</td>
480	<td valign="top" width="33%">Compiler does not implement argument-dependent lookup
481	(also named Koenig lookup); see std::3.4.2 [basic.koenig.lookup]</td>
482	</tr>
483	<tr>
484	<td valign="top" width="51%">BOOST_NO_AUTO_PTR</td>
485	<td valign="top" width="16%">Standard library</td>
486	<td valign="top" width="33%">If the compiler / library supplies non-standard or
487	broken std::auto_ptr.</td>
488	</tr>
489	<tr>
490	<td valign="top" width="51%">BOOST_NO_CTYPE_FUNCTIONS</td>
491	<td valign="top" width="16%">Platform</td>
492	<td valign="top" width="33%">The Platform does not provide functions for the
493	character-classifying operations <ctype.h> and <cctype>, only
494	macros.</td>
495	</tr>
496	<tr>
497	<td valign="top" width="51%">BOOST_NO_CV_SPECIALIZATIONS</td>
498	<td valign="top" width="16%">Compiler</td>
499	<td valign="top" width="33%">If template specialisations for cv-qualified types
500	conflict with a specialisation for a cv-unqualififed type.</td>
501	</tr>
502	<tr>
503	<td valign="top" width="51%">BOOST_NO_CV_VOID_SPECIALIZATIONS</td>
504	<td valign="top" width="16%">Compiler</td>
505	<td valign="top" width="33%">If template specialisations for cv-void types
506	conflict with a specialisation for void.</td>
507	</tr>
508	<tr>
509	<td valign="top" width="51%">BOOST_NO_CWCHAR</td>
510	<td valign="top" width="16%">Platform</td>
511	<td valign="top" width="33%">The Platform does not provide <wchar.h> and
512	<cwchar>.</td>
513	</tr>
514	<tr>
515	<td valign="top" width="51%">BOOST_NO_CWCTYPE</td>
516	<td valign="top" width="16%">Platform</td>
517	<td valign="top" width="33%">The Platform does not provide <wctype.h> and
518	<cwctype>.</td>
519	</tr>
520	<tr>
521	<td valign="top" width="51%">BOOST_NO_DEPENDENT_NESTED_DERIVATIONS</td>
522	<td valign="top" width="16%">Compiler</td>
523	<td valign="top" width="33%">The compiler fails to compile a nested class that has
524	a dependent base class:<pre>template<typename T>
525	struct foo : {
526	template<typename U>
527	struct bar : public U {};
528	};</pre>
529	</td>
530	</tr>
531	<tr>
532	<td valign="top" width="51%">BOOST_NO_DEPENDENT_TYPES_IN_TEMPLATE_VALUE_PARAMETERS</td>
533	<td valign="top" width="16%">Compiler</td>
534	<td valign="top" width="33%">Template value parameters cannot have a dependent
535	type, for example:<pre>template<class T, typename T::type value>
536	class X { ... };</pre>
537	</td>
538	</tr>
539	<tr>
540	<td valign="top">BOOST_NO_EXCEPTION_STD_NAMESPACE</td>
541	<td valign="top">Standard Library</td>
542	<td>The standard library does not put some or all of the contents of
543	<exception> in namespace std.</td>
544	</tr>
545	<tr>
546	<td valign="top">BOOST_NO_EXCEPTIONS</td>
547	<td valign="top">Compiler</td>
548	<td>The compiler does not support exception handling (this setting is typically
549	required by many C++ compilers for embedded platforms). Note that there is no
550	requirement for boost libraries to honor this configuration setting - indeed
551	doing so may be impossible in some cases. Those libraries that do honor this
552	will typically abort if a critical error occurs - you have been warned!</td>
553	</tr>
554	<tr>
555	<td valign="top" width="51%">BOOST_NO_EXPLICIT_FUNCTION_TEMPLATE_ARGUMENTS</td>
556	<td valign="top" width="16%">Compiler</td>
557	<td valign="top" width="33%">Can only use deduced template arguments when calling
558	function template instantiations.</td>
559	</tr>
560	<tr>
561	<td valign="top" width="51%">BOOST_NO_FUNCTION_TEMPLATE_ORDERING</td>
562	<td valign="top" width="16%">Compiler</td>
563	<td valign="top" width="33%">The compiler does not perform function template
564	ordering or its function template ordering is incorrect.
565	<pre>template<typename T> void f(T); // #1
566	template<typename T, typename U> void f(T (*)(U)); // #2
567
568	void bar(int);
569
570	f(&bar); // should choose #2.</pre>
571	</td>
572	</tr>
573	<tr>
574	<td valign="top" width="51%">BOOST_NO_INCLASS_MEMBER_INITIALIZATION</td>
575	<td valign="top" width="16%">Compiler</td>
576	<td valign="top" width="33%">Compiler violates std::9.4.2/4.</td>
577	</tr>
578	<tr>
579	<td valign="top" width="51%">BOOST_NO_INTRINSIC_WCHAR_T</td>
580	<td valign="top" width="16%">Compiler</td>
581	<td valign="top" width="33%">The C++ implementation does not provide wchar_t, or
582	it is really a synonym for another integral type. Use this symbol to decide
583	whether it is appropriate to explicitly specialize a template on wchar_t if
584	there is already a specialization for other integer types.</td>
585	</tr>
586	<TR>
587	<TD vAlign="top" width="51%">BOOST_NO_IS_ABSTRACT</TD>
588	<TD vAlign="top" width="16%">Compiler</TD>
589	<TD vAlign="top" width="33%">The C++ compiler does not support SFINAE with
590	abstract types, this is covered by <A href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#337">
591	Core Language DR337</A>, but is not part of the current standard.
592	Fortunately most compilers that support SFINAE also support this DR.</TD>
593	</TR>
594	<tr>
595	<td valign="top" width="51%">BOOST_NO_LIMITS</td>
596	<td valign="top" width="16%">Standard library</td>
597	<td valign="top" width="33%">The C++ implementation does not provide the
598	<limits> header. Never check for this symbol in library code; always
599	include <boost/limits.hpp>, which guarantees to provide <code>std::numeric_limits</code>.</td>
600	</tr>
601	<tr>
602	<td valign="top" width="51%">BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS</td>
603	<td valign="top" width="16%">Standard library</td>
604	<td valign="top" width="33%">Constants such as numeric_limits<T>::is_signed
605	are not available for use at compile-time.</td>
606	</tr>
607	<tr>
608	<td>BOOST_NO_LONG_LONG_NUMERIC_LIMITS</td>
609	<td>Standard library</td>
610	<td>There is no specialization for numeric_limits<long long> and
611	numeric_limits<unsigned long long>. <boost/limits.hpp> will then
612	add these specializations as a standard library "fix" only if the compiler
613	supports the long long datatype.</td>
614	</tr>
615	<tr>
616	<td>BOOST_NO_MEMBER_FUNCTION_SPECIALIZATIONS</td>
617	<td>Compiler</td>
618	<td>The compiler does not support the specialization of individual member
619	functions of template classes.</td>
620	</tr>
621	<tr>
622	<td valign="top" width="51%">BOOST_NO_MEMBER_TEMPLATE_KEYWORD</td>
623	<td valign="top" width="16%">Compiler</td>
624	<td valign="top" width="33%">If the compiler supports member templates, but not
625	the template keyword when accessing member template classes.</td>
626	</tr>
627	<tr>
628	<td valign="top" width="51%">BOOST_NO_MEMBER_TEMPLATE_FRIENDS</td>
629	<td valign="top" width="16%">Compiler</td>
630	<td valign="top" width="33%">Member template friend syntax ("template<class
631	P> friend class frd;") described in the C++ Standard, 14.5.3, not supported.</td>
632	</tr>
633	<tr>
634	<td valign="top" width="51%">BOOST_NO_MEMBER_TEMPLATES</td>
635	<td valign="top" width="16%">Compiler</td>
636	<td valign="top" width="33%">Member template functions not fully supported.</td>
637	</tr>
638	<tr>
639	<td>BOOST_NO_MS_INT64_NUMERIC_LIMITS</td>
640	<td>Standard library</td>
641	<td>There is no specialization for numeric_limits<__int64> and
642	numeric_limits<unsigned __int64>. <boost/limits.hpp> will then add
643	these specializations as a standard library "fix", only if the compiler
644	supports the __int64 datatype.</td>
645	</tr>
646	<tr>
647	<td valign="top" width="51%">BOOST_NO_OPERATORS_IN_NAMESPACE</td>
648	<td valign="top" width="16%">Compiler</td>
649	<td valign="top" width="33%">Compiler requires inherited operator friend functions
650	to be defined at namespace scope, then using'ed to boost. Probably GCC
651	specific. See <a href="../../boost/operators.hpp">boost/operators.hpp</a> for
652	example.</td>
653	</tr>
654	<tr>
655	<td valign="top" width="51%">BOOST_NO_POINTER_TO_MEMBER_CONST</td>
656	<td valign="top" width="16%">Compiler</td>
657	<td valign="top" width="33%">The compiler does not correctly handle pointers to
658	const member functions, preventing use of these in overloaded function
659	templates. See <a href="../../boost/functional.hpp">boost/functional.hpp</a> for
660	example.</td>
661	</tr>
662	<TR>
663	<TD vAlign="top" width="51%">BOOST_NO_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS</TD>
664	<TD vAlign="top" width="16%">Compiler</TD>
665	<TD vAlign="top" width="33%">Pointers to members don't work when used as template
666	parameters.</TD>
667	</TR>
668	<tr>
669	<td valign="top" width="51%">BOOST_NO_PRIVATE_IN_AGGREGATE</td>
670	<td valign="top" width="16%">Compiler</td>
671	<td valign="top" width="33%">The compiler misreads 8.5.1, treating classes as
672	non-aggregate if they contain private or protected member functions.</td>
673	</tr>
674	<TR>
675	<TD vAlign="top" width="51%">BOOST_NO_SFINAE</TD>
676	<TD vAlign="top" width="16%">Compiler</TD>
677	<TD vAlign="top" width="33%">The compiler does not support the "Substitution
678	Failure Is Not An Error" meta-programming idiom.</TD>
679	</TR>
680	<tr>
681	<td valign="top" width="51%">BOOST_NO_STD_ALLOCATOR</td>
682	<td valign="top" width="16%">Standard library</td>
683	<td valign="top" width="33%">The C++ standard library does not provide a standards
684	conforming std::allocator.</td>
685	</tr>
686	<tr>
687	<td valign="top" width="51%">BOOST_NO_STD_DISTANCE</td>
688	<td valign="top" width="16%">Standard library</td>
689	<td valign="top" width="33%">The platform does not have a conforming version of
690	std::distance.</td>
691	</tr>
692	<tr>
693	<td valign="top" width="51%">BOOST_NO_STD_ITERATOR</td>
694	<td valign="top" width="16%">Standard library</td>
695	<td valign="top" width="33%">The C++ implementation fails to provide the
696	std::iterator class.</td>
697	</tr>
698	<tr>
699	<td valign="top" width="51%">BOOST_NO_STD_ITERATOR_TRAITS</td>
700	<td valign="top" width="16%">Standard library</td>
701	<td valign="top" width="33%">The compiler does not provide a standard compliant
702	implementation of std::iterator_traits. Note that the compiler may still have a
703	non-standard implementation.</td>
704	</tr>
705	<tr>
706	<td valign="top" width="51%">BOOST_NO_STD_LOCALE</td>
707	<td valign="top" width="16%">Standard library</td>
708	<td valign="top" width="33%">The standard library lacks std::locale.</td>
709	</tr>
710	<tr>
711	<td valign="top" width="51%">BOOST_NO_STD_MESSAGES</td>
712	<td valign="top" width="16%">Standard library</td>
713	<td valign="top" width="33%">The standard library lacks a conforming std::messages
714	facet.</td>
715	</tr>
716	<tr>
717	<td valign="top" width="51%">BOOST_NO_STD_MIN_MAX</td>
718	<td valign="top" width="16%">Standard library</td>
719	<td valign="top" width="33%">The C++ standard library does not provide the min()
720	and max() template functions that should be in <algorithm>.</td>
721	</tr>
722	<tr>
723	<td valign="top">BOOST_NO_STD_OUTPUT_ITERATOR_ASSIGN</td>
724	<td valign="top">Standard library</td>
725	<td valign="top">Defined if the standard library's output iterators are not
726	assignable.</td>
727	</tr>
728	<tr>
729	<td valign="top" width="51%">BOOST_NO_STD_USE_FACET</td>
730	<td valign="top" width="16%">Standard library</td>
731	<td valign="top" width="33%">The standard library lacks a conforming
732	std::use_facet.</td>
733	</tr>
734	<tr>
735	<td>BOOST_NO_STD_WSTREAMBUF</td>
736	<td>Standard library</td>
737	<td>The standard library's implementation of std::basic_streambuf<wchar_t>
738	is either missing, incomplete, or buggy.</td>
739	</tr>
740	<tr>
741	<td valign="top" width="51%">BOOST_NO_STD_WSTRING</td>
742	<td valign="top" width="16%">Standard library</td>
743	<td valign="top" width="33%">The standard library lacks std::wstring.</td>
744	</tr>
745	<tr>
746	<td valign="top" width="51%">BOOST_NO_STDC_NAMESPACE</td>
747	<td valign="top" width="16%">Compiler/Platform</td>
748	<td valign="top" width="33%">The contents of C++ standard headers for C library
749	functions (the <c...> headers) have not been placed in namespace std.
750	This test is difficult - some libraries "fake" the std C functions by adding
751	using declarations to import them into namespace std, unfortunately they don't
752	necessarily catch all of them...</td>
753	</tr>
754	<tr>
755	<td valign="top" width="51%">BOOST_NO_STRINGSTREAM</td>
756	<td valign="top" width="16%">Standard library</td>
757	<td valign="top" width="33%">The C++ implementation does not provide the
758	<sstream> header.</td>
759	</tr>
760	<tr>
761	<td valign="top" width="51%">BOOST_NO_SWPRINTF</td>
762	<td valign="top" width="16%">Platform</td>
763	<td valign="top" width="33%">The platform does not have a conforming version of
764	swprintf.</td>
765	</tr>
766	<tr>
767	<td valign="top" width="51%">BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION</td>
768	<td valign="top" width="16%">Compiler</td>
769	<td valign="top" width="33%">Class template partial specialization (14.5.4
770	[temp.class.spec]) not supported.</td>
771	</tr>
772	<tr>
773	<td valign="top" width="51%">BOOST_NO_TEMPLATED_ITERATOR_CONSTRUCTORS</td>
774	<td valign="top" width="16%">Standard library</td>
775	<td valign="top" width="33%">The standard library does not provide templated
776	iterator constructors for its containers.</td>
777	</tr>
778	<tr>
779	<td>BOOST_NO_TEMPLATE_TEMPLATES</td>
780	<td>Compiler</td>
781	<td>The compiler does not support template template parameters.</td>
782	</tr>
783	<tr>
784	<td>BOOST_NO_UNREACHABLE_RETURN_DETECTION</td>
785	<td>Compiler</td>
786	<td>If a return is unreachable, then no return statement should be required,
787	however some compilers insist on it, while other issue a bunch of warnings if
788	it is in fact present.</td>
789	</tr>
790	<TR>
791	<TD vAlign="top" width="51%">BOOST_NO_USING_DECLARATION_OVERLOADS_FROM_TYPENAME_BASE</TD>
792	<TD vAlign="top" width="16%">Compiler</TD>
793	<TD vAlign="top" width="33%">The compiler will not accept a using
794	declaration that brings a function from a typename used as a base
795	class into a derived class if functions of the same name are present
796	in the derived class.</TD>
797	</TR>
798	<tr>
799	<td valign="top" width="51%">BOOST_NO_USING_TEMPLATE</td>
800	<td valign="top" width="16%">Compiler</td>
801	<td valign="top" width="33%">The compiler will not accept a using declaration that
802	imports a template class or function from another namespace. Originally a
803	Borland specific problem with imports to/from the global namespace, extended to
804	MSVC6 which has a specific issue with importing template classes (but not
805	functions).</td>
806	</tr>
807	<tr>
808	<td valign="top" width="51%">BOOST_NO_VOID_RETURNS</td>
809	<td valign="top" width="16%">Compiler</td>
810	<td valign="top" width="33%">The compiler does not allow a void function to return
811	the result of calling another void function.
812	<pre>void f() {}
813	void g() { return f(); }</pre>
814	</td>
815	</tr>
816	</table>
817	<h4><a name="features"></a>Macros that describe optional features:</h4>
818	<p>The following macros describe features that are not required by the C++
819	standard. The macro is only defined if the feature is present.</p>
820	<table border="1" cellpadding="7" cellspacing="1" width="100%">
821	<tr>
822	<td valign="top" width="48%"><p align="center"><b>Macro</b></p>
823	</td>
824	<td valign="top" width="15%"><p align="center"><b>Section</b></p>
825	</td>
826	<td valign="top" width="37%"><p align="center"><b>Description</b></p>
827	</td>
828	</tr>
829	<tr>
830	<td valign="top" width="48%">BOOST_HAS_BETHREADS</td>
831	<td valign="top" width="15%">Platform</td>
832	<td valign="top" width="37%">The platform supports BeOS style threads.</td>
833	</tr>
834	<tr>
835	<td>BOOST_HAS_CLOCK_GETTIME</td>
836	<td>Platform</td>
837	<td>The platform has the POSIX API clock_gettime.</td>
838	</tr>
839	<TR>
840	<TD>BOOST_HAS_DECLSPEC
841	</TD>
842	<TD>Compiler</TD>
843	<TD>The compiler uses __declspec(dllexport) and __declspec(dllimport) to
844	export/import symbols from dll's.</TD>
845	</TR>
846	<tr>
847	<td>BOOST_HAS_DIRENT_H</td>
848	<td>Platform</td>
849	<td>The platform has the POSIX header <dirent.h>.</td>
850	</tr>
851	<TR>
852	<TD>BOOST_HAS_EXPM1</TD>
853	<TD>Platform</TD>
854	<TD>The platform has the functions expm1 expm1f and expm1l in <math.h></TD>
855	</TR>
856	<tr>
857	<td>BOOST_HAS_FTIME</td>
858	<td>Platform</td>
859	<td>The platform has the Win32 API GetSystemTimeAsFileTime.</td>
860	</tr>
861	<tr>
862	<td>BOOST_HAS_GETTIMEOFDAY</td>
863	<td>Platform</td>
864	<td>The platform has the POSIX API gettimeofday.</td>
865	</tr>
866	<tr>
867	<td valign="top" width="48%">BOOST_HAS_HASH</td>
868	<td valign="top" width="15%">Standard library</td>
869	<td valign="top" width="37%">The C++ implementation provides the (SGI) hash_set
870	and hash_map classes. When defined, BOOST_HASH_SET_HEADER and
871	BOOST_HASH_LIST_HEADER will contain the names of the header needed to access
872	hash_set and hash_map; BOOST_STD_EXTENSION_NAMESPACE will provide the namespace
873	in which the two class templates reside.</td>
874	</tr>
875	<TR>
876	<TD vAlign="top" width="48%">BOOST_HAS_LOG1P</TD>
877	<TD vAlign="top" width="15%">Platform</TD>
878	<TD vAlign="top" width="37%">The platform has the functions log1p, log1pf and
879	log1pl in <math.h>.</TD>
880	</TR>
881	<tr>
882	<td>BOOST_HAS_LONG_LONG</td>
883	<td>Compiler</td>
884	<td>The compiler supports the long long data type.</td>
885	</tr>
886	<tr>
887	<td valign="top" width="48%">BOOST_HAS_MACRO_USE_FACET</td>
888	<td valign="top" width="15%">Standard library</td>
889	<td valign="top" width="37%">The standard library lacks a conforming
890	std::use_facet, but has a macro _USE(loc, Type) that does the job. This is
891	primarily for the Dinkumware std lib.</td>
892	</tr>
893	<tr>
894	<td>BOOST_HAS_MS_INT64</td>
895	<td>Compiler</td>
896	<td>The compiler supports the __int64 data type.</td>
897	</tr>
898	<tr>
899	<td>BOOST_HAS_NANOSLEEP</td>
900	<td>Platform</td>
901	<td>The platform has the POSIX API nanosleep.</td>
902	</tr>
903	<tr>
904	<td valign="top" width="48%">BOOST_HAS_NL_TYPES_H</td>
905	<td valign="top" width="15%">Platform</td>
906	<td valign="top" width="37%">The platform has an <nl_types.h>.</td>
907	</tr>
908	<tr>
909	<td>BOOST_HAS_NRVO</td>
910	<td>Compiler</td>
911	<td>Indicated that the compiler supports the named return value optimization
912	(NRVO). Used to select the most efficient implementation for some function. See <a href="../../boost/operators.hpp">
913	boost/operators.hpp</a> for example.</td>
914	</tr>
915	<tr>
916	<td valign="top">BOOST_HAS_PARTIAL_STD_ALLOCATOR</td>
917	<td>Standard Library</td>
918	<td>The standard library has a partially conforming std::allocator class, but
919	without any of the member templates.</td>
920	</tr>
921	<tr>
922	<td>BOOST_HAS_PTHREAD_DELAY_NP</td>
923	<td>Platform</td>
924	<td>The platform has the POSIX API pthread_delay_np.</td>
925	</tr>
926	<tr>
927	<td>BOOST_HAS_PTHREAD_MUTEXATTR_SETTYPE</td>
928	<td>Platform</td>
929	<td>The platform has the POSIX API pthread_mutexattr_settype.</td>
930	</tr>
931	<tr>
932	<td>BOOST_HAS_PTHREAD_YIELD</td>
933	<td>Platform</td>
934	<td>The platform has the POSIX API pthread_yield.</td>
935	</tr>
936	<tr>
937	<td valign="top" width="48%">BOOST_HAS_PTHREADS</td>
938	<td valign="top" width="15%">Platform</td>
939	<td valign="top" width="37%">The platform support POSIX style threads.</td>
940	</tr>
941	<tr>
942	<td>BOOST_HAS_SCHED_YIELD</td>
943	<td>Platform</td>
944	<td>The platform has the POSIX API sched_yield.</td>
945	</tr>
946	<tr>
947	<td>BOOST_HAS_SGI_TYPE_TRAITS</td>
948	<td>Compiler/standard library</td>
949	<td>The compiler has native support for SGI style type traits.</td>
950	</tr>
951	<tr>
952	<td>BOOST_HAS_STDINT_H</td>
953	<td>Platform</td>
954	<td>The platform has a <stdint.h></td>
955	</tr>
956	<tr>
957	<td valign="top" width="48%">BOOST_HAS_SLIST</td>
958	<td valign="top" width="15%">Standard library</td>
959	<td valign="top" width="37%">The C++ implementation provides the (SGI) slist
960	class. When defined, BOOST_SLIST_HEADER will contain the name of the header
961	needed to access slist and BOOST_STD_EXTENSION_NAMESPACE will provide the
962	namespace in which slist resides.</td>
963	</tr>
964	<tr>
965	<td valign="top" width="48%">BOOST_HAS_STLP_USE_FACET</td>
966	<td valign="top" width="15%">Standard library</td>
967	<td valign="top" width="37%">The standard library lacks a conforming
968	std::use_facet, but has a workaround class-version that does the job. This is
969	primarily for the STLport std lib.</td>
970	</tr>
971	<TR>
972	<TD vAlign="top" width="48%">BOOST_HAS_TR1_ARRAY</TD>
973	<TD vAlign="top" width="15%">Standard library</TD>
974	<TD vAlign="top" width="37%">The library has a TR1 conforming version of
975	<array></TD>
976	</TR>
977	<TR>
978	<TD vAlign="top" width="48%">BOOST_HAS_TR1_COMPLEX_OVERLOADS</TD>
979	<TD vAlign="top" width="15%">Standard library</TD>
980	<TD vAlign="top" width="37%">The library has a version of <complex> that
981	supports passing scalars to the complex number algorithms.</TD>
982	</TR>
983	<TR>
984	<TD vAlign="top" width="48%">BOOST_HAS_TR1_COMPLEX_INVERSE_TRIG</TD>
985	<TD vAlign="top" width="15%">Standard library</TD>
986	<TD vAlign="top" width="37%">The library has a version of <complex> that
987	includes the new inverse trig functions from TR1.</TD>
988	</TR>
989	<TR>
990	<TD vAlign="top" width="48%">BOOST_HAS_TR1_REFERENCE_WRAPPER</TD>
991	<TD vAlign="top" width="15%">Standard library</TD>
992	<TD vAlign="top" width="37%">The library has TR1 conforming reference wrappers in
993	<functional>.</TD>
994	</TR>
995	<TR>
996	<TD vAlign="top" width="48%">BOOST_HAS_TR1_RESULT_OF</TD>
997	<TD vAlign="top" width="15%">Standard library</TD>
998	<TD vAlign="top" width="37%">The library has a TR1 conforming result_of template
999	in <functional>.</TD>
1000	</TR>
1001	<TR>
1002	<TD vAlign="top" width="48%">BOOST_HAS_TR1_MEM_FN</TD>
1003	<TD vAlign="top" width="15%">Standard library</TD>
1004	<TD vAlign="top" width="37%">The library has a TR1 conforming mem_fn function
1005	template in <functional>.</TD>
1006	</TR>
1007	<TR>
1008	<TD vAlign="top" width="48%">BOOST_HAS_TR1_BIND</TD>
1009	<TD vAlign="top" width="15%">Standard library</TD>
1010	<TD vAlign="top" width="37%">The library has a TR1 conforming bind function
1011	template in <functional>.</TD>
1012	</TR>
1013	<TR>
1014	<TD vAlign="top" width="48%">BOOST_HAS_TR1_FUNCTION</TD>
1015	<TD vAlign="top" width="15%">Standard library</TD>
1016	<TD vAlign="top" width="37%">The library has a TR1 conforming <EM>function</EM>
1017	class template in <functional>.</TD>
1018	</TR>
1019	<TR>
1020	<TD vAlign="top" width="48%">BOOST_HAS_TR1_HASH</TD>
1021	<TD vAlign="top" width="15%">Standard library</TD>
1022	<TD vAlign="top" width="37%">The library has a TR1 conforming <EM>hash </EM>function
1023	template in <functional>.</TD>
1024	</TR>
1025	<TR>
1026	<TD vAlign="top" width="48%">BOOST_HAS_TR1_SHARED_PTR</TD>
1027	<TD vAlign="top" width="15%">Standard library</TD>
1028	<TD vAlign="top" width="37%">The library has a TR1 conforming <EM>shared_ptr </EM>
1029	class template in <memory>.</TD>
1030	</TR>
1031	<TR>
1032	<TD vAlign="top" width="48%">BOOST_HAS_TR1_RANDOM</TD>
1033	<TD vAlign="top" width="15%">Standard library</TD>
1034	<TD vAlign="top" width="37%">The library has a TR1 conforming version of
1035	<random>.</TD>
1036	</TR>
1037	<TR>
1038	<TD vAlign="top" width="48%">BOOST_HAS_TR1_REGEX</TD>
1039	<TD vAlign="top" width="15%">Standard library</TD>
1040	<TD vAlign="top" width="37%">The library has a TR1 conforming version of
1041	<regex>.</TD>
1042	</TR>
1043	<TR>
1044	<TD vAlign="top" width="48%">BOOST_HAS_TR1_TUPLE</TD>
1045	<TD vAlign="top" width="15%">Standard library</TD>
1046	<TD vAlign="top" width="37%">The library has a TR1 conforming version of
1047	<tuple>.</TD>
1048	</TR>
1049	<TR>
1050	<TD vAlign="top" width="48%">BOOST_HAS_TR1_TYPE_TRAITS</TD>
1051	<TD vAlign="top" width="15%">Standard library</TD>
1052	<TD vAlign="top" width="37%">The library has a TR1 conforming version of
1053	<type_traits>.</TD>
1054	</TR>
1055	<TR>
1056	<TD vAlign="top" width="48%">BOOST_HAS_TR1_UTILITY</TD>
1057	<TD vAlign="top" width="15%">Standard library</TD>
1058	<TD vAlign="top" width="37%">The library has the TR1 additions to <utility>
1059	(tuple interface to std::pair).</TD>
1060	</TR>
1061	<TR>
1062	<TD vAlign="top" width="48%">BOOST_HAS_TR1_UNORDERED_MAP</TD>
1063	<TD vAlign="top" width="15%">Standard library</TD>
1064	<TD vAlign="top" width="37%">The library has a TR1 conforming version of
1065	<unordered_map>.</TD>
1066	</TR>
1067	<TR>
1068	<TD vAlign="top" width="48%">BOOST_HAS_TR1_UNORDERED_SET</TD>
1069	<TD vAlign="top" width="15%">Standard library</TD>
1070	<TD vAlign="top" width="37%">The library has a TR1 conforming version of
1071	<unordered_set>.</TD>
1072	</TR>
1073	<TR>
1074	<TD vAlign="top" width="48%">BOOST_HAS_TR1</TD>
1075	<TD vAlign="top" width="15%">Standard library</TD>
1076	<TD vAlign="top" width="37%">Implies all the other BOOST_HAS_TR1_* macros should
1077	be set.</TD>
1078	</TR>
1079	<tr>
1080	<td valign="top" width="48%">BOOST_HAS_THREADS</td>
1081	<td valign="top" width="15%">Platform/compiler</td>
1082	<td valign="top" width="37%">Defined if the compiler, in its current translation
1083	mode, supports multiple threads of execution.</td>
1084	</tr>
1085	<tr>
1086	<td valign="top" width="48%">BOOST_HAS_TWO_ARG_USE_FACET</td>
1087	<td valign="top" width="15%">Standard library</td>
1088	<td valign="top" width="37%">The standard library lacks a conforming
1089	std::use_facet, but has a two argument version that does the job. This is
1090	primarily for the Rogue Wave std lib.</td>
1091	</tr>
1092	<tr>
1093	<td valign="top" width="48%">BOOST_HAS_UNISTD_H</td>
1094	<td valign="top" width="15%">Platform</td>
1095	<td valign="top" width="37%">The Platform provides <unistd.h>.</td>
1096	</tr>
1097	<tr>
1098	<td valign="top" width="48%">BOOST_HAS_WINTHREADS</td>
1099	<td valign="top" width="15%">Platform</td>
1100	<td valign="top" width="37%">The platform supports MS Windows style threads.</td>
1101	</tr>
1102	<tr>
1103	<td valign="top" width="48%">BOOST_MSVC_STD_ITERATOR</td>
1104	<td valign="top" width="15%">Standard library</td>
1105	<td valign="top" width="37%">Microsoft's broken version of std::iterator is being
1106	used. This implies that std::iterator takes no more than two template
1107	parameters.</td>
1108	</tr>
1109	<tr>
1110	<td valign="top" width="48%">BOOST_MSVC6_MEMBER_TEMPLATES</td>
1111	<td valign="top" width="15%">Compiler</td>
1112	<td valign="top" width="37%">Microsoft Visual C++ 6.0 has enough member template
1113	idiosyncrasies (being polite) that BOOST_NO_MEMBER_TEMPLATES is defined for
1114	this compiler. BOOST_MSVC6_MEMBER_TEMPLATES is defined to allow compiler
1115	specific workarounds. This macro gets defined automatically if
1116	BOOST_NO_MEMBER_TEMPLATES is not defined - in other words this is treated as a
1117	strict subset of the features required by the standard.</td>
1118	</tr>
1119	<tr>
1120	<td valign="top" width="48%">BOOST_HAS_STDINT_H</td>
1121	<td valign="top" width="15%">Platform</td>
1122	<td valign="top" width="37%">There are no 1998 C++ Standard headers
1123	<stdint.h> or <cstdint>, although the 1999 C Standard does include
1124	<stdint.h>. If <stdint.h> is present, <boost/stdint.h> can
1125	make good use of it, so a flag is supplied (signalling presence; thus the
1126	default is not present, conforming to the current C++ standard).</td>
1127	</tr>
1128	</table>
1129	<h4><a name="helpers"></a>Boost Helper Macros</h4>
1130	<p>The following macros are either simple helpers, or macros that provide
1131	workarounds for compiler/standard library defects.</p>
1132	<table border="1" cellpadding="7" cellspacing="1" width="100%">
1133	<tr>
1134	<td valign="top" width="50%"><p align="center"><b>Macro</b></p>
1135	</td>
1136	<td valign="top" width="50%"><p align="center"><b>Description</b></p>
1137	</td>
1138	</tr>
1139	<tr>
1140	<td valign="top" width="50%">BOOST_DEDUCED_TYPENAME</td>
1141	<td valign="top" width="50%">Some compilers don't support the use of <code>typename</code>
1142	for dependent types in deduced contexts. This macro expands to nothing on those
1143	compilers, and <code>typename</code> elsewhere. For example, replace:<pre>template <class T> void f(T, typename T::type);</pre>
1144	<p>with:</p>
1145	<pre>template <class T> void f(T, BOOST_DEDUCED_TYPENAME T::type);</pre>
1146	</td>
1147	</tr>
1148	<tr>
1149	<td>BOOST_HASH_MAP_HEADER</td>
1150	<td>The header to include to get the SGI hash_map class. This macro is only
1151	available if BOOST_HAS_HASH is defined.</td>
1152	</tr>
1153	<tr>
1154	<td>BOOST_HASH_SET_HEADER</td>
1155	<td>The header to include to get the SGI hash_set class. This macro is only
1156	available if BOOST_HAS_HASH is defined.</td>
1157	</tr>
1158	<tr>
1159	<td>BOOST_SLIST_HEADER</td>
1160	<td>The header to include to get the SGI slist class. This macro is only available
1161	if BOOST_HAS_SLIST is defined.</td>
1162	</tr>
1163	<tr>
1164	<td>BOOST_STD_EXTENSION_NAMESPACE</td>
1165	<td>The namespace used for std library extensions (hashtable classes etc).</td>
1166	</tr>
1167	<tr>
1168	<td valign="top" width="50%">BOOST_STATIC_CONSTANT(Type, assignment)</td>
1169	<td valign="top" width="50%">On compilers which don't allow in-class
1170	initialization of static integral constant members, we must use enums as a
1171	workaround if we want the constants to be available at compile-time. This macro
1172	gives us a convenient way to declare such constants. For example instead of:<pre>struct foo{
1173	static const int value = 2;
1174	};</pre>
1175	<p>use:</p>
1176	<pre>struct foo{
1177	BOOST_STATIC_CONSTANT(int, value = 2);
1178	};</pre>
1179	</td>
1180	</tr>
1181	<tr>
1182	<td>BOOST_UNREACHABLE_RETURN(result)</td>
1183	<td>Normally evaluates to nothing, but evaluates to <font face="Courier New">return
1184	x;</font> if the compiler requires a return, even when it can never be
1185	reached.</td>
1186	</tr>
1187	<tr>
1188	<td>BOOST_EXPLICIT_TEMPLATE_TYPE(t)<br>
1189	BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t, v)<br>
1190	BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t)<br>
1191	BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t, v)<br>
1192	</td>
1193	<td>Some compilers silently "fold" different function template instantiations if
1194	some of the template parameters don't appear in the function parameter list.
1195	For instance:
1196	<pre> #include <iostream>
1197	#include <ostream>
1198	#include <typeinfo>
1199
1200	template <int n>
1201	void f() { std::cout << n << ' '; }
1202
1203	template <typename T>
1204	void g() { std::cout << typeid(T).name() << ' '; }
1205
1206	int main() {
1207	f<1>();
1208	f<2>();
1209
1210	g<int>();
1211	g<double>();
1212	}
1213	</pre>
1214	incorrectly outputs <tt>"2 2 double double "</tt> on VC++ 6. These macros, to
1215	be used in the function parameter list, fix the problem without effects on the
1216	calling syntax. For instance, in the case above write:
1217	<pre> template <int n>
1218	void f(BOOST_EXPLICIT_TEMPLATE_NON_TYPE(int, n)) { ... }
1219
1220	template <typename T>
1221	void g(BOOST_EXPLICIT_TEMPLATE_TYPE(T)) { ... }
1222	</pre>
1223	Beware that they can declare (for affected compilers) a dummy <i>defaulted</i> parameter,
1224	so they
1225	<br>
1226	<br>
1227	a) should be always invoked at the end of the parameter list
1228	<br>
1229	b) can't be used if your function template is multiply declared.
1230	<br>
1231	<br>
1232	Furthermore, in order to add any needed comma separator, an "APPEND_*" version
1233	must be used when the macro invocation appears after a normal parameter
1234	declaration or after the invocation of another macro of this same group.
1235	</td>
1236	</tr>
1237	<tr>
1238	<td valign="top" width="50%">BOOST_USE_FACET(Type, loc)</td>
1239	<td valign="top" width="50%">When the standard library does not have a comforming
1240	std::use_facet there are various workarounds available, but they differ from
1241	library to library. This macro provides a consistent way to access a locale's
1242	facets. For example, replace:<pre>std::use_facet<Type>(loc);</pre>
1243	<p>with:</p>
1244	<pre>BOOST_USE_FACET(Type, loc);</pre>
1245	<p>Note do not add a std:: prefix to the front of BOOST_USE_FACET.</p>
1246	</td>
1247	</tr>
1248	<tr>
1249	<td valign="top" width="50%">BOOST_HAS_FACET(Type, loc)</td>
1250	<td valign="top" width="50%">When the standard library does not have a comforming
1251	std::has_facet there are various workarounds available, but they differ from
1252	library to library. This macro provides a consistent way to check a locale's
1253	facets. For example, replace:<pre>std::has_facet<Type>(loc);</pre>
1254	<p>with:</p>
1255	<pre>BOOST_HAS_FACET(Type, loc);</pre>
1256	<p>Note do not add a std:: prefix to the front of BOOST_HAS_FACET.</p>
1257	</td>
1258	</tr>
1259	<tr>
1260	<td valign="top" width="50%">BOOST_NESTED_TEMPLATE</td>
1261	<td valign="top" width="50%">Member templates are supported by some compilers even
1262	though they can't use the A::template member<U> syntax, as a workaround
1263	replace:<pre>typedef typename A::template rebind<U> binder;</pre>
1264	<p>with:</p>
1265	<pre>typedef typename A::BOOST_NESTED_TEMPLATE rebind<U> binder;</pre>
1266	</td>
1267	</tr>
1268	<tr>
1269	<td valign="top" width="50%">BOOST_STRINGIZE(X)</td>
1270	<td valign="top" width="50%">Converts the parameter X to a string after macro
1271	replacement on X has been performed.</td>
1272	</tr>
1273	<tr>
1274	<td valign="top" width="50%">BOOST_JOIN(X,Y)</td>
1275	<td valign="top" width="50%">This piece of macro magic joins the two arguments
1276	together, even when one of the arguments is itself a macro (see 16.3.1 in C++
1277	standard). This is normally used to create a mangled name in combination with a
1278	predefined macro such a __LINE__.</td>
1279	</tr>
1280	</table>
1281	<h4><a name="info_macros"></a>Boost Informational Macros</h4>
1282	<p>The following macros describe boost features; these are, generally speaking the
1283	only boost macros that should be tested in user code.</p>
1284	<table border="1" cellpadding="7" cellspacing="1" width="100%">
1285	<tr>
1286	<td valign="top" width="33%"><p align="center"><b>Macro</b></p>
1287	</td>
1288	<td valign="top" width="33%"><p align="center"><b>Header</b></p>
1289	</td>
1290	<td valign="top" width="33%"><p align="center"><b>Description</b></p>
1291	</td>
1292	</tr>
1293	<tr>
1294	<td valign="top" width="33%">BOOST_VERSION</td>
1295	<td valign="top" width="33%"><boost/version.hpp></td>
1296	<td valign="top" width="33%">Describes the boost version number in XXYYZZ format
1297	such that: (BOOST_VERSION % 100) is the sub-minor version, ((BOOST_VERSION /
1298	100) % 1000) is the minor version, and (BOOST_VERSION / 100000) is the major
1299	version.</td>
1300	</tr>
1301	<tr>
1302	<td valign="top" width="33%">BOOST_NO_INT64_T</td>
1303	<td valign="top" width="33%"><boost/cstdint.hpp><p><boost/stdint.h></p>
1304	</td>
1305	<td valign="top" width="33%">Defined if there are no 64-bit integral types:
1306	int64_t, uint64_t etc.</td>
1307	</tr>
1308	<tr>
1309	<td valign="top" width="33%">BOOST_NO_INTEGRAL_INT64_T</td>
1310	<td valign="top" width="33%"><boost/cstdint.hpp><p><boost/stdint.h></p>
1311	</td>
1312	<td valign="top" width="33%">Defined if int64_t as defined by
1313	<boost/cstdint.hpp> is not usable in integral constant expressions.</td>
1314	</tr>
1315	<tr>
1316	<td valign="top">BOOST_MSVC</td>
1317	<td valign="top"><boost/config.hpp></td>
1318	<td valign="top">Defined if the compiler is really Microsoft Visual C++, as
1319	opposed to one of the many other compilers that also define _MSC_VER.</td>
1320	</tr>
1321	<tr>
1322	<td valign="top">BOOST_INTEL</td>
1323	<td valign="top"><boost/config.hpp></td>
1324	<td valign="top">Defined if the compiler is an Intel compiler, takes the same
1325	value as the compiler version macro.</td>
1326	</tr>
1327	<TR>
1328	<TD vAlign="top">BOOST_WINDOWS</TD>
1329	<TD vAlign="top"><boost/config.hpp></TD>
1330	<TD vAlign="top">Defined if the Windows platfrom API is available.</TD>
1331	</TR>
1332	<tr>
1333	<td>BOOST_DINKUMWARE_STDLIB</td>
1334	<td><boost/config.hpp></td>
1335	<td>Defined if the dinkumware standard library is in use, takes the same value as
1336	the Dinkumware library version macro _CPPLIB_VER if defined, otherwise 1.</td>
1337	</tr>
1338	<tr>
1339	<td valign="top" width="33%">BOOST_NO_WREGEX</td>
1340	<td valign="top" width="33%"><boost/regex.hpp></td>
1341	<td valign="top" width="33%">Defined if the regex library does not support wide
1342	character regular expressions.</td>
1343	</tr>
1344	<tr>
1345	<td valign="top" width="33%">BOOST_COMPILER</td>
1346	<td valign="top" width="33%"><boost/config.hpp></td>
1347	<td valign="top" width="33%">Defined as a string describing the name and version
1348	number of the compiler in use. Mainly for debugging the configuration.</td>
1349	</tr>
1350	<tr>
1351	<td valign="top" width="33%">BOOST_STDLIB</td>
1352	<td valign="top" width="33%"><boost/config.hpp></td>
1353	<td valign="top" width="33%">Defined as a string describing the name and version
1354	number of the standard library in use. Mainly for debugging the configuration.</td>
1355	</tr>
1356	<tr>
1357	<td valign="top" width="33%">BOOST_PLATFORM</td>
1358	<td valign="top" width="33%"><boost/config.hpp></td>
1359	<td valign="top" width="33%">Defined as a string describing the name of the
1360	platform. Mainly for debugging the configuration.</td>
1361	</tr>
1362	</table>
1363	<h2><a name="guidelines"></a></h2>
1364	<H4><A name="source"></A>Macros for libraries with separate source code</H4>
1365	<P>The following macros and helper headers are of use to authors whose libraries
1366	include separate source code, and are intended to address two issues: fixing
1367	the ABI of the compiled library, and selecting which compiled library to link
1368	against based upon the compilers settings.</P>
1369	<H5>ABI Fixing</H5>
1370	<P>When linking against a pre-compiled library it vital that the ABI used by the
1371	compiler when building the library <EM>matches</EM> <EM>exactly</EM> the ABI
1372	used by the code using the library.  In this case ABI means things like
1373	the struct packing arrangement used, the name mangling scheme used, or the size
1374	of some types (enum types for example).  This is separate from things like
1375	threading support, or runtime library variations, which have to be dealt with
1376	by build variants.  To put this in perspective there is one compiler
1377	(Borland's) that has so many compiler options that make subtle changes to the
1378	ABI, that at least in theory there 3200 combinations, and that's without
1379	considering runtime library variations.  Fortunately these variations can
1380	be managed by #pragma's that tell the compiler what ABI to use for the types
1381	declared in your library. In order to avoid sprinkling #pragma's all over the
1382	boost headers, there are some prefix and suffix headers that do the job.
1383	Typical usage is:</P>
1384	<P><b>my_library.cpp</b></P>
1385	<blockquote>
1386	<PRE>#ifndef MY_INCLUDE_GUARD
1387	#define MY_INCLUDE_GUARD
1388
1389	// all includes go here:
1390	<b>#include <boost/config.hpp></b>
1391	#include <whatever>
1392
1393	<b>#include <boost/config/abi_prefix.hpp> // must be the last #include</b>
1394
1395	namespace boost{
1396	// your code goes here
1397	}
1398
1399	<b>#include <boost/config/abi_suffix.hpp> // pops abi_prefix.hpp pragmas</b>
1400
1401	#endif // include guard
1402	</PRE>
1403	</blockquote>
1404	<P><b>my_library.cpp</b></P>
1405	<blockquote>
1406	<pre>...
1407	<b>// nothing special need be done in the implementation file</b>
1408	...</pre>
1409	</blockquote>
1410	<P>The user can disable this mechanism by defining BOOST_DISABLE_ABI_HEADERS, or
1411	they can define BOOST_ABI_PREFIX and/or BOOST_ABI_SUFFIX to point to their own
1412	prefix/suffix headers if they so wish.</P>
1413	<H5>Automatic library selection</H5>
1414	<P>It is essential that users link to a build of a library which was built against
1415	the same runtime library that their application will be built against - if this
1416	does not happen then the library will not be binary compatible with their own
1417	code - and there is a high likelihood  that their application will
1418	experience runtime crashes.  These kinds of problems can be extremely
1419	time consuming and difficult to debug, and often lead to frustrated users and
1420	authors alike (simply selecting the right library to link against is not as
1421	easy as it seems when their are 6-8 of them to chose from, and some users seem
1422	to be blissfully unaware that there even are different runtimes available to
1423	them).</P>
1424	<P>To solve this issue, some compilers allow source code to contain #pragma's that
1425	instruct the linker which library to link against, all the user need do is
1426	include the headers they need, place the compiled libraries in their library
1427	search path, and the compiler and linker do the rest.  Boost.config
1428	supports this via the header <boost/config/auto_link.hpp>, before
1429	including this header one or more of the following macros need to be defined:</P>
1430	<TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="1">
1431	<TR>
1432	<TD>BOOST_LIB_NAME</TD>
1433	<TD>
1434	Required: An identifier containing the basename of the library, for
1435	example 'boost_regex'.</TD>
1436	</TR>
1437	<TR>
1438	<TD>BOOST_DYN_LINK</TD>
1439	<TD>Optional: when set link to dll rather than static library.</TD>
1440	</TR>
1441	<TR>
1442	<TD>BOOST_LIB_DIAGNOSTIC</TD>
1443	<TD>Optional: when set the header will print out the name of the library selected
1444	(useful for debugging).</TD>
1445	</TR>
1446	</TABLE>
1447	<P>If the compiler supports this mechanism, then it will be told to link against
1448	the appropriately named library, the actual algorithm used to mangle the name
1449	of the library is documented inside <boost/config/auto_link.hpp> and has
1450	to match that used to create the libraries via bjam 's install rules.</P>
1451	<P>Typical usage is:</P>
1452	<P><b>my_library.hpp</b></P>
1453	<blockquote>
1454	<PRE>...
1455	//
1456	// Don't include auto-linking code if the user has disabled it by
1457	// defining BOOST_ALL_NO_LIB, or BOOST_MY_LIBRARY_NO_LIB, or if this
1458	// is one of our own source files (signified by BOOST_MY_LIBRARY_SOURCE):
1459	//
1460	<b>#if !defined(BOOST_ALL_NO_LIB) && !defined(BOOST_MY_LIBRARY_NO_LIB) && !defined(BOOST_MY_LIBRARY_SOURCE)
1461	# define BOOST_LIB_NAME boost_my_library
1462	# ifdef BOOST_MY_LIBRARY_DYN_LINK
1463	# define BOOST_DYN_LINK
1464	# endif
1465	# include <boost/config/auto_link.hpp>
1466	#endif
1467	</b>...
1468	</PRE>
1469	</blockquote>
1470	<p><b>my_library.cpp</b></p>
1471	<blockquote>
1472	<pre>// define BOOST_MY_LIBRARY_SOURCE so that the header knows that the
1473	// library is being built (possibly exporting rather than importing code)
1474	//
1475	<b>#define BOOST_MY_LIBRARY_SOURCE</b>
1476
1477	<b>#include <boost/my_library/my_library.hpp></b>
1478	...</pre>
1479	</blockquote>
1480	<H2>Guidelines for Boost Authors</H2>
1481	<p>The <a href="../../boost/config.hpp">boost/config.hpp</a> header is used to
1482	pass configuration information to other boost files, allowing them to cope with
1483	platform dependencies such as arithmetic byte ordering, compiler pragmas, or
1484	compiler shortcomings. Without such configuration information, many current
1485	compilers would not work with the Boost libraries.</p>
1486	<p>Centralizing configuration information in this header reduces the number of
1487	files that must be modified when porting libraries to new platforms, or when
1488	compilers are updated. Ideally, no other files would have to be modified when
1489	porting to a new platform.</p>
1490	<p>Configuration headers are controversial because some view them as condoning
1491	broken compilers and encouraging non-standard subsets. Adding settings for
1492	additional platforms and maintaining existing settings can also be a problem.
1493	In other words, configuration headers are a necessary evil rather than a
1494	desirable feature. The boost config.hpp policy is designed to minimize the
1495	problems and maximize the benefits of a configuration header.</p>
1496	<p>Note that:</p>
1497	<ul>
1498	<li>
1499	Boost library implementers are not required to #include
1500	<boost/config.hpp>, and are not required in any way to support compilers
1501	that do not comply with the C++ Standard (ISO/IEC 14882).
1502	<li>
1503	If a library implementer wishes to support some non-conforming compiler, or to
1504	support some platform specific feature, #include <boost/config.hpp> is
1505	the preferred way to obtain configuration information not available from the
1506	standard headers such as <climits>, etc.
1507	<li>
1508	If configuration information can be deduced from standard headers such as
1509	<climits>, use those standard headers rather than
1510	<boost/config.hpp>.
1511	<li>
1512	Boost files that use macros defined in <boost/config.hpp> should have
1513	sensible, standard conforming, default behavior if the macro is not defined.
1514	This means that the starting point for porting <boost/config.hpp> to a
1515	new platform is simply to define nothing at all specific to that platform. In
1516	the rare case where there is no sensible default behavior, an #error message
1517	should describe the problem.
1518	<li>
1519	If a Boost library implementer wants something added to config.hpp, post a
1520	request on the Boost mailing list. There is no guarantee such a request will be
1521	honored; the intent is to limit the complexity of config.hpp.
1522	<li>
1523	The intent is to support only compilers which appear on their way to becoming
1524	C++ Standard compliant, and only recent releases of those compilers at that.
1525	<li>
1526	The intent is not to disable mainstream features now well-supported by the
1527	majority of compilers, such as namespaces, exceptions, RTTI, or templates.
1528	</li>
1529	</ul>
1530	<h4><a name="defect_guidelines"></a>Adding New Defect Macros</h4>
1531	<p>When you need to add a new defect macro - either to fix a problem with an
1532	existing library, or when adding a new library - distil the issue down to a
1533	simple test case; often, at this point other (possibly better) workarounds may
1534	become apparent. Secondly always post the test case code to the boost mailing
1535	list and invite comments; remember that C++ is complex and that sometimes what
1536	may appear a defect, may in fact turn out to be a problem with the authors
1537	understanding of the standard.</p>
1538	<p>When you name the macro, follow the BOOST_NO_SOMETHING naming convention, so
1539	that it's obvious that this is a macro reporting a defect.</p>
1540	<p>Finally, add the test program to the regression tests. You will need to place
1541	the test case in a .ipp file with the following comments near the top:</p>
1542	<pre>// MACRO: BOOST_NO_FOO
1543	// TITLE: foo
1544	// DESCRIPTION: If the compiler fails to support foo</pre>
1545	<p>These comments are processed by the autoconf script, so make sure the format
1546	follows the one given. The file should be named "boost_no_foo.ipp", where foo
1547	is the defect description - try and keep the file name under the Mac 30
1548	character filename limit though. You will also need to provide a function
1549	prototype "int test()" that is declared in a namespace with the same name as
1550	the macro, but in all lower case, and which returns zero on success:</p>
1551	<pre>namespace boost_no_foo{
1552
1553	int test()
1554	{
1555	// test code goes here:
1556	//
1557	return 0;
1558	}
1559
1560	}</pre>
1561	<p>
1562	Once the test code is in place, build and run the program "generate.cpp" that
1563	you will find in the boost-root/libs/config/tools/ directory. This generates
1564	two .cpp test files from the new test code, and adds the tests to the
1565	regression test Jamfile, and the config_test.cpp test program. Finally add a
1566	new entry to config_info.cpp so that the new macro gets printed out when that
1567	program is run.</p>
1568	<h4><a name="feature_guidelines"></a>Adding New Feature Test Macros</h4>
1569	<p>When you need to add a macro that describes a feature that the standard does
1570	not require, follow the convention for adding a new defect macro (above), but
1571	call the macro BOOST_HAS_FOO, and name the test file "boost_has_foo.ipp". Try
1572	not to add feature test macros unnecessarily, if there is a platform specific
1573	macro that can already be used (for example _WIN32, __BEOS__, or __linux) to
1574	identify the feature then use that. Try to keep the macro to a feature group,
1575	or header name, rather than one specific API (for example BOOST_HAS_NL_TYPES_H
1576	rather than BOOST_HAS_CATOPEN). If the macro describes a POSIX feature group,
1577	then add boilerplate code to <a href="../../boost/config/suffix.hpp">boost/config/suffix.hpp</a>
1578	to auto-detect the feature where possible (if you are wondering why we can't
1579	use POSIX feature test macro directly, remember that many of these features can
1580	be added by third party libraries, and are not therefore identified inside
1581	<unistd.h>).</p>
1582	<h4><a name="modify_guidelines"></a>Modifying the Boost Configuration Headers</h4>
1583	<p>The aim of boost's configuration setup is that the configuration headers should
1584	be relatively stable - a boost user should not have to recompile their code
1585	just because the configuration for some compiler that they're not interested in
1586	has changed. Separating the configuration into separate compiler/standard
1587	library/platform sections provides for part of this stability, but boost
1588	authors require some amount of restraint as well, in particular:</p>
1589	<p><<a href="../../boost/config.hpp">boost/config.hpp</a>> should never
1590	change, don't alter this file.</p>
1591	<p><<a href="../../boost/config/user.hpp">boost/config/user.hpp</a>> is
1592	included by default, don't add extra code to this file unless you have to. If
1593	you do, please remember to update <a href="tools/configure.in">libs/config/tools/configure.in</a>
1594	as well.</p>
1595	<p><<a href="../../boost/config/suffix.hpp">boost/config/suffix.hpp</a>> is
1596	always included so be careful about modifying this file as it breaks
1597	dependencies for everyone. This file should include only "boilerplate"
1598	configuration code, and generally should change only when new macros are added.</p>
1599	<p><<a href="../../boost/config/select_compiler_config.hpp">boost/config/select_compiler_config.hpp</a>>,
1600	<<a href="../../boost/config/select_platform_config.hpp">boost/config/select_platform_config.hpp</a>>
1601	and <<a href="../../boost/config/select_stdlib_config.hpp">boost/config/select_stdlib_config.hpp</a>>
1602	are included by default and should change only if support for a new
1603	compiler/standard library/platform is added.</p>
1604	<p>The compiler/platform/standard library selection code is set up so that unknown
1605	platforms are ignored and assumed to be fully standards compliant - this gives
1606	unknown platforms a "sporting chance" of working "as is" even without running
1607	the configure script.</p>
1608	<p>When adding or modifying the individual mini-configs, assume that future, as
1609	yet unreleased versions of compilers, have all the defects of the current
1610	version. Although this is perhaps unnecessarily pessimistic, it cuts down on
1611	the maintenance of these files, and experience suggests that pessimism is
1612	better placed than optimism here!</p>
1613	<h2><a name="rationale"></a>Rationale</h2>
1614	<p>The problem with many traditional "textbook" implementations of configuration
1615	headers (where all the configuration options are in a single "monolithic"
1616	header) is that they violate certain fundamental software engineering
1617	principles which would have the effect of making boost more fragile, more
1618	difficult to maintain and more difficult to use safely. You can find a
1619	description of the principles from the <a href="http://www.objectmentor.com/publications/Principles%20and%20Patterns.PDF">
1620	following article</a>.</p>
1621	<h4>The problem</h4>
1622	<p>Consider a situation in which you are concurrently developing on multiple
1623	platforms. Then consider adding a new platform or changing the platform
1624	definitions of an existing platform. What happens? Everything, and this does
1625	literally mean everything, recompiles. Isn't it quite absurd that adding a new
1626	platform, which has absolutely nothing to do with previously existing
1627	platforms, means that all code on all existing platforms needs to be
1628	recompiled?</p>
1629	<p>Effectively, there is an imposed physical dependency between platforms that
1630	have nothing to do with each other. Essentially, the traditional solution
1631	employed by configuration headers does not conform to the Open-Closed
1632	Principle:</p>
1633	<p><b><i>"A module should be open for extension but closed for modification."</i></b></p>
1634	<p>Extending a traditional configuration header implies modifying existing code.</p>
1635	<p>Furthermore, consider the complexity and fragility of the platform detection
1636	code. What if a simple change breaks the detection on some minor platform? What
1637	if someone accidentally or on purpose (as a workaround for some other problem)
1638	defines some platform dependent macros that are used by the detection code? A
1639	traditional configuration header is one of the most volatile headers of the
1640	entire library, and more stable elements of Boost would depend on it. This
1641	violates the Stable Dependencies Principle:</p>
1642	<p><b><i>"Depend in the direction of stability."</i></b></p>
1643	<p>After even a minor change to a traditional configuration header on one minor
1644	platform, almost everything on every platform should be tested if we follow
1645	sound software engineering practice.</p>
1646	<p>Another important issue is that it is not always possible to submit changes to
1647	<boost/config.hpp>. Some boost users are currently working on platforms
1648	using tools and libraries that are under strict Non-Disclosure Agreements. In
1649	this situation it is impossible to submit changes to a traditional monolithic
1650	configuration header, instead some method by which the user can insert their
1651	own configuration code must be provided.</p>
1652	<h4>The solution</h4>
1653	<p>The approach taken by boost's configuration headers is to separate
1654	configuration into three orthogonal parts: the compiler, the standard library
1655	and the platform. Each compiler/standard library/platform gets its own
1656	mini-configuration header, so that changes to one compiler's configuration (for
1657	example) does not affect other compilers. In addition there are measures that
1658	can be taken both to omit the compiler/standard library/platform detection code
1659	(so that adding support to a new platform does not break dependencies), or to
1660	freeze the configuration completely; providing almost complete protection
1661	against dependency changes.</p>
1662	<h2><a name="Acknowledgements"></a>Acknowledgements</h2>
1663	<p>Beman Dawes provided the original config.hpp and part of this document. Vesa
1664	Karvonen provided a description of the principles (see <a href="#rationale">rationale</a>)
1665	and put together an early version of the current configuration setup. John
1666	Maddock put together the configuration current code, the test programs, the
1667	configuration script and the reference section of this document. Numerous boost
1668	members, past and present, have contributed fixes to boost's configuration.</p>
1669	<p> </p>
1670	<hr>
1671	<p>Copyright Beman Dawes 2001</p>
1672	<p>Copyright Vesa Karvonen 2001</p>
1673	<p>Copyright John Maddock 2001</p>
1674	<P>Distributed under the Boost Software License, Version 1.0. (See accompanying
1675	file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">
1676	www.boost.org/LICENSE_1_0.txt</A>).</P>
1677	<p> </p>
1678	<p> </p>
1679	<p> </p>
1680	<p> </p>
1681	<p> </p>
1682	</body>
1683	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: