GDC(1)

📦
version 12-20220222 · 7 versions
, in ubuntu jammy

🎀 GDC(1) 🎀

okay bestie, this one's from the GNU manual 💖 so grab your snacks, we're about to go through gdc together 🫶

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

only the most useful options are listed up there 👀 the rest are down below, so don't panic 🫶

💖 DESCRIPTION 💖

the gdc command is the GNU compiler for the D language 🔥 it supports a bunch of the same options as gcc, so if you already know gcc you're literally halfway there ✨ this manual only covers the options that are specific to gdc 🦋

👑 OPTIONS 👑

📁 Input and Output files

the file name suffix on each input file decides what kind of compilation happens 🌈 these are the kinds of input file names that work:

  • file.d — D source files 💜
  • file.dd — Ddoc source files 🌸
  • file.di — D interface files 🧚

you can give gdc more than one input file on the command line 💅 each one gets compiled separately. but if you use -o file, then all the input files get compiled together into one single output file called file. and this works even with -S or -c, so no judgment 🙈

a D interface file only holds what an import of the module actually needs, not the whole implementation of that module ✨ gdc can make these 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, and only then goes looking for .d files 👀

a Ddoc source file has code written in the D macro processor language 💖 it's mainly made for turning embedded comments into user documentation, leaning a little toward HTML generation 🌷 and if a .d source file starts with the string "Ddoc", it gets treated as general purpose documentation instead of as D source code 📄

🏃 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 to skip 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 🏎️ this can speed things up for code that uses arrays a lot, BUT:
⚠️ bestie, listen: if the code actually does break array bounds, this can cause unpredictable behavior 💀 it's only safe to use if you're totally sure your code never throws a RangeError.
  • -fbounds-check=value — a more flexible version of -fbounds-check, so you get more control over where bounds checking is 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 begin with the prefix __builtin_ 🙅‍♀️ by default, the compiler does recognize when a function in the core.stdc package is a built-in function ✨
  • -fcheckaction=value — controls what code gets generated when an assertion, bounds check, or final switch fails 💥 the supported values are:
    • context — throws an AssertError with extra context information 🔍
    • halt — halts the program execution 🛑
    • throw — throws an AssertError (this is the default) 🎀
  • -fdebug, -fdebug=value — turns on compilation 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 in 📊
    • ident — turns on compilation of any debug code identified by ident 🏷️
  • -fno-druntime — implements <https://dlang.org/spec/betterc.html> 🧼 hmm, the link is https://dlang.org/spec/betterc.html, and it assumes you're targeting an environment without a D runtime library 🌙 this is the same as compiling with these options:
gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
  • -fextern-std=standard — sets the C++ name mangling compatibility to the version you pick with standard 🧚 the supported values are:
    • c++98, c++03 — set __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 one's the default, so it's the main character 👑
    • c++20 — sets __traits(getTargetInfo, "cppStd") to 202002 🚀
  • -fno-invariants — turns off code generation for invariant class contracts 🫠
  • -fmain — generates a default main() function when compiling 🎀 this is super handy when you're unittesting a library, since you can run the unittests without manually writing an entry-point function 🙌 it does nothing if main is already defined in your code 🫶
  • -fno-moduleinfo — turns off generation of ModuleInfo and the related functions that would become unreferenced without it 🧹 this might let you link to programs that aren't 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 🔮 the supported values are:
    • all — turns on all upcoming D language features 🤯
    • dip1000 — implements https://wiki.dlang.org/DIP1000 (Scoped pointers) 📌
    • dip1008 — implements https://wiki.dlang.org/DIP1008 (Allow exceptions in @nogc code) 🧁
    • dip1021 — implements https://wiki.dlang.org/DIP1021 (Mutable function arguments) 🔁
    • dip25 — implements https://wiki.dlang.org/DIP25 (Sealed references) 🔒
    • dtorfields — turns on generation for destructing fields of partially constructed objects 🧩
    • fieldwise — turns on generation of struct equality so it uses field-wise comparisons 🪞
    • fixaliasthis — implements new lookup rules that check the current scope for alias this before searching upper scopes 🔍
    • in — implements in parameters to mean scope const [ref], and accepts rvalues 🫧
    • inclusiveincontracts — implements in contracts of overridden methods so they're a superset of the parent contract 📚
    • 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 to lambdas ➡️
  • -frelease — turns on compiling in release mode 🚀 that means no runtime checks for contracts and asserts get emitted 🏃‍♀️ array bounds checking is skipped for @system and @trusted functions, and assertion failures are undefined behavior 💀
