GDC(1)

📦
version 12.4.0 · 3 versions
, in ubuntu noble

🌸 NAME 🌸

gdc — a GCC-based compiler for the D language ✨ straight outta the GNU manual, page GDC(1), and bestie it's so much. 💖

✨ SYNOPSIS ✨

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

okay so real talk — only the most useful options are listed up here 👆, the rest are down below, keep scrolling, no skipping 💅

💫 DESCRIPTION 💫

The gdc command is the GNU compiler for the D language, and it supports many of the same options as gcc. This manual only documents the options specific to gdc — so like, the D-specific stuff, the gcc lore lives somewhere else, iykyk 🫶

🔥 OPTIONS 🔥

🎀 Input and Output files 🎀

For any given input file, the file name suffix decides what kind of compilation is gonna happen. These are the input file name kinds that are supported, and honestly? they ate 👑

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

You can specify more than one input file on the gdc command line, and each one gets compiled separately in the compilation process. Now if you specify a -o file option, all the input files get compiled together, producing a single output file named file. This is allowed even when you're using -S or -c — yes, even then 💖

A D interface file contains only what an import of the module needs, rather than the whole implementation of that module. They can be created by gdc from a D source file by using the -H option. When the compiler resolves an import declaration, it searches for matching .di files first, then for .d. first come first served, periodt ✨

A Ddoc source file contains code in the D macro processor language. It is primarily designed for use in producing user documentation from embedded comments, with a slight affinity towards HTML generation. And here's the plot twist 👀 — if a .d source file starts with the string "Ddoc" then it is treated as general purpose documentation, not as a D source file. main character behavior fr fr.

⚡ Runtime Options ⚡

These options affect the runtime behavior of programs compiled with gdc. pay attention bestie, this is the good part 💅

  • -fall-instantiations — Generate code for all template instantiations. The default template emission strategy is to not generate code for declarations that were either instantiated speculatively, such as from __traits(compiles, ...), or that come from an imported module not being compiled. 🌀
  • -fno-assert — Turn off code generation for assert contracts. bye bye asserts 👋
  • -fno-bounds-check — Turns off array bounds checking for all functions, which can improve performance for code that uses arrays extensively. Note that this can result in unpredictable behavior if the code in question actually does violate array bounds constraints. It is safe to use this option if you are sure that your code never throws a RangeError.
⚠️ okay so read this part twice — unpredictable behavior is a real thing here. only reach for it if you're sure nothing ever throws a RangeError, no cap.
  • -fbounds-check=value — An alternative to -fbounds-check that allows more control as to where bounds checking is turned on or off. The following 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 — Don'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 — This option controls what code is generated on an assertion, bounds check, or final switch failure. The following values are supported:
    • context — Throw an AssertError with extra context information. 🔍
    • halt — Halt the program execution. 🛑
    • throw — Throw an AssertError (the default). 🎯
  • -fdebug, -fdebug=value — Turn on compilation of conditional debug code into the program. The -fdebug option itself sets the debug level to 1, while -fdebug= enables debug code that are identified by any of the following values:
    • level — Sets the debug level to level, any debug code <= level is compiled into the program.
    • ident — Turns on compilation of any debug code identified by ident. 🐛
  • -fno-druntime — Implements https://dlang.org/spec/betterc.html. Assumes that 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. The following 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.
  • -fno-invariants — Turns off code generation for class invariant contracts. 🚫
  • -fmain — Generates a default main() function when compiling. This is useful when unittesting a library, as it enables running the unittests in a library without having to manually define an entry-point function. This option does nothing when main is already defined in user code. cute lil shortcut 🎀
  • -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. Functions that are not 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. 🚪
  • -fpreview=id — Turns on an upcoming D language change identified by id. The following values are supported:
    • all — Turns on all upcoming D language features. 🌈
    • dip1000 — Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md (Scoped pointers).
    • dip1008 — Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md (Allow exceptions in @nogc code).
    • dip1021 — Implements https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md (Mutable function arguments).
    • dip25 — Implements https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md (Sealed references).
    • dtorfields — Turns on generation for destructing fields of partially constructed objects.
    • fieldwise — Turns on generation of struct equality to use field-wise comparisons.
    • fixaliasthis — Implements new lookup rules that check the current scope for alias this before searching in upper scopes.
    • in — Implements in parameters to mean scope const [ref] and accepts rvalues.
    • inclusiveincontracts — Implements in contracts of overridden methods to be a superset of 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, which means not emitting runtime checks for contracts and asserts. Array bounds checking is not done for @system and @trusted functions, and assertion failures are undefined behavior.
⚠️ yes bestie, undefined behavior — that's the dramatic kind. it means exactly what it says. 😭

