GDC(1)

📦
version 10.5.0 · 2 versions
, in ubuntu noble

🎀 GDC(1): the GNU D compiler manual (part 1 of 2) 🎀

✨ NAME ✨

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

okay so the synopsis only flashes the most useful options 👀 the rest are down below, bestie 💖

✨ DESCRIPTION ✨

The gdc command is the GNU compiler for the D language, and it supports a lot of the same options as gcc 🔥 This page only covers the options that are specific to gdc, so that's where the focus is 🎀

✨ OPTIONS ✨

📂 Input and Output files 📂

okay so the file name suffix decides what kind of compilation happens 📂 these are the input file name kinds that work:

  • file.d — D source files 💖
  • 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 in the process 🔄 but if you use -o file, all the input files get compiled together into one single output file named file 🫶 that works even with -S or -c, periodt 💅

a D interface file only holds what an import of the module actually needs, not the whole implementation of that module 🦋 you can make these from a D source file with the -H option. when the compiler resolves an import declaration, it looks for matching .di files first, and then for .d files 👀

a Ddoc source file holds code written in the D macro processor language 🧚 it's mainly made for turning embedded comments into user documentation, with a slight lean toward HTML generation 🌸 and if a .d source file starts with the string Ddoc, it gets treated as general purpose documentation instead of D source 📖

🌈 Runtime Options 🌈

these options change how programs compiled with gdc behave at runtime ⚡

  • -fall-instantiations — generates code for all template instantiations 🧚 the default emission strategy is different though: it skips 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, which can give your performance a boost for code that uses arrays a lot 🏎️ it's safe to use this only if you're sure your code never throws a RangeError 🫶
💀 Heads up: if the code in question actually does violate array bounds constraints, this can result in unpredictable behavior.
  • -fbounds-check=value — an alternative to -fbounds-check that gives you more control over where bounds checking gets turned on or off 🎛️ the supported values are:
    • 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 does 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 your program 🐛 the -fdebug option by itself sets the debug level to 1, while -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 the spec at https://dlang.org/spec/betterc.html 📖 it assumes you're compiling for an environment with no D runtime library 🏕️ this is basically the same as compiling with these 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 🔗 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 🚫
  • -frelease — turns on release mode, which means no runtime checks for contracts and asserts 🚀 array bounds checking isn't done for @system and @trusted functions, and assertion failures are undefined behavior. this is basically the same as compiling with these options 👇
💀 Heads up: under -frelease, assertion failures are undefined behavior.
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 requiring that info will result in 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 the program's execution is 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 lacks support for weak symbols. disabling this option means common symbols are put in COMDAT instead, or become private 🔒

these options tell gdc where to look for files, libraries, and other parts of the compiler 🗂️

  • -Idir — specify a directory to search when looking for imported modules at compile time 📦 you can use multiple -I options, and the paths are searched in the same order.
  • -Jdir — specify a directory to search when looking 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 are searched in the same order.
  • -Ldir — when linking, specify a library search directory, as with gcc 🔗
  • -Bdir — specifies where to find the executables, libraries, source files, and data files of the compiler itself, as with gcc 🛠️
  • -fmodule-file=module=spec — a little spicy 🌶️ but super useful. it manipulates file paths of imported modules, so 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. you'd use this when the 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 annotated 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 contains target-specific D sources and interfaces 🎯
  • -iprefix prefix — specifies prefix as the prefix for the gcc directory that contains target-specific D sources and interfaces 🧭 if the prefix represents a directory, you should include the final /.
  • -nostdinc — doesn't search the standard system directories for D source and interface files 🚫 only the directories specified with -I options (and the directory of the current file, if appropriate) get searched 🎀
  • -MD — okay so this one is basically -M -MF file in a cute little disguise 🧥 The driver figures out file by chopping off any directory bits and the suffix from the input file, then slapping a .deps suffix on the end. 🎀
  • -MMD — Same vibe as -MD, but it doesn't mention imported modules from the D standard library package directories 🙈
  • -X — Dumps info about the contents of every source file being compiled, in JSON format, into a file. The driver names that file by removing any directory components and suffix from the input file, then adding a .json suffix. Literally so organized 💜
  • -Xf file — Same energy as -X, except all the JSON goes into the specific file you pick ✨
  • -fdoc — Generates "Ddoc" documentation and writes it to a file. The compiler names the file by removing directory components and suffix from the input file, then adding a .html suffix 📄
  • -fdoc-dir=dir — Same as -fdoc, but the docs go into the directory dir. You can pair it with -fdoc-file=file to set the output file and directory path separately. Main character energy 👑
  • -fdoc-file=file — Same as -fdoc, but the docs go into file. Use it with -fdoc-dir=dir if you want to set the file and directory independently 🦋
  • -fdoc-inc=file — Tells it to read file as a Ddoc macro file. You can use multiple -fdoc-inc options, and the files get read and processed in the same order you list them 🌈