⚠️ undefined behavior alert: in release mode, assertion failures are undefined behavior, so be careful, bestie 🫣

this is the same as compiling with these 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 supported values are:
    • all — turns off all revertable D language features 🧹
    • dip25 — reverts https://wiki.dlang.org/DIP25 (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 language features needing this info will throw an error, so heads up 💀
  • -fno-switch-errors — controls what code gets generated when no case is matched in a final switch statement 🔀 by default, the run time behavior is to throw a SwitchError 💥 turning off -fswitch-errors means the program immediately halts 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-templates — turns off emission of declarations that can be defined in multiple objects as weak symbols 🫧 by default, all public symbols get emitted as weak, unless the target doesn't support weak symbols 🌙 if you disable this, common symbols get put in COMDAT or become private instead 🔐

these options tell the compiler where to look for files, libraries, and other parts of the compiler itself 🧭

  • -Idir — specifies a directory to search 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 search 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 they're searched in the same order too 🔁
  • -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 — okay so this one is a whole vibe 💅 It rewrites the file paths of imported modules. If an imported module matches all of module or its leftmost part, the path in spec becomes the place where D sources get searched for. This comes in clutch when your file paths and names don't line up with your 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 every import path for the source file foo.d when importing A.B, and to look in the directory bar/ when importing C. Here's how that plays out in 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 — pick dir as a subdirectory of the gcc directory that holds target-specific D sources and interfaces 🌸
  • -iprefix prefix — set prefix as the prefix for that same gcc directory with the target-specific D sources and interfaces 🧚 If the prefix is a directory, remember to add the final '/' 🫶
  • -nostdinc — skip the standard system directories when hunting for D source and interface files 🙅‍♀️ Only the directories you passed with -I options get searched (plus the directory of the current file, if that applies).

✨ Code Generation ✨

Okay so gdc has a bunch of code generation options all its own, on top of the many gcc ones that control code generation 💖

  • -H — generates D interface files for every module being compiled 🦋 The compiler names the output file after the input file, strips any directory components and the suffix, then slaps on the .di suffix.
  • -Hd dir — same as -H, but the interface files land in the directory dir 📁 You can pair this with -Hf file to set the output file and the directory path separately.
  • -Hf file — same as -H, but the interface files get written to file 🎀 You can pair this with -Hd dir to set the output file and the directory path independently.
  • -M — outputs the module dependencies of all the source files being compiled, formatted so make can read them 🍓 The compiler spits out one make rule with the object file name for that source file, a colon, and the names of all the imported files.
  • -MM — basically -M, but it doesn't mention imported modules from the D standard library package directories 🙈
  • -MF file — when used with -M or -MM, it picks the file the dependencies get written to 📝 When used with the driver options -MD or -MMD, -MF overrides the default dependency output file.
  • -MG — exists purely for compatibility with gcc, and the compiler just ignores it 🤷‍♀️
  • -MP — outputs a phony target for each dependency other than the modules being compiled, so each one depends on nothing 👻
  • -MT target — changes the target of the rule made by dependency generation to be exactly the string you give it 🎯 Want multiple targets? Either put them all in one argument to -MT, or use multiple -MT options.
  • -MQ target — same as -MT, except it quotes any characters that are special to make 💅
  • -MD — this one is equivalent to -M -MF file ✨ The driver figures out file by stripping any directory components and the suffix from the input file, then adding a .deps suffix.
  • -MMD — like -MD, but it doesn't mention imported modules from the D standard library package directories 🫧
  • -X — outputs info describing the contents of all source files being compiled, in JSON format, to a file 🧾 The driver picks file by stripping any directory components and the suffix from the input file, then adding a .json suffix.
  • -Xf file — same as -X, but all the JSON contents get written to the file you specify 💜
  • -fdoc — generates "Ddoc" documentation and writes it to a file 📚 The compiler picks file by stripping any 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 directory path separately.
  • -fdoc-file=file — same as -fdoc, but the docs get written to file 🌷 You can pair this with -fdoc-dir=dir to set the output file and directory path 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 order you gave them.
  • -fdump-c++-spec=file — for D source files, generates matching C++ declarations in file 🌟
  • -fdump-c++-spec-verbose — works together with -fdump-c++-spec= from above 💭 It adds comments for the ignored declarations in the generated C++ header.
  • -fsave-mixins=file — generates the code expanded from D mixin statements and writes the processed sources to file 🔍 This is super useful for debugging compilation errors, and it gives debuggers the source they need to show when you ask for it.

