-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathmcpp-manual.html
4617 lines (4339 loc) · 394 KB
/
mcpp-manual.html
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
<html>
<head>
<meta http-equiv="Content-Type" content="text/html">
<style> pre {color: navy} tt {color: maroon} </style>
<style> table {border-collapse: separate; border-spacing: 0px; empty-cells: show; background-color: #f0f0ff} </style>
<style> th, td {text-align: left; padding-left: 15px; padding-right: 15px} </style>
</head>
<body>
<div align="center">
<h1>MCPP-MANUAL</h1>
<h2>== How to Use MCPP ==</h2>
</div>
<div align="right">
<h4>for V.2.7.2 (2008/11)<br>
Kiyoshi Matsui ([email protected])</h4>
</div>
<div align="center">
<h2>Contents</h2>
</div>
<dl><dt><a name="toc.1" href="#1">1. Overview</a>
<dd><a name="toc.1.1" href="#1.1">1.1. High Portability</a>
<dd><a name="toc.1.2" href="#1.2">1.2. Standard C Mode with Highest Conformance and Other Modes</a>
<dd><a name="toc.1.3" href="#1.3">1.3. Notations in this Manual</a>
<br>
<br>
<dt><a name="toc.2" href="#2">2. Invocation Options and Environment Settings</a>
<dd><a name="toc.2.1" href="#2.1">2.1. Two Kinds of Build and Five Behavioral Modes</a>
<dd><a name="toc.2.2" href="#2.2">2.2. How to Specify Invocation Options</a>
<dd><a name="toc.2.3" href="#2.3">2.3. Common Options</a>
<dd><a name="toc.2.4" href="#2.4">2.4. Options by <b>mcpp</b> Behavioral Modes</a>
<dd><a name="toc.2.5" href="#2.5">2.5. Common Options Except for Some Compiler Systems</a>
<dd><a name="toc.2.6" href="#2.6">2.6. Options by Compiler System</a>
<dd><a name="toc.2.7" href="#2.7">2.7. Environment Variables</a>
<dd><a name="toc.2.8" href="#2.8">2.8. Multi-Byte Character Encodings</a>
<dd><a name="toc.2.9" href="#2.9">2.9. How to Use <b>mcpp</b> in One-Pass Compilers</a>
<dd><dl><dt><a name="toc.2.10" href="#2.10">2.10. How to Use <b>mcpp</b> in IDE</a>
<dd><a name="toc.2.10.1" href="#2.10.1">2.10.1. How to Make <b>mcpp</b> available in Visual C++ IDE</a>
<dd><a name="toc.2.10.2" href="#2.10.2">2.10.2. How to Make <b>mcpp</b> available in Mac OS X / Xcode.app</a></dl>
<br>
<dt><a name="toc.3" href="#3">3. Enhancement and Compatibility</a>
<dd><dl><dt><a name="toc.3.1" href="#3.1">3.1. #pragma MCPP put_defines, #pragma MCPP preprocess and others</a>
<dd><a name="toc.3.1.1" href="#3.1.1">3.1.1. Pre-preprocessing of Header File</a></dl>
<dd><dl><dt><a name="toc.3.2" href="#3.2">3.2. #pragma once</a>
<dd><a name="toc.3.2.1" href="#3.2.1">3.2.1. Tool to Write #pragma once to Header Files</a></dl>
<dd><a name="toc.3.3" href="#3.3">3.3. #pragma MCPP warning, #include_next, #warning</a>
<dd><a name="toc.3.4" href="#3.4">3.4. #pragma MCPP push_macro, #pragma __setlocale and others</a>
<dd><dl><dt><a name="toc.3.5" href="#3.5">3.5. #pragma MCPP debug, #pragma MCPP end_debug, #debug, #end_debug</a>
<dd><a name="toc.3.5.1" href="#3.5.1">3.5.1. #pragma MCPP debug path, #debug path</a>
<dd><a name="toc.3.5.2" href="#3.5.2">3.5.2. #pragma MCPP debug token, #debug token</a>
<dd><a name="toc.3.5.3" href="#3.5.3">3.5.3. #pragma MCPP debug expand, #debug expand</a>
<dd><a name="toc.3.5.4" href="#3.5.4">3.5.4. #pragma MCPP debug if, #debug if</a>
<dd><a name="toc.3.5.5" href="#3.5.5">3.5.5. #pragma MCPP debug expression, #debug expression</a>
<dd><a name="toc.3.5.6" href="#3.5.6">3.5.6. #pragma MCPP debug getc, #debug getc</a>
<dd><a name="toc.3.5.7" href="#3.5.7">3.5.7. #pragma MCPP debug memory, #debug memory</a>
<dd><a name="toc.3.5.8" href="#3.5.8">3.5.8. #pragma MCPP debug macro_call</a></dl>
<dd><a name="toc.3.6" href="#3.6">3.6. #assert, #asm, #endasm</a>
<dd><a name="toc.3.7" href="#3.7">3.7. New C99 Features (_Pragma() operator, Variadic Macro and others)</a>
<dd><dl><dt><a name="toc.3.8" href="#3.8">3.8. Particular specifications for certain compiler system</a>
<dd><a name="toc.3.8.1" href="#3.8.1">3.8.1. Variadic macro of GCC and Visual C</a>
<dd><a name="toc.3.8.2" href="#3.8.2">3.8.2. Handling of 'defined' by GCC</a>
<dd><a name="toc.3.8.3" href="#3.8.3">3.8.3. Asm Statement in Borland C and Other Special Syntaxes</a>
<dd><a name="toc.3.8.4" href="#3.8.4">3.8.4. #import and Others</a></dl>
<dd><dl><dt><a name="toc.3.9" href="#3.9">3.9. Problems of GCC and Compatibility with GCC</a>
<dd><a name="toc.3.9.1" href="#3.9.1">3.9.1. Preprocessing FreeBSD 2/Kernel Sources</a>
<dd><a name="toc.3.9.2" href="#3.9.2">3.9.2. Preprocessing FreeBSD 2/Libc</a>
<dd><a name="toc.3.9.3" href="#3.9.3">3.9.3. Problems Concerning GCC 2/cpp</a>
<dd><a name="toc.3.9.4" href="#3.9.4">3.9.4. Preprocessing Linux/glibc 2.1</a>
<dd><dl><dt><a name="toc.3.9.5" href="#3.9.5">3.9.5. To Use <b>mcpp</b> with GCC 2</a>
<dd><a name="toc.3.9.5.1" href="#3.9.5.1">3.9.5.1. To Sort <b>mcpp</b>'s Warnings</a></dl>
<dd><a name="toc.3.9.6" href="#3.9.6">3.9.6. Preprocessing GCC 3.2 Source</a>
<dd><a name="toc.3.9.7" href="#3.9.7">3.9.7. To Use <b>mcpp</b> with GCC 3 or 4</a>
<dd><a name="toc.3.9.8" href="#3.9.8">3.9.8. Preprocessing Linux/glibc 2.4</a>
<dd><a name="toc.3.9.9" href="#3.9.9">3.9.9. The Problems of Linux / stddef.h, limits.h and #include_next</a>
<dd><a name="toc.3.9.10" href="#3.9.10">3.9.10. Problems of Mac OS X / Apple-GCC and its System Headers</a>
<dd><a name="toc.3.9.11" href="#3.9.11">3.9.11. Preprocessing firefox 3.0b3pre</a></dl>
<dd><dl><dt><a name="toc.3.10" href="#3.10">3.10. Visual C++ System Header Problems</a>
<dd><a name="toc.3.10.1" href="#3.10.1">3.10.1. Comment Generating Macro?</a>
<dd><a name="toc.3.10.2" href="#3.10.2">3.10.2. '$' in Identifiers</a></dl>
<br>
<dt><a name="toc.4" href="#4">4. Implementation-defined Behaviors</a>
<dd><a name="toc.4.1" href="#4.1">4.1. Status Value on Exit</a>
<dd><a name="toc.4.2" href="#4.2">4.2. Include Directory Search Path</a>
<dd><a name="toc.4.3" href="#4.3">4.3. How to Construct Header Name</a>
<dd><a name="toc.4.4" href="#4.4">4.4. Evaluation of #if Expression</a>
<dd><a name="toc.4.5" href="#4.5">4.5. Character Constant Evaluation in #if Expression</a>
<dd><a name="toc.4.6" href="#4.6">4.6. #if sizeof (type)</a>
<dd><a name="toc.4.7" href="#4.7">4.7. How to Handle White-Space Sequence</a>
<dd><a name="toc.4.8" href="#4.8">4.8. Default Specifications for <b>mcpp</b> Executables</a>
<br>
<br>
<dt><a name="toc.5" href="#5">5. Diagnostic Messages</a>
<dd><a name="toc.5.1" href="#5.1">5.1. Diagnostic Messages Format</a>
<dd><a name="toc.5.2" href="#5.2">5.2. Translation Limits</a>
<dd><dl><dt><a name="toc.5.3" href="#5.3">5.3. Fatal Errors</a>
<dd><a name="toc.5.3.1" href="#5.3.1">5.3.1. <b>mcpp</b>'s Own Bugs</a>
<dd><a name="toc.5.3.2" href="#5.3.2">5.3.2. Physical Errors</a>
<dd><a name="toc.5.3.3" href="#5.3.3">5.3.3. Translation Limits and Internal Buffer Errors</a>
<dd><a name="toc.5.3.4" href="#5.3.4">5.3.4. #pragma MCPP preprocessed Related Errors</a></dl>
<dd><dl><dt><a name="toc.5.4" href="#5.4">5.4. Errors</a>
<dd><a name="toc.5.4.1" href="#5.4.1">5.4.1. Character and Token Related Errors</a>
<dd><a name="toc.5.4.2" href="#5.4.2">5.4.2. Unterminated Source File Related Errors</a>
<dd><a name="toc.5.4.3" href="#5.4.3">5.4.3. Ill-Balanced Preprocessing Group Related Errors</a>
<dd><a name="toc.5.4.4" href="#5.4.4">5.4.4. Simple Syntax Errors on Directive Lines</a>
<dd><a name="toc.5.4.5" href="#5.4.5">5.4.5. Syntax Errors in #if Expressions</a>
<dd><a name="toc.5.4.6" href="#5.4.6">5.4.6. #if Expression Evaluation Errors</a>
<dd><a name="toc.5.4.7" href="#5.4.7">5.4.7. #define Related Errors</a>
<dd><a name="toc.5.4.8" href="#5.4.8">5.4.8. #undef Related Errors</a>
<dd><a name="toc.5.4.9" href="#5.4.9">5.4.9. Macro Expansion Errors</a>
<dd><a name="toc.5.4.10" href="#5.4.10">5.4.10. #error and #assert</a>
<dd><a name="toc.5.4.11" href="#5.4.11">5.4.11. Failure of #include</a>
<dd><a name="toc.5.4.12" href="#5.4.12">5.4.12. Other Errors</a></dl>
<dd><dl><dt><a name="toc.5.5" href="#5.5">5.5. Warnings (Class 1)</a>
<dd><a name="toc.5.5.1" href="#5.5.1">5.5.1. Character, Token and Comment Related Warnings</a>
<dd><a name="toc.5.5.2" href="#5.5.2">5.5.2. Unterminated Source File Related Warnings</a>
<dd><a name="toc.5.5.3" href="#5.5.3">5.5.3. Directive Line Related Warnings</a>
<dd><a name="toc.5.5.4" href="#5.5.4">5.5.4. #if Expression Related Warnings</a>
<dd><a name="toc.5.5.5" href="#5.5.5">5.5.5. Macro Expansion Related Warnings</a>
<dd><a name="toc.5.5.6" href="#5.5.6">5.5.6. Line Number Related Warnings</a>
<dd><a name="toc.5.5.7" href="#5.5.7">5.5.7. #pragma MCPP warning, #warning</a></dl>
<dd><a name="toc.5.6" href="#5.6">5.6. Warnings (Class 2)</a>
<dd><a name="toc.5.7" href="#5.7">5.7. Warnings (Class 4)</a>
<dd><a name="toc.5.8" href="#5.8">5.8. Warnings (Class 8)</a>
<dd><a name="toc.5.9" href="#5.9">5.9. Warnings (Class 16)</a>
<dd><a name="toc.5.10" href="#5.10">5.10. Diagnostic Messages Index</a>
<br>
<br>
<dt><a name="toc.6" href="#6">6. Reporting on Bugs and Others</a>
</dl>
<br>
<h1><a name="1" href="#toc.1">1. Overview</a></h1>
<p><b>mcpp</b> is a C preprocessor developed by kmatsui (Kiyoshi Matsui) based on DECUS cpp written by Martin Minow, and then rewritten entirely. <b>mcpp</b> means Matsui cpp. This software is supplied as source codes, and to use <b>mcpp</b> in any compiler systems, a small amount of modifications to adapt to the compiler system are required before it can be compiled into an executable. *1</p>
<p>This document describes the specification for <b>mcpp</b> executables that has been already ported to certain compiler systems. For those who want to know more about <b>mcpp</b> or want to port it to other compiler systems, refer to <b>mcpp</b> source and its document <a href="mcpp-porting.html">mcpp-porting.html</a>.</p>
<p>All these sources and related documents are provided as an open-source-software.</p>
<p>Before going into detail, some of the <b>mcpp</b> features are introduced here.</p>
<p>Note:</p>
<p>*1 <b>mcpp</b> V.2.6.3 onward provides some binary packages too, at the following site.</p>
<blockquote>
<p><a href="http://mcpp.sourceforge.net/">http://mcpp.sourceforge.net/</a></p>
</blockquote>
<br>
<h2><a name="1.1" href="#toc.1.1">1.1. High portability</a></h2>
<p><b>mcpp</b> is a portable preprocessor, supporting various operating systems, including Linux, FreeBSD and Windows. Its source has a wide portability, and can be compiled by any compilers which support Standard C or C++ (ANSI/ISO C or C++). The library functions used are only the classic ones.</p>
<p>To port <b>mcpp</b> to each compiler system, in many cases, one only needs to change some macro definitions in the header files and simply compile it. In the worst case, adding several dozen of lines into a source file would be enough.</p>
<p>To process multi-byte characters (Kanji), it supports Japanese EUC-JP, shift-JIS and ISO2022-JP, Chinese GB-2312, Taiwanese Big-5 and Korean KSC-5601 (KSX 1001), as well as UTF-8. For shift-JIS, ISO2022-JP or Big-5, <b>mcpp</b> can complement the compiler-proper if it does not recognize them.</p>
<br>
<h2><a name="1.2" href="#toc.1.2">1.2. Standard C mode with highest conformance and other modes</a></h2>
<p><b>mcpp</b> has various behavioral modes. Other than Standard-conforming mode, there are K&R 1st mode, "Reiser" cpp mode and what I call post-Standard mode. <b>mcpp</b> has also an execution option for C++ preprocessor.</p>
<p>Different from many existing preprocessors, Standard mode of <b>mcpp</b> has the highest conformance to Standards: all of C90, C99 and C++98. It has been developed aiming to become the reference model of the Standard C preprocessor. Those versions of the Standard can be specified by an execution option. *1</p>
<p>In addition, it provides several useful enhancements: '#pragma MCPP debug', which traces the process of macro expansion or #if expression evaluation, and the header file "pre-preprocessing" facility.</p>
<p><b>mcpp</b> also provides several useful execution options, such as warning level or include directory specification options.</p>
<p>Even if there are any mistakes in the source, <b>mcpp</b> deals suitably with accurate plain diagnostic messages without running out of control or displaying misguiding error messages. It also displays warnings for portability problems. The detailed documents are also attached.</p>
<p>In spite of its high quality, <b>mcpp</b>'s code size and memory usage is relatively small.</p>
<p>A disadvantage of <b>mcpp</b>, if any, is slower processing speed. It takes two or three times time of GCC 3.*, 4.* / cc1, but seeing that its processing speed is almost the same as that of Borland C 5.5/cpp32 and that it runs a little bit faster when the header file pre-preprocessing facility is used, it cannot be described as particularly slow. <b>mcpp</b> puts an emphasis on standard conformance, source portability and operability in a small memory space, making this level of processing speed inevitable.</p>
<p>Validation Suite for Standard C Preprocessing, which is used to test the extent to which a preprocessor conforms to Standard C, its documentation cpp-test.html, which contains results of applying Validation Suite to various preprocessors, are also released with <b>mcpp</b>. When looking through this file, you will notice that so-called Standard-conforming preprocessors have so many conformance-related problems.</p>
<p>During the course of developing <b>mcpp</b> V.2.3, it was selected as one of the "Exploratory Software Projects for 2002" by Information-technology Promotion Agency (IPA), Japan, along with its Validation Suite. From July 2002 to February 2003, the project, financed by IPA, proceeded under advice of Yutaka Niibe project manager. I asked "HighWell, Inc." Limited Company, Tokyo, for translation of all the documents. For technical details, I revised and corrected the translated documents.</p>
<p><b>mcpp</b> was continuously adopted to one of the "Exploratory Software Projects" in 2003 by Hiroshi Ichiji project manager. The update of <b>mcpp</b> proceeded into the next version, V.2.4. *2</p>
<p>After the project, I am still going on updating <b>mcpp</b> and Validation Suite.</p>
<p>Note:</p>
<p>*1 ISO/IEC 9899:1990 (JIS X 3010-1993) had been used as C Standard, but in 1999, ISO/IEC 9899:1999 was adopted as a new Standard. This document calls the former C90 and latter C99. The former is generally called ANSI C or C89 because it migrated from ANSI X3.159-1989. ISO/IEC 9899:1990 + Amendment 1995 is sometimes called C95. C++ Standards are ISO/IEC 14882:1998 and its corrigendum version ISO/IEC 14882:2003. This document calls both of them C++98.</p>
<p>*2 The outline of the "Exploratory Software Project" can be seen at the following site (Japanese only).</p>
<blockquote>
<p><a href="http://www.ipa.go.jp/jinzai/esp/"> http://www.ipa.go.jp/jinzai/esp/</a></p>
</blockquote>
<p><b>mcpp</b> from V.2.3 through V.2.5 had been located at:</p>
<blockquote>
<p><a href="http://www.m17n.org/mcpp/"> http://www.m17n.org/mcpp/</a></p>
</blockquote>
<p>In April 2006, <b>mcpp</b> project moved to:</p>
<blockquote>
<p><a href="http://mcpp.sourceforge.net/"> http://mcpp.sourceforge.net/</a></p>
</blockquote>
<p>The old version of <b>mcpp</b>, cpp V.2.2 and Validation Suite V.1.2 are located in the following Vector's web site. They are in the directory called dos/prog/c, but they are not for MS-DOS exclusively. Sources are for UNIX, WIN32, MS-DOS. The documents are Japanese only.</p>
<blockquote>
<a href="http://www.vector.co.jp/soft/dos/prog/se081188.html">http://www.vector.co.jp/soft/dos/prog/se081188.html</a><br>
<a href="http://www.vector.co.jp/soft/dos/prog/se081189.html">http://www.vector.co.jp/soft/dos/prog/se081189.html</a><br>
<a href="http://www.vector.co.jp/soft/dos/prog/se081186.html">http://www.vector.co.jp/soft/dos/prog/se081186.html</a><br>
</blockquote>
<p>The text files in these archive files available at Vector use [CR]+[LF] as a <newline> and encode Kanji in shift-JIS for DOS/Windows. On the other hand, those from V.2.3 through V.2.5 available at SourceForge use [LF] as a <newline> and encode Kanji in EUC-JP for UNIX. From V.2.6 on two types of archive, .tar.gz file with [LF]/EUC-JP and .zip file with [CR]+[LF]/shift-JIS, are provided.</p>
<br>
<h2><a name="1.3" href="#toc.1.3">1.3. Notations in this Manual</a></h2>
<p>Though this manual was text-file in the older versions, it has changed to html-file at V.2.6.2.<br>
This manual uses the following typographical conventions:</p>
<ul>
<li><tt style="color:navy">source:</tt><br>
<tt style="color:navy">Navy</tt> colored constant-width font is used for code snippets and command line inputs.<br>
<li><tt>__STDC__:</tt><br>
<tt style="color:maroon">Maroon</tt> colored constant-width font is used for Standard predefined macros or any other macros found in some codes.<br>
<li><i>STD</i>:<br>
<i>Italic</i> font is used for the macros defined in <b>mcpp</b> source file named system.H. This manual uses these names to denote various <b>mcpp</b> settings. Note that these macros are only used in compilation of <b>mcpp</b>, and that the <b>mcpp</b> executable does not have such macros.<br>
</ul>
<br>
<h1><a name="2" href="#toc.2">2. Invocation Options and Environment Settings</a></h1>
<h2><a name="2.1" href="#toc.2.1">2.1. Two Kinds of Build and Five Behavioral Modes</a></h2>
<p>There are two types of build (or compiling configuration) for <b>mcpp</b> executable. *1, *2</p>
<ol>
<li><b>Compiler-independent-build</b>: the preprocessor which behaves on its own not depending on compiler system. The invocation options of compiler-independent-build are the same across the compilers with which <b>mcpp</b> is compiled. Although it can preprocess source files, it cannot behave as an integrated part of a compiler system.<br>
<li><b>Compiler-specific-build</b>: the preprocessor to replace the resident preprocessor of certain compiler system, if possible. Each compiler-specific-build has some different specifications for compatibility with the compiler system. It has the options common with the compiler-independent-build, except a few options different from the commons to avoid conflict with the compiler system.<br>
</ol>
<p>Each <b>mcpp</b> executable has following 5 behavioral modes regardless of the building types.</p>
<ol>
<li><i>STD</i>: Standards (C90, C99, C++98) conforming mode. This is the default.<br>
<li><i>COMPAT</i>: A variation of <i>STD</i> mode, which expands recursive macro more than the Standards' specification.<br>
<li><i>POSTSTD</i>: Special "post-Standard" mode created by the author, based on the Standards and simplified removing all the Standards irregular specifications.<br>
<li><i>KR</i>: K&R 1st specification mode.<br>
<li><i>OLDPREP</i>: "Reiser" model cpp mode (old-preprocessor mode).<br>
</ol>
<p>The mode of <b>mcpp</b> is specified by the run-time options as follows:</p>
<ul>
<li><samp>-@std</samp><br>
The <i>STD</i> mode (default).<br>
<li><samp>-@compat</samp><br>
The <i>COMPAT</i> mode.<br>
<li><samp>-@poststd, -@post</samp><br>
The <i>POSTSTD</i> mode.<br>
<li><samp>-@kr</samp><br>
The <i>KR</i> mode.<br>
<li><samp>-@oldprep, -@old</samp><br>
The <i>OLDPREP</i> mode.<br>
</ul>
<p>In this document, I group <i>OLDPREP</i> and <i>KR</i> into pre-Standard modes, and group <i>STD</i>, <i>COMPAT</i> and <i>POSTSTD</i> into Standard modes. Since <i>COMPAT</i> mode is almost the same with <i>STD</i> mode, <i>STD</i> includes <i>COMPAT</i> unless otherwise mentioned. *3</p>
<p>There are differences in the macro expansion methods between Standard and pre-Standard modes. Roughly speaking, this difference is the difference between C90 and pre-C90. The biggest difference is the expansion of the function-like macros (macros with arguments). For the arguments with macros, while in Standard mode, <b>mcpp</b> substitutes the parameter within the replacement list of the original macro after completely expanding the arguments, in pre-Standard, <b>mcpp</b> substitutes the parameter without expanding, then expands the argument at rescan time.</p>
<p>Also, in Standard mode, a macro is not expanded recursively in principle, even if the macro definition is recursive directly or indirectly. If there is a recursive macro definition in pre-Standard mode, it causes infinite recursion and becomes an error at expansion time.</p>
<p>Handling of \ at line end is also different by mode. In Standard mode, after processing the trigraph, the sequence of <backslash><newline> gets deleted before tokenization, but in pre-Standard mode, these only get deleted when they are within the string literals or in a #define line.</p>
<p>There is a subtle difference in tokenization (token parsing, decomposition to tokens). In Standard mode, it tokenizes on "token based processing" principle. To put it concretely, in Standard mode, spaces will be inserted surrounding the expanded macro to prevent the unexpected merging with its adjacent tokens. In pre-Standard mode, traditional, convenient and tacit tokenization and the macro expansion methods of "character based text replacement" are left a trace. About these, please see <a href="cpp-test.html#2"> cpp-test.html#2</a>.</p>
<p>In Standard mode, it handles the numeric token, called preprocessing number, according to the Standard specification. In pre-Standard, the numeric tokens are the same as integer constant tokens or floating point tokens. The suffix 'U', 'u', 'LL' and 'll' of the integer constant and the suffixes 'F', 'f', 'L' and 'l' of floating point are not recognized as a part of the tokens in pre-Standard.</p>
<p>The string literals and character constants of wide characters are recognized as single tokens only in Standard mode.</p>
<p>Digraph, #error, #pragma, and _Pragma() operator are available only in Standard mode. Also, -S <n> option (strict-ansi specs) and -+ option (the one run as C++ preprocessor) are used only in Standard mode. Pre-defined macros <tt>__STDC__</tt>, <tt>__STDC_VERSION__</tt> are defined in Standard mode, and they don't get defined in pre-Standard.</p>
<p>#if defined, #elif cannot be used in pre-Standard mode. Macros cannot be used within argument of #include or #line in pre-Standard. Predefined macros, <tt>__FILE__</tt>, <tt>__LINE__</tt>, <tt>__DATE__</tt>, <tt>__TIME__</tt> are not defined at pre-Standard.</p>
<p>On the other hand, #assert, #asm (#endasm), #put_defines and #debug are available in pre-Standard mode only.</p>
<p>#if expression is evaluated in long / unsigned long or long long / unsigned long long at Standard mode, and in (signed) long only at pre-Standard. sizeof (type) in #if expression can be used only in pre-Standard.</p>
<p>Trigraphs and UCN (universal character name) are available only in <i>STD</i> mode.</p>
<p>The output of diagnostic messages is also slightly different between the modes. Please see chapter <a href="#5"> 5</a> for details.</p>
<p>Any other items, which do not have any distinct rules between K&R 1st and the Standards, follow the C90 rules in pre-Standard mode.</p>
<p>The difference of <i>OLDPREP</i> mode from <i>KR</i> mode and the difference of <i>POSTSTD</i> and <i>COMPAT</i> modes from <i>STD</i> mode are as follows:</p>
<ul>
<li><i>OLDPREP</i><br>
<ol>
<li>Convert comment to 0 space instead of 1 space. Usually this conversion is done in the output at the end. In macro definition, however, the conversion is done immediately after the definition.<br>
<li>When there are string literals or character constants in the replacement list of the macro definition, and if any of the parameter names match to any part of these, that part will be substituted with the argument corresponding to the parameter when calling the macro. That is to say, when the content of the string literal or character constant is searched as token sequence, stripping the enclosing quotes, if a parameter name is found, that will be substituted.<br>
<li>You can write anything you like in the lines of #else, #endif. (One usually writes MACRO of corresponding #if MACRO or #ifdef MACRO.)<br>
<li>It stops "unterminated string literal" and "unterminated character constant" errors. If there is no closure of the literal " or ', it assumes the close at line end.<br>
<li>It treats '# 123' line as '#line 123'.<br>
</ol>
<br>
<li><i>COMPAT</i><br>
Expand recursive macro more than the Standard's specification. On expanding recursive macro, set the range of non-re-replacing of the same name narrower than the Standard.<br>
<br>
Refer to <a href="cpp-test.html#3.4.26"> cpp-test.html#3.4.26</a> about the specifications of recursive macro expansion. See test-t/recurs.t for a sample of recursive macro. *4<br>
<br>
<li><i>POSTSTD</i><br>
This mode differs from <i>STD</i> mode in the following points:<br>
<ol>
<br>
<li>Does not recognize trigraphs. Digraphs are converted at translation phase 1, that is, the beginning of preprocessing. Does not deal with digraph as a token.<br>
<li>Simplified tokenization according to complete token-base rule. When there is no white space, as a token separator between preprocessing tokens in the source code, insert a space automatically. (However, this does not get inserted between macro name and the following "(" within macro definition). Therefore, even for stringizing by # operator, it gets stringized after a space is inserted between all the preprocessing tokens. Also, at the re-definition of macros, it does not matter whether there is a token separator or not.<br>
<li>At the re-definition of function-like macros, the difference of the parameter name is not relevant.<br>
<li>Character constants cannot be used in #if expressions (it will cause an error).<br>
<li>It removed irregular "function-unlike" rules for function-like macro expansion. Hence, rescanning only targets to the replacement list of the macro, and not the sequence after that.<br>
<li>Normally, the header name with the format of #include <stdio.h> is accepted, but it gets a warning. (by class 2 warning option.) If the header name with the format of <stdio.h> is used in a macro, it can get an error at a particular instance. It recommends to use the format of #include "stdio.h".<br>
<li>The rule, a space is required between macro name and replacement list in macro definition, is added in C99, but this rule is not complied with. (A space is inserted automatically at tokenization.)<br>
<li>UCN (universal-character-name) is not recognized. Multi-byte characters in identifier are not recognized.<br>
<li>In C++, eleven identifier-like operators are not dealt as operators.<br>
</ol>
</ul>
<p>Moreover, there is a mode called <b>lang-asm</b>.
That is a mode to process anomalous sources which are assembler sources and nevertheless have comments, directives and macros of C embedded.
While <i>POST_STD</i> cannot become this mode, <i>STD, KR</i> and <i>OLD</i> get to this mode when specified by an option.
See <a href="#2.5">2.5</a> for its specifications.</p>
<p>For the above reasons, there are some different specifications in <b>mcpp</b> executables. So, please read this manual carefully. This chapter describes first the common options, next the behavioral-mode-dependent options, then the the options common to most compiler systems, finally the compiler-dependent options for each compiler-specific-build.</p>
<p>Note:</p>
<p>*1 There is another one named <b>subroutine-build</b> which is called as a subroutine from some other main program. The behavioral specification of subroutine-build is, however, the same with either of compiler-specific-build or compiler-independent-build according to its compile time setting. Hence, this manual does not mention subroutine-build particularly.
As for subroutine-build, refer to <a href="mcpp-porting.html#3.12">mcpp-porting.html#3.12</a>.</p>
<p>*2 The binary packages provided at the SourceForge site are of compiler-independent-builds.</p>
<p>*3 <b>mcpp</b> had two separate executables for Standard mode and pre-Standard mode; they were integrated into one at V.2.6.</p>
<p>*4 This option is for compatibility with GCC, Visual C++ and other major implementations. 'compat' means "compatible mode".</p>
<br>
<h2><a name="2.2" href="#toc.2.2">2.2. How to Specify Invocation Options</a></h2>
<p>The <arg> and [arg] shown below indicate required and optional arguments respectively. Note that the <, >, [, or ] character itself must not be entered.</p>
<p><b>mcpp</b> invocation takes a form of:</p>
<pre>
mcpp [-<opts> [-<opts>]] [in_file] [out_file] [-<opts> [-<opts>]]
</pre>
<p>Note that you have to replace the above "mcpp" with other name, depending on how <b>mcpp</b> is installed.</p>
<p>When out_file (an output path) is omitted, stdout is used unless the -o option is specified. When in_file (an input path) is omitted, stdin is used. A diagnostic message is output to stderr unless the -Q option is specified.</p>
<p>If any of these files cannot be opened, preprocessing is terminated, issuing an error message.</p>
<p>For an option with argument, white-space characters may or may not be inserted between the option character and an argument. In other words, both of "-I<arg>" and "-I <arg>" are acceptable. For options without argument, both of "-Qi" and "-Q -i" are valid.</p>
<p>For an option with an argument, missing a required argument causes an error except for the -M option,</p>
<p>If -D, -U, -I, or -W option is specified multiple times, each of them is valid. For -S, -V, or -+ option, only the first one is valid. For -2, or -3 option, its specification switches each time an option is specified. For other options, the last one is valid.</p>
<p>The option letters are case sensitive.</p>
<p>The switch character is '-', not '/', even under Windows.</p>
<p>When invalid options are specified, a usage statement is displayed. To check valid options, enter a command, such as "mcpp -?". In addition to the usage message, there are several error messages, but they are self-explanatory. I will omit their explanations.</p>
<br>
<h2><a name="2.3" href="#toc.2.3">2.3. Common Options</a></h2>
<p>This section covers common options across <b>mcpp</b> modes or compiler systems.</p>
<ul>
<li><samp>-C</samp><br>
Output also comments in source code. This option is useful for debugging. Note that a comment is moved ahead of a logical source line when output. This is because a comment is processed before macro expansion or directive processing, and a comment may appear during a macro invocation.<br>
<br>
<li><samp>-D <macro>[=[<value>]]</samp><br>
<li><samp>-D <macro(a,b)>[=[<value>]]</samp><br>
Define a macro named "macro". This option can be used to change the definitions of predefined macros other than <tt>__STDC__</tt>, <tt>__STDC_VERSION__</tt>, <tt>__FILE__</tt>, <tt>__LINE__</tt>, <tt>__DATE__</tt>, <tt>__TIME__</tt> and <tt>__cplusplus</tt>. (<tt>__STDC_HOSTED__</tt>, C99's predefined macro, is exceptionally redefined by this option, because some compiler systems, like GCC V.3, use the -D option to define <tt>__STDC_HOSTED__</tt>.) To specify a value, use "=<value>". If "=<value>" is omitted, 1 is assumed. (Note that in bcc32, the macro is defined as zero-token by default.) Do not enter white-space characters immediately before "=". If a white-space character is entered immediately after "=", the macro is defined as zero token.<br>
A macro with arguments can be defined by this option.<br>
This option can be specified repeatedly.<br>
<br>
<li><samp>-e <encoding></samp><br>
Change a multi-byte character encoding to <encoding>. For <encoding>, refer to <a href="#2.8"> 2.8</a>.<br>
<br>
<li><samp>-I <directory></samp><br>
Specify the first directory in the include directory search path order with <directory>. For a search path, refer to <a href="#4.2"> 4.2</a>. If a directory name contains spaces, it has to be enclosed with " and ".<br>
<br>
<li><samp>-I 1, -I 2, -I 3</samp><br>
Specify a directory from which <b>mcpp</b> begins searching when it encounters a #include "header" directive (i.e. not <header> format). -I1, -I2 and -I3 indicate the current directory, the source file (i.e. includer) directory, and the both respectively. For details, see <a href="#4.2"> 4.2</a>.<br>
<br>
<li><samp>-j</samp><br>
On outputting a diagnostic message, <b>mcpp</b> displays only one line of diagnostic without additional information, such as source lines. (By default, one line of diagnostic message is followed by a source code line having a problem. If the source code line in question is found in a #included file, all the #including file names and including line numbers are also displayed in sequence. For a diagnostic on macro, <b>mcpp</b> displays also its definition information).<br>
When Validation Suite is used in the GCC testsuite, this option has to be specified to output a diagnostic message in the same format as GCC.<br>
</ul>
<p>The -M* options are to output source file dependency lines for makefile. When there are several source files and the -M* option is specified for each of these source files to process and merge the outputs into a file, dependency description lines are aligned. These options are similar to those of GCC, but there are several differences. *1</p>
<ul>
<li><samp>-M</samp><br>
Output lines that describe dependency among source files. The output destination is the file specified in a command line, or stdout if omitted. If a dependency description is too long to fit in a line, it is folded over the next lines. The preprocessing result is not output.<br>
<br>
<li><samp>-MM</samp><br>
Almost the same with -M, except that the following header files are not output.<br>
<ol>
<li>Files specified in the format of #include <stdio.h>.<br>
<li>Files specified using an absolute path name, such as #include "/usr/include/stdio.h".<br>
<li>Files specified in the format of #include "stdio.h" that are found not in the current or source directory, depending on compiler systems or the -I <n> option, but in system include directories, including those specified with the -I <directory> option or with environment variables.<br>
</ol>
But, GCC-specific-build differs from this, it output the header files excluding only system headers, as GCC does.<br><br>
<li><samp>-MD [FILE]</samp><br>
Almost the same with -M, except that the preprocessing result is output to the specified file on a command line or stdout. If FILE is specified, <b>mcpp</b> outputs dependency description lines to that file. Otherwise, they are output to a file having the same base filename with the source file and the suffix of ".d" instead of ".c".<br>
<br>
<li><samp>-MMD [FILE]</samp><br>
Almost the same with -MD, except that, like -MM, the files that are regarded as system header are not output. An output file <b>mcpp</b> outputs dependency description lines to is same as -MD [FILE].<br>
<br>
<li><samp>-MF FILE</samp><br>
The dependency lines are output to FILE. -MF FILE takes precedence over -MD FILE or -MMD FILE.<br>
<br>
<li><samp>-MP</samp><br>
"Phony targets" are also output. Each included file can be written as a phony target without a dependency as follows:<br>
<pre>
test.o: test.c test.h
test.h:
</pre>
<li><samp>-MT TARGET</samp><br>
The target name is specified as TARGET not foo.o. -MT '$(objpfx)foo.o' outputs the following line.<br>
<pre>
$(objpfx)foo.o: foo.c
</pre>
<li><samp>-MQ TARGET</samp><br>
Same as -MT, except that a string that has a special meaning to 'make' is 'quoted' as follows:<br>
<pre>
$$(objpfx)foo.o: foo.c
</pre>
<li><samp>-N</samp><br>
Disable all the predefined macros, including those that begin with "_", except for the ones required by Standards and <tt>__MCPP</tt>. The Standard predefined macros include <tt>__FILE__, __LINE__, __DATE__, __TIME__, __STDC__, __STDC_VERSION__</tt>, as well as <tt>__STDC_HOSTED__</tt> for C99 and <tt>__cplusplus</tt> for C++. If you want to disable <tt>__MCPP</tt>, use the -U option.<br>
<br>
<li><samp>-o <file></samp><br>
Output the preprocessed source to the file. If this option is omitted, the second file argument is regarded as an output path, so this option is not necessary, however, some compiler drivers use this option.<br>
<br>
<li><samp>-P</samp><br>
Do not output line number information for the compiler-proper. This option is specified when you want to use <b>mcpp</b> for purpose other than C preprocessing.<br>
<br>
<li><samp>-Q</samp><br>
Output diagnostic messages to the "mcpp.err" file in the current directory. As these messages are appended to this file, it may become bigger. Delete it from time to time.<br>
<br>
<li><samp>-U <macro></samp><br>
Undefine predefined macro named "macro". This option cannot undefine <tt>__FILE__, __LINE__, __DATE__, __TIME__, __STDC__, __STDC_VERSION__</tt> (and <tt>__STDC_HOSTED__</tt> for C99), as well as <tt>__cplusplus</tt> invoked with -+ options.<br>
<br>
<li><samp>-v</samp><br>
Output the <b>mcpp</b> version and a search order of include directories to stderr.<br>
However, when -K option, explained at <a href="#2.4">2.4</a>, is specified or #pragma MCPP macro_call directive, explained at <a href="#3.5.8">3.5.8</a>, is specified, this option changes its meaning.<br>
<br>
<li><samp>-W <level></samp><br>
Specify a warning level with <level>. <level> should be 0 or "OR" of any one or more values of 1, 2, 4, 8 and 16. 1, 2, 4, 8 or 16 indicates a warning class. For example, if -W 5 is specified, warnings of classes 1 and 4 are output. If 0 is specified, no warnings are output. If this option is specified several times, all the specified values are "ORed" together. For example, -W 1 -W 2 -W 4 is equivalent to -W 7. Instead of -W 7 you can also write as -W "1|2|4". (Enclose with " and " so as | is not interpreted as a pipe.) If this option is omitted, -W 1 is assumed. For warning messages, refer from <a href="#5.5"> 5.5</a> through <a href="#5.9"> 5.9</a>.<br>
<br>
<li><samp>-z</samp><br>
The preprocessing results of the #included files are not output, but macros are defined. The #include lines themselves are output instead, though #include lines in an included file is not output. This option is used in debug of preprocessing.<br>
</ul>
<p>Note:</p>
<p>*1 <b>mcpp</b> differs from GCC in that:</p>
<ol>
<li><b>mcpp</b> does not provide the -MG option because its option specification is too complicated. (Therefore, I will omit its explanation.) The -M option can substitute for the -MG option because when include files cannot be found using the -M option, <b>mcpp</b> fails but outputs dependency description lines.<br>
<li><b>mcpp</b>, other than GCC-specific-build, excludes a wider range of header files when using the -MM and -MMD options.<br>
</ol>
<br>
<h2><a name="2.4" href="#toc.2.4">2.4. Options by <b>mcpp</b> Behavioral Modes</a></h2>
<p><b>mcpp</b> has several behavioral modes. For their specifications refer to sec <a href="#2.1"> 2.1</a>.</p>
<p>This manual shows a list of various <b>mcpp</b> behaviors by mode, which may not be readable. Please be patient. In this manual, all the uppercased names that do not begin with "__" and displayed in italics, such as <i>DIGRAPHS_INIT</i>, <i>TRUE</i>, <i>FALSE</i>, etc, are macros defined in system.H. These macros are only used for compiling <b>mcpp</b> itself and a <b>mcpp</b> executable generated does not predefine these macros. You must understand this point clearly.</p>
<p>The following options are available in Standard mode:</p>
<ul>
<li><samp>-+</samp><br>
Behave as C++ preprocessor. <b>mcpp</b> predefines the <tt>__cplusplus</tt> macro (its value is defined in system.H and defaults to 1), interprets the text from // to the end of a logical line as a comment and recognizes <samp>"::", ".*", "->*"</samp> as a single token. It evaluates "true" and "false" tokens in a #if expression to 1 and 0, respectively. If <tt>__STDC__</tt> and <tt>__STDC_VERSION__</tt> are defined, they are undefined. (For GCC-specific-<b>mcpp</b>, <tt>__STDC__</tt> is not undefined for compatibility with GCC.) The predefined macros that do not begin with "_" are also undefined. However, extended characters are not converted to UCN. *1, *2<br>
<br>
<li><samp>-2</samp><br>
Reverse initial settings for the digraphs processing. With <i>DIGRAPHS_INIT</i> == <i>FALSE</i>, <b>mcpp</b> recognizes digraphs. Otherwise, it doesn't.<br>
<br>
<li><samp>-h <n></samp><br>
Define the value of <tt>__STDC_HOSTED__</tt> macro with <n>.<br>
<br>
<li><samp>-S <n></samp><br>
Change the value of <tt>__STDC__</tt> to <n> in C. In C++, this option is ignored. The range of <n> has to be 0-9. With <n> set to 1 or higher, the predefined macros that do not begin with "_", such as <tt>unix</tt>, <tt>linux</tt>, are disabled. S indicates <tt>__STDC__</tt>. If this option is omitted, <tt>__STDC__</tt> is set to a default value (i.e. 1).<br>
For a GCC-specific-build, -pedantic, -pedantic-errors, or -lang-c89 is equivalent to -S1, so the next -S is ignored.
This option does not disable the non-conforming predefined macros such as <tt>unix, linux, i386</tt> for compatibility with GCC.
These macros are disabled only by -ansi or -std=iso* options.<br>
<br>
<li><samp>-V <value></samp><br>
Change the values of the predefined macros <tt>__STDC_VERSION__</tt> for C and <tt>__cplusplus</tt> for C++ to <value>. <value> is of a long type. (In C95, C99, and C++ Standard, this value is set to 199409L, 199901L and 199711L, respectively.) With <tt>__STDC__</tt> set to 0, <tt>__STDC_VERSION__</tt> is always set to 0L, overriding the -V option.<br>
<br>
If this option is omitted for C, <tt>__STDC_VERSION__</tt> is set to the value of <i>STDC_VERSION</i> in system.H. (For GCC V.2.7 - V.2.9, 199409L. For others, 0L.) If specifying -V199901L results in <tt>__STDC_VERSION__</tt> >= 199901L, <b>mcpp</b> conforms to the following C99 specifications (See <a href="#3.7"> 3.7</a>.):<br>
<br>
<ol>
<li>Treats the text from // to the end of a line as a comment. *3<br>
<li>Allows the sequence of p+, P+, p-, and P-, as well as e+, E+, e-, and E-, in the preprocessing-number. This is to represent a bit pattern of a floating-point number in Hex, like 0x1.FFFFFEp+128.<br>
<li>Enables the _Pragma operator (A _Pragma( "foo bar") has the same effect as specifying a #pragma foo bar.)<br>
<li><b>mcpp</b> compiled with the <i>EXPAND_PRAGMA</i> macro set to <i>TRUE</i> will macro-expand an argument on a #pragma line that does not begin with STDC or MCPP. (By default, <i>EXPAND_PRAGMA</i> is set to <i>FALSE</i> in other than Visual C-specific-build and Borland C-specific-build, so macro expansion does not occur.)<br>
<li>Allows an escape sequence of Universal-Character-Name (UCN) in identifiers, character constants, string literals and pp-numbers. (This is only enabled in <i>STD</i> mode.)<br>
</ol>
Note that although C99 provides for variable argument macros, <b>mcpp</b> allows them in the C90 and C++ modes. *4<br>
<br>
In C++ also, when specifying -V199901L results in <tt>__cplusplus</tt> >= 199901L, <b>mcpp</b> will enter the C99 compatibility mode, providing the above 2-4 enhancements. (1 is enabled unconditionally and 5 is almost the same.) These are <b>mcpp</b>'s own enhancements that do not conform to the C++ Standard.<br>
<br>
The -D option cannot be used with <tt>__STDC__</tt>, <tt>__STDC_VERSION__</tt>, and <tt>__cplusplus</tt>. This is to distinguish system-defined macros from user-defined ones.<br>
</ul>
<p>The following option is available for <i>STD</i> mode:</p>
<ul>
<li><samp>-3</samp><br>
Reverse initial settings for the trigraphs processing. With <i>TRIGRAPHS_INIT</i> == <i>FALSE</i>, <b>mcpp</b> recognizes trigraphs. Otherwise, it does not.<br>
<li><samp>-K</samp><br>
Enable <b>macro notification mode</b> which embeds macro notifications into comments. This mode is designed to allow reconstruction of the original source position from the preprocessed output. The primary purpose of the macro notification mode is to allow C/C++ refactoring tools to refactor source code without having to implement a special-purpose C preprocessor. This mode is also handy for debugging macro expansions. The goal for macro expansion mode is to annotate every macro expansion, while still allowing the code to be compiled. *5<br>
This mode is also enabled by the following pragma:
<pre>
#pragma MCPP debug macro_call
</pre>
The -K option has almost the same effect with this pragma at top of an input file except predefined macros are notified only by this option.
About the specs of macro notification, see <a href="#3.5.8">3.5.8. #pragma MCPP debug macro_call</a>.<br>
This option implies -k option.
The -v option changes its meaning in this mode, and outputs more verbose notations.
On the other hand, -a (-x assembler-with-cpp) or -C options automatically disable -K option. *6<br>
<li><samp>-k</samp><br>
Keep horizontal white spaces ('\t' and space characters) without squeezing them into one space.
Comment is converted to spaces of the same length.
This option is to keep column position of source file in preprocessed output except within macro expansion. (Column position of macros are known by -K option.) *7
</ul>
<p>Note:</p>
<p>*1 C++'s <tt>__STDC__</tt> is not desirable and causes many problems. GCC document says that <tt>__STDC__</tt> needs to be predefined in C++ because many header files expect <tt>__STDC__</tt> to be defined. The header files should be blamed for this. For common parts among C90, C99 and C++, "<samp>#if __STDC__ || __cplusplus</samp>" should be used.</p>
<p>*2 Different from C99, the C++ Standard makes much of UCN. So did C 1997/11 draft. Half-hearted implementation is not permitted. However, implementing Unicode in earnest is too much burden for preprocessor.</p>
<p>*3 In C90 <b>mcpp</b> treats // as a comment but issues a warning.</p>
<p>*4 This is for compatibility with GCC.</p>
<p>*5 If you install GCC-specific-mcpp, cc1 (cc1plus) is set to be handed from <b>mcpp</b> preprocessed file with -fpreprocessed option.
Though this option means that the input is already preprocessed,
cc1 still processes comment.
Therefore, you can safely pass output of -K to cc1 with -fpreprocessed.
Furthermore, if you add -save-temps option to gcc (g++) command, preprocessed output is left as *.i (*.ii) file, and you can read it by some refactoring tool.</p>
<p>*6 Comment insertion by -K option causes column shifts in sources, and this makes *.S file of GCC, which is not C/C++ source and compiled with -x assembler-with-cpp option, unable to be assembled.
Also comments kept by -C option are sometimes confusing with that inserted by -K option.
Therefore these options cannot be used at the same time.</p>
<p>*7 This option fails to keep column position on some particularly complex cases.
When line splicing by a <backslash><newline> and line splicing by a line-crossing comment are intermingled on one output line, or a comment crosses over 256 lines, column position will be lost.
Note that each '\v' and '\f' is converted to a space with or without this option.</p>
<br>
<h2><a name="2.5" href="#toc.2.5">2.5. Common Options Except for Some Compiler Systems</a></h2>
<p>The following 2 options can be used on UNIX-like systems, for either of compiler-independent-build and GCC-specific-build.
On GCC-specific-build, however, these will get an error if the GCC does not support them.</p>
<ul>
<li><samp>-m32</samp><br>
Predefine macros for 32bit mode.
If the CPU is <samp>x86_64</samp> or <samp>ppc64</samp>, predefined macros for 64bit mode are used by default.
With this option, however, those for <samp>i386</samp> or <samp>ppc</samp> respectively are used.<br>
<li><samp>-m64</samp><br>
Predefine macros for 64bit mode.
If the CPU is <samp>i386</samp> or <samp>ppc</samp>, predefined macros for 32bit mode are used by default.
With this option, however, those for <samp>x86_64</samp> or <samp>ppc64</samp> respectively are used.<br>
</ul>
<p>Since GCC has so many options that GCC-specific-build of <b>mcpp</b> has some different options from the other builds in order to avoid conflicts with GCC. Note that the options in compiler-independent-build are all the same even if compiled by GCC. The options common to the builds other than GCC-specific are as follows.</p>
<ul>
<li><samp>-a</samp><br>
Accept the following notations used in some assembler sources without causing an error.<br>
<ol>
<li>
<pre>
#APP
</pre>
<p>If the token that follows the line top # does not agree with any of C directives as above, <b>mcpp</b> outputs this line as it is without causing an error.</p>
<li>
<pre>
# + any comment.
</pre>
<p>If the token that follows the line top # is not even an identifier nor pp-number, <b>mcpp</b> discards the line with a warning, without causing an error.</p>
<li>
<pre>
"A very very
long long
string literal"
</pre>
<p>The above old-fashioned string literals are concatenated into "<samp>A very very\nlong long\nstring literal</samp>".</p>
<li>Even if token concatenation using a ## operator generates an invalid pp-token, it is not regarded as error.<br><br>
<li><b>mcpp</b> does not insert spaces around a macro expansion result, and does not regard an unintended token merging of the macro expansion result with its adjacent token as an error.<br>
</ol>
<p>These sometimes happen to GNU source code, however, this option for GCC is -x assembler-with-cpp or -lang-asm.<br>
This option cannot be used in <i>POSTSTD</i> mode.<br>
This manual calls this mode <b>lang-asm</b> mode.<br>
This mode is recommended when you use <b>mcpp</b> as a macro processor for some text other than C/C++, for example, as a cpp called from xrdb.</p>
<li><samp>-I-</samp><br>
Cancel default include directories and enable only ones specified with an environment variable and the -I option. Instead of -I-, GCC-specific-build uses -nostdinc. In GCC, the -I- option provides quite different functionality. See <a href="#2.6"> 2.6</a>.<br>
</ul>
<br>
<h2><a name="2.6" href="#toc.2.6">2.6. Options by Compiler System</a></h2>
<p>To use <b>mcpp</b> replacing the compiler system's resident preprocessor, install it in the directory where the resident preprocessor is located under an appropriate name. Before copying <b>mcpp</b>, be sure to change the name of resident preprocessor so that it may not be overwritten.</p>
<p>For settings on Linux, FreeBSD, or CygWIN see <a href="#3.9.5"> 3.9.5</a>.
For settings in GCC 3.*, 4.*, see also <a href="#3.9.7"> 3.9.7</a>, and <a href="#3.9.7.1"> 3.9.7.1</a>.
For MinGW, see <a href="#3.9.7.1"> 3.9.7.1</a>.</p>
<p>Possibly the compiler driver cannot pass some options to <b>mcpp</b> in a normal manner. However, GCC provides the -Wp almighty option to allow you to pass any options to the preprocessor. For example, if you specify as follows:</p>
<pre>
gcc -Wp,-W31,-Q23
</pre>
<p>The -W31 and -Q23 options are passed to preprocessor. The options you want to pass to preprocessor have to be specified following -Wp with each option delimited by ", ". *1, *2</p>
<p>For other compiler systems, if their compiler driver source is available, it is recommended that this type of an almighty option should be added to the source. If you modify the compiler driver source code in the way that, for example, when -P<opt> is specified, only -<opt> is passed to preprocessor, it would be very convenient because any options can be passed.</p>
<p>An alternative way to use all the options of <b>mcpp</b> is to write a makefile in which first preprocess with <b>mcpp</b>, then compile the output file of <b>mcpp</b> as a source file. For this method, refer to sections <a href="#2.9"> 2.9</a> and <a href="#2.10"> 2.10</a>.</p>
<p>The following options are available for some compiler-specific-builds. The compiler-independent-build has not these options, of course.</p>
<p>The following options are available for the LCC-Win32-specific-build.</p>
<ul>
<li><samp>-g <n></samp><br>
Define the <tt>__LCCDEBUGLEVEL</tt> macro as <n>.<br>
<li><samp>-O</samp><br>
Defines the <tt>__LCCOPTIMLEVEL</tt> macro as 1.<br>
</ul>
<p>The following options are available for the Visual C-specific-build.</p>
<ul>
<li><samp>-arch:SSE, -arch:SSE2</samp><br>
Define the macro <tt>_M_IX86_FP</tt> as 1, 2 respectively.<br>
<li><samp>-Fl <file></samp><br>
Same as -include <file> for GCC.<br>
<li><samp>-G<n></samp><br>
If <n> is one of 3, 4, 5, 6, B, define the macro <tt>_M_IX86</tt> as 300, 400, 500, 600, 600, respectively.<br>
<li><samp>-GR</samp><br>
Define the macro <tt>_CPPRTTI</tt> to 1.<br>
<li><samp>-GX</samp><br>
Define the macro <tt>_CPPUNWIND</tt> to 1.<br>
<li><samp>-GZ</samp><br>
Define the macro <tt>__MSVC_RUNTIME_CHECKS</tt> to 1.<br>
<li><samp>-J</samp><br>
Define the macro <tt>_CHAR_UNSIGNED</tt> to 1.<br>
<li><samp>-RTC*</samp><br>
If -RTC1, -RTCc, -RTCs, -RTCu and such option is specified, define the macro <tt>__MSVC_RUNTIME_CHECKS</tt> to 1.<br>
<li><samp>-Tc, -TC</samp><br>
Specify that the source is written in C. The result is same with or without this option.<br>
<li><samp>-Tp, -TP</samp><br>
Same as -+.<br>
<li><samp>-u</samp><br>
Same as -N.<br>
<li><samp>-Wall</samp><br>
Same as -W17 (-W1 -W16).<br>
<li><samp>-WL</samp><br>
Same as -j.<br>
<li><samp>-w</samp><br>
Same as -W0.<br>
<li><samp>-X</samp><br>
Same as -I-.<br>
<li><samp>-Za</samp><br>
Undefine the macro <tt>_MSC_EXTENSIONS</tt> and prohibit '$' in identifiers.<br>
<li><samp>-Zc:wchar_t</samp><br>
Define the macros <tt>_NATIVE_WCHAR_T_DEFINED</tt> and <tt>_WCHAR_T_DEFINED</tt> to 1.<br>
<li><samp>-Zl</samp><br>
Define the macro <tt>_VC_NODEFAULTLIB</tt> to 1.<br>
</ul>
<p><b>mcpp</b> on Mac OS X accepts the following option, on both of GCC-specific-build and compiler-independent-build.</p>
<ul>
<li><samp>-F <framework></samp><br>
Put the <framework> directory to top of the framework directories to search.
The standard framework directories are /System/Library/Frameworks and /Library/Frameworks by default.
</ul>
<p><b>mcpp</b> on Mac OS X accepts the following option on GCC-specific-build.</p>
<ul>
<li><samp>-arch <arch></samp><br>
Change the target architecture of machine as <arch> from the default one.
This causes changes of some predefined macros.
<arch> should be i386 or x86_64 on the preprocessor for x86, ppc or ppc64 on the one for ppc.
(You can specify any of these 4 for <samp>gcc</samp> command.
<samp>gcc</samp> command invokes the preprocessor for x86 on '<samp>-arch i386</samp>' or '<samp>-arch x86_64</samp>' options, and the one for ppc on '<samp>-arch ppc</samp>' or '<samp>-arch ppc64</samp>' options.)
</ul>
<p>The following options (until at the end of this 2.6 section) are available for the GCC-specific-build. Note that since <tt>__STDC__</tt> is set to 1 for GCC, the result is same with or without the -S1 option.</p>
<p>The followings are available across the modes.</p>
<ul>
<li><samp>-$</samp><br>
Same as -fno-dollars-in-identifiers.<br>
<li><samp>-b</samp><br>
Output line number information just like C sources.<br>
The format used to pass the line number information from a preprocessor to compiler-proper is usually as follows:<br>
<pre>
#line 123 "filename"
</pre>
Most compiler systems can use this C source format, but some systems cannot. The default specification of <b>mcpp</b> is such that, in compiler-specific-build for the compiler systems that cannot use the C source format, <b>mcpp</b> outputs the line number information in a format that the compiler-proper can accept it.<br>
However, with this option specified, even in compiler-specific-build for the compiler systems that do not accept the C source format outputs the line number information in that format. This option is used with '#pragma MCPP preprocess' to pre-preprocess header files.<br>
<li><samp>-dD, -dM</samp><br>
Output valid macro definitions in the form of #define lines at the end of preprocessing.<br>
With the -dD option specified, the preprocessing result is output too. Predefined macros are not output.<br>
With the -dM option specified, the preprocessing result is not output, and predefined macros are output except the Standard predefined ones. *3, *4<br>
<li><samp>-fexceptions</samp><br>
Define the macro <tt>__EXCEPTIONS</tt> to 1.<br>
<samp>-fno-exceptions</samp> does not define this macro.<br>
<li><samp>-finput-charset=<encoding></samp><br>
Same as -e <encoding>. Note that GCC convert the <encoding> to UTF-8 by this option, whereas <b>mcpp</b> does not convert any encoding.<br>
<li><samp>-fno-dollars-in-identifiers</samp><br>
Prohibit '$' in identifiers. (Allow it by default.)<br>
<li><samp>-fPIC, -fpic, -fPIE, -fpie</samp><br>
Any of these options defines both of the macro <tt>__PIC__, __pic__</tt> to 1.
<li><samp>-fstack-protector</samp><br>
Define the macro <tt>__SSP__</tt> to 1.<br>
<li><samp>-fstack-protector-all</samp><br>
Define the macro <tt>__SSP_ALL__</tt> to 2.<br>
<li><samp>-fworking-directory</samp><br>
Emit a special line as the second line of preprocessor's output to convey the current working directory.<br>
<li><samp>-I-</samp><br>
Switch the specification of the -I <directory> before and after this option; directories specified with the -I options before -I- are used to search for header files only in the form of #include "header.h"; the directories specified with -I after -I-, if any, are used to search for all #include directives. In addition, during the former search, includer's directories are not used.<br>
<li><samp>-include <file></samp><br>
include the <file> before processing the main source file. This is equivalent to writing #include <file> at the beginning of the main source file.<br>
<li><samp>-iquote <dir></samp><br>
Add <dir> to the include path for #include "header.h" form.<br>
<li><samp>-isysroot=<dir>, -isysroot <dir>, --sysroot=<dir>, --sysroot <dir></samp><br>
Use <dir> as the logical root directory for system headers, that is, prefix <dir> to the path-list of system header directory.
For example, if the default include directory is /usr/include and <dir> is /Developer/SDKs/MacOSX10.4u.sdk, then alter the include directory to /Developer/SDKs/MacOSX10.4u.sdk/usr/include.<br>
<li><samp>-isystem <dir></samp><br>
Add <dir> to the include path immediately before system-specific directories and immediately after site-specific directories.<br>
<li><samp>-lang-c, -x c</samp><br>
Perform C preprocessing. The same as not specifying this option at all.<br>
<li><samp>-mmmx</samp><br>
Predefine a macro <tt>__MMX__</tt> to 1.<br>
<samp>-mno-mmx</samp> undefines <tt>__MMX__</tt>.<br>
<li><samp>-nostdinc</samp><br>
Same as -I- for other compiler systems.<br>
<li><samp>-undef</samp><br>
Same as -N.<br>
<li><samp>-O?</samp><br>
If ? is a non-0 digit, define a macro <tt>__OPTIMIZE__</tt> to 1.<br>
<li><samp>-Wcomment, -Wcomments</samp><br>
Same as -W1. The result is same with or without this option.<br>
<li><samp>-Wtrigraphs</samp><br>
Same as -W16.<br>
<li><samp>-Wall</samp><br>
Same as -W17. (With -Wall, <b>mcpp</b> does not issue class 2 and 4 warnings because these warnings are issued frequently and annoying for Linux or some other system's standard header files. Class 8 warnings are generally surplus and bothering, but are helpful to confirm portability and etc. To use this option, be sure to specify gcc -Wp,-W31.)<br>
<li><samp>-w</samp><br>
Same as -W0.<br>
</ul>
<p>The following options are available for Standard mode.</p>
<ul>
<li><samp>-ansi</samp><br>
Define macro <tt>__STRICT_ANSI__</tt> as 1.
Disable non-conforming predefined macros such as <tt>linux, i386</tt>.<br>
Do not remove comma preceding absent variable argument of GCC-spec variadic. *5<br>
<li><samp>-digraphs</samp><br>
Recognize digraphs. Digraphs specification is also reversed by -2.<br>
<li><samp>-lang-c89, -std=gnu89</samp><br>
Same as -S1. Not only C90 but also C95 specifications are used. The result is same with or without this option.<br>
<li><samp>-std=c89, -std=c90</samp><br>
Almost same as -S1, except these imply -ansi.<br>
<li><samp>-lang-c99, -lang-c9x, -std=gnu99, -std=gnu9x</samp><br>
Same as -V199901L.<br>
<li><samp>-std=c99, -std=c9x</samp><br>
Same as -V199901L and also imply -ansi.<br>
<li><samp>-lang-c++, -x c++</samp><br>
Perform C++ preprocessing. Same as -+.<br>
<li><samp>-std=c++98</samp><br>
Same as -+ and also implies -ansi.<br>
<li><samp>-pedantic, -pedantic-errors</samp><br>
Same as -W7 (i.e. -W1 -W2 -W4).<br>
<li><samp>-std=iso<n>:<ym></samp><br>
Specify a version of C Standard. To specify C, <n> is 9899 and C++, 14882. If <n> is 9899, <ym> is any of 1990, 199409, 1999 and 199901. If <n> is 14882, <ym> is 199711. If you enter other value than these in <ym>, <tt>__STDC_VERSION__</tt> or <tt>__cplusplus</tt> is set to that value. In this case, <ym> must be specified in six digits, like 200503.<br>
These options imply -ansi.
On the other hand, -std=gnu* do not imply -ansi, also -pedantic does not imply -ansi.<br>
</ul>
<p>For <i>STD</i> mode, following options are available. (These cannot be used in <i>POSTSTD</i> mode.)</p>
<ul>
<li><samp>-lang-asm, -x assembler-with-cpp</samp><br>
Same as -a for other compiler systems.
Specify lang-asm mode.
In GCC-specific-build, a macro <tt>__ASSEMBLER__</tt> is defined to 1, and '$' in identifiers are prohibited.
When the main source file is named *.S, lang-asm mode is implicitly specified without this option.<br>
<li><samp>-trigraphs</samp><br>
Recognize trigraphs. Trigraphs specification is also reversed by -3.<br>
</ul>
<p>The following option is available for pre-Standard mode of GCC-specific-build.</p>
<ul>
<li><samp>-traditional, -traditional-cpp</samp><br>
Same as -@old.<br>
</ul>
<p>The next option is available on CygWIN GCC-specific-build.</p>
<ul>
<li><samp>-mno-cygwin</samp><br>
Alter the include directory from /usr/include to /usr/include/mingw, and alter the predefined macros from the ones for cygwin1.dll to the ones for msvcrt.dll.<br>
</ul>
<p><b>mcpp</b> neither makes the following options an error nor does anything about them. (It sometime issues a warning.)</p>
<ul>
<li><samp>-A <predicate(answer)></samp><br>
<b>mcpp</b> ignores this option. In GCC, this option is equivalent to writing #assert <predicate (answer)> in the source code. Standard C, does not permit extension directives other than #pragma. Fortunately, so far, gcc, by default, passes an equivalent macro with the -D option, so there are no actual problems unless a source program uses #assert, which is a rare case.<br>
<br>
<li><samp>-g <n></samp><br>
<li><samp>-idirafter <dir></samp><br>
<li><samp>-iprefix <dir>, -iwithprefix <dir>, -iwithprefixbefore <dir></samp><br>
<li><samp>-noprecomp</samp><br>
<li><samp>-remap</samp><br>
</ul>
<p>In GCC V.3.3 or later, preprocessor has been absorbed into compiler, and independent preprocessor does not exist. Moreover, gcc often passes to preprocessor the options not for preprocessor, even if it is invoked with -no-integrated-cpp option. GCC-specific-build of <b>mcpp</b> for V.3.3 or later ignores the following options, if it cannot recognize them, as that kind of false options.</p>
<ul>
<li><samp>-c</samp><br>
<li><samp>-E</samp><br>
<li><samp>-f*</samp><br>
<li><samp>-m*</samp><br>
<li><samp>-quiet</samp><br>
<li><samp>-W*</samp><br>
</ul>
<p>Note:</p>
<p>*1 -Wa and -Wl are almighty options for assembler and linker, respectively. The documentation on UNIX/System V/cc describes these options. Probably, GCC provides the -W<x> option for compatibility.</p>
<p>*2 In GCC V.3, cpp was absorbed into cc1 (cc1plus). Therefore, the options specified with -Wp are normally passed to cc1 (cc1plus). To have cpp (cpp0), not ccl, preprocess, the -no-integrated-cpp option must be specified on gcc invocation.</p>
<p>*3 GCC V.3.3 or later predefines several dozen of macros. -dD option does not regard these macros as predefined and output them.</p>
<p>*4 The output of -dM option is similar to that of '#pragma MCPP put_defines' ('#put_defines') with the following differences:</p>
<ol>
<li>'put_defines' outputs also Standard predefined macros as comments.<br>
<li>'put_defines' outputs also the file name and the line number of the macro definition as a comment, arranging to readable format. On the other hand, -d* options output in the same simple format with GCC, because some makefiles expect that format.<br>
</ol>
<p>*5 Refer <a href="#3.9.6.3">3.9.6.3</a>.</p>
<br>
<h2><a name="2.7" href="#toc.2.7">2.7. Environment Variables</a></h2>
<p>In compiler-independent-build of <b>mcpp</b>, the include directories are not set up other than /usr/include and /usr/local/include in UNIX systems. Other directories, if required, must be specified using environment variables or runtime options. The environment variable in compiler-independent-build is INCLUDE for C and CPLUS_INCLUDE for C++. Searching the file starts from the includer's source directory by default. (refer to <a href="#4.2"> 4.2</a> for the search rule.) Besides, in Linux there is a confusion of include directories, hence special setup is necessary to cope with this problem.
Refer to <a href="#3.9.9"> 3.9.9</a> for the problem.</p>
<p>For the default include directories on GCC-specific-build, refer to noconfig/*.dif files, and for search rule and environment variable name, refer to <a href="#4.2"> 4.2</a>.</p>
<p>For the environment variable LC_ALL, LC_CTYPE, LANG, refer to <a href="#2.8"> 2.8</a>.</p>
<br>
<h2><a name="2.8" href="#toc.2.8">2.8. Multi-Byte Character Encodings</a></h2>
<p><b>mcpp</b> can process various multi-byte character encodings as follows.</p>
<blockquote>
<table>
<tr><th>EUC-JP </th><td>Japanese extended UNIX code (UJIS)</td></tr>
<tr><th>shift-JIS </th><td>Japanese MS-Kanji</td></tr>
<tr><th>GB-2312 </th><td>EUC-like Chinese encoding (Simplified Chinese)</td></tr>
<tr><th>Big-Five </th><td>Taiwanese encoding (Traditional Chinese)</td></tr>
<tr><th>KSC-5601 </th><td>EUC-like Korean encoding (KSX 1001)</td></tr>
<tr><th>ISO-2022-JP1</th><td>International standard Japanese</td></tr>
<tr><th>UTF-8 </th><td>A kind of Unicode encoding</td></tr>
</table>
</blockquote>
<p>The encoding used during execution can be specified as follows (Priority is given in this order):</p>
<ol>
<li>The encoding specified in '#pragma __setlocale( "<encoding>")' in source code. (For Visual C-specific-build, '#pragma setlocale( "<encoding>")'.) This directive allows you to specify several encodings in one source file.<br>
<li>The encoding specified with -e <encoding> or -finput-charset=<encoding> as run-time option.<br>
<li>The encoding specified with the LC_ALL, LC_CTYPE and LANG environment variables. Priority is given in this order.<br>
<li>The default encoding specified when <b>mcpp</b> is compiled.<br>
</ol>
<p>How to specify a <encoding> is basically same across #pragma __setlocale, -e option, and the environment variables; in the table below, the encoding on the left-side hand is specified by the <encoding> on right-hand side; <encoding> is not case sensitive; '-' and '_' are ignored. Moreover, if it has '.', the character sequence to the '.' is ignored. Therefore, EUC_JP, EUC-JP, EUCJP, euc-jp, eucjp and ja_JP.eucJP are regarded as same. '*' represents any character sequence of zero or more bytes. (iso8859-1, iso8859-2 are equivalent to iso8859*.).</p>
<blockquote>
<table>
<tr><th>EUC-JP </th><td>eucjp, euc, ujis</td></tr>
<tr><th>shift-JIS </th><td>sjis, shiftjis, mskanji</td></tr>
<tr><th>GB-2312 </th><td>gb2312, cngb, euccn</td></tr>
<tr><th>BIG-FIVE </th><td>bigfive, big5, cnbig5, euctw</td></tr>
<tr><th>KSC-5601 </th><td>ksc5601, ksx1001, wansung, euckr</td></tr>
<tr><th>IS0-2022-JP1 </th><td>iso2022jp, iso2022jp1, jis</td></tr>
<tr><th>UTF-8 </th><td>utf8, utf</td></tr>
<tr><th>Not specified</th><td>c, en*, latin*, iso8859*</td></tr>
</table>
</blockquote>
<p>If any of the following encodings is specified, <b>mcpp</b> is no longer able to recognize multi-byte characters: C, en* (english), latin* and iso8859*. When a non-ASCII ISO-8859 Latin-<n> single-byte character set is used, one of these encodings must be specified. When an empty name is used (#pragma __setlocale( "")), the encoding is restored to the default.</p>
<p>Only in the Visual C-specific-build, the following encoding name can be specified with '#pragma setlocale'. This is for compatibility with Visual C++. It is recommended you should use these names because the Visual C++ compiler cannot recognize encoding names other than these. ('-' can be omitted for <b>mcpp</b>, but not for the Visual C++ compiler-proper.)</p>
<blockquote>
<table>
<tr><th>shift-JIS </th><td>japanese, jpn</td></tr>
<tr><th>GB-2312 </th><td>chinese-simplified, chs</td></tr>
<tr><th>BIG-FIVE </th><td>chinese-traditional, cht</td></tr>
<tr><th>KSC-5601 </th><td>korean, kor</td></tr>
<tr><th>Not specified</th><td>C, english</td></tr>
</table>
</blockquote>
<p>In Visual C++, the default multi-byte character encoding varies, depending on what language the language parameter and "Region and Language Option" of Windows are set to. However, the #pragma setlocale specification takes precedence over these Windows's settings.</p>
<p>GCC sometimes fails to handle shift-JIS, ISO2022JP and BIG-FIVE encodings, which contain the byte of 0x5c value.
So, GCC-specific-build of <b>mcpp</b> complements it. *1</p>
<p>Note</p>
<p>*1 If the --enable-c-mbchar option is specified to configure GCC itself, that GCC recognizes an encoding specified by an environmental variable LANG set to one of C-EUCJP, C-SJIS or C-JIS, gcc's info says.
This way of configuring seems to be available from 1998 onward, but it has been seldom used, and its implementation does not work.
Although GCC-specific-build of <b>mcpp</b> had supported these environmental variables, such as LANG=C-SJIS, it removed that feature since V.2.7.<br>
Also GCC info says that, besides LANG, environmental variables LC_ALL and LC_CTYPE can be used to specify an encoding. However, the difference between using LC_ALL or LC_CTYPE or not lies only in their diagnostic messages, in actual.</p>
<br>
<h2><a name="2.9" href="#toc.2.9">2.9. How to Use <b>mcpp</b> in One-Pass Compilers</a></h2>
<p>Compilers whose preprocessor is integrated into themselves are called one-pass compilers. These includes Visual C, Borland C, and LCC-Win32. Such compilers are becoming more popular because they can achieve a little higher processing speed. However, the time for preprocessing becomes shorter due to better hardware performance. In the first place, there is much point for preprocessing to be a common phase, mostly independent of run-time environment and compiler systems. It is not desirable that one-pass compilers become more popular. There will be more compiler-system-specific specifications.</p>
<p>Anyhow, it is impossible to replace the preprocessor of a one-pass compiler with <b>mcpp</b>. To use <b>mcpp</b>, a source program is preprocessed with <b>mcpp</b> and then the output is passed to a one-pass compiler. As you see, preprocessing takes place twice. It is useless but inevitable. Using of <b>mcpp</b> still has merits of source checking and can avail functions not available in resident preprocessor.</p>
<p>To use <b>mcpp</b> with a one-pass compiler, the procedure must be written in makefile. For sample procedures, refer to the makefile re-compilation settings used to compile <b>mcpp</b> itself, such as visualc.mak, borlandc.mak, and lcc_w32.mak.</p>
<p>Although GCC 3 or 4 compiler now integrates its preprocessing facility into itself, gcc provides an option to use an external preprocessor. Use this option when <b>mcpp</b> is used. (See <a href="#3.9.7"> 3.9.7</a>.)</p>
<br>
<h2><a name="2.10" href="#toc.2.10">2.10. How to Use <b>mcpp</b> in IDE</a></h2>
<p>It is difficult to use <b>mcpp</b> in Integrated Development Environment (IDE) because IDE's GUI follows compiler-system-specific specifications and internal interfaces are not usually made available to third parties. Furthermore, one-pass compilers make it more difficult to insert a phase to use <b>mcpp</b>.</p>
<p>This subsection describes how to make <b>mcpp</b> available in Windows / Visual C++ 2003, 2005, 2008 IDE. Use the compiler-specific-build for Borland C and LCC-Win32 on command lines.</p>
<p>Also, it is described here how to make <b>mcpp</b> available in Mac OS X / Xcode.app / Apple-GCC.</p>
<h3><a name="2.10.1" href="#toc.2.10.1">2.10.1. How to Make <b>mcpp</b> Available in Visual C++ IDE</a></h3>
<p><b>mcpp</b> cannot be used in a normal "project" since the internal specifications of Visual C++'s IDE are not made available to third parties and the compiler is a one-pass compiler. However, once a makefile that uses <b>mcpp</b> is created, Visual C++'s IDE can recognize the makefile and you can create a "makefile project" using that file. This allows you to utilize most of the IDE functions, including source editing, search, and source level debugging.</p>
<p>"Creating a Makefile Project" of a Visual C++ 2003 document, Visual C++ 2005 Express Edition Help and Visual C++ 2008 Express Edition Help describe how to make a makefile project. Perform the following procedure to create a makefile project.</p>
<ol>
<li>Login as a user with debugging privilege. *1<br>
<li>Write a makefile that specifies <b>mcpp</b>. (Refer to noconfig/visualc.mak.) *2<br>
<li>Start Visual Studio. *3<br>
<li>Click "New Project" to display the "New Project" window. Select "Makefile Project" and specify "Name" and "Location", and then click "OK".<br>
<li>Then the "Makefile Application Wizard" windows appears. Click "Application settings", and enter appropriate values in the "Build command line", "Output", "Clean commands", and "Rebuild command line" fields.<br>
Let me explain the appropriate values for these fields by taking an example of making the compiler-independent-build of <b>mcpp</b> itself. (Assuming the name of <b>mcpp</b> executable as mcpp.exe.)<br>
<pre>
"Build command line": nmake
"Output": mcpp.exe
"Clean command": nmake clean
"Rebuild command line": nmake PREPROCESSED=1
</pre>
To make the Visual C-specific-build of <b>mcpp</b>, add an option COMPILER=MSC as:
<pre>
"Build command line": nmake COMPILER=MSC
"Output": mcpp.exe
"Clean command": nmake clean
"Rebuild command line": nmake COMPILER=MSC PREPROCESSED=1
</pre>
Since a Makefile project does not provide a 'make install' equivalent command, you must write the makefile in such a way that the commands you specify in "Build command line" and "Rebuild command line" also perform installation. *4<br>
If you do not compile <b>mcpp</b>, "Build command line" and "Rebuild command line" can be the same.<br>
When completed, click "Finish".<br>
<li>Then the Makefile project appears in "Solution Explorer". Click the "Source Files" folder, choose "Add Existing Solution Item" from the "Project" menu, select all the source files, and then click "OK". Then the source file names appear in Solution Explorer.<br>
</ol>
<p>You can now use every functions, including Edit, Build, Rebuild and Debugging.</p>
<p>Note:</p>
<p>*1 On VC 2003 and 2005, to use the debugging function under Windows XP pro or Windows 2000, a user must belong to a group called "Debugger users". However, Windows XP HE does not provide such a group, so one has to login as an administrator. On VC 2008, such a limitation on users group was lifted.</p>
<p>*2 In order to perform the source level debugging function, makefile must be written in such a way that cl.exe is called with the -Zi option appended to generate debugging information.</p>
<p>*3 If you start Visual Studio by selecting "Start" -> "Programs", environment variables, such as for include directories, are not set. In order to have these variables set, you should open the 'Visual Studio command prompt' to start Visual Studio by typing on VC 2003:</p>
<pre>
devenv <Project File> /useenv
</pre>
<p>On VC 2005 express edition and VC 2008 express edition:</p>
<pre>
vcexpress <Project File> /useenv
</pre>
<p>*4 You must have a writing permission to the directory into which you install <b>mcpp</b>.
If you try to install into 'bin' or 'lib' directories of the compiler system, the permission should be carefully set by an administrator account.
It is recommended to make the user account belong to "Power users" or "Authenticated users" group and set "write" and "modify" permissions to the directory for the group.
Another way of controlling the permission is to install the compiler system into a directory which the user has wrinting permission on, such as a shared directory.</p>
<h3><a name="2.10.2" href="#toc.2.10.2">2.10.2. How to Make <b>mcpp</b> available in Mac OS X / Xcode.app</a></h3>
<p>You can use Xcode.app, which is an IDE on Mac OS X, with <b>mcpp</b> without problems. *1</p>
<p>Xcode.app uses gcc (g++) in /Developer/usr/bin rather than /usr/bin for some reason.
(/Developer is the default install directory for Xcode.)
To use <b>mcpp</b> in Xcode.app, you must install GCC-specific-build for the gcc (g++) in that directory.
You should do as follows to install it.
(${mcpp_dir} means the directory where the source of <b>mcpp</b> is placed.)</p>
<pre>
export PATH=/Developer/usr/bin:$PATH
configure ${mcpp_dir}/configure --enable-replace-cpp
make
sudo make install
</pre>
<p>The installation method is the same with that for gcc in /usr/bin, except PATH setting.
So, please refer to INSTALL for installation to cross-compiler or installation of universal binary.</p>
<p>After installing <b>mcpp</b> in such a way, you can use Xcode.app without any special setting for <b>mcpp</b>.
Also the Apple-GCC-specific *.hmap files, which are "header map" files generated by Xcode.app, are read and processed by <b>mcpp</b>.
However, <b>mcpp</b> does not process precompiled-header.
It processes '<samp>#include "header.pch"</samp>' as an ordinary #include.
Also, <b>mcpp</b> does not preprocess Objective-C and Objective-C++, so *.m and *.mm source files are directly handed on to cc1obj and cc1objplus, bypassing <b>mcpp</b>.</p>
<p>When you use <b>mcpp</b>-specific options, specify them as follows:<br>
From screen top menu bar of Xcode.app, select "Project" > "Edit Project Settings".
The "project editor" window will appear.
Then, select "Build" pane of it, and edit "Other C flags" item.
The options should be specified following '-Wp,' and separated by commas, for example:</p>
<pre>
-Wp,-23,-W3
</pre>
<p>Note:</p>
<p>*1 Here we refer to Mac OS X Leopard / Xcode 3.0.</p>
<br>
<h1><a name="3" href="#toc.3">3. Enhancements and Compatibility</a></h1>
<p><b>mcpp</b> has its own enhancements. Each compiler-system-resident preprocessor has its own enhancements, some of which are not available in <b>mcpp</b>. This section covers these enhancements and their compatibility problems.</p>
<p>Principally, <b>mcpp</b> outputs #pragma lines as they are. This principle is applied to the #pragma lines processed by <b>mcpp</b> itself. This is because the compiler-proper may interpret the same #pragma for itself.</p>
<p>However, <b>mcpp</b> does not outputs the lines beginning with '#pragma MCPP', since these are for <b>mcpp</b> only. Also, <b>mcpp</b> does not outputs lines of '#pragma GCC' followed by either 'poison', 'dependency' or 'system_header'. Moreover, <b>mcpp</b> outputs neither of '#pragma once', '#pragma push_macro', nor '#pragma pop_macro' because they are useless on the later phases.
On the other hand, '#pragma GCC visibility *' is outputted, because it is for the compiler and the linker. *1</p>
<p><b>mcpp</b> compiled with <i>EXPAND_PRAGMA</i> == <i>TRUE</i> expands macros in #pragma line (in actual, <i>EXPAND_PRAGMA</i> is set <i>TRUE</i> only for Visual C-specific-build and Borland C-specific-build). However, #pragma lines followed by STDC, MCPP or GCC are never expanded.</p>
<p>#pragma sub-directives are implementation-defined, hence there are risks of same name sub-directive having different meanings to different compiler-systems. Some device is necessary to avoid name collision. Moreover, when <i>EXPAND_PRAGMA</i> == <i>TRUE</i>, there should be a device to avoid the name of #pragma sub-directive itself being macro expanded. This is why <b>mcpp</b>-specific sub-directives begin with '#pragma MCPP' and are not subject to macro expansion. This device is adopted from '#pragma STDC' of C99 and '#pragma GCC' of GCC 3.</p>
<p>'#pragma once' is, however, implemented as it is, since this pragma has been implemented in many preprocessors and has now no risk of name collision. '#pragma __setlocale' is prefixed with "__" instead of MCPP, because it has also meaning for compiler-proper, and because the prefix avoids user-name-space.</p>
<p>Note:</p>
<p>*1 The GCC-specific-build of <b>mcpp</b> only supports '#pragma GCC system_header' of the pragmas starting with GCC. It does not support '#pragma GCC poison' and '#pragma GCC dependency'.</p>
<br>
<h2><a name="3.1" href="#toc.3.1">3.1. #pragma MCPP put_defines, #pragma MCPP preprocess and others</a></h2>
<p><b>mcpp</b> in Standard mode uses '#pragma MCPP put_defines', '#pragma MCPP preprocess' and '#pragma MCPP preprocessed'. Pre-Standard mode uses #put_defines, #preprocess and #preprocessed. Let me explain by taking an example of #pragma.</p>
<p>When <b>mcpp</b> encounters '#pragma MCPP put_defines' directive, it outputs all the macros defined at that time in the form of #define lines. Of course, the #undef-ed macros are not output. The macros that cannot be #defined or #undef-ed, such <tt>__STDC__</tt> and etc, are output in the form of #define lines, but are enclosed with comment marks. (Since <tt>__FILE__</tt> and <tt>__LINE__</tt> are special macros defined dynamically on a macro invocation, the replacement list output here means nothing.)</p>
<p>In pre-Standard mode and <i>POSTSTD</i> mode <b>mcpp</b> do not memorize parameter names of function-like macro definitions. So, these directives mechanically represent names of the first, second, third parameters as a, b, c, ... and so on. If it reaches the 27th parameter, it begins with a1, b1, c1, ..., a2, b2, c2, ... and so on.</p>
<p>If you enter the following directive after invoking <b>mcpp</b> from keyboard without specifying input and output files, all the predefined macros are listed.</p>
<pre>
#pragma MCPP put_defines
</pre>
<p>It also outputs a comment to indicate the source file name where each macro definition is found, as well as its line number. If you invoke <b>mcpp</b> with options such as -S1 or -N, you will see a different set of predefined macros.</p>
<p>When <b>mcpp</b> encounters '#pragma MCPP preprocess' directive, it outputs the following line:</p>
<pre>
#pragma MCPP preprocessed
</pre>
<p>This indicates that the source file has been already preprocessed by <b>mcpp</b>.</p>
<p>When <b>mcpp</b> encounters a '#pragma MCPP preprocessed' directive, it determines that the source file has been preprocessed by <b>mcpp</b> and continues to output the code it reads as it is, until it encounters a #define line. When <b>mcpp</b> does encounter a #define directive, <b>mcpp</b> determines that the rest of the source file are all #define lines and defines macros. At this time, <b>mcpp</b> would memorize the source filename and line number in the comment. *1, *2</p>
<p>A '#pragma MCPP preprocessed' is applied only to the lines that follow the directive in the source file where the '#pragma MCPP preprocessed' directive is found. If the source file is an #included one, when control is returned to the #including file, '#pragma MCPP preprocessed' is no longer applied.</p>
<p>Note:</p>
<p>*1 Actual processing is a little more complex. When <b>mcpp</b> encounters a '#pragma MCPP preprocessed', <b>mcpp</b> outputs lines it has read just as they are, except for #line lines, which compiler-specific-build of <b>mcpp</b> converts and outputs into a format that the compiler-proper can accept. <b>mcpp</b> disregards predefined standard macro because its #define line is enclosed with comment marks.</p>
<p>*2 Therefore, information on where a macro definition is found is not lost during pre-preprocessing.</p>
<h3><a name="3.1.1" href="#toc.3.1.1">3.1.1. Pre-preprocessing of Header File</a></h3>
<p>With above directives, you can "pre-preprocess" header files. Pre-preprocessing considerably saves the entire preprocessing time. I think the explanation so far has already given you an understanding of how to pre-preprocess header files, but to deepen your understanding, let me explain it by taking an example of <b>mcpp</b>'s own source code.</p>
<p><b>mcpp</b> source consists of eight *.c files, of which seven files include "system.H" and "internal.H". No other headers are included. The source looks like this:</p>
<pre>
#if PREPROCESSED
#include "mcpp.H"
#else
#include "system.H"
#include "internal.H"
#endif
</pre>
<p>The system.H includes noconfig.H or configed.H, as well as several standard header files. mcpp.H is not a source file I provide and is a "pre-preprocessed" header file I am going to generate.</p>
<p>To generate mcpp.H (of course, after setting up noconfig.H and other headers), invoke <b>mcpp</b> as follows:</p>
<pre>
mcpp > mcpp.H
</pre>
<p>For compiler systems, such as GCC, also specify the -b option.</p>
<p>Enter the following directives from the keyboard:</p>
<pre>
#pragma MCPP preprocess
#include "system.H"
#include "internal.H"
#pragma MCPP put_defines
</pre>
<p>Enter "end-of-file" to terminate <b>mcpp</b>.</p>
<p>This has accomplished mcpp.H, which consists of the preprocessed system.H and internal.H and a set of #define lines following them. Including mcpp.H gives the same effect as including system.H and internal.H, but its size is one-nth of the original header files including the standard ones. This is because #if and comments are eliminated. It takes far less time to include mcpp.H in seven *.c files than to include system.H and internal.H seven times. By using '#pragma MCPP preprocess', much more time can be saved.</p>
<p>On compilation, use the -DPREPROCESSED=1 option.</p>
<p>It is recommended that the above procedure should be written in a file and the makefile should refer to it. The makefile and preproc.c appended to <b>mcpp</b> sources contain the procedure. Please refer to it.</p>
<p>Although the usage of independent preprocessor is limited for one-pass compilers like Visual C, Borland C or LCC-Win32, the pre-preprocessing facility is useful even for those.</p>
<p>The pre-preprocessing facility of header files is similar to that of the -dD option of GCC, but it differs from it in that:</p>
<ol>
<li>GCC outputs line number information not in the form of '#line 123 "filename"', but in the form of '# 123 "filename"', which allows GCC to reprocess the information, but the Standard C preprocessor cannot.<br>
<li>GCC/cpp of older version outputs a #define line whenever it encounters it, but does not output a #undef line. Therefore, reprocessing the preprocessed result may produce a different result from what the original source intends.<br>
<li>By using '#pragma MCPP preprocess', which is not provided by GCC, <b>mcpp</b> can provides a higher processing speed.<br>
</ol>
<p>As far as the pre-preprocessing facility is concerned, <b>mcpp</b> is more accurate and practical than GCC.</p>
<br>
<h2><a name="3.2" href="#toc.3.2">3.2. #pragma once</a></h2>
<p>#pragma once directive is available in Standard mode.</p>
<p>#pragma once is also available for GCC, Visual C, LCC-Win32 and compiler-independent preprocessor called Wave.</p>
<p>This directive is used when you want to include a header file only once. With the following directive in a header file, <b>mcpp</b> includes the header file only once even if a #include line for that file appears many times.</p>
<pre>
#pragma once
</pre>
<p>Usually, compiler-system-specific standard header files prevent duplicate definitions by using the following code:</p>
<pre>
#ifndef __STDIO_H
#define __STDIO_H
/* Contents of stdio.h */
#endif
</pre>
<p>#pragma once provides similar functionality to this. Using macros always involves reading a header file. (The preprocessor cannot skip reading the code as people do and must read the entire header file for #if's or #endif's; It must read a comment before it can determine whether a line is a directive line, that is, a line with # at the beginning followed by a preprocessing directive; To do so, the preprocessor must identify a string literal; After all, it must read through the entire header file and perform most of tokenization.) #pragma once eliminates the need of even accessing to a header file, resulting in a improved processing speed for multiple includes.</p>
<p>To determine whether two header files are identical, file name characters, including directory names in a search path, are compared. Windows is not case sensitive. Therefore, "/DIR1/header.h" and "/DIR2/header.h" are regarded as distinct, but "header.h" and "HEADER.H" are regarded as the same on Windows, but distinct on UNIX-like systems. A directory is memorized after converting to absolute path, and a symbolic link in UNIX systems is memorized after dereferencing. Moreover, path-list is normalized by removing redundant part such as <samp>"foo/../"</samp>. So, the identical files are determined always correctly. *1, *2, *3</p>
<p>I borrowed the idea of #pragma once from GCC V.1.*/cpp. GCC V.2.*, and V.3.* still has this functionality but it is regarded as obsolete. The specification of GCC V.2.*/cpp has been changed as follows: If the entire header file is enclosed with #ifndef _MACRO, #define _MACRO, and #endif, the cpp memorizes it and inclusion occurs only once, even without #pragma once.</p>
<p>However, this GCC V.2 and V.3 specification sometimes does not work for commercially available compiler systems that are not based on the GCC specification, due to a difference in the standard header file notation. In addition, the GCC V.2 and V.3 specification is more complex to implement. For this reason, I decided to implement only #pragma once.</p>
<p>As with other preprocessors, it is not advisable to rely only on #pragma once when the same header files are used. It is recommended that #pragma once should be combined with macros as follows:</p>
<pre>
#ifndef __STDIO_H
#define __STDIO_H
#pragma once
/* Contents of stdio.h */
#endif
</pre>
<p>Note that #pragma once must not be written in <assert.h>. For the reason, see <a href="cpp-test.html#5.1.2"> cpp-test.html#5.1.2</a>. The same thing can be said with <cassert> and <cassert.h> of C++.</p>
<p>Another problem is that the recent GCC/GLIBC system has header files, like <stddef.h>, which are repeatedly #included by other system headers. They define macros, such as <tt>__need_NULL</tt>, <tt>__need_size_t</tt>, and <tt>__need_ptrdiff_t</tt>, and then #include <stddef.h>. Each time they do so, definitions such as <tt>NULL</tt>, size_t, and ptrdiff_t are defined in the <stddef.h>. The same thing can be said with <errno.h> and <signal.h>, and even with <stdio.h>. Other system headers define macros, such as <tt>__need_FILE, __need___FILE</tt>, and then #include <stdio.h>. Each time they do so, definitions such as FILE may be defined in <stdio.h>. #pragma once can not be used in such header files. *4</p>
<p>Note:</p>
<p>*1 The normalized result can be seen by <samp>'#pragma MCPP debug path'</samp>. See <a href="#3.5.1">3.5.1</a>.
<samp>'#pragma MCPP put_defines'</samp> and diagnostics use the same result, too.<br>
However, the path-list is not normalized usually in #line line.
By default, the #line line is output as specified by #include line, prepending the normalized include path, if any.
But, if -K option is specified, it is normalized so as to be easily utilized by some other tools.</p>
<p>*2 On CygWIN, /bin and /usr/bin are the same directory in real, also /lib and /usr/lib are the same, and supposing / is C:/dir/cygwin on Windows, /cygdrive/c/dir/cygwin is the same as /. <b>mcpp</b> treats these directories as the same, converting the path-list to the format of /cygdrive/c/dir/cygwin/dir-list/file.</p>
<p>*3 On MinGW, / and /usr are the same directory in real. Supposing / is C:/dir/msys/1.0, /c/dir/msys/1.0 is the same as /, and supposing /mingw is C:/dir/mingw, /c/dir/mingw is the same with /mingw. <b>mcpp</b> treats each of these as the same directories, converting the path-list to the format of c:/dir/msys/1.0/dir-list/file or c:/dir/mingw/dir-list/file.</p>
<p>*4 This is applied at least to Linux/GCC 2.9x, 3.* and 4.*/glibc 2.1, 2.2 and 2.3. FreeBSD 4, 5, 6 has much simpler system headers because it does not use glibc.</p>
<h3><a name="3.2.1" href="#toc.3.2.1">3.2.1. Tool to Write #pragma once to Header Files</a></h3>
<p>With a small number of header files, writing #pragma once to them does not require much effort, but it would be tremendous work if there are many header files. I wrote a simple tool to write it automatically to header files.</p>
<p>tool/ins_once.c is a tool written for old versions of GCC. As Borland 5.5 conform to the same standard header file notation with GCC, this tool can be used. However, it is advisable that this tool should not be used in the systems like Glibc 2 that has many exceptions shown above.</p>
<p>Even in the compiler systems that can use the tool, some header files do not strictly conform to the GCC notation. GCC's read-once functionality also does not work properly for these header files.</p>