]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. index:: preprocessor, options, preprocessor, CPP, FPP, Conditional compilation, Preprocessing, preprocessor, include file handling | |
7 | ||
8 | .. _preprocessing-options: | |
9 | ||
10 | Enable and customize preprocessing | |
11 | ********************************** | |
12 | ||
13 | Many Fortran compilers including GNU Fortran allow passing the source code | |
14 | through a C preprocessor (CPP; sometimes also called the Fortran preprocessor, | |
15 | FPP) to allow for conditional compilation. In the case of GNU Fortran, | |
16 | this is the GNU C Preprocessor in the traditional mode. On systems with | |
17 | case-preserving file names, the preprocessor is automatically invoked if the | |
18 | filename extension is :samp:`.F`, :samp:`.FOR`, :samp:`.FTN`, :samp:`.fpp`, | |
19 | :samp:`.FPP`, :samp:`.F90`, :samp:`.F95`, :samp:`.F03` or :samp:`.F08`. To manually | |
20 | invoke the preprocessor on any file, use :option:`-cpp`, to disable | |
21 | preprocessing on files where the preprocessor is run automatically, use | |
22 | :option:`-nocpp`. | |
23 | ||
24 | If a preprocessed file includes another file with the Fortran ``INCLUDE`` | |
25 | statement, the included file is not preprocessed. To preprocess included | |
26 | files, use the equivalent preprocessor statement ``#include``. | |
27 | ||
28 | If GNU Fortran invokes the preprocessor, ``__GFORTRAN__`` | |
29 | is defined. The macros ``__GNUC__``, ``__GNUC_MINOR__`` and | |
30 | ``__GNUC_PATCHLEVEL__`` can be used to determine the version of the | |
31 | compiler. See :ref:`cpp:top` for details. | |
32 | ||
33 | GNU Fortran supports a number of ``INTEGER`` and ``REAL`` kind types | |
34 | in additional to the kind types required by the Fortran standard. | |
35 | The availability of any given kind type is architecture dependent. The | |
36 | following pre-defined preprocessor macros can be used to conditionally | |
37 | include code for these additional kind types: ``__GFC_INT_1__``, | |
38 | ``__GFC_INT_2__``, ``__GFC_INT_8__``, ``__GFC_INT_16__``, | |
39 | ``__GFC_REAL_10__``, and ``__GFC_REAL_16__``. | |
40 | ||
41 | While CPP is the de-facto standard for preprocessing Fortran code, | |
42 | Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines | |
43 | Conditional Compilation, which is not widely used and not directly | |
44 | supported by the GNU Fortran compiler. You can use the program coco | |
45 | to preprocess such files (http://www.daniellnagle.com/coco.html). | |
46 | ||
47 | The following options control preprocessing of Fortran code: | |
48 | ||
49 | .. index:: cpp, fpp, preprocessor, enable, preprocessor, disable | |
50 | ||
51 | .. option:: -cpp, -nocpp | |
52 | ||
53 | Enable preprocessing. The preprocessor is automatically invoked if | |
54 | the file extension is :samp:`.fpp`, :samp:`.FPP`, :samp:`.F`, :samp:`.FOR`, | |
55 | :samp:`.FTN`, :samp:`.F90`, :samp:`.F95`, :samp:`.F03` or :samp:`.F08`. Use | |
56 | this option to manually enable preprocessing of any kind of Fortran file. | |
57 | ||
58 | To disable preprocessing of files with any of the above listed extensions, | |
59 | use the negative form: :option:`-nocpp`. | |
60 | ||
61 | The preprocessor is run in traditional mode. Any restrictions of the | |
62 | file-format, especially the limits on line length, apply for | |
63 | preprocessed output as well, so it might be advisable to use the | |
64 | :option:`-ffree-line-length-none` or :option:`-ffixed-line-length-none` | |
65 | options. | |
66 | ||
67 | .. index:: dM, preprocessor, debugging, debugging, preprocessor | |
68 | ||
69 | .. option:: -dM | |
70 | ||
71 | Instead of the normal output, generate a list of ``'#define'`` | |
72 | directives for all the macros defined during the execution of the | |
73 | preprocessor, including predefined macros. This gives you a way | |
74 | of finding out what is predefined in your version of the preprocessor. | |
75 | Assuming you have no file :samp:`foo.f90`, the command | |
76 | ||
77 | .. code-block:: bash | |
78 | ||
79 | touch foo.f90; gfortran -cpp -E -dM foo.f90 | |
80 | ||
81 | will show all the predefined macros. | |
82 | ||
83 | .. index:: dD, preprocessor, debugging, debugging, preprocessor | |
84 | ||
85 | .. option:: -dD | |
86 | ||
87 | Like :option:`-dM` except in two respects: it does not include the | |
88 | predefined macros, and it outputs both the ``#define`` directives | |
89 | and the result of preprocessing. Both kinds of output go to the | |
90 | standard output file. | |
91 | ||
92 | .. index:: dN, preprocessor, debugging, debugging, preprocessor | |
93 | ||
94 | .. option:: -dN | |
95 | ||
96 | Like :option:`-dD`, but emit only the macro names, not their expansions. | |
97 | ||
98 | .. index:: dU, preprocessor, debugging, debugging, preprocessor | |
99 | ||
100 | .. option:: -dU | |
101 | ||
102 | Like dD except that only macros that are expanded, or whose | |
103 | definedness is tested in preprocessor directives, are output; the | |
104 | output is delayed until the use or test of the macro; and ``'#undef'`` | |
105 | directives are also output for macros tested but undefined at the time. | |
106 | ||
107 | .. index:: dI, preprocessor, debugging, debugging, preprocessor | |
108 | ||
109 | .. option:: -dI | |
110 | ||
111 | Output ``'#include'`` directives in addition to the result | |
112 | of preprocessing. | |
113 | ||
114 | .. index:: fworking-directory, preprocessor, working directory | |
115 | ||
116 | .. option:: -fworking-directory | |
117 | ||
118 | Enable generation of linemarkers in the preprocessor output that will | |
119 | let the compiler know the current working directory at the time of | |
120 | preprocessing. When this option is enabled, the preprocessor will emit, | |
121 | after the initial linemarker, a second linemarker with the current | |
122 | working directory followed by two slashes. GCC will use this directory, | |
123 | when it is present in the preprocessed input, as the directory emitted | |
124 | as the current working directory in some debugging information formats. | |
125 | This option is implicitly enabled if debugging information is enabled, | |
126 | but this can be inhibited with the negated form | |
127 | :option:`-fno-working-directory`. If the :option:`-P` flag is present | |
128 | in the command line, this option has no effect, since no ``#line`` | |
129 | directives are emitted whatsoever. | |
130 | ||
131 | .. index:: idirafter dir, preprocessing, include path | |
132 | ||
133 | .. option:: -idirafter {dir} | |
134 | ||
135 | Search :samp:`{dir}` for include files, but do it after all directories | |
136 | specified with :option:`-I` and the standard system directories have | |
137 | been exhausted. :samp:`{dir}` is treated as a system include directory. | |
138 | If dir begins with ``=``, then the ``=`` will be replaced by | |
139 | the sysroot prefix; see :option:`--sysroot` and :option:`-isysroot`. | |
140 | ||
141 | .. index:: imultilib dir, preprocessing, include path | |
142 | ||
143 | .. option:: -imultilib {dir} | |
144 | ||
145 | Use :samp:`{dir}` as a subdirectory of the directory containing target-specific | |
146 | C++ headers. | |
147 | ||
148 | .. index:: iprefix prefix, preprocessing, include path | |
149 | ||
150 | .. option:: -iprefix {prefix} | |
151 | ||
152 | Specify :samp:`{prefix}` as the prefix for subsequent :option:`-iwithprefix` | |
153 | options. If the :samp:`{prefix}` represents a directory, you should include | |
154 | the final ``'/'``. | |
155 | ||
156 | .. index:: isysroot dir, preprocessing, include path | |
157 | ||
158 | .. option:: -isysroot {dir} | |
159 | ||
160 | This option is like the :option:`--sysroot` option, but applies only to | |
161 | header files. See the :option:`--sysroot` option for more information. | |
162 | ||
163 | .. index:: iquote dir, preprocessing, include path | |
164 | ||
165 | .. option:: -iquote {dir} | |
166 | ||
167 | Search :samp:`{dir}` only for header files requested with ``#include "file"`` ; | |
168 | they are not searched for ``#include <file>``, before all directories | |
169 | specified by :option:`-I` and before the standard system directories. If | |
170 | :samp:`{dir}` begins with ``=``, then the ``=`` will be replaced by the | |
171 | sysroot prefix; see :option:`--sysroot` and :option:`-isysroot`. | |
172 | ||
173 | .. index:: isystem dir, preprocessing, include path | |
174 | ||
175 | .. option:: -isystem {dir} | |
176 | ||
177 | Search :samp:`{dir}` for header files, after all directories specified by | |
178 | :option:`-I` but before the standard system directories. Mark it as a | |
179 | system directory, so that it gets the same special treatment as is | |
180 | applied to the standard system directories. If :samp:`{dir}` begins with | |
181 | ``=``, then the ``=`` will be replaced by the sysroot prefix; | |
182 | see :option:`--sysroot` and :option:`-isysroot`. | |
183 | ||
184 | .. index:: nostdinc | |
185 | ||
186 | .. option:: -nostdinc | |
187 | ||
188 | Do not search the standard system directories for header files. Only | |
189 | the directories you have specified with :option:`-I` options (and the | |
190 | directory of the current file, if appropriate) are searched. | |
191 | ||
192 | .. index:: undef | |
193 | ||
194 | .. option:: -undef | |
195 | ||
196 | Do not predefine any system-specific or GCC-specific macros. | |
197 | The standard predefined macros remain defined. | |
198 | ||
199 | .. index:: Apredicate=answer, preprocessing, assertion | |
200 | ||
201 | .. option:: -Apredicate={answer} | |
202 | ||
203 | Make an assertion with the predicate :samp:`{predicate}` and answer :samp:`{answer}`. | |
204 | This form is preferred to the older form -A predicate(answer), which is still | |
205 | supported, because it does not use shell special characters. | |
206 | ||
207 | .. index:: A-predicate=answer, preprocessing, assertion | |
208 | ||
209 | .. option:: -A-predicate={answer} | |
210 | ||
211 | Cancel an assertion with the predicate :samp:`{predicate}` and answer :samp:`{answer}`. | |
212 | ||
213 | .. index:: C, preprocessing, keep comments | |
214 | ||
215 | .. option:: -C | |
216 | ||
217 | Do not discard comments. All comments are passed through to the output | |
218 | file, except for comments in processed directives, which are deleted | |
219 | along with the directive. | |
220 | ||
221 | You should be prepared for side effects when using :option:`-C` ; it causes | |
222 | the preprocessor to treat comments as tokens in their own right. For example, | |
223 | comments appearing at the start of what would be a directive line have the | |
224 | effect of turning that line into an ordinary source line, since the first | |
225 | token on the line is no longer a ``'#'``. | |
226 | ||
227 | Warning: this currently handles C-Style comments only. The preprocessor | |
228 | does not yet recognize Fortran-style comments. | |
229 | ||
230 | .. index:: CC, preprocessing, keep comments | |
231 | ||
232 | .. option:: -CC | |
233 | ||
234 | Do not discard comments, including during macro expansion. This is like | |
235 | :option:`-C`, except that comments contained within macros are also passed | |
236 | through to the output file where the macro is expanded. | |
237 | ||
238 | In addition to the side-effects of the :option:`-C` option, the :option:`-CC` | |
239 | option causes all C++-style comments inside a macro to be converted to C-style | |
240 | comments. This is to prevent later use of that macro from inadvertently | |
241 | commenting out the remainder of the source line. The :option:`-CC` option | |
242 | is generally used to support lint comments. | |
243 | ||
244 | Warning: this currently handles C- and C++-Style comments only. The | |
245 | preprocessor does not yet recognize Fortran-style comments. | |
246 | ||
247 | .. index:: Dname, preprocessing, define macros | |
248 | ||
249 | .. option:: -Dname | |
250 | ||
251 | Predefine name as a macro, with definition ``1``. | |
252 | ||
253 | .. index:: Dname=definition, preprocessing, define macros | |
254 | ||
255 | .. option:: -Dname={definition} | |
256 | ||
257 | The contents of :samp:`{definition}` are tokenized and processed as if they | |
258 | appeared during translation phase three in a ``'#define'`` directive. | |
259 | In particular, the definition will be truncated by embedded newline | |
260 | characters. | |
261 | ||
262 | If you are invoking the preprocessor from a shell or shell-like program | |
263 | you may need to use the shell's quoting syntax to protect characters such | |
264 | as spaces that have a meaning in the shell syntax. | |
265 | ||
266 | If you wish to define a function-like macro on the command line, write | |
267 | its argument list with surrounding parentheses before the equals sign | |
268 | (if any). Parentheses are meaningful to most shells, so you will need | |
269 | to quote the option. With sh and csh, ``-D'name(args...)=definition'`` | |
270 | works. | |
271 | ||
272 | :option:`-D` and :option:`-U` options are processed in the order they are | |
273 | given on the command line. All -imacros file and -include file options | |
274 | are processed after all -D and -U options. | |
275 | ||
276 | .. index:: H | |
277 | ||
278 | .. option:: -H | |
279 | ||
280 | Print the name of each header file used, in addition to other normal | |
281 | activities. Each name is indented to show how deep in the ``'#include'`` | |
282 | stack it is. | |
283 | ||
284 | .. index:: P, preprocessing, no linemarkers | |
285 | ||
286 | .. option:: -P | |
287 | ||
288 | Inhibit generation of linemarkers in the output from the preprocessor. | |
289 | This might be useful when running the preprocessor on something that | |
290 | is not C code, and will be sent to a program which might be confused | |
291 | by the linemarkers. | |
292 | ||
293 | .. index:: Uname, preprocessing, undefine macros | |
294 | ||
295 | .. option:: -Uname | |
296 | ||
297 | Cancel any previous definition of :samp:`{name}`, either built in or provided | |
3ed1b4ce | 298 | with a :option:`-D` option. |