     [file gcc-common.texi not included]

Copyright © 2006-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Introduction
************

This manual describes how to use gdc, the GNU compiler for the D programming language.  This manual is specifically about how to invoke gdc, as well as its features and incompatibilities. For more information about the D programming language in general, including language specifications and standard package documentation, see https://dlang.org/.

Invoking gdc
************

The gdc command is the GNU compiler for the D language and supports many of the same options as gcc.  See Option Summary (Using the GNU Compiler Collection (GCC)). This manual only documents the options specific to gdc.

Input and Output files
======================

For any given input file, the file name suffix determines what kind of compilation is done.  The following kinds of input file names are supported:

FILE.d
     D source files.

FILE.dd
     Ddoc source files.

FILE.di
     D interface files.

You can specify more than one input file on the gdc command line, each being compiled separately in the compilation process.  If you specify a -o FILE option, all the input files are compiled together, producing a single output file, named FILE.  This is allowed even when using -S or -c.

A D interface file contains only what an import of the module needs, rather than the whole implementation of that module.  They can be created by gdc from a D source file by using the -H option. When the compiler resolves an import declaration, it searches for matching .di files first, then for .d.

A Ddoc source file contains code in the D macro processor language.  It is primarily designed for use in producing user documentation from embedded comments, with a slight affinity towards HTML generation.  If a .d source file starts with the string Ddoc then it is treated as general purpose documentation, not as a D source file.

Runtime Options
===============

These options affect the runtime behavior of programs compiled with gdc.

-fall-instantiations
     Generate code for all template instantiations.  The default template emission strategy is to not generate code for declarations that were either instantiated speculatively, such as from __traits(compiles, ...), or that come from an imported module not being compiled.

-fno-assert
     Turn off code generation for assert contracts.

-fno-bounds-check
     Turns off array bounds checking for all functions, which can improve performance for code that uses arrays extensively.  Note that this can result in unpredictable behavior if the code in question actually does violate array bounds constraints.  It is safe to use this option if you are sure that your code never throws a RangeError.

-fbounds-check=VALUE
     An alternative to -fbounds-check that allows more control as to where bounds checking is turned on or off.  The following values are supported:

     on
          Turns on array bounds checking for all functions.

     safeonly
          Turns on array bounds checking only for @safe functions.

     off
          Turns off array bounds checking completely.

-fno-builtin
     Don't recognize built-in functions unless they begin with the prefix __builtin_.  By default, the compiler will recognize when a function in the core.stdc package is a built-in function.

-fcheckaction=VALUE
     This option controls what code is generated on an assertion, bounds check, or final switch failure.  The following values are supported:

     context
          Throw an AssertError with extra context information.

     halt
          Halt the program execution.

     throw
          Throw an AssertError (the default).

-fdebug

-fdebug=VALUE
     Turn on compilation of conditional debug code into the program. The -fdebug option itself sets the debug level to 1, while -fdebug= enables debug code that are identified by any of the following values:

     ident
          Turns on compilation of any debug code identified by IDENT.

-fno-druntime
     Implements https://dlang.org/spec/betterc.html.  Assumes that compilation targets an environment without a D runtime library.

     This is equivalent to compiling with the following options:

          gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti

-fextern-std=STANDARD
     Sets the C++ name mangling compatibility to the version identified by STANDARD.  The following values are supported:

     c++98

     c++03
          Sets __traits(getTargetInfo, "cppStd") to 199711.

     c++11
          Sets __traits(getTargetInfo, "cppStd") to 201103.

     c++14
          Sets __traits(getTargetInfo, "cppStd") to 201402.

     c++17
          Sets __traits(getTargetInfo, "cppStd") to 201703. This is the default.

     c++20
          Sets __traits(getTargetInfo, "cppStd") to 202002.

-fno-invariants
     Turns off code generation for class invariant contracts.

-fmain
     Generates a default main() function when compiling.  This is useful when unittesting a library, as it enables running the unittests in a library without having to manually define an entry-point function.  This option does nothing when main is already defined in user code.

-fno-moduleinfo
     Turns off generation of the ModuleInfo and related functions that would become unreferenced without it, which may allow linking to programs not written in D.  Functions that are not be generated include module constructors and destructors (static this and static ~this), unittest code, and DSO registry functions for dynamically linked code.

