1GDC(1)                                GNU                               GDC(1)
2
3
4

NAME

6       gdc - A GCC-based compiler for the D language
7

SYNOPSIS

9       gdc [-c|-S] [-g] [-pg]
10           [-Olevel] [-Wwarn...]
11           [-Idir...] [-Ldir...]
12           [-foption...] [-mmachine-option...]
13           [-o outfile] [@file] infile...
14
15       Only the most useful options are listed here; see below for the
16       remainder.
17

DESCRIPTION

19       The gdc command is the GNU compiler for the D language and supports
20       many of the same options as gcc.  This manual only documents the
21       options specific to gdc.
22

OPTIONS

24   Input and Output files
25       For any given input file, the file name suffix determines what kind of
26       compilation is done.  The following kinds of input file names are
27       supported:
28
29       file.d
30           D source files.
31
32       file.dd
33           Ddoc source files.
34
35       file.di
36           D interface files.
37
38       You can specify more than one input file on the gdc command line, each
39       being compiled separately in the compilation process.  If you specify a
40       "-o file" option, all the input files are compiled together, producing
41       a single output file, named file.  This is allowed even when using "-S"
42       or "-c".
43
44       A D interface file contains only what an import of the module needs,
45       rather than the whole implementation of that module.  They can be
46       created by gdc from a D source file by using the "-H" option.  When the
47       compiler resolves an import declaration, it searches for matching .di
48       files first, then for .d.
49
50       A Ddoc source file contains code in the D macro processor language.  It
51       is primarily designed for use in producing user documentation from
52       embedded comments, with a slight affinity towards HTML generation.  If
53       a .d source file starts with the string "Ddoc" then it is treated as
54       general purpose documentation, not as a D source file.
55
56   Runtime Options
57       These options affect the runtime behavior of programs compiled with
58       gdc.
59
60       -fall-instantiations
61           Generate code for all template instantiations.  The default
62           template emission strategy is to not generate code for declarations
63           that were either instantiated speculatively, such as from
64           "__traits(compiles, ...)", or that come from an imported module not
65           being compiled.
66
67       -fno-assert
68           Turn off code generation for "assert" contracts.
69
70       -fno-bounds-check
71           Turns off array bounds checking for all functions, which can
72           improve performance for code that uses arrays extensively.  Note
73           that this can result in unpredictable behavior if the code in
74           question actually does violate array bounds constraints.  It is
75           safe to use this option if you are sure that your code never throws
76           a "RangeError".
77
78       -fbounds-check=value
79           An alternative to -fbounds-check that allows more control as to
80           where bounds checking is turned on or off.  The following values
81           are supported:
82
83           on  Turns on array bounds checking for all functions.
84
85           safeonly
86               Turns on array bounds checking only for @safe functions.
87
88           off Turns off array bounds checking completely.
89
90       -fno-builtin
91           Don't recognize built-in functions unless they begin with the
92           prefix __builtin_.  By default, the compiler will recognize when a
93           function in the "core.stdc" package is a built-in function.
94
95       -fcheckaction=value
96           This option controls what code is generated on an assertion, bounds
97           check, or final switch failure.  The following values are
98           supported:
99
100           context
101               Throw an "AssertError" with extra context information.
102
103           halt
104               Halt the program execution.
105
106           throw
107               Throw an "AssertError" (the default).
108
109       -fdebug
110       -fdebug=value
111           Turn on compilation of conditional "debug" code into the program.
112           The -fdebug option itself sets the debug level to 1, while -fdebug=
113           enables "debug" code that are identified by any of the following
114           values:
115
116           ident
117               Turns on compilation of any "debug" code identified by ident.
118
119       -fno-druntime
120           Implements <https://dlang.org/spec/betterc.html>.  Assumes that
121           compilation targets an environment without a D runtime library.
122
123           This is equivalent to compiling with the following options:
124
125                   gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
126
127       -fextern-std=standard
128           Sets the C++ name mangling compatibility to the version identified
129           by standard.  The following values are supported:
130
131           c++98
132           c++03
133               Sets "__traits(getTargetInfo, "cppStd")" to 199711.
134
135           c++11
136               Sets "__traits(getTargetInfo, "cppStd")" to 201103.
137
138           c++14
139               Sets "__traits(getTargetInfo, "cppStd")" to 201402.
140
141           c++17
142               Sets "__traits(getTargetInfo, "cppStd")" to 201703.  This is
143               the default.
144
145           c++20
146               Sets "__traits(getTargetInfo, "cppStd")" to 202002.
147
148       -fno-invariants
149           Turns off code generation for class "invariant" contracts.
150
151       -fmain
152           Generates a default main() function when compiling.  This is useful
153           when unittesting a library, as it enables running the unittests in
154           a library without having to manually define an entry-point
155           function.  This option does nothing when "main" is already defined
156           in user code.
157
158       -fno-moduleinfo
159           Turns off generation of the "ModuleInfo" and related functions that
160           would become unreferenced without it, which may allow linking to
161           programs not written in D.  Functions that are not be generated
162           include module constructors and destructors ("static this" and
163           "static ~this"), "unittest" code, and "DSO" registry functions for
164           dynamically linked code.
165
166       -fonly=filename
167           Tells the compiler to parse and run semantic analysis on all
168           modules on the command line, but only generate code for the module
169           specified by filename.
170
171       -fno-postconditions
172           Turns off code generation for postcondition "out" contracts.
173
174       -fno-preconditions
175           Turns off code generation for precondition "in" contracts.
176
177       -fpreview=id
178           Turns on an upcoming D language change identified by id.  The
179           following values are supported:
180
181           all Turns on all upcoming D language features.
182
183           bitfields
184               Implements bit-fields in D.
185
186           dip1000
187               Implements
188               <https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md>
189               (Scoped pointers).
190
191           dip1008
192               Implements
193               <https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md>
194               (Allow exceptions in @nogc code).
195
196           dip1021
197               Implements
198               <https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md>
199               (Mutable function arguments).
200
201           dip25
202               Implements
203               <https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md>
204               (Sealed references).
205
206           dtorfields
207               Turns on generation for destructing fields of partially
208               constructed objects.
209
210           fieldwise
211               Turns on generation of struct equality to use field-wise
212               comparisons.
213
214           fixaliasthis
215               Implements new lookup rules that check the current scope for
216               "alias this" before searching in upper scopes.
217
218           fiximmutableconv
219               Disallows unsound immutable conversions that were formerly
220               incorrectly permitted.
221
222           in  Implements "in" parameters to mean "scope const [ref]" and
223               accepts rvalues.
224
225           inclusiveincontracts
226               Implements "in" contracts of overridden methods to be a
227               superset of parent contract.
228
229           nosharedaccess
230               Turns off and disallows all access to shared memory objects.
231
232           rvaluerefparam
233               Implements rvalue arguments to "ref" parameters.
234
235           systemvariables
236               Disables access to variables marked @system from @safe code.
237
238       -frelease
239           Turns on compiling in release mode, which means not emitting
240           runtime checks for contracts and asserts.  Array bounds checking is
241           not done for @system and @trusted functions, and assertion failures
242           are undefined behavior.
243
244           This is equivalent to compiling with the following options:
245
246                   gdc -fno-assert -fbounds-check=safe -fno-invariants \
247                       -fno-postconditions -fno-preconditions -fno-switch-errors
248
249       -frevert=
250           Turns off a D language feature identified by id.  The following
251           values are supported:
252
253           all Turns off all revertable D language features.
254
255           dip1000
256               Reverts
257               <https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md>
258               (Scoped pointers).
259
260           dip25
261               Reverts
262               <https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md>
263               (Sealed references).
264
265           dtorfields
266               Turns off generation for destructing fields of partially
267               constructed objects.
268
269           intpromote
270               Turns off C-style integral promotion for unary "+", "-" and "~"
271               expressions.
272
273       -fno-rtti
274           Turns off generation of run-time type information for all user
275           defined types.  Any code that uses features of the language that
276           require access to this information will result in an error.
277
278       -fno-switch-errors
279           This option controls what code is generated when no case is matched
280           in a "final switch" statement.  The default run time behavior is to
281           throw a "SwitchError".  Turning off -fswitch-errors means that
282           instead the execution of the program is immediately halted.
283
284       -funittest
285           Turns on compilation of "unittest" code, and turns on the
286           version(unittest) identifier.  This implies -fassert.
287
288       -fversion=value
289           Turns on compilation of conditional "version" code into the program
290           identified by any of the following values:
291
292           ident
293               Turns on compilation of "version" code identified by ident.
294
295       -fno-weak-templates
296           Turns off emission of declarations that can be defined in multiple
297           objects as weak symbols.  The default is to emit all public symbols
298           as weak, unless the target lacks support for weak symbols.
299           Disabling this option means that common symbols are instead put in
300           COMDAT or become private.
301
302   Options for Directory Search
303       These options specify directories to search for files, libraries, and
304       other parts of the compiler:
305
306       -Idir
307           Specify a directory to use when searching for imported modules at
308           compile time.  Multiple -I options can be used, and the paths are
309           searched in the same order.
310
311       -Jdir
312           Specify a directory to use when searching for files in string
313           imports at compile time.  This switch is required in order to use
314           import(file) expressions.  Multiple -J options can be used, and the
315           paths are searched in the same order.
316
317       -Ldir
318           When linking, specify a library search directory, as with gcc.
319
320       -Bdir
321           This option specifies where to find the executables, libraries,
322           source files, and data files of the compiler itself, as with gcc.
323
324       -fmodule-file=module=spec
325           This option manipulates file paths of imported modules, such that
326           if an imported module matches all or the leftmost part of module,
327           the file path in spec is used as the location to search for D
328           sources.  This is used when the source file path and names are not
329           the same as the package and module hierarchy.  Consider the
330           following examples:
331
332                   gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
333
334           This will tell the compiler to search in all import paths for the
335           source file foo.d when importing A.B, and the directory bar/ when
336           importing C, as annotated in the following D code:
337
338                   module test;
339                   import A.B;     // Matches A.B, searches for foo.d
340                   import C.D.E;   // Matches C, searches for bar/D/E.d
341                   import A.B.C;   // No match, searches for A/B/C.d
342
343       -imultilib dir
344           Use dir as a subdirectory of the gcc directory containing target-
345           specific D sources and interfaces.
346
347       -iprefix prefix
348           Specify prefix as the prefix for the gcc directory containing
349           target-specific D sources and interfaces.  If the prefix represents
350           a directory, you should include the final '/'.
351
352       -nostdinc
353           Do not search the standard system directories for D source and
354           interface files.  Only the directories that have been specified
355           with -I options (and the directory of the current file, if
356           appropriate) are searched.
357
358   Code Generation
359       In addition to the many gcc options controlling code generation, gdc
360       has several options specific to itself.
361
362       -H  Generates D interface files for all modules being compiled.  The
363           compiler determines the output file based on the name of the input
364           file, removes any directory components and suffix, and applies the
365           .di suffix.
366
367       -Hd dir
368           Same as -H, but writes interface files to directory dir.  This
369           option can be used with -Hf file to independently set the output
370           file and directory path.
371
372       -Hf file
373           Same as -H but writes interface files to file.  This option can be
374           used with -Hd dir to independently set the output file and
375           directory path.
376
377       -M  Output the module dependencies of all source files being compiled
378           in a format suitable for make.  The compiler outputs one make rule
379           containing the object file name for that source file, a colon, and
380           the names of all imported files.
381
382       -MM Like -M but does not mention imported modules from the D standard
383           library package directories.
384
385       -MF file
386           When used with -M or -MM, specifies a file to write the
387           dependencies to.  When used with the driver options -MD or -MMD,
388           -MF overrides the default dependency output file.
389
390       -MG This option is for compatibility with gcc, and is ignored by the
391           compiler.
392
393       -MP Outputs a phony target for each dependency other than the modules
394           being compiled, causing each to depend on nothing.
395
396       -MT target
397           Change the target of the rule emitted by dependency generation to
398           be exactly the string you specify.  If you want multiple targets,
399           you can specify them as a single argument to -MT, or use multiple
400           -MT options.
401
402       -MQ target
403           Same as -MT, but it quotes any characters which are special to
404           make.
405
406       -MD This option is equivalent to -M -MF file.  The driver determines
407           file by removing any directory components and suffix from the input
408           file, and then adding a .deps suffix.
409
410       -MMD
411           Like -MD but does not mention imported modules from the D standard
412           library package directories.
413
414       -X  Output information describing the contents of all source files
415           being compiled in JSON format to a file.  The driver determines
416           file by removing any directory components and suffix from the input
417           file, and then adding a .json suffix.
418
419       -Xf file
420           Same as -X, but writes all JSON contents to the specified file.
421
422       -fdoc
423           Generates "Ddoc" documentation and writes it to a file.  The
424           compiler determines file by removing any directory components and
425           suffix from the input file, and then adding a .html suffix.
426
427       -fdoc-dir=dir
428           Same as -fdoc, but writes documentation to directory dir.  This
429           option can be used with -fdoc-file=file to independently set the
430           output file and directory path.
431
432       -fdoc-file=file
433           Same as -fdoc, but writes documentation to file.  This option can
434           be used with -fdoc-dir=dir to independently set the output file and
435           directory path.
436
437       -fdoc-inc=file
438           Specify file as a Ddoc macro file to be read.  Multiple -fdoc-inc
439           options can be used, and files are read and processed in the same
440           order.
441
442       -fdump-c++-spec=file
443           For D source files, generate corresponding C++ declarations in
444           file.
445
446       -fdump-c++-spec-verbose
447           In conjunction with -fdump-c++-spec= above, add comments for
448           ignored declarations in the generated C++ header.
449
450       -fsave-mixins=file
451           Generates code expanded from D "mixin" statements and writes the
452           processed sources to file.  This is useful to debug errors in
453           compilation and provides source for debuggers to show when
454           requested.
455
456   Warnings
457       Warnings are diagnostic messages that report constructions that are not
458       inherently erroneous but that are risky or suggest there is likely to
459       be a bug in the program.  Unless -Werror is specified, they do not
460       prevent compilation of the program.
461
462       -Wall
463           Turns on all warnings messages.  Warnings are not a defined part of
464           the D language, and all constructs for which this may generate a
465           warning message are valid code.
466
467       -Walloca
468           This option warns on all uses of "alloca" in the source.
469
470       -Walloca-larger-than=n
471           Warn on unbounded uses of alloca, and on bounded uses of alloca
472           whose bound can be larger than n bytes.  -Wno-alloca-larger-than
473           disables -Walloca-larger-than warning and is equivalent to
474           -Walloca-larger-than=SIZE_MAX or larger.
475
476       -Wno-builtin-declaration-mismatch
477           Warn if a built-in function is declared with an incompatible
478           signature.
479
480       -Wcast-result
481           Warn about casts that will produce a null or zero result.
482           Currently this is only done for casting between an imaginary and
483           non-imaginary data type, or casting between a D and C++ class.
484
485       -Wno-deprecated
486           Do not warn about usage of deprecated features and symbols with
487           "deprecated" attributes.
488
489       -Werror
490           Turns all warnings into errors.
491
492       -Wextra
493           This enables some extra warning flags that are not enabled by
494           -Wall.
495
496           -Waddress -Wcast-result -Wmismatched-special-enum -Wunknown-pragmas
497
498       -Wmismatched-special-enum
499           Warn when an enum the compiler recognizes as special is declared
500           with a different size to the built-in type it is representing.
501
502       -Wspeculative
503           List all error messages from speculative compiles, such as
504           "__traits(compiles, ...)".  This option does not report messages as
505           warnings, and these messages therefore never become errors when the
506           -Werror option is also used.
507
508       -Wunknown-pragmas
509           Warn when a pragma() is encountered that is not understood by gdc.
510           This differs from -fignore-unknown-pragmas where a pragma that is
511           part of the D language, but not implemented by the compiler, won't
512           get reported.
513
514       -Wno-varargs
515           Do not warn upon questionable usage of the macros used to handle
516           variable arguments like "va_start".
517
518       -fignore-unknown-pragmas
519           Turns off errors for unsupported pragmas.
520
521       -fmax-errors=n
522           Limits the maximum number of error messages to n, at which point
523           gdc bails out rather than attempting to continue processing the
524           source code.  If n is 0 (the default), there is no limit on the
525           number of error messages produced.
526
527       -fsyntax-only
528           Check the code for syntax errors, but do not actually compile it.
529           This can be used in conjunction with -fdoc or -H to generate files
530           for each module present on the command-line, but no other output
531           file.
532
533       -ftransition=id
534           Report additional information about D language changes identified
535           by id.  The following values are supported:
536
537           all List information on all D language transitions.
538
539           complex
540               List all usages of complex or imaginary types.
541
542           field
543               List all non-mutable fields which occupy an object instance.
544
545           in  List all usages of "in" on parameter.
546
547           nogc
548               List all hidden GC allocations.
549
550           templates
551               List statistics on template instantiations.
552
553           tls List all variables going into thread local storage.
554
555   Options for Linking
556       These options come into play when the compiler links object files into
557       an executable output file.  They are meaningless if the compiler is not
558       doing a link step.
559
560       -defaultlib=libname
561           Specify the library to use instead of libphobos when linking.
562           Options specifying the linkage of libphobos, such as
563           -static-libphobos or -shared-libphobos, are ignored.
564
565       -debuglib=libname
566           Specify the debug library to use instead of libphobos when linking.
567           This option has no effect unless the -g option was also given on
568           the command line.  Options specifying the linkage of libphobos,
569           such as -static-libphobos or -shared-libphobos, are ignored.
570
571       -nophoboslib
572           Do not use the Phobos or D runtime library when linking.  Options
573           specifying the linkage of libphobos, such as -static-libphobos or
574           -shared-libphobos, are ignored.  The standard system libraries are
575           used normally, unless -nostdlib or -nodefaultlibs is used.
576
577       -shared-libphobos
578           On systems that provide libgphobos and libgdruntime as a shared and
579           a static library, this option forces the use of the shared version.
580           If no shared version was built when the compiler was configured,
581           this option has no effect.
582
583       -static-libphobos
584           On systems that provide libgphobos and libgdruntime as a shared and
585           a static library, this option forces the use of the static version.
586           If no static version was built when the compiler was configured,
587           this option has no effect.
588
589   Developer Options
590       This section describes command-line options that are primarily of
591       interest to developers or language tooling.
592
593       -fdump-d-original
594           Output the internal front-end AST after the "semantic3" stage.
595           This option is only useful for debugging the GNU D compiler itself.
596
597       -v  Dump information about the compiler language processing stages as
598           the source program is being compiled.  This includes listing all
599           modules that are processed through the "parse", "semantic",
600           "semantic2", and "semantic3" stages; all "import" modules and their
601           file paths; and all "function" bodies that are being compiled.
602

SEE ALSO

604       gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entries for gdc
605       and gcc.
606
608       Copyright (c) 2006-2023 Free Software Foundation, Inc.
609
610       Permission is granted to copy, distribute and/or modify this document
611       under the terms of the GNU Free Documentation License, Version 1.3 or
612       any later version published by the Free Software Foundation; with no
613       Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
614       copy of the license is included in the man page gfdl(7).
615
616
617
618gcc-13                            2023-12-05                            GDC(1)
Impressum