GDC(1)

📦
version 10.5.0 · 3 versions
, in ubuntu jammy

💖 GDC(1) · GNU Manual 💖

✨ 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, so scroll down for the rest 👀

🌸 DESCRIPTION 🌸

okay so gdc is the GNU compiler for the D language, and it's giving very familiar energy because it supports a lot of the same options as gcc ✨ This manual only covers the options that are specific to gdc, so you don't have to re-learn everything 🫶

🦋 OPTIONS 🦋

📁 Input and Output files

For any given input file, the file name suffix decides what kind of compilation happens. These are the input file names that are supported:

  • file.d — D source files, the main event 💜
  • file.dd — Ddoc source files
  • file.di — D interface files

You can pass more than one input file on the gdc command line, and each one gets compiled separately. If you use the "-o file" option, though, all the input files get compiled together and you end up with one single output file, named file. This works even with "-S" or "-c" 🔥

A D interface file only has what an import of the module needs, not the whole implementation of that module, so it's like a lighter version 🎀 You can make one with gdc from a D source file by using the "-H" option. When the compiler resolves an import declaration, it looks for matching .di files first, and then for .d ✨

A Ddoc source file has code in the D macro processor language. It's mainly made for turning embedded comments into user documentation, and it's leaning towards HTML generation 🌈 If a .d source file starts with the string "Ddoc", then it gets treated as general purpose documentation instead of as a D source file. Not me, treating my docs like code 🙈

🔥 Runtime Options

These options change how programs compiled with gdc behave at runtime, so they're lowkey important 👑

  • -fall-instantiations — Generates code for all template instantiations. By default, the template emission strategy doesn't 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 💅
  • -fno-assert — Turns off code generation for "assert" contracts 🙅‍♀️
  • -fno-bounds-check — Turns off array bounds checking for all functions. This can improve performance for code that uses arrays a lot. Heads up, though: if the code actually does violate array bounds constraints, you can get unpredictable behavior. It's only safe to use this if you're sure your code never throws a "RangeError" 💀
  • -fbounds-check=value — An alternative to -fbounds-check that gives you more control over where bounds checking is turned on or off. These 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 — Doesn't recognize built-in functions unless they start 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 — Turns on compilation of conditional "debug" code into the program. The -fdebug option by itself sets the debug level to 1. -fdebug= enables "debug" code identified by any of these values:
    • level — Sets the debug level to level, so any "debug" code <= level gets compiled in
    • ident — Turns on compilation of any "debug" code identified by ident
  • -fno-druntime — Implements https://dlang.org/spec/betterc.html. It assumes compilation is targeting an environment without a D runtime library, which is giving bare-metal vibes 🌸 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. This might let you link to programs that aren't written in D ✨ The functions that won't 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 release mode, which means no runtime checks for contracts and asserts get emitted. Array bounds checking isn't done for @system and @trusted functions, and assertion failures are undefined behavior. > Undefined behavior, bestie. Be careful with this one 😭

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 language features needing this info will throw an error 💔
  • -fno-switch-errors — Controls what code gets generated when no case is matched in a "final switch" statement. The default runtime behavior is to throw a "SwitchError". Turning off -fswitch-errors means that the program's execution gets immediately halted instead 🛑
  • -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 these values:
    • level — Sets the version level to level, so any "version" code >= level gets compiled in
    • ident — Turns on compilation of "version" code identified by ident
  • -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 the target doesn't support weak symbols. Disabling this means common symbols get put in COMDAT or become private instead 🌈

These options tell the compiler which directories to search for files, libraries, and other parts of the compiler itself 🧭

  • -Idir — Specifies a directory to use when searching for imported modules at compile time. You can use multiple -I options, and the paths get searched in the same order they were given 📂
  • -Jdir (the -J switch with its dir argument) — Specifies a directory to use when searching for files in string imports at compile time. This switch is required if you want to use import(file) expressions. You can use multiple -J options, and the paths get searched in the same order 🎀
  • -Ldir — When linking, specifies a library search directory, just like with gcc 📚
  • -Bdir — Specifies where to find the executables, libraries, source files, and data files of the compiler itself, just like with gcc 🛠️
  • -fmodule-file=module=spec — Manipulates file paths of imported modules. If an imported module matches all or the leftmost part of module, the file path in spec gets used as the location to search for D sources. This is useful when your source file paths and names don't match the package and module hierarchy 🦋 Check out these examples:
gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar

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

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 — Uses dir as a subdirectory of the gcc directory that holds target-specific D sources and interfaces 🌷
  • -iprefix prefix — Specifies prefix as the prefix for the gcc directory that holds target-specific D sources and interfaces. If the prefix represents a directory, make sure you include the final '/' 💜
  • -nostdinc — Doesn't search the standard system directories for D source and interface files. Only the directories specified with -I options (plus the directory of the current file, if appropriate) get searched 🙅‍♀️
  • -MD — okay this one is basically -M -MF file in a trench coat 🧥. The driver works out the file name by stripping any directory components and the suffix off the input file, then slapping a .deps suffix on the end 💅
  • -MMD — like -MD, but it doesn't mention imported modules from the D standard library package directories 🦋
  • -X — dumps info describing the contents of every source file being compiled into a JSON file. The driver picks the name by removing directory components and the suffix from the input file, then adding a .json suffix 🧾
  • -Xf file — same energy as -X, but all the JSON goes into the file you name 📁
  • -fdoc — generates "Ddoc" documentation and writes it to a file. The compiler builds the name by removing directory components and suffix from the input file, then adding .html 📝
  • -fdoc-dir=dir — same as -fdoc, but the docs go into directory dir. Pair it with -fdoc-file=file if you want to set the output file and directory path separately 🗂️
  • -fdoc-file=file — same as -fdoc, but the docs go into file. Pair it with -fdoc-dir=dir to set the file and directory independently 🌸
  • -fdoc-inc=file — tells it to read file as a Ddoc macro file. You can stack multiple -fdoc-inc options, and the files get read and processed in the order you gave them 🧩