This is equivalent to compiling with the following 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 following values are supported:
    • all — Turns off all revertable D language features. ↩️
    • dip25 — Reverts https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md (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 features of the language that require access to this information will result in an error. 💀
  • -fno-switch-errors — This option controls what code is 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 instead the execution of the program is immediately halted. 🛑
  • -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 the following values:
    • level — Sets the version level to level, any version code >= level is 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 lacks support for weak symbols. Disabling this option means that common symbols are instead put in COMDAT or become private.

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

  • -Idir — Specify a directory to use when searching for imported modules at compile time. Multiple -I options can be used, and the paths are searched in the same order. 🗂️

okay and that's where this part wraps, bestie — but we are not done, keep going, there's more coming 💅✨

  • -Jdir — okay so bestie, this tells the compiler where to look for files when it's doing string imports at compile time. You need this switch if you wanna use import(file) expressions. You can stack multiple -J options, and the paths get searched in the same order. 💖
  • -Ldir — when you're linking, this says “hey, look in this directory for libraries,” just like gcc does. 🫶
  • -Bdir — this one points to where the compiler's own executables, libraries, source files, and data files live, same vibe as gcc. ✨
  • -fmodule-file=module=spec — okay so this 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. It's used when the source file path and names are not the same as the package and module hierarchy. Consider this example:
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 this 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 — sets prefix as the prefix for the gcc directory with target-specific D sources and interfaces. If the prefix is a directory, bestie, include that final /. 🎀
  • -nostdinc — do not search the standard system directories for D source and interface files. Only the directories you gave with -I options (and the directory of the current file, if appropriate) get searched. periodt. 🌸

✨ Code Generation ✨

Besides all the gcc options that control code generation, gdc has its own little set of options. slay. 💅

  • -H — generates D interface files for every module being compiled. The compiler figures out the output file from the input file's name, strips any directory components and suffix, then slaps on a .di suffix. iconic. ✨
  • -Hd dir — same as -H, but writes interface files into 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 interface files to file. You can use it with -Hd dir to independently set the output file and directory path. 💖
  • -M — spits out the module dependencies of all source files being compiled in a format that make can eat. The compiler outputs one make rule with the object file name for that source file, a colon, and the names of all imported files. 🔥
  • -MM — like -M, but it doesn't mention imported modules from the D standard library package directories. 🙈
  • -MF file — when you use it with -M or -MM, it says which file to write the dependencies to. When you use it with the driver options -MD or -MMD, -MF overrides the default dependency output file. 💅
  • -MG — this is just for compatibility with gcc; the compiler ignores it. lowkey useless but there. 💀
  • -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 emitted by dependency generation to be exactly the string you specify. Want multiple targets? You can pass them as a single argument to -MT, or use multiple -MT options. slay. 🌈
  • -MQ target — same as -MT, but it quotes any characters that are special to make. 🧚
  • -MD — equivalent to -M -MF file. The driver determines 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 determines file by removing any 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 specified file. 🫶
  • -fdoc — generates “Ddoc” documentation and writes it to a file. The compiler determines file by removing any directory components and suffix from the input file, then adding a .html suffix. 💅
  • -fdoc-dir=dir — same as -fdoc, but writes documentation to directory dir. You can use it with -fdoc-file=file to independently set the output file and directory path. 🌸
  • -fdoc-file=file — same as -fdoc, but writes documentation to file. You can use it with -fdoc-dir=dir to independently set the output file and directory path. 🎀
  • -fdoc-inc=file — specify file as a Ddoc macro file to read. You can use multiple -fdoc-inc options, and files are read and processed in the same order. 💖
  • -fdump-c++-spec=file — for D source files, generate corresponding C++ declarations in file. ✨
  • -fdump-c++-spec-verbose — use it with -fdump-c++-spec= above, and it 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. It's useful for debugging compilation errors and gives debuggers source to show when requested. 💅

⚠️ Warnings ⚠️

Warnings are diagnostic messages that call out constructions that aren't inherently erroneous but are risky or suggest there's probably a bug in the program. Unless -Werror is specified, they do not prevent compilation. so dramatic but also fair. 😭

  • -Wall — turns on all warnings messages. Warnings aren't a defined part of the D language, and every construct that might trigger one is still valid code. periodt. 🔥
  • -Walloca — warns on every use 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 the -Walloca-larger-than warning 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 is only done for casting between an imaginary and non-imaginary data type, or casting between a D and C++ class. 🙈
  • -Wno-deprecated — do not warn about usage of deprecated features and symbols with “deprecated” attributes. 💅
  • -Werror — turns all warnings into errors. no mercy. 😤
  • -Wspeculative — lists all error messages from speculative compiles, like __traits(compiles, ...). This option doesn't report messages as warnings, so these messages never become errors even when -Werror is also used. 🧚
  • -Wtemplates — warns when a template instantiation is encountered. Some coding rules disallow templates, and this can enforce that rule. 🎀
  • -Wunknown-pragmas — warns when a pragma() is encountered that gdc doesn't understand. 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 — do not warn upon 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 — limits the maximum number of error messages to n, and at that point gdc bails out instead of trying to continue processing the source code. If n is 0 (the default), there's no limit on the number of error messages 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 present on the command-line, but no other output file. ✨
  • -ftransition=id — reports additional info 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.
    • vmarkdown — List instances of Markdown replacements in Ddoc.

🔗 Options for Linking 🔗

These options show up 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 bother otherwise. 💅

  • -defaultlib=libname — specifies the library to use instead of libphobos when linking. Options that specify 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 — do not 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 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 has no effect. 🧚
  • -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 has no effect. 👑

🛠️ Developer Options 🛠️

This section is for command-line options that are mainly interesting to developers or language tooling. iykyk. 💅

  • -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 — okay bestie this one is chef's kiss for snooping on your own build 👀 it dumps info about the compiler's language processing stages while your source program is being compiled. So like, live commentary but make it compiler. What does it show you? All of it:
    • every module getting processed through the "parse", "semantic", "semantic2", and "semantic3" stages
    • every "import" module and its file path 🗂️
    • every "function" body that's currently being compiled

Basically a backstage pass to the whole pipeline. No cap, it's giving production diary. 🎬

🦋 SEE ALSO 🦋

Go read these when you're done here, they're the extended universe:

Copyright (c) 2006-2022 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).

TL;DR bestie: yes you can copy it, share it, remix it — just keep it under the GFDL terms above and don't come for the Invariant Sections, because there aren't any. 🫶

And that's the whole page, babes!! ✨ This one shipped as gcc-12, dated 2024-07-11, and it's filed under GDC(1) in the manual. Slay, go compile something iconic. 💅🌈🦋

📦 where this page comes from