1\input texinfo @c -*-texinfo-*- 2@setfilename gdc.info 3@settitle The GNU D Compiler 4 5@c Merge the standard indexes into a single one. 6@syncodeindex fn cp 7@syncodeindex vr cp 8@syncodeindex ky cp 9@syncodeindex pg cp 10@syncodeindex tp cp 11 12@include gcc-common.texi 13 14@c Copyright years for this manual. 15@set copyrights-d 2006-2020 16 17@copying 18@c man begin COPYRIGHT 19Copyright @copyright{} @value{copyrights-d} Free Software Foundation, Inc. 20 21Permission is granted to copy, distribute and/or modify this document 22under the terms of the GNU Free Documentation License, Version 1.3 or 23any later version published by the Free Software Foundation; with no 24Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 25A copy of the license is included in the 26@c man end 27section entitled ``GNU Free Documentation License''. 28@ignore 29@c man begin COPYRIGHT 30man page gfdl(7). 31@c man end 32@end ignore 33@end copying 34 35@ifinfo 36@format 37@dircategory Software development 38@direntry 39* gdc: (gdc). A GCC-based compiler for the D language 40@end direntry 41@end format 42 43@insertcopying 44@end ifinfo 45 46@titlepage 47@title The GNU D Compiler 48@versionsubtitle 49@author David Friedman, Iain Buclaw 50 51@page 52@vskip 0pt plus 1filll 53Published by the Free Software Foundation @* 5451 Franklin Street, Fifth Floor@* 55Boston, MA 02110-1301, USA@* 56@sp 1 57@insertcopying 58@end titlepage 59@contents 60@page 61 62@node Top 63@top Introduction 64 65This manual describes how to use @command{gdc}, the GNU compiler for 66the D programming language. This manual is specifically about 67@command{gdc}. For more information about the D programming 68language in general, including language specifications and standard 69package documentation, see @uref{http://dlang.org/}. 70 71@menu 72* Copying:: The GNU General Public License. 73* GNU Free Documentation License:: 74 How you can share and copy this manual. 75* Invoking gdc:: How to run gdc. 76* Index:: Index. 77@end menu 78 79 80@include gpl_v3.texi 81 82@include fdl.texi 83 84 85@node Invoking gdc 86@chapter Invoking gdc 87 88@c man title gdc A GCC-based compiler for the D language 89 90@ignore 91@c man begin SYNOPSIS gdc 92gdc [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}] 93 [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}] 94 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}] 95 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}] 96 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{} 97 98Only the most useful options are listed here; see below for the 99remainder. 100@c man end 101@c man begin SEEALSO 102gpl(7), gfdl(7), fsf-funding(7), gcc(1) 103and the Info entries for @file{gdc} and @file{gcc}. 104@c man end 105@end ignore 106 107@c man begin DESCRIPTION gdc 108 109The @command{gdc} command is the GNU compiler for the D language and 110supports many of the same options as @command{gcc}. @xref{Option Summary, , 111Option Summary, gcc, Using the GNU Compiler Collection (GCC)}. 112This manual only documents the options specific to @command{gdc}. 113 114@c man end 115 116@menu 117* Input and Output files:: Controlling the kind of output: 118 an executable, object files, assembler files, 119* Runtime Options:: Options controlling runtime behavior 120* Directory Options:: Where to find module files 121* Code Generation:: Options controlling the output of gdc 122* Warnings:: Options controlling warnings specific to gdc 123* Linking:: Options influencing the linking step 124* Developer Options:: Options useful for developers of gdc 125@end menu 126 127@c man begin OPTIONS 128 129@node Input and Output files 130@section Input and Output files 131@cindex suffixes for D source 132@cindex D source file suffixes 133 134For any given input file, the file name suffix determines what kind of 135compilation is done. The following kinds of input file names are supported: 136 137@table @gcctabopt 138@item @var{file}.d 139D source files. 140@item @var{file}.dd 141Ddoc source files. 142@item @var{file}.di 143D interface files. 144@end table 145 146You can specify more than one input file on the @command{gdc} command line, 147each being compiled separately in the compilation process. If you specify a 148@code{-o @var{file}} option, all the input files are compiled together, 149producing a single output file, named @var{file}. This is allowed even 150when using @code{-S} or @code{-c}. 151 152@cindex D interface files. 153A D interface file contains only what an import of the module needs, 154rather than the whole implementation of that module. They can be created 155by @command{gdc} from a D source file by using the @code{-H} option. 156When the compiler resolves an import declaration, it searches for matching 157@file{.di} files first, then for @file{.d}. 158 159@cindex Ddoc source files. 160A Ddoc source file contains code in the D macro processor language. It is 161primarily designed for use in producing user documentation from embedded 162comments, with a slight affinity towards HTML generation. If a @file{.d} 163source file starts with the string @code{Ddoc} then it is treated as general 164purpose documentation, not as a D source file. 165 166@node Runtime Options 167@section Runtime Options 168@cindex options, runtime 169 170These options affect the runtime behavior of programs compiled with 171@command{gdc}. 172 173@table @gcctabopt 174 175@item -fall-instantiations 176@cindex @option{-fall-instantiations} 177@cindex @option{-fno-all-instantiations} 178Generate code for all template instantiations. The default template emission 179strategy is to not generate code for declarations that were either 180instantiated speculatively, such as from @code{__traits(compiles, ...)}, or 181that come from an imported module not being compiled. 182 183@item -fno-assert 184@cindex @option{-fassert} 185@cindex @option{-fno-assert} 186Turn off code generation for @code{assert} contracts. 187 188@item -fno-bounds-check 189@cindex @option{-fbounds-check} 190@cindex @option{-fno-bounds-check} 191Turns off array bounds checking for all functions, which can improve 192performance for code that uses arrays extensively. Note that this 193can result in unpredictable behavior if the code in question actually 194does violate array bounds constraints. It is safe to use this option 195if you are sure that your code never throws a @code{RangeError}. 196 197@item -fbounds-check=@var{value} 198@cindex @option{-fbounds-check=} 199An alternative to @option{-fbounds-check} that allows more control 200as to where bounds checking is turned on or off. The following values 201are supported: 202 203@table @samp 204@item on 205Turns on array bounds checking for all functions. 206@item safeonly 207Turns on array bounds checking only for @code{@@safe} functions. 208@item off 209Turns off array bounds checking completely. 210@end table 211 212@item -fno-builtin 213@cindex @option{-fbuiltin} 214@cindex @option{-fno-builtin} 215Don't recognize built-in functions unless they begin with the prefix 216@samp{__builtin_}. By default, the compiler will recognize when a 217function in the @code{core.stdc} package is a built-in function. 218 219@item -fdebug 220@item -fdebug=@var{value} 221@cindex @option{-fdebug} 222@cindex @option{-fno-debug} 223Turn on compilation of conditional @code{debug} code into the program. 224The @option{-fdebug} option itself sets the debug level to @code{1}, 225while @option{-fdebug=} enables @code{debug} code that are identified 226by any of the following values: 227 228@table @samp 229@item level 230Sets the debug level to @var{level}, any @code{debug} code <= @var{level} 231is compiled into the program. 232@item ident 233Turns on compilation of any @code{debug} code identified by @var{ident}. 234@end table 235 236@item -fno-druntime 237@cindex @option{-fdruntime} 238@cindex @option{-fno-druntime} 239Implements @uref{https://dlang.org/spec/betterc.html}. Assumes that 240compilation targets an environment without a D runtime library. 241 242This is equivalent to compiling with the following options: 243 244@example 245gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti 246@end example 247 248@item -fno-invariants 249@cindex @option{-finvariants} 250@cindex @option{-fno-invariants} 251Turns off code generation for class @code{invariant} contracts. 252 253@item -fno-moduleinfo 254@cindex @option{-fmoduleinfo} 255@cindex @option{-fno-moduleinfo} 256Turns off generation of the @code{ModuleInfo} and related functions 257that would become unreferenced without it, which may allow linking 258to programs not written in D. Functions that are not be generated 259include module constructors and destructors (@code{static this} and 260@code{static ~this}), @code{unittest} code, and @code{DSO} registry 261functions for dynamically linked code. 262 263@item -fonly=@var{filename} 264@cindex @option{-fonly} 265Tells the compiler to parse and run semantic analysis on all modules 266on the command line, but only generate code for the module specified 267by @var{filename}. 268 269@item -fno-postconditions 270@cindex @option{-fpostconditions} 271@cindex @option{-fno-postconditions} 272Turns off code generation for postcondition @code{out} contracts. 273 274@item -fno-preconditions 275@cindex @option{-fpreconditions} 276@cindex @option{-fno-preconditions} 277Turns off code generation for precondition @code{in} contracts. 278 279@item -frelease 280@cindex @option{-frelease} 281@cindex @option{-fno-release} 282Turns on compiling in release mode, which means not emitting runtime 283checks for contracts and asserts. Array bounds checking is not done 284for @code{@@system} and @code{@@trusted} functions, and assertion 285failures are undefined behavior. 286 287This is equivalent to compiling with the following options: 288 289@example 290gdc -fno-assert -fbounds-check=safe -fno-invariants \ 291 -fno-postconditions -fno-preconditions -fno-switch-errors 292@end example 293 294@item -fno-rtti 295@cindex @option{-frtti} 296@cindex @option{-fno-rtti} 297Turns off generation of run-time type information for all user defined types. 298Any code that uses features of the language that require access to this 299information will result in an error. 300 301@item -fno-switch-errors 302@cindex @option{-fswitch-errors} 303@cindex @option{-fno-switch-errors} 304This option controls what code is generated when no case is matched 305in a @code{final switch} statement. The default run time behavior 306is to throw a @code{SwitchError}. Turning off @option{-fswitch-errors} 307means that instead the execution of the program is immediately halted. 308 309@item -funittest 310@cindex @option{-funittest} 311@cindex @option{-fno-unittest} 312Turns on compilation of @code{unittest} code, and turns on the 313@code{version(unittest)} identifier. This implies @option{-fassert}. 314 315@item -fversion=@var{value} 316@cindex @option{-fversion} 317Turns on compilation of conditional @code{version} code into the program 318identified by any of the following values: 319 320@table @samp 321@item level 322Sets the version level to @var{level}, any @code{version} code >= @var{level} 323is compiled into the program. 324@item ident 325Turns on compilation of @code{version} code identified by @var{ident}. 326@end table 327 328@item -fno-weak 329@cindex @option{-fweak} 330@cindex @option{-fno-weak} 331Turns off emission of instantiated declarations that can be defined in multiple 332objects as weak or one-only symbols. The default is to emit all public symbols 333as weak, unless the target lacks support for weak symbols. Disabling this 334option means that common symbols are instead put in COMDAT or become private. 335 336@end table 337 338@node Directory Options 339@section Options for Directory Search 340@cindex directory options 341@cindex options, directory search 342@cindex search path 343 344These options specify directories to search for files, libraries, and 345other parts of the compiler: 346 347@table @gcctabopt 348 349@item -I@var{dir} 350@cindex @option{-I} 351Specify a directory to use when searching for imported modules at 352compile time. Multiple @option{-I} options can be used, and the 353paths are searched in the same order. 354 355@item -J@var{dir} 356@cindex @option{-J} 357Specify a directory to use when searching for files in string imports 358at compile time. This switch is required in order to use 359@code{import(file)} expressions. Multiple @option{-J} options can be 360used, and the paths are searched in the same order. 361 362@item -L@var{dir} 363@cindex @option{-L} 364When linking, specify a library search directory, as with @command{gcc}. 365 366@item -B@var{dir} 367@cindex @option{-B} 368This option specifies where to find the executables, libraries, 369source files, and data files of the compiler itself, as with @command{gcc}. 370 371@item -fmodule-file=@var{module}=@var{spec} 372@cindex @option{-fmodule-file} 373This option manipulates file paths of imported modules, such that if an 374imported module matches all or the leftmost part of @var{module}, the file 375path in @var{spec} is used as the location to search for D sources. 376This is used when the source file path and names are not the same as the 377package and module hierarchy. Consider the following examples: 378 379@example 380gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar 381@end example 382 383This will tell the compiler to search in all import paths for the source 384file @var{foo.d} when importing @var{A.B}, and the directory @var{bar/} 385when importing @var{C}, as annotated in the following D code: 386 387@example 388module test; 389import A.B; // Matches A.B, searches for foo.d 390import C.D.E; // Matches C, searches for bar/D/E.d 391import A.B.C; // No match, searches for A/B/C.d 392@end example 393 394@item -imultilib @var{dir} 395@cindex @option{-imultilib} 396Use @var{dir} as a subdirectory of the gcc directory containing 397target-specific D sources and interfaces. 398 399@item -iprefix @var{prefix} 400@cindex @option{-iprefix} 401Specify @var{prefix} as the prefix for the gcc directory containing 402target-specific D sources and interfaces. If the @var{prefix} represents 403a directory, you should include the final @code{'/'}. 404 405@item -nostdinc 406@cindex @option{-nostdinc} 407Do not search the standard system directories for D source and interface 408files. Only the directories that have been specified with @option{-I} options 409(and the directory of the current file, if appropriate) are searched. 410 411@end table 412 413@node Code Generation 414@section Code Generation 415@cindex options, code generation 416 417In addition to the many @command{gcc} options controlling code generation, 418@command{gdc} has several options specific to itself. 419 420@table @gcctabopt 421 422@item -H 423@cindex @option{-H} 424Generates D interface files for all modules being compiled. The compiler 425determines the output file based on the name of the input file, removes 426any directory components and suffix, and applies the @file{.di} suffix. 427 428@item -Hd @var{dir} 429@cindex @option{-Hd} 430Same as @option{-H}, but writes interface files to directory @var{dir}. 431This option can be used with @option{-Hf @var{file}} to independently set the 432output file and directory path. 433 434@item -Hf @var{file} 435@cindex @option{-Hf} 436Same as @option{-H} but writes interface files to @var{file}. This option can 437be used with @option{-Hd @var{dir}} to independently set the output file and 438directory path. 439 440@item -M 441@cindex @option{-M} 442Output the module dependencies of all source files being compiled in a 443format suitable for @command{make}. The compiler outputs one 444@command{make} rule containing the object file name for that source file, 445a colon, and the names of all imported files. 446 447@item -MM 448@cindex @option{-MM} 449Like @option{-M} but does not mention imported modules from the D standard 450library package directories. 451 452@item -MF @var{file} 453@cindex @option{-MF} 454When used with @option{-M} or @option{-MM}, specifies a @var{file} to write 455the dependencies to. When used with the driver options @option{-MD} or 456@option{-MMD}, @option{-MF} overrides the default dependency output file. 457 458@item -MG 459@cindex @option{-MG} 460This option is for compatibility with @command{gcc}, and is ignored by the 461compiler. 462 463@item -MP 464@cindex @option{-MP} 465Outputs a phony target for each dependency other than the modules being 466compiled, causing each to depend on nothing. 467 468@item -MT @var{target} 469@cindex @option{-MT} 470Change the @var{target} of the rule emitted by dependency generation 471to be exactly the string you specify. If you want multiple targets, 472you can specify them as a single argument to @option{-MT}, or use 473multiple @option{-MT} options. 474 475@item -MQ @var{target} 476@cindex @option{-MQ} 477Same as @option{-MT}, but it quotes any characters which are special to 478@command{make}. 479 480@item -MD 481@cindex @option{-MD} 482This option is equivalent to @option{-M -MF @var{file}}. The driver 483determines @var{file} by removing any directory components and suffix 484from the input file, and then adding a @file{.deps} suffix. 485 486@item -MMD 487@cindex @option{-MMD} 488Like @option{-MD} but does not mention imported modules from the D standard 489library package directories. 490 491@item -X 492@cindex @option{-X} 493Output information describing the contents of all source files being 494compiled in JSON format to a file. The driver determines @var{file} by 495removing any directory components and suffix from the input file, and then 496adding a @file{.json} suffix. 497 498@item -Xf @var{file} 499@cindex @option{-Xf} 500Same as @option{-X}, but writes all JSON contents to the specified 501@var{file}. 502 503@item -fdoc 504@cindex @option{-fdoc} 505Generates @code{Ddoc} documentation and writes it to a file. The compiler 506determines @var{file} by removing any directory components and suffix 507from the input file, and then adding a @file{.html} suffix. 508 509@item -fdoc-dir=@var{dir} 510@cindex @option{-fdoc-dir} 511Same as @option{-fdoc}, but writes documentation to directory @var{dir}. 512This option can be used with @option{-fdoc-file=@var{file}} to 513independently set the output file and directory path. 514 515@item -fdoc-file=@var{file} 516@cindex @option{-fdoc-file} 517Same as @option{-fdoc}, but writes documentation to @var{file}. This 518option can be used with @option{-fdoc-dir=@var{dir}} to independently 519set the output file and directory path. 520 521@item -fdoc-inc=@var{file} 522@cindex @option{-fdoc-inc} 523Specify @var{file} as a @var{Ddoc} macro file to be read. Multiple 524@option{-fdoc-inc} options can be used, and files are read and processed 525in the same order. 526 527@end table 528 529@node Warnings 530@section Warnings 531@cindex options to control warnings 532@cindex warning messages 533@cindex messages, warning 534@cindex suppressing warnings 535 536Warnings are diagnostic messages that report constructions that 537are not inherently erroneous but that are risky or suggest there 538is likely to be a bug in the program. Unless @option{-Werror} is 539specified, they do not prevent compilation of the program. 540 541@table @gcctabopt 542 543@item -Wall 544@cindex @option{-Wall} 545@cindex @option{-Wno-all} 546Turns on all warnings messages. Warnings are not a defined part of 547the D language, and all constructs for which this may generate a 548warning message are valid code. 549 550@item -Walloca 551@cindex @option{-Walloca} 552This option warns on all uses of "alloca" in the source. 553 554@item -Walloca-larger-than=@var{n} 555@cindex @option{-Walloca-larger-than} 556@cindex @option{-Wno-alloca-larger-than} 557Warn on unbounded uses of alloca, and on bounded uses of alloca 558whose bound can be larger than @var{n} bytes. 559@option{-Wno-alloca-larger-than} disables 560@option{-Walloca-larger-than} warning and is equivalent to 561@option{-Walloca-larger-than=@var{SIZE_MAX}} or larger. 562 563@item -Wcast-result 564@cindex @option{-Wcast-result} 565@cindex @option{-Wno-cast-result} 566Warn about casts that will produce a null or zero result. Currently 567this is only done for casting between an imaginary and non-imaginary 568data type, or casting between a D and C++ class. 569 570@item -Wno-deprecated 571@cindex @option{-Wdeprecated} 572@cindex @option{-Wno-deprecated} 573Do not warn about usage of deprecated features and symbols with 574@code{deprecated} attributes. 575 576@item -Werror 577@cindex @option{-Werror} 578@cindex @option{-Wno-error} 579Turns all warnings into errors. 580 581@item -Wspeculative 582@cindex @option{-Wspeculative} 583@cindex @option{-Wno-speculative} 584List all error messages from speculative compiles, such as 585@code{__traits(compiles, ...)}. This option does not report 586messages as warnings, and these messages therefore never become 587errors when the @option{-Werror} option is also used. 588 589@item -Wtemplates 590@cindex @option{-Wtemplates} 591@cindex @option{-Wno-templates} 592Warn when a template instantiation is encountered. Some coding 593rules disallow templates, and this may be used to enforce that rule. 594 595@item -Wunknown-pragmas 596@cindex @option{-Wunknown-pragmas} 597@cindex @option{-Wno-unknown-pragmas} 598Warn when a @code{pragma()} is encountered that is not understood by 599@command{gdc}. This differs from @option{-fignore-unknown-pragmas} 600where a pragma that is part of the D language, but not implemented by 601the compiler, won't get reported. 602 603@item -fignore-unknown-pragmas 604@cindex @option{-fignore-unknown-pragmas} 605@cindex @option{-fno-ignore-unknown-pragmas} 606Turns off errors for unsupported pragmas. 607 608@item -fmax-errors=@var{n} 609@cindex @option{-fmax-errors} 610Limits the maximum number of error messages to @var{n}, at which point 611@command{gdc} bails out rather than attempting to continue processing the 612source code. If @var{n} is 0 (the default), there is no limit on the 613number of error messages produced. 614 615@item -fsyntax-only 616@cindex @option{-fsyntax-only} 617@cindex @option{-fno-syntax-only} 618Check the code for syntax errors, but do not actually compile it. This 619can be used in conjunction with @option{-fdoc} or @option{-H} to generate 620files for each module present on the command-line, but no other output 621file. 622 623@item -ftransition=@var{id} 624@cindex @option{-ftransition} 625Report additional information about D language changes identified by 626@var{id}. The following values are supported: 627 628@table @samp 629@item all 630List information on all language changes. 631@item checkimports 632Give deprecation messages about @option{-ftransition=import} anomalies. 633@item complex 634List all usages of complex or imaginary types. 635@item dip1000 636Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md} 637(Scoped pointers). 638@item dip25 639Implements @uref{https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md} 640(Sealed references). 641@item field 642List all non-mutable fields which occupy an object instance. 643@item import 644Tells the compiler to revert to using an old lookup behavior for resolving 645unqualified symbol names, where this was done in a single pass, ignoring 646any protection attributes. The default name lookup strategy is to use two 647passes, the first ignoring imported declarations, and the second only 648looking at imports. The protection (@code{private}, @code{package}, 649@code{protected}) of symbols is also enforced to resolve any conflicts 650between private and public symbols. 651@item nogc 652List all hidden GC allocations. 653@item tls 654List all variables going into thread local storage. 655@end table 656 657@end table 658 659@node Linking 660@section Options for Linking 661@cindex options, linking 662@cindex linking, static 663 664These options come into play when the compiler links object files into an 665executable output file. They are meaningless if the compiler is not doing 666a link step. 667 668@table @gcctabopt 669 670@item -defaultlib=@var{libname} 671@cindex @option{-defaultlib=} 672Specify the library to use instead of libphobos when linking. Options 673specifying the linkage of libphobos, such as @option{-static-libphobos} 674or @option{-shared-libphobos}, are ignored. 675 676@item -debuglib=@var{libname} 677@cindex @option{-debuglib=} 678Specify the debug library to use instead of libphobos when linking. 679This option has no effect unless the @option{-g} option was also given 680on the command line. Options specifying the linkage of libphobos, such 681as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored. 682 683@item -nophoboslib 684@cindex @option{-nophoboslib} 685Do not use the Phobos or D runtime library when linking. Options specifying 686the linkage of libphobos, such as @option{-static-libphobos} or 687@option{-shared-libphobos}, are ignored. The standard system libraries are 688used normally, unless @option{-nostdlib} or @option{-nodefaultlibs} is used. 689 690@item -shared-libphobos 691@cindex @option{-shared-libphobos} 692On systems that provide @file{libgphobos} and @file{libgdruntime} as a 693shared and a static library, this option forces the use of the shared 694version. If no shared version was built when the compiler was configured, 695this option has no effect. 696 697@item -static-libphobos 698@cindex @option{-static-libphobos} 699On systems that provide @file{libgphobos} and @file{libgdruntime} as a 700shared and a static library, this option forces the use of the static 701version. If no static version was built when the compiler was configured, 702this option has no effect. 703 704@end table 705 706@node Developer Options 707@section Developer Options 708@cindex developer options 709@cindex debug dump options 710@cindex dump options 711 712This section describes command-line options that are primarily of 713interest to developers or language tooling. 714 715@table @gcctabopt 716 717@item -fdump-d-original 718@cindex @option{-fdump-d-original} 719Output the internal front-end AST after the @code{semantic3} stage. 720This option is only useful for debugging the GNU D compiler itself. 721 722@item -v 723@cindex @option{-v} 724Dump information about the compiler language processing stages as the source 725program is being compiled. This includes listing all modules that are 726processed through the @code{parse}, @code{semantic}, @code{semantic2}, and 727@code{semantic3} stages; all @code{import} modules and their file paths; 728and all @code{function} bodies that are being compiled. 729 730@end table 731 732@c man end 733 734@node Index 735@unnumbered Index 736 737@printindex cp 738 739@bye 740