aboutsummaryrefslogtreecommitdiff
path: root/gcc/doc/sourcebuild.texi
blob: 14397b78653a35e72666f0a2394bb5786d8fd3f4 (plain)
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
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node Source Tree
@chapter Source Tree Structure and Build System

This chapter describes the structure of the GCC source tree, and how
GCC is built.  The user documentation for building and installing GCC
is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
which it is presumed that you are familiar.

@menu
* Configure Terms:: Configuration terminology and history.
* Top Level::       The top level source directory.
* gcc Directory::   The @file{gcc} subdirectory.
@end menu

@include configterms.texi

@node Top Level
@section Top Level Source Directory

The top level source directory in a GCC distribution contains several
files and directories that are shared with other software
distributions such as that of GNU Binutils.  It also contains several
subdirectories that contain parts of GCC and its runtime libraries:

@table @file
@item boehm-gc
The Boehm conservative garbage collector, used as part of the Java
runtime library.

@item config
Autoconf macros and Makefile fragments used throughout the tree.

@item contrib
Contributed scripts that may be found useful in conjunction with GCC@.
One of these, @file{contrib/texi2pod.pl}, is used to generate man
pages from Texinfo manuals as part of the GCC build process.

@item fixincludes
The support for fixing system headers to work with GCC@.  See
@file{fixincludes/README} for more information.  The headers fixed by
this mechanism are installed in @file{@var{libsubdir}/include-fixed}.
Along with those headers, @file{README-fixinc} is also installed, as
@file{@var{libsubdir}/include-fixed/README}.

@item gcc
The main sources of GCC itself (except for runtime libraries),
including optimizers, support for different target architectures,
language front ends, and testsuites.  @xref{gcc Directory, , The
@file{gcc} Subdirectory}, for details.

@item gnattools
Support tools for GNAT.

@item include
Headers for the @code{libiberty} library.

@item intl
GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
include it in @code{libc}.

@item libada
The Ada runtime library.

@item libcpp
The C preprocessor library.

@item libdecnumber
The Decimal Float support library.

@item libffi
The @code{libffi} library, used as part of the Java runtime library.

@item libgcc
The GCC runtime library.

@item libgfortran
The Fortran runtime library.

@item libgomp
The GNU OpenMP runtime library.

@item libiberty
The @code{libiberty} library, used for portability and for some
generally useful data structures and algorithms.  @xref{Top, ,
Introduction, libiberty, @sc{gnu} libiberty}, for more information
about this library.

@item libjava
The Java runtime library.

@item libmudflap
The @code{libmudflap} library, used for instrumenting pointer and array
dereferencing operations.

@item libobjc
The Objective-C and Objective-C++ runtime library.

@item libssp
The Stack protector runtime library.

@item libstdc++-v3
The C++ runtime library.

@item lto-plugin
Plugin used by @command{gold} if link-time optimizations are enabled.

@item maintainer-scripts
Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.

@item zlib
The @code{zlib} compression library, used by the Java front end, as
part of the Java runtime library, and for compressing and uncompressing
GCC's intermediate language in LTO object files.
@end table

The build system in the top level directory, including how recursion
into subdirectories works and how building runtime libraries for
multilibs is handled, is documented in a separate manual, included
with GNU Binutils.  @xref{Top, , GNU configure and build system,
configure, The GNU configure and build system}, for details.

@node gcc Directory
@section The @file{gcc} Subdirectory

The @file{gcc} directory contains many files that are part of the C
sources of GCC, other files used as part of the configuration and
build process, and subdirectories including documentation and a
testsuite.  The files that are sources of GCC are documented in a
separate chapter.  @xref{Passes, , Passes and Files of the Compiler}.

@menu
* Subdirectories:: Subdirectories of @file{gcc}.
* Configuration::  The configuration process, and the files it uses.
* Build::          The build system in the @file{gcc} directory.
* Makefile::       Targets in @file{gcc/Makefile}.
* Library Files::  Library source files and headers under @file{gcc/}.
* Headers::        Headers installed by GCC.
* Documentation::  Building documentation in GCC.
* Front End::      Anatomy of a language front end.
* Back End::       Anatomy of a target back end.
@end menu

@node Subdirectories
@subsection Subdirectories of @file{gcc}

The @file{gcc} directory contains the following subdirectories:

@table @file
@item @var{language}
Subdirectories for various languages.  Directories containing a file
@file{config-lang.in} are language subdirectories.  The contents of
the subdirectories @file{cp} (for C++), @file{lto} (for LTO),
@file{objc} (for Objective-C) and @file{objcp} (for Objective-C++) are
documented in this manual (@pxref{Passes, , Passes and Files of the
Compiler}); those for other languages are not.  @xref{Front End, ,
Anatomy of a Language Front End}, for details of the files in these
directories.

@item config
Configuration files for supported architectures and operating
systems.  @xref{Back End, , Anatomy of a Target Back End}, for
details of the files in this directory.

@item doc
Texinfo documentation for GCC, together with automatically generated
man pages and support for converting the installation manual to
HTML@.  @xref{Documentation}.

@item ginclude
System headers installed by GCC, mainly those required by the C
standard of freestanding implementations.  @xref{Headers, , Headers
Installed by GCC}, for details of when these and other headers are
installed.

@item po
Message catalogs with translations of messages produced by GCC into
various languages, @file{@var{language}.po}.  This directory also
contains @file{gcc.pot}, the template for these message catalogues,
@file{exgettext}, a wrapper around @command{gettext} to extract the
messages from the GCC sources and create @file{gcc.pot}, which is run
by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
which messages should not be extracted.

@item testsuite
The GCC testsuites (except for those for runtime libraries).
@xref{Testsuites}.
@end table

@node Configuration
@subsection Configuration in the @file{gcc} Directory

The @file{gcc} directory is configured with an Autoconf-generated
script @file{configure}.  The @file{configure} script is generated
from @file{configure.ac} and @file{aclocal.m4}.  From the files
@file{configure.ac} and @file{acconfig.h}, Autoheader generates the
file @file{config.in}.  The file @file{cstamp-h.in} is used as a
timestamp.

@menu
* Config Fragments::     Scripts used by @file{configure}.
* System Config::        The @file{config.build}, @file{config.host}, and
                         @file{config.gcc} files.
* Configuration Files::  Files created by running @file{configure}.
@end menu

@node Config Fragments
@subsubsection Scripts Used by @file{configure}

@file{configure} uses some other scripts to help in its work:

@itemize @bullet
@item The standard GNU @file{config.sub} and @file{config.guess}
files, kept in the top level directory, are used.

@item The file @file{config.gcc} is used to handle configuration
specific to the particular target machine.  The file
@file{config.build} is used to handle configuration specific to the
particular build machine.  The file @file{config.host} is used to handle
configuration specific to the particular host machine.  (In general,
these should only be used for features that cannot reasonably be tested in
Autoconf feature tests.)
@xref{System Config, , The @file{config.build}; @file{config.host};
and @file{config.gcc} Files}, for details of the contents of these files.

@item Each language subdirectory has a file
@file{@var{language}/config-lang.in} that is used for
front-end-specific configuration.  @xref{Front End Config, , The Front
End @file{config-lang.in} File}, for details of this file.

@item A helper script @file{configure.frag} is used as part of
creating the output of @file{configure}.
@end itemize

@node System Config
@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files

The @file{config.build} file contains specific rules for particular systems
which GCC is built on.  This should be used as rarely as possible, as the
behavior of the build system can always be detected by autoconf.

The @file{config.host} file contains specific rules for particular systems
which GCC will run on.  This is rarely needed.

The @file{config.gcc} file contains specific rules for particular systems
which GCC will generate code for.  This is usually needed.

Each file has a list of the shell variables it sets, with descriptions, at the
top of the file.

FIXME: document the contents of these files, and what variables should
be set to control build, host and target configuration.

@include configfiles.texi

@node Build
@subsection Build System in the @file{gcc} Directory

FIXME: describe the build system, including what is built in what
stages.  Also list the various source files that are used in the build
process but aren't source files of GCC itself and so aren't documented
below (@pxref{Passes}).

@include makefile.texi

@node Library Files
@subsection Library Source Files and Headers under the @file{gcc} Directory

FIXME: list here, with explanation, all the C source files and headers
under the @file{gcc} directory that aren't built into the GCC
executable but rather are part of runtime libraries and object files,
such as @file{crtstuff.c} and @file{unwind-dw2.c}.  @xref{Headers, ,
Headers Installed by GCC}, for more information about the
@file{ginclude} directory.

@node Headers
@subsection Headers Installed by GCC

In general, GCC expects the system C library to provide most of the
headers to be used with it.  However, GCC will fix those headers if
necessary to make them work with GCC, and will install some headers
required of freestanding implementations.  These headers are installed
in @file{@var{libsubdir}/include}.  Headers for non-C runtime
libraries are also installed by GCC; these are not documented here.
(FIXME: document them somewhere.)

Several of the headers GCC installs are in the @file{ginclude}
directory.  These headers, @file{iso646.h},
@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
are installed in @file{@var{libsubdir}/include},
unless the target Makefile fragment (@pxref{Target Fragment})
overrides this by setting @code{USER_H}.

In addition to these headers and those generated by fixing system
headers to work with GCC, some other headers may also be installed in
@file{@var{libsubdir}/include}.  @file{config.gcc} may set
@code{extra_headers}; this specifies additional headers under
@file{config} to be installed on some systems.

GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
This is done to cope with command-line options that change the
representation of floating point numbers.