✨ Warnings ✨

Okay bestie, warnings are diagnostic messages about constructions that aren't straight-up wrong but are risky, or that hint there's probably a bug hiding in the program. Unless you add -Werror, they won't stop your program from compiling 🫶

  • -Wall — Turns on all warning messages. Warnings aren't an official part of the D language, and every construct that might 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, and on bounded uses whose bound can be larger than n bytes. -Wno-alloca-larger-than turns off the -Walloca-larger-than warning, and it's the same as -Walloca-larger-than=SIZE_MAX or larger 🌸
  • -Wcast-result — Warns about casts that will produce a null or zero result. Right now this only happens when 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 that have "deprecated" attributes 🙈
  • -Werror — Turns every warning into an error. Serious, no cap 🔥
  • -Wspeculative — Lists all error messages from speculative compiles, like __traits(compiles, ...). This option doesn't report the messages as warnings, so they never become errors, even when -Werror is also in use 🦋
  • -Wtemplates — Warns whenever a template instantiation is encountered. Some coding rules ban templates, and this can help you enforce that rule 💜
  • -Wunknown-pragmas — Warns when pragma() shows up and gdc doesn't understand it. This is different from -fignore-unknown-pragmas, because a pragma that's part of the D language but isn't implemented by the compiler won't get reported with this one 🎀
  • -fignore-unknown-pragmas — Turns off errors for unsupported pragmas ✨
  • -fmax-errors=n — Caps the number of error messages at n. Once it hits that number, 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 it doesn't produce any other output file 🌈
  • -ftransition=id — Reports extra info about D language changes identified by id. The supported values are:
    • all — Lists info on all language changes.
    • checkimports — Gives deprecation messages about -ftransition=import anomalies.
    • complex — Lists 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 — Lists all non-mutable fields that occupy an object instance.
    • import — Tells the compiler to go back to an old lookup behavior for resolving unqualified symbol names, where that lookup was done in a single pass and ignored any protection attributes. The default name lookup strategy uses two passes instead: the first ignores imported declarations, and the second only looks at imports. The protection ("private", "package", "protected") of symbols is also enforced, so conflicts between private and public symbols get resolved 🫣
    • nogc — Lists all hidden GC allocations 🙈
    • tls — Lists 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, so don't stress 🦋

  • -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 -g was also given on the command line. Options that set the linkage of libphobos, like -static-libphobos or -shared-libphobos, get ignored too 🌸
  • -nophoboslib — Don't use the Phobos or D runtime library when linking. Options that set the linkage of libphobos, like -static-libphobos or -shared-libphobos, get ignored. The standard system libraries are used normally, 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, this 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, this does nothing 🧚

✨ Developer Options ✨

This section is for the command-line options that mostly matter to developers or language tooling. Main developer hours 🤓💅

  • -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 the 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. Go read those when you want the full story, bestie 📚💖

Copyright (c) 2006-2020 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. There are 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) 🩷

That's a wrap on GDC(1), bestie 🎀 This one is from the gcc-10 source, dated 2023-07-07, and you absolutely slayed reading the whole thing 💅✨

📦 where this page comes from