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       -fdebug
96       -fdebug=value
97           Turn on compilation of conditional "debug" code into the program.
98           The -fdebug option itself sets the debug level to 1, while -fdebug=
99           enables "debug" code that are identified by any of the following
100           values:
101
102           level
103               Sets the debug level to level, any "debug" code <= level is
104               compiled into the program.
105
106           ident
107               Turns on compilation of any "debug" code identified by ident.
108
109       -fno-druntime
110           Implements <https://dlang.org/spec/betterc.html>.  Assumes that
111           compilation targets an environment without a D runtime library.
112
113           This is equivalent to compiling with the following options:
114
115                   gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
116
117       -fno-invariants
118           Turns off code generation for class "invariant" contracts.
119
120       -fno-moduleinfo
121           Turns off generation of the "ModuleInfo" and related functions that
122           would become unreferenced without it, which may allow linking to
123           programs not written in D.  Functions that are not be generated
124           include module constructors and destructors ("static this" and
125           "static ~this"), "unittest" code, and "DSO" registry functions for
126           dynamically linked code.
127
128       -fonly=filename
129           Tells the compiler to parse and run semantic analysis on all
130           modules on the command line, but only generate code for the module
131           specified by filename.
132
133       -fno-postconditions
134           Turns off code generation for postcondition "out" contracts.
135
136       -fno-preconditions
137           Turns off code generation for precondition "in" contracts.
138
139       -frelease
140           Turns on compiling in release mode, which means not emitting
141           runtime checks for contracts and asserts.  Array bounds checking is
142           not done for @system and @trusted functions, and assertion failures
143           are undefined behavior.
144
145           This is equivalent to compiling with the following options:
146
147                   gdc -fno-assert -fbounds-check=safe -fno-invariants \
148                       -fno-postconditions -fno-preconditions -fno-switch-errors
149
150       -fno-rtti
151           Turns off generation of run-time type information for all user
152           defined types.  Any code that uses features of the language that
153           require access to this information will result in an error.
154
155       -fno-switch-errors
156           This option controls what code is generated when no case is matched
157           in a "final switch" statement.  The default run time behavior is to
158           throw a "SwitchError".  Turning off -fswitch-errors means that
159           instead the execution of the program is immediately halted.
160
161       -funittest
162           Turns on compilation of "unittest" code, and turns on the
163           "version(unittest)" identifier.  This implies -fassert.
164
165       -fversion=value
166           Turns on compilation of conditional "version" code into the program
167           identified by any of the following values:
168
169           level
170               Sets the version level to level, any "version" code >= level is
171               compiled into the program.
172
173           ident
174               Turns on compilation of "version" code identified by ident.
175
176       -fno-weak-templates
177           Turns off emission of declarations that can be defined in multiple
178           objects as weak symbols.  The default is to emit all public symbols
179           as weak, unless the target lacks support for weak symbols.
180           Disabling this option means that common symbols are instead put in
181           COMDAT or become private.
182
183   Options for Directory Search
184       These options specify directories to search for files, libraries, and
185       other parts of the compiler:
186
187       -Idir
188           Specify a directory to use when searching for imported modules at
189           compile time.  Multiple -I options can be used, and the paths are
190           searched in the same order.
191
192       -Jdir
193           Specify a directory to use when searching for files in string
194           imports at compile time.  This switch is required in order to use
195           "import(file)" expressions.  Multiple -J options can be used, and
196           the paths are searched in the same order.
197
198       -Ldir
199           When linking, specify a library search directory, as with gcc.
200
201       -Bdir
202           This option specifies where to find the executables, libraries,
203           source files, and data files of the compiler itself, as with gcc.
204
205       -fmodule-file=module=spec
206           This option manipulates file paths of imported modules, such that
207           if an imported module matches all or the leftmost part of module,
208           the file path in spec is used as the location to search for D
209           sources.  This is used when the source file path and names are not
210           the same as the package and module hierarchy.  Consider the
211           following examples:
212
213                   gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
214
215           This will tell the compiler to search in all import paths for the
216           source file foo.d when importing A.B, and the directory bar/ when
217           importing C, as annotated in the following D code:
218
219                   module test;
220                   import A.B;     // Matches A.B, searches for foo.d
221                   import C.D.E;   // Matches C, searches for bar/D/E.d
222                   import A.B.C;   // No match, searches for A/B/C.d
223
224       -imultilib dir
225           Use dir as a subdirectory of the gcc directory containing target-
226           specific D sources and interfaces.
227
228       -iprefix prefix
229           Specify prefix as the prefix for the gcc directory containing
230           target-specific D sources and interfaces.  If the prefix represents
231           a directory, you should include the final '/'.
232
233       -nostdinc
234           Do not search the standard system directories for D source and
235           interface files.  Only the directories that have been specified
236           with -I options (and the directory of the current file, if
237           appropriate) are searched.
238
239   Code Generation
240       In addition to the many gcc options controlling code generation, gdc
241       has several options specific to itself.
242
243       -H  Generates D interface files for all modules being compiled.  The
244           compiler determines the output file based on the name of the input
245           file, removes any directory components and suffix, and applies the
246           .di suffix.
247
248       -Hd dir
249           Same as -H, but writes interface files to directory dir.  This
250           option can be used with -Hf file to independently set the output
251           file and directory path.
252
253       -Hf file
254           Same as -H but writes interface files to file.  This option can be
255           used with -Hd dir to independently set the output file and
256           directory path.
257
258       -M  Output the module dependencies of all source files being compiled
259           in a format suitable for make.  The compiler outputs one make rule
260           containing the object file name for that source file, a colon, and
261           the names of all imported files.
262
263       -MM Like -M but does not mention imported modules from the D standard
264           library package directories.
265
266       -MF file
267           When used with -M or -MM, specifies a file to write the
268           dependencies to.  When used with the driver options -MD or -MMD,
269           -MF overrides the default dependency output file.
270
271       -MG This option is for compatibility with gcc, and is ignored by the
272           compiler.
273
274       -MP Outputs a phony target for each dependency other than the modules
275           being compiled, causing each to depend on nothing.
276
277       -MT target
278           Change the target of the rule emitted by dependency generation to
279           be exactly the string you specify.  If you want multiple targets,
280           you can specify them as a single argument to -MT, or use multiple
281           -MT options.
282
283       -MQ target
284           Same as -MT, but it quotes any characters which are special to
285           make.
286
287       -MD This option is equivalent to -M -MF file.  The driver determines
288           file by removing any directory components and suffix from the input
289           file, and then adding a .deps suffix.
290
291       -MMD
292           Like -MD but does not mention imported modules from the D standard
293           library package directories.
294
295       -X  Output information describing the contents of all source files
296           being compiled in JSON format to a file.  The driver determines
297           file by removing any directory components and suffix from the input
298           file, and then adding a .json suffix.
299
300       -Xf file
301           Same as -X, but writes all JSON contents to the specified file.
302
303       -fdoc
304           Generates "Ddoc" documentation and writes it to a file.  The
305           compiler determines file by removing any directory components and
306           suffix from the input file, and then adding a .html suffix.
307
308       -fdoc-dir=dir
309           Same as -fdoc, but writes documentation to directory dir.  This
310           option can be used with -fdoc-file=file to independently set the
311           output file and directory path.
312
313       -fdoc-file=file
314           Same as -fdoc, but writes documentation to file.  This option can
315           be used with -fdoc-dir=dir to independently set the output file and
316           directory path.
317
318       -fdoc-inc=file
319           Specify file as a Ddoc macro file to be read.  Multiple -fdoc-inc
320           options can be used, and files are read and processed in the same
321           order.
322
323   Warnings
324       Warnings are diagnostic messages that report constructions that are not
325       inherently erroneous but that are risky or suggest there is likely to
326       be a bug in the program.  Unless -Werror is specified, they do not
327       prevent compilation of the program.
328
329       -Wall
330           Turns on all warnings messages.  Warnings are not a defined part of
331           the D language, and all constructs for which this may generate a
332           warning message are valid code.
333
334       -Walloca
335           This option warns on all uses of "alloca" in the source.
336
337       -Walloca-larger-than=n
338           Warn on unbounded uses of alloca, and on bounded uses of alloca
339           whose bound can be larger than n bytes.  -Wno-alloca-larger-than
340           disables -Walloca-larger-than warning and is equivalent to
341           -Walloca-larger-than=SIZE_MAX or larger.
342
343       -Wcast-result
344           Warn about casts that will produce a null or zero result.
345           Currently this is only done for casting between an imaginary and
346           non-imaginary data type, or casting between a D and C++ class.
347
348       -Wno-deprecated
349           Do not warn about usage of deprecated features and symbols with
350           "deprecated" attributes.
351
352       -Werror
353           Turns all warnings into errors.
354
355       -Wspeculative
356           List all error messages from speculative compiles, such as
357           "__traits(compiles, ...)".  This option does not report messages as
358           warnings, and these messages therefore never become errors when the
359           -Werror option is also used.
360
361       -Wtemplates
362           Warn when a template instantiation is encountered.  Some coding
363           rules disallow templates, and this may be used to enforce that
364           rule.
365
366       -Wunknown-pragmas
367           Warn when a "pragma()" is encountered that is not understood by
368           gdc.  This differs from -fignore-unknown-pragmas where a pragma
369           that is part of the D language, but not implemented by the
370           compiler, won't get reported.
371
372       -Wno-varargs
373           Do not warn upon questionable usage of the macros used to handle
374           variable arguments like "va_start".
375
376       -fignore-unknown-pragmas
377           Turns off errors for unsupported pragmas.
378
379       -fmax-errors=n
380           Limits the maximum number of error messages to n, at which point
381           gdc bails out rather than attempting to continue processing the
382           source code.  If n is 0 (the default), there is no limit on the
383           number of error messages produced.
384
385       -fsyntax-only
386           Check the code for syntax errors, but do not actually compile it.
387           This can be used in conjunction with -fdoc or -H to generate files
388           for each module present on the command-line, but no other output
389           file.
390
391       -ftransition=id
392           Report additional information about D language changes identified
393           by id.  The following values are supported:
394
395           all List information on all language changes.
396
397           complex
398               List all usages of complex or imaginary types.
399
400           dip1000
401               Implements <http://wiki.dlang.org/DIP1000> (experimental).
402
403           dip25
404               Implements <http://wiki.dlang.org/DIP25> (experimental).
405
406           field
407               List all non-mutable fields which occupy an object instance.
408
409           nogc
410               List all hidden GC allocations.
411
412           tls List all variables going into thread local storage.
413
414   Options for Linking
415       These options come into play when the compiler links object files into
416       an executable output file.  They are meaningless if the compiler is not
417       doing a link step.
418
419       -defaultlib=libname
420           Specify the library to use instead of libphobos when linking.
421           Options specifying the linkage of libphobos, such as
422           -static-libphobos or -shared-libphobos, are ignored.
423
424       -debuglib=libname
425           Specify the debug library to use instead of libphobos when linking.
426           This option has no effect unless the -g option was also given on
427           the command line.  Options specifying the linkage of libphobos,
428           such as -static-libphobos or -shared-libphobos, are ignored.
429
430       -nophoboslib
431           Do not use the Phobos or D runtime library when linking.  Options
432           specifying the linkage of libphobos, such as -static-libphobos or
433           -shared-libphobos, are ignored.  The standard system libraries are
434           used normally, unless -nostdlib or -nodefaultlibs is used.
435
436       -shared-libphobos
437           On systems that provide libgphobos and libgdruntime as a shared and
438           a static library, this option forces the use of the shared version.
439           If no shared version was built when the compiler was configured,
440           this option has no effect.
441
442       -static-libphobos
443           On systems that provide libgphobos and libgdruntime as a shared and
444           a static library, this option forces the use of the static version.
445           If no static version was built when the compiler was configured,
446           this option has no effect.
447
448   Developer Options
449       This section describes command-line options that are primarily of
450       interest to developers or language tooling.
451
452       -fdump-d-original
453           Output the internal front-end AST after the "semantic3" stage.
454           This option is only useful for debugging the GNU D compiler itself.
455
456       -v  Dump information about the compiler language processing stages as
457           the source program is being compiled.  This includes listing all
458           modules that are processed through the "parse", "semantic",
459           "semantic2", and "semantic3" stages; all "import" modules and their
460           file paths; and all "function" bodies that are being compiled.
461

SEE ALSO

463       gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entries for gdc
464       and gcc.
465
467       Copyright (c) 2006-2021 Free Software Foundation, Inc.
468
469       Permission is granted to copy, distribute and/or modify this document
470       under the terms of the GNU Free Documentation License, Version 1.3 or
471       any later version published by the Free Software Foundation; with no
472       Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
473       copy of the license is included in the man page gfdl(7).
474
475
476
477gcc-11                            2021-05-31                            GDC(1)
Impressum