GDC(1)

✨ GDC(1) ✨

okay bestie, this manual page is from the GNU crew 🌈 and it's all about gdc. Let's get into it 💅

✨ 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 🧚 the rest are down below, so keep scrolling!

✨ DESCRIPTION ✨

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're not going to get bored with repeats 🦋.

✨ OPTIONS ✨

🌸 Input and Output files

Okay so, for any input file, the file name suffix decides what kind of compilation happens 👑. These are the input file names that work:

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

You can throw more than one input file onto 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 into one single output file, named file. This is allowed even when you're using -S or -c ✨.

A D interface file only has 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 then it checks 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, with a slight lean toward HTML generation 📝. If a .d source file starts with the string Ddoc, it's treated as general purpose documentation instead of as a D source file. Not me, but iykyk 🙈.

🌈 Runtime Options

These options change how programs compiled with gdc behave at runtime ⭐.

• -fall-instantiations — Generates code for all template instantiations 🦋. By default, the compiler 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 boost performance for code that uses arrays a lot 🚀. Heads up 💀: this can lead to unpredictable behavior if the code in question actually does violate array bounds constraints. It's only safe if you're totally 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 work:
  • 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 will 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 😭. These values are supported:
  • 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 🔍. -fdebug by itself sets the debug level to 1, while -fdebug= enables debug code identified by any of these values:
  • ident — turns on compilation 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

• -fextern-std=standard — Sets the C++ name mangling compatibility to the version identified by standard 👑. These values are supported:
  • 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.
• -Ldir — okay so when you're linking, this lets you point at a library search directory, same as gcc 🦋
• -Bdir — tells the compiler where to find its own stuff: executables, libraries, source files, and data files. Also same as gcc 🧚
• -fmodule-file=module=spec — lowkey a lifesaver 💅 This one messes with the file paths of imported modules. If an imported module matches all of module or its leftmost part, the file path in spec becomes the place it searches for D sources. You'd use this when your source file paths and names don't match your package and module hierarchy. Check these out:

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

So this tells the compiler to search all import paths for foo.d when importing A.B, and to check the bar/ directory when importing C. Here's how it 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 — use 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 of target-specific D sources and interfaces. If the prefix is a directory, make sure you include the final / 🫶
• -nostdinc — don't search the standard system directories for D source and interface files 🙅 Only the directories given with -I options get searched (plus the directory of the current file, if that applies).

🎀 Code Generation 🎀

Besides all the usual gcc options for code generation, gdc has a few of its own, bestie 💖

• -H — generates D interface files for all modules being compiled. The compiler works out the output file from the input file name, strips any directory components and suffix, and slaps on the .di suffix 📝
• -Hd dir — same as -H, but writes the interface files to directory dir. You can pair it with -Hf file to set the output file and directory path independently ✨
• -Hf file — same as -H, but writes the interface files to file. You can pair it with -Hd dir to set the output file and directory path independently 🦋
• -M — outputs the module dependencies of all source files being compiled, in a format that works with make 🔥 It 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 🙈
• -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's just for compatibility with gcc, so the compiler ignores it 🤷
• -MP — outputs a phony target for each dependency other than the modules being compiled, causing each one to depend on nothing 👻
• -MT target — changes the target of the rule emitted by dependency generation to be exactly the string you specify. If you 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 that are special to make 💜
• -MD — this is equivalent to -M -MF file. The driver works out the file by removing any directory components and suffix from the input file, then adding a .deps suffix 📦
• -MMD — like -MD, but 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 figures out the file by removing directory components and suffix from the input file, then adding a .json suffix 🧾
• -Xf file — same as -X, but writes all the JSON contents to the file you specify 💅
• -fdoc — generates "Ddoc" documentation and writes it to a file. The compiler determines the file by removing directory components and suffix from the input file, then adding a .html suffix 📚
• -fdoc-dir=dir — same as -fdoc, but writes the documentation to directory dir. You can use it with -fdoc-file=file to set the output file and directory path independently 🗂️
• -fdoc-file=file — same as -fdoc, but writes the documentation to file. You can use it with -fdoc-dir=dir to set the output file and directory path independently 🗃️
• -fdoc-inc=file — specifies file as a Ddoc macro file to be read. You can use multiple -fdoc-inc options, and the files are read and processed in the same order 📖
• -fdump-c++-spec=file — for D source files, generates the corresponding C++ declarations in file 🌟
• -fdump-c++-spec-verbose — used alongside -fdump-c++-spec= above, this adds comments for ignored declarations in the generated C++ header 💬
• -fsave-mixins=file — generates code expanded from D "mixin" statements and writes the processed sources to file. This is super useful for debugging compile errors, and gives debuggers source to show when requested 🐛

