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