1 \input texinfo @c -*-texinfo-*-
3 @settitle The GNU D Compiler
5 @c Merge the standard indexes into a single one.
12 @include gcc-common.texi
14 @c Copyright years for this manual.
15 @set copyrights-d 2006-2022
18 @c man begin COPYRIGHT
19 Copyright @copyright{} @value{copyrights-d} Free Software Foundation, Inc.
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
27 section entitled ``GNU Free Documentation License''.
29 @c man begin COPYRIGHT
37 @dircategory Software development
39 * gdc: (gdc). A GCC-based compiler for the D language
47 @title The GNU D Compiler
49 @author David Friedman, Iain Buclaw
52 @vskip 0pt plus 1filll
53 Published by the Free Software Foundation @*
54 51 Franklin Street, Fifth Floor@*
55 Boston, MA 02110-1301, USA@*
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
69 package documentation, see @uref{https://dlang.org/}.
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.
88 @c man title gdc A GCC-based compiler for the D language
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{}
98 Only the most useful options are listed here; see below for the
102 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
103 and the Info entries for @file{gdc} and @file{gcc}.
107 @c man begin DESCRIPTION gdc
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}.
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
129 @node Input and Output files
130 @section Input and Output files
131 @cindex suffixes for D source
132 @cindex D source file suffixes
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:
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}.
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}.
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.
166 @node Runtime Options
167 @section Runtime Options
168 @cindex options, runtime
170 These options affect the runtime behavior of programs compiled with
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.
184 @cindex @option{-fassert}
185 @cindex @option{-fno-assert}
186 Turn off code generation for @code{assert} contracts.
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}.
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
205 Turns on array bounds checking for all functions.
207 Turns on array bounds checking only for @code{@@safe} functions.
209 Turns off array bounds checking completely.
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.
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:
226 Throw an @code{AssertError} with extra context information.
228 Halt the program execution.
230 Throw an @code{AssertError} (the default).
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:
244 Sets the debug level to @var{level}, any @code{debug} code <= @var{level}
245 is compiled into the program.
247 Turns on compilation of any @code{debug} code identified by @var{ident}.
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.
256 This is equivalent to compiling with the following options:
259 gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
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:
270 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{199711}.
272 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201103}.
274 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201402}.
276 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201703}.
279 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{202002}.
282 @item -fno-invariants
283 @cindex @option{-finvariants}
284 @cindex @option{-fno-invariants}
285 Turns off code generation for class @code{invariant} contracts.
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.
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.
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
310 @item -fno-postconditions
311 @cindex @option{-fpostconditions}
312 @cindex @option{-fno-postconditions}
313 Turns off code generation for postcondition @code{out} contracts.
315 @item -fno-preconditions
316 @cindex @option{-fpreconditions}
317 @cindex @option{-fno-preconditions}
318 Turns off code generation for precondition @code{in} contracts.
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:
327 Turns on all upcoming D language features.
329 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md}
332 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md}
333 (Allow exceptions in @code{@@nogc} code).
335 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md}
336 (Mutable function arguments).
338 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
341 Turns on generation for destructing fields of partially constructed objects.
343 Turns on generation of struct equality to use field-wise comparisons.
345 Implements new lookup rules that check the current scope for @code{alias this}
346 before searching in upper scopes.
347 @item fiximmutableconv
348 Disallows unsound immutable conversions that were formerly incorrectly
351 Implements @code{in} parameters to mean @code{scope const [ref]} and accepts
353 @item inclusiveincontracts
354 Implements @code{in} contracts of overridden methods to be a superset of parent
357 Implements C-style integral promotion for unary @code{+}, @code{-} and @code{~}
360 Turns off and disallows all access to shared memory objects.
362 Implements rvalue arguments to @code{ref} parameters.
363 @item systemvariables
364 Disables access to variables marked @code{@@system} from @code{@@safe} code.
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.
375 This is equivalent to compiling with the following options:
378 gdc -fno-assert -fbounds-check=safe -fno-invariants \
379 -fno-postconditions -fno-preconditions -fno-switch-errors
383 @cindex @option{-frevert}
384 Turns off a D language feature identified by @var{id}. The following values
389 Turns off all revertable D language features.
391 Reverts @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
394 Turns off generation for destructing fields of partially constructed objects.
396 Turns off Markdown replacements in Ddoc comments.
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.
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.
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}.
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:
427 Sets the version level to @var{level}, any @code{version} code >= @var{level}
428 is compiled into the program.
430 Turns on compilation of @code{version} code identified by @var{ident}.
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.
443 @node Directory Options
444 @section Options for Directory Search
445 @cindex directory options
446 @cindex options, directory search
449 These options specify directories to search for files, libraries, and
450 other parts of the compiler:
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.
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.
469 When linking, specify a library search directory, as with @command{gcc}.
473 This option specifies where to find the executables, libraries,
474 source files, and data files of the compiler itself, as with @command{gcc}.
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:
485 gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
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:
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
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.
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{'/'}.
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.
518 @node Code Generation
519 @section Code Generation
520 @cindex options, code generation
522 In addition to the many @command{gcc} options controlling code generation,
523 @command{gdc} has several options specific to itself.
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.
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.
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
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.
554 Like @option{-M} but does not mention imported modules from the D standard
555 library package directories.
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.
565 This option is for compatibility with @command{gcc}, and is ignored by the
570 Outputs a phony target for each dependency other than the modules being
571 compiled, causing each to depend on nothing.
573 @item -MT @var{target}
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.
580 @item -MQ @var{target}
582 Same as @option{-MT}, but it quotes any characters which are special to
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.
592 @cindex @option{-MMD}
593 Like @option{-MD} but does not mention imported modules from the D standard
594 library package directories.
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.
605 Same as @option{-X}, but writes all JSON contents to the specified
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.
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.
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.
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
632 @item -fdump-c++-spec=@var{file}
633 For D source files, generate corresponding C++ declarations in @var{file}.
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.
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.
649 @cindex options to control warnings
650 @cindex warning messages
651 @cindex messages, warning
652 @cindex suppressing warnings
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.
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.
669 @cindex @option{-Walloca}
670 This option warns on all uses of "alloca" in the source.
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.
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.
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.
695 @cindex @option{-Werror}
696 @cindex @option{-Wno-error}
697 Turns all warnings into errors.
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.
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.
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.
724 Do not warn upon questionable usage of the macros used to handle variable
725 arguments like @code{va_start}.
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.
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.
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
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:
754 List information on all D language transitions.
756 List all usages of complex or imaginary types.
758 List all non-mutable fields which occupy an object instance.
760 List all usages of @code{in} on parameter.
762 List all hidden GC allocations.
764 List statistics on template instantiations.
766 List all variables going into thread local storage.
768 List instances of Markdown replacements in Ddoc.
774 @section Options for Linking
775 @cindex options, linking
776 @cindex linking, static
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
784 @item -defaultlib=@var{libname}
785 @cindex @option{-defaultlib=}
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.
790 @item -debuglib=@var{libname}
791 @cindex @option{-debuglib=}
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.
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.
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.
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.
820 @node Developer Options
821 @section Developer Options
822 @cindex developer options
823 @cindex debug dump options
826 This section describes command-line options that are primarily of
827 interest to developers or language tooling.
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.
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.