-fonly=FILENAME
     Tells the compiler to parse and run semantic analysis on all modules on the command line, but only generate code for the module specified by FILENAME.

-fno-postconditions
     Turns off code generation for postcondition out contracts.

-fno-preconditions
     Turns off code generation for precondition in contracts.

-fpreview=ID
     Turns on an upcoming D language change identified by ID.  The following values are supported:

     all
          Turns on all upcoming D language features.

     bitfields
          Implements bit-fields in D.

     dip1000
          Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md (Scoped pointers).

     dip1008
          Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md (Allow exceptions in @nogc code).

     dip1021
          Implements https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md (Mutable function arguments).

     dip25
          Implements https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md (Sealed references).

     dtorfields
          Turns on generation for destructing fields of partially constructed objects.

     fieldwise
          Turns on generation of struct equality to use field-wise comparisons.

     fixaliasthis
          Implements new lookup rules that check the current scope for alias this before searching in upper scopes.

     fiximmutableconv
          Disallows unsound immutable conversions that were formerly incorrectly permitted.

     in
          Implements in parameters to mean scope const [ref] and accepts rvalues.

     inclusiveincontracts
          Implements in contracts of overridden methods to be a superset of parent contract.

     nosharedaccess
          Turns off and disallows all access to shared memory objects.

     rvaluerefparam
          Implements rvalue arguments to ref parameters.

     systemvariables
          Disables access to variables marked @system from @safe code.

-frelease
     Turns on compiling in release mode, which means not emitting runtime checks for contracts and asserts.  Array bounds checking is not done for @system and @trusted functions, and assertion failures are undefined behavior.

     This is equivalent to compiling with the following options:

          gdc -fno-assert -fbounds-check=safe -fno-invariants \
              -fno-postconditions -fno-preconditions -fno-switch-errors

-frevert=
     Turns off a D language feature identified by ID.  The following values are supported:

     all
          Turns off all revertable D language features.

     dip1000
          Reverts https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md (Scoped pointers).

     dip25
          Reverts https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md (Sealed references).

     dtorfields
          Turns off generation for destructing fields of partially constructed objects.

     intpromote
          Turns off C-style integral promotion for unary +, - and ~ expressions.

-fno-rtti
     Turns off generation of run-time type information for all user defined types. Any code that uses features of the language that require access to this information will result in an error.

-fno-switch-errors
     This option controls what code is generated when no case is matched in a final switch statement.  The default run time behavior is to throw a SwitchError.  Turning off -fswitch-errors means that instead the execution of the program is immediately halted.

-funittest
     Turns on compilation of unittest code, and turns on the version(unittest) identifier.  This implies -fassert.

-fversion=VALUE
     Turns on compilation of conditional version code into the program identified by any of the following values:

     ident
          Turns on compilation of version code identified by IDENT.

-fno-weak-templates
     Turns off emission of declarations that can be defined in multiple objects as weak symbols.  The default is to emit all public symbols as weak, unless the target lacks support for weak symbols.  Disabling this option means that common symbols are instead put in COMDAT or become private.

Options for Directory Search
============================

These options specify directories to search for files, libraries, and other parts of the compiler:

-IDIR
     Specify a directory to use when searching for imported modules at compile time.  Multiple -I options can be used, and the paths are searched in the same order.

-JDIR
     Specify a directory to use when searching for files in string imports at compile time.  This switch is required in order to use import(file) expressions.  Multiple -J options can be used, and the paths are searched in the same order.

-LDIR
     When linking, specify a library search directory, as with gcc.

-BDIR
     This option specifies where to find the executables, libraries, source files, and data files of the compiler itself, as with gcc.

-fmodule-file=MODULE=SPEC
     This option manipulates file paths of imported modules, such that if an imported module matches all or the leftmost part of MODULE, the file path in SPEC is used as the location to search for D sources. This is used when the source file path and names are not the same as the package and module hierarchy.  Consider the following examples:

          gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar

     This will tell the compiler to search in all import paths for the source file FOO.D when importing A.B, and the directory BAR/ when importing C, as annotated in the following D code:

          module test;
          import A.B;     // Matches A.B, searches for foo.d
          import C.D.E;   // Matches C, searches for bar/D/E.d
          import A.B.C;   // No match, searches for A/B/C.d

