gcc/d/doc/invoking-gdc/runtime-options.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: options, runtime
   7
   8 .. _runtime-options:
   9
  10 Runtime Options
  11 ***************
  12
  13 These options affect the runtime behavior of programs compiled with
  14 :command:`gdc`.
  15
  16 .. option:: -fall-instantiations
  17
  18   .. index:: -fall-instantiations, -fno-all-instantiations
  19
  20   Generate code for all template instantiations.  The default template emission
  21   strategy is to not generate code for declarations that were either
  22   instantiated speculatively, such as from ``__traits(compiles, ...)``, or
  23   that come from an imported module not being compiled.
  24
  25 .. option:: -fno-assert
  26
  27   .. index:: -fassert, -fno-assert
  28
  29   Turn off code generation for ``assert`` contracts.
  30
  31 .. option:: -fno-bounds-check
  32
  33   .. index:: -fbounds-check, -fno-bounds-check
  34
  35   Turns off array bounds checking for all functions, which can improve
  36   performance for code that uses arrays extensively.  Note that this
  37   can result in unpredictable behavior if the code in question actually
  38   does violate array bounds constraints.  It is safe to use this option
  39   if you are sure that your code never throws a ``RangeError``.
  40
  41 .. option:: -fbounds-check=value
  42
  43   .. index:: -fbounds-check=
  44
  45   An alternative to :option:`-fbounds-check` that allows more control
  46   as to where bounds checking is turned on or off.  The following values
  47   are supported:
  48
  49   :samp:`on`
  50     Turns on array bounds checking for all functions.
  51
  52   :samp:`safeonly`
  53     Turns on array bounds checking only for ``@safe`` functions.
  54
  55   :samp:`off`
  56     Turns off array bounds checking completely.
  57
  58 .. option:: -fno-builtin
  59
  60   .. index:: -fbuiltin, -fno-builtin
  61
  62   Don't recognize built-in functions unless they begin with the prefix
  63   :samp:`__builtin_`.  By default, the compiler will recognize when a
  64   function in the ``core.stdc`` package is a built-in function.
  65
  66 .. option:: -fcheckaction
  67
  68   This option controls what code is generated on an assertion, bounds check, or
  69   final switch failure.  The following values are supported:
  70
  71   :samp:`context`
  72     Throw an ``AssertError`` with extra context information.
  73
  74   :samp:`halt`
  75     Halt the program execution.
  76
  77   :samp:`throw`
  78     Throw an ``AssertError`` (the default).
  79
  80 .. option:: -fdebug=value
  81
  82   .. index:: -fno-debug
  83
  84   Turn on compilation of conditional ``debug`` code into the program.
  85   The :option:`-fdebug` option itself sets the debug level to ``1``,
  86   while :option:`-fdebug=` enables ``debug`` code that are identified
  87   by any of the following values:
  88
  89   :samp:`level`
  90     Sets the debug level to :samp:`{level}`, any ``debug`` code <= :samp:`{level}`
  91     is compiled into the program.
  92
  93   :samp:`ident`
  94     Turns on compilation of any ``debug`` code identified by :samp:`{ident}`.
  95
  96 .. option:: -fno-druntime
  97
  98   .. index:: -fdruntime, -fno-druntime
  99
 100   Implements https://dlang.org/spec/betterc.html.  Assumes that
 101   compilation targets an environment without a D runtime library.
 102
 103   This is equivalent to compiling with the following options:
 104
 105   .. code-block:: c++
 106
 107     gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
 108
 109 .. option:: -fextern-std=standard
 110
 111   Sets the C++ name mangling compatibility to the version identified by
 112   :samp:`{standard}`.  The following values are supported:
 113
 114   :samp:`c++98`, :samp:`c++03`
 115     Sets ``__traits(getTargetInfo, "cppStd")`` to ``199711``.
 116
 117   :samp:`c++11`
 118     Sets ``__traits(getTargetInfo, "cppStd")`` to ``201103``.
 119
 120   :samp:`c++14`
 121     Sets ``__traits(getTargetInfo, "cppStd")`` to ``201402``.
 122
 123   :samp:`c++17`
 124     Sets ``__traits(getTargetInfo, "cppStd")`` to ``201703``.
 125     This is the default.
 126
 127   :samp:`c++20`
 128     Sets ``__traits(getTargetInfo, "cppStd")`` to ``202002``.
 129
 130 .. option:: -fno-invariants
 131
 132   .. index:: -finvariants, -fno-invariants
 133
 134   Turns off code generation for class ``invariant`` contracts.
 135
 136 .. option:: -fmain
 137
 138   Generates a default ``main()`` function when compiling.  This is useful when
 139   unittesting a library, as it enables running the unittests in a library without
 140   having to manually define an entry-point function.  This option does nothing
 141   when ``main`` is already defined in user code.
 142
 143 .. option:: -fno-moduleinfo
 144
 145   Turns off generation of the ``ModuleInfo`` and related functions
 146   that would become unreferenced without it, which may allow linking
 147   to programs not written in D.  Functions that are not be generated
 148   include module constructors and destructors (``static this`` and
 149   ``static ~this``), ``unittest`` code, and ``DSO`` registry
 150   functions for dynamically linked code.
 151
 152 .. option:: -fonly=filename
 153
 154   .. index:: -fonly
 155
 156   Tells the compiler to parse and run semantic analysis on all modules
 157   on the command line, but only generate code for the module specified
 158   by :samp:`{filename}`.
 159
 160 .. option:: -fno-postconditions
 161
 162   .. index:: -fpostconditions, -fno-postconditions
 163
 164   Turns off code generation for postcondition ``out`` contracts.
 165
 166 .. option:: -fno-preconditions
 167
 168   .. index:: -fpreconditions, -fno-preconditions
 169
 170   Turns off code generation for precondition ``in`` contracts.
 171
 172 .. option:: -fpreview=id
 173
 174   .. index:: -fpreview
 175
 176   Turns on an upcoming D language change identified by :samp:`{id}`.  The following
 177   values are supported:
 178
 179   :samp:`all`
 180     Turns on all upcoming D language features.
 181
 182   :samp:`dip1000`
 183     Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md
 184     (Scoped pointers).
 185
 186   :samp:`dip1008`
 187     Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md
 188     (Allow exceptions in ``@nogc`` code).
 189
 190   :samp:`dip1021`
 191     Implements https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md
 192     (Mutable function arguments).
 193
 194   :samp:`dip25`
 195     Implements https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md
 196     (Sealed references).
 197
 198   :samp:`dtorfields`
 199     Turns on generation for destructing fields of partially constructed objects.
 200
 201   :samp:`fieldwise`
 202     Turns on generation of struct equality to use field-wise comparisons.
 203
 204   :samp:`fixaliasthis`
 205     Implements new lookup rules that check the current scope for ``alias this``
 206     before searching in upper scopes.
 207
 208   :samp:`fiximmutableconv`
 209     Disallows unsound immutable conversions that were formerly incorrectly
 210     permitted.
 211
 212   :samp:`in`
 213     Implements ``in`` parameters to mean ``scope const [ref]`` and accepts
 214     rvalues.
 215
 216   :samp:`inclusiveincontracts`
 217     Implements ``in`` contracts of overridden methods to be a superset of parent
 218     contract.
 219
 220   :samp:`intpromote`
 221     Implements C-style integral promotion for unary ``+``, ``-`` and ``~``
 222     expressions.
 223
 224   :samp:`nosharedaccess`
 225     Turns off and disallows all access to shared memory objects.
 226
 227   :samp:`rvaluerefparam`
 228     Implements rvalue arguments to ``ref`` parameters.
 229
 230   :samp:`systemvariables`
 231     Disables access to variables marked ``@system`` from ``@safe`` code.
 232
 233 .. option:: -frelease
 234
 235   .. index:: -fno-release
 236
 237   Turns on compiling in release mode, which means not emitting runtime
 238   checks for contracts and asserts.  Array bounds checking is not done
 239   for ``@system`` and ``@trusted`` functions, and assertion
 240   failures are undefined behavior.
 241
 242   This is equivalent to compiling with the following options:
 243
 244   .. code-block:: c++
 245
 246     gdc -fno-assert -fbounds-check=safe -fno-invariants \
 247         -fno-postconditions -fno-preconditions -fno-switch-errors
 248
 249 .. option:: -frevert=
 250
 251   .. index:: -frevert
 252
 253   Turns off a D language feature identified by :samp:`{id}`.  The following values
 254   are supported:
 255
 256   :samp:`all`
 257     Turns off all revertable D language features.
 258
 259   :samp:`dip25`
 260     Reverts https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md
 261     (Sealed references).
 262
 263   :samp:`dtorfields`
 264     Turns off generation for destructing fields of partially constructed objects.
 265
 266   :samp:`markdown`
 267     Turns off Markdown replacements in Ddoc comments.
 268
 269 .. option:: -fno-rtti
 270
 271   .. index:: -frtti, -fno-rtti
 272
 273   Turns off generation of run-time type information for all user defined types.
 274   Any code that uses features of the language that require access to this
 275   information will result in an error.
 276
 277 .. option:: -fno-switch-errors
 278
 279   .. index:: -fswitch-errors, -fno-switch-errors
 280
 281   This option controls what code is generated when no case is matched
 282   in a ``final switch`` statement.  The default run time behavior
 283   is to throw a ``SwitchError``.  Turning off :option:`-fswitch-errors`
 284   means that instead the execution of the program is immediately halted.
 285
 286 .. option:: -funittest
 287
 288   .. index:: -funittest, -fno-unittest
 289
 290   Turns on compilation of ``unittest`` code, and turns on the
 291   ``version(unittest)`` identifier.  This implies :option:`-fassert`.
 292
 293 .. option:: -fversion=value
 294
 295   .. index:: -fversion
 296
 297   Turns on compilation of conditional ``version`` code into the program
 298   identified by any of the following values:
 299
 300   :samp:`level`
 301     Sets the version level to :samp:`{level}`, any ``version`` code >= :samp:`{level}`
 302     is compiled into the program.
 303
 304   :samp:`ident`
 305     Turns on compilation of ``version`` code identified by :samp:`{ident}`.
 306
 307 .. option:: -fno-weak-templates
 308
 309   .. index:: -fweak-templates, -fno-weak-templates
 310
 311   Turns off emission of declarations that can be defined in multiple objects as
 312   weak symbols.  The default is to emit all public symbols as weak, unless the
 313   target lacks support for weak symbols.  Disabling this option means that common
 314   symbols are instead put in COMDAT or become private.