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, in which case they will all be compiled. If you specify a "-o file" option, all the input files will be 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 array 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 will never throw 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:

-fno-builtin

Don't recognize built-in functions that do not begin with __builtin_ as prefix. By default, the compiler will recognize when a function in the "core.stdc" package is a built-in function.

-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:

-fno-invariants

Turns off code generation for class "invariant" contracts.

-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 will not be generated include module constructor 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.

-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 behaviour.

This is equivalent to compiling with the following options:

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

-fno-switch-errors

This option controls what code should be generated when no case is matched in a "final switch" statement. The default run time behavior is that a "SwitchError" will be thrown. 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:

-fno-weak

Turns off emission of instantiated declarations that can be defined in multiple objects as weak or one-only symbols. The default is to emit all public symbols as weak, unless there lacks target support. Disabling this options 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 hierachy. 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 dir directory. 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 based on the name of the input file, removes any directory components and suffix, and applies 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 based on the name of the input file, removes any directory components and suffix, and applies a .json suffix.

-Xf file

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

-fdoc

Generates "Ddoc" documentation and writes to a file. The compiler determines file based on the name of the input file, removes any directory components and suffix, and applies a .html suffix.

-fdoc-dir=dir

Same as -fdoc, but writes documentation to dir directory. 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.

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 legal code.

-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.

-Wspeculative

Report on 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.

-Wtemplates

Warn when a template instantiation is encountered. Some coding rules disallow templates, and this may be used to enforce that rule.

-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, will not get reported.

-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 only suppresses the generation of the object code, and can be used in conjunction with -fdoc or -H options.

-ftransition=id

Report additional information about D language changes identified by id. The following values are supported:

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

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

Dump the front-end AST after after parsing and running semantic on the source program. Only really useful for debugging the 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.