GCC also installs its own version of @code{<limits.h>}; this is generated
from @file{glimits.h}, together with @file{limitx.h} and
@file{limity.h} if the system also has its own version of
@code{<limits.h>}.  (GCC provides its own header because it is
required of ISO C freestanding implementations, but needs to include
the system header from its own header as well because other standards
such as POSIX specify additional values to be defined in
@code{<limits.h>}.)  The system's @code{<limits.h>} header is used via
@file{@var{libsubdir}/include/syslimits.h}, which is copied from
@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
needs fixing, @file{syslimits.h} is the fixed copy.

GCC can also install @code{<tgmath.h>}.  It will do this when
@file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.

@node Documentation
@subsection Building Documentation

The main GCC documentation is in the form of manuals in Texinfo
format.  These are installed in Info format; DVI versions may be
generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
HTML versions by @samp{make html}.  In addition, some man pages are
generated from the Texinfo manuals, there are some other text files
with miscellaneous documentation, and runtime libraries have their own
documentation outside the @file{gcc} directory.  FIXME: document the
documentation for runtime libraries somewhere.

@menu
* Texinfo Manuals::      GCC manuals in Texinfo format.
* Man Page Generation::  Generating man pages from Texinfo manuals.
* Miscellaneous Docs::   Miscellaneous text files with documentation.
@end menu

@node Texinfo Manuals
@subsubsection Texinfo Manuals

