GDC(1)

📦
version 9.5.0 · 3 versions
, in ubuntu jammy

💖 GDC(1) — GNU manual, part 1 of 2 💖

✨ NAME ✨

okay so gdc is a GCC-based compiler for the D language 🦋 that's the whole name, no cap.

✨ SYNOPSIS ✨

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

Bestie, this is just the highlight reel 🎬 Only the most useful options are up here, and the rest are down below.

✨ DESCRIPTION ✨

The gdc command is the GNU compiler for the D language, and it's giving gcc energy because it supports a lot of the same options as gcc. This manual only covers the options that are specific to gdc, so we're skipping the gcc ones 💅

✨ OPTIONS ✨

✨ Input and Output files ✨

For any 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.
  • file.dd — Ddoc source files.
  • file.di — D interface files.

You can pass more than one input file, and each one gets compiled separately during the process. But if you use -o file, all the input files get compiled together into one output file named file. That works even with -S or -c, so no skipping the rules 🫶

A D interface file only has what an import of the module actually needs, not the whole implementation of that module. gdc can make them from a D source file if you use the -H option. When the compiler resolves an import declaration, it looks for matching .di files first, then for .d files.

A Ddoc source file contains code in the D macro processor language. It's mainly for making user docs out of embedded comments, with a slight vibe toward HTML generation. If a .d source file starts with the string Ddoc, it's treated as general purpose documentation instead of a D source file 📝

✨ Runtime Options ✨

These options affect how programs compiled with gdc behave at runtime 🌸

  • -fall-instantiations — Generates code for all template instantiations. The default strategy skips code for declarations that were 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 improve performance for code that uses arrays a ton.
🚨 Heads up: if the code in question actually violates array bounds constraints, this can lead to unpredictable behavior. It's only safe to use if you're sure your code never throws a RangeError.
  • -fbounds-check=value — A more flexible alternative to -fbounds-check that lets you pick where bounds checking gets 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 begin with the prefix __builtin_. By default, the compiler recognizes when a function in the core.stdc package is a built-in function.
  • -fdebug, -fdebug=value — Turns on compiling of conditional debug code into the 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 into the program.
    • ident — Turns on compiling of any debug code identified by ident.
  • -fno-druntime — Implements https://dlang.org/spec/betterc.html. It assumes 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. 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. Array bounds checking isn't done for @system and @trusted functions.
💀 Heads up: in this mode, 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 language features requiring access to this information 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 run-time behavior is to throw a SwitchError. Turning off -fswitch-errors means that the execution of the program is immediately halted instead.
  • -funittest — Turns on compiling of unittest code and turns on the version(unittest) identifier. This implies -fassert.
  • -fversion=value — Turns on compiling 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 into the program.
    • ident — Turns on compiling 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 that common symbols are instead put in COMDAT or become private.

These options specify which directories to search for files, libraries, and other parts of the compiler 🗂️

  • -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.
  • -Jdir — Specifies 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. 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 is used as the location to search for D sources. This comes in clutch 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 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 — Uses dir as a subdirectory of the gcc directory containing target-specific D sources and interfaces.
  • -iprefix prefix — Specifies 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 — 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 🎀 The driver works out the file by stripping off any directory components and the suffix from the input file, then tacking on a .deps suffix. 💅
  • -MMD — Like -MD, but it doesn't mention imported modules from the D standard library package directories 🌸
  • -X — Dumps info about the contents of all the source files being compiled, in JSON format, into a file 🧚 The driver picks the file name by stripping directory components and the suffix from the input file, then adding a .json suffix. 🦋
  • -Xf file — Same vibe as -X, except all the JSON goes into the file you specify 💜
  • -fdoc — Generates "Ddoc" documentation and writes it to a file 📖 The compiler figures out the file name by stripping directory components and the 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 this with -fdoc-file=file to set the output file and the 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 path independently ✨
  • -fdoc-inc=file — Tells the compiler 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 ⚠️

Warnings are diagnostic messages that flag constructions which aren't inherently erroneous, but are risky or suggest there's probably a bug in the program 👀 Unless you use -Werror, 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 might trigger a warning here 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 of alloca whose bound could be larger than n bytes. -Wno-alloca-larger-than turns off -Walloca-larger-than 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 only happens when casting between an imaginary and a non-imaginary data type, or between a D and C++ class 🧊
  • -Wno-deprecated — Stops the warnings about using deprecated features and symbols that have "deprecated" attributes 😌
  • -Werror — Turns all warnings into errors. No cap, it's a whole vibe check 🚫
  • -Wspeculative — Lists all the error messages from speculative compiles, like __traits(compiles, ...). This option doesn't report messages 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 can help 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 isn't implemented by the compiler won't get reported 🎀
  • -fignore-unknown-pragmas — Turns off errors for unsupported pragmas 🌸
  • -fmax-errors=n — Caps the maximum number of error messages at n. When you hit that number, gdc bails out instead of trying to keep processing 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 won't produce any other output file 📄
  • -ftransition=id — Reports extra info about D language changes identified by id. These values are supported:
    • 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 <http://wiki.dlang.org/DIP1000> (experimental) 🧪
    • dip25 — Implements <http://wiki.dlang.org/DIP25> (experimental) 🧪
    • field — Lists 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. That old way 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, 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 come into play when the compiler links object files into an executable output file. They're meaningless if the compiler isn't doing a link step.

Heads up bestie: if there's no link step, these options do absolutely nothing 💀
  • -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 — Specifies the debug library to use instead of libphobos when linking. This option does nothing unless the -g option was also given on the command line. Options that set the linkage of libphobos, like -static-libphobos or -shared-libphobos, get ignored 🐛
  • -nophoboslib — Doesn'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 get 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 use of the shared version. If no shared version was built when the compiler was configured, this option does nothing 🌊
  • -static-libphobos — On systems that provide libgphobos and libgdruntime as both a shared and a static library, this forces the use of the static version. If no static version was built when the compiler was configured, this option does nothing 🧱

🛠️ Developer Options 🛠️

This section covers command-line options that are mainly of interest to 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 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 📚🦋

Copyright (c) 2006-2019 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, bestie! 🎀 This page was written for gcc 9 and dated May 27, 2022. Now go read some D code and be iconic about it ✨🫶💅

📦 where this page comes from