1GDC(1) GNU GDC(1)
2
6 gdc - A GCC-based compiler for the D language
7
9 gdc [-c|-S] [-g] [-pg]
10 [-Olevel] [-Wwarn...]
11 [-Idir...] [-Ldir...]
12 [-foption...] [-mmachine-option...]
13 [-o outfile] [@file] infile...
14 Only the most useful options are listed here; see below for the
16 remainder.
17
19 The gdc command is the GNU compiler for the D language and supports
20 many of the same options as gcc. This manual only documents the
21 options specific to gdc.
22
24 Input and Output files
25 For any given input file, the file name suffix determines what kind of
26 compilation is done. The following kinds of input file names are
27 supported:
28 file.d
30 D source files.
31 file.dd
33 Ddoc source files.
34 file.di
36 D interface files.
37 You can specify more than one input file on the gdc command line, each
39 being compiled separately in the compilation process. If you specify a
40 "-o file" option, all the input files are compiled together, producing
41 a single output file, named file. This is allowed even when using "-S"
42 or "-c".
43 A D interface file contains only what an import of the module needs,
45 rather than the whole implementation of that module. They can be
46 created by gdc from a D source file by using the "-H" option. When the
47 compiler resolves an import declaration, it searches for matching .di
48 files first, then for .d.
49 A Ddoc source file contains code in the D macro processor language. It
51 is primarily designed for use in producing user documentation from
52 embedded comments, with a slight affinity towards HTML generation. If
53 a .d source file starts with the string "Ddoc" then it is treated as
54 general purpose documentation, not as a D source file.
55 Runtime Options
57 These options affect the runtime behavior of programs compiled with
58 gdc.
59 -fall-instantiations
61 Generate code for all template instantiations. The default
62 template emission strategy is to not generate code for declarations
63 that were either instantiated speculatively, such as from
64 "__traits(compiles, ...)", or that come from an imported module not
65 being compiled.
66 -fno-assert
68 Turn off code generation for "assert" contracts.
69 -fno-bounds-check
71 Turns off array bounds checking for all functions, which can
72 improve performance for code that uses arrays extensively. Note
73 that this can result in unpredictable behavior if the code in
74 question actually does violate array bounds constraints. It is
75 safe to use this option if you are sure that your code never throws
76 a "RangeError".
77 -fbounds-check=value
79 An alternative to -fbounds-check that allows more control as to
80 where bounds checking is turned on or off. The following values
81 are supported:
82 on Turns on array bounds checking for all functions.
84 safeonly
86 Turns on array bounds checking only for @safe functions.
87 off Turns off array bounds checking completely.
89 -fno-builtin
91 Don't recognize built-in functions unless they begin with the
92 prefix __builtin_. By default, the compiler will recognize when a
93 function in the "core.stdc" package is a built-in function.
94 -fcheckaction=value
96 This option controls what code is generated on an assertion, bounds
97 check, or final switch failure. The following values are
98 supported:
99 context
101 Throw an "AssertError" with extra context information.
102 halt
104 Halt the program execution.
105 throw
107 Throw an "AssertError" (the default).
108 -fdebug
110 -fdebug=value
111 Turn on compilation of conditional "debug" code into the program.
112 The -fdebug option itself sets the debug level to 1, while -fdebug=
113 enables "debug" code that are identified by any of the following
114 values:
115 level
117 Sets the debug level to level, any "debug" code <= level is
118 compiled into the program.
119 ident
121 Turns on compilation of any "debug" code identified by ident.
122 -fno-druntime
124 Implements <https://dlang.org/spec/betterc.html>. Assumes that
125 compilation targets an environment without a D runtime library.
126 This is equivalent to compiling with the following options:
128 gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
130 -fextern-std=standard
132 Sets the C++ name mangling compatibility to the version identified
133 by standard. The following values are supported:
134 c++98
136 c++03
137 Sets "__traits(getTargetInfo, "cppStd")" to 199711.
138 c++11
140 Sets "__traits(getTargetInfo, "cppStd")" to 201103.
141 c++14
143 Sets "__traits(getTargetInfo, "cppStd")" to 201402.
144 c++17
146 Sets "__traits(getTargetInfo, "cppStd")" to 201703. This is
147 the default.
148 c++20
150 Sets "__traits(getTargetInfo, "cppStd")" to 202002.
151 -fno-invariants
153 Turns off code generation for class "invariant" contracts.
154 -fmain
156 Generates a default "main()" function when compiling. This is
157 useful when unittesting a library, as it enables running the
158 unittests in a library without having to manually define an entry-
159 point function. This option does nothing when "main" is already
160 defined in user code.
161 -fno-moduleinfo
163 Turns off generation of the "ModuleInfo" and related functions that
164 would become unreferenced without it, which may allow linking to
165 programs not written in D. Functions that are not be generated
166 include module constructors and destructors ("static this" and
167 "static ~this"), "unittest" code, and "DSO" registry functions for
168 dynamically linked code.
169 -fonly=filename
171 Tells the compiler to parse and run semantic analysis on all
172 modules on the command line, but only generate code for the module
173 specified by filename.
174 -fno-postconditions
176 Turns off code generation for postcondition "out" contracts.
177 -fno-preconditions
179 Turns off code generation for precondition "in" contracts.
180 -fpreview=id
182 Turns on an upcoming D language change identified by id. The
183 following values are supported:
184 all Turns on all upcoming D language features.
186 dip1000
188 Implements <https://wiki.dlang.org/DIP1000> (Scoped pointers).
189 dip1008
191 Implements <https://wiki.dlang.org/DIP1008> (Allow exceptions
192 in @nogc code).
193 dip1021
195 Implements <https://wiki.dlang.org/DIP1021> (Mutable function
196 arguments).
197 dip25
199 Implements <https://wiki.dlang.org/DIP25> (Sealed references).
200 dtorfields
202 Turns on generation for destructing fields of partially
203 constructed objects.
204 fieldwise
206 Turns on generation of struct equality to use field-wise
207 comparisons.
208 fixaliasthis
210 Implements new lookup rules that check the current scope for
211 "alias this" before searching in upper scopes.
212 in Implements "in" parameters to mean "scope const [ref]" and
214 accepts rvalues.
215 inclusiveincontracts
217 Implements "in" contracts of overridden methods to be a
218 superset of parent contract.
219 intpromote
221 Implements C-style integral promotion for unary "+", "-" and
222 "~" expressions.
223 nosharedaccess
225 Turns off and disallows all access to shared memory objects.
226 rvaluerefparam
228 Implements rvalue arguments to "ref" parameters.
229 shortenedmethods
231 Implements use of "=>" for methods and top-level functions in
232 addition to lambdas.
233 -frelease
235 Turns on compiling in release mode, which means not emitting
236 runtime checks for contracts and asserts. Array bounds checking is
237 not done for @system and @trusted functions, and assertion failures
238 are undefined behavior.
239 This is equivalent to compiling with the following options:
241 gdc -fno-assert -fbounds-check=safe -fno-invariants \
243 -fno-postconditions -fno-preconditions -fno-switch-errors
244 -frevert=
246 Turns off a D language feature identified by id. The following
247 values are supported:
248 all Turns off all revertable D language features.
250 dip25
252 Reverts <https://wiki.dlang.org/DIP25> (Sealed references).
253 dtorfields
255 Turns off generation for destructing fields of partially
256 constructed objects.
257 markdown
259 Turns off Markdown replacements in Ddoc comments.
260 -fno-rtti
262 Turns off generation of run-time type information for all user
263 defined types. Any code that uses features of the language that
264 require access to this information will result in an error.
265 -fno-switch-errors
267 This option controls what code is generated when no case is matched
268 in a "final switch" statement. The default run time behavior is to
269 throw a "SwitchError". Turning off -fswitch-errors means that
270 instead the execution of the program is immediately halted.
271 -funittest
273 Turns on compilation of "unittest" code, and turns on the
274 "version(unittest)" identifier. This implies -fassert.
275 -fversion=value
277 Turns on compilation of conditional "version" code into the program
278 identified by any of the following values:
279 level
281 Sets the version level to level, any "version" code >= level is
282 compiled into the program.
283 ident
285 Turns on compilation of "version" code identified by ident.
286 -fno-weak-templates
288 Turns off emission of declarations that can be defined in multiple
289 objects as weak symbols. The default is to emit all public symbols
290 as weak, unless the target lacks support for weak symbols.
291 Disabling this option means that common symbols are instead put in
292 COMDAT or become private.
293 Options for Directory Search
295 These options specify directories to search for files, libraries, and
296 other parts of the compiler:
297 -Idir
299 Specify a directory to use when searching for imported modules at
300 compile time. Multiple -I options can be used, and the paths are
301 searched in the same order.
302 -Jdir
304 Specify a directory to use when searching for files in string
305 imports at compile time. This switch is required in order to use
306 "import(file)" expressions. Multiple -J options can be used, and
307 the paths are searched in the same order.
308 -Ldir
310 When linking, specify a library search directory, as with gcc.
311 -Bdir
313 This option specifies where to find the executables, libraries,
314 source files, and data files of the compiler itself, as with gcc.
315 -fmodule-file=module=spec
317 This option manipulates file paths of imported modules, such that
318 if an imported module matches all or the leftmost part of module,
319 the file path in spec is used as the location to search for D
320 sources. This is used when the source file path and names are not
321 the same as the package and module hierarchy. Consider the
322 following examples:
323 gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
325 This will tell the compiler to search in all import paths for the
327 source file foo.d when importing A.B, and the directory bar/ when
328 importing C, as annotated in the following D code:
329 module test;
331 import A.B; // Matches A.B, searches for foo.d
332 import C.D.E; // Matches C, searches for bar/D/E.d
333 import A.B.C; // No match, searches for A/B/C.d
334 -imultilib dir
336 Use dir as a subdirectory of the gcc directory containing target-
337 specific D sources and interfaces.
338 -iprefix prefix
340 Specify prefix as the prefix for the gcc directory containing
341 target-specific D sources and interfaces. If the prefix represents
342 a directory, you should include the final '/'.
343 -nostdinc
345 Do not search the standard system directories for D source and
346 interface files. Only the directories that have been specified
347 with -I options (and the directory of the current file, if
348 appropriate) are searched.
349 Code Generation
351 In addition to the many gcc options controlling code generation, gdc
352 has several options specific to itself.
353 -H Generates D interface files for all modules being compiled. The
355 compiler determines the output file based on the name of the input
356 file, removes any directory components and suffix, and applies the
357 .di suffix.
358 -Hd dir
360 Same as -H, but writes interface files to directory dir. This
361 option can be used with -Hf file to independently set the output
362 file and directory path.
363 -Hf file
365 Same as -H but writes interface files to file. This option can be
366 used with -Hd dir to independently set the output file and
367 directory path.
368 -M Output the module dependencies of all source files being compiled
370 in a format suitable for make. The compiler outputs one make rule
371 containing the object file name for that source file, a colon, and
372 the names of all imported files.
373 -MM Like -M but does not mention imported modules from the D standard
375 library package directories.
376 -MF file
378 When used with -M or -MM, specifies a file to write the
379 dependencies to. When used with the driver options -MD or -MMD,
380 -MF overrides the default dependency output file.
381 -MG This option is for compatibility with gcc, and is ignored by the
383 compiler.
384 -MP Outputs a phony target for each dependency other than the modules
386 being compiled, causing each to depend on nothing.
387 -MT target
389 Change the target of the rule emitted by dependency generation to
390 be exactly the string you specify. If you want multiple targets,
391 you can specify them as a single argument to -MT, or use multiple
392 -MT options.
393 -MQ target
395 Same as -MT, but it quotes any characters which are special to
396 make.
397 -MD This option is equivalent to -M -MF file. The driver determines
399 file by removing any directory components and suffix from the input
400 file, and then adding a .deps suffix.
401 -MMD
403 Like -MD but does not mention imported modules from the D standard
404 library package directories.
405 -X Output information describing the contents of all source files
407 being compiled in JSON format to a file. The driver determines
408 file by removing any directory components and suffix from the input
409 file, and then adding a .json suffix.
410 -Xf file
412 Same as -X, but writes all JSON contents to the specified file.
413 -fdoc
415 Generates "Ddoc" documentation and writes it to a file. The
416 compiler determines file by removing any directory components and
417 suffix from the input file, and then adding a .html suffix.
418 -fdoc-dir=dir
420 Same as -fdoc, but writes documentation to directory dir. This
421 option can be used with -fdoc-file=file to independently set the
422 output file and directory path.
423 -fdoc-file=file
425 Same as -fdoc, but writes documentation to file. This option can
426 be used with -fdoc-dir=dir to independently set the output file and
427 directory path.
428 -fdoc-inc=file
430 Specify file as a Ddoc macro file to be read. Multiple -fdoc-inc
431 options can be used, and files are read and processed in the same
432 order.
433 -fdump-c++-spec=file
435 For D source files, generate corresponding C++ declarations in
436 file.
437 -fdump-c++-spec-verbose
439 In conjunction with -fdump-c++-spec= above, add comments for
440 ignored declarations in the generated C++ header.
441 -fsave-mixins=file
443 Generates code expanded from D "mixin" statements and writes the
444 processed sources to file. This is useful to debug errors in
445 compilation and provides source for debuggers to show when
446 requested.
447 Warnings
449 Warnings are diagnostic messages that report constructions that are not
450 inherently erroneous but that are risky or suggest there is likely to
451 be a bug in the program. Unless -Werror is specified, they do not
452 prevent compilation of the program.
453 -Wall
455 Turns on all warnings messages. Warnings are not a defined part of
456 the D language, and all constructs for which this may generate a
457 warning message are valid code.
458 -Walloca
460 This option warns on all uses of "alloca" in the source.
461 -Walloca-larger-than=n
463 Warn on unbounded uses of alloca, and on bounded uses of alloca
464 whose bound can be larger than n bytes. -Wno-alloca-larger-than
465 disables -Walloca-larger-than warning and is equivalent to
466 -Walloca-larger-than=SIZE_MAX or larger.
467 -Wcast-result
469 Warn about casts that will produce a null or zero result.
470 Currently this is only done for casting between an imaginary and
471 non-imaginary data type, or casting between a D and C++ class.
472 -Wno-deprecated
474 Do not warn about usage of deprecated features and symbols with
475 "deprecated" attributes.
476 -Werror
478 Turns all warnings into errors.
479 -Wspeculative
481 List all error messages from speculative compiles, such as
482 "__traits(compiles, ...)". This option does not report messages as
483 warnings, and these messages therefore never become errors when the
484 -Werror option is also used.
485 -Wtemplates
487 Warn when a template instantiation is encountered. Some coding
488 rules disallow templates, and this may be used to enforce that
489 rule.
490 -Wunknown-pragmas
492 Warn when a "pragma()" is encountered that is not understood by
493 gdc. This differs from -fignore-unknown-pragmas where a pragma
494 that is part of the D language, but not implemented by the
495 compiler, won't get reported.
496 -Wno-varargs
498 Do not warn upon questionable usage of the macros used to handle
499 variable arguments like "va_start".
500 -fignore-unknown-pragmas
502 Turns off errors for unsupported pragmas.
503 -fmax-errors=n
505 Limits the maximum number of error messages to n, at which point
506 gdc bails out rather than attempting to continue processing the
507 source code. If n is 0 (the default), there is no limit on the
508 number of error messages produced.
509 -fsyntax-only
511 Check the code for syntax errors, but do not actually compile it.
512 This can be used in conjunction with -fdoc or -H to generate files
513 for each module present on the command-line, but no other output
514 file.
515 -ftransition=id
517 Report additional information about D language changes identified
518 by id. The following values are supported:
519 all List information on all D language transitions.
521 complex
523 List all usages of complex or imaginary types.
524 field
526 List all non-mutable fields which occupy an object instance.
527 in List all usages of "in" on parameter.
529 nogc
531 List all hidden GC allocations.
532 templates
534 List statistics on template instantiations.
535 tls List all variables going into thread local storage.
537 vmarkdown
539 List instances of Markdown replacements in Ddoc.
540 Options for Linking
542 These options come into play when the compiler links object files into
543 an executable output file. They are meaningless if the compiler is not
544 doing a link step.
545 -defaultlib=libname
547 Specify the library to use instead of libphobos when linking.
548 Options specifying the linkage of libphobos, such as
549 -static-libphobos or -shared-libphobos, are ignored.
550 -debuglib=libname
552 Specify the debug library to use instead of libphobos when linking.
553 This option has no effect unless the -g option was also given on
554 the command line. Options specifying the linkage of libphobos,
555 such as -static-libphobos or -shared-libphobos, are ignored.
556 -nophoboslib
558 Do not use the Phobos or D runtime library when linking. Options
559 specifying the linkage of libphobos, such as -static-libphobos or
560 -shared-libphobos, are ignored. The standard system libraries are
561 used normally, unless -nostdlib or -nodefaultlibs is used.
562 -shared-libphobos
564 On systems that provide libgphobos and libgdruntime as a shared and
565 a static library, this option forces the use of the shared version.
566 If no shared version was built when the compiler was configured,
567 this option has no effect.
568 -static-libphobos
570 On systems that provide libgphobos and libgdruntime as a shared and
571 a static library, this option forces the use of the static version.
572 If no static version was built when the compiler was configured,
573 this option has no effect.
574 Developer Options
576 This section describes command-line options that are primarily of
577 interest to developers or language tooling.
578 -fdump-d-original
580 Output the internal front-end AST after the "semantic3" stage.
581 This option is only useful for debugging the GNU D compiler itself.
582 -v Dump information about the compiler language processing stages as
584 the source program is being compiled. This includes listing all
585 modules that are processed through the "parse", "semantic",
586 "semantic2", and "semantic3" stages; all "import" modules and their
587 file paths; and all "function" bodies that are being compiled.
588
590 gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entries for gdc
591 and gcc.
592
594 Copyright (c) 2006-2022 Free Software Foundation, Inc.
595 Permission is granted to copy, distribute and/or modify this document
597 under the terms of the GNU Free Documentation License, Version 1.3 or
598 any later version published by the Free Software Foundation; with no
599 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
600 copy of the license is included in the man page gfdl(7).
601gcc-12 2022-05-07 GDC(1)