-imultilib DIR
     Use DIR as a subdirectory of the gcc directory containing target-specific D sources and interfaces.

-iprefix PREFIX
     Specify PREFIX as the prefix for the gcc directory containing target-specific D sources and interfaces.  If the PREFIX represents a directory, you should include the final '/'.

-nostdinc
     Do not search the standard system directories for D source and interface files.  Only the directories that have been specified with -I options (and the directory of the current file, if appropriate) are searched.

Code Generation
===============

In addition to the many gcc options controlling code generation, gdc has several options specific to itself.

-H
     Generates D interface files for all modules being compiled.  The compiler determines the output file based on the name of the input file, removes any directory components and suffix, and applies the .di suffix.

-Hd DIR
     Same as -H, but writes interface files to directory DIR. This option can be used with -Hf FILE to independently set the output file and directory path.

-Hf FILE
     Same as -H but writes interface files to FILE.  This option can be used with -Hd DIR to independently set the output file and directory path.

-M
     Output the module dependencies of all source files being compiled in a format suitable for make.  The compiler outputs one make rule containing the object file name for that source file, a colon, and the names of all imported files.

-MM
     Like -M but does not mention imported modules from the D standard library package directories.

-MF FILE
     When used with -M or -MM, specifies a FILE to write the dependencies to.  When used with the driver options -MD or -MMD, -MF overrides the default dependency output file.

-MG
     This option is for compatibility with gcc, and is ignored by the compiler.

-MP
     Outputs a phony target for each dependency other than the modules being compiled, causing each to depend on nothing.

-MT TARGET
     Change the TARGET of the rule emitted by dependency generation to be exactly the string you specify.  If you want multiple targets, you can specify them as a single argument to -MT, or use multiple -MT options.

-MQ TARGET
     Same as -MT, but it quotes any characters which are special to make.

-MD
     This option is equivalent to -M -MF FILE.  The driver determines FILE by removing any directory components and suffix from the input file, and then adding a .deps suffix.

-MMD
     Like -MD but does not mention imported modules from the D standard library package directories.

-X
     Output information describing the contents of all source files being compiled in JSON format to a file.  The driver determines FILE by removing any directory components and suffix from the input file, and then adding a .json suffix.

-Xf FILE
     Same as -X, but writes all JSON contents to the specified FILE.

-fdoc
     Generates Ddoc documentation and writes it to a file.  The compiler determines FILE by removing any directory components and suffix from the input file, and then adding a .html suffix.

-fdoc-dir=DIR
     Same as -fdoc, but writes documentation to directory DIR. This option can be used with -fdoc-file=FILE to independently set the output file and directory path.

-fdoc-file=FILE
     Same as -fdoc, but writes documentation to FILE.  This option can be used with -fdoc-dir=DIR to independently set the output file and directory path.

-fdoc-inc=FILE
     Specify FILE as a DDOC macro file to be read.  Multiple -fdoc-inc options can be used, and files are read and processed in the same order.

-fdump-c++-spec=FILE
     For D source files, generate corresponding C++ declarations in FILE.

-fdump-c++-spec-verbose
     In conjunction with -fdump-c++-spec= above, add comments for ignored declarations in the generated C++ header.

-fsave-mixins=FILE
     Generates code expanded from D mixin statements and writes the processed sources to FILE.  This is useful to debug errors in compilation and provides source for debuggers to show when requested.

Warnings
========

Warnings are diagnostic messages that report constructions that are not inherently erroneous but that are risky or suggest there is likely to be a bug in the program.  Unless -Werror is specified, they do not prevent compilation of the program.

-Wall
     Turns on all warnings messages.  Warnings are not a defined part of the D language, and all constructs for which this may generate a warning message are valid code.

-Walloca
     This option warns on all uses of "alloca" in the source.

-Walloca-larger-than=N
     Warn on unbounded uses of alloca, and on bounded uses of alloca whose bound can be larger than N bytes. -Wno-alloca-larger-than disables -Walloca-larger-than warning and is equivalent to -Walloca-larger-than=SIZE_MAX or larger.