✨ Warnings ✨

Warnings are diagnostic messages that flag constructions that aren't technically wrong, but are risky or hint that there's probably a bug in your program 👀 Unless -Werror is specified, they won't stop your program from compiling, so no panic 🫶

  • -Wall — turns on all warning messages 🚨 Warnings aren't a defined part of the D language, and every construct that might trigger a warning 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 could be bigger than n bytes 📏 -Wno-alloca-larger-than turns off the -Walloca-larger-than warning, and it's equivalent to -Walloca-larger-than=SIZE_MAX or larger.
  • -Wcast-result — warns about casts that will end up producing a null or zero result 🙃 Right now this only happens when casting between an imaginary and a non-imaginary data type, or when casting between a D class and a C++ class.
  • -Wno-deprecated — stops the warnings about deprecated features and symbols that have "deprecated" attributes 🙅‍♀️
  • -Werror — turns every warning into an error 🚫 Major main character energy, no cap.
  • -Wspeculative — lists all error messages from speculative compiles, like the ones from __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 helps you enforce that rule.
  • -Wunknown-pragmas — warns when a pragma() shows up that gdc doesn't understand 🤔 This is different from -fignore-unknown-pragmas: a pragma that's part of the D language but isn't implemented by the compiler won't get reported with this one.
  • -Wno-varargs — doesn't warn about questionable usage of the macros used to handle variable arguments, like va_start 🫠
  • -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 with 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 without actually compiling 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 the D language changes identified by id 📣 These values are supported:
    • all — lists info on all D language transitions 🌍
    • complex — lists all usages of complex or imaginary types 🌀
    • field — lists all non-mutable fields that take up space in an object instance 🧊
    • in — lists all usages of in on a parameter 🫳
    • nogc — lists all hidden GC allocations 🗑️
    • templates — lists statistics on template instantiations 📊
    • tls — lists all variables going into thread local storage 🧵
    • vmarkdown — lists instances of Markdown replacements in Ddoc 📝

✨ 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, so don't stress about them then 💀

  • -defaultlib=libname — picks 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 — picks the debug library to use instead of libphobos when linking 🐞 This 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 here too.
  • -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 are still 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 option 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 option 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, so it's a dev-only flex 🤓
  • -v — dumps info about the compiler's language processing stages while your source program is being compiled 📜 This includes listing all modules that go 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 🌸

okay bestie, the legal bit at the end 🫶 Copyright (c) 2006-2022 Free Software Foundation, Inc. 💅 That's the FSF claiming it, full stop.

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 📜 (so you're allowed to share and remix it, as long as you follow that license 🦋). 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) ✨, so go check it out if you want the nitty-gritty 🧚.

gcc-12 · 2022-02-22 · GDC(1) 🍓 that's the source version, the date, and the page name all tucked into the footer, and honestly that's giving very organized energy 💜 Stay iconic and keep reading the manuals, periodt! 💖🌈

📦 where this page comes from