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 ident
117 Turns on compilation of any "debug" code identified by ident.
118 -fno-druntime
120 Implements <https://dlang.org/spec/betterc.html>. Assumes that
121 compilation targets an environment without a D runtime library.
122 This is equivalent to compiling with the following options:
124 gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
126 -fextern-std=standard
128 Sets the C++ name mangling compatibility to the version identified
129 by standard. The following values are supported:
130 c++98
132 c++03
133 Sets "__traits(getTargetInfo, "cppStd")" to 199711.
134 c++11
136 Sets "__traits(getTargetInfo, "cppStd")" to 201103.
137 c++14
139 Sets "__traits(getTargetInfo, "cppStd")" to 201402.
140 c++17
142 Sets "__traits(getTargetInfo, "cppStd")" to 201703. This is
143 the default.
144 c++20
146 Sets "__traits(getTargetInfo, "cppStd")" to 202002.
147 -fno-invariants
149 Turns off code generation for class "invariant" contracts.
150 -fmain
152 Generates a default main() function when compiling. This is useful
153 when unittesting a library, as it enables running the unittests in
154 a library without having to manually define an entry-point
155 function. This option does nothing when "main" is already defined
156 in user code.
157 -fno-moduleinfo
159 Turns off generation of the "ModuleInfo" and related functions that
160 would become unreferenced without it, which may allow linking to
161 programs not written in D. Functions that are not be generated
162 include module constructors and destructors ("static this" and
163 "static ~this"), "unittest" code, and "DSO" registry functions for
164 dynamically linked code.
165 -fonly=filename
167 Tells the compiler to parse and run semantic analysis on all
168 modules on the command line, but only generate code for the module
169 specified by filename.
170 -fno-postconditions
172 Turns off code generation for postcondition "out" contracts.
173 -fno-preconditions
175 Turns off code generation for precondition "in" contracts.
176 -fpreview=id
178 Turns on an upcoming D language change identified by id. The
179 following values are supported:
180 all Turns on all upcoming D language features.
182 bitfields
184 Implements bit-fields in D.
185 dip1000
187 Implements
188 <https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md>
189 (Scoped pointers).
190 dip1008
192 Implements
193 <https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md>
194 (Allow exceptions in @nogc code).
195 dip1021
197 Implements
198 <https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md>
199 (Mutable function arguments).
200 dip25
202 Implements
203 <https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md>
204 (Sealed references).
205 dtorfields
207 Turns on generation for destructing fields of partially
208 constructed objects.
209 fieldwise
211 Turns on generation of struct equality to use field-wise
212 comparisons.
213 fixaliasthis
215 Implements new lookup rules that check the current scope for
216 "alias this" before searching in upper scopes.
217 fiximmutableconv
219 Disallows unsound immutable conversions that were formerly
220 incorrectly permitted.
221 in Implements "in" parameters to mean "scope const [ref]" and
223 accepts rvalues.
224 inclusiveincontracts
226 Implements "in" contracts of overridden methods to be a
227 superset of parent contract.
228 nosharedaccess
230 Turns off and disallows all access to shared memory objects.
231 rvaluerefparam
233 Implements rvalue arguments to "ref" parameters.
234 systemvariables
236 Disables access to variables marked @system from @safe code.
237 -frelease
239 Turns on compiling in release mode, which means not emitting
240 runtime checks for contracts and asserts. Array bounds checking is
241 not done for @system and @trusted functions, and assertion failures
242 are undefined behavior.
243 This is equivalent to compiling with the following options:
245 gdc -fno-assert -fbounds-check=safe -fno-invariants \
247 -fno-postconditions -fno-preconditions -fno-switch-errors
248 -frevert=
250 Turns off a D language feature identified by id. The following
251 values are supported:
252 all Turns off all revertable D language features.
254 dip1000
256 Reverts
257 <https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md>
258 (Scoped pointers).
259 dip25
261 Reverts
262 <https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md>
263 (Sealed references).
264 dtorfields
266 Turns off generation for destructing fields of partially
267 constructed objects.
268 intpromote
270 Turns off C-style integral promotion for unary "+", "-" and "~"
271 expressions.
272 -fno-rtti
274 Turns off generation of run-time type information for all user
275 defined types. Any code that uses features of the language that
276 require access to this information will result in an error.
277 -fno-switch-errors
279 This option controls what code is generated when no case is matched
280 in a "final switch" statement. The default run time behavior is to
281 throw a "SwitchError". Turning off -fswitch-errors means that
282 instead the execution of the program is immediately halted.
283 -funittest
285 Turns on compilation of "unittest" code, and turns on the
286 version(unittest) identifier. This implies -fassert.
287 -fversion=value
289 Turns on compilation of conditional "version" code into the program
290 identified by any of the following values:
291 ident
293 Turns on compilation of "version" code identified by ident.
294 -fno-weak-templates
296 Turns off emission of declarations that can be defined in multiple
297 objects as weak symbols. The default is to emit all public symbols
298 as weak, unless the target lacks support for weak symbols.
299 Disabling this option means that common symbols are instead put in
300 COMDAT or become private.
301 Options for Directory Search
303 These options specify directories to search for files, libraries, and
304 other parts of the compiler:
305 -Idir
307 Specify a directory to use when searching for imported modules at
308 compile time. Multiple -I options can be used, and the paths are
309 searched in the same order.
310 -Jdir
312 Specify a directory to use when searching for files in string
313 imports at compile time. This switch is required in order to use
314 import(file) expressions. Multiple -J options can be used, and the
315 paths are searched in the same order.
316 -Ldir
318 When linking, specify a library search directory, as with gcc.
319 -Bdir
321 This option specifies where to find the executables, libraries,
322 source files, and data files of the compiler itself, as with gcc.
323 -fmodule-file=module=spec
325 This option manipulates file paths of imported modules, such that
326 if an imported module matches all or the leftmost part of module,
327 the file path in spec is used as the location to search for D
328 sources. This is used when the source file path and names are not
329 the same as the package and module hierarchy. Consider the
330 following examples:
331 gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
333 This will tell the compiler to search in all import paths for the
335 source file foo.d when importing A.B, and the directory bar/ when
336 importing C, as annotated in the following D code:
337 module test;
339 import A.B; // Matches A.B, searches for foo.d
340 import C.D.E; // Matches C, searches for bar/D/E.d
341 import A.B.C; // No match, searches for A/B/C.d
342 -imultilib dir
344 Use dir as a subdirectory of the gcc directory containing target-
345 specific D sources and interfaces.
346 -iprefix prefix
348 Specify prefix as the prefix for the gcc directory containing
349 target-specific D sources and interfaces. If the prefix represents
350 a directory, you should include the final '/'.
351 -nostdinc
353 Do not search the standard system directories for D source and
354 interface files. Only the directories that have been specified
355 with -I options (and the directory of the current file, if
356 appropriate) are searched.
357 Code Generation
359 In addition to the many gcc options controlling code generation, gdc
360 has several options specific to itself.
361 -H Generates D interface files for all modules being compiled. The
363 compiler determines the output file based on the name of the input
364 file, removes any directory components and suffix, and applies the
365 .di suffix.
366 -Hd dir
368 Same as -H, but writes interface files to directory dir. This
369 option can be used with -Hf file to independently set the output
370 file and directory path.
371 -Hf file
373 Same as -H but writes interface files to file. This option can be
374 used with -Hd dir to independently set the output file and
375 directory path.
376 -M Output the module dependencies of all source files being compiled
378 in a format suitable for make. The compiler outputs one make rule
379 containing the object file name for that source file, a colon, and
380 the names of all imported files.
381 -MM Like -M but does not mention imported modules from the D standard
383 library package directories.
384 -MF file
386 When used with -M or -MM, specifies a file to write the
387 dependencies to. When used with the driver options -MD or -MMD,
388 -MF overrides the default dependency output file.
389 -MG This option is for compatibility with gcc, and is ignored by the
391 compiler.
392 -MP Outputs a phony target for each dependency other than the modules
394 being compiled, causing each to depend on nothing.
395 -MT target
397 Change the target of the rule emitted by dependency generation to
398 be exactly the string you specify. If you want multiple targets,
399 you can specify them as a single argument to -MT, or use multiple
400 -MT options.
401 -MQ target
403 Same as -MT, but it quotes any characters which are special to
404 make.
405 -MD This option is equivalent to -M -MF file. The driver determines
407 file by removing any directory components and suffix from the input
408 file, and then adding a .deps suffix.
409 -MMD
411 Like -MD but does not mention imported modules from the D standard
412 library package directories.
413 -X Output information describing the contents of all source files
415 being compiled in JSON format to a file. The driver determines
416 file by removing any directory components and suffix from the input
417 file, and then adding a .json suffix.
418 -Xf file
420 Same as -X, but writes all JSON contents to the specified file.
421 -fdoc
423 Generates "Ddoc" documentation and writes it to a file. The
424 compiler determines file by removing any directory components and
425 suffix from the input file, and then adding a .html suffix.
426 -fdoc-dir=dir
428 Same as -fdoc, but writes documentation to directory dir. This
429 option can be used with -fdoc-file=file to independently set the
430 output file and directory path.
431 -fdoc-file=file
433 Same as -fdoc, but writes documentation to file. This option can
434 be used with -fdoc-dir=dir to independently set the output file and
435 directory path.
436 -fdoc-inc=file
438 Specify file as a Ddoc macro file to be read. Multiple -fdoc-inc
439 options can be used, and files are read and processed in the same
440 order.
441 -fdump-c++-spec=file
443 For D source files, generate corresponding C++ declarations in
444 file.
445 -fdump-c++-spec-verbose
447 In conjunction with -fdump-c++-spec= above, add comments for
448 ignored declarations in the generated C++ header.
449 -fsave-mixins=file
451 Generates code expanded from D "mixin" statements and writes the
452 processed sources to file. This is useful to debug errors in
453 compilation and provides source for debuggers to show when
454 requested.
455 Warnings
457 Warnings are diagnostic messages that report constructions that are not
458 inherently erroneous but that are risky or suggest there is likely to
459 be a bug in the program. Unless -Werror is specified, they do not
460 prevent compilation of the program.
461 -Wall
463 Turns on all warnings messages. Warnings are not a defined part of
464 the D language, and all constructs for which this may generate a
465 warning message are valid code.
466 -Walloca
468 This option warns on all uses of "alloca" in the source.
469 -Walloca-larger-than=n
471 Warn on unbounded uses of alloca, and on bounded uses of alloca
472 whose bound can be larger than n bytes. -Wno-alloca-larger-than
473 disables -Walloca-larger-than warning and is equivalent to
474 -Walloca-larger-than=SIZE_MAX or larger.
475 -Wno-builtin-declaration-mismatch
477 Warn if a built-in function is declared with an incompatible
478 signature.
479 -Wcast-result
481 Warn about casts that will produce a null or zero result.
482 Currently this is only done for casting between an imaginary and
483 non-imaginary data type, or casting between a D and C++ class.
484 -Wno-deprecated
486 Do not warn about usage of deprecated features and symbols with
487 "deprecated" attributes.
488 -Werror
490 Turns all warnings into errors.
491 -Wextra
493 This enables some extra warning flags that are not enabled by
494 -Wall.
495 -Waddress -Wcast-result -Wmismatched-special-enum -Wunknown-pragmas
497 -Wmismatched-special-enum
499 Warn when an enum the compiler recognizes as special is declared
500 with a different size to the built-in type it is representing.
501 -Wspeculative
503 List all error messages from speculative compiles, such as
504 "__traits(compiles, ...)". This option does not report messages as
505 warnings, and these messages therefore never become errors when the
506 -Werror option is also used.
507 -Wunknown-pragmas
509 Warn when a pragma() is encountered that is not understood by gdc.
510 This differs from -fignore-unknown-pragmas where a pragma that is
511 part of the D language, but not implemented by the compiler, won't
512 get reported.
513 -Wno-varargs
515 Do not warn upon questionable usage of the macros used to handle
516 variable arguments like "va_start".
517 -fignore-unknown-pragmas
519 Turns off errors for unsupported pragmas.
520 -fmax-errors=n
522 Limits the maximum number of error messages to n, at which point
523 gdc bails out rather than attempting to continue processing the
524 source code. If n is 0 (the default), there is no limit on the
525 number of error messages produced.
526 -fsyntax-only
528 Check the code for syntax errors, but do not actually compile it.
529 This can be used in conjunction with -fdoc or -H to generate files
530 for each module present on the command-line, but no other output
531 file.
532 -ftransition=id
534 Report additional information about D language changes identified
535 by id. The following values are supported:
536 all List information on all D language transitions.
538 complex
540 List all usages of complex or imaginary types.
541 field
543 List all non-mutable fields which occupy an object instance.
544 in List all usages of "in" on parameter.
546 nogc
548 List all hidden GC allocations.
549 templates
551 List statistics on template instantiations.
552 tls List all variables going into thread local storage.
554 Options for Linking
556 These options come into play when the compiler links object files into
557 an executable output file. They are meaningless if the compiler is not
558 doing a link step.
559 -defaultlib=libname
561 Specify the library to use instead of libphobos when linking.
562 Options specifying the linkage of libphobos, such as
563 -static-libphobos or -shared-libphobos, are ignored.
564 -debuglib=libname
566 Specify the debug library to use instead of libphobos when linking.
567 This option has no effect unless the -g option was also given on
568 the command line. Options specifying the linkage of libphobos,
569 such as -static-libphobos or -shared-libphobos, are ignored.
570 -nophoboslib
572 Do not use the Phobos or D runtime library when linking. Options
573 specifying the linkage of libphobos, such as -static-libphobos or
574 -shared-libphobos, are ignored. The standard system libraries are
575 used normally, unless -nostdlib or -nodefaultlibs is used.
576 -shared-libphobos
578 On systems that provide libgphobos and libgdruntime as a shared and
579 a static library, this option forces the use of the shared version.
580 If no shared version was built when the compiler was configured,
581 this option has no effect.
582 -static-libphobos
584 On systems that provide libgphobos and libgdruntime as a shared and
585 a static library, this option forces the use of the static version.
586 If no static version was built when the compiler was configured,
587 this option has no effect.
588 Developer Options
590 This section describes command-line options that are primarily of
591 interest to developers or language tooling.
592 -fdump-d-original
594 Output the internal front-end AST after the "semantic3" stage.
595 This option is only useful for debugging the GNU D compiler itself.
596 -v Dump information about the compiler language processing stages as
598 the source program is being compiled. This includes listing all
599 modules that are processed through the "parse", "semantic",
600 "semantic2", and "semantic3" stages; all "import" modules and their
601 file paths; and all "function" bodies that are being compiled.
602
604 gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entries for gdc
605 and gcc.
606
608 Copyright (c) 2006-2023 Free Software Foundation, Inc.
609 Permission is granted to copy, distribute and/or modify this document
611 under the terms of the GNU Free Documentation License, Version 1.3 or
612 any later version published by the Free Software Foundation; with no
613 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
614 copy of the license is included in the man page gfdl(7).
615gcc-13 2023-12-05 GDC(1)