The manuals for GCC as a whole, and the C and C++ front ends, are in
files @file{doc/*.texi}.  Other front ends have their own manuals in
files @file{@var{language}/*.texi}.  Common files
@file{doc/include/*.texi} are provided which may be included in
multiple manuals; the following files are in @file{doc/include}:

@table @file
@item fdl.texi
The GNU Free Documentation License.
@item funding.texi
The section ``Funding Free Software''.
@item gcc-common.texi
Common definitions for manuals.
@item gpl.texi
@itemx gpl_v3.texi
The GNU General Public License.
@item texinfo.tex
A copy of @file{texinfo.tex} known to work with the GCC manuals.
@end table

DVI-formatted manuals are generated by @samp{make dvi}, which uses
@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).  
PDF-formatted manuals are generated by @samp{make pdf}, which uses
@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}).  HTML
formatted manuals are generated by @samp{make html}.  Info
manuals are generated by @samp{make info} (which is run as part of
a bootstrap); this generates the manuals in the source directory,
using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
and they are included in release distributions.

Manuals are also provided on the GCC web site, in both HTML and
PostScript forms.  This is done via the script
@file{maintainer-scripts/update_web_docs}.  Each manual to be
provided online must be listed in the definition of @code{MANUALS} in
that file; a file @file{@var{name}.texi} must only appear once in the
source tree, and the output manual must have the same name as the
source file.  (However, other Texinfo files, included in manuals but
not themselves the root files of manuals, may have names that appear
more than once in the source tree.)  The manual file
@file{@var{name}.texi} should only include other files in its own
directory or in @file{doc/include}.  HTML manuals will be generated by
@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
and @command{dvips}, and PDF manuals by @command{texi2pdf}.
All Texinfo files that are parts of manuals must
be version-controlled, even if they are generated files, for the
generation of online manuals to work.

The installation manual, @file{doc/install.texi}, is also provided on
the GCC web site.  The HTML version is generated by the script
@file{doc/install.texi2html}.

@node Man Page Generation
@subsubsection Man Page Generation

Because of user demand, in addition to full Texinfo manuals, man pages
are provided which contain extracts from those manuals.  These man
pages are generated from the Texinfo manuals using
@file{contrib/texi2pod.pl} and @command{pod2man}.  (The man page for
@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
to @file{gcc.1}, but all the other man pages are generated from
Texinfo manuals.)

Because many systems may not have the necessary tools installed to
generate the man pages, they are only generated if the
@file{configure} script detects that recent enough tools are
installed, and the Makefiles allow generating man pages to fail
without aborting the build.  Man pages are also included in release
distributions.  They are generated in the source directory.

Magic comments in Texinfo files starting @samp{@@c man} control what
parts of a Texinfo file go into a man page.  Only a subset of Texinfo
is supported by @file{texi2pod.pl}, and it may be necessary to add
support for more Texinfo features to this script when generating new
man pages.  To improve the man page output, some special Texinfo
macros are provided in @file{doc/include/gcc-common.texi} which
@file{texi2pod.pl} understands:

@table @code
@item @@gcctabopt
Use in the form @samp{@@table @@gcctabopt} for tables of options,
where for printed output the effect of @samp{@@code} is better than
that of @samp{@@option} but for man page output a different effect is
wanted.
@item @@gccoptlist
Use for summary lists of options in manuals.
@item @@gol
Use at the end of each line inside @samp{@@gccoptlist}.  This is
necessary to avoid problems with differences in how the
@samp{@@gccoptlist} macro is handled by different Texinfo formatters.
@end table

FIXME: describe the @file{texi2pod.pl} input language and magic
comments in more detail.

@node Miscellaneous Docs
@subsubsection Miscellaneous Documentation

In addition to the formal documentation that is installed by GCC,
there are several other text files in the @file{gcc} subdirectory
with miscellaneous documentation:

@table @file
@item ABOUT-GCC-NLS
Notes on GCC's Native Language Support.  FIXME: this should be part of
this manual rather than a separate file.
@item ABOUT-NLS
Notes on the Free Translation Project.
@item COPYING
@itemx COPYING3
The GNU General Public License, Versions 2 and 3.
@item COPYING.LIB
@itemx COPYING3.LIB
The GNU Lesser General Public License, Versions 2.1 and 3.
@item *ChangeLog*
@itemx */ChangeLog*
Change log files for various parts of GCC@.
@item LANGUAGES
Details of a few changes to the GCC front-end interface.  FIXME: the
information in this file should be part of general documentation of
the front-end interface in this manual.
@item ONEWS
Information about new features in old versions of GCC@.  (For recent
versions, the information is on the GCC web site.)
@item README.Portability
Information about portability issues when writing code in GCC@.  FIXME:
why isn't this part of this manual or of the GCC Coding Conventions?
@end table

FIXME: document such files in subdirectories, at least @file{config},
@file{cp}, @file{objc}, @file{testsuite}.

@node Front End
@subsection Anatomy of a Language Front End

A front end for a language in GCC has the following parts:

@itemize @bullet
@item
A directory @file{@var{language}} under @file{gcc} containing source
files for that front end.  @xref{Front End Directory, , The Front End
@file{@var{language}} Directory}, for details.
@item
A mention of the language in the list of supported languages in
@file{gcc/doc/install.texi}.
@item
A mention of the name under which the language's runtime library is
recognized by @option{--enable-shared=@var{package}} in the
documentation of that option in @file{gcc/doc/install.texi}.
@item
A mention of any special prerequisites for building the front end in
the documentation of prerequisites in @file{gcc/doc/install.texi}.
@item
Details of contributors to that front end in
@file{gcc/doc/contrib.texi}.  If the details are in that front end's
own manual then there should be a link to that manual's list in
@file{contrib.texi}.
@item
Information about support for that language in
@file{gcc/doc/frontends.texi}.
@item
Information about standards for that language, and the front end's
support for them, in @file{gcc/doc/standards.texi}.  This may be a
link to such information in the front end's own manual.
@item
Details of source file suffixes for that language and @option{-x
@var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
@item
Entries in @code{default_compilers} in @file{gcc.c} for source file
suffixes for that language.
@item
Preferably testsuites, which may be under @file{gcc/testsuite} or
runtime library directories.  FIXME: document somewhere how to write
testsuite harnesses.
@item
Probably a runtime library for the language, outside the @file{gcc}
directory.  FIXME: document this further.
@item
Details of the directories of any runtime libraries in
@file{gcc/doc/sourcebuild.texi}.
@item
Check targets in @file{Makefile.def} for the top-level @file{Makefile}
to check just the compiler or the compiler and runtime library for the
language.
@end itemize

If the front end is added to the official GCC source repository, the
following are also necessary:

@itemize @bullet
@item
At least one Bugzilla component for bugs in that front end and runtime
libraries.  This category needs to be mentioned in
@file{gcc/gccbug.in}, as well as being added to the Bugzilla database.
@item
Normally, one or more maintainers of that front end listed in
@file{MAINTAINERS}.
@item
Mentions on the GCC web site in @file{index.html} and
@file{frontends.html}, with any relevant links on
@file{readings.html}.  (Front ends that are not an official part of
GCC may also be listed on @file{frontends.html}, with relevant links.)
@item
A news item on @file{index.html}, and possibly an announcement on the
@email{gcc-announce@@gcc.gnu.org} mailing list.
@item
The front end's manuals should be mentioned in
@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
and the online manuals should be linked to from
@file{onlinedocs/index.html}.
@item
Any old releases or CVS repositories of the front end, before its
inclusion in GCC, should be made available on the GCC FTP site
@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
@item
The release and snapshot script @file{maintainer-scripts/gcc_release}
should be updated to generate appropriate tarballs for this front end.
The associated @file{maintainer-scripts/snapshot-README} and
@file{maintainer-scripts/snapshot-index.html} files should be updated
to list the tarballs and diffs for this front end.
@item
If this front end includes its own version files that include the
current date, @file{maintainer-scripts/update_version} should be
updated accordingly.
@end itemize

@menu
* Front End Directory::  The front end @file{@var{language}} directory.
* Front End Config::     The front end @file{config-lang.in} file.
* Front End Makefile::   The front end @file{Make-lang.in} file.
@end menu

@node Front End Directory
@subsubsection The Front End @file{@var{language}} Directory

A front end @file{@var{language}} directory contains the source files
of that front end (but not of any runtime libraries, which should be
outside the @file{gcc} directory).  This includes documentation, and
possibly some subsidiary programs built alongside the front end.
Certain files are special and other parts of the compiler depend on
their names:

@table @file
@item config-lang.in
This file is required in all language subdirectories.  @xref{Front End
Config, , The Front End @file{config-lang.in} File}, for details of
its contents
@item Make-lang.in
This file is required in all language subdirectories.  @xref{Front End
Makefile, , The Front End @file{Make-lang.in} File}, for details of its
contents.
@item lang.opt
This file registers the set of switches that the front end accepts on
the command line, and their @option{--help} text.  @xref{Options}.
@item lang-specs.h
This file provides entries for @code{default_compilers} in
@file{gcc.c} which override the default of giving an error that a
compiler for that language is not installed.
@item @var{language}-tree.def
This file, which need not exist, defines any language-specific tree
codes.
@end table

@node Front End Config
@subsubsection The Front End @file{config-lang.in} File

Each language subdirectory contains a @file{config-lang.in} file.  In
addition the main directory contains @file{c-config-lang.in}, which
contains limited information for the C language.  This file is a shell
script that may define some variables describing the language:

@table @code
@item language
This definition must be present, and gives the name of the language
for some purposes such as arguments to @option{--enable-languages}.
@item lang_requires
If defined, this variable lists (space-separated) language front ends
other than C that this front end requires to be enabled (with the
names given being their @code{language} settings).  For example, the
Java front end depends on the C++ front end, so sets
@samp{lang_requires=c++}.
@item subdir_requires
If defined, this variable lists (space-separated) front end directories
other than C that this front end requires to be present.  For example,
the Objective-C++ front end uses source files from the C++ and
Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
@item target_libs
If defined, this variable lists (space-separated) targets in the top
level @file{Makefile} to build the runtime libraries for this
language, such as @code{target-libobjc}.
@item lang_dirs
If defined, this variable lists (space-separated) top level
directories (parallel to @file{gcc}), apart from the runtime libraries,
that should not be configured if this front end is not built.
@item build_by_default
If defined to @samp{no}, this language front end is not built unless
enabled in a @option{--enable-languages} argument.  Otherwise, front
ends are built by default, subject to any special logic in
@file{configure.ac} (as is present to disable the Ada front end if the
Ada compiler is not already installed).
@item boot_language
If defined to @samp{yes}, this front end is built in stage1 of the
bootstrap.  This is only relevant to front ends written in their own
languages.
@item compilers
If defined, a space-separated list of compiler executables that will
be run by the driver.  The names here will each end
with @samp{\$(exeext)}.
@item outputs
If defined, a space-separated list of files that should be generated
by @file{configure} substituting values in them.  This mechanism can
be used to create a file @file{@var{language}/Makefile} from
@file{@var{language}/Makefile.in}, but this is deprecated, building
everything from the single @file{gcc/Makefile} is preferred.
@item gtfiles
If defined, a space-separated list of files that should be scanned by
@file{gengtype.c} to generate the garbage collection tables and routines for
this language.  This excludes the files that are common to all front
ends.  @xref{Type Information}.

@end table

@node Front End Makefile
@subsubsection The Front End @file{Make-lang.in} File

Each language subdirectory contains a @file{Make-lang.in} file.  It contains
targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
setting of @code{language} in @file{config-lang.in}) for the following
values of @code{@var{hook}}, and any other Makefile rules required to
build those targets (which may if necessary use other Makefiles
specified in @code{outputs} in @file{config-lang.in}, although this is
deprecated).  It also adds any testsuite targets that can use the
standard rule in @file{gcc/Makefile.in} to the variable
@code{lang_checks}.

@table @code
@itemx all.cross
@itemx start.encap
@itemx rest.encap
FIXME: exactly what goes in each of these targets?
@item tags
Build an @command{etags} @file{TAGS} file in the language subdirectory
in the source tree.
@item info
Build info documentation for the front end, in the build directory.
This target is only called by @samp{make bootstrap} if a suitable
version of @command{makeinfo} is available, so does not need to check
for this, and should fail if an error occurs.
@item dvi
Build DVI documentation for the front end, in the build directory.
This should be done using @code{$(TEXI2DVI)}, with appropriate
@option{-I} arguments pointing to directories of included files.
@item pdf
Build PDF documentation for the front end, in the build directory.
This should be done using @code{$(TEXI2PDF)}, with appropriate
@option{-I} arguments pointing to directories of included files.
@item html
Build HTML documentation for the front end, in the build directory.
@item man
Build generated man pages for the front end from Texinfo manuals
(@pxref{Man Page Generation}), in the build directory.  This target
is only called if the necessary tools are available, but should ignore
errors so as not to stop the build if errors occur; man pages are
optional and the tools involved may be installed in a broken way.
@item install-common
Install everything that is part of the front end, apart from the
compiler executables listed in @code{compilers} in
@file{config-lang.in}.
@item install-info
Install info documentation for the front end, if it is present in the
source directory.  This target should have dependencies on info files
that should be installed.
@item install-man
Install man pages for the front end.  This target should ignore
errors.
@item install-plugin
Install headers needed for plugins.
@item srcextra
Copies its dependencies into the source directory.  This generally should
be used for generated files such as Bison output files which are not
version-controlled, but should be included in any release tarballs.  This
target will be executed during a bootstrap if
@samp{--enable-generated-files-in-srcdir} was specified as a
@file{configure} option.
@item srcinfo
@itemx srcman
Copies its dependencies into the source directory.  These targets will be
executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
was specified as a @file{configure} option.
@item uninstall
Uninstall files installed by installing the compiler.  This is
currently documented not to be supported, so the hook need not do
anything.
@item mostlyclean
@itemx clean
@itemx distclean
@itemx maintainer-clean
The language parts of the standard GNU
@samp{*clean} targets.  @xref{Standard Targets, , Standard Targets for
Users, standards, GNU Coding Standards}, for details of the standard
targets.  For GCC, @code{maintainer-clean} should delete
all generated files in the source directory that are not version-controlled,
but should not delete anything that is.
@end table

@file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
to a list of host object files that are used by that language.

@node Back End
@subsection Anatomy of a Target Back End

A back end for a target architecture in GCC has the following parts:

@itemize @bullet
@item
A directory @file{@var{machine}} under @file{gcc/config}, containing a
machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
, Machine Descriptions}), header files @file{@var{machine}.h} and
@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
(@pxref{Target Macros, , Target Description Macros and Functions}),
possibly a target Makefile fragment @file{t-@var{machine}}
(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
some other files.  The names of these files may be changed from the
defaults given by explicit specifications in @file{config.gcc}.
@item
If necessary, a file @file{@var{machine}-modes.def} in the
@file{@var{machine}} directory, containing additional machine modes to
represent condition codes.  @xref{Condition Code}, for further details.
@item
An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
directory, containing a list of target-specific options.  You can also
add other option files using the @code{extra_options} variable in
@file{config.gcc}.  @xref{Options}.
@item
Entries in @file{config.gcc} (@pxref{System Config, , The
@file{config.gcc} File}) for the systems with this target
architecture.
@item
Documentation in @file{gcc/doc/invoke.texi} for any command-line
options supported by this target (@pxref{Run-time Target, , Run-time
Target Specification}).  This means both entries in the summary table
of options and details of the individual options.
@item
Documentation in @file{gcc/doc/extend.texi} for any target-specific
attributes supported (@pxref{Target Attributes, , Defining
target-specific uses of @code{__attribute__}}), including where the
same attribute is already supported on some targets, which are
enumerated in the manual.
@item
Documentation in @file{gcc/doc/extend.texi} for any target-specific
pragmas supported.
@item
Documentation in @file{gcc/doc/extend.texi} of any target-specific
built-in functions supported.
@item
Documentation in @file{gcc/doc/extend.texi} of any target-specific
format checking styles supported.
@item
Documentation in @file{gcc/doc/md.texi} of any target-specific
constraint letters (@pxref{Machine Constraints, , Constraints for
Particular Machines}).
@item
A note in @file{gcc/doc/contrib.texi} under the person or people who
contributed the target support.
@item
Entries in @file{gcc/doc/install.texi} for all target triplets
supported with this target architecture, giving details of any special
notes about installation for this target, or saying that there are no
special notes if there are none.
@item
Possibly other support outside the @file{gcc} directory for runtime
libraries.  FIXME: reference docs for this.  The @code{libstdc++} porting
manual needs to be installed as info for this to work, or to be a
chapter of this manual.
@end itemize

If the back end is added to the official GCC source repository, the
following are also necessary:

@itemize @bullet
@item
An entry for the target architecture in @file{readings.html} on the
GCC web site, with any relevant links.
@item
Details of the properties of the back end and target architecture in
@file{backends.html} on the GCC web site.
@item
A news item about the contribution of support for that target
architecture, in @file{index.html} on the GCC web site.
@item
Normally, one or more maintainers of that target listed in
@file{MAINTAINERS}.  Some existing architectures may be unmaintained,
but it would be unusual to add support for a target that does not have
a maintainer when support is added.
@end itemize

@node Testsuites
@chapter Testsuites

GCC contains several testsuites to help maintain compiler quality.
Most of the runtime libraries and language front ends in GCC have
testsuites.  Currently only the C language testsuites are documented
here; FIXME: document the others.

@menu
* Test Idioms::     Idioms used in testsuite code.
* Test Directives:: Directives used within DejaGnu tests.
* Ada Tests::       The Ada language testsuites.
* C Tests::         The C language testsuites.
* libgcj Tests::    The Java library testsuites.
* LTO Testing::     Support for testing link-time optimizations.
* gcov Testing::    Support for testing gcov.
* profopt Testing:: Support for testing profile-directed optimizations.
* compat Testing::  Support for testing binary compatibility.
* Torture Tests::   Support for torture testing using multiple options.
@end menu

@node Test Idioms
@section Idioms Used in Testsuite Code

In general, C testcases have a trailing @file{-@var{n}.c}, starting
with @file{-1.c}, in case other testcases with similar names are added
later.  If the test is a test of some well-defined feature, it should
have a name referring to that feature such as
@file{@var{feature}-1.c}.  If it does not test a well-defined feature
but just happens to exercise a bug somewhere in the compiler, and a
bug report has been filed for this bug in the GCC bug database,
@file{pr@var{bug-number}-1.c} is the appropriate form of name.
Otherwise (for miscellaneous bugs not filed in the GCC bug database),
and previously more generally, test cases are named after the date on
which they were added.  This allows people to tell at a glance whether
a test failure is because of a recently found bug that has not yet
been fixed, or whether it may be a regression, but does not give any
other information about the bug or where discussion of it may be
found.  Some other language testsuites follow similar conventions.

In the @file{gcc.dg} testsuite, it is often necessary to test that an
error is indeed a hard error and not just a warning---for example,
where it is a constraint violation in the C standard, which must
become an error with @option{-pedantic-errors}.  The following idiom,
where the first line shown is line @var{line} of the file and the line
that generates the error, is used for this:

@smallexample
/* @{ dg-bogus "warning" "warning in place of error" @} */
/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
@end smallexample

It may be necessary to check that an expression is an integer constant
expression and has a certain value.  To check that @code{@var{E}} has
value @code{@var{V}}, an idiom similar to the following is used:

@smallexample
char x[((E) == (V) ? 1 : -1)];
@end smallexample

In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
assertions about the types of expressions.  See, for example,
@file{gcc.dg/c99-condexpr-1.c}.  The more subtle uses depend on the
exact rules for the types of conditional expressions in the C
standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.

It is useful to be able to test that optimizations are being made
properly.  This cannot be done in all cases, but it can be done where
the optimization will lead to code being optimized away (for example,
where flow analysis or alias analysis should show that certain code
cannot be called) or to functions not being called because they have
been expanded as built-in functions.  Such tests go in
@file{gcc.c-torture/execute}.  Where code should be optimized away, a
call to a nonexistent function such as @code{link_failure ()} may be
inserted; a definition

@smallexample
#ifndef __OPTIMIZE__
void
link_failure (void)
@{
  abort ();
@}
#endif
@end smallexample

@noindent
will also be needed so that linking still succeeds when the test is
run without optimization.  When all calls to a built-in function
should have been optimized and no calls to the non-built-in version of
the function should remain, that function may be defined as
@code{static} to call @code{abort ()} (although redeclaring a function
as static may not work on all targets).

All testcases must be portable.  Target-specific testcases must have
appropriate code to avoid causing failures on unsupported systems;
unfortunately, the mechanisms for this differ by directory.

FIXME: discuss non-C testsuites here.

@node Test Directives
@section Directives used within DejaGnu tests

@menu
* Directives::  Syntax and descriptions of test directives.
* Selectors:: Selecting targets to which a test applies.
* Effective-Target Keywords:: Keywords describing target attributes.
* Add Options:: Features for @code{dg-add-options}
* Require Support:: Variants of @code{dg-require-@var{support}}
* Final Actions:: Commands for use in @code{dg-final}
@end menu

@node Directives
@subsection Syntax and Descriptions of test directives

Test directives appear within comments in a test source file and begin
with @code{dg-}.  Some of these are defined within DejaGnu and others
are local to the GCC testsuite.

The order in which test directives appear in a test can be important:
directives local to GCC sometimes override information used by the
DejaGnu directives, which know nothing about the GCC directives, so the
DejaGnu directives must precede GCC directives.

Several test directives include selectors (@pxref{Selectors, , })
which are usually preceded by the keyword @code{target} or @code{xfail}.

@subsubsection Specify how to build the test

@table @code
@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
@var{do-what-keyword} specifies how the test is compiled and whether
it is executed.  It is one of:

@table @code
@item preprocess
Compile with @option{-E} to run only the preprocessor.
@item compile
Compile with @option{-S} to produce an assembly code file.
@item assemble
Compile with @option{-c} to produce a relocatable object file.
@item link
Compile, assemble, and link to produce an executable file.
@item run
Produce and run an executable file, which is expected to return
an exit code of 0.
@end table

The default is @code{compile}.  That can be overridden for a set of
tests by redefining @code{dg-do-what-default} within the @code{.exp}
file for those tests.

If the directive includes the optional @samp{@{ target @var{selector} @}}
then the test is skipped unless the target system matches the
@var{selector}.

If @var{do-what-keyword} is @code{run} and the directive includes
the optional @samp{@{ xfail @var{selector} @}} and the selector is met
then the test is expected to fail.  The @code{xfail} clause is ignored
for other values of @var{do-what-keyword}; those tests can use
directive @code{dg-xfail-if}.
@end table

@subsubsection Specify additional compiler options

@table @code
@item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
This DejaGnu directive provides a list of compiler options, to be used
if the target system matches @var{selector}, that replace the default
options used for this set of tests.

@item @{ dg-add-options @var{feature} @dots{} @}
Add any compiler options that are needed to access certain features.
This directive does nothing on targets that enable the features by
default, or that don't provide them at all.  It must come after
all @code{dg-options} directives.
For supported values of @var{feature} see @ref{Add Options, ,}.
@end table

@subsubsection Modify the test timeout value

The normal timeout limit, in seconds, is found by searching the
following in order:

@itemize @bullet
@item the value defined by an earlier @code{dg-timeout} directive in
the test

@item variable @var{tool_timeout} defined by the set of tests

@item @var{gcc},@var{timeout} set in the target board

@item 300
@end itemize

@table @code
@item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
Set the time limit for the compilation and for the execution of the test
to the specified number of seconds.

@item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
Multiply the normal time limit for compilation and execution of the test
by the specified floating-point factor.
@end table

@subsubsection Skip a test for some targets

@table @code
@item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
Arguments @var{include-opts} and @var{exclude-opts} are lists in which
each element is a string of zero or more GCC options.
Skip the test if all of the following conditions are met:
@itemize @bullet
@item the test system is included in @var{selector}

@item for at least one of the option strings in @var{include-opts},
every option from that string is in the set of options with which
the test would be compiled; use @samp{"*"} for an @var{include-opts} list
that matches any options; that is the default if @var{include-opts} is
not specified

@item for each of the option strings in @var{exclude-opts}, at least one
option from that string is not in the set of options with which the test
would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
that is the default if @var{exclude-opts} is not specified
@end itemize

For example, to skip a test if option @code{-Os} is present:

@smallexample
/* @{ dg-skip-if "" @{ *-*-* @}  @{ "-Os" @} @{ "" @} @} */
@end smallexample

To skip a test if both options @code{-O2} and @code{-g} are present:

@smallexample
/* @{ dg-skip-if "" @{ *-*-* @}  @{ "-O2 -g" @} @{ "" @} @} */
@end smallexample

To skip a test if either @code{-O2} or @code{-O3} is present:

@smallexample
/* @{ dg-skip-if "" @{ *-*-* @}  @{ "-O2" "-O3" @} @{ "" @} @} */
@end smallexample

To skip a test unless option @code{-Os} is present:

@smallexample
/* @{ dg-skip-if "" @{ *-*-* @}  @{ "*" @} @{ "-Os" @} @} */
@end smallexample

To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
but not if @code{-fpic} is also present:

@smallexample
/* @{ dg-skip-if "" @{ *-*-* @}  @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
@end smallexample

@item @{ dg-require-effective-target @var{keyword} @}
Skip the test if the test target, including current multilib flags,
is not covered by the effective-target keyword.
This directive must appear after any @code{dg-do} directive in the test
and before any @code{dg-additional-sources} directive.
@xref{Effective-Target Keywords, , }.

@item @{ dg-require-@var{support} args @}
Skip the test if the target does not provide the required support.
These directives must appear after any @code{dg-do} directive in the test
and before any @code{dg-additional-sources} directive.
They require at least one argument, which can be an empty string if the
specific procedure does not examine the argument.
@xref{Require Support, , }, for a complete list of these directives.
@end table

@subsubsection Expect a test to fail for some targets

@table @code
@item  @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
Expect the test to fail if the conditions (which are the same as for
@code{dg-skip-if}) are met.  This does not affect the execute step.

@item  @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
Expect the execute step of a test to fail if the conditions (which are
the same as for @code{dg-skip-if}) are met.
@end table

@subsubsection Expect the test executable to fail

@table @code
@item  @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
Expect the test executable to return a nonzero exit status if the
conditions (which are the same as for @code{dg-skip-if}) are met.
@end table

@subsubsection Verify compiler messages

@table @code
@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
This DejaGnu directive appears on a source line that is expected to get
an error message, or else specifies the source line associated with the
message.  If there is no message for that line or if the text of that
message is not matched by @var{regexp} then the check fails and
@var{comment} is included in the @code{FAIL} message.  The check does
not look for the string @samp{error} unless it is part of @var{regexp}.

@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
This DejaGnu directive appears on a source line that is expected to get
a warning message, or else specifies the source line associated with the
message.  If there is no message for that line or if the text of that
message is not matched by @var{regexp} then the check fails and
@var{comment} is included in the @code{FAIL} message.  The check does
not look for the string @samp{warning} unless it is part of @var{regexp}.

@item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
The line is expected to get a message other than an error or warning.
If there is no message for that line or if the text of that message is
not matched by @var{regexp} then the check fails and @var{comment} is
included in the @code{FAIL} message.

@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
This DejaGnu directive appears on a source line that should not get a
message matching @var{regexp}, or else specifies the source line
associated with the bogus message.  It is usually used with @samp{xfail}
to indicate that the message is a known problem for a particular set of
targets.

@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
This DejaGnu directive indicates that the test is expected to fail due
to compiler messages that are not handled by @samp{dg-error},
@samp{dg-warning} or @samp{dg-bogus}.  For this directive @samp{xfail}
has the same effect as @samp{target}.

@item @{ dg-prune-output @var{regexp} @}
Prune messages matching @var{regexp} from the test output.
@end table

@subsubsection Verify output of the test executable

@table @code
@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
This DejaGnu directive compares @var{regexp} to the combined output
that the test executable writes to @file{stdout} and @file{stderr}.
@end table

@subsubsection Specify additional files for a test

@table @code
@item @{ dg-additional-files "@var{filelist}" @}
Specify additional files, other than source files, that must be copied
to the system where the compiler runs.

@item @{ dg-additional-sources "@var{filelist}" @}
Specify additional source files to appear in the compile line
following the main test file.
@end table

@subsubsection Add checks at the end of a test

@table @code
@item @{ dg-final @{ @var{local-directive} @} @}
This DejaGnu directive is placed within a comment anywhere in the
source file and is processed after the test has been compiled and run.
Multiple @samp{dg-final} commands are processed in the order in which
they appear in the source file.  @xref{Final Actions, , }, for a list
of directives that can be used within @code{dg-final}.
@end table

@node Selectors
@subsection Selecting targets to which a test applies

Several test directives include @var{selector}s to limit the targets
for which a test is run or to declare that a test is expected to fail
on particular targets.

A selector is:
@itemize @bullet
@item one or more target triplets, possibly including wildcard characters
@item a single effective-target keyword (@pxref{Effective-Target Keywords})
@item a logical expression
@end itemize

Depending on the
context, the selector specifies whether a test is skipped and reported
as unsupported or is expected to fail.  Use @samp{*-*-*} to match any
target.

A selector expression appears within curly braces and uses a single
logical operator: one of @samp{!}, @samp{&&}, or @samp{||}.  An
operand is another selector expression, an effective-target keyword,
a single target triplet, or a list of target triplets within quotes or
curly braces.  For example:

@smallexample
@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
@{ target @{ powerpc*-*-* && lp64 @} @}
@{ xfail @{ lp64 || vect_no_align @} @}
@end smallexample

@node Effective-Target Keywords
@subsection Keywords describing target attributes

Effective-target keywords identify sets of targets that support
particular functionality.  They are used to limit tests to be run only
for particular targets, or to specify that particular sets of targets
are expected to fail some tests.

Effective-target keywords are defined in @file{lib/target-supports.exp} in
the GCC testsuite, with the exception of those that are documented as
being local to a particular test directory.

The @samp{effective target} takes into account all of the compiler options
with which the test will be compiled, including the multilib options.
By convention, keywords ending in @code{_nocache} can also include options
specified for the particular test in an earlier @code{dg-options} or
@code{dg-add-options} directive.

@subsubsection Data type sizes

@table @code
@item ilp32
Target has 32-bit @code{int}, @code{long}, and pointers.

@item lp64
Target has 32-bit @code{int}, 64-bit @code{long} and pointers.

@item llp64
Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
and pointers.

@item double64
Target has 64-bit @code{double}.

@item double64plus
Target has @code{double} that is 64 bits or longer.

@item int32plus
Target has @code{int} that is at 32 bits or longer.

@item int16
Target has @code{int} that is 16 bits or shorter.

@item large_double
Target supports @code{double} that is longer than @code{float}.

@item large_long_double
Target supports @code{long double} that is longer than @code{double}.

@item ptr32plus
Target has pointers that are 32 bits or longer.

@item size32plus
Target supports array and structure sizes that are 32 bits or longer.

@item 4byte_wchar_t
Target has @code{wchar_t} that is at least 4 bytes.
@end table

@subsubsection Fortran-specific attributes

@table @code
@item fortran_integer_16
Target supports Fortran @code{integer} that is 16 bytes or longer.

@item fortran_large_int
Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.

@item fortran_large_real
Target supports Fortran @code{real} kinds larger than @code{real(8)}.
@end table

@subsubsection Vector-specific attributes

@table @code
@item vect_condition
Target supports vector conditional operations.

@item vect_double
Target supports hardware vectors of @code{double}.

@item vect_float
Target supports hardware vectors of @code{float}.

@item vect_int
Target supports hardware vectors of @code{int}.

@item vect_int_mult
Target supports a vector widening multiplication of @code{short} operands
into an @code{int} result, or supports promotion (unpacking) from
@code{short} to @code{int} and a non-widening multiplication of @code{int}.

@item vect_long
Target supports hardware vectors of @code{long}.

@item vect_long_long
Target supports hardware vectors of @code{long long}.

@item vect_aligned_arrays
Target aligns arrays to vector alignment boundary.

@item vect_hw_misalign
Target supports a vector misalign access.

@item vect_no_align
Target does not support a vector alignment mechanism.

@item vect_no_int_max
Target does not support a vector max instruction on @code{int}.

@item vect_no_int_add
Target does not support a vector add instruction on @code{int}.

@item vect_no_bitwise
Target does not support vector bitwise instructions.

@item vect_char_mult
Target supports @code{vector char} multiplication.

@item vect_short_mult
Target supports @code{vector short} multiplication.

@item vect_int_mult
Target supports @code{vector int} multiplication.

@item vect_extract_even_odd
Target supports vector even/odd element extraction.

@item vect_extract_even_odd_wide
Target supports vector even/odd element extraction of vectors with elements
@code{SImode} or larger.

@item vect_interleave
Target supports vector interleaving.

@item vect_strided
Target supports vector interleaving and extract even/odd.

@item vect_strided_wide
Target supports vector interleaving and extract even/odd for wide
element types.

@item vect_perm
Target supports vector permutation.

@item vect_shift
Target supports a hardware vector shift operation.

@item vect_widen_sum_hi_to_si
Target supports a vector widening summation of @code{short} operands
into @code{int} results, or can promote (unpack) from @code{short}
to @code{int}.

@item vect_widen_sum_qi_to_hi
Target supports a vector widening summation of @code{char} operands
into @code{short} results, or can promote (unpack) from @code{char}
to @code{short}.

@item vect_widen_sum_qi_to_si
Target supports a vector widening summation of @code{char} operands
into @code{int} results.

@item vect_widen_mult_qi_to_hi
Target supports a vector widening multiplication of @code{char} operands
into @code{short} results, or can promote (unpack) from @code{char} to
@code{short} and perform non-widening multiplication of @code{short}.

@item vect_widen_mult_hi_to_si
Target supports a vector widening multiplication of @code{short} operands
into @code{int} results, or can promote (unpack) from @code{short} to
@code{int} and perform non-widening multiplication of @code{int}.

@item vect_sdot_qi
Target supports a vector dot-product of @code{signed char}.

@item vect_udot_qi
Target supports a vector dot-product of @code{unsigned char}.

@item vect_sdot_hi
Target supports a vector dot-product of @code{signed short}.

@item vect_udot_hi
Target supports a vector dot-product of @code{unsigned short}.

@item vect_pack_trunc
Target supports a vector demotion (packing) of @code{short} to @code{char}
and from @code{int} to @code{short} using modulo arithmetic.

@item vect_unpack
Target supports a vector promotion (unpacking) of @code{char} to @code{short}
and from @code{char} to @code{int}.

@item vect_intfloat_cvt
Target supports conversion from @code{signed int} to @code{float}.

@item vect_uintfloat_cvt
Target supports conversion from @code{unsigned int} to @code{float}.

@item vect_floatint_cvt
Target supports conversion from @code{float} to @code{signed int}.

@item vect_floatuint_cvt
Target supports conversion from @code{float} to @code{unsigned int}.
@end table

@subsubsection Thread Local Storage attributes

@table @code
@item tls
Target supports thread-local storage.

@item tls_native
Target supports native (rather than emulated) thread-local storage.

@item tls_runtime
Test system supports executing TLS executables.
@end table

@subsubsection Decimal floating point attributes

@table @code
@item dfp
Targets supports compiling decimal floating point extension to C.

@item dfp_nocache
Including the options used to compile this particular test, the
target supports compiling decimal floating point extension to C.

@item dfprt
Test system can execute decimal floating point tests.

@item dfprt_nocache
Including the options used to compile this particular test, the
test system can execute decimal floating point tests.

@item hard_dfp
Target generates decimal floating point instructions with current options.
@end table

@subsubsection ARM-specific attributes

@table @code
@item arm32
ARM target generates 32-bit code.

@item arm_eabi
ARM target adheres to the ABI for the ARM Architecture.

@item arm_hard_vfp_ok
ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
Some multilibs may be incompatible with these options.

@item arm_iwmmxt_ok
ARM target supports @code{-mcpu=iwmmxt}.
Some multilibs may be incompatible with this option.

@item arm_neon
ARM target supports generating NEON instructions.

@item arm_neon_hw
Test system supports executing NEON instructions.

@item arm_neon_ok
ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp}.
Some multilibs may be incompatible with these options.

@item arm_thumb1_ok
ARM target generates Thumb-1 code for @code{-mthumb}.

@item arm_thumb2_ok
ARM target generates Thumb-2 code for @code{-mthumb}.

@item arm_vfp_ok
ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
Some multilibs may be incompatible with these options.
@end table

@subsubsection MIPS-specific attributes

@table @code
@item mips64
MIPS target supports 64-bit instructions.

@item nomips16
MIPS target does not produce MIPS16 code.

@item mips16_attribute
MIPS target can generate MIPS16 code.

@item mips_loongson
MIPS target is a Loongson-2E or -2F target using an ABI that supports
the Loongson vector modes.

@item mips_newabi_large_long_double
MIPS target supports @code{long double} larger than @code{double}
when using the new ABI.

@item mpaired_single
MIPS target supports @code{-mpaired-single}.
@end table

@subsubsection PowerPC-specific attributes

@table @code
@item powerpc64
Test system supports executing 64-bit instructions.

@item powerpc_altivec
PowerPC target supports AltiVec.

@item powerpc_altivec_ok
PowerPC target supports @code{-maltivec}.

@item powerpc_fprs
PowerPC target supports floating-point registers.

@item powerpc_hard_double
PowerPC target supports hardware double-precision floating-point.

@item powerpc_ppu_ok
PowerPC target supports @code{-mcpu=cell}.

@item powerpc_spe
PowerPC target supports PowerPC SPE.

@item powerpc_spe_nocache
Including the options used to compile this particular test, the
PowerPC target supports PowerPC SPE.

@item powerpc_spu
PowerPC target supports PowerPC SPU.

@item spu_auto_overlay
SPU target has toolchain that supports automatic overlay generation.

@item powerpc_vsx_ok
PowerPC target supports @code{-mvsx}.

@item powerpc_405_nocache
Including the options used to compile this particular test, the
PowerPC target supports PowerPC 405.

@item vmx_hw
PowerPC target supports executing AltiVec instructions.
@end table

@subsubsection Other hardware attributes

@table @code
@item avx
Target supports compiling AVX instructions.

@item cell_hw
Test system can execute AltiVec and Cell PPU instructions.

@item coldfire_fpu
Target uses a ColdFire FPU.

@item hard_float
Target supports FPU instructions.

@item sync_char_short
Target supports atomic operations on @code{char} and @code{short}.

@item sync_int_long
Target supports atomic operations on @code{int} and @code{long}.

@item ultrasparc_hw
Test environment appears to run executables on a simulator that
accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
or @code{EM_SPARCV9} executables.

@item vect_cmdline_needed
Target requires a command line argument to enable a SIMD instruction set.
@end table

@subsubsection Environment attributes

@table @code
@item c
The language for the compiler under test is C.

@item c++
The language for the compiler under test is C++.

@item c99_runtime
Target provides a full C99 runtime.

@item correct_iso_cpp_string_wchar_protos
Target @code{string.h} and @code{wchar.h} headers provide C++ required
overloads for @code{strchr} etc. functions.

@item dummy_wcsftime
Target uses a dummy @code{wcsftime} function that always returns zero.

@item fd_truncate
Target can truncate a file from a file descriptor, as used by
@file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or
@code{chsize}.

@item freestanding
Target is @samp{freestanding} as defined in section 4 of the C99 standard.
Effectively, it is a target which supports no extra headers or libraries
other than what is considered essential.

@item init_priority
Target supports constructors with initialization priority arguments.

@item inttypes_types
Target has the basic signed and unsigned types in @code{inttypes.h}.
This is for tests that GCC's notions of these types agree with those
in the header, as some systems have only @code{inttypes.h}.

@item lax_strtofp
Target might have errors of a few ULP in string to floating-point
conversion functions and overflow is not always detected correctly by
those functions.

@item newlib
Target supports Newlib.

@item pow10
Target provides @code{pow10} function.

@item pthread
Target can compile using @code{pthread.h} with no errors or warnings.

@item pthread_h
Target has @code{pthread.h}.

@item simulator
Test system runs executables on a simulator (i.e. slowly) rather than
hardware (i.e. fast).

@item stdint_types
Target has the basic signed and unsigned C types in @code{stdint.h}.
This will be obsolete when GCC ensures a working @code{stdint.h} for
all targets.

@item trampolines
Target supports trampolines.

@item uclibc
Target supports uClibc.

@item unwrapped
Target does not use a status wrapper.

@item vxworks_kernel
Target is a VxWorks kernel.

@item vxworks_rtp
Target is a VxWorks RTP.

@item wchar
Target supports wide characters.
@end table

@subsubsection Other attributes

@table @code
@item automatic_stack_alignment
Target supports automatic stack alignment.

@item cxa_atexit
Target uses @code{__cxa_atexit}.

@item default_packed
Target has packed layout of structure members by default.

@item fgraphite
Target supports Graphite optimizations.

@item fixed_point
Target supports fixed-point extension to C.

@item fopenmp
Target supports OpenMP via @option{-fopenmp}.

@item fpic
Target supports @option{-fpic} and @option{-fPIC}.

@item freorder
Target supports @option{-freorder-blocks-and-partition}.

@item fstack_protector
Target supports @option{-fstack-protector}.

@item gc_sections
Target supports @option{--gc-sections}.

@item keeps_null_pointer_checks
Target keeps null pointer checks, either due to the use of
@option{-fno-delete-null-pointer-checks} or hardwired into the target.

@item lto
Compiler has been configured to support link-time optimization (LTO).

@item named_sections
Target supports named sections.

@item natural_alignment_32
Target uses natural alignment (aligned to type size) for types of
32 bits or less.

@item target_natural_alignment_64
Target uses natural alignment (aligned to type size) for types of
64 bits or less.

@item nonpic
Target does not generate PIC by default.

@item pcc_bitfield_type_matters
Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.

@item pe_aligned_commons
Target supports @option{-mpe-aligned-commons}.

@item section_anchors
Target supports section anchors.

@item short_enums
Target defaults to short enums.

@item static
Target supports @option{-static}.

@item static_libgfortran
Target supports statically linking @samp{libgfortran}.

@item string_merging
Target supports merging string constants at link time.

@item ucn
Target supports compiling and assembling UCN.

@item ucn_nocache
Including the options used to compile this particular test, the
target supports compiling and assembling UCN.

@item unaligned_stack
Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
or equal to the required vector alignment.

@item vector_alignment_reachable
Vector alignment is reachable for types of 32 bits or less.

@item vector_alignment_reachable_for_64bit
Vector alignment is reachable for types of 64 bits or less.

@item wchar_t_char16_t_compatible
Target supports @code{wchar_t} that is compatible with @code{char16_t}.

@item wchar_t_char32_t_compatible
Target supports @code{wchar_t} that is compatible with @code{char32_t}.
@end table

@subsubsection Local to tests in @code{gcc.target/i386}

@table @code
@item aes
Target supports compiling @code{aes} instructions.

@item fma4
Target supports compiling @code{fma4} instructions.

@item ms_hook_prologue
Target supports attribute @code{ms_hook_prologue}.

@item pclmul
Target supports compiling @code{pclmul} instructions.

@item sse4
Target supports compiling @code{sse4} instructions.

@item sse4a
Target supports compiling @code{sse4a} instructions.

@item ssse3
Target supports compiling @code{ssse3} instructions.

@item vaes
Target supports compiling @code{vaes} instructions.

@item vpclmul
Target supports compiling @code{vpclmul} instructions.

@item xop
Target supports compiling @code{xop} instructions.
@end table

@subsubsection Local to tests in @code{gcc.target/spu/ea}

@table @code
@item ealib
Target @code{__ea} library functions are available.
@end table

@subsubsection Local to tests in @code{gcc.test-framework}

@table @code
@item no
Always returns 0.

@item yes
Always returns 1.
@end table

@node Add Options
@subsection Features for @code{dg-add-options}

The supported values of @var{feature} for directive @code{dg-add-options}
are:

@table @code
@item bind_pic_locally
Add the target-specific flags needed to enable functions to bind
locally when using pic/PIC passes in the testsuite.

@item c99_runtime
Add the target-specific flags needed to access the C99 runtime.

@item ieee
Add the target-specific flags needed to enable full IEEE
compliance mode.

@item mips16_attribute
@code{mips16} function attributes.
Only MIPS targets support this feature, and only then in certain modes.
@end table

@node Require Support
@subsection Variants of @code{dg-require-@var{support}}

A few of the @code{dg-require} directives take arguments.

@table @code
@item dg-require-iconv @var{codeset}
Skip the test if the target does not support iconv.  @var{codeset} is
the codeset to convert to.

@item dg-require-profiling @var{profopt}
Skip the test if the target does not support profiling with option
@var{profopt}.

@item dg-require-visibility @var{vis}
Skip the test if the target does not support the @code{visibility} attribute.
If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
checked, for @code{visibility("@var{vis}")} otherwise.
@end table

The original @code{dg-require} directives were defined before there
was support for effective-target keywords.  The directives that do not
take arguments could be replaced with effective-target keywords.

@table @code
@item dg-require-alias ""
Skip the test if the target does not support the @samp{alias} attribute.

@item dg-require-compat-dfp ""
Skip this test unless both compilers in a @file{compat} testsuite
support decimal floating point.

@item dg-require-cxa-atexit ""
Skip the test if the target does not support @code{__cxa_atexit}.
This is equivalent to @code{dg-require-effective-target cxa_atexit}.

@item dg-require-dll ""
Skip the test if the target does not support DLL attributes.

@item dg-require-fork ""
Skip the test if the target does not support @code{fork}.

@item dg-require-gc-sections ""
Skip the test if the target's linker does not support the
@code{--gc-sections} flags.
This is equivalent to @code{dg-require-effective-target gc-sections}.

@item dg-require-host-local ""
Skip the test if the host is remote, rather than the same as the build
system.  Some tests are incompatible with DejaGnu's handling of remote
hosts, which involves copying the source file to the host and compiling
it with a relative path and "@code{-o a.out}".

@item dg-require-mkfifo ""
Skip the test if the target does not support @code{mkfifo}.

@item dg-require-named-sections ""
Skip the test is the target does not support named sections.
This is equivalent to @code{dg-require-effective-target named_sections}.

@item dg-require-weak ""
Skip the test if the target does not support weak symbols.

@item dg-require-weak-override ""
Skip the test if the target does not support overriding weak symbols.
@end table

@node Final Actions
@subsection Commands for use in @code{dg-final}

The GCC testsuite defines the following directives to be used within
@code{dg-final}.

@subsubsection Scan a particular file

@table @code
@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
Passes if @var{regexp} matches text in @var{filename}.
@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
Passes if @var{regexp} does not match text in @var{filename}.
@item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
Passes if @var{regexp} matches in Fortran module @var{module}.
@end table

@subsubsection Scan the assembly output

@table @code
@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} matches text in the test's assembler output.

@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} does not match text in the test's assembler output.

@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} is matched exactly @var{num} times in the test's
assembler output.

@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} matches text in the test's demangled assembler output.

@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} does not match text in the test's demangled assembler
output.

@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
Passes if @var{symbol} is defined as a hidden symbol in the test's
assembly output.

@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
Passes if @var{symbol} is not defined as a hidden symbol in the test's
assembly output.
@end table

@subsubsection Scan optimization dump files

These commands are available for @var{kind} of @code{tree}, @code{rtl},
and @code{ipa}.

@table @code
@item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.

@item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} does not match text in the dump file with suffix
@var{suffix}.

@item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} is found exactly @var{num} times in the dump file
with suffix @var{suffix}.

@item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} matches demangled text in the dump file with
suffix @var{suffix}.

@item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} does not match demangled text in the dump file with
suffix @var{suffix}.
@end table

@subsubsection Verify that an output files exists or not

@table @code
@item output-exists [@{ target/xfail @var{selector} @}]
Passes if compiler output file exists.

@item output-exists-not [@{ target/xfail @var{selector} @}]
Passes if compiler output file does not exist.
@end table

@subsubsection Check for LTO tests

@table @code
@item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
Passes if the pattern is present in the final executable.
@end table

@subsubsection Checks for @command{gcov} tests

@table @code
@item run-gcov @var{sourcefile}
Check line counts in @command{gcov} tests.

@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
Check branch and/or call counts, in addition to line counts, in
@command{gcov} tests.
@end table

@subsubsection Clean up generated test files

@table @code
@item cleanup-coverage-files
Removes coverage data files generated for this test.

@item cleanup-ipa-dump @var{suffix}
Removes IPA dump files generated for this test.

@item cleanup-modules
Removes Fortran module files generated for this test.

@item cleanup-profile-file
Removes profiling files generated for this test.

@item cleanup-repo-files
Removes files generated for this test for @option{-frepo}.

@item cleanup-rtl-dump @var{suffix}
Removes RTL dump files generated for this test.

@item cleanup-saved-temps
Removes files for the current test which were kept for @option{-save-temps}.

@item cleanup-tree-dump @var{suffix}
Removes tree dump files matching @var{suffix} which were generated for
this test.
@end table

@node Ada Tests
@section Ada Language Testsuites

The Ada testsuite includes executable tests from the ACATS 2.5
testsuite, publicly available at
@uref{http://www.adaic.org/compilers/acats/2.5}.

These tests are integrated in the GCC testsuite in the
@file{ada/acats} directory, and
enabled automatically when running @code{make check}, assuming
the Ada language has been enabled when configuring GCC@.

You can also run the Ada testsuite independently, using
@code{make check-ada}, or run a subset of the tests by specifying which
chapter to run, e.g.:

@smallexample
$ make check-ada CHAPTERS="c3 c9"
@end smallexample

The tests are organized by directory, each directory corresponding to
a chapter of the Ada Reference Manual.  So for example, @file{c9} corresponds
to chapter 9, which deals with tasking features of the language.

There is also an extra chapter called @file{gcc} containing a template for
creating new executable tests, although this is deprecated in favor of
the @file{gnat.dg} testsuite.

The tests are run using two @command{sh} scripts: @file{run_acats} and
@file{run_all.sh}.  To run the tests using a simulator or a cross
target, see the small
customization section at the top of @file{run_all.sh}.

These tests are run using the build tree: they can be run without doing
a @code{make install}.

@node C Tests
@section C Language Testsuites

GCC contains the following C language testsuites, in the
@file{gcc/testsuite} directory:

@table @file
@item gcc.dg
This contains tests of particular features of the C compiler, using the
more modern @samp{dg} harness.  Correctness tests for various compiler
features should go here if possible.

Magic comments determine whether the file
is preprocessed, compiled, linked or run.  In these tests, error and warning
message texts are compared against expected texts or regular expressions
given in comments.  These tests are run with the options @samp{-ansi -pedantic}
unless other options are given in the test.  Except as noted below they
are not run with multiple optimization options.
@item gcc.dg/compat
This subdirectory contains tests for binary compatibility using
@file{lib/compat.exp}, which in turn uses the language-independent support
(@pxref{compat Testing, , Support for testing binary compatibility}).
@item gcc.dg/cpp
This subdirectory contains tests of the preprocessor.
@item gcc.dg/debug
This subdirectory contains tests for debug formats.  Tests in this
subdirectory are run for each debug format that the compiler supports.
@item gcc.dg/format
This subdirectory contains tests of the @option{-Wformat} format
checking.  Tests in this directory are run with and without
@option{-DWIDE}.
@item gcc.dg/noncompile
This subdirectory contains tests of code that should not compile and
does not need any special compilation options.  They are run with
multiple optimization options, since sometimes invalid code crashes
the compiler with optimization.
@item gcc.dg/special
FIXME: describe this.

@item gcc.c-torture
This contains particular code fragments which have historically broken easily.
These tests are run with multiple optimization options, so tests for features
which only break at some optimization levels belong here.  This also contains
tests to check that certain optimizations occur.  It might be worthwhile to
separate the correctness tests cleanly from the code quality tests, but
it hasn't been done yet.

@item gcc.c-torture/compat
FIXME: describe this.

This directory should probably not be used for new tests.
@item gcc.c-torture/compile
This testsuite contains test cases that should compile, but do not
need to link or run.  These test cases are compiled with several
different combinations of optimization options.  All warnings are
disabled for these test cases, so this directory is not suitable if
you wish to test for the presence or absence of compiler warnings.
While special options can be set, and tests disabled on specific
platforms, by the use of @file{.x} files, mostly these test cases
should not contain platform dependencies.  FIXME: discuss how defines
such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
@item gcc.c-torture/execute
This testsuite contains test cases that should compile, link and run;
otherwise the same comments as for @file{gcc.c-torture/compile} apply.
@item gcc.c-torture/execute/ieee
This contains tests which are specific to IEEE floating point.
@item gcc.c-torture/unsorted
FIXME: describe this.

This directory should probably not be used for new tests.
@item gcc.misc-tests
This directory contains C tests that require special handling.  Some
of these tests have individual expect files, and others share
special-purpose expect files:

@table @file
@item @code{bprob*.c}
Test @option{-fbranch-probabilities} using
@file{gcc.misc-tests/bprob.exp}, which
in turn uses the generic, language-independent framework
(@pxref{profopt Testing, , Support for testing profile-directed
optimizations}).

@item @code{gcov*.c}
Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
language-independent support (@pxref{gcov Testing, , Support for testing gcov}).

@item @code{i386-pf-*.c}
Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
@end table

@item gcc.test-framework
@table @file
@item @code{dg-*.c}
Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
@end table

@end table

FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
test cases and magic comments more.

@node libgcj Tests
@section The Java library testsuites.

Runtime tests are executed via @samp{make check} in the
@file{@var{target}/libjava/testsuite} directory in the build
tree.  Additional runtime tests can be checked into this testsuite.

Regression testing of the core packages in libgcj is also covered by the
Mauve testsuite.  The @uref{http://sourceware.org/mauve/,,Mauve Project}
develops tests for the Java Class Libraries.  These tests are run as part
of libgcj testing by placing the Mauve tree within the libjava testsuite
sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
the location of that tree when invoking @samp{make}, as in
@samp{make MAUVEDIR=~/mauve check}.

To detect regressions, a mechanism in @file{mauve.exp} compares the
failures for a test run against the list of expected failures in
@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
Update this file when adding new failing tests to Mauve, or when fixing
bugs in libgcj that had caused Mauve test failures.

We encourage developers to contribute test cases to Mauve.

@node LTO Testing
@section Support for testing link-time optimizations

Tests for link-time optimizations usually require multiple source files
that are compiled separately, perhaps with different sets of options.
There are several special-purpose test directives used for these tests.

@table @code
@item @{ dg-lto-do @var{do-what-keyword} @}
@var{do-what-keyword} specifies how the test is compiled and whether
it is executed.  It is one of:

@table @code
@item assemble
Compile with @option{-c} to produce a relocatable object file.
@item link
Compile, assemble, and link to produce an executable file.
@item run
Produce and run an executable file, which is expected to return
an exit code of 0.
@end table

The default is @code{assemble}.  That can be overridden for a set of
tests by redefining @code{dg-do-what-default} within the @code{.exp}
file for those tests.

Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
@samp{target} or @samp{xfail} list.  Use @code{dg-skip-if},
@code{dg-xfail-if}, or @code{dg-xfail-run-if}.

@item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
This directive provides a list of one or more sets of compiler options
to override @var{LTO_OPTIONS}.  Each test will be compiled and run with
each of these sets of options.

@item @{ dg-extra-ld-options @var{options} @}
This directive adds @var{options} to the linker options used.

@item @{ dg-suppress-ld-options @var{options} @}
This directive removes @var{options} from the set of linker options used.
@end table

@node gcov Testing
@section Support for testing @command{gcov}

Language-independent support for testing @command{gcov}, and for checking
that branch profiling produces expected values, is provided by the
expect file @file{lib/gcov.exp}.  @command{gcov} tests also rely on procedures
in @file{lib/gcc-dg.exp} to compile and run the test program.  A typical
@command{gcov} test contains the following DejaGnu commands within comments:

@smallexample
@{ dg-options "-fprofile-arcs -ftest-coverage" @}
@{ dg-do run @{ target native @} @}
@{ dg-final @{ run-gcov sourcefile @} @}
@end smallexample

Checks of @command{gcov} output can include line counts, branch percentages,
and call return percentages.  All of these checks are requested via
commands that appear in comments in the test's source file.
Commands to check line counts are processed by default.
Commands to check branch percentages and call return percentages are
processed if the @command{run-gcov} command has arguments @code{branches}
or @code{calls}, respectively.  For example, the following specifies
checking both, as well as passing @option{-b} to @command{gcov}:

@smallexample
@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
@end smallexample

A line count command appears within a comment on the source line
that is expected to get the specified count and has the form
@code{count(@var{cnt})}.  A test should only check line counts for
lines that will get the same count for any architecture.

Commands to check branch percentages (@code{branch}) and call
return percentages (@code{returns}) are very similar to each other.
A beginning command appears on or before the first of a range of
lines that will report the percentage, and the ending command
follows that range of lines.  The beginning command can include a
list of percentages, all of which are expected to be found within
the range.  A range is terminated by the next command of the same
kind.  A command @code{branch(end)} or @code{returns(end)} marks
the end of a range without starting a new one.  For example:

@smallexample
if (i > 10 && j > i && j < 20)  /* @r{branch(27 50 75)} */
                                /* @r{branch(end)} */
  foo (i, j);
@end smallexample

For a call return percentage, the value specified is the
percentage of calls reported to return.  For a branch percentage,
the value is either the expected percentage or 100 minus that
value, since the direction of a branch can differ depending on the
target or the optimization level.

Not all branches and calls need to be checked.  A test should not
check for branches that might be optimized away or replaced with
predicated instructions.  Don't check for calls inserted by the
compiler or ones that might be inlined or optimized away.

A single test can check for combinations of line counts, branch
percentages, and call return percentages.  The command to check a
line count must appear on the line that will report that count, but
commands to check branch percentages and call return percentages can
bracket the lines that report them.

@node profopt Testing
@section Support for testing profile-directed optimizations

The file @file{profopt.exp} provides language-independent support for
checking correct execution of a test built with profile-directed
optimization.  This testing requires that a test program be built and
executed twice.  The first time it is compiled to generate profile
data, and the second time it is compiled to use the data that was
generated during the first execution.  The second execution is to
verify that the test produces the expected results.

To check that the optimization actually generated better code, a
test can be built and run a third time with normal optimizations to
verify that the performance is better with the profile-directed
optimizations.  @file{profopt.exp} has the beginnings of this kind
of support.

@file{profopt.exp} provides generic support for profile-directed
optimizations.  Each set of tests that uses it provides information
about a specific optimization:

@table @code
@item tool
tool being tested, e.g., @command{gcc}

@item profile_option
options used to generate profile data

@item feedback_option
options used to optimize using that profile data

@item prof_ext
suffix of profile data files

@item PROFOPT_OPTIONS
list of options with which to run each test, similar to the lists for
torture tests

@item @{ dg-final-generate @{ @var{local-directive} @} @}
This directive is similar to @code{dg-final}, but the
@var{local-directive} is run after the generation of profile data.

@item @{ dg-final-use @{ @var{local-directive} @} @}
The @var{local-directive} is run after the profile data have been
used.
@end table

@node compat Testing
@section Support for testing binary compatibility

The file @file{compat.exp} provides language-independent support for
binary compatibility testing.  It supports testing interoperability of
two compilers that follow the same ABI, or of multiple sets of
compiler options that should not affect binary compatibility.  It is
intended to be used for testsuites that complement ABI testsuites.

A test supported by this framework has three parts, each in a
separate source file: a main program and two pieces that interact
with each other to split up the functionality being tested.

@table @file
@item @var{testname}_main.@var{suffix}
Contains the main program, which calls a function in file
@file{@var{testname}_x.@var{suffix}}.

@item @var{testname}_x.@var{suffix}
Contains at least one call to a function in
@file{@var{testname}_y.@var{suffix}}.

@item @var{testname}_y.@var{suffix}
Shares data with, or gets arguments from,
@file{@var{testname}_x.@var{suffix}}.
@end table

Within each test, the main program and one functional piece are
compiled by the GCC under test.  The other piece can be compiled by
an alternate compiler.  If no alternate compiler is specified,
then all three source files are all compiled by the GCC under test.
You can specify pairs of sets of compiler options.  The first element
of such a pair specifies options used with the GCC under test, and the
second element of the pair specifies options used with the alternate
compiler.  Each test is compiled with each pair of options.

@file{compat.exp} defines default pairs of compiler options.
These can be overridden by defining the environment variable
@env{COMPAT_OPTIONS} as:

@smallexample
COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
  @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
@end smallexample

where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
used by the compiler under test and @var{alti} used by the alternate
compiler.  For example, with
@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
the test is first built with @option{-g -O0} by the compiler under
test and with @option{-O3} by the alternate compiler.  The test is
built a second time using @option{-fpic} by the compiler under test
and @option{-fPIC -O2} by the alternate compiler.

An alternate compiler is specified by defining an environment
variable to be the full pathname of an installed compiler; for C
define @env{ALT_CC_UNDER_TEST}, and for C++ define
@env{ALT_CXX_UNDER_TEST}.  These will be written to the
@file{site.exp} file used by DejaGnu.  The default is to build each
test with the compiler under test using the first of each pair of
compiler options from @env{COMPAT_OPTIONS}.  When
@env{ALT_CC_UNDER_TEST} or
@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
the compiler under test but with combinations of the options from
@env{COMPAT_OPTIONS}.

To run only the C++ compatibility suite using the compiler under test
and another version of GCC using specific compiler options, do the
following from @file{@var{objdir}/gcc}:

@smallexample
rm site.exp
make -k \
  ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
  COMPAT_OPTIONS="@var{lists as shown above}" \
  check-c++ \
  RUNTESTFLAGS="compat.exp"
@end smallexample

A test that fails when the source files are compiled with different
compilers, but passes when the files are compiled with the same
compiler, demonstrates incompatibility of the generated code or
runtime support.  A test that fails for the alternate compiler but
passes for the compiler under test probably tests for a bug that was
fixed in the compiler under test but is present in the alternate
compiler.

The binary compatibility tests support a small number of test framework
commands that appear within comments in a test file.

@table @code
@item dg-require-*
These commands can be used in @file{@var{testname}_main.@var{suffix}}
to skip the test if specific support is not available on the target.

@item dg-options
The specified options are used for compiling this particular source
file, appended to the options from @env{COMPAT_OPTIONS}.  When this
command appears in @file{@var{testname}_main.@var{suffix}} the options
are also used to link the test program.

@item dg-xfail-if
This command can be used in a secondary source file to specify that
compilation is expected to fail for particular options on particular
targets.
@end table

@node Torture Tests
@section Support for torture testing using multiple options

Throughout the compiler testsuite there are several directories whose
tests are run multiple times, each with a different set of options.
These are known as torture tests.
@file{lib/torture-options.exp} defines procedures to
set up these lists:

@table @code
@item torture-init
Initialize use of torture lists.
@item set-torture-options
Set lists of torture options to use for tests with and without loops.
Optionally combine a set of torture options with a set of other
options, as is done with Objective-C runtime options.
@item torture-finish
Finalize use of torture lists.
@end table

The @file{.exp} file for a set of tests that use torture options must
include calls to these three procedures if:

@itemize @bullet
@item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.

@item It calls @var{$@{tool@}}@code{-torture} or
@var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
@code{fortran}, or @code{objc}.

@item It calls @code{dg-pch}.
@end itemize

It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
to call the torture procedures if the tests should use the list in
@var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.

Most uses of torture options can override the default lists by defining
@var{TORTURE_OPTIONS} or add to the default list by defining
@var{ADDITIONAL_TORTURE_OPTIONS}.  Define these in a @file{.dejagnurc}
file or add them to the @file{site.exp} file; for example

@smallexample
set ADDITIONAL_TORTURE_OPTIONS  [list \
  @{ -O2 -ftree-loop-linear @} \
  @{ -O2 -fpeel-loops @} ]
@end smallexample