]>
Commit | Line | Data |
---|---|---|
b4c522fa IB |
1 | \input texinfo @c -*-texinfo-*- |
2 | @setfilename gdc.info | |
3 | @settitle The GNU D Compiler | |
4 | ||
5 | @c Merge the standard indexes into a single one. | |
6 | @syncodeindex fn cp | |
7 | @syncodeindex vr cp | |
8 | @syncodeindex ky cp | |
9 | @syncodeindex pg cp | |
10 | @syncodeindex tp cp | |
11 | ||
12 | @include gcc-common.texi | |
13 | ||
14 | @c Copyright years for this manual. | |
abc1ac2d | 15 | @set copyrights-d 2006-2022 |
b4c522fa IB |
16 | |
17 | @copying | |
18 | @c man begin COPYRIGHT | |
19 | Copyright @copyright{} @value{copyrights-d} Free Software Foundation, Inc. | |
20 | ||
21 | Permission is granted to copy, distribute and/or modify this document | |
22 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
23 | any later version published by the Free Software Foundation; with no | |
24 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. | |
25 | A copy of the license is included in the | |
26 | @c man end | |
27 | section entitled ``GNU Free Documentation License''. | |
28 | @ignore | |
29 | @c man begin COPYRIGHT | |
30 | man page gfdl(7). | |
31 | @c man end | |
32 | @end ignore | |
33 | @end copying | |
34 | ||
35 | @ifinfo | |
36 | @format | |
37 | @dircategory Software development | |
38 | @direntry | |
39 | * gdc: (gdc). A GCC-based compiler for the D language | |
40 | @end direntry | |
41 | @end format | |
42 | ||
43 | @insertcopying | |
44 | @end ifinfo | |
45 | ||
46 | @titlepage | |
47 | @title The GNU D Compiler | |
48 | @versionsubtitle | |
49 | @author David Friedman, Iain Buclaw | |
50 | ||
51 | @page | |
52 | @vskip 0pt plus 1filll | |
53 | Published by the Free Software Foundation @* | |
54 | 51 Franklin Street, Fifth Floor@* | |
55 | Boston, MA 02110-1301, USA@* | |
56 | @sp 1 | |
57 | @insertcopying | |
58 | @end titlepage | |
59 | @contents | |
60 | @page | |
61 | ||
62 | @node Top | |
63 | @top Introduction | |
64 | ||
65 | This manual describes how to use @command{gdc}, the GNU compiler for | |
66 | the D programming language. This manual is specifically about | |
67 | @command{gdc}. For more information about the D programming | |
68 | language in general, including language specifications and standard | |
cff8fa9a | 69 | package documentation, see @uref{https://dlang.org/}. |
b4c522fa IB |
70 | |
71 | @menu | |
72 | * Copying:: The GNU General Public License. | |
73 | * GNU Free Documentation License:: | |
74 | How you can share and copy this manual. | |
75 | * Invoking gdc:: How to run gdc. | |
76 | * Index:: Index. | |
77 | @end menu | |
78 | ||
79 | ||
80 | @include gpl_v3.texi | |
81 | ||
82 | @include fdl.texi | |
83 | ||
84 | ||
85 | @node Invoking gdc | |
86 | @chapter Invoking gdc | |
87 | ||
88 | @c man title gdc A GCC-based compiler for the D language | |
89 | ||
90 | @ignore | |
91 | @c man begin SYNOPSIS gdc | |
92 | gdc [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}] | |
93 | [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}] | |
94 | [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}] | |
95 | [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}] | |
96 | [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{} | |
97 | ||
98 | Only the most useful options are listed here; see below for the | |
99 | remainder. | |
100 | @c man end | |
101 | @c man begin SEEALSO | |
102 | gpl(7), gfdl(7), fsf-funding(7), gcc(1) | |
103 | and the Info entries for @file{gdc} and @file{gcc}. | |
104 | @c man end | |
105 | @end ignore | |
106 | ||
107 | @c man begin DESCRIPTION gdc | |
108 | ||
109 | The @command{gdc} command is the GNU compiler for the D language and | |
110 | supports many of the same options as @command{gcc}. @xref{Option Summary, , | |
111 | Option Summary, gcc, Using the GNU Compiler Collection (GCC)}. | |
112 | This manual only documents the options specific to @command{gdc}. | |
113 | ||
114 | @c man end | |
115 | ||
116 | @menu | |
117 | * Input and Output files:: Controlling the kind of output: | |
118 | an executable, object files, assembler files, | |
119 | * Runtime Options:: Options controlling runtime behavior | |
120 | * Directory Options:: Where to find module files | |
121 | * Code Generation:: Options controlling the output of gdc | |
122 | * Warnings:: Options controlling warnings specific to gdc | |
123 | * Linking:: Options influencing the linking step | |
124 | * Developer Options:: Options useful for developers of gdc | |
125 | @end menu | |
126 | ||
127 | @c man begin OPTIONS | |
128 | ||
129 | @node Input and Output files | |
130 | @section Input and Output files | |
131 | @cindex suffixes for D source | |
132 | @cindex D source file suffixes | |
133 | ||
134 | For any given input file, the file name suffix determines what kind of | |
135 | compilation is done. The following kinds of input file names are supported: | |
136 | ||
137 | @table @gcctabopt | |
138 | @item @var{file}.d | |
139 | D source files. | |
140 | @item @var{file}.dd | |
141 | Ddoc source files. | |
142 | @item @var{file}.di | |
143 | D interface files. | |
144 | @end table | |
145 | ||
146 | You can specify more than one input file on the @command{gdc} command line, | |
147 | each being compiled separately in the compilation process. If you specify a | |
148 | @code{-o @var{file}} option, all the input files are compiled together, | |
149 | producing a single output file, named @var{file}. This is allowed even | |
150 | when using @code{-S} or @code{-c}. | |
151 | ||
152 | @cindex D interface files. | |
153 | A D interface file contains only what an import of the module needs, | |
154 | rather than the whole implementation of that module. They can be created | |
155 | by @command{gdc} from a D source file by using the @code{-H} option. | |
156 | When the compiler resolves an import declaration, it searches for matching | |
157 | @file{.di} files first, then for @file{.d}. | |
158 | ||
159 | @cindex Ddoc source files. | |
160 | A Ddoc source file contains code in the D macro processor language. It is | |
161 | primarily designed for use in producing user documentation from embedded | |
162 | comments, with a slight affinity towards HTML generation. If a @file{.d} | |
163 | source file starts with the string @code{Ddoc} then it is treated as general | |
164 | purpose documentation, not as a D source file. | |
165 | ||
166 | @node Runtime Options | |
167 | @section Runtime Options | |
168 | @cindex options, runtime | |
169 | ||
170 | These options affect the runtime behavior of programs compiled with | |
171 | @command{gdc}. | |
172 | ||
173 | @table @gcctabopt | |
174 | ||
175 | @item -fall-instantiations | |
176 | @cindex @option{-fall-instantiations} | |
177 | @cindex @option{-fno-all-instantiations} | |
178 | Generate code for all template instantiations. The default template emission | |
179 | strategy is to not generate code for declarations that were either | |
180 | instantiated speculatively, such as from @code{__traits(compiles, ...)}, or | |
181 | that come from an imported module not being compiled. | |
182 | ||
183 | @item -fno-assert | |
184 | @cindex @option{-fassert} | |
185 | @cindex @option{-fno-assert} | |
186 | Turn off code generation for @code{assert} contracts. | |
187 | ||
188 | @item -fno-bounds-check | |
189 | @cindex @option{-fbounds-check} | |
190 | @cindex @option{-fno-bounds-check} | |
191 | Turns off array bounds checking for all functions, which can improve | |
192 | performance for code that uses arrays extensively. Note that this | |
193 | can result in unpredictable behavior if the code in question actually | |
194 | does violate array bounds constraints. It is safe to use this option | |
195 | if you are sure that your code never throws a @code{RangeError}. | |
196 | ||
197 | @item -fbounds-check=@var{value} | |
198 | @cindex @option{-fbounds-check=} | |
199 | An alternative to @option{-fbounds-check} that allows more control | |
200 | as to where bounds checking is turned on or off. The following values | |
201 | are supported: | |
202 | ||
203 | @table @samp | |
204 | @item on | |
205 | Turns on array bounds checking for all functions. | |
206 | @item safeonly | |
207 | Turns on array bounds checking only for @code{@@safe} functions. | |
208 | @item off | |
209 | Turns off array bounds checking completely. | |
210 | @end table | |
211 | ||
212 | @item -fno-builtin | |
213 | @cindex @option{-fbuiltin} | |
214 | @cindex @option{-fno-builtin} | |
215 | Don't recognize built-in functions unless they begin with the prefix | |
216 | @samp{__builtin_}. By default, the compiler will recognize when a | |
217 | function in the @code{core.stdc} package is a built-in function. | |
218 | ||
47fe7be6 IB |
219 | @item -fcheckaction=@var{value} |
220 | @cindex @option{-fcheckaction} | |
221 | This option controls what code is generated on an assertion, bounds check, or | |
222 | final switch failure. The following values are supported: | |
223 | ||
224 | @table @samp | |
225 | @item context | |
226 | Throw an @code{AssertError} with extra context information. | |
227 | @item halt | |
228 | Halt the program execution. | |
229 | @item throw | |
230 | Throw an @code{AssertError} (the default). | |
231 | @end table | |
232 | ||
b4c522fa IB |
233 | @item -fdebug |
234 | @item -fdebug=@var{value} | |
235 | @cindex @option{-fdebug} | |
236 | @cindex @option{-fno-debug} | |
237 | Turn on compilation of conditional @code{debug} code into the program. | |
238 | The @option{-fdebug} option itself sets the debug level to @code{1}, | |
239 | while @option{-fdebug=} enables @code{debug} code that are identified | |
240 | by any of the following values: | |
241 | ||
242 | @table @samp | |
243 | @item level | |
244 | Sets the debug level to @var{level}, any @code{debug} code <= @var{level} | |
245 | is compiled into the program. | |
246 | @item ident | |
247 | Turns on compilation of any @code{debug} code identified by @var{ident}. | |
248 | @end table | |
249 | ||
c0aebc60 IB |
250 | @item -fno-druntime |
251 | @cindex @option{-fdruntime} | |
252 | @cindex @option{-fno-druntime} | |
253 | Implements @uref{https://dlang.org/spec/betterc.html}. Assumes that | |
254 | compilation targets an environment without a D runtime library. | |
255 | ||
256 | This is equivalent to compiling with the following options: | |
257 | ||
258 | @example | |
259 | gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti | |
260 | @end example | |
261 | ||
47fe7be6 IB |
262 | @item -fextern-std=@var{standard} |
263 | @cindex @option{-fextern-std} | |
264 | Sets the C++ name mangling compatibility to the version identified by | |
265 | @var{standard}. The following values are supported: | |
266 | ||
267 | @table @samp | |
268 | @item c++98 | |
269 | @item c++03 | |
fd43568c | 270 | Sets @code{__traits(getTargetInfo, "cppStd")} to @code{199711}. |
47fe7be6 | 271 | @item c++11 |
fd43568c | 272 | Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201103}. |
47fe7be6 | 273 | @item c++14 |
fd43568c | 274 | Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201402}. |
47fe7be6 | 275 | @item c++17 |
fd43568c IB |
276 | Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201703}. |
277 | This is the default. | |
47fe7be6 | 278 | @item c++20 |
fd43568c | 279 | Sets @code{__traits(getTargetInfo, "cppStd")} to @code{202002}. |
47fe7be6 IB |
280 | @end table |
281 | ||
b4c522fa IB |
282 | @item -fno-invariants |
283 | @cindex @option{-finvariants} | |
284 | @cindex @option{-fno-invariants} | |
285 | Turns off code generation for class @code{invariant} contracts. | |
286 | ||
0fb57034 IB |
287 | @item -fmain |
288 | @cindex @option{-fmain} | |
289 | Generates a default @code{main()} function when compiling. This is useful when | |
290 | unittesting a library, as it enables running the unittests in a library without | |
291 | having to manually define an entry-point function. This option does nothing | |
292 | when @code{main} is already defined in user code. | |
293 | ||
b4c522fa IB |
294 | @item -fno-moduleinfo |
295 | @cindex @option{-fmoduleinfo} | |
296 | @cindex @option{-fno-moduleinfo} | |
297 | Turns off generation of the @code{ModuleInfo} and related functions | |
298 | that would become unreferenced without it, which may allow linking | |
299 | to programs not written in D. Functions that are not be generated | |
300 | include module constructors and destructors (@code{static this} and | |
301 | @code{static ~this}), @code{unittest} code, and @code{DSO} registry | |
302 | functions for dynamically linked code. | |
303 | ||
304 | @item -fonly=@var{filename} | |
305 | @cindex @option{-fonly} | |
306 | Tells the compiler to parse and run semantic analysis on all modules | |
307 | on the command line, but only generate code for the module specified | |
308 | by @var{filename}. | |
309 | ||
310 | @item -fno-postconditions | |
311 | @cindex @option{-fpostconditions} | |
312 | @cindex @option{-fno-postconditions} | |
313 | Turns off code generation for postcondition @code{out} contracts. | |
314 | ||
315 | @item -fno-preconditions | |
316 | @cindex @option{-fpreconditions} | |
317 | @cindex @option{-fno-preconditions} | |
318 | Turns off code generation for precondition @code{in} contracts. | |
319 | ||
47fe7be6 IB |
320 | @item -fpreview=@var{id} |
321 | @cindex @option{-fpreview} | |
322 | Turns on an upcoming D language change identified by @var{id}. The following | |
323 | values are supported: | |
324 | ||
325 | @table @samp | |
326 | @item all | |
327 | Turns on all upcoming D language features. | |
328 | @item dip1000 | |
e56b695a IB |
329 | Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md} |
330 | (Scoped pointers). | |
47fe7be6 | 331 | @item dip1008 |
e56b695a IB |
332 | Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md} |
333 | (Allow exceptions in @code{@@nogc} code). | |
47fe7be6 | 334 | @item dip1021 |
e56b695a IB |
335 | Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md} |
336 | (Mutable function arguments). | |
47fe7be6 | 337 | @item dip25 |
e56b695a IB |
338 | Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md} |
339 | (Sealed references). | |
47fe7be6 IB |
340 | @item dtorfields |
341 | Turns on generation for destructing fields of partially constructed objects. | |
342 | @item fieldwise | |
343 | Turns on generation of struct equality to use field-wise comparisons. | |
344 | @item fixaliasthis | |
345 | Implements new lookup rules that check the current scope for @code{alias this} | |
346 | before searching in upper scopes. | |
7e7ebe3e IB |
347 | @item fiximmutableconv |
348 | Disallows unsound immutable conversions that were formerly incorrectly | |
349 | permitted. | |
47fe7be6 IB |
350 | @item in |
351 | Implements @code{in} parameters to mean @code{scope const [ref]} and accepts | |
352 | rvalues. | |
353 | @item inclusiveincontracts | |
354 | Implements @code{in} contracts of overridden methods to be a superset of parent | |
355 | contract. | |
356 | @item intpromote | |
357 | Implements C-style integral promotion for unary @code{+}, @code{-} and @code{~} | |
358 | expressions. | |
359 | @item nosharedaccess | |
360 | Turns off and disallows all access to shared memory objects. | |
361 | @item rvaluerefparam | |
362 | Implements rvalue arguments to @code{ref} parameters. | |
7e7ebe3e IB |
363 | @item systemvariables |
364 | Disables access to variables marked @code{@@system} from @code{@@safe} code. | |
47fe7be6 IB |
365 | @end table |
366 | ||
b4c522fa IB |
367 | @item -frelease |
368 | @cindex @option{-frelease} | |
369 | @cindex @option{-fno-release} | |
370 | Turns on compiling in release mode, which means not emitting runtime | |
371 | checks for contracts and asserts. Array bounds checking is not done | |
372 | for @code{@@system} and @code{@@trusted} functions, and assertion | |
373 | failures are undefined behavior. | |
374 | ||
375 | This is equivalent to compiling with the following options: | |
376 | ||
377 | @example | |
378 | gdc -fno-assert -fbounds-check=safe -fno-invariants \ | |
379 | -fno-postconditions -fno-preconditions -fno-switch-errors | |
380 | @end example | |
381 | ||
47fe7be6 IB |
382 | @item -frevert= |
383 | @cindex @option{-frevert} | |
384 | Turns off a D language feature identified by @var{id}. The following values | |
385 | are supported: | |
386 | ||
387 | @table @samp | |
388 | @item all | |
389 | Turns off all revertable D language features. | |
390 | @item dip25 | |
e56b695a IB |
391 | Reverts @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md} |
392 | (Sealed references). | |
47fe7be6 IB |
393 | @item dtorfields |
394 | Turns off generation for destructing fields of partially constructed objects. | |
395 | @item markdown | |
396 | Turns off Markdown replacements in Ddoc comments. | |
397 | @end table | |
398 | ||
c0aebc60 IB |
399 | @item -fno-rtti |
400 | @cindex @option{-frtti} | |
401 | @cindex @option{-fno-rtti} | |
402 | Turns off generation of run-time type information for all user defined types. | |
403 | Any code that uses features of the language that require access to this | |
404 | information will result in an error. | |
405 | ||
b4c522fa IB |
406 | @item -fno-switch-errors |
407 | @cindex @option{-fswitch-errors} | |
408 | @cindex @option{-fno-switch-errors} | |
409 | This option controls what code is generated when no case is matched | |
410 | in a @code{final switch} statement. The default run time behavior | |
411 | is to throw a @code{SwitchError}. Turning off @option{-fswitch-errors} | |
412 | means that instead the execution of the program is immediately halted. | |
413 | ||
414 | @item -funittest | |
415 | @cindex @option{-funittest} | |
416 | @cindex @option{-fno-unittest} | |
417 | Turns on compilation of @code{unittest} code, and turns on the | |
418 | @code{version(unittest)} identifier. This implies @option{-fassert}. | |
419 | ||
420 | @item -fversion=@var{value} | |
421 | @cindex @option{-fversion} | |
422 | Turns on compilation of conditional @code{version} code into the program | |
423 | identified by any of the following values: | |
424 | ||
425 | @table @samp | |
426 | @item level | |
427 | Sets the version level to @var{level}, any @code{version} code >= @var{level} | |
428 | is compiled into the program. | |
429 | @item ident | |
430 | Turns on compilation of @code{version} code identified by @var{ident}. | |
431 | @end table | |
432 | ||
76a7e7e7 IB |
433 | @item -fno-weak-templates |
434 | @cindex @option{-fweak-templates} | |
435 | @cindex @option{-fno-weak-templates} | |
436 | Turns off emission of declarations that can be defined in multiple objects as | |
437 | weak symbols. The default is to emit all public symbols as weak, unless the | |
438 | target lacks support for weak symbols. Disabling this option means that common | |
439 | symbols are instead put in COMDAT or become private. | |
b4c522fa IB |
440 | |
441 | @end table | |
442 | ||
443 | @node Directory Options | |
444 | @section Options for Directory Search | |
445 | @cindex directory options | |
446 | @cindex options, directory search | |
447 | @cindex search path | |
448 | ||
449 | These options specify directories to search for files, libraries, and | |
450 | other parts of the compiler: | |
451 | ||
452 | @table @gcctabopt | |
453 | ||
454 | @item -I@var{dir} | |
455 | @cindex @option{-I} | |
456 | Specify a directory to use when searching for imported modules at | |
457 | compile time. Multiple @option{-I} options can be used, and the | |
458 | paths are searched in the same order. | |
459 | ||
460 | @item -J@var{dir} | |
461 | @cindex @option{-J} | |
462 | Specify a directory to use when searching for files in string imports | |
463 | at compile time. This switch is required in order to use | |
464 | @code{import(file)} expressions. Multiple @option{-J} options can be | |
465 | used, and the paths are searched in the same order. | |
466 | ||
467 | @item -L@var{dir} | |
468 | @cindex @option{-L} | |
469 | When linking, specify a library search directory, as with @command{gcc}. | |
470 | ||
471 | @item -B@var{dir} | |
472 | @cindex @option{-B} | |
473 | This option specifies where to find the executables, libraries, | |
474 | source files, and data files of the compiler itself, as with @command{gcc}. | |
475 | ||
476 | @item -fmodule-file=@var{module}=@var{spec} | |
477 | @cindex @option{-fmodule-file} | |
478 | This option manipulates file paths of imported modules, such that if an | |
479 | imported module matches all or the leftmost part of @var{module}, the file | |
480 | path in @var{spec} is used as the location to search for D sources. | |
481 | This is used when the source file path and names are not the same as the | |
482 | package and module hierarchy. Consider the following examples: | |
483 | ||
484 | @example | |
485 | gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar | |
486 | @end example | |
487 | ||
488 | This will tell the compiler to search in all import paths for the source | |
489 | file @var{foo.d} when importing @var{A.B}, and the directory @var{bar/} | |
490 | when importing @var{C}, as annotated in the following D code: | |
491 | ||
492 | @example | |
493 | module test; | |
494 | import A.B; // Matches A.B, searches for foo.d | |
495 | import C.D.E; // Matches C, searches for bar/D/E.d | |
496 | import A.B.C; // No match, searches for A/B/C.d | |
497 | @end example | |
498 | ||
499 | @item -imultilib @var{dir} | |
500 | @cindex @option{-imultilib} | |
501 | Use @var{dir} as a subdirectory of the gcc directory containing | |
502 | target-specific D sources and interfaces. | |
503 | ||
504 | @item -iprefix @var{prefix} | |
505 | @cindex @option{-iprefix} | |
506 | Specify @var{prefix} as the prefix for the gcc directory containing | |
507 | target-specific D sources and interfaces. If the @var{prefix} represents | |
508 | a directory, you should include the final @code{'/'}. | |
509 | ||
510 | @item -nostdinc | |
511 | @cindex @option{-nostdinc} | |
512 | Do not search the standard system directories for D source and interface | |
513 | files. Only the directories that have been specified with @option{-I} options | |
514 | (and the directory of the current file, if appropriate) are searched. | |
515 | ||
516 | @end table | |
517 | ||
518 | @node Code Generation | |
519 | @section Code Generation | |
520 | @cindex options, code generation | |
521 | ||
522 | In addition to the many @command{gcc} options controlling code generation, | |
523 | @command{gdc} has several options specific to itself. | |
524 | ||
525 | @table @gcctabopt | |
526 | ||
527 | @item -H | |
528 | @cindex @option{-H} | |
529 | Generates D interface files for all modules being compiled. The compiler | |
530 | determines the output file based on the name of the input file, removes | |
531 | any directory components and suffix, and applies the @file{.di} suffix. | |
532 | ||
533 | @item -Hd @var{dir} | |
534 | @cindex @option{-Hd} | |
535 | Same as @option{-H}, but writes interface files to directory @var{dir}. | |
536 | This option can be used with @option{-Hf @var{file}} to independently set the | |
537 | output file and directory path. | |
538 | ||
539 | @item -Hf @var{file} | |
540 | @cindex @option{-Hf} | |
541 | Same as @option{-H} but writes interface files to @var{file}. This option can | |
542 | be used with @option{-Hd @var{dir}} to independently set the output file and | |
543 | directory path. | |
544 | ||
545 | @item -M | |
546 | @cindex @option{-M} | |
547 | Output the module dependencies of all source files being compiled in a | |
548 | format suitable for @command{make}. The compiler outputs one | |
549 | @command{make} rule containing the object file name for that source file, | |
550 | a colon, and the names of all imported files. | |
551 | ||
552 | @item -MM | |
553 | @cindex @option{-MM} | |
554 | Like @option{-M} but does not mention imported modules from the D standard | |
555 | library package directories. | |
556 | ||
557 | @item -MF @var{file} | |
558 | @cindex @option{-MF} | |
559 | When used with @option{-M} or @option{-MM}, specifies a @var{file} to write | |
560 | the dependencies to. When used with the driver options @option{-MD} or | |
561 | @option{-MMD}, @option{-MF} overrides the default dependency output file. | |
562 | ||
563 | @item -MG | |
564 | @cindex @option{-MG} | |
565 | This option is for compatibility with @command{gcc}, and is ignored by the | |
566 | compiler. | |
567 | ||
568 | @item -MP | |
569 | @cindex @option{-MP} | |
570 | Outputs a phony target for each dependency other than the modules being | |
571 | compiled, causing each to depend on nothing. | |
572 | ||
573 | @item -MT @var{target} | |
574 | @cindex @option{-MT} | |
575 | Change the @var{target} of the rule emitted by dependency generation | |
576 | to be exactly the string you specify. If you want multiple targets, | |
577 | you can specify them as a single argument to @option{-MT}, or use | |
578 | multiple @option{-MT} options. | |
579 | ||
580 | @item -MQ @var{target} | |
581 | @cindex @option{-MQ} | |
582 | Same as @option{-MT}, but it quotes any characters which are special to | |
583 | @command{make}. | |
584 | ||
585 | @item -MD | |
586 | @cindex @option{-MD} | |
587 | This option is equivalent to @option{-M -MF @var{file}}. The driver | |
588 | determines @var{file} by removing any directory components and suffix | |
589 | from the input file, and then adding a @file{.deps} suffix. | |
590 | ||
591 | @item -MMD | |
592 | @cindex @option{-MMD} | |
593 | Like @option{-MD} but does not mention imported modules from the D standard | |
594 | library package directories. | |
595 | ||
596 | @item -X | |
597 | @cindex @option{-X} | |
598 | Output information describing the contents of all source files being | |
599 | compiled in JSON format to a file. The driver determines @var{file} by | |
600 | removing any directory components and suffix from the input file, and then | |
601 | adding a @file{.json} suffix. | |
602 | ||
603 | @item -Xf @var{file} | |
604 | @cindex @option{-Xf} | |
605 | Same as @option{-X}, but writes all JSON contents to the specified | |
606 | @var{file}. | |
607 | ||
608 | @item -fdoc | |
609 | @cindex @option{-fdoc} | |
610 | Generates @code{Ddoc} documentation and writes it to a file. The compiler | |
611 | determines @var{file} by removing any directory components and suffix | |
612 | from the input file, and then adding a @file{.html} suffix. | |
613 | ||
614 | @item -fdoc-dir=@var{dir} | |
615 | @cindex @option{-fdoc-dir} | |
616 | Same as @option{-fdoc}, but writes documentation to directory @var{dir}. | |
617 | This option can be used with @option{-fdoc-file=@var{file}} to | |
618 | independently set the output file and directory path. | |
619 | ||
620 | @item -fdoc-file=@var{file} | |
621 | @cindex @option{-fdoc-file} | |
622 | Same as @option{-fdoc}, but writes documentation to @var{file}. This | |
623 | option can be used with @option{-fdoc-dir=@var{dir}} to independently | |
624 | set the output file and directory path. | |
625 | ||
626 | @item -fdoc-inc=@var{file} | |
627 | @cindex @option{-fdoc-inc} | |
628 | Specify @var{file} as a @var{Ddoc} macro file to be read. Multiple | |
629 | @option{-fdoc-inc} options can be used, and files are read and processed | |
630 | in the same order. | |
631 | ||
47fe7be6 IB |
632 | @item -fdump-c++-spec=@var{file} |
633 | For D source files, generate corresponding C++ declarations in @var{file}. | |
634 | ||
635 | @item -fdump-c++-spec-verbose | |
636 | In conjunction with @option{-fdump-c++-spec=} above, add comments for ignored | |
637 | declarations in the generated C++ header. | |
638 | ||
639 | @item -fsave-mixins=@var{file} | |
640 | @cindex @option{-fsave-mixins} | |
641 | Generates code expanded from D @code{mixin} statements and writes the | |
642 | processed sources to @var{file}. This is useful to debug errors in compilation | |
643 | and provides source for debuggers to show when requested. | |
644 | ||
b4c522fa IB |
645 | @end table |
646 | ||
647 | @node Warnings | |
648 | @section Warnings | |
649 | @cindex options to control warnings | |
650 | @cindex warning messages | |
651 | @cindex messages, warning | |
652 | @cindex suppressing warnings | |
653 | ||
654 | Warnings are diagnostic messages that report constructions that | |
655 | are not inherently erroneous but that are risky or suggest there | |
656 | is likely to be a bug in the program. Unless @option{-Werror} is | |
657 | specified, they do not prevent compilation of the program. | |
658 | ||
659 | @table @gcctabopt | |
660 | ||
661 | @item -Wall | |
662 | @cindex @option{-Wall} | |
663 | @cindex @option{-Wno-all} | |
664 | Turns on all warnings messages. Warnings are not a defined part of | |
665 | the D language, and all constructs for which this may generate a | |
666 | warning message are valid code. | |
667 | ||
668 | @item -Walloca | |
669 | @cindex @option{-Walloca} | |
670 | This option warns on all uses of "alloca" in the source. | |
671 | ||
672 | @item -Walloca-larger-than=@var{n} | |
673 | @cindex @option{-Walloca-larger-than} | |
674 | @cindex @option{-Wno-alloca-larger-than} | |
675 | Warn on unbounded uses of alloca, and on bounded uses of alloca | |
676 | whose bound can be larger than @var{n} bytes. | |
677 | @option{-Wno-alloca-larger-than} disables | |
678 | @option{-Walloca-larger-than} warning and is equivalent to | |
679 | @option{-Walloca-larger-than=@var{SIZE_MAX}} or larger. | |
680 | ||
681 | @item -Wcast-result | |
682 | @cindex @option{-Wcast-result} | |
683 | @cindex @option{-Wno-cast-result} | |
684 | Warn about casts that will produce a null or zero result. Currently | |
685 | this is only done for casting between an imaginary and non-imaginary | |
686 | data type, or casting between a D and C++ class. | |
687 | ||
688 | @item -Wno-deprecated | |
689 | @cindex @option{-Wdeprecated} | |
690 | @cindex @option{-Wno-deprecated} | |
691 | Do not warn about usage of deprecated features and symbols with | |
692 | @code{deprecated} attributes. | |
693 | ||
694 | @item -Werror | |
695 | @cindex @option{-Werror} | |
696 | @cindex @option{-Wno-error} | |
697 | Turns all warnings into errors. | |
698 | ||
699 | @item -Wspeculative | |
700 | @cindex @option{-Wspeculative} | |
701 | @cindex @option{-Wno-speculative} | |
702 | List all error messages from speculative compiles, such as | |
703 | @code{__traits(compiles, ...)}. This option does not report | |
704 | messages as warnings, and these messages therefore never become | |
705 | errors when the @option{-Werror} option is also used. | |
706 | ||
707 | @item -Wtemplates | |
708 | @cindex @option{-Wtemplates} | |
709 | @cindex @option{-Wno-templates} | |
710 | Warn when a template instantiation is encountered. Some coding | |
711 | rules disallow templates, and this may be used to enforce that rule. | |
712 | ||
713 | @item -Wunknown-pragmas | |
714 | @cindex @option{-Wunknown-pragmas} | |
715 | @cindex @option{-Wno-unknown-pragmas} | |
716 | Warn when a @code{pragma()} is encountered that is not understood by | |
717 | @command{gdc}. This differs from @option{-fignore-unknown-pragmas} | |
718 | where a pragma that is part of the D language, but not implemented by | |
719 | the compiler, won't get reported. | |
720 | ||
873b45d3 IB |
721 | @item -Wno-varargs |
722 | @cindex Wvarargs | |
723 | @cindex Wno-varargs | |
724 | Do not warn upon questionable usage of the macros used to handle variable | |
725 | arguments like @code{va_start}. | |
726 | ||
b4c522fa IB |
727 | @item -fignore-unknown-pragmas |
728 | @cindex @option{-fignore-unknown-pragmas} | |
729 | @cindex @option{-fno-ignore-unknown-pragmas} | |
730 | Turns off errors for unsupported pragmas. | |
731 | ||
732 | @item -fmax-errors=@var{n} | |
733 | @cindex @option{-fmax-errors} | |
734 | Limits the maximum number of error messages to @var{n}, at which point | |
735 | @command{gdc} bails out rather than attempting to continue processing the | |
736 | source code. If @var{n} is 0 (the default), there is no limit on the | |
737 | number of error messages produced. | |
738 | ||
739 | @item -fsyntax-only | |
740 | @cindex @option{-fsyntax-only} | |
741 | @cindex @option{-fno-syntax-only} | |
742 | Check the code for syntax errors, but do not actually compile it. This | |
743 | can be used in conjunction with @option{-fdoc} or @option{-H} to generate | |
744 | files for each module present on the command-line, but no other output | |
745 | file. | |
746 | ||
747 | @item -ftransition=@var{id} | |
748 | @cindex @option{-ftransition} | |
749 | Report additional information about D language changes identified by | |
750 | @var{id}. The following values are supported: | |
751 | ||
752 | @table @samp | |
753 | @item all | |
47fe7be6 | 754 | List information on all D language transitions. |
b4c522fa IB |
755 | @item complex |
756 | List all usages of complex or imaginary types. | |
b4c522fa IB |
757 | @item field |
758 | List all non-mutable fields which occupy an object instance. | |
0fb57034 IB |
759 | @item in |
760 | List all usages of @code{in} on parameter. | |
b4c522fa IB |
761 | @item nogc |
762 | List all hidden GC allocations. | |
47fe7be6 IB |
763 | @item templates |
764 | List statistics on template instantiations. | |
b4c522fa IB |
765 | @item tls |
766 | List all variables going into thread local storage. | |
47fe7be6 IB |
767 | @item vmarkdown |
768 | List instances of Markdown replacements in Ddoc. | |
b4c522fa IB |
769 | @end table |
770 | ||
771 | @end table | |
772 | ||
773 | @node Linking | |
774 | @section Options for Linking | |
775 | @cindex options, linking | |
776 | @cindex linking, static | |
777 | ||
778 | These options come into play when the compiler links object files into an | |
779 | executable output file. They are meaningless if the compiler is not doing | |
780 | a link step. | |
781 | ||
782 | @table @gcctabopt | |
783 | ||
852c4b04 IB |
784 | @item -defaultlib=@var{libname} |
785 | @cindex @option{-defaultlib=} | |
b4c522fa IB |
786 | Specify the library to use instead of libphobos when linking. Options |
787 | specifying the linkage of libphobos, such as @option{-static-libphobos} | |
788 | or @option{-shared-libphobos}, are ignored. | |
789 | ||
852c4b04 IB |
790 | @item -debuglib=@var{libname} |
791 | @cindex @option{-debuglib=} | |
b4c522fa IB |
792 | Specify the debug library to use instead of libphobos when linking. |
793 | This option has no effect unless the @option{-g} option was also given | |
794 | on the command line. Options specifying the linkage of libphobos, such | |
795 | as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored. | |
796 | ||
797 | @item -nophoboslib | |
798 | @cindex @option{-nophoboslib} | |
799 | Do not use the Phobos or D runtime library when linking. Options specifying | |
800 | the linkage of libphobos, such as @option{-static-libphobos} or | |
801 | @option{-shared-libphobos}, are ignored. The standard system libraries are | |
802 | used normally, unless @option{-nostdlib} or @option{-nodefaultlibs} is used. | |
803 | ||
804 | @item -shared-libphobos | |
805 | @cindex @option{-shared-libphobos} | |
806 | On systems that provide @file{libgphobos} and @file{libgdruntime} as a | |
807 | shared and a static library, this option forces the use of the shared | |
808 | version. If no shared version was built when the compiler was configured, | |
809 | this option has no effect. | |
810 | ||
811 | @item -static-libphobos | |
812 | @cindex @option{-static-libphobos} | |
813 | On systems that provide @file{libgphobos} and @file{libgdruntime} as a | |
814 | shared and a static library, this option forces the use of the static | |
815 | version. If no static version was built when the compiler was configured, | |
816 | this option has no effect. | |
817 | ||
818 | @end table | |
819 | ||
820 | @node Developer Options | |
821 | @section Developer Options | |
822 | @cindex developer options | |
823 | @cindex debug dump options | |
824 | @cindex dump options | |
825 | ||
826 | This section describes command-line options that are primarily of | |
827 | interest to developers or language tooling. | |
828 | ||
829 | @table @gcctabopt | |
830 | ||
831 | @item -fdump-d-original | |
832 | @cindex @option{-fdump-d-original} | |
833 | Output the internal front-end AST after the @code{semantic3} stage. | |
834 | This option is only useful for debugging the GNU D compiler itself. | |
835 | ||
836 | @item -v | |
837 | @cindex @option{-v} | |
838 | Dump information about the compiler language processing stages as the source | |
839 | program is being compiled. This includes listing all modules that are | |
840 | processed through the @code{parse}, @code{semantic}, @code{semantic2}, and | |
841 | @code{semantic3} stages; all @code{import} modules and their file paths; | |
842 | and all @code{function} bodies that are being compiled. | |
843 | ||
844 | @end table | |
845 | ||
846 | @c man end | |
847 | ||
848 | @node Index | |
849 | @unnumbered Index | |
850 | ||
851 | @printindex cp | |
852 | ||
853 | @bye |