⚠️ Warnings

Warnings are diagnostic messages about constructions that aren't straight-up erroneous, but are risky or hint that there's probably a bug in the program. Unless -Werror is specified, they won't stop your program from compiling 🫶

  • -Wall — turns on all warning messages. Warnings aren't a defined part of the D language, and every construct that could trigger one is still valid code 🌈
  • -Walloca — warns on all uses of alloca in the source 🙈
  • -Walloca-larger-than=n — warns on unbounded uses of alloca, plus bounded uses whose bound can be larger than n bytes. -Wno-alloca-larger-than turns off the -Walloca-larger-than warning and is equivalent to -Walloca-larger-than=SIZE_MAX or larger 💜
  • -Wcast-result — warns about casts that will produce a null or zero result. Right now this is only checked for casting between an imaginary and non-imaginary data type, or between a D and C++ class ✨
  • -Wno-deprecated — don't warn about deprecated features and symbols with "deprecated" attributes 🍓
  • -Werror — turns every warning into an error. Harsh, but iconic 🔥
  • -Wspeculative — lists all error messages from speculative compiles, like __traits(compiles, ...). It doesn't report these as warnings, so they never become errors, even when -Werror is also used 🧚
  • -Wtemplates — warns whenever a template instantiation is encountered. Some coding rules ban templates, and this is how you enforce that rule 👑
  • -Wunknown-pragmas — warns when a pragma() shows up that gdc doesn't understand. This is different from -fignore-unknown-pragmas, where a pragma that's part of the D language but not implemented by the compiler won't get reported 🎀
  • -fignore-unknown-pragmas — turns off errors for unsupported pragmas 🦋
  • -fmax-errors=n — caps the number of error messages at n, and then gdc bails out instead of trying to keep going through the source code. If n is 0 (the default), there's no limit on how many error messages get produced 💀
  • -fsyntax-only — checks the code for syntax errors but doesn't actually compile it. You can combine it with -fdoc or -H to generate files for each module on the command line, but no other output file 🌸
  • -ftransition=id — reports extra info about D language changes identified by id. These values are supported:
    • all — list info on all language changes 🌟
    • checkimports — give deprecation messages about -ftransition=import anomalies 🙃
    • complex — list all usages of complex or imaginary types 🧮
    • dip1000 — implements <https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md> (Scoped pointers) 🔒
    • dip25 — implements <https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md> (Sealed references) 🫧
    • field — list all non-mutable fields that occupy an object instance 🧊
    • import — tells the compiler to go back to the old lookup behavior for resolving unqualified symbol names, which happened in a single pass and ignored any protection attributes. The default lookup strategy uses two passes: the first ignores imported declarations, and the second only looks at imports. The protection ("private", "package", "protected") of symbols is also enforced to sort out conflicts between private and public symbols 🕰️
    • nogc — list all hidden GC allocations 🗑️
    • tls — list all variables going into thread local storage 🧵

Options for Linking

These options only matter when the compiler links object files into an executable output file. If the compiler isn't doing a link step, they're meaningless 🔗

  • -defaultlib=libname — specifies the library to use instead of libphobos when linking. Options that set the linkage of libphobos, like -static-libphobos or -shared-libphobos, get ignored 💖
  • -debuglib=libname — specifies the debug library to use instead of libphobos when linking. This does nothing unless the -g option was also given on the command line. Linkage options like -static-libphobos or -shared-libphobos are ignored 🐞
  • -nophoboslib — don't use the Phobos or D runtime library when linking. Linkage options like -static-libphobos or -shared-libphobos are ignored. The standard system libraries get used as normal, unless -nostdlib or -nodefaultlibs is used 🚫
  • -shared-libphobos — on systems that provide libgphobos and libgdruntime as both a shared and a static library, this forces the shared version. If no shared version was built when the compiler was configured, it does nothing 🌊
  • -static-libphobos — on systems that provide libgphobos and libgdruntime as both a shared and a static library, this forces the static version. If no static version was built when the compiler was configured, it does nothing 🪨

Developer Options

This section covers command-line options that are mainly for developers or language tooling 🛠️

  • -fdump-d-original — outputs the internal front-end AST after the "semantic3" stage. This is only useful for debugging the GNU D compiler itself 🕵️
  • -v — dumps info about the compiler's language processing stages while your source program is being compiled. That includes listing all modules processed through the "parse", "semantic", "semantic2", and "semantic3" stages, all "import" modules and their file paths, and all "function" bodies being compiled 📣

🌟 SEE ALSO

gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entries for gdc and gcc 📚

Copyright (c) 2006-2020 Free Software Foundation, Inc. 🌈

Okay, so you're allowed to copy, distribute, and/or modify this document under the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation. There are no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is in the man page gfdl(7) 🫶

That's the whole page, bestie 💜 You now have the gcc-10 GDC(1) page from 2023-07-07 in your brain forever ✨🎀

📦 where this page comes from