GDC(1)

📦
version 13.5.0 · 2 versions
, in ubuntu stonking

👑 GDC(1) — the GNU D compiler, bestie edition

okay so welcome to gdc, straight out of the GNU lineup 💖 this is a long one so grab a snack, we're going section by section and I'm not leaving anything out, iykyk.

🌸 NAME 🌸

gdc — a GCC-based compiler for the D language. that's it, that's the girl 💅

✨ SYNOPSIS ✨

gdc [-c|-S] [-g] [-pg]
    [-Olevel] [-Wwarn...]
    [-Idir...] [-Ldir...]
    [-foption...] [-mmachine-option...]
    [-o outfile] [@file] infile...

ngl that list up there is literally just the greatest-hits version — only the most useful options are listed here; see below for the remainder 👇 the rest of them are all down in OPTIONS and there are so many.

🫶 DESCRIPTION 🫶

so gdc is the GNU compiler for the D language, and it supports a whole bunch of the same options as gcc 💖 but heads up — this manual is only about the options that are specific to gdc, not the shared ones.

💖 OPTIONS 💖

🎀 Input and Output files 🎀

for any given input file, the suffix on the file name is what decides what kind of compilation happens. no cap, the suffix runs the show. here's what's supported:

  • file.d — D source files. the main characters 🎀
  • file.dd — Ddoc source files.
  • file.di — D interface files.

you can drop more than one input file on the gdc command line, and each one gets compiled separately during the compilation process. but if you pass a -o file option, then all the input files get compiled together, producing one single output file named file ✨ and yes, that's allowed even when you're using -S or -c.

a D interface file only contains what an import of the module needs — not the whole implementation of that module, bestie, just the vibes you need to import it. you can make them with 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 holds code in the D macro processor language 💜 it's primarily designed for use in producing user documentation from embedded comments, with a slight affinity towards HTML generation. and here's the twist: if a .d source file starts with the string "Ddoc" then it's treated as general purpose documentation, not as a D source file. plot twist fr fr 🙈

🌈 Runtime Options 🌈

these options affect the runtime behavior of programs compiled with gdc. so like, the compiler's out of the picture and your program is living its life — these are the settings that shape it.

  • -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 — like from __traits(compiles, ...) — or that come from an imported module that isn't being compiled. so if you want absolutely every single one, this is your girl.
  • -fno-assert — turns off code generation for assert contracts. bye-bye asserts 👋
  • -fno-bounds-check — turns off array bounds checking for all functions, which can improve performance for code that uses arrays extensively. but bestie, listen: this can result in unpredictable behavior if the code in question actually does violate array bounds constraints. it is safe to use if you're sure your code never throws a RangeError. be so for real before you flip this one.
  • -fbounds-check=value — an alternative to -fbounds-check that gives you way more control over where bounds checking is turned on or off 🎛️ here's the supported values:
    • 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 gets generated on an assertion, bounds check, or final switch failure 💀 supported values:
    • context — throw an AssertError with extra context information.
    • halt — halt the program execution.
    • throw — throw an AssertError (the default).
  • -fdebug, -fdebug=value — turns 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's 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. it 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. supported values:
    • 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 one is so useful when unittesting a library, because it lets you run the unittests in a library without having to manually define an entry-point function. it does nothing when main is already defined in user code, so no conflict, no drama.
  • -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 🔥 the functions that don't get 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 🔮 supported values:
    • 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. supported values:
  • -fno-rtti — turns off generation of run-time type information for all user defined types. and heads up bestie: any code that uses features of the language that require access to this information will result in an error. it's giving "you asked for it" 😭
  • -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 🦋

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. order matters, bestie, it's a whole queue.
  • -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 you're linking, this says “bestie, go look in dir for libraries too,” exactly like gcc does it. 💅
  • -Bdir — tells the compiler where to find its own executables, libraries, source files, and data files, just like gcc. It's giving “I know where I live” energy. 🏠
  • -fmodule-file=module=spec — okay so this one is a whole vibe for imported modules. If an imported module matches all of module or the leftmost part of it, then the file path in spec becomes the spot to search for D sources. It's your “these file paths and names are NOT matching the package and module hierarchy” rescue. 🙈

Consider this example:

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

This tells the compiler: search all import paths for the source file foo.d when importing A.B, and search the directory bar/ when importing C, like the D code below shows:

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 that has target-specific D sources and interfaces. 🌸
  • -iprefix prefix — set prefix as the prefix for the gcc directory containing target-specific D sources and interfaces. If the prefix is a directory, bestie, include that final /. Slash included, periodt. 💅
  • -nostdinc — do NOT search the standard system directories for D source and interface files. Only the directories you gave with -I options (plus the current file's directory, if that's appropriate) get searched. 🚫