---

🚨 Warnings 🚨

Warnings are diagnostic messages that flag constructions which aren't inherently erroneous, but are risky or suggest there's likely 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 may 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 disables -Walloca-larger-than and is equivalent to -Walloca-larger-than=SIZE_MAX or larger 📏
• -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. Right now this is only done for casting between an imaginary and non-imaginary data type, or casting between a D and C++ class 🎭
• -Wno-deprecated — don't warn about usage of deprecated features and symbols with "deprecated" attributes 🙅
• -Werror — turns all warnings into errors 🚫
• -Wextra — enables some extra warning flags that are not enabled by -Wall. It adds -Waddress -Wcast-result -Wmismatched-special-enum -Wunknown-pragmas ✨
• -Wmismatched-special-enum — warns when an enum the compiler recognizes as special is declared with a different size than the built-in type it represents 📐
• -Wspeculative — lists all error messages from speculative compiles, such as __traits(compiles, ...). This option doesn't report messages as warnings, so these messages never become errors when -Werror is also used 🔮
• -Wunknown-pragmas — warns when a pragma() is encountered that isn't understood by gdc. This differs from -fignore-unknown-pragmas, where a pragma that's part of the D language but not implemented by the compiler won't get reported 🤔
• -Wno-varargs — don't warn about questionable usage of the macros used to handle variable arguments, like va_start 🧩
• -fno-ignore-unknown-pragmas — doesn't recognize unsupported pragmas. Any pragma() encountered that isn't part of the D language will result in an error

⚠️ Deprecation alert: this option is now deprecated and will be removed in a future release.

• -fmax-errors=n — limits the maximum number of error messages to n, at which point gdc bails out rather than trying to keep processing the source code. If n is 0 (the default), there is no limit on the number of error messages produced 🛑
• -fsyntax-only — checks the code for syntax errors, but doesn't actually compile it. This can be used with -fdoc or -H to generate files for each module on the command line, but no other output file 📝
• -ftransition=id — reports additional information about D language changes identified by id. These values are supported:
  • 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 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 🥺

• -defaultlib=libname — specifies the library to use instead of libphobos when linking. Options specifying the linkage of libphobos, like -static-libphobos or -shared-libphobos, are ignored 🫧
• -debuglib=libname — specifies the debug library to use instead of libphobos when linking. This has no effect unless -g was also given on the command line. Options specifying the linkage of libphobos, like -static-libphobos or -shared-libphobos, are ignored 🐞
• -nophoboslib — don't use the Phobos or D runtime library when linking. Options specifying the linkage of libphobos, like -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 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 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 describes command-line options that are primarily of interest to developers or language tooling 💜

• -fdump-d-original 🔍 — okay bestie, this one dumps the internal front-end AST right after the "semantic3" stage. It's only useful for debugging the GNU D compiler itself 💀, so unless you're literally building the compiler, you can let this one sleep 😴.
• -v 🎀 — this is the chatty one! While your source program is being compiled, it spills the tea on the compiler's language processing stages. It lists every module that goes through the "parse", "semantic", "semantic2", and "semantic3" stages 🧚, every "import" module along with its file path 🗂️, and every "function" body being compiled ✨.

🦋 SEE ALSO 🦋

Go check these out, they're giving useful info 📚: gpl(7), gfdl(7), fsf-funding(7), gcc(1), and the Info entries for gdc and gcc.

🎀 COPYRIGHT 🎀

Copyright (c) 2006-2024 Free Software Foundation, Inc. 💜

Okay so the legal part is actually super chill 🫶. 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 included in the man page gfdl(7) 📜.

---

And that's the whole page, bestie! 💖 It came from gcc-14 and is dated 2024-04-12, so you officially know more about GDC than most people 👑🌈 slay forever 💅✨