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