GDC(1)

📦
version 11.5.0 · 5 versions
, in ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 GDC(1) · GNU 🎀

✨ NAME ✨

okay bestie, the name card says it all: 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 top, so scroll down for the rest 🙈

✨ DESCRIPTION ✨

gdc is the GNU compiler for D and it's giving GCC energy, so it takes 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 relearn everything ✨

✨ OPTIONS ✨

🦋 Input and Output files

For any input file, the file name suffix decides what kind of compilation happens. These are the input file name kinds 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 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 into one single output file named file. That's allowed even with -S or -c 🌸

A D interface file only holds what an import of the module actually needs, not the whole implementation of that module 🧚 You can make one from a D source file with the -H option. When the compiler resolves an import declaration, it looks for matching .di files first, then .d 👑

A Ddoc source file has code written in the D macro processor language. It's mainly for making user docs out of embedded comments, with a little HTML-generation vibe 🍓 If a .d source file starts with the string "Ddoc", it gets treated as general purpose documentation instead of D source code 🦋

🌈 Runtime Options

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

  • -fall-instantiations — Generates code for all template instantiations. By default, the template 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, which can give performance a real boost for code that leans on arrays 🔥
⚠️ Heads up bestie: if your code actually breaks array bounds, this can lead to unpredictable behavior. It's only safe to use if you're totally sure your code never throws a RangeError 💀
  • -fbounds-check=value — The more flexible cousin of -fbounds-check, letting you pick exactly 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 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 plain -fdebug option 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 BetterC spec at https://dlang.org/spec/betterc.html 💜 It assumes compilation targets an environment with no 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 ModuleInfo and the 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.
🚨 In this mode, assertion failures are undefined behavior. Not a vibe.

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 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 run-time behavior is to throw a SwitchError. Turning off -fswitch-errors means the execution of the program 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-templates — Turns off emission of declarations that can be defined in multiple objects as weak symbols 🌈 By default, all public symbols are emitted as weak, unless the target doesn't support weak symbols. With this disabled, common symbols are instead put in COMDAT or become private.
  • -MD — okay so this is basically -M -MF file, bestie! 🫶 The driver figures out the file name by stripping any directory parts and the suffix from the input file, then tacks on 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, into a file. The driver picks that file 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 exact file you name. ✨
  • -fdoc — generates "Ddoc" documentation and writes it to a file. The compiler names it by removing 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. 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 get written to file. Pair it with -fdoc-dir=dir to set the file and directory independently. 💜
  • -fdoc-inc=file — tells the compiler to read file as a Ddoc macro file. You can use multiple -fdoc-inc options, and they get read and processed in the order you gave them. 📖

⚠️ Warnings

Okay, warnings are diagnostic messages about constructions that aren't straight-up erroneous, but that are risky or suggest 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 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, and on bounded uses whose bound can 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 non-imaginary data type, or casting between a D and C++ class. ✨
  • -Wno-deprecated — stops the warnings about deprecated features and symbols with deprecated attributes. 🫠
  • -Werror — turns every warning into an error. Literally no mercy. 💀
  • -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.
Lowkey the big catch with -Wspeculative: those messages never turn into errors, even with -Werror on. 🙃
  • -Wtemplates — warns when a template instantiation is encountered. Some coding rules ban templates, so you can use this to 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. 🔍
  • -Wno-varargs — stops the warnings 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 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 use 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:

🔗 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 waste your time on them otherwise. 🥲

  • -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. Options that set the linkage of libphobos, like -static-libphobos or -shared-libphobos, get ignored. 🐞
  • -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 still 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 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 covers command-line options that are mainly of interest to developers or language tooling. Main character energy for the nerds 🤓💜

  • -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 unless you're doing that, it's not for you, babe. 🙅‍♀️
  • -v — dumps info about the compiler 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-2021 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, with 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 a wrap, bestie! 🎀 This page is giving gcc-11 energy, last dated 2024-07-19, and I'm obsessed. 💖✨

📦 where this page comes from