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