MAN page from RedHat EL 9 gdc122-12.2.0-4.1.el9.x86_64.rpm

GDC

Section: GNU (1)
Updated: 2022-08-19
Index

NAME

gdc - A GCC-based compiler for the D language

SYNOPSIS

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

DESCRIPTION

The gdc command is the GNU compiler for the D language andsupports many of the same options as gcc. This manual only documents the options specific to gdc.

OPTIONS

Input and Output files

For any given input file, the file name suffix determines what kind ofcompilation 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 evenwhen 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 createdby 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 isprimarily designed for use in producing user documentation from embeddedcomments, with a slight affinity towards HTML generation. If a .dsource file starts with the string "Ddoc" then it is treated as generalpurpose documentation, not as a D source file.

Runtime Options

These options affect the runtime behavior of programs compiled withgdc.

-fall-instantiations

Generate code for all template instantiations. The default template emissionstrategy is to not generate code for declarations that were eitherinstantiated speculatively, such as from "__traits(compiles, ...)", orthat 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 improveperformance for code that uses arrays extensively. Note that thiscan result in unpredictable behavior if the code in question actuallydoes violate array bounds constraints. It is safe to use this optionif you are sure that your code never throws a "RangeError".

-fbounds-check=value

An alternative to -fbounds-check that allows more controlas to where bounds checking is turned on or off. The following valuesare 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 afunction in the "core.stdc" package is a built-in function.

-fcheckaction=value

This option controls what code is generated on an assertion, bounds check, orfinal 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 identifiedby any of the following values:

level: Sets the debug level to level, any "debug" code <= levelis 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 thatcompilation 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 bystandard. 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 whenunittesting a library, as it enables running the unittests in a library withouthaving to manually define an entry-point function. This option does nothingwhen "main" is already defined in user code.

-fno-moduleinfo

Turns off generation of the "ModuleInfo" and related functionsthat would become unreferenced without it, which may allow linkingto programs not written in D. Functions that are not be generatedinclude module constructors and destructors ("static this" and"static ~this"), "unittest" code, and "DSO" registryfunctions for dynamically linked code.

-fonly=filename

Tells the compiler to parse and run semantic analysis on all moduleson the command line, but only generate code for the module specifiedby 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 followingvalues are supported:

all: Turns on all upcoming D language features.
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.
in: Implements "in" parameters to mean "scope const [ref]" and acceptsrvalues.
inclusiveincontracts: Implements "in" contracts of overridden methods to be a superset of parentcontract.
intpromote: Implements C-style integral promotion for unary "+", "-" and "~"expressions.
nosharedaccess: Turns off and disallows all access to shared memory objects.
rvaluerefparam: Implements rvalue arguments to "ref" parameters.
shortenedmethods: Implements use of "=>" for methods and top-level functions in addition tolambdas.

-frelease

Turns on compiling in release mode, which means not emitting runtimechecks for contracts and asserts. Array bounds checking is not donefor @system and @trusted functions, and assertionfailures 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 valuesare supported:

all: Turns off all revertable D language features.
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.
markdown: Turns off Markdown replacements in Ddoc comments.

-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 thisinformation will result in an error.

-fno-switch-errors

This option controls what code is generated when no case is matchedin a "final switch" statement. The default run time behavioris to throw a "SwitchError". Turning off -fswitch-errorsmeans 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 programidentified by any of the following values:

level: Sets the version level to level, any "version" code >= levelis 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 asweak symbols. The default is to emit all public symbols as weak, unless thetarget lacks support for weak symbols. Disabling this option means that commonsymbols are instead put in COMDAT or become private.

Options for Directory Search

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

-Idir

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

-Jdir

Specify a directory to use when searching for files in string importsat compile time. This switch is required in order to use"import(file)" expressions. Multiple -J options can beused, 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 animported module matches all or the leftmost part of module, the filepath 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 thepackage 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 sourcefile 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 containingtarget-specific D sources and interfaces.

-iprefix prefix

Specify prefix as the prefix for the gcc directory containingtarget-specific D sources and interfaces. If the prefix representsa directory, you should include the final '/'.

-nostdinc

