gdc - A GCC-based compiler for the D language
gdc [-c|-S] [-g] [-pg]
[-Olevel] [-Wwarn...]
[-Idir...] [-Ldir...]
[-foption...] [-mmachine-option...]
[-o outfile] [@file] infile...
Only the most useful options are listed here; see below for the
remainder.
The gdc command is the GNU compiler for the D language and
supports many of the same options as gcc. This manual only documents
the options specific to gdc.
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.
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.
- -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:
- level
- Sets the debug level to level, any
"debug" code <= level is
compiled into the program.
- 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
- -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 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.
- -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
- -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:
- level
- Sets the version level to level, any
"version" code >= level is
compiled into the program.
- 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.
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.
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.
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.
- -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
- 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.
- -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, 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 language changes.
- complex
- List all usages of complex or imaginary types.
- dip1000
- Implements <http://wiki.dlang.org/DIP1000>
(experimental).
- dip25
- Implements <http://wiki.dlang.org/DIP25> (experimental).
- field
- List all non-mutable fields which occupy an object instance.
- nogc
- List all hidden GC allocations.
- tls
- List all variables going into thread local storage.
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.
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.
Copyright (c) 2006-2021 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 man page gfdl(7).