-Wno-builtin-declaration-mismatch
     Warn if a built-in function is declared with an incompatible signature.

-Wcast-result
     Warn about casts that will produce a null or zero result.  Currently this is only done for casting between an imaginary and non-imaginary data type, or casting between a D and C++ class.

-Wno-deprecated
     Do not warn about usage of deprecated features and symbols with deprecated attributes.

-Werror
     Turns all warnings into errors.

-Wextra
     This enables some extra warning flags that are not enabled by -Wall.

     -Waddress -Wcast-result -Wmismatched-special-enum -Wunknown-pragmas

-Wmismatched-special-enum
     Warn when an enum the compiler recognizes as special is declared with a different size to the built-in type it is representing.

-Wspeculative
     List all error messages from speculative compiles, such as __traits(compiles, ...).  This option does not report messages as warnings, and these messages therefore never become errors when the -Werror option is also used.

-Wunknown-pragmas
     Warn when a pragma() is encountered that is not understood by gdc.  This differs from -fignore-unknown-pragmas where a pragma that is part of the D language, but not implemented by the compiler, won't get reported.

-Wno-varargs
     Do not warn upon questionable usage of the macros used to handle variable arguments like va_start.

-fignore-unknown-pragmas
     Turns off errors for unsupported pragmas.

-fmax-errors=N
     Limits the maximum number of error messages to N, at which point gdc bails out rather than attempting to continue processing the source code.  If N is 0 (the default), there is no limit on the number of error messages produced.

-fsyntax-only
     Check the code for syntax errors, but do not actually compile it.  This can be used in conjunction with -fdoc or -H to generate files for each module present on the command-line, but no other output file.

-ftransition=ID
     Report additional information about D language changes identified by ID.  The following values are supported:

     all
          List information on all D language transitions.

     complex
          List all usages of complex or imaginary types.

     field
          List all non-mutable fields which occupy an object instance.

     in
          List all usages of in on parameter.

     nogc
          List all hidden GC allocations.

     templates
          List statistics on template instantiations.

     tls
          List all variables going into thread local storage.

Options for Linking
===================

These options come into play when the compiler links object files into an executable output file.  They are meaningless if the compiler is not doing a link step.

-defaultlib=LIBNAME
     Specify the library to use instead of libphobos when linking.  Options specifying the linkage of libphobos, such as -static-libphobos or -shared-libphobos, are ignored.

-debuglib=LIBNAME
     Specify the debug library to use instead of libphobos when linking. This option has no effect unless the -g option was also given on the command line.  Options specifying the linkage of libphobos, such as -static-libphobos or -shared-libphobos, are ignored.

-nophoboslib
     Do not use the Phobos or D runtime library when linking.  Options specifying the linkage of libphobos, such as -static-libphobos or -shared-libphobos, are ignored.  The standard system libraries are used normally, unless -nostdlib or -nodefaultlibs is used.

-shared-libphobos
     On systems that provide libgphobos and libgdruntime as a shared and a static library, this option forces the use of the shared version.  If no shared version was built when the compiler was configured, this option has no effect.

-static-libphobos
     On systems that provide libgphobos and libgdruntime as a shared and a static library, this option forces the use of the static version.  If no static version was built when the compiler was configured, this option has no effect.

Developer Options
=================

This section describes command-line options that are primarily of interest to developers or language tooling.

-fdump-d-original
     Output the internal front-end AST after the semantic3 stage. This option is only useful for debugging the GNU D compiler itself.

-v
     Dump information about the compiler language processing stages as the source program is being compiled.  This includes listing all modules that are processed through the parse, semantic, semantic2, and semantic3 stages; all import modules and their file paths; and all function bodies that are being compiled.

     [file implement-d.texi not included]

     [file gpl_v3.texi not included]
     [file fdl.texi not included]

Option Index
************

gdc's command line options are indexed here without any initial - or --.  Where an option has both positive and negative forms (such as -fOPTION and -fno-OPTION), relevant entries in the manual are indexed under the most appropriate form; it may sometimes be useful to look up both forms.