GDC(1)

📦
version 11.5.0 · 2 versions
, in ubuntu noble

🎀 GDC(1) · the GNU manual 🎀

✨ NAME ✨

gdc is a GCC-based compiler for the D language. It's giving main character energy 💅

✨ SYNOPSIS ✨

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

Okay so this is only the most useful options 🫶 The rest are down in the OPTIONS section, so keep reading, 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 manual only covers the options that are specific to gdc, so you're not reading the same stuff twice.

✨ 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 during the compilation process. If you use the -o file option, though, all the input files get compiled together into a single output file, named file. This still works with -S or -c 🎀

A D interface file has only what an import of the module needs, not the whole implementation of that module. gdc 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 only then for .d files.

A Ddoc source file has code in the D macro processor language. It's mainly built for making user docs out of embedded comments, with a little extra love for HTML generation 📖 If a .d source file starts with the string "Ddoc", then it gets treated as general purpose documentation instead of as a D source file. Not a D source file, bestie 💀

🔥 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 generating 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. This can boost performance for code that uses arrays a lot 🔥 Heads up though, this can cause unpredictable behavior if the code actually does break array bounds constraints. It's only safe if you're sure your code never throws a "RangeError" 💀
  • -fbounds-check=value — An alternative to -fbounds-check that gives you more control over 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 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 your program. The -fdebug option by itself sets the debug level to 1, while -fdebug= turns on "debug" code that's identified by any of these values:
    • level — Sets the debug level to level, and any "debug" code <= level gets compiled into the program.
    • 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 you're compiling for an environment with no D runtime library, so no runtime library, no cap 🦋

This is 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" stuff and related functions that would become unreferenced without it. This might let you link to programs that weren'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 🙅‍♀️
  • -frelease — Turns on release mode, which means no runtime checks for contracts and asserts get emitted. Array bounds checking isn't done for @system and @trusted functions, and 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
  • -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 🚫
  • -fno-switch-errors — This option controls what code gets generated when no case matches in a "final switch" statement. The default runtime behavior is to throw a "SwitchError". Turning off -fswitch-errors means that 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, and any "version" code >= level gets compiled into the program.
    • 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. The default is to emit all public symbols as weak, unless the target doesn't support weak symbols. Disabling this means common symbols get put in COMDAT or become private instead 🌸

These options tell the compiler which directories to search for files, libraries, and other parts of the compiler 🧭

  • -Idir — Specifies a directory to search when looking 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 when looking for files in string imports at compile time. You need this switch 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 — This option messes with file paths of imported modules. If an imported module matches all or the leftmost part of module, then the file path in spec gets used as the place to search for D sources. This is handy 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 holds the target-specific D sources and interfaces 🧩
  • -iprefix prefix — Specifies prefix as the prefix for the gcc directory that holds the 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 you specified with -I options (and the directory of the current file, if that applies) get searched 🙅‍♀️
  • -MD — okay so this one is basically -M -MF file in a trench coat 🧚 The driver makes the file name by stripping any directory parts and the suffix off your input file, then tacking on a .deps suffix. 💅
  • -MMD — same vibe as -MD, but it skips mentioning imported modules that come from the D standard library package directories 🙈
  • -X — dumps info describing everything in all the source files being compiled, in JSON format, into a file 📦 The driver names it by removing directory components and suffix from the input file, then adding a .json suffix.
  • -Xf file — same as -X, but 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, 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 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 they were given.

✨ Warnings ✨

Warnings are diagnostic messages that flag constructions that aren't straight-up erroneous but are risky, or that 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 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 -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 it only checks casting between an imaginary and a non-imaginary data type, or casting between a D and C++ class.
  • -Wno-deprecated — no warnings about deprecated features and symbols with "deprecated" attributes 🙅‍♀️
  • -Werror — turns every warning into an error no cap, this one's strict 💀
  • -Wspeculative — lists all error messages from speculative compiles, like __traits(compiles, ...) 🔍 It doesn't report them 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, so this is a lowkey great way 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 — no warnings about questionable usage of the macros used for variable arguments, like va_start 🫠
  • -fignore-unknown-pragmas — turns off errors for unsupported pragmas 🌈
  • -fmax-errors=n — caps the maximum number of error messages at n, and then gdc bails out instead of trying to keep going 🛑 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 stress about them otherwise.

  • -defaultlib=libname — uses this library instead of libphobos when linking 📚 Options that set the linkage of libphobos, like -static-libphobos or -shared-libphobos, get ignored.
  • -debuglib=libname — uses this debug library instead of libphobos when linking 🐛 It 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 — no 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 got built when the compiler was configured, it 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 got built when the compiler was configured, it does nothing.

✨ Developer Options ✨

This section is all about 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.
  • -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-2021 Free Software Foundation, Inc.

Okay, legal stuff but make it cute 💖 You're allowed 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 the whole page, bestie! 🫶 It's the gcc-11 build, stamped 2024-07-19. Go be iconic with your D code 👑✨

📦 where this page comes from