1 \input texinfo @c -*-texinfo-*-
3 @settitle The GNU D Compiler
5 @c Create a separate index for command line options
7 @c Merge the standard indexes into a single one.
14 @include gcc-common.texi
16 @c Copyright years for this manual.
17 @set copyrights-d 2006-2024
20 @c man begin COPYRIGHT
21 Copyright @copyright{} @value{copyrights-d} Free Software Foundation, Inc.
23 Permission is granted to copy, distribute and/or modify this document
24 under the terms of the GNU Free Documentation License, Version 1.3 or
25 any later version published by the Free Software Foundation; with no
26 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
27 A copy of the license is included in the
29 section entitled ``GNU Free Documentation License''.
31 @c man begin COPYRIGHT
39 @dircategory Software development
41 * gdc: (gdc). A GCC-based compiler for the D language
49 @title The GNU D Compiler
51 @author David Friedman, Iain Buclaw
54 @vskip 0pt plus 1filll
55 Published by the Free Software Foundation @*
56 51 Franklin Street, Fifth Floor@*
57 Boston, MA 02110-1301, USA@*
67 This manual describes how to use @command{gdc}, the GNU compiler for
68 the D programming language. This manual is specifically about how to
69 invoke @command{gdc}, as well as its features and incompatibilities.
70 For more information about the D programming language in general,
71 including language specifications and standard package documentation,
72 see @uref{https://dlang.org/}.
75 * Invoking gdc:: How to run gdc.
76 * D Implementation:: User-visible implementation details.
77 * Copying:: The GNU General Public License.
78 * GNU Free Documentation License::
79 How you can share and copy this manual.
80 * Option Index:: Index of command line options.
81 * Keyword Index:: Index of concepts.
87 @c man title gdc A GCC-based compiler for the D language
90 @c man begin SYNOPSIS gdc
91 gdc [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}]
92 [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}]
93 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
94 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
95 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
97 Only the most useful options are listed here; see below for the
101 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
102 and the Info entries for @file{gdc} and @file{gcc}.
106 @c man begin DESCRIPTION gdc
108 The @command{gdc} command is the GNU compiler for the D language and
109 supports many of the same options as @command{gcc}. @xref{Option Summary, ,
110 Option Summary, gcc, Using the GNU Compiler Collection (GCC)}.
111 This manual only documents the options specific to @command{gdc}.
116 * Input and Output files:: Controlling the kind of output:
117 an executable, object files, assembler files,
118 * Runtime Options:: Options controlling runtime behavior
119 * Directory Options:: Where to find module files
120 * Code Generation:: Options controlling the output of gdc
121 * Warnings:: Options controlling warnings specific to gdc
122 * Linking:: Options influencing the linking step
123 * Developer Options:: Options useful for developers of gdc
128 @node Input and Output files
129 @section Input and Output files
130 @cindex suffixes for D source
131 @cindex D source file suffixes
133 For any given input file, the file name suffix determines what kind of
134 compilation is done. The following kinds of input file names are supported:
145 You can specify more than one input file on the @command{gdc} command line,
146 each being compiled separately in the compilation process. If you specify a
147 @code{-o @var{file}} option, all the input files are compiled together,
148 producing a single output file, named @var{file}. This is allowed even
149 when using @code{-S} or @code{-c}.
151 @cindex D interface files.
152 A D interface file contains only what an import of the module needs,
153 rather than the whole implementation of that module. They can be created
154 by @command{gdc} from a D source file by using the @code{-H} option.
155 When the compiler resolves an import declaration, it searches for matching
156 @file{.di} files first, then for @file{.d}.
158 @cindex Ddoc source files.
159 A Ddoc source file contains code in the D macro processor language. It is
160 primarily designed for use in producing user documentation from embedded
161 comments, with a slight affinity towards HTML generation. If a @file{.d}
162 source file starts with the string @code{Ddoc} then it is treated as general
163 purpose documentation, not as a D source file.
165 @node Runtime Options
166 @section Runtime Options
167 @cindex options, runtime
169 These options affect the runtime behavior of programs compiled with
174 @opindex fall-instantiations
175 @opindex fno-all-instantiations
176 @item -fall-instantiations
177 Generate code for all template instantiations. The default template emission
178 strategy is to not generate code for declarations that were either
179 instantiated speculatively, such as from @code{__traits(compiles, ...)}, or
180 that come from an imported module not being compiled.
185 Turn off code generation for @code{assert} contracts.
187 @opindex fbounds-check
188 @opindex fno-bounds-check
189 @item -fno-bounds-check
190 Turns off array bounds checking for all functions, which can improve
191 performance for code that uses arrays extensively. Note that this
192 can result in unpredictable behavior if the code in question actually
193 does violate array bounds constraints. It is safe to use this option
194 if you are sure that your code never throws a @code{RangeError}.
196 @opindex fbounds-check=
197 @item -fbounds-check=@var{value}
198 An alternative to @option{-fbounds-check} that allows more control
199 as to where bounds checking is turned on or off. The following values
204 Turns on array bounds checking for all functions.
206 Turns on array bounds checking only for @code{@@safe} functions.
208 Turns off array bounds checking completely.
214 Don't recognize built-in functions unless they begin with the prefix
215 @samp{__builtin_}. By default, the compiler will recognize when a
216 function in the @code{core.stdc} package is a built-in function.
218 @opindex fcheckaction
219 @item -fcheckaction=@var{value}
220 This option controls what code is generated on an assertion, bounds check, or
221 final switch failure. The following values are supported:
225 Throw an @code{AssertError} with extra context information.
227 Halt the program execution.
229 Throw an @code{AssertError} (the default).
235 @item -fdebug=@var{value}
236 Turn on compilation of conditional @code{debug} code into the program.
237 The @option{-fdebug} option itself sets the debug level to @code{1},
238 while @option{-fdebug=} enables @code{debug} code that are identified
239 by any of the following values:
243 Turns on compilation of any @code{debug} code identified by @var{ident}.
247 @opindex fno-druntime
249 Implements @uref{https://dlang.org/spec/betterc.html}. Assumes that
250 compilation targets an environment without a D runtime library.
252 This is equivalent to compiling with the following options:
255 gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
259 @item -fextern-std=@var{standard}
260 Sets the C++ name mangling compatibility to the version identified by
261 @var{standard}. The following values are supported:
266 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{199711}.
268 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201103}.
270 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201402}.
272 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{201703}.
275 Sets @code{__traits(getTargetInfo, "cppStd")} to @code{202002}.
279 @opindex fno-invariants
280 @item -fno-invariants
281 Turns off code generation for class @code{invariant} contracts.
285 Generates a default @code{main()} function when compiling. This is useful when
286 unittesting a library, as it enables running the unittests in a library without
287 having to manually define an entry-point function. This option does nothing
288 when @code{main} is already defined in user code.
291 @opindex fno-moduleinfo
292 @item -fno-moduleinfo
293 Turns off generation of the @code{ModuleInfo} and related functions
294 that would become unreferenced without it, which may allow linking
295 to programs not written in D. Functions that are not be generated
296 include module constructors and destructors (@code{static this} and
297 @code{static ~this}), @code{unittest} code, and @code{DSO} registry
298 functions for dynamically linked code.
301 @item -fonly=@var{filename}
302 Tells the compiler to parse and run semantic analysis on all modules
303 on the command line, but only generate code for the module specified
306 @opindex fpostconditions
307 @opindex fno-postconditions
308 @item -fno-postconditions
309 Turns off code generation for postcondition @code{out} contracts.
311 @opindex fpreconditions
312 @opindex fno-preconditions
313 @item -fno-preconditions
314 Turns off code generation for precondition @code{in} contracts.
317 @item -fpreview=@var{id}
318 Turns on an upcoming D language change identified by @var{id}. The following
319 values are supported:
323 Turns on all upcoming D language features.
325 Implements bit-fields in D.
327 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md}
330 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md}
331 (Allow exceptions in @code{@@nogc} code).
333 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md}
334 (Mutable function arguments).
336 Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
339 Turns on generation for destructing fields of partially constructed objects.
341 Turns on generation of struct equality to use field-wise comparisons.
343 Implements new lookup rules that check the current scope for @code{alias this}
344 before searching in upper scopes.
345 @item fiximmutableconv
346 Disallows unsound immutable conversions that were formerly incorrectly
349 Implements @code{in} parameters to mean @code{scope const [ref]} and accepts
351 @item inclusiveincontracts
352 Implements @code{in} contracts of overridden methods to be a superset of parent
355 Turns off and disallows all access to shared memory objects.
357 Implements rvalue arguments to @code{ref} parameters.
358 @item systemvariables
359 Disables access to variables marked @code{@@system} from @code{@@safe} code.
365 Turns on compiling in release mode, which means not emitting runtime
366 checks for contracts and asserts. Array bounds checking is not done
367 for @code{@@system} and @code{@@trusted} functions, and assertion
368 failures are undefined behavior.
370 This is equivalent to compiling with the following options:
373 gdc -fno-assert -fbounds-check=safe -fno-invariants \
374 -fno-postconditions -fno-preconditions -fno-switch-errors
379 Turns off a D language feature identified by @var{id}. The following values
384 Turns off all revertable D language features.
386 Reverts @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md}
389 Reverts @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md}
392 Turns off generation for destructing fields of partially constructed objects.
394 Turns off C-style integral promotion for unary @code{+}, @code{-} and @code{~}
401 Turns off generation of run-time type information for all user defined types.
402 Any code that uses features of the language that require access to this
403 information will result in an error.
405 @opindex fswitch-errors
406 @opindex fno-switch-errors
407 @item -fno-switch-errors
408 This option controls what code is generated when no case is matched
409 in a @code{final switch} statement. The default run time behavior
410 is to throw a @code{SwitchError}. Turning off @option{-fswitch-errors}
411 means that instead the execution of the program is immediately halted.
414 @opindex fno-unittest
416 Turns on compilation of @code{unittest} code, and turns on the
417 @code{version(unittest)} identifier. This implies @option{-fassert}.
420 @item -fversion=@var{value}
421 Turns on compilation of conditional @code{version} code into the program
422 identified by any of the following values:
426 Turns on compilation of @code{version} code identified by @var{ident}.
429 @opindex fweak-templates
430 @opindex fno-weak-templates
431 @item -fno-weak-templates
432 Turns off emission of declarations that can be defined in multiple objects as
433 weak symbols. The default is to emit all public symbols as weak, unless the
434 target lacks support for weak symbols. Disabling this option means that common
435 symbols are instead put in COMDAT or become private.
439 @node Directory Options
440 @section Options for Directory Search
441 @cindex directory options
442 @cindex options, directory search
445 These options specify directories to search for files, libraries, and
446 other parts of the compiler:
452 Specify a directory to use when searching for imported modules at
453 compile time. Multiple @option{-I} options can be used, and the
454 paths are searched in the same order.
458 Specify a directory to use when searching for files in string imports
459 at compile time. This switch is required in order to use
460 @code{import(file)} expressions. Multiple @option{-J} options can be
461 used, and the paths are searched in the same order.
465 When linking, specify a library search directory, as with @command{gcc}.
469 This option specifies where to find the executables, libraries,
470 source files, and data files of the compiler itself, as with @command{gcc}.
472 @opindex fmodule-file
473 @item -fmodule-file=@var{module}=@var{spec}
474 This option manipulates file paths of imported modules, such that if an
475 imported module matches all or the leftmost part of @var{module}, the file
476 path in @var{spec} is used as the location to search for D sources.
477 This is used when the source file path and names are not the same as the
478 package and module hierarchy. Consider the following examples:
481 gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
484 This will tell the compiler to search in all import paths for the source
485 file @var{foo.d} when importing @var{A.B}, and the directory @var{bar/}
486 when importing @var{C}, as annotated in the following D code:
490 import A.B; // Matches A.B, searches for foo.d
491 import C.D.E; // Matches C, searches for bar/D/E.d
492 import A.B.C; // No match, searches for A/B/C.d
496 @item -imultilib @var{dir}
497 Use @var{dir} as a subdirectory of the gcc directory containing
498 target-specific D sources and interfaces.
501 @item -iprefix @var{prefix}
502 Specify @var{prefix} as the prefix for the gcc directory containing
503 target-specific D sources and interfaces. If the @var{prefix} represents
504 a directory, you should include the final @code{'/'}.
508 Do not search the standard system directories for D source and interface
509 files. Only the directories that have been specified with @option{-I} options
510 (and the directory of the current file, if appropriate) are searched.
514 @node Code Generation
515 @section Code Generation
516 @cindex options, code generation
518 In addition to the many @command{gcc} options controlling code generation,
519 @command{gdc} has several options specific to itself.
525 Generates D interface files for all modules being compiled. The compiler
526 determines the output file based on the name of the input file, removes
527 any directory components and suffix, and applies the @file{.di} suffix.
531 Same as @option{-H}, but writes interface files to directory @var{dir}.
532 This option can be used with @option{-Hf @var{file}} to independently set the
533 output file and directory path.
537 Same as @option{-H} but writes interface files to @var{file}. This option can
538 be used with @option{-Hd @var{dir}} to independently set the output file and
543 Output the module dependencies of all source files being compiled in a
544 format suitable for @command{make}. The compiler outputs one
545 @command{make} rule containing the object file name for that source file,
546 a colon, and the names of all imported files.
550 Like @option{-M} but does not mention imported modules from the D standard
551 library package directories.
555 When used with @option{-M} or @option{-MM}, specifies a @var{file} to write
556 the dependencies to. When used with the driver options @option{-MD} or
557 @option{-MMD}, @option{-MF} overrides the default dependency output file.
561 This option is for compatibility with @command{gcc}, and is ignored by the
566 Outputs a phony target for each dependency other than the modules being
567 compiled, causing each to depend on nothing.
570 @item -MT @var{target}
571 Change the @var{target} of the rule emitted by dependency generation
572 to be exactly the string you specify. If you want multiple targets,
573 you can specify them as a single argument to @option{-MT}, or use
574 multiple @option{-MT} options.
577 @item -MQ @var{target}
578 Same as @option{-MT}, but it quotes any characters which are special to
583 This option is equivalent to @option{-M -MF @var{file}}. The driver
584 determines @var{file} by removing any directory components and suffix
585 from the input file, and then adding a @file{.deps} suffix.
589 Like @option{-MD} but does not mention imported modules from the D standard
590 library package directories.
594 Output information describing the contents of all source files being
595 compiled in JSON format to a file. The driver determines @var{file} by
596 removing any directory components and suffix from the input file, and then
597 adding a @file{.json} suffix.
601 Same as @option{-X}, but writes all JSON contents to the specified
606 Generates @code{Ddoc} documentation and writes it to a file. The compiler
607 determines @var{file} by removing any directory components and suffix
608 from the input file, and then adding a @file{.html} suffix.
611 @item -fdoc-dir=@var{dir}
612 Same as @option{-fdoc}, but writes documentation to directory @var{dir}.
613 This option can be used with @option{-fdoc-file=@var{file}} to
614 independently set the output file and directory path.
617 @item -fdoc-file=@var{file}
618 Same as @option{-fdoc}, but writes documentation to @var{file}. This
619 option can be used with @option{-fdoc-dir=@var{dir}} to independently
620 set the output file and directory path.
623 @item -fdoc-inc=@var{file}
624 Specify @var{file} as a @var{Ddoc} macro file to be read. Multiple
625 @option{-fdoc-inc} options can be used, and files are read and processed
628 @item -fdump-c++-spec=@var{file}
629 For D source files, generate corresponding C++ declarations in @var{file}.
631 @item -fdump-c++-spec-verbose
632 In conjunction with @option{-fdump-c++-spec=} above, add comments for ignored
633 declarations in the generated C++ header.
635 @opindex fsave-mixins
636 @item -fsave-mixins=@var{file}
637 Generates code expanded from D @code{mixin} statements and writes the
638 processed sources to @var{file}. This is useful to debug errors in compilation
639 and provides source for debuggers to show when requested.
645 @cindex options, warnings
646 @cindex options, errors
647 @cindex warnings, suppressing
648 @cindex messages, error
649 @cindex messages, warning
650 @cindex suppressing warnings
652 Warnings are diagnostic messages that report constructions that
653 are not inherently erroneous but that are risky or suggest there
654 is likely to be a bug in the program. Unless @option{-Werror} is
655 specified, they do not prevent compilation of the program.
662 Turns on all warnings messages. Warnings are not a defined part of
663 the D language, and all constructs for which this may generate a
664 warning message are valid code.
668 This option warns on all uses of "alloca" in the source.
670 @opindex Walloca-larger-than
671 @opindex Wno-alloca-larger-than
672 @item -Walloca-larger-than=@var{n}
673 Warn on unbounded uses of alloca, and on bounded uses of alloca
674 whose bound can be larger than @var{n} bytes.
675 @option{-Wno-alloca-larger-than} disables
676 @option{-Walloca-larger-than} warning and is equivalent to
677 @option{-Walloca-larger-than=@var{SIZE_MAX}} or larger.
679 @opindex Wno-builtin-declaration-mismatch
680 @opindex Wbuiltin-declaration-mismatch
681 @item -Wno-builtin-declaration-mismatch
682 Warn if a built-in function is declared with an incompatible signature.
684 @opindex Wcast-result
685 @opindex Wno-cast-result
687 Warn about casts that will produce a null or zero result. Currently
688 this is only done for casting between an imaginary and non-imaginary
689 data type, or casting between a D and C++ class.
692 @opindex Wno-deprecated
693 @item -Wno-deprecated
694 Do not warn about usage of deprecated features and symbols with
695 @code{deprecated} attributes.
700 Turns all warnings into errors.
705 This enables some extra warning flags that are not enabled by
708 @gccoptlist{-Waddress
710 -Wmismatched-special-enum
713 @opindex Wmismatched-special-enum
714 @opindex Wno-mismatched-special-enum
715 @item -Wmismatched-special-enum
716 Warn when an enum the compiler recognizes as special is declared with a
717 different size to the built-in type it is representing.
719 @opindex Wspeculative
720 @opindex Wno-speculative
722 List all error messages from speculative compiles, such as
723 @code{__traits(compiles, ...)}. This option does not report
724 messages as warnings, and these messages therefore never become
725 errors when the @option{-Werror} option is also used.
727 @opindex Wunknown-pragmas
728 @opindex Wno-unknown-pragmas
729 @item -Wunknown-pragmas
730 Warn when a @code{pragma()} is encountered that is not understood by
731 @command{gdc}. This differs from @option{-fignore-unknown-pragmas}
732 where a pragma that is part of the D language, but not implemented by
733 the compiler, won't get reported.
738 Do not warn upon questionable usage of the macros used to handle variable
739 arguments like @code{va_start}.
741 @opindex fignore-unknown-pragmas
742 @opindex fno-ignore-unknown-pragmas
743 @item -fignore-unknown-pragmas
744 Turns off errors for unsupported pragmas.
747 @item -fmax-errors=@var{n}
748 Limits the maximum number of error messages to @var{n}, at which point
749 @command{gdc} bails out rather than attempting to continue processing the
750 source code. If @var{n} is 0 (the default), there is no limit on the
751 number of error messages produced.
753 @opindex fsyntax-only
754 @opindex fno-syntax-only
756 Check the code for syntax errors, but do not actually compile it. This
757 can be used in conjunction with @option{-fdoc} or @option{-H} to generate
758 files for each module present on the command-line, but no other output
762 @item -ftransition=@var{id}
763 Report additional information about D language changes identified by
764 @var{id}. The following values are supported:
768 List information on all D language transitions.
770 List all usages of complex or imaginary types.
772 List all non-mutable fields which occupy an object instance.
774 List all usages of @code{in} on parameter.
776 List all hidden GC allocations.
778 List statistics on template instantiations.
780 List all variables going into thread local storage.
786 @section Options for Linking
787 @cindex options, linking
788 @cindex linking, static
790 These options come into play when the compiler links object files into an
791 executable output file. They are meaningless if the compiler is not doing
797 @item -defaultlib=@var{libname}
798 Specify the library to use instead of libphobos when linking. Options
799 specifying the linkage of libphobos, such as @option{-static-libphobos}
800 or @option{-shared-libphobos}, are ignored.
803 @item -debuglib=@var{libname}
804 Specify the debug library to use instead of libphobos when linking.
805 This option has no effect unless the @option{-g} option was also given
806 on the command line. Options specifying the linkage of libphobos, such
807 as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored.
811 Do not use the Phobos or D runtime library when linking. Options specifying
812 the linkage of libphobos, such as @option{-static-libphobos} or
813 @option{-shared-libphobos}, are ignored. The standard system libraries are
814 used normally, unless @option{-nostdlib} or @option{-nodefaultlibs} is used.
816 @opindex shared-libphobos
817 @item -shared-libphobos
818 On systems that provide @file{libgphobos} and @file{libgdruntime} as a
819 shared and a static library, this option forces the use of the shared
820 version. If no shared version was built when the compiler was configured,
821 this option has no effect.
823 @opindex static-libphobos
824 @item -static-libphobos
825 On systems that provide @file{libgphobos} and @file{libgdruntime} as a
826 shared and a static library, this option forces the use of the static
827 version. If no static version was built when the compiler was configured,
828 this option has no effect.
832 @node Developer Options
833 @section Developer Options
834 @cindex developer options
835 @cindex debug dump options
838 This section describes command-line options that are primarily of
839 interest to developers or language tooling.
843 @opindex fdump-d-original
844 @item -fdump-d-original
845 Output the internal front-end AST after the @code{semantic3} stage.
846 This option is only useful for debugging the GNU D compiler itself.
850 Dump information about the compiler language processing stages as the source
851 program is being compiled. This includes listing all modules that are
852 processed through the @code{parse}, @code{semantic}, @code{semantic2}, and
853 @code{semantic3} stages; all @code{import} modules and their file paths;
854 and all @code{function} bodies that are being compiled.
860 @include implement-d.texi
866 @unnumbered Option Index
868 @command{gdc}'s command line options are indexed here without any initial
869 @samp{-} or @samp{--}. Where an option has both positive and negative forms
870 (such as @option{-f@var{option}} and @option{-fno-@var{option}}), relevant
871 entries in the manual are indexed under the most appropriate form; it may
872 sometimes be useful to look up both forms.
877 @unnumbered Keyword Index