Do not search the standard system directories for D source and interfacefiles. 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 compilerdetermines the output file based on the name of the input file, removesany 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 theoutput file and directory path.
-Hf file: Same as -H but writes interface files to file. This option canbe used with -Hd dir to independently set the output file anddirectory path.
-M: Output the module dependencies of all source files being compiled in aformat suitable for make. The compiler outputs onemake 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 standardlibrary package directories.
-MF file: When used with -M or -MM, specifies a file to writethe 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 thecompiler.
-MP: Outputs a phony target for each dependency other than the modules beingcompiled, causing each to depend on nothing.
-MT target: Change the target of the rule emitted by dependency generationto be exactly the string you specify. If you want multiple targets,you can specify them as a single argument to -MT, or usemultiple -MT options.
-MQ target: Same as -MT, but it quotes any characters which are special tomake.
-MD: This option is equivalent to -M -MF file. The driverdetermines file by removing any directory components and suffixfrom the input file, and then adding a .deps suffix.
-MMD: Like -MD but does not mention imported modules from the D standardlibrary package directories.
-X: Output information describing the contents of all source files beingcompiled in JSON format to a file. The driver determines file byremoving any directory components and suffix from the input file, and thenadding a .json suffix.
-Xf file: Same as -X, but writes all JSON contents to the specifiedfile.
-fdoc: Generates "Ddoc" documentation and writes it to a file. The compilerdetermines file by removing any directory components and suffixfrom 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 toindependently set the output file and directory path.
-fdoc-file=file: Same as -fdoc, but writes documentation to file. Thisoption can be used with -fdoc-dir=dir to independentlyset 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 processedin 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 ignoreddeclarations in the generated C++ header.
-fsave-mixins=file: Generates code expanded from D "mixin" statements and writes theprocessed sources to file. This is useful to debug errors in compilationand provides source for debuggers to show when requested.

Warnings

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

-Wall

Turns on all warnings messages. Warnings are not a defined part ofthe D language, and all constructs for which this may generate awarning 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 allocawhose 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. Currentlythis is only done for casting between an imaginary and non-imaginarydata 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 reportmessages as warnings, and these messages therefore never becomeerrors when the -Werror option is also used.

-Wtemplates

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

-Wunknown-pragmas

Warn when a "pragma()" is encountered that is not understood bygdc. This differs from -fignore-unknown-pragmaswhere a pragma that is part of the D language, but not implemented bythe compiler, won't get reported.

-Wno-varargs

Do not warn upon questionable usage of the macros used to handle variablearguments 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 pointgdc bails out rather than attempting to continue processing thesource code. If n is 0 (the default), there is no limit on thenumber of error messages produced.

-fsyntax-only

Check the code for syntax errors, but do not actually compile it. Thiscan be used in conjunction with -fdoc or -H to generatefiles for each module present on the command-line, but no other outputfile.

-ftransition=id

Report additional information about D language changes identified byid. 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.
vmarkdown: List instances of Markdown replacements in Ddoc.

Options for Linking

These options come into play when the compiler links object files into anexecutable output file. They are meaningless if the compiler is not doinga link step.

-defaultlib=libname: Specify the library to use instead of libphobos when linking. Optionsspecifying the linkage of libphobos, such as -static-libphobosor -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 givenon the command line. Options specifying the linkage of libphobos, suchas -static-libphobos or -shared-libphobos, are ignored.
-nophoboslib: Do not use the Phobos or D runtime library when linking. Options specifyingthe linkage of libphobos, such as -static-libphobos or-shared-libphobos, are ignored. The standard system libraries areused normally, unless -nostdlib or -nodefaultlibs is used.
-shared-libphobos: On systems that provide libgphobos and libgdruntime as ashared and a static library, this option forces the use of the sharedversion. 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 ashared and a static library, this option forces the use of the staticversion. 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 ofinterest 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 sourceprogram is being compiled. This includes listing all modules that areprocessed through the "parse", "semantic", "semantic2", and"semantic3" stages; all "import" modules and their file paths;and all "function" bodies that are being compiled.

COPYRIGHT

Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.3 orany later version published by the Free Software Foundation; with noInvariant Sections, no Front-Cover Texts, and no Back-Cover Texts.A copy of the license is included in theman page gfdl(7).

SEE ALSO

COPYRIGHT

This document was created byman2html,using the manual pages.