💖 Code Generation 💖

On top of the many gcc options that control code generation, gdc has its own little collection. And yes, they're iconic. ✨

  • -H — generates D interface files for all modules being compiled. The compiler picks the output file based on the input file's name, strips any directory components and suffix, then slaps on .di. 💅
  • -Hd dir — same as -H, but writes those interface files into directory dir. You can use this with -Hf file to independently set the output file and directory path. 🎀
  • -Hf file — same as -H but writes interface files to file. Can be used with -Hd dir to independently set the output file and directory path. 🫶
  • -M — outputs the module dependencies of all source files being compiled in a format suitable for make. The compiler spits out 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 doesn't mention imported modules from the D standard library package directories. Lowkey the same, highkey less noisy. 🙈
  • -MF file — when used with -M or -MM, this 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 one is for compatibility with gcc, and is ignored by the compiler. It's literally just there to vibe. 💀
  • -MP — outputs a phony target for each dependency other than the modules being compiled, causing each to depend on nothing. Iconic make trick. ✨
  • -MT target — change the target of the rule emitted by dependency generation to be exactly the string you specify. 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. She's careful. 💅
  • -MD — 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. Standard library stays out of it. 🚫
  • -X — outputs 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. JSON bestie! 🌈
  • -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. Docs slay. 📝
  • -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. Order matters, bestie. 📚
  • -fdump-c++-spec=file — for D source files, generate corresponding C++ declarations in file. C++ crossover episode. 🔄
  • -fdump-c++-spec-verbose — in conjunction with -fdump-c++-spec= above, add comments for ignored declarations in the generated C++ header. Extra chatty. 💬
  • -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. Debugging glow-up. 🐛

💖 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. So like, they're the group chat going “bestie are you sure?” but they won't stop the show. 😭

  • -Wall — turns on all warning 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. She's loud but valid. 📢
  • -Walloca — warns on all uses of "alloca" in the source. 🚨
  • -Walloca-larger-than=n — warns 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. Math is mathing. 🧮
  • -Wno-builtin-declaration-mismatch — warns if a built-in function is declared with an incompatible signature. 🚩
  • -Wcast-result — warns 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. She's checking your casts. 🔍
  • -Wno-deprecated — do not warn about usage of deprecated features and symbols with "deprecated" attributes. Living in the past? Not her problem. 🙅
  • -Werror — turns all warnings into errors. No more warning era, only error era. 💀
  • -Wextra — enables some extra warning flags that are not enabled by -Wall. The extra ones are: -Waddress, -Wcast-result, -Wmismatched-special-enum, -Wunknown-pragmas. More warnings, more power. ✨
  • -Wmismatched-special-enum — warns when an enum the compiler recognizes as special is declared with a different size to the built-in type it is representing. Size mismatch = warning. 📏
  • -Wspeculative — lists 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. Speculative tea. ☕
  • -Wunknown-pragmas — warns 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". Questionable usage? Not today. 🙈
  • -fignore-unknown-pragmas — turns off errors for unsupported pragmas. Let them be. 🕊
  • -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. Set your limit, bestie. 🛑
  • -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. Vibe check only. 👀
  • -ftransition=id — reports additional information about D language changes identified by id. The supported values are:
    • 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 bad boys only matter when the compiler is linking object files into an executable output file. If there's no link step, they're literally meaningless. Periodt. 💅

  • -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 is for the devs and language tooling girlies. Options that are mostly interesting if you're building the compiler or working on 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 — bestie, this one is the behind-the-scenes cam 🎥 and it is so nosy in the best way. It dumps info about the compiler's language processing stages while your source program is being compiled. What's in the dump? Listen:
    • every module that gets processed through the "parse", "semantic", "semantic2", and "semantic3" stages 👑
    • all "import" modules plus their file paths (so you can see exactly where it's pulling stuff from, no cap)
    • and all "function" bodies that are being compiled

Like… it's giving "compiler diary, unlocked" 📖✨. If you've ever been squinting at a build going "okay but WHAT is it even doing rn", this is your answer fr fr.

🌈 SEE ALSO 🌈

Go read your sisters, bestie, they're all iconic in their own lanes 💖

…and also the Info entries for gdc and gcc, which are lowkey the main characters if you want the deep lore 🫶

Copyright (c) 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 man page gfdl(7). 📜✨

Translation bestie: yes you can copy/distribute/modify this doc, go off, just follow the license terms above and grab the full text from gfdl(7). Periodt. 💅

And that's the whole page, bestie!! 🌸 This one shipped as version gcc-13.5.0 and it's dated 2026-09-10 — that's the source and the date right there, the little footer origin story 🦋✨ Thanks for reading all three parts, you ate that 💖👑

📦 where this page comes from