~ubuntu-branches/debian/stretch/gcc-6-doc/stretch : revision 2

1

2

@c This is part of the GCC manual.

3

@c For copying conditions, see the file gcc.texi.

4

5

@ignore

6

@c man begin INCLUDE

7

@include gcc-vers.texi

8

@c man end

9

10

@c man begin COPYRIGHT

11

Copyright @copyright{} 1988-2016 Free Software Foundation, Inc.

12

13

Permission is granted to copy, distribute and/or modify this document

14

under the terms of the GNU Free Documentation License, Version 1.3 or

15

any later version published by the Free Software Foundation; with the

16

Invariant Sections being ``GNU General Public License'' and ``Funding

17

Free Software'', the Front-Cover texts being (a) (see below), and with

18

the Back-Cover Texts being (b) (see below). A copy of the license is

19

included in the gfdl(7) man page.

20

21

(a) The FSF's Front-Cover Text is:

22

23

A GNU Manual

24

25

(b) The FSF's Back-Cover Text is:

26

27

You have freedom to copy and modify this GNU Manual, like GNU

28

software. Copies published by the Free Software Foundation raise

29

funds for GNU development.

30

@c man end

31

@c Set file name and title for the man page.

32

@setfilename gcc

33

@settitle GNU project C and C++ compiler

34

@c man begin SYNOPSIS

35

gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]

36

[@option{-g}] [@option{-pg}] [@option{-O}@var{level}]

37

[@option{-W}@var{warn}@dots{}] [@option{-Wpedantic}]

38

[@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]

39

[@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]

40

[@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]

41

[@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}

42

43

Only the most useful options are listed here; see below for the

44

remainder. @command{g++} accepts mostly the same options as @command{gcc}.

45

@c man end

46

@c man begin SEEALSO

47

gpl(7), gfdl(7), fsf-funding(7),

48

cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)

49

and the Info entries for @file{gcc}, @file{cpp}, @file{as},

50

@file{ld}, @file{binutils} and @file{gdb}.

51

@c man end

52

@c man begin BUGS

53

For instructions on reporting bugs, see

54

@w{@value{BUGURL}}.

55

@c man end

56

@c man begin AUTHOR

57

See the Info entry for @command{gcc}, or

58

@w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},

59

for contributors to GCC@.

60

@c man end

61

@end ignore

62

63

@node Invoking GCC

64

@chapter GCC Command Options

65

@cindex GCC command options

66

@cindex command options

67

@cindex options, GCC command

68

69

@c man begin DESCRIPTION

70

When you invoke GCC, it normally does preprocessing, compilation,

71

assembly and linking. The ``overall options'' allow you to stop this

72

process at an intermediate stage. For example, the @option{-c} option

73

says not to run the linker. Then the output consists of object files

74

output by the assembler.

75

@xref{Overall Options,,Options Controlling the Kind of Output}.

76

77

Other options are passed on to one or more stages of processing. Some options

78

control the preprocessor and others the compiler itself. Yet other

79

options control the assembler and linker; most of these are not

80

documented here, since you rarely need to use any of them.

81

82

@cindex C compilation options

83

Most of the command-line options that you can use with GCC are useful

84

for C programs; when an option is only useful with another language

85

(usually C++), the explanation says so explicitly. If the description

86

for a particular option does not mention a source language, you can use

87

that option with all supported languages.

88

89

@cindex cross compiling

90

@cindex specifying machine version

91

@cindex specifying compiler version and target machine

92

@cindex compiler version, specifying

93

@cindex target machine, specifying

94

The usual way to run GCC is to run the executable called @command{gcc}, or

95

@command{@var{machine}-gcc} when cross-compiling, or

96

@command{@var{machine}-gcc-@var{version}} to run a specific version of GCC.

97

When you compile C++ programs, you should invoke GCC as @command{g++}

98

instead. @xref{Invoking G++,,Compiling C++ Programs},

99

for information about the differences in behavior between @command{gcc}

100

and @code{g++} when compiling C++ programs.

101

102

@cindex grouping options

103

@cindex options, grouping

104

The @command{gcc} program accepts options and file names as operands. Many

105

options have multi-letter names; therefore multiple single-letter options

106

may @emph{not} be grouped: @option{-dv} is very different from @w{@samp{-d

107

-v}}.

108

109

@cindex order of options

110

@cindex options, order

111

You can mix options and other arguments. For the most part, the order

112

you use doesn't matter. Order does matter when you use several

113

options of the same kind; for example, if you specify @option{-L} more

114

than once, the directories are searched in the order specified. Also,

115

the placement of the @option{-l} option is significant.

116

117

Many options have long names starting with @samp{-f} or with

118

@samp{-W}---for example,

119

@option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of

120

these have both positive and negative forms; the negative form of

121

@option{-ffoo} is @option{-fno-foo}. This manual documents

122

only one of these two forms, whichever one is not the default.

123

124

@c man end

125

126

@xref{Option Index}, for an index to GCC's options.

127

128

@menu

129

* Option Summary:: Brief list of all options, without explanations.

130

* Overall Options:: Controlling the kind of output:

131

an executable, object files, assembler files,

132

or preprocessed source.

133

* Invoking G++:: Compiling C++ programs.

134

* C Dialect Options:: Controlling the variant of C language compiled.

135

* C++ Dialect Options:: Variations on C++.

136

* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C

137

and Objective-C++.

138

* Diagnostic Message Formatting Options:: Controlling how diagnostics should

139

be formatted.

140

* Warning Options:: How picky should the compiler be?

141

* Debugging Options:: Producing debuggable code.

142

* Optimize Options:: How much optimization?

143

* Instrumentation Options:: Enabling profiling and extra run-time error checking.

144

* Preprocessor Options:: Controlling header files and macro definitions.

145

Also, getting dependency information for Make.

146

* Assembler Options:: Passing options to the assembler.

147

* Link Options:: Specifying libraries and so on.

148

* Directory Options:: Where to find header files and libraries.

149

Where to find the compiler executable files.

150

* Code Gen Options:: Specifying conventions for function calls, data layout

151

and register usage.

152

* Developer Options:: Printing GCC configuration info, statistics, and

153

debugging dumps.

154

* Submodel Options:: Target-specific options, such as compiling for a

155

specific processor variant.

156

* Spec Files:: How to pass switches to sub-processes.

157

* Environment Variables:: Env vars that affect GCC.

158

* Precompiled Headers:: Compiling a header once, and using it many times.

159

@end menu

160

161

@c man begin OPTIONS

162

163

@node Option Summary

164

@section Option Summary

165

166

Here is a summary of all the options, grouped by type. Explanations are

167

in the following sections.

168

169

@table @emph

170

@item Overall Options

171

@xref{Overall Options,,Options Controlling the Kind of Output}.

172

@gccoptlist{-c -S -E -o @var{file} -x @var{language} @gol

173

-v -### --help@r{[}=@var{class}@r{[},@dots{}@r{]]} --target-help --version @gol

174

-pass-exit-codes -pipe -specs=@var{file} -wrapper @gol

175

@@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg} @gol

176

-fdump-ada-spec@r{[}-slim@r{]} -fada-spec-parent=@var{unit} -fdump-go-spec=@var{file}}

177

178

@item C Language Options

179

@xref{C Dialect Options,,Options Controlling C Dialect}.

180

@gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol

181

-aux-info @var{filename} -fallow-parameterless-variadic-functions @gol

182

-fno-asm -fno-builtin -fno-builtin-@var{function} @gol

183

-fhosted -ffreestanding -fopenacc -fopenmp -fopenmp-simd @gol

184

-fms-extensions -fplan9-extensions -fsso-struct=@var{endianness}

185

-fallow-single-precision -fcond-mismatch -flax-vector-conversions @gol

186

-fsigned-bitfields -fsigned-char @gol

187

-funsigned-bitfields -funsigned-char @gol

188

-trigraphs -traditional -traditional-cpp}

189

190

@item C++ Language Options

191

@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.

192

@gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol

193

-fconstexpr-depth=@var{n} -ffriend-injection @gol

194

-fno-elide-constructors @gol

195

-fno-enforce-eh-specs @gol

196

-ffor-scope -fno-for-scope -fno-gnu-keywords @gol

197

-fno-implicit-templates @gol

198

-fno-implicit-inline-templates @gol

199

-fno-implement-inlines -fms-extensions @gol

200

-fno-nonansi-builtins -fnothrow-opt -fno-operator-names @gol

201

-fno-optional-diags -fpermissive @gol

202

-fno-pretty-templates @gol

203

-frepo -fno-rtti -fsized-deallocation @gol

204

-ftemplate-backtrace-limit=@var{n} @gol

205

-ftemplate-depth=@var{n} @gol

206

-fno-threadsafe-statics -fuse-cxa-atexit @gol

207

-fno-weak -nostdinc++ @gol

208

-fvisibility-inlines-hidden @gol

209

-fvisibility-ms-compat @gol

210

-fext-numeric-literals @gol

211

-Wabi=@var{n} -Wabi-tag -Wconversion-null -Wctor-dtor-privacy @gol

212

-Wdelete-non-virtual-dtor -Wliteral-suffix -Wmultiple-inheritance @gol

213

-Wnamespaces -Wnarrowing @gol

214

-Wnoexcept -Wnon-virtual-dtor -Wreorder @gol

215

-Weffc++ -Wstrict-null-sentinel -Wtemplates @gol

216

-Wno-non-template-friend -Wold-style-cast @gol

217

-Woverloaded-virtual -Wno-pmf-conversions @gol

218

-Wsign-promo -Wvirtual-inheritance}

219

220

@item Objective-C and Objective-C++ Language Options

221

@xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling

222

Objective-C and Objective-C++ Dialects}.

223

@gccoptlist{-fconstant-string-class=@var{class-name} @gol

224

-fgnu-runtime -fnext-runtime @gol

225

-fno-nil-receivers @gol

226

-fobjc-abi-version=@var{n} @gol

227

-fobjc-call-cxx-cdtors @gol

228

-fobjc-direct-dispatch @gol

229

-fobjc-exceptions @gol

230

-fobjc-gc @gol

231

-fobjc-nilcheck @gol

232

-fobjc-std=objc1 @gol

233

-fno-local-ivars @gol

234

-fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]} @gol

235

-freplace-objc-classes @gol

236

-fzero-link @gol

237

-gen-decls @gol

238

-Wassign-intercept @gol

239

-Wno-protocol -Wselector @gol

240

-Wstrict-selector-match @gol

241

-Wundeclared-selector}

242

243

@item Diagnostic Message Formatting Options

244

@xref{Diagnostic Message Formatting Options,,Options to Control Diagnostic Messages Formatting}.

245

@gccoptlist{-fmessage-length=@var{n} @gol

246

-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol

247

-fdiagnostics-color=@r{[}auto@r{|}never@r{|}always@r{]} @gol

248

-fno-diagnostics-show-option -fno-diagnostics-show-caret}

249

250

@item Warning Options

251

@xref{Warning Options,,Options to Request or Suppress Warnings}.

252

@gccoptlist{-fsyntax-only -fmax-errors=@var{n} -Wpedantic @gol

253

-pedantic-errors @gol

254

-w -Wextra -Wall -Waddress -Waggregate-return @gol

255

-Wno-aggressive-loop-optimizations -Warray-bounds -Warray-bounds=@var{n} @gol

256

-Wno-attributes -Wbool-compare -Wno-builtin-macro-redefined @gol

257

-Wc90-c99-compat -Wc99-c11-compat @gol

258

-Wc++-compat -Wc++11-compat -Wc++14-compat -Wcast-align -Wcast-qual @gol

259

-Wchar-subscripts -Wclobbered -Wcomment -Wconditionally-supported @gol

260

-Wconversion -Wcoverage-mismatch -Wno-cpp -Wdate-time -Wdelete-incomplete @gol

261

-Wno-deprecated -Wno-deprecated-declarations -Wno-designated-init @gol

262

-Wdisabled-optimization @gol

263

-Wno-discarded-qualifiers -Wno-discarded-array-qualifiers @gol

264

-Wno-div-by-zero -Wdouble-promotion -Wduplicated-cond @gol

265

-Wempty-body -Wenum-compare -Wno-endif-labels @gol

266

-Werror -Werror=* -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol

267

-Wno-format-contains-nul -Wno-format-extra-args -Wformat-nonliteral @gol

268

-Wformat-security -Wformat-signedness -Wformat-y2k -Wframe-address @gol

269

-Wframe-larger-than=@var{len} -Wno-free-nonheap-object -Wjump-misses-init @gol

270

-Wignored-qualifiers -Wignored-attributes -Wincompatible-pointer-types @gol

271

-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol

272

-Winit-self -Winline -Wno-int-conversion @gol

273

-Wno-int-to-pointer-cast -Winvalid-memory-model -Wno-invalid-offsetof @gol

274

-Winvalid-pch -Wlarger-than=@var{len} @gol

275

-Wlogical-op -Wlogical-not-parentheses -Wlong-long @gol

276

-Wmain -Wmaybe-uninitialized -Wmemset-transposed-args @gol

277

-Wmisleading-indentation -Wmissing-braces @gol

278

-Wmissing-field-initializers -Wmissing-include-dirs @gol

279

-Wno-multichar -Wnonnull -Wnonnull-compare @gol

280

-Wnormalized=@r{[}none@r{|}id@r{|}nfc@r{|}nfkc@r{]} @gol

281

-Wnull-dereference -Wodr -Wno-overflow -Wopenmp-simd @gol

282

-Woverride-init-side-effects -Woverlength-strings @gol

283

-Wpacked -Wpacked-bitfield-compat -Wpadded @gol

284

-Wparentheses -Wno-pedantic-ms-format @gol

285

-Wplacement-new -Wplacement-new=@var{n} @gol

286

-Wpointer-arith -Wno-pointer-to-int-cast @gol

287

-Wno-pragmas -Wredundant-decls -Wno-return-local-addr @gol

288

-Wreturn-type -Wsequence-point -Wshadow -Wno-shadow-ivar @gol

289

-Wshift-overflow -Wshift-overflow=@var{n} @gol

290

-Wshift-count-negative -Wshift-count-overflow -Wshift-negative-value @gol

291

-Wsign-compare -Wsign-conversion -Wfloat-conversion @gol

292

-Wno-scalar-storage-order @gol

293

-Wsizeof-pointer-memaccess -Wsizeof-array-argument @gol

294

-Wstack-protector -Wstack-usage=@var{len} -Wstrict-aliasing @gol

295

-Wstrict-aliasing=n -Wstrict-overflow -Wstrict-overflow=@var{n} @gol

296

-Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{]} @gol

297

-Wsuggest-final-types @gol -Wsuggest-final-methods -Wsuggest-override @gol

298

-Wmissing-format-attribute -Wsubobject-linkage @gol

299

-Wswitch -Wswitch-default -Wswitch-enum -Wswitch-bool -Wsync-nand @gol

300

-Wsystem-headers -Wtautological-compare -Wtrampolines -Wtrigraphs @gol

301

-Wtype-limits -Wundef @gol

302

-Wuninitialized -Wunknown-pragmas -Wunsafe-loop-optimizations @gol

303

-Wunsuffixed-float-constants -Wunused -Wunused-function @gol

304

-Wunused-label -Wunused-local-typedefs -Wunused-parameter @gol

305

-Wno-unused-result -Wunused-value @gol -Wunused-variable @gol

306

-Wunused-const-variable -Wunused-const-variable=@var{n} @gol

307

-Wunused-but-set-parameter -Wunused-but-set-variable @gol

308

-Wuseless-cast -Wvariadic-macros -Wvector-operation-performance @gol

309

-Wvla -Wvolatile-register-var -Wwrite-strings @gol

310

-Wzero-as-null-pointer-constant -Whsa}

311

312

@item C and Objective-C-only Warning Options

313

@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol

314

-Wmissing-parameter-type -Wmissing-prototypes -Wnested-externs @gol

315

-Wold-style-declaration -Wold-style-definition @gol

316

-Wstrict-prototypes -Wtraditional -Wtraditional-conversion @gol

317

-Wdeclaration-after-statement -Wpointer-sign}

318

319

@item Debugging Options

320

@xref{Debugging Options,,Options for Debugging Your Program}.

321

@gccoptlist{-g -g@var{level} -gcoff -gdwarf -gdwarf-@var{version} @gol

322

-ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol

323

-gstabs -gstabs+ -gstrict-dwarf -gno-strict-dwarf @gol

324

-gvms -gxcoff -gxcoff+ -gz@r{[}=@var{type}@r{]} @gol

325

-fdebug-prefix-map=@var{old}=@var{new} -fdebug-types-section @gol

326

-feliminate-dwarf2-dups -fno-eliminate-unused-debug-types @gol

327

-femit-struct-debug-baseonly -femit-struct-debug-reduced @gol

328

-femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol

329

-feliminate-unused-debug-symbols -femit-class-debug-always @gol

330

-fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol

331

-fvar-tracking -fvar-tracking-assignments}

332

333

@item Optimization Options

334

@xref{Optimize Options,,Options that Control Optimization}.

335

@gccoptlist{-faggressive-loop-optimizations -falign-functions[=@var{n}] @gol

336

-falign-jumps[=@var{n}] @gol

337

-falign-labels[=@var{n}] -falign-loops[=@var{n}] @gol

338

-fassociative-math -fauto-profile -fauto-profile[=@var{path}] @gol

339

-fauto-inc-dec -fbranch-probabilities @gol

340

-fbranch-target-load-optimize -fbranch-target-load-optimize2 @gol

341

-fbtr-bb-exclusive -fcaller-saves @gol

342

-fcombine-stack-adjustments -fconserve-stack @gol

343

-fcompare-elim -fcprop-registers -fcrossjumping @gol

344

-fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules @gol

345

-fcx-limited-range @gol

346

-fdata-sections -fdce -fdelayed-branch @gol

347

-fdelete-null-pointer-checks -fdevirtualize -fdevirtualize-speculatively @gol

348

-fdevirtualize-at-ltrans -fdse @gol

349

-fearly-inlining -fipa-sra -fexpensive-optimizations -ffat-lto-objects @gol

350

-ffast-math -ffinite-math-only -ffloat-store -fexcess-precision=@var{style} @gol

351

-fforward-propagate -ffp-contract=@var{style} -ffunction-sections @gol

352

-fgcse -fgcse-after-reload -fgcse-las -fgcse-lm -fgraphite-identity @gol

353

-fgcse-sm -fhoist-adjacent-loads -fif-conversion @gol

354

-fif-conversion2 -findirect-inlining @gol

355

-finline-functions -finline-functions-called-once -finline-limit=@var{n} @gol

356

-finline-small-functions -fipa-cp -fipa-cp-clone -fipa-cp-alignment @gol

357

-fipa-pta -fipa-profile -fipa-pure-const -fipa-reference -fipa-icf @gol

358

-fira-algorithm=@var{algorithm} @gol

359

-fira-region=@var{region} -fira-hoist-pressure @gol

360

-fira-loop-pressure -fno-ira-share-save-slots @gol

361

-fno-ira-share-spill-slots @gol

362

-fisolate-erroneous-paths-dereference -fisolate-erroneous-paths-attribute @gol

363

-fivopts -fkeep-inline-functions -fkeep-static-functions @gol

364

-fkeep-static-consts -flive-range-shrinkage @gol

365

-floop-block -floop-interchange -floop-strip-mine @gol

366

-floop-unroll-and-jam -floop-nest-optimize @gol

367

-floop-parallelize-all -flra-remat -flto -flto-compression-level @gol

368

-flto-partition=@var{alg} -fmerge-all-constants @gol

369

-fmerge-constants -fmodulo-sched -fmodulo-sched-allow-regmoves @gol

370

-fmove-loop-invariants -fno-branch-count-reg @gol

371

-fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol

372

-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol

373

-fno-sched-interblock -fno-sched-spec -fno-signed-zeros @gol

374

-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol

375

-fomit-frame-pointer -foptimize-sibling-calls @gol

376

-fpartial-inlining -fpeel-loops -fpredictive-commoning @gol

377

-fprefetch-loop-arrays @gol

378

-fprofile-correction @gol

379

-fprofile-use -fprofile-use=@var{path} -fprofile-values @gol

380

-fprofile-reorder-functions @gol

381

-freciprocal-math -free -frename-registers -freorder-blocks @gol

382

-freorder-blocks-algorithm=@var{algorithm} @gol

383

-freorder-blocks-and-partition -freorder-functions @gol

384

-frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol

385

-frounding-math -fsched2-use-superblocks -fsched-pressure @gol

386

-fsched-spec-load -fsched-spec-load-dangerous @gol

387

-fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol

388

-fsched-group-heuristic -fsched-critical-path-heuristic @gol

389

-fsched-spec-insn-heuristic -fsched-rank-heuristic @gol

390

-fsched-last-insn-heuristic -fsched-dep-count-heuristic @gol

391

-fschedule-fusion @gol

392

-fschedule-insns -fschedule-insns2 -fsection-anchors @gol

393

-fselective-scheduling -fselective-scheduling2 @gol

394

-fsel-sched-pipelining -fsel-sched-pipelining-outer-loops @gol

395

-fsemantic-interposition -fshrink-wrap -fsignaling-nans @gol

396

-fsingle-precision-constant -fsplit-ivs-in-unroller @gol

397

-fsplit-paths @gol

398

-fsplit-wide-types -fssa-backprop -fssa-phiopt @gol

399

-fstdarg-opt -fstrict-aliasing @gol

400

-fstrict-overflow -fthread-jumps -ftracer -ftree-bit-ccp @gol

401

-ftree-builtin-call-dce -ftree-ccp -ftree-ch @gol

402

-ftree-coalesce-vars -ftree-copy-prop -ftree-dce -ftree-dominator-opts @gol

403

-ftree-dse -ftree-forwprop -ftree-fre -ftree-loop-if-convert @gol

404

-ftree-loop-if-convert-stores -ftree-loop-im @gol

405

-ftree-phiprop -ftree-loop-distribution -ftree-loop-distribute-patterns @gol

406

-ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize @gol

407

-ftree-loop-vectorize @gol

408

-ftree-parallelize-loops=@var{n} -ftree-pre -ftree-partial-pre -ftree-pta @gol

409

-ftree-reassoc -ftree-sink -ftree-slsr -ftree-sra @gol

410

-ftree-switch-conversion -ftree-tail-merge -ftree-ter @gol

411

-ftree-vectorize -ftree-vrp -funconstrained-commons @gol

412

-funit-at-a-time -funroll-all-loops -funroll-loops @gol

413

-funsafe-loop-optimizations -funsafe-math-optimizations -funswitch-loops @gol

414

-fipa-ra -fvariable-expansion-in-unroller -fvect-cost-model -fvpt @gol

415

-fweb -fwhole-program -fwpa -fuse-linker-plugin @gol

416

--param @var{name}=@var{value}

417

-O -O0 -O1 -O2 -O3 -Os -Ofast -Og}

418

419

@item Program Instrumentation Options

420

@xref{Instrumentation Options,,Program Instrumentation Options}.

421

@gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol

422

-fprofile-dir=@var{path} -fprofile-generate -fprofile-generate=@var{path} @gol

423

-fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol

424

-fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol

425

-fsanitize-undefined-trap-on-error -fbounds-check @gol

426

-fcheck-pointer-bounds -fchkp-check-incomplete-type @gol

427

-fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol

428

-fchkp-narrow-to-innermost-array -fchkp-optimize @gol

429

-fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol

430

-fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol

431

-fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol

432

-fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol

433

-fchkp-instrument-calls -fchkp-instrument-marked-only @gol

434

-fchkp-use-wrappers @gol

435

-fstack-protector -fstack-protector-all -fstack-protector-strong @gol

436

-fstack-protector-explicit -fstack-check @gol

437

-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol

438

-fno-stack-limit -fsplit-stack @gol

439

-fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol

440

-fvtv-counts -fvtv-debug @gol

441

-finstrument-functions @gol

442

-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol

443

-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}}

444

445

@item Preprocessor Options

446

@xref{Preprocessor Options,,Options Controlling the Preprocessor}.

447

@gccoptlist{-A@var{question}=@var{answer} @gol

448

-A-@var{question}@r{[}=@var{answer}@r{]} @gol

449

-C -dD -dI -dM -dN @gol

450

-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol

451

-idirafter @var{dir} @gol

452

-include @var{file} -imacros @var{file} @gol

453

-iprefix @var{file} -iwithprefix @var{dir} @gol

454

-iwithprefixbefore @var{dir} -isystem @var{dir} @gol

455

-imultilib @var{dir} -isysroot @var{dir} @gol

456

-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol

457

-P -fdebug-cpp -ftrack-macro-expansion -fworking-directory @gol

458

-remap -trigraphs -undef -U@var{macro} @gol

459

-Wp,@var{option} -Xpreprocessor @var{option} -no-integrated-cpp}

460

461

@item Assembler Option

462

@xref{Assembler Options,,Passing Options to the Assembler}.

463

@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}

464

465

@item Linker Options

466

@xref{Link Options,,Options for Linking}.

467

@gccoptlist{@var{object-file-name} -fuse-ld=@var{linker} -l@var{library} @gol

468

-nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol

469

-s -static -static-libgcc -static-libstdc++ @gol

470

-static-libasan -static-libtsan -static-liblsan -static-libubsan @gol

471

-static-libmpx -static-libmpxwrappers @gol

472

-shared -shared-libgcc -symbolic @gol

473

-T @var{script} -Wl,@var{option} -Xlinker @var{option} @gol

474

-u @var{symbol} -z @var{keyword}}

475

476

@item Directory Options

477

@xref{Directory Options,,Options for Directory Search}.

478

@gccoptlist{-B@var{prefix} -I@var{dir} -iplugindir=@var{dir} @gol

479

-iquote@var{dir} -L@var{dir} -no-canonical-prefixes -I- @gol

480

--sysroot=@var{dir} --no-sysroot-suffix}

481

482

@item Code Generation Options

483

@xref{Code Gen Options,,Options for Code Generation Conventions}.

484

@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol

485

-ffixed-@var{reg} -fexceptions @gol

486

-fnon-call-exceptions -fdelete-dead-exceptions -funwind-tables @gol

487

-fasynchronous-unwind-tables @gol

488

-fno-gnu-unique @gol

489

-finhibit-size-directive -fno-common -fno-ident @gol

490

-fpcc-struct-return -fpic -fPIC -fpie -fPIE -fno-plt @gol

491

-fno-jump-tables @gol

492

-frecord-gcc-switches @gol

493

-freg-struct-return -fshort-enums -fshort-wchar @gol

494

-fverbose-asm -fpack-struct[=@var{n}] @gol

495

-fleading-underscore -ftls-model=@var{model} @gol

496

-fstack-reuse=@var{reuse_level} @gol

497

-ftrapv -fwrapv @gol

498

-fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol

499

-fstrict-volatile-bitfields -fsync-libcalls}

500

501

@item Developer Options

502

@xref{Developer Options,,GCC Developer Options}.

503

@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol

504

-fchecking -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol

505

-fdisable-ipa-@var{pass_name} @gol

506

-fdisable-rtl-@var{pass_name} @gol

507

-fdisable-rtl-@var{pass-name}=@var{range-list} @gol

508

-fdisable-tree-@var{pass_name} @gol

509

-fdisable-tree-@var{pass-name}=@var{range-list} @gol

510

-fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol

511

-fdump-translation-unit@r{[}-@var{n}@r{]} @gol

512

-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol

513

-fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol

514

-fdump-passes @gol

515

-fdump-rtl-@var{pass} -fdump-rtl-@var{pass}=@var{filename} @gol

516

-fdump-statistics @gol

517

-fdump-tree-all @gol

518

-fdump-tree-original@r{[}-@var{n}@r{]} @gol

519

-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol

520

-fdump-tree-cfg -fdump-tree-alias @gol

521

-fdump-tree-ch @gol

522

-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol

523

-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol

524

-fdump-tree-gimple@r{[}-raw@r{]} @gol

525

-fdump-tree-dom@r{[}-@var{n}@r{]} @gol

526

-fdump-tree-dse@r{[}-@var{n}@r{]} @gol

527

-fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol

528

-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol

529

-fdump-tree-backprop@r{[}-@var{n}@r{]} @gol

530

-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol

531

-fdump-tree-nrv -fdump-tree-vect @gol

532

-fdump-tree-sink @gol

533

-fdump-tree-sra@r{[}-@var{n}@r{]} @gol

534

-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol

535

-fdump-tree-fre@r{[}-@var{n}@r{]} @gol

536

-fdump-tree-vtable-verify @gol

537

-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol

538

-fdump-tree-split-paths@r{[}-@var{n}@r{]} @gol

539

-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol

540

-fdump-final-insns=@var{file} @gol

541

-fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol

542

-fenable-@var{kind}-@var{pass} @gol

543

-fenable-@var{kind}-@var{pass}=@var{range-list} @gol

544

-fira-verbose=@var{n} @gol

545

-flto-report -flto-report-wpa -fmem-report-wpa @gol

546

-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol

547

-fopt-info -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol

548

-fprofile-report @gol

549

-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol

550

-fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol

551

-fstats -fstack-usage -ftime-report @gol

552

-fvar-tracking-assignments-toggle -gtoggle @gol

553

-print-file-name=@var{library} -print-libgcc-file-name @gol

554

-print-multi-directory -print-multi-lib -print-multi-os-directory @gol

555

-print-prog-name=@var{program} -print-search-dirs -Q @gol

556

-print-sysroot -print-sysroot-headers-suffix @gol

557

-save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}}

558

559

@item Machine-Dependent Options

560

@xref{Submodel Options,,Machine-Dependent Options}.

561

@c This list is ordered alphanumerically by subsection name.

562

@c Try and put the significant identifier (CPU or system) first,

563

@c so users have a clue at guessing where the ones they want will be.

564

565

@emph{AArch64 Options}

566

@gccoptlist{-mabi=@var{name} -mbig-endian -mlittle-endian @gol

567

-mgeneral-regs-only @gol

568

-mcmodel=tiny -mcmodel=small -mcmodel=large @gol

569

-mstrict-align @gol

570

-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol

571

-mtls-dialect=desc -mtls-dialect=traditional @gol

572

-mtls-size=@var{size} @gol

573

-mfix-cortex-a53-835769 -mno-fix-cortex-a53-835769 @gol

574

-mfix-cortex-a53-843419 -mno-fix-cortex-a53-843419 @gol

575

-mlow-precision-recip-sqrt -mno-low-precision-recip-sqrt@gol

576

-march=@var{name} -mcpu=@var{name} -mtune=@var{name}}

577

578

@emph{Adapteva Epiphany Options}

579

@gccoptlist{-mhalf-reg-file -mprefer-short-insn-regs @gol

580

-mbranch-cost=@var{num} -mcmove -mnops=@var{num} -msoft-cmpsf @gol

581

-msplit-lohi -mpost-inc -mpost-modify -mstack-offset=@var{num} @gol

582

-mround-nearest -mlong-calls -mshort-calls -msmall16 @gol

583

-mfp-mode=@var{mode} -mvect-double -max-vect-align=@var{num} @gol

584

-msplit-vecmove-early -m1reg-@var{reg}}

585

586

@emph{ARC Options}

587

@gccoptlist{-mbarrel-shifter @gol

588

-mcpu=@var{cpu} -mA6 -mARC600 -mA7 -mARC700 @gol

589

-mdpfp -mdpfp-compact -mdpfp-fast -mno-dpfp-lrsr @gol

590

-mea -mno-mpy -mmul32x16 -mmul64 -matomic @gol

591

-mnorm -mspfp -mspfp-compact -mspfp-fast -msimd -msoft-float -mswap @gol

592

-mcrc -mdsp-packa -mdvbf -mlock -mmac-d16 -mmac-24 -mrtsc -mswape @gol

593

-mtelephony -mxy -misize -mannotate-align -marclinux -marclinux_prof @gol

594

-mlong-calls -mmedium-calls -msdata @gol

595

-mucb-mcount -mvolatile-cache @gol

596

-malign-call -mauto-modify-reg -mbbit-peephole -mno-brcc @gol

597

-mcase-vector-pcrel -mcompact-casesi -mno-cond-exec -mearly-cbranchsi @gol

598

-mexpand-adddi -mindexed-loads -mlra -mlra-priority-none @gol

599

-mlra-priority-compact mlra-priority-noncompact -mno-millicode @gol

600

-mmixed-code -mq-class -mRcq -mRcw -msize-level=@var{level} @gol

601

-mtune=@var{cpu} -mmultcost=@var{num} @gol

602

-munalign-prob-threshold=@var{probability} -mmpy-option=@var{multo} @gol

603

-mdiv-rem -mcode-density -mll64 -mfpu=@var{fpu}}

604

605

@emph{ARM Options}

606

@gccoptlist{-mapcs-frame -mno-apcs-frame @gol

607

-mabi=@var{name} @gol

608

-mapcs-stack-check -mno-apcs-stack-check @gol

609

-mapcs-float -mno-apcs-float @gol

610

-mapcs-reentrant -mno-apcs-reentrant @gol

611

-msched-prolog -mno-sched-prolog @gol

612

-mlittle-endian -mbig-endian @gol

613

-mfloat-abi=@var{name} @gol

614

-mfp16-format=@var{name}

615

-mthumb-interwork -mno-thumb-interwork @gol

616

-mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol

617

-mtune=@var{name} -mprint-tune-info @gol

618

-mstructure-size-boundary=@var{n} @gol

619

-mabort-on-noreturn @gol

620

-mlong-calls -mno-long-calls @gol

621

-msingle-pic-base -mno-single-pic-base @gol

622

-mpic-register=@var{reg} @gol

623

-mnop-fun-dllimport @gol

624

-mpoke-function-name @gol

625

-mthumb -marm @gol

626

-mtpcs-frame -mtpcs-leaf-frame @gol

627

-mcaller-super-interworking -mcallee-super-interworking @gol

628

-mtp=@var{name} -mtls-dialect=@var{dialect} @gol

629

-mword-relocations @gol

630

-mfix-cortex-m3-ldrd @gol

631

-munaligned-access @gol

632

-mneon-for-64bits @gol

633

-mslow-flash-data @gol

634

-masm-syntax-unified @gol

635

-mrestrict-it}

636

637

@emph{AVR Options}

638

@gccoptlist{-mmcu=@var{mcu} -maccumulate-args -mbranch-cost=@var{cost} @gol

639

-mcall-prologues -mint8 -mn_flash=@var{size} -mno-interrupts @gol

640

-mrelax -mrmw -mstrict-X -mtiny-stack -nodevicelib -Waddr-space-convert}

641

642

@emph{Blackfin Options}

643

@gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol

644

-msim -momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol

645

-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol

646

-mlow-64k -mno-low64k -mstack-check-l1 -mid-shared-library @gol

647

-mno-id-shared-library -mshared-library-id=@var{n} @gol

648

-mleaf-id-shared-library -mno-leaf-id-shared-library @gol

649

-msep-data -mno-sep-data -mlong-calls -mno-long-calls @gol

650

-mfast-fp -minline-plt -mmulticore -mcorea -mcoreb -msdram @gol

651

-micplb}

652

653

@emph{C6X Options}

654

@gccoptlist{-mbig-endian -mlittle-endian -march=@var{cpu} @gol

655

-msim -msdata=@var{sdata-type}}

656

657

@emph{CRIS Options}

658

@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol

659

-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol

660

-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol

661

-mstack-align -mdata-align -mconst-align @gol

662

-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol

663

-melf -maout -melinux -mlinux -sim -sim2 @gol

664

-mmul-bug-workaround -mno-mul-bug-workaround}

665

666

@emph{CR16 Options}

667

@gccoptlist{-mmac @gol

668

-mcr16cplus -mcr16c @gol

669

-msim -mint32 -mbit-ops

670

-mdata-model=@var{model}}

671

672

@emph{Darwin Options}

673

@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol

674

-arch_only -bind_at_load -bundle -bundle_loader @gol

675

-client_name -compatibility_version -current_version @gol

676

-dead_strip @gol

677

-dependency-file -dylib_file -dylinker_install_name @gol

678

-dynamic -dynamiclib -exported_symbols_list @gol

679

-filelist -flat_namespace -force_cpusubtype_ALL @gol

680

-force_flat_namespace -headerpad_max_install_names @gol

681

-iframework @gol

682

-image_base -init -install_name -keep_private_externs @gol

683

-multi_module -multiply_defined -multiply_defined_unused @gol

684

-noall_load -no_dead_strip_inits_and_terms @gol

685

-nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol

686

-pagezero_size -prebind -prebind_all_twolevel_modules @gol

687

-private_bundle -read_only_relocs -sectalign @gol

688

-sectobjectsymbols -whyload -seg1addr @gol

689

-sectcreate -sectobjectsymbols -sectorder @gol

690

-segaddr -segs_read_only_addr -segs_read_write_addr @gol

691

-seg_addr_table -seg_addr_table_filename -seglinkedit @gol

692

-segprot -segs_read_only_addr -segs_read_write_addr @gol

693

-single_module -static -sub_library -sub_umbrella @gol

694

-twolevel_namespace -umbrella -undefined @gol

695

-unexported_symbols_list -weak_reference_mismatches @gol

696

-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol

697

-mkernel -mone-byte-bool}

698

699

@emph{DEC Alpha Options}

700

@gccoptlist{-mno-fp-regs -msoft-float @gol

701

-mieee -mieee-with-inexact -mieee-conformant @gol

702

-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol

703

-mtrap-precision=@var{mode} -mbuild-constants @gol

704

-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol

705

-mbwx -mmax -mfix -mcix @gol

706

-mfloat-vax -mfloat-ieee @gol

707

-mexplicit-relocs -msmall-data -mlarge-data @gol

708

-msmall-text -mlarge-text @gol

709

-mmemory-latency=@var{time}}

710

711

@emph{FR30 Options}

712

@gccoptlist{-msmall-model -mno-lsim}

713

714

@emph{FT32 Options}

715

@gccoptlist{-msim -mlra -mnodiv}

716

717

@emph{FRV Options}

718

@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol

719

-mhard-float -msoft-float @gol

720

-malloc-cc -mfixed-cc -mdword -mno-dword @gol

721

-mdouble -mno-double @gol

722

-mmedia -mno-media -mmuladd -mno-muladd @gol

723

-mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol

724

-mlinked-fp -mlong-calls -malign-labels @gol

725

-mlibrary-pic -macc-4 -macc-8 @gol

726

-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol

727

-moptimize-membar -mno-optimize-membar @gol

728

-mscc -mno-scc -mcond-exec -mno-cond-exec @gol

729

-mvliw-branch -mno-vliw-branch @gol

730

-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol

731

-mno-nested-cond-exec -mtomcat-stats @gol

732

-mTLS -mtls @gol

733

-mcpu=@var{cpu}}

734

735

@emph{GNU/Linux Options}

736

@gccoptlist{-mglibc -muclibc -mmusl -mbionic -mandroid @gol

737

-tno-android-cc -tno-android-ld}

738

739

@emph{H8/300 Options}

740

@gccoptlist{-mrelax -mh -ms -mn -mexr -mno-exr -mint32 -malign-300}

741

742

@emph{HPPA Options}

743

@gccoptlist{-march=@var{architecture-type} @gol

744

-mdisable-fpregs -mdisable-indexing @gol

745

-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol

746

-mfixed-range=@var{register-range} @gol

747

-mjump-in-delay -mlinker-opt -mlong-calls @gol

748

-mlong-load-store -mno-disable-fpregs @gol

749

-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol

750

-mno-jump-in-delay -mno-long-load-store @gol

751

-mno-portable-runtime -mno-soft-float @gol

752

-mno-space-regs -msoft-float -mpa-risc-1-0 @gol

753

-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol

754

-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol

755

-munix=@var{unix-std} -nolibdld -static -threads}

756

757

@emph{IA-64 Options}

758

@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol

759

-mvolatile-asm-stop -mregister-names -msdata -mno-sdata @gol

760

-mconstant-gp -mauto-pic -mfused-madd @gol

761

-minline-float-divide-min-latency @gol

762

-minline-float-divide-max-throughput @gol

763

-mno-inline-float-divide @gol

764

-minline-int-divide-min-latency @gol

765

-minline-int-divide-max-throughput @gol

766

-mno-inline-int-divide @gol

767

-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol

768

-mno-inline-sqrt @gol

769

-mdwarf2-asm -mearly-stop-bits @gol

770

-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol

771

-mtune=@var{cpu-type} -milp32 -mlp64 @gol

772

-msched-br-data-spec -msched-ar-data-spec -msched-control-spec @gol

773

-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol

774

-msched-spec-ldc -msched-spec-control-ldc @gol

775

-msched-prefer-non-data-spec-insns -msched-prefer-non-control-spec-insns @gol

776

-msched-stop-bits-after-every-cycle -msched-count-spec-in-critical-path @gol

777

-msel-sched-dont-check-control-spec -msched-fp-mem-deps-zero-cost @gol

778

-msched-max-memory-insns-hard-limit -msched-max-memory-insns=@var{max-insns}}

779

780

@emph{LM32 Options}

781

@gccoptlist{-mbarrel-shift-enabled -mdivide-enabled -mmultiply-enabled @gol

782

-msign-extend-enabled -muser-enabled}

783

784

@emph{M32R/D Options}

785

@gccoptlist{-m32r2 -m32rx -m32r @gol

786

-mdebug @gol

787

-malign-loops -mno-align-loops @gol

788

-missue-rate=@var{number} @gol

789

-mbranch-cost=@var{number} @gol

790

-mmodel=@var{code-size-model-type} @gol

791

-msdata=@var{sdata-type} @gol

792

-mno-flush-func -mflush-func=@var{name} @gol

793

-mno-flush-trap -mflush-trap=@var{number} @gol

794

-G @var{num}}

795

796

@emph{M32C Options}

797

@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}

798

799

@emph{M680x0 Options}

800

@gccoptlist{-march=@var{arch} -mcpu=@var{cpu} -mtune=@var{tune} @gol

801

-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol

802

-m68060 -mcpu32 -m5200 -m5206e -m528x -m5307 -m5407 @gol

803

-mcfv4e -mbitfield -mno-bitfield -mc68000 -mc68020 @gol

804

-mnobitfield -mrtd -mno-rtd -mdiv -mno-div -mshort @gol

805

-mno-short -mhard-float -m68881 -msoft-float -mpcrel @gol

806

-malign-int -mstrict-align -msep-data -mno-sep-data @gol

807

-mshared-library-id=n -mid-shared-library -mno-id-shared-library @gol

808

-mxgot -mno-xgot}

809

810

@emph{MCore Options}

811

@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol

812

-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol

813

-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol

814

-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol

815

-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}

816

817

@emph{MeP Options}

818

@gccoptlist{-mabsdiff -mall-opts -maverage -mbased=@var{n} -mbitops @gol

819

-mc=@var{n} -mclip -mconfig=@var{name} -mcop -mcop32 -mcop64 -mivc2 @gol

820

-mdc -mdiv -meb -mel -mio-volatile -ml -mleadz -mm -mminmax @gol

821

-mmult -mno-opts -mrepeat -ms -msatur -msdram -msim -msimnovec -mtf @gol

822

-mtiny=@var{n}}

823

824

@emph{MicroBlaze Options}

825

@gccoptlist{-msoft-float -mhard-float -msmall-divides -mcpu=@var{cpu} @gol

826

-mmemcpy -mxl-soft-mul -mxl-soft-div -mxl-barrel-shift @gol

827

-mxl-pattern-compare -mxl-stack-check -mxl-gp-opt -mno-clearbss @gol

828

-mxl-multiply-high -mxl-float-convert -mxl-float-sqrt @gol

829

-mbig-endian -mlittle-endian -mxl-reorder -mxl-mode-@var{app-model}}

830

831

@emph{MIPS Options}

832

@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol

833

-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips32r3 -mips32r5 @gol

834

-mips32r6 -mips64 -mips64r2 -mips64r3 -mips64r5 -mips64r6 @gol

835

-mips16 -mno-mips16 -mflip-mips16 @gol

836

-minterlink-compressed -mno-interlink-compressed @gol

837

-minterlink-mips16 -mno-interlink-mips16 @gol

838

-mabi=@var{abi} -mabicalls -mno-abicalls @gol

839

-mshared -mno-shared -mplt -mno-plt -mxgot -mno-xgot @gol

840

-mgp32 -mgp64 -mfp32 -mfpxx -mfp64 -mhard-float -msoft-float @gol

841

-mno-float -msingle-float -mdouble-float @gol

842

-modd-spreg -mno-odd-spreg @gol

843

-mabs=@var{mode} -mnan=@var{encoding} @gol

844

-mdsp -mno-dsp -mdspr2 -mno-dspr2 @gol

845

-mmcu -mmno-mcu @gol

846

-meva -mno-eva @gol

847

-mvirt -mno-virt @gol

848

-mxpa -mno-xpa @gol

849

-mmicromips -mno-micromips @gol

850

-mfpu=@var{fpu-type} @gol

851

-msmartmips -mno-smartmips @gol

852

-mpaired-single -mno-paired-single -mdmx -mno-mdmx @gol

853

-mips3d -mno-mips3d -mmt -mno-mt -mllsc -mno-llsc @gol

854

-mlong64 -mlong32 -msym32 -mno-sym32 @gol

855

-G@var{num} -mlocal-sdata -mno-local-sdata @gol

856

-mextern-sdata -mno-extern-sdata -mgpopt -mno-gopt @gol

857

-membedded-data -mno-embedded-data @gol

858

-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol

859

-mcode-readable=@var{setting} @gol

860

-msplit-addresses -mno-split-addresses @gol

861

-mexplicit-relocs -mno-explicit-relocs @gol

862

-mcheck-zero-division -mno-check-zero-division @gol

863

-mdivide-traps -mdivide-breaks @gol

864

-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol

865

-mmad -mno-mad -mimadd -mno-imadd -mfused-madd -mno-fused-madd -nocpp @gol

866

-mfix-24k -mno-fix-24k @gol

867

-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol

868

-mfix-r10000 -mno-fix-r10000 -mfix-rm7000 -mno-fix-rm7000 @gol

869

-mfix-vr4120 -mno-fix-vr4120 @gol

870

-mfix-vr4130 -mno-fix-vr4130 -mfix-sb1 -mno-fix-sb1 @gol

871

-mflush-func=@var{func} -mno-flush-func @gol

872

-mbranch-cost=@var{num} -mbranch-likely -mno-branch-likely @gol

873

-mcompact-branches=@var{policy} @gol

874

-mfp-exceptions -mno-fp-exceptions @gol

875

-mvr4130-align -mno-vr4130-align -msynci -mno-synci @gol

876

-mrelax-pic-calls -mno-relax-pic-calls -mmcount-ra-address @gol

877

-mframe-header-opt -mno-frame-header-opt}

878

879

@emph{MMIX Options}

880

@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol

881

-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol

882

-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol

883

-mno-base-addresses -msingle-exit -mno-single-exit}

884

885

@emph{MN10300 Options}

886

@gccoptlist{-mmult-bug -mno-mult-bug @gol

887

-mno-am33 -mam33 -mam33-2 -mam34 @gol

888

-mtune=@var{cpu-type} @gol

889

-mreturn-pointer-on-d0 @gol

890

-mno-crt0 -mrelax -mliw -msetlb}

891

892

@emph{Moxie Options}

893

@gccoptlist{-meb -mel -mmul.x -mno-crt0}

894

895

@emph{MSP430 Options}

896

@gccoptlist{-msim -masm-hex -mmcu= -mcpu= -mlarge -msmall -mrelax @gol

897

-mwarn-mcu @gol

898

-mcode-region= -mdata-region= @gol

899

-msilicon-errata= -msilicon-errata-warn= @gol

900

-mhwmult= -minrt}

901

902

@emph{NDS32 Options}

903

@gccoptlist{-mbig-endian -mlittle-endian @gol

904

-mreduced-regs -mfull-regs @gol

905

-mcmov -mno-cmov @gol

906

-mperf-ext -mno-perf-ext @gol

907

-mv3push -mno-v3push @gol

908

-m16bit -mno-16bit @gol

909

-misr-vector-size=@var{num} @gol

910

-mcache-block-size=@var{num} @gol

911

-march=@var{arch} @gol

912

-mcmodel=@var{code-model} @gol

913

-mctor-dtor -mrelax}

914

915

@emph{Nios II Options}

916

@gccoptlist{-G @var{num} -mgpopt=@var{option} -mgpopt -mno-gpopt @gol

917

-mel -meb @gol

918

-mno-bypass-cache -mbypass-cache @gol

919

-mno-cache-volatile -mcache-volatile @gol

920

-mno-fast-sw-div -mfast-sw-div @gol

921

-mhw-mul -mno-hw-mul -mhw-mulx -mno-hw-mulx -mno-hw-div -mhw-div @gol

922

-mcustom-@var{insn}=@var{N} -mno-custom-@var{insn} @gol

923

-mcustom-fpu-cfg=@var{name} @gol

924

-mhal -msmallc -msys-crt0=@var{name} -msys-lib=@var{name} @gol

925

-march=@var{arch} -mbmx -mno-bmx -mcdx -mno-cdx}

926

927

@emph{Nvidia PTX Options}

928

@gccoptlist{-m32 -m64 -mmainkernel -moptimize}

929

930

@emph{PDP-11 Options}

931

@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol

932

-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol

933

-mint16 -mno-int32 -mfloat32 -mno-float64 @gol

934

-mfloat64 -mno-float32 -mabshi -mno-abshi @gol

935

-mbranch-expensive -mbranch-cheap @gol

936

-munix-asm -mdec-asm}

937

938

@emph{picoChip Options}

939

@gccoptlist{-mae=@var{ae_type} -mvliw-lookahead=@var{N} @gol

940

-msymbol-as-address -mno-inefficient-warnings}

941

942

@emph{PowerPC Options}

943

See RS/6000 and PowerPC Options.

944

945

@emph{RL78 Options}

946

@gccoptlist{-msim -mmul=none -mmul=g13 -mmul=g14 -mallregs @gol

947

-mcpu=g10 -mcpu=g13 -mcpu=g14 -mg10 -mg13 -mg14 @gol

948

-m64bit-doubles -m32bit-doubles}

949

950

@emph{RS/6000 and PowerPC Options}

951

@gccoptlist{-mcpu=@var{cpu-type} @gol

952

-mtune=@var{cpu-type} @gol

953

-mcmodel=@var{code-model} @gol

954

-mpowerpc64 @gol

955

-maltivec -mno-altivec @gol

956

-mpowerpc-gpopt -mno-powerpc-gpopt @gol

957

-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol

958

-mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mpopcntd -mno-popcntd @gol

959

-mfprnd -mno-fprnd @gol

960

-mcmpb -mno-cmpb -mmfpgpr -mno-mfpgpr -mhard-dfp -mno-hard-dfp @gol

961

-mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol

962

-m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol

963

-malign-power -malign-natural @gol

964

-msoft-float -mhard-float -mmultiple -mno-multiple @gol

965

-msingle-float -mdouble-float -msimple-fpu @gol

966

-mstring -mno-string -mupdate -mno-update @gol

967

-mavoid-indexed-addresses -mno-avoid-indexed-addresses @gol

968

-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol

969

-mstrict-align -mno-strict-align -mrelocatable @gol

970

-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol

971

-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol

972

-mdynamic-no-pic -maltivec -mswdiv -msingle-pic-base @gol

973

-mprioritize-restricted-insns=@var{priority} @gol

974

-msched-costly-dep=@var{dependence_type} @gol

975

-minsert-sched-nops=@var{scheme} @gol

976

-mcall-sysv -mcall-netbsd @gol

977

-maix-struct-return -msvr4-struct-return @gol

978

-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol

979

-mblock-move-inline-limit=@var{num} @gol

980

-misel -mno-isel @gol

981

-misel=yes -misel=no @gol

982

-mspe -mno-spe @gol

983

-mspe=yes -mspe=no @gol

984

-mpaired @gol

985

-mgen-cell-microcode -mwarn-cell-microcode @gol

986

-mvrsave -mno-vrsave @gol

987

-mmulhw -mno-mulhw @gol

988

-mdlmzb -mno-dlmzb @gol

989

-mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol

990

-mprototype -mno-prototype @gol

991

-msim -mmvme -mads -myellowknife -memb -msdata @gol

992

-msdata=@var{opt} -mvxworks -G @var{num} -pthread @gol

993

-mrecip -mrecip=@var{opt} -mno-recip -mrecip-precision @gol

994

-mno-recip-precision @gol

995

-mveclibabi=@var{type} -mfriz -mno-friz @gol

996

-mpointers-to-nested-functions -mno-pointers-to-nested-functions @gol

997

-msave-toc-indirect -mno-save-toc-indirect @gol

998

-mpower8-fusion -mno-mpower8-fusion -mpower8-vector -mno-power8-vector @gol

999

-mcrypto -mno-crypto -mdirect-move -mno-direct-move @gol

1000

-mquad-memory -mno-quad-memory @gol

1001

-mquad-memory-atomic -mno-quad-memory-atomic @gol

1002

-mcompat-align-parm -mno-compat-align-parm @gol

1003

-mupper-regs-df -mno-upper-regs-df -mupper-regs-sf -mno-upper-regs-sf @gol

1004

-mupper-regs -mno-upper-regs -mmodulo -mno-modulo @gol

1005

-mfloat128 -mno-float128 -mfloat128-hardware -mno-float128-hardware @gol

1006

-mpower9-fusion -mno-mpower9-fusion -mpower9-vector -mno-power9-vector}

1007

1008

@emph{RX Options}

1009

@gccoptlist{-m64bit-doubles -m32bit-doubles -fpu -nofpu@gol

1010

-mcpu=@gol

1011

-mbig-endian-data -mlittle-endian-data @gol

1012

-msmall-data @gol

1013

-msim -mno-sim@gol

1014

-mas100-syntax -mno-as100-syntax@gol

1015

-mrelax@gol

1016

-mmax-constant-size=@gol

1017

-mint-register=@gol

1018

-mpid@gol

1019

-mallow-string-insns -mno-allow-string-insns@gol

1020

-mjsr@gol

1021

-mno-warn-multiple-fast-interrupts@gol

1022

-msave-acc-in-interrupts}

1023

1024

@emph{S/390 and zSeries Options}

1025

@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol

1026

-mhard-float -msoft-float -mhard-dfp -mno-hard-dfp @gol

1027

-mlong-double-64 -mlong-double-128 @gol

1028

-mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol

1029

-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol

1030

-m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol

1031

-mhtm -mvx -mzvector @gol

1032

-mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol

1033

-mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard @gol

1034

-mhotpatch=@var{halfwords},@var{halfwords}}

1035

1036

@emph{Score Options}

1037

@gccoptlist{-meb -mel @gol

1038

-mnhwloop @gol

1039

-muls @gol

1040

-mmac @gol

1041

-mscore5 -mscore5u -mscore7 -mscore7d}

1042

1043

@emph{SH Options}

1044

@gccoptlist{-m1 -m2 -m2e @gol

1045

-m2a-nofpu -m2a-single-only -m2a-single -m2a @gol

1046

-m3 -m3e @gol

1047

-m4-nofpu -m4-single-only -m4-single -m4 @gol

1048

-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol

1049

-mb -ml -mdalign -mrelax @gol

1050

-mbigtable -mfmovd -mrenesas -mno-renesas -mnomacsave @gol

1051

-mieee -mno-ieee -mbitops -misize -minline-ic_invalidate -mpadstruct @gol

1052

-mspace -mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol

1053

-mdivsi3_libfunc=@var{name} -mfixed-range=@var{register-range} @gol

1054

-maccumulate-outgoing-args @gol

1055

-matomic-model=@var{atomic-model} @gol

1056

-mbranch-cost=@var{num} -mzdcbranch -mno-zdcbranch @gol

1057

-mcbranch-force-delay-slot @gol

1058

-mfused-madd -mno-fused-madd -mfsca -mno-fsca -mfsrra -mno-fsrra @gol

1059

-mpretend-cmove -mtas}

1060

1061

@emph{Solaris 2 Options}

1062

@gccoptlist{-mclear-hwcap -mno-clear-hwcap -mimpure-text -mno-impure-text @gol

1063

-pthreads -pthread}

1064

1065

@emph{SPARC Options}

1066

@gccoptlist{-mcpu=@var{cpu-type} @gol

1067

-mtune=@var{cpu-type} @gol

1068

-mcmodel=@var{code-model} @gol

1069

-mmemory-model=@var{mem-model} @gol

1070

-m32 -m64 -mapp-regs -mno-app-regs @gol

1071

-mfaster-structs -mno-faster-structs -mflat -mno-flat @gol

1072

-mfpu -mno-fpu -mhard-float -msoft-float @gol

1073

-mhard-quad-float -msoft-quad-float @gol

1074

-mstack-bias -mno-stack-bias @gol

1075

-mstd-struct-return -mno-std-struct-return @gol

1076

-munaligned-doubles -mno-unaligned-doubles @gol

1077

-muser-mode -mno-user-mode @gol

1078

-mv8plus -mno-v8plus -mvis -mno-vis @gol

1079

-mvis2 -mno-vis2 -mvis3 -mno-vis3 @gol

1080

-mcbcond -mno-cbcond @gol

1081

-mfmaf -mno-fmaf -mpopc -mno-popc @gol

1082

-mfix-at697f -mfix-ut699}

1083

1084

@emph{SPU Options}

1085

@gccoptlist{-mwarn-reloc -merror-reloc @gol

1086

-msafe-dma -munsafe-dma @gol

1087

-mbranch-hints @gol

1088

-msmall-mem -mlarge-mem -mstdmain @gol

1089

-mfixed-range=@var{register-range} @gol

1090

-mea32 -mea64 @gol

1091

-maddress-space-conversion -mno-address-space-conversion @gol

1092

-mcache-size=@var{cache-size} @gol

1093

-matomic-updates -mno-atomic-updates}

1094

1095

@emph{System V Options}

1096

@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}

1097

1098

@emph{TILE-Gx Options}

1099

@gccoptlist{-mcpu=CPU -m32 -m64 -mbig-endian -mlittle-endian @gol

1100

-mcmodel=@var{code-model}}

1101

1102

@emph{TILEPro Options}

1103

@gccoptlist{-mcpu=@var{cpu} -m32}

1104

1105

@emph{V850 Options}

1106

@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol

1107

-mprolog-function -mno-prolog-function -mspace @gol

1108

-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol

1109

-mapp-regs -mno-app-regs @gol

1110

-mdisable-callt -mno-disable-callt @gol

1111

-mv850e2v3 -mv850e2 -mv850e1 -mv850es @gol

1112

-mv850e -mv850 -mv850e3v5 @gol

1113

-mloop @gol

1114

-mrelax @gol

1115

-mlong-jumps @gol

1116

-msoft-float @gol

1117

-mhard-float @gol

1118

-mgcc-abi @gol

1119

-mrh850-abi @gol

1120

-mbig-switch}

1121

1122

@emph{VAX Options}

1123

@gccoptlist{-mg -mgnu -munix}

1124

1125

@emph{Visium Options}

1126

@gccoptlist{-mdebug -msim -mfpu -mno-fpu -mhard-float -msoft-float @gol

1127

-mcpu=@var{cpu-type} -mtune=@var{cpu-type} -msv-mode -muser-mode}

1128

1129

@emph{VMS Options}

1130

@gccoptlist{-mvms-return-codes -mdebug-main=@var{prefix} -mmalloc64 @gol

1131

-mpointer-size=@var{size}}

1132

1133

@emph{VxWorks Options}

1134

@gccoptlist{-mrtp -non-static -Bstatic -Bdynamic @gol

1135

-Xbind-lazy -Xbind-now}

1136

1137

@emph{x86 Options}

1138

@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol

1139

-mtune-ctrl=@var{feature-list} -mdump-tune-features -mno-default @gol

1140

-mfpmath=@var{unit} @gol

1141

-masm=@var{dialect} -mno-fancy-math-387 @gol

1142

-mno-fp-ret-in-387 -msoft-float @gol

1143

-mno-wide-multiply -mrtd -malign-double @gol

1144

-mpreferred-stack-boundary=@var{num} @gol

1145

-mincoming-stack-boundary=@var{num} @gol

1146

-mcld -mcx16 -msahf -mmovbe -mcrc32 @gol

1147

-mrecip -mrecip=@var{opt} @gol

1148

-mvzeroupper -mprefer-avx128 @gol

1149

-mmmx -msse -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 -mavx @gol

1150

-mavx2 -mavx512f -mavx512pf -mavx512er -mavx512cd -mavx512vl @gol

1151

-mavx512bw -mavx512dq -mavx512ifma -mavx512vbmi -msha -maes @gol

1152

-mpclmul -mfsgsbase -mrdrnd -mf16c -mfma @gol

1153

-mprefetchwt1 -mclflushopt -mxsavec -mxsaves @gol

1154

-msse4a -m3dnow -mpopcnt -mabm -mbmi -mtbm -mfma4 -mxop -mlzcnt @gol

1155

-mbmi2 -mfxsr -mxsave -mxsaveopt -mrtm -mlwp -mmpx -mmwaitx -mclzero

1156

-mpku -mthreads @gol

1157

-mms-bitfields -mno-align-stringops -minline-all-stringops @gol

1158

-minline-stringops-dynamically -mstringop-strategy=@var{alg} @gol

1159

-mmemcpy-strategy=@var{strategy} -mmemset-strategy=@var{strategy} @gol

1160

-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol

1161

-m96bit-long-double -mlong-double-64 -mlong-double-80 -mlong-double-128 @gol

1162

-mregparm=@var{num} -msseregparm @gol

1163

-mveclibabi=@var{type} -mvect8-ret-in-mem @gol

1164

-mpc32 -mpc64 -mpc80 -mstackrealign @gol

1165

-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol

1166

-mcmodel=@var{code-model} -mabi=@var{name} -maddress-mode=@var{mode} @gol

1167

-m32 -m64 -mx32 -m16 -miamcu -mlarge-data-threshold=@var{num} @gol

1168

-msse2avx -mfentry -mrecord-mcount -mnop-mcount -m8bit-idiv @gol

1169

-mavx256-split-unaligned-load -mavx256-split-unaligned-store @gol

1170

-malign-data=@var{type} -mstack-protector-guard=@var{guard} @gol

1171

-mmitigate-rop}

1172

1173

@emph{x86 Windows Options}

1174

@gccoptlist{-mconsole -mcygwin -mno-cygwin -mdll @gol

1175

-mnop-fun-dllimport -mthread @gol

1176

-municode -mwin32 -mwindows -fno-set-stack-executable}

1177

1178

@emph{Xstormy16 Options}

1179

@gccoptlist{-msim}

1180

1181

@emph{Xtensa Options}

1182

@gccoptlist{-mconst16 -mno-const16 @gol

1183

-mfused-madd -mno-fused-madd @gol

1184

-mforce-no-pic @gol

1185

-mserialize-volatile -mno-serialize-volatile @gol

1186

-mtext-section-literals -mno-text-section-literals @gol

1187

-mauto-litpools -mno-auto-litpools @gol

1188

-mtarget-align -mno-target-align @gol

1189

-mlongcalls -mno-longcalls}

1190

1191

@emph{zSeries Options}

1192

See S/390 and zSeries Options.

1193

@end table

1194

1195

1196

@node Overall Options

1197

@section Options Controlling the Kind of Output

1198

1199

Compilation can involve up to four stages: preprocessing, compilation

1200

proper, assembly and linking, always in that order. GCC is capable of

1201

preprocessing and compiling several files either into several

1202

assembler input files, or into one assembler input file; then each

1203

assembler input file produces an object file, and linking combines all

1204

the object files (those newly compiled, and those specified as input)

1205

into an executable file.

1206

1207

@cindex file name suffix

1208

For any given input file, the file name suffix determines what kind of

1209

compilation is done:

1210

1211

@table @gcctabopt

1212

@item @var{file}.c

1213

C source code that must be preprocessed.

1214

1215

@item @var{file}.i

1216

C source code that should not be preprocessed.

1217

1218

@item @var{file}.ii

1219

C++ source code that should not be preprocessed.

1220

1221

@item @var{file}.m

1222

Objective-C source code. Note that you must link with the @file{libobjc}

1223

library to make an Objective-C program work.

1224

1225

@item @var{file}.mi

1226

Objective-C source code that should not be preprocessed.

1227

1228

@item @var{file}.mm

1229

@itemx @var{file}.M

1230

Objective-C++ source code. Note that you must link with the @file{libobjc}

1231

library to make an Objective-C++ program work. Note that @samp{.M} refers

1232

to a literal capital M@.

1233

1234

@item @var{file}.mii

1235

Objective-C++ source code that should not be preprocessed.

1236

1237

@item @var{file}.h

1238

C, C++, Objective-C or Objective-C++ header file to be turned into a

1239

precompiled header (default), or C, C++ header file to be turned into an

1240

Ada spec (via the @option{-fdump-ada-spec} switch).

1241

1242

@item @var{file}.cc

1243

@itemx @var{file}.cp

1244

@itemx @var{file}.cxx

1245

@itemx @var{file}.cpp

1246

@itemx @var{file}.CPP

1247

@itemx @var{file}.c++

1248

@itemx @var{file}.C

1249

C++ source code that must be preprocessed. Note that in @samp{.cxx},

1250

the last two letters must both be literally @samp{x}. Likewise,

1251

@samp{.C} refers to a literal capital C@.

1252

1253

@item @var{file}.mm

1254

@itemx @var{file}.M

1255

Objective-C++ source code that must be preprocessed.

1256

1257

@item @var{file}.mii

1258

Objective-C++ source code that should not be preprocessed.

1259

1260

@item @var{file}.hh

1261

@itemx @var{file}.H

1262

@itemx @var{file}.hp

1263

@itemx @var{file}.hxx

1264

@itemx @var{file}.hpp

1265

@itemx @var{file}.HPP

1266

@itemx @var{file}.h++

1267

@itemx @var{file}.tcc

1268

C++ header file to be turned into a precompiled header or Ada spec.

1269

1270

@item @var{file}.f

1271

@itemx @var{file}.for

1272

@itemx @var{file}.ftn

1273

Fixed form Fortran source code that should not be preprocessed.

1274

1275

@item @var{file}.F

1276

@itemx @var{file}.FOR

1277

@itemx @var{file}.fpp

1278

@itemx @var{file}.FPP

1279

@itemx @var{file}.FTN

1280

Fixed form Fortran source code that must be preprocessed (with the traditional

1281

preprocessor).

1282

1283

@item @var{file}.f90

1284

@itemx @var{file}.f95

1285

@itemx @var{file}.f03

1286

@itemx @var{file}.f08

1287

Free form Fortran source code that should not be preprocessed.

1288

1289

@item @var{file}.F90

1290

@itemx @var{file}.F95

1291

@itemx @var{file}.F03

1292

@itemx @var{file}.F08

1293

Free form Fortran source code that must be preprocessed (with the

1294

traditional preprocessor).

1295

1296

@item @var{file}.go

1297

Go source code.

1298

1299

@c FIXME: Descriptions of Java file types.

1300

@c @var{file}.java

1301

@c @var{file}.class

1302

@c @var{file}.zip

1303

@c @var{file}.jar

1304

1305

@item @var{file}.ads

1306

Ada source code file that contains a library unit declaration (a

1307

declaration of a package, subprogram, or generic, or a generic

1308

instantiation), or a library unit renaming declaration (a package,

1309

generic, or subprogram renaming declaration). Such files are also

1310

called @dfn{specs}.

1311

1312

@item @var{file}.adb

1313

Ada source code file containing a library unit body (a subprogram or

1314

package body). Such files are also called @dfn{bodies}.

1315

1316

@c GCC also knows about some suffixes for languages not yet included:

1317

@c Pascal:

1318

@c @var{file}.p

1319

@c @var{file}.pas

1320

@c Ratfor:

1321

@c @var{file}.r

1322

1323

@item @var{file}.s

1324

Assembler code.

1325

1326

@item @var{file}.S

1327

@itemx @var{file}.sx

1328

Assembler code that must be preprocessed.

1329

1330

@item @var{other}

1331

An object file to be fed straight into linking.

1332

Any file name with no recognized suffix is treated this way.

1333

@end table

1334

1335

@opindex x

1336

You can specify the input language explicitly with the @option{-x} option:

1337

1338

@table @gcctabopt

1339

@item -x @var{language}

1340

Specify explicitly the @var{language} for the following input files

1341

(rather than letting the compiler choose a default based on the file

1342

name suffix). This option applies to all following input files until

1343

the next @option{-x} option. Possible values for @var{language} are:

1344

@smallexample

1345

c c-header cpp-output

1346

c++ c++-header c++-cpp-output

1347

objective-c objective-c-header objective-c-cpp-output

1348

objective-c++ objective-c++-header objective-c++-cpp-output

1349

assembler assembler-with-cpp

1350

ada

1351

f77 f77-cpp-input f95 f95-cpp-input

1352

go

1353

java

1354

@end smallexample

1355

1356

@item -x none

1357

Turn off any specification of a language, so that subsequent files are

1358

handled according to their file name suffixes (as they are if @option{-x}

1359

has not been used at all).

1360

@end table

1361

1362

If you only want some of the stages of compilation, you can use

1363

@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and

1364

one of the options @option{-c}, @option{-S}, or @option{-E} to say where

1365

@command{gcc} is to stop. Note that some combinations (for example,

1366

@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.

1367

1368

@table @gcctabopt

1369

@item -c

1370

@opindex c

1371

Compile or assemble the source files, but do not link. The linking

1372

stage simply is not done. The ultimate output is in the form of an

1373

object file for each source file.

1374

1375

By default, the object file name for a source file is made by replacing

1376

the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.

1377

1378

Unrecognized input files, not requiring compilation or assembly, are

1379

ignored.

1380

1381

@item -S

1382

@opindex S

1383

Stop after the stage of compilation proper; do not assemble. The output

1384

is in the form of an assembler code file for each non-assembler input

1385

file specified.

1386

1387

By default, the assembler file name for a source file is made by

1388

replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.

1389

1390

Input files that don't require compilation are ignored.

1391

1392

@item -E

1393

@opindex E

1394

Stop after the preprocessing stage; do not run the compiler proper. The

1395

output is in the form of preprocessed source code, which is sent to the

1396

standard output.

1397

1398

Input files that don't require preprocessing are ignored.

1399

1400

@cindex output file option

1401

@item -o @var{file}

1402

@opindex o

1403

Place output in file @var{file}. This applies to whatever

1404

sort of output is being produced, whether it be an executable file,

1405

an object file, an assembler file or preprocessed C code.

1406

1407

If @option{-o} is not specified, the default is to put an executable

1408

file in @file{a.out}, the object file for

1409

@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its

1410

assembler file in @file{@var{source}.s}, a precompiled header file in

1411

@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on

1412

standard output.

1413

1414

@item -v

1415

@opindex v

1416

Print (on standard error output) the commands executed to run the stages

1417

of compilation. Also print the version number of the compiler driver

1418

program and of the preprocessor and the compiler proper.

1419

1420

@item -###

1421

@opindex ###

1422

Like @option{-v} except the commands are not executed and arguments

1423

are quoted unless they contain only alphanumeric characters or @code{./-_}.

1424

This is useful for shell scripts to capture the driver-generated command lines.

1425

1426

@item --help

1427

@opindex help

1428

Print (on the standard output) a description of the command-line options

1429

understood by @command{gcc}. If the @option{-v} option is also specified

1430

then @option{--help} is also passed on to the various processes

1431

invoked by @command{gcc}, so that they can display the command-line options

1432

they accept. If the @option{-Wextra} option has also been specified

1433

(prior to the @option{--help} option), then command-line options that

1434

have no documentation associated with them are also displayed.

1435

1436

@item --target-help

1437

@opindex target-help

1438

Print (on the standard output) a description of target-specific command-line

1439

options for each tool. For some targets extra target-specific

1440

information may also be printed.

1441

1442

@item --help=@{@var{class}@r{|[}^@r{]}@var{qualifier}@}@r{[},@dots{}@r{]}

1443

Print (on the standard output) a description of the command-line

1444

options understood by the compiler that fit into all specified classes

1445

and qualifiers. These are the supported classes:

1446

1447

@table @asis

1448

@item @samp{optimizers}

1449

Display all of the optimization options supported by the

1450

compiler.

1451

1452

@item @samp{warnings}

1453

Display all of the options controlling warning messages

1454

produced by the compiler.

1455

1456

@item @samp{target}

1457

Display target-specific options. Unlike the

1458

@option{--target-help} option however, target-specific options of the

1459

linker and assembler are not displayed. This is because those

1460

tools do not currently support the extended @option{--help=} syntax.

1461

1462

@item @samp{params}

1463

Display the values recognized by the @option{--param}

1464

option.

1465

1466

@item @var{language}

1467

Display the options supported for @var{language}, where

1468

@var{language} is the name of one of the languages supported in this

1469

version of GCC@.

1470

1471

@item @samp{common}

1472

Display the options that are common to all languages.

1473

@end table

1474

1475

These are the supported qualifiers:

1476

1477

@table @asis

1478

@item @samp{undocumented}

1479

Display only those options that are undocumented.

1480

1481

@item @samp{joined}

1482

Display options taking an argument that appears after an equal

1483

sign in the same continuous piece of text, such as:

1484

@samp{--help=target}.

1485

1486

@item @samp{separate}

1487

Display options taking an argument that appears as a separate word

1488

following the original option, such as: @samp{-o output-file}.

1489

@end table

1490

1491

Thus for example to display all the undocumented target-specific

1492

switches supported by the compiler, use:

1493

1494

@smallexample

1495

--help=target,undocumented

1496

@end smallexample

1497

1498

The sense of a qualifier can be inverted by prefixing it with the

1499

@samp{^} character, so for example to display all binary warning

1500

options (i.e., ones that are either on or off and that do not take an

1501

argument) that have a description, use:

1502

1503

@smallexample

1504

--help=warnings,^joined,^undocumented

1505

@end smallexample

1506

1507

The argument to @option{--help=} should not consist solely of inverted

1508

qualifiers.

1509

1510

Combining several classes is possible, although this usually

1511

restricts the output so much that there is nothing to display. One

1512

case where it does work, however, is when one of the classes is

1513

@var{target}. For example, to display all the target-specific

1514

optimization options, use:

1515

1516

@smallexample

1517

--help=target,optimizers

1518

@end smallexample

1519

1520

The @option{--help=} option can be repeated on the command line. Each

1521

successive use displays its requested class of options, skipping

1522

those that have already been displayed.

1523

1524

If the @option{-Q} option appears on the command line before the

1525

@option{--help=} option, then the descriptive text displayed by

1526

@option{--help=} is changed. Instead of describing the displayed

1527

options, an indication is given as to whether the option is enabled,

1528

disabled or set to a specific value (assuming that the compiler

1529

knows this at the point where the @option{--help=} option is used).

1530

1531

Here is a truncated example from the ARM port of @command{gcc}:

1532

1533

@smallexample

1534

% gcc -Q -mabi=2 --help=target -c

1535

The following options are target specific:

1536

-mabi= 2

1537

-mabort-on-noreturn [disabled]

1538

-mapcs [disabled]

1539

@end smallexample

1540

1541

The output is sensitive to the effects of previous command-line

1542

options, so for example it is possible to find out which optimizations

1543

are enabled at @option{-O2} by using:

1544

1545

@smallexample

1546

-Q -O2 --help=optimizers

1547

@end smallexample

1548

1549

Alternatively you can discover which binary optimizations are enabled

1550

by @option{-O3} by using:

1551

1552

@smallexample

1553

gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts

1554

gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts

1555

diff /tmp/O2-opts /tmp/O3-opts | grep enabled

1556

@end smallexample

1557

1558

@item --version

1559

@opindex version

1560

Display the version number and copyrights of the invoked GCC@.

1561

1562

@item -pass-exit-codes

1563

@opindex pass-exit-codes

1564

Normally the @command{gcc} program exits with the code of 1 if any

1565

phase of the compiler returns a non-success return code. If you specify

1566

@option{-pass-exit-codes}, the @command{gcc} program instead returns with

1567

the numerically highest error produced by any phase returning an error

1568

indication. The C, C++, and Fortran front ends return 4 if an internal

1569

compiler error is encountered.

1570

1571

@item -pipe

1572

@opindex pipe

1573

Use pipes rather than temporary files for communication between the

1574

various stages of compilation. This fails to work on some systems where

1575

the assembler is unable to read from a pipe; but the GNU assembler has

1576

no trouble.

1577

1578

@item -specs=@var{file}

1579

@opindex specs

1580

Process @var{file} after the compiler reads in the standard @file{specs}

1581

file, in order to override the defaults which the @command{gcc} driver

1582

program uses when determining what switches to pass to @command{cc1},

1583

@command{cc1plus}, @command{as}, @command{ld}, etc. More than one

1584

@option{-specs=@var{file}} can be specified on the command line, and they

1585

are processed in order, from left to right. @xref{Spec Files}, for

1586

information about the format of the @var{file}.

1587

1588

@item -wrapper

1589

@opindex wrapper

1590

Invoke all subcommands under a wrapper program. The name of the

1591

wrapper program and its parameters are passed as a comma separated

1592

list.

1593

1594

@smallexample

1595

gcc -c t.c -wrapper gdb,--args

1596

@end smallexample

1597

1598

@noindent

1599

This invokes all subprograms of @command{gcc} under

1600

@samp{gdb --args}, thus the invocation of @command{cc1} is

1601

@samp{gdb --args cc1 @dots{}}.

1602

1603

@item -fplugin=@var{name}.so

1604

@opindex fplugin

1605

Load the plugin code in file @var{name}.so, assumed to be a

1606

shared object to be dlopen'd by the compiler. The base name of

1607

the shared object file is used to identify the plugin for the

1608

purposes of argument parsing (See

1609

@option{-fplugin-arg-@var{name}-@var{key}=@var{value}} below).

1610

Each plugin should define the callback functions specified in the

1611

Plugins API.

1612

1613

@item -fplugin-arg-@var{name}-@var{key}=@var{value}

1614

@opindex fplugin-arg

1615

Define an argument called @var{key} with a value of @var{value}

1616

for the plugin called @var{name}.

1617

1618

@item -fdump-ada-spec@r{[}-slim@r{]}

1619

@opindex fdump-ada-spec

1620

For C and C++ source and include files, generate corresponding Ada specs.

1621

@xref{Generating Ada Bindings for C and C++ headers,,, gnat_ugn,

1622

GNAT User's Guide}, which provides detailed documentation on this feature.

1623

1624

@item -fada-spec-parent=@var{unit}

1625

@opindex fada-spec-parent

1626

In conjunction with @option{-fdump-ada-spec@r{[}-slim@r{]}} above, generate

1627

Ada specs as child units of parent @var{unit}.

1628

1629

@item -fdump-go-spec=@var{file}

1630

@opindex fdump-go-spec

1631

For input files in any language, generate corresponding Go

1632

declarations in @var{file}. This generates Go @code{const},

1633

@code{type}, @code{var}, and @code{func} declarations which may be a

1634

useful way to start writing a Go interface to code written in some

1635

other language.

1636

1637

@include @value{srcdir}/../libiberty/at-file.texi

1638

@end table

1639

1640

@node Invoking G++

1641

@section Compiling C++ Programs

1642

1643

@cindex suffixes for C++ source

1644

@cindex C++ source file suffixes

1645

C++ source files conventionally use one of the suffixes @samp{.C},

1646

@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or

1647

@samp{.cxx}; C++ header files often use @samp{.hh}, @samp{.hpp},

1648

@samp{.H}, or (for shared template code) @samp{.tcc}; and

1649

preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes

1650

files with these names and compiles them as C++ programs even if you

1651

call the compiler the same way as for compiling C programs (usually

1652

with the name @command{gcc}).

1653

1654

@findex g++

1655

@findex c++

1656

However, the use of @command{gcc} does not add the C++ library.

1657

@command{g++} is a program that calls GCC and automatically specifies linking

1658

against the C++ library. It treats @samp{.c},

1659

@samp{.h} and @samp{.i} files as C++ source files instead of C source

1660

files unless @option{-x} is used. This program is also useful when

1661

precompiling a C header file with a @samp{.h} extension for use in C++

1662

compilations. On many systems, @command{g++} is also installed with

1663

the name @command{c++}.

1664

1665

@cindex invoking @command{g++}

1666

When you compile C++ programs, you may specify many of the same

1667

command-line options that you use for compiling programs in any

1668

language; or command-line options meaningful for C and related

1669

languages; or options that are meaningful only for C++ programs.

1670

@xref{C Dialect Options,,Options Controlling C Dialect}, for

1671

explanations of options for languages related to C@.

1672

@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for

1673

explanations of options that are meaningful only for C++ programs.

1674

1675

@node C Dialect Options

1676

@section Options Controlling C Dialect

1677

@cindex dialect options

1678

@cindex language dialect options

1679

@cindex options, dialect

1680

1681

The following options control the dialect of C (or languages derived

1682

from C, such as C++, Objective-C and Objective-C++) that the compiler

1683

accepts:

1684

1685

@table @gcctabopt

1686

@cindex ANSI support

1687

@cindex ISO support

1688

@item -ansi

1689

@opindex ansi

1690

In C mode, this is equivalent to @option{-std=c90}. In C++ mode, it is

1691

equivalent to @option{-std=c++98}.

1692

1693

This turns off certain features of GCC that are incompatible with ISO

1694

C90 (when compiling C code), or of standard C++ (when compiling C++ code),

1695

such as the @code{asm} and @code{typeof} keywords, and

1696

predefined macros such as @code{unix} and @code{vax} that identify the

1697

type of system you are using. It also enables the undesirable and

1698

rarely used ISO trigraph feature. For the C compiler,

1699

it disables recognition of C++ style @samp{//} comments as well as

1700

the @code{inline} keyword.

1701

1702

The alternate keywords @code{__asm__}, @code{__extension__},

1703

@code{__inline__} and @code{__typeof__} continue to work despite

1704

@option{-ansi}. You would not want to use them in an ISO C program, of

1705

course, but it is useful to put them in header files that might be included

1706

in compilations done with @option{-ansi}. Alternate predefined macros

1707

such as @code{__unix__} and @code{__vax__} are also available, with or

1708

without @option{-ansi}.

1709

1710

The @option{-ansi} option does not cause non-ISO programs to be

1711

rejected gratuitously. For that, @option{-Wpedantic} is required in

1712

addition to @option{-ansi}. @xref{Warning Options}.

1713

1714

The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}

1715

option is used. Some header files may notice this macro and refrain

1716

from declaring certain functions or defining certain macros that the

1717

ISO standard doesn't call for; this is to avoid interfering with any

1718

programs that might use these names for other things.

1719

1720

Functions that are normally built in but do not have semantics

1721

defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in

1722

functions when @option{-ansi} is used. @xref{Other Builtins,,Other

1723

built-in functions provided by GCC}, for details of the functions

1724

affected.

1725

1726

@item -std=

1727

@opindex std

1728

Determine the language standard. @xref{Standards,,Language Standards

1729

Supported by GCC}, for details of these standard versions. This option

1730

is currently only supported when compiling C or C++.

1731

1732

The compiler can accept several base standards, such as @samp{c90} or

1733

@samp{c++98}, and GNU dialects of those standards, such as

1734

@samp{gnu90} or @samp{gnu++98}. When a base standard is specified, the

1735

compiler accepts all programs following that standard plus those

1736

using GNU extensions that do not contradict it. For example,

1737

@option{-std=c90} turns off certain features of GCC that are

1738

incompatible with ISO C90, such as the @code{asm} and @code{typeof}

1739

keywords, but not other GNU extensions that do not have a meaning in

1740

ISO C90, such as omitting the middle term of a @code{?:}

1741

expression. On the other hand, when a GNU dialect of a standard is

1742

specified, all features supported by the compiler are enabled, even when

1743

those features change the meaning of the base standard. As a result, some

1744

strict-conforming programs may be rejected. The particular standard

1745

is used by @option{-Wpedantic} to identify which features are GNU

1746

extensions given that version of the standard. For example

1747

@option{-std=gnu90 -Wpedantic} warns about C++ style @samp{//}

1748

comments, while @option{-std=gnu99 -Wpedantic} does not.

1749

1750

A value for this option must be provided; possible values are

1751

1752

@table @samp

1753

@item c90

1754

@itemx c89

1755

@itemx iso9899:1990

1756

Support all ISO C90 programs (certain GNU extensions that conflict

1757

with ISO C90 are disabled). Same as @option{-ansi} for C code.

1758

1759

@item iso9899:199409

1760

ISO C90 as modified in amendment 1.

1761

1762

@item c99

1763

@itemx c9x

1764

@itemx iso9899:1999

1765

@itemx iso9899:199x

1766

ISO C99. This standard is substantially completely supported, modulo

1767

bugs and floating-point issues

1768

(mainly but not entirely relating to optional C99 features from

1769

Annexes F and G). See

1770

@w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The

1771

names @samp{c9x} and @samp{iso9899:199x} are deprecated.

1772

1773

@item c11

1774

@itemx c1x

1775

@itemx iso9899:2011

1776

ISO C11, the 2011 revision of the ISO C standard. This standard is

1777

substantially completely supported, modulo bugs, floating-point issues

1778

(mainly but not entirely relating to optional C11 features from

1779

Annexes F and G) and the optional Annexes K (Bounds-checking

1780

interfaces) and L (Analyzability). The name @samp{c1x} is deprecated.

1781

1782

@item gnu90

1783

@itemx gnu89

1784

GNU dialect of ISO C90 (including some C99 features).

1785

1786

@item gnu99

1787

@itemx gnu9x

1788

GNU dialect of ISO C99. The name @samp{gnu9x} is deprecated.

1789

1790

@item gnu11

1791

@itemx gnu1x

1792

GNU dialect of ISO C11. This is the default for C code.

1793

The name @samp{gnu1x} is deprecated.

1794

1795

@item c++98

1796

@itemx c++03

1797

The 1998 ISO C++ standard plus the 2003 technical corrigendum and some

1798

additional defect reports. Same as @option{-ansi} for C++ code.

1799

1800

@item gnu++98

1801

@itemx gnu++03

1802

GNU dialect of @option{-std=c++98}.

1803

1804

@item c++11

1805

@itemx c++0x

1806

The 2011 ISO C++ standard plus amendments.

1807

The name @samp{c++0x} is deprecated.

1808

1809

@item gnu++11

1810

@itemx gnu++0x

1811

GNU dialect of @option{-std=c++11}.

1812

The name @samp{gnu++0x} is deprecated.

1813

1814

@item c++14

1815

@itemx c++1y

1816

The 2014 ISO C++ standard plus amendments.

1817

The name @samp{c++1y} is deprecated.

1818

1819

@item gnu++14

1820

@itemx gnu++1y

1821

GNU dialect of @option{-std=c++14}.

1822

This is the default for C++ code.

1823

The name @samp{gnu++1y} is deprecated.

1824

1825

@item c++1z

1826

The next revision of the ISO C++ standard, tentatively planned for

1827

2017. Support is highly experimental, and will almost certainly

1828

change in incompatible ways in future releases.

1829

1830

@item gnu++1z

1831

GNU dialect of @option{-std=c++1z}. Support is highly experimental,

1832

and will almost certainly change in incompatible ways in future

1833

releases.

1834

@end table

1835

1836

@item -fgnu89-inline

1837

@opindex fgnu89-inline

1838

The option @option{-fgnu89-inline} tells GCC to use the traditional

1839

GNU semantics for @code{inline} functions when in C99 mode.

1840

@xref{Inline,,An Inline Function is As Fast As a Macro}.

1841

Using this option is roughly equivalent to adding the

1842

@code{gnu_inline} function attribute to all inline functions

1843

(@pxref{Function Attributes}).

1844

1845

The option @option{-fno-gnu89-inline} explicitly tells GCC to use the

1846

C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it

1847

specifies the default behavior).

1848

This option is not supported in @option{-std=c90} or

1849

@option{-std=gnu90} mode.

1850

1851

The preprocessor macros @code{__GNUC_GNU_INLINE__} and

1852

@code{__GNUC_STDC_INLINE__} may be used to check which semantics are

1853

in effect for @code{inline} functions. @xref{Common Predefined

1854

Macros,,,cpp,The C Preprocessor}.

1855

1856

@item -aux-info @var{filename}

1857

@opindex aux-info

1858

Output to the given filename prototyped declarations for all functions

1859

declared and/or defined in a translation unit, including those in header

1860

files. This option is silently ignored in any language other than C@.

1861

1862

Besides declarations, the file indicates, in comments, the origin of

1863

each declaration (source file and line), whether the declaration was

1864

implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or

1865

@samp{O} for old, respectively, in the first character after the line

1866

number and the colon), and whether it came from a declaration or a

1867

definition (@samp{C} or @samp{F}, respectively, in the following

1868

character). In the case of function definitions, a K&R-style list of

1869

arguments followed by their declarations is also provided, inside

1870

comments, after the declaration.

1871

1872

@item -fallow-parameterless-variadic-functions

1873

@opindex fallow-parameterless-variadic-functions

1874

Accept variadic functions without named parameters.

1875

1876

Although it is possible to define such a function, this is not very

1877

useful as it is not possible to read the arguments. This is only

1878

supported for C as this construct is allowed by C++.

1879

1880

@item -fno-asm

1881

@opindex fno-asm

1882

Do not recognize @code{asm}, @code{inline} or @code{typeof} as a

1883

keyword, so that code can use these words as identifiers. You can use

1884

the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}

1885

instead. @option{-ansi} implies @option{-fno-asm}.

1886

1887

In C++, this switch only affects the @code{typeof} keyword, since

1888

@code{asm} and @code{inline} are standard keywords. You may want to

1889

use the @option{-fno-gnu-keywords} flag instead, which has the same

1890

effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this

1891

switch only affects the @code{asm} and @code{typeof} keywords, since

1892

@code{inline} is a standard keyword in ISO C99.

1893

1894

@item -fno-builtin

1895

@itemx -fno-builtin-@var{function}

1896

@opindex fno-builtin

1897

@cindex built-in functions

1898

Don't recognize built-in functions that do not begin with

1899

@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in

1900

functions provided by GCC}, for details of the functions affected,

1901

including those which are not built-in functions when @option{-ansi} or

1902

@option{-std} options for strict ISO C conformance are used because they

1903

do not have an ISO standard meaning.

1904

1905

GCC normally generates special code to handle certain built-in functions

1906

more efficiently; for instance, calls to @code{alloca} may become single

1907

instructions which adjust the stack directly, and calls to @code{memcpy}

1908

may become inline copy loops. The resulting code is often both smaller

1909

and faster, but since the function calls no longer appear as such, you

1910

cannot set a breakpoint on those calls, nor can you change the behavior

1911

of the functions by linking with a different library. In addition,

1912

when a function is recognized as a built-in function, GCC may use

1913

information about that function to warn about problems with calls to

1914

that function, or to generate more efficient code, even if the

1915

resulting code still contains calls to that function. For example,

1916

warnings are given with @option{-Wformat} for bad calls to

1917

@code{printf} when @code{printf} is built in and @code{strlen} is

1918

known not to modify global memory.

1919

1920

With the @option{-fno-builtin-@var{function}} option

1921

only the built-in function @var{function} is

1922

disabled. @var{function} must not begin with @samp{__builtin_}. If a

1923

function is named that is not built-in in this version of GCC, this

1924

option is ignored. There is no corresponding

1925

@option{-fbuiltin-@var{function}} option; if you wish to enable

1926

built-in functions selectively when using @option{-fno-builtin} or

1927

@option{-ffreestanding}, you may define macros such as:

1928

1929

@smallexample

1930

#define abs(n) __builtin_abs ((n))

1931

#define strcpy(d, s) __builtin_strcpy ((d), (s))

1932

@end smallexample

1933

1934

@item -fhosted

1935

@opindex fhosted

1936

@cindex hosted environment

1937

1938

Assert that compilation targets a hosted environment. This implies

1939

@option{-fbuiltin}. A hosted environment is one in which the

1940

entire standard library is available, and in which @code{main} has a return

1941

type of @code{int}. Examples are nearly everything except a kernel.

1942

This is equivalent to @option{-fno-freestanding}.

1943

1944

@item -ffreestanding

1945

@opindex ffreestanding

1946

@cindex hosted environment

1947

1948

Assert that compilation targets a freestanding environment. This

1949

implies @option{-fno-builtin}. A freestanding environment

1950

is one in which the standard library may not exist, and program startup may

1951

not necessarily be at @code{main}. The most obvious example is an OS kernel.

1952

This is equivalent to @option{-fno-hosted}.

1953

1954

@xref{Standards,,Language Standards Supported by GCC}, for details of

1955

freestanding and hosted environments.

1956

1957

@item -fopenacc

1958

@opindex fopenacc

1959

@cindex OpenACC accelerator programming

1960

Enable handling of OpenACC directives @code{#pragma acc} in C/C++ and

1961

@code{!$acc} in Fortran. When @option{-fopenacc} is specified, the

1962

compiler generates accelerated code according to the OpenACC Application

1963

Programming Interface v2.0 @w{@uref{http://www.openacc.org/}}. This option

1964

implies @option{-pthread}, and thus is only supported on targets that

1965

have support for @option{-pthread}.

1966

1967

@item -fopenacc-dim=@var{geom}

1968

@opindex fopenacc-dim

1969

@cindex OpenACC accelerator programming

1970

Specify default compute dimensions for parallel offload regions that do

1971

not explicitly specify. The @var{geom} value is a triple of

1972

':'-separated sizes, in order 'gang', 'worker' and, 'vector'. A size

1973

can be omitted, to use a target-specific default value.

1974

1975

@item -fopenmp

1976

@opindex fopenmp

1977

@cindex OpenMP parallel

1978

Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and

1979

@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the

1980

compiler generates parallel code according to the OpenMP Application

1981

Program Interface v4.0 @w{@uref{http://www.openmp.org/}}. This option

1982

implies @option{-pthread}, and thus is only supported on targets that

1983

have support for @option{-pthread}. @option{-fopenmp} implies

1984

@option{-fopenmp-simd}.

1985

1986

@item -fopenmp-simd

1987

@opindex fopenmp-simd

1988

@cindex OpenMP SIMD

1989

@cindex SIMD

1990

Enable handling of OpenMP's SIMD directives with @code{#pragma omp}

1991

in C/C++ and @code{!$omp} in Fortran. Other OpenMP directives

1992

are ignored.

1993

1994

@item -fcilkplus

1995

@opindex fcilkplus

1996

@cindex Enable Cilk Plus

1997

Enable the usage of Cilk Plus language extension features for C/C++.

1998

When the option @option{-fcilkplus} is specified, enable the usage of

1999

the Cilk Plus Language extension features for C/C++. The present

2000

implementation follows ABI version 1.2. This is an experimental

2001

feature that is only partially complete, and whose interface may

2002

change in future versions of GCC as the official specification

2003

changes. Currently, all features but @code{_Cilk_for} have been

2004

implemented.

2005

2006

@item -fgnu-tm

2007

@opindex fgnu-tm

2008

When the option @option{-fgnu-tm} is specified, the compiler

2009

generates code for the Linux variant of Intel's current Transactional

2010

Memory ABI specification document (Revision 1.1, May 6 2009). This is

2011

an experimental feature whose interface may change in future versions

2012

of GCC, as the official specification changes. Please note that not

2013

all architectures are supported for this feature.

2014

2015

For more information on GCC's support for transactional memory,

2016

@xref{Enabling libitm,,The GNU Transactional Memory Library,libitm,GNU

2017

Transactional Memory Library}.

2018

2019

Note that the transactional memory feature is not supported with

2020

non-call exceptions (@option{-fnon-call-exceptions}).

2021

2022

@item -fms-extensions

2023

@opindex fms-extensions

2024

Accept some non-standard constructs used in Microsoft header files.

2025

2026

In C++ code, this allows member names in structures to be similar

2027

to previous types declarations.

2028

2029

@smallexample

2030

typedef int UOW;

2031

struct ABC @{

2032

UOW UOW;

2033

@};

2034

@end smallexample

2035

2036

Some cases of unnamed fields in structures and unions are only

2037

accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union

2038

fields within structs/unions}, for details.

2039

2040

Note that this option is off for all targets but x86

2041

targets using ms-abi.

2042

2043

@item -fplan9-extensions

2044

@opindex fplan9-extensions

2045

Accept some non-standard constructs used in Plan 9 code.

2046

2047

This enables @option{-fms-extensions}, permits passing pointers to

2048

structures with anonymous fields to functions that expect pointers to

2049

elements of the type of the field, and permits referring to anonymous

2050

fields declared using a typedef. @xref{Unnamed Fields,,Unnamed

2051

struct/union fields within structs/unions}, for details. This is only

2052

supported for C, not C++.

2053

2054

@item -trigraphs

2055

@opindex trigraphs

2056

Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}

2057

options for strict ISO C conformance) implies @option{-trigraphs}.

2058

2059

@cindex traditional C language

2060

@cindex C language, traditional

2061

@item -traditional

2062

@itemx -traditional-cpp

2063

@opindex traditional-cpp

2064

@opindex traditional

2065

Formerly, these options caused GCC to attempt to emulate a pre-standard

2066

C compiler. They are now only supported with the @option{-E} switch.

2067

The preprocessor continues to support a pre-standard mode. See the GNU

2068

CPP manual for details.

2069

2070

@item -fcond-mismatch

2071

@opindex fcond-mismatch

2072

Allow conditional expressions with mismatched types in the second and

2073

third arguments. The value of such an expression is void. This option

2074

is not supported for C++.

2075

2076

@item -flax-vector-conversions

2077

@opindex flax-vector-conversions

2078

Allow implicit conversions between vectors with differing numbers of

2079

elements and/or incompatible element types. This option should not be

2080

used for new code.

2081

2082

@item -funsigned-char

2083

@opindex funsigned-char

2084

Let the type @code{char} be unsigned, like @code{unsigned char}.

2085

2086

Each kind of machine has a default for what @code{char} should

2087

be. It is either like @code{unsigned char} by default or like

2088

@code{signed char} by default.

2089

2090

Ideally, a portable program should always use @code{signed char} or

2091

@code{unsigned char} when it depends on the signedness of an object.

2092

But many programs have been written to use plain @code{char} and

2093

expect it to be signed, or expect it to be unsigned, depending on the

2094

machines they were written for. This option, and its inverse, let you

2095

make such a program work with the opposite default.

2096

2097

The type @code{char} is always a distinct type from each of

2098

@code{signed char} or @code{unsigned char}, even though its behavior

2099

is always just like one of those two.

2100

2101

@item -fsigned-char

2102

@opindex fsigned-char

2103

Let the type @code{char} be signed, like @code{signed char}.

2104

2105

Note that this is equivalent to @option{-fno-unsigned-char}, which is

2106

the negative form of @option{-funsigned-char}. Likewise, the option

2107

@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.

2108

2109

@item -fsigned-bitfields

2110

@itemx -funsigned-bitfields

2111

@itemx -fno-signed-bitfields

2112

@itemx -fno-unsigned-bitfields

2113

@opindex fsigned-bitfields

2114

@opindex funsigned-bitfields

2115

@opindex fno-signed-bitfields

2116

@opindex fno-unsigned-bitfields

2117

These options control whether a bit-field is signed or unsigned, when the

2118

declaration does not use either @code{signed} or @code{unsigned}. By

2119

default, such a bit-field is signed, because this is consistent: the

2120

basic integer types such as @code{int} are signed types.

2121

2122

@item -fsso-struct=@var{endianness}

2123

@opindex fsso-struct

2124

Set the default scalar storage order of structures and unions to the

2125

specified endianness. The accepted values are @samp{big-endian} and

2126

@samp{little-endian}. If the option is not passed, the compiler uses

2127

the native endianness of the target. This option is not supported for C++.

2128

2129

@strong{Warning:} the @option{-fsso-struct} switch causes GCC to generate

2130

code that is not binary compatible with code generated without it if the

2131

specified endianness is not the native endianness of the target.

2132

@end table

2133

2134

@node C++ Dialect Options

2135

@section Options Controlling C++ Dialect

2136

2137

@cindex compiler options, C++

2138

@cindex C++ options, command-line

2139

@cindex options, C++

2140

This section describes the command-line options that are only meaningful

2141

for C++ programs. You can also use most of the GNU compiler options

2142

regardless of what language your program is in. For example, you

2143

might compile a file @file{firstClass.C} like this:

2144

2145

@smallexample

2146

g++ -g -fstrict-enums -O -c firstClass.C

2147

@end smallexample

2148

2149

@noindent

2150

In this example, only @option{-fstrict-enums} is an option meant

2151

only for C++ programs; you can use the other options with any

2152

language supported by GCC@.

2153

2154

Some options for compiling C programs, such as @option{-std}, are also

2155

relevant for C++ programs.

2156

@xref{C Dialect Options,,Options Controlling C Dialect}.

2157

2158

Here is a list of options that are @emph{only} for compiling C++ programs:

2159

2160

@table @gcctabopt

2161

2162

@item -fabi-version=@var{n}

2163

@opindex fabi-version

2164

Use version @var{n} of the C++ ABI@. The default is version 0.

2165

2166

Version 0 refers to the version conforming most closely to

2167

the C++ ABI specification. Therefore, the ABI obtained using version 0

2168

will change in different versions of G++ as ABI bugs are fixed.

2169

2170

Version 1 is the version of the C++ ABI that first appeared in G++ 3.2.

2171

2172

Version 2 is the version of the C++ ABI that first appeared in G++

2173

3.4, and was the default through G++ 4.9.

2174

2175

Version 3 corrects an error in mangling a constant address as a

2176

template argument.

2177

2178

Version 4, which first appeared in G++ 4.5, implements a standard

2179

mangling for vector types.

2180

2181

Version 5, which first appeared in G++ 4.6, corrects the mangling of

2182

attribute const/volatile on function pointer types, decltype of a

2183

plain decl, and use of a function parameter in the declaration of

2184

another parameter.

2185

2186

Version 6, which first appeared in G++ 4.7, corrects the promotion

2187

behavior of C++11 scoped enums and the mangling of template argument

2188

packs, const/static_cast, prefix ++ and --, and a class scope function

2189

used as a template argument.

2190

2191

Version 7, which first appeared in G++ 4.8, that treats nullptr_t as a

2192

builtin type and corrects the mangling of lambdas in default argument

2193

scope.

2194

2195

Version 8, which first appeared in G++ 4.9, corrects the substitution

2196

behavior of function types with function-cv-qualifiers.

2197

2198

Version 9, which first appeared in G++ 5.2, corrects the alignment of

2199

@code{nullptr_t}.

2200

2201

Version 10, which first appeared in G++ 6.1, adds mangling of

2202

attributes that affect type identity, such as ia32 calling convention

2203

attributes (e.g. @samp{stdcall}).

2204

2205

See also @option{-Wabi}.

2206

2207

@item -fabi-compat-version=@var{n}

2208

@opindex fabi-compat-version

2209

On targets that support strong aliases, G++

2210

works around mangling changes by creating an alias with the correct

2211

mangled name when defining a symbol with an incorrect mangled name.

2212

This switch specifies which ABI version to use for the alias.

2213

2214

With @option{-fabi-version=0} (the default), this defaults to 8 (GCC 5

2215

compatibility). If another ABI version is explicitly selected, this

2216

defaults to 0. For compatibility with GCC versions 3.2 through 4.9,

2217

use @option{-fabi-compat-version=2}.

2218

2219

If this option is not provided but @option{-Wabi=@var{n}} is, that

2220

version is used for compatibility aliases. If this option is provided

2221

along with @option{-Wabi} (without the version), the version from this

2222

option is used for the warning.

2223

2224

@item -fno-access-control

2225

@opindex fno-access-control

2226

Turn off all access checking. This switch is mainly useful for working

2227

around bugs in the access control code.

2228

2229

@item -fcheck-new

2230

@opindex fcheck-new

2231

Check that the pointer returned by @code{operator new} is non-null

2232

before attempting to modify the storage allocated. This check is

2233

normally unnecessary because the C++ standard specifies that

2234

@code{operator new} only returns @code{0} if it is declared

2235

@code{throw()}, in which case the compiler always checks the

2236

return value even without this option. In all other cases, when

2237

@code{operator new} has a non-empty exception specification, memory

2238

exhaustion is signalled by throwing @code{std::bad_alloc}. See also

2239

@samp{new (nothrow)}.

2240

2241

@item -fconcepts

2242

@opindex fconcepts

2243

Enable support for the C++ Extensions for Concepts Technical

2244

Specification, ISO 19217 (2015), which allows code like

2245

2246

@smallexample

2247

template <class T> concept bool Addable = requires (T t) @{ t + t; @};

2248

template <Addable T> T add (T a, T b) @{ return a + b; @}

2249

@end smallexample

2250

2251

@item -fconstexpr-depth=@var{n}

2252

@opindex fconstexpr-depth

2253

Set the maximum nested evaluation depth for C++11 constexpr functions

2254

to @var{n}. A limit is needed to detect endless recursion during

2255

constant expression evaluation. The minimum specified by the standard

2256

is 512.

2257

2258

@item -fdeduce-init-list

2259

@opindex fdeduce-init-list

2260

Enable deduction of a template type parameter as

2261

@code{std::initializer_list} from a brace-enclosed initializer list, i.e.@:

2262

2263

@smallexample

2264

template <class T> auto forward(T t) -> decltype (realfn (t))

2265

@{

2266

return realfn (t);

2267

@}

2268

2269

void f()

2270

@{

2271

forward(@{1,2@}); // call forward<std::initializer_list<int>>

2272

@}

2273

@end smallexample

2274

2275

This deduction was implemented as a possible extension to the

2276

originally proposed semantics for the C++11 standard, but was not part

2277

of the final standard, so it is disabled by default. This option is

2278

deprecated, and may be removed in a future version of G++.

2279

2280

@item -ffriend-injection

2281

@opindex ffriend-injection

2282

Inject friend functions into the enclosing namespace, so that they are

2283

visible outside the scope of the class in which they are declared.

2284

Friend functions were documented to work this way in the old Annotated

2285

C++ Reference Manual.

2286

However, in ISO C++ a friend function that is not declared

2287

in an enclosing scope can only be found using argument dependent

2288

lookup. GCC defaults to the standard behavior.

2289

2290

This option is for compatibility, and may be removed in a future

2291

release of G++.

2292

2293

@item -fno-elide-constructors

2294

@opindex fno-elide-constructors

2295

The C++ standard allows an implementation to omit creating a temporary

2296

that is only used to initialize another object of the same type.

2297

Specifying this option disables that optimization, and forces G++ to

2298

call the copy constructor in all cases.

2299

2300

@item -fno-enforce-eh-specs

2301

@opindex fno-enforce-eh-specs

2302

Don't generate code to check for violation of exception specifications

2303

at run time. This option violates the C++ standard, but may be useful

2304

for reducing code size in production builds, much like defining

2305

@code{NDEBUG}. This does not give user code permission to throw

2306

exceptions in violation of the exception specifications; the compiler

2307

still optimizes based on the specifications, so throwing an

2308

unexpected exception results in undefined behavior at run time.

2309

2310

@item -fextern-tls-init

2311

@itemx -fno-extern-tls-init

2312

@opindex fextern-tls-init

2313

@opindex fno-extern-tls-init

2314

The C++11 and OpenMP standards allow @code{thread_local} and

2315

@code{threadprivate} variables to have dynamic (runtime)

2316

initialization. To support this, any use of such a variable goes

2317

through a wrapper function that performs any necessary initialization.

2318

When the use and definition of the variable are in the same

2319

translation unit, this overhead can be optimized away, but when the

2320

use is in a different translation unit there is significant overhead

2321

even if the variable doesn't actually need dynamic initialization. If

2322

the programmer can be sure that no use of the variable in a

2323

non-defining TU needs to trigger dynamic initialization (either

2324

because the variable is statically initialized, or a use of the

2325

variable in the defining TU will be executed before any uses in

2326

another TU), they can avoid this overhead with the

2327

@option{-fno-extern-tls-init} option.

2328

2329

On targets that support symbol aliases, the default is

2330

@option{-fextern-tls-init}. On targets that do not support symbol

2331

aliases, the default is @option{-fno-extern-tls-init}.

2332

2333

@item -ffor-scope

2334

@itemx -fno-for-scope

2335

@opindex ffor-scope

2336

@opindex fno-for-scope

2337

If @option{-ffor-scope} is specified, the scope of variables declared in

2338

a @i{for-init-statement} is limited to the @code{for} loop itself,

2339

as specified by the C++ standard.

2340

If @option{-fno-for-scope} is specified, the scope of variables declared in

2341

a @i{for-init-statement} extends to the end of the enclosing scope,

2342

as was the case in old versions of G++, and other (traditional)

2343

implementations of C++.

2344

2345

If neither flag is given, the default is to follow the standard,

2346

but to allow and give a warning for old-style code that would

2347

otherwise be invalid, or have different behavior.

2348

2349

@item -fno-gnu-keywords

2350

@opindex fno-gnu-keywords

2351

Do not recognize @code{typeof} as a keyword, so that code can use this

2352

word as an identifier. You can use the keyword @code{__typeof__} instead.

2353

This option is implied by the strict ISO C++ dialects: @option{-ansi},

2354

@option{-std=c++98}, @option{-std=c++11}, etc.

2355

2356

@item -fno-implicit-templates

2357

@opindex fno-implicit-templates

2358

Never emit code for non-inline templates that are instantiated

2359

implicitly (i.e.@: by use); only emit code for explicit instantiations.

2360

@xref{Template Instantiation}, for more information.

2361

2362

@item -fno-implicit-inline-templates

2363

@opindex fno-implicit-inline-templates

2364

Don't emit code for implicit instantiations of inline templates, either.

2365

The default is to handle inlines differently so that compiles with and

2366

without optimization need the same set of explicit instantiations.

2367

2368

@item -fno-implement-inlines

2369

@opindex fno-implement-inlines

2370

To save space, do not emit out-of-line copies of inline functions

2371

controlled by @code{#pragma implementation}. This causes linker

2372

errors if these functions are not inlined everywhere they are called.

2373

2374

@item -fms-extensions

2375

@opindex fms-extensions

2376

Disable Wpedantic warnings about constructs used in MFC, such as implicit

2377

int and getting a pointer to member function via non-standard syntax.

2378

2379

@item -fno-nonansi-builtins

2380

@opindex fno-nonansi-builtins

2381

Disable built-in declarations of functions that are not mandated by

2382

ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},

2383

@code{index}, @code{bzero}, @code{conjf}, and other related functions.

2384

2385

@item -fnothrow-opt

2386

@opindex fnothrow-opt

2387

Treat a @code{throw()} exception specification as if it were a

2388

@code{noexcept} specification to reduce or eliminate the text size

2389

overhead relative to a function with no exception specification. If

2390

the function has local variables of types with non-trivial

2391

destructors, the exception specification actually makes the

2392

function smaller because the EH cleanups for those variables can be

2393

optimized away. The semantic effect is that an exception thrown out of

2394

a function with such an exception specification results in a call

2395

to @code{terminate} rather than @code{unexpected}.

2396

2397

@item -fno-operator-names

2398

@opindex fno-operator-names

2399

Do not treat the operator name keywords @code{and}, @code{bitand},

2400

@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as

2401

synonyms as keywords.

2402

2403

@item -fno-optional-diags

2404

@opindex fno-optional-diags

2405

Disable diagnostics that the standard says a compiler does not need to

2406

issue. Currently, the only such diagnostic issued by G++ is the one for

2407

a name having multiple meanings within a class.

2408

2409

@item -fpermissive

2410

@opindex fpermissive

2411

Downgrade some diagnostics about nonconformant code from errors to

2412

warnings. Thus, using @option{-fpermissive} allows some

2413

nonconforming code to compile.

2414

2415

@item -fno-pretty-templates

2416

@opindex fno-pretty-templates

2417

When an error message refers to a specialization of a function

2418

template, the compiler normally prints the signature of the

2419

template followed by the template arguments and any typedefs or

2420

typenames in the signature (e.g. @code{void f(T) [with T = int]}

2421

rather than @code{void f(int)}) so that it's clear which template is

2422

involved. When an error message refers to a specialization of a class

2423

template, the compiler omits any template arguments that match

2424

the default template arguments for that template. If either of these

2425

behaviors make it harder to understand the error message rather than

2426

easier, you can use @option{-fno-pretty-templates} to disable them.

2427

2428

@item -frepo

2429

@opindex frepo

2430

Enable automatic template instantiation at link time. This option also

2431

implies @option{-fno-implicit-templates}. @xref{Template

2432

Instantiation}, for more information.

2433

2434

@item -fno-rtti

2435

@opindex fno-rtti

2436

Disable generation of information about every class with virtual

2437

functions for use by the C++ run-time type identification features

2438

(@code{dynamic_cast} and @code{typeid}). If you don't use those parts

2439

of the language, you can save some space by using this flag. Note that

2440

exception handling uses the same information, but G++ generates it as

2441

needed. The @code{dynamic_cast} operator can still be used for casts that

2442

do not require run-time type information, i.e.@: casts to @code{void *} or to

2443

unambiguous base classes.

2444

2445

@item -fsized-deallocation

2446

@opindex fsized-deallocation

2447

Enable the built-in global declarations

2448

@smallexample

2449

void operator delete (void *, std::size_t) noexcept;

2450

void operator delete[] (void *, std::size_t) noexcept;

2451

@end smallexample

2452

as introduced in C++14. This is useful for user-defined replacement

2453

deallocation functions that, for example, use the size of the object

2454

to make deallocation faster. Enabled by default under

2455

@option{-std=c++14} and above. The flag @option{-Wsized-deallocation}

2456

warns about places that might want to add a definition.

2457

2458

@item -fstrict-enums

2459

@opindex fstrict-enums

2460

Allow the compiler to optimize using the assumption that a value of

2461

enumerated type can only be one of the values of the enumeration (as

2462

defined in the C++ standard; basically, a value that can be

2463

represented in the minimum number of bits needed to represent all the

2464

enumerators). This assumption may not be valid if the program uses a

2465

cast to convert an arbitrary integer value to the enumerated type.

2466

2467

@item -ftemplate-backtrace-limit=@var{n}

2468

@opindex ftemplate-backtrace-limit

2469

Set the maximum number of template instantiation notes for a single

2470

warning or error to @var{n}. The default value is 10.

2471

2472

@item -ftemplate-depth=@var{n}

2473

@opindex ftemplate-depth

2474

Set the maximum instantiation depth for template classes to @var{n}.

2475

A limit on the template instantiation depth is needed to detect

2476

endless recursions during template class instantiation. ANSI/ISO C++

2477

conforming programs must not rely on a maximum depth greater than 17

2478

(changed to 1024 in C++11). The default value is 900, as the compiler

2479

can run out of stack space before hitting 1024 in some situations.

2480

2481

@item -fno-threadsafe-statics

2482

@opindex fno-threadsafe-statics

2483

Do not emit the extra code to use the routines specified in the C++

2484

ABI for thread-safe initialization of local statics. You can use this

2485

option to reduce code size slightly in code that doesn't need to be

2486

thread-safe.

2487

2488

@item -fuse-cxa-atexit

2489

@opindex fuse-cxa-atexit

2490

Register destructors for objects with static storage duration with the

2491

@code{__cxa_atexit} function rather than the @code{atexit} function.

2492

This option is required for fully standards-compliant handling of static

2493

destructors, but only works if your C library supports

2494

@code{__cxa_atexit}.

2495

2496

@item -fno-use-cxa-get-exception-ptr

2497

@opindex fno-use-cxa-get-exception-ptr

2498

Don't use the @code{__cxa_get_exception_ptr} runtime routine. This

2499

causes @code{std::uncaught_exception} to be incorrect, but is necessary

2500

if the runtime routine is not available.

2501

2502

@item -fvisibility-inlines-hidden

2503

@opindex fvisibility-inlines-hidden

2504

This switch declares that the user does not attempt to compare

2505

pointers to inline functions or methods where the addresses of the two functions

2506

are taken in different shared objects.

2507

2508

The effect of this is that GCC may, effectively, mark inline methods with

2509

@code{__attribute__ ((visibility ("hidden")))} so that they do not

2510

appear in the export table of a DSO and do not require a PLT indirection

2511

when used within the DSO@. Enabling this option can have a dramatic effect

2512

on load and link times of a DSO as it massively reduces the size of the

2513

dynamic export table when the library makes heavy use of templates.

2514

2515

The behavior of this switch is not quite the same as marking the

2516

methods as hidden directly, because it does not affect static variables

2517

local to the function or cause the compiler to deduce that

2518

the function is defined in only one shared object.

2519

2520

You may mark a method as having a visibility explicitly to negate the

2521

effect of the switch for that method. For example, if you do want to

2522

compare pointers to a particular inline method, you might mark it as

2523

having default visibility. Marking the enclosing class with explicit

2524

visibility has no effect.

2525

2526

Explicitly instantiated inline methods are unaffected by this option

2527

as their linkage might otherwise cross a shared library boundary.

2528

@xref{Template Instantiation}.

2529

2530

@item -fvisibility-ms-compat

2531

@opindex fvisibility-ms-compat

2532

This flag attempts to use visibility settings to make GCC's C++

2533

linkage model compatible with that of Microsoft Visual Studio.

2534

2535

The flag makes these changes to GCC's linkage model:

2536

2537

@enumerate

2538

@item

2539

It sets the default visibility to @code{hidden}, like

2540

@option{-fvisibility=hidden}.

2541

2542

@item

2543

Types, but not their members, are not hidden by default.

2544

2545

@item

2546

The One Definition Rule is relaxed for types without explicit

2547

visibility specifications that are defined in more than one

2548

shared object: those declarations are permitted if they are

2549

permitted when this option is not used.

2550

@end enumerate

2551

2552

In new code it is better to use @option{-fvisibility=hidden} and

2553

export those classes that are intended to be externally visible.

2554

Unfortunately it is possible for code to rely, perhaps accidentally,

2555

on the Visual Studio behavior.

2556

2557

Among the consequences of these changes are that static data members

2558

of the same type with the same name but defined in different shared

2559

objects are different, so changing one does not change the other;

2560

and that pointers to function members defined in different shared

2561

objects may not compare equal. When this flag is given, it is a

2562

violation of the ODR to define types with the same name differently.

2563

2564

@item -fno-weak

2565

@opindex fno-weak

2566

Do not use weak symbol support, even if it is provided by the linker.

2567

By default, G++ uses weak symbols if they are available. This

2568

option exists only for testing, and should not be used by end-users;

2569

it results in inferior code and has no benefits. This option may

2570

be removed in a future release of G++.

2571

2572

@item -nostdinc++

2573

@opindex nostdinc++

2574

Do not search for header files in the standard directories specific to

2575

C++, but do still search the other standard directories. (This option

2576

is used when building the C++ library.)

2577

@end table

2578

2579

In addition, these optimization, warning, and code generation options

2580

have meanings only for C++ programs:

2581

2582

@table @gcctabopt

2583

@item -Wabi @r{(C, Objective-C, C++ and Objective-C++ only)}

2584

@opindex Wabi

2585

@opindex Wno-abi

2586

Warn when G++ it generates code that is probably not compatible with

2587

the vendor-neutral C++ ABI@. Since G++ now defaults to updating the

2588

ABI with each major release, normally @option{-Wabi} will warn only if

2589

there is a check added later in a release series for an ABI issue

2590

discovered since the initial release. @option{-Wabi} will warn about

2591

more things if an older ABI version is selected (with

2592

@option{-fabi-version=@var{n}}).

2593

2594

@option{-Wabi} can also be used with an explicit version number to

2595

warn about compatibility with a particular @option{-fabi-version}

2596

level, e.g. @option{-Wabi=2} to warn about changes relative to

2597

@option{-fabi-version=2}.

2598

2599

If an explicit version number is provided and

2600

@option{-fabi-compat-version} is not specified, the version number

2601

from this option is used for compatibility aliases. If no explicit

2602

version number is provided with this option, but

2603

@option{-fabi-compat-version} is specified, that version number is

2604

used for ABI warnings.

2605

2606

Although an effort has been made to warn about

2607

all such cases, there are probably some cases that are not warned about,

2608

even though G++ is generating incompatible code. There may also be

2609

cases where warnings are emitted even though the code that is generated

2610

is compatible.

2611

2612

You should rewrite your code to avoid these warnings if you are

2613

concerned about the fact that code generated by G++ may not be binary

2614

compatible with code generated by other compilers.

2615

2616

Known incompatibilities in @option{-fabi-version=2} (which was the

2617

default from GCC 3.4 to 4.9) include:

2618

2619

@itemize @bullet

2620

2621

@item

2622

A template with a non-type template parameter of reference type was

2623

mangled incorrectly:

2624

@smallexample

2625

extern int N;

2626

template <int &> struct S @{@};

2627

void n (S<N>) @{2@}

2628

@end smallexample

2629

2630

This was fixed in @option{-fabi-version=3}.

2631

2632

@item

2633

SIMD vector types declared using @code{__attribute ((vector_size))} were

2634

mangled in a non-standard way that does not allow for overloading of

2635

functions taking vectors of different sizes.

2636

2637

The mangling was changed in @option{-fabi-version=4}.

2638

2639

@item

2640

@code{__attribute ((const))} and @code{noreturn} were mangled as type

2641

qualifiers, and @code{decltype} of a plain declaration was folded away.

2642

2643

These mangling issues were fixed in @option{-fabi-version=5}.

2644

2645

@item

2646

Scoped enumerators passed as arguments to a variadic function are

2647

promoted like unscoped enumerators, causing @code{va_arg} to complain.

2648

On most targets this does not actually affect the parameter passing

2649

ABI, as there is no way to pass an argument smaller than @code{int}.

2650

2651

Also, the ABI changed the mangling of template argument packs,

2652

@code{const_cast}, @code{static_cast}, prefix increment/decrement, and

2653

a class scope function used as a template argument.

2654

2655

These issues were corrected in @option{-fabi-version=6}.

2656

2657

@item

2658

Lambdas in default argument scope were mangled incorrectly, and the

2659

ABI changed the mangling of @code{nullptr_t}.

2660

2661

These issues were corrected in @option{-fabi-version=7}.

2662

2663

@item

2664

When mangling a function type with function-cv-qualifiers, the

2665

un-qualified function type was incorrectly treated as a substitution

2666

candidate.

2667

2668

This was fixed in @option{-fabi-version=8}, the default for GCC 5.1.

2669

2670

@item

2671

@code{decltype(nullptr)} incorrectly had an alignment of 1, leading to

2672

unaligned accesses. Note that this did not affect the ABI of a

2673

function with a @code{nullptr_t} parameter, as parameters have a

2674

minimum alignment.

2675

2676

This was fixed in @option{-fabi-version=9}, the default for GCC 5.2.

2677

2678

@item

2679

Target-specific attributes that affect the identity of a type, such as

2680

ia32 calling conventions on a function type (stdcall, regparm, etc.),

2681

did not affect the mangled name, leading to name collisions when

2682

function pointers were used as template arguments.

2683

2684

This was fixed in @option{-fabi-version=10}, the default for GCC 6.1.

2685

2686

@end itemize

2687

2688

It also warns about psABI-related changes. The known psABI changes at this

2689

point include:

2690

2691

@itemize @bullet

2692

2693

@item

2694

For SysV/x86-64, unions with @code{long double} members are

2695

passed in memory as specified in psABI. For example:

2696

2697

@smallexample

2698

union U @{

2699

long double ld;

2700

int i;

2701

@};

2702

@end smallexample

2703

2704

@noindent

2705

@code{union U} is always passed in memory.

2706

2707

@end itemize

2708

2709

@item -Wabi-tag @r{(C++ and Objective-C++ only)}

2710

@opindex Wabi-tag

2711

@opindex -Wabi-tag

2712

Warn when a type with an ABI tag is used in a context that does not

2713

have that ABI tag. See @ref{C++ Attributes} for more information

2714

about ABI tags.

2715

2716

@item -Wctor-dtor-privacy @r{(C++ and Objective-C++ only)}

2717

@opindex Wctor-dtor-privacy

2718

@opindex Wno-ctor-dtor-privacy

2719

Warn when a class seems unusable because all the constructors or

2720

destructors in that class are private, and it has neither friends nor

2721

public static member functions. Also warn if there are no non-private

2722

methods, and there's at least one private member function that isn't

2723

a constructor or destructor.

2724

2725

@item -Wdelete-non-virtual-dtor @r{(C++ and Objective-C++ only)}

2726

@opindex Wdelete-non-virtual-dtor

2727

@opindex Wno-delete-non-virtual-dtor

2728

Warn when @code{delete} is used to destroy an instance of a class that

2729

has virtual functions and non-virtual destructor. It is unsafe to delete

2730

an instance of a derived class through a pointer to a base class if the

2731

base class does not have a virtual destructor. This warning is enabled

2732

by @option{-Wall}.

2733

2734

@item -Wliteral-suffix @r{(C++ and Objective-C++ only)}

2735

@opindex Wliteral-suffix

2736

@opindex Wno-literal-suffix

2737

Warn when a string or character literal is followed by a ud-suffix which does

2738

not begin with an underscore. As a conforming extension, GCC treats such

2739

suffixes as separate preprocessing tokens in order to maintain backwards

2740

compatibility with code that uses formatting macros from @code{<inttypes.h>}.

2741

For example:

2742

2743

@smallexample

2744

#define __STDC_FORMAT_MACROS

2745

#include <inttypes.h>

2746

#include <stdio.h>

2747

2748

int main() @{

2749

int64_t i64 = 123;

2750

printf("My int64: %" PRId64"\n", i64);

2751

@}

2752

@end smallexample

2753

2754

In this case, @code{PRId64} is treated as a separate preprocessing token.

2755

2756

This warning is enabled by default.

2757

2758

@item -Wlto-type-mismatch

2759

@opindex Wlto-type-mismatch

2760

@opindex Wno-lto-type-mismatch

2761

2762

During the link-time optimization warn about type mismatches in

2763

global declarations from different compilation units.

2764

Requires @option{-flto} to be enabled. Enabled by default.

2765

2766

@item -Wnarrowing @r{(C++ and Objective-C++ only)}

2767

@opindex Wnarrowing

2768

@opindex Wno-narrowing

2769

With @option{-std=gnu++98} or @option{-std=c++98}, warn when a narrowing

2770

conversion prohibited by C++11 occurs within

2771

@samp{@{ @}}, e.g.

2772

2773

@smallexample

2774

int i = @{ 2.2 @}; // error: narrowing from double to int

2775

@end smallexample

2776

2777

This flag is included in @option{-Wall} and @option{-Wc++11-compat}.

2778

2779

When a later standard is in effect, e.g. when using @option{-std=c++11},

2780

narrowing conversions are diagnosed by default, as required by the standard.

2781

A narrowing conversion from a constant produces an error,

2782

and a narrowing conversion from a non-constant produces a warning,

2783

but @option{-Wno-narrowing} suppresses the diagnostic.

2784

Note that this does not affect the meaning of well-formed code;

2785

narrowing conversions are still considered ill-formed in SFINAE contexts.

2786

2787

@item -Wnoexcept @r{(C++ and Objective-C++ only)}

2788

@opindex Wnoexcept

2789

@opindex Wno-noexcept

2790

Warn when a noexcept-expression evaluates to false because of a call

2791

to a function that does not have a non-throwing exception

2792

specification (i.e. @code{throw()} or @code{noexcept}) but is known by

2793

the compiler to never throw an exception.

2794

2795

@item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}

2796

@opindex Wnon-virtual-dtor

2797

@opindex Wno-non-virtual-dtor

2798

Warn when a class has virtual functions and an accessible non-virtual

2799

destructor itself or in an accessible polymorphic base class, in which

2800

case it is possible but unsafe to delete an instance of a derived

2801

class through a pointer to the class itself or base class. This

2802

warning is automatically enabled if @option{-Weffc++} is specified.

2803

2804

@item -Wreorder @r{(C++ and Objective-C++ only)}

2805

@opindex Wreorder

2806

@opindex Wno-reorder

2807

@cindex reordering, warning

2808

@cindex warning for reordering of member initializers

2809

Warn when the order of member initializers given in the code does not

2810

match the order in which they must be executed. For instance:

2811

2812

@smallexample

2813

struct A @{

2814

int i;

2815

int j;

2816

A(): j (0), i (1) @{ @}

2817

@};

2818

@end smallexample

2819

2820

@noindent

2821

The compiler rearranges the member initializers for @code{i}

2822

and @code{j} to match the declaration order of the members, emitting

2823

a warning to that effect. This warning is enabled by @option{-Wall}.

2824

2825

@item -fext-numeric-literals @r{(C++ and Objective-C++ only)}

2826

@opindex fext-numeric-literals

2827

@opindex fno-ext-numeric-literals

2828

Accept imaginary, fixed-point, or machine-defined

2829

literal number suffixes as GNU extensions.

2830

When this option is turned off these suffixes are treated

2831

as C++11 user-defined literal numeric suffixes.

2832

This is on by default for all pre-C++11 dialects and all GNU dialects:

2833

@option{-std=c++98}, @option{-std=gnu++98}, @option{-std=gnu++11},

2834

@option{-std=gnu++14}.

2835

This option is off by default

2836

for ISO C++11 onwards (@option{-std=c++11}, ...).

2837

@end table

2838

2839

The following @option{-W@dots{}} options are not affected by @option{-Wall}.

2840

2841

@table @gcctabopt

2842

@item -Weffc++ @r{(C++ and Objective-C++ only)}

2843

@opindex Weffc++

2844

@opindex Wno-effc++

2845

Warn about violations of the following style guidelines from Scott Meyers'

2846

@cite{Effective C++} series of books:

2847

2848

@itemize @bullet

2849

@item

2850

Define a copy constructor and an assignment operator for classes

2851

with dynamically-allocated memory.

2852

2853

@item

2854

Prefer initialization to assignment in constructors.

2855

2856

@item

2857

Have @code{operator=} return a reference to @code{*this}.

2858

2859

@item

2860

Don't try to return a reference when you must return an object.

2861

2862

@item

2863

Distinguish between prefix and postfix forms of increment and

2864

decrement operators.

2865

2866

@item

2867

Never overload @code{&&}, @code{||}, or @code{,}.

2868

2869

@end itemize

2870

2871

This option also enables @option{-Wnon-virtual-dtor}, which is also

2872

one of the effective C++ recommendations. However, the check is

2873

extended to warn about the lack of virtual destructor in accessible

2874

non-polymorphic bases classes too.

2875

2876

When selecting this option, be aware that the standard library

2877

headers do not obey all of these guidelines; use @samp{grep -v}

2878

to filter out those warnings.

2879

2880

@item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)}

2881

@opindex Wstrict-null-sentinel

2882

@opindex Wno-strict-null-sentinel

2883

Warn about the use of an uncasted @code{NULL} as sentinel. When

2884

compiling only with GCC this is a valid sentinel, as @code{NULL} is defined

2885

to @code{__null}. Although it is a null pointer constant rather than a

2886

null pointer, it is guaranteed to be of the same size as a pointer.

2887

But this use is not portable across different compilers.

2888

2889

@item -Wno-non-template-friend @r{(C++ and Objective-C++ only)}

2890

@opindex Wno-non-template-friend

2891

@opindex Wnon-template-friend

2892

Disable warnings when non-templatized friend functions are declared

2893

within a template. Since the advent of explicit template specification

2894

support in G++, if the name of the friend is an unqualified-id (i.e.,

2895

@samp{friend foo(int)}), the C++ language specification demands that the

2896

friend declare or define an ordinary, nontemplate function. (Section

2897

14.5.3). Before G++ implemented explicit specification, unqualified-ids

2898

could be interpreted as a particular specialization of a templatized

2899

function. Because this non-conforming behavior is no longer the default

2900

behavior for G++, @option{-Wnon-template-friend} allows the compiler to

2901

check existing code for potential trouble spots and is on by default.

2902

This new compiler behavior can be turned off with

2903

@option{-Wno-non-template-friend}, which keeps the conformant compiler code

2904

but disables the helpful warning.

2905

2906

@item -Wold-style-cast @r{(C++ and Objective-C++ only)}

2907

@opindex Wold-style-cast

2908

@opindex Wno-old-style-cast

2909

Warn if an old-style (C-style) cast to a non-void type is used within

2910

a C++ program. The new-style casts (@code{dynamic_cast},

2911

@code{static_cast}, @code{reinterpret_cast}, and @code{const_cast}) are

2912

less vulnerable to unintended effects and much easier to search for.

2913

2914

@item -Woverloaded-virtual @r{(C++ and Objective-C++ only)}

2915

@opindex Woverloaded-virtual

2916

@opindex Wno-overloaded-virtual

2917

@cindex overloaded virtual function, warning

2918

@cindex warning for overloaded virtual function

2919

Warn when a function declaration hides virtual functions from a

2920

base class. For example, in:

2921

2922

@smallexample

2923

struct A @{

2924

virtual void f();

2925

@};

2926

2927

struct B: public A @{

2928

void f(int);

2929

@};

2930

@end smallexample

2931

2932

the @code{A} class version of @code{f} is hidden in @code{B}, and code

2933

like:

2934

2935

@smallexample

2936

B* b;

2937

b->f();

2938

@end smallexample

2939

2940

@noindent

2941

fails to compile.

2942

2943

@item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)}

2944

@opindex Wno-pmf-conversions

2945

@opindex Wpmf-conversions

2946

Disable the diagnostic for converting a bound pointer to member function

2947

to a plain pointer.

2948

2949

@item -Wsign-promo @r{(C++ and Objective-C++ only)}

2950

@opindex Wsign-promo

2951

@opindex Wno-sign-promo

2952

Warn when overload resolution chooses a promotion from unsigned or

2953

enumerated type to a signed type, over a conversion to an unsigned type of

2954

the same size. Previous versions of G++ tried to preserve

2955

unsignedness, but the standard mandates the current behavior.

2956

2957

@item -Wtemplates @r{(C++ and Objective-C++ only)}

2958

@opindex Wtemplates

2959

Warn when a primary template declaration is encountered. Some coding

2960

rules disallow templates, and this may be used to enforce that rule.

2961

The warning is inactive inside a system header file, such as the STL, so

2962

one can still use the STL. One may also instantiate or specialize

2963

templates.

2964

2965

@item -Wmultiple-inheritance @r{(C++ and Objective-C++ only)}

2966

@opindex Wmultiple-inheritance

2967

Warn when a class is defined with multiple direct base classes. Some

2968

coding rules disallow multiple inheritance, and this may be used to

2969

enforce that rule. The warning is inactive inside a system header file,

2970

such as the STL, so one can still use the STL. One may also define

2971

classes that indirectly use multiple inheritance.

2972

2973

@item -Wvirtual-inheritance

2974

@opindex Wvirtual-inheritance

2975

Warn when a class is defined with a virtual direct base classe. Some

2976

coding rules disallow multiple inheritance, and this may be used to

2977

enforce that rule. The warning is inactive inside a system header file,

2978

such as the STL, so one can still use the STL. One may also define

2979

classes that indirectly use virtual inheritance.

2980

2981

@item -Wnamespaces

2982

@opindex Wnamespaces

2983

Warn when a namespace definition is opened. Some coding rules disallow

2984

namespaces, and this may be used to enforce that rule. The warning is

2985

inactive inside a system header file, such as the STL, so one can still

2986

use the STL. One may also use using directives and qualified names.

2987

2988

@item -Wno-terminate @r{(C++ and Objective-C++ only)}

2989

@opindex Wterminate

2990

@opindex Wno-terminate

2991

Disable the warning about a throw-expression that will immediately

2992

result in a call to @code{terminate}.

2993

@end table

2994

2995

@node Objective-C and Objective-C++ Dialect Options

2996

@section Options Controlling Objective-C and Objective-C++ Dialects

2997

2998

@cindex compiler options, Objective-C and Objective-C++

2999

@cindex Objective-C and Objective-C++ options, command-line

3000

@cindex options, Objective-C and Objective-C++

3001

(NOTE: This manual does not describe the Objective-C and Objective-C++

3002

languages themselves. @xref{Standards,,Language Standards

3003

Supported by GCC}, for references.)

3004

3005

This section describes the command-line options that are only meaningful

3006

for Objective-C and Objective-C++ programs. You can also use most of

3007

the language-independent GNU compiler options.

3008

For example, you might compile a file @file{some_class.m} like this:

3009

3010

@smallexample

3011

gcc -g -fgnu-runtime -O -c some_class.m

3012

@end smallexample

3013

3014

@noindent

3015

In this example, @option{-fgnu-runtime} is an option meant only for

3016

Objective-C and Objective-C++ programs; you can use the other options with

3017

any language supported by GCC@.

3018

3019

Note that since Objective-C is an extension of the C language, Objective-C

3020

compilations may also use options specific to the C front-end (e.g.,

3021

@option{-Wtraditional}). Similarly, Objective-C++ compilations may use

3022

C++-specific options (e.g., @option{-Wabi}).

3023

3024

Here is a list of options that are @emph{only} for compiling Objective-C

3025

and Objective-C++ programs:

3026

3027

@table @gcctabopt

3028

@item -fconstant-string-class=@var{class-name}

3029

@opindex fconstant-string-class

3030

Use @var{class-name} as the name of the class to instantiate for each

3031

literal string specified with the syntax @code{@@"@dots{}"}. The default

3032

class name is @code{NXConstantString} if the GNU runtime is being used, and

3033

@code{NSConstantString} if the NeXT runtime is being used (see below). The

3034

@option{-fconstant-cfstrings} option, if also present, overrides the

3035

@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals

3036

to be laid out as constant CoreFoundation strings.

3037

3038

@item -fgnu-runtime

3039

@opindex fgnu-runtime

3040

Generate object code compatible with the standard GNU Objective-C

3041

runtime. This is the default for most types of systems.

3042

3043

@item -fnext-runtime

3044

@opindex fnext-runtime

3045

Generate output compatible with the NeXT runtime. This is the default

3046

for NeXT-based systems, including Darwin and Mac OS X@. The macro

3047

@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is

3048

used.

3049

3050

@item -fno-nil-receivers

3051

@opindex fno-nil-receivers

3052

Assume that all Objective-C message dispatches (@code{[receiver

3053

message:arg]}) in this translation unit ensure that the receiver is

3054

not @code{nil}. This allows for more efficient entry points in the

3055

runtime to be used. This option is only available in conjunction with

3056

the NeXT runtime and ABI version 0 or 1.

3057

3058

@item -fobjc-abi-version=@var{n}

3059

@opindex fobjc-abi-version

3060

Use version @var{n} of the Objective-C ABI for the selected runtime.

3061

This option is currently supported only for the NeXT runtime. In that

3062

case, Version 0 is the traditional (32-bit) ABI without support for

3063

properties and other Objective-C 2.0 additions. Version 1 is the

3064

traditional (32-bit) ABI with support for properties and other

3065

Objective-C 2.0 additions. Version 2 is the modern (64-bit) ABI. If

3066

nothing is specified, the default is Version 0 on 32-bit target

3067

machines, and Version 2 on 64-bit target machines.

3068

3069

@item -fobjc-call-cxx-cdtors

3070

@opindex fobjc-call-cxx-cdtors

3071

For each Objective-C class, check if any of its instance variables is a

3072

C++ object with a non-trivial default constructor. If so, synthesize a

3073

special @code{- (id) .cxx_construct} instance method which runs

3074

non-trivial default constructors on any such instance variables, in order,

3075

and then return @code{self}. Similarly, check if any instance variable

3076

is a C++ object with a non-trivial destructor, and if so, synthesize a

3077

special @code{- (void) .cxx_destruct} method which runs

3078

all such default destructors, in reverse order.

3079

3080

The @code{- (id) .cxx_construct} and @code{- (void) .cxx_destruct}

3081

methods thusly generated only operate on instance variables

3082

declared in the current Objective-C class, and not those inherited

3083

from superclasses. It is the responsibility of the Objective-C

3084

runtime to invoke all such methods in an object's inheritance

3085

hierarchy. The @code{- (id) .cxx_construct} methods are invoked

3086

by the runtime immediately after a new object instance is allocated;

3087

the @code{- (void) .cxx_destruct} methods are invoked immediately

3088

before the runtime deallocates an object instance.

3089

3090

As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has

3091

support for invoking the @code{- (id) .cxx_construct} and

3092

@code{- (void) .cxx_destruct} methods.

3093

3094

@item -fobjc-direct-dispatch

3095

@opindex fobjc-direct-dispatch

3096

Allow fast jumps to the message dispatcher. On Darwin this is

3097

accomplished via the comm page.

3098

3099

@item -fobjc-exceptions

3100

@opindex fobjc-exceptions

3101

Enable syntactic support for structured exception handling in

3102

Objective-C, similar to what is offered by C++ and Java. This option

3103

is required to use the Objective-C keywords @code{@@try},

3104

@code{@@throw}, @code{@@catch}, @code{@@finally} and

3105

@code{@@synchronized}. This option is available with both the GNU

3106

runtime and the NeXT runtime (but not available in conjunction with

3107

the NeXT runtime on Mac OS X 10.2 and earlier).

3108

3109

@item -fobjc-gc

3110

@opindex fobjc-gc

3111

Enable garbage collection (GC) in Objective-C and Objective-C++

3112

programs. This option is only available with the NeXT runtime; the

3113

GNU runtime has a different garbage collection implementation that

3114

does not require special compiler flags.

3115

3116

@item -fobjc-nilcheck

3117

@opindex fobjc-nilcheck

3118

For the NeXT runtime with version 2 of the ABI, check for a nil

3119

receiver in method invocations before doing the actual method call.

3120

This is the default and can be disabled using

3121

@option{-fno-objc-nilcheck}. Class methods and super calls are never

3122

checked for nil in this way no matter what this flag is set to.

3123

Currently this flag does nothing when the GNU runtime, or an older

3124

version of the NeXT runtime ABI, is used.

3125

3126

@item -fobjc-std=objc1

3127

@opindex fobjc-std

3128

Conform to the language syntax of Objective-C 1.0, the language

3129

recognized by GCC 4.0. This only affects the Objective-C additions to

3130

the C/C++ language; it does not affect conformance to C/C++ standards,

3131

which is controlled by the separate C/C++ dialect option flags. When

3132

this option is used with the Objective-C or Objective-C++ compiler,

3133

any Objective-C syntax that is not recognized by GCC 4.0 is rejected.

3134

This is useful if you need to make sure that your Objective-C code can

3135

be compiled with older versions of GCC@.

3136

3137

@item -freplace-objc-classes

3138

@opindex freplace-objc-classes

3139

Emit a special marker instructing @command{ld(1)} not to statically link in

3140

the resulting object file, and allow @command{dyld(1)} to load it in at

3141

run time instead. This is used in conjunction with the Fix-and-Continue

3142

debugging mode, where the object file in question may be recompiled and

3143

dynamically reloaded in the course of program execution, without the need

3144

to restart the program itself. Currently, Fix-and-Continue functionality

3145

is only available in conjunction with the NeXT runtime on Mac OS X 10.3

3146

and later.

3147

3148

@item -fzero-link

3149

@opindex fzero-link

3150

When compiling for the NeXT runtime, the compiler ordinarily replaces calls

3151

to @code{objc_getClass("@dots{}")} (when the name of the class is known at

3152

compile time) with static class references that get initialized at load time,

3153

which improves run-time performance. Specifying the @option{-fzero-link} flag

3154

suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}

3155

to be retained. This is useful in Zero-Link debugging mode, since it allows

3156

for individual class implementations to be modified during program execution.

3157

The GNU runtime currently always retains calls to @code{objc_get_class("@dots{}")}

3158

regardless of command-line options.

3159

3160

@item -fno-local-ivars

3161

@opindex fno-local-ivars

3162

@opindex flocal-ivars

3163

By default instance variables in Objective-C can be accessed as if

3164

they were local variables from within the methods of the class they're

3165

declared in. This can lead to shadowing between instance variables

3166

and other variables declared either locally inside a class method or

3167

globally with the same name. Specifying the @option{-fno-local-ivars}

3168

flag disables this behavior thus avoiding variable shadowing issues.

3169

3170

@item -fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]}

3171

@opindex fivar-visibility

3172

Set the default instance variable visibility to the specified option

3173

so that instance variables declared outside the scope of any access

3174

modifier directives default to the specified visibility.

3175

3176

@item -gen-decls

3177

@opindex gen-decls

3178

Dump interface declarations for all classes seen in the source file to a

3179

file named @file{@var{sourcename}.decl}.

3180

3181

@item -Wassign-intercept @r{(Objective-C and Objective-C++ only)}

3182

@opindex Wassign-intercept

3183

@opindex Wno-assign-intercept

3184

Warn whenever an Objective-C assignment is being intercepted by the

3185

garbage collector.

3186

3187

@item -Wno-protocol @r{(Objective-C and Objective-C++ only)}

3188

@opindex Wno-protocol

3189

@opindex Wprotocol

3190

If a class is declared to implement a protocol, a warning is issued for

3191

every method in the protocol that is not implemented by the class. The

3192

default behavior is to issue a warning for every method not explicitly

3193

implemented in the class, even if a method implementation is inherited

3194

from the superclass. If you use the @option{-Wno-protocol} option, then

3195

methods inherited from the superclass are considered to be implemented,

3196

and no warning is issued for them.

3197

3198

@item -Wselector @r{(Objective-C and Objective-C++ only)}

3199

@opindex Wselector

3200

@opindex Wno-selector

3201

Warn if multiple methods of different types for the same selector are

3202

found during compilation. The check is performed on the list of methods

3203

in the final stage of compilation. Additionally, a check is performed

3204

for each selector appearing in a @code{@@selector(@dots{})}

3205

expression, and a corresponding method for that selector has been found

3206

during compilation. Because these checks scan the method table only at

3207

the end of compilation, these warnings are not produced if the final

3208

stage of compilation is not reached, for example because an error is

3209

found during compilation, or because the @option{-fsyntax-only} option is

3210

being used.

3211

3212

@item -Wstrict-selector-match @r{(Objective-C and Objective-C++ only)}

3213

@opindex Wstrict-selector-match

3214

@opindex Wno-strict-selector-match

3215

Warn if multiple methods with differing argument and/or return types are

3216

found for a given selector when attempting to send a message using this

3217

selector to a receiver of type @code{id} or @code{Class}. When this flag

3218

is off (which is the default behavior), the compiler omits such warnings

3219

if any differences found are confined to types that share the same size

3220

and alignment.

3221

3222

@item -Wundeclared-selector @r{(Objective-C and Objective-C++ only)}

3223

@opindex Wundeclared-selector

3224

@opindex Wno-undeclared-selector

3225

Warn if a @code{@@selector(@dots{})} expression referring to an

3226

undeclared selector is found. A selector is considered undeclared if no

3227

method with that name has been declared before the

3228

@code{@@selector(@dots{})} expression, either explicitly in an

3229

@code{@@interface} or @code{@@protocol} declaration, or implicitly in

3230

an @code{@@implementation} section. This option always performs its

3231

checks as soon as a @code{@@selector(@dots{})} expression is found,

3232

while @option{-Wselector} only performs its checks in the final stage of

3233

compilation. This also enforces the coding style convention

3234

that methods and selectors must be declared before being used.

3235

3236

@item -print-objc-runtime-info

3237

@opindex print-objc-runtime-info

3238

Generate C header describing the largest structure that is passed by

3239

value, if any.

3240

3241

@end table

3242

3243

@node Diagnostic Message Formatting Options

3244

@section Options to Control Diagnostic Messages Formatting

3245

@cindex options to control diagnostics formatting

3246

@cindex diagnostic messages

3247

@cindex message formatting

3248

3249

Traditionally, diagnostic messages have been formatted irrespective of

3250

the output device's aspect (e.g.@: its width, @dots{}). You can use the

3251

options described below

3252

to control the formatting algorithm for diagnostic messages,

3253

e.g.@: how many characters per line, how often source location

3254

information should be reported. Note that some language front ends may not

3255

honor these options.

3256

3257

@table @gcctabopt

3258

@item -fmessage-length=@var{n}

3259

@opindex fmessage-length

3260

Try to format error messages so that they fit on lines of about

3261

@var{n} characters. If @var{n} is zero, then no line-wrapping is

3262

done; each error message appears on a single line. This is the

3263

default for all front ends.

3264

3265

@item -fdiagnostics-show-location=once

3266

@opindex fdiagnostics-show-location

3267

Only meaningful in line-wrapping mode. Instructs the diagnostic messages

3268

reporter to emit source location information @emph{once}; that is, in

3269

case the message is too long to fit on a single physical line and has to

3270

be wrapped, the source location won't be emitted (as prefix) again,

3271

over and over, in subsequent continuation lines. This is the default

3272

behavior.

3273

3274

@item -fdiagnostics-show-location=every-line

3275

Only meaningful in line-wrapping mode. Instructs the diagnostic

3276

messages reporter to emit the same source location information (as

3277

prefix) for physical lines that result from the process of breaking

3278

a message which is too long to fit on a single line.

3279

3280

@item -fdiagnostics-color[=@var{WHEN}]

3281

@itemx -fno-diagnostics-color

3282

@opindex fdiagnostics-color

3283

@cindex highlight, color

3284

@vindex GCC_COLORS @r{environment variable}

3285

Use color in diagnostics. @var{WHEN} is @samp{never}, @samp{always},

3286

or @samp{auto}. The default depends on how the compiler has been configured,

3287

it can be any of the above @var{WHEN} options or also @samp{never}

3288

if @env{GCC_COLORS} environment variable isn't present in the environment,

3289

and @samp{auto} otherwise.

3290

@samp{auto} means to use color only when the standard error is a terminal.

3291

The forms @option{-fdiagnostics-color} and @option{-fno-diagnostics-color} are

3292

aliases for @option{-fdiagnostics-color=always} and

3293

@option{-fdiagnostics-color=never}, respectively.

3294

3295

The colors are defined by the environment variable @env{GCC_COLORS}.

3296

Its value is a colon-separated list of capabilities and Select Graphic

3297

Rendition (SGR) substrings. SGR commands are interpreted by the

3298

terminal or terminal emulator. (See the section in the documentation

3299

of your text terminal for permitted values and their meanings as

3300

character attributes.) These substring values are integers in decimal

3301

representation and can be concatenated with semicolons.

3302

Common values to concatenate include

3303

@samp{1} for bold,

3304

@samp{4} for underline,

3305

@samp{5} for blink,

3306

@samp{7} for inverse,

3307

@samp{39} for default foreground color,

3308

@samp{30} to @samp{37} for foreground colors,

3309

@samp{90} to @samp{97} for 16-color mode foreground colors,

3310

@samp{38;5;0} to @samp{38;5;255}

3311

for 88-color and 256-color modes foreground colors,

3312

@samp{49} for default background color,

3313

@samp{40} to @samp{47} for background colors,

3314

@samp{100} to @samp{107} for 16-color mode background colors,

3315

and @samp{48;5;0} to @samp{48;5;255}

3316

for 88-color and 256-color modes background colors.

3317

3318

The default @env{GCC_COLORS} is

3319

@smallexample

3320

error=01;31:warning=01;35:note=01;36:caret=01;32:locus=01:quote=01

3321

@end smallexample

3322

@noindent

3323

where @samp{01;31} is bold red, @samp{01;35} is bold magenta,

3324

@samp{01;36} is bold cyan, @samp{01;32} is bold green and

3325

@samp{01} is bold. Setting @env{GCC_COLORS} to the empty

3326

string disables colors.

3327

Supported capabilities are as follows.

3328

3329

@table @code

3330

@item error=

3331

@vindex error GCC_COLORS @r{capability}

3332

SGR substring for error: markers.

3333

3334

@item warning=

3335

@vindex warning GCC_COLORS @r{capability}

3336

SGR substring for warning: markers.

3337

3338

@item note=

3339

@vindex note GCC_COLORS @r{capability}

3340

SGR substring for note: markers.

3341

3342

@item caret=

3343

@vindex caret GCC_COLORS @r{capability}

3344

SGR substring for caret line.

3345

3346

@item locus=

3347

@vindex locus GCC_COLORS @r{capability}

3348

SGR substring for location information, @samp{file:line} or

3349

@samp{file:line:column} etc.

3350

3351

@item quote=

3352

@vindex quote GCC_COLORS @r{capability}

3353

SGR substring for information printed within quotes.

3354

@end table

3355

3356

@item -fno-diagnostics-show-option

3357

@opindex fno-diagnostics-show-option

3358

@opindex fdiagnostics-show-option

3359

By default, each diagnostic emitted includes text indicating the

3360

command-line option that directly controls the diagnostic (if such an

3361

option is known to the diagnostic machinery). Specifying the

3362

@option{-fno-diagnostics-show-option} flag suppresses that behavior.

3363

3364

@item -fno-diagnostics-show-caret

3365

@opindex fno-diagnostics-show-caret

3366

@opindex fdiagnostics-show-caret

3367

By default, each diagnostic emitted includes the original source line

3368

and a caret @samp{^} indicating the column. This option suppresses this

3369

information. The source line is truncated to @var{n} characters, if

3370

the @option{-fmessage-length=n} option is given. When the output is done

3371

to the terminal, the width is limited to the width given by the

3372

@env{COLUMNS} environment variable or, if not set, to the terminal width.

3373

3374

@end table

3375

3376

@node Warning Options

3377

@section Options to Request or Suppress Warnings

3378

@cindex options to control warnings

3379

@cindex warning messages

3380

@cindex messages, warning

3381

@cindex suppressing warnings

3382

3383

Warnings are diagnostic messages that report constructions that

3384

are not inherently erroneous but that are risky or suggest there

3385

may have been an error.

3386

3387

The following language-independent options do not enable specific

3388

warnings but control the kinds of diagnostics produced by GCC@.

3389

3390

@table @gcctabopt

3391

@cindex syntax checking

3392

@item -fsyntax-only

3393

@opindex fsyntax-only

3394

Check the code for syntax errors, but don't do anything beyond that.

3395

3396

@item -fmax-errors=@var{n}

3397

@opindex fmax-errors

3398

Limits the maximum number of error messages to @var{n}, at which point

3399

GCC bails out rather than attempting to continue processing the source

3400

code. If @var{n} is 0 (the default), there is no limit on the number

3401

of error messages produced. If @option{-Wfatal-errors} is also

3402

specified, then @option{-Wfatal-errors} takes precedence over this

3403

option.

3404

3405

@item -w

3406

@opindex w

3407

Inhibit all warning messages.

3408

3409

@item -Werror

3410

@opindex Werror

3411

@opindex Wno-error

3412

Make all warnings into errors.

3413

3414

@item -Werror=

3415

@opindex Werror=

3416

@opindex Wno-error=

3417

Make the specified warning into an error. The specifier for a warning

3418

is appended; for example @option{-Werror=switch} turns the warnings

3419

controlled by @option{-Wswitch} into errors. This switch takes a

3420

negative form, to be used to negate @option{-Werror} for specific

3421

warnings; for example @option{-Wno-error=switch} makes

3422

@option{-Wswitch} warnings not be errors, even when @option{-Werror}

3423

is in effect.

3424

3425

The warning message for each controllable warning includes the

3426

option that controls the warning. That option can then be used with

3427

@option{-Werror=} and @option{-Wno-error=} as described above.

3428

(Printing of the option in the warning message can be disabled using the

3429

@option{-fno-diagnostics-show-option} flag.)

3430

3431

Note that specifying @option{-Werror=}@var{foo} automatically implies

3432

@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not

3433

imply anything.

3434

3435

@item -Wfatal-errors

3436

@opindex Wfatal-errors

3437

@opindex Wno-fatal-errors

3438

This option causes the compiler to abort compilation on the first error

3439

occurred rather than trying to keep going and printing further error

3440

messages.

3441

3442

@end table

3443

3444

You can request many specific warnings with options beginning with

3445

@samp{-W}, for example @option{-Wimplicit} to request warnings on

3446

implicit declarations. Each of these specific warning options also

3447

has a negative form beginning @samp{-Wno-} to turn off warnings; for

3448

example, @option{-Wno-implicit}. This manual lists only one of the

3449

two forms, whichever is not the default. For further

3450

language-specific options also refer to @ref{C++ Dialect Options} and

3451

@ref{Objective-C and Objective-C++ Dialect Options}.

3452

3453

Some options, such as @option{-Wall} and @option{-Wextra}, turn on other

3454

options, such as @option{-Wunused}, which may turn on further options,

3455

such as @option{-Wunused-value}. The combined effect of positive and

3456

negative forms is that more specific options have priority over less

3457

specific ones, independently of their position in the command-line. For

3458

options of the same specificity, the last one takes effect. Options

3459

enabled or disabled via pragmas (@pxref{Diagnostic Pragmas}) take effect

3460

as if they appeared at the end of the command-line.

3461

3462

When an unrecognized warning option is requested (e.g.,

3463

@option{-Wunknown-warning}), GCC emits a diagnostic stating

3464

that the option is not recognized. However, if the @option{-Wno-} form

3465

is used, the behavior is slightly different: no diagnostic is

3466

produced for @option{-Wno-unknown-warning} unless other diagnostics

3467

are being produced. This allows the use of new @option{-Wno-} options

3468

with old compilers, but if something goes wrong, the compiler

3469

warns that an unrecognized option is present.

3470

3471

@table @gcctabopt

3472

@item -Wpedantic

3473

@itemx -pedantic

3474

@opindex pedantic

3475

@opindex Wpedantic

3476

Issue all the warnings demanded by strict ISO C and ISO C++;

3477

reject all programs that use forbidden extensions, and some other

3478

programs that do not follow ISO C and ISO C++. For ISO C, follows the

3479

version of the ISO C standard specified by any @option{-std} option used.

3480

3481

Valid ISO C and ISO C++ programs should compile properly with or without

3482

this option (though a rare few require @option{-ansi} or a

3483

@option{-std} option specifying the required version of ISO C)@. However,

3484

without this option, certain GNU extensions and traditional C and C++

3485

features are supported as well. With this option, they are rejected.

3486

3487

@option{-Wpedantic} does not cause warning messages for use of the

3488

alternate keywords whose names begin and end with @samp{__}. Pedantic

3489

warnings are also disabled in the expression that follows

3490

@code{__extension__}. However, only system header files should use

3491

these escape routes; application programs should avoid them.

3492

@xref{Alternate Keywords}.

3493

3494

Some users try to use @option{-Wpedantic} to check programs for strict ISO

3495

C conformance. They soon find that it does not do quite what they want:

3496

it finds some non-ISO practices, but not all---only those for which

3497

ISO C @emph{requires} a diagnostic, and some others for which

3498

diagnostics have been added.

3499

3500

A feature to report any failure to conform to ISO C might be useful in

3501

some instances, but would require considerable additional work and would

3502

be quite different from @option{-Wpedantic}. We don't have plans to

3503

support such a feature in the near future.

3504

3505

Where the standard specified with @option{-std} represents a GNU

3506

extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a

3507

corresponding @dfn{base standard}, the version of ISO C on which the GNU

3508

extended dialect is based. Warnings from @option{-Wpedantic} are given

3509

where they are required by the base standard. (It does not make sense

3510

for such warnings to be given only for features not in the specified GNU

3511

C dialect, since by definition the GNU dialects of C include all

3512

features the compiler supports with the given option, and there would be

3513

nothing to warn about.)

3514

3515

@item -pedantic-errors

3516

@opindex pedantic-errors

3517

Give an error whenever the @dfn{base standard} (see @option{-Wpedantic})

3518

requires a diagnostic, in some cases where there is undefined behavior

3519

at compile-time and in some other cases that do not prevent compilation

3520

of programs that are valid according to the standard. This is not

3521

equivalent to @option{-Werror=pedantic}, since there are errors enabled

3522

by this option and not enabled by the latter and vice versa.

3523

3524

@item -Wall

3525

@opindex Wall

3526

@opindex Wno-all

3527

This enables all the warnings about constructions that some users

3528

consider questionable, and that are easy to avoid (or modify to

3529

prevent the warning), even in conjunction with macros. This also

3530

enables some language-specific warnings described in @ref{C++ Dialect

3531

Options} and @ref{Objective-C and Objective-C++ Dialect Options}.

3532

3533

@option{-Wall} turns on the following warning flags:

3534

3535

@gccoptlist{-Waddress @gol

3536

-Warray-bounds=1 @r{(only with} @option{-O2}@r{)} @gol

3537

-Wbool-compare @gol

3538

-Wc++11-compat -Wc++14-compat@gol

3539

-Wchar-subscripts @gol

3540

-Wcomment @gol

3541

-Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol

3542

-Wformat @gol

3543

-Wimplicit @r{(C and Objective-C only)} @gol

3544

-Wimplicit-int @r{(C and Objective-C only)} @gol

3545

-Wimplicit-function-declaration @r{(C and Objective-C only)} @gol

3546

-Winit-self @r{(only for C++)} @gol

3547

-Wlogical-not-parentheses

3548

-Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)} @gol

3549

-Wmaybe-uninitialized @gol

3550

-Wmemset-transposed-args @gol

3551

-Wmisleading-indentation @r{(only for C/C++)} @gol

3552

-Wmissing-braces @r{(only for C/ObjC)} @gol

3553

-Wnarrowing @r{(only for C++)} @gol

3554

-Wnonnull @gol

3555

-Wnonnull-compare @gol

3556

-Wopenmp-simd @gol

3557

-Wparentheses @gol

3558

-Wpointer-sign @gol

3559

-Wreorder @gol

3560

-Wreturn-type @gol

3561

-Wsequence-point @gol

3562

-Wsign-compare @r{(only in C++)} @gol

3563

-Wsizeof-pointer-memaccess @gol

3564

-Wstrict-aliasing @gol

3565

-Wstrict-overflow=1 @gol

3566

-Wswitch @gol

3567

-Wtautological-compare @gol

3568

-Wtrigraphs @gol

3569

-Wuninitialized @gol

3570

-Wunknown-pragmas @gol

3571

-Wunused-function @gol

3572

-Wunused-label @gol

3573

-Wunused-value @gol

3574

-Wunused-variable @gol

3575

-Wvolatile-register-var @gol

3576

}

3577

3578

Note that some warning flags are not implied by @option{-Wall}. Some of

3579

them warn about constructions that users generally do not consider

3580

questionable, but which occasionally you might wish to check for;

3581

others warn about constructions that are necessary or hard to avoid in

3582

some cases, and there is no simple way to modify the code to suppress

3583

the warning. Some of them are enabled by @option{-Wextra} but many of

3584

them must be enabled individually.

3585

3586

@item -Wextra

3587

@opindex W

3588

@opindex Wextra

3589

@opindex Wno-extra

3590

This enables some extra warning flags that are not enabled by

3591

@option{-Wall}. (This option used to be called @option{-W}. The older

3592

name is still supported, but the newer name is more descriptive.)

3593

3594

@gccoptlist{-Wclobbered @gol

3595

-Wempty-body @gol

3596

-Wignored-qualifiers @gol

3597

-Wmissing-field-initializers @gol

3598

-Wmissing-parameter-type @r{(C only)} @gol

3599

-Wold-style-declaration @r{(C only)} @gol

3600

-Woverride-init @gol

3601

-Wsign-compare @r{(C only)} @gol

3602

-Wtype-limits @gol

3603

-Wuninitialized @gol

3604

-Wshift-negative-value @r{(in C++03 and in C99 and newer)} @gol

3605

-Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol

3606

-Wunused-but-set-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol

3607

}

3608

3609

The option @option{-Wextra} also prints warning messages for the

3610

following cases:

3611

3612

@itemize @bullet

3613

3614

@item

3615

A pointer is compared against integer zero with @code{<}, @code{<=},

3616

@code{>}, or @code{>=}.

3617

3618

@item

3619

(C++ only) An enumerator and a non-enumerator both appear in a

3620

conditional expression.

3621

3622

@item

3623

(C++ only) Ambiguous virtual bases.

3624

3625

@item

3626

(C++ only) Subscripting an array that has been declared @code{register}.

3627

3628

@item

3629

(C++ only) Taking the address of a variable that has been declared

3630

@code{register}.

3631

3632

@item

3633

(C++ only) A base class is not initialized in a derived class's copy

3634

constructor.

3635

3636

@end itemize

3637

3638

@item -Wchar-subscripts

3639

@opindex Wchar-subscripts

3640

@opindex Wno-char-subscripts

3641

Warn if an array subscript has type @code{char}. This is a common cause

3642

of error, as programmers often forget that this type is signed on some

3643

machines.

3644

This warning is enabled by @option{-Wall}.

3645

3646

@item -Wcomment

3647

@opindex Wcomment

3648

@opindex Wno-comment

3649

Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}

3650

comment, or whenever a Backslash-Newline appears in a @samp{//} comment.

3651

This warning is enabled by @option{-Wall}.

3652

3653

@item -Wno-coverage-mismatch

3654

@opindex Wno-coverage-mismatch

3655

Warn if feedback profiles do not match when using the

3656

@option{-fprofile-use} option.

3657

If a source file is changed between compiling with @option{-fprofile-gen} and

3658

with @option{-fprofile-use}, the files with the profile feedback can fail

3659

to match the source file and GCC cannot use the profile feedback

3660

information. By default, this warning is enabled and is treated as an

3661

error. @option{-Wno-coverage-mismatch} can be used to disable the

3662

warning or @option{-Wno-error=coverage-mismatch} can be used to

3663

disable the error. Disabling the error for this warning can result in

3664

poorly optimized code and is useful only in the

3665

case of very minor changes such as bug fixes to an existing code-base.

3666

Completely disabling the warning is not recommended.

3667

3668

@item -Wno-cpp

3669

@r{(C, Objective-C, C++, Objective-C++ and Fortran only)}

3670

3671

Suppress warning messages emitted by @code{#warning} directives.

3672

3673

@item -Wdouble-promotion @r{(C, C++, Objective-C and Objective-C++ only)}

3674

@opindex Wdouble-promotion

3675

@opindex Wno-double-promotion

3676

Give a warning when a value of type @code{float} is implicitly

3677

promoted to @code{double}. CPUs with a 32-bit ``single-precision''

3678

floating-point unit implement @code{float} in hardware, but emulate

3679

@code{double} in software. On such a machine, doing computations

3680

using @code{double} values is much more expensive because of the

3681

overhead required for software emulation.

3682

3683

It is easy to accidentally do computations with @code{double} because

3684

floating-point literals are implicitly of type @code{double}. For

3685

example, in:

3686

@smallexample

3687

@group

3688

float area(float radius)

3689

@{

3690

return 3.14159 * radius * radius;

3691

@}

3692

@end group

3693

@end smallexample

3694

the compiler performs the entire computation with @code{double}

3695

because the floating-point literal is a @code{double}.

3696

3697

@item -Wformat

3698

@itemx -Wformat=@var{n}

3699

@opindex Wformat

3700

@opindex Wno-format

3701

@opindex ffreestanding

3702

@opindex fno-builtin

3703

@opindex Wformat=

3704

Check calls to @code{printf} and @code{scanf}, etc., to make sure that

3705

the arguments supplied have types appropriate to the format string

3706

specified, and that the conversions specified in the format string make

3707

sense. This includes standard functions, and others specified by format

3708

attributes (@pxref{Function Attributes}), in the @code{printf},

3709

@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,

3710

not in the C standard) families (or other target-specific families).

3711

Which functions are checked without format attributes having been

3712

specified depends on the standard version selected, and such checks of

3713

functions without the attribute specified are disabled by

3714

@option{-ffreestanding} or @option{-fno-builtin}.

3715

3716

The formats are checked against the format features supported by GNU

3717

libc version 2.2. These include all ISO C90 and C99 features, as well

3718

as features from the Single Unix Specification and some BSD and GNU

3719

extensions. Other library implementations may not support all these

3720

features; GCC does not support warning about features that go beyond a

3721

particular library's limitations. However, if @option{-Wpedantic} is used

3722

with @option{-Wformat}, warnings are given about format features not

3723

in the selected standard version (but not for @code{strfmon} formats,

3724

since those are not in any version of the C standard). @xref{C Dialect

3725

Options,,Options Controlling C Dialect}.

3726

3727

@table @gcctabopt

3728

@item -Wformat=1

3729

@itemx -Wformat

3730

@opindex Wformat

3731

@opindex Wformat=1

3732

Option @option{-Wformat} is equivalent to @option{-Wformat=1}, and

3733

@option{-Wno-format} is equivalent to @option{-Wformat=0}. Since

3734

@option{-Wformat} also checks for null format arguments for several

3735

functions, @option{-Wformat} also implies @option{-Wnonnull}. Some

3736

aspects of this level of format checking can be disabled by the

3737

options: @option{-Wno-format-contains-nul},

3738

@option{-Wno-format-extra-args}, and @option{-Wno-format-zero-length}.

3739

@option{-Wformat} is enabled by @option{-Wall}.

3740

3741

@item -Wno-format-contains-nul

3742

@opindex Wno-format-contains-nul

3743

@opindex Wformat-contains-nul

3744

If @option{-Wformat} is specified, do not warn about format strings that

3745

contain NUL bytes.

3746

3747

@item -Wno-format-extra-args

3748

@opindex Wno-format-extra-args

3749

@opindex Wformat-extra-args

3750

If @option{-Wformat} is specified, do not warn about excess arguments to a

3751

@code{printf} or @code{scanf} format function. The C standard specifies

3752

that such arguments are ignored.

3753

3754

Where the unused arguments lie between used arguments that are

3755

specified with @samp{$} operand number specifications, normally

3756

warnings are still given, since the implementation could not know what

3757

type to pass to @code{va_arg} to skip the unused arguments. However,

3758

in the case of @code{scanf} formats, this option suppresses the

3759

warning if the unused arguments are all pointers, since the Single

3760

Unix Specification says that such unused arguments are allowed.

3761

3762

@item -Wno-format-zero-length

3763

@opindex Wno-format-zero-length

3764

@opindex Wformat-zero-length

3765

If @option{-Wformat} is specified, do not warn about zero-length formats.

3766

The C standard specifies that zero-length formats are allowed.

3767

3768

3769

@item -Wformat=2

3770

@opindex Wformat=2

3771

Enable @option{-Wformat} plus additional format checks. Currently

3772

equivalent to @option{-Wformat -Wformat-nonliteral -Wformat-security

3773

-Wformat-y2k}.

3774

3775

@item -Wformat-nonliteral

3776

@opindex Wformat-nonliteral

3777

@opindex Wno-format-nonliteral

3778

If @option{-Wformat} is specified, also warn if the format string is not a

3779

string literal and so cannot be checked, unless the format function

3780

takes its format arguments as a @code{va_list}.

3781

3782

@item -Wformat-security

3783

@opindex Wformat-security

3784

@opindex Wno-format-security

3785

If @option{-Wformat} is specified, also warn about uses of format

3786

functions that represent possible security problems. At present, this

3787

warns about calls to @code{printf} and @code{scanf} functions where the

3788

format string is not a string literal and there are no format arguments,

3789

as in @code{printf (foo);}. This may be a security hole if the format

3790

string came from untrusted input and contains @samp{%n}. (This is

3791

currently a subset of what @option{-Wformat-nonliteral} warns about, but

3792

in future warnings may be added to @option{-Wformat-security} that are not

3793

included in @option{-Wformat-nonliteral}.)

3794

3795

@item -Wformat-signedness

3796

@opindex Wformat-signedness

3797

@opindex Wno-format-signedness

3798

If @option{-Wformat} is specified, also warn if the format string

3799

requires an unsigned argument and the argument is signed and vice versa.

3800

3801

@item -Wformat-y2k

3802

@opindex Wformat-y2k

3803

@opindex Wno-format-y2k

3804

If @option{-Wformat} is specified, also warn about @code{strftime}

3805

formats that may yield only a two-digit year.

3806

@end table

3807

3808

@item -Wnonnull

3809

@opindex Wnonnull

3810

@opindex Wno-nonnull

3811

Warn about passing a null pointer for arguments marked as

3812

requiring a non-null value by the @code{nonnull} function attribute.

3813

3814

@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It

3815

can be disabled with the @option{-Wno-nonnull} option.

3816

3817

@item -Wnonnull-compare

3818

@opindex Wnonnull-compare

3819

@opindex Wno-nonnull-compare

3820

Warn when comparing an argument marked with the @code{nonnull}

3821

function attribute against null inside the function.

3822

3823

@option{-Wnonnull-compare} is included in @option{-Wall}. It

3824

can be disabled with the @option{-Wno-nonnull-compare} option.

3825

3826

@item -Wnull-dereference

3827

@opindex Wnull-dereference

3828

@opindex Wno-null-dereference

3829

Warn if the compiler detects paths that trigger erroneous or

3830

undefined behavior due to dereferencing a null pointer. This option

3831

is only active when @option{-fdelete-null-pointer-checks} is active,

3832

which is enabled by optimizations in most targets. The precision of

3833

the warnings depends on the optimization options used.

3834

3835

@item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}

3836

@opindex Winit-self

3837

@opindex Wno-init-self

3838

Warn about uninitialized variables that are initialized with themselves.

3839

Note this option can only be used with the @option{-Wuninitialized} option.

3840

3841

For example, GCC warns about @code{i} being uninitialized in the

3842

following snippet only when @option{-Winit-self} has been specified:

3843

@smallexample

3844

@group

3845

int f()

3846

@{

3847

int i = i;

3848

return i;

3849

@}

3850

@end group

3851

@end smallexample

3852

3853

This warning is enabled by @option{-Wall} in C++.

3854

3855

@item -Wimplicit-int @r{(C and Objective-C only)}

3856

@opindex Wimplicit-int

3857

@opindex Wno-implicit-int

3858

Warn when a declaration does not specify a type.

3859

This warning is enabled by @option{-Wall}.

3860

3861

@item -Wimplicit-function-declaration @r{(C and Objective-C only)}

3862

@opindex Wimplicit-function-declaration

3863

@opindex Wno-implicit-function-declaration

3864

Give a warning whenever a function is used before being declared. In

3865

C99 mode (@option{-std=c99} or @option{-std=gnu99}), this warning is

3866

enabled by default and it is made into an error by

3867

@option{-pedantic-errors}. This warning is also enabled by

3868

@option{-Wall}.

3869

3870

@item -Wimplicit @r{(C and Objective-C only)}

3871

@opindex Wimplicit

3872

@opindex Wno-implicit

3873

Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.

3874

This warning is enabled by @option{-Wall}.

3875

3876

@item -Wignored-qualifiers @r{(C and C++ only)}

3877

@opindex Wignored-qualifiers

3878

@opindex Wno-ignored-qualifiers

3879

Warn if the return type of a function has a type qualifier

3880

such as @code{const}. For ISO C such a type qualifier has no effect,

3881

since the value returned by a function is not an lvalue.

3882

For C++, the warning is only emitted for scalar types or @code{void}.

3883

ISO C prohibits qualified @code{void} return types on function

3884

definitions, so such return types always receive a warning

3885

even without this option.

3886

3887

This warning is also enabled by @option{-Wextra}.

3888

3889

@item -Wignored-attributes @r{(C and C++ only)}

3890

@opindex Wignored-attributes

3891

@opindex Wno-ignored-attributes

3892

Warn when an attribute is ignored. This is different from the

3893

@option{-Wattributes} option in that it warns whenever the compiler decides

3894

to drop an attribute, not that the attribute is either unknown, used in a

3895

wrong place, etc. This warning is enabled by default.

3896

3897

@item -Wmain

3898

@opindex Wmain

3899

@opindex Wno-main

3900

Warn if the type of @code{main} is suspicious. @code{main} should be

3901

a function with external linkage, returning int, taking either zero

3902

arguments, two, or three arguments of appropriate types. This warning

3903

is enabled by default in C++ and is enabled by either @option{-Wall}

3904

or @option{-Wpedantic}.

3905

3906

@item -Wmisleading-indentation @r{(C and C++ only)}

3907

@opindex Wmisleading-indentation

3908

@opindex Wno-misleading-indentation

3909

Warn when the indentation of the code does not reflect the block structure.

3910

Specifically, a warning is issued for @code{if}, @code{else}, @code{while}, and

3911

@code{for} clauses with a guarded statement that does not use braces,

3912

followed by an unguarded statement with the same indentation.

3913

3914

In the following example, the call to ``bar'' is misleadingly indented as

3915

if it were guarded by the ``if'' conditional.

3916

3917

@smallexample

3918

if (some_condition ())

3919

foo ();

3920

bar (); /* Gotcha: this is not guarded by the "if". */

3921

@end smallexample

3922

3923

In the case of mixed tabs and spaces, the warning uses the

3924

@option{-ftabstop=} option to determine if the statements line up

3925

(defaulting to 8).

3926

3927

The warning is not issued for code involving multiline preprocessor logic

3928

such as the following example.

3929

3930

@smallexample

3931

if (flagA)

3932

foo (0);

3933

#if SOME_CONDITION_THAT_DOES_NOT_HOLD

3934

if (flagB)

3935

#endif

3936

foo (1);

3937

@end smallexample

3938

3939

The warning is not issued after a @code{#line} directive, since this

3940

typically indicates autogenerated code, and no assumptions can be made

3941

about the layout of the file that the directive references.

3942

3943

This warning is enabled by @option{-Wall} in C and C++.

3944

3945

@item -Wmissing-braces

3946

@opindex Wmissing-braces

3947

@opindex Wno-missing-braces

3948

Warn if an aggregate or union initializer is not fully bracketed. In

3949

the following example, the initializer for @code{a} is not fully

3950

bracketed, but that for @code{b} is fully bracketed. This warning is

3951

enabled by @option{-Wall} in C.

3952

3953

@smallexample

3954

int a[2][2] = @{ 0, 1, 2, 3 @};

3955

int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};

3956

@end smallexample

3957

3958

This warning is enabled by @option{-Wall}.

3959

3960

@item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}

3961

@opindex Wmissing-include-dirs

3962

@opindex Wno-missing-include-dirs

3963

Warn if a user-supplied include directory does not exist.

3964

3965

@item -Wparentheses

3966

@opindex Wparentheses

3967

@opindex Wno-parentheses

3968

Warn if parentheses are omitted in certain contexts, such

3969

as when there is an assignment in a context where a truth value

3970

is expected, or when operators are nested whose precedence people

3971

often get confused about.

3972

3973

Also warn if a comparison like @code{x<=y<=z} appears; this is

3974

equivalent to @code{(x<=y ? 1 : 0) <= z}, which is a different

3975

interpretation from that of ordinary mathematical notation.

3976

3977

Also warn about constructions where there may be confusion to which

3978

@code{if} statement an @code{else} branch belongs. Here is an example of

3979

such a case:

3980

3981

@smallexample

3982

@group

3983

@{

3984

if (a)

3985

if (b)

3986

foo ();

3987

else

3988

bar ();

3989

@}

3990

@end group

3991

@end smallexample

3992

3993

In C/C++, every @code{else} branch belongs to the innermost possible

3994

@code{if} statement, which in this example is @code{if (b)}. This is

3995

often not what the programmer expected, as illustrated in the above

3996

example by indentation the programmer chose. When there is the

3997

potential for this confusion, GCC issues a warning when this flag

3998

is specified. To eliminate the warning, add explicit braces around

3999

the innermost @code{if} statement so there is no way the @code{else}

4000

can belong to the enclosing @code{if}. The resulting code

4001

looks like this:

4002

4003

@smallexample

4004

@group

4005

@{

4006

if (a)

4007

@{

4008

if (b)

4009

foo ();

4010

else

4011

bar ();

4012

@}

4013

@}

4014

@end group

4015

@end smallexample

4016

4017

Also warn for dangerous uses of the GNU extension to

4018

@code{?:} with omitted middle operand. When the condition

4019

in the @code{?}: operator is a boolean expression, the omitted value is

4020

always 1. Often programmers expect it to be a value computed

4021

inside the conditional expression instead.

4022

4023

This warning is enabled by @option{-Wall}.

4024

4025

@item -Wsequence-point

4026

@opindex Wsequence-point

4027

@opindex Wno-sequence-point

4028

Warn about code that may have undefined semantics because of violations

4029

of sequence point rules in the C and C++ standards.

4030

4031

The C and C++ standards define the order in which expressions in a C/C++

4032

program are evaluated in terms of @dfn{sequence points}, which represent

4033

a partial ordering between the execution of parts of the program: those

4034

executed before the sequence point, and those executed after it. These

4035

occur after the evaluation of a full expression (one which is not part

4036

of a larger expression), after the evaluation of the first operand of a

4037

@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a

4038

function is called (but after the evaluation of its arguments and the

4039

expression denoting the called function), and in certain other places.

4040

Other than as expressed by the sequence point rules, the order of

4041

evaluation of subexpressions of an expression is not specified. All

4042

these rules describe only a partial order rather than a total order,

4043

since, for example, if two functions are called within one expression

4044

with no sequence point between them, the order in which the functions

4045

are called is not specified. However, the standards committee have

4046

ruled that function calls do not overlap.

4047

4048

It is not specified when between sequence points modifications to the

4049

values of objects take effect. Programs whose behavior depends on this

4050

have undefined behavior; the C and C++ standards specify that ``Between

4051

the previous and next sequence point an object shall have its stored

4052

value modified at most once by the evaluation of an expression.

4053

Furthermore, the prior value shall be read only to determine the value

4054

to be stored.''. If a program breaks these rules, the results on any

4055

particular implementation are entirely unpredictable.

4056

4057

Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]

4058

= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not

4059

diagnosed by this option, and it may give an occasional false positive

4060

result, but in general it has been found fairly effective at detecting

4061

this sort of problem in programs.

4062

4063

The standard is worded confusingly, therefore there is some debate

4064

over the precise meaning of the sequence point rules in subtle cases.

4065

Links to discussions of the problem, including proposed formal

4066

definitions, may be found on the GCC readings page, at

4067

@uref{http://gcc.gnu.org/@/readings.html}.

4068

4069

This warning is enabled by @option{-Wall} for C and C++.

4070

4071

@item -Wno-return-local-addr

4072

@opindex Wno-return-local-addr

4073

@opindex Wreturn-local-addr

4074

Do not warn about returning a pointer (or in C++, a reference) to a

4075

variable that goes out of scope after the function returns.

4076

4077

@item -Wreturn-type

4078

@opindex Wreturn-type

4079

@opindex Wno-return-type

4080

Warn whenever a function is defined with a return type that defaults

4081

to @code{int}. Also warn about any @code{return} statement with no

4082

return value in a function whose return type is not @code{void}

4083

(falling off the end of the function body is considered returning

4084

without a value), and about a @code{return} statement with an

4085

expression in a function whose return type is @code{void}.

4086

4087

For C++, a function without return type always produces a diagnostic

4088

message, even when @option{-Wno-return-type} is specified. The only

4089

exceptions are @code{main} and functions defined in system headers.

4090

4091

This warning is enabled by @option{-Wall}.

4092

4093

@item -Wshift-count-negative

4094

@opindex Wshift-count-negative

4095

@opindex Wno-shift-count-negative

4096

Warn if shift count is negative. This warning is enabled by default.

4097

4098

@item -Wshift-count-overflow

4099

@opindex Wshift-count-overflow

4100

@opindex Wno-shift-count-overflow

4101

Warn if shift count >= width of type. This warning is enabled by default.

4102

4103

@item -Wshift-negative-value

4104

@opindex Wshift-negative-value

4105

@opindex Wno-shift-negative-value

4106

Warn if left shifting a negative value. This warning is enabled by

4107

@option{-Wextra} in C99 and C++11 modes (and newer).

4108

4109

@item -Wshift-overflow

4110

@itemx -Wshift-overflow=@var{n}

4111

@opindex Wshift-overflow

4112

@opindex Wno-shift-overflow

4113

Warn about left shift overflows. This warning is enabled by

4114

default in C99 and C++11 modes (and newer).

4115

4116

@table @gcctabopt

4117

@item -Wshift-overflow=1

4118

This is the warning level of @option{-Wshift-overflow} and is enabled

4119

by default in C99 and C++11 modes (and newer). This warning level does

4120

not warn about left-shifting 1 into the sign bit. (However, in C, such

4121

an overflow is still rejected in contexts where an integer constant expression

4122

is required.)

4123

4124

@item -Wshift-overflow=2

4125

This warning level also warns about left-shifting 1 into the sign bit,

4126

unless C++14 mode is active.

4127

@end table

4128

4129

@item -Wswitch

4130

@opindex Wswitch

4131

@opindex Wno-switch

4132

Warn whenever a @code{switch} statement has an index of enumerated type

4133

and lacks a @code{case} for one or more of the named codes of that

4134

enumeration. (The presence of a @code{default} label prevents this

4135

warning.) @code{case} labels outside the enumeration range also

4136

provoke warnings when this option is used (even if there is a

4137

@code{default} label).

4138

This warning is enabled by @option{-Wall}.

4139

4140

@item -Wswitch-default

4141

@opindex Wswitch-default

4142

@opindex Wno-switch-default

4143

Warn whenever a @code{switch} statement does not have a @code{default}

4144

case.

4145

4146

@item -Wswitch-enum

4147

@opindex Wswitch-enum

4148

@opindex Wno-switch-enum

4149

Warn whenever a @code{switch} statement has an index of enumerated type

4150

and lacks a @code{case} for one or more of the named codes of that

4151

enumeration. @code{case} labels outside the enumeration range also

4152

provoke warnings when this option is used. The only difference

4153

between @option{-Wswitch} and this option is that this option gives a

4154

warning about an omitted enumeration code even if there is a

4155

@code{default} label.

4156

4157

@item -Wswitch-bool

4158

@opindex Wswitch-bool

4159

@opindex Wno-switch-bool

4160

Warn whenever a @code{switch} statement has an index of boolean type

4161

and the case values are outside the range of a boolean type.

4162

It is possible to suppress this warning by casting the controlling

4163

expression to a type other than @code{bool}. For example:

4164

@smallexample

4165

@group

4166

switch ((int) (a == 4))

4167

@{

4168

@dots{}

4169

@}

4170

@end group

4171

@end smallexample

4172

This warning is enabled by default for C and C++ programs.

4173

4174

@item -Wsync-nand @r{(C and C++ only)}

4175

@opindex Wsync-nand

4176

@opindex Wno-sync-nand

4177

Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch}

4178

built-in functions are used. These functions changed semantics in GCC 4.4.

4179

4180

@item -Wtrigraphs

4181

@opindex Wtrigraphs

4182

@opindex Wno-trigraphs

4183

Warn if any trigraphs are encountered that might change the meaning of

4184

the program (trigraphs within comments are not warned about).

4185

This warning is enabled by @option{-Wall}.

4186

4187

@item -Wunused-but-set-parameter

4188

@opindex Wunused-but-set-parameter

4189

@opindex Wno-unused-but-set-parameter

4190

Warn whenever a function parameter is assigned to, but otherwise unused

4191

(aside from its declaration).

4192

4193

To suppress this warning use the @code{unused} attribute

4194

(@pxref{Variable Attributes}).

4195

4196

This warning is also enabled by @option{-Wunused} together with

4197

@option{-Wextra}.

4198

4199

@item -Wunused-but-set-variable

4200

@opindex Wunused-but-set-variable

4201

@opindex Wno-unused-but-set-variable

4202

Warn whenever a local variable is assigned to, but otherwise unused

4203

(aside from its declaration).

4204

This warning is enabled by @option{-Wall}.

4205

4206

To suppress this warning use the @code{unused} attribute

4207

(@pxref{Variable Attributes}).

4208

4209

This warning is also enabled by @option{-Wunused}, which is enabled

4210

by @option{-Wall}.

4211

4212

@item -Wunused-function

4213

@opindex Wunused-function

4214

@opindex Wno-unused-function

4215

Warn whenever a static function is declared but not defined or a

4216

non-inline static function is unused.

4217

This warning is enabled by @option{-Wall}.

4218

4219

@item -Wunused-label

4220

@opindex Wunused-label

4221

@opindex Wno-unused-label

4222

Warn whenever a label is declared but not used.

4223

This warning is enabled by @option{-Wall}.

4224

4225

To suppress this warning use the @code{unused} attribute

4226

(@pxref{Variable Attributes}).

4227

4228

@item -Wunused-local-typedefs @r{(C, Objective-C, C++ and Objective-C++ only)}

4229

@opindex Wunused-local-typedefs

4230

Warn when a typedef locally defined in a function is not used.

4231

This warning is enabled by @option{-Wall}.

4232

4233

@item -Wunused-parameter

4234

@opindex Wunused-parameter

4235

@opindex Wno-unused-parameter

4236

Warn whenever a function parameter is unused aside from its declaration.

4237

4238

To suppress this warning use the @code{unused} attribute

4239

(@pxref{Variable Attributes}).

4240

4241

@item -Wno-unused-result

4242

@opindex Wunused-result

4243

@opindex Wno-unused-result

4244

Do not warn if a caller of a function marked with attribute

4245

@code{warn_unused_result} (@pxref{Function Attributes}) does not use

4246

its return value. The default is @option{-Wunused-result}.

4247

4248

@item -Wunused-variable

4249

@opindex Wunused-variable

4250

@opindex Wno-unused-variable

4251

Warn whenever a local or static variable is unused aside from its

4252

declaration. This option implies @option{-Wunused-const-variable=1} for C,

4253

but not for C++. This warning is enabled by @option{-Wall}.

4254

4255

To suppress this warning use the @code{unused} attribute

4256

(@pxref{Variable Attributes}).

4257

4258

@item -Wunused-const-variable

4259

@itemx -Wunused-const-variable=@var{n}

4260

@opindex Wunused-const-variable

4261

@opindex Wno-unused-const-variable

4262

Warn whenever a constant static variable is unused aside from its declaration.

4263

@option{-Wunused-const-variable=1} is enabled by @option{-Wunused-variable}

4264

for C, but not for C++. In C this declares variable storage, but in C++ this

4265

is not an error since const variables take the place of @code{#define}s.

4266

4267

To suppress this warning use the @code{unused} attribute

4268

(@pxref{Variable Attributes}).

4269

4270

@table @gcctabopt

4271

@item -Wunused-const-variable=1

4272

This is the warning level that is enabled by @option{-Wunused-variable} for

4273

C. It warns only about unused static const variables defined in the main

4274

compilation unit, but not about static const variables declared in any

4275

header included.

4276

4277

@item -Wunused-const-variable=2

4278

This warning level also warns for unused constant static variables in

4279

headers (excluding system headers). This is the warning level of

4280

@option{-Wunused-const-variable} and must be explicitly requested since

4281

in C++ this isn't an error and in C it might be harder to clean up all

4282

headers included.

4283

@end table

4284

4285

@item -Wunused-value

4286

@opindex Wunused-value

4287

@opindex Wno-unused-value

4288

Warn whenever a statement computes a result that is explicitly not

4289

used. To suppress this warning cast the unused expression to

4290

@code{void}. This includes an expression-statement or the left-hand

4291

side of a comma expression that contains no side effects. For example,

4292

an expression such as @code{x[i,j]} causes a warning, while

4293

@code{x[(void)i,j]} does not.

4294

4295

This warning is enabled by @option{-Wall}.

4296

4297

@item -Wunused

4298

@opindex Wunused

4299

@opindex Wno-unused

4300

All the above @option{-Wunused} options combined.

4301

4302

In order to get a warning about an unused function parameter, you must

4303

either specify @option{-Wextra -Wunused} (note that @option{-Wall} implies

4304

@option{-Wunused}), or separately specify @option{-Wunused-parameter}.

4305

4306

@item -Wuninitialized

4307

@opindex Wuninitialized

4308

@opindex Wno-uninitialized

4309

Warn if an automatic variable is used without first being initialized

4310

or if a variable may be clobbered by a @code{setjmp} call. In C++,

4311

warn if a non-static reference or non-static @code{const} member

4312

appears in a class without constructors.

4313

4314

If you want to warn about code that uses the uninitialized value of the

4315

variable in its own initializer, use the @option{-Winit-self} option.

4316

4317

These warnings occur for individual uninitialized or clobbered

4318

elements of structure, union or array variables as well as for

4319

variables that are uninitialized or clobbered as a whole. They do

4320

not occur for variables or elements declared @code{volatile}. Because

4321

these warnings depend on optimization, the exact variables or elements

4322

for which there are warnings depends on the precise optimization

4323

options and version of GCC used.

4324

4325

Note that there may be no warning about a variable that is used only

4326

to compute a value that itself is never used, because such

4327

computations may be deleted by data flow analysis before the warnings

4328

are printed.

4329

4330

@item -Winvalid-memory-model

4331

@opindex Winvalid-memory-model

4332

@opindex Wno-invalid-memory-model

4333

Warn for invocations of @ref{__atomic Builtins}, @ref{__sync Builtins},

4334

and the C11 atomic generic functions with a memory consistency argument

4335

that is either invalid for the operation or outside the range of values

4336

of the @code{memory_order} enumeration. For example, since the

4337

@code{__atomic_store} and @code{__atomic_store_n} built-ins are only

4338

defined for the relaxed, release, and sequentially consistent memory

4339

orders the following code is diagnosed:

4340

4341

@smallexample

4342

void store (int *i)

4343

@{

4344

__atomic_store_n (i, 0, memory_order_consume);

4345

@}

4346

@end smallexample

4347

4348

@option{-Winvalid-memory-model} is enabled by default.

4349

4350

@item -Wmaybe-uninitialized

4351

@opindex Wmaybe-uninitialized

4352

@opindex Wno-maybe-uninitialized

4353

For an automatic variable, if there exists a path from the function

4354

entry to a use of the variable that is initialized, but there exist

4355

some other paths for which the variable is not initialized, the compiler

4356

emits a warning if it cannot prove the uninitialized paths are not

4357

executed at run time. These warnings are made optional because GCC is

4358

not smart enough to see all the reasons why the code might be correct

4359

in spite of appearing to have an error. Here is one example of how

4360

this can happen:

4361

4362

@smallexample

4363

@group

4364

@{

4365

int x;

4366

switch (y)

4367

@{

4368

case 1: x = 1;

4369

break;

4370

case 2: x = 4;

4371

break;

4372

case 3: x = 5;

4373

@}

4374

foo (x);

4375

@}

4376

@end group

4377

@end smallexample

4378

4379

@noindent

4380

If the value of @code{y} is always 1, 2 or 3, then @code{x} is

4381

always initialized, but GCC doesn't know this. To suppress the

4382

warning, you need to provide a default case with assert(0) or

4383

similar code.

4384

4385

@cindex @code{longjmp} warnings

4386

This option also warns when a non-volatile automatic variable might be

4387

changed by a call to @code{longjmp}. These warnings as well are possible

4388

only in optimizing compilation.

4389

4390

The compiler sees only the calls to @code{setjmp}. It cannot know

4391

where @code{longjmp} will be called; in fact, a signal handler could

4392

call it at any point in the code. As a result, you may get a warning

4393

even when there is in fact no problem because @code{longjmp} cannot

4394

in fact be called at the place that would cause a problem.

4395

4396

Some spurious warnings can be avoided if you declare all the functions

4397

you use that never return as @code{noreturn}. @xref{Function

4398

Attributes}.

4399

4400

This warning is enabled by @option{-Wall} or @option{-Wextra}.

4401

4402

@item -Wunknown-pragmas

4403

@opindex Wunknown-pragmas

4404

@opindex Wno-unknown-pragmas

4405

@cindex warning for unknown pragmas

4406

@cindex unknown pragmas, warning

4407

@cindex pragmas, warning of unknown

4408

Warn when a @code{#pragma} directive is encountered that is not understood by

4409

GCC@. If this command-line option is used, warnings are even issued

4410

for unknown pragmas in system header files. This is not the case if

4411

the warnings are only enabled by the @option{-Wall} command-line option.

4412

4413

@item -Wno-pragmas

4414

@opindex Wno-pragmas

4415

@opindex Wpragmas

4416

Do not warn about misuses of pragmas, such as incorrect parameters,

4417

invalid syntax, or conflicts between pragmas. See also

4418

@option{-Wunknown-pragmas}.

4419

4420

@item -Wstrict-aliasing

4421

@opindex Wstrict-aliasing

4422

@opindex Wno-strict-aliasing

4423

This option is only active when @option{-fstrict-aliasing} is active.

4424

It warns about code that might break the strict aliasing rules that the

4425

compiler is using for optimization. The warning does not catch all

4426

cases, but does attempt to catch the more common pitfalls. It is

4427

included in @option{-Wall}.

4428

It is equivalent to @option{-Wstrict-aliasing=3}

4429

4430

@item -Wstrict-aliasing=n

4431

@opindex Wstrict-aliasing=n

4432

This option is only active when @option{-fstrict-aliasing} is active.

4433

It warns about code that might break the strict aliasing rules that the

4434

compiler is using for optimization.

4435

Higher levels correspond to higher accuracy (fewer false positives).

4436

Higher levels also correspond to more effort, similar to the way @option{-O}

4437

works.

4438

@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=3}.

4439

4440

Level 1: Most aggressive, quick, least accurate.

4441

Possibly useful when higher levels

4442

do not warn but @option{-fstrict-aliasing} still breaks the code, as it has very few

4443

false negatives. However, it has many false positives.

4444

Warns for all pointer conversions between possibly incompatible types,

4445

even if never dereferenced. Runs in the front end only.

4446

4447

Level 2: Aggressive, quick, not too precise.

4448

May still have many false positives (not as many as level 1 though),

4449

and few false negatives (but possibly more than level 1).

4450

Unlike level 1, it only warns when an address is taken. Warns about

4451

incomplete types. Runs in the front end only.

4452

4453

Level 3 (default for @option{-Wstrict-aliasing}):

4454

Should have very few false positives and few false

4455

negatives. Slightly slower than levels 1 or 2 when optimization is enabled.

4456

Takes care of the common pun+dereference pattern in the front end:

4457

@code{*(int*)&some_float}.

4458

If optimization is enabled, it also runs in the back end, where it deals

4459

with multiple statement cases using flow-sensitive points-to information.

4460

Only warns when the converted pointer is dereferenced.

4461

Does not warn about incomplete types.

4462

4463

@item -Wstrict-overflow

4464

@itemx -Wstrict-overflow=@var{n}

4465

@opindex Wstrict-overflow

4466

@opindex Wno-strict-overflow

4467

This option is only active when @option{-fstrict-overflow} is active.

4468

It warns about cases where the compiler optimizes based on the

4469

assumption that signed overflow does not occur. Note that it does not

4470

warn about all cases where the code might overflow: it only warns

4471

about cases where the compiler implements some optimization. Thus

4472

this warning depends on the optimization level.

4473

4474

An optimization that assumes that signed overflow does not occur is

4475

perfectly safe if the values of the variables involved are such that

4476

overflow never does, in fact, occur. Therefore this warning can

4477

easily give a false positive: a warning about code that is not

4478

actually a problem. To help focus on important issues, several

4479

warning levels are defined. No warnings are issued for the use of

4480

undefined signed overflow when estimating how many iterations a loop

4481

requires, in particular when determining whether a loop will be

4482

executed at all.

4483

4484

@table @gcctabopt

4485

@item -Wstrict-overflow=1

4486

Warn about cases that are both questionable and easy to avoid. For

4487

example, with @option{-fstrict-overflow}, the compiler simplifies

4488

@code{x + 1 > x} to @code{1}. This level of

4489

@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels

4490

are not, and must be explicitly requested.

4491

4492

@item -Wstrict-overflow=2

4493

Also warn about other cases where a comparison is simplified to a

4494

constant. For example: @code{abs (x) >= 0}. This can only be

4495

simplified when @option{-fstrict-overflow} is in effect, because

4496

@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than

4497

zero. @option{-Wstrict-overflow} (with no level) is the same as

4498

@option{-Wstrict-overflow=2}.

4499

4500

@item -Wstrict-overflow=3

4501

Also warn about other cases where a comparison is simplified. For

4502

example: @code{x + 1 > 1} is simplified to @code{x > 0}.

4503

4504

@item -Wstrict-overflow=4

4505

Also warn about other simplifications not covered by the above cases.

4506

For example: @code{(x * 10) / 5} is simplified to @code{x * 2}.

4507

4508

@item -Wstrict-overflow=5

4509

Also warn about cases where the compiler reduces the magnitude of a

4510

constant involved in a comparison. For example: @code{x + 2 > y} is

4511

simplified to @code{x + 1 >= y}. This is reported only at the

4512

highest warning level because this simplification applies to many

4513

comparisons, so this warning level gives a very large number of

4514

false positives.

4515

@end table

4516

4517

@item -Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{]}

4518

@opindex Wsuggest-attribute=

4519

@opindex Wno-suggest-attribute=

4520

Warn for cases where adding an attribute may be beneficial. The

4521

attributes currently supported are listed below.

4522

4523

@table @gcctabopt

4524

@item -Wsuggest-attribute=pure

4525

@itemx -Wsuggest-attribute=const

4526

@itemx -Wsuggest-attribute=noreturn

4527

@opindex Wsuggest-attribute=pure

4528

@opindex Wno-suggest-attribute=pure

4529

@opindex Wsuggest-attribute=const

4530

@opindex Wno-suggest-attribute=const

4531

@opindex Wsuggest-attribute=noreturn

4532

@opindex Wno-suggest-attribute=noreturn

4533

4534

Warn about functions that might be candidates for attributes

4535

@code{pure}, @code{const} or @code{noreturn}. The compiler only warns for

4536

functions visible in other compilation units or (in the case of @code{pure} and

4537

@code{const}) if it cannot prove that the function returns normally. A function

4538

returns normally if it doesn't contain an infinite loop or return abnormally

4539

by throwing, calling @code{abort} or trapping. This analysis requires option

4540

@option{-fipa-pure-const}, which is enabled by default at @option{-O} and

4541

higher. Higher optimization levels improve the accuracy of the analysis.

4542

4543

@item -Wsuggest-attribute=format

4544

@itemx -Wmissing-format-attribute

4545

@opindex Wsuggest-attribute=format

4546

@opindex Wmissing-format-attribute

4547

@opindex Wno-suggest-attribute=format

4548

@opindex Wno-missing-format-attribute

4549

@opindex Wformat

4550

@opindex Wno-format

4551

4552

Warn about function pointers that might be candidates for @code{format}

4553

attributes. Note these are only possible candidates, not absolute ones.

4554

GCC guesses that function pointers with @code{format} attributes that

4555

are used in assignment, initialization, parameter passing or return

4556

statements should have a corresponding @code{format} attribute in the

4557

resulting type. I.e.@: the left-hand side of the assignment or

4558

initialization, the type of the parameter variable, or the return type

4559

of the containing function respectively should also have a @code{format}

4560

attribute to avoid the warning.

4561

4562

GCC also warns about function definitions that might be

4563

candidates for @code{format} attributes. Again, these are only

4564

possible candidates. GCC guesses that @code{format} attributes

4565

might be appropriate for any function that calls a function like

4566

@code{vprintf} or @code{vscanf}, but this might not always be the

4567

case, and some functions for which @code{format} attributes are

4568

appropriate may not be detected.

4569

@end table

4570

4571

@item -Wsuggest-final-types

4572

@opindex Wno-suggest-final-types

4573

@opindex Wsuggest-final-types

4574

Warn about types with virtual methods where code quality would be improved

4575

if the type were declared with the C++11 @code{final} specifier,

4576

or, if possible,

4577

declared in an anonymous namespace. This allows GCC to more aggressively

4578

devirtualize the polymorphic calls. This warning is more effective with link

4579

time optimization, where the information about the class hierarchy graph is

4580

more complete.

4581

4582

@item -Wsuggest-final-methods

4583

@opindex Wno-suggest-final-methods

4584

@opindex Wsuggest-final-methods

4585

Warn about virtual methods where code quality would be improved if the method

4586

were declared with the C++11 @code{final} specifier,

4587

or, if possible, its type were

4588

declared in an anonymous namespace or with the @code{final} specifier.

4589

This warning is

4590

more effective with link time optimization, where the information about the

4591

class hierarchy graph is more complete. It is recommended to first consider

4592

suggestions of @option{-Wsuggest-final-types} and then rebuild with new

4593

annotations.

4594

4595

@item -Wsuggest-override

4596

Warn about overriding virtual functions that are not marked with the override

4597

keyword.

4598

4599

@item -Warray-bounds

4600

@itemx -Warray-bounds=@var{n}

4601

@opindex Wno-array-bounds

4602

@opindex Warray-bounds

4603

This option is only active when @option{-ftree-vrp} is active

4604

(default for @option{-O2} and above). It warns about subscripts to arrays

4605

that are always out of bounds. This warning is enabled by @option{-Wall}.

4606

4607

@table @gcctabopt

4608

@item -Warray-bounds=1

4609

This is the warning level of @option{-Warray-bounds} and is enabled

4610

by @option{-Wall}; higher levels are not, and must be explicitly requested.

4611

4612

@item -Warray-bounds=2

4613

This warning level also warns about out of bounds access for

4614

arrays at the end of a struct and for arrays accessed through

4615

pointers. This warning level may give a larger number of

4616

false positives and is deactivated by default.

4617

@end table

4618

4619

@item -Wbool-compare

4620

@opindex Wno-bool-compare

4621

@opindex Wbool-compare

4622

Warn about boolean expression compared with an integer value different from

4623

@code{true}/@code{false}. For instance, the following comparison is

4624

always false:

4625

@smallexample

4626

int n = 5;

4627

@dots{}

4628

if ((n > 1) == 2) @{ @dots{} @}

4629

@end smallexample

4630

This warning is enabled by @option{-Wall}.

4631

4632

@item -Wduplicated-cond

4633

@opindex Wno-duplicated-cond

4634

@opindex Wduplicated-cond

4635

Warn about duplicated conditions in an if-else-if chain. For instance,

4636

warn for the following code:

4637

@smallexample

4638

if (p->q != NULL) @{ @dots{} @}

4639

else if (p->q != NULL) @{ @dots{} @}

4640

@end smallexample

4641

4642

@item -Wframe-address

4643

@opindex Wno-frame-address

4644

@opindex Wframe-address

4645

Warn when the @samp{__builtin_frame_address} or @samp{__builtin_return_address}

4646

is called with an argument greater than 0. Such calls may return indeterminate

4647

values or crash the program. The warning is included in @option{-Wall}.

4648

4649

@item -Wno-discarded-qualifiers @r{(C and Objective-C only)}

4650

@opindex Wno-discarded-qualifiers

4651

@opindex Wdiscarded-qualifiers

4652

Do not warn if type qualifiers on pointers are being discarded.

4653

Typically, the compiler warns if a @code{const char *} variable is

4654

passed to a function that takes a @code{char *} parameter. This option

4655

can be used to suppress such a warning.

4656

4657

@item -Wno-discarded-array-qualifiers @r{(C and Objective-C only)}

4658

@opindex Wno-discarded-array-qualifiers

4659

@opindex Wdiscarded-array-qualifiers

4660

Do not warn if type qualifiers on arrays which are pointer targets

4661

are being discarded. Typically, the compiler warns if a

4662

@code{const int (*)[]} variable is passed to a function that

4663

takes a @code{int (*)[]} parameter. This option can be used to

4664

suppress such a warning.

4665

4666

@item -Wno-incompatible-pointer-types @r{(C and Objective-C only)}

4667

@opindex Wno-incompatible-pointer-types

4668

@opindex Wincompatible-pointer-types

4669

Do not warn when there is a conversion between pointers that have incompatible

4670

types. This warning is for cases not covered by @option{-Wno-pointer-sign},

4671

which warns for pointer argument passing or assignment with different

4672

signedness.

4673

4674

@item -Wno-int-conversion @r{(C and Objective-C only)}

4675

@opindex Wno-int-conversion

4676

@opindex Wint-conversion

4677

Do not warn about incompatible integer to pointer and pointer to integer

4678

conversions. This warning is about implicit conversions; for explicit

4679

conversions the warnings @option{-Wno-int-to-pointer-cast} and

4680

@option{-Wno-pointer-to-int-cast} may be used.

4681

4682

@item -Wno-div-by-zero

4683

@opindex Wno-div-by-zero

4684

@opindex Wdiv-by-zero

4685

Do not warn about compile-time integer division by zero. Floating-point

4686

division by zero is not warned about, as it can be a legitimate way of

4687

obtaining infinities and NaNs.

4688

4689

@item -Wsystem-headers

4690

@opindex Wsystem-headers

4691

@opindex Wno-system-headers

4692

@cindex warnings from system headers

4693

@cindex system headers, warnings from

4694

Print warning messages for constructs found in system header files.

4695

Warnings from system headers are normally suppressed, on the assumption

4696

that they usually do not indicate real problems and would only make the

4697

compiler output harder to read. Using this command-line option tells

4698

GCC to emit warnings from system headers as if they occurred in user

4699

code. However, note that using @option{-Wall} in conjunction with this

4700

option does @emph{not} warn about unknown pragmas in system

4701

headers---for that, @option{-Wunknown-pragmas} must also be used.

4702

4703

@item -Wtautological-compare

4704

@opindex Wtautological-compare

4705

@opindex Wno-tautological-compare

4706

Warn if a self-comparison always evaluates to true or false. This

4707

warning detects various mistakes such as:

4708

@smallexample

4709

int i = 1;

4710

@dots{}

4711

if (i > i) @{ @dots{} @}

4712

@end smallexample

4713

This warning is enabled by @option{-Wall}.

4714

4715

@item -Wtrampolines

4716

@opindex Wtrampolines

4717

@opindex Wno-trampolines

4718

Warn about trampolines generated for pointers to nested functions.

4719

A trampoline is a small piece of data or code that is created at run

4720

time on the stack when the address of a nested function is taken, and is

4721

used to call the nested function indirectly. For some targets, it is

4722

made up of data only and thus requires no special treatment. But, for

4723

most targets, it is made up of code and thus requires the stack to be

4724

made executable in order for the program to work properly.

4725

4726

@item -Wfloat-equal

4727

@opindex Wfloat-equal

4728

@opindex Wno-float-equal

4729

Warn if floating-point values are used in equality comparisons.

4730

4731

The idea behind this is that sometimes it is convenient (for the

4732

programmer) to consider floating-point values as approximations to

4733

infinitely precise real numbers. If you are doing this, then you need

4734

to compute (by analyzing the code, or in some other way) the maximum or

4735

likely maximum error that the computation introduces, and allow for it

4736

when performing comparisons (and when producing output, but that's a

4737

different problem). In particular, instead of testing for equality, you

4738

should check to see whether the two values have ranges that overlap; and

4739

this is done with the relational operators, so equality comparisons are

4740

probably mistaken.

4741

4742

@item -Wtraditional @r{(C and Objective-C only)}

4743

@opindex Wtraditional

4744

@opindex Wno-traditional

4745

Warn about certain constructs that behave differently in traditional and

4746

ISO C@. Also warn about ISO C constructs that have no traditional C

4747

equivalent, and/or problematic constructs that should be avoided.

4748

4749

@itemize @bullet

4750

@item

4751

Macro parameters that appear within string literals in the macro body.

4752

In traditional C macro replacement takes place within string literals,

4753

but in ISO C it does not.

4754

4755

@item

4756

In traditional C, some preprocessor directives did not exist.

4757

Traditional preprocessors only considered a line to be a directive

4758

if the @samp{#} appeared in column 1 on the line. Therefore

4759

@option{-Wtraditional} warns about directives that traditional C

4760

understands but ignores because the @samp{#} does not appear as the

4761

first character on the line. It also suggests you hide directives like

4762

@code{#pragma} not understood by traditional C by indenting them. Some

4763

traditional implementations do not recognize @code{#elif}, so this option

4764

suggests avoiding it altogether.

4765

4766

@item

4767

A function-like macro that appears without arguments.

4768

4769

@item

4770

The unary plus operator.

4771

4772

@item

4773

The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating-point

4774

constant suffixes. (Traditional C does support the @samp{L} suffix on integer

4775

constants.) Note, these suffixes appear in macros defined in the system

4776

headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.

4777

Use of these macros in user code might normally lead to spurious

4778

warnings, however GCC's integrated preprocessor has enough context to

4779

avoid warning in these cases.

4780

4781

@item

4782

A function declared external in one block and then used after the end of

4783

the block.

4784

4785

@item

4786

A @code{switch} statement has an operand of type @code{long}.

4787

4788

@item

4789

A non-@code{static} function declaration follows a @code{static} one.

4790

This construct is not accepted by some traditional C compilers.

4791

4792

@item

4793

The ISO type of an integer constant has a different width or

4794

signedness from its traditional type. This warning is only issued if

4795

the base of the constant is ten. I.e.@: hexadecimal or octal values, which

4796

typically represent bit patterns, are not warned about.

4797

4798

@item

4799

Usage of ISO string concatenation is detected.

4800

4801

@item

4802

Initialization of automatic aggregates.

4803

4804

@item

4805

Identifier conflicts with labels. Traditional C lacks a separate

4806

namespace for labels.

4807

4808

@item

4809

Initialization of unions. If the initializer is zero, the warning is

4810

omitted. This is done under the assumption that the zero initializer in

4811

user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing

4812

initializer warnings and relies on default initialization to zero in the

4813

traditional C case.

4814

4815

@item

4816

Conversions by prototypes between fixed/floating-point values and vice

4817

versa. The absence of these prototypes when compiling with traditional

4818

C causes serious problems. This is a subset of the possible

4819

conversion warnings; for the full set use @option{-Wtraditional-conversion}.

4820

4821

@item

4822

Use of ISO C style function definitions. This warning intentionally is

4823

@emph{not} issued for prototype declarations or variadic functions

4824

because these ISO C features appear in your code when using

4825

libiberty's traditional C compatibility macros, @code{PARAMS} and

4826

@code{VPARAMS}. This warning is also bypassed for nested functions

4827

because that feature is already a GCC extension and thus not relevant to

4828

traditional C compatibility.

4829

@end itemize

4830

4831

@item -Wtraditional-conversion @r{(C and Objective-C only)}

4832

@opindex Wtraditional-conversion

4833

@opindex Wno-traditional-conversion

4834

Warn if a prototype causes a type conversion that is different from what

4835

would happen to the same argument in the absence of a prototype. This

4836

includes conversions of fixed point to floating and vice versa, and

4837

conversions changing the width or signedness of a fixed-point argument

4838

except when the same as the default promotion.

4839

4840

@item -Wdeclaration-after-statement @r{(C and Objective-C only)}

4841

@opindex Wdeclaration-after-statement

4842

@opindex Wno-declaration-after-statement

4843

Warn when a declaration is found after a statement in a block. This

4844

construct, known from C++, was introduced with ISO C99 and is by default

4845

allowed in GCC@. It is not supported by ISO C90. @xref{Mixed Declarations}.

4846

4847

@item -Wundef

4848

@opindex Wundef

4849

@opindex Wno-undef

4850

Warn if an undefined identifier is evaluated in an @code{#if} directive.

4851

4852

@item -Wno-endif-labels

4853

@opindex Wno-endif-labels

4854

@opindex Wendif-labels

4855

Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.

4856

4857

@item -Wshadow

4858

@opindex Wshadow

4859

@opindex Wno-shadow

4860

Warn whenever a local variable or type declaration shadows another

4861

variable, parameter, type, class member (in C++), or instance variable

4862

(in Objective-C) or whenever a built-in function is shadowed. Note

4863

that in C++, the compiler warns if a local variable shadows an

4864

explicit typedef, but not if it shadows a struct/class/enum.

4865

4866

@item -Wno-shadow-ivar @r{(Objective-C only)}

4867

@opindex Wno-shadow-ivar

4868

@opindex Wshadow-ivar

4869

Do not warn whenever a local variable shadows an instance variable in an

4870

Objective-C method.

4871

4872

@item -Wlarger-than=@var{len}

4873

@opindex Wlarger-than=@var{len}

4874

@opindex Wlarger-than-@var{len}

4875

Warn whenever an object of larger than @var{len} bytes is defined.

4876

4877

@item -Wframe-larger-than=@var{len}

4878

@opindex Wframe-larger-than

4879

Warn if the size of a function frame is larger than @var{len} bytes.

4880

The computation done to determine the stack frame size is approximate

4881

and not conservative.

4882

The actual requirements may be somewhat greater than @var{len}

4883

even if you do not get a warning. In addition, any space allocated

4884

via @code{alloca}, variable-length arrays, or related constructs

4885

is not included by the compiler when determining

4886

whether or not to issue a warning.

4887

4888

@item -Wno-free-nonheap-object

4889

@opindex Wno-free-nonheap-object

4890

@opindex Wfree-nonheap-object

4891

Do not warn when attempting to free an object that was not allocated

4892

on the heap.

4893

4894

@item -Wstack-usage=@var{len}

4895

@opindex Wstack-usage

4896

Warn if the stack usage of a function might be larger than @var{len} bytes.

4897

The computation done to determine the stack usage is conservative.

4898

Any space allocated via @code{alloca}, variable-length arrays, or related

4899

constructs is included by the compiler when determining whether or not to

4900

issue a warning.

4901

4902

The message is in keeping with the output of @option{-fstack-usage}.

4903

4904

@itemize

4905

@item

4906

If the stack usage is fully static but exceeds the specified amount, it's:

4907

4908

@smallexample

4909

warning: stack usage is 1120 bytes

4910

@end smallexample

4911

@item

4912

If the stack usage is (partly) dynamic but bounded, it's:

4913

4914

@smallexample

4915

warning: stack usage might be 1648 bytes

4916

@end smallexample

4917

@item

4918

If the stack usage is (partly) dynamic and not bounded, it's:

4919

4920

@smallexample

4921

warning: stack usage might be unbounded

4922

@end smallexample

4923

@end itemize

4924

4925

@item -Wunsafe-loop-optimizations

4926

@opindex Wunsafe-loop-optimizations

4927

@opindex Wno-unsafe-loop-optimizations

4928

Warn if the loop cannot be optimized because the compiler cannot

4929

assume anything on the bounds of the loop indices. With

4930

@option{-funsafe-loop-optimizations} warn if the compiler makes

4931

such assumptions.

4932

4933

@item -Wno-pedantic-ms-format @r{(MinGW targets only)}

4934

@opindex Wno-pedantic-ms-format

4935

@opindex Wpedantic-ms-format

4936

When used in combination with @option{-Wformat}

4937

and @option{-pedantic} without GNU extensions, this option

4938

disables the warnings about non-ISO @code{printf} / @code{scanf} format

4939

width specifiers @code{I32}, @code{I64}, and @code{I} used on Windows targets,

4940

which depend on the MS runtime.

4941

4942

@item -Wplacement-new

4943

@itemx -Wplacement-new=@var{n}

4944

@opindex Wplacement-new

4945

@opindex Wno-placement-new

4946

Warn about placement new expressions with undefined behavior, such as

4947

constructing an object in a buffer that is smaller than the type of

4948

the object. For example, the placement new expression below is diagnosed

4949

because it attempts to construct an array of 64 integers in a buffer only

4950

64 bytes large.

4951

@smallexample

4952

char buf [64];

4953

new (buf) int[64];

4954

@end smallexample

4955

This warning is enabled by default.

4956

4957

@table @gcctabopt

4958

@item -Wplacement-new=1

4959

This is the default warning level of @option{-Wplacement-new}. At this

4960

level the warning is not issued for some strictly undefined constructs that

4961

GCC allows as extensions for compatibility with legacy code. For example,

4962

the following @code{new} expression is not diagnosed at this level even

4963

though it has undefined behavior according to the C++ standard because

4964

it writes past the end of the one-element array.

4965

@smallexample

4966

struct S @{ int n, a[1]; @};

4967

S *s = (S *)malloc (sizeof *s + 31 * sizeof s->a[0]);

4968

new (s->a)int [32]();

4969

@end smallexample

4970

4971

@item -Wplacement-new=2

4972

At this level, in addition to diagnosing all the same constructs as at level

4973

1, a diagnostic is also issued for placement new expressions that construct

4974

an object in the last member of structure whose type is an array of a single

4975

element and whose size is less than the size of the object being constructed.

4976

While the previous example would be diagnosed, the following construct makes

4977

use of the flexible member array extension to avoid the warning at level 2.

4978

@smallexample

4979

struct S @{ int n, a[]; @};

4980

S *s = (S *)malloc (sizeof *s + 32 * sizeof s->a[0]);

4981

new (s->a)int [32]();

4982

@end smallexample

4983

4984

@end table

4985

4986

@item -Wpointer-arith

4987

@opindex Wpointer-arith

4988

@opindex Wno-pointer-arith

4989

Warn about anything that depends on the ``size of'' a function type or

4990

of @code{void}. GNU C assigns these types a size of 1, for

4991

convenience in calculations with @code{void *} pointers and pointers

4992

to functions. In C++, warn also when an arithmetic operation involves

4993

@code{NULL}. This warning is also enabled by @option{-Wpedantic}.

4994

4995

@item -Wtype-limits

4996

@opindex Wtype-limits

4997

@opindex Wno-type-limits

4998

Warn if a comparison is always true or always false due to the limited

4999

range of the data type, but do not warn for constant expressions. For

5000

example, warn if an unsigned variable is compared against zero with

5001

@code{<} or @code{>=}. This warning is also enabled by

5002

@option{-Wextra}.

5003

5004

@item -Wbad-function-cast @r{(C and Objective-C only)}

5005

@opindex Wbad-function-cast

5006

@opindex Wno-bad-function-cast

5007

Warn when a function call is cast to a non-matching type.

5008

For example, warn if a call to a function returning an integer type

5009

is cast to a pointer type.

5010

5011

@item -Wc90-c99-compat @r{(C and Objective-C only)}

5012

@opindex Wc90-c99-compat

5013

@opindex Wno-c90-c99-compat

5014

Warn about features not present in ISO C90, but present in ISO C99.

5015

For instance, warn about use of variable length arrays, @code{long long}

5016

type, @code{bool} type, compound literals, designated initializers, and so

5017

on. This option is independent of the standards mode. Warnings are disabled

5018

in the expression that follows @code{__extension__}.

5019

5020

@item -Wc99-c11-compat @r{(C and Objective-C only)}

5021

@opindex Wc99-c11-compat

5022

@opindex Wno-c99-c11-compat

5023

Warn about features not present in ISO C99, but present in ISO C11.

5024

For instance, warn about use of anonymous structures and unions,

5025

@code{_Atomic} type qualifier, @code{_Thread_local} storage-class specifier,

5026

@code{_Alignas} specifier, @code{Alignof} operator, @code{_Generic} keyword,

5027

and so on. This option is independent of the standards mode. Warnings are

5028

disabled in the expression that follows @code{__extension__}.

5029

5030

@item -Wc++-compat @r{(C and Objective-C only)}

5031

@opindex Wc++-compat

5032

Warn about ISO C constructs that are outside of the common subset of

5033

ISO C and ISO C++, e.g.@: request for implicit conversion from

5034

@code{void *} to a pointer to non-@code{void} type.

5035

5036

@item -Wc++11-compat @r{(C++ and Objective-C++ only)}

5037

@opindex Wc++11-compat

5038

Warn about C++ constructs whose meaning differs between ISO C++ 1998

5039

and ISO C++ 2011, e.g., identifiers in ISO C++ 1998 that are keywords

5040

in ISO C++ 2011. This warning turns on @option{-Wnarrowing} and is

5041

enabled by @option{-Wall}.

5042

5043

@item -Wc++14-compat @r{(C++ and Objective-C++ only)}

5044

@opindex Wc++14-compat

5045

Warn about C++ constructs whose meaning differs between ISO C++ 2011

5046

and ISO C++ 2014. This warning is enabled by @option{-Wall}.

5047

5048

@item -Wcast-qual

5049

@opindex Wcast-qual

5050

@opindex Wno-cast-qual

5051

Warn whenever a pointer is cast so as to remove a type qualifier from

5052

the target type. For example, warn if a @code{const char *} is cast

5053

to an ordinary @code{char *}.

5054

5055

Also warn when making a cast that introduces a type qualifier in an

5056

unsafe way. For example, casting @code{char **} to @code{const char **}

5057

is unsafe, as in this example:

5058

5059

@smallexample

5060

/* p is char ** value. */

5061

const char **q = (const char **) p;

5062

/* Assignment of readonly string to const char * is OK. */

5063

*q = "string";

5064

/* Now char** pointer points to read-only memory. */

5065

**p = 'b';

5066

@end smallexample

5067

5068

@item -Wcast-align

5069

@opindex Wcast-align

5070

@opindex Wno-cast-align

5071

Warn whenever a pointer is cast such that the required alignment of the

5072

target is increased. For example, warn if a @code{char *} is cast to

5073

an @code{int *} on machines where integers can only be accessed at

5074

two- or four-byte boundaries.

5075

5076

@item -Wwrite-strings

5077

@opindex Wwrite-strings

5078

@opindex Wno-write-strings

5079

When compiling C, give string constants the type @code{const

5080

char[@var{length}]} so that copying the address of one into a

5081

non-@code{const} @code{char *} pointer produces a warning. These

5082

warnings help you find at compile time code that can try to write

5083

into a string constant, but only if you have been very careful about

5084

using @code{const} in declarations and prototypes. Otherwise, it is

5085

just a nuisance. This is why we did not make @option{-Wall} request

5086

these warnings.

5087

5088

When compiling C++, warn about the deprecated conversion from string

5089

literals to @code{char *}. This warning is enabled by default for C++

5090

programs.

5091

5092

@item -Wclobbered

5093

@opindex Wclobbered

5094

@opindex Wno-clobbered

5095

Warn for variables that might be changed by @code{longjmp} or

5096

@code{vfork}. This warning is also enabled by @option{-Wextra}.

5097

5098

@item -Wconditionally-supported @r{(C++ and Objective-C++ only)}

5099

@opindex Wconditionally-supported

5100

@opindex Wno-conditionally-supported

5101

Warn for conditionally-supported (C++11 [intro.defs]) constructs.

5102

5103

@item -Wconversion

5104

@opindex Wconversion

5105

@opindex Wno-conversion

5106

Warn for implicit conversions that may alter a value. This includes

5107

conversions between real and integer, like @code{abs (x)} when

5108

@code{x} is @code{double}; conversions between signed and unsigned,

5109

like @code{unsigned ui = -1}; and conversions to smaller types, like

5110

@code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs

5111

((int) x)} and @code{ui = (unsigned) -1}, or if the value is not

5112

changed by the conversion like in @code{abs (2.0)}. Warnings about

5113

conversions between signed and unsigned integers can be disabled by

5114

using @option{-Wno-sign-conversion}.

5115

5116

For C++, also warn for confusing overload resolution for user-defined

5117

conversions; and conversions that never use a type conversion

5118

operator: conversions to @code{void}, the same type, a base class or a

5119

reference to them. Warnings about conversions between signed and

5120

unsigned integers are disabled by default in C++ unless

5121

@option{-Wsign-conversion} is explicitly enabled.

5122

5123

@item -Wno-conversion-null @r{(C++ and Objective-C++ only)}

5124

@opindex Wconversion-null

5125

@opindex Wno-conversion-null

5126

Do not warn for conversions between @code{NULL} and non-pointer

5127

types. @option{-Wconversion-null} is enabled by default.

5128

5129

@item -Wzero-as-null-pointer-constant @r{(C++ and Objective-C++ only)}

5130

@opindex Wzero-as-null-pointer-constant

5131

@opindex Wno-zero-as-null-pointer-constant

5132

Warn when a literal @samp{0} is used as null pointer constant. This can

5133

be useful to facilitate the conversion to @code{nullptr} in C++11.

5134

5135

@item -Wsubobject-linkage @r{(C++ and Objective-C++ only)}

5136

@opindex Wsubobject-linkage

5137

@opindex Wno-subobject-linkage

5138

Warn if a class type has a base or a field whose type uses the anonymous

5139

namespace or depends on a type with no linkage. If a type A depends on

5140

a type B with no or internal linkage, defining it in multiple

5141

translation units would be an ODR violation because the meaning of B

5142

is different in each translation unit. If A only appears in a single

5143

translation unit, the best way to silence the warning is to give it

5144

internal linkage by putting it in an anonymous namespace as well. The

5145

compiler doesn't give this warning for types defined in the main .C

5146

file, as those are unlikely to have multiple definitions.

5147

@option{-Wsubobject-linkage} is enabled by default.

5148

5149

@item -Wdate-time

5150

@opindex Wdate-time

5151

@opindex Wno-date-time

5152

Warn when macros @code{__TIME__}, @code{__DATE__} or @code{__TIMESTAMP__}

5153

are encountered as they might prevent bit-wise-identical reproducible

5154

compilations.

5155

5156

@item -Wdelete-incomplete @r{(C++ and Objective-C++ only)}

5157

@opindex Wdelete-incomplete

5158

@opindex Wno-delete-incomplete

5159

Warn when deleting a pointer to incomplete type, which may cause

5160

undefined behavior at runtime. This warning is enabled by default.

5161

5162

@item -Wuseless-cast @r{(C++ and Objective-C++ only)}

5163

@opindex Wuseless-cast

5164

@opindex Wno-useless-cast

5165

Warn when an expression is casted to its own type.

5166

5167

@item -Wempty-body

5168

@opindex Wempty-body

5169

@opindex Wno-empty-body

5170

Warn if an empty body occurs in an @code{if}, @code{else} or @code{do

5171

while} statement. This warning is also enabled by @option{-Wextra}.

5172

5173

@item -Wenum-compare

5174

@opindex Wenum-compare

5175

@opindex Wno-enum-compare

5176

Warn about a comparison between values of different enumerated types.

5177

In C++ enumeral mismatches in conditional expressions are also

5178

diagnosed and the warning is enabled by default. In C this warning is

5179

enabled by @option{-Wall}.

5180

5181

@item -Wjump-misses-init @r{(C, Objective-C only)}

5182

@opindex Wjump-misses-init

5183

@opindex Wno-jump-misses-init

5184

Warn if a @code{goto} statement or a @code{switch} statement jumps

5185

forward across the initialization of a variable, or jumps backward to a

5186

label after the variable has been initialized. This only warns about

5187

variables that are initialized when they are declared. This warning is

5188

only supported for C and Objective-C; in C++ this sort of branch is an

5189

error in any case.

5190

5191

@option{-Wjump-misses-init} is included in @option{-Wc++-compat}. It

5192

can be disabled with the @option{-Wno-jump-misses-init} option.

5193

5194

@item -Wsign-compare

5195

@opindex Wsign-compare

5196

@opindex Wno-sign-compare

5197

@cindex warning for comparison of signed and unsigned values

5198

@cindex comparison of signed and unsigned values, warning

5199

@cindex signed and unsigned values, comparison warning

5200

Warn when a comparison between signed and unsigned values could produce

5201

an incorrect result when the signed value is converted to unsigned.

5202

In C++, this warning is also enabled by @option{-Wall}. In C, it is

5203

also enabled by @option{-Wextra}.

5204

5205

@item -Wsign-conversion

5206

@opindex Wsign-conversion

5207

@opindex Wno-sign-conversion

5208

Warn for implicit conversions that may change the sign of an integer

5209

value, like assigning a signed integer expression to an unsigned

5210

integer variable. An explicit cast silences the warning. In C, this

5211

option is enabled also by @option{-Wconversion}.

5212

5213

@item -Wfloat-conversion

5214

@opindex Wfloat-conversion

5215

@opindex Wno-float-conversion

5216

Warn for implicit conversions that reduce the precision of a real value.

5217

This includes conversions from real to integer, and from higher precision

5218

real to lower precision real values. This option is also enabled by

5219

@option{-Wconversion}.

5220

5221

@item -Wno-scalar-storage-order

5222

@opindex -Wno-scalar-storage-order

5223

@opindex -Wscalar-storage-order

5224

Do not warn on suspicious constructs involving reverse scalar storage order.

5225

5226

@item -Wsized-deallocation @r{(C++ and Objective-C++ only)}

5227

@opindex Wsized-deallocation

5228

@opindex Wno-sized-deallocation

5229

Warn about a definition of an unsized deallocation function

5230

@smallexample

5231

void operator delete (void *) noexcept;

5232

void operator delete[] (void *) noexcept;

5233

@end smallexample

5234

without a definition of the corresponding sized deallocation function

5235

@smallexample

5236

void operator delete (void *, std::size_t) noexcept;

5237

void operator delete[] (void *, std::size_t) noexcept;

5238

@end smallexample

5239

or vice versa. Enabled by @option{-Wextra} along with

5240

@option{-fsized-deallocation}.

5241

5242

@item -Wsizeof-pointer-memaccess

5243

@opindex Wsizeof-pointer-memaccess

5244

@opindex Wno-sizeof-pointer-memaccess

5245

Warn for suspicious length parameters to certain string and memory built-in

5246

functions if the argument uses @code{sizeof}. This warning warns e.g.@:

5247

about @code{memset (ptr, 0, sizeof (ptr));} if @code{ptr} is not an array,

5248

but a pointer, and suggests a possible fix, or about

5249

@code{memcpy (&foo, ptr, sizeof (&foo));}. This warning is enabled by

5250

@option{-Wall}.

5251

5252

@item -Wsizeof-array-argument

5253

@opindex Wsizeof-array-argument

5254

@opindex Wno-sizeof-array-argument

5255

Warn when the @code{sizeof} operator is applied to a parameter that is

5256

declared as an array in a function definition. This warning is enabled by

5257

default for C and C++ programs.

5258

5259

@item -Wmemset-transposed-args

5260

@opindex Wmemset-transposed-args

5261

@opindex Wno-memset-transposed-args

5262

Warn for suspicious calls to the @code{memset} built-in function, if the

5263

second argument is not zero and the third argument is zero. This warns e.g.@

5264

about @code{memset (buf, sizeof buf, 0)} where most probably

5265

@code{memset (buf, 0, sizeof buf)} was meant instead. The diagnostics

5266

is only emitted if the third argument is literal zero. If it is some

5267

expression that is folded to zero, a cast of zero to some type, etc.,

5268

it is far less likely that the user has mistakenly exchanged the arguments

5269

and no warning is emitted. This warning is enabled by @option{-Wall}.

5270

5271

@item -Waddress

5272

@opindex Waddress

5273

@opindex Wno-address

5274

Warn about suspicious uses of memory addresses. These include using

5275

the address of a function in a conditional expression, such as

5276

@code{void func(void); if (func)}, and comparisons against the memory

5277

address of a string literal, such as @code{if (x == "abc")}. Such

5278

uses typically indicate a programmer error: the address of a function

5279

always evaluates to true, so their use in a conditional usually

5280

indicate that the programmer forgot the parentheses in a function

5281

call; and comparisons against string literals result in unspecified

5282

behavior and are not portable in C, so they usually indicate that the

5283

programmer intended to use @code{strcmp}. This warning is enabled by

5284

@option{-Wall}.

5285

5286

@item -Wlogical-op

5287

@opindex Wlogical-op

5288

@opindex Wno-logical-op

5289

Warn about suspicious uses of logical operators in expressions.

5290

This includes using logical operators in contexts where a

5291

bit-wise operator is likely to be expected. Also warns when

5292

the operands of a logical operator are the same:

5293

@smallexample

5294

extern int a;

5295

if (a < 0 && a < 0) @{ @dots{} @}

5296

@end smallexample

5297

5298

@item -Wlogical-not-parentheses

5299

@opindex Wlogical-not-parentheses

5300

@opindex Wno-logical-not-parentheses

5301

Warn about logical not used on the left hand side operand of a comparison.

5302

This option does not warn if the RHS operand is of a boolean type. Its

5303

purpose is to detect suspicious code like the following:

5304

@smallexample

5305

int a;

5306

@dots{}

5307

if (!a > 1) @{ @dots{} @}

5308

@end smallexample

5309

5310

It is possible to suppress the warning by wrapping the LHS into

5311

parentheses:

5312

@smallexample

5313

if ((!a) > 1) @{ @dots{} @}

5314

@end smallexample

5315

5316

This warning is enabled by @option{-Wall}.

5317

5318

@item -Waggregate-return

5319

@opindex Waggregate-return

5320

@opindex Wno-aggregate-return

5321

Warn if any functions that return structures or unions are defined or

5322

called. (In languages where you can return an array, this also elicits

5323

a warning.)

5324

5325

@item -Wno-aggressive-loop-optimizations

5326

@opindex Wno-aggressive-loop-optimizations

5327

@opindex Waggressive-loop-optimizations

5328

Warn if in a loop with constant number of iterations the compiler detects

5329

undefined behavior in some statement during one or more of the iterations.

5330

5331

@item -Wno-attributes

5332

@opindex Wno-attributes

5333

@opindex Wattributes

5334

Do not warn if an unexpected @code{__attribute__} is used, such as

5335

unrecognized attributes, function attributes applied to variables,

5336

etc. This does not stop errors for incorrect use of supported

5337

attributes.

5338

5339

@item -Wno-builtin-macro-redefined

5340

@opindex Wno-builtin-macro-redefined

5341

@opindex Wbuiltin-macro-redefined

5342

Do not warn if certain built-in macros are redefined. This suppresses

5343

warnings for redefinition of @code{__TIMESTAMP__}, @code{__TIME__},

5344

@code{__DATE__}, @code{__FILE__}, and @code{__BASE_FILE__}.

5345

5346

@item -Wstrict-prototypes @r{(C and Objective-C only)}

5347

@opindex Wstrict-prototypes

5348

@opindex Wno-strict-prototypes

5349

Warn if a function is declared or defined without specifying the

5350

argument types. (An old-style function definition is permitted without

5351

a warning if preceded by a declaration that specifies the argument

5352

types.)

5353

5354

@item -Wold-style-declaration @r{(C and Objective-C only)}

5355

@opindex Wold-style-declaration

5356

@opindex Wno-old-style-declaration

5357

Warn for obsolescent usages, according to the C Standard, in a

5358

declaration. For example, warn if storage-class specifiers like

5359

@code{static} are not the first things in a declaration. This warning

5360

is also enabled by @option{-Wextra}.

5361

5362

@item -Wold-style-definition @r{(C and Objective-C only)}

5363

@opindex Wold-style-definition

5364

@opindex Wno-old-style-definition

5365

Warn if an old-style function definition is used. A warning is given

5366

even if there is a previous prototype.

5367

5368

@item -Wmissing-parameter-type @r{(C and Objective-C only)}

5369

@opindex Wmissing-parameter-type

5370

@opindex Wno-missing-parameter-type

5371

A function parameter is declared without a type specifier in K&R-style

5372

functions:

5373

5374

@smallexample

5375

void foo(bar) @{ @}

5376

@end smallexample

5377

5378

This warning is also enabled by @option{-Wextra}.

5379

5380

@item -Wmissing-prototypes @r{(C and Objective-C only)}

5381

@opindex Wmissing-prototypes

5382

@opindex Wno-missing-prototypes

5383

Warn if a global function is defined without a previous prototype

5384

declaration. This warning is issued even if the definition itself

5385

provides a prototype. Use this option to detect global functions

5386

that do not have a matching prototype declaration in a header file.

5387

This option is not valid for C++ because all function declarations

5388

provide prototypes and a non-matching declaration declares an

5389

overload rather than conflict with an earlier declaration.

5390

Use @option{-Wmissing-declarations} to detect missing declarations in C++.

5391

5392

@item -Wmissing-declarations

5393

@opindex Wmissing-declarations

5394

@opindex Wno-missing-declarations

5395

Warn if a global function is defined without a previous declaration.

5396

Do so even if the definition itself provides a prototype.

5397

Use this option to detect global functions that are not declared in

5398

header files. In C, no warnings are issued for functions with previous

5399

non-prototype declarations; use @option{-Wmissing-prototypes} to detect

5400

missing prototypes. In C++, no warnings are issued for function templates,

5401

or for inline functions, or for functions in anonymous namespaces.

5402

5403

@item -Wmissing-field-initializers

5404

@opindex Wmissing-field-initializers

5405

@opindex Wno-missing-field-initializers

5406

@opindex W

5407

@opindex Wextra

5408

@opindex Wno-extra

5409

Warn if a structure's initializer has some fields missing. For

5410

example, the following code causes such a warning, because

5411

@code{x.h} is implicitly zero:

5412

5413

@smallexample

5414

struct s @{ int f, g, h; @};

5415

struct s x = @{ 3, 4 @};

5416

@end smallexample

5417

5418

This option does not warn about designated initializers, so the following

5419

modification does not trigger a warning:

5420

5421

@smallexample

5422

struct s @{ int f, g, h; @};

5423

struct s x = @{ .f = 3, .g = 4 @};

5424

@end smallexample

5425

5426

In C++ this option does not warn either about the empty @{ @}

5427

initializer, for example:

5428

5429

@smallexample

5430

struct s @{ int f, g, h; @};

5431

s x = @{ @};

5432

@end smallexample

5433

5434

This warning is included in @option{-Wextra}. To get other @option{-Wextra}

5435

warnings without this one, use @option{-Wextra -Wno-missing-field-initializers}.

5436

5437

@item -Wno-multichar

5438

@opindex Wno-multichar

5439

@opindex Wmultichar

5440

Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.

5441

Usually they indicate a typo in the user's code, as they have

5442

implementation-defined values, and should not be used in portable code.

5443

5444

@item -Wnormalized@r{[}=@r{<}none@r{|}id@r{|}nfc@r{|}nfkc@r{>]}

5445

@opindex Wnormalized=

5446

@opindex Wnormalized

5447

@opindex Wno-normalized

5448

@cindex NFC

5449

@cindex NFKC

5450

@cindex character set, input normalization

5451

In ISO C and ISO C++, two identifiers are different if they are

5452

different sequences of characters. However, sometimes when characters

5453

outside the basic ASCII character set are used, you can have two

5454

different character sequences that look the same. To avoid confusion,

5455

the ISO 10646 standard sets out some @dfn{normalization rules} which

5456

when applied ensure that two sequences that look the same are turned into

5457

the same sequence. GCC can warn you if you are using identifiers that

5458

have not been normalized; this option controls that warning.

5459

5460

There are four levels of warning supported by GCC@. The default is

5461

@option{-Wnormalized=nfc}, which warns about any identifier that is

5462

not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the

5463

recommended form for most uses. It is equivalent to

5464

@option{-Wnormalized}.

5465

5466

Unfortunately, there are some characters allowed in identifiers by

5467

ISO C and ISO C++ that, when turned into NFC, are not allowed in

5468

identifiers. That is, there's no way to use these symbols in portable

5469

ISO C or C++ and have all your identifiers in NFC@.

5470

@option{-Wnormalized=id} suppresses the warning for these characters.

5471

It is hoped that future versions of the standards involved will correct

5472

this, which is why this option is not the default.

5473

5474

You can switch the warning off for all characters by writing

5475

@option{-Wnormalized=none} or @option{-Wno-normalized}. You should

5476

only do this if you are using some other normalization scheme (like

5477

``D''), because otherwise you can easily create bugs that are

5478

literally impossible to see.

5479

5480

Some characters in ISO 10646 have distinct meanings but look identical

5481

in some fonts or display methodologies, especially once formatting has

5482

been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL

5483

LETTER N'', displays just like a regular @code{n} that has been

5484

placed in a superscript. ISO 10646 defines the @dfn{NFKC}

5485

normalization scheme to convert all these into a standard form as

5486

well, and GCC warns if your code is not in NFKC if you use

5487

@option{-Wnormalized=nfkc}. This warning is comparable to warning

5488

about every identifier that contains the letter O because it might be

5489

confused with the digit 0, and so is not the default, but may be

5490

useful as a local coding convention if the programming environment

5491

cannot be fixed to display these characters distinctly.

5492

5493

@item -Wno-deprecated

5494

@opindex Wno-deprecated

5495

@opindex Wdeprecated

5496

Do not warn about usage of deprecated features. @xref{Deprecated Features}.

5497

5498

@item -Wno-deprecated-declarations

5499

@opindex Wno-deprecated-declarations

5500

@opindex Wdeprecated-declarations

5501

Do not warn about uses of functions (@pxref{Function Attributes}),

5502

variables (@pxref{Variable Attributes}), and types (@pxref{Type

5503

Attributes}) marked as deprecated by using the @code{deprecated}

5504

attribute.

5505

5506

@item -Wno-overflow

5507

@opindex Wno-overflow

5508

@opindex Woverflow

5509

Do not warn about compile-time overflow in constant expressions.

5510

5511

@item -Wno-odr

5512

@opindex Wno-odr

5513

@opindex Wodr

5514

Warn about One Definition Rule violations during link-time optimization.

5515

Requires @option{-flto-odr-type-merging} to be enabled. Enabled by default.

5516

5517

@item -Wopenmp-simd

5518

@opindex Wopenm-simd

5519

Warn if the vectorizer cost model overrides the OpenMP or the Cilk Plus

5520

simd directive set by user. The @option{-fsimd-cost-model=unlimited}

5521

option can be used to relax the cost model.

5522

5523

@item -Woverride-init @r{(C and Objective-C only)}

5524

@opindex Woverride-init

5525

@opindex Wno-override-init

5526

@opindex W

5527

@opindex Wextra

5528

@opindex Wno-extra

5529

Warn if an initialized field without side effects is overridden when

5530

using designated initializers (@pxref{Designated Inits, , Designated

5531

Initializers}).

5532

5533

This warning is included in @option{-Wextra}. To get other

5534

@option{-Wextra} warnings without this one, use @option{-Wextra

5535

-Wno-override-init}.

5536

5537

@item -Woverride-init-side-effects @r{(C and Objective-C only)}

5538

@opindex Woverride-init-side-effects

5539

@opindex Wno-override-init-side-effects

5540

Warn if an initialized field with side effects is overridden when

5541

using designated initializers (@pxref{Designated Inits, , Designated

5542

Initializers}). This warning is enabled by default.

5543

5544

@item -Wpacked

5545

@opindex Wpacked

5546

@opindex Wno-packed

5547

Warn if a structure is given the packed attribute, but the packed

5548

attribute has no effect on the layout or size of the structure.

5549

Such structures may be mis-aligned for little benefit. For

5550

instance, in this code, the variable @code{f.x} in @code{struct bar}

5551

is misaligned even though @code{struct bar} does not itself

5552

have the packed attribute:

5553

5554

@smallexample

5555

@group

5556

struct foo @{

5557

int x;

5558

char a, b, c, d;

5559

@} __attribute__((packed));

5560

struct bar @{

5561

char z;

5562

struct foo f;

5563

@};

5564

@end group

5565

@end smallexample

5566

5567

@item -Wpacked-bitfield-compat

5568

@opindex Wpacked-bitfield-compat

5569

@opindex Wno-packed-bitfield-compat

5570

The 4.1, 4.2 and 4.3 series of GCC ignore the @code{packed} attribute

5571

on bit-fields of type @code{char}. This has been fixed in GCC 4.4 but

5572

the change can lead to differences in the structure layout. GCC

5573

informs you when the offset of such a field has changed in GCC 4.4.

5574

For example there is no longer a 4-bit padding between field @code{a}

5575

and @code{b} in this structure:

5576

5577

@smallexample

5578

struct foo

5579

@{

5580

char a:4;

5581

char b:8;

5582

@} __attribute__ ((packed));

5583

@end smallexample

5584

5585

This warning is enabled by default. Use

5586

@option{-Wno-packed-bitfield-compat} to disable this warning.

5587

5588

@item -Wpadded

5589

@opindex Wpadded

5590

@opindex Wno-padded

5591

Warn if padding is included in a structure, either to align an element

5592

of the structure or to align the whole structure. Sometimes when this

5593

happens it is possible to rearrange the fields of the structure to

5594

reduce the padding and so make the structure smaller.

5595

5596

@item -Wredundant-decls

5597

@opindex Wredundant-decls

5598

@opindex Wno-redundant-decls

5599

Warn if anything is declared more than once in the same scope, even in

5600

cases where multiple declaration is valid and changes nothing.

5601

5602

@item -Wnested-externs @r{(C and Objective-C only)}

5603

@opindex Wnested-externs

5604

@opindex Wno-nested-externs

5605

Warn if an @code{extern} declaration is encountered within a function.

5606

5607

@item -Wno-inherited-variadic-ctor

5608

@opindex Winherited-variadic-ctor

5609

@opindex Wno-inherited-variadic-ctor

5610

Suppress warnings about use of C++11 inheriting constructors when the

5611

base class inherited from has a C variadic constructor; the warning is

5612

on by default because the ellipsis is not inherited.

5613

5614

@item -Winline

5615

@opindex Winline

5616

@opindex Wno-inline

5617

Warn if a function that is declared as inline cannot be inlined.

5618

Even with this option, the compiler does not warn about failures to

5619

inline functions declared in system headers.

5620

5621

The compiler uses a variety of heuristics to determine whether or not

5622

to inline a function. For example, the compiler takes into account

5623

the size of the function being inlined and the amount of inlining

5624

that has already been done in the current function. Therefore,

5625

seemingly insignificant changes in the source program can cause the

5626

warnings produced by @option{-Winline} to appear or disappear.

5627

5628

@item -Wno-invalid-offsetof @r{(C++ and Objective-C++ only)}

5629

@opindex Wno-invalid-offsetof

5630

@opindex Winvalid-offsetof

5631

Suppress warnings from applying the @code{offsetof} macro to a non-POD

5632

type. According to the 2014 ISO C++ standard, applying @code{offsetof}

5633

to a non-standard-layout type is undefined. In existing C++ implementations,

5634

however, @code{offsetof} typically gives meaningful results.

5635

This flag is for users who are aware that they are

5636

writing nonportable code and who have deliberately chosen to ignore the

5637

warning about it.

5638

5639

The restrictions on @code{offsetof} may be relaxed in a future version

5640

of the C++ standard.

5641

5642

@item -Wno-int-to-pointer-cast

5643

@opindex Wno-int-to-pointer-cast

5644

@opindex Wint-to-pointer-cast

5645

Suppress warnings from casts to pointer type of an integer of a

5646

different size. In C++, casting to a pointer type of smaller size is

5647

an error. @option{Wint-to-pointer-cast} is enabled by default.

5648

5649

5650

@item -Wno-pointer-to-int-cast @r{(C and Objective-C only)}

5651

@opindex Wno-pointer-to-int-cast

5652

@opindex Wpointer-to-int-cast

5653

Suppress warnings from casts from a pointer to an integer type of a

5654

different size.

5655

5656

@item -Winvalid-pch

5657

@opindex Winvalid-pch

5658

@opindex Wno-invalid-pch

5659

Warn if a precompiled header (@pxref{Precompiled Headers}) is found in

5660

the search path but can't be used.

5661

5662

@item -Wlong-long

5663

@opindex Wlong-long

5664

@opindex Wno-long-long

5665

Warn if @code{long long} type is used. This is enabled by either

5666

@option{-Wpedantic} or @option{-Wtraditional} in ISO C90 and C++98

5667

modes. To inhibit the warning messages, use @option{-Wno-long-long}.

5668

5669

@item -Wvariadic-macros

5670

@opindex Wvariadic-macros

5671

@opindex Wno-variadic-macros

5672

Warn if variadic macros are used in ISO C90 mode, or if the GNU

5673

alternate syntax is used in ISO C99 mode. This is enabled by either

5674

@option{-Wpedantic} or @option{-Wtraditional}. To inhibit the warning

5675

messages, use @option{-Wno-variadic-macros}.

5676

5677

@item -Wvarargs

5678

@opindex Wvarargs

5679

@opindex Wno-varargs

5680

Warn upon questionable usage of the macros used to handle variable

5681

arguments like @code{va_start}. This is default. To inhibit the

5682

warning messages, use @option{-Wno-varargs}.

5683

5684

@item -Wvector-operation-performance

5685

@opindex Wvector-operation-performance

5686

@opindex Wno-vector-operation-performance

5687

Warn if vector operation is not implemented via SIMD capabilities of the

5688

architecture. Mainly useful for the performance tuning.

5689

Vector operation can be implemented @code{piecewise}, which means that the

5690

scalar operation is performed on every vector element;

5691

@code{in parallel}, which means that the vector operation is implemented

5692

using scalars of wider type, which normally is more performance efficient;

5693

and @code{as a single scalar}, which means that vector fits into a

5694

scalar type.

5695

5696

@item -Wno-virtual-move-assign

5697

@opindex Wvirtual-move-assign

5698

@opindex Wno-virtual-move-assign

5699

Suppress warnings about inheriting from a virtual base with a

5700

non-trivial C++11 move assignment operator. This is dangerous because

5701

if the virtual base is reachable along more than one path, it is

5702

moved multiple times, which can mean both objects end up in the

5703

moved-from state. If the move assignment operator is written to avoid

5704

moving from a moved-from object, this warning can be disabled.

5705

5706

@item -Wvla

5707

@opindex Wvla

5708

@opindex Wno-vla

5709

Warn if variable length array is used in the code.

5710

@option{-Wno-vla} prevents the @option{-Wpedantic} warning of

5711

the variable length array.

5712

5713

@item -Wvolatile-register-var

5714

@opindex Wvolatile-register-var

5715

@opindex Wno-volatile-register-var

5716

Warn if a register variable is declared volatile. The volatile

5717

modifier does not inhibit all optimizations that may eliminate reads

5718

and/or writes to register variables. This warning is enabled by

5719

@option{-Wall}.

5720

5721

@item -Wdisabled-optimization

5722

@opindex Wdisabled-optimization

5723

@opindex Wno-disabled-optimization

5724

Warn if a requested optimization pass is disabled. This warning does

5725

not generally indicate that there is anything wrong with your code; it

5726

merely indicates that GCC's optimizers are unable to handle the code

5727

effectively. Often, the problem is that your code is too big or too

5728

complex; GCC refuses to optimize programs when the optimization

5729

itself is likely to take inordinate amounts of time.

5730

5731

@item -Wpointer-sign @r{(C and Objective-C only)}

5732

@opindex Wpointer-sign

5733

@opindex Wno-pointer-sign

5734

Warn for pointer argument passing or assignment with different signedness.

5735

This option is only supported for C and Objective-C@. It is implied by

5736

@option{-Wall} and by @option{-Wpedantic}, which can be disabled with

5737

@option{-Wno-pointer-sign}.

5738

5739

@item -Wstack-protector

5740

@opindex Wstack-protector

5741

@opindex Wno-stack-protector

5742

This option is only active when @option{-fstack-protector} is active. It

5743

warns about functions that are not protected against stack smashing.

5744

5745

@item -Woverlength-strings

5746

@opindex Woverlength-strings

5747

@opindex Wno-overlength-strings

5748

Warn about string constants that are longer than the ``minimum

5749

maximum'' length specified in the C standard. Modern compilers

5750

generally allow string constants that are much longer than the

5751

standard's minimum limit, but very portable programs should avoid

5752

using longer strings.

5753

5754

The limit applies @emph{after} string constant concatenation, and does

5755

not count the trailing NUL@. In C90, the limit was 509 characters; in

5756

C99, it was raised to 4095. C++98 does not specify a normative

5757

minimum maximum, so we do not diagnose overlength strings in C++@.

5758

5759

This option is implied by @option{-Wpedantic}, and can be disabled with

5760

@option{-Wno-overlength-strings}.

5761

5762

@item -Wunsuffixed-float-constants @r{(C and Objective-C only)}

5763

@opindex Wunsuffixed-float-constants

5764

5765

Issue a warning for any floating constant that does not have

5766

a suffix. When used together with @option{-Wsystem-headers} it

5767

warns about such constants in system header files. This can be useful

5768

when preparing code to use with the @code{FLOAT_CONST_DECIMAL64} pragma

5769

from the decimal floating-point extension to C99.

5770

5771

@item -Wno-designated-init @r{(C and Objective-C only)}

5772

Suppress warnings when a positional initializer is used to initialize

5773

a structure that has been marked with the @code{designated_init}

5774

attribute.

5775

5776

@item -Whsa

5777

Issue a warning when HSAIL cannot be emitted for the compiled function or

5778

OpenMP construct.

5779

5780

@end table

5781

5782

@node Debugging Options

5783

@section Options for Debugging Your Program

5784

@cindex options, debugging

5785

@cindex debugging information options

5786

5787

To tell GCC to emit extra information for use by a debugger, in almost

5788

all cases you need only to add @option{-g} to your other options.

5789

5790

GCC allows you to use @option{-g} with

5791

@option{-O}. The shortcuts taken by optimized code may occasionally

5792

be surprising: some variables you declared may not exist

5793

at all; flow of control may briefly move where you did not expect it;

5794

some statements may not be executed because they compute constant

5795

results or their values are already at hand; some statements may

5796

execute in different places because they have been moved out of loops.

5797

Nevertheless it is possible to debug optimized output. This makes

5798

it reasonable to use the optimizer for programs that might have bugs.

5799

5800

If you are not using some other optimization option, consider

5801

using @option{-Og} (@pxref{Optimize Options}) with @option{-g}.

5802

With no @option{-O} option at all, some compiler passes that collect

5803

information useful for debugging do not run at all, so that

5804

@option{-Og} may result in a better debugging experience.

5805

5806

@table @gcctabopt

5807

@item -g

5808

@opindex g

5809

Produce debugging information in the operating system's native format

5810

(stabs, COFF, XCOFF, or DWARF)@. GDB can work with this debugging

5811

information.

5812

5813

On most systems that use stabs format, @option{-g} enables use of extra

5814

debugging information that only GDB can use; this extra information

5815

makes debugging work better in GDB but probably makes other debuggers

5816

crash or

5817

refuse to read the program. If you want to control for certain whether

5818

to generate the extra information, use @option{-gstabs+}, @option{-gstabs},

5819

@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).

5820

5821

@item -ggdb

5822

@opindex ggdb

5823

Produce debugging information for use by GDB@. This means to use the

5824

most expressive format available (DWARF, stabs, or the native format

5825

if neither of those are supported), including GDB extensions if at all

5826

possible.

5827

5828

@item -gdwarf

5829

@itemx -gdwarf-@var{version}

5830

@opindex gdwarf

5831

Produce debugging information in DWARF format (if that is supported).

5832

The value of @var{version} may be either 2, 3, 4 or 5; the default version

5833

for most targets is 4. DWARF Version 5 is only experimental.

5834

5835

Note that with DWARF Version 2, some ports require and always

5836

use some non-conflicting DWARF 3 extensions in the unwind tables.

5837

5838

Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}

5839

for maximum benefit.

5840

5841

GCC no longer supports DWARF Version 1, which is substantially

5842

different than Version 2 and later. For historical reasons, some

5843

other DWARF-related options (including @option{-feliminate-dwarf2-dups}

5844

and @option{-fno-dwarf2-cfi-asm}) retain a reference to DWARF Version 2

5845

in their names, but apply to all currently-supported versions of DWARF.

5846

5847

@item -gstabs

5848

@opindex gstabs

5849

Produce debugging information in stabs format (if that is supported),

5850

without GDB extensions. This is the format used by DBX on most BSD

5851

systems. On MIPS, Alpha and System V Release 4 systems this option

5852

produces stabs debugging output that is not understood by DBX or SDB@.

5853

On System V Release 4 systems this option requires the GNU assembler.

5854

5855

@item -gstabs+

5856

@opindex gstabs+

5857

Produce debugging information in stabs format (if that is supported),

5858

using GNU extensions understood only by the GNU debugger (GDB)@. The

5859

use of these extensions is likely to make other debuggers crash or

5860

refuse to read the program.

5861

5862

@item -gcoff

5863

@opindex gcoff

5864

Produce debugging information in COFF format (if that is supported).

5865

This is the format used by SDB on most System V systems prior to

5866

System V Release 4.

5867

5868

@item -gxcoff

5869

@opindex gxcoff

5870

Produce debugging information in XCOFF format (if that is supported).

5871

This is the format used by the DBX debugger on IBM RS/6000 systems.

5872

5873

@item -gxcoff+

5874

@opindex gxcoff+

5875

Produce debugging information in XCOFF format (if that is supported),

5876

using GNU extensions understood only by the GNU debugger (GDB)@. The

5877

use of these extensions is likely to make other debuggers crash or

5878

refuse to read the program, and may cause assemblers other than the GNU

5879

assembler (GAS) to fail with an error.

5880

5881

@item -gvms

5882

@opindex gvms

5883

Produce debugging information in Alpha/VMS debug format (if that is

5884

supported). This is the format used by DEBUG on Alpha/VMS systems.

5885

5886

@item -g@var{level}

5887

@itemx -ggdb@var{level}

5888

@itemx -gstabs@var{level}

5889

@itemx -gcoff@var{level}

5890

@itemx -gxcoff@var{level}

5891

@itemx -gvms@var{level}

5892

Request debugging information and also use @var{level} to specify how

5893

much information. The default level is 2.

5894

5895

Level 0 produces no debug information at all. Thus, @option{-g0} negates

5896

@option{-g}.

5897

5898

Level 1 produces minimal information, enough for making backtraces in

5899

parts of the program that you don't plan to debug. This includes

5900

descriptions of functions and external variables, and line number

5901

tables, but no information about local variables.

5902

5903

Level 3 includes extra information, such as all the macro definitions

5904

present in the program. Some debuggers support macro expansion when

5905

you use @option{-g3}.

5906

5907

@option{-gdwarf} does not accept a concatenated debug level, to avoid

5908

confusion with @option{-gdwarf-@var{level}}.

5909

Instead use an additional @option{-g@var{level}} option to change the

5910

debug level for DWARF.

5911

5912

@item -feliminate-unused-debug-symbols

5913

@opindex feliminate-unused-debug-symbols

5914

Produce debugging information in stabs format (if that is supported),

5915

for only symbols that are actually used.

5916

5917

@item -femit-class-debug-always

5918

@opindex femit-class-debug-always

5919

Instead of emitting debugging information for a C++ class in only one

5920

object file, emit it in all object files using the class. This option

5921

should be used only with debuggers that are unable to handle the way GCC

5922

normally emits debugging information for classes because using this

5923

option increases the size of debugging information by as much as a

5924

factor of two.

5925

5926

@item -fno-merge-debug-strings

5927

@opindex fmerge-debug-strings

5928

@opindex fno-merge-debug-strings

5929

Direct the linker to not merge together strings in the debugging

5930

information that are identical in different object files. Merging is

5931

not supported by all assemblers or linkers. Merging decreases the size

5932

of the debug information in the output file at the cost of increasing

5933

link processing time. Merging is enabled by default.

5934

5935

@item -fdebug-prefix-map=@var{old}=@var{new}

5936

@opindex fdebug-prefix-map

5937

When compiling files in directory @file{@var{old}}, record debugging

5938

information describing them as in @file{@var{new}} instead.

5939

5940

@item -fvar-tracking

5941

@opindex fvar-tracking

5942

Run variable tracking pass. It computes where variables are stored at each

5943

position in code. Better debugging information is then generated

5944

(if the debugging information format supports this information).

5945

5946

It is enabled by default when compiling with optimization (@option{-Os},

5947

@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and

5948

the debug info format supports it.

5949

5950

@item -fvar-tracking-assignments

5951

@opindex fvar-tracking-assignments

5952

@opindex fno-var-tracking-assignments

5953

Annotate assignments to user variables early in the compilation and

5954

attempt to carry the annotations over throughout the compilation all the

5955

way to the end, in an attempt to improve debug information while

5956

optimizing. Use of @option{-gdwarf-4} is recommended along with it.

5957

5958

It can be enabled even if var-tracking is disabled, in which case

5959

annotations are created and maintained, but discarded at the end.

5960

By default, this flag is enabled together with @option{-fvar-tracking},

5961

except when selective scheduling is enabled.

5962

5963

@item -gsplit-dwarf

5964

@opindex gsplit-dwarf

5965

Separate as much DWARF debugging information as possible into a

5966

separate output file with the extension @file{.dwo}. This option allows

5967

the build system to avoid linking files with debug information. To

5968

be useful, this option requires a debugger capable of reading @file{.dwo}

5969

files.

5970

5971

@item -gpubnames

5972

@opindex gpubnames

5973

Generate DWARF @code{.debug_pubnames} and @code{.debug_pubtypes} sections.

5974

5975

@item -ggnu-pubnames

5976

@opindex ggnu-pubnames

5977

Generate @code{.debug_pubnames} and @code{.debug_pubtypes} sections in a format

5978

suitable for conversion into a GDB@ index. This option is only useful

5979

with a linker that can produce GDB@ index version 7.

5980

5981

@item -fdebug-types-section

5982

@opindex fdebug-types-section

5983

@opindex fno-debug-types-section

5984

When using DWARF Version 4 or higher, type DIEs can be put into

5985

their own @code{.debug_types} section instead of making them part of the

5986

@code{.debug_info} section. It is more efficient to put them in a separate

5987

comdat sections since the linker can then remove duplicates.

5988

But not all DWARF consumers support @code{.debug_types} sections yet

5989

and on some objects @code{.debug_types} produces larger instead of smaller

5990

debugging information.

5991

5992

@item -grecord-gcc-switches

5993

@item -gno-record-gcc-switches

5994

@opindex grecord-gcc-switches

5995

@opindex gno-record-gcc-switches

5996

This switch causes the command-line options used to invoke the

5997

compiler that may affect code generation to be appended to the

5998

DW_AT_producer attribute in DWARF debugging information. The options

5999

are concatenated with spaces separating them from each other and from

6000

the compiler version.

6001

It is enabled by default.

6002

See also @option{-frecord-gcc-switches} for another

6003

way of storing compiler options into the object file.

6004

6005

@item -gstrict-dwarf

6006

@opindex gstrict-dwarf

6007

Disallow using extensions of later DWARF standard version than selected

6008

with @option{-gdwarf-@var{version}}. On most targets using non-conflicting

6009

DWARF extensions from later standard versions is allowed.

6010

6011

@item -gno-strict-dwarf

6012

@opindex gno-strict-dwarf

6013

Allow using extensions of later DWARF standard version than selected with

6014

@option{-gdwarf-@var{version}}.

6015

6016

@item -gz@r{[}=@var{type}@r{]}

6017

@opindex gz

6018

Produce compressed debug sections in DWARF format, if that is supported.

6019

If @var{type} is not given, the default type depends on the capabilities

6020

of the assembler and linker used. @var{type} may be one of

6021

@samp{none} (don't compress debug sections), @samp{zlib} (use zlib

6022

compression in ELF gABI format), or @samp{zlib-gnu} (use zlib

6023

compression in traditional GNU format). If the linker doesn't support

6024

writing compressed debug sections, the option is rejected. Otherwise,

6025

if the assembler does not support them, @option{-gz} is silently ignored

6026

when producing object files.

6027

6028

@item -feliminate-dwarf2-dups

6029

@opindex feliminate-dwarf2-dups

6030

Compress DWARF debugging information by eliminating duplicated

6031

information about each symbol. This option only makes sense when

6032

generating DWARF debugging information.

6033

6034

@item -femit-struct-debug-baseonly

6035

@opindex femit-struct-debug-baseonly

6036

Emit debug information for struct-like types

6037

only when the base name of the compilation source file

6038

matches the base name of file in which the struct is defined.

6039

6040

This option substantially reduces the size of debugging information,

6041

but at significant potential loss in type information to the debugger.

6042

See @option{-femit-struct-debug-reduced} for a less aggressive option.

6043

See @option{-femit-struct-debug-detailed} for more detailed control.

6044

6045

This option works only with DWARF debug output.

6046

6047

@item -femit-struct-debug-reduced

6048

@opindex femit-struct-debug-reduced

6049

Emit debug information for struct-like types

6050

only when the base name of the compilation source file

6051

matches the base name of file in which the type is defined,

6052

unless the struct is a template or defined in a system header.

6053

6054

This option significantly reduces the size of debugging information,

6055

with some potential loss in type information to the debugger.

6056

See @option{-femit-struct-debug-baseonly} for a more aggressive option.

6057

See @option{-femit-struct-debug-detailed} for more detailed control.

6058

6059

This option works only with DWARF debug output.

6060

6061

@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}

6062

@opindex femit-struct-debug-detailed

6063

Specify the struct-like types

6064

for which the compiler generates debug information.

6065

The intent is to reduce duplicate struct debug information

6066

between different object files within the same program.

6067

6068

This option is a detailed version of

6069

@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},

6070

which serves for most needs.

6071

6072

A specification has the syntax@*

6073

[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})

6074

6075

The optional first word limits the specification to

6076

structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).

6077

A struct type is used directly when it is the type of a variable, member.

6078

Indirect uses arise through pointers to structs.

6079

That is, when use of an incomplete struct is valid, the use is indirect.

6080

An example is

6081

@samp{struct one direct; struct two * indirect;}.

6082

6083

The optional second word limits the specification to

6084

ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).

6085

Generic structs are a bit complicated to explain.

6086

For C++, these are non-explicit specializations of template classes,

6087

or non-template classes within the above.

6088

Other programming languages have generics,

6089

but @option{-femit-struct-debug-detailed} does not yet implement them.

6090

6091

The third word specifies the source files for those

6092

structs for which the compiler should emit debug information.

6093

The values @samp{none} and @samp{any} have the normal meaning.

6094

The value @samp{base} means that

6095

the base of name of the file in which the type declaration appears

6096

must match the base of the name of the main compilation file.

6097

In practice, this means that when compiling @file{foo.c}, debug information

6098

is generated for types declared in that file and @file{foo.h},

6099

but not other header files.

6100

The value @samp{sys} means those types satisfying @samp{base}

6101

or declared in system or compiler headers.

6102

6103

You may need to experiment to determine the best settings for your application.

6104

6105

The default is @option{-femit-struct-debug-detailed=all}.

6106

6107

This option works only with DWARF debug output.

6108

6109

@item -fno-dwarf2-cfi-asm

6110

@opindex fdwarf2-cfi-asm

6111

@opindex fno-dwarf2-cfi-asm

6112

Emit DWARF unwind info as compiler generated @code{.eh_frame} section

6113

instead of using GAS @code{.cfi_*} directives.

6114

6115

@item -fno-eliminate-unused-debug-types

6116

@opindex feliminate-unused-debug-types

6117

@opindex fno-eliminate-unused-debug-types

6118

Normally, when producing DWARF output, GCC avoids producing debug symbol

6119

output for types that are nowhere used in the source file being compiled.

6120

Sometimes it is useful to have GCC emit debugging

6121

information for all types declared in a compilation

6122

unit, regardless of whether or not they are actually used

6123

in that compilation unit, for example

6124

if, in the debugger, you want to cast a value to a type that is

6125

not actually used in your program (but is declared). More often,

6126

however, this results in a significant amount of wasted space.

6127

@end table

6128

6129

@node Optimize Options

6130

@section Options That Control Optimization

6131

@cindex optimize options

6132

@cindex options, optimization

6133

6134

These options control various sorts of optimizations.

6135

6136

Without any optimization option, the compiler's goal is to reduce the

6137

cost of compilation and to make debugging produce the expected

6138

results. Statements are independent: if you stop the program with a

6139

breakpoint between statements, you can then assign a new value to any

6140

variable or change the program counter to any other statement in the

6141

function and get exactly the results you expect from the source

6142

code.

6143

6144

Turning on optimization flags makes the compiler attempt to improve

6145

the performance and/or code size at the expense of compilation time

6146

and possibly the ability to debug the program.

6147

6148

The compiler performs optimization based on the knowledge it has of the

6149

program. Compiling multiple files at once to a single output file mode allows

6150

the compiler to use information gained from all of the files when compiling

6151

each of them.

6152

6153

Not all optimizations are controlled directly by a flag. Only

6154

optimizations that have a flag are listed in this section.

6155

6156

Most optimizations are only enabled if an @option{-O} level is set on

6157

the command line. Otherwise they are disabled, even if individual

6158

optimization flags are specified.

6159

6160

Depending on the target and how GCC was configured, a slightly different

6161

set of optimizations may be enabled at each @option{-O} level than

6162

those listed here. You can invoke GCC with @option{-Q --help=optimizers}

6163

to find out the exact set of optimizations that are enabled at each level.

6164

@xref{Overall Options}, for examples.

6165

6166

@table @gcctabopt

6167

@item -O

6168

@itemx -O1

6169

@opindex O

6170

@opindex O1

6171

Optimize. Optimizing compilation takes somewhat more time, and a lot

6172

more memory for a large function.

6173

6174

With @option{-O}, the compiler tries to reduce code size and execution

6175

time, without performing any optimizations that take a great deal of

6176

compilation time.

6177

6178

@option{-O} turns on the following optimization flags:

6179

@gccoptlist{

6180

-fauto-inc-dec @gol

6181

-fbranch-count-reg @gol

6182

-fcombine-stack-adjustments @gol

6183

-fcompare-elim @gol

6184

-fcprop-registers @gol

6185

-fdce @gol

6186

-fdefer-pop @gol

6187

-fdelayed-branch @gol

6188

-fdse @gol

6189

-fforward-propagate @gol

6190

-fguess-branch-probability @gol

6191

-fif-conversion2 @gol

6192

-fif-conversion @gol

6193

-finline-functions-called-once @gol

6194

-fipa-pure-const @gol

6195

-fipa-profile @gol

6196

-fipa-reference @gol

6197

-fmerge-constants @gol

6198

-fmove-loop-invariants @gol

6199

-freorder-blocks @gol

6200

-fshrink-wrap @gol

6201

-fsplit-wide-types @gol

6202

-fssa-backprop @gol

6203

-fssa-phiopt @gol

6204

-ftree-bit-ccp @gol

6205

-ftree-ccp @gol

6206

-ftree-ch @gol

6207

-ftree-coalesce-vars @gol

6208

-ftree-copy-prop @gol

6209

-ftree-dce @gol

6210

-ftree-dominator-opts @gol

6211

-ftree-dse @gol

6212

-ftree-forwprop @gol

6213

-ftree-fre @gol

6214

-ftree-phiprop @gol

6215

-ftree-sink @gol

6216

-ftree-slsr @gol

6217

-ftree-sra @gol

6218

-ftree-pta @gol

6219

-ftree-ter @gol

6220

-funit-at-a-time}

6221

6222

@option{-O} also turns on @option{-fomit-frame-pointer} on machines

6223

where doing so does not interfere with debugging.

6224

6225

@item -O2

6226

@opindex O2

6227

Optimize even more. GCC performs nearly all supported optimizations

6228

that do not involve a space-speed tradeoff.

6229

As compared to @option{-O}, this option increases both compilation time

6230

and the performance of the generated code.

6231

6232

@option{-O2} turns on all optimization flags specified by @option{-O}. It

6233

also turns on the following optimization flags:

6234

@gccoptlist{-fthread-jumps @gol

6235

-falign-functions -falign-jumps @gol

6236

-falign-loops -falign-labels @gol

6237

-fcaller-saves @gol

6238

-fcrossjumping @gol

6239

-fcse-follow-jumps -fcse-skip-blocks @gol

6240

-fdelete-null-pointer-checks @gol

6241

-fdevirtualize -fdevirtualize-speculatively @gol

6242

-fexpensive-optimizations @gol

6243

-fgcse -fgcse-lm @gol

6244

-fhoist-adjacent-loads @gol

6245

-finline-small-functions @gol

6246

-findirect-inlining @gol

6247

-fipa-cp @gol

6248

-fipa-cp-alignment @gol

6249

-fipa-sra @gol

6250

-fipa-icf @gol

6251

-fisolate-erroneous-paths-dereference @gol

6252

-flra-remat @gol

6253

-foptimize-sibling-calls @gol

6254

-foptimize-strlen @gol

6255

-fpartial-inlining @gol

6256

-fpeephole2 @gol

6257

-freorder-blocks-algorithm=stc @gol

6258

-freorder-blocks-and-partition -freorder-functions @gol

6259

-frerun-cse-after-loop @gol

6260

-fsched-interblock -fsched-spec @gol

6261

-fschedule-insns -fschedule-insns2 @gol

6262

-fstrict-aliasing -fstrict-overflow @gol

6263

-ftree-builtin-call-dce @gol

6264

-ftree-switch-conversion -ftree-tail-merge @gol

6265

-ftree-pre @gol

6266

-ftree-vrp @gol

6267

-fipa-ra}

6268

6269

Please note the warning under @option{-fgcse} about

6270

invoking @option{-O2} on programs that use computed gotos.

6271

6272

@item -O3

6273

@opindex O3

6274

Optimize yet more. @option{-O3} turns on all optimizations specified

6275

by @option{-O2} and also turns on the @option{-finline-functions},

6276

@option{-funswitch-loops}, @option{-fpredictive-commoning},

6277

@option{-fgcse-after-reload}, @option{-ftree-loop-vectorize},

6278

@option{-ftree-loop-distribute-patterns}, @option{-fsplit-paths}

6279

@option{-ftree-slp-vectorize}, @option{-fvect-cost-model},

6280

@option{-ftree-partial-pre} and @option{-fipa-cp-clone} options.

6281

6282

@item -O0

6283

@opindex O0

6284

Reduce compilation time and make debugging produce the expected

6285

results. This is the default.

6286

6287

@item -Os

6288

@opindex Os

6289

Optimize for size. @option{-Os} enables all @option{-O2} optimizations that

6290

do not typically increase code size. It also performs further

6291

optimizations designed to reduce code size.

6292

6293

@option{-Os} disables the following optimization flags:

6294

@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol

6295

-falign-labels -freorder-blocks -freorder-blocks-algorithm=stc @gol

6296

-freorder-blocks-and-partition -fprefetch-loop-arrays}

6297

6298

@item -Ofast

6299

@opindex Ofast

6300

Disregard strict standards compliance. @option{-Ofast} enables all

6301

@option{-O3} optimizations. It also enables optimizations that are not

6302

valid for all standard-compliant programs.

6303

It turns on @option{-ffast-math} and the Fortran-specific

6304

@option{-fno-protect-parens} and @option{-fstack-arrays}.

6305

6306

@item -Og

6307

@opindex Og

6308

Optimize debugging experience. @option{-Og} enables optimizations

6309

that do not interfere with debugging. It should be the optimization

6310

level of choice for the standard edit-compile-debug cycle, offering

6311

a reasonable level of optimization while maintaining fast compilation

6312

and a good debugging experience.

6313

@end table

6314

6315

If you use multiple @option{-O} options, with or without level numbers,

6316

the last such option is the one that is effective.

6317

6318

Options of the form @option{-f@var{flag}} specify machine-independent

6319

flags. Most flags have both positive and negative forms; the negative

6320

form of @option{-ffoo} is @option{-fno-foo}. In the table

6321

below, only one of the forms is listed---the one you typically

6322

use. You can figure out the other form by either removing @samp{no-}

6323

or adding it.

6324

6325

The following options control specific optimizations. They are either

6326

activated by @option{-O} options or are related to ones that are. You

6327

can use the following flags in the rare cases when ``fine-tuning'' of

6328

optimizations to be performed is desired.

6329

6330

@table @gcctabopt

6331

@item -fno-defer-pop

6332

@opindex fno-defer-pop

6333

Always pop the arguments to each function call as soon as that function

6334

returns. For machines that must pop arguments after a function call,

6335

the compiler normally lets arguments accumulate on the stack for several

6336

function calls and pops them all at once.

6337

6338

Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

6339

6340

@item -fforward-propagate

6341

@opindex fforward-propagate

6342

Perform a forward propagation pass on RTL@. The pass tries to combine two

6343

instructions and checks if the result can be simplified. If loop unrolling

6344

is active, two passes are performed and the second is scheduled after

6345

loop unrolling.

6346

6347

This option is enabled by default at optimization levels @option{-O},

6348

@option{-O2}, @option{-O3}, @option{-Os}.

6349

6350

@item -ffp-contract=@var{style}

6351

@opindex ffp-contract

6352

@option{-ffp-contract=off} disables floating-point expression contraction.

6353

@option{-ffp-contract=fast} enables floating-point expression contraction

6354

such as forming of fused multiply-add operations if the target has

6355

native support for them.

6356

@option{-ffp-contract=on} enables floating-point expression contraction

6357

if allowed by the language standard. This is currently not implemented

6358

and treated equal to @option{-ffp-contract=off}.

6359

6360

The default is @option{-ffp-contract=fast}.

6361

6362

@item -fomit-frame-pointer

6363

@opindex fomit-frame-pointer

6364

Don't keep the frame pointer in a register for functions that

6365

don't need one. This avoids the instructions to save, set up and

6366

restore frame pointers; it also makes an extra register available

6367

in many functions. @strong{It also makes debugging impossible on

6368

some machines.}

6369

6370

On some machines, such as the VAX, this flag has no effect, because

6371

the standard calling sequence automatically handles the frame pointer

6372

and nothing is saved by pretending it doesn't exist. The

6373

machine-description macro @code{FRAME_POINTER_REQUIRED} controls

6374

whether a target machine supports this flag. @xref{Registers,,Register

6375

Usage, gccint, GNU Compiler Collection (GCC) Internals}.

6376

6377

The default setting (when not optimizing for

6378

size) for 32-bit GNU/Linux x86 and 32-bit Darwin x86 targets is

6379

@option{-fomit-frame-pointer}. You can configure GCC with the

6380

@option{--enable-frame-pointer} configure option to change the default.

6381

6382

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

6383

6384

@item -foptimize-sibling-calls

6385

@opindex foptimize-sibling-calls

6386

Optimize sibling and tail recursive calls.

6387

6388

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6389

6390

@item -foptimize-strlen

6391

@opindex foptimize-strlen

6392

Optimize various standard C string functions (e.g. @code{strlen},

6393

@code{strchr} or @code{strcpy}) and

6394

their @code{_FORTIFY_SOURCE} counterparts into faster alternatives.

6395

6396

Enabled at levels @option{-O2}, @option{-O3}.

6397

6398

@item -fno-inline

6399

@opindex fno-inline

6400

Do not expand any functions inline apart from those marked with

6401

the @code{always_inline} attribute. This is the default when not

6402

optimizing.

6403

6404

Single functions can be exempted from inlining by marking them

6405

with the @code{noinline} attribute.

6406

6407

@item -finline-small-functions

6408

@opindex finline-small-functions

6409

Integrate functions into their callers when their body is smaller than expected

6410

function call code (so overall size of program gets smaller). The compiler

6411

heuristically decides which functions are simple enough to be worth integrating

6412

in this way. This inlining applies to all functions, even those not declared

6413

inline.

6414

6415

Enabled at level @option{-O2}.

6416

6417

@item -findirect-inlining

6418

@opindex findirect-inlining

6419

Inline also indirect calls that are discovered to be known at compile

6420

time thanks to previous inlining. This option has any effect only

6421

when inlining itself is turned on by the @option{-finline-functions}

6422

or @option{-finline-small-functions} options.

6423

6424

Enabled at level @option{-O2}.

6425

6426

@item -finline-functions

6427

@opindex finline-functions

6428

Consider all functions for inlining, even if they are not declared inline.

6429

The compiler heuristically decides which functions are worth integrating

6430

in this way.

6431

6432

If all calls to a given function are integrated, and the function is

6433

declared @code{static}, then the function is normally not output as

6434

assembler code in its own right.

6435

6436

Enabled at level @option{-O3}.

6437

6438

@item -finline-functions-called-once

6439

@opindex finline-functions-called-once

6440

Consider all @code{static} functions called once for inlining into their

6441

caller even if they are not marked @code{inline}. If a call to a given

6442

function is integrated, then the function is not output as assembler code

6443

in its own right.

6444

6445

Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}.

6446

6447

@item -fearly-inlining

6448

@opindex fearly-inlining

6449

Inline functions marked by @code{always_inline} and functions whose body seems

6450

smaller than the function call overhead early before doing

6451

@option{-fprofile-generate} instrumentation and real inlining pass. Doing so

6452

makes profiling significantly cheaper and usually inlining faster on programs

6453

having large chains of nested wrapper functions.

6454

6455

Enabled by default.

6456

6457

@item -fipa-sra

6458

@opindex fipa-sra

6459

Perform interprocedural scalar replacement of aggregates, removal of

6460

unused parameters and replacement of parameters passed by reference

6461

by parameters passed by value.

6462

6463

Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}.

6464

6465

@item -finline-limit=@var{n}

6466

@opindex finline-limit

6467

By default, GCC limits the size of functions that can be inlined. This flag

6468

allows coarse control of this limit. @var{n} is the size of functions that

6469

can be inlined in number of pseudo instructions.

6470

6471

Inlining is actually controlled by a number of parameters, which may be

6472

specified individually by using @option{--param @var{name}=@var{value}}.

6473

The @option{-finline-limit=@var{n}} option sets some of these parameters

6474

as follows:

6475

6476

@table @gcctabopt

6477

@item max-inline-insns-single

6478

is set to @var{n}/2.

6479

@item max-inline-insns-auto

6480

is set to @var{n}/2.

6481

@end table

6482

6483

See below for a documentation of the individual

6484

parameters controlling inlining and for the defaults of these parameters.

6485

6486

@emph{Note:} there may be no value to @option{-finline-limit} that results

6487

in default behavior.

6488

6489

@emph{Note:} pseudo instruction represents, in this particular context, an

6490

abstract measurement of function's size. In no way does it represent a count

6491

of assembly instructions and as such its exact meaning might change from one

6492

release to an another.

6493

6494

@item -fno-keep-inline-dllexport

6495

@opindex fno-keep-inline-dllexport

6496

This is a more fine-grained version of @option{-fkeep-inline-functions},

6497

which applies only to functions that are declared using the @code{dllexport}

6498

attribute or declspec (@xref{Function Attributes,,Declaring Attributes of

6499

Functions}.)

6500

6501

@item -fkeep-inline-functions

6502

@opindex fkeep-inline-functions

6503

In C, emit @code{static} functions that are declared @code{inline}

6504

into the object file, even if the function has been inlined into all

6505

of its callers. This switch does not affect functions using the

6506

@code{extern inline} extension in GNU C90@. In C++, emit any and all

6507

inline functions into the object file.

6508

6509

@item -fkeep-static-functions

6510

@opindex fkeep-static-functions

6511

Emit @code{static} functions into the object file, even if the function

6512

is never used.

6513

6514

@item -fkeep-static-consts

6515

@opindex fkeep-static-consts

6516

Emit variables declared @code{static const} when optimization isn't turned

6517

on, even if the variables aren't referenced.

6518

6519

GCC enables this option by default. If you want to force the compiler to

6520

check if a variable is referenced, regardless of whether or not

6521

optimization is turned on, use the @option{-fno-keep-static-consts} option.

6522

6523

@item -fmerge-constants

6524

@opindex fmerge-constants

6525

Attempt to merge identical constants (string constants and floating-point

6526

constants) across compilation units.

6527

6528

This option is the default for optimized compilation if the assembler and

6529

linker support it. Use @option{-fno-merge-constants} to inhibit this

6530

behavior.

6531

6532

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

6533

6534

@item -fmerge-all-constants

6535

@opindex fmerge-all-constants

6536

Attempt to merge identical constants and identical variables.

6537

6538

This option implies @option{-fmerge-constants}. In addition to

6539

@option{-fmerge-constants} this considers e.g.@: even constant initialized

6540

arrays or initialized constant variables with integral or floating-point

6541

types. Languages like C or C++ require each variable, including multiple

6542

instances of the same variable in recursive calls, to have distinct locations,

6543

so using this option results in non-conforming

6544

behavior.

6545

6546

@item -fmodulo-sched

6547

@opindex fmodulo-sched

6548

Perform swing modulo scheduling immediately before the first scheduling

6549

pass. This pass looks at innermost loops and reorders their

6550

instructions by overlapping different iterations.

6551

6552

@item -fmodulo-sched-allow-regmoves

6553

@opindex fmodulo-sched-allow-regmoves

6554

Perform more aggressive SMS-based modulo scheduling with register moves

6555

allowed. By setting this flag certain anti-dependences edges are

6556

deleted, which triggers the generation of reg-moves based on the

6557

life-range analysis. This option is effective only with

6558

@option{-fmodulo-sched} enabled.

6559

6560

@item -fno-branch-count-reg

6561

@opindex fno-branch-count-reg

6562

Avoid running a pass scanning for opportunities to use ``decrement and

6563

branch'' instructions on a count register instead of generating sequences

6564

of instructions that decrement a register, compare it against zero, and

6565

then branch based upon the result. This option is only meaningful on

6566

architectures that support such instructions, which include x86, PowerPC,

6567

IA-64 and S/390. Note that the @option{-fno-branch-count-reg} option

6568

doesn't remove the decrement and branch instructions from the generated

6569

instruction stream introduced by other optimization passes.

6570

6571

Enabled by default at @option{-O1} and higher.

6572

6573

The default is @option{-fbranch-count-reg}.

6574

6575

@item -fno-function-cse

6576

@opindex fno-function-cse

6577

Do not put function addresses in registers; make each instruction that

6578

calls a constant function contain the function's address explicitly.

6579

6580

This option results in less efficient code, but some strange hacks

6581

that alter the assembler output may be confused by the optimizations

6582

performed when this option is not used.

6583

6584

The default is @option{-ffunction-cse}

6585

6586

@item -fno-zero-initialized-in-bss

6587

@opindex fno-zero-initialized-in-bss

6588

If the target supports a BSS section, GCC by default puts variables that

6589

are initialized to zero into BSS@. This can save space in the resulting

6590

code.

6591

6592

This option turns off this behavior because some programs explicitly

6593

rely on variables going to the data section---e.g., so that the

6594

resulting executable can find the beginning of that section and/or make

6595

assumptions based on that.

6596

6597

The default is @option{-fzero-initialized-in-bss}.

6598

6599

@item -fthread-jumps

6600

@opindex fthread-jumps

6601

Perform optimizations that check to see if a jump branches to a

6602

location where another comparison subsumed by the first is found. If

6603

so, the first branch is redirected to either the destination of the

6604

second branch or a point immediately following it, depending on whether

6605

the condition is known to be true or false.

6606

6607

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6608

6609

@item -fsplit-wide-types

6610

@opindex fsplit-wide-types

6611

When using a type that occupies multiple registers, such as @code{long

6612

long} on a 32-bit system, split the registers apart and allocate them

6613

independently. This normally generates better code for those types,

6614

but may make debugging more difficult.

6615

6616

Enabled at levels @option{-O}, @option{-O2}, @option{-O3},

6617

@option{-Os}.

6618

6619

@item -fcse-follow-jumps

6620

@opindex fcse-follow-jumps

6621

In common subexpression elimination (CSE), scan through jump instructions

6622

when the target of the jump is not reached by any other path. For

6623

example, when CSE encounters an @code{if} statement with an

6624

@code{else} clause, CSE follows the jump when the condition

6625

tested is false.

6626

6627

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6628

6629

@item -fcse-skip-blocks

6630

@opindex fcse-skip-blocks

6631

This is similar to @option{-fcse-follow-jumps}, but causes CSE to

6632

follow jumps that conditionally skip over blocks. When CSE

6633

encounters a simple @code{if} statement with no else clause,

6634

@option{-fcse-skip-blocks} causes CSE to follow the jump around the

6635

body of the @code{if}.

6636

6637

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6638

6639

@item -frerun-cse-after-loop

6640

@opindex frerun-cse-after-loop

6641

Re-run common subexpression elimination after loop optimizations are

6642

performed.

6643

6644

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6645

6646

@item -fgcse

6647

@opindex fgcse

6648

Perform a global common subexpression elimination pass.

6649

This pass also performs global constant and copy propagation.

6650

6651

@emph{Note:} When compiling a program using computed gotos, a GCC

6652

extension, you may get better run-time performance if you disable

6653

the global common subexpression elimination pass by adding

6654

@option{-fno-gcse} to the command line.

6655

6656

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6657

6658

@item -fgcse-lm

6659

@opindex fgcse-lm

6660

When @option{-fgcse-lm} is enabled, global common subexpression elimination

6661

attempts to move loads that are only killed by stores into themselves. This

6662

allows a loop containing a load/store sequence to be changed to a load outside

6663

the loop, and a copy/store within the loop.

6664

6665

Enabled by default when @option{-fgcse} is enabled.

6666

6667

@item -fgcse-sm

6668

@opindex fgcse-sm

6669

When @option{-fgcse-sm} is enabled, a store motion pass is run after

6670

global common subexpression elimination. This pass attempts to move

6671

stores out of loops. When used in conjunction with @option{-fgcse-lm},

6672

loops containing a load/store sequence can be changed to a load before

6673

the loop and a store after the loop.

6674

6675

Not enabled at any optimization level.

6676

6677

@item -fgcse-las

6678

@opindex fgcse-las

6679

When @option{-fgcse-las} is enabled, the global common subexpression

6680

elimination pass eliminates redundant loads that come after stores to the

6681

same memory location (both partial and full redundancies).

6682

6683

Not enabled at any optimization level.

6684

6685

@item -fgcse-after-reload

6686

@opindex fgcse-after-reload

6687

When @option{-fgcse-after-reload} is enabled, a redundant load elimination

6688

pass is performed after reload. The purpose of this pass is to clean up

6689

redundant spilling.

6690

6691

@item -faggressive-loop-optimizations

6692

@opindex faggressive-loop-optimizations

6693

This option tells the loop optimizer to use language constraints to

6694

derive bounds for the number of iterations of a loop. This assumes that

6695

loop code does not invoke undefined behavior by for example causing signed

6696

integer overflows or out-of-bound array accesses. The bounds for the

6697

number of iterations of a loop are used to guide loop unrolling and peeling

6698

and loop exit test optimizations.

6699

This option is enabled by default.

6700

6701

@item -funsafe-loop-optimizations

6702

@opindex funsafe-loop-optimizations

6703

This option tells the loop optimizer to assume that loop indices do not

6704

overflow, and that loops with nontrivial exit condition are not

6705

infinite. This enables a wider range of loop optimizations even if

6706

the loop optimizer itself cannot prove that these assumptions are valid.

6707

If you use @option{-Wunsafe-loop-optimizations}, the compiler warns you

6708

if it finds this kind of loop.

6709

6710

@item -funconstrained-commons

6711

@opindex funconstrained-commons

6712

This option tells the compiler that variables declared in common blocks

6713

(e.g. Fortran) may later be overridden with longer trailing arrays. This

6714

prevents certain optimizations that depend on knowing the array bounds.

6715

6716

@item -fcrossjumping

6717

@opindex fcrossjumping

6718

Perform cross-jumping transformation.

6719

This transformation unifies equivalent code and saves code size. The

6720

resulting code may or may not perform better than without cross-jumping.

6721

6722

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6723

6724

@item -fauto-inc-dec

6725

@opindex fauto-inc-dec

6726

Combine increments or decrements of addresses with memory accesses.

6727

This pass is always skipped on architectures that do not have

6728

instructions to support this. Enabled by default at @option{-O} and

6729

higher on architectures that support this.

6730

6731

@item -fdce

6732

@opindex fdce

6733

Perform dead code elimination (DCE) on RTL@.

6734

Enabled by default at @option{-O} and higher.

6735

6736

@item -fdse

6737

@opindex fdse

6738

Perform dead store elimination (DSE) on RTL@.

6739

Enabled by default at @option{-O} and higher.

6740

6741

@item -fif-conversion

6742

@opindex fif-conversion

6743

Attempt to transform conditional jumps into branch-less equivalents. This

6744

includes use of conditional moves, min, max, set flags and abs instructions, and

6745

some tricks doable by standard arithmetics. The use of conditional execution

6746

on chips where it is available is controlled by @option{-fif-conversion2}.

6747

6748

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

6749

6750

@item -fif-conversion2

6751

@opindex fif-conversion2

6752

Use conditional execution (where available) to transform conditional jumps into

6753

branch-less equivalents.

6754

6755

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

6756

6757

@item -fdeclone-ctor-dtor

6758

@opindex fdeclone-ctor-dtor

6759

The C++ ABI requires multiple entry points for constructors and

6760

destructors: one for a base subobject, one for a complete object, and

6761

one for a virtual destructor that calls operator delete afterwards.

6762

For a hierarchy with virtual bases, the base and complete variants are

6763

clones, which means two copies of the function. With this option, the

6764

base and complete variants are changed to be thunks that call a common

6765

implementation.

6766

6767

Enabled by @option{-Os}.

6768

6769

@item -fdelete-null-pointer-checks

6770

@opindex fdelete-null-pointer-checks

6771

Assume that programs cannot safely dereference null pointers, and that

6772

no code or data element resides at address zero.

6773

This option enables simple constant

6774

folding optimizations at all optimization levels. In addition, other

6775

optimization passes in GCC use this flag to control global dataflow

6776

analyses that eliminate useless checks for null pointers; these assume

6777

that a memory access to address zero always results in a trap, so

6778

that if a pointer is checked after it has already been dereferenced,

6779

it cannot be null.

6780

6781

Note however that in some environments this assumption is not true.

6782

Use @option{-fno-delete-null-pointer-checks} to disable this optimization

6783

for programs that depend on that behavior.

6784

6785

This option is enabled by default on most targets. On Nios II ELF, it

6786

defaults to off. On AVR and CR16, this option is completely disabled.

6787

6788

Passes that use the dataflow information

6789

are enabled independently at different optimization levels.

6790

6791

@item -fdevirtualize

6792

@opindex fdevirtualize

6793

Attempt to convert calls to virtual functions to direct calls. This

6794

is done both within a procedure and interprocedurally as part of

6795

indirect inlining (@option{-findirect-inlining}) and interprocedural constant

6796

propagation (@option{-fipa-cp}).

6797

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6798

6799

@item -fdevirtualize-speculatively

6800

@opindex fdevirtualize-speculatively

6801

Attempt to convert calls to virtual functions to speculative direct calls.

6802

Based on the analysis of the type inheritance graph, determine for a given call

6803

the set of likely targets. If the set is small, preferably of size 1, change

6804

the call into a conditional deciding between direct and indirect calls. The

6805

speculative calls enable more optimizations, such as inlining. When they seem

6806

useless after further optimization, they are converted back into original form.

6807

6808

@item -fdevirtualize-at-ltrans

6809

@opindex fdevirtualize-at-ltrans

6810

Stream extra information needed for aggressive devirtualization when running

6811

the link-time optimizer in local transformation mode.

6812

This option enables more devirtualization but

6813

significantly increases the size of streamed data. For this reason it is

6814

disabled by default.

6815

6816

@item -fexpensive-optimizations

6817

@opindex fexpensive-optimizations

6818

Perform a number of minor optimizations that are relatively expensive.

6819

6820

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6821

6822

@item -free

6823

@opindex free

6824

Attempt to remove redundant extension instructions. This is especially

6825

helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit

6826

registers after writing to their lower 32-bit half.

6827

6828

Enabled for Alpha, AArch64 and x86 at levels @option{-O2},

6829

@option{-O3}, @option{-Os}.

6830

6831

@item -fno-lifetime-dse

6832

@opindex fno-lifetime-dse

6833

In C++ the value of an object is only affected by changes within its

6834

lifetime: when the constructor begins, the object has an indeterminate

6835

value, and any changes during the lifetime of the object are dead when

6836

the object is destroyed. Normally dead store elimination will take

6837

advantage of this; if your code relies on the value of the object

6838

storage persisting beyond the lifetime of the object, you can use this

6839

flag to disable this optimization. To preserve stores before the

6840

constructor starts (e.g. because your operator new clears the object

6841

storage) but still treat the object as dead after the destructor you,

6842

can use @option{-flifetime-dse=1}. The default behavior can be

6843

explicitly selected with @option{-flifetime-dse=2}.

6844

@option{-flifetime-dse=0} is equivalent to @option{-fno-lifetime-dse}.

6845

6846

@item -flive-range-shrinkage

6847

@opindex flive-range-shrinkage

6848

Attempt to decrease register pressure through register live range

6849

shrinkage. This is helpful for fast processors with small or moderate

6850

size register sets.

6851

6852

@item -fira-algorithm=@var{algorithm}

6853

@opindex fira-algorithm

6854

Use the specified coloring algorithm for the integrated register

6855

allocator. The @var{algorithm} argument can be @samp{priority}, which

6856

specifies Chow's priority coloring, or @samp{CB}, which specifies

6857

Chaitin-Briggs coloring. Chaitin-Briggs coloring is not implemented

6858

for all architectures, but for those targets that do support it, it is

6859

the default because it generates better code.

6860

6861

@item -fira-region=@var{region}

6862

@opindex fira-region

6863

Use specified regions for the integrated register allocator. The

6864

@var{region} argument should be one of the following:

6865

6866

@table @samp

6867

6868

@item all

6869

Use all loops as register allocation regions.

6870

This can give the best results for machines with a small and/or

6871

irregular register set.

6872

6873

@item mixed

6874

Use all loops except for loops with small register pressure

6875

as the regions. This value usually gives

6876

the best results in most cases and for most architectures,

6877

and is enabled by default when compiling with optimization for speed

6878

(@option{-O}, @option{-O2}, @dots{}).

6879

6880

@item one

6881

Use all functions as a single region.

6882

This typically results in the smallest code size, and is enabled by default for

6883

@option{-Os} or @option{-O0}.

6884

6885

@end table

6886

6887

@item -fira-hoist-pressure

6888

@opindex fira-hoist-pressure

6889

Use IRA to evaluate register pressure in the code hoisting pass for

6890

decisions to hoist expressions. This option usually results in smaller

6891

code, but it can slow the compiler down.

6892

6893

This option is enabled at level @option{-Os} for all targets.

6894

6895

@item -fira-loop-pressure

6896

@opindex fira-loop-pressure

6897

Use IRA to evaluate register pressure in loops for decisions to move

6898

loop invariants. This option usually results in generation

6899

of faster and smaller code on machines with large register files (>= 32

6900

registers), but it can slow the compiler down.

6901

6902

This option is enabled at level @option{-O3} for some targets.

6903

6904

@item -fno-ira-share-save-slots

6905

@opindex fno-ira-share-save-slots

6906

Disable sharing of stack slots used for saving call-used hard

6907

registers living through a call. Each hard register gets a

6908

separate stack slot, and as a result function stack frames are

6909

larger.

6910

6911

@item -fno-ira-share-spill-slots

6912

@opindex fno-ira-share-spill-slots

6913

Disable sharing of stack slots allocated for pseudo-registers. Each

6914

pseudo-register that does not get a hard register gets a separate

6915

stack slot, and as a result function stack frames are larger.

6916

6917

@item -flra-remat

6918

@opindex flra-remat

6919

Enable CFG-sensitive rematerialization in LRA. Instead of loading

6920

values of spilled pseudos, LRA tries to rematerialize (recalculate)

6921

values if it is profitable.

6922

6923

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6924

6925

@item -fdelayed-branch

6926

@opindex fdelayed-branch

6927

If supported for the target machine, attempt to reorder instructions

6928

to exploit instruction slots available after delayed branch

6929

instructions.

6930

6931

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

6932

6933

@item -fschedule-insns

6934

@opindex fschedule-insns

6935

If supported for the target machine, attempt to reorder instructions to

6936

eliminate execution stalls due to required data being unavailable. This

6937

helps machines that have slow floating point or memory load instructions

6938

by allowing other instructions to be issued until the result of the load

6939

or floating-point instruction is required.

6940

6941

Enabled at levels @option{-O2}, @option{-O3}.

6942

6943

@item -fschedule-insns2

6944

@opindex fschedule-insns2

6945

Similar to @option{-fschedule-insns}, but requests an additional pass of

6946

instruction scheduling after register allocation has been done. This is

6947

especially useful on machines with a relatively small number of

6948

registers and where memory load instructions take more than one cycle.

6949

6950

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

6951

6952

@item -fno-sched-interblock

6953

@opindex fno-sched-interblock

6954

Don't schedule instructions across basic blocks. This is normally

6955

enabled by default when scheduling before register allocation, i.e.@:

6956

with @option{-fschedule-insns} or at @option{-O2} or higher.

6957

6958

@item -fno-sched-spec

6959

@opindex fno-sched-spec

6960

Don't allow speculative motion of non-load instructions. This is normally

6961

enabled by default when scheduling before register allocation, i.e.@:

6962

with @option{-fschedule-insns} or at @option{-O2} or higher.

6963

6964

@item -fsched-pressure

6965

@opindex fsched-pressure

6966

Enable register pressure sensitive insn scheduling before register

6967

allocation. This only makes sense when scheduling before register

6968

allocation is enabled, i.e.@: with @option{-fschedule-insns} or at

6969

@option{-O2} or higher. Usage of this option can improve the

6970

generated code and decrease its size by preventing register pressure

6971

increase above the number of available hard registers and subsequent

6972

spills in register allocation.

6973

6974

@item -fsched-spec-load

6975

@opindex fsched-spec-load

6976

Allow speculative motion of some load instructions. This only makes

6977

sense when scheduling before register allocation, i.e.@: with

6978

@option{-fschedule-insns} or at @option{-O2} or higher.

6979

6980

@item -fsched-spec-load-dangerous

6981

@opindex fsched-spec-load-dangerous

6982

Allow speculative motion of more load instructions. This only makes

6983

sense when scheduling before register allocation, i.e.@: with

6984

@option{-fschedule-insns} or at @option{-O2} or higher.

6985

6986

@item -fsched-stalled-insns

6987

@itemx -fsched-stalled-insns=@var{n}

6988

@opindex fsched-stalled-insns

6989

Define how many insns (if any) can be moved prematurely from the queue

6990

of stalled insns into the ready list during the second scheduling pass.

6991

@option{-fno-sched-stalled-insns} means that no insns are moved

6992

prematurely, @option{-fsched-stalled-insns=0} means there is no limit

6993

on how many queued insns can be moved prematurely.

6994

@option{-fsched-stalled-insns} without a value is equivalent to

6995

@option{-fsched-stalled-insns=1}.

6996

6997

@item -fsched-stalled-insns-dep

6998

@itemx -fsched-stalled-insns-dep=@var{n}

6999

@opindex fsched-stalled-insns-dep

7000

Define how many insn groups (cycles) are examined for a dependency

7001

on a stalled insn that is a candidate for premature removal from the queue

7002

of stalled insns. This has an effect only during the second scheduling pass,

7003

and only if @option{-fsched-stalled-insns} is used.

7004

@option{-fno-sched-stalled-insns-dep} is equivalent to

7005

@option{-fsched-stalled-insns-dep=0}.

7006

@option{-fsched-stalled-insns-dep} without a value is equivalent to

7007

@option{-fsched-stalled-insns-dep=1}.

7008

7009

@item -fsched2-use-superblocks

7010

@opindex fsched2-use-superblocks

7011

When scheduling after register allocation, use superblock scheduling.

7012

This allows motion across basic block boundaries,

7013

resulting in faster schedules. This option is experimental, as not all machine

7014

descriptions used by GCC model the CPU closely enough to avoid unreliable

7015

results from the algorithm.

7016

7017

This only makes sense when scheduling after register allocation, i.e.@: with

7018

@option{-fschedule-insns2} or at @option{-O2} or higher.

7019

7020

@item -fsched-group-heuristic

7021

@opindex fsched-group-heuristic

7022

Enable the group heuristic in the scheduler. This heuristic favors

7023

the instruction that belongs to a schedule group. This is enabled

7024

by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns}

7025

or @option{-fschedule-insns2} or at @option{-O2} or higher.

7026

7027

@item -fsched-critical-path-heuristic

7028

@opindex fsched-critical-path-heuristic

7029

Enable the critical-path heuristic in the scheduler. This heuristic favors

7030

instructions on the critical path. This is enabled by default when

7031

scheduling is enabled, i.e.@: with @option{-fschedule-insns}

7032

or @option{-fschedule-insns2} or at @option{-O2} or higher.

7033

7034

@item -fsched-spec-insn-heuristic

7035

@opindex fsched-spec-insn-heuristic

7036

Enable the speculative instruction heuristic in the scheduler. This

7037

heuristic favors speculative instructions with greater dependency weakness.

7038

This is enabled by default when scheduling is enabled, i.e.@:

7039

with @option{-fschedule-insns} or @option{-fschedule-insns2}

7040

or at @option{-O2} or higher.

7041

7042

@item -fsched-rank-heuristic

7043

@opindex fsched-rank-heuristic

7044

Enable the rank heuristic in the scheduler. This heuristic favors

7045

the instruction belonging to a basic block with greater size or frequency.

7046

This is enabled by default when scheduling is enabled, i.e.@:

7047

with @option{-fschedule-insns} or @option{-fschedule-insns2} or

7048

at @option{-O2} or higher.

7049

7050

@item -fsched-last-insn-heuristic

7051

@opindex fsched-last-insn-heuristic

7052

Enable the last-instruction heuristic in the scheduler. This heuristic

7053

favors the instruction that is less dependent on the last instruction

7054

scheduled. This is enabled by default when scheduling is enabled,

7055

i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or

7056

at @option{-O2} or higher.

7057

7058

@item -fsched-dep-count-heuristic

7059

@opindex fsched-dep-count-heuristic

7060

Enable the dependent-count heuristic in the scheduler. This heuristic

7061

favors the instruction that has more instructions depending on it.

7062

This is enabled by default when scheduling is enabled, i.e.@:

7063

with @option{-fschedule-insns} or @option{-fschedule-insns2} or

7064

at @option{-O2} or higher.

7065

7066

@item -freschedule-modulo-scheduled-loops

7067

@opindex freschedule-modulo-scheduled-loops

7068

Modulo scheduling is performed before traditional scheduling. If a loop

7069

is modulo scheduled, later scheduling passes may change its schedule.

7070

Use this option to control that behavior.

7071

7072

@item -fselective-scheduling

7073

@opindex fselective-scheduling

7074

Schedule instructions using selective scheduling algorithm. Selective

7075

scheduling runs instead of the first scheduler pass.

7076

7077

@item -fselective-scheduling2

7078

@opindex fselective-scheduling2

7079

Schedule instructions using selective scheduling algorithm. Selective

7080

scheduling runs instead of the second scheduler pass.

7081

7082

@item -fsel-sched-pipelining

7083

@opindex fsel-sched-pipelining

7084

Enable software pipelining of innermost loops during selective scheduling.

7085

This option has no effect unless one of @option{-fselective-scheduling} or

7086

@option{-fselective-scheduling2} is turned on.

7087

7088

@item -fsel-sched-pipelining-outer-loops

7089

@opindex fsel-sched-pipelining-outer-loops

7090

When pipelining loops during selective scheduling, also pipeline outer loops.

7091

This option has no effect unless @option{-fsel-sched-pipelining} is turned on.

7092

7093

@item -fsemantic-interposition

7094

@opindex fsemantic-interposition

7095

Some object formats, like ELF, allow interposing of symbols by the

7096

dynamic linker.

7097

This means that for symbols exported from the DSO, the compiler cannot perform

7098

interprocedural propagation, inlining and other optimizations in anticipation

7099

that the function or variable in question may change. While this feature is

7100

useful, for example, to rewrite memory allocation functions by a debugging

7101

implementation, it is expensive in the terms of code quality.

7102

With @option{-fno-semantic-interposition} the compiler assumes that

7103

if interposition happens for functions the overwriting function will have

7104

precisely the same semantics (and side effects).

7105

Similarly if interposition happens

7106

for variables, the constructor of the variable will be the same. The flag

7107

has no effect for functions explicitly declared inline

7108

(where it is never allowed for interposition to change semantics)

7109

and for symbols explicitly declared weak.

7110

7111

@item -fshrink-wrap

7112

@opindex fshrink-wrap

7113

Emit function prologues only before parts of the function that need it,

7114

rather than at the top of the function. This flag is enabled by default at

7115

@option{-O} and higher.

7116

7117

@item -fcaller-saves

7118

@opindex fcaller-saves

7119

Enable allocation of values to registers that are clobbered by

7120

function calls, by emitting extra instructions to save and restore the

7121

registers around such calls. Such allocation is done only when it

7122

seems to result in better code.

7123

7124

This option is always enabled by default on certain machines, usually

7125

those which have no call-preserved registers to use instead.

7126

7127

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

7128

7129

@item -fcombine-stack-adjustments

7130

@opindex fcombine-stack-adjustments

7131

Tracks stack adjustments (pushes and pops) and stack memory references

7132

and then tries to find ways to combine them.

7133

7134

Enabled by default at @option{-O1} and higher.

7135

7136

@item -fipa-ra

7137

@opindex fipa-ra

7138

Use caller save registers for allocation if those registers are not used by

7139

any called function. In that case it is not necessary to save and restore

7140

them around calls. This is only possible if called functions are part of

7141

same compilation unit as current function and they are compiled before it.

7142

7143

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

7144

7145

@item -fconserve-stack

7146

@opindex fconserve-stack

7147

Attempt to minimize stack usage. The compiler attempts to use less

7148

stack space, even if that makes the program slower. This option

7149

implies setting the @option{large-stack-frame} parameter to 100

7150

and the @option{large-stack-frame-growth} parameter to 400.

7151

7152

@item -ftree-reassoc

7153

@opindex ftree-reassoc

7154

Perform reassociation on trees. This flag is enabled by default

7155

at @option{-O} and higher.

7156

7157

@item -ftree-pre

7158

@opindex ftree-pre

7159

Perform partial redundancy elimination (PRE) on trees. This flag is

7160

enabled by default at @option{-O2} and @option{-O3}.

7161

7162

@item -ftree-partial-pre

7163

@opindex ftree-partial-pre

7164

Make partial redundancy elimination (PRE) more aggressive. This flag is

7165

enabled by default at @option{-O3}.

7166

7167

@item -ftree-forwprop

7168

@opindex ftree-forwprop

7169

Perform forward propagation on trees. This flag is enabled by default

7170

at @option{-O} and higher.

7171

7172

@item -ftree-fre

7173

@opindex ftree-fre

7174

Perform full redundancy elimination (FRE) on trees. The difference

7175

between FRE and PRE is that FRE only considers expressions

7176

that are computed on all paths leading to the redundant computation.

7177

This analysis is faster than PRE, though it exposes fewer redundancies.

7178

This flag is enabled by default at @option{-O} and higher.

7179

7180

@item -ftree-phiprop

7181

@opindex ftree-phiprop

7182

Perform hoisting of loads from conditional pointers on trees. This

7183

pass is enabled by default at @option{-O} and higher.

7184

7185

@item -fhoist-adjacent-loads

7186

@opindex fhoist-adjacent-loads

7187

Speculatively hoist loads from both branches of an if-then-else if the

7188

loads are from adjacent locations in the same structure and the target

7189

architecture has a conditional move instruction. This flag is enabled

7190

by default at @option{-O2} and higher.

7191

7192

@item -ftree-copy-prop

7193

@opindex ftree-copy-prop

7194

Perform copy propagation on trees. This pass eliminates unnecessary

7195

copy operations. This flag is enabled by default at @option{-O} and

7196

higher.

7197

7198

@item -fipa-pure-const

7199

@opindex fipa-pure-const

7200

Discover which functions are pure or constant.

7201

Enabled by default at @option{-O} and higher.

7202

7203

@item -fipa-reference

7204

@opindex fipa-reference

7205

Discover which static variables do not escape the

7206

compilation unit.

7207

Enabled by default at @option{-O} and higher.

7208

7209

@item -fipa-pta

7210

@opindex fipa-pta

7211

Perform interprocedural pointer analysis and interprocedural modification

7212

and reference analysis. This option can cause excessive memory and

7213

compile-time usage on large compilation units. It is not enabled by

7214

default at any optimization level.

7215

7216

@item -fipa-profile

7217

@opindex fipa-profile

7218

Perform interprocedural profile propagation. The functions called only from

7219

cold functions are marked as cold. Also functions executed once (such as

7220

@code{cold}, @code{noreturn}, static constructors or destructors) are identified. Cold

7221

functions and loop less parts of functions executed once are then optimized for

7222

size.

7223

Enabled by default at @option{-O} and higher.

7224

7225

@item -fipa-cp

7226

@opindex fipa-cp

7227

Perform interprocedural constant propagation.

7228

This optimization analyzes the program to determine when values passed

7229

to functions are constants and then optimizes accordingly.

7230

This optimization can substantially increase performance

7231

if the application has constants passed to functions.

7232

This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}.

7233

7234

@item -fipa-cp-clone

7235

@opindex fipa-cp-clone

7236

Perform function cloning to make interprocedural constant propagation stronger.

7237

When enabled, interprocedural constant propagation performs function cloning

7238

when externally visible function can be called with constant arguments.

7239

Because this optimization can create multiple copies of functions,

7240

it may significantly increase code size

7241

(see @option{--param ipcp-unit-growth=@var{value}}).

7242

This flag is enabled by default at @option{-O3}.

7243

7244

@item -fipa-cp-alignment

7245

@opindex -fipa-cp-alignment

7246

When enabled, this optimization propagates alignment of function

7247

parameters to support better vectorization and string operations.

7248

7249

This flag is enabled by default at @option{-O2} and @option{-Os}. It

7250

requires that @option{-fipa-cp} is enabled.

7251

7252

@item -fipa-icf

7253

@opindex fipa-icf

7254

Perform Identical Code Folding for functions and read-only variables.

7255

The optimization reduces code size and may disturb unwind stacks by replacing

7256

a function by equivalent one with a different name. The optimization works

7257

more effectively with link time optimization enabled.

7258

7259

Nevertheless the behavior is similar to Gold Linker ICF optimization, GCC ICF

7260

works on different levels and thus the optimizations are not same - there are

7261

equivalences that are found only by GCC and equivalences found only by Gold.

7262

7263

This flag is enabled by default at @option{-O2} and @option{-Os}.

7264

7265

@item -fisolate-erroneous-paths-dereference

7266

@opindex fisolate-erroneous-paths-dereference

7267

Detect paths that trigger erroneous or undefined behavior due to

7268

dereferencing a null pointer. Isolate those paths from the main control

7269

flow and turn the statement with erroneous or undefined behavior into a trap.

7270

This flag is enabled by default at @option{-O2} and higher and depends on

7271

@option{-fdelete-null-pointer-checks} also being enabled.

7272

7273

@item -fisolate-erroneous-paths-attribute

7274

@opindex fisolate-erroneous-paths-attribute

7275

Detect paths that trigger erroneous or undefined behavior due a null value

7276

being used in a way forbidden by a @code{returns_nonnull} or @code{nonnull}

7277

attribute. Isolate those paths from the main control flow and turn the

7278

statement with erroneous or undefined behavior into a trap. This is not

7279

currently enabled, but may be enabled by @option{-O2} in the future.

7280

7281

@item -ftree-sink

7282

@opindex ftree-sink

7283

Perform forward store motion on trees. This flag is

7284

enabled by default at @option{-O} and higher.

7285

7286

@item -ftree-bit-ccp

7287

@opindex ftree-bit-ccp

7288

Perform sparse conditional bit constant propagation on trees and propagate

7289

pointer alignment information.

7290

This pass only operates on local scalar variables and is enabled by default

7291

at @option{-O} and higher. It requires that @option{-ftree-ccp} is enabled.

7292

7293

@item -ftree-ccp

7294

@opindex ftree-ccp

7295

Perform sparse conditional constant propagation (CCP) on trees. This

7296

pass only operates on local scalar variables and is enabled by default

7297

at @option{-O} and higher.

7298

7299

@item -fssa-backprop

7300

@opindex fssa-backprop

7301

Propagate information about uses of a value up the definition chain

7302

in order to simplify the definitions. For example, this pass strips

7303

sign operations if the sign of a value never matters. The flag is

7304

enabled by default at @option{-O} and higher.

7305

7306

@item -fssa-phiopt

7307

@opindex fssa-phiopt

7308

Perform pattern matching on SSA PHI nodes to optimize conditional

7309

code. This pass is enabled by default at @option{-O} and higher.

7310

7311

@item -ftree-switch-conversion

7312

@opindex ftree-switch-conversion

7313

Perform conversion of simple initializations in a switch to

7314

initializations from a scalar array. This flag is enabled by default

7315

at @option{-O2} and higher.

7316

7317

@item -ftree-tail-merge

7318

@opindex ftree-tail-merge

7319

Look for identical code sequences. When found, replace one with a jump to the

7320

other. This optimization is known as tail merging or cross jumping. This flag

7321

is enabled by default at @option{-O2} and higher. The compilation time

7322

in this pass can

7323

be limited using @option{max-tail-merge-comparisons} parameter and

7324

@option{max-tail-merge-iterations} parameter.

7325

7326

@item -ftree-dce

7327

@opindex ftree-dce

7328

Perform dead code elimination (DCE) on trees. This flag is enabled by

7329

default at @option{-O} and higher.

7330

7331

@item -ftree-builtin-call-dce

7332

@opindex ftree-builtin-call-dce

7333

Perform conditional dead code elimination (DCE) for calls to built-in functions

7334

that may set @code{errno} but are otherwise side-effect free. This flag is

7335

enabled by default at @option{-O2} and higher if @option{-Os} is not also

7336

specified.

7337

7338

@item -ftree-dominator-opts

7339

@opindex ftree-dominator-opts

7340

Perform a variety of simple scalar cleanups (constant/copy

7341

propagation, redundancy elimination, range propagation and expression

7342

simplification) based on a dominator tree traversal. This also

7343

performs jump threading (to reduce jumps to jumps). This flag is

7344

enabled by default at @option{-O} and higher.

7345

7346

@item -ftree-dse

7347

@opindex ftree-dse

7348

Perform dead store elimination (DSE) on trees. A dead store is a store into

7349

a memory location that is later overwritten by another store without

7350

any intervening loads. In this case the earlier store can be deleted. This

7351

flag is enabled by default at @option{-O} and higher.

7352

7353

@item -ftree-ch

7354

@opindex ftree-ch

7355

Perform loop header copying on trees. This is beneficial since it increases

7356

effectiveness of code motion optimizations. It also saves one jump. This flag

7357

is enabled by default at @option{-O} and higher. It is not enabled

7358

for @option{-Os}, since it usually increases code size.

7359

7360

@item -ftree-loop-optimize

7361

@opindex ftree-loop-optimize

7362

Perform loop optimizations on trees. This flag is enabled by default

7363

at @option{-O} and higher.

7364

7365

@item -ftree-loop-linear

7366

@itemx -floop-interchange

7367

@itemx -floop-strip-mine

7368

@itemx -floop-block

7369

@itemx -floop-unroll-and-jam

7370

@opindex ftree-loop-linear

7371

@opindex floop-interchange

7372

@opindex floop-strip-mine

7373

@opindex floop-block

7374

@opindex floop-unroll-and-jam

7375

Perform loop nest optimizations. Same as

7376

@option{-floop-nest-optimize}. To use this code transformation, GCC has

7377

to be configured with @option{--with-isl} to enable the Graphite loop

7378

transformation infrastructure.

7379

7380

@item -fgraphite-identity

7381

@opindex fgraphite-identity

7382

Enable the identity transformation for graphite. For every SCoP we generate

7383

the polyhedral representation and transform it back to gimple. Using

7384

@option{-fgraphite-identity} we can check the costs or benefits of the

7385

GIMPLE -> GRAPHITE -> GIMPLE transformation. Some minimal optimizations

7386

are also performed by the code generator isl, like index splitting and

7387

dead code elimination in loops.

7388

7389

@item -floop-nest-optimize

7390

@opindex floop-nest-optimize

7391

Enable the isl based loop nest optimizer. This is a generic loop nest

7392

optimizer based on the Pluto optimization algorithms. It calculates a loop

7393

structure optimized for data-locality and parallelism. This option

7394

is experimental.

7395

7396

@item -floop-parallelize-all

7397

@opindex floop-parallelize-all

7398

Use the Graphite data dependence analysis to identify loops that can

7399

be parallelized. Parallelize all the loops that can be analyzed to

7400

not contain loop carried dependences without checking that it is

7401

profitable to parallelize the loops.

7402

7403

@item -ftree-coalesce-vars

7404

@opindex ftree-coalesce-vars

7405

While transforming the program out of the SSA representation, attempt to

7406

reduce copying by coalescing versions of different user-defined

7407

variables, instead of just compiler temporaries. This may severely

7408

limit the ability to debug an optimized program compiled with

7409

@option{-fno-var-tracking-assignments}. In the negated form, this flag

7410

prevents SSA coalescing of user variables. This option is enabled by

7411

default if optimization is enabled, and it does very little otherwise.

7412

7413

@item -ftree-loop-if-convert

7414

@opindex ftree-loop-if-convert

7415

Attempt to transform conditional jumps in the innermost loops to

7416

branch-less equivalents. The intent is to remove control-flow from

7417

the innermost loops in order to improve the ability of the

7418

vectorization pass to handle these loops. This is enabled by default

7419

if vectorization is enabled.

7420

7421

@item -ftree-loop-if-convert-stores

7422

@opindex ftree-loop-if-convert-stores

7423

Attempt to also if-convert conditional jumps containing memory writes.

7424

This transformation can be unsafe for multi-threaded programs as it

7425

transforms conditional memory writes into unconditional memory writes.

7426

For example,

7427

@smallexample

7428

for (i = 0; i < N; i++)

7429

if (cond)

7430

A[i] = expr;

7431

@end smallexample

7432

is transformed to

7433

@smallexample

7434

for (i = 0; i < N; i++)

7435

A[i] = cond ? expr : A[i];

7436

@end smallexample

7437

potentially producing data races.

7438

7439

@item -ftree-loop-distribution

7440

@opindex ftree-loop-distribution

7441

Perform loop distribution. This flag can improve cache performance on

7442

big loop bodies and allow further loop optimizations, like

7443

parallelization or vectorization, to take place. For example, the loop

7444

@smallexample

7445

DO I = 1, N

7446

A(I) = B(I) + C

7447

D(I) = E(I) * F

7448

ENDDO

7449

@end smallexample

7450

is transformed to

7451

@smallexample

7452

DO I = 1, N

7453

A(I) = B(I) + C

7454

ENDDO

7455

DO I = 1, N

7456

D(I) = E(I) * F

7457

ENDDO

7458

@end smallexample

7459

7460

@item -ftree-loop-distribute-patterns

7461

@opindex ftree-loop-distribute-patterns

7462

Perform loop distribution of patterns that can be code generated with

7463

calls to a library. This flag is enabled by default at @option{-O3}.

7464

7465

This pass distributes the initialization loops and generates a call to

7466

memset zero. For example, the loop

7467

@smallexample

7468

DO I = 1, N

7469

A(I) = 0

7470

B(I) = A(I) + I

7471

ENDDO

7472

@end smallexample

7473

is transformed to

7474

@smallexample

7475

DO I = 1, N

7476

A(I) = 0

7477

ENDDO

7478

DO I = 1, N

7479

B(I) = A(I) + I

7480

ENDDO

7481

@end smallexample

7482

and the initialization loop is transformed into a call to memset zero.

7483

7484

@item -ftree-loop-im

7485

@opindex ftree-loop-im

7486

Perform loop invariant motion on trees. This pass moves only invariants that

7487

are hard to handle at RTL level (function calls, operations that expand to

7488

nontrivial sequences of insns). With @option{-funswitch-loops} it also moves

7489

operands of conditions that are invariant out of the loop, so that we can use

7490

just trivial invariantness analysis in loop unswitching. The pass also includes

7491

store motion.

7492

7493

@item -ftree-loop-ivcanon

7494

@opindex ftree-loop-ivcanon

7495

Create a canonical counter for number of iterations in loops for which

7496

determining number of iterations requires complicated analysis. Later

7497

optimizations then may determine the number easily. Useful especially

7498

in connection with unrolling.

7499

7500

@item -fivopts

7501

@opindex fivopts

7502

Perform induction variable optimizations (strength reduction, induction

7503

variable merging and induction variable elimination) on trees.

7504

7505

@item -ftree-parallelize-loops=n

7506

@opindex ftree-parallelize-loops

7507

Parallelize loops, i.e., split their iteration space to run in n threads.

7508

This is only possible for loops whose iterations are independent

7509

and can be arbitrarily reordered. The optimization is only

7510

profitable on multiprocessor machines, for loops that are CPU-intensive,

7511

rather than constrained e.g.@: by memory bandwidth. This option

7512

implies @option{-pthread}, and thus is only supported on targets

7513

that have support for @option{-pthread}.

7514

7515

@item -ftree-pta

7516

@opindex ftree-pta

7517

Perform function-local points-to analysis on trees. This flag is

7518

enabled by default at @option{-O} and higher.

7519

7520

@item -ftree-sra

7521

@opindex ftree-sra

7522

Perform scalar replacement of aggregates. This pass replaces structure

7523

references with scalars to prevent committing structures to memory too

7524

early. This flag is enabled by default at @option{-O} and higher.

7525

7526

@item -ftree-ter

7527

@opindex ftree-ter

7528

Perform temporary expression replacement during the SSA->normal phase. Single

7529

use/single def temporaries are replaced at their use location with their

7530

defining expression. This results in non-GIMPLE code, but gives the expanders

7531

much more complex trees to work on resulting in better RTL generation. This is

7532

enabled by default at @option{-O} and higher.

7533

7534

@item -ftree-slsr

7535

@opindex ftree-slsr

7536

Perform straight-line strength reduction on trees. This recognizes related

7537

expressions involving multiplications and replaces them by less expensive

7538

calculations when possible. This is enabled by default at @option{-O} and

7539

higher.

7540

7541

@item -ftree-vectorize

7542

@opindex ftree-vectorize

7543

Perform vectorization on trees. This flag enables @option{-ftree-loop-vectorize}

7544

and @option{-ftree-slp-vectorize} if not explicitly specified.

7545

7546

@item -ftree-loop-vectorize

7547

@opindex ftree-loop-vectorize

7548

Perform loop vectorization on trees. This flag is enabled by default at

7549

@option{-O3} and when @option{-ftree-vectorize} is enabled.

7550

7551

@item -ftree-slp-vectorize

7552

@opindex ftree-slp-vectorize

7553

Perform basic block vectorization on trees. This flag is enabled by default at

7554

@option{-O3} and when @option{-ftree-vectorize} is enabled.

7555

7556

@item -fvect-cost-model=@var{model}

7557

@opindex fvect-cost-model

7558

Alter the cost model used for vectorization. The @var{model} argument

7559

should be one of @samp{unlimited}, @samp{dynamic} or @samp{cheap}.

7560

With the @samp{unlimited} model the vectorized code-path is assumed

7561

to be profitable while with the @samp{dynamic} model a runtime check

7562

guards the vectorized code-path to enable it only for iteration

7563

counts that will likely execute faster than when executing the original

7564

scalar loop. The @samp{cheap} model disables vectorization of

7565

loops where doing so would be cost prohibitive for example due to

7566

required runtime checks for data dependence or alignment but otherwise

7567

is equal to the @samp{dynamic} model.

7568

The default cost model depends on other optimization flags and is

7569

either @samp{dynamic} or @samp{cheap}.

7570

7571

@item -fsimd-cost-model=@var{model}

7572

@opindex fsimd-cost-model

7573

Alter the cost model used for vectorization of loops marked with the OpenMP

7574

or Cilk Plus simd directive. The @var{model} argument should be one of

7575

@samp{unlimited}, @samp{dynamic}, @samp{cheap}. All values of @var{model}

7576

have the same meaning as described in @option{-fvect-cost-model} and by

7577

default a cost model defined with @option{-fvect-cost-model} is used.

7578

7579

@item -ftree-vrp

7580

@opindex ftree-vrp

7581

Perform Value Range Propagation on trees. This is similar to the

7582

constant propagation pass, but instead of values, ranges of values are

7583

propagated. This allows the optimizers to remove unnecessary range

7584

checks like array bound checks and null pointer checks. This is

7585

enabled by default at @option{-O2} and higher. Null pointer check

7586

elimination is only done if @option{-fdelete-null-pointer-checks} is

7587

enabled.

7588

7589

@item -fsplit-paths

7590

@opindex fsplit-paths

7591

Split paths leading to loop backedges. This can improve dead code

7592

elimination and common subexpression elimination. This is enabled by

7593

default at @option{-O2} and above.

7594

7595

@item -fsplit-ivs-in-unroller

7596

@opindex fsplit-ivs-in-unroller

7597

Enables expression of values of induction variables in later iterations

7598

of the unrolled loop using the value in the first iteration. This breaks

7599

long dependency chains, thus improving efficiency of the scheduling passes.

7600

7601

A combination of @option{-fweb} and CSE is often sufficient to obtain the

7602

same effect. However, that is not reliable in cases where the loop body

7603

is more complicated than a single basic block. It also does not work at all

7604

on some architectures due to restrictions in the CSE pass.

7605

7606

This optimization is enabled by default.

7607

7608

@item -fvariable-expansion-in-unroller

7609

@opindex fvariable-expansion-in-unroller

7610

With this option, the compiler creates multiple copies of some

7611

local variables when unrolling a loop, which can result in superior code.

7612

7613

@item -fpartial-inlining

7614

@opindex fpartial-inlining

7615

Inline parts of functions. This option has any effect only

7616

when inlining itself is turned on by the @option{-finline-functions}

7617

or @option{-finline-small-functions} options.

7618

7619

Enabled at level @option{-O2}.

7620

7621

@item -fpredictive-commoning

7622

@opindex fpredictive-commoning

7623

Perform predictive commoning optimization, i.e., reusing computations

7624

(especially memory loads and stores) performed in previous

7625

iterations of loops.

7626

7627

This option is enabled at level @option{-O3}.

7628

7629

@item -fprefetch-loop-arrays

7630

@opindex fprefetch-loop-arrays

7631

If supported by the target machine, generate instructions to prefetch

7632

memory to improve the performance of loops that access large arrays.

7633

7634

This option may generate better or worse code; results are highly

7635

dependent on the structure of loops within the source code.

7636

7637

Disabled at level @option{-Os}.

7638

7639

@item -fno-peephole

7640

@itemx -fno-peephole2

7641

@opindex fno-peephole

7642

@opindex fno-peephole2

7643

Disable any machine-specific peephole optimizations. The difference

7644

between @option{-fno-peephole} and @option{-fno-peephole2} is in how they

7645

are implemented in the compiler; some targets use one, some use the

7646

other, a few use both.

7647

7648

@option{-fpeephole} is enabled by default.

7649

@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

7650

7651

@item -fno-guess-branch-probability

7652

@opindex fno-guess-branch-probability

7653

Do not guess branch probabilities using heuristics.

7654

7655

GCC uses heuristics to guess branch probabilities if they are

7656

not provided by profiling feedback (@option{-fprofile-arcs}). These

7657

heuristics are based on the control flow graph. If some branch probabilities

7658

are specified by @code{__builtin_expect}, then the heuristics are

7659

used to guess branch probabilities for the rest of the control flow graph,

7660

taking the @code{__builtin_expect} info into account. The interactions

7661

between the heuristics and @code{__builtin_expect} can be complex, and in

7662

some cases, it may be useful to disable the heuristics so that the effects

7663

of @code{__builtin_expect} are easier to understand.

7664

7665

The default is @option{-fguess-branch-probability} at levels

7666

@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

7667

7668

@item -freorder-blocks

7669

@opindex freorder-blocks

7670

Reorder basic blocks in the compiled function in order to reduce number of

7671

taken branches and improve code locality.

7672

7673

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

7674

7675

@item -freorder-blocks-algorithm=@var{algorithm}

7676

@opindex freorder-blocks-algorithm

7677

Use the specified algorithm for basic block reordering. The

7678

@var{algorithm} argument can be @samp{simple}, which does not increase

7679

code size (except sometimes due to secondary effects like alignment),

7680

or @samp{stc}, the ``software trace cache'' algorithm, which tries to

7681

put all often executed code together, minimizing the number of branches

7682

executed by making extra copies of code.

7683

7684

The default is @samp{simple} at levels @option{-O}, @option{-Os}, and

7685

@samp{stc} at levels @option{-O2}, @option{-O3}.

7686

7687

@item -freorder-blocks-and-partition

7688

@opindex freorder-blocks-and-partition

7689

In addition to reordering basic blocks in the compiled function, in order

7690

to reduce number of taken branches, partitions hot and cold basic blocks

7691

into separate sections of the assembly and @file{.o} files, to improve

7692

paging and cache locality performance.

7693

7694

This optimization is automatically turned off in the presence of

7695

exception handling, for linkonce sections, for functions with a user-defined

7696

section attribute and on any architecture that does not support named

7697

sections.

7698

7699

Enabled for x86 at levels @option{-O2}, @option{-O3}.

7700

7701

@item -freorder-functions

7702

@opindex freorder-functions

7703

Reorder functions in the object file in order to

7704

improve code locality. This is implemented by using special

7705

subsections @code{.text.hot} for most frequently executed functions and

7706

@code{.text.unlikely} for unlikely executed functions. Reordering is done by

7707

the linker so object file format must support named sections and linker must

7708

place them in a reasonable way.

7709

7710

Also profile feedback must be available to make this option effective. See

7711

@option{-fprofile-arcs} for details.

7712

7713

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

7714

7715

@item -fstrict-aliasing

7716

@opindex fstrict-aliasing

7717

Allow the compiler to assume the strictest aliasing rules applicable to

7718

the language being compiled. For C (and C++), this activates

7719

optimizations based on the type of expressions. In particular, an

7720

object of one type is assumed never to reside at the same address as an

7721

object of a different type, unless the types are almost the same. For

7722

example, an @code{unsigned int} can alias an @code{int}, but not a

7723

@code{void*} or a @code{double}. A character type may alias any other

7724

type.

7725

7726

@anchor{Type-punning}Pay special attention to code like this:

7727

@smallexample

7728

union a_union @{

7729

int i;

7730

double d;

7731

@};

7732

7733

int f() @{

7734

union a_union t;

7735

t.d = 3.0;

7736

return t.i;

7737

@}

7738

@end smallexample

7739

The practice of reading from a different union member than the one most

7740

recently written to (called ``type-punning'') is common. Even with

7741

@option{-fstrict-aliasing}, type-punning is allowed, provided the memory

7742

is accessed through the union type. So, the code above works as

7743

expected. @xref{Structures unions enumerations and bit-fields

7744

implementation}. However, this code might not:

7745

@smallexample

7746

int f() @{

7747

union a_union t;

7748

int* ip;

7749

t.d = 3.0;

7750

ip = &t.i;

7751

return *ip;

7752

@}

7753

@end smallexample

7754

7755

Similarly, access by taking the address, casting the resulting pointer

7756

and dereferencing the result has undefined behavior, even if the cast

7757

uses a union type, e.g.:

7758

@smallexample

7759

int f() @{

7760

double d = 3.0;

7761

return ((union a_union *) &d)->i;

7762

@}

7763

@end smallexample

7764

7765

The @option{-fstrict-aliasing} option is enabled at levels

7766

@option{-O2}, @option{-O3}, @option{-Os}.

7767

7768

@item -fstrict-overflow

7769

@opindex fstrict-overflow

7770

Allow the compiler to assume strict signed overflow rules, depending

7771

on the language being compiled. For C (and C++) this means that

7772

overflow when doing arithmetic with signed numbers is undefined, which

7773

means that the compiler may assume that it does not happen. This

7774

permits various optimizations. For example, the compiler assumes

7775

that an expression like @code{i + 10 > i} is always true for

7776

signed @code{i}. This assumption is only valid if signed overflow is

7777

undefined, as the expression is false if @code{i + 10} overflows when

7778

using twos complement arithmetic. When this option is in effect any

7779

attempt to determine whether an operation on signed numbers

7780

overflows must be written carefully to not actually involve overflow.

7781

7782

This option also allows the compiler to assume strict pointer

7783

semantics: given a pointer to an object, if adding an offset to that

7784

pointer does not produce a pointer to the same object, the addition is

7785

undefined. This permits the compiler to conclude that @code{p + u >

7786

p} is always true for a pointer @code{p} and unsigned integer

7787

@code{u}. This assumption is only valid because pointer wraparound is

7788

undefined, as the expression is false if @code{p + u} overflows using

7789

twos complement arithmetic.

7790

7791

See also the @option{-fwrapv} option. Using @option{-fwrapv} means

7792

that integer signed overflow is fully defined: it wraps. When

7793

@option{-fwrapv} is used, there is no difference between

7794

@option{-fstrict-overflow} and @option{-fno-strict-overflow} for

7795

integers. With @option{-fwrapv} certain types of overflow are

7796

permitted. For example, if the compiler gets an overflow when doing

7797

arithmetic on constants, the overflowed value can still be used with

7798

@option{-fwrapv}, but not otherwise.

7799

7800

The @option{-fstrict-overflow} option is enabled at levels

7801

@option{-O2}, @option{-O3}, @option{-Os}.

7802

7803

@item -falign-functions

7804

@itemx -falign-functions=@var{n}

7805

@opindex falign-functions

7806

Align the start of functions to the next power-of-two greater than

7807

@var{n}, skipping up to @var{n} bytes. For instance,

7808

@option{-falign-functions=32} aligns functions to the next 32-byte

7809

boundary, but @option{-falign-functions=24} aligns to the next

7810

32-byte boundary only if this can be done by skipping 23 bytes or less.

7811

7812

@option{-fno-align-functions} and @option{-falign-functions=1} are

7813

equivalent and mean that functions are not aligned.

7814

7815

Some assemblers only support this flag when @var{n} is a power of two;

7816

in that case, it is rounded up.

7817

7818

If @var{n} is not specified or is zero, use a machine-dependent default.

7819

7820

Enabled at levels @option{-O2}, @option{-O3}.

7821

7822

@item -falign-labels

7823

@itemx -falign-labels=@var{n}

7824

@opindex falign-labels

7825

Align all branch targets to a power-of-two boundary, skipping up to

7826

@var{n} bytes like @option{-falign-functions}. This option can easily

7827

make code slower, because it must insert dummy operations for when the

7828

branch target is reached in the usual flow of the code.

7829

7830

@option{-fno-align-labels} and @option{-falign-labels=1} are

7831

equivalent and mean that labels are not aligned.

7832

7833

If @option{-falign-loops} or @option{-falign-jumps} are applicable and

7834

are greater than this value, then their values are used instead.

7835

7836

If @var{n} is not specified or is zero, use a machine-dependent default

7837

which is very likely to be @samp{1}, meaning no alignment.

7838

7839

Enabled at levels @option{-O2}, @option{-O3}.

7840

7841

@item -falign-loops

7842

@itemx -falign-loops=@var{n}

7843

@opindex falign-loops

7844

Align loops to a power-of-two boundary, skipping up to @var{n} bytes

7845

like @option{-falign-functions}. If the loops are

7846

executed many times, this makes up for any execution of the dummy

7847

operations.

7848

7849

@option{-fno-align-loops} and @option{-falign-loops=1} are

7850

equivalent and mean that loops are not aligned.

7851

7852

If @var{n} is not specified or is zero, use a machine-dependent default.

7853

7854

Enabled at levels @option{-O2}, @option{-O3}.

7855

7856

@item -falign-jumps

7857

@itemx -falign-jumps=@var{n}

7858

@opindex falign-jumps

7859

Align branch targets to a power-of-two boundary, for branch targets

7860

where the targets can only be reached by jumping, skipping up to @var{n}

7861

bytes like @option{-falign-functions}. In this case, no dummy operations

7862

need be executed.

7863

7864

@option{-fno-align-jumps} and @option{-falign-jumps=1} are

7865

equivalent and mean that loops are not aligned.

7866

7867

If @var{n} is not specified or is zero, use a machine-dependent default.

7868

7869

Enabled at levels @option{-O2}, @option{-O3}.

7870

7871

@item -funit-at-a-time

7872

@opindex funit-at-a-time

7873

This option is left for compatibility reasons. @option{-funit-at-a-time}

7874

has no effect, while @option{-fno-unit-at-a-time} implies

7875

@option{-fno-toplevel-reorder} and @option{-fno-section-anchors}.

7876

7877

Enabled by default.

7878

7879

@item -fno-toplevel-reorder

7880

@opindex fno-toplevel-reorder

7881

Do not reorder top-level functions, variables, and @code{asm}

7882

statements. Output them in the same order that they appear in the

7883

input file. When this option is used, unreferenced static variables

7884

are not removed. This option is intended to support existing code

7885

that relies on a particular ordering. For new code, it is better to

7886

use attributes when possible.

7887

7888

Enabled at level @option{-O0}. When disabled explicitly, it also implies

7889

@option{-fno-section-anchors}, which is otherwise enabled at @option{-O0} on some

7890

targets.

7891

7892

@item -fweb

7893

@opindex fweb

7894

Constructs webs as commonly used for register allocation purposes and assign

7895

each web individual pseudo register. This allows the register allocation pass

7896

to operate on pseudos directly, but also strengthens several other optimization

7897

passes, such as CSE, loop optimizer and trivial dead code remover. It can,

7898

however, make debugging impossible, since variables no longer stay in a

7899

``home register''.

7900

7901

Enabled by default with @option{-funroll-loops}.

7902

7903

@item -fwhole-program

7904

@opindex fwhole-program

7905

Assume that the current compilation unit represents the whole program being

7906

compiled. All public functions and variables with the exception of @code{main}

7907

and those merged by attribute @code{externally_visible} become static functions

7908

and in effect are optimized more aggressively by interprocedural optimizers.

7909

7910

This option should not be used in combination with @option{-flto}.

7911

Instead relying on a linker plugin should provide safer and more precise

7912

information.

7913

7914

@item -flto[=@var{n}]

7915

@opindex flto

7916

This option runs the standard link-time optimizer. When invoked

7917

with source code, it generates GIMPLE (one of GCC's internal

7918

representations) and writes it to special ELF sections in the object

7919

file. When the object files are linked together, all the function

7920

bodies are read from these ELF sections and instantiated as if they

7921

had been part of the same translation unit.

7922

7923

To use the link-time optimizer, @option{-flto} and optimization

7924

options should be specified at compile time and during the final link.

7925

It is recommended that you compile all the files participating in the

7926

same link with the same options and also specify those options at

7927

link time.

7928

For example:

7929

7930

@smallexample

7931

gcc -c -O2 -flto foo.c

7932

gcc -c -O2 -flto bar.c

7933

gcc -o myprog -flto -O2 foo.o bar.o

7934

@end smallexample

7935

7936

The first two invocations to GCC save a bytecode representation

7937

of GIMPLE into special ELF sections inside @file{foo.o} and

7938

@file{bar.o}. The final invocation reads the GIMPLE bytecode from

7939

@file{foo.o} and @file{bar.o}, merges the two files into a single

7940

internal image, and compiles the result as usual. Since both

7941

@file{foo.o} and @file{bar.o} are merged into a single image, this

7942

causes all the interprocedural analyses and optimizations in GCC to

7943

work across the two files as if they were a single one. This means,

7944

for example, that the inliner is able to inline functions in

7945

@file{bar.o} into functions in @file{foo.o} and vice-versa.

7946

7947

Another (simpler) way to enable link-time optimization is:

7948

7949

@smallexample

7950

gcc -o myprog -flto -O2 foo.c bar.c

7951

@end smallexample

7952

7953

The above generates bytecode for @file{foo.c} and @file{bar.c},

7954

merges them together into a single GIMPLE representation and optimizes

7955

them as usual to produce @file{myprog}.

7956

7957

The only important thing to keep in mind is that to enable link-time

7958

optimizations you need to use the GCC driver to perform the link step.

7959

GCC then automatically performs link-time optimization if any of the

7960

objects involved were compiled with the @option{-flto} command-line option.

7961

You generally

7962

should specify the optimization options to be used for link-time

7963

optimization though GCC tries to be clever at guessing an

7964

optimization level to use from the options used at compile time

7965

if you fail to specify one at link time. You can always override

7966

the automatic decision to do link-time optimization at link time

7967

by passing @option{-fno-lto} to the link command.

7968

7969

To make whole program optimization effective, it is necessary to make

7970

certain whole program assumptions. The compiler needs to know

7971

what functions and variables can be accessed by libraries and runtime

7972

outside of the link-time optimized unit. When supported by the linker,

7973

the linker plugin (see @option{-fuse-linker-plugin}) passes information

7974

to the compiler about used and externally visible symbols. When

7975

the linker plugin is not available, @option{-fwhole-program} should be

7976

used to allow the compiler to make these assumptions, which leads

7977

to more aggressive optimization decisions.

7978

7979

When @option{-fuse-linker-plugin} is not enabled, when a file is

7980

compiled with @option{-flto}, the generated object file is larger than

7981

a regular object file because it contains GIMPLE bytecodes and the usual

7982

final code (see @option{-ffat-lto-objects}. This means that

7983

object files with LTO information can be linked as normal object

7984

files; if @option{-fno-lto} is passed to the linker, no

7985

interprocedural optimizations are applied. Note that when

7986

@option{-fno-fat-lto-objects} is enabled the compile stage is faster

7987

but you cannot perform a regular, non-LTO link on them.

7988

7989

Additionally, the optimization flags used to compile individual files

7990

are not necessarily related to those used at link time. For instance,

7991

7992

@smallexample

7993

gcc -c -O0 -ffat-lto-objects -flto foo.c

7994

gcc -c -O0 -ffat-lto-objects -flto bar.c

7995

gcc -o myprog -O3 foo.o bar.o

7996

@end smallexample

7997

7998

This produces individual object files with unoptimized assembler

7999

code, but the resulting binary @file{myprog} is optimized at

8000

@option{-O3}. If, instead, the final binary is generated with

8001

@option{-fno-lto}, then @file{myprog} is not optimized.

8002

8003

When producing the final binary, GCC only

8004

applies link-time optimizations to those files that contain bytecode.

8005

Therefore, you can mix and match object files and libraries with

8006

GIMPLE bytecodes and final object code. GCC automatically selects

8007

which files to optimize in LTO mode and which files to link without

8008

further processing.

8009

8010

There are some code generation flags preserved by GCC when

8011

generating bytecodes, as they need to be used during the final link

8012

stage. Generally options specified at link time override those

8013

specified at compile time.

8014

8015

If you do not specify an optimization level option @option{-O} at

8016

link time, then GCC uses the highest optimization level

8017

used when compiling the object files.

8018

8019

Currently, the following options and their settings are taken from

8020

the first object file that explicitly specifies them:

8021

@option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon},

8022

@option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm}

8023

and all the @option{-m} target flags.

8024

8025

Certain ABI-changing flags are required to match in all compilation units,

8026

and trying to override this at link time with a conflicting value

8027

is ignored. This includes options such as @option{-freg-struct-return}

8028

and @option{-fpcc-struct-return}.

8029

8030

Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow},

8031

@option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing}

8032

are passed through to the link stage and merged conservatively for

8033

conflicting translation units. Specifically

8034

@option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take

8035

precedence; and for example @option{-ffp-contract=off} takes precedence

8036

over @option{-ffp-contract=fast}. You can override them at link time.

8037

8038

If LTO encounters objects with C linkage declared with incompatible

8039

types in separate translation units to be linked together (undefined

8040

behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be

8041

issued. The behavior is still undefined at run time. Similar

8042

diagnostics may be raised for other languages.

8043

8044

Another feature of LTO is that it is possible to apply interprocedural

8045

optimizations on files written in different languages:

8046

8047

@smallexample

8048

gcc -c -flto foo.c

8049

g++ -c -flto bar.cc

8050

gfortran -c -flto baz.f90

8051

g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran

8052

@end smallexample

8053

8054

Notice that the final link is done with @command{g++} to get the C++

8055

runtime libraries and @option{-lgfortran} is added to get the Fortran

8056

runtime libraries. In general, when mixing languages in LTO mode, you

8057

should use the same link command options as when mixing languages in a

8058

regular (non-LTO) compilation.

8059

8060

If object files containing GIMPLE bytecode are stored in a library archive, say

8061

@file{libfoo.a}, it is possible to extract and use them in an LTO link if you

8062

are using a linker with plugin support. To create static libraries suitable

8063

for LTO, use @command{gcc-ar} and @command{gcc-ranlib} instead of @command{ar}

8064

and @command{ranlib};

8065

to show the symbols of object files with GIMPLE bytecode, use

8066

@command{gcc-nm}. Those commands require that @command{ar}, @command{ranlib}

8067

and @command{nm} have been compiled with plugin support. At link time, use the the

8068

flag @option{-fuse-linker-plugin} to ensure that the library participates in

8069

the LTO optimization process:

8070

8071

@smallexample

8072

gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo

8073

@end smallexample

8074

8075

With the linker plugin enabled, the linker extracts the needed

8076

GIMPLE files from @file{libfoo.a} and passes them on to the running GCC

8077

to make them part of the aggregated GIMPLE image to be optimized.

8078

8079

If you are not using a linker with plugin support and/or do not

8080

enable the linker plugin, then the objects inside @file{libfoo.a}

8081

are extracted and linked as usual, but they do not participate

8082

in the LTO optimization process. In order to make a static library suitable

8083

for both LTO optimization and usual linkage, compile its object files with

8084

@option{-flto} @option{-ffat-lto-objects}.

8085

8086

Link-time optimizations do not require the presence of the whole program to

8087

operate. If the program does not require any symbols to be exported, it is

8088

possible to combine @option{-flto} and @option{-fwhole-program} to allow

8089

the interprocedural optimizers to use more aggressive assumptions which may

8090

lead to improved optimization opportunities.

8091

Use of @option{-fwhole-program} is not needed when linker plugin is

8092

active (see @option{-fuse-linker-plugin}).

8093

8094

The current implementation of LTO makes no

8095

attempt to generate bytecode that is portable between different

8096

types of hosts. The bytecode files are versioned and there is a

8097

strict version check, so bytecode files generated in one version of

8098

GCC do not work with an older or newer version of GCC.

8099

8100

Link-time optimization does not work well with generation of debugging

8101

information. Combining @option{-flto} with

8102

@option{-g} is currently experimental and expected to produce unexpected

8103

results.

8104

8105

If you specify the optional @var{n}, the optimization and code

8106

generation done at link time is executed in parallel using @var{n}

8107

parallel jobs by utilizing an installed @command{make} program. The

8108

environment variable @env{MAKE} may be used to override the program

8109

used. The default value for @var{n} is 1.

8110

8111

You can also specify @option{-flto=jobserver} to use GNU make's

8112

job server mode to determine the number of parallel jobs. This

8113

is useful when the Makefile calling GCC is already executing in parallel.

8114

You must prepend a @samp{+} to the command recipe in the parent Makefile

8115

for this to work. This option likely only works if @env{MAKE} is

8116

GNU make.

8117

8118

@item -flto-partition=@var{alg}

8119

@opindex flto-partition

8120

Specify the partitioning algorithm used by the link-time optimizer.

8121

The value is either @samp{1to1} to specify a partitioning mirroring

8122

the original source files or @samp{balanced} to specify partitioning

8123

into equally sized chunks (whenever possible) or @samp{max} to create

8124

new partition for every symbol where possible. Specifying @samp{none}

8125

as an algorithm disables partitioning and streaming completely.

8126

The default value is @samp{balanced}. While @samp{1to1} can be used

8127

as an workaround for various code ordering issues, the @samp{max}

8128

partitioning is intended for internal testing only.

8129

The value @samp{one} specifies that exactly one partition should be

8130

used while the value @samp{none} bypasses partitioning and executes

8131

the link-time optimization step directly from the WPA phase.

8132

8133

@item -flto-odr-type-merging

8134

@opindex flto-odr-type-merging

8135

Enable streaming of mangled types names of C++ types and their unification

8136

at link time. This increases size of LTO object files, but enables

8137

diagnostics about One Definition Rule violations.

8138

8139

@item -flto-compression-level=@var{n}

8140

@opindex flto-compression-level

8141

This option specifies the level of compression used for intermediate

8142

language written to LTO object files, and is only meaningful in

8143

conjunction with LTO mode (@option{-flto}). Valid

8144

values are 0 (no compression) to 9 (maximum compression). Values

8145

outside this range are clamped to either 0 or 9. If the option is not

8146

given, a default balanced compression setting is used.

8147

8148

@item -fuse-linker-plugin

8149

@opindex fuse-linker-plugin

8150

Enables the use of a linker plugin during link-time optimization. This

8151

option relies on plugin support in the linker, which is available in gold

8152

or in GNU ld 2.21 or newer.

8153

8154

This option enables the extraction of object files with GIMPLE bytecode out

8155

of library archives. This improves the quality of optimization by exposing

8156

more code to the link-time optimizer. This information specifies what

8157

symbols can be accessed externally (by non-LTO object or during dynamic

8158

linking). Resulting code quality improvements on binaries (and shared

8159

libraries that use hidden visibility) are similar to @option{-fwhole-program}.

8160

See @option{-flto} for a description of the effect of this flag and how to

8161

use it.

8162

8163

This option is enabled by default when LTO support in GCC is enabled

8164

and GCC was configured for use with

8165

a linker supporting plugins (GNU ld 2.21 or newer or gold).

8166

8167

@item -ffat-lto-objects

8168

@opindex ffat-lto-objects

8169

Fat LTO objects are object files that contain both the intermediate language

8170

and the object code. This makes them usable for both LTO linking and normal

8171

linking. This option is effective only when compiling with @option{-flto}

8172

and is ignored at link time.

8173

8174

@option{-fno-fat-lto-objects} improves compilation time over plain LTO, but

8175

requires the complete toolchain to be aware of LTO. It requires a linker with

8176

linker plugin support for basic functionality. Additionally,

8177

@command{nm}, @command{ar} and @command{ranlib}

8178

need to support linker plugins to allow a full-featured build environment

8179

(capable of building static libraries etc). GCC provides the @command{gcc-ar},

8180

@command{gcc-nm}, @command{gcc-ranlib} wrappers to pass the right options

8181

to these tools. With non fat LTO makefiles need to be modified to use them.

8182

8183

The default is @option{-fno-fat-lto-objects} on targets with linker plugin

8184

support.

8185

8186

@item -fcompare-elim

8187

@opindex fcompare-elim

8188

After register allocation and post-register allocation instruction splitting,

8189

identify arithmetic instructions that compute processor flags similar to a

8190

comparison operation based on that arithmetic. If possible, eliminate the

8191

explicit comparison operation.

8192

8193

This pass only applies to certain targets that cannot explicitly represent

8194

the comparison operation before register allocation is complete.

8195

8196

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

8197

8198

@item -fcprop-registers

8199

@opindex fcprop-registers

8200

After register allocation and post-register allocation instruction splitting,

8201

perform a copy-propagation pass to try to reduce scheduling dependencies

8202

and occasionally eliminate the copy.

8203

8204

Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.

8205

8206

@item -fprofile-correction

8207

@opindex fprofile-correction

8208

Profiles collected using an instrumented binary for multi-threaded programs may

8209

be inconsistent due to missed counter updates. When this option is specified,

8210

GCC uses heuristics to correct or smooth out such inconsistencies. By

8211

default, GCC emits an error message when an inconsistent profile is detected.

8212

8213

@item -fprofile-use

8214

@itemx -fprofile-use=@var{path}

8215

@opindex fprofile-use

8216

Enable profile feedback-directed optimizations,

8217

and the following optimizations

8218

which are generally profitable only with profile feedback available:

8219

@option{-fbranch-probabilities}, @option{-fvpt},

8220

@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer},

8221

@option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}.

8222

8223

Before you can use this option, you must first generate profiling information.

8224

@xref{Optimize Options}, for information about the @option{-fprofile-generate}

8225

option.

8226

8227

By default, GCC emits an error message if the feedback profiles do not

8228

match the source code. This error can be turned into a warning by using

8229

@option{-Wcoverage-mismatch}. Note this may result in poorly optimized

8230

code.

8231

8232

If @var{path} is specified, GCC looks at the @var{path} to find

8233

the profile feedback data files. See @option{-fprofile-dir}.

8234

8235

@item -fauto-profile

8236

@itemx -fauto-profile=@var{path}

8237

@opindex fauto-profile

8238

Enable sampling-based feedback-directed optimizations,

8239

and the following optimizations

8240

which are generally profitable only with profile feedback available:

8241

@option{-fbranch-probabilities}, @option{-fvpt},

8242

@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer},

8243

@option{-ftree-vectorize},

8244

@option{-finline-functions}, @option{-fipa-cp}, @option{-fipa-cp-clone},

8245

@option{-fpredictive-commoning}, @option{-funswitch-loops},

8246

@option{-fgcse-after-reload}, and @option{-ftree-loop-distribute-patterns}.

8247

8248

@var{path} is the name of a file containing AutoFDO profile information.

8249

If omitted, it defaults to @file{fbdata.afdo} in the current directory.

8250

8251

Producing an AutoFDO profile data file requires running your program

8252

with the @command{perf} utility on a supported GNU/Linux target system.

8253

For more information, see @uref{https://perf.wiki.kernel.org/}.

8254

8255

E.g.

8256

@smallexample

8257

perf record -e br_inst_retired:near_taken -b -o perf.data \

8258

-- your_program

8259

@end smallexample

8260

8261

Then use the @command{create_gcov} tool to convert the raw profile data

8262

to a format that can be used by GCC.@ You must also supply the

8263

unstripped binary for your program to this tool.

8264

See @uref{https://github.com/google/autofdo}.

8265

8266

E.g.

8267

@smallexample

8268

create_gcov --binary=your_program.unstripped --profile=perf.data \

8269

--gcov=profile.afdo

8270

@end smallexample

8271

@end table

8272

8273

The following options control compiler behavior regarding floating-point

8274

arithmetic. These options trade off between speed and

8275

correctness. All must be specifically enabled.

8276

8277

@table @gcctabopt

8278

@item -ffloat-store

8279

@opindex ffloat-store

8280

Do not store floating-point variables in registers, and inhibit other

8281

options that might change whether a floating-point value is taken from a

8282

register or memory.

8283

8284

@cindex floating-point precision

8285

This option prevents undesirable excess precision on machines such as

8286

the 68000 where the floating registers (of the 68881) keep more

8287

precision than a @code{double} is supposed to have. Similarly for the

8288

x86 architecture. For most programs, the excess precision does only

8289

good, but a few programs rely on the precise definition of IEEE floating

8290

point. Use @option{-ffloat-store} for such programs, after modifying

8291

them to store all pertinent intermediate computations into variables.

8292

8293

@item -fexcess-precision=@var{style}

8294

@opindex fexcess-precision

8295

This option allows further control over excess precision on machines

8296

where floating-point registers have more precision than the IEEE

8297

@code{float} and @code{double} types and the processor does not

8298

support operations rounding to those types. By default,

8299

@option{-fexcess-precision=fast} is in effect; this means that

8300

operations are carried out in the precision of the registers and that

8301

it is unpredictable when rounding to the types specified in the source

8302

code takes place. When compiling C, if

8303

@option{-fexcess-precision=standard} is specified then excess

8304

precision follows the rules specified in ISO C99; in particular,

8305

both casts and assignments cause values to be rounded to their

8306

semantic types (whereas @option{-ffloat-store} only affects

8307

assignments). This option is enabled by default for C if a strict

8308

conformance option such as @option{-std=c99} is used.

8309

8310

@opindex mfpmath

8311

@option{-fexcess-precision=standard} is not implemented for languages

8312

other than C, and has no effect if

8313

@option{-funsafe-math-optimizations} or @option{-ffast-math} is

8314

specified. On the x86, it also has no effect if @option{-mfpmath=sse}

8315

or @option{-mfpmath=sse+387} is specified; in the former case, IEEE

8316

semantics apply without excess precision, and in the latter, rounding

8317

is unpredictable.

8318

8319

@item -ffast-math

8320

@opindex ffast-math

8321

Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations},

8322

@option{-ffinite-math-only}, @option{-fno-rounding-math},

8323

@option{-fno-signaling-nans} and @option{-fcx-limited-range}.

8324

8325

This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.

8326

8327

This option is not turned on by any @option{-O} option besides

8328

@option{-Ofast} since it can result in incorrect output for programs

8329

that depend on an exact implementation of IEEE or ISO rules/specifications

8330

for math functions. It may, however, yield faster code for programs

8331

that do not require the guarantees of these specifications.

8332

8333

@item -fno-math-errno

8334

@opindex fno-math-errno

8335

Do not set @code{errno} after calling math functions that are executed

8336

with a single instruction, e.g., @code{sqrt}. A program that relies on

8337

IEEE exceptions for math error handling may want to use this flag

8338

for speed while maintaining IEEE arithmetic compatibility.

8339

8340

This option is not turned on by any @option{-O} option since

8341

it can result in incorrect output for programs that depend on

8342

an exact implementation of IEEE or ISO rules/specifications for

8343

math functions. It may, however, yield faster code for programs

8344

that do not require the guarantees of these specifications.

8345

8346

The default is @option{-fmath-errno}.

8347

8348

On Darwin systems, the math library never sets @code{errno}. There is

8349

therefore no reason for the compiler to consider the possibility that

8350

it might, and @option{-fno-math-errno} is the default.

8351

8352

@item -funsafe-math-optimizations

8353

@opindex funsafe-math-optimizations

8354

8355

Allow optimizations for floating-point arithmetic that (a) assume

8356

that arguments and results are valid and (b) may violate IEEE or

8357

ANSI standards. When used at link time, it may include libraries

8358

or startup files that change the default FPU control word or other

8359

similar optimizations.

8360

8361

This option is not turned on by any @option{-O} option since

8362

it can result in incorrect output for programs that depend on

8363

an exact implementation of IEEE or ISO rules/specifications for

8364

math functions. It may, however, yield faster code for programs

8365

that do not require the guarantees of these specifications.

8366

Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math},

8367

@option{-fassociative-math} and @option{-freciprocal-math}.

8368

8369

The default is @option{-fno-unsafe-math-optimizations}.

8370

8371

@item -fassociative-math

8372

@opindex fassociative-math

8373

8374

Allow re-association of operands in series of floating-point operations.

8375

This violates the ISO C and C++ language standard by possibly changing

8376

computation result. NOTE: re-ordering may change the sign of zero as

8377

well as ignore NaNs and inhibit or create underflow or overflow (and

8378

thus cannot be used on code that relies on rounding behavior like

8379

@code{(x + 2**52) - 2**52}. May also reorder floating-point comparisons

8380

and thus may not be used when ordered comparisons are required.

8381

This option requires that both @option{-fno-signed-zeros} and

8382

@option{-fno-trapping-math} be in effect. Moreover, it doesn't make

8383

much sense with @option{-frounding-math}. For Fortran the option

8384

is automatically enabled when both @option{-fno-signed-zeros} and

8385

@option{-fno-trapping-math} are in effect.

8386

8387

The default is @option{-fno-associative-math}.

8388

8389

@item -freciprocal-math

8390

@opindex freciprocal-math

8391

8392

Allow the reciprocal of a value to be used instead of dividing by

8393

the value if this enables optimizations. For example @code{x / y}

8394

can be replaced with @code{x * (1/y)}, which is useful if @code{(1/y)}

8395

is subject to common subexpression elimination. Note that this loses

8396

precision and increases the number of flops operating on the value.

8397

8398

The default is @option{-fno-reciprocal-math}.

8399

8400

@item -ffinite-math-only

8401

@opindex ffinite-math-only

8402

Allow optimizations for floating-point arithmetic that assume

8403

that arguments and results are not NaNs or +-Infs.

8404

8405

This option is not turned on by any @option{-O} option since

8406

it can result in incorrect output for programs that depend on

8407

an exact implementation of IEEE or ISO rules/specifications for

8408

math functions. It may, however, yield faster code for programs

8409

that do not require the guarantees of these specifications.

8410

8411

The default is @option{-fno-finite-math-only}.

8412

8413

@item -fno-signed-zeros

8414

@opindex fno-signed-zeros

8415

Allow optimizations for floating-point arithmetic that ignore the

8416

signedness of zero. IEEE arithmetic specifies the behavior of

8417

distinct +0.0 and @minus{}0.0 values, which then prohibits simplification

8418

of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).

8419

This option implies that the sign of a zero result isn't significant.

8420

8421

The default is @option{-fsigned-zeros}.

8422

8423

@item -fno-trapping-math

8424

@opindex fno-trapping-math

8425

Compile code assuming that floating-point operations cannot generate

8426

user-visible traps. These traps include division by zero, overflow,

8427

underflow, inexact result and invalid operation. This option requires

8428

that @option{-fno-signaling-nans} be in effect. Setting this option may

8429

allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example.

8430

8431

This option should never be turned on by any @option{-O} option since

8432

it can result in incorrect output for programs that depend on

8433

an exact implementation of IEEE or ISO rules/specifications for

8434

math functions.

8435

8436

The default is @option{-ftrapping-math}.

8437

8438

@item -frounding-math

8439

@opindex frounding-math

8440

Disable transformations and optimizations that assume default floating-point

8441

rounding behavior. This is round-to-zero for all floating point

8442

to integer conversions, and round-to-nearest for all other arithmetic

8443

truncations. This option should be specified for programs that change

8444

the FP rounding mode dynamically, or that may be executed with a

8445

non-default rounding mode. This option disables constant folding of

8446

floating-point expressions at compile time (which may be affected by

8447

rounding mode) and arithmetic transformations that are unsafe in the

8448

presence of sign-dependent rounding modes.

8449

8450

The default is @option{-fno-rounding-math}.

8451

8452

This option is experimental and does not currently guarantee to

8453

disable all GCC optimizations that are affected by rounding mode.

8454

Future versions of GCC may provide finer control of this setting

8455

using C99's @code{FENV_ACCESS} pragma. This command-line option

8456

will be used to specify the default state for @code{FENV_ACCESS}.

8457

8458

@item -fsignaling-nans

8459

@opindex fsignaling-nans

8460

Compile code assuming that IEEE signaling NaNs may generate user-visible

8461

traps during floating-point operations. Setting this option disables

8462

optimizations that may change the number of exceptions visible with

8463

signaling NaNs. This option implies @option{-ftrapping-math}.

8464

8465

This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to

8466

be defined.

8467

8468

The default is @option{-fno-signaling-nans}.

8469

8470

This option is experimental and does not currently guarantee to

8471

disable all GCC optimizations that affect signaling NaN behavior.

8472

8473

@item -fsingle-precision-constant

8474

@opindex fsingle-precision-constant

8475

Treat floating-point constants as single precision instead of

8476

implicitly converting them to double-precision constants.

8477

8478

@item -fcx-limited-range

8479

@opindex fcx-limited-range

8480

When enabled, this option states that a range reduction step is not

8481

needed when performing complex division. Also, there is no checking

8482

whether the result of a complex multiplication or division is @code{NaN

8483

+ I*NaN}, with an attempt to rescue the situation in that case. The

8484

default is @option{-fno-cx-limited-range}, but is enabled by

8485

@option{-ffast-math}.

8486

8487

This option controls the default setting of the ISO C99

8488

@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to

8489

all languages.

8490

8491

@item -fcx-fortran-rules

8492

@opindex fcx-fortran-rules

8493

Complex multiplication and division follow Fortran rules. Range

8494

reduction is done as part of complex division, but there is no checking

8495

whether the result of a complex multiplication or division is @code{NaN

8496

+ I*NaN}, with an attempt to rescue the situation in that case.

8497

8498

The default is @option{-fno-cx-fortran-rules}.

8499

8500

@end table

8501

8502

The following options control optimizations that may improve

8503

performance, but are not enabled by any @option{-O} options. This

8504

section includes experimental options that may produce broken code.

8505

8506

@table @gcctabopt

8507

@item -fbranch-probabilities

8508

@opindex fbranch-probabilities

8509

After running a program compiled with @option{-fprofile-arcs}

8510

(@pxref{Instrumentation Options}),

8511

you can compile it a second time using

8512

@option{-fbranch-probabilities}, to improve optimizations based on

8513

the number of times each branch was taken. When a program

8514

compiled with @option{-fprofile-arcs} exits, it saves arc execution

8515

counts to a file called @file{@var{sourcename}.gcda} for each source

8516

file. The information in this data file is very dependent on the

8517

structure of the generated code, so you must use the same source code

8518

and the same optimization options for both compilations.

8519

8520

With @option{-fbranch-probabilities}, GCC puts a

8521

@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.

8522

These can be used to improve optimization. Currently, they are only

8523

used in one place: in @file{reorg.c}, instead of guessing which path a

8524

branch is most likely to take, the @samp{REG_BR_PROB} values are used to

8525

exactly determine which path is taken more often.

8526

8527

@item -fprofile-values

8528

@opindex fprofile-values

8529

If combined with @option{-fprofile-arcs}, it adds code so that some

8530

data about values of expressions in the program is gathered.

8531

8532

With @option{-fbranch-probabilities}, it reads back the data gathered

8533

from profiling values of expressions for usage in optimizations.

8534

8535

Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.

8536

8537

@item -fprofile-reorder-functions

8538

@opindex fprofile-reorder-functions

8539

Function reordering based on profile instrumentation collects

8540

first time of execution of a function and orders these functions

8541

in ascending order.

8542

8543

Enabled with @option{-fprofile-use}.

8544

8545

@item -fvpt

8546

@opindex fvpt

8547

If combined with @option{-fprofile-arcs}, this option instructs the compiler

8548

to add code to gather information about values of expressions.

8549

8550

With @option{-fbranch-probabilities}, it reads back the data gathered

8551

and actually performs the optimizations based on them.

8552

Currently the optimizations include specialization of division operations

8553

using the knowledge about the value of the denominator.

8554

8555

@item -frename-registers

8556

@opindex frename-registers

8557

Attempt to avoid false dependencies in scheduled code by making use

8558

of registers left over after register allocation. This optimization

8559

most benefits processors with lots of registers. Depending on the

8560

debug information format adopted by the target, however, it can

8561

make debugging impossible, since variables no longer stay in

8562

a ``home register''.

8563

8564

Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}.

8565

8566

@item -fschedule-fusion

8567

@opindex fschedule-fusion

8568

Performs a target dependent pass over the instruction stream to schedule

8569

instructions of same type together because target machine can execute them

8570

more efficiently if they are adjacent to each other in the instruction flow.

8571

8572

Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.

8573

8574

@item -ftracer

8575

@opindex ftracer

8576

Perform tail duplication to enlarge superblock size. This transformation

8577

simplifies the control flow of the function allowing other optimizations to do

8578

a better job.

8579

8580

Enabled with @option{-fprofile-use}.

8581

8582

@item -funroll-loops

8583

@opindex funroll-loops

8584

Unroll loops whose number of iterations can be determined at compile time or

8585

upon entry to the loop. @option{-funroll-loops} implies

8586

@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.

8587

It also turns on complete loop peeling (i.e.@: complete removal of loops with

8588

a small constant number of iterations). This option makes code larger, and may

8589

or may not make it run faster.

8590

8591

Enabled with @option{-fprofile-use}.

8592

8593

@item -funroll-all-loops

8594

@opindex funroll-all-loops

8595

Unroll all loops, even if their number of iterations is uncertain when

8596

the loop is entered. This usually makes programs run more slowly.

8597

@option{-funroll-all-loops} implies the same options as

8598

@option{-funroll-loops}.

8599

8600

@item -fpeel-loops

8601

@opindex fpeel-loops

8602

Peels loops for which there is enough information that they do not

8603

roll much (from profile feedback). It also turns on complete loop peeling

8604

(i.e.@: complete removal of loops with small constant number of iterations).

8605

8606

Enabled with @option{-fprofile-use}.

8607

8608

@item -fmove-loop-invariants

8609

@opindex fmove-loop-invariants

8610

Enables the loop invariant motion pass in the RTL loop optimizer. Enabled

8611

at level @option{-O1}

8612

8613

@item -funswitch-loops

8614

@opindex funswitch-loops

8615

Move branches with loop invariant conditions out of the loop, with duplicates

8616

of the loop on both branches (modified according to result of the condition).

8617

8618

@item -ffunction-sections

8619

@itemx -fdata-sections

8620

@opindex ffunction-sections

8621

@opindex fdata-sections

8622

Place each function or data item into its own section in the output

8623

file if the target supports arbitrary sections. The name of the

8624

function or the name of the data item determines the section's name

8625

in the output file.

8626

8627

Use these options on systems where the linker can perform optimizations

8628

to improve locality of reference in the instruction space. Most systems

8629

using the ELF object format and SPARC processors running Solaris 2 have

8630

linkers with such optimizations. AIX may have these optimizations in

8631

the future.

8632

8633

Only use these options when there are significant benefits from doing

8634

so. When you specify these options, the assembler and linker

8635

create larger object and executable files and are also slower.

8636

You cannot use @command{gprof} on all systems if you

8637

specify this option, and you may have problems with debugging if

8638

you specify both this option and @option{-g}.

8639

8640

@item -fbranch-target-load-optimize

8641

@opindex fbranch-target-load-optimize

8642

Perform branch target register load optimization before prologue / epilogue

8643

threading.

8644

The use of target registers can typically be exposed only during reload,

8645

thus hoisting loads out of loops and doing inter-block scheduling needs

8646

a separate optimization pass.

8647

8648

@item -fbranch-target-load-optimize2

8649

@opindex fbranch-target-load-optimize2

8650

Perform branch target register load optimization after prologue / epilogue

8651

threading.

8652

8653

@item -fbtr-bb-exclusive

8654

@opindex fbtr-bb-exclusive

8655

When performing branch target register load optimization, don't reuse

8656

branch target registers within any basic block.

8657

8658

@item -fstdarg-opt

8659

@opindex fstdarg-opt

8660

Optimize the prologue of variadic argument functions with respect to usage of

8661

those arguments.

8662

8663

@item -fsection-anchors

8664

@opindex fsection-anchors

8665

Try to reduce the number of symbolic address calculations by using

8666

shared ``anchor'' symbols to address nearby objects. This transformation

8667

can help to reduce the number of GOT entries and GOT accesses on some

8668

targets.

8669

8670

For example, the implementation of the following function @code{foo}:

8671

8672

@smallexample

8673

static int a, b, c;

8674

int foo (void) @{ return a + b + c; @}

8675

@end smallexample

8676

8677

@noindent

8678

usually calculates the addresses of all three variables, but if you

8679

compile it with @option{-fsection-anchors}, it accesses the variables

8680

from a common anchor point instead. The effect is similar to the

8681

following pseudocode (which isn't valid C):

8682

8683

@smallexample

8684

int foo (void)

8685

@{

8686

register int *xr = &x;

8687

return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];

8688

@}

8689

@end smallexample

8690

8691

Not all targets support this option.

8692

8693

@item --param @var{name}=@var{value}

8694

@opindex param

8695

In some places, GCC uses various constants to control the amount of

8696

optimization that is done. For example, GCC does not inline functions

8697

that contain more than a certain number of instructions. You can

8698

control some of these constants on the command line using the

8699

@option{--param} option.

8700

8701

The names of specific parameters, and the meaning of the values, are

8702

tied to the internals of the compiler, and are subject to change

8703

without notice in future releases.

8704

8705

In each case, the @var{value} is an integer. The allowable choices for

8706

@var{name} are:

8707

8708

@table @gcctabopt

8709

@item predictable-branch-outcome

8710

When branch is predicted to be taken with probability lower than this threshold

8711

(in percent), then it is considered well predictable. The default is 10.

8712

8713

@item max-rtl-if-conversion-insns

8714

RTL if-conversion tries to remove conditional branches around a block and

8715

replace them with conditionally executed instructions. This parameter

8716

gives the maximum number of instructions in a block which should be

8717

considered for if-conversion. The default is 10, though the compiler will

8718

also use other heuristics to decide whether if-conversion is likely to be

8719

profitable.

8720

8721

@item max-crossjump-edges

8722

The maximum number of incoming edges to consider for cross-jumping.

8723

The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in

8724

the number of edges incoming to each block. Increasing values mean

8725

more aggressive optimization, making the compilation time increase with

8726

probably small improvement in executable size.

8727

8728

@item min-crossjump-insns

8729

The minimum number of instructions that must be matched at the end

8730

of two blocks before cross-jumping is performed on them. This

8731

value is ignored in the case where all instructions in the block being

8732

cross-jumped from are matched. The default value is 5.

8733

8734

@item max-grow-copy-bb-insns

8735

The maximum code size expansion factor when copying basic blocks

8736

instead of jumping. The expansion is relative to a jump instruction.

8737

The default value is 8.

8738

8739

@item max-goto-duplication-insns

8740

The maximum number of instructions to duplicate to a block that jumps

8741

to a computed goto. To avoid @math{O(N^2)} behavior in a number of

8742

passes, GCC factors computed gotos early in the compilation process,

8743

and unfactors them as late as possible. Only computed jumps at the

8744

end of a basic blocks with no more than max-goto-duplication-insns are

8745

unfactored. The default value is 8.

8746

8747

@item max-delay-slot-insn-search

8748

The maximum number of instructions to consider when looking for an

8749

instruction to fill a delay slot. If more than this arbitrary number of

8750

instructions are searched, the time savings from filling the delay slot

8751

are minimal, so stop searching. Increasing values mean more

8752

aggressive optimization, making the compilation time increase with probably

8753

small improvement in execution time.

8754

8755

@item max-delay-slot-live-search

8756

When trying to fill delay slots, the maximum number of instructions to

8757

consider when searching for a block with valid live register

8758

information. Increasing this arbitrarily chosen value means more

8759

aggressive optimization, increasing the compilation time. This parameter

8760

should be removed when the delay slot code is rewritten to maintain the

8761

control-flow graph.

8762

8763

@item max-gcse-memory

8764

The approximate maximum amount of memory that can be allocated in

8765

order to perform the global common subexpression elimination

8766

optimization. If more memory than specified is required, the

8767

optimization is not done.

8768

8769

@item max-gcse-insertion-ratio

8770

If the ratio of expression insertions to deletions is larger than this value

8771

for any expression, then RTL PRE inserts or removes the expression and thus

8772

leaves partially redundant computations in the instruction stream. The default value is 20.

8773

8774

@item max-pending-list-length

8775

The maximum number of pending dependencies scheduling allows

8776

before flushing the current state and starting over. Large functions

8777

with few branches or calls can create excessively large lists which

8778

needlessly consume memory and resources.

8779

8780

@item max-modulo-backtrack-attempts

8781

The maximum number of backtrack attempts the scheduler should make

8782

when modulo scheduling a loop. Larger values can exponentially increase

8783

compilation time.

8784

8785

@item max-inline-insns-single

8786

Several parameters control the tree inliner used in GCC@.

8787

This number sets the maximum number of instructions (counted in GCC's

8788

internal representation) in a single function that the tree inliner

8789

considers for inlining. This only affects functions declared

8790

inline and methods implemented in a class declaration (C++).

8791

The default value is 400.

8792

8793

@item max-inline-insns-auto

8794

When you use @option{-finline-functions} (included in @option{-O3}),

8795

a lot of functions that would otherwise not be considered for inlining

8796

by the compiler are investigated. To those functions, a different

8797

(more restrictive) limit compared to functions declared inline can

8798

be applied.

8799

The default value is 40.

8800

8801

@item inline-min-speedup

8802

When estimated performance improvement of caller + callee runtime exceeds this

8803

threshold (in precent), the function can be inlined regardless the limit on

8804

@option{--param max-inline-insns-single} and @option{--param

8805

max-inline-insns-auto}.

8806

8807

@item large-function-insns

8808

The limit specifying really large functions. For functions larger than this

8809

limit after inlining, inlining is constrained by

8810

@option{--param large-function-growth}. This parameter is useful primarily

8811

to avoid extreme compilation time caused by non-linear algorithms used by the

8812

back end.

8813

The default value is 2700.

8814

8815

@item large-function-growth

8816

Specifies maximal growth of large function caused by inlining in percents.

8817

The default value is 100 which limits large function growth to 2.0 times

8818

the original size.

8819

8820

@item large-unit-insns

8821

The limit specifying large translation unit. Growth caused by inlining of

8822

units larger than this limit is limited by @option{--param inline-unit-growth}.

8823

For small units this might be too tight.

8824

For example, consider a unit consisting of function A

8825

that is inline and B that just calls A three times. If B is small relative to

8826

A, the growth of unit is 300\% and yet such inlining is very sane. For very

8827

large units consisting of small inlineable functions, however, the overall unit

8828

growth limit is needed to avoid exponential explosion of code size. Thus for

8829

smaller units, the size is increased to @option{--param large-unit-insns}

8830

before applying @option{--param inline-unit-growth}. The default is 10000.

8831

8832

@item inline-unit-growth

8833

Specifies maximal overall growth of the compilation unit caused by inlining.

8834

The default value is 20 which limits unit growth to 1.2 times the original

8835

size. Cold functions (either marked cold via an attribute or by profile

8836

feedback) are not accounted into the unit size.

8837

8838

@item ipcp-unit-growth

8839

Specifies maximal overall growth of the compilation unit caused by

8840

interprocedural constant propagation. The default value is 10 which limits

8841

unit growth to 1.1 times the original size.

8842

8843

@item large-stack-frame

8844

The limit specifying large stack frames. While inlining the algorithm is trying

8845

to not grow past this limit too much. The default value is 256 bytes.

8846

8847

@item large-stack-frame-growth

8848

Specifies maximal growth of large stack frames caused by inlining in percents.

8849

The default value is 1000 which limits large stack frame growth to 11 times

8850

the original size.

8851

8852

@item max-inline-insns-recursive

8853

@itemx max-inline-insns-recursive-auto

8854

Specifies the maximum number of instructions an out-of-line copy of a

8855

self-recursive inline

8856

function can grow into by performing recursive inlining.

8857

8858

@option{--param max-inline-insns-recursive} applies to functions

8859

declared inline.

8860

For functions not declared inline, recursive inlining

8861

happens only when @option{-finline-functions} (included in @option{-O3}) is

8862

enabled; @option{--param max-inline-insns-recursive-auto} applies instead. The

8863

default value is 450.

8864

8865

@item max-inline-recursive-depth

8866

@itemx max-inline-recursive-depth-auto

8867

Specifies the maximum recursion depth used for recursive inlining.

8868

8869

@option{--param max-inline-recursive-depth} applies to functions

8870

declared inline. For functions not declared inline, recursive inlining

8871

happens only when @option{-finline-functions} (included in @option{-O3}) is

8872

enabled; @option{--param max-inline-recursive-depth-auto} applies instead. The

8873

default value is 8.

8874

8875

@item min-inline-recursive-probability

8876

Recursive inlining is profitable only for function having deep recursion

8877

in average and can hurt for function having little recursion depth by

8878

increasing the prologue size or complexity of function body to other

8879

optimizers.

8880

8881

When profile feedback is available (see @option{-fprofile-generate}) the actual

8882

recursion depth can be guessed from probability that function recurses via a

8883

given call expression. This parameter limits inlining only to call expressions

8884

whose probability exceeds the given threshold (in percents).

8885

The default value is 10.

8886

8887

@item early-inlining-insns

8888

Specify growth that the early inliner can make. In effect it increases

8889

the amount of inlining for code having a large abstraction penalty.

8890

The default value is 14.

8891

8892

@item max-early-inliner-iterations

8893

Limit of iterations of the early inliner. This basically bounds

8894

the number of nested indirect calls the early inliner can resolve.

8895

Deeper chains are still handled by late inlining.

8896

8897

@item comdat-sharing-probability

8898

Probability (in percent) that C++ inline function with comdat visibility

8899

are shared across multiple compilation units. The default value is 20.

8900

8901

@item profile-func-internal-id

8902

A parameter to control whether to use function internal id in profile

8903

database lookup. If the value is 0, the compiler uses an id that

8904

is based on function assembler name and filename, which makes old profile

8905

data more tolerant to source changes such as function reordering etc.

8906

The default value is 0.

8907

8908

@item min-vect-loop-bound

8909

The minimum number of iterations under which loops are not vectorized

8910

when @option{-ftree-vectorize} is used. The number of iterations after

8911

vectorization needs to be greater than the value specified by this option

8912

to allow vectorization. The default value is 0.

8913

8914

@item gcse-cost-distance-ratio

8915

Scaling factor in calculation of maximum distance an expression

8916

can be moved by GCSE optimizations. This is currently supported only in the

8917

code hoisting pass. The bigger the ratio, the more aggressive code hoisting

8918

is with simple expressions, i.e., the expressions that have cost

8919

less than @option{gcse-unrestricted-cost}. Specifying 0 disables

8920

hoisting of simple expressions. The default value is 10.

8921

8922

@item gcse-unrestricted-cost

8923

Cost, roughly measured as the cost of a single typical machine

8924

instruction, at which GCSE optimizations do not constrain

8925

the distance an expression can travel. This is currently

8926

supported only in the code hoisting pass. The lesser the cost,

8927

the more aggressive code hoisting is. Specifying 0

8928

allows all expressions to travel unrestricted distances.

8929

The default value is 3.

8930

8931

@item max-hoist-depth

8932

The depth of search in the dominator tree for expressions to hoist.

8933

This is used to avoid quadratic behavior in hoisting algorithm.

8934

The value of 0 does not limit on the search, but may slow down compilation

8935

of huge functions. The default value is 30.

8936

8937

@item max-tail-merge-comparisons

8938

The maximum amount of similar bbs to compare a bb with. This is used to

8939

avoid quadratic behavior in tree tail merging. The default value is 10.

8940

8941

@item max-tail-merge-iterations

8942

The maximum amount of iterations of the pass over the function. This is used to

8943

limit compilation time in tree tail merging. The default value is 2.

8944

8945

@item max-unrolled-insns

8946

The maximum number of instructions that a loop may have to be unrolled.

8947

If a loop is unrolled, this parameter also determines how many times

8948

the loop code is unrolled.

8949

8950

@item max-average-unrolled-insns

8951

The maximum number of instructions biased by probabilities of their execution

8952

that a loop may have to be unrolled. If a loop is unrolled,

8953

this parameter also determines how many times the loop code is unrolled.

8954

8955

@item max-unroll-times

8956

The maximum number of unrollings of a single loop.

8957

8958

@item max-peeled-insns

8959

The maximum number of instructions that a loop may have to be peeled.

8960

If a loop is peeled, this parameter also determines how many times

8961

the loop code is peeled.

8962

8963

@item max-peel-times

8964

The maximum number of peelings of a single loop.

8965

8966

@item max-peel-branches

8967

The maximum number of branches on the hot path through the peeled sequence.

8968

8969

@item max-completely-peeled-insns

8970

The maximum number of insns of a completely peeled loop.

8971

8972

@item max-completely-peel-times

8973

The maximum number of iterations of a loop to be suitable for complete peeling.

8974

8975

@item max-completely-peel-loop-nest-depth

8976

The maximum depth of a loop nest suitable for complete peeling.

8977

8978

@item max-unswitch-insns

8979

The maximum number of insns of an unswitched loop.

8980

8981

@item max-unswitch-level

8982

The maximum number of branches unswitched in a single loop.

8983

8984

@item lim-expensive

8985

The minimum cost of an expensive expression in the loop invariant motion.

8986

8987

@item iv-consider-all-candidates-bound

8988

Bound on number of candidates for induction variables, below which

8989

all candidates are considered for each use in induction variable

8990

optimizations. If there are more candidates than this,

8991

only the most relevant ones are considered to avoid quadratic time complexity.

8992

8993

@item iv-max-considered-uses

8994

The induction variable optimizations give up on loops that contain more

8995

induction variable uses.

8996

8997

@item iv-always-prune-cand-set-bound

8998

If the number of candidates in the set is smaller than this value,

8999

always try to remove unnecessary ivs from the set

9000

when adding a new one.

9001

9002

@item scev-max-expr-size

9003

Bound on size of expressions used in the scalar evolutions analyzer.

9004

Large expressions slow the analyzer.

9005

9006

@item scev-max-expr-complexity

9007

Bound on the complexity of the expressions in the scalar evolutions analyzer.

9008

Complex expressions slow the analyzer.

9009

9010

@item vect-max-version-for-alignment-checks

9011

The maximum number of run-time checks that can be performed when

9012

doing loop versioning for alignment in the vectorizer.

9013

9014

@item vect-max-version-for-alias-checks

9015

The maximum number of run-time checks that can be performed when

9016

doing loop versioning for alias in the vectorizer.

9017

9018

@item vect-max-peeling-for-alignment

9019

The maximum number of loop peels to enhance access alignment

9020

for vectorizer. Value -1 means no limit.

9021

9022

@item max-iterations-to-track

9023

The maximum number of iterations of a loop the brute-force algorithm

9024

for analysis of the number of iterations of the loop tries to evaluate.

9025

9026

@item hot-bb-count-ws-permille

9027

A basic block profile count is considered hot if it contributes to

9028

the given permillage (i.e. 0...1000) of the entire profiled execution.

9029

9030

@item hot-bb-frequency-fraction

9031

Select fraction of the entry block frequency of executions of basic block in

9032

function given basic block needs to have to be considered hot.

9033

9034

@item max-predicted-iterations

9035

The maximum number of loop iterations we predict statically. This is useful

9036

in cases where a function contains a single loop with known bound and

9037

another loop with unknown bound.

9038

The known number of iterations is predicted correctly, while

9039

the unknown number of iterations average to roughly 10. This means that the

9040

loop without bounds appears artificially cold relative to the other one.

9041

9042

@item builtin-expect-probability

9043

Control the probability of the expression having the specified value. This

9044

parameter takes a percentage (i.e. 0 ... 100) as input.

9045

The default probability of 90 is obtained empirically.

9046

9047

@item align-threshold

9048

9049

Select fraction of the maximal frequency of executions of a basic block in

9050

a function to align the basic block.

9051

9052

@item align-loop-iterations

9053

9054

A loop expected to iterate at least the selected number of iterations is

9055

aligned.

9056

9057

@item tracer-dynamic-coverage

9058

@itemx tracer-dynamic-coverage-feedback

9059

9060

This value is used to limit superblock formation once the given percentage of

9061

executed instructions is covered. This limits unnecessary code size

9062

expansion.

9063

9064

The @option{tracer-dynamic-coverage-feedback} parameter

9065

is used only when profile

9066

feedback is available. The real profiles (as opposed to statically estimated

9067

ones) are much less balanced allowing the threshold to be larger value.

9068

9069

@item tracer-max-code-growth

9070

Stop tail duplication once code growth has reached given percentage. This is

9071

a rather artificial limit, as most of the duplicates are eliminated later in

9072

cross jumping, so it may be set to much higher values than is the desired code

9073

growth.

9074

9075

@item tracer-min-branch-ratio

9076

9077

Stop reverse growth when the reverse probability of best edge is less than this

9078

threshold (in percent).

9079

9080

@item tracer-min-branch-probability

9081

@itemx tracer-min-branch-probability-feedback

9082

9083

Stop forward growth if the best edge has probability lower than this

9084

threshold.

9085

9086

Similarly to @option{tracer-dynamic-coverage} two parameters are

9087

provided. @option{tracer-min-branch-probability-feedback} is used for

9088

compilation with profile feedback and @option{tracer-min-branch-probability}

9089

compilation without. The value for compilation with profile feedback

9090

needs to be more conservative (higher) in order to make tracer

9091

effective.

9092

9093

@item max-cse-path-length

9094

9095

The maximum number of basic blocks on path that CSE considers.

9096

The default is 10.

9097

9098

@item max-cse-insns

9099

The maximum number of instructions CSE processes before flushing.

9100

The default is 1000.

9101

9102

@item ggc-min-expand

9103

9104

GCC uses a garbage collector to manage its own memory allocation. This

9105

parameter specifies the minimum percentage by which the garbage

9106

collector's heap should be allowed to expand between collections.

9107

Tuning this may improve compilation speed; it has no effect on code

9108

generation.

9109

9110

The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when

9111

RAM >= 1GB@. If @code{getrlimit} is available, the notion of ``RAM'' is

9112

the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If

9113

GCC is not able to calculate RAM on a particular platform, the lower

9114

bound of 30% is used. Setting this parameter and

9115

@option{ggc-min-heapsize} to zero causes a full collection to occur at

9116

every opportunity. This is extremely slow, but can be useful for

9117

debugging.

9118

9119

@item ggc-min-heapsize

9120

9121

Minimum size of the garbage collector's heap before it begins bothering

9122

to collect garbage. The first collection occurs after the heap expands

9123

by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,

9124

tuning this may improve compilation speed, and has no effect on code

9125

generation.

9126

9127

The default is the smaller of RAM/8, RLIMIT_RSS, or a limit that

9128

tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but

9129

with a lower bound of 4096 (four megabytes) and an upper bound of

9130

131072 (128 megabytes). If GCC is not able to calculate RAM on a

9131

particular platform, the lower bound is used. Setting this parameter

9132

very large effectively disables garbage collection. Setting this

9133

parameter and @option{ggc-min-expand} to zero causes a full collection

9134

to occur at every opportunity.

9135

9136

@item max-reload-search-insns

9137

The maximum number of instruction reload should look backward for equivalent

9138

register. Increasing values mean more aggressive optimization, making the

9139

compilation time increase with probably slightly better performance.

9140

The default value is 100.

9141

9142

@item max-cselib-memory-locations

9143

The maximum number of memory locations cselib should take into account.

9144

Increasing values mean more aggressive optimization, making the compilation time

9145

increase with probably slightly better performance. The default value is 500.

9146

9147

@item max-sched-ready-insns

9148

The maximum number of instructions ready to be issued the scheduler should

9149

consider at any given time during the first scheduling pass. Increasing

9150

values mean more thorough searches, making the compilation time increase

9151

with probably little benefit. The default value is 100.

9152

9153

@item max-sched-region-blocks

9154

The maximum number of blocks in a region to be considered for

9155

interblock scheduling. The default value is 10.

9156

9157

@item max-pipeline-region-blocks

9158

The maximum number of blocks in a region to be considered for

9159

pipelining in the selective scheduler. The default value is 15.

9160

9161

@item max-sched-region-insns

9162

The maximum number of insns in a region to be considered for

9163

interblock scheduling. The default value is 100.

9164

9165

@item max-pipeline-region-insns

9166

The maximum number of insns in a region to be considered for

9167

pipelining in the selective scheduler. The default value is 200.

9168

9169

@item min-spec-prob

9170

The minimum probability (in percents) of reaching a source block

9171

for interblock speculative scheduling. The default value is 40.

9172

9173

@item max-sched-extend-regions-iters

9174

The maximum number of iterations through CFG to extend regions.

9175

A value of 0 (the default) disables region extensions.

9176

9177

@item max-sched-insn-conflict-delay

9178

The maximum conflict delay for an insn to be considered for speculative motion.

9179

The default value is 3.

9180

9181

@item sched-spec-prob-cutoff

9182

The minimal probability of speculation success (in percents), so that

9183

speculative insns are scheduled.

9184

The default value is 40.

9185

9186

@item sched-state-edge-prob-cutoff

9187

The minimum probability an edge must have for the scheduler to save its

9188

state across it.

9189

The default value is 10.

9190

9191

@item sched-mem-true-dep-cost

9192

Minimal distance (in CPU cycles) between store and load targeting same

9193

memory locations. The default value is 1.

9194

9195

@item selsched-max-lookahead

9196

The maximum size of the lookahead window of selective scheduling. It is a

9197

depth of search for available instructions.

9198

The default value is 50.

9199

9200

@item selsched-max-sched-times

9201

The maximum number of times that an instruction is scheduled during

9202

selective scheduling. This is the limit on the number of iterations

9203

through which the instruction may be pipelined. The default value is 2.

9204

9205

@item selsched-insns-to-rename

9206

The maximum number of best instructions in the ready list that are considered

9207

for renaming in the selective scheduler. The default value is 2.

9208

9209

@item sms-min-sc

9210

The minimum value of stage count that swing modulo scheduler

9211

generates. The default value is 2.

9212

9213

@item max-last-value-rtl

9214

The maximum size measured as number of RTLs that can be recorded in an expression

9215

in combiner for a pseudo register as last known value of that register. The default

9216

is 10000.

9217

9218

@item max-combine-insns

9219

The maximum number of instructions the RTL combiner tries to combine.

9220

The default value is 2 at @option{-Og} and 4 otherwise.

9221

9222

@item integer-share-limit

9223

Small integer constants can use a shared data structure, reducing the

9224

compiler's memory usage and increasing its speed. This sets the maximum

9225

value of a shared integer constant. The default value is 256.

9226

9227

@item ssp-buffer-size

9228

The minimum size of buffers (i.e.@: arrays) that receive stack smashing

9229

protection when @option{-fstack-protection} is used.

9230

9231

@item min-size-for-stack-sharing

9232

The minimum size of variables taking part in stack slot sharing when not

9233

optimizing. The default value is 32.

9234

9235

@item max-jump-thread-duplication-stmts

9236

Maximum number of statements allowed in a block that needs to be

9237

duplicated when threading jumps.

9238

9239

@item max-fields-for-field-sensitive

9240

Maximum number of fields in a structure treated in

9241

a field sensitive manner during pointer analysis. The default is zero

9242

for @option{-O0} and @option{-O1},

9243

and 100 for @option{-Os}, @option{-O2}, and @option{-O3}.

9244

9245

@item prefetch-latency

9246

Estimate on average number of instructions that are executed before

9247

prefetch finishes. The distance prefetched ahead is proportional

9248

to this constant. Increasing this number may also lead to less

9249

streams being prefetched (see @option{simultaneous-prefetches}).

9250

9251

@item simultaneous-prefetches

9252

Maximum number of prefetches that can run at the same time.

9253

9254

@item l1-cache-line-size

9255

The size of cache line in L1 cache, in bytes.

9256

9257

@item l1-cache-size

9258

The size of L1 cache, in kilobytes.

9259

9260

@item l2-cache-size

9261

The size of L2 cache, in kilobytes.

9262

9263

@item min-insn-to-prefetch-ratio

9264

The minimum ratio between the number of instructions and the

9265

number of prefetches to enable prefetching in a loop.

9266

9267

@item prefetch-min-insn-to-mem-ratio

9268

The minimum ratio between the number of instructions and the

9269

number of memory references to enable prefetching in a loop.

9270

9271

@item use-canonical-types

9272

Whether the compiler should use the ``canonical'' type system. By

9273

default, this should always be 1, which uses a more efficient internal

9274

mechanism for comparing types in C++ and Objective-C++. However, if

9275

bugs in the canonical type system are causing compilation failures,

9276

set this value to 0 to disable canonical types.

9277

9278

@item switch-conversion-max-branch-ratio

9279

Switch initialization conversion refuses to create arrays that are

9280

bigger than @option{switch-conversion-max-branch-ratio} times the number of

9281

branches in the switch.

9282

9283

@item max-partial-antic-length

9284

Maximum length of the partial antic set computed during the tree

9285

partial redundancy elimination optimization (@option{-ftree-pre}) when

9286

optimizing at @option{-O3} and above. For some sorts of source code

9287

the enhanced partial redundancy elimination optimization can run away,

9288

consuming all of the memory available on the host machine. This

9289

parameter sets a limit on the length of the sets that are computed,

9290

which prevents the runaway behavior. Setting a value of 0 for

9291

this parameter allows an unlimited set length.

9292

9293

@item sccvn-max-scc-size

9294

Maximum size of a strongly connected component (SCC) during SCCVN

9295

processing. If this limit is hit, SCCVN processing for the whole

9296

function is not done and optimizations depending on it are

9297

disabled. The default maximum SCC size is 10000.

9298

9299

@item sccvn-max-alias-queries-per-access

9300

Maximum number of alias-oracle queries we perform when looking for

9301

redundancies for loads and stores. If this limit is hit the search

9302

is aborted and the load or store is not considered redundant. The

9303

number of queries is algorithmically limited to the number of

9304

stores on all paths from the load to the function entry.

9305

The default maximum number of queries is 1000.

9306

9307

@item ira-max-loops-num

9308

IRA uses regional register allocation by default. If a function

9309

contains more loops than the number given by this parameter, only at most

9310

the given number of the most frequently-executed loops form regions

9311

for regional register allocation. The default value of the

9312

parameter is 100.

9313

9314

@item ira-max-conflict-table-size

9315

Although IRA uses a sophisticated algorithm to compress the conflict

9316

table, the table can still require excessive amounts of memory for

9317

huge functions. If the conflict table for a function could be more

9318

than the size in MB given by this parameter, the register allocator

9319

instead uses a faster, simpler, and lower-quality

9320

algorithm that does not require building a pseudo-register conflict table.

9321

The default value of the parameter is 2000.

9322

9323

@item ira-loop-reserved-regs

9324

IRA can be used to evaluate more accurate register pressure in loops

9325

for decisions to move loop invariants (see @option{-O3}). The number

9326

of available registers reserved for some other purposes is given

9327

by this parameter. The default value of the parameter is 2, which is

9328

the minimal number of registers needed by typical instructions.

9329

This value is the best found from numerous experiments.

9330

9331

@item lra-inheritance-ebb-probability-cutoff

9332

LRA tries to reuse values reloaded in registers in subsequent insns.

9333

This optimization is called inheritance. EBB is used as a region to

9334

do this optimization. The parameter defines a minimal fall-through

9335

edge probability in percentage used to add BB to inheritance EBB in

9336

LRA. The default value of the parameter is 40. The value was chosen

9337

from numerous runs of SPEC2000 on x86-64.

9338

9339

@item loop-invariant-max-bbs-in-loop

9340

Loop invariant motion can be very expensive, both in compilation time and

9341

in amount of needed compile-time memory, with very large loops. Loops

9342

with more basic blocks than this parameter won't have loop invariant

9343

motion optimization performed on them. The default value of the

9344

parameter is 1000 for @option{-O1} and 10000 for @option{-O2} and above.

9345

9346

@item loop-max-datarefs-for-datadeps

9347

Building data dependencies is expensive for very large loops. This

9348

parameter limits the number of data references in loops that are

9349

considered for data dependence analysis. These large loops are no

9350

handled by the optimizations using loop data dependencies.

9351

The default value is 1000.

9352

9353

@item max-vartrack-size

9354

Sets a maximum number of hash table slots to use during variable

9355

tracking dataflow analysis of any function. If this limit is exceeded

9356

with variable tracking at assignments enabled, analysis for that

9357

function is retried without it, after removing all debug insns from

9358

the function. If the limit is exceeded even without debug insns, var

9359

tracking analysis is completely disabled for the function. Setting

9360

the parameter to zero makes it unlimited.

9361

9362

@item max-vartrack-expr-depth

9363

Sets a maximum number of recursion levels when attempting to map

9364

variable names or debug temporaries to value expressions. This trades

9365

compilation time for more complete debug information. If this is set too

9366

low, value expressions that are available and could be represented in

9367

debug information may end up not being used; setting this higher may

9368

enable the compiler to find more complex debug expressions, but compile

9369

time and memory use may grow. The default is 12.

9370

9371

@item min-nondebug-insn-uid

9372

Use uids starting at this parameter for nondebug insns. The range below

9373

the parameter is reserved exclusively for debug insns created by

9374

@option{-fvar-tracking-assignments}, but debug insns may get

9375

(non-overlapping) uids above it if the reserved range is exhausted.

9376

9377

@item ipa-sra-ptr-growth-factor

9378

IPA-SRA replaces a pointer to an aggregate with one or more new

9379

parameters only when their cumulative size is less or equal to

9380

@option{ipa-sra-ptr-growth-factor} times the size of the original

9381

pointer parameter.

9382

9383

@item sra-max-scalarization-size-Ospeed

9384

@item sra-max-scalarization-size-Osize

9385

The two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) aim to

9386

replace scalar parts of aggregates with uses of independent scalar

9387

variables. These parameters control the maximum size, in storage units,

9388

of aggregate which is considered for replacement when compiling for

9389

speed

9390

(@option{sra-max-scalarization-size-Ospeed}) or size

9391

(@option{sra-max-scalarization-size-Osize}) respectively.

9392

9393

@item tm-max-aggregate-size

9394

When making copies of thread-local variables in a transaction, this

9395

parameter specifies the size in bytes after which variables are

9396

saved with the logging functions as opposed to save/restore code

9397

sequence pairs. This option only applies when using

9398

@option{-fgnu-tm}.

9399

9400

@item graphite-max-nb-scop-params

9401

To avoid exponential effects in the Graphite loop transforms, the

9402

number of parameters in a Static Control Part (SCoP) is bounded. The

9403

default value is 10 parameters. A variable whose value is unknown at

9404

compilation time and defined outside a SCoP is a parameter of the SCoP.

9405

9406

@item graphite-max-bbs-per-function

9407

To avoid exponential effects in the detection of SCoPs, the size of

9408

the functions analyzed by Graphite is bounded. The default value is

9409

100 basic blocks.

9410

9411

@item loop-block-tile-size

9412

Loop blocking or strip mining transforms, enabled with

9413

@option{-floop-block} or @option{-floop-strip-mine}, strip mine each

9414

loop in the loop nest by a given number of iterations. The strip

9415

length can be changed using the @option{loop-block-tile-size}

9416

parameter. The default value is 51 iterations.

9417

9418

@item loop-unroll-jam-size

9419

Specify the unroll factor for the @option{-floop-unroll-and-jam} option. The

9420

default value is 4.

9421

9422

@item loop-unroll-jam-depth

9423

Specify the dimension to be unrolled (counting from the most inner loop)

9424

for the @option{-floop-unroll-and-jam}. The default value is 2.

9425

9426

@item ipa-cp-value-list-size

9427

IPA-CP attempts to track all possible values and types passed to a function's

9428

parameter in order to propagate them and perform devirtualization.

9429

@option{ipa-cp-value-list-size} is the maximum number of values and types it

9430

stores per one formal parameter of a function.

9431

9432

@item ipa-cp-eval-threshold

9433

IPA-CP calculates its own score of cloning profitability heuristics

9434

and performs those cloning opportunities with scores that exceed

9435

@option{ipa-cp-eval-threshold}.

9436

9437

@item ipa-cp-recursion-penalty

9438

Percentage penalty the recursive functions will receive when they

9439

are evaluated for cloning.

9440

9441

@item ipa-cp-single-call-penalty

9442

Percentage penalty functions containg a single call to another

9443

function will receive when they are evaluated for cloning.

9444

9445

9446

@item ipa-max-agg-items

9447

IPA-CP is also capable to propagate a number of scalar values passed

9448

in an aggregate. @option{ipa-max-agg-items} controls the maximum

9449

number of such values per one parameter.

9450

9451

@item ipa-cp-loop-hint-bonus

9452

When IPA-CP determines that a cloning candidate would make the number

9453

of iterations of a loop known, it adds a bonus of

9454

@option{ipa-cp-loop-hint-bonus} to the profitability score of

9455

the candidate.

9456

9457

@item ipa-cp-array-index-hint-bonus

9458

When IPA-CP determines that a cloning candidate would make the index of

9459

an array access known, it adds a bonus of

9460

@option{ipa-cp-array-index-hint-bonus} to the profitability

9461

score of the candidate.

9462

9463

@item ipa-max-aa-steps

9464

During its analysis of function bodies, IPA-CP employs alias analysis

9465

in order to track values pointed to by function parameters. In order

9466

not spend too much time analyzing huge functions, it gives up and

9467

consider all memory clobbered after examining

9468

@option{ipa-max-aa-steps} statements modifying memory.

9469

9470

@item lto-partitions

9471

Specify desired number of partitions produced during WHOPR compilation.

9472

The number of partitions should exceed the number of CPUs used for compilation.

9473

The default value is 32.

9474

9475

@item lto-min-partition

9476

Size of minimal partition for WHOPR (in estimated instructions).

9477

This prevents expenses of splitting very small programs into too many

9478

partitions.

9479

9480

@item cxx-max-namespaces-for-diagnostic-help

9481

The maximum number of namespaces to consult for suggestions when C++

9482

name lookup fails for an identifier. The default is 1000.

9483

9484

@item sink-frequency-threshold

9485

The maximum relative execution frequency (in percents) of the target block

9486

relative to a statement's original block to allow statement sinking of a

9487

statement. Larger numbers result in more aggressive statement sinking.

9488

The default value is 75. A small positive adjustment is applied for

9489

statements with memory operands as those are even more profitable so sink.

9490

9491

@item max-stores-to-sink

9492

The maximum number of conditional store pairs that can be sunk. Set to 0

9493

if either vectorization (@option{-ftree-vectorize}) or if-conversion

9494

(@option{-ftree-loop-if-convert}) is disabled. The default is 2.

9495

9496

@item allow-store-data-races

9497

Allow optimizers to introduce new data races on stores.

9498

Set to 1 to allow, otherwise to 0. This option is enabled by default

9499

at optimization level @option{-Ofast}.

9500

9501

@item case-values-threshold

9502

The smallest number of different values for which it is best to use a

9503

jump-table instead of a tree of conditional branches. If the value is

9504

0, use the default for the machine. The default is 0.

9505

9506

@item tree-reassoc-width

9507

Set the maximum number of instructions executed in parallel in

9508

reassociated tree. This parameter overrides target dependent

9509

heuristics used by default if has non zero value.

9510

9511

@item sched-pressure-algorithm

9512

Choose between the two available implementations of

9513

@option{-fsched-pressure}. Algorithm 1 is the original implementation

9514

and is the more likely to prevent instructions from being reordered.

9515

Algorithm 2 was designed to be a compromise between the relatively

9516

conservative approach taken by algorithm 1 and the rather aggressive

9517

approach taken by the default scheduler. It relies more heavily on

9518

having a regular register file and accurate register pressure classes.

9519

See @file{haifa-sched.c} in the GCC sources for more details.

9520

9521

The default choice depends on the target.

9522

9523

@item max-slsr-cand-scan

9524

Set the maximum number of existing candidates that are considered when

9525

seeking a basis for a new straight-line strength reduction candidate.

9526

9527

@item asan-globals

9528

Enable buffer overflow detection for global objects. This kind

9529

of protection is enabled by default if you are using

9530

@option{-fsanitize=address} option.

9531

To disable global objects protection use @option{--param asan-globals=0}.

9532

9533

@item asan-stack

9534

Enable buffer overflow detection for stack objects. This kind of

9535

protection is enabled by default when using @option{-fsanitize=address}.

9536

To disable stack protection use @option{--param asan-stack=0} option.

9537

9538

@item asan-instrument-reads

9539

Enable buffer overflow detection for memory reads. This kind of

9540

protection is enabled by default when using @option{-fsanitize=address}.

9541

To disable memory reads protection use

9542

@option{--param asan-instrument-reads=0}.

9543

9544

@item asan-instrument-writes

9545

Enable buffer overflow detection for memory writes. This kind of

9546

protection is enabled by default when using @option{-fsanitize=address}.

9547

To disable memory writes protection use

9548

@option{--param asan-instrument-writes=0} option.

9549

9550

@item asan-memintrin

9551

Enable detection for built-in functions. This kind of protection

9552

is enabled by default when using @option{-fsanitize=address}.

9553

To disable built-in functions protection use

9554

@option{--param asan-memintrin=0}.

9555

9556

@item asan-use-after-return

9557

Enable detection of use-after-return. This kind of protection

9558

is enabled by default when using @option{-fsanitize=address} option.

9559

To disable use-after-return detection use

9560

@option{--param asan-use-after-return=0}.

9561

9562

@item asan-instrumentation-with-call-threshold

9563

If number of memory accesses in function being instrumented

9564

is greater or equal to this number, use callbacks instead of inline checks.

9565

E.g. to disable inline code use

9566

@option{--param asan-instrumentation-with-call-threshold=0}.

9567

9568

@item chkp-max-ctor-size

9569

Static constructors generated by Pointer Bounds Checker may become very

9570

large and significantly increase compile time at optimization level

9571

@option{-O1} and higher. This parameter is a maximum nubmer of statements

9572

in a single generated constructor. Default value is 5000.

9573

9574

@item max-fsm-thread-path-insns

9575

Maximum number of instructions to copy when duplicating blocks on a

9576

finite state automaton jump thread path. The default is 100.

9577

9578

@item max-fsm-thread-length

9579

Maximum number of basic blocks on a finite state automaton jump thread

9580

path. The default is 10.

9581

9582

@item max-fsm-thread-paths

9583

Maximum number of new jump thread paths to create for a finite state

9584

automaton. The default is 50.

9585

9586

@item parloops-chunk-size

9587

Chunk size of omp schedule for loops parallelized by parloops. The default

9588

is 0.

9589

9590

@item parloops-schedule

9591

Schedule type of omp schedule for loops parallelized by parloops (static,

9592

dynamic, guided, auto, runtime). The default is static.

9593

9594

@item max-ssa-name-query-depth

9595

Maximum depth of recursion when querying properties of SSA names in things

9596

like fold routines. One level of recursion corresponds to following a

9597

use-def chain.

9598

9599

@item hsa-gen-debug-stores

9600

Enable emission of special debug stores within HSA kernels which are

9601

then read and reported by libgomp plugin. Generation of these stores

9602

is disabled by default, use @option{--param hsa-gen-debug-stores=1} to

9603

enable it.

9604

9605

@item max-speculative-devirt-maydefs

9606

The maximum number of may-defs we analyze when looking for a must-def

9607

specifying the dynamic type of an object that invokes a virtual call

9608

we may be able to devirtualize speculatively.

9609

@end table

9610

@end table

9611

9612

@node Instrumentation Options

9613

@section Program Instrumentation Options

9614

@cindex instrumentation options

9615

@cindex program instrumentation options

9616

@cindex run-time error checking options

9617

@cindex profiling options

9618

@cindex options, program instrumentation

9619

@cindex options, run-time error checking

9620

@cindex options, profiling

9621

9622

GCC supports a number of command-line options that control adding

9623

run-time instrumentation to the code it normally generates.

9624

For example, one purpose of instrumentation is collect profiling

9625

statistics for use in finding program hot spots, code coverage

9626

analysis, or profile-guided optimizations.

9627

Another class of program instrumentation is adding run-time checking

9628

to detect programming errors like invalid pointer

9629

dereferences or out-of-bounds array accesses, as well as deliberately

9630

hostile attacks such as stack smashing or C++ vtable hijacking.

9631

There is also a general hook which can be used to implement other

9632

forms of tracing or function-level instrumentation for debug or

9633

program analysis purposes.

9634

9635

@table @gcctabopt

9636

@cindex @command{prof}

9637

@item -p

9638

@opindex p

9639

Generate extra code to write profile information suitable for the

9640

analysis program @command{prof}. You must use this option when compiling

9641

the source files you want data about, and you must also use it when

9642

linking.

9643

9644

@cindex @command{gprof}

9645

@item -pg

9646

@opindex pg

9647

Generate extra code to write profile information suitable for the

9648

analysis program @command{gprof}. You must use this option when compiling

9649

the source files you want data about, and you must also use it when

9650

linking.

9651

9652

@item -fprofile-arcs

9653

@opindex fprofile-arcs

9654

Add code so that program flow @dfn{arcs} are instrumented. During

9655

execution the program records how many times each branch and call is

9656

executed and how many times it is taken or returns. When the compiled

9657

program exits it saves this data to a file called

9658

@file{@var{auxname}.gcda} for each source file. The data may be used for

9659

profile-directed optimizations (@option{-fbranch-probabilities}), or for

9660

test coverage analysis (@option{-ftest-coverage}). Each object file's

9661

@var{auxname} is generated from the name of the output file, if

9662

explicitly specified and it is not the final executable, otherwise it is

9663

the basename of the source file. In both cases any suffix is removed

9664

(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or

9665

@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).

9666

@xref{Cross-profiling}.

9667

9668

@cindex @command{gcov}

9669

@item --coverage

9670

@opindex coverage

9671

9672

This option is used to compile and link code instrumented for coverage

9673

analysis. The option is a synonym for @option{-fprofile-arcs}

9674

@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when

9675

linking). See the documentation for those options for more details.

9676

9677

@itemize

9678

9679

@item

9680

Compile the source files with @option{-fprofile-arcs} plus optimization

9681

and code generation options. For test coverage analysis, use the

9682

additional @option{-ftest-coverage} option. You do not need to profile

9683

every source file in a program.

9684

9685

@item

9686

Link your object files with @option{-lgcov} or @option{-fprofile-arcs}

9687

(the latter implies the former).

9688

9689

@item

9690

Run the program on a representative workload to generate the arc profile

9691

information. This may be repeated any number of times. You can run

9692

concurrent instances of your program, and provided that the file system

9693

supports locking, the data files will be correctly updated. Also

9694

@code{fork} calls are detected and correctly handled (double counting

9695

will not happen).

9696

9697

@item

9698

For profile-directed optimizations, compile the source files again with

9699

the same optimization and code generation options plus

9700

@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that

9701

Control Optimization}).

9702

9703

@item

9704

For test coverage analysis, use @command{gcov} to produce human readable

9705

information from the @file{.gcno} and @file{.gcda} files. Refer to the

9706

@command{gcov} documentation for further information.

9707

9708

@end itemize

9709

9710

With @option{-fprofile-arcs}, for each function of your program GCC

9711

creates a program flow graph, then finds a spanning tree for the graph.

9712

Only arcs that are not on the spanning tree have to be instrumented: the

9713

compiler adds code to count the number of times that these arcs are

9714

executed. When an arc is the only exit or only entrance to a block, the

9715

instrumentation code can be added to the block; otherwise, a new basic

9716

block must be created to hold the instrumentation code.

9717

9718

@need 2000

9719

@item -ftest-coverage

9720

@opindex ftest-coverage

9721

Produce a notes file that the @command{gcov} code-coverage utility

9722

(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to

9723

show program coverage. Each source file's note file is called

9724

@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option

9725

above for a description of @var{auxname} and instructions on how to

9726

generate test coverage data. Coverage data matches the source files

9727

more closely if you do not optimize.

9728

9729

@item -fprofile-dir=@var{path}

9730

@opindex fprofile-dir

9731

9732

Set the directory to search for the profile data files in to @var{path}.

9733

This option affects only the profile data generated by

9734

@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}

9735

and used by @option{-fprofile-use} and @option{-fbranch-probabilities}

9736

and its related options. Both absolute and relative paths can be used.

9737

By default, GCC uses the current directory as @var{path}, thus the

9738

profile data file appears in the same directory as the object file.

9739

9740

@item -fprofile-generate

9741

@itemx -fprofile-generate=@var{path}

9742

@opindex fprofile-generate

9743

9744

Enable options usually used for instrumenting application to produce

9745

profile useful for later recompilation with profile feedback based

9746

optimization. You must use @option{-fprofile-generate} both when

9747

compiling and when linking your program.

9748

9749

The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}.

9750

9751

If @var{path} is specified, GCC looks at the @var{path} to find

9752

the profile feedback data files. See @option{-fprofile-dir}.

9753

9754

To optimize the program based on the collected profile information, use

9755

@option{-fprofile-use}. @xref{Optimize Options}, for more information.

9756

9757

@item -fsanitize=address

9758

@opindex fsanitize=address

9759

Enable AddressSanitizer, a fast memory error detector.

9760

Memory access instructions are instrumented to detect

9761

out-of-bounds and use-after-free bugs.

9762

See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for

9763

more details. The run-time behavior can be influenced using the

9764

@env{ASAN_OPTIONS} environment variable. When set to @code{help=1},

9765

the available options are shown at startup of the instrumented program. See

9766

@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags}

9767

for a list of supported options.

9768

9769

@item -fsanitize=kernel-address

9770

@opindex fsanitize=kernel-address

9771

Enable AddressSanitizer for Linux kernel.

9772

See @uref{https://github.com/google/kasan/wiki} for more details.

9773

9774

@item -fsanitize=thread

9775

@opindex fsanitize=thread

9776

Enable ThreadSanitizer, a fast data race detector.

9777

Memory access instructions are instrumented to detect

9778

data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more

9779

details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS}

9780

environment variable; see

9781

@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of

9782

supported options.

9783

9784

@item -fsanitize=leak

9785

@opindex fsanitize=leak

9786

Enable LeakSanitizer, a memory leak detector.

9787

This option only matters for linking of executables and if neither

9788

@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that

9789

case the executable is linked against a library that overrides @code{malloc}

9790

and other allocator functions. See

9791

@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more

9792

details. The run-time behavior can be influenced using the

9793

@env{LSAN_OPTIONS} environment variable.

9794

9795

@item -fsanitize=undefined

9796

@opindex fsanitize=undefined

9797

Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.

9798

Various computations are instrumented to detect undefined behavior

9799

at runtime. Current suboptions are:

9800

9801

@table @gcctabopt

9802

9803

@item -fsanitize=shift

9804

@opindex fsanitize=shift

9805

This option enables checking that the result of a shift operation is

9806

not undefined. Note that what exactly is considered undefined differs

9807

slightly between C and C++, as well as between ISO C90 and C99, etc.

9808

9809

@item -fsanitize=integer-divide-by-zero

9810

@opindex fsanitize=integer-divide-by-zero

9811

Detect integer division by zero as well as @code{INT_MIN / -1} division.

9812

9813

@item -fsanitize=unreachable

9814

@opindex fsanitize=unreachable

9815

With this option, the compiler turns the @code{__builtin_unreachable}

9816

call into a diagnostics message call instead. When reaching the

9817

@code{__builtin_unreachable} call, the behavior is undefined.

9818

9819

@item -fsanitize=vla-bound

9820

@opindex fsanitize=vla-bound

9821

This option instructs the compiler to check that the size of a variable

9822

length array is positive.

9823

9824

@item -fsanitize=null

9825

@opindex fsanitize=null

9826

This option enables pointer checking. Particularly, the application

9827

built with this option turned on will issue an error message when it

9828

tries to dereference a NULL pointer, or if a reference (possibly an

9829

rvalue reference) is bound to a NULL pointer, or if a method is invoked

9830

on an object pointed by a NULL pointer.

9831

9832

@item -fsanitize=return

9833

@opindex fsanitize=return

9834

This option enables return statement checking. Programs

9835

built with this option turned on will issue an error message

9836

when the end of a non-void function is reached without actually

9837

returning a value. This option works in C++ only.

9838

9839

@item -fsanitize=signed-integer-overflow

9840

@opindex fsanitize=signed-integer-overflow

9841

This option enables signed integer overflow checking. We check that

9842

the result of @code{+}, @code{*}, and both unary and binary @code{-}

9843

does not overflow in the signed arithmetics. Note, integer promotion

9844

rules must be taken into account. That is, the following is not an

9845

overflow:

9846

@smallexample

9847

signed char a = SCHAR_MAX;

9848

a++;

9849

@end smallexample

9850

9851

@item -fsanitize=bounds

9852

@opindex fsanitize=bounds

9853

This option enables instrumentation of array bounds. Various out of bounds

9854

accesses are detected. Flexible array members, flexible array member-like

9855

arrays, and initializers of variables with static storage are not instrumented.

9856

9857

@item -fsanitize=bounds-strict

9858

@opindex fsanitize=bounds-strict

9859

This option enables strict instrumentation of array bounds. Most out of bounds

9860

accesses are detected, including flexible array members and flexible array

9861

member-like arrays. Initializers of variables with static storage are not

9862

instrumented.

9863

9864

@item -fsanitize=alignment

9865

@opindex fsanitize=alignment

9866

9867

This option enables checking of alignment of pointers when they are

9868

dereferenced, or when a reference is bound to insufficiently aligned target,

9869

or when a method or constructor is invoked on insufficiently aligned object.

9870

9871

@item -fsanitize=object-size

9872

@opindex fsanitize=object-size

9873

This option enables instrumentation of memory references using the

9874

@code{__builtin_object_size} function. Various out of bounds pointer

9875

accesses are detected.

9876

9877

@item -fsanitize=float-divide-by-zero

9878

@opindex fsanitize=float-divide-by-zero

9879

Detect floating-point division by zero. Unlike other similar options,

9880

@option{-fsanitize=float-divide-by-zero} is not enabled by

9881

@option{-fsanitize=undefined}, since floating-point division by zero can

9882

be a legitimate way of obtaining infinities and NaNs.

9883

9884

@item -fsanitize=float-cast-overflow

9885

@opindex fsanitize=float-cast-overflow

9886

This option enables floating-point type to integer conversion checking.

9887

We check that the result of the conversion does not overflow.

9888

Unlike other similar options, @option{-fsanitize=float-cast-overflow} is

9889

not enabled by @option{-fsanitize=undefined}.

9890

This option does not work well with @code{FE_INVALID} exceptions enabled.

9891

9892

@item -fsanitize=nonnull-attribute

9893

@opindex fsanitize=nonnull-attribute

9894

9895

This option enables instrumentation of calls, checking whether null values

9896

are not passed to arguments marked as requiring a non-null value by the

9897

@code{nonnull} function attribute.

9898

9899

@item -fsanitize=returns-nonnull-attribute

9900

@opindex fsanitize=returns-nonnull-attribute

9901

9902

This option enables instrumentation of return statements in functions

9903

marked with @code{returns_nonnull} function attribute, to detect returning

9904

of null values from such functions.

9905

9906

@item -fsanitize=bool

9907

@opindex fsanitize=bool

9908

9909

This option enables instrumentation of loads from bool. If a value other

9910

than 0/1 is loaded, a run-time error is issued.

9911

9912

@item -fsanitize=enum

9913

@opindex fsanitize=enum

9914

9915

This option enables instrumentation of loads from an enum type. If

9916

a value outside the range of values for the enum type is loaded,

9917

a run-time error is issued.

9918

9919

@item -fsanitize=vptr

9920

@opindex fsanitize=vptr

9921

9922

This option enables instrumentation of C++ member function calls, member

9923

accesses and some conversions between pointers to base and derived classes,

9924

to verify the referenced object has the correct dynamic type.

9925

9926

@end table

9927

9928

While @option{-ftrapv} causes traps for signed overflows to be emitted,

9929

@option{-fsanitize=undefined} gives a diagnostic message.

9930

This currently works only for the C family of languages.

9931

9932

@item -fno-sanitize=all

9933

@opindex fno-sanitize=all

9934

9935

This option disables all previously enabled sanitizers.

9936

@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used

9937

together.

9938

9939

@item -fasan-shadow-offset=@var{number}

9940

@opindex fasan-shadow-offset

9941

This option forces GCC to use custom shadow offset in AddressSanitizer checks.

9942

It is useful for experimenting with different shadow memory layouts in

9943

Kernel AddressSanitizer.

9944

9945

@item -fsanitize-sections=@var{s1},@var{s2},...

9946

@opindex fsanitize-sections

9947

Sanitize global variables in selected user-defined sections. @var{si} may

9948

contain wildcards.

9949

9950

@item -fsanitize-recover@r{[}=@var{opts}@r{]}

9951

@opindex fsanitize-recover

9952

@opindex fno-sanitize-recover

9953

@option{-fsanitize-recover=} controls error recovery mode for sanitizers

9954

mentioned in comma-separated list of @var{opts}. Enabling this option

9955

for a sanitizer component causes it to attempt to continue

9956

running the program as if no error happened. This means multiple

9957

runtime errors can be reported in a single program run, and the exit

9958

code of the program may indicate success even when errors

9959

have been reported. The @option{-fno-sanitize-recover=} option

9960

can be used to alter

9961

this behavior: only the first detected error is reported

9962

and program then exits with a non-zero exit code.

9963

9964

Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions

9965

except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}),

9966

@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero},

9967

@option{-fsanitize=kernel-address} and @option{-fsanitize=address}.

9968

For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address},

9969

for which this feature is experimental.

9970

@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also

9971

accepted, the former enables recovery for all sanitizers that support it,

9972

the latter disables recovery for all sanitizers that support it.

9973

9974

Syntax without explicit @var{opts} parameter is deprecated. It is equivalent to

9975

@smallexample

9976

-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero

9977

@end smallexample

9978

@noindent

9979

Similarly @option{-fno-sanitize-recover} is equivalent to

9980

@smallexample

9981

-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero

9982

@end smallexample

9983

9984

@item -fsanitize-undefined-trap-on-error

9985

@opindex fsanitize-undefined-trap-on-error

9986

The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to

9987

report undefined behavior using @code{__builtin_trap} rather than

9988

a @code{libubsan} library routine. The advantage of this is that the

9989

@code{libubsan} library is not needed and is not linked in, so this

9990

is usable even in freestanding environments.

9991

9992

@item -fsanitize-coverage=trace-pc

9993

@opindex fsanitize-coverage=trace-pc

9994

Enable coverage-guided fuzzing code instrumentation.

9995

Inserts a call to @code{__sanitizer_cov_trace_pc} into every basic block.

9996

9997

@item -fbounds-check

9998

@opindex fbounds-check

9999

For front ends that support it, generate additional code to check that

10000

indices used to access arrays are within the declared range. This is

10001

currently only supported by the Java and Fortran front ends, where

10002

this option defaults to true and false respectively.

10003

10004

@item -fcheck-pointer-bounds

10005

@opindex fcheck-pointer-bounds

10006

@opindex fno-check-pointer-bounds

10007

@cindex Pointer Bounds Checker options

10008

Enable Pointer Bounds Checker instrumentation. Each memory reference

10009

is instrumented with checks of the pointer used for memory access against

10010

bounds associated with that pointer.

10011

10012

Currently there

10013

is only an implementation for Intel MPX available, thus x86 GNU/Linux target

10014

and @option{-mmpx} are required to enable this feature.

10015

MPX-based instrumentation requires

10016

a runtime library to enable MPX in hardware and handle bounds

10017

violation signals. By default when @option{-fcheck-pointer-bounds}

10018

and @option{-mmpx} options are used to link a program, the GCC driver

10019

links against the @file{libmpx} and @file{libmpxwrappers} libraries.

10020

Bounds checking on calls to dynamic libraries requires a linker

10021

with @option{-z bndplt} support; if GCC was configured with a linker

10022

without support for this option (including the Gold linker and older

10023

versions of ld), a warning is given if you link with @option{-mmpx}

10024

without also specifying @option{-static}, since the overall effectiveness

10025

of the bounds checking protection is reduced.

10026

See also @option{-static-libmpxwrappers}.

10027

10028

MPX-based instrumentation

10029

may be used for debugging and also may be included in production code

10030

to increase program security. Depending on usage, you may

10031

have different requirements for the runtime library. The current version

10032

of the MPX runtime library is more oriented for use as a debugging

10033

tool. MPX runtime library usage implies @option{-lpthread}. See

10034

also @option{-static-libmpx}. The runtime library behavior can be

10035

influenced using various @env{CHKP_RT_*} environment variables. See

10036

@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler}

10037

for more details.

10038

10039

Generated instrumentation may be controlled by various

10040

@option{-fchkp-*} options and by the @code{bnd_variable_size}

10041

structure field attribute (@pxref{Type Attributes}) and

10042

@code{bnd_legacy}, and @code{bnd_instrument} function attributes

10043

(@pxref{Function Attributes}). GCC also provides a number of built-in

10044

functions for controlling the Pointer Bounds Checker. @xref{Pointer

10045

Bounds Checker builtins}, for more information.

10046

10047

@item -fchkp-check-incomplete-type

10048

@opindex fchkp-check-incomplete-type

10049

@opindex fno-chkp-check-incomplete-type

10050

Generate pointer bounds checks for variables with incomplete type.

10051

Enabled by default.

10052

10053

@item -fchkp-narrow-bounds

10054

@opindex fchkp-narrow-bounds

10055

@opindex fno-chkp-narrow-bounds

10056

Controls bounds used by Pointer Bounds Checker for pointers to object

10057

fields. If narrowing is enabled then field bounds are used. Otherwise

10058

object bounds are used. See also @option{-fchkp-narrow-to-innermost-array}

10059

and @option{-fchkp-first-field-has-own-bounds}. Enabled by default.

10060

10061

@item -fchkp-first-field-has-own-bounds

10062

@opindex fchkp-first-field-has-own-bounds

10063

@opindex fno-chkp-first-field-has-own-bounds

10064

Forces Pointer Bounds Checker to use narrowed bounds for the address of the

10065

first field in the structure. By default a pointer to the first field has

10066

the same bounds as a pointer to the whole structure.

10067

10068

@item -fchkp-narrow-to-innermost-array

10069

@opindex fchkp-narrow-to-innermost-array

10070

@opindex fno-chkp-narrow-to-innermost-array

10071

Forces Pointer Bounds Checker to use bounds of the innermost arrays in

10072

case of nested static array access. By default this option is disabled and

10073

bounds of the outermost array are used.

10074

10075

@item -fchkp-optimize

10076

@opindex fchkp-optimize

10077

@opindex fno-chkp-optimize

10078

Enables Pointer Bounds Checker optimizations. Enabled by default at

10079

optimization levels @option{-O}, @option{-O2}, @option{-O3}.

10080

10081

@item -fchkp-use-fast-string-functions

10082

@opindex fchkp-use-fast-string-functions

10083

@opindex fno-chkp-use-fast-string-functions

10084

Enables use of @code{*_nobnd} versions of string functions (not copying bounds)

10085

by Pointer Bounds Checker. Disabled by default.

10086

10087

@item -fchkp-use-nochk-string-functions

10088

@opindex fchkp-use-nochk-string-functions

10089

@opindex fno-chkp-use-nochk-string-functions

10090

Enables use of @code{*_nochk} versions of string functions (not checking bounds)

10091

by Pointer Bounds Checker. Disabled by default.

10092

10093

@item -fchkp-use-static-bounds

10094

@opindex fchkp-use-static-bounds

10095

@opindex fno-chkp-use-static-bounds

10096

Allow Pointer Bounds Checker to generate static bounds holding

10097

bounds of static variables. Enabled by default.

10098

10099

@item -fchkp-use-static-const-bounds

10100

@opindex fchkp-use-static-const-bounds

10101

@opindex fno-chkp-use-static-const-bounds

10102

Use statically-initialized bounds for constant bounds instead of

10103

generating them each time they are required. By default enabled when

10104

@option{-fchkp-use-static-bounds} is enabled.

10105

10106

@item -fchkp-treat-zero-dynamic-size-as-infinite

10107

@opindex fchkp-treat-zero-dynamic-size-as-infinite

10108

@opindex fno-chkp-treat-zero-dynamic-size-as-infinite

10109

With this option, objects with incomplete type whose

10110

dynamically-obtained size is zero are treated as having infinite size

10111

instead by Pointer Bounds

10112

Checker. This option may be helpful if a program is linked with a library

10113

missing size information for some symbols. Disabled by default.

10114

10115

@item -fchkp-check-read

10116

@opindex fchkp-check-read

10117

@opindex fno-chkp-check-read

10118

Instructs Pointer Bounds Checker to generate checks for all read

10119

accesses to memory. Enabled by default.

10120

10121

@item -fchkp-check-write

10122

@opindex fchkp-check-write

10123

@opindex fno-chkp-check-write

10124

Instructs Pointer Bounds Checker to generate checks for all write

10125

accesses to memory. Enabled by default.

10126

10127

@item -fchkp-store-bounds

10128

@opindex fchkp-store-bounds

10129

@opindex fno-chkp-store-bounds

10130

Instructs Pointer Bounds Checker to generate bounds stores for

10131

pointer writes. Enabled by default.

10132

10133

@item -fchkp-instrument-calls

10134

@opindex fchkp-instrument-calls

10135

@opindex fno-chkp-instrument-calls

10136

Instructs Pointer Bounds Checker to pass pointer bounds to calls.

10137

Enabled by default.

10138

10139

@item -fchkp-instrument-marked-only

10140

@opindex fchkp-instrument-marked-only

10141

@opindex fno-chkp-instrument-marked-only

10142

Instructs Pointer Bounds Checker to instrument only functions

10143

marked with the @code{bnd_instrument} attribute

10144

(@pxref{Function Attributes}). Disabled by default.

10145

10146

@item -fchkp-use-wrappers

10147

@opindex fchkp-use-wrappers

10148

@opindex fno-chkp-use-wrappers

10149

Allows Pointer Bounds Checker to replace calls to built-in functions

10150

with calls to wrapper functions. When @option{-fchkp-use-wrappers}

10151

is used to link a program, the GCC driver automatically links

10152

against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}.

10153

Enabled by default.

10154

10155

@item -fstack-protector

10156

@opindex fstack-protector

10157

Emit extra code to check for buffer overflows, such as stack smashing

10158

attacks. This is done by adding a guard variable to functions with

10159

vulnerable objects. This includes functions that call @code{alloca}, and

10160

functions with buffers larger than 8 bytes. The guards are initialized

10161

when a function is entered and then checked when the function exits.

10162

If a guard check fails, an error message is printed and the program exits.

10163

10164

@item -fstack-protector-all

10165

@opindex fstack-protector-all

10166

Like @option{-fstack-protector} except that all functions are protected.

10167

10168

@item -fstack-protector-strong

10169

@opindex fstack-protector-strong

10170

Like @option{-fstack-protector} but includes additional functions to

10171

be protected --- those that have local array definitions, or have

10172

references to local frame addresses.

10173

10174

@item -fstack-protector-explicit

10175

@opindex fstack-protector-explicit

10176

Like @option{-fstack-protector} but only protects those functions which

10177

have the @code{stack_protect} attribute.

10178

10179

@item -fstack-check

10180

@opindex fstack-check

10181

Generate code to verify that you do not go beyond the boundary of the

10182

stack. You should specify this flag if you are running in an

10183

environment with multiple threads, but you only rarely need to specify it in

10184

a single-threaded environment since stack overflow is automatically

10185

detected on nearly all systems if there is only one stack.

10186

10187

Note that this switch does not actually cause checking to be done; the

10188

operating system or the language runtime must do that. The switch causes

10189

generation of code to ensure that they see the stack being extended.

10190

10191

You can additionally specify a string parameter: @samp{no} means no

10192

checking, @samp{generic} means force the use of old-style checking,

10193

@samp{specific} means use the best checking method and is equivalent

10194

to bare @option{-fstack-check}.

10195

10196

Old-style checking is a generic mechanism that requires no specific

10197

target support in the compiler but comes with the following drawbacks:

10198

10199

@enumerate

10200

@item

10201

Modified allocation strategy for large objects: they are always

10202

allocated dynamically if their size exceeds a fixed threshold.

10203

10204

@item

10205

Fixed limit on the size of the static frame of functions: when it is

10206

topped by a particular function, stack checking is not reliable and

10207

a warning is issued by the compiler.

10208

10209

@item

10210

Inefficiency: because of both the modified allocation strategy and the

10211

generic implementation, code performance is hampered.

10212

@end enumerate

10213

10214

Note that old-style stack checking is also the fallback method for

10215

@samp{specific} if no target support has been added in the compiler.

10216

10217

@item -fstack-limit-register=@var{reg}

10218

@itemx -fstack-limit-symbol=@var{sym}

10219

@itemx -fno-stack-limit

10220

@opindex fstack-limit-register

10221

@opindex fstack-limit-symbol

10222

@opindex fno-stack-limit

10223

Generate code to ensure that the stack does not grow beyond a certain value,

10224

either the value of a register or the address of a symbol. If a larger

10225

stack is required, a signal is raised at run time. For most targets,

10226

the signal is raised before the stack overruns the boundary, so

10227

it is possible to catch the signal without taking special precautions.

10228

10229

For instance, if the stack starts at absolute address @samp{0x80000000}

10230

and grows downwards, you can use the flags

10231

@option{-fstack-limit-symbol=__stack_limit} and

10232

@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit

10233

of 128KB@. Note that this may only work with the GNU linker.

10234

10235

You can locally override stack limit checking by using the

10236

@code{no_stack_limit} function attribute (@pxref{Function Attributes}).

10237

10238

@item -fsplit-stack

10239

@opindex fsplit-stack

10240

Generate code to automatically split the stack before it overflows.

10241

The resulting program has a discontiguous stack which can only

10242

overflow if the program is unable to allocate any more memory. This

10243

is most useful when running threaded programs, as it is no longer

10244

necessary to calculate a good stack size to use for each thread. This

10245

is currently only implemented for the x86 targets running

10246

GNU/Linux.

10247

10248

When code compiled with @option{-fsplit-stack} calls code compiled

10249

without @option{-fsplit-stack}, there may not be much stack space

10250

available for the latter code to run. If compiling all code,

10251

including library code, with @option{-fsplit-stack} is not an option,

10252

then the linker can fix up these calls so that the code compiled

10253

without @option{-fsplit-stack} always has a large stack. Support for

10254

this is implemented in the gold linker in GNU binutils release 2.21

10255

and later.

10256

10257

@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]}

10258

@opindex fvtable-verify

10259

This option is only available when compiling C++ code.

10260

It turns on (or off, if using @option{-fvtable-verify=none}) the security

10261

feature that verifies at run time, for every virtual call, that

10262

the vtable pointer through which the call is made is valid for the type of

10263

the object, and has not been corrupted or overwritten. If an invalid vtable

10264

pointer is detected at run time, an error is reported and execution of the

10265

program is immediately halted.

10266

10267

This option causes run-time data structures to be built at program startup,

10268

which are used for verifying the vtable pointers.

10269

The options @samp{std} and @samp{preinit}

10270

control the timing of when these data structures are built. In both cases the

10271

data structures are built before execution reaches @code{main}. Using

10272

@option{-fvtable-verify=std} causes the data structures to be built after

10273

shared libraries have been loaded and initialized.

10274

@option{-fvtable-verify=preinit} causes them to be built before shared

10275

libraries have been loaded and initialized.

10276

10277

If this option appears multiple times in the command line with different

10278

values specified, @samp{none} takes highest priority over both @samp{std} and

10279

@samp{preinit}; @samp{preinit} takes priority over @samp{std}.

10280

10281

@item -fvtv-debug

10282

@opindex fvtv-debug

10283

When used in conjunction with @option{-fvtable-verify=std} or

10284

@option{-fvtable-verify=preinit}, causes debug versions of the

10285

runtime functions for the vtable verification feature to be called.

10286

This flag also causes the compiler to log information about which

10287

vtable pointers it finds for each class.

10288

This information is written to a file named @file{vtv_set_ptr_data.log}

10289

in the directory named by the environment variable @env{VTV_LOGS_DIR}

10290

if that is defined or the current working directory otherwise.

10291

10292

Note: This feature @emph{appends} data to the log file. If you want a fresh log

10293

file, be sure to delete any existing one.

10294

10295

@item -fvtv-counts

10296

@opindex fvtv-counts

10297

This is a debugging flag. When used in conjunction with

10298

@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this

10299

causes the compiler to keep track of the total number of virtual calls

10300

it encounters and the number of verifications it inserts. It also

10301

counts the number of calls to certain run-time library functions

10302

that it inserts and logs this information for each compilation unit.

10303

The compiler writes this information to a file named

10304

@file{vtv_count_data.log} in the directory named by the environment

10305

variable @env{VTV_LOGS_DIR} if that is defined or the current working

10306

directory otherwise. It also counts the size of the vtable pointer sets

10307

for each class, and writes this information to @file{vtv_class_set_sizes.log}

10308

in the same directory.

10309

10310

Note: This feature @emph{appends} data to the log files. To get fresh log

10311

files, be sure to delete any existing ones.

10312

10313

@item -finstrument-functions

10314

@opindex finstrument-functions

10315

Generate instrumentation calls for entry and exit to functions. Just

10316

after function entry and just before function exit, the following

10317

profiling functions are called with the address of the current

10318

function and its call site. (On some platforms,

10319

@code{__builtin_return_address} does not work beyond the current

10320

function, so the call site information may not be available to the

10321

profiling functions otherwise.)

10322

10323

@smallexample

10324

void __cyg_profile_func_enter (void *this_fn,

10325

void *call_site);

10326

void __cyg_profile_func_exit (void *this_fn,

10327

void *call_site);

10328

@end smallexample

10329

10330

The first argument is the address of the start of the current function,

10331

which may be looked up exactly in the symbol table.

10332

10333

This instrumentation is also done for functions expanded inline in other

10334

functions. The profiling calls indicate where, conceptually, the

10335

inline function is entered and exited. This means that addressable

10336

versions of such functions must be available. If all your uses of a

10337

function are expanded inline, this may mean an additional expansion of

10338

code size. If you use @code{extern inline} in your C code, an

10339

addressable version of such functions must be provided. (This is

10340

normally the case anyway, but if you get lucky and the optimizer always

10341

expands the functions inline, you might have gotten away without

10342

providing static copies.)

10343

10344

A function may be given the attribute @code{no_instrument_function}, in

10345

which case this instrumentation is not done. This can be used, for

10346

example, for the profiling functions listed above, high-priority

10347

interrupt routines, and any functions from which the profiling functions

10348

cannot safely be called (perhaps signal handlers, if the profiling

10349

routines generate output or allocate memory).

10350

10351

@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}

10352

@opindex finstrument-functions-exclude-file-list

10353

10354

Set the list of functions that are excluded from instrumentation (see

10355

the description of @option{-finstrument-functions}). If the file that

10356

contains a function definition matches with one of @var{file}, then

10357

that function is not instrumented. The match is done on substrings:

10358

if the @var{file} parameter is a substring of the file name, it is

10359

considered to be a match.

10360

10361

For example:

10362

10363

@smallexample

10364

-finstrument-functions-exclude-file-list=/bits/stl,include/sys

10365

@end smallexample

10366

10367

@noindent

10368

excludes any inline function defined in files whose pathnames

10369

contain @file{/bits/stl} or @file{include/sys}.

10370

10371

If, for some reason, you want to include letter @samp{,} in one of

10372

@var{sym}, write @samp{\,}. For example,

10373

@option{-finstrument-functions-exclude-file-list='\,\,tmp'}

10374

(note the single quote surrounding the option).

10375

10376

@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}

10377

@opindex finstrument-functions-exclude-function-list

10378

10379

This is similar to @option{-finstrument-functions-exclude-file-list},

10380

but this option sets the list of function names to be excluded from

10381

instrumentation. The function name to be matched is its user-visible

10382

name, such as @code{vector<int> blah(const vector<int> &)}, not the

10383

internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The

10384

match is done on substrings: if the @var{sym} parameter is a substring

10385

of the function name, it is considered to be a match. For C99 and C++

10386

extended identifiers, the function name must be given in UTF-8, not

10387

using universal character names.

10388

10389

@end table

10390

10391

10392

@node Preprocessor Options

10393

@section Options Controlling the Preprocessor

10394

@cindex preprocessor options

10395

@cindex options, preprocessor

10396

10397

These options control the C preprocessor, which is run on each C source

10398

file before actual compilation.

10399

10400

If you use the @option{-E} option, nothing is done except preprocessing.

10401

Some of these options make sense only together with @option{-E} because

10402

they cause the preprocessor output to be unsuitable for actual

10403

compilation.

10404

10405

@table @gcctabopt

10406

@item -Wp,@var{option}

10407

@opindex Wp

10408

You can use @option{-Wp,@var{option}} to bypass the compiler driver

10409

and pass @var{option} directly through to the preprocessor. If

10410

@var{option} contains commas, it is split into multiple options at the

10411

commas. However, many options are modified, translated or interpreted

10412

by the compiler driver before being passed to the preprocessor, and

10413

@option{-Wp} forcibly bypasses this phase. The preprocessor's direct

10414

interface is undocumented and subject to change, so whenever possible

10415

you should avoid using @option{-Wp} and let the driver handle the

10416

options instead.

10417

10418

@item -Xpreprocessor @var{option}

10419

@opindex Xpreprocessor

10420

Pass @var{option} as an option to the preprocessor. You can use this to

10421

supply system-specific preprocessor options that GCC does not

10422

recognize.

10423

10424

If you want to pass an option that takes an argument, you must use

10425

@option{-Xpreprocessor} twice, once for the option and once for the argument.

10426

10427

@item -no-integrated-cpp

10428

@opindex no-integrated-cpp

10429

Perform preprocessing as a separate pass before compilation.

10430

By default, GCC performs preprocessing as an integrated part of

10431

input tokenization and parsing.

10432

If this option is provided, the appropriate language front end

10433

(@command{cc1}, @command{cc1plus}, or @command{cc1obj} for C, C++,

10434

and Objective-C, respectively) is instead invoked twice,

10435

once for preprocessing only and once for actual compilation

10436

of the preprocessed input.

10437

This option may be useful in conjunction with the @option{-B} or

10438

@option{-wrapper} options to specify an alternate preprocessor or

10439

perform additional processing of the program source between

10440

normal preprocessing and compilation.

10441

@end table

10442

10443

@include cppopts.texi

10444

10445

@node Assembler Options

10446

@section Passing Options to the Assembler

10447

10448

@c prevent bad page break with this line

10449

You can pass options to the assembler.

10450

10451

@table @gcctabopt

10452

@item -Wa,@var{option}

10453

@opindex Wa

10454

Pass @var{option} as an option to the assembler. If @var{option}

10455

contains commas, it is split into multiple options at the commas.

10456

10457

@item -Xassembler @var{option}

10458

@opindex Xassembler

10459

Pass @var{option} as an option to the assembler. You can use this to

10460

supply system-specific assembler options that GCC does not

10461

recognize.

10462

10463

If you want to pass an option that takes an argument, you must use

10464

@option{-Xassembler} twice, once for the option and once for the argument.

10465

10466

@end table

10467

10468

@node Link Options

10469

@section Options for Linking

10470

@cindex link options

10471

@cindex options, linking

10472

10473

These options come into play when the compiler links object files into

10474

an executable output file. They are meaningless if the compiler is

10475

not doing a link step.

10476

10477

@table @gcctabopt

10478

@cindex file names

10479

@item @var{object-file-name}

10480

A file name that does not end in a special recognized suffix is

10481

considered to name an object file or library. (Object files are

10482

distinguished from libraries by the linker according to the file

10483

contents.) If linking is done, these object files are used as input

10484

to the linker.

10485

10486

@item -c

10487

@itemx -S

10488

@itemx -E

10489

@opindex c

10490

@opindex S

10491

@opindex E

10492

If any of these options is used, then the linker is not run, and

10493

object file names should not be used as arguments. @xref{Overall

10494

Options}.

10495

10496

@item -fuse-ld=bfd

10497

@opindex fuse-ld=bfd

10498

Use the @command{bfd} linker instead of the default linker.

10499

10500

@item -fuse-ld=gold

10501

@opindex fuse-ld=gold

10502

Use the @command{gold} linker instead of the default linker.

10503

10504

@cindex Libraries

10505

@item -l@var{library}

10506

@itemx -l @var{library}

10507

@opindex l

10508

Search the library named @var{library} when linking. (The second

10509

alternative with the library as a separate argument is only for

10510

POSIX compliance and is not recommended.)

10511

10512

It makes a difference where in the command you write this option; the

10513

linker searches and processes libraries and object files in the order they

10514

are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}

10515

after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers

10516

to functions in @samp{z}, those functions may not be loaded.

10517

10518

The linker searches a standard list of directories for the library,

10519

which is actually a file named @file{lib@var{library}.a}. The linker

10520

then uses this file as if it had been specified precisely by name.

10521

10522

The directories searched include several standard system directories

10523

plus any that you specify with @option{-L}.

10524

10525

Normally the files found this way are library files---archive files

10526

whose members are object files. The linker handles an archive file by

10527

scanning through it for members which define symbols that have so far

10528

been referenced but not defined. But if the file that is found is an

10529

ordinary object file, it is linked in the usual fashion. The only

10530

difference between using an @option{-l} option and specifying a file name

10531

is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}

10532

and searches several directories.

10533

10534

@item -lobjc

10535

@opindex lobjc

10536

You need this special case of the @option{-l} option in order to

10537

link an Objective-C or Objective-C++ program.

10538

10539

@item -nostartfiles

10540

@opindex nostartfiles

10541

Do not use the standard system startup files when linking.

10542

The standard system libraries are used normally, unless @option{-nostdlib}

10543

or @option{-nodefaultlibs} is used.

10544

10545

@item -nodefaultlibs

10546

@opindex nodefaultlibs

10547

Do not use the standard system libraries when linking.

10548

Only the libraries you specify are passed to the linker, and options

10549

specifying linkage of the system libraries, such as @option{-static-libgcc}

10550

or @option{-shared-libgcc}, are ignored.

10551

The standard startup files are used normally, unless @option{-nostartfiles}

10552

is used.

10553

10554

The compiler may generate calls to @code{memcmp},

10555

@code{memset}, @code{memcpy} and @code{memmove}.

10556

These entries are usually resolved by entries in

10557

libc. These entry points should be supplied through some other

10558

mechanism when this option is specified.

10559

10560

@item -nostdlib

10561

@opindex nostdlib

10562

Do not use the standard system startup files or libraries when linking.

10563

No startup files and only the libraries you specify are passed to

10564

the linker, and options specifying linkage of the system libraries, such as

10565

@option{-static-libgcc} or @option{-shared-libgcc}, are ignored.

10566

10567

The compiler may generate calls to @code{memcmp}, @code{memset},

10568

@code{memcpy} and @code{memmove}.

10569

These entries are usually resolved by entries in

10570

libc. These entry points should be supplied through some other

10571

mechanism when this option is specified.

10572

10573

@cindex @option{-lgcc}, use with @option{-nostdlib}

10574

@cindex @option{-nostdlib} and unresolved references

10575

@cindex unresolved references and @option{-nostdlib}

10576

@cindex @option{-lgcc}, use with @option{-nodefaultlibs}

10577

@cindex @option{-nodefaultlibs} and unresolved references

10578

@cindex unresolved references and @option{-nodefaultlibs}

10579

One of the standard libraries bypassed by @option{-nostdlib} and

10580

@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines

10581

which GCC uses to overcome shortcomings of particular machines, or special

10582

needs for some languages.

10583

(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler

10584

Collection (GCC) Internals},

10585

for more discussion of @file{libgcc.a}.)

10586

In most cases, you need @file{libgcc.a} even when you want to avoid

10587

other standard libraries. In other words, when you specify @option{-nostdlib}

10588

or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.

10589

This ensures that you have no unresolved references to internal GCC

10590

library subroutines.

10591

(An example of such an internal subroutine is @code{__main}, used to ensure C++

10592

constructors are called; @pxref{Collect2,,@code{collect2}, gccint,

10593

GNU Compiler Collection (GCC) Internals}.)

10594

10595

@item -pie

10596

@opindex pie

10597

Produce a position independent executable on targets that support it.

10598

For predictable results, you must also specify the same set of options

10599

used for compilation (@option{-fpie}, @option{-fPIE},

10600

or model suboptions) when you specify this linker option.

10601

10602

@item -no-pie

10603

@opindex no-pie

10604

Don't produce a position independent executable.

10605

10606

@item -rdynamic

10607

@opindex rdynamic

10608

Pass the flag @option{-export-dynamic} to the ELF linker, on targets

10609

that support it. This instructs the linker to add all symbols, not

10610

only used ones, to the dynamic symbol table. This option is needed

10611

for some uses of @code{dlopen} or to allow obtaining backtraces

10612

from within a program.

10613

10614

@item -s

10615

@opindex s

10616

Remove all symbol table and relocation information from the executable.

10617

10618

@item -static

10619

@opindex static

10620

On systems that support dynamic linking, this prevents linking with the shared

10621

libraries. On other systems, this option has no effect.

10622

10623

@item -shared

10624

@opindex shared

10625

Produce a shared object which can then be linked with other objects to

10626

form an executable. Not all systems support this option. For predictable

10627

results, you must also specify the same set of options used for compilation

10628

(@option{-fpic}, @option{-fPIC}, or model suboptions) when

10629

you specify this linker option.@footnote{On some systems, @samp{gcc -shared}

10630

needs to build supplementary stub code for constructors to work. On

10631

multi-libbed systems, @samp{gcc -shared} must select the correct support

10632

libraries to link against. Failing to supply the correct flags may lead

10633

to subtle defects. Supplying them in cases where they are not necessary

10634

is innocuous.}

10635

10636

@item -shared-libgcc

10637

@itemx -static-libgcc

10638

@opindex shared-libgcc

10639

@opindex static-libgcc

10640

On systems that provide @file{libgcc} as a shared library, these options

10641

force the use of either the shared or static version, respectively.

10642

If no shared version of @file{libgcc} was built when the compiler was

10643

configured, these options have no effect.

10644

10645

There are several situations in which an application should use the

10646

shared @file{libgcc} instead of the static version. The most common

10647

of these is when the application wishes to throw and catch exceptions

10648

across different shared libraries. In that case, each of the libraries

10649

as well as the application itself should use the shared @file{libgcc}.

10650

10651

Therefore, the G++ and GCJ drivers automatically add

10652

@option{-shared-libgcc} whenever you build a shared library or a main

10653

executable, because C++ and Java programs typically use exceptions, so

10654

this is the right thing to do.

10655

10656

If, instead, you use the GCC driver to create shared libraries, you may

10657

find that they are not always linked with the shared @file{libgcc}.

10658

If GCC finds, at its configuration time, that you have a non-GNU linker

10659

or a GNU linker that does not support option @option{--eh-frame-hdr},

10660

it links the shared version of @file{libgcc} into shared libraries

10661

by default. Otherwise, it takes advantage of the linker and optimizes

10662

away the linking with the shared version of @file{libgcc}, linking with

10663

the static version of libgcc by default. This allows exceptions to

10664

propagate through such shared libraries, without incurring relocation

10665

costs at library load time.

10666

10667

However, if a library or main executable is supposed to throw or catch

10668

exceptions, you must link it using the G++ or GCJ driver, as appropriate

10669

for the languages used in the program, or using the option

10670

@option{-shared-libgcc}, such that it is linked with the shared

10671

@file{libgcc}.

10672

10673

@item -static-libasan

10674

@opindex static-libasan

10675

When the @option{-fsanitize=address} option is used to link a program,

10676

the GCC driver automatically links against @option{libasan}. If

10677

@file{libasan} is available as a shared library, and the @option{-static}

10678

option is not used, then this links against the shared version of

10679

@file{libasan}. The @option{-static-libasan} option directs the GCC

10680

driver to link @file{libasan} statically, without necessarily linking

10681

other libraries statically.

10682

10683

@item -static-libtsan

10684

@opindex static-libtsan

10685

When the @option{-fsanitize=thread} option is used to link a program,

10686

the GCC driver automatically links against @option{libtsan}. If

10687

@file{libtsan} is available as a shared library, and the @option{-static}

10688

option is not used, then this links against the shared version of

10689

@file{libtsan}. The @option{-static-libtsan} option directs the GCC

10690

driver to link @file{libtsan} statically, without necessarily linking

10691

other libraries statically.

10692

10693

@item -static-liblsan

10694

@opindex static-liblsan

10695

When the @option{-fsanitize=leak} option is used to link a program,

10696

the GCC driver automatically links against @option{liblsan}. If

10697

@file{liblsan} is available as a shared library, and the @option{-static}

10698

option is not used, then this links against the shared version of

10699

@file{liblsan}. The @option{-static-liblsan} option directs the GCC

10700

driver to link @file{liblsan} statically, without necessarily linking

10701

other libraries statically.

10702

10703

@item -static-libubsan

10704

@opindex static-libubsan

10705

When the @option{-fsanitize=undefined} option is used to link a program,

10706

the GCC driver automatically links against @option{libubsan}. If

10707

@file{libubsan} is available as a shared library, and the @option{-static}

10708

option is not used, then this links against the shared version of

10709

@file{libubsan}. The @option{-static-libubsan} option directs the GCC

10710

driver to link @file{libubsan} statically, without necessarily linking

10711

other libraries statically.

10712

10713

@item -static-libmpx

10714

@opindex static-libmpx

10715

When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are

10716

used to link a program, the GCC driver automatically links against

10717

@file{libmpx}. If @file{libmpx} is available as a shared library,

10718

and the @option{-static} option is not used, then this links against

10719

the shared version of @file{libmpx}. The @option{-static-libmpx}

10720

option directs the GCC driver to link @file{libmpx} statically,

10721

without necessarily linking other libraries statically.

10722

10723

@item -static-libmpxwrappers

10724

@opindex static-libmpxwrappers

10725

When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are used

10726

to link a program without also using @option{-fno-chkp-use-wrappers}, the

10727

GCC driver automatically links against @file{libmpxwrappers}. If

10728

@file{libmpxwrappers} is available as a shared library, and the

10729

@option{-static} option is not used, then this links against the shared

10730

version of @file{libmpxwrappers}. The @option{-static-libmpxwrappers}

10731

option directs the GCC driver to link @file{libmpxwrappers} statically,

10732

without necessarily linking other libraries statically.

10733

10734

@item -static-libstdc++

10735

@opindex static-libstdc++

10736

When the @command{g++} program is used to link a C++ program, it

10737

normally automatically links against @option{libstdc++}. If

10738

@file{libstdc++} is available as a shared library, and the

10739

@option{-static} option is not used, then this links against the

10740

shared version of @file{libstdc++}. That is normally fine. However, it

10741

is sometimes useful to freeze the version of @file{libstdc++} used by

10742

the program without going all the way to a fully static link. The

10743

@option{-static-libstdc++} option directs the @command{g++} driver to

10744

link @file{libstdc++} statically, without necessarily linking other

10745

libraries statically.

10746

10747

@item -symbolic

10748

@opindex symbolic

10749

Bind references to global symbols when building a shared object. Warn

10750

about any unresolved references (unless overridden by the link editor

10751

option @option{-Xlinker -z -Xlinker defs}). Only a few systems support

10752

this option.

10753

10754

@item -T @var{script}

10755

@opindex T

10756

@cindex linker script

10757

Use @var{script} as the linker script. This option is supported by most

10758

systems using the GNU linker. On some targets, such as bare-board

10759

targets without an operating system, the @option{-T} option may be required

10760

when linking to avoid references to undefined symbols.

10761

10762

@item -Xlinker @var{option}

10763

@opindex Xlinker

10764

Pass @var{option} as an option to the linker. You can use this to

10765

supply system-specific linker options that GCC does not recognize.

10766

10767

If you want to pass an option that takes a separate argument, you must use

10768

@option{-Xlinker} twice, once for the option and once for the argument.

10769

For example, to pass @option{-assert definitions}, you must write

10770

@option{-Xlinker -assert -Xlinker definitions}. It does not work to write

10771

@option{-Xlinker "-assert definitions"}, because this passes the entire

10772

string as a single argument, which is not what the linker expects.

10773

10774

When using the GNU linker, it is usually more convenient to pass

10775

arguments to linker options using the @option{@var{option}=@var{value}}

10776

syntax than as separate arguments. For example, you can specify

10777

@option{-Xlinker -Map=output.map} rather than

10778

@option{-Xlinker -Map -Xlinker output.map}. Other linkers may not support

10779

this syntax for command-line options.

10780

10781

@item -Wl,@var{option}

10782

@opindex Wl

10783

Pass @var{option} as an option to the linker. If @var{option} contains

10784

commas, it is split into multiple options at the commas. You can use this

10785

syntax to pass an argument to the option.

10786

For example, @option{-Wl,-Map,output.map} passes @option{-Map output.map} to the

10787

linker. When using the GNU linker, you can also get the same effect with

10788

@option{-Wl,-Map=output.map}.

10789

10790

@item -u @var{symbol}

10791

@opindex u

10792

Pretend the symbol @var{symbol} is undefined, to force linking of

10793

library modules to define it. You can use @option{-u} multiple times with

10794

different symbols to force loading of additional library modules.

10795

10796

@item -z @var{keyword}

10797

@opindex z

10798

@option{-z} is passed directly on to the linker along with the keyword

10799

@var{keyword}. See the section in the documentation of your linker for

10800

permitted values and their meanings.

10801

@end table

10802

10803

@node Directory Options

10804

@section Options for Directory Search

10805

@cindex directory options

10806

@cindex options, directory search

10807

@cindex search path

10808

10809

These options specify directories to search for header files, for

10810

libraries and for parts of the compiler:

10811

10812

@table @gcctabopt

10813

@item -I@var{dir}

10814

@opindex I

10815

Add the directory @var{dir} to the head of the list of directories to be

10816

searched for header files. This can be used to override a system header

10817

file, substituting your own version, since these directories are

10818

searched before the system header file directories. However, you should

10819

not use this option to add directories that contain vendor-supplied

10820

system header files (use @option{-isystem} for that). If you use more than

10821

one @option{-I} option, the directories are scanned in left-to-right

10822

order; the standard system directories come after.

10823

10824

If a standard system include directory, or a directory specified with

10825

@option{-isystem}, is also specified with @option{-I}, the @option{-I}

10826

option is ignored. The directory is still searched but as a

10827

system directory at its normal position in the system include chain.

10828

This is to ensure that GCC's procedure to fix buggy system headers and

10829

the ordering for the @code{include_next} directive are not inadvertently changed.

10830

If you really need to change the search order for system directories,

10831

use the @option{-nostdinc} and/or @option{-isystem} options.

10832

10833

@item -iplugindir=@var{dir}

10834

@opindex iplugindir=

10835

Set the directory to search for plugins that are passed

10836

by @option{-fplugin=@var{name}} instead of

10837

@option{-fplugin=@var{path}/@var{name}.so}. This option is not meant

10838

to be used by the user, but only passed by the driver.

10839

10840

@item -iquote@var{dir}

10841

@opindex iquote

10842

Add the directory @var{dir} to the head of the list of directories to

10843

be searched for header files only for the case of @code{#include

10844

"@var{file}"}; they are not searched for @code{#include <@var{file}>},

10845

otherwise just like @option{-I}.

10846

10847

@item -L@var{dir}

10848

@opindex L

10849

Add directory @var{dir} to the list of directories to be searched

10850

for @option{-l}.

10851

10852

@item -B@var{prefix}

10853

@opindex B

10854

This option specifies where to find the executables, libraries,

10855

include files, and data files of the compiler itself.

10856

10857

The compiler driver program runs one or more of the subprograms

10858

@command{cpp}, @command{cc1}, @command{as} and @command{ld}. It tries

10859

@var{prefix} as a prefix for each program it tries to run, both with and

10860

without @samp{@var{machine}/@var{version}/} for the corresponding target

10861

machine and compiler version.

10862

10863

For each subprogram to be run, the compiler driver first tries the

10864

@option{-B} prefix, if any. If that name is not found, or if @option{-B}

10865

is not specified, the driver tries two standard prefixes,

10866

@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of

10867

those results in a file name that is found, the unmodified program

10868

name is searched for using the directories specified in your

10869

@env{PATH} environment variable.

10870

10871

The compiler checks to see if the path provided by @option{-B}

10872

refers to a directory, and if necessary it adds a directory

10873

separator character at the end of the path.

10874

10875

@option{-B} prefixes that effectively specify directory names also apply

10876

to libraries in the linker, because the compiler translates these

10877

options into @option{-L} options for the linker. They also apply to

10878

include files in the preprocessor, because the compiler translates these

10879

options into @option{-isystem} options for the preprocessor. In this case,

10880

the compiler appends @samp{include} to the prefix.

10881

10882

The runtime support file @file{libgcc.a} can also be searched for using

10883

the @option{-B} prefix, if needed. If it is not found there, the two

10884

standard prefixes above are tried, and that is all. The file is left

10885

out of the link if it is not found by those means.

10886

10887

Another way to specify a prefix much like the @option{-B} prefix is to use

10888

the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment

10889

Variables}.

10890

10891

As a special kludge, if the path provided by @option{-B} is

10892

@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to

10893

9, then it is replaced by @file{[dir/]include}. This is to help

10894

with boot-strapping the compiler.

10895

10896

@item -no-canonical-prefixes

10897

@opindex no-canonical-prefixes

10898

Do not expand any symbolic links, resolve references to @samp{/../}

10899

or @samp{/./}, or make the path absolute when generating a relative

10900

prefix.

10901

10902

@item --sysroot=@var{dir}

10903

@opindex sysroot

10904

Use @var{dir} as the logical root directory for headers and libraries.

10905

For example, if the compiler normally searches for headers in

10906

@file{/usr/include} and libraries in @file{/usr/lib}, it instead

10907

searches @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.

10908

10909

If you use both this option and the @option{-isysroot} option, then

10910

the @option{--sysroot} option applies to libraries, but the

10911

@option{-isysroot} option applies to header files.

10912

10913

The GNU linker (beginning with version 2.16) has the necessary support

10914

for this option. If your linker does not support this option, the

10915

header file aspect of @option{--sysroot} still works, but the

10916

library aspect does not.

10917

10918

@item --no-sysroot-suffix

10919

@opindex no-sysroot-suffix

10920

For some targets, a suffix is added to the root directory specified

10921

with @option{--sysroot}, depending on the other options used, so that

10922

headers may for example be found in

10923

@file{@var{dir}/@var{suffix}/usr/include} instead of

10924

@file{@var{dir}/usr/include}. This option disables the addition of

10925

such a suffix.

10926

10927

@item -I-

10928

@opindex I-

10929

This option has been deprecated. Please use @option{-iquote} instead for

10930

@option{-I} directories before the @option{-I-} and remove the @option{-I-}

10931

option.

10932

Any directories you specify with @option{-I} options before the @option{-I-}

10933

option are searched only for the case of @code{#include "@var{file}"};

10934

they are not searched for @code{#include <@var{file}>}.

10935

10936

If additional directories are specified with @option{-I} options after

10937

the @option{-I-} option, these directories are searched for all @code{#include}

10938

directives. (Ordinarily @emph{all} @option{-I} directories are used

10939

this way.)

10940

10941

In addition, the @option{-I-} option inhibits the use of the current

10942

directory (where the current input file came from) as the first search

10943

directory for @code{#include "@var{file}"}. There is no way to

10944

override this effect of @option{-I-}. With @option{-I.} you can specify

10945

searching the directory that is current when the compiler is

10946

invoked. That is not exactly the same as what the preprocessor does

10947

by default, but it is often satisfactory.

10948

10949

@option{-I-} does not inhibit the use of the standard system directories

10950

for header files. Thus, @option{-I-} and @option{-nostdinc} are

10951

independent.

10952

@end table

10953

10954

@node Code Gen Options

10955

@section Options for Code Generation Conventions

10956

@cindex code generation conventions

10957

@cindex options, code generation

10958

@cindex run-time options

10959

10960

These machine-independent options control the interface conventions

10961

used in code generation.

10962

10963

Most of them have both positive and negative forms; the negative form

10964

of @option{-ffoo} is @option{-fno-foo}. In the table below, only

10965

one of the forms is listed---the one that is not the default. You

10966

can figure out the other form by either removing @samp{no-} or adding

10967

it.

10968

10969

@table @gcctabopt

10970

@item -fstack-reuse=@var{reuse-level}

10971

@opindex fstack_reuse

10972

This option controls stack space reuse for user declared local/auto variables

10973

and compiler generated temporaries. @var{reuse_level} can be @samp{all},

10974

@samp{named_vars}, or @samp{none}. @samp{all} enables stack reuse for all

10975

local variables and temporaries, @samp{named_vars} enables the reuse only for

10976

user defined local variables with names, and @samp{none} disables stack reuse

10977

completely. The default value is @samp{all}. The option is needed when the

10978

program extends the lifetime of a scoped local variable or a compiler generated

10979

temporary beyond the end point defined by the language. When a lifetime of

10980

a variable ends, and if the variable lives in memory, the optimizing compiler

10981

has the freedom to reuse its stack space with other temporaries or scoped

10982

local variables whose live range does not overlap with it. Legacy code extending

10983

local lifetime is likely to break with the stack reuse optimization.

10984

10985

For example,

10986

10987

@smallexample

10988

int *p;

10989

@{

10990

int local1;

10991

10992

p = &local1;

10993

local1 = 10;

10994

....

10995

@}

10996

@{

10997

int local2;

10998

local2 = 20;

10999

...

11000

@}

11001

11002

if (*p == 10) // out of scope use of local1

11003

@{

11004

11005

@}

11006

@end smallexample

11007

11008

Another example:

11009

@smallexample

11010

11011

struct A

11012

@{

11013

A(int k) : i(k), j(k) @{ @}

11014

int i;

11015

int j;

11016

@};

11017

11018

A *ap;

11019

11020

void foo(const A& ar)

11021

@{

11022

ap = &ar;

11023

@}

11024

11025

void bar()

11026

@{

11027

foo(A(10)); // temp object's lifetime ends when foo returns

11028

11029

@{

11030

A a(20);

11031

....

11032

@}

11033

ap->i+= 10; // ap references out of scope temp whose space

11034

// is reused with a. What is the value of ap->i?

11035

@}

11036

11037

@end smallexample

11038

11039

The lifetime of a compiler generated temporary is well defined by the C++

11040

standard. When a lifetime of a temporary ends, and if the temporary lives

11041

in memory, the optimizing compiler has the freedom to reuse its stack

11042

space with other temporaries or scoped local variables whose live range

11043

does not overlap with it. However some of the legacy code relies on

11044

the behavior of older compilers in which temporaries' stack space is

11045

not reused, the aggressive stack reuse can lead to runtime errors. This

11046

option is used to control the temporary stack reuse optimization.

11047

11048

@item -ftrapv

11049

@opindex ftrapv

11050

This option generates traps for signed overflow on addition, subtraction,

11051

multiplication operations.

11052

The options @option{-ftrapv} and @option{-fwrapv} override each other, so using

11053

@option{-ftrapv} @option{-fwrapv} on the command-line results in

11054

@option{-fwrapv} being effective. Note that only active options override, so

11055

using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line

11056

results in @option{-ftrapv} being effective.

11057

11058

@item -fwrapv

11059

@opindex fwrapv

11060

This option instructs the compiler to assume that signed arithmetic

11061

overflow of addition, subtraction and multiplication wraps around

11062

using twos-complement representation. This flag enables some optimizations

11063

and disables others. This option is enabled by default for the Java

11064

front end, as required by the Java language specification.

11065

The options @option{-ftrapv} and @option{-fwrapv} override each other, so using

11066

@option{-ftrapv} @option{-fwrapv} on the command-line results in

11067

@option{-fwrapv} being effective. Note that only active options override, so

11068

using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line

11069

results in @option{-ftrapv} being effective.

11070

11071

@item -fexceptions

11072

@opindex fexceptions

11073

Enable exception handling. Generates extra code needed to propagate

11074

exceptions. For some targets, this implies GCC generates frame

11075

unwind information for all functions, which can produce significant data

11076

size overhead, although it does not affect execution. If you do not

11077

specify this option, GCC enables it by default for languages like

11078

C++ that normally require exception handling, and disables it for

11079

languages like C that do not normally require it. However, you may need

11080

to enable this option when compiling C code that needs to interoperate

11081

properly with exception handlers written in C++. You may also wish to

11082

disable this option if you are compiling older C++ programs that don't

11083

use exception handling.

11084

11085

@item -fnon-call-exceptions

11086

@opindex fnon-call-exceptions

11087

Generate code that allows trapping instructions to throw exceptions.

11088

Note that this requires platform-specific runtime support that does

11089

not exist everywhere. Moreover, it only allows @emph{trapping}

11090

instructions to throw exceptions, i.e.@: memory references or floating-point

11091

instructions. It does not allow exceptions to be thrown from

11092

arbitrary signal handlers such as @code{SIGALRM}.

11093

11094

@item -fdelete-dead-exceptions

11095

@opindex fdelete-dead-exceptions

11096

Consider that instructions that may throw exceptions but don't otherwise

11097

contribute to the execution of the program can be optimized away.

11098

This option is enabled by default for the Ada front end, as permitted by

11099

the Ada language specification.

11100

Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels.

11101

11102

@item -funwind-tables

11103

@opindex funwind-tables

11104

Similar to @option{-fexceptions}, except that it just generates any needed

11105

static data, but does not affect the generated code in any other way.

11106

You normally do not need to enable this option; instead, a language processor

11107

that needs this handling enables it on your behalf.

11108

11109

@item -fasynchronous-unwind-tables

11110

@opindex fasynchronous-unwind-tables

11111

Generate unwind table in DWARF format, if supported by target machine. The

11112

table is exact at each instruction boundary, so it can be used for stack

11113

unwinding from asynchronous events (such as debugger or garbage collector).

11114

11115

@item -fno-gnu-unique

11116

@opindex fno-gnu-unique

11117

On systems with recent GNU assembler and C library, the C++ compiler

11118

uses the @code{STB_GNU_UNIQUE} binding to make sure that definitions

11119

of template static data members and static local variables in inline

11120

functions are unique even in the presence of @code{RTLD_LOCAL}; this

11121

is necessary to avoid problems with a library used by two different

11122

@code{RTLD_LOCAL} plugins depending on a definition in one of them and

11123

therefore disagreeing with the other one about the binding of the

11124

symbol. But this causes @code{dlclose} to be ignored for affected

11125

DSOs; if your program relies on reinitialization of a DSO via

11126

@code{dlclose} and @code{dlopen}, you can use

11127

@option{-fno-gnu-unique}.

11128

11129

@item -fpcc-struct-return

11130

@opindex fpcc-struct-return

11131

Return ``short'' @code{struct} and @code{union} values in memory like

11132

longer ones, rather than in registers. This convention is less

11133

efficient, but it has the advantage of allowing intercallability between

11134

GCC-compiled files and files compiled with other compilers, particularly

11135

the Portable C Compiler (pcc).

11136

11137

The precise convention for returning structures in memory depends

11138

on the target configuration macros.

11139

11140

Short structures and unions are those whose size and alignment match

11141

that of some integer type.

11142

11143

@strong{Warning:} code compiled with the @option{-fpcc-struct-return}

11144

switch is not binary compatible with code compiled with the

11145

@option{-freg-struct-return} switch.

11146

Use it to conform to a non-default application binary interface.

11147

11148

@item -freg-struct-return

11149

@opindex freg-struct-return

11150

Return @code{struct} and @code{union} values in registers when possible.

11151

This is more efficient for small structures than

11152

@option{-fpcc-struct-return}.

11153

11154

If you specify neither @option{-fpcc-struct-return} nor

11155

@option{-freg-struct-return}, GCC defaults to whichever convention is

11156

standard for the target. If there is no standard convention, GCC

11157

defaults to @option{-fpcc-struct-return}, except on targets where GCC is

11158

the principal compiler. In those cases, we can choose the standard, and

11159

we chose the more efficient register return alternative.

11160

11161

@strong{Warning:} code compiled with the @option{-freg-struct-return}

11162

switch is not binary compatible with code compiled with the

11163

@option{-fpcc-struct-return} switch.

11164

Use it to conform to a non-default application binary interface.

11165

11166

@item -fshort-enums

11167

@opindex fshort-enums

11168

Allocate to an @code{enum} type only as many bytes as it needs for the

11169

declared range of possible values. Specifically, the @code{enum} type

11170

is equivalent to the smallest integer type that has enough room.

11171

11172

@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate

11173

code that is not binary compatible with code generated without that switch.

11174

Use it to conform to a non-default application binary interface.

11175

11176

@item -fshort-wchar

11177

@opindex fshort-wchar

11178

Override the underlying type for @code{wchar_t} to be @code{short

11179

unsigned int} instead of the default for the target. This option is

11180

useful for building programs to run under WINE@.

11181

11182

@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate

11183

code that is not binary compatible with code generated without that switch.

11184

Use it to conform to a non-default application binary interface.

11185

11186

@item -fno-common

11187

@opindex fno-common

11188

In C code, controls the placement of uninitialized global variables.

11189

Unix C compilers have traditionally permitted multiple definitions of

11190

such variables in different compilation units by placing the variables

11191

in a common block.

11192

This is the behavior specified by @option{-fcommon}, and is the default

11193

for GCC on most targets.

11194

On the other hand, this behavior is not required by ISO C, and on some

11195

targets may carry a speed or code size penalty on variable references.

11196

The @option{-fno-common} option specifies that the compiler should place

11197

uninitialized global variables in the data section of the object file,

11198

rather than generating them as common blocks.

11199

This has the effect that if the same variable is declared

11200

(without @code{extern}) in two different compilations,

11201

you get a multiple-definition error when you link them.

11202

In this case, you must compile with @option{-fcommon} instead.

11203

Compiling with @option{-fno-common} is useful on targets for which

11204

it provides better performance, or if you wish to verify that the

11205

program will work on other systems that always treat uninitialized

11206

variable declarations this way.

11207

11208

@item -fno-ident

11209

@opindex fno-ident

11210

Ignore the @code{#ident} directive.

11211

11212

@item -finhibit-size-directive

11213

@opindex finhibit-size-directive

11214

Don't output a @code{.size} assembler directive, or anything else that

11215

would cause trouble if the function is split in the middle, and the

11216

two halves are placed at locations far apart in memory. This option is

11217

used when compiling @file{crtstuff.c}; you should not need to use it

11218

for anything else.

11219

11220

@item -fverbose-asm

11221

@opindex fverbose-asm

11222

Put extra commentary information in the generated assembly code to

11223

make it more readable. This option is generally only of use to those

11224

who actually need to read the generated assembly code (perhaps while

11225

debugging the compiler itself).

11226

11227

@option{-fno-verbose-asm}, the default, causes the

11228

extra information to be omitted and is useful when comparing two assembler

11229

files.

11230

11231

@item -frecord-gcc-switches

11232

@opindex frecord-gcc-switches

11233

This switch causes the command line used to invoke the

11234

compiler to be recorded into the object file that is being created.

11235

This switch is only implemented on some targets and the exact format

11236

of the recording is target and binary file format dependent, but it

11237

usually takes the form of a section containing ASCII text. This

11238

switch is related to the @option{-fverbose-asm} switch, but that

11239

switch only records information in the assembler output file as

11240

comments, so it never reaches the object file.

11241

See also @option{-grecord-gcc-switches} for another

11242

way of storing compiler options into the object file.

11243

11244

@item -fpic

11245

@opindex fpic

11246

@cindex global offset table

11247

@cindex PIC

11248

Generate position-independent code (PIC) suitable for use in a shared

11249

library, if supported for the target machine. Such code accesses all

11250

constant addresses through a global offset table (GOT)@. The dynamic

11251

loader resolves the GOT entries when the program starts (the dynamic

11252

loader is not part of GCC; it is part of the operating system). If

11253

the GOT size for the linked executable exceeds a machine-specific

11254

maximum size, you get an error message from the linker indicating that

11255

@option{-fpic} does not work; in that case, recompile with @option{-fPIC}

11256

instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k

11257

on the m68k and RS/6000. The x86 has no such limit.)

11258

11259

Position-independent code requires special support, and therefore works

11260

only on certain machines. For the x86, GCC supports PIC for System V

11261

but not for the Sun 386i. Code generated for the IBM RS/6000 is always

11262

position-independent.

11263

11264

When this flag is set, the macros @code{__pic__} and @code{__PIC__}

11265

are defined to 1.

11266

11267

@item -fPIC

11268

@opindex fPIC

11269

If supported for the target machine, emit position-independent code,

11270

suitable for dynamic linking and avoiding any limit on the size of the

11271

global offset table. This option makes a difference on AArch64, m68k,

11272

PowerPC and SPARC@.

11273

11274

Position-independent code requires special support, and therefore works

11275

only on certain machines.

11276

11277

When this flag is set, the macros @code{__pic__} and @code{__PIC__}

11278

are defined to 2.

11279

11280

@item -fpie

11281

@itemx -fPIE

11282

@opindex fpie

11283

@opindex fPIE

11284

These options are similar to @option{-fpic} and @option{-fPIC}, but

11285

generated position independent code can be only linked into executables.

11286

Usually these options are used when @option{-pie} GCC option is

11287

used during linking.

11288

11289

@option{-fpie} and @option{-fPIE} both define the macros

11290

@code{__pie__} and @code{__PIE__}. The macros have the value 1

11291

for @option{-fpie} and 2 for @option{-fPIE}.

11292

11293

@item -fno-plt

11294

@opindex fno-plt

11295

Do not use the PLT for external function calls in position-independent code.

11296

Instead, load the callee address at call sites from the GOT and branch to it.

11297

This leads to more efficient code by eliminating PLT stubs and exposing

11298

GOT loads to optimizations. On architectures such as 32-bit x86 where

11299

PLT stubs expect the GOT pointer in a specific register, this gives more

11300

register allocation freedom to the compiler.

11301

Lazy binding requires use of the PLT;

11302

with @option{-fno-plt} all external symbols are resolved at load time.

11303

11304

Alternatively, the function attribute @code{noplt} can be used to avoid calls

11305

through the PLT for specific external functions.

11306

11307

In position-dependent code, a few targets also convert calls to

11308

functions that are marked to not use the PLT to use the GOT instead.

11309

11310

@item -fno-jump-tables

11311

@opindex fno-jump-tables

11312

Do not use jump tables for switch statements even where it would be

11313

more efficient than other code generation strategies. This option is

11314

of use in conjunction with @option{-fpic} or @option{-fPIC} for

11315

building code that forms part of a dynamic linker and cannot

11316

reference the address of a jump table. On some targets, jump tables

11317

do not require a GOT and this option is not needed.

11318

11319

@item -ffixed-@var{reg}

11320

@opindex ffixed

11321

Treat the register named @var{reg} as a fixed register; generated code

11322

should never refer to it (except perhaps as a stack pointer, frame

11323

pointer or in some other fixed role).

11324

11325

@var{reg} must be the name of a register. The register names accepted

11326

are machine-specific and are defined in the @code{REGISTER_NAMES}

11327

macro in the machine description macro file.

11328

11329

This flag does not have a negative form, because it specifies a

11330

three-way choice.

11331

11332

@item -fcall-used-@var{reg}

11333

@opindex fcall-used

11334

Treat the register named @var{reg} as an allocable register that is

11335

clobbered by function calls. It may be allocated for temporaries or

11336

variables that do not live across a call. Functions compiled this way

11337

do not save and restore the register @var{reg}.

11338

11339

It is an error to use this flag with the frame pointer or stack pointer.

11340

Use of this flag for other registers that have fixed pervasive roles in

11341

the machine's execution model produces disastrous results.

11342

11343

This flag does not have a negative form, because it specifies a

11344

three-way choice.

11345

11346

@item -fcall-saved-@var{reg}

11347

@opindex fcall-saved

11348

Treat the register named @var{reg} as an allocable register saved by

11349

functions. It may be allocated even for temporaries or variables that

11350

live across a call. Functions compiled this way save and restore

11351

the register @var{reg} if they use it.

11352

11353

It is an error to use this flag with the frame pointer or stack pointer.

11354

Use of this flag for other registers that have fixed pervasive roles in

11355

the machine's execution model produces disastrous results.

11356

11357

A different sort of disaster results from the use of this flag for

11358

a register in which function values may be returned.

11359

11360

This flag does not have a negative form, because it specifies a

11361

three-way choice.

11362

11363

@item -fpack-struct[=@var{n}]

11364

@opindex fpack-struct

11365

Without a value specified, pack all structure members together without

11366

holes. When a value is specified (which must be a small power of two), pack

11367

structure members according to this value, representing the maximum

11368

alignment (that is, objects with default alignment requirements larger than

11369

this are output potentially unaligned at the next fitting location.

11370

11371

@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate

11372

code that is not binary compatible with code generated without that switch.

11373

Additionally, it makes the code suboptimal.

11374

Use it to conform to a non-default application binary interface.

11375

11376

@item -fleading-underscore

11377

@opindex fleading-underscore

11378

This option and its counterpart, @option{-fno-leading-underscore}, forcibly

11379

change the way C symbols are represented in the object file. One use

11380

is to help link with legacy assembly code.

11381

11382

@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to

11383

generate code that is not binary compatible with code generated without that

11384

switch. Use it to conform to a non-default application binary interface.

11385

Not all targets provide complete support for this switch.

11386

11387

@item -ftls-model=@var{model}

11388

@opindex ftls-model

11389

Alter the thread-local storage model to be used (@pxref{Thread-Local}).

11390

The @var{model} argument should be one of @samp{global-dynamic},

11391

@samp{local-dynamic}, @samp{initial-exec} or @samp{local-exec}.

11392

Note that the choice is subject to optimization: the compiler may use

11393

a more efficient model for symbols not visible outside of the translation

11394

unit, or if @option{-fpic} is not given on the command line.

11395

11396

The default without @option{-fpic} is @samp{initial-exec}; with

11397

@option{-fpic} the default is @samp{global-dynamic}.

11398

11399

@item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]}

11400

@opindex fvisibility

11401

Set the default ELF image symbol visibility to the specified option---all

11402

symbols are marked with this unless overridden within the code.

11403

Using this feature can very substantially improve linking and

11404

load times of shared object libraries, produce more optimized

11405

code, provide near-perfect API export and prevent symbol clashes.

11406

It is @strong{strongly} recommended that you use this in any shared objects

11407

you distribute.

11408

11409

Despite the nomenclature, @samp{default} always means public; i.e.,

11410

available to be linked against from outside the shared object.

11411

@samp{protected} and @samp{internal} are pretty useless in real-world

11412

usage so the only other commonly used option is @samp{hidden}.

11413

The default if @option{-fvisibility} isn't specified is

11414

@samp{default}, i.e., make every symbol public.

11415

11416

A good explanation of the benefits offered by ensuring ELF

11417

symbols have the correct visibility is given by ``How To Write

11418

Shared Libraries'' by Ulrich Drepper (which can be found at

11419

@w{@uref{http://www.akkadia.org/drepper/}})---however a superior

11420

solution made possible by this option to marking things hidden when

11421

the default is public is to make the default hidden and mark things

11422

public. This is the norm with DLLs on Windows and with @option{-fvisibility=hidden}

11423

and @code{__attribute__ ((visibility("default")))} instead of

11424

@code{__declspec(dllexport)} you get almost identical semantics with

11425

identical syntax. This is a great boon to those working with

11426

cross-platform projects.

11427

11428

For those adding visibility support to existing code, you may find

11429

@code{#pragma GCC visibility} of use. This works by you enclosing

11430

the declarations you wish to set visibility for with (for example)

11431

@code{#pragma GCC visibility push(hidden)} and

11432

@code{#pragma GCC visibility pop}.

11433

Bear in mind that symbol visibility should be viewed @strong{as

11434

part of the API interface contract} and thus all new code should

11435

always specify visibility when it is not the default; i.e., declarations

11436

only for use within the local DSO should @strong{always} be marked explicitly

11437

as hidden as so to avoid PLT indirection overheads---making this

11438

abundantly clear also aids readability and self-documentation of the code.

11439

Note that due to ISO C++ specification requirements, @code{operator new} and

11440

@code{operator delete} must always be of default visibility.

11441

11442

Be aware that headers from outside your project, in particular system

11443

headers and headers from any other library you use, may not be

11444

expecting to be compiled with visibility other than the default. You

11445

may need to explicitly say @code{#pragma GCC visibility push(default)}

11446

before including any such headers.

11447

11448

@code{extern} declarations are not affected by @option{-fvisibility}, so

11449

a lot of code can be recompiled with @option{-fvisibility=hidden} with

11450

no modifications. However, this means that calls to @code{extern}

11451

functions with no explicit visibility use the PLT, so it is more

11452

effective to use @code{__attribute ((visibility))} and/or

11453

@code{#pragma GCC visibility} to tell the compiler which @code{extern}

11454

declarations should be treated as hidden.

11455

11456

Note that @option{-fvisibility} does affect C++ vague linkage

11457

entities. This means that, for instance, an exception class that is

11458

be thrown between DSOs must be explicitly marked with default

11459

visibility so that the @samp{type_info} nodes are unified between

11460

the DSOs.

11461

11462

An overview of these techniques, their benefits and how to use them

11463

is at @uref{http://gcc.gnu.org/@/wiki/@/Visibility}.

11464

11465

@item -fstrict-volatile-bitfields

11466

@opindex fstrict-volatile-bitfields

11467

This option should be used if accesses to volatile bit-fields (or other

11468

structure fields, although the compiler usually honors those types

11469

anyway) should use a single access of the width of the

11470

field's type, aligned to a natural alignment if possible. For

11471

example, targets with memory-mapped peripheral registers might require

11472

all such accesses to be 16 bits wide; with this flag you can

11473

declare all peripheral bit-fields as @code{unsigned short} (assuming short

11474

is 16 bits on these targets) to force GCC to use 16-bit accesses

11475

instead of, perhaps, a more efficient 32-bit access.

11476

11477

If this option is disabled, the compiler uses the most efficient

11478

instruction. In the previous example, that might be a 32-bit load

11479

instruction, even though that accesses bytes that do not contain

11480

any portion of the bit-field, or memory-mapped registers unrelated to

11481

the one being updated.

11482

11483

In some cases, such as when the @code{packed} attribute is applied to a

11484

structure field, it may not be possible to access the field with a single

11485

read or write that is correctly aligned for the target machine. In this

11486

case GCC falls back to generating multiple accesses rather than code that

11487

will fault or truncate the result at run time.

11488

11489

Note: Due to restrictions of the C/C++11 memory model, write accesses are

11490

not allowed to touch non bit-field members. It is therefore recommended

11491

to define all bits of the field's type as bit-field members.

11492

11493

The default value of this option is determined by the application binary

11494

interface for the target processor.

11495

11496

@item -fsync-libcalls

11497

@opindex fsync-libcalls

11498

This option controls whether any out-of-line instance of the @code{__sync}

11499

family of functions may be used to implement the C++11 @code{__atomic}

11500

family of functions.

11501

11502

The default value of this option is enabled, thus the only useful form

11503

of the option is @option{-fno-sync-libcalls}. This option is used in

11504

the implementation of the @file{libatomic} runtime library.

11505

11506

@end table

11507

11508

@node Developer Options

11509

@section GCC Developer Options

11510

@cindex developer options

11511

@cindex debugging GCC

11512

@cindex debug dump options

11513

@cindex dump options

11514

@cindex compilation statistics

11515

11516

This section describes command-line options that are primarily of

11517

interest to GCC developers, including options to support compiler

11518

testing and investigation of compiler bugs and compile-time

11519

performance problems. This includes options that produce debug dumps

11520

at various points in the compilation; that print statistics such as

11521

memory use and execution time; and that print information about GCC's

11522

configuration, such as where it searches for libraries. You should

11523

rarely need to use any of these options for ordinary compilation and

11524

linking tasks.

11525

11526

@table @gcctabopt

11527

11528

@item -d@var{letters}

11529

@itemx -fdump-rtl-@var{pass}

11530

@itemx -fdump-rtl-@var{pass}=@var{filename}

11531

@opindex d

11532

@opindex fdump-rtl-@var{pass}

11533

Says to make debugging dumps during compilation at times specified by

11534

@var{letters}. This is used for debugging the RTL-based passes of the

11535

compiler. The file names for most of the dumps are made by appending

11536

a pass number and a word to the @var{dumpname}, and the files are

11537

created in the directory of the output file. In case of

11538

@option{=@var{filename}} option, the dump is output on the given file

11539

instead of the pass numbered dump files. Note that the pass number is

11540

assigned as passes are registered into the pass manager. Most passes

11541

are registered in the order that they will execute and for these passes

11542

the number corresponds to the pass execution order. However, passes

11543

registered by plugins, passes specific to compilation targets, or

11544

passes that are otherwise registered after all the other passes are

11545

numbered higher than a pass named "final", even if they are executed

11546

earlier. @var{dumpname} is generated from the name of the output

11547

file if explicitly specified and not an executable, otherwise it is

11548

the basename of the source file. These switches may have different

11549

effects when @option{-E} is used for preprocessing.

11550

11551

Debug dumps can be enabled with a @option{-fdump-rtl} switch or some

11552

@option{-d} option @var{letters}. Here are the possible

11553

letters for use in @var{pass} and @var{letters}, and their meanings:

11554

11555

@table @gcctabopt

11556

11557

@item -fdump-rtl-alignments

11558

@opindex fdump-rtl-alignments

11559

Dump after branch alignments have been computed.

11560

11561

@item -fdump-rtl-asmcons

11562

@opindex fdump-rtl-asmcons

11563

Dump after fixing rtl statements that have unsatisfied in/out constraints.

11564

11565

@item -fdump-rtl-auto_inc_dec

11566

@opindex fdump-rtl-auto_inc_dec

11567

Dump after auto-inc-dec discovery. This pass is only run on

11568

architectures that have auto inc or auto dec instructions.

11569

11570

@item -fdump-rtl-barriers

11571

@opindex fdump-rtl-barriers

11572

Dump after cleaning up the barrier instructions.

11573

11574

@item -fdump-rtl-bbpart

11575

@opindex fdump-rtl-bbpart

11576

Dump after partitioning hot and cold basic blocks.

11577

11578

@item -fdump-rtl-bbro

11579

@opindex fdump-rtl-bbro

11580

Dump after block reordering.

11581

11582

@item -fdump-rtl-btl1

11583

@itemx -fdump-rtl-btl2

11584

@opindex fdump-rtl-btl2

11585

@opindex fdump-rtl-btl2

11586

@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping

11587

after the two branch

11588

target load optimization passes.

11589

11590

@item -fdump-rtl-bypass

11591

@opindex fdump-rtl-bypass

11592

Dump after jump bypassing and control flow optimizations.

11593

11594

@item -fdump-rtl-combine

11595

@opindex fdump-rtl-combine

11596

Dump after the RTL instruction combination pass.

11597

11598

@item -fdump-rtl-compgotos

11599

@opindex fdump-rtl-compgotos

11600

Dump after duplicating the computed gotos.

11601

11602

@item -fdump-rtl-ce1

11603

@itemx -fdump-rtl-ce2

11604

@itemx -fdump-rtl-ce3

11605

@opindex fdump-rtl-ce1

11606

@opindex fdump-rtl-ce2

11607

@opindex fdump-rtl-ce3

11608

@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and

11609

@option{-fdump-rtl-ce3} enable dumping after the three

11610

if conversion passes.

11611

11612

@item -fdump-rtl-cprop_hardreg

11613

@opindex fdump-rtl-cprop_hardreg

11614

Dump after hard register copy propagation.

11615

11616

@item -fdump-rtl-csa

11617

@opindex fdump-rtl-csa

11618

Dump after combining stack adjustments.

11619

11620

@item -fdump-rtl-cse1

11621

@itemx -fdump-rtl-cse2

11622

@opindex fdump-rtl-cse1

11623

@opindex fdump-rtl-cse2

11624

@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after

11625

the two common subexpression elimination passes.

11626

11627

@item -fdump-rtl-dce

11628

@opindex fdump-rtl-dce

11629

Dump after the standalone dead code elimination passes.

11630

11631

@item -fdump-rtl-dbr

11632

@opindex fdump-rtl-dbr

11633

Dump after delayed branch scheduling.

11634

11635

@item -fdump-rtl-dce1

11636

@itemx -fdump-rtl-dce2

11637

@opindex fdump-rtl-dce1

11638

@opindex fdump-rtl-dce2

11639

@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after

11640

the two dead store elimination passes.

11641

11642

@item -fdump-rtl-eh

11643

@opindex fdump-rtl-eh

11644

Dump after finalization of EH handling code.

11645

11646

@item -fdump-rtl-eh_ranges

11647

@opindex fdump-rtl-eh_ranges

11648

Dump after conversion of EH handling range regions.

11649

11650

@item -fdump-rtl-expand

11651

@opindex fdump-rtl-expand

11652

Dump after RTL generation.

11653

11654

@item -fdump-rtl-fwprop1

11655

@itemx -fdump-rtl-fwprop2

11656

@opindex fdump-rtl-fwprop1

11657

@opindex fdump-rtl-fwprop2

11658

@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable

11659

dumping after the two forward propagation passes.

11660

11661

@item -fdump-rtl-gcse1

11662

@itemx -fdump-rtl-gcse2

11663

@opindex fdump-rtl-gcse1

11664

@opindex fdump-rtl-gcse2

11665

@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping

11666

after global common subexpression elimination.

11667

11668

@item -fdump-rtl-init-regs

11669

@opindex fdump-rtl-init-regs

11670

Dump after the initialization of the registers.

11671

11672

@item -fdump-rtl-initvals

11673

@opindex fdump-rtl-initvals

11674

Dump after the computation of the initial value sets.

11675

11676

@item -fdump-rtl-into_cfglayout

11677

@opindex fdump-rtl-into_cfglayout

11678

Dump after converting to cfglayout mode.

11679

11680

@item -fdump-rtl-ira

11681

@opindex fdump-rtl-ira

11682

Dump after iterated register allocation.

11683

11684

@item -fdump-rtl-jump

11685

@opindex fdump-rtl-jump

11686

Dump after the second jump optimization.

11687

11688

@item -fdump-rtl-loop2

11689

@opindex fdump-rtl-loop2

11690

@option{-fdump-rtl-loop2} enables dumping after the rtl

11691

loop optimization passes.

11692

11693

@item -fdump-rtl-mach

11694

@opindex fdump-rtl-mach

11695

Dump after performing the machine dependent reorganization pass, if that

11696

pass exists.

11697

11698

@item -fdump-rtl-mode_sw

11699

@opindex fdump-rtl-mode_sw

11700

Dump after removing redundant mode switches.

11701

11702

@item -fdump-rtl-rnreg

11703

@opindex fdump-rtl-rnreg

11704

Dump after register renumbering.

11705

11706

@item -fdump-rtl-outof_cfglayout

11707

@opindex fdump-rtl-outof_cfglayout

11708

Dump after converting from cfglayout mode.

11709

11710

@item -fdump-rtl-peephole2

11711

@opindex fdump-rtl-peephole2

11712

Dump after the peephole pass.

11713

11714

@item -fdump-rtl-postreload

11715

@opindex fdump-rtl-postreload

11716

Dump after post-reload optimizations.

11717

11718

@item -fdump-rtl-pro_and_epilogue

11719

@opindex fdump-rtl-pro_and_epilogue

11720

Dump after generating the function prologues and epilogues.

11721

11722

@item -fdump-rtl-sched1

11723

@itemx -fdump-rtl-sched2

11724

@opindex fdump-rtl-sched1

11725

@opindex fdump-rtl-sched2

11726

@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping

11727

after the basic block scheduling passes.

11728

11729

@item -fdump-rtl-ree

11730

@opindex fdump-rtl-ree

11731

Dump after sign/zero extension elimination.

11732

11733

@item -fdump-rtl-seqabstr

11734

@opindex fdump-rtl-seqabstr

11735

Dump after common sequence discovery.

11736

11737

@item -fdump-rtl-shorten

11738

@opindex fdump-rtl-shorten

11739

Dump after shortening branches.

11740

11741

@item -fdump-rtl-sibling

11742

@opindex fdump-rtl-sibling

11743

Dump after sibling call optimizations.

11744

11745

@item -fdump-rtl-split1

11746

@itemx -fdump-rtl-split2

11747

@itemx -fdump-rtl-split3

11748

@itemx -fdump-rtl-split4

11749

@itemx -fdump-rtl-split5

11750

@opindex fdump-rtl-split1

11751

@opindex fdump-rtl-split2

11752

@opindex fdump-rtl-split3

11753

@opindex fdump-rtl-split4

11754

@opindex fdump-rtl-split5

11755

These options enable dumping after five rounds of

11756

instruction splitting.

11757

11758

@item -fdump-rtl-sms

11759

@opindex fdump-rtl-sms

11760

Dump after modulo scheduling. This pass is only run on some

11761

architectures.

11762

11763

@item -fdump-rtl-stack

11764

@opindex fdump-rtl-stack

11765

Dump after conversion from GCC's ``flat register file'' registers to the

11766

x87's stack-like registers. This pass is only run on x86 variants.

11767

11768

@item -fdump-rtl-subreg1

11769

@itemx -fdump-rtl-subreg2

11770

@opindex fdump-rtl-subreg1

11771

@opindex fdump-rtl-subreg2

11772

@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after

11773

the two subreg expansion passes.

11774

11775

@item -fdump-rtl-unshare

11776

@opindex fdump-rtl-unshare

11777

Dump after all rtl has been unshared.

11778

11779

@item -fdump-rtl-vartrack

11780

@opindex fdump-rtl-vartrack

11781

Dump after variable tracking.

11782

11783

@item -fdump-rtl-vregs

11784

@opindex fdump-rtl-vregs

11785

Dump after converting virtual registers to hard registers.

11786

11787

@item -fdump-rtl-web

11788

@opindex fdump-rtl-web

11789

Dump after live range splitting.

11790

11791

@item -fdump-rtl-regclass

11792

@itemx -fdump-rtl-subregs_of_mode_init

11793

@itemx -fdump-rtl-subregs_of_mode_finish

11794

@itemx -fdump-rtl-dfinit

11795

@itemx -fdump-rtl-dfinish

11796

@opindex fdump-rtl-regclass

11797

@opindex fdump-rtl-subregs_of_mode_init

11798

@opindex fdump-rtl-subregs_of_mode_finish

11799

@opindex fdump-rtl-dfinit

11800

@opindex fdump-rtl-dfinish

11801

These dumps are defined but always produce empty files.

11802

11803

@item -da

11804

@itemx -fdump-rtl-all

11805

@opindex da

11806

@opindex fdump-rtl-all

11807

Produce all the dumps listed above.

11808

11809

@item -dA

11810

@opindex dA

11811

Annotate the assembler output with miscellaneous debugging information.

11812

11813

@item -dD

11814

@opindex dD

11815

Dump all macro definitions, at the end of preprocessing, in addition to

11816

normal output.

11817

11818

@item -dH

11819

@opindex dH

11820

Produce a core dump whenever an error occurs.

11821

11822

@item -dp

11823

@opindex dp

11824

Annotate the assembler output with a comment indicating which

11825

pattern and alternative is used. The length of each instruction is

11826

also printed.

11827

11828

@item -dP

11829

@opindex dP

11830

Dump the RTL in the assembler output as a comment before each instruction.

11831

Also turns on @option{-dp} annotation.

11832

11833

@item -dx

11834

@opindex dx

11835

Just generate RTL for a function instead of compiling it. Usually used

11836

with @option{-fdump-rtl-expand}.

11837

@end table

11838

11839

@item -fdump-noaddr

11840

@opindex fdump-noaddr

11841

When doing debugging dumps, suppress address output. This makes it more

11842

feasible to use diff on debugging dumps for compiler invocations with

11843

different compiler binaries and/or different

11844

text / bss / data / heap / stack / dso start locations.

11845

11846

@item -freport-bug

11847

@opindex freport-bug

11848

Collect and dump debug information into a temporary file if an

11849

internal compiler error (ICE) occurs.

11850

11851

@item -fdump-unnumbered

11852

@opindex fdump-unnumbered

11853

When doing debugging dumps, suppress instruction numbers and address output.

11854

This makes it more feasible to use diff on debugging dumps for compiler

11855

invocations with different options, in particular with and without

11856

@option{-g}.

11857

11858

@item -fdump-unnumbered-links

11859

@opindex fdump-unnumbered-links

11860

When doing debugging dumps (see @option{-d} option above), suppress

11861

instruction numbers for the links to the previous and next instructions

11862

in a sequence.

11863

11864

@item -fdump-translation-unit @r{(C++ only)}

11865

@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}

11866

@opindex fdump-translation-unit

11867

Dump a representation of the tree structure for the entire translation

11868

unit to a file. The file name is made by appending @file{.tu} to the

11869

source file name, and the file is created in the same directory as the

11870

output file. If the @samp{-@var{options}} form is used, @var{options}

11871

controls the details of the dump as described for the

11872

@option{-fdump-tree} options.

11873

11874

@item -fdump-class-hierarchy @r{(C++ only)}

11875

@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}

11876

@opindex fdump-class-hierarchy

11877

Dump a representation of each class's hierarchy and virtual function

11878

table layout to a file. The file name is made by appending

11879

@file{.class} to the source file name, and the file is created in the

11880

same directory as the output file. If the @samp{-@var{options}} form

11881

is used, @var{options} controls the details of the dump as described

11882

for the @option{-fdump-tree} options.

11883

11884

@item -fdump-ipa-@var{switch}

11885

@opindex fdump-ipa

11886

Control the dumping at various stages of inter-procedural analysis

11887

language tree to a file. The file name is generated by appending a

11888

switch specific suffix to the source file name, and the file is created

11889

in the same directory as the output file. The following dumps are

11890

possible:

11891

11892

@table @samp

11893

@item all

11894

Enables all inter-procedural analysis dumps.

11895

11896

@item cgraph

11897

Dumps information about call-graph optimization, unused function removal,

11898

and inlining decisions.

11899

11900

@item inline

11901

Dump after function inlining.

11902

11903

@end table

11904

11905

@item -fdump-passes

11906

@opindex fdump-passes

11907

Dump the list of optimization passes that are turned on and off by

11908

the current command-line options.

11909

11910

@item -fdump-statistics-@var{option}

11911

@opindex fdump-statistics

11912

Enable and control dumping of pass statistics in a separate file. The

11913

file name is generated by appending a suffix ending in

11914

@samp{.statistics} to the source file name, and the file is created in

11915

the same directory as the output file. If the @samp{-@var{option}}

11916

form is used, @samp{-stats} causes counters to be summed over the

11917

whole compilation unit while @samp{-details} dumps every event as

11918

the passes generate them. The default with no option is to sum

11919

counters for each function compiled.

11920

11921

@item -fdump-tree-@var{switch}

11922

@itemx -fdump-tree-@var{switch}-@var{options}

11923

@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename}

11924

@opindex fdump-tree

11925

Control the dumping at various stages of processing the intermediate

11926

language tree to a file. The file name is generated by appending a

11927

switch-specific suffix to the source file name, and the file is

11928

created in the same directory as the output file. In case of

11929

@option{=@var{filename}} option, the dump is output on the given file

11930

instead of the auto named dump files. If the @samp{-@var{options}}

11931

form is used, @var{options} is a list of @samp{-} separated options

11932

which control the details of the dump. Not all options are applicable

11933

to all dumps; those that are not meaningful are ignored. The

11934

following options are available

11935

11936

@table @samp

11937

@item address

11938

Print the address of each node. Usually this is not meaningful as it

11939

changes according to the environment and source file. Its primary use

11940

is for tying up a dump file with a debug environment.

11941

@item asmname

11942

If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that

11943

in the dump instead of @code{DECL_NAME}. Its primary use is ease of

11944

use working backward from mangled names in the assembly file.

11945

@item slim

11946

When dumping front-end intermediate representations, inhibit dumping

11947

of members of a scope or body of a function merely because that scope

11948

has been reached. Only dump such items when they are directly reachable

11949

by some other path.

11950

11951

When dumping pretty-printed trees, this option inhibits dumping the

11952

bodies of control structures.

11953

11954

When dumping RTL, print the RTL in slim (condensed) form instead of

11955

the default LISP-like representation.

11956

@item raw

11957

Print a raw representation of the tree. By default, trees are

11958

pretty-printed into a C-like representation.

11959

@item details

11960

Enable more detailed dumps (not honored by every dump option). Also

11961

include information from the optimization passes.

11962

@item stats

11963

Enable dumping various statistics about the pass (not honored by every dump

11964

option).

11965

@item blocks

11966

Enable showing basic block boundaries (disabled in raw dumps).

11967

@item graph

11968

For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}),

11969

dump a representation of the control flow graph suitable for viewing with

11970

GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in

11971

the file is pretty-printed as a subgraph, so that GraphViz can render them

11972

all in a single plot.

11973

11974

This option currently only works for RTL dumps, and the RTL is always

11975

dumped in slim form.

11976

@item vops

11977

Enable showing virtual operands for every statement.

11978

@item lineno

11979

Enable showing line numbers for statements.

11980

@item uid

11981

Enable showing the unique ID (@code{DECL_UID}) for each variable.

11982

@item verbose

11983

Enable showing the tree dump for each statement.

11984

@item eh

11985

Enable showing the EH region number holding each statement.

11986

@item scev

11987

Enable showing scalar evolution analysis details.

11988

@item optimized

11989

Enable showing optimization information (only available in certain

11990

passes).

11991

@item missed

11992

Enable showing missed optimization information (only available in certain

11993

passes).

11994

@item note

11995

Enable other detailed optimization information (only available in

11996

certain passes).

11997

@item =@var{filename}

11998

Instead of an auto named dump file, output into the given file

11999

name. The file names @file{stdout} and @file{stderr} are treated

12000

specially and are considered already open standard streams. For

12001

example,

12002

12003

@smallexample

12004

gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump

12005

-fdump-tree-pre=stderr file.c

12006

@end smallexample

12007

12008

outputs vectorizer dump into @file{foo.dump}, while the PRE dump is

12009

output on to @file{stderr}. If two conflicting dump filenames are

12010

given for the same pass, then the latter option overrides the earlier

12011

one.

12012

12013

@item split-paths

12014

@opindex fdump-tree-split-paths

12015

Dump each function after splitting paths to loop backedges. The file

12016

name is made by appending @file{.split-paths} to the source file name.

12017

12018

@item all

12019

Turn on all options, except @option{raw}, @option{slim}, @option{verbose}

12020

and @option{lineno}.

12021

12022

@item optall

12023

Turn on all optimization options, i.e., @option{optimized},

12024

@option{missed}, and @option{note}.

12025

@end table

12026

12027

The following tree dumps are possible:

12028

@table @samp

12029

12030

@item original

12031

@opindex fdump-tree-original

12032

Dump before any tree based optimization, to @file{@var{file}.original}.

12033

12034

@item optimized

12035

@opindex fdump-tree-optimized

12036

Dump after all tree based optimization, to @file{@var{file}.optimized}.

12037

12038

@item gimple

12039

@opindex fdump-tree-gimple

12040

Dump each function before and after the gimplification pass to a file. The

12041

file name is made by appending @file{.gimple} to the source file name.

12042

12043

@item cfg

12044

@opindex fdump-tree-cfg

12045

Dump the control flow graph of each function to a file. The file name is

12046

made by appending @file{.cfg} to the source file name.

12047

12048

@item ch

12049

@opindex fdump-tree-ch

12050

Dump each function after copying loop headers. The file name is made by

12051

appending @file{.ch} to the source file name.

12052

12053

@item ssa

12054

@opindex fdump-tree-ssa

12055

Dump SSA related information to a file. The file name is made by appending

12056

@file{.ssa} to the source file name.

12057

12058

@item alias

12059

@opindex fdump-tree-alias

12060

Dump aliasing information for each function. The file name is made by

12061

appending @file{.alias} to the source file name.

12062

12063

@item ccp

12064

@opindex fdump-tree-ccp

12065

Dump each function after CCP@. The file name is made by appending

12066

@file{.ccp} to the source file name.

12067

12068

@item storeccp

12069

@opindex fdump-tree-storeccp

12070

Dump each function after STORE-CCP@. The file name is made by appending

12071

@file{.storeccp} to the source file name.

12072

12073

@item pre

12074

@opindex fdump-tree-pre

12075

Dump trees after partial redundancy elimination. The file name is made

12076

by appending @file{.pre} to the source file name.

12077

12078

@item fre

12079

@opindex fdump-tree-fre

12080

Dump trees after full redundancy elimination. The file name is made

12081

by appending @file{.fre} to the source file name.

12082

12083

@item copyprop

12084

@opindex fdump-tree-copyprop

12085

Dump trees after copy propagation. The file name is made

12086

by appending @file{.copyprop} to the source file name.

12087

12088

@item store_copyprop

12089

@opindex fdump-tree-store_copyprop

12090

Dump trees after store copy-propagation. The file name is made

12091

by appending @file{.store_copyprop} to the source file name.

12092

12093

@item dce

12094

@opindex fdump-tree-dce

12095

Dump each function after dead code elimination. The file name is made by

12096

appending @file{.dce} to the source file name.

12097

12098

@item sra

12099

@opindex fdump-tree-sra

12100

Dump each function after performing scalar replacement of aggregates. The

12101

file name is made by appending @file{.sra} to the source file name.

12102

12103

@item sink

12104

@opindex fdump-tree-sink

12105

Dump each function after performing code sinking. The file name is made

12106

by appending @file{.sink} to the source file name.

12107

12108

@item dom

12109

@opindex fdump-tree-dom

12110

Dump each function after applying dominator tree optimizations. The file

12111

name is made by appending @file{.dom} to the source file name.

12112

12113

@item dse

12114

@opindex fdump-tree-dse

12115

Dump each function after applying dead store elimination. The file

12116

name is made by appending @file{.dse} to the source file name.

12117

12118

@item phiopt

12119

@opindex fdump-tree-phiopt

12120

Dump each function after optimizing PHI nodes into straightline code. The file

12121

name is made by appending @file{.phiopt} to the source file name.

12122

12123

@item backprop

12124

@opindex fdump-tree-backprop

12125

Dump each function after back-propagating use information up the definition

12126

chain. The file name is made by appending @file{.backprop} to the

12127

source file name.

12128

12129

@item forwprop

12130

@opindex fdump-tree-forwprop

12131

Dump each function after forward propagating single use variables. The file

12132

name is made by appending @file{.forwprop} to the source file name.

12133

12134

@item nrv

12135

@opindex fdump-tree-nrv

12136

Dump each function after applying the named return value optimization on

12137

generic trees. The file name is made by appending @file{.nrv} to the source

12138

file name.

12139

12140

@item vect

12141

@opindex fdump-tree-vect

12142

Dump each function after applying vectorization of loops. The file name is

12143

made by appending @file{.vect} to the source file name.

12144

12145

@item slp

12146

@opindex fdump-tree-slp

12147

Dump each function after applying vectorization of basic blocks. The file name

12148

is made by appending @file{.slp} to the source file name.

12149

12150

@item vrp

12151

@opindex fdump-tree-vrp

12152

Dump each function after Value Range Propagation (VRP). The file name

12153

is made by appending @file{.vrp} to the source file name.

12154

12155

@item oaccdevlow

12156

@opindex fdump-tree-oaccdevlow

12157

Dump each function after applying device-specific OpenACC transformations.

12158

The file name is made by appending @file{.oaccdevlow} to the source file name.

12159

12160

@item all

12161

@opindex fdump-tree-all

12162

Enable all the available tree dumps with the flags provided in this option.

12163

@end table

12164

12165

@item -fopt-info

12166

@itemx -fopt-info-@var{options}

12167

@itemx -fopt-info-@var{options}=@var{filename}

12168

@opindex fopt-info

12169

Controls optimization dumps from various optimization passes. If the

12170

@samp{-@var{options}} form is used, @var{options} is a list of

12171

@samp{-} separated option keywords to select the dump details and

12172

optimizations.

12173

12174

The @var{options} can be divided into two groups: options describing the

12175

verbosity of the dump, and options describing which optimizations

12176

should be included. The options from both the groups can be freely

12177

mixed as they are non-overlapping. However, in case of any conflicts,

12178

the later options override the earlier options on the command

12179

line.

12180

12181

The following options control the dump verbosity:

12182

12183

@table @samp

12184

@item optimized

12185

Print information when an optimization is successfully applied. It is

12186

up to a pass to decide which information is relevant. For example, the

12187

vectorizer passes print the source location of loops which are

12188

successfully vectorized.

12189

@item missed

12190

Print information about missed optimizations. Individual passes

12191

control which information to include in the output.

12192

@item note

12193

Print verbose information about optimizations, such as certain

12194

transformations, more detailed messages about decisions etc.

12195

@item all

12196

Print detailed optimization information. This includes

12197

@samp{optimized}, @samp{missed}, and @samp{note}.

12198

@end table

12199

12200

One or more of the following option keywords can be used to describe a

12201

group of optimizations:

12202

12203

@table @samp

12204

@item ipa

12205

Enable dumps from all interprocedural optimizations.

12206

@item loop

12207

Enable dumps from all loop optimizations.

12208

@item inline

12209

Enable dumps from all inlining optimizations.

12210

@item vec

12211

Enable dumps from all vectorization optimizations.

12212

@item optall

12213

Enable dumps from all optimizations. This is a superset of

12214

the optimization groups listed above.

12215

@end table

12216

12217

If @var{options} is

12218

omitted, it defaults to @samp{optimized-optall}, which means to dump all

12219

info about successful optimizations from all the passes.

12220

12221

If the @var{filename} is provided, then the dumps from all the

12222

applicable optimizations are concatenated into the @var{filename}.

12223

Otherwise the dump is output onto @file{stderr}. Though multiple

12224

@option{-fopt-info} options are accepted, only one of them can include

12225

a @var{filename}. If other filenames are provided then all but the

12226

first such option are ignored.

12227

12228

Note that the output @var{filename} is overwritten

12229

in case of multiple translation units. If a combined output from

12230

multiple translation units is desired, @file{stderr} should be used

12231

instead.

12232

12233

In the following example, the optimization info is output to

12234

@file{stderr}:

12235

12236

@smallexample

12237

gcc -O3 -fopt-info

12238

@end smallexample

12239

12240

This example:

12241

@smallexample

12242

gcc -O3 -fopt-info-missed=missed.all

12243

@end smallexample

12244

12245

@noindent

12246

outputs missed optimization report from all the passes into

12247

@file{missed.all}, and this one:

12248

12249

@smallexample

12250

gcc -O2 -ftree-vectorize -fopt-info-vec-missed

12251

@end smallexample

12252

12253

@noindent

12254

prints information about missed optimization opportunities from

12255

vectorization passes on @file{stderr}.

12256

Note that @option{-fopt-info-vec-missed} is equivalent to

12257

@option{-fopt-info-missed-vec}.

12258

12259

As another example,

12260

@smallexample

12261

gcc -O3 -fopt-info-inline-optimized-missed=inline.txt

12262

@end smallexample

12263

12264

@noindent

12265

outputs information about missed optimizations as well as

12266

optimized locations from all the inlining passes into

12267

@file{inline.txt}.

12268

12269

Finally, consider:

12270

12271

@smallexample

12272

gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt

12273

@end smallexample

12274

12275

@noindent

12276

Here the two output filenames @file{vec.miss} and @file{loop.opt} are

12277

in conflict since only one output file is allowed. In this case, only

12278

the first option takes effect and the subsequent options are

12279

ignored. Thus only @file{vec.miss} is produced which contains

12280

dumps from the vectorizer about missed opportunities.

12281

12282

@item -fsched-verbose=@var{n}

12283

@opindex fsched-verbose

12284

On targets that use instruction scheduling, this option controls the

12285

amount of debugging output the scheduler prints to the dump files.

12286

12287

For @var{n} greater than zero, @option{-fsched-verbose} outputs the

12288

same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}.

12289

For @var{n} greater than one, it also output basic block probabilities,

12290

detailed ready list information and unit/insn info. For @var{n} greater

12291

than two, it includes RTL at abort point, control-flow and regions info.

12292

And for @var{n} over four, @option{-fsched-verbose} also includes

12293

dependence info.

12294

12295

12296

12297

@item -fenable-@var{kind}-@var{pass}

12298

@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list}

12299

@opindex fdisable-

12300

@opindex fenable-

12301

12302

This is a set of options that are used to explicitly disable/enable

12303

optimization passes. These options are intended for use for debugging GCC.

12304

Compiler users should use regular options for enabling/disabling

12305

passes instead.

12306

12307

@table @gcctabopt

12308

12309

@item -fdisable-ipa-@var{pass}

12310

Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is

12311

statically invoked in the compiler multiple times, the pass name should be

12312

appended with a sequential number starting from 1.

12313

12314

@item -fdisable-rtl-@var{pass}

12315

@itemx -fdisable-rtl-@var{pass}=@var{range-list}

12316

Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is

12317

statically invoked in the compiler multiple times, the pass name should be

12318

appended with a sequential number starting from 1. @var{range-list} is a

12319

comma-separated list of function ranges or assembler names. Each range is a number

12320

pair separated by a colon. The range is inclusive in both ends. If the range

12321

is trivial, the number pair can be simplified as a single number. If the

12322

function's call graph node's @var{uid} falls within one of the specified ranges,

12323

the @var{pass} is disabled for that function. The @var{uid} is shown in the

12324

function header of a dump file, and the pass names can be dumped by using

12325

option @option{-fdump-passes}.

12326

12327

@item -fdisable-tree-@var{pass}

12328

@itemx -fdisable-tree-@var{pass}=@var{range-list}

12329

Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of

12330

option arguments.

12331

12332

@item -fenable-ipa-@var{pass}

12333

Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is

12334

statically invoked in the compiler multiple times, the pass name should be

12335

appended with a sequential number starting from 1.

12336

12337

@item -fenable-rtl-@var{pass}

12338

@itemx -fenable-rtl-@var{pass}=@var{range-list}

12339

Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument

12340

description and examples.

12341

12342

@item -fenable-tree-@var{pass}

12343

@itemx -fenable-tree-@var{pass}=@var{range-list}

12344

Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description

12345

of option arguments.

12346

12347

@end table

12348

12349

Here are some examples showing uses of these options.

12350

12351

@smallexample

12352

12353

# disable ccp1 for all functions

12354

-fdisable-tree-ccp1

12355

# disable complete unroll for function whose cgraph node uid is 1

12356

-fenable-tree-cunroll=1

12357

# disable gcse2 for functions at the following ranges [1,1],

12358

# [300,400], and [400,1000]

12359

# disable gcse2 for functions foo and foo2

12360

-fdisable-rtl-gcse2=foo,foo2

12361

# disable early inlining

12362

-fdisable-tree-einline

12363

# disable ipa inlining

12364

-fdisable-ipa-inline

12365

# enable tree full unroll

12366

-fenable-tree-unroll

12367

12368

@end smallexample

12369

12370

@item -fchecking

12371

@opindex fchecking

12372

@opindex fno-checking

12373

Enable internal consistency checking. The default depends on

12374

the compiler configuration.

12375

12376

@item -frandom-seed=@var{string}

12377

@opindex frandom-seed

12378

This option provides a seed that GCC uses in place of

12379

random numbers in generating certain symbol names

12380

that have to be different in every compiled file. It is also used to

12381

place unique stamps in coverage data files and the object files that

12382

produce them. You can use the @option{-frandom-seed} option to produce

12383

reproducibly identical object files.

12384

12385

The @var{string} can either be a number (decimal, octal or hex) or an

12386

arbitrary string (in which case it's converted to a number by

12387

computing CRC32).

12388

12389

The @var{string} should be different for every file you compile.

12390

12391

@item -save-temps

12392

@itemx -save-temps=cwd

12393

@opindex save-temps

12394

Store the usual ``temporary'' intermediate files permanently; place them

12395

in the current directory and name them based on the source file. Thus,

12396

compiling @file{foo.c} with @option{-c -save-temps} produces files

12397

@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a

12398

preprocessed @file{foo.i} output file even though the compiler now

12399

normally uses an integrated preprocessor.

12400

12401

When used in combination with the @option{-x} command-line option,

12402

@option{-save-temps} is sensible enough to avoid over writing an

12403

input source file with the same extension as an intermediate file.

12404

The corresponding intermediate file may be obtained by renaming the

12405

source file before using @option{-save-temps}.

12406

12407

If you invoke GCC in parallel, compiling several different source

12408

files that share a common base name in different subdirectories or the

12409

same source file compiled for multiple output destinations, it is

12410

likely that the different parallel compilers will interfere with each

12411

other, and overwrite the temporary files. For instance:

12412

12413

@smallexample

12414

gcc -save-temps -o outdir1/foo.o indir1/foo.c&

12415

gcc -save-temps -o outdir2/foo.o indir2/foo.c&

12416

@end smallexample

12417

12418

may result in @file{foo.i} and @file{foo.o} being written to

12419

simultaneously by both compilers.

12420

12421

@item -save-temps=obj

12422

@opindex save-temps=obj

12423

Store the usual ``temporary'' intermediate files permanently. If the

12424

@option{-o} option is used, the temporary files are based on the

12425

object file. If the @option{-o} option is not used, the

12426

@option{-save-temps=obj} switch behaves like @option{-save-temps}.

12427

12428

For example:

12429

12430

@smallexample

12431

gcc -save-temps=obj -c foo.c

12432

gcc -save-temps=obj -c bar.c -o dir/xbar.o

12433

gcc -save-temps=obj foobar.c -o dir2/yfoobar

12434

@end smallexample

12435

12436

@noindent

12437

creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},

12438

@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and

12439

@file{dir2/yfoobar.o}.

12440

12441

@item -time@r{[}=@var{file}@r{]}

12442

@opindex time

12443

Report the CPU time taken by each subprocess in the compilation

12444

sequence. For C source files, this is the compiler proper and assembler

12445

(plus the linker if linking is done).

12446

12447

Without the specification of an output file, the output looks like this:

12448

12449

@smallexample

12450

# cc1 0.12 0.01

12451

# as 0.00 0.01

12452

@end smallexample

12453

12454

The first number on each line is the ``user time'', that is time spent

12455

executing the program itself. The second number is ``system time'',

12456

time spent executing operating system routines on behalf of the program.

12457

Both numbers are in seconds.

12458

12459

With the specification of an output file, the output is appended to the

12460

named file, and it looks like this:

12461

12462

@smallexample

12463

0.12 0.01 cc1 @var{options}

12464

0.00 0.01 as @var{options}

12465

@end smallexample

12466

12467

The ``user time'' and the ``system time'' are moved before the program

12468

name, and the options passed to the program are displayed, so that one

12469

can later tell what file was being compiled, and with which options.

12470

12471

@item -fdump-final-insns@r{[}=@var{file}@r{]}

12472

@opindex fdump-final-insns

12473

Dump the final internal representation (RTL) to @var{file}. If the

12474

optional argument is omitted (or if @var{file} is @code{.}), the name

12475

of the dump file is determined by appending @code{.gkd} to the

12476

compilation output file name.

12477

12478

@item -fcompare-debug@r{[}=@var{opts}@r{]}

12479

@opindex fcompare-debug

12480

@opindex fno-compare-debug

12481

If no error occurs during compilation, run the compiler a second time,

12482

adding @var{opts} and @option{-fcompare-debug-second} to the arguments

12483

passed to the second compilation. Dump the final internal

12484

representation in both compilations, and print an error if they differ.

12485

12486

If the equal sign is omitted, the default @option{-gtoggle} is used.

12487

12488

The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty

12489

and nonzero, implicitly enables @option{-fcompare-debug}. If

12490

@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash,

12491

then it is used for @var{opts}, otherwise the default @option{-gtoggle}

12492

is used.

12493

12494

@option{-fcompare-debug=}, with the equal sign but without @var{opts},

12495

is equivalent to @option{-fno-compare-debug}, which disables the dumping

12496

of the final representation and the second compilation, preventing even

12497

@env{GCC_COMPARE_DEBUG} from taking effect.

12498

12499

To verify full coverage during @option{-fcompare-debug} testing, set

12500

@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden},

12501

which GCC rejects as an invalid option in any actual compilation

12502

(rather than preprocessing, assembly or linking). To get just a

12503

warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug

12504

not overridden} will do.

12505

12506

@item -fcompare-debug-second

12507

@opindex fcompare-debug-second

12508

This option is implicitly passed to the compiler for the second

12509

compilation requested by @option{-fcompare-debug}, along with options to

12510

silence warnings, and omitting other options that would cause

12511

side-effect compiler outputs to files or to the standard output. Dump

12512

files and preserved temporary files are renamed so as to contain the

12513

@code{.gk} additional extension during the second compilation, to avoid

12514

overwriting those generated by the first.

12515

12516

When this option is passed to the compiler driver, it causes the

12517

@emph{first} compilation to be skipped, which makes it useful for little

12518

other than debugging the compiler proper.

12519

12520

@item -gtoggle

12521

@opindex gtoggle

12522

Turn off generation of debug info, if leaving out this option

12523

generates it, or turn it on at level 2 otherwise. The position of this

12524

argument in the command line does not matter; it takes effect after all

12525

other options are processed, and it does so only once, no matter how

12526

many times it is given. This is mainly intended to be used with

12527

@option{-fcompare-debug}.

12528

12529

@item -fvar-tracking-assignments-toggle

12530

@opindex fvar-tracking-assignments-toggle

12531

@opindex fno-var-tracking-assignments-toggle

12532

Toggle @option{-fvar-tracking-assignments}, in the same way that

12533

@option{-gtoggle} toggles @option{-g}.

12534

12535

@item -Q

12536

@opindex Q

12537

Makes the compiler print out each function name as it is compiled, and

12538

print some statistics about each pass when it finishes.

12539

12540

@item -ftime-report

12541

@opindex ftime-report

12542

Makes the compiler print some statistics about the time consumed by each

12543

pass when it finishes.

12544

12545

@item -fira-verbose=@var{n}

12546

@opindex fira-verbose

12547

Control the verbosity of the dump file for the integrated register allocator.

12548

The default value is 5. If the value @var{n} is greater or equal to 10,

12549

the dump output is sent to stderr using the same format as @var{n} minus 10.

12550

12551

@item -flto-report

12552

@opindex flto-report

12553

Prints a report with internal details on the workings of the link-time

12554

optimizer. The contents of this report vary from version to version.

12555

It is meant to be useful to GCC developers when processing object

12556

files in LTO mode (via @option{-flto}).

12557

12558

Disabled by default.

12559

12560

@item -flto-report-wpa

12561

@opindex flto-report-wpa

12562

Like @option{-flto-report}, but only print for the WPA phase of Link

12563

Time Optimization.

12564

12565

@item -fmem-report

12566

@opindex fmem-report

12567

Makes the compiler print some statistics about permanent memory

12568

allocation when it finishes.

12569

12570

@item -fmem-report-wpa

12571

@opindex fmem-report-wpa

12572

Makes the compiler print some statistics about permanent memory

12573

allocation for the WPA phase only.

12574

12575

@item -fpre-ipa-mem-report

12576

@opindex fpre-ipa-mem-report

12577

@item -fpost-ipa-mem-report

12578

@opindex fpost-ipa-mem-report

12579

Makes the compiler print some statistics about permanent memory

12580

allocation before or after interprocedural optimization.

12581

12582

@item -fprofile-report

12583

@opindex fprofile-report

12584

Makes the compiler print some statistics about consistency of the

12585

(estimated) profile and effect of individual passes.

12586

12587

@item -fstack-usage

12588

@opindex fstack-usage

12589

Makes the compiler output stack usage information for the program, on a

12590

per-function basis. The filename for the dump is made by appending

12591

@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of

12592

the output file, if explicitly specified and it is not an executable,

12593

otherwise it is the basename of the source file. An entry is made up

12594

of three fields:

12595

12596

@itemize

12597

@item

12598

The name of the function.

12599

@item

12600

A number of bytes.

12601

@item

12602

One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.

12603

@end itemize

12604

12605

The qualifier @code{static} means that the function manipulates the stack

12606

statically: a fixed number of bytes are allocated for the frame on function

12607

entry and released on function exit; no stack adjustments are otherwise made

12608

in the function. The second field is this fixed number of bytes.

12609

12610

The qualifier @code{dynamic} means that the function manipulates the stack

12611

dynamically: in addition to the static allocation described above, stack

12612

adjustments are made in the body of the function, for example to push/pop

12613

arguments around function calls. If the qualifier @code{bounded} is also

12614

present, the amount of these adjustments is bounded at compile time and

12615

the second field is an upper bound of the total amount of stack used by

12616

the function. If it is not present, the amount of these adjustments is

12617

not bounded at compile time and the second field only represents the

12618

bounded part.

12619

12620

@item -fstats

12621

@opindex fstats

12622

Emit statistics about front-end processing at the end of the compilation.

12623

This option is supported only by the C++ front end, and

12624

the information is generally only useful to the G++ development team.

12625

12626

@item -fdbg-cnt-list

12627

@opindex fdbg-cnt-list

12628

Print the name and the counter upper bound for all debug counters.

12629

12630

12631

@item -fdbg-cnt=@var{counter-value-list}

12632

@opindex fdbg-cnt

12633

Set the internal debug counter upper bound. @var{counter-value-list}

12634

is a comma-separated list of @var{name}:@var{value} pairs

12635

which sets the upper bound of each debug counter @var{name} to @var{value}.

12636

All debug counters have the initial upper bound of @code{UINT_MAX};

12637

thus @code{dbg_cnt} returns true always unless the upper bound

12638

is set by this option.

12639

For example, with @option{-fdbg-cnt=dce:10,tail_call:0},

12640

@code{dbg_cnt(dce)} returns true only for first 10 invocations.

12641

12642

@item -print-file-name=@var{library}

12643

@opindex print-file-name

12644

Print the full absolute name of the library file @var{library} that

12645

would be used when linking---and don't do anything else. With this

12646

option, GCC does not compile or link anything; it just prints the

12647

file name.

12648

12649

@item -print-multi-directory

12650

@opindex print-multi-directory

12651

Print the directory name corresponding to the multilib selected by any

12652

other switches present in the command line. This directory is supposed

12653

to exist in @env{GCC_EXEC_PREFIX}.

12654

12655

@item -print-multi-lib

12656

@opindex print-multi-lib

12657

Print the mapping from multilib directory names to compiler switches

12658

that enable them. The directory name is separated from the switches by

12659

@samp{;}, and each switch starts with an @samp{@@} instead of the

12660

@samp{-}, without spaces between multiple switches. This is supposed to

12661

ease shell processing.

12662

12663

@item -print-multi-os-directory

12664

@opindex print-multi-os-directory

12665

Print the path to OS libraries for the selected

12666

multilib, relative to some @file{lib} subdirectory. If OS libraries are

12667

present in the @file{lib} subdirectory and no multilibs are used, this is

12668

usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}}

12669

sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or

12670

@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}}

12671

subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}.

12672

12673

@item -print-multiarch

12674

@opindex print-multiarch

12675

Print the path to OS libraries for the selected multiarch,

12676

relative to some @file{lib} subdirectory.

12677

12678

@item -print-prog-name=@var{program}

12679

@opindex print-prog-name

12680

Like @option{-print-file-name}, but searches for a program such as @command{cpp}.

12681

12682

@item -print-libgcc-file-name

12683

@opindex print-libgcc-file-name

12684

Same as @option{-print-file-name=libgcc.a}.

12685

12686

This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}

12687

but you do want to link with @file{libgcc.a}. You can do:

12688

12689

@smallexample

12690

gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`

12691

@end smallexample

12692

12693

@item -print-search-dirs

12694

@opindex print-search-dirs

12695

Print the name of the configured installation directory and a list of

12696

program and library directories @command{gcc} searches---and don't do anything else.

12697

12698

This is useful when @command{gcc} prints the error message

12699

@samp{installation problem, cannot exec cpp0: No such file or directory}.

12700

To resolve this you either need to put @file{cpp0} and the other compiler

12701

components where @command{gcc} expects to find them, or you can set the environment

12702

variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.

12703

Don't forget the trailing @samp{/}.

12704

@xref{Environment Variables}.

12705

12706

@item -print-sysroot

12707

@opindex print-sysroot

12708

Print the target sysroot directory that is used during

12709

compilation. This is the target sysroot specified either at configure

12710

time or using the @option{--sysroot} option, possibly with an extra

12711

suffix that depends on compilation options. If no target sysroot is

12712

specified, the option prints nothing.

12713

12714

@item -print-sysroot-headers-suffix

12715

@opindex print-sysroot-headers-suffix

12716

Print the suffix added to the target sysroot when searching for

12717

headers, or give an error if the compiler is not configured with such

12718

a suffix---and don't do anything else.

12719

12720

@item -dumpmachine

12721

@opindex dumpmachine

12722

Print the compiler's target machine (for example,

12723

@samp{i686-pc-linux-gnu})---and don't do anything else.

12724

12725

@item -dumpversion

12726

@opindex dumpversion

12727

Print the compiler version (for example, @code{3.0})---and don't do

12728

anything else.

12729

12730

@item -dumpspecs

12731

@opindex dumpspecs

12732

Print the compiler's built-in specs---and don't do anything else. (This

12733

is used when GCC itself is being built.) @xref{Spec Files}.

12734

@end table

12735

12736

@node Submodel Options

12737

@section Machine-Dependent Options

12738

@cindex submodel options

12739

@cindex specifying hardware config

12740

@cindex hardware models and configurations, specifying

12741

@cindex target-dependent options

12742

@cindex machine-dependent options

12743

12744

Each target machine supported by GCC can have its own options---for

12745

example, to allow you to compile for a particular processor variant or

12746

ABI, or to control optimizations specific to that machine. By

12747

convention, the names of machine-specific options start with

12748

@samp{-m}.

12749

12750

Some configurations of the compiler also support additional target-specific

12751

options, usually for compatibility with other compilers on the same

12752

platform.

12753

12754

@c This list is ordered alphanumerically by subsection name.

12755

@c It should be the same order and spelling as these options are listed

12756

@c in Machine Dependent Options

12757

12758

@menu

12759

* AArch64 Options::

12760

* Adapteva Epiphany Options::

12761

* ARC Options::

12762

* ARM Options::

12763

* AVR Options::

12764

* Blackfin Options::

12765

* C6X Options::

12766

* CRIS Options::

12767

* CR16 Options::

12768

* Darwin Options::

12769

* DEC Alpha Options::

12770

* FR30 Options::

12771

* FT32 Options::

12772

* FRV Options::

12773

* GNU/Linux Options::

12774

* H8/300 Options::

12775

* HPPA Options::

12776

* IA-64 Options::

12777

* LM32 Options::

12778

* M32C Options::

12779

* M32R/D Options::

12780

* M680x0 Options::

12781

* MCore Options::

12782

* MeP Options::

12783

* MicroBlaze Options::

12784

* MIPS Options::

12785

* MMIX Options::

12786

* MN10300 Options::

12787

* Moxie Options::

12788

* MSP430 Options::

12789

* NDS32 Options::

12790

* Nios II Options::

12791

* Nvidia PTX Options::

12792

* PDP-11 Options::

12793

* picoChip Options::

12794

* PowerPC Options::

12795

* RL78 Options::

12796

* RS/6000 and PowerPC Options::

12797

* RX Options::

12798

* S/390 and zSeries Options::

12799

* Score Options::

12800

* SH Options::

12801

* Solaris 2 Options::

12802

* SPARC Options::

12803

* SPU Options::

12804

* System V Options::

12805

* TILE-Gx Options::

12806

* TILEPro Options::

12807

* V850 Options::

12808

* VAX Options::

12809

* Visium Options::

12810

* VMS Options::

12811

* VxWorks Options::

12812

* x86 Options::

12813

* x86 Windows Options::

12814

* Xstormy16 Options::

12815

* Xtensa Options::

12816

* zSeries Options::

12817

@end menu

12818

12819

@node AArch64 Options

12820

@subsection AArch64 Options

12821

@cindex AArch64 Options

12822

12823

These options are defined for AArch64 implementations:

12824

12825

@table @gcctabopt

12826

12827

@item -mabi=@var{name}

12828

@opindex mabi

12829

Generate code for the specified data model. Permissible values

12830

are @samp{ilp32} for SysV-like data model where int, long int and pointer

12831

are 32-bit, and @samp{lp64} for SysV-like data model where int is 32-bit,

12832

but long int and pointer are 64-bit.

12833

12834

The default depends on the specific target configuration. Note that

12835

the LP64 and ILP32 ABIs are not link-compatible; you must compile your

12836

entire program with the same ABI, and link with a compatible set of libraries.

12837

12838

@item -mbig-endian

12839

@opindex mbig-endian

12840

Generate big-endian code. This is the default when GCC is configured for an

12841

@samp{aarch64_be-*-*} target.

12842

12843

@item -mgeneral-regs-only

12844

@opindex mgeneral-regs-only

12845

Generate code which uses only the general-purpose registers. This will prevent

12846

the compiler from using floating-point and Advanced SIMD registers but will not

12847

impose any restrictions on the assembler.

12848

12849

@item -mlittle-endian

12850

@opindex mlittle-endian

12851

Generate little-endian code. This is the default when GCC is configured for an

12852

@samp{aarch64-*-*} but not an @samp{aarch64_be-*-*} target.

12853

12854

@item -mcmodel=tiny

12855

@opindex mcmodel=tiny

12856

Generate code for the tiny code model. The program and its statically defined

12857

symbols must be within 1GB of each other. Pointers are 64 bits. Programs can

12858

be statically or dynamically linked. This model is not fully implemented and

12859

mostly treated as @samp{small}.

12860

12861

@item -mcmodel=small

12862

@opindex mcmodel=small

12863

Generate code for the small code model. The program and its statically defined

12864

symbols must be within 4GB of each other. Pointers are 64 bits. Programs can

12865

be statically or dynamically linked. This is the default code model.

12866

12867

@item -mcmodel=large

12868

@opindex mcmodel=large

12869

Generate code for the large code model. This makes no assumptions about

12870

addresses and sizes of sections. Pointers are 64 bits. Programs can be

12871

statically linked only.

12872

12873

@item -mstrict-align

12874

@opindex mstrict-align

12875

Do not assume that unaligned memory references are handled by the system.

12876

12877

@item -momit-leaf-frame-pointer

12878

@itemx -mno-omit-leaf-frame-pointer

12879

@opindex momit-leaf-frame-pointer

12880

@opindex mno-omit-leaf-frame-pointer

12881

Omit or keep the frame pointer in leaf functions. The former behavior is the

12882

default.

12883

12884

@item -mtls-dialect=desc

12885

@opindex mtls-dialect=desc

12886

Use TLS descriptors as the thread-local storage mechanism for dynamic accesses

12887

of TLS variables. This is the default.

12888

12889

@item -mtls-dialect=traditional

12890

@opindex mtls-dialect=traditional

12891

Use traditional TLS as the thread-local storage mechanism for dynamic accesses

12892

of TLS variables.

12893

12894

@item -mtls-size=@var{size}

12895

@opindex mtls-size

12896

Specify bit size of immediate TLS offsets. Valid values are 12, 24, 32, 48.

12897

This option depends on binutils higher than 2.25.

12898

12899

@item -mfix-cortex-a53-835769

12900

@itemx -mno-fix-cortex-a53-835769

12901

@opindex mfix-cortex-a53-835769

12902

@opindex mno-fix-cortex-a53-835769

12903

Enable or disable the workaround for the ARM Cortex-A53 erratum number 835769.

12904

This involves inserting a NOP instruction between memory instructions and

12905

64-bit integer multiply-accumulate instructions.

12906

12907

@item -mfix-cortex-a53-843419

12908

@itemx -mno-fix-cortex-a53-843419

12909

@opindex mfix-cortex-a53-843419

12910

@opindex mno-fix-cortex-a53-843419

12911

Enable or disable the workaround for the ARM Cortex-A53 erratum number 843419.

12912

This erratum workaround is made at link time and this will only pass the

12913

corresponding flag to the linker.

12914

12915

@item -mlow-precision-recip-sqrt

12916

@item -mno-low-precision-recip-sqrt

12917

@opindex -mlow-precision-recip-sqrt

12918

@opindex -mno-low-precision-recip-sqrt

12919

When calculating the reciprocal square root approximation,

12920

uses one less step than otherwise, thus reducing latency and precision.

12921

This is only relevant if @option{-ffast-math} enables the reciprocal square root

12922

approximation, which in turn depends on the target processor.

12923

12924

@item -march=@var{name}

12925

@opindex march

12926

Specify the name of the target architecture and, optionally, one or

12927

more feature modifiers. This option has the form

12928

@option{-march=@var{arch}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}.

12929

12930

The permissible values for @var{arch} are @samp{armv8-a},

12931

@samp{armv8.1-a} or @var{native}.

12932

12933

The value @samp{armv8.1-a} implies @samp{armv8-a} and enables compiler

12934

support for the ARMv8.1 architecture extension. In particular, it

12935

enables the @samp{+crc} and @samp{+lse} features.

12936

12937

The value @samp{native} is available on native AArch64 GNU/Linux and

12938

causes the compiler to pick the architecture of the host system. This

12939

option has no effect if the compiler is unable to recognize the

12940

architecture of the host system,

12941

12942

The permissible values for @var{feature} are listed in the sub-section

12943

on @ref{aarch64-feature-modifiers,,@option{-march} and @option{-mcpu}

12944

Feature Modifiers}. Where conflicting feature modifiers are

12945

specified, the right-most feature is used.

12946

12947

GCC uses @var{name} to determine what kind of instructions it can emit

12948

when generating assembly code. If @option{-march} is specified

12949

without either of @option{-mtune} or @option{-mcpu} also being

12950

specified, the code is tuned to perform well across a range of target

12951

processors implementing the target architecture.

12952

12953

@item -mtune=@var{name}

12954

@opindex mtune

12955

Specify the name of the target processor for which GCC should tune the

12956

performance of the code. Permissible values for this option are:

12957

@samp{generic}, @samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a57},

12958

@samp{cortex-a72}, @samp{exynos-m1}, @samp{qdf24xx}, @samp{thunderx},

12959

@samp{xgene1}.

12960

12961

Additionally, this option can specify that GCC should tune the performance

12962

of the code for a big.LITTLE system. Permissible values for this

12963

option are: @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53}.

12964

12965

Additionally on native AArch64 GNU/Linux systems the value

12966

@samp{native} is available. This option causes the compiler to pick

12967

the architecture of and tune the performance of the code for the

12968

processor of the host system. This option has no effect if the

12969

compiler is unable to recognize the architecture of the host system.

12970

12971

Where none of @option{-mtune=}, @option{-mcpu=} or @option{-march=}

12972

are specified, the code is tuned to perform well across a range

12973

of target processors.

12974

12975

This option cannot be suffixed by feature modifiers.

12976

12977

@item -mcpu=@var{name}

12978

@opindex mcpu

12979

Specify the name of the target processor, optionally suffixed by one

12980

or more feature modifiers. This option has the form

12981

@option{-mcpu=@var{cpu}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}, where

12982

the permissible values for @var{cpu} are the same as those available

12983

for @option{-mtune}. The permissible values for @var{feature} are

12984

documented in the sub-section on

12985

@ref{aarch64-feature-modifiers,,@option{-march} and @option{-mcpu}

12986

Feature Modifiers}. Where conflicting feature modifiers are

12987

specified, the right-most feature is used.

12988

12989

Additionally on native AArch64 GNU/Linux systems the value

12990

@samp{native} is available. This option causes the compiler to tune

12991

the performance of the code for the processor of the host system.

12992

This option has no effect if the compiler is unable to recognize the

12993

architecture of the host system.

12994

12995

GCC uses @var{name} to determine what kind of instructions it can emit when

12996

generating assembly code (as if by @option{-march}) and to determine

12997

the target processor for which to tune for performance (as if

12998

by @option{-mtune}). Where this option is used in conjunction

12999

with @option{-march} or @option{-mtune}, those options take precedence

13000

over the appropriate part of this option.

13001

13002

@item -moverride=@var{string}

13003

@opindex moverride

13004

Override tuning decisions made by the back-end in response to a

13005

@option{-mtune=} switch. The syntax, semantics, and accepted values

13006

for @var{string} in this option are not guaranteed to be consistent

13007

across releases.

13008

13009

This option is only intended to be useful when developing GCC.

13010

13011

@item -mpc-relative-literal-loads

13012

@opindex mpcrelativeliteralloads

13013

Enable PC relative literal loads. If this option is used, literal

13014

pools are assumed to have a range of up to 1MiB and an appropriate

13015

instruction sequence is used. This option has no impact when used

13016

with @option{-mcmodel=tiny}.

13017

13018

@end table

13019

13020

@subsubsection @option{-march} and @option{-mcpu} Feature Modifiers

13021

@anchor{aarch64-feature-modifiers}

13022

@cindex @option{-march} feature modifiers

13023

@cindex @option{-mcpu} feature modifiers

13024

Feature modifiers used with @option{-march} and @option{-mcpu} can be any of

13025

the following and their inverses @option{no@var{feature}}:

13026

13027

@table @samp

13028

@item crc

13029

Enable CRC extension. This is on by default for

13030

@option{-march=armv8.1-a}.

13031

@item crypto

13032

Enable Crypto extension. This also enables Advanced SIMD and floating-point

13033

instructions.

13034

@item fp

13035

Enable floating-point instructions. This is on by default for all possible

13036

values for options @option{-march} and @option{-mcpu}.

13037

@item simd

13038

Enable Advanced SIMD instructions. This also enables floating-point

13039

instructions. This is on by default for all possible values for options

13040

@option{-march} and @option{-mcpu}.

13041

@item lse

13042

Enable Large System Extension instructions. This is on by default for

13043

@option{-march=armv8.1-a}.

13044

13045

@end table

13046

13047

That is, @option{crypto} implies @option{simd} implies @option{fp}.

13048

Conversely, @option{nofp} (or equivalently, @option{-mgeneral-regs-only})

13049

implies @option{nosimd} implies @option{nocrypto}.

13050

13051

@node Adapteva Epiphany Options

13052

@subsection Adapteva Epiphany Options

13053

13054

These @samp{-m} options are defined for Adapteva Epiphany:

13055

13056

@table @gcctabopt

13057

@item -mhalf-reg-file

13058

@opindex mhalf-reg-file

13059

Don't allocate any register in the range @code{r32}@dots{}@code{r63}.

13060

That allows code to run on hardware variants that lack these registers.

13061

13062

@item -mprefer-short-insn-regs

13063

@opindex mprefer-short-insn-regs

13064

Preferentially allocate registers that allow short instruction generation.

13065

This can result in increased instruction count, so this may either reduce or

13066

increase overall code size.

13067

13068

@item -mbranch-cost=@var{num}

13069

@opindex mbranch-cost

13070

Set the cost of branches to roughly @var{num} ``simple'' instructions.

13071

This cost is only a heuristic and is not guaranteed to produce

13072

consistent results across releases.

13073

13074

@item -mcmove

13075

@opindex mcmove

13076

Enable the generation of conditional moves.

13077

13078

@item -mnops=@var{num}

13079

@opindex mnops

13080

Emit @var{num} NOPs before every other generated instruction.

13081

13082

@item -mno-soft-cmpsf

13083

@opindex mno-soft-cmpsf

13084

For single-precision floating-point comparisons, emit an @code{fsub} instruction

13085

and test the flags. This is faster than a software comparison, but can

13086

get incorrect results in the presence of NaNs, or when two different small

13087

numbers are compared such that their difference is calculated as zero.

13088

The default is @option{-msoft-cmpsf}, which uses slower, but IEEE-compliant,

13089

software comparisons.

13090

13091

@item -mstack-offset=@var{num}

13092

@opindex mstack-offset

13093

Set the offset between the top of the stack and the stack pointer.

13094

E.g., a value of 8 means that the eight bytes in the range @code{sp+0@dots{}sp+7}

13095

can be used by leaf functions without stack allocation.

13096

Values other than @samp{8} or @samp{16} are untested and unlikely to work.

13097

Note also that this option changes the ABI; compiling a program with a

13098

different stack offset than the libraries have been compiled with

13099

generally does not work.

13100

This option can be useful if you want to evaluate if a different stack

13101

offset would give you better code, but to actually use a different stack

13102

offset to build working programs, it is recommended to configure the

13103

toolchain with the appropriate @option{--with-stack-offset=@var{num}} option.

13104

13105

@item -mno-round-nearest

13106

@opindex mno-round-nearest

13107

Make the scheduler assume that the rounding mode has been set to

13108

truncating. The default is @option{-mround-nearest}.

13109

13110

@item -mlong-calls

13111

@opindex mlong-calls

13112

If not otherwise specified by an attribute, assume all calls might be beyond

13113

the offset range of the @code{b} / @code{bl} instructions, and therefore load the

13114

function address into a register before performing a (otherwise direct) call.

13115

This is the default.

13116

13117

@item -mshort-calls

13118

@opindex short-calls

13119

If not otherwise specified by an attribute, assume all direct calls are

13120

in the range of the @code{b} / @code{bl} instructions, so use these instructions

13121

for direct calls. The default is @option{-mlong-calls}.

13122

13123

@item -msmall16

13124

@opindex msmall16

13125

Assume addresses can be loaded as 16-bit unsigned values. This does not

13126

apply to function addresses for which @option{-mlong-calls} semantics

13127

are in effect.

13128

13129

@item -mfp-mode=@var{mode}

13130

@opindex mfp-mode

13131

Set the prevailing mode of the floating-point unit.

13132

This determines the floating-point mode that is provided and expected

13133

at function call and return time. Making this mode match the mode you

13134

predominantly need at function start can make your programs smaller and

13135

faster by avoiding unnecessary mode switches.

13136

13137

@var{mode} can be set to one the following values:

13138

13139

@table @samp

13140

@item caller

13141

Any mode at function entry is valid, and retained or restored when

13142

the function returns, and when it calls other functions.

13143

This mode is useful for compiling libraries or other compilation units

13144

you might want to incorporate into different programs with different

13145

prevailing FPU modes, and the convenience of being able to use a single

13146

object file outweighs the size and speed overhead for any extra

13147

mode switching that might be needed, compared with what would be needed

13148

with a more specific choice of prevailing FPU mode.

13149

13150

@item truncate

13151

This is the mode used for floating-point calculations with

13152

truncating (i.e.@: round towards zero) rounding mode. That includes

13153

conversion from floating point to integer.

13154

13155

@item round-nearest

13156

This is the mode used for floating-point calculations with

13157

round-to-nearest-or-even rounding mode.

13158

13159

@item int

13160

This is the mode used to perform integer calculations in the FPU, e.g.@:

13161

integer multiply, or integer multiply-and-accumulate.

13162

@end table

13163

13164

The default is @option{-mfp-mode=caller}

13165

13166

@item -mnosplit-lohi

13167

@itemx -mno-postinc

13168

@itemx -mno-postmodify

13169

@opindex mnosplit-lohi

13170

@opindex mno-postinc

13171

@opindex mno-postmodify

13172

Code generation tweaks that disable, respectively, splitting of 32-bit

13173

loads, generation of post-increment addresses, and generation of

13174

post-modify addresses. The defaults are @option{msplit-lohi},

13175

@option{-mpost-inc}, and @option{-mpost-modify}.

13176

13177

@item -mnovect-double

13178

@opindex mno-vect-double

13179

Change the preferred SIMD mode to SImode. The default is

13180

@option{-mvect-double}, which uses DImode as preferred SIMD mode.

13181

13182

@item -max-vect-align=@var{num}

13183

@opindex max-vect-align

13184

The maximum alignment for SIMD vector mode types.

13185

@var{num} may be 4 or 8. The default is 8.

13186

Note that this is an ABI change, even though many library function

13187

interfaces are unaffected if they don't use SIMD vector modes

13188

in places that affect size and/or alignment of relevant types.

13189

13190

@item -msplit-vecmove-early

13191

@opindex msplit-vecmove-early

13192

Split vector moves into single word moves before reload. In theory this

13193

can give better register allocation, but so far the reverse seems to be

13194

generally the case.

13195

13196

@item -m1reg-@var{reg}

13197

@opindex m1reg-

13198

Specify a register to hold the constant @minus{}1, which makes loading small negative

13199

constants and certain bitmasks faster.

13200

Allowable values for @var{reg} are @samp{r43} and @samp{r63},

13201

which specify use of that register as a fixed register,

13202

and @samp{none}, which means that no register is used for this

13203

purpose. The default is @option{-m1reg-none}.

13204

13205

@end table

13206

13207

@node ARC Options

13208

@subsection ARC Options

13209

@cindex ARC options

13210

13211

The following options control the architecture variant for which code

13212

is being compiled:

13213

13214

@c architecture variants

13215

@table @gcctabopt

13216

13217

@item -mbarrel-shifter

13218

@opindex mbarrel-shifter

13219

Generate instructions supported by barrel shifter. This is the default

13220

unless @option{-mcpu=ARC601} or @samp{-mcpu=ARCEM} is in effect.

13221

13222

@item -mcpu=@var{cpu}

13223

@opindex mcpu

13224

Set architecture type, register usage, and instruction scheduling

13225

parameters for @var{cpu}. There are also shortcut alias options

13226

available for backward compatibility and convenience. Supported

13227

values for @var{cpu} are

13228

13229

@table @samp

13230

@opindex mA6

13231

@opindex mARC600

13232

@item ARC600

13233

@item arc600

13234

Compile for ARC600. Aliases: @option{-mA6}, @option{-mARC600}.

13235

13236

@item ARC601

13237

@item arc601

13238

@opindex mARC601

13239

Compile for ARC601. Alias: @option{-mARC601}.

13240

13241

@item ARC700

13242

@item arc700

13243

@opindex mA7

13244

@opindex mARC700

13245

Compile for ARC700. Aliases: @option{-mA7}, @option{-mARC700}.

13246

This is the default when configured with @option{--with-cpu=arc700}@.

13247

13248

@item ARCEM

13249

@item arcem

13250

Compile for ARC EM.

13251

13252

@item ARCHS

13253

@item archs

13254

Compile for ARC HS.

13255

@end table

13256

13257

@item -mdpfp

13258

@opindex mdpfp

13259

@itemx -mdpfp-compact

13260

@opindex mdpfp-compact

13261

FPX: Generate Double Precision FPX instructions, tuned for the compact

13262

implementation.

13263

13264

@item -mdpfp-fast

13265

@opindex mdpfp-fast

13266

FPX: Generate Double Precision FPX instructions, tuned for the fast

13267

implementation.

13268

13269

@item -mno-dpfp-lrsr

13270

@opindex mno-dpfp-lrsr

13271

Disable LR and SR instructions from using FPX extension aux registers.

13272

13273

@item -mea

13274

@opindex mea

13275

Generate Extended arithmetic instructions. Currently only

13276

@code{divaw}, @code{adds}, @code{subs}, and @code{sat16} are

13277

supported. This is always enabled for @option{-mcpu=ARC700}.

13278

13279

@item -mno-mpy

13280

@opindex mno-mpy

13281

Do not generate mpy instructions for ARC700.

13282

13283

@item -mmul32x16

13284

@opindex mmul32x16

13285

Generate 32x16 bit multiply and mac instructions.

13286

13287

@item -mmul64

13288

@opindex mmul64

13289

Generate mul64 and mulu64 instructions. Only valid for @option{-mcpu=ARC600}.

13290

13291

@item -mnorm

13292

@opindex mnorm

13293

Generate norm instruction. This is the default if @option{-mcpu=ARC700}

13294

is in effect.

13295

13296

@item -mspfp

13297

@opindex mspfp

13298

@itemx -mspfp-compact

13299

@opindex mspfp-compact

13300

FPX: Generate Single Precision FPX instructions, tuned for the compact

13301

implementation.

13302

13303

@item -mspfp-fast

13304

@opindex mspfp-fast

13305

FPX: Generate Single Precision FPX instructions, tuned for the fast

13306

implementation.

13307

13308

@item -msimd

13309

@opindex msimd

13310

Enable generation of ARC SIMD instructions via target-specific

13311

builtins. Only valid for @option{-mcpu=ARC700}.

13312

13313

@item -msoft-float

13314

@opindex msoft-float

13315

This option ignored; it is provided for compatibility purposes only.

13316

Software floating point code is emitted by default, and this default

13317

can overridden by FPX options; @samp{mspfp}, @samp{mspfp-compact}, or

13318

@samp{mspfp-fast} for single precision, and @samp{mdpfp},

13319

@samp{mdpfp-compact}, or @samp{mdpfp-fast} for double precision.

13320

13321

@item -mswap

13322

@opindex mswap

13323

Generate swap instructions.

13324

13325

@item -matomic

13326

@opindex matomic

13327

This enables Locked Load/Store Conditional extension to implement

13328

atomic memopry built-in functions. Not available for ARC 6xx or ARC

13329

EM cores.

13330

13331

@item -mdiv-rem

13332

@opindex mdiv-rem

13333

Enable DIV/REM instructions for ARCv2 cores.

13334

13335

@item -mcode-density

13336

@opindex mcode-density

13337

Enable code density instructions for ARC EM, default on for ARC HS.

13338

13339

@item -mll64

13340

@opindex mll64

13341

Enable double load/store operations for ARC HS cores.

13342

13343

@item -mmpy-option=@var{multo}

13344

@opindex mmpy-option

13345

Compile ARCv2 code with a multiplier design option. @samp{wlh1} is

13346

the default value. The recognized values for @var{multo} are:

13347

13348

@table @samp

13349

@item 0

13350

No multiplier available.

13351

13352

@item 1

13353

@opindex w

13354

The multiply option is set to w: 16x16 multiplier, fully pipelined.

13355

The following instructions are enabled: MPYW, and MPYUW.

13356

13357

@item 2

13358

@opindex wlh1

13359

The multiply option is set to wlh1: 32x32 multiplier, fully

13360

pipelined (1 stage). The following instructions are additionally

13361

enabled: MPY, MPYU, MPYM, MPYMU, and MPY_S.

13362

13363

@item 3

13364

@opindex wlh2

13365

The multiply option is set to wlh2: 32x32 multiplier, fully pipelined

13366

(2 stages). The following instructions are additionally enabled: MPY,

13367

MPYU, MPYM, MPYMU, and MPY_S.

13368

13369

@item 4

13370

@opindex wlh3

13371

The multiply option is set to wlh3: Two 16x16 multiplier, blocking,

13372

sequential. The following instructions are additionally enabled: MPY,

13373

MPYU, MPYM, MPYMU, and MPY_S.

13374

13375

@item 5

13376

@opindex wlh4

13377

The multiply option is set to wlh4: One 16x16 multiplier, blocking,

13378

sequential. The following instructions are additionally enabled: MPY,

13379

MPYU, MPYM, MPYMU, and MPY_S.

13380

13381

@item 6

13382

@opindex wlh5

13383

The multiply option is set to wlh5: One 32x4 multiplier, blocking,

13384

sequential. The following instructions are additionally enabled: MPY,

13385

MPYU, MPYM, MPYMU, and MPY_S.

13386

13387

@end table

13388

13389

This option is only available for ARCv2 cores@.

13390

13391

@item -mfpu=@var{fpu}

13392

@opindex mfpu

13393

Enables specific floating-point hardware extension for ARCv2

13394

core. Supported values for @var{fpu} are:

13395

13396

@table @samp

13397

13398

@item fpus

13399

@opindex fpus

13400

Enables support for single precision floating point hardware

13401

extensions@.

13402

13403

@item fpud

13404

@opindex fpud

13405

Enables support for double precision floating point hardware

13406

extensions. The single precision floating point extension is also

13407

enabled. Not available for ARC EM@.

13408

13409

@item fpuda

13410

@opindex fpuda

13411

Enables support for double precision floating point hardware

13412

extensions using double precision assist instructions. The single

13413

precision floating point extension is also enabled. This option is

13414

only available for ARC EM@.

13415

13416

@item fpuda_div

13417

@opindex fpuda_div

13418

Enables support for double precision floating point hardware

13419

extensions using double precision assist instructions, and simple

13420

precision square-root and divide hardware extensions. The single

13421

precision floating point extension is also enabled. This option is

13422

only available for ARC EM@.

13423

13424

@item fpuda_fma

13425

@opindex fpuda_fma

13426

Enables support for double precision floating point hardware

13427

extensions using double precision assist instructions, and simple

13428

precision fused multiple and add hardware extension. The single

13429

precision floating point extension is also enabled. This option is

13430

only available for ARC EM@.

13431

13432

@item fpuda_all

13433

@opindex fpuda_all

13434

Enables support for double precision floating point hardware

13435

extensions using double precision assist instructions, and all simple

13436

precision hardware extensions. The single precision floating point

13437

extension is also enabled. This option is only available for ARC EM@.

13438

13439

@item fpus_div

13440

@opindex fpus_div

13441

Enables support for single precision floating point, and single

13442

precision square-root and divide hardware extensions@.

13443

13444

@item fpud_div

13445

@opindex fpud_div

13446

Enables support for double precision floating point, and double

13447

precision square-root and divide hardware extensions. This option

13448

includes option @samp{fpus_div}. Not available for ARC EM@.

13449

13450

@item fpus_fma

13451

@opindex fpus_fma

13452

Enables support for single precision floating point, and single

13453

precision fused multiple and add hardware extensions@.

13454

13455

@item fpud_fma

13456

@opindex fpud_fma

13457

Enables support for double precision floating point, and double

13458

precision fused multiple and add hardware extensions. This option

13459

includes option @samp{fpus_fma}. Not available for ARC EM@.

13460

13461

@item fpus_all

13462

@opindex fpus_all

13463

Enables support for all single precision floating point hardware

13464

extensions@.

13465

13466

@item fpud_all

13467

@opindex fpud_all

13468

Enables support for all single and double precision floating point

13469

hardware extensions. Not available for ARC EM@.

13470

13471

@end table

13472

13473

@end table

13474

13475

The following options are passed through to the assembler, and also

13476

define preprocessor macro symbols.

13477

13478

@c Flags used by the assembler, but for which we define preprocessor

13479

@c macro symbols as well.

13480

@table @gcctabopt

13481

@item -mdsp-packa

13482

@opindex mdsp-packa

13483

Passed down to the assembler to enable the DSP Pack A extensions.

13484

Also sets the preprocessor symbol @code{__Xdsp_packa}.

13485

13486

@item -mdvbf

13487

@opindex mdvbf

13488

Passed down to the assembler to enable the dual viterbi butterfly

13489

extension. Also sets the preprocessor symbol @code{__Xdvbf}.

13490

13491

@c ARC700 4.10 extension instruction

13492

@item -mlock

13493

@opindex mlock

13494

Passed down to the assembler to enable the Locked Load/Store

13495

Conditional extension. Also sets the preprocessor symbol

13496

@code{__Xlock}.

13497

13498

@item -mmac-d16

13499

@opindex mmac-d16

13500

Passed down to the assembler. Also sets the preprocessor symbol

13501

@code{__Xxmac_d16}.

13502

13503

@item -mmac-24

13504

@opindex mmac-24

13505

Passed down to the assembler. Also sets the preprocessor symbol

13506

@code{__Xxmac_24}.

13507

13508

@c ARC700 4.10 extension instruction

13509

@item -mrtsc

13510

@opindex mrtsc

13511

Passed down to the assembler to enable the 64-bit Time-Stamp Counter

13512

extension instruction. Also sets the preprocessor symbol

13513

@code{__Xrtsc}.

13514

13515

@c ARC700 4.10 extension instruction

13516

@item -mswape

13517

@opindex mswape

13518

Passed down to the assembler to enable the swap byte ordering

13519

extension instruction. Also sets the preprocessor symbol

13520

@code{__Xswape}.

13521

13522

@item -mtelephony

13523

@opindex mtelephony

13524

Passed down to the assembler to enable dual and single operand

13525

instructions for telephony. Also sets the preprocessor symbol

13526

@code{__Xtelephony}.

13527

13528

@item -mxy

13529

@opindex mxy

13530

Passed down to the assembler to enable the XY Memory extension. Also

13531

sets the preprocessor symbol @code{__Xxy}.

13532

13533

@end table

13534

13535

The following options control how the assembly code is annotated:

13536

13537

@c Assembly annotation options

13538

@table @gcctabopt

13539

@item -misize

13540

@opindex misize

13541

Annotate assembler instructions with estimated addresses.

13542

13543

@item -mannotate-align

13544

@opindex mannotate-align

13545

Explain what alignment considerations lead to the decision to make an

13546

instruction short or long.

13547

13548

@end table

13549

13550

The following options are passed through to the linker:

13551

13552

@c options passed through to the linker

13553

@table @gcctabopt

13554

@item -marclinux

13555

@opindex marclinux

13556

Passed through to the linker, to specify use of the @code{arclinux} emulation.

13557

This option is enabled by default in tool chains built for

13558

@w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}} targets

13559

when profiling is not requested.

13560

13561

@item -marclinux_prof

13562

@opindex marclinux_prof

13563

Passed through to the linker, to specify use of the

13564

@code{arclinux_prof} emulation. This option is enabled by default in

13565

tool chains built for @w{@code{arc-linux-uclibc}} and

13566

@w{@code{arceb-linux-uclibc}} targets when profiling is requested.

13567

13568

@end table

13569

13570

The following options control the semantics of generated code:

13571

13572

@c semantically relevant code generation options

13573

@table @gcctabopt

13574

@item -mlong-calls

13575

@opindex mlong-calls

13576

Generate call insns as register indirect calls, thus providing access

13577

to the full 32-bit address range.

13578

13579

@item -mmedium-calls

13580

@opindex mmedium-calls

13581

Don't use less than 25 bit addressing range for calls, which is the

13582

offset available for an unconditional branch-and-link

13583

instruction. Conditional execution of function calls is suppressed, to

13584

allow use of the 25-bit range, rather than the 21-bit range with

13585

conditional branch-and-link. This is the default for tool chains built

13586

for @w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}} targets.

13587

13588

@item -mno-sdata

13589

@opindex mno-sdata

13590

Do not generate sdata references. This is the default for tool chains

13591

built for @w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}}

13592

targets.

13593

13594

@item -mucb-mcount

13595

@opindex mucb-mcount

13596

Instrument with mcount calls as used in UCB code. I.e. do the

13597

counting in the callee, not the caller. By default ARC instrumentation

13598

counts in the caller.

13599

13600

@item -mvolatile-cache

13601

@opindex mvolatile-cache

13602

Use ordinarily cached memory accesses for volatile references. This is the

13603

default.

13604

13605

@item -mno-volatile-cache

13606

@opindex mno-volatile-cache

13607

Enable cache bypass for volatile references.

13608

13609

@end table

13610

13611

The following options fine tune code generation:

13612

@c code generation tuning options

13613

@table @gcctabopt

13614

@item -malign-call

13615

@opindex malign-call

13616

Do alignment optimizations for call instructions.

13617

13618

@item -mauto-modify-reg

13619

@opindex mauto-modify-reg

13620

Enable the use of pre/post modify with register displacement.

13621

13622

@item -mbbit-peephole

13623

@opindex mbbit-peephole

13624

Enable bbit peephole2.

13625

13626

@item -mno-brcc

13627

@opindex mno-brcc

13628

This option disables a target-specific pass in @file{arc_reorg} to

13629

generate @code{BRcc} instructions. It has no effect on @code{BRcc}

13630

generation driven by the combiner pass.

13631

13632

@item -mcase-vector-pcrel

13633

@opindex mcase-vector-pcrel

13634

Use pc-relative switch case tables - this enables case table shortening.

13635

This is the default for @option{-Os}.

13636

13637

@item -mcompact-casesi

13638

@opindex mcompact-casesi

13639

Enable compact casesi pattern.

13640

This is the default for @option{-Os}.

13641

13642

@item -mno-cond-exec

13643

@opindex mno-cond-exec

13644

Disable ARCompact specific pass to generate conditional execution instructions.

13645

Due to delay slot scheduling and interactions between operand numbers,

13646

literal sizes, instruction lengths, and the support for conditional execution,

13647

the target-independent pass to generate conditional execution is often lacking,

13648

so the ARC port has kept a special pass around that tries to find more

13649

conditional execution generating opportunities after register allocation,

13650

branch shortening, and delay slot scheduling have been done. This pass

13651

generally, but not always, improves performance and code size, at the cost of

13652

extra compilation time, which is why there is an option to switch it off.

13653

If you have a problem with call instructions exceeding their allowable

13654

offset range because they are conditionalized, you should consider using

13655

@option{-mmedium-calls} instead.

13656

13657

@item -mearly-cbranchsi

13658

@opindex mearly-cbranchsi

13659

Enable pre-reload use of the cbranchsi pattern.

13660

13661

@item -mexpand-adddi

13662

@opindex mexpand-adddi

13663

Expand @code{adddi3} and @code{subdi3} at rtl generation time into

13664

@code{add.f}, @code{adc} etc.

13665

13666

@item -mindexed-loads

13667

@opindex mindexed-loads

13668

Enable the use of indexed loads. This can be problematic because some

13669

optimizers then assume that indexed stores exist, which is not

13670

the case.

13671

13672

@item -mlra

13673

@opindex mlra

13674

Enable Local Register Allocation. This is still experimental for ARC,

13675

so by default the compiler uses standard reload

13676

(i.e. @option{-mno-lra}).

13677

13678

@item -mlra-priority-none

13679

@opindex mlra-priority-none

13680

Don't indicate any priority for target registers.

13681

13682

@item -mlra-priority-compact

13683

@opindex mlra-priority-compact

13684

Indicate target register priority for r0..r3 / r12..r15.

13685

13686

@item -mlra-priority-noncompact

13687

@opindex mlra-priority-noncompact

13688

Reduce target register priority for r0..r3 / r12..r15.

13689

13690

@item -mno-millicode

13691

@opindex mno-millicode

13692

When optimizing for size (using @option{-Os}), prologues and epilogues

13693

that have to save or restore a large number of registers are often

13694

shortened by using call to a special function in libgcc; this is

13695

referred to as a @emph{millicode} call. As these calls can pose

13696

performance issues, and/or cause linking issues when linking in a

13697

nonstandard way, this option is provided to turn off millicode call

13698

generation.

13699

13700

@item -mmixed-code

13701

@opindex mmixed-code

13702

Tweak register allocation to help 16-bit instruction generation.

13703

This generally has the effect of decreasing the average instruction size

13704

while increasing the instruction count.

13705

13706

@item -mq-class

13707

@opindex mq-class

13708

Enable 'q' instruction alternatives.

13709

This is the default for @option{-Os}.

13710

13711

@item -mRcq

13712

@opindex mRcq

13713

Enable Rcq constraint handling - most short code generation depends on this.

13714

This is the default.

13715

13716

@item -mRcw

13717

@opindex mRcw

13718

Enable Rcw constraint handling - ccfsm condexec mostly depends on this.

13719

This is the default.

13720

13721

@item -msize-level=@var{level}

13722

@opindex msize-level

13723

Fine-tune size optimization with regards to instruction lengths and alignment.

13724

The recognized values for @var{level} are:

13725

@table @samp

13726

@item 0

13727

No size optimization. This level is deprecated and treated like @samp{1}.

13728

13729

@item 1

13730

Short instructions are used opportunistically.

13731

13732

@item 2

13733

In addition, alignment of loops and of code after barriers are dropped.

13734

13735

@item 3

13736

In addition, optional data alignment is dropped, and the option @option{Os} is enabled.

13737

13738

@end table

13739

13740

This defaults to @samp{3} when @option{-Os} is in effect. Otherwise,

13741

the behavior when this is not set is equivalent to level @samp{1}.

13742

13743

@item -mtune=@var{cpu}

13744

@opindex mtune

13745

Set instruction scheduling parameters for @var{cpu}, overriding any implied

13746

by @option{-mcpu=}.

13747

13748

Supported values for @var{cpu} are

13749

13750

@table @samp

13751

@item ARC600

13752

Tune for ARC600 cpu.

13753

13754

@item ARC601

13755

Tune for ARC601 cpu.

13756

13757

@item ARC700

13758

Tune for ARC700 cpu with standard multiplier block.

13759

13760

@item ARC700-xmac

13761

Tune for ARC700 cpu with XMAC block.

13762

13763

@item ARC725D

13764

Tune for ARC725D cpu.

13765

13766

@item ARC750D

13767

Tune for ARC750D cpu.

13768

13769

@end table

13770

13771

@item -mmultcost=@var{num}

13772

@opindex mmultcost

13773

Cost to assume for a multiply instruction, with @samp{4} being equal to a

13774

normal instruction.

13775

13776

@item -munalign-prob-threshold=@var{probability}

13777

@opindex munalign-prob-threshold

13778

Set probability threshold for unaligning branches.

13779

When tuning for @samp{ARC700} and optimizing for speed, branches without

13780

filled delay slot are preferably emitted unaligned and long, unless

13781

profiling indicates that the probability for the branch to be taken

13782

is below @var{probability}. @xref{Cross-profiling}.

13783

The default is (REG_BR_PROB_BASE/2), i.e.@: 5000.

13784

13785

@end table

13786

13787

The following options are maintained for backward compatibility, but

13788

are now deprecated and will be removed in a future release:

13789

13790

@c Deprecated options

13791

@table @gcctabopt

13792

13793

@item -margonaut

13794

@opindex margonaut

13795

Obsolete FPX.

13796

13797

@item -mbig-endian

13798

@opindex mbig-endian

13799

@itemx -EB

13800

@opindex EB

13801

Compile code for big endian targets. Use of these options is now

13802

deprecated. Users wanting big-endian code, should use the

13803

@w{@code{arceb-elf32}} and @w{@code{arceb-linux-uclibc}} targets when

13804

building the tool chain, for which big-endian is the default.

13805

13806

@item -mlittle-endian

13807

@opindex mlittle-endian

13808

@itemx -EL

13809

@opindex EL

13810

Compile code for little endian targets. Use of these options is now

13811

deprecated. Users wanting little-endian code should use the

13812

@w{@code{arc-elf32}} and @w{@code{arc-linux-uclibc}} targets when

13813

building the tool chain, for which little-endian is the default.

13814

13815

@item -mbarrel_shifter

13816

@opindex mbarrel_shifter

13817

Replaced by @option{-mbarrel-shifter}.

13818

13819

@item -mdpfp_compact

13820

@opindex mdpfp_compact

13821

Replaced by @option{-mdpfp-compact}.

13822

13823

@item -mdpfp_fast

13824

@opindex mdpfp_fast

13825

Replaced by @option{-mdpfp-fast}.

13826

13827

@item -mdsp_packa

13828

@opindex mdsp_packa

13829

Replaced by @option{-mdsp-packa}.

13830

13831

@item -mEA

13832

@opindex mEA

13833

Replaced by @option{-mea}.

13834

13835

@item -mmac_24

13836

@opindex mmac_24

13837

Replaced by @option{-mmac-24}.

13838

13839

@item -mmac_d16

13840

@opindex mmac_d16

13841

Replaced by @option{-mmac-d16}.

13842

13843

@item -mspfp_compact

13844

@opindex mspfp_compact

13845

Replaced by @option{-mspfp-compact}.

13846

13847

@item -mspfp_fast

13848

@opindex mspfp_fast

13849

Replaced by @option{-mspfp-fast}.

13850

13851

@item -mtune=@var{cpu}

13852

@opindex mtune

13853

Values @samp{arc600}, @samp{arc601}, @samp{arc700} and

13854

@samp{arc700-xmac} for @var{cpu} are replaced by @samp{ARC600},

13855

@samp{ARC601}, @samp{ARC700} and @samp{ARC700-xmac} respectively

13856

13857

@item -multcost=@var{num}

13858

@opindex multcost

13859

Replaced by @option{-mmultcost}.

13860

13861

@end table

13862

13863

@node ARM Options

13864

@subsection ARM Options

13865

@cindex ARM options

13866

13867

These @samp{-m} options are defined for the ARM port:

13868

13869

@table @gcctabopt

13870

@item -mabi=@var{name}

13871

@opindex mabi

13872

Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},

13873

@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.

13874

13875

@item -mapcs-frame

13876

@opindex mapcs-frame

13877

Generate a stack frame that is compliant with the ARM Procedure Call

13878

Standard for all functions, even if this is not strictly necessary for

13879

correct execution of the code. Specifying @option{-fomit-frame-pointer}

13880

with this option causes the stack frames not to be generated for

13881

leaf functions. The default is @option{-mno-apcs-frame}.

13882

This option is deprecated.

13883

13884

@item -mapcs

13885

@opindex mapcs

13886

This is a synonym for @option{-mapcs-frame} and is deprecated.

13887

13888

@ignore

13889

@c not currently implemented

13890

@item -mapcs-stack-check

13891

@opindex mapcs-stack-check

13892

Generate code to check the amount of stack space available upon entry to

13893

every function (that actually uses some stack space). If there is

13894

insufficient space available then either the function

13895

@code{__rt_stkovf_split_small} or @code{__rt_stkovf_split_big} is

13896

called, depending upon the amount of stack space required. The runtime

13897

system is required to provide these functions. The default is

13898

@option{-mno-apcs-stack-check}, since this produces smaller code.

13899

13900

@c not currently implemented

13901

@item -mapcs-float

13902

@opindex mapcs-float

13903

Pass floating-point arguments using the floating-point registers. This is

13904

one of the variants of the APCS@. This option is recommended if the

13905

target hardware has a floating-point unit or if a lot of floating-point

13906

arithmetic is going to be performed by the code. The default is

13907

@option{-mno-apcs-float}, since the size of integer-only code is

13908

slightly increased if @option{-mapcs-float} is used.

13909

13910

@c not currently implemented

13911

@item -mapcs-reentrant

13912

@opindex mapcs-reentrant

13913

Generate reentrant, position-independent code. The default is

13914

@option{-mno-apcs-reentrant}.

13915

@end ignore

13916

13917

@item -mthumb-interwork

13918

@opindex mthumb-interwork

13919

Generate code that supports calling between the ARM and Thumb

13920

instruction sets. Without this option, on pre-v5 architectures, the

13921

two instruction sets cannot be reliably used inside one program. The

13922

default is @option{-mno-thumb-interwork}, since slightly larger code

13923

is generated when @option{-mthumb-interwork} is specified. In AAPCS

13924

configurations this option is meaningless.

13925

13926

@item -mno-sched-prolog

13927

@opindex mno-sched-prolog

13928

Prevent the reordering of instructions in the function prologue, or the

13929

merging of those instruction with the instructions in the function's

13930

body. This means that all functions start with a recognizable set

13931

of instructions (or in fact one of a choice from a small set of

13932

different function prologues), and this information can be used to

13933

locate the start of functions inside an executable piece of code. The

13934

default is @option{-msched-prolog}.

13935

13936

@item -mfloat-abi=@var{name}

13937

@opindex mfloat-abi

13938

Specifies which floating-point ABI to use. Permissible values

13939

are: @samp{soft}, @samp{softfp} and @samp{hard}.

13940

13941

Specifying @samp{soft} causes GCC to generate output containing

13942

library calls for floating-point operations.

13943

@samp{softfp} allows the generation of code using hardware floating-point

13944

instructions, but still uses the soft-float calling conventions.

13945

@samp{hard} allows generation of floating-point instructions

13946

and uses FPU-specific calling conventions.

13947

13948

The default depends on the specific target configuration. Note that

13949

the hard-float and soft-float ABIs are not link-compatible; you must

13950

compile your entire program with the same ABI, and link with a

13951

compatible set of libraries.

13952

13953

@item -mlittle-endian

13954

@opindex mlittle-endian

13955

Generate code for a processor running in little-endian mode. This is

13956

the default for all standard configurations.

13957

13958

@item -mbig-endian

13959

@opindex mbig-endian

13960

Generate code for a processor running in big-endian mode; the default is

13961

to compile code for a little-endian processor.

13962

13963

@item -march=@var{name}

13964

@opindex march

13965

This specifies the name of the target ARM architecture. GCC uses this

13966

name to determine what kind of instructions it can emit when generating

13967

assembly code. This option can be used in conjunction with or instead

13968

of the @option{-mcpu=} option. Permissible names are: @samp{armv2},

13969

@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},

13970

@samp{armv5}, @samp{armv5t}, @samp{armv5e}, @samp{armv5te},

13971

@samp{armv6}, @samp{armv6j},

13972

@samp{armv6t2}, @samp{armv6z}, @samp{armv6kz}, @samp{armv6-m},

13973

@samp{armv7}, @samp{armv7-a}, @samp{armv7-r}, @samp{armv7-m}, @samp{armv7e-m},

13974

@samp{armv7ve}, @samp{armv8-a}, @samp{armv8-a+crc}, @samp{armv8.1-a},

13975

@samp{armv8.1-a+crc}, @samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}.

13976

13977

Architecture revisions older than @option{armv4t} are deprecated.

13978

13979

@option{-march=armv7ve} is the armv7-a architecture with virtualization

13980

extensions.

13981

13982

@option{-march=armv8-a+crc} enables code generation for the ARMv8-A

13983

architecture together with the optional CRC32 extensions.

13984

13985

@option{-march=native} causes the compiler to auto-detect the architecture

13986

of the build computer. At present, this feature is only supported on

13987

GNU/Linux, and not all architectures are recognized. If the auto-detect

13988

is unsuccessful the option has no effect.

13989

13990

@item -mtune=@var{name}

13991

@opindex mtune

13992

This option specifies the name of the target ARM processor for

13993

which GCC should tune the performance of the code.

13994

For some ARM implementations better performance can be obtained by using

13995

this option.

13996

Permissible names are: @samp{arm2}, @samp{arm250},

13997

@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},

13998

@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},

13999

@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},

14000

@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},

14001

@samp{arm720},

14002

@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},

14003

@samp{arm710t}, @samp{arm720t}, @samp{arm740t},

14004

@samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},

14005

@samp{strongarm1110},

14006

@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},

14007

@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},

14008

@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},

14009

@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},

14010

@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},

14011

@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},

14012

@samp{arm1156t2-s}, @samp{arm1156t2f-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},

14013

@samp{generic-armv7-a}, @samp{cortex-a5}, @samp{cortex-a7}, @samp{cortex-a8},

14014

@samp{cortex-a9}, @samp{cortex-a12}, @samp{cortex-a15}, @samp{cortex-a17},

14015

@samp{cortex-a32}, @samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a57},

14016

@samp{cortex-a72}, @samp{cortex-r4},

14017

@samp{cortex-r4f}, @samp{cortex-r5}, @samp{cortex-r7}, @samp{cortex-r8},

14018

@samp{cortex-m7},

14019

@samp{cortex-m4},

14020

@samp{cortex-m3},

14021

@samp{cortex-m1},

14022

@samp{cortex-m0},

14023

@samp{cortex-m0plus},

14024

@samp{cortex-m1.small-multiply},

14025

@samp{cortex-m0.small-multiply},

14026

@samp{cortex-m0plus.small-multiply},

14027

@samp{exynos-m1},

14028

@samp{qdf24xx},

14029

@samp{marvell-pj4},

14030

@samp{xscale}, @samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312},

14031

@samp{fa526}, @samp{fa626},

14032

@samp{fa606te}, @samp{fa626te}, @samp{fmp626}, @samp{fa726te},

14033

@samp{xgene1}.

14034

14035

Additionally, this option can specify that GCC should tune the performance

14036

of the code for a big.LITTLE system. Permissible names are:

14037

@samp{cortex-a15.cortex-a7}, @samp{cortex-a17.cortex-a7},

14038

@samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53}.

14039

14040

@option{-mtune=generic-@var{arch}} specifies that GCC should tune the

14041

performance for a blend of processors within architecture @var{arch}.

14042

The aim is to generate code that run well on the current most popular

14043

processors, balancing between optimizations that benefit some CPUs in the

14044

range, and avoiding performance pitfalls of other CPUs. The effects of

14045

this option may change in future GCC versions as CPU models come and go.

14046

14047

@option{-mtune=native} causes the compiler to auto-detect the CPU

14048

of the build computer. At present, this feature is only supported on

14049

GNU/Linux, and not all architectures are recognized. If the auto-detect is

14050

unsuccessful the option has no effect.

14051

14052

@item -mcpu=@var{name}

14053

@opindex mcpu

14054

This specifies the name of the target ARM processor. GCC uses this name

14055

to derive the name of the target ARM architecture (as if specified

14056

by @option{-march}) and the ARM processor type for which to tune for

14057

performance (as if specified by @option{-mtune}). Where this option

14058

is used in conjunction with @option{-march} or @option{-mtune},

14059

those options take precedence over the appropriate part of this option.

14060

14061

Permissible names for this option are the same as those for

14062

@option{-mtune}.

14063

14064

@option{-mcpu=generic-@var{arch}} is also permissible, and is

14065

equivalent to @option{-march=@var{arch} -mtune=generic-@var{arch}}.

14066

See @option{-mtune} for more information.

14067

14068

@option{-mcpu=native} causes the compiler to auto-detect the CPU

14069

of the build computer. At present, this feature is only supported on

14070

GNU/Linux, and not all architectures are recognized. If the auto-detect

14071

is unsuccessful the option has no effect.

14072

14073

@item -mfpu=@var{name}

14074

@opindex mfpu

14075

This specifies what floating-point hardware (or hardware emulation) is

14076

available on the target. Permissible names are: @samp{vfp}, @samp{vfpv3},

14077

@samp{vfpv3-fp16}, @samp{vfpv3-d16}, @samp{vfpv3-d16-fp16}, @samp{vfpv3xd},

14078

@samp{vfpv3xd-fp16}, @samp{neon}, @samp{neon-fp16}, @samp{vfpv4},

14079

@samp{vfpv4-d16}, @samp{fpv4-sp-d16}, @samp{neon-vfpv4},

14080

@samp{fpv5-d16}, @samp{fpv5-sp-d16},

14081

@samp{fp-armv8}, @samp{neon-fp-armv8} and @samp{crypto-neon-fp-armv8}.

14082

14083

If @option{-msoft-float} is specified this specifies the format of

14084

floating-point values.

14085

14086

If the selected floating-point hardware includes the NEON extension

14087

(e.g. @option{-mfpu}=@samp{neon}), note that floating-point

14088

operations are not generated by GCC's auto-vectorization pass unless

14089

@option{-funsafe-math-optimizations} is also specified. This is

14090

because NEON hardware does not fully implement the IEEE 754 standard for

14091

floating-point arithmetic (in particular denormal values are treated as

14092

zero), so the use of NEON instructions may lead to a loss of precision.

14093

14094

You can also set the fpu name at function level by using the @code{target("fpu=")} function attributes (@pxref{ARM Function Attributes}) or pragmas (@pxref{Function Specific Option Pragmas}).

14095

14096

@item -mfp16-format=@var{name}

14097

@opindex mfp16-format

14098

Specify the format of the @code{__fp16} half-precision floating-point type.

14099

Permissible names are @samp{none}, @samp{ieee}, and @samp{alternative};

14100

the default is @samp{none}, in which case the @code{__fp16} type is not

14101

defined. @xref{Half-Precision}, for more information.

14102

14103

@item -mstructure-size-boundary=@var{n}

14104

@opindex mstructure-size-boundary

14105

The sizes of all structures and unions are rounded up to a multiple

14106

of the number of bits set by this option. Permissible values are 8, 32

14107

and 64. The default value varies for different toolchains. For the COFF

14108

targeted toolchain the default value is 8. A value of 64 is only allowed

14109

if the underlying ABI supports it.

14110

14111

Specifying a larger number can produce faster, more efficient code, but

14112

can also increase the size of the program. Different values are potentially

14113

incompatible. Code compiled with one value cannot necessarily expect to

14114

work with code or libraries compiled with another value, if they exchange

14115

information using structures or unions.

14116

14117

@item -mabort-on-noreturn

14118

@opindex mabort-on-noreturn

14119

Generate a call to the function @code{abort} at the end of a

14120

@code{noreturn} function. It is executed if the function tries to

14121

return.

14122

14123

@item -mlong-calls

14124

@itemx -mno-long-calls

14125

@opindex mlong-calls

14126

@opindex mno-long-calls

14127

Tells the compiler to perform function calls by first loading the

14128

address of the function into a register and then performing a subroutine

14129

call on this register. This switch is needed if the target function

14130

lies outside of the 64-megabyte addressing range of the offset-based

14131

version of subroutine call instruction.

14132

14133

Even if this switch is enabled, not all function calls are turned

14134

into long calls. The heuristic is that static functions, functions

14135

that have the @code{short_call} attribute, functions that are inside

14136

the scope of a @code{#pragma no_long_calls} directive, and functions whose

14137

definitions have already been compiled within the current compilation

14138

unit are not turned into long calls. The exceptions to this rule are

14139

that weak function definitions, functions with the @code{long_call}

14140

attribute or the @code{section} attribute, and functions that are within

14141

the scope of a @code{#pragma long_calls} directive are always

14142

turned into long calls.

14143

14144

This feature is not enabled by default. Specifying

14145

@option{-mno-long-calls} restores the default behavior, as does

14146

placing the function calls within the scope of a @code{#pragma

14147

long_calls_off} directive. Note these switches have no effect on how

14148

the compiler generates code to handle function calls via function

14149

pointers.

14150

14151

@item -msingle-pic-base

14152

@opindex msingle-pic-base

14153

Treat the register used for PIC addressing as read-only, rather than

14154

loading it in the prologue for each function. The runtime system is

14155

responsible for initializing this register with an appropriate value

14156

before execution begins.

14157

14158

@item -mpic-register=@var{reg}

14159

@opindex mpic-register

14160

Specify the register to be used for PIC addressing.

14161

For standard PIC base case, the default is any suitable register

14162

determined by compiler. For single PIC base case, the default is

14163

@samp{R9} if target is EABI based or stack-checking is enabled,

14164

otherwise the default is @samp{R10}.

14165

14166

@item -mpic-data-is-text-relative

14167

@opindex mpic-data-is-text-relative

14168

Assume that each data segments are relative to text segment at load time.

14169

Therefore, it permits addressing data using PC-relative operations.

14170

This option is on by default for targets other than VxWorks RTP.

14171

14172

@item -mpoke-function-name

14173

@opindex mpoke-function-name

14174

Write the name of each function into the text section, directly

14175

preceding the function prologue. The generated code is similar to this:

14176

14177

@smallexample

14178

t0

14179

.ascii "arm_poke_function_name", 0

14180

.align

14181

t1

14182

.word 0xff000000 + (t1 - t0)

14183

arm_poke_function_name

14184

mov ip, sp

14185

stmfd sp!, @{fp, ip, lr, pc@}

14186

sub fp, ip, #4

14187

@end smallexample

14188

14189

When performing a stack backtrace, code can inspect the value of

14190

@code{pc} stored at @code{fp + 0}. If the trace function then looks at

14191

location @code{pc - 12} and the top 8 bits are set, then we know that

14192

there is a function name embedded immediately preceding this location

14193

and has length @code{((pc[-3]) & 0xff000000)}.

14194

14195

@item -mthumb

14196

@itemx -marm

14197

@opindex marm

14198

@opindex mthumb

14199

14200

Select between generating code that executes in ARM and Thumb

14201

states. The default for most configurations is to generate code

14202

that executes in ARM state, but the default can be changed by

14203

configuring GCC with the @option{--with-mode=}@var{state}

14204

configure option.

14205

14206

You can also override the ARM and Thumb mode for each function

14207

by using the @code{target("thumb")} and @code{target("arm")} function attributes

14208

(@pxref{ARM Function Attributes}) or pragmas (@pxref{Function Specific Option Pragmas}).

14209

14210

@item -mtpcs-frame

14211

@opindex mtpcs-frame

14212

Generate a stack frame that is compliant with the Thumb Procedure Call

14213

Standard for all non-leaf functions. (A leaf function is one that does

14214

not call any other functions.) The default is @option{-mno-tpcs-frame}.

14215

14216

@item -mtpcs-leaf-frame

14217

@opindex mtpcs-leaf-frame

14218

Generate a stack frame that is compliant with the Thumb Procedure Call

14219

Standard for all leaf functions. (A leaf function is one that does

14220

not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.

14221

14222

@item -mcallee-super-interworking

14223

@opindex mcallee-super-interworking

14224

Gives all externally visible functions in the file being compiled an ARM

14225

instruction set header which switches to Thumb mode before executing the

14226

rest of the function. This allows these functions to be called from

14227

non-interworking code. This option is not valid in AAPCS configurations

14228

because interworking is enabled by default.

14229

14230

@item -mcaller-super-interworking

14231

@opindex mcaller-super-interworking

14232

Allows calls via function pointers (including virtual functions) to

14233

execute correctly regardless of whether the target code has been

14234

compiled for interworking or not. There is a small overhead in the cost

14235

of executing a function pointer if this option is enabled. This option

14236

is not valid in AAPCS configurations because interworking is enabled

14237

by default.

14238

14239

@item -mtp=@var{name}

14240

@opindex mtp

14241

Specify the access model for the thread local storage pointer. The valid

14242

models are @samp{soft}, which generates calls to @code{__aeabi_read_tp},

14243

@samp{cp15}, which fetches the thread pointer from @code{cp15} directly

14244

(supported in the arm6k architecture), and @samp{auto}, which uses the

14245

best available method for the selected processor. The default setting is

14246

@samp{auto}.

14247

14248

@item -mtls-dialect=@var{dialect}

14249

@opindex mtls-dialect

14250

Specify the dialect to use for accessing thread local storage. Two

14251

@var{dialect}s are supported---@samp{gnu} and @samp{gnu2}. The

14252

@samp{gnu} dialect selects the original GNU scheme for supporting

14253

local and global dynamic TLS models. The @samp{gnu2} dialect

14254

selects the GNU descriptor scheme, which provides better performance

14255

for shared libraries. The GNU descriptor scheme is compatible with

14256

the original scheme, but does require new assembler, linker and

14257

library support. Initial and local exec TLS models are unaffected by

14258

this option and always use the original scheme.

14259

14260

@item -mword-relocations

14261

@opindex mword-relocations

14262

Only generate absolute relocations on word-sized values (i.e. R_ARM_ABS32).

14263

This is enabled by default on targets (uClinux, SymbianOS) where the runtime

14264

loader imposes this restriction, and when @option{-fpic} or @option{-fPIC}

14265

is specified.

14266

14267

@item -mfix-cortex-m3-ldrd

14268

@opindex mfix-cortex-m3-ldrd

14269

Some Cortex-M3 cores can cause data corruption when @code{ldrd} instructions

14270

with overlapping destination and base registers are used. This option avoids

14271

generating these instructions. This option is enabled by default when

14272

@option{-mcpu=cortex-m3} is specified.

14273

14274

@item -munaligned-access

14275

@itemx -mno-unaligned-access

14276

@opindex munaligned-access

14277

@opindex mno-unaligned-access

14278

Enables (or disables) reading and writing of 16- and 32- bit values

14279

from addresses that are not 16- or 32- bit aligned. By default

14280

unaligned access is disabled for all pre-ARMv6 and all ARMv6-M

14281

architectures, and enabled for all other architectures. If unaligned

14282

access is not enabled then words in packed data structures are

14283

accessed a byte at a time.

14284

14285

The ARM attribute @code{Tag_CPU_unaligned_access} is set in the

14286

generated object file to either true or false, depending upon the

14287

setting of this option. If unaligned access is enabled then the

14288

preprocessor symbol @code{__ARM_FEATURE_UNALIGNED} is also

14289

defined.

14290

14291

@item -mneon-for-64bits

14292

@opindex mneon-for-64bits

14293

Enables using Neon to handle scalar 64-bits operations. This is

14294

disabled by default since the cost of moving data from core registers

14295

to Neon is high.

14296

14297

@item -mslow-flash-data

14298

@opindex mslow-flash-data

14299

Assume loading data from flash is slower than fetching instruction.

14300

Therefore literal load is minimized for better performance.

14301

This option is only supported when compiling for ARMv7 M-profile and

14302

off by default.

14303

14304

@item -masm-syntax-unified

14305

@opindex masm-syntax-unified

14306

Assume inline assembler is using unified asm syntax. The default is

14307

currently off which implies divided syntax. This option has no impact

14308

on Thumb2. However, this may change in future releases of GCC.

14309

Divided syntax should be considered deprecated.

14310

14311

@item -mrestrict-it

14312

@opindex mrestrict-it

14313

Restricts generation of IT blocks to conform to the rules of ARMv8.

14314

IT blocks can only contain a single 16-bit instruction from a select

14315

set of instructions. This option is on by default for ARMv8 Thumb mode.

14316

14317

@item -mprint-tune-info

14318

@opindex mprint-tune-info

14319

Print CPU tuning information as comment in assembler file. This is

14320

an option used only for regression testing of the compiler and not

14321

intended for ordinary use in compiling code. This option is disabled

14322

by default.

14323

@end table

14324

14325

@node AVR Options

14326

@subsection AVR Options

14327

@cindex AVR Options

14328

14329

These options are defined for AVR implementations:

14330

14331

@table @gcctabopt

14332

@item -mmcu=@var{mcu}

14333

@opindex mmcu

14334

Specify Atmel AVR instruction set architectures (ISA) or MCU type.

14335

14336

The default for this option is@tie{}@samp{avr2}.

14337

14338

GCC supports the following AVR devices and ISAs:

14339

14340

@include avr-mmcu.texi

14341

14342

@item -maccumulate-args

14343

@opindex maccumulate-args

14344

Accumulate outgoing function arguments and acquire/release the needed

14345

stack space for outgoing function arguments once in function

14346

prologue/epilogue. Without this option, outgoing arguments are pushed

14347

before calling a function and popped afterwards.

14348

14349

Popping the arguments after the function call can be expensive on

14350

AVR so that accumulating the stack space might lead to smaller

14351

executables because arguments need not to be removed from the

14352

stack after such a function call.

14353

14354

This option can lead to reduced code size for functions that perform

14355

several calls to functions that get their arguments on the stack like

14356

calls to printf-like functions.

14357

14358

@item -mbranch-cost=@var{cost}

14359

@opindex mbranch-cost

14360

Set the branch costs for conditional branch instructions to

14361

@var{cost}. Reasonable values for @var{cost} are small, non-negative

14362

integers. The default branch cost is 0.

14363

14364

@item -mcall-prologues

14365

@opindex mcall-prologues

14366

Functions prologues/epilogues are expanded as calls to appropriate

14367

subroutines. Code size is smaller.

14368

14369

@item -mint8

14370

@opindex mint8

14371

Assume @code{int} to be 8-bit integer. This affects the sizes of all types: a

14372

@code{char} is 1 byte, an @code{int} is 1 byte, a @code{long} is 2 bytes,

14373

and @code{long long} is 4 bytes. Please note that this option does not

14374

conform to the C standards, but it results in smaller code

14375

size.

14376

14377

@item -mn-flash=@var{num}

14378

@opindex mn-flash

14379

Assume that the flash memory has a size of

14380

@var{num} times 64@tie{}KiB.

14381

14382

@item -mno-interrupts

14383

@opindex mno-interrupts

14384

Generated code is not compatible with hardware interrupts.

14385

Code size is smaller.

14386

14387

@item -mrelax

14388

@opindex mrelax

14389

Try to replace @code{CALL} resp.@: @code{JMP} instruction by the shorter

14390

@code{RCALL} resp.@: @code{RJMP} instruction if applicable.

14391

Setting @option{-mrelax} just adds the @option{--mlink-relax} option to

14392

the assembler's command line and the @option{--relax} option to the

14393

linker's command line.

14394

14395

Jump relaxing is performed by the linker because jump offsets are not

14396

known before code is located. Therefore, the assembler code generated by the

14397

compiler is the same, but the instructions in the executable may

14398

differ from instructions in the assembler code.

14399

14400

Relaxing must be turned on if linker stubs are needed, see the

14401

section on @code{EIND} and linker stubs below.

14402

14403

@item -mrmw

14404

@opindex mrmw

14405

Assume that the device supports the Read-Modify-Write

14406

instructions @code{XCH}, @code{LAC}, @code{LAS} and @code{LAT}.

14407

14408

@item -msp8

14409

@opindex msp8

14410

Treat the stack pointer register as an 8-bit register,

14411

i.e.@: assume the high byte of the stack pointer is zero.

14412

In general, you don't need to set this option by hand.

14413

14414

This option is used internally by the compiler to select and

14415

build multilibs for architectures @code{avr2} and @code{avr25}.

14416

These architectures mix devices with and without @code{SPH}.

14417

For any setting other than @option{-mmcu=avr2} or @option{-mmcu=avr25}

14418

the compiler driver adds or removes this option from the compiler

14419

proper's command line, because the compiler then knows if the device

14420

or architecture has an 8-bit stack pointer and thus no @code{SPH}

14421

register or not.

14422

14423

@item -mstrict-X

14424

@opindex mstrict-X

14425

Use address register @code{X} in a way proposed by the hardware. This means

14426

that @code{X} is only used in indirect, post-increment or

14427

pre-decrement addressing.

14428

14429

Without this option, the @code{X} register may be used in the same way

14430

as @code{Y} or @code{Z} which then is emulated by additional

14431

instructions.

14432

For example, loading a value with @code{X+const} addressing with a

14433

small non-negative @code{const < 64} to a register @var{Rn} is

14434

performed as

14435

14436

@example

14437

adiw r26, const ; X += const

14438

ld @var{Rn}, X ; @var{Rn} = *X

14439

sbiw r26, const ; X -= const

14440

@end example

14441

14442

@item -mtiny-stack

14443

@opindex mtiny-stack

14444

Only change the lower 8@tie{}bits of the stack pointer.

14445

14446

@item -nodevicelib

14447

@opindex nodevicelib

14448

Don't link against AVR-LibC's device specific library @code{libdev.a}.

14449

14450

@item -Waddr-space-convert

14451

@opindex Waddr-space-convert

14452

Warn about conversions between address spaces in the case where the

14453

resulting address space is not contained in the incoming address space.

14454

@end table

14455

14456

@subsubsection @code{EIND} and Devices with More Than 128 Ki Bytes of Flash

14457

@cindex @code{EIND}

14458

Pointers in the implementation are 16@tie{}bits wide.

14459

The address of a function or label is represented as word address so

14460

that indirect jumps and calls can target any code address in the

14461

range of 64@tie{}Ki words.

14462

14463

In order to facilitate indirect jump on devices with more than 128@tie{}Ki

14464

bytes of program memory space, there is a special function register called

14465

@code{EIND} that serves as most significant part of the target address

14466

when @code{EICALL} or @code{EIJMP} instructions are used.

14467

14468

Indirect jumps and calls on these devices are handled as follows by

14469

the compiler and are subject to some limitations:

14470

14471

@itemize @bullet

14472

14473

@item

14474

The compiler never sets @code{EIND}.

14475

14476

@item

14477

The compiler uses @code{EIND} implicitly in @code{EICALL}/@code{EIJMP}

14478

instructions or might read @code{EIND} directly in order to emulate an

14479

indirect call/jump by means of a @code{RET} instruction.

14480

14481

@item

14482

The compiler assumes that @code{EIND} never changes during the startup

14483

code or during the application. In particular, @code{EIND} is not

14484

saved/restored in function or interrupt service routine

14485

prologue/epilogue.

14486

14487

@item

14488

For indirect calls to functions and computed goto, the linker

14489

generates @emph{stubs}. Stubs are jump pads sometimes also called

14490

@emph{trampolines}. Thus, the indirect call/jump jumps to such a stub.

14491

The stub contains a direct jump to the desired address.

14492

14493

@item

14494

Linker relaxation must be turned on so that the linker generates

14495

the stubs correctly in all situations. See the compiler option

14496

@option{-mrelax} and the linker option @option{--relax}.

14497

There are corner cases where the linker is supposed to generate stubs

14498

but aborts without relaxation and without a helpful error message.

14499

14500

@item

14501

The default linker script is arranged for code with @code{EIND = 0}.

14502

If code is supposed to work for a setup with @code{EIND != 0}, a custom

14503

linker script has to be used in order to place the sections whose

14504

name start with @code{.trampolines} into the segment where @code{EIND}

14505

points to.

14506

14507

@item

14508

The startup code from libgcc never sets @code{EIND}.

14509

Notice that startup code is a blend of code from libgcc and AVR-LibC.

14510

For the impact of AVR-LibC on @code{EIND}, see the

14511

@w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC user manual}}.

14512

14513

@item

14514

It is legitimate for user-specific startup code to set up @code{EIND}

14515

early, for example by means of initialization code located in

14516

section @code{.init3}. Such code runs prior to general startup code

14517

that initializes RAM and calls constructors, but after the bit

14518

of startup code from AVR-LibC that sets @code{EIND} to the segment

14519

where the vector table is located.

14520

@example

14521

#include <avr/io.h>

14522

14523

static void

14524

__attribute__((section(".init3"),naked,used,no_instrument_function))

14525

init3_set_eind (void)

14526

@{

14527

__asm volatile ("ldi r24,pm_hh8(__trampolines_start)\n\t"

14528

"out %i0,r24" :: "n" (&EIND) : "r24","memory");

14529

@}

14530

@end example

14531

14532

@noindent

14533

The @code{__trampolines_start} symbol is defined in the linker script.

14534

14535

@item

14536

Stubs are generated automatically by the linker if

14537

the following two conditions are met:

14538

@itemize @minus

14539

14540

@item The address of a label is taken by means of the @code{gs} modifier

14541

(short for @emph{generate stubs}) like so:

14542

@example

14543

LDI r24, lo8(gs(@var{func}))

14544

LDI r25, hi8(gs(@var{func}))

14545

@end example

14546

@item The final location of that label is in a code segment

14547

@emph{outside} the segment where the stubs are located.

14548

@end itemize

14549

14550

@item

14551

The compiler emits such @code{gs} modifiers for code labels in the

14552

following situations:

14553

@itemize @minus

14554

@item Taking address of a function or code label.

14555

@item Computed goto.

14556

@item If prologue-save function is used, see @option{-mcall-prologues}

14557

command-line option.

14558

@item Switch/case dispatch tables. If you do not want such dispatch

14559

tables you can specify the @option{-fno-jump-tables} command-line option.

14560

@item C and C++ constructors/destructors called during startup/shutdown.

14561

@item If the tools hit a @code{gs()} modifier explained above.

14562

@end itemize

14563

14564

@item

14565

Jumping to non-symbolic addresses like so is @emph{not} supported:

14566

14567

@example

14568

int main (void)

14569

@{

14570

/* Call function at word address 0x2 */

14571

return ((int(*)(void)) 0x2)();

14572

@}

14573

@end example

14574

14575

Instead, a stub has to be set up, i.e.@: the function has to be called

14576

through a symbol (@code{func_4} in the example):

14577

14578

@example

14579

int main (void)

14580

@{

14581

extern int func_4 (void);

14582

14583

/* Call function at byte address 0x4 */

14584

return func_4();

14585

@}

14586

@end example

14587

14588

and the application be linked with @option{-Wl,--defsym,func_4=0x4}.

14589

Alternatively, @code{func_4} can be defined in the linker script.

14590

@end itemize

14591

14592

@subsubsection Handling of the @code{RAMPD}, @code{RAMPX}, @code{RAMPY} and @code{RAMPZ} Special Function Registers

14593

@cindex @code{RAMPD}

14594

@cindex @code{RAMPX}

14595

@cindex @code{RAMPY}

14596

@cindex @code{RAMPZ}

14597

Some AVR devices support memories larger than the 64@tie{}KiB range

14598

that can be accessed with 16-bit pointers. To access memory locations

14599

outside this 64@tie{}KiB range, the contentent of a @code{RAMP}

14600

register is used as high part of the address:

14601

The @code{X}, @code{Y}, @code{Z} address register is concatenated

14602

with the @code{RAMPX}, @code{RAMPY}, @code{RAMPZ} special function

14603

register, respectively, to get a wide address. Similarly,

14604

@code{RAMPD} is used together with direct addressing.

14605

14606

@itemize

14607

@item

14608

The startup code initializes the @code{RAMP} special function

14609

registers with zero.

14610

14611

@item

14612

If a @ref{AVR Named Address Spaces,named address space} other than

14613

generic or @code{__flash} is used, then @code{RAMPZ} is set

14614

as needed before the operation.

14615

14616

@item

14617

If the device supports RAM larger than 64@tie{}KiB and the compiler

14618

needs to change @code{RAMPZ} to accomplish an operation, @code{RAMPZ}

14619

is reset to zero after the operation.

14620

14621

@item

14622

If the device comes with a specific @code{RAMP} register, the ISR

14623

prologue/epilogue saves/restores that SFR and initializes it with

14624

zero in case the ISR code might (implicitly) use it.

14625

14626

@item

14627

RAM larger than 64@tie{}KiB is not supported by GCC for AVR targets.

14628

If you use inline assembler to read from locations outside the

14629

16-bit address range and change one of the @code{RAMP} registers,

14630

you must reset it to zero after the access.

14631

14632

@end itemize

14633

14634

@subsubsection AVR Built-in Macros

14635

14636

GCC defines several built-in macros so that the user code can test

14637

for the presence or absence of features. Almost any of the following

14638

built-in macros are deduced from device capabilities and thus

14639

triggered by the @option{-mmcu=} command-line option.

14640

14641

For even more AVR-specific built-in macros see

14642

@ref{AVR Named Address Spaces} and @ref{AVR Built-in Functions}.

14643

14644

@table @code

14645

14646

@item __AVR_ARCH__

14647

Build-in macro that resolves to a decimal number that identifies the

14648

architecture and depends on the @option{-mmcu=@var{mcu}} option.

14649

Possible values are:

14650

14651

@code{2}, @code{25}, @code{3}, @code{31}, @code{35},

14652

@code{4}, @code{5}, @code{51}, @code{6}

14653

14654

for @var{mcu}=@code{avr2}, @code{avr25}, @code{avr3}, @code{avr31},

14655

@code{avr35}, @code{avr4}, @code{avr5}, @code{avr51}, @code{avr6},

14656

14657

respectively and

14658

14659

@code{100}, @code{102}, @code{104},

14660

@code{105}, @code{106}, @code{107}

14661

14662

for @var{mcu}=@code{avrtiny}, @code{avrxmega2}, @code{avrxmega4},

14663

@code{avrxmega5}, @code{avrxmega6}, @code{avrxmega7}, respectively.

14664

If @var{mcu} specifies a device, this built-in macro is set

14665

accordingly. For example, with @option{-mmcu=atmega8} the macro is

14666

defined to @code{4}.

14667

14668

@item __AVR_@var{Device}__

14669

Setting @option{-mmcu=@var{device}} defines this built-in macro which reflects

14670

the device's name. For example, @option{-mmcu=atmega8} defines the

14671

built-in macro @code{__AVR_ATmega8__}, @option{-mmcu=attiny261a} defines

14672

@code{__AVR_ATtiny261A__}, etc.

14673

14674

The built-in macros' names follow

14675

the scheme @code{__AVR_@var{Device}__} where @var{Device} is

14676

the device name as from the AVR user manual. The difference between

14677

@var{Device} in the built-in macro and @var{device} in

14678

@option{-mmcu=@var{device}} is that the latter is always lowercase.

14679

14680

If @var{device} is not a device but only a core architecture like

14681

@samp{avr51}, this macro is not defined.

14682

14683

@item __AVR_DEVICE_NAME__

14684

Setting @option{-mmcu=@var{device}} defines this built-in macro to

14685

the device's name. For example, with @option{-mmcu=atmega8} the macro

14686

is defined to @code{atmega8}.

14687

14688

If @var{device} is not a device but only a core architecture like

14689

@samp{avr51}, this macro is not defined.

14690

14691

@item __AVR_XMEGA__

14692

The device / architecture belongs to the XMEGA family of devices.

14693

14694

@item __AVR_HAVE_ELPM__

14695

The device has the @code{ELPM} instruction.

14696

14697

@item __AVR_HAVE_ELPMX__

14698

The device has the @code{ELPM R@var{n},Z} and @code{ELPM

14699

R@var{n},Z+} instructions.

14700

14701

@item __AVR_HAVE_MOVW__

14702

The device has the @code{MOVW} instruction to perform 16-bit

14703

register-register moves.

14704

14705

@item __AVR_HAVE_LPMX__

14706

The device has the @code{LPM R@var{n},Z} and

14707

@code{LPM R@var{n},Z+} instructions.

14708

14709

@item __AVR_HAVE_MUL__

14710

The device has a hardware multiplier.

14711

14712

@item __AVR_HAVE_JMP_CALL__

14713

The device has the @code{JMP} and @code{CALL} instructions.

14714

This is the case for devices with at least 16@tie{}KiB of program

14715

memory.

14716

14717

@item __AVR_HAVE_EIJMP_EICALL__

14718

@itemx __AVR_3_BYTE_PC__

14719

The device has the @code{EIJMP} and @code{EICALL} instructions.

14720

This is the case for devices with more than 128@tie{}KiB of program memory.

14721

This also means that the program counter

14722

(PC) is 3@tie{}bytes wide.

14723

14724

@item __AVR_2_BYTE_PC__

14725

The program counter (PC) is 2@tie{}bytes wide. This is the case for devices

14726

with up to 128@tie{}KiB of program memory.

14727

14728

@item __AVR_HAVE_8BIT_SP__

14729

@itemx __AVR_HAVE_16BIT_SP__

14730

The stack pointer (SP) register is treated as 8-bit respectively

14731

16-bit register by the compiler.

14732

The definition of these macros is affected by @option{-mtiny-stack}.

14733

14734

@item __AVR_HAVE_SPH__

14735

@itemx __AVR_SP8__

14736

The device has the SPH (high part of stack pointer) special function

14737

register or has an 8-bit stack pointer, respectively.

14738

The definition of these macros is affected by @option{-mmcu=} and

14739

in the cases of @option{-mmcu=avr2} and @option{-mmcu=avr25} also

14740

by @option{-msp8}.

14741

14742

@item __AVR_HAVE_RAMPD__

14743

@itemx __AVR_HAVE_RAMPX__

14744

@itemx __AVR_HAVE_RAMPY__

14745

@itemx __AVR_HAVE_RAMPZ__

14746

The device has the @code{RAMPD}, @code{RAMPX}, @code{RAMPY},

14747

@code{RAMPZ} special function register, respectively.

14748

14749

@item __NO_INTERRUPTS__

14750

This macro reflects the @option{-mno-interrupts} command-line option.

14751

14752

@item __AVR_ERRATA_SKIP__

14753

@itemx __AVR_ERRATA_SKIP_JMP_CALL__

14754

Some AVR devices (AT90S8515, ATmega103) must not skip 32-bit

14755

instructions because of a hardware erratum. Skip instructions are

14756

@code{SBRS}, @code{SBRC}, @code{SBIS}, @code{SBIC} and @code{CPSE}.

14757

The second macro is only defined if @code{__AVR_HAVE_JMP_CALL__} is also

14758

set.

14759

14760

@item __AVR_ISA_RMW__

14761

The device has Read-Modify-Write instructions (XCH, LAC, LAS and LAT).

14762

14763

@item __AVR_SFR_OFFSET__=@var{offset}

14764

Instructions that can address I/O special function registers directly

14765

like @code{IN}, @code{OUT}, @code{SBI}, etc.@: may use a different

14766

address as if addressed by an instruction to access RAM like @code{LD}

14767

or @code{STS}. This offset depends on the device architecture and has

14768

to be subtracted from the RAM address in order to get the

14769

respective I/O@tie{}address.

14770

14771

@item __WITH_AVRLIBC__

14772

The compiler is configured to be used together with AVR-Libc.

14773

See the @option{--with-avrlibc} configure option.

14774

14775

@end table

14776

14777

@node Blackfin Options

14778

@subsection Blackfin Options

14779

@cindex Blackfin Options

14780

14781

@table @gcctabopt

14782

@item -mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]}

14783

@opindex mcpu=

14784

Specifies the name of the target Blackfin processor. Currently, @var{cpu}

14785

can be one of @samp{bf512}, @samp{bf514}, @samp{bf516}, @samp{bf518},

14786

@samp{bf522}, @samp{bf523}, @samp{bf524}, @samp{bf525}, @samp{bf526},

14787

@samp{bf527}, @samp{bf531}, @samp{bf532}, @samp{bf533},

14788

@samp{bf534}, @samp{bf536}, @samp{bf537}, @samp{bf538}, @samp{bf539},

14789

@samp{bf542}, @samp{bf544}, @samp{bf547}, @samp{bf548}, @samp{bf549},

14790

@samp{bf542m}, @samp{bf544m}, @samp{bf547m}, @samp{bf548m}, @samp{bf549m},

14791

@samp{bf561}, @samp{bf592}.

14792

14793

The optional @var{sirevision} specifies the silicon revision of the target

14794

Blackfin processor. Any workarounds available for the targeted silicon revision

14795

are enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled.

14796

If @var{sirevision} is @samp{any}, all workarounds for the targeted processor

14797

are enabled. The @code{__SILICON_REVISION__} macro is defined to two

14798

hexadecimal digits representing the major and minor numbers in the silicon

14799

revision. If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}

14800

is not defined. If @var{sirevision} is @samp{any}, the

14801

@code{__SILICON_REVISION__} is defined to be @code{0xffff}.

14802

If this optional @var{sirevision} is not used, GCC assumes the latest known

14803

silicon revision of the targeted Blackfin processor.

14804

14805

GCC defines a preprocessor macro for the specified @var{cpu}.

14806

For the @samp{bfin-elf} toolchain, this option causes the hardware BSP

14807

provided by libgloss to be linked in if @option{-msim} is not given.

14808

14809

Without this option, @samp{bf532} is used as the processor by default.

14810

14811

Note that support for @samp{bf561} is incomplete. For @samp{bf561},

14812

only the preprocessor macro is defined.

14813

14814

@item -msim

14815

@opindex msim

14816

Specifies that the program will be run on the simulator. This causes

14817

the simulator BSP provided by libgloss to be linked in. This option

14818

has effect only for @samp{bfin-elf} toolchain.

14819

Certain other options, such as @option{-mid-shared-library} and

14820

@option{-mfdpic}, imply @option{-msim}.

14821

14822

@item -momit-leaf-frame-pointer

14823

@opindex momit-leaf-frame-pointer

14824

Don't keep the frame pointer in a register for leaf functions. This

14825

avoids the instructions to save, set up and restore frame pointers and

14826

makes an extra register available in leaf functions. The option

14827

@option{-fomit-frame-pointer} removes the frame pointer for all functions,

14828

which might make debugging harder.

14829

14830

@item -mspecld-anomaly

14831

@opindex mspecld-anomaly

14832

When enabled, the compiler ensures that the generated code does not

14833

contain speculative loads after jump instructions. If this option is used,

14834

@code{__WORKAROUND_SPECULATIVE_LOADS} is defined.

14835

14836

@item -mno-specld-anomaly

14837

@opindex mno-specld-anomaly

14838

Don't generate extra code to prevent speculative loads from occurring.

14839

14840

@item -mcsync-anomaly

14841

@opindex mcsync-anomaly

14842

When enabled, the compiler ensures that the generated code does not

14843

contain CSYNC or SSYNC instructions too soon after conditional branches.

14844

If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.

14845

14846

@item -mno-csync-anomaly

14847

@opindex mno-csync-anomaly

14848

Don't generate extra code to prevent CSYNC or SSYNC instructions from

14849

occurring too soon after a conditional branch.

14850

14851

@item -mlow-64k

14852

@opindex mlow-64k

14853

When enabled, the compiler is free to take advantage of the knowledge that

14854

the entire program fits into the low 64k of memory.

14855

14856

@item -mno-low-64k

14857

@opindex mno-low-64k

14858

Assume that the program is arbitrarily large. This is the default.

14859

14860

@item -mstack-check-l1

14861

@opindex mstack-check-l1

14862

Do stack checking using information placed into L1 scratchpad memory by the

14863

uClinux kernel.

14864

14865

@item -mid-shared-library

14866

@opindex mid-shared-library

14867

Generate code that supports shared libraries via the library ID method.

14868

This allows for execute in place and shared libraries in an environment

14869

without virtual memory management. This option implies @option{-fPIC}.

14870

With a @samp{bfin-elf} target, this option implies @option{-msim}.

14871

14872

@item -mno-id-shared-library

14873

@opindex mno-id-shared-library

14874

Generate code that doesn't assume ID-based shared libraries are being used.

14875

This is the default.

14876

14877

@item -mleaf-id-shared-library

14878

@opindex mleaf-id-shared-library

14879

Generate code that supports shared libraries via the library ID method,

14880

but assumes that this library or executable won't link against any other

14881

ID shared libraries. That allows the compiler to use faster code for jumps

14882

and calls.

14883

14884

@item -mno-leaf-id-shared-library

14885

@opindex mno-leaf-id-shared-library

14886

Do not assume that the code being compiled won't link against any ID shared

14887

libraries. Slower code is generated for jump and call insns.

14888

14889

@item -mshared-library-id=n

14890

@opindex mshared-library-id

14891

Specifies the identification number of the ID-based shared library being

14892

compiled. Specifying a value of 0 generates more compact code; specifying

14893

other values forces the allocation of that number to the current

14894

library but is no more space- or time-efficient than omitting this option.

14895

14896

@item -msep-data

14897

@opindex msep-data

14898

Generate code that allows the data segment to be located in a different

14899

area of memory from the text segment. This allows for execute in place in

14900

an environment without virtual memory management by eliminating relocations

14901

against the text section.

14902

14903

@item -mno-sep-data

14904

@opindex mno-sep-data

14905

Generate code that assumes that the data segment follows the text segment.

14906

This is the default.

14907

14908

@item -mlong-calls

14909

@itemx -mno-long-calls

14910

@opindex mlong-calls

14911

@opindex mno-long-calls

14912

Tells the compiler to perform function calls by first loading the

14913

address of the function into a register and then performing a subroutine

14914

call on this register. This switch is needed if the target function

14915

lies outside of the 24-bit addressing range of the offset-based

14916

version of subroutine call instruction.

14917

14918

This feature is not enabled by default. Specifying

14919

@option{-mno-long-calls} restores the default behavior. Note these

14920

switches have no effect on how the compiler generates code to handle

14921

function calls via function pointers.

14922

14923

@item -mfast-fp

14924

@opindex mfast-fp

14925

Link with the fast floating-point library. This library relaxes some of

14926

the IEEE floating-point standard's rules for checking inputs against

14927

Not-a-Number (NAN), in the interest of performance.

14928

14929

@item -minline-plt

14930

@opindex minline-plt

14931

Enable inlining of PLT entries in function calls to functions that are

14932

not known to bind locally. It has no effect without @option{-mfdpic}.

14933

14934

@item -mmulticore

14935

@opindex mmulticore

14936

Build a standalone application for multicore Blackfin processors.

14937

This option causes proper start files and link scripts supporting

14938

multicore to be used, and defines the macro @code{__BFIN_MULTICORE}.

14939

It can only be used with @option{-mcpu=bf561@r{[}-@var{sirevision}@r{]}}.

14940

14941

This option can be used with @option{-mcorea} or @option{-mcoreb}, which

14942

selects the one-application-per-core programming model. Without

14943

@option{-mcorea} or @option{-mcoreb}, the single-application/dual-core

14944

programming model is used. In this model, the main function of Core B

14945

should be named as @code{coreb_main}.

14946

14947

If this option is not used, the single-core application programming

14948

model is used.

14949

14950

@item -mcorea

14951

@opindex mcorea

14952

Build a standalone application for Core A of BF561 when using

14953

the one-application-per-core programming model. Proper start files

14954

and link scripts are used to support Core A, and the macro

14955

@code{__BFIN_COREA} is defined.

14956

This option can only be used in conjunction with @option{-mmulticore}.

14957

14958

@item -mcoreb

14959

@opindex mcoreb

14960

Build a standalone application for Core B of BF561 when using

14961

the one-application-per-core programming model. Proper start files

14962

and link scripts are used to support Core B, and the macro

14963

@code{__BFIN_COREB} is defined. When this option is used, @code{coreb_main}

14964

should be used instead of @code{main}.

14965

This option can only be used in conjunction with @option{-mmulticore}.

14966

14967

@item -msdram

14968

@opindex msdram

14969

Build a standalone application for SDRAM. Proper start files and

14970

link scripts are used to put the application into SDRAM, and the macro

14971

@code{__BFIN_SDRAM} is defined.

14972

The loader should initialize SDRAM before loading the application.

14973

14974

@item -micplb

14975

@opindex micplb

14976

Assume that ICPLBs are enabled at run time. This has an effect on certain

14977

anomaly workarounds. For Linux targets, the default is to assume ICPLBs

14978

are enabled; for standalone applications the default is off.

14979

@end table

14980

14981

@node C6X Options

14982

@subsection C6X Options

14983

@cindex C6X Options

14984

14985

@table @gcctabopt

14986

@item -march=@var{name}

14987

@opindex march

14988

This specifies the name of the target architecture. GCC uses this

14989

name to determine what kind of instructions it can emit when generating

14990

assembly code. Permissible names are: @samp{c62x},

14991

@samp{c64x}, @samp{c64x+}, @samp{c67x}, @samp{c67x+}, @samp{c674x}.

14992

14993

@item -mbig-endian

14994

@opindex mbig-endian

14995

Generate code for a big-endian target.

14996

14997

@item -mlittle-endian

14998

@opindex mlittle-endian

14999

Generate code for a little-endian target. This is the default.

15000

15001

@item -msim

15002

@opindex msim

15003

Choose startup files and linker script suitable for the simulator.

15004

15005

@item -msdata=default

15006

@opindex msdata=default

15007

Put small global and static data in the @code{.neardata} section,

15008

which is pointed to by register @code{B14}. Put small uninitialized

15009

global and static data in the @code{.bss} section, which is adjacent

15010

to the @code{.neardata} section. Put small read-only data into the

15011

@code{.rodata} section. The corresponding sections used for large

15012

pieces of data are @code{.fardata}, @code{.far} and @code{.const}.

15013

15014

@item -msdata=all

15015

@opindex msdata=all

15016

Put all data, not just small objects, into the sections reserved for

15017

small data, and use addressing relative to the @code{B14} register to

15018

access them.

15019

15020

@item -msdata=none

15021

@opindex msdata=none

15022

Make no use of the sections reserved for small data, and use absolute

15023

addresses to access all data. Put all initialized global and static

15024

data in the @code{.fardata} section, and all uninitialized data in the

15025

@code{.far} section. Put all constant data into the @code{.const}

15026

section.

15027

@end table

15028

15029

@node CRIS Options

15030

@subsection CRIS Options

15031

@cindex CRIS Options

15032

15033

These options are defined specifically for the CRIS ports.

15034

15035

@table @gcctabopt

15036

@item -march=@var{architecture-type}

15037

@itemx -mcpu=@var{architecture-type}

15038

@opindex march

15039

@opindex mcpu

15040

Generate code for the specified architecture. The choices for

15041

@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for

15042

respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.

15043

Default is @samp{v0} except for cris-axis-linux-gnu, where the default is

15044

@samp{v10}.

15045

15046

@item -mtune=@var{architecture-type}

15047

@opindex mtune

15048

Tune to @var{architecture-type} everything applicable about the generated

15049

code, except for the ABI and the set of available instructions. The

15050

choices for @var{architecture-type} are the same as for

15051

@option{-march=@var{architecture-type}}.

15052

15053

@item -mmax-stack-frame=@var{n}

15054

@opindex mmax-stack-frame

15055

Warn when the stack frame of a function exceeds @var{n} bytes.

15056

15057

@item -metrax4

15058

@itemx -metrax100

15059

@opindex metrax4

15060

@opindex metrax100

15061

The options @option{-metrax4} and @option{-metrax100} are synonyms for

15062

@option{-march=v3} and @option{-march=v8} respectively.

15063

15064

@item -mmul-bug-workaround

15065

@itemx -mno-mul-bug-workaround

15066

@opindex mmul-bug-workaround

15067

@opindex mno-mul-bug-workaround

15068

Work around a bug in the @code{muls} and @code{mulu} instructions for CPU

15069

models where it applies. This option is active by default.

15070

15071

@item -mpdebug

15072

@opindex mpdebug

15073

Enable CRIS-specific verbose debug-related information in the assembly

15074

code. This option also has the effect of turning off the @samp{#NO_APP}

15075

formatted-code indicator to the assembler at the beginning of the

15076

assembly file.

15077

15078

@item -mcc-init

15079

@opindex mcc-init

15080

Do not use condition-code results from previous instruction; always emit

15081

compare and test instructions before use of condition codes.

15082

15083

@item -mno-side-effects

15084

@opindex mno-side-effects

15085

Do not emit instructions with side effects in addressing modes other than

15086

post-increment.

15087

15088

@item -mstack-align

15089

@itemx -mno-stack-align

15090

@itemx -mdata-align

15091

@itemx -mno-data-align

15092

@itemx -mconst-align

15093

@itemx -mno-const-align

15094

@opindex mstack-align

15095

@opindex mno-stack-align

15096

@opindex mdata-align

15097

@opindex mno-data-align

15098

@opindex mconst-align

15099

@opindex mno-const-align

15100

These options (@samp{no-} options) arrange (eliminate arrangements) for the

15101

stack frame, individual data and constants to be aligned for the maximum

15102

single data access size for the chosen CPU model. The default is to

15103

arrange for 32-bit alignment. ABI details such as structure layout are

15104

not affected by these options.

15105

15106

@item -m32-bit

15107

@itemx -m16-bit

15108

@itemx -m8-bit

15109

@opindex m32-bit

15110

@opindex m16-bit

15111

@opindex m8-bit

15112

Similar to the stack- data- and const-align options above, these options

15113

arrange for stack frame, writable data and constants to all be 32-bit,

15114

16-bit or 8-bit aligned. The default is 32-bit alignment.

15115

15116

@item -mno-prologue-epilogue

15117

@itemx -mprologue-epilogue

15118

@opindex mno-prologue-epilogue

15119

@opindex mprologue-epilogue

15120

With @option{-mno-prologue-epilogue}, the normal function prologue and

15121

epilogue which set up the stack frame are omitted and no return

15122

instructions or return sequences are generated in the code. Use this

15123

option only together with visual inspection of the compiled code: no

15124

warnings or errors are generated when call-saved registers must be saved,

15125

or storage for local variables needs to be allocated.

15126

15127

@item -mno-gotplt

15128

@itemx -mgotplt

15129

@opindex mno-gotplt

15130

@opindex mgotplt

15131

With @option{-fpic} and @option{-fPIC}, don't generate (do generate)

15132

instruction sequences that load addresses for functions from the PLT part

15133

of the GOT rather than (traditional on other architectures) calls to the

15134

PLT@. The default is @option{-mgotplt}.

15135

15136

@item -melf

15137

@opindex melf

15138

Legacy no-op option only recognized with the cris-axis-elf and

15139

cris-axis-linux-gnu targets.

15140

15141

@item -mlinux

15142

@opindex mlinux

15143

Legacy no-op option only recognized with the cris-axis-linux-gnu target.

15144

15145

@item -sim

15146

@opindex sim

15147

This option, recognized for the cris-axis-elf, arranges

15148

to link with input-output functions from a simulator library. Code,

15149

initialized data and zero-initialized data are allocated consecutively.

15150

15151

@item -sim2

15152

@opindex sim2

15153

Like @option{-sim}, but pass linker options to locate initialized data at

15154

0x40000000 and zero-initialized data at 0x80000000.

15155

@end table

15156

15157

@node CR16 Options

15158

@subsection CR16 Options

15159

@cindex CR16 Options

15160

15161

These options are defined specifically for the CR16 ports.

15162

15163

@table @gcctabopt

15164

15165

@item -mmac

15166

@opindex mmac

15167

Enable the use of multiply-accumulate instructions. Disabled by default.

15168

15169

@item -mcr16cplus

15170

@itemx -mcr16c

15171

@opindex mcr16cplus

15172

@opindex mcr16c

15173

Generate code for CR16C or CR16C+ architecture. CR16C+ architecture

15174

is default.

15175

15176

@item -msim

15177

@opindex msim

15178

Links the library libsim.a which is in compatible with simulator. Applicable

15179

to ELF compiler only.

15180

15181

@item -mint32

15182

@opindex mint32

15183

Choose integer type as 32-bit wide.

15184

15185

@item -mbit-ops

15186

@opindex mbit-ops

15187

Generates @code{sbit}/@code{cbit} instructions for bit manipulations.

15188

15189

@item -mdata-model=@var{model}

15190

@opindex mdata-model

15191

Choose a data model. The choices for @var{model} are @samp{near},

15192

@samp{far} or @samp{medium}. @samp{medium} is default.

15193

However, @samp{far} is not valid with @option{-mcr16c}, as the

15194

CR16C architecture does not support the far data model.

15195

@end table

15196

15197

@node Darwin Options

15198

@subsection Darwin Options

15199

@cindex Darwin options

15200

15201

These options are defined for all architectures running the Darwin operating

15202

system.

15203

15204

FSF GCC on Darwin does not create ``fat'' object files; it creates

15205

an object file for the single architecture that GCC was built to

15206

target. Apple's GCC on Darwin does create ``fat'' files if multiple

15207

@option{-arch} options are used; it does so by running the compiler or

15208

linker multiple times and joining the results together with

15209

@file{lipo}.

15210

15211

The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or

15212

@samp{i686}) is determined by the flags that specify the ISA

15213

that GCC is targeting, like @option{-mcpu} or @option{-march}. The

15214

@option{-force_cpusubtype_ALL} option can be used to override this.

15215

15216

The Darwin tools vary in their behavior when presented with an ISA

15217

mismatch. The assembler, @file{as}, only permits instructions to

15218

be used that are valid for the subtype of the file it is generating,

15219

so you cannot put 64-bit instructions in a @samp{ppc750} object file.

15220

The linker for shared libraries, @file{/usr/bin/libtool}, fails

15221

and prints an error if asked to create a shared library with a less

15222

restrictive subtype than its input files (for instance, trying to put

15223

a @samp{ppc970} object file in a @samp{ppc7400} library). The linker

15224

for executables, @command{ld}, quietly gives the executable the most

15225

restrictive subtype of any of its input files.

15226

15227

@table @gcctabopt

15228

@item -F@var{dir}

15229

@opindex F

15230

Add the framework directory @var{dir} to the head of the list of

15231

directories to be searched for header files. These directories are

15232

interleaved with those specified by @option{-I} options and are

15233

scanned in a left-to-right order.

15234

15235

A framework directory is a directory with frameworks in it. A

15236

framework is a directory with a @file{Headers} and/or

15237

@file{PrivateHeaders} directory contained directly in it that ends

15238

in @file{.framework}. The name of a framework is the name of this

15239

directory excluding the @file{.framework}. Headers associated with

15240

the framework are found in one of those two directories, with

15241

@file{Headers} being searched first. A subframework is a framework

15242

directory that is in a framework's @file{Frameworks} directory.

15243

Includes of subframework headers can only appear in a header of a

15244

framework that contains the subframework, or in a sibling subframework

15245

header. Two subframeworks are siblings if they occur in the same

15246

framework. A subframework should not have the same name as a

15247

framework; a warning is issued if this is violated. Currently a

15248

subframework cannot have subframeworks; in the future, the mechanism

15249

may be extended to support this. The standard frameworks can be found

15250

in @file{/System/Library/Frameworks} and

15251

@file{/Library/Frameworks}. An example include looks like

15252

@code{#include <Framework/header.h>}, where @file{Framework} denotes

15253

the name of the framework and @file{header.h} is found in the

15254

@file{PrivateHeaders} or @file{Headers} directory.

15255

15256

@item -iframework@var{dir}

15257

@opindex iframework

15258

Like @option{-F} except the directory is a treated as a system

15259

directory. The main difference between this @option{-iframework} and

15260

@option{-F} is that with @option{-iframework} the compiler does not

15261

warn about constructs contained within header files found via

15262

@var{dir}. This option is valid only for the C family of languages.

15263

15264

@item -gused

15265

@opindex gused

15266

Emit debugging information for symbols that are used. For stabs

15267

debugging format, this enables @option{-feliminate-unused-debug-symbols}.

15268

This is by default ON@.

15269

15270

@item -gfull

15271

@opindex gfull

15272

Emit debugging information for all symbols and types.

15273

15274

@item -mmacosx-version-min=@var{version}

15275

The earliest version of MacOS X that this executable will run on

15276

is @var{version}. Typical values of @var{version} include @code{10.1},

15277

@code{10.2}, and @code{10.3.9}.

15278

15279

If the compiler was built to use the system's headers by default,

15280

then the default for this option is the system version on which the

15281

compiler is running, otherwise the default is to make choices that

15282

are compatible with as many systems and code bases as possible.

15283

15284

@item -mkernel

15285

@opindex mkernel

15286

Enable kernel development mode. The @option{-mkernel} option sets

15287

@option{-static}, @option{-fno-common}, @option{-fno-use-cxa-atexit},

15288

@option{-fno-exceptions}, @option{-fno-non-call-exceptions},

15289

@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where

15290

applicable. This mode also sets @option{-mno-altivec},

15291

@option{-msoft-float}, @option{-fno-builtin} and

15292

@option{-mlong-branch} for PowerPC targets.

15293

15294

@item -mone-byte-bool

15295

@opindex mone-byte-bool

15296

Override the defaults for @code{bool} so that @code{sizeof(bool)==1}.

15297

By default @code{sizeof(bool)} is @code{4} when compiling for

15298

Darwin/PowerPC and @code{1} when compiling for Darwin/x86, so this

15299

option has no effect on x86.

15300

15301

@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC

15302

to generate code that is not binary compatible with code generated

15303

without that switch. Using this switch may require recompiling all

15304

other modules in a program, including system libraries. Use this

15305

switch to conform to a non-default data model.

15306

15307

@item -mfix-and-continue

15308

@itemx -ffix-and-continue

15309

@itemx -findirect-data

15310

@opindex mfix-and-continue

15311

@opindex ffix-and-continue

15312

@opindex findirect-data

15313

Generate code suitable for fast turnaround development, such as to

15314

allow GDB to dynamically load @file{.o} files into already-running

15315

programs. @option{-findirect-data} and @option{-ffix-and-continue}

15316

are provided for backwards compatibility.

15317

15318

@item -all_load

15319

@opindex all_load

15320

Loads all members of static archive libraries.

15321

See man ld(1) for more information.

15322

15323

@item -arch_errors_fatal

15324

@opindex arch_errors_fatal

15325

Cause the errors having to do with files that have the wrong architecture

15326

to be fatal.

15327

15328

@item -bind_at_load

15329

@opindex bind_at_load

15330

Causes the output file to be marked such that the dynamic linker will

15331

bind all undefined references when the file is loaded or launched.

15332

15333

@item -bundle

15334

@opindex bundle

15335

Produce a Mach-o bundle format file.

15336

See man ld(1) for more information.

15337

15338

@item -bundle_loader @var{executable}

15339

@opindex bundle_loader

15340

This option specifies the @var{executable} that will load the build

15341

output file being linked. See man ld(1) for more information.

15342

15343

@item -dynamiclib

15344

@opindex dynamiclib

15345

When passed this option, GCC produces a dynamic library instead of

15346

an executable when linking, using the Darwin @file{libtool} command.

15347

15348

@item -force_cpusubtype_ALL

15349

@opindex force_cpusubtype_ALL

15350

This causes GCC's output file to have the @samp{ALL} subtype, instead of

15351

one controlled by the @option{-mcpu} or @option{-march} option.

15352

15353

@item -allowable_client @var{client_name}

15354

@itemx -client_name

15355

@itemx -compatibility_version

15356

@itemx -current_version

15357

@itemx -dead_strip

15358

@itemx -dependency-file

15359

@itemx -dylib_file

15360

@itemx -dylinker_install_name

15361

@itemx -dynamic

15362

@itemx -exported_symbols_list

15363

@itemx -filelist

15364

@need 800

15365

@itemx -flat_namespace

15366

@itemx -force_flat_namespace

15367

@itemx -headerpad_max_install_names

15368

@itemx -image_base

15369

@itemx -init

15370

@itemx -install_name

15371

@itemx -keep_private_externs

15372

@itemx -multi_module

15373

@itemx -multiply_defined

15374

@itemx -multiply_defined_unused

15375

@need 800

15376

@itemx -noall_load

15377

@itemx -no_dead_strip_inits_and_terms

15378

@itemx -nofixprebinding

15379

@itemx -nomultidefs

15380

@itemx -noprebind

15381

@itemx -noseglinkedit

15382

@itemx -pagezero_size

15383

@itemx -prebind

15384

@itemx -prebind_all_twolevel_modules

15385

@itemx -private_bundle

15386

@need 800

15387

@itemx -read_only_relocs

15388

@itemx -sectalign

15389

@itemx -sectobjectsymbols

15390

@itemx -whyload

15391

@itemx -seg1addr

15392

@itemx -sectcreate

15393

@itemx -sectobjectsymbols

15394

@itemx -sectorder

15395

@itemx -segaddr

15396

@itemx -segs_read_only_addr

15397

@need 800

15398

@itemx -segs_read_write_addr

15399

@itemx -seg_addr_table

15400

@itemx -seg_addr_table_filename

15401

@itemx -seglinkedit

15402

@itemx -segprot

15403

@itemx -segs_read_only_addr

15404

@itemx -segs_read_write_addr

15405

@itemx -single_module

15406

@itemx -static

15407

@itemx -sub_library

15408

@need 800

15409

@itemx -sub_umbrella

15410

@itemx -twolevel_namespace

15411

@itemx -umbrella

15412

@itemx -undefined

15413

@itemx -unexported_symbols_list

15414

@itemx -weak_reference_mismatches

15415

@itemx -whatsloaded

15416

@opindex allowable_client

15417

@opindex client_name

15418

@opindex compatibility_version

15419

@opindex current_version

15420

@opindex dead_strip

15421

@opindex dependency-file

15422

@opindex dylib_file

15423

@opindex dylinker_install_name

15424

@opindex dynamic

15425

@opindex exported_symbols_list

15426

@opindex filelist

15427

@opindex flat_namespace

15428

@opindex force_flat_namespace

15429

@opindex headerpad_max_install_names

15430

@opindex image_base

15431

@opindex init

15432

@opindex install_name

15433

@opindex keep_private_externs

15434

@opindex multi_module

15435

@opindex multiply_defined

15436

@opindex multiply_defined_unused

15437

@opindex noall_load

15438

@opindex no_dead_strip_inits_and_terms

15439

@opindex nofixprebinding

15440

@opindex nomultidefs

15441

@opindex noprebind

15442

@opindex noseglinkedit

15443

@opindex pagezero_size

15444

@opindex prebind

15445

@opindex prebind_all_twolevel_modules

15446

@opindex private_bundle

15447

@opindex read_only_relocs

15448

@opindex sectalign

15449

@opindex sectobjectsymbols

15450

@opindex whyload

15451

@opindex seg1addr

15452

@opindex sectcreate

15453

@opindex sectobjectsymbols

15454

@opindex sectorder

15455

@opindex segaddr

15456

@opindex segs_read_only_addr

15457

@opindex segs_read_write_addr

15458

@opindex seg_addr_table

15459

@opindex seg_addr_table_filename

15460

@opindex seglinkedit

15461

@opindex segprot

15462

@opindex segs_read_only_addr

15463

@opindex segs_read_write_addr

15464

@opindex single_module

15465

@opindex static

15466

@opindex sub_library

15467

@opindex sub_umbrella

15468

@opindex twolevel_namespace

15469

@opindex umbrella

15470

@opindex undefined

15471

@opindex unexported_symbols_list

15472

@opindex weak_reference_mismatches

15473

@opindex whatsloaded

15474

These options are passed to the Darwin linker. The Darwin linker man page

15475

describes them in detail.

15476

@end table

15477

15478

@node DEC Alpha Options

15479

@subsection DEC Alpha Options

15480

15481

These @samp{-m} options are defined for the DEC Alpha implementations:

15482

15483

@table @gcctabopt

15484

@item -mno-soft-float

15485

@itemx -msoft-float

15486

@opindex mno-soft-float

15487

@opindex msoft-float

15488

Use (do not use) the hardware floating-point instructions for

15489

floating-point operations. When @option{-msoft-float} is specified,

15490

functions in @file{libgcc.a} are used to perform floating-point

15491

operations. Unless they are replaced by routines that emulate the

15492

floating-point operations, or compiled in such a way as to call such

15493

emulations routines, these routines issue floating-point

15494

operations. If you are compiling for an Alpha without floating-point

15495

operations, you must ensure that the library is built so as not to call

15496

them.

15497

15498

Note that Alpha implementations without floating-point operations are

15499

required to have floating-point registers.

15500

15501

@item -mfp-reg

15502

@itemx -mno-fp-regs

15503

@opindex mfp-reg

15504

@opindex mno-fp-regs

15505

Generate code that uses (does not use) the floating-point register set.

15506

@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point

15507

register set is not used, floating-point operands are passed in integer

15508

registers as if they were integers and floating-point results are passed

15509

in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,

15510

so any function with a floating-point argument or return value called by code

15511

compiled with @option{-mno-fp-regs} must also be compiled with that

15512

option.

15513

15514

A typical use of this option is building a kernel that does not use,

15515

and hence need not save and restore, any floating-point registers.

15516

15517

@item -mieee

15518

@opindex mieee

15519

The Alpha architecture implements floating-point hardware optimized for

15520

maximum performance. It is mostly compliant with the IEEE floating-point

15521

standard. However, for full compliance, software assistance is

15522

required. This option generates code fully IEEE-compliant code

15523

@emph{except} that the @var{inexact-flag} is not maintained (see below).

15524

If this option is turned on, the preprocessor macro @code{_IEEE_FP} is

15525

defined during compilation. The resulting code is less efficient but is

15526

able to correctly support denormalized numbers and exceptional IEEE

15527

values such as not-a-number and plus/minus infinity. Other Alpha

15528

compilers call this option @option{-ieee_with_no_inexact}.

15529

15530

DEBIAN SPECIFIC: This option is on by default for alpha-linux-gnu, unless

15531

@option{-ffinite-math-only} (which is part of the @option{-ffast-math}

15532

set) is specified, because the software functions in the GNU libc math

15533

libraries generate denormalized numbers, NaNs, and infs (all of which

15534

will cause a programs to SIGFPE when it attempts to use the results without

15535

@option{-mieee}).

15536

15537

@item -mieee-with-inexact

15538

@opindex mieee-with-inexact

15539

This is like @option{-mieee} except the generated code also maintains

15540

the IEEE @var{inexact-flag}. Turning on this option causes the

15541

generated code to implement fully-compliant IEEE math. In addition to

15542

@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor

15543

macro. On some Alpha implementations the resulting code may execute

15544

significantly slower than the code generated by default. Since there is

15545

very little code that depends on the @var{inexact-flag}, you should

15546

normally not specify this option. Other Alpha compilers call this

15547

option @option{-ieee_with_inexact}.

15548

15549

@item -mfp-trap-mode=@var{trap-mode}

15550

@opindex mfp-trap-mode

15551

This option controls what floating-point related traps are enabled.

15552

Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.

15553

The trap mode can be set to one of four values:

15554

15555

@table @samp

15556

@item n

15557

This is the default (normal) setting. The only traps that are enabled

15558

are the ones that cannot be disabled in software (e.g., division by zero

15559

trap).

15560

15561

@item u

15562

In addition to the traps enabled by @samp{n}, underflow traps are enabled

15563

as well.

15564

15565

@item su

15566

Like @samp{u}, but the instructions are marked to be safe for software

15567

completion (see Alpha architecture manual for details).

15568

15569

@item sui

15570

Like @samp{su}, but inexact traps are enabled as well.

15571

@end table

15572

15573

@item -mfp-rounding-mode=@var{rounding-mode}

15574

@opindex mfp-rounding-mode

15575

Selects the IEEE rounding mode. Other Alpha compilers call this option

15576

@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one

15577

of:

15578

15579

@table @samp

15580

@item n

15581

Normal IEEE rounding mode. Floating-point numbers are rounded towards

15582

the nearest machine number or towards the even machine number in case

15583

of a tie.

15584

15585

@item m

15586

Round towards minus infinity.

15587

15588

@item c

15589

Chopped rounding mode. Floating-point numbers are rounded towards zero.

15590

15591

@item d

15592

Dynamic rounding mode. A field in the floating-point control register

15593

(@var{fpcr}, see Alpha architecture reference manual) controls the

15594

rounding mode in effect. The C library initializes this register for

15595

rounding towards plus infinity. Thus, unless your program modifies the

15596

@var{fpcr}, @samp{d} corresponds to round towards plus infinity.

15597

@end table

15598

15599

@item -mtrap-precision=@var{trap-precision}

15600

@opindex mtrap-precision

15601

In the Alpha architecture, floating-point traps are imprecise. This

15602

means without software assistance it is impossible to recover from a

15603

floating trap and program execution normally needs to be terminated.

15604

GCC can generate code that can assist operating system trap handlers

15605

in determining the exact location that caused a floating-point trap.

15606

Depending on the requirements of an application, different levels of

15607

precisions can be selected:

15608

15609

@table @samp

15610

@item p

15611

Program precision. This option is the default and means a trap handler

15612

can only identify which program caused a floating-point exception.

15613

15614

@item f

15615

Function precision. The trap handler can determine the function that

15616

caused a floating-point exception.

15617

15618

@item i

15619

Instruction precision. The trap handler can determine the exact

15620

instruction that caused a floating-point exception.

15621

@end table

15622

15623

Other Alpha compilers provide the equivalent options called

15624

@option{-scope_safe} and @option{-resumption_safe}.

15625

15626

@item -mieee-conformant

15627

@opindex mieee-conformant

15628

This option marks the generated code as IEEE conformant. You must not

15629

use this option unless you also specify @option{-mtrap-precision=i} and either

15630

@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect

15631

is to emit the line @samp{.eflag 48} in the function prologue of the

15632

generated assembly file.

15633

15634

@item -mbuild-constants

15635

@opindex mbuild-constants

15636

Normally GCC examines a 32- or 64-bit integer constant to

15637

see if it can construct it from smaller constants in two or three

15638

instructions. If it cannot, it outputs the constant as a literal and

15639

generates code to load it from the data segment at run time.

15640

15641

Use this option to require GCC to construct @emph{all} integer constants

15642

using code, even if it takes more instructions (the maximum is six).

15643

15644

You typically use this option to build a shared library dynamic

15645

loader. Itself a shared library, it must relocate itself in memory

15646

before it can find the variables and constants in its own data segment.

15647

15648

@item -mbwx

15649

@itemx -mno-bwx

15650

@itemx -mcix

15651

@itemx -mno-cix

15652

@itemx -mfix

15653

@itemx -mno-fix

15654

@itemx -mmax

15655

@itemx -mno-max

15656

@opindex mbwx

15657

@opindex mno-bwx

15658

@opindex mcix

15659

@opindex mno-cix

15660

@opindex mfix

15661

@opindex mno-fix

15662

@opindex mmax

15663

@opindex mno-max

15664

Indicate whether GCC should generate code to use the optional BWX,

15665

CIX, FIX and MAX instruction sets. The default is to use the instruction

15666

sets supported by the CPU type specified via @option{-mcpu=} option or that

15667

of the CPU on which GCC was built if none is specified.

15668

15669

@item -mfloat-vax

15670

@itemx -mfloat-ieee

15671

@opindex mfloat-vax

15672

@opindex mfloat-ieee

15673

Generate code that uses (does not use) VAX F and G floating-point

15674

arithmetic instead of IEEE single and double precision.

15675

15676

@item -mexplicit-relocs

15677

@itemx -mno-explicit-relocs

15678

@opindex mexplicit-relocs

15679

@opindex mno-explicit-relocs

15680

Older Alpha assemblers provided no way to generate symbol relocations

15681

except via assembler macros. Use of these macros does not allow

15682

optimal instruction scheduling. GNU binutils as of version 2.12

15683

supports a new syntax that allows the compiler to explicitly mark

15684

which relocations should apply to which instructions. This option

15685

is mostly useful for debugging, as GCC detects the capabilities of

15686

the assembler when it is built and sets the default accordingly.

15687

15688

@item -msmall-data

15689

@itemx -mlarge-data

15690

@opindex msmall-data

15691

@opindex mlarge-data

15692

When @option{-mexplicit-relocs} is in effect, static data is

15693

accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}

15694

is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}

15695

(the @code{.sdata} and @code{.sbss} sections) and are accessed via

15696

16-bit relocations off of the @code{$gp} register. This limits the

15697

size of the small data area to 64KB, but allows the variables to be

15698

directly accessed via a single instruction.

15699

15700

The default is @option{-mlarge-data}. With this option the data area

15701

is limited to just below 2GB@. Programs that require more than 2GB of

15702

data must use @code{malloc} or @code{mmap} to allocate the data in the

15703

heap instead of in the program's data segment.

15704

15705

When generating code for shared libraries, @option{-fpic} implies

15706

@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.

15707

15708

@item -msmall-text

15709

@itemx -mlarge-text

15710

@opindex msmall-text

15711

@opindex mlarge-text

15712

When @option{-msmall-text} is used, the compiler assumes that the

15713

code of the entire program (or shared library) fits in 4MB, and is

15714

thus reachable with a branch instruction. When @option{-msmall-data}

15715

is used, the compiler can assume that all local symbols share the

15716

same @code{$gp} value, and thus reduce the number of instructions

15717

required for a function call from 4 to 1.

15718

15719

The default is @option{-mlarge-text}.

15720

15721

@item -mcpu=@var{cpu_type}

15722

@opindex mcpu

15723

Set the instruction set and instruction scheduling parameters for

15724

machine type @var{cpu_type}. You can specify either the @samp{EV}

15725

style name or the corresponding chip number. GCC supports scheduling

15726

parameters for the EV4, EV5 and EV6 family of processors and

15727

chooses the default values for the instruction set from the processor

15728

you specify. If you do not specify a processor type, GCC defaults

15729

to the processor on which the compiler was built.

15730

15731

Supported values for @var{cpu_type} are

15732

15733

@table @samp

15734

@item ev4

15735

@itemx ev45

15736

@itemx 21064

15737

Schedules as an EV4 and has no instruction set extensions.

15738

15739

@item ev5

15740

@itemx 21164

15741

Schedules as an EV5 and has no instruction set extensions.

15742

15743

@item ev56

15744

@itemx 21164a

15745

Schedules as an EV5 and supports the BWX extension.

15746

15747

@item pca56

15748

@itemx 21164pc

15749

@itemx 21164PC

15750

Schedules as an EV5 and supports the BWX and MAX extensions.

15751

15752

@item ev6

15753

@itemx 21264

15754

Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.

15755

15756

@item ev67

15757

@itemx 21264a

15758

Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.

15759

@end table

15760

15761

Native toolchains also support the value @samp{native},

15762

which selects the best architecture option for the host processor.

15763

@option{-mcpu=native} has no effect if GCC does not recognize

15764

the processor.

15765

15766

@item -mtune=@var{cpu_type}

15767

@opindex mtune

15768

Set only the instruction scheduling parameters for machine type

15769

@var{cpu_type}. The instruction set is not changed.

15770

15771

Native toolchains also support the value @samp{native},

15772

which selects the best architecture option for the host processor.

15773

@option{-mtune=native} has no effect if GCC does not recognize

15774

the processor.

15775

15776

@item -mmemory-latency=@var{time}

15777

@opindex mmemory-latency

15778

Sets the latency the scheduler should assume for typical memory

15779

references as seen by the application. This number is highly

15780

dependent on the memory access patterns used by the application

15781

and the size of the external cache on the machine.

15782

15783

Valid options for @var{time} are

15784

15785

@table @samp

15786

@item @var{number}

15787

A decimal number representing clock cycles.

15788

15789

@item L1

15790

@itemx L2

15791

@itemx L3

15792

@itemx main

15793

The compiler contains estimates of the number of clock cycles for

15794

``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches

15795

(also called Dcache, Scache, and Bcache), as well as to main memory.

15796

Note that L3 is only valid for EV5.

15797

15798

@end table

15799

@end table

15800

15801

@node FR30 Options

15802

@subsection FR30 Options

15803

@cindex FR30 Options

15804

15805

These options are defined specifically for the FR30 port.

15806

15807

@table @gcctabopt

15808

15809

@item -msmall-model

15810

@opindex msmall-model

15811

Use the small address space model. This can produce smaller code, but

15812

it does assume that all symbolic values and addresses fit into a

15813

20-bit range.

15814

15815

@item -mno-lsim

15816

@opindex mno-lsim

15817

Assume that runtime support has been provided and so there is no need

15818

to include the simulator library (@file{libsim.a}) on the linker

15819

command line.

15820

15821

@end table

15822

15823

@node FT32 Options

15824

@subsection FT32 Options

15825

@cindex FT32 Options

15826

15827

These options are defined specifically for the FT32 port.

15828

15829

@table @gcctabopt

15830

15831

@item -msim

15832

@opindex msim

15833

Specifies that the program will be run on the simulator. This causes

15834

an alternate runtime startup and library to be linked.

15835

You must not use this option when generating programs that will run on

15836

real hardware; you must provide your own runtime library for whatever

15837

I/O functions are needed.

15838

15839

@item -mlra

15840

@opindex mlra

15841

Enable Local Register Allocation. This is still experimental for FT32,

15842

so by default the compiler uses standard reload.

15843

15844

@item -mnodiv

15845

@opindex mnodiv

15846

Do not use div and mod instructions.

15847

15848

@end table

15849

15850

@node FRV Options

15851

@subsection FRV Options

15852

@cindex FRV Options

15853

15854

@table @gcctabopt

15855

@item -mgpr-32

15856

@opindex mgpr-32

15857

15858

Only use the first 32 general-purpose registers.

15859

15860

@item -mgpr-64

15861

@opindex mgpr-64

15862

15863

Use all 64 general-purpose registers.

15864

15865

@item -mfpr-32

15866

@opindex mfpr-32

15867

15868

Use only the first 32 floating-point registers.

15869

15870

@item -mfpr-64

15871

@opindex mfpr-64

15872

15873

Use all 64 floating-point registers.

15874

15875

@item -mhard-float

15876

@opindex mhard-float

15877

15878

Use hardware instructions for floating-point operations.

15879

15880

@item -msoft-float

15881

@opindex msoft-float

15882

15883

Use library routines for floating-point operations.

15884

15885

@item -malloc-cc

15886

@opindex malloc-cc

15887

15888

Dynamically allocate condition code registers.

15889

15890

@item -mfixed-cc

15891

@opindex mfixed-cc

15892

15893

Do not try to dynamically allocate condition code registers, only

15894

use @code{icc0} and @code{fcc0}.

15895

15896

@item -mdword

15897

@opindex mdword

15898

15899

Change ABI to use double word insns.

15900

15901

@item -mno-dword

15902

@opindex mno-dword

15903

15904

Do not use double word instructions.

15905

15906

@item -mdouble

15907

@opindex mdouble

15908

15909

Use floating-point double instructions.

15910

15911

@item -mno-double

15912

@opindex mno-double

15913

15914

Do not use floating-point double instructions.

15915

15916

@item -mmedia

15917

@opindex mmedia

15918

15919

Use media instructions.

15920

15921

@item -mno-media

15922

@opindex mno-media

15923

15924

Do not use media instructions.

15925

15926

@item -mmuladd

15927

@opindex mmuladd

15928

15929

Use multiply and add/subtract instructions.

15930

15931

@item -mno-muladd

15932

@opindex mno-muladd

15933

15934

Do not use multiply and add/subtract instructions.

15935

15936

@item -mfdpic

15937

@opindex mfdpic

15938

15939

Select the FDPIC ABI, which uses function descriptors to represent

15940

pointers to functions. Without any PIC/PIE-related options, it

15941

implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it

15942

assumes GOT entries and small data are within a 12-bit range from the

15943

GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets

15944

are computed with 32 bits.

15945

With a @samp{bfin-elf} target, this option implies @option{-msim}.

15946

15947

@item -minline-plt

15948

@opindex minline-plt

15949

15950

Enable inlining of PLT entries in function calls to functions that are

15951

not known to bind locally. It has no effect without @option{-mfdpic}.

15952

It's enabled by default if optimizing for speed and compiling for

15953

shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an

15954

optimization option such as @option{-O3} or above is present in the

15955

command line.

15956

15957

@item -mTLS

15958

@opindex mTLS

15959

15960

Assume a large TLS segment when generating thread-local code.

15961

15962

@item -mtls

15963

@opindex mtls

15964

15965

Do not assume a large TLS segment when generating thread-local code.

15966

15967

@item -mgprel-ro

15968

@opindex mgprel-ro

15969

15970

Enable the use of @code{GPREL} relocations in the FDPIC ABI for data

15971

that is known to be in read-only sections. It's enabled by default,

15972

except for @option{-fpic} or @option{-fpie}: even though it may help

15973

make the global offset table smaller, it trades 1 instruction for 4.

15974

With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,

15975

one of which may be shared by multiple symbols, and it avoids the need

15976

for a GOT entry for the referenced symbol, so it's more likely to be a

15977

win. If it is not, @option{-mno-gprel-ro} can be used to disable it.

15978

15979

@item -multilib-library-pic

15980

@opindex multilib-library-pic

15981

15982

Link with the (library, not FD) pic libraries. It's implied by

15983

@option{-mlibrary-pic}, as well as by @option{-fPIC} and

15984

@option{-fpic} without @option{-mfdpic}. You should never have to use

15985

it explicitly.

15986

15987

@item -mlinked-fp

15988

@opindex mlinked-fp

15989

15990

Follow the EABI requirement of always creating a frame pointer whenever

15991

a stack frame is allocated. This option is enabled by default and can

15992

be disabled with @option{-mno-linked-fp}.

15993

15994

@item -mlong-calls

15995

@opindex mlong-calls

15996

15997

Use indirect addressing to call functions outside the current

15998

compilation unit. This allows the functions to be placed anywhere

15999

within the 32-bit address space.

16000

16001

@item -malign-labels

16002

@opindex malign-labels

16003

16004

Try to align labels to an 8-byte boundary by inserting NOPs into the

16005

previous packet. This option only has an effect when VLIW packing

16006

is enabled. It doesn't create new packets; it merely adds NOPs to

16007

existing ones.

16008

16009

@item -mlibrary-pic

16010

@opindex mlibrary-pic

16011

16012

Generate position-independent EABI code.

16013

16014

@item -macc-4

16015

@opindex macc-4

16016

16017

Use only the first four media accumulator registers.

16018

16019

@item -macc-8

16020

@opindex macc-8

16021

16022

Use all eight media accumulator registers.

16023

16024

@item -mpack

16025

@opindex mpack

16026

16027

Pack VLIW instructions.

16028

16029

@item -mno-pack

16030

@opindex mno-pack

16031

16032

Do not pack VLIW instructions.

16033

16034

@item -mno-eflags

16035

@opindex mno-eflags

16036

16037

Do not mark ABI switches in e_flags.

16038

16039

@item -mcond-move

16040

@opindex mcond-move

16041

16042

Enable the use of conditional-move instructions (default).

16043

16044

This switch is mainly for debugging the compiler and will likely be removed

16045

in a future version.

16046

16047

@item -mno-cond-move

16048

@opindex mno-cond-move

16049

16050

Disable the use of conditional-move instructions.

16051

16052

This switch is mainly for debugging the compiler and will likely be removed

16053

in a future version.

16054

16055

@item -mscc

16056

@opindex mscc

16057

16058

Enable the use of conditional set instructions (default).

16059

16060

This switch is mainly for debugging the compiler and will likely be removed

16061

in a future version.

16062

16063

@item -mno-scc

16064

@opindex mno-scc

16065

16066

Disable the use of conditional set instructions.

16067

16068

This switch is mainly for debugging the compiler and will likely be removed

16069

in a future version.

16070

16071

@item -mcond-exec

16072

@opindex mcond-exec

16073

16074

Enable the use of conditional execution (default).

16075

16076

This switch is mainly for debugging the compiler and will likely be removed

16077

in a future version.

16078

16079

@item -mno-cond-exec

16080

@opindex mno-cond-exec

16081

16082

Disable the use of conditional execution.

16083

16084

This switch is mainly for debugging the compiler and will likely be removed

16085

in a future version.

16086

16087

@item -mvliw-branch

16088

@opindex mvliw-branch

16089

16090

Run a pass to pack branches into VLIW instructions (default).

16091

16092

This switch is mainly for debugging the compiler and will likely be removed

16093

in a future version.

16094

16095

@item -mno-vliw-branch

16096

@opindex mno-vliw-branch

16097

16098

Do not run a pass to pack branches into VLIW instructions.

16099

16100

This switch is mainly for debugging the compiler and will likely be removed

16101

in a future version.

16102

16103

@item -mmulti-cond-exec

16104

@opindex mmulti-cond-exec

16105

16106

Enable optimization of @code{&&} and @code{||} in conditional execution

16107

(default).

16108

16109

This switch is mainly for debugging the compiler and will likely be removed

16110

in a future version.

16111

16112

@item -mno-multi-cond-exec

16113

@opindex mno-multi-cond-exec

16114

16115

Disable optimization of @code{&&} and @code{||} in conditional execution.

16116

16117

This switch is mainly for debugging the compiler and will likely be removed

16118

in a future version.

16119

16120

@item -mnested-cond-exec

16121

@opindex mnested-cond-exec

16122

16123

Enable nested conditional execution optimizations (default).

16124

16125

This switch is mainly for debugging the compiler and will likely be removed

16126

in a future version.

16127

16128

@item -mno-nested-cond-exec

16129

@opindex mno-nested-cond-exec

16130

16131

Disable nested conditional execution optimizations.

16132

16133

This switch is mainly for debugging the compiler and will likely be removed

16134

in a future version.

16135

16136

@item -moptimize-membar

16137

@opindex moptimize-membar

16138

16139

This switch removes redundant @code{membar} instructions from the

16140

compiler-generated code. It is enabled by default.

16141

16142

@item -mno-optimize-membar

16143

@opindex mno-optimize-membar

16144

16145

This switch disables the automatic removal of redundant @code{membar}

16146

instructions from the generated code.

16147

16148

@item -mtomcat-stats

16149

@opindex mtomcat-stats

16150

16151

Cause gas to print out tomcat statistics.

16152

16153

@item -mcpu=@var{cpu}

16154

@opindex mcpu

16155

16156

Select the processor type for which to generate code. Possible values are

16157

@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},

16158

@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.

16159

16160

@end table

16161

16162

@node GNU/Linux Options

16163

@subsection GNU/Linux Options

16164

16165

These @samp{-m} options are defined for GNU/Linux targets:

16166

16167

@table @gcctabopt

16168

@item -mglibc

16169

@opindex mglibc

16170

Use the GNU C library. This is the default except

16171

on @samp{*-*-linux-*uclibc*}, @samp{*-*-linux-*musl*} and

16172

@samp{*-*-linux-*android*} targets.

16173

16174

@item -muclibc

16175

@opindex muclibc

16176

Use uClibc C library. This is the default on

16177

@samp{*-*-linux-*uclibc*} targets.

16178

16179

@item -mmusl

16180

@opindex mmusl

16181

Use the musl C library. This is the default on

16182

@samp{*-*-linux-*musl*} targets.

16183

16184

@item -mbionic

16185

@opindex mbionic

16186

Use Bionic C library. This is the default on

16187

@samp{*-*-linux-*android*} targets.

16188

16189

@item -mandroid

16190

@opindex mandroid

16191

Compile code compatible with Android platform. This is the default on

16192

@samp{*-*-linux-*android*} targets.

16193

16194

When compiling, this option enables @option{-mbionic}, @option{-fPIC},

16195

@option{-fno-exceptions} and @option{-fno-rtti} by default. When linking,

16196

this option makes the GCC driver pass Android-specific options to the linker.

16197

Finally, this option causes the preprocessor macro @code{__ANDROID__}

16198

to be defined.

16199

16200

@item -tno-android-cc

16201

@opindex tno-android-cc

16202

Disable compilation effects of @option{-mandroid}, i.e., do not enable

16203

@option{-mbionic}, @option{-fPIC}, @option{-fno-exceptions} and

16204

@option{-fno-rtti} by default.

16205

16206

@item -tno-android-ld

16207

@opindex tno-android-ld

16208

Disable linking effects of @option{-mandroid}, i.e., pass standard Linux

16209

linking options to the linker.

16210

16211

@end table

16212

16213

@node H8/300 Options

16214

@subsection H8/300 Options

16215

16216

These @samp{-m} options are defined for the H8/300 implementations:

16217

16218

@table @gcctabopt

16219

@item -mrelax

16220

@opindex mrelax

16221

Shorten some address references at link time, when possible; uses the

16222

linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,

16223

ld, Using ld}, for a fuller description.

16224

16225

@item -mh

16226

@opindex mh

16227

Generate code for the H8/300H@.

16228

16229

@item -ms

16230

@opindex ms

16231

Generate code for the H8S@.

16232

16233

@item -mn

16234

@opindex mn

16235

Generate code for the H8S and H8/300H in the normal mode. This switch

16236

must be used either with @option{-mh} or @option{-ms}.

16237

16238

@item -ms2600

16239

@opindex ms2600

16240

Generate code for the H8S/2600. This switch must be used with @option{-ms}.

16241

16242

@item -mexr

16243

@opindex mexr

16244

Extended registers are stored on stack before execution of function

16245

with monitor attribute. Default option is @option{-mexr}.

16246

This option is valid only for H8S targets.

16247

16248

@item -mno-exr

16249

@opindex mno-exr

16250

Extended registers are not stored on stack before execution of function

16251

with monitor attribute. Default option is @option{-mno-exr}.

16252

This option is valid only for H8S targets.

16253

16254

@item -mint32

16255

@opindex mint32

16256

Make @code{int} data 32 bits by default.

16257

16258

@item -malign-300

16259

@opindex malign-300

16260

On the H8/300H and H8S, use the same alignment rules as for the H8/300.

16261

The default for the H8/300H and H8S is to align longs and floats on

16262

4-byte boundaries.

16263

@option{-malign-300} causes them to be aligned on 2-byte boundaries.

16264

This option has no effect on the H8/300.

16265

@end table

16266

16267

@node HPPA Options

16268

@subsection HPPA Options

16269

@cindex HPPA Options

16270

16271

These @samp{-m} options are defined for the HPPA family of computers:

16272

16273

@table @gcctabopt

16274

@item -march=@var{architecture-type}

16275

@opindex march

16276

Generate code for the specified architecture. The choices for

16277

@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA

16278

1.1, and @samp{2.0} for PA 2.0 processors. Refer to

16279

@file{/usr/lib/sched.models} on an HP-UX system to determine the proper

16280

architecture option for your machine. Code compiled for lower numbered

16281

architectures runs on higher numbered architectures, but not the

16282

other way around.

16283

16284

@item -mpa-risc-1-0

16285

@itemx -mpa-risc-1-1

16286

@itemx -mpa-risc-2-0

16287

@opindex mpa-risc-1-0

16288

@opindex mpa-risc-1-1

16289

@opindex mpa-risc-2-0

16290

Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.

16291

16292

@item -mjump-in-delay

16293

@opindex mjump-in-delay

16294

This option is ignored and provided for compatibility purposes only.

16295

16296

@item -mdisable-fpregs

16297

@opindex mdisable-fpregs

16298

Prevent floating-point registers from being used in any manner. This is

16299

necessary for compiling kernels that perform lazy context switching of

16300

floating-point registers. If you use this option and attempt to perform

16301

floating-point operations, the compiler aborts.

16302

16303

@item -mdisable-indexing

16304

@opindex mdisable-indexing

16305

Prevent the compiler from using indexing address modes. This avoids some

16306

rather obscure problems when compiling MIG generated code under MACH@.

16307

16308

@item -mno-space-regs

16309

@opindex mno-space-regs

16310

Generate code that assumes the target has no space registers. This allows

16311

GCC to generate faster indirect calls and use unscaled index address modes.

16312

16313

Such code is suitable for level 0 PA systems and kernels.

16314

16315

@item -mfast-indirect-calls

16316

@opindex mfast-indirect-calls

16317

Generate code that assumes calls never cross space boundaries. This

16318

allows GCC to emit code that performs faster indirect calls.

16319

16320

This option does not work in the presence of shared libraries or nested

16321

functions.

16322

16323

@item -mfixed-range=@var{register-range}

16324

@opindex mfixed-range

16325

Generate code treating the given register range as fixed registers.

16326

A fixed register is one that the register allocator cannot use. This is

16327

useful when compiling kernel code. A register range is specified as

16328

two registers separated by a dash. Multiple register ranges can be

16329

specified separated by a comma.

16330

16331

@item -mlong-load-store

16332

@opindex mlong-load-store

16333

Generate 3-instruction load and store sequences as sometimes required by

16334

the HP-UX 10 linker. This is equivalent to the @samp{+k} option to

16335

the HP compilers.

16336

16337

@item -mportable-runtime

16338

@opindex mportable-runtime

16339

Use the portable calling conventions proposed by HP for ELF systems.

16340

16341

@item -mgas

16342

@opindex mgas

16343

Enable the use of assembler directives only GAS understands.

16344

16345

@item -mschedule=@var{cpu-type}

16346

@opindex mschedule

16347

Schedule code according to the constraints for the machine type

16348

@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}

16349

@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer

16350

to @file{/usr/lib/sched.models} on an HP-UX system to determine the

16351

proper scheduling option for your machine. The default scheduling is

16352

@samp{8000}.

16353

16354

@item -mlinker-opt

16355

@opindex mlinker-opt

16356

Enable the optimization pass in the HP-UX linker. Note this makes symbolic

16357

debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9

16358

linkers in which they give bogus error messages when linking some programs.

16359

16360

@item -msoft-float

16361

@opindex msoft-float

16362

Generate output containing library calls for floating point.

16363

@strong{Warning:} the requisite libraries are not available for all HPPA

16364

targets. Normally the facilities of the machine's usual C compiler are

16365

used, but this cannot be done directly in cross-compilation. You must make

16366

your own arrangements to provide suitable library functions for

16367

cross-compilation.

16368

16369

@option{-msoft-float} changes the calling convention in the output file;

16370

therefore, it is only useful if you compile @emph{all} of a program with

16371

this option. In particular, you need to compile @file{libgcc.a}, the

16372

library that comes with GCC, with @option{-msoft-float} in order for

16373

this to work.

16374

16375

@item -msio

16376

@opindex msio

16377

Generate the predefine, @code{_SIO}, for server IO@. The default is

16378

@option{-mwsio}. This generates the predefines, @code{__hp9000s700},

16379

@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These

16380

options are available under HP-UX and HI-UX@.

16381

16382

@item -mgnu-ld

16383

@opindex mgnu-ld

16384

Use options specific to GNU @command{ld}.

16385

This passes @option{-shared} to @command{ld} when

16386

building a shared library. It is the default when GCC is configured,

16387

explicitly or implicitly, with the GNU linker. This option does not

16388

affect which @command{ld} is called; it only changes what parameters

16389

are passed to that @command{ld}.

16390

The @command{ld} that is called is determined by the

16391

@option{--with-ld} configure option, GCC's program search path, and

16392

finally by the user's @env{PATH}. The linker used by GCC can be printed

16393

using @samp{which `gcc -print-prog-name=ld`}. This option is only available

16394

on the 64-bit HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.

16395

16396

@item -mhp-ld

16397

@opindex mhp-ld

16398

Use options specific to HP @command{ld}.

16399

This passes @option{-b} to @command{ld} when building

16400

a shared library and passes @option{+Accept TypeMismatch} to @command{ld} on all

16401

links. It is the default when GCC is configured, explicitly or

16402

implicitly, with the HP linker. This option does not affect

16403

which @command{ld} is called; it only changes what parameters are passed to that

16404

@command{ld}.

16405

The @command{ld} that is called is determined by the @option{--with-ld}

16406

configure option, GCC's program search path, and finally by the user's

16407

@env{PATH}. The linker used by GCC can be printed using @samp{which

16408

`gcc -print-prog-name=ld`}. This option is only available on the 64-bit

16409

HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.

16410

16411

@item -mlong-calls

16412

@opindex mno-long-calls

16413

Generate code that uses long call sequences. This ensures that a call

16414

is always able to reach linker generated stubs. The default is to generate

16415

long calls only when the distance from the call site to the beginning

16416

of the function or translation unit, as the case may be, exceeds a

16417

predefined limit set by the branch type being used. The limits for

16418

normal calls are 7,600,000 and 240,000 bytes, respectively for the

16419

PA 2.0 and PA 1.X architectures. Sibcalls are always limited at

16420

240,000 bytes.

16421

16422

Distances are measured from the beginning of functions when using the

16423

@option{-ffunction-sections} option, or when using the @option{-mgas}

16424

and @option{-mno-portable-runtime} options together under HP-UX with

16425

the SOM linker.

16426

16427

It is normally not desirable to use this option as it degrades

16428

performance. However, it may be useful in large applications,

16429

particularly when partial linking is used to build the application.

16430

16431

The types of long calls used depends on the capabilities of the

16432

assembler and linker, and the type of code being generated. The

16433

impact on systems that support long absolute calls, and long pic

16434

symbol-difference or pc-relative calls should be relatively small.

16435

However, an indirect call is used on 32-bit ELF systems in pic code

16436

and it is quite long.

16437

16438

@item -munix=@var{unix-std}

16439

@opindex march

16440

Generate compiler predefines and select a startfile for the specified

16441

UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}

16442

and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}

16443

is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX

16444

11.11 and later. The default values are @samp{93} for HP-UX 10.00,

16445

@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11

16446

and later.

16447

16448

@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.

16449

@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}

16450

and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.

16451

@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},

16452

@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and

16453

@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.

16454

16455

It is @emph{important} to note that this option changes the interfaces

16456

for various library routines. It also affects the operational behavior

16457

of the C library. Thus, @emph{extreme} care is needed in using this

16458

option.

16459

16460

Library code that is intended to operate with more than one UNIX

16461

standard must test, set and restore the variable @code{__xpg4_extended_mask}

16462

as appropriate. Most GNU software doesn't provide this capability.

16463

16464

@item -nolibdld

16465

@opindex nolibdld

16466

Suppress the generation of link options to search libdld.sl when the

16467

@option{-static} option is specified on HP-UX 10 and later.

16468

16469

@item -static

16470

@opindex static

16471

The HP-UX implementation of setlocale in libc has a dependency on

16472

libdld.sl. There isn't an archive version of libdld.sl. Thus,

16473

when the @option{-static} option is specified, special link options

16474

are needed to resolve this dependency.

16475

16476

On HP-UX 10 and later, the GCC driver adds the necessary options to

16477

link with libdld.sl when the @option{-static} option is specified.

16478

This causes the resulting binary to be dynamic. On the 64-bit port,

16479

the linkers generate dynamic binaries by default in any case. The

16480

@option{-nolibdld} option can be used to prevent the GCC driver from

16481

adding these link options.

16482

16483

@item -threads

16484

@opindex threads

16485

Add support for multithreading with the @dfn{dce thread} library

16486

under HP-UX@. This option sets flags for both the preprocessor and

16487

linker.

16488

@end table

16489

16490

@node IA-64 Options

16491

@subsection IA-64 Options

16492

@cindex IA-64 Options

16493

16494

These are the @samp{-m} options defined for the Intel IA-64 architecture.

16495

16496

@table @gcctabopt

16497

@item -mbig-endian

16498

@opindex mbig-endian

16499

Generate code for a big-endian target. This is the default for HP-UX@.

16500

16501

@item -mlittle-endian

16502

@opindex mlittle-endian

16503

Generate code for a little-endian target. This is the default for AIX5

16504

and GNU/Linux.

16505

16506

@item -mgnu-as

16507

@itemx -mno-gnu-as

16508

@opindex mgnu-as

16509

@opindex mno-gnu-as

16510

Generate (or don't) code for the GNU assembler. This is the default.

16511

@c Also, this is the default if the configure option @option{--with-gnu-as}

16512

@c is used.

16513

16514

@item -mgnu-ld

16515

@itemx -mno-gnu-ld

16516

@opindex mgnu-ld

16517

@opindex mno-gnu-ld

16518

Generate (or don't) code for the GNU linker. This is the default.

16519

@c Also, this is the default if the configure option @option{--with-gnu-ld}

16520

@c is used.

16521

16522

@item -mno-pic

16523

@opindex mno-pic

16524

Generate code that does not use a global pointer register. The result

16525

is not position independent code, and violates the IA-64 ABI@.

16526

16527

@item -mvolatile-asm-stop

16528

@itemx -mno-volatile-asm-stop

16529

@opindex mvolatile-asm-stop

16530

@opindex mno-volatile-asm-stop

16531

Generate (or don't) a stop bit immediately before and after volatile asm

16532

statements.

16533

16534

@item -mregister-names

16535

@itemx -mno-register-names

16536

@opindex mregister-names

16537

@opindex mno-register-names

16538

Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for

16539

the stacked registers. This may make assembler output more readable.

16540

16541

@item -mno-sdata

16542

@itemx -msdata

16543

@opindex mno-sdata

16544

@opindex msdata

16545

Disable (or enable) optimizations that use the small data section. This may

16546

be useful for working around optimizer bugs.

16547

16548

@item -mconstant-gp

16549

@opindex mconstant-gp

16550

Generate code that uses a single constant global pointer value. This is

16551

useful when compiling kernel code.

16552

16553

@item -mauto-pic

16554

@opindex mauto-pic

16555

Generate code that is self-relocatable. This implies @option{-mconstant-gp}.

16556

This is useful when compiling firmware code.

16557

16558

@item -minline-float-divide-min-latency

16559

@opindex minline-float-divide-min-latency

16560

Generate code for inline divides of floating-point values

16561

using the minimum latency algorithm.

16562

16563

@item -minline-float-divide-max-throughput

16564

@opindex minline-float-divide-max-throughput

16565

Generate code for inline divides of floating-point values

16566

using the maximum throughput algorithm.

16567

16568

@item -mno-inline-float-divide

16569

@opindex mno-inline-float-divide

16570

Do not generate inline code for divides of floating-point values.

16571

16572

@item -minline-int-divide-min-latency

16573

@opindex minline-int-divide-min-latency

16574

Generate code for inline divides of integer values

16575

using the minimum latency algorithm.

16576

16577

@item -minline-int-divide-max-throughput

16578

@opindex minline-int-divide-max-throughput

16579

Generate code for inline divides of integer values

16580

using the maximum throughput algorithm.

16581

16582

@item -mno-inline-int-divide

16583

@opindex mno-inline-int-divide

16584

Do not generate inline code for divides of integer values.

16585

16586

@item -minline-sqrt-min-latency

16587

@opindex minline-sqrt-min-latency

16588

Generate code for inline square roots

16589

using the minimum latency algorithm.

16590

16591

@item -minline-sqrt-max-throughput

16592

@opindex minline-sqrt-max-throughput

16593

Generate code for inline square roots

16594

using the maximum throughput algorithm.

16595

16596

@item -mno-inline-sqrt

16597

@opindex mno-inline-sqrt

16598

Do not generate inline code for @code{sqrt}.

16599

16600

@item -mfused-madd

16601

@itemx -mno-fused-madd

16602

@opindex mfused-madd

16603

@opindex mno-fused-madd

16604

Do (don't) generate code that uses the fused multiply/add or multiply/subtract

16605

instructions. The default is to use these instructions.

16606

16607

@item -mno-dwarf2-asm

16608

@itemx -mdwarf2-asm

16609

@opindex mno-dwarf2-asm

16610

@opindex mdwarf2-asm

16611

Don't (or do) generate assembler code for the DWARF line number debugging

16612

info. This may be useful when not using the GNU assembler.

16613

16614

@item -mearly-stop-bits

16615

@itemx -mno-early-stop-bits

16616

@opindex mearly-stop-bits

16617

@opindex mno-early-stop-bits

16618

Allow stop bits to be placed earlier than immediately preceding the

16619

instruction that triggered the stop bit. This can improve instruction

16620

scheduling, but does not always do so.

16621

16622

@item -mfixed-range=@var{register-range}

16623

@opindex mfixed-range

16624

Generate code treating the given register range as fixed registers.

16625

A fixed register is one that the register allocator cannot use. This is

16626

useful when compiling kernel code. A register range is specified as

16627

two registers separated by a dash. Multiple register ranges can be

16628

specified separated by a comma.

16629

16630

@item -mtls-size=@var{tls-size}

16631

@opindex mtls-size

16632

Specify bit size of immediate TLS offsets. Valid values are 14, 22, and

16633

64.

16634

16635

@item -mtune=@var{cpu-type}

16636

@opindex mtune

16637

Tune the instruction scheduling for a particular CPU, Valid values are

16638

@samp{itanium}, @samp{itanium1}, @samp{merced}, @samp{itanium2},

16639

and @samp{mckinley}.

16640

16641

@item -milp32

16642

@itemx -mlp64

16643

@opindex milp32

16644

@opindex mlp64

16645

Generate code for a 32-bit or 64-bit environment.

16646

The 32-bit environment sets int, long and pointer to 32 bits.

16647

The 64-bit environment sets int to 32 bits and long and pointer

16648

to 64 bits. These are HP-UX specific flags.

16649

16650

@item -mno-sched-br-data-spec

16651

@itemx -msched-br-data-spec

16652

@opindex mno-sched-br-data-spec

16653

@opindex msched-br-data-spec

16654

(Dis/En)able data speculative scheduling before reload.

16655

This results in generation of @code{ld.a} instructions and

16656

the corresponding check instructions (@code{ld.c} / @code{chk.a}).

16657

The default setting is disabled.

16658

16659

@item -msched-ar-data-spec

16660

@itemx -mno-sched-ar-data-spec

16661

@opindex msched-ar-data-spec

16662

@opindex mno-sched-ar-data-spec

16663

(En/Dis)able data speculative scheduling after reload.

16664

This results in generation of @code{ld.a} instructions and

16665

the corresponding check instructions (@code{ld.c} / @code{chk.a}).

16666

The default setting is enabled.

16667

16668

@item -mno-sched-control-spec

16669

@itemx -msched-control-spec

16670

@opindex mno-sched-control-spec

16671

@opindex msched-control-spec

16672

(Dis/En)able control speculative scheduling. This feature is

16673

available only during region scheduling (i.e.@: before reload).

16674

This results in generation of the @code{ld.s} instructions and

16675

the corresponding check instructions @code{chk.s}.

16676

The default setting is disabled.

16677

16678

@item -msched-br-in-data-spec

16679

@itemx -mno-sched-br-in-data-spec

16680

@opindex msched-br-in-data-spec

16681

@opindex mno-sched-br-in-data-spec

16682

(En/Dis)able speculative scheduling of the instructions that

16683

are dependent on the data speculative loads before reload.

16684

This is effective only with @option{-msched-br-data-spec} enabled.

16685

The default setting is enabled.

16686

16687

@item -msched-ar-in-data-spec

16688

@itemx -mno-sched-ar-in-data-spec

16689

@opindex msched-ar-in-data-spec

16690

@opindex mno-sched-ar-in-data-spec

16691

(En/Dis)able speculative scheduling of the instructions that

16692

are dependent on the data speculative loads after reload.

16693

This is effective only with @option{-msched-ar-data-spec} enabled.

16694

The default setting is enabled.

16695

16696

@item -msched-in-control-spec

16697

@itemx -mno-sched-in-control-spec

16698

@opindex msched-in-control-spec

16699

@opindex mno-sched-in-control-spec

16700

(En/Dis)able speculative scheduling of the instructions that

16701

are dependent on the control speculative loads.

16702

This is effective only with @option{-msched-control-spec} enabled.

16703

The default setting is enabled.

16704

16705

@item -mno-sched-prefer-non-data-spec-insns

16706

@itemx -msched-prefer-non-data-spec-insns

16707

@opindex mno-sched-prefer-non-data-spec-insns

16708

@opindex msched-prefer-non-data-spec-insns

16709

If enabled, data-speculative instructions are chosen for schedule

16710

only if there are no other choices at the moment. This makes

16711

the use of the data speculation much more conservative.

16712

The default setting is disabled.

16713

16714

@item -mno-sched-prefer-non-control-spec-insns

16715

@itemx -msched-prefer-non-control-spec-insns

16716

@opindex mno-sched-prefer-non-control-spec-insns

16717

@opindex msched-prefer-non-control-spec-insns

16718

If enabled, control-speculative instructions are chosen for schedule

16719

only if there are no other choices at the moment. This makes

16720

the use of the control speculation much more conservative.

16721

The default setting is disabled.

16722

16723

@item -mno-sched-count-spec-in-critical-path

16724

@itemx -msched-count-spec-in-critical-path

16725

@opindex mno-sched-count-spec-in-critical-path

16726

@opindex msched-count-spec-in-critical-path

16727

If enabled, speculative dependencies are considered during

16728

computation of the instructions priorities. This makes the use of the

16729

speculation a bit more conservative.

16730

The default setting is disabled.

16731

16732

@item -msched-spec-ldc

16733

@opindex msched-spec-ldc

16734

Use a simple data speculation check. This option is on by default.

16735

16736

@item -msched-control-spec-ldc

16737

@opindex msched-spec-ldc

16738

Use a simple check for control speculation. This option is on by default.

16739

16740

@item -msched-stop-bits-after-every-cycle

16741

@opindex msched-stop-bits-after-every-cycle

16742

Place a stop bit after every cycle when scheduling. This option is on

16743

by default.

16744

16745

@item -msched-fp-mem-deps-zero-cost

16746

@opindex msched-fp-mem-deps-zero-cost

16747

Assume that floating-point stores and loads are not likely to cause a conflict

16748

when placed into the same instruction group. This option is disabled by

16749

default.

16750

16751

@item -msel-sched-dont-check-control-spec

16752

@opindex msel-sched-dont-check-control-spec

16753

Generate checks for control speculation in selective scheduling.

16754

This flag is disabled by default.

16755

16756

@item -msched-max-memory-insns=@var{max-insns}

16757

@opindex msched-max-memory-insns

16758

Limit on the number of memory insns per instruction group, giving lower

16759

priority to subsequent memory insns attempting to schedule in the same

16760

instruction group. Frequently useful to prevent cache bank conflicts.

16761

The default value is 1.

16762

16763

@item -msched-max-memory-insns-hard-limit

16764

@opindex msched-max-memory-insns-hard-limit

16765

Makes the limit specified by @option{msched-max-memory-insns} a hard limit,

16766

disallowing more than that number in an instruction group.

16767

Otherwise, the limit is ``soft'', meaning that non-memory operations

16768

are preferred when the limit is reached, but memory operations may still

16769

be scheduled.

16770

16771

@end table

16772

16773

@node LM32 Options

16774

@subsection LM32 Options

16775

@cindex LM32 options

16776

16777

These @option{-m} options are defined for the LatticeMico32 architecture:

16778

16779

@table @gcctabopt

16780

@item -mbarrel-shift-enabled

16781

@opindex mbarrel-shift-enabled

16782

Enable barrel-shift instructions.

16783

16784

@item -mdivide-enabled

16785

@opindex mdivide-enabled

16786

Enable divide and modulus instructions.

16787

16788

@item -mmultiply-enabled

16789

@opindex multiply-enabled

16790

Enable multiply instructions.

16791

16792

@item -msign-extend-enabled

16793

@opindex msign-extend-enabled

16794

Enable sign extend instructions.

16795

16796

@item -muser-enabled

16797

@opindex muser-enabled

16798

Enable user-defined instructions.

16799

16800

@end table

16801

16802

@node M32C Options

16803

@subsection M32C Options

16804

@cindex M32C options

16805

16806

@table @gcctabopt

16807

@item -mcpu=@var{name}

16808

@opindex mcpu=

16809

Select the CPU for which code is generated. @var{name} may be one of

16810

@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to

16811

/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for

16812

the M32C/80 series.

16813

16814

@item -msim

16815

@opindex msim

16816

Specifies that the program will be run on the simulator. This causes

16817

an alternate runtime library to be linked in which supports, for

16818

example, file I/O@. You must not use this option when generating

16819

programs that will run on real hardware; you must provide your own

16820

runtime library for whatever I/O functions are needed.

16821

16822

@item -memregs=@var{number}

16823

@opindex memregs=

16824

Specifies the number of memory-based pseudo-registers GCC uses

16825

during code generation. These pseudo-registers are used like real

16826

registers, so there is a tradeoff between GCC's ability to fit the

16827

code into available registers, and the performance penalty of using

16828

memory instead of registers. Note that all modules in a program must

16829

be compiled with the same value for this option. Because of that, you

16830

must not use this option with GCC's default runtime libraries.

16831

16832

@end table

16833

16834

@node M32R/D Options

16835

@subsection M32R/D Options

16836

@cindex M32R/D options

16837

16838

These @option{-m} options are defined for Renesas M32R/D architectures:

16839

16840

@table @gcctabopt

16841

@item -m32r2

16842

@opindex m32r2

16843

Generate code for the M32R/2@.

16844

16845

@item -m32rx

16846

@opindex m32rx

16847

Generate code for the M32R/X@.

16848

16849

@item -m32r

16850

@opindex m32r

16851

Generate code for the M32R@. This is the default.

16852

16853

@item -mmodel=small

16854

@opindex mmodel=small

16855

Assume all objects live in the lower 16MB of memory (so that their addresses

16856

can be loaded with the @code{ld24} instruction), and assume all subroutines

16857

are reachable with the @code{bl} instruction.

16858

This is the default.

16859

16860

The addressability of a particular object can be set with the

16861

@code{model} attribute.

16862

16863

@item -mmodel=medium

16864

@opindex mmodel=medium

16865

Assume objects may be anywhere in the 32-bit address space (the compiler

16866

generates @code{seth/add3} instructions to load their addresses), and

16867

assume all subroutines are reachable with the @code{bl} instruction.

16868

16869

@item -mmodel=large

16870

@opindex mmodel=large

16871

Assume objects may be anywhere in the 32-bit address space (the compiler

16872

generates @code{seth/add3} instructions to load their addresses), and

16873

assume subroutines may not be reachable with the @code{bl} instruction

16874

(the compiler generates the much slower @code{seth/add3/jl}

16875

instruction sequence).

16876

16877

@item -msdata=none

16878

@opindex msdata=none

16879

Disable use of the small data area. Variables are put into

16880

one of @code{.data}, @code{.bss}, or @code{.rodata} (unless the

16881

@code{section} attribute has been specified).

16882

This is the default.

16883

16884

The small data area consists of sections @code{.sdata} and @code{.sbss}.

16885

Objects may be explicitly put in the small data area with the

16886

@code{section} attribute using one of these sections.

16887

16888

@item -msdata=sdata

16889

@opindex msdata=sdata

16890

Put small global and static data in the small data area, but do not

16891

generate special code to reference them.

16892

16893

@item -msdata=use

16894

@opindex msdata=use

16895

Put small global and static data in the small data area, and generate

16896

special instructions to reference them.

16897

16898

@item -G @var{num}

16899

@opindex G

16900

@cindex smaller data references

16901

Put global and static objects less than or equal to @var{num} bytes

16902

into the small data or BSS sections instead of the normal data or BSS

16903

sections. The default value of @var{num} is 8.

16904

The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}

16905

for this option to have any effect.

16906

16907

All modules should be compiled with the same @option{-G @var{num}} value.

16908

Compiling with different values of @var{num} may or may not work; if it

16909

doesn't the linker gives an error message---incorrect code is not

16910

generated.

16911

16912

@item -mdebug

16913

@opindex mdebug

16914

Makes the M32R-specific code in the compiler display some statistics

16915

that might help in debugging programs.

16916

16917

@item -malign-loops

16918

@opindex malign-loops

16919

Align all loops to a 32-byte boundary.

16920

16921

@item -mno-align-loops

16922

@opindex mno-align-loops

16923

Do not enforce a 32-byte alignment for loops. This is the default.

16924

16925

@item -missue-rate=@var{number}

16926

@opindex missue-rate=@var{number}

16927

Issue @var{number} instructions per cycle. @var{number} can only be 1

16928

or 2.

16929

16930

@item -mbranch-cost=@var{number}

16931

@opindex mbranch-cost=@var{number}

16932

@var{number} can only be 1 or 2. If it is 1 then branches are

16933

preferred over conditional code, if it is 2, then the opposite applies.

16934

16935

@item -mflush-trap=@var{number}

16936

@opindex mflush-trap=@var{number}

16937

Specifies the trap number to use to flush the cache. The default is

16938

12. Valid numbers are between 0 and 15 inclusive.

16939

16940

@item -mno-flush-trap

16941

@opindex mno-flush-trap

16942

Specifies that the cache cannot be flushed by using a trap.

16943

16944

@item -mflush-func=@var{name}

16945

@opindex mflush-func=@var{name}

16946

Specifies the name of the operating system function to call to flush

16947

the cache. The default is @samp{_flush_cache}, but a function call

16948

is only used if a trap is not available.

16949

16950

@item -mno-flush-func

16951

@opindex mno-flush-func

16952

Indicates that there is no OS function for flushing the cache.

16953

16954

@end table

16955

16956

@node M680x0 Options

16957

@subsection M680x0 Options

16958

@cindex M680x0 options

16959

16960

These are the @samp{-m} options defined for M680x0 and ColdFire processors.

16961

The default settings depend on which architecture was selected when

16962

the compiler was configured; the defaults for the most common choices

16963

are given below.

16964

16965

@table @gcctabopt

16966

@item -march=@var{arch}

16967

@opindex march

16968

Generate code for a specific M680x0 or ColdFire instruction set

16969

architecture. Permissible values of @var{arch} for M680x0

16970

architectures are: @samp{68000}, @samp{68010}, @samp{68020},

16971

@samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}. ColdFire

16972

architectures are selected according to Freescale's ISA classification

16973

and the permissible values are: @samp{isaa}, @samp{isaaplus},

16974

@samp{isab} and @samp{isac}.

16975

16976

GCC defines a macro @code{__mcf@var{arch}__} whenever it is generating

16977

code for a ColdFire target. The @var{arch} in this macro is one of the

16978

@option{-march} arguments given above.

16979

16980

When used together, @option{-march} and @option{-mtune} select code

16981

that runs on a family of similar processors but that is optimized

16982

for a particular microarchitecture.

16983

16984

@item -mcpu=@var{cpu}

16985

@opindex mcpu

16986

Generate code for a specific M680x0 or ColdFire processor.

16987

The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},

16988

@samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}

16989

and @samp{cpu32}. The ColdFire @var{cpu}s are given by the table

16990

below, which also classifies the CPUs into families:

16991

16992

@multitable @columnfractions 0.20 0.80

16993

@item @strong{Family} @tab @strong{@samp{-mcpu} arguments}

16994

@item @samp{51} @tab @samp{51} @samp{51ac} @samp{51ag} @samp{51cn} @samp{51em} @samp{51je} @samp{51jf} @samp{51jg} @samp{51jm} @samp{51mm} @samp{51qe} @samp{51qm}

16995

@item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}

16996

@item @samp{5206e} @tab @samp{5206e}

16997

@item @samp{5208} @tab @samp{5207} @samp{5208}

16998

@item @samp{5211a} @tab @samp{5210a} @samp{5211a}

16999

@item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}

17000

@item @samp{5216} @tab @samp{5214} @samp{5216}

17001

@item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}

17002

@item @samp{5225} @tab @samp{5224} @samp{5225}

17003

@item @samp{52259} @tab @samp{52252} @samp{52254} @samp{52255} @samp{52256} @samp{52258} @samp{52259}

17004

@item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}

17005

@item @samp{5249} @tab @samp{5249}

17006

@item @samp{5250} @tab @samp{5250}

17007

@item @samp{5271} @tab @samp{5270} @samp{5271}

17008

@item @samp{5272} @tab @samp{5272}

17009

@item @samp{5275} @tab @samp{5274} @samp{5275}

17010

@item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}

17011

@item @samp{53017} @tab @samp{53011} @samp{53012} @samp{53013} @samp{53014} @samp{53015} @samp{53016} @samp{53017}

17012

@item @samp{5307} @tab @samp{5307}

17013

@item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}

17014

@item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}

17015

@item @samp{5407} @tab @samp{5407}

17016

@item @samp{5475} @tab @samp{5470} @samp{5471} @samp{5472} @samp{5473} @samp{5474} @samp{5475} @samp{547x} @samp{5480} @samp{5481} @samp{5482} @samp{5483} @samp{5484} @samp{5485}

17017

@end multitable

17018

17019

@option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if

17020

@var{arch} is compatible with @var{cpu}. Other combinations of

17021

@option{-mcpu} and @option{-march} are rejected.

17022

17023

GCC defines the macro @code{__mcf_cpu_@var{cpu}} when ColdFire target

17024

@var{cpu} is selected. It also defines @code{__mcf_family_@var{family}},

17025

where the value of @var{family} is given by the table above.

17026

17027

@item -mtune=@var{tune}

17028

@opindex mtune

17029

Tune the code for a particular microarchitecture within the

17030

constraints set by @option{-march} and @option{-mcpu}.

17031

The M680x0 microarchitectures are: @samp{68000}, @samp{68010},

17032

@samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}

17033

and @samp{cpu32}. The ColdFire microarchitectures

17034

are: @samp{cfv1}, @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.

17035

17036

You can also use @option{-mtune=68020-40} for code that needs

17037

to run relatively well on 68020, 68030 and 68040 targets.

17038

@option{-mtune=68020-60} is similar but includes 68060 targets

17039

as well. These two options select the same tuning decisions as

17040

@option{-m68020-40} and @option{-m68020-60} respectively.

17041

17042

GCC defines the macros @code{__mc@var{arch}} and @code{__mc@var{arch}__}

17043

when tuning for 680x0 architecture @var{arch}. It also defines

17044

@code{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}

17045

option is used. If GCC is tuning for a range of architectures,

17046

as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},

17047

it defines the macros for every architecture in the range.

17048

17049

GCC also defines the macro @code{__m@var{uarch}__} when tuning for

17050

ColdFire microarchitecture @var{uarch}, where @var{uarch} is one

17051

of the arguments given above.

17052

17053

@item -m68000

17054

@itemx -mc68000

17055

@opindex m68000

17056

@opindex mc68000

17057

Generate output for a 68000. This is the default

17058

when the compiler is configured for 68000-based systems.

17059

It is equivalent to @option{-march=68000}.

17060

17061

Use this option for microcontrollers with a 68000 or EC000 core,

17062

including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.

17063

17064

@item -m68010

17065

@opindex m68010

17066

Generate output for a 68010. This is the default

17067

when the compiler is configured for 68010-based systems.

17068

It is equivalent to @option{-march=68010}.

17069

17070

@item -m68020

17071

@itemx -mc68020

17072

@opindex m68020

17073

@opindex mc68020

17074

Generate output for a 68020. This is the default

17075

when the compiler is configured for 68020-based systems.

17076

It is equivalent to @option{-march=68020}.

17077

17078

@item -m68030

17079

@opindex m68030

17080

Generate output for a 68030. This is the default when the compiler is

17081

configured for 68030-based systems. It is equivalent to

17082

@option{-march=68030}.

17083

17084

@item -m68040

17085

@opindex m68040

17086

Generate output for a 68040. This is the default when the compiler is

17087

configured for 68040-based systems. It is equivalent to

17088

@option{-march=68040}.

17089

17090

This option inhibits the use of 68881/68882 instructions that have to be

17091

emulated by software on the 68040. Use this option if your 68040 does not

17092

have code to emulate those instructions.

17093

17094

@item -m68060

17095

@opindex m68060

17096

Generate output for a 68060. This is the default when the compiler is

17097

configured for 68060-based systems. It is equivalent to

17098

@option{-march=68060}.

17099

17100

This option inhibits the use of 68020 and 68881/68882 instructions that

17101

have to be emulated by software on the 68060. Use this option if your 68060

17102

does not have code to emulate those instructions.

17103

17104

@item -mcpu32

17105

@opindex mcpu32

17106

Generate output for a CPU32. This is the default

17107

when the compiler is configured for CPU32-based systems.

17108

It is equivalent to @option{-march=cpu32}.

17109

17110

Use this option for microcontrollers with a

17111

CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,

17112

68336, 68340, 68341, 68349 and 68360.

17113

17114

@item -m5200

17115

@opindex m5200

17116

Generate output for a 520X ColdFire CPU@. This is the default

17117

when the compiler is configured for 520X-based systems.

17118

It is equivalent to @option{-mcpu=5206}, and is now deprecated

17119

in favor of that option.

17120

17121

Use this option for microcontroller with a 5200 core, including

17122

the MCF5202, MCF5203, MCF5204 and MCF5206.

17123

17124

@item -m5206e

17125

@opindex m5206e

17126

Generate output for a 5206e ColdFire CPU@. The option is now

17127

deprecated in favor of the equivalent @option{-mcpu=5206e}.

17128

17129

@item -m528x

17130

@opindex m528x

17131

Generate output for a member of the ColdFire 528X family.

17132

The option is now deprecated in favor of the equivalent

17133

@option{-mcpu=528x}.

17134

17135

@item -m5307

17136

@opindex m5307

17137

Generate output for a ColdFire 5307 CPU@. The option is now deprecated

17138

in favor of the equivalent @option{-mcpu=5307}.

17139

17140

@item -m5407

17141

@opindex m5407

17142

Generate output for a ColdFire 5407 CPU@. The option is now deprecated

17143

in favor of the equivalent @option{-mcpu=5407}.

17144

17145

@item -mcfv4e

17146

@opindex mcfv4e

17147

Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).

17148

This includes use of hardware floating-point instructions.

17149

The option is equivalent to @option{-mcpu=547x}, and is now

17150

deprecated in favor of that option.

17151

17152

@item -m68020-40

17153

@opindex m68020-40

17154

Generate output for a 68040, without using any of the new instructions.

17155

This results in code that can run relatively efficiently on either a

17156

68020/68881 or a 68030 or a 68040. The generated code does use the

17157

68881 instructions that are emulated on the 68040.

17158

17159

The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.

17160

17161

@item -m68020-60

17162

@opindex m68020-60

17163

Generate output for a 68060, without using any of the new instructions.

17164

This results in code that can run relatively efficiently on either a

17165

68020/68881 or a 68030 or a 68040. The generated code does use the

17166

68881 instructions that are emulated on the 68060.

17167

17168

The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.

17169

17170

@item -mhard-float

17171

@itemx -m68881

17172

@opindex mhard-float

17173

@opindex m68881

17174

Generate floating-point instructions. This is the default for 68020

17175

and above, and for ColdFire devices that have an FPU@. It defines the

17176

macro @code{__HAVE_68881__} on M680x0 targets and @code{__mcffpu__}

17177

on ColdFire targets.

17178

17179

@item -msoft-float

17180

@opindex msoft-float

17181

Do not generate floating-point instructions; use library calls instead.

17182

This is the default for 68000, 68010, and 68832 targets. It is also

17183

the default for ColdFire devices that have no FPU.

17184

17185

@item -mdiv

17186

@itemx -mno-div

17187

@opindex mdiv

17188

@opindex mno-div

17189

Generate (do not generate) ColdFire hardware divide and remainder

17190

instructions. If @option{-march} is used without @option{-mcpu},

17191

the default is ``on'' for ColdFire architectures and ``off'' for M680x0

17192

architectures. Otherwise, the default is taken from the target CPU

17193

(either the default CPU, or the one specified by @option{-mcpu}). For

17194

example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for

17195

@option{-mcpu=5206e}.

17196

17197

GCC defines the macro @code{__mcfhwdiv__} when this option is enabled.

17198

17199

@item -mshort

17200

@opindex mshort

17201

Consider type @code{int} to be 16 bits wide, like @code{short int}.

17202

Additionally, parameters passed on the stack are also aligned to a

17203

16-bit boundary even on targets whose API mandates promotion to 32-bit.

17204

17205

@item -mno-short

17206

@opindex mno-short

17207

Do not consider type @code{int} to be 16 bits wide. This is the default.

17208

17209

@item -mnobitfield

17210

@itemx -mno-bitfield

17211

@opindex mnobitfield

17212

@opindex mno-bitfield

17213

Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}

17214

and @option{-m5200} options imply @w{@option{-mnobitfield}}.

17215

17216

@item -mbitfield

17217

@opindex mbitfield

17218

Do use the bit-field instructions. The @option{-m68020} option implies

17219

@option{-mbitfield}. This is the default if you use a configuration

17220

designed for a 68020.

17221

17222

@item -mrtd

17223

@opindex mrtd

17224

Use a different function-calling convention, in which functions

17225

that take a fixed number of arguments return with the @code{rtd}

17226

instruction, which pops their arguments while returning. This

17227

saves one instruction in the caller since there is no need to pop

17228

the arguments there.

17229

17230

This calling convention is incompatible with the one normally

17231

used on Unix, so you cannot use it if you need to call libraries

17232

compiled with the Unix compiler.

17233

17234

Also, you must provide function prototypes for all functions that

17235

take variable numbers of arguments (including @code{printf});

17236

otherwise incorrect code is generated for calls to those

17237

functions.

17238

17239

In addition, seriously incorrect code results if you call a

17240

function with too many arguments. (Normally, extra arguments are

17241

harmlessly ignored.)

17242

17243

The @code{rtd} instruction is supported by the 68010, 68020, 68030,

17244

68040, 68060 and CPU32 processors, but not by the 68000 or 5200.

17245

17246

@item -mno-rtd

17247

@opindex mno-rtd

17248

Do not use the calling conventions selected by @option{-mrtd}.

17249

This is the default.

17250

17251

@item -malign-int

17252

@itemx -mno-align-int

17253

@opindex malign-int

17254

@opindex mno-align-int

17255

Control whether GCC aligns @code{int}, @code{long}, @code{long long},

17256

@code{float}, @code{double}, and @code{long double} variables on a 32-bit

17257

boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).

17258

Aligning variables on 32-bit boundaries produces code that runs somewhat

17259

faster on processors with 32-bit busses at the expense of more memory.

17260

17261

@strong{Warning:} if you use the @option{-malign-int} switch, GCC

17262

aligns structures containing the above types differently than

17263

most published application binary interface specifications for the m68k.

17264

17265

@item -mpcrel

17266

@opindex mpcrel

17267

Use the pc-relative addressing mode of the 68000 directly, instead of

17268

using a global offset table. At present, this option implies @option{-fpic},

17269

allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is

17270

not presently supported with @option{-mpcrel}, though this could be supported for

17271

68020 and higher processors.

17272

17273

@item -mno-strict-align

17274

@itemx -mstrict-align

17275

@opindex mno-strict-align

17276

@opindex mstrict-align

17277

Do not (do) assume that unaligned memory references are handled by

17278

the system.

17279

17280

@item -msep-data

17281

Generate code that allows the data segment to be located in a different

17282

area of memory from the text segment. This allows for execute-in-place in

17283

an environment without virtual memory management. This option implies

17284

@option{-fPIC}.

17285

17286

@item -mno-sep-data

17287

Generate code that assumes that the data segment follows the text segment.

17288

This is the default.

17289

17290

@item -mid-shared-library

17291

Generate code that supports shared libraries via the library ID method.

17292

This allows for execute-in-place and shared libraries in an environment

17293

without virtual memory management. This option implies @option{-fPIC}.

17294

17295

@item -mno-id-shared-library

17296

Generate code that doesn't assume ID-based shared libraries are being used.

17297

This is the default.

17298

17299

@item -mshared-library-id=n

17300

Specifies the identification number of the ID-based shared library being

17301

compiled. Specifying a value of 0 generates more compact code; specifying

17302

other values forces the allocation of that number to the current

17303

library, but is no more space- or time-efficient than omitting this option.

17304

17305

@item -mxgot

17306

@itemx -mno-xgot

17307

@opindex mxgot

17308

@opindex mno-xgot

17309

When generating position-independent code for ColdFire, generate code

17310

that works if the GOT has more than 8192 entries. This code is

17311

larger and slower than code generated without this option. On M680x0

17312

processors, this option is not needed; @option{-fPIC} suffices.

17313

17314

GCC normally uses a single instruction to load values from the GOT@.

17315

While this is relatively efficient, it only works if the GOT

17316

is smaller than about 64k. Anything larger causes the linker

17317

to report an error such as:

17318

17319

@cindex relocation truncated to fit (ColdFire)

17320

@smallexample

17321

relocation truncated to fit: R_68K_GOT16O foobar

17322

@end smallexample

17323

17324

If this happens, you should recompile your code with @option{-mxgot}.

17325

It should then work with very large GOTs. However, code generated with

17326

@option{-mxgot} is less efficient, since it takes 4 instructions to fetch

17327

the value of a global symbol.

17328

17329

Note that some linkers, including newer versions of the GNU linker,

17330

can create multiple GOTs and sort GOT entries. If you have such a linker,

17331

you should only need to use @option{-mxgot} when compiling a single

17332

object file that accesses more than 8192 GOT entries. Very few do.

17333

17334

These options have no effect unless GCC is generating

17335

position-independent code.

17336

17337

@end table

17338

17339

@node MCore Options

17340

@subsection MCore Options

17341

@cindex MCore options

17342

17343

These are the @samp{-m} options defined for the Motorola M*Core

17344

processors.

17345

17346

@table @gcctabopt

17347

17348

@item -mhardlit

17349

@itemx -mno-hardlit

17350

@opindex mhardlit

17351

@opindex mno-hardlit

17352

Inline constants into the code stream if it can be done in two

17353

instructions or less.

17354

17355

@item -mdiv

17356

@itemx -mno-div

17357

@opindex mdiv

17358

@opindex mno-div

17359

Use the divide instruction. (Enabled by default).

17360

17361

@item -mrelax-immediate

17362

@itemx -mno-relax-immediate

17363

@opindex mrelax-immediate

17364

@opindex mno-relax-immediate

17365

Allow arbitrary-sized immediates in bit operations.

17366

17367

@item -mwide-bitfields

17368

@itemx -mno-wide-bitfields

17369

@opindex mwide-bitfields

17370

@opindex mno-wide-bitfields

17371

Always treat bit-fields as @code{int}-sized.

17372

17373

@item -m4byte-functions

17374

@itemx -mno-4byte-functions

17375

@opindex m4byte-functions

17376

@opindex mno-4byte-functions

17377

Force all functions to be aligned to a 4-byte boundary.

17378

17379

@item -mcallgraph-data

17380

@itemx -mno-callgraph-data

17381

@opindex mcallgraph-data

17382

@opindex mno-callgraph-data

17383

Emit callgraph information.

17384

17385

@item -mslow-bytes

17386

@itemx -mno-slow-bytes

17387

@opindex mslow-bytes

17388

@opindex mno-slow-bytes

17389

Prefer word access when reading byte quantities.

17390

17391

@item -mlittle-endian

17392

@itemx -mbig-endian

17393

@opindex mlittle-endian

17394

@opindex mbig-endian

17395

Generate code for a little-endian target.

17396

17397

@item -m210

17398

@itemx -m340

17399

@opindex m210

17400

@opindex m340

17401

Generate code for the 210 processor.

17402

17403

@item -mno-lsim

17404

@opindex mno-lsim

17405

Assume that runtime support has been provided and so omit the

17406

simulator library (@file{libsim.a)} from the linker command line.

17407

17408

@item -mstack-increment=@var{size}

17409

@opindex mstack-increment

17410

Set the maximum amount for a single stack increment operation. Large

17411

values can increase the speed of programs that contain functions

17412

that need a large amount of stack space, but they can also trigger a

17413

segmentation fault if the stack is extended too much. The default

17414

value is 0x1000.

17415

17416

@end table

17417

17418

@node MeP Options

17419

@subsection MeP Options

17420

@cindex MeP options

17421

17422

@table @gcctabopt

17423

17424

@item -mabsdiff

17425

@opindex mabsdiff

17426

Enables the @code{abs} instruction, which is the absolute difference

17427

between two registers.

17428

17429

@item -mall-opts

17430

@opindex mall-opts

17431

Enables all the optional instructions---average, multiply, divide, bit

17432

operations, leading zero, absolute difference, min/max, clip, and

17433

saturation.

17434

17435

17436

@item -maverage

17437

@opindex maverage

17438

Enables the @code{ave} instruction, which computes the average of two

17439

registers.

17440

17441

@item -mbased=@var{n}

17442

@opindex mbased=

17443

Variables of size @var{n} bytes or smaller are placed in the

17444

@code{.based} section by default. Based variables use the @code{$tp}

17445

register as a base register, and there is a 128-byte limit to the

17446

@code{.based} section.

17447

17448

@item -mbitops

17449

@opindex mbitops

17450

Enables the bit operation instructions---bit test (@code{btstm}), set

17451

(@code{bsetm}), clear (@code{bclrm}), invert (@code{bnotm}), and

17452

test-and-set (@code{tas}).

17453

17454

@item -mc=@var{name}

17455

@opindex mc=

17456

Selects which section constant data is placed in. @var{name} may

17457

be @samp{tiny}, @samp{near}, or @samp{far}.

17458

17459

@item -mclip

17460

@opindex mclip

17461

Enables the @code{clip} instruction. Note that @option{-mclip} is not

17462

useful unless you also provide @option{-mminmax}.

17463

17464

@item -mconfig=@var{name}

17465

@opindex mconfig=

17466

Selects one of the built-in core configurations. Each MeP chip has

17467

one or more modules in it; each module has a core CPU and a variety of

17468

coprocessors, optional instructions, and peripherals. The

17469

@code{MeP-Integrator} tool, not part of GCC, provides these

17470

configurations through this option; using this option is the same as

17471

using all the corresponding command-line options. The default

17472

configuration is @samp{default}.

17473

17474

@item -mcop

17475

@opindex mcop

17476

Enables the coprocessor instructions. By default, this is a 32-bit

17477

coprocessor. Note that the coprocessor is normally enabled via the

17478

@option{-mconfig=} option.

17479

17480

@item -mcop32

17481

@opindex mcop32

17482

Enables the 32-bit coprocessor's instructions.

17483

17484

@item -mcop64

17485

@opindex mcop64

17486

Enables the 64-bit coprocessor's instructions.

17487

17488

@item -mivc2

17489

@opindex mivc2

17490

Enables IVC2 scheduling. IVC2 is a 64-bit VLIW coprocessor.

17491

17492

@item -mdc

17493

@opindex mdc

17494

Causes constant variables to be placed in the @code{.near} section.

17495

17496

@item -mdiv

17497

@opindex mdiv

17498

Enables the @code{div} and @code{divu} instructions.

17499

17500

@item -meb

17501

@opindex meb

17502

Generate big-endian code.

17503

17504

@item -mel

17505

@opindex mel

17506

Generate little-endian code.

17507

17508

@item -mio-volatile

17509

@opindex mio-volatile

17510

Tells the compiler that any variable marked with the @code{io}

17511

attribute is to be considered volatile.

17512

17513

@item -ml

17514

@opindex ml

17515

Causes variables to be assigned to the @code{.far} section by default.

17516

17517

@item -mleadz

17518

@opindex mleadz

17519

Enables the @code{leadz} (leading zero) instruction.

17520

17521

@item -mm

17522

@opindex mm

17523

Causes variables to be assigned to the @code{.near} section by default.

17524

17525

@item -mminmax

17526

@opindex mminmax

17527

Enables the @code{min} and @code{max} instructions.

17528

17529

@item -mmult

17530

@opindex mmult

17531

Enables the multiplication and multiply-accumulate instructions.

17532

17533

@item -mno-opts

17534

@opindex mno-opts

17535

Disables all the optional instructions enabled by @option{-mall-opts}.

17536

17537

@item -mrepeat

17538

@opindex mrepeat

17539

Enables the @code{repeat} and @code{erepeat} instructions, used for

17540

low-overhead looping.

17541

17542

@item -ms

17543

@opindex ms

17544

Causes all variables to default to the @code{.tiny} section. Note

17545

that there is a 65536-byte limit to this section. Accesses to these

17546

variables use the @code{%gp} base register.

17547

17548

@item -msatur

17549

@opindex msatur

17550

Enables the saturation instructions. Note that the compiler does not

17551

currently generate these itself, but this option is included for

17552

compatibility with other tools, like @code{as}.

17553

17554

@item -msdram

17555

@opindex msdram

17556

Link the SDRAM-based runtime instead of the default ROM-based runtime.

17557

17558

@item -msim

17559

@opindex msim

17560

Link the simulator run-time libraries.

17561

17562

@item -msimnovec

17563

@opindex msimnovec

17564

Link the simulator runtime libraries, excluding built-in support

17565

for reset and exception vectors and tables.

17566

17567

@item -mtf

17568

@opindex mtf

17569

Causes all functions to default to the @code{.far} section. Without

17570

this option, functions default to the @code{.near} section.

17571

17572

@item -mtiny=@var{n}

17573

@opindex mtiny=

17574

Variables that are @var{n} bytes or smaller are allocated to the

17575

@code{.tiny} section. These variables use the @code{$gp} base

17576

register. The default for this option is 4, but note that there's a

17577

65536-byte limit to the @code{.tiny} section.

17578

17579

@end table

17580

17581

@node MicroBlaze Options

17582

@subsection MicroBlaze Options

17583

@cindex MicroBlaze Options

17584

17585

@table @gcctabopt

17586

17587

@item -msoft-float

17588

@opindex msoft-float

17589

Use software emulation for floating point (default).

17590

17591

@item -mhard-float

17592

@opindex mhard-float

17593

Use hardware floating-point instructions.

17594

17595

@item -mmemcpy

17596

@opindex mmemcpy

17597

Do not optimize block moves, use @code{memcpy}.

17598

17599

@item -mno-clearbss

17600

@opindex mno-clearbss

17601

This option is deprecated. Use @option{-fno-zero-initialized-in-bss} instead.

17602

17603

@item -mcpu=@var{cpu-type}

17604

@opindex mcpu=

17605

Use features of, and schedule code for, the given CPU.

17606

Supported values are in the format @samp{v@var{X}.@var{YY}.@var{Z}},

17607

where @var{X} is a major version, @var{YY} is the minor version, and

17608

@var{Z} is compatibility code. Example values are @samp{v3.00.a},

17609

@samp{v4.00.b}, @samp{v5.00.a}, @samp{v5.00.b}, @samp{v5.00.b}, @samp{v6.00.a}.

17610

17611

@item -mxl-soft-mul

17612

@opindex mxl-soft-mul

17613

Use software multiply emulation (default).

17614

17615

@item -mxl-soft-div

17616

@opindex mxl-soft-div

17617

Use software emulation for divides (default).

17618

17619

@item -mxl-barrel-shift

17620

@opindex mxl-barrel-shift

17621

Use the hardware barrel shifter.

17622

17623

@item -mxl-pattern-compare

17624

@opindex mxl-pattern-compare

17625

Use pattern compare instructions.

17626

17627

@item -msmall-divides

17628

@opindex msmall-divides

17629

Use table lookup optimization for small signed integer divisions.

17630

17631

@item -mxl-stack-check

17632

@opindex mxl-stack-check

17633

This option is deprecated. Use @option{-fstack-check} instead.

17634

17635

@item -mxl-gp-opt

17636

@opindex mxl-gp-opt

17637

Use GP-relative @code{.sdata}/@code{.sbss} sections.

17638

17639

@item -mxl-multiply-high

17640

@opindex mxl-multiply-high

17641

Use multiply high instructions for high part of 32x32 multiply.

17642

17643

@item -mxl-float-convert

17644

@opindex mxl-float-convert

17645

Use hardware floating-point conversion instructions.

17646

17647

@item -mxl-float-sqrt

17648

@opindex mxl-float-sqrt

17649

Use hardware floating-point square root instruction.

17650

17651

@item -mbig-endian

17652

@opindex mbig-endian

17653

Generate code for a big-endian target.

17654

17655

@item -mlittle-endian

17656

@opindex mlittle-endian

17657

Generate code for a little-endian target.

17658

17659

@item -mxl-reorder

17660

@opindex mxl-reorder

17661

Use reorder instructions (swap and byte reversed load/store).

17662

17663

@item -mxl-mode-@var{app-model}

17664

Select application model @var{app-model}. Valid models are

17665

@table @samp

17666

@item executable

17667

normal executable (default), uses startup code @file{crt0.o}.

17668

17669

@item xmdstub

17670

for use with Xilinx Microprocessor Debugger (XMD) based

17671

software intrusive debug agent called xmdstub. This uses startup file

17672

@file{crt1.o} and sets the start address of the program to 0x800.

17673

17674

@item bootstrap

17675

for applications that are loaded using a bootloader.

17676

This model uses startup file @file{crt2.o} which does not contain a processor

17677

reset vector handler. This is suitable for transferring control on a

17678

processor reset to the bootloader rather than the application.

17679

17680

@item novectors

17681

for applications that do not require any of the

17682

MicroBlaze vectors. This option may be useful for applications running

17683

within a monitoring application. This model uses @file{crt3.o} as a startup file.

17684

@end table

17685

17686

Option @option{-xl-mode-@var{app-model}} is a deprecated alias for

17687

@option{-mxl-mode-@var{app-model}}.

17688

17689

@end table

17690

17691

@node MIPS Options

17692

@subsection MIPS Options

17693

@cindex MIPS options

17694

17695

@table @gcctabopt

17696

17697

@item -EB

17698

@opindex EB

17699

Generate big-endian code.

17700

17701

@item -EL

17702

@opindex EL

17703

Generate little-endian code. This is the default for @samp{mips*el-*-*}

17704

configurations.

17705

17706

@item -march=@var{arch}

17707

@opindex march

17708

Generate code that runs on @var{arch}, which can be the name of a

17709

generic MIPS ISA, or the name of a particular processor.

17710

The ISA names are:

17711

@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},

17712

@samp{mips32}, @samp{mips32r2}, @samp{mips32r3}, @samp{mips32r5},

17713

@samp{mips32r6}, @samp{mips64}, @samp{mips64r2}, @samp{mips64r3},

17714

@samp{mips64r5} and @samp{mips64r6}.

17715

The processor names are:

17716

@samp{4kc}, @samp{4km}, @samp{4kp}, @samp{4ksc},

17717

@samp{4kec}, @samp{4kem}, @samp{4kep}, @samp{4ksd},

17718

@samp{5kc}, @samp{5kf},

17719

@samp{20kc},

17720

@samp{24kc}, @samp{24kf2_1}, @samp{24kf1_1},

17721

@samp{24kec}, @samp{24kef2_1}, @samp{24kef1_1},

17722

@samp{34kc}, @samp{34kf2_1}, @samp{34kf1_1}, @samp{34kn},

17723

@samp{74kc}, @samp{74kf2_1}, @samp{74kf1_1}, @samp{74kf3_2},

17724

@samp{1004kc}, @samp{1004kf2_1}, @samp{1004kf1_1},

17725

@samp{i6400},

17726

@samp{interaptiv},

17727

@samp{loongson2e}, @samp{loongson2f}, @samp{loongson3a},

17728

@samp{m4k},

17729

@samp{m14k}, @samp{m14kc}, @samp{m14ke}, @samp{m14kec},

17730

@samp{m5100}, @samp{m5101},

17731

@samp{octeon}, @samp{octeon+}, @samp{octeon2}, @samp{octeon3},

17732

@samp{orion},

17733

@samp{p5600},

17734

@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},

17735

@samp{r4600}, @samp{r4650}, @samp{r4700}, @samp{r6000}, @samp{r8000},

17736

@samp{rm7000}, @samp{rm9000},

17737

@samp{r10000}, @samp{r12000}, @samp{r14000}, @samp{r16000},

17738

@samp{sb1},

17739

@samp{sr71000},

17740

@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},

17741

@samp{vr5000}, @samp{vr5400}, @samp{vr5500},

17742

@samp{xlr} and @samp{xlp}.

17743

The special value @samp{from-abi} selects the

17744

most compatible architecture for the selected ABI (that is,

17745

@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.

17746

17747

The native Linux/GNU toolchain also supports the value @samp{native},

17748

which selects the best architecture option for the host processor.

17749

@option{-march=native} has no effect if GCC does not recognize

17750

the processor.

17751

17752

In processor names, a final @samp{000} can be abbreviated as @samp{k}

17753

(for example, @option{-march=r2k}). Prefixes are optional, and

17754

@samp{vr} may be written @samp{r}.

17755

17756

Names of the form @samp{@var{n}f2_1} refer to processors with

17757

FPUs clocked at half the rate of the core, names of the form

17758

@samp{@var{n}f1_1} refer to processors with FPUs clocked at the same

17759

rate as the core, and names of the form @samp{@var{n}f3_2} refer to

17760

processors with FPUs clocked a ratio of 3:2 with respect to the core.

17761

For compatibility reasons, @samp{@var{n}f} is accepted as a synonym

17762

for @samp{@var{n}f2_1} while @samp{@var{n}x} and @samp{@var{b}fx} are

17763

accepted as synonyms for @samp{@var{n}f1_1}.

17764

17765

GCC defines two macros based on the value of this option. The first

17766

is @code{_MIPS_ARCH}, which gives the name of target architecture, as

17767

a string. The second has the form @code{_MIPS_ARCH_@var{foo}},

17768

where @var{foo} is the capitalized value of @code{_MIPS_ARCH}@.

17769

For example, @option{-march=r2000} sets @code{_MIPS_ARCH}

17770

to @code{"r2000"} and defines the macro @code{_MIPS_ARCH_R2000}.

17771

17772

Note that the @code{_MIPS_ARCH} macro uses the processor names given

17773

above. In other words, it has the full prefix and does not

17774

abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},

17775

the macro names the resolved architecture (either @code{"mips1"} or

17776

@code{"mips3"}). It names the default architecture when no

17777

@option{-march} option is given.

17778

17779

@item -mtune=@var{arch}

17780

@opindex mtune

17781

Optimize for @var{arch}. Among other things, this option controls

17782

the way instructions are scheduled, and the perceived cost of arithmetic

17783

operations. The list of @var{arch} values is the same as for

17784

@option{-march}.

17785

17786

When this option is not used, GCC optimizes for the processor

17787

specified by @option{-march}. By using @option{-march} and

17788

@option{-mtune} together, it is possible to generate code that

17789

runs on a family of processors, but optimize the code for one

17790

particular member of that family.

17791

17792

@option{-mtune} defines the macros @code{_MIPS_TUNE} and

17793

@code{_MIPS_TUNE_@var{foo}}, which work in the same way as the

17794

@option{-march} ones described above.

17795

17796

@item -mips1

17797

@opindex mips1

17798

Equivalent to @option{-march=mips1}.

17799

17800

@item -mips2

17801

@opindex mips2

17802

Equivalent to @option{-march=mips2}.

17803

17804

@item -mips3

17805

@opindex mips3

17806

Equivalent to @option{-march=mips3}.

17807

17808

@item -mips4

17809

@opindex mips4

17810

Equivalent to @option{-march=mips4}.

17811

17812

@item -mips32

17813

@opindex mips32

17814

Equivalent to @option{-march=mips32}.

17815

17816

@item -mips32r3

17817

@opindex mips32r3

17818

Equivalent to @option{-march=mips32r3}.

17819

17820

@item -mips32r5

17821

@opindex mips32r5

17822

Equivalent to @option{-march=mips32r5}.

17823

17824

@item -mips32r6

17825

@opindex mips32r6

17826

Equivalent to @option{-march=mips32r6}.

17827

17828

@item -mips64

17829

@opindex mips64

17830

Equivalent to @option{-march=mips64}.

17831

17832

@item -mips64r2

17833

@opindex mips64r2

17834

Equivalent to @option{-march=mips64r2}.

17835

17836

@item -mips64r3

17837

@opindex mips64r3

17838

Equivalent to @option{-march=mips64r3}.

17839

17840

@item -mips64r5

17841

@opindex mips64r5

17842

Equivalent to @option{-march=mips64r5}.

17843

17844

@item -mips64r6

17845

@opindex mips64r6

17846

Equivalent to @option{-march=mips64r6}.

17847

17848

@item -mips16

17849

@itemx -mno-mips16

17850

@opindex mips16

17851

@opindex mno-mips16

17852

Generate (do not generate) MIPS16 code. If GCC is targeting a

17853

MIPS32 or MIPS64 architecture, it makes use of the MIPS16e ASE@.

17854

17855

MIPS16 code generation can also be controlled on a per-function basis

17856

by means of @code{mips16} and @code{nomips16} attributes.

17857

@xref{Function Attributes}, for more information.

17858

17859

@item -mflip-mips16

17860

@opindex mflip-mips16

17861

Generate MIPS16 code on alternating functions. This option is provided

17862

for regression testing of mixed MIPS16/non-MIPS16 code generation, and is

17863

not intended for ordinary use in compiling user code.

17864

17865

@item -minterlink-compressed

17866

@item -mno-interlink-compressed

17867

@opindex minterlink-compressed

17868

@opindex mno-interlink-compressed

17869

Require (do not require) that code using the standard (uncompressed) MIPS ISA

17870

be link-compatible with MIPS16 and microMIPS code, and vice versa.

17871

17872

For example, code using the standard ISA encoding cannot jump directly

17873

to MIPS16 or microMIPS code; it must either use a call or an indirect jump.

17874

@option{-minterlink-compressed} therefore disables direct jumps unless GCC

17875

knows that the target of the jump is not compressed.

17876

17877

@item -minterlink-mips16

17878

@itemx -mno-interlink-mips16

17879

@opindex minterlink-mips16

17880

@opindex mno-interlink-mips16

17881

Aliases of @option{-minterlink-compressed} and

17882

@option{-mno-interlink-compressed}. These options predate the microMIPS ASE

17883

and are retained for backwards compatibility.

17884

17885

@item -mabi=32

17886

@itemx -mabi=o64

17887

@itemx -mabi=n32

17888

@itemx -mabi=64

17889

@itemx -mabi=eabi

17890

@opindex mabi=32

17891

@opindex mabi=o64

17892

@opindex mabi=n32

17893

@opindex mabi=64

17894

@opindex mabi=eabi

17895

Generate code for the given ABI@.

17896

17897

Note that the EABI has a 32-bit and a 64-bit variant. GCC normally

17898

generates 64-bit code when you select a 64-bit architecture, but you

17899

can use @option{-mgp32} to get 32-bit code instead.

17900

17901

For information about the O64 ABI, see

17902

@uref{http://gcc.gnu.org/@/projects/@/mipso64-abi.html}.

17903

17904

GCC supports a variant of the o32 ABI in which floating-point registers

17905

are 64 rather than 32 bits wide. You can select this combination with

17906

@option{-mabi=32} @option{-mfp64}. This ABI relies on the @code{mthc1}

17907

and @code{mfhc1} instructions and is therefore only supported for

17908

MIPS32R2, MIPS32R3 and MIPS32R5 processors.

17909

17910

The register assignments for arguments and return values remain the

17911

same, but each scalar value is passed in a single 64-bit register

17912

rather than a pair of 32-bit registers. For example, scalar

17913

floating-point values are returned in @samp{$f0} only, not a

17914

@samp{$f0}/@samp{$f1} pair. The set of call-saved registers also

17915

remains the same in that the even-numbered double-precision registers

17916

are saved.

17917

17918

Two additional variants of the o32 ABI are supported to enable

17919

a transition from 32-bit to 64-bit registers. These are FPXX

17920

(@option{-mfpxx}) and FP64A (@option{-mfp64} @option{-mno-odd-spreg}).

17921

The FPXX extension mandates that all code must execute correctly

17922

when run using 32-bit or 64-bit registers. The code can be interlinked

17923

with either FP32 or FP64, but not both.

17924

The FP64A extension is similar to the FP64 extension but forbids the

17925

use of odd-numbered single-precision registers. This can be used

17926

in conjunction with the @code{FRE} mode of FPUs in MIPS32R5

17927

processors and allows both FP32 and FP64A code to interlink and

17928

run in the same process without changing FPU modes.

17929

17930

@item -mabicalls

17931

@itemx -mno-abicalls

17932

@opindex mabicalls

17933

@opindex mno-abicalls

17934

Generate (do not generate) code that is suitable for SVR4-style

17935

dynamic objects. @option{-mabicalls} is the default for SVR4-based

17936

systems.

17937

17938

@item -mshared

17939

@itemx -mno-shared

17940

Generate (do not generate) code that is fully position-independent,

17941

and that can therefore be linked into shared libraries. This option

17942

only affects @option{-mabicalls}.

17943

17944

All @option{-mabicalls} code has traditionally been position-independent,

17945

regardless of options like @option{-fPIC} and @option{-fpic}. However,

17946

as an extension, the GNU toolchain allows executables to use absolute

17947

accesses for locally-binding symbols. It can also use shorter GP

17948

initialization sequences and generate direct calls to locally-defined

17949

functions. This mode is selected by @option{-mno-shared}.

17950

17951

@option{-mno-shared} depends on binutils 2.16 or higher and generates

17952

objects that can only be linked by the GNU linker. However, the option

17953

does not affect the ABI of the final executable; it only affects the ABI

17954

of relocatable objects. Using @option{-mno-shared} generally makes

17955

executables both smaller and quicker.

17956

17957

@option{-mshared} is the default.

17958

17959

@item -mplt

17960

@itemx -mno-plt

17961

@opindex mplt

17962

@opindex mno-plt

17963

Assume (do not assume) that the static and dynamic linkers

17964

support PLTs and copy relocations. This option only affects

17965

@option{-mno-shared -mabicalls}. For the n64 ABI, this option

17966

has no effect without @option{-msym32}.

17967

17968

You can make @option{-mplt} the default by configuring

17969

GCC with @option{--with-mips-plt}. The default is

17970

@option{-mno-plt} otherwise.

17971

17972

@item -mxgot

17973

@itemx -mno-xgot

17974

@opindex mxgot

17975

@opindex mno-xgot

17976

Lift (do not lift) the usual restrictions on the size of the global

17977

offset table.

17978

17979

GCC normally uses a single instruction to load values from the GOT@.

17980

While this is relatively efficient, it only works if the GOT

17981

is smaller than about 64k. Anything larger causes the linker

17982

to report an error such as:

17983

17984

@cindex relocation truncated to fit (MIPS)

17985

@smallexample

17986

relocation truncated to fit: R_MIPS_GOT16 foobar

17987

@end smallexample

17988

17989

If this happens, you should recompile your code with @option{-mxgot}.

17990

This works with very large GOTs, although the code is also

17991

less efficient, since it takes three instructions to fetch the

17992

value of a global symbol.

17993

17994

Note that some linkers can create multiple GOTs. If you have such a

17995

linker, you should only need to use @option{-mxgot} when a single object

17996

file accesses more than 64k's worth of GOT entries. Very few do.

17997

17998

These options have no effect unless GCC is generating position

17999

independent code.

18000

18001

@item -mgp32

18002

@opindex mgp32

18003

Assume that general-purpose registers are 32 bits wide.

18004

18005

@item -mgp64

18006

@opindex mgp64

18007

Assume that general-purpose registers are 64 bits wide.

18008

18009

@item -mfp32

18010

@opindex mfp32

18011

Assume that floating-point registers are 32 bits wide.

18012

18013

@item -mfp64

18014

@opindex mfp64

18015

Assume that floating-point registers are 64 bits wide.

18016

18017

@item -mfpxx

18018

@opindex mfpxx

18019

Do not assume the width of floating-point registers.

18020

18021

@item -mhard-float

18022

@opindex mhard-float

18023

Use floating-point coprocessor instructions.

18024

18025

@item -msoft-float

18026

@opindex msoft-float

18027

Do not use floating-point coprocessor instructions. Implement

18028

floating-point calculations using library calls instead.

18029

18030

@item -mno-float

18031

@opindex mno-float

18032

Equivalent to @option{-msoft-float}, but additionally asserts that the

18033

program being compiled does not perform any floating-point operations.

18034

This option is presently supported only by some bare-metal MIPS

18035

configurations, where it may select a special set of libraries

18036

that lack all floating-point support (including, for example, the

18037

floating-point @code{printf} formats).

18038

If code compiled with @option{-mno-float} accidentally contains

18039

floating-point operations, it is likely to suffer a link-time

18040

or run-time failure.

18041

18042

@item -msingle-float

18043

@opindex msingle-float

18044

Assume that the floating-point coprocessor only supports single-precision

18045

operations.

18046

18047

@item -mdouble-float

18048

@opindex mdouble-float

18049

Assume that the floating-point coprocessor supports double-precision

18050

operations. This is the default.

18051

18052

@item -modd-spreg

18053

@itemx -mno-odd-spreg

18054

@opindex modd-spreg

18055

@opindex mno-odd-spreg

18056

Enable the use of odd-numbered single-precision floating-point registers

18057

for the o32 ABI. This is the default for processors that are known to

18058

support these registers. When using the o32 FPXX ABI, @option{-mno-odd-spreg}

18059

is set by default.

18060

18061

@item -mabs=2008

18062

@itemx -mabs=legacy

18063

@opindex mabs=2008

18064

@opindex mabs=legacy

18065

These options control the treatment of the special not-a-number (NaN)

18066

IEEE 754 floating-point data with the @code{abs.@i{fmt}} and

18067

@code{neg.@i{fmt}} machine instructions.

18068

18069

By default or when @option{-mabs=legacy} is used the legacy

18070

treatment is selected. In this case these instructions are considered

18071

arithmetic and avoided where correct operation is required and the

18072

input operand might be a NaN. A longer sequence of instructions that

18073

manipulate the sign bit of floating-point datum manually is used

18074

instead unless the @option{-ffinite-math-only} option has also been

18075

specified.

18076

18077

The @option{-mabs=2008} option selects the IEEE 754-2008 treatment. In

18078

this case these instructions are considered non-arithmetic and therefore

18079

operating correctly in all cases, including in particular where the

18080

input operand is a NaN. These instructions are therefore always used

18081

for the respective operations.

18082

18083

@item -mnan=2008

18084

@itemx -mnan=legacy

18085

@opindex mnan=2008

18086

@opindex mnan=legacy

18087

These options control the encoding of the special not-a-number (NaN)

18088

IEEE 754 floating-point data.

18089

18090

The @option{-mnan=legacy} option selects the legacy encoding. In this

18091

case quiet NaNs (qNaNs) are denoted by the first bit of their trailing

18092

significand field being 0, whereas signalling NaNs (sNaNs) are denoted

18093

by the first bit of their trailing significand field being 1.

18094

18095

The @option{-mnan=2008} option selects the IEEE 754-2008 encoding. In

18096

this case qNaNs are denoted by the first bit of their trailing

18097

significand field being 1, whereas sNaNs are denoted by the first bit of

18098

their trailing significand field being 0.

18099

18100

The default is @option{-mnan=legacy} unless GCC has been configured with

18101

@option{--with-nan=2008}.

18102

18103

@item -mllsc

18104

@itemx -mno-llsc

18105

@opindex mllsc

18106

@opindex mno-llsc

18107

Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to

18108

implement atomic memory built-in functions. When neither option is

18109

specified, GCC uses the instructions if the target architecture

18110

supports them.

18111

18112

@option{-mllsc} is useful if the runtime environment can emulate the

18113

instructions and @option{-mno-llsc} can be useful when compiling for

18114

nonstandard ISAs. You can make either option the default by

18115

configuring GCC with @option{--with-llsc} and @option{--without-llsc}

18116

respectively. @option{--with-llsc} is the default for some

18117

configurations; see the installation documentation for details.

18118

18119

@item -mdsp

18120

@itemx -mno-dsp

18121

@opindex mdsp

18122

@opindex mno-dsp

18123

Use (do not use) revision 1 of the MIPS DSP ASE@.

18124

@xref{MIPS DSP Built-in Functions}. This option defines the

18125

preprocessor macro @code{__mips_dsp}. It also defines

18126

@code{__mips_dsp_rev} to 1.

18127

18128

@item -mdspr2

18129

@itemx -mno-dspr2

18130

@opindex mdspr2

18131

@opindex mno-dspr2

18132

Use (do not use) revision 2 of the MIPS DSP ASE@.

18133

@xref{MIPS DSP Built-in Functions}. This option defines the

18134

preprocessor macros @code{__mips_dsp} and @code{__mips_dspr2}.

18135

It also defines @code{__mips_dsp_rev} to 2.

18136

18137

@item -msmartmips

18138

@itemx -mno-smartmips

18139

@opindex msmartmips

18140

@opindex mno-smartmips

18141

Use (do not use) the MIPS SmartMIPS ASE.

18142

18143

@item -mpaired-single

18144

@itemx -mno-paired-single

18145

@opindex mpaired-single

18146

@opindex mno-paired-single

18147

Use (do not use) paired-single floating-point instructions.

18148

@xref{MIPS Paired-Single Support}. This option requires

18149

hardware floating-point support to be enabled.

18150

18151

@item -mdmx

18152

@itemx -mno-mdmx

18153

@opindex mdmx

18154

@opindex mno-mdmx

18155

Use (do not use) MIPS Digital Media Extension instructions.

18156

This option can only be used when generating 64-bit code and requires

18157

hardware floating-point support to be enabled.

18158

18159

@item -mips3d

18160

@itemx -mno-mips3d

18161

@opindex mips3d

18162

@opindex mno-mips3d

18163

Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.

18164

The option @option{-mips3d} implies @option{-mpaired-single}.

18165

18166

@item -mmicromips

18167

@itemx -mno-micromips

18168

@opindex mmicromips

18169

@opindex mno-mmicromips

18170

Generate (do not generate) microMIPS code.

18171

18172

MicroMIPS code generation can also be controlled on a per-function basis

18173

by means of @code{micromips} and @code{nomicromips} attributes.

18174

@xref{Function Attributes}, for more information.

18175

18176

@item -mmt

18177

@itemx -mno-mt

18178

@opindex mmt

18179

@opindex mno-mt

18180

Use (do not use) MT Multithreading instructions.

18181

18182

@item -mmcu

18183

@itemx -mno-mcu

18184

@opindex mmcu

18185

@opindex mno-mcu

18186

Use (do not use) the MIPS MCU ASE instructions.

18187

18188

@item -meva

18189

@itemx -mno-eva

18190

@opindex meva

18191

@opindex mno-eva

18192

Use (do not use) the MIPS Enhanced Virtual Addressing instructions.

18193

18194

@item -mvirt

18195

@itemx -mno-virt

18196

@opindex mvirt

18197

@opindex mno-virt

18198

Use (do not use) the MIPS Virtualization Application Specific instructions.

18199

18200

@item -mxpa

18201

@itemx -mno-xpa

18202

@opindex mxpa

18203

@opindex mno-xpa

18204

Use (do not use) the MIPS eXtended Physical Address (XPA) instructions.

18205

18206

@item -mlong64

18207

@opindex mlong64

18208

Force @code{long} types to be 64 bits wide. See @option{-mlong32} for

18209

an explanation of the default and the way that the pointer size is

18210

determined.

18211

18212

@item -mlong32

18213

@opindex mlong32

18214

Force @code{long}, @code{int}, and pointer types to be 32 bits wide.

18215

18216

The default size of @code{int}s, @code{long}s and pointers depends on

18217

the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI

18218

uses 64-bit @code{long}s, as does the 64-bit EABI; the others use

18219

32-bit @code{long}s. Pointers are the same size as @code{long}s,

18220

or the same size as integer registers, whichever is smaller.

18221

18222

@item -msym32

18223

@itemx -mno-sym32

18224

@opindex msym32

18225

@opindex mno-sym32

18226

Assume (do not assume) that all symbols have 32-bit values, regardless

18227

of the selected ABI@. This option is useful in combination with

18228

@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC

18229

to generate shorter and faster references to symbolic addresses.

18230

18231

@item -G @var{num}

18232

@opindex G

18233

Put definitions of externally-visible data in a small data section

18234

if that data is no bigger than @var{num} bytes. GCC can then generate

18235

more efficient accesses to the data; see @option{-mgpopt} for details.

18236

18237

The default @option{-G} option depends on the configuration.

18238

18239

@item -mlocal-sdata

18240

@itemx -mno-local-sdata

18241

@opindex mlocal-sdata

18242

@opindex mno-local-sdata

18243

Extend (do not extend) the @option{-G} behavior to local data too,

18244

such as to static variables in C@. @option{-mlocal-sdata} is the

18245

default for all configurations.

18246

18247

If the linker complains that an application is using too much small data,

18248

you might want to try rebuilding the less performance-critical parts with

18249

@option{-mno-local-sdata}. You might also want to build large

18250

libraries with @option{-mno-local-sdata}, so that the libraries leave

18251

more room for the main program.

18252

18253

@item -mextern-sdata

18254

@itemx -mno-extern-sdata

18255

@opindex mextern-sdata

18256

@opindex mno-extern-sdata

18257

Assume (do not assume) that externally-defined data is in

18258

a small data section if the size of that data is within the @option{-G} limit.

18259

@option{-mextern-sdata} is the default for all configurations.

18260

18261

If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G

18262

@var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}

18263

that is no bigger than @var{num} bytes, you must make sure that @var{Var}

18264

is placed in a small data section. If @var{Var} is defined by another

18265

module, you must either compile that module with a high-enough

18266

@option{-G} setting or attach a @code{section} attribute to @var{Var}'s

18267

definition. If @var{Var} is common, you must link the application

18268

with a high-enough @option{-G} setting.

18269

18270

The easiest way of satisfying these restrictions is to compile

18271

and link every module with the same @option{-G} option. However,

18272

you may wish to build a library that supports several different

18273

small data limits. You can do this by compiling the library with

18274

the highest supported @option{-G} setting and additionally using

18275

@option{-mno-extern-sdata} to stop the library from making assumptions

18276

about externally-defined data.

18277

18278

@item -mgpopt

18279

@itemx -mno-gpopt

18280

@opindex mgpopt

18281

@opindex mno-gpopt

18282

Use (do not use) GP-relative accesses for symbols that are known to be

18283

in a small data section; see @option{-G}, @option{-mlocal-sdata} and

18284

@option{-mextern-sdata}. @option{-mgpopt} is the default for all

18285

configurations.

18286

18287

@option{-mno-gpopt} is useful for cases where the @code{$gp} register

18288

might not hold the value of @code{_gp}. For example, if the code is

18289

part of a library that might be used in a boot monitor, programs that

18290

call boot monitor routines pass an unknown value in @code{$gp}.

18291

(In such situations, the boot monitor itself is usually compiled

18292

with @option{-G0}.)

18293

18294

@option{-mno-gpopt} implies @option{-mno-local-sdata} and

18295

@option{-mno-extern-sdata}.

18296

18297

@item -membedded-data

18298

@itemx -mno-embedded-data

18299

@opindex membedded-data

18300

@opindex mno-embedded-data

18301

Allocate variables to the read-only data section first if possible, then

18302

next in the small data section if possible, otherwise in data. This gives

18303

slightly slower code than the default, but reduces the amount of RAM required

18304

when executing, and thus may be preferred for some embedded systems.

18305

18306

@item -muninit-const-in-rodata

18307

@itemx -mno-uninit-const-in-rodata

18308

@opindex muninit-const-in-rodata

18309

@opindex mno-uninit-const-in-rodata

18310

Put uninitialized @code{const} variables in the read-only data section.

18311

This option is only meaningful in conjunction with @option{-membedded-data}.

18312

18313

@item -mcode-readable=@var{setting}

18314

@opindex mcode-readable

18315

Specify whether GCC may generate code that reads from executable sections.

18316

There are three possible settings:

18317

18318

@table @gcctabopt

18319

@item -mcode-readable=yes

18320

Instructions may freely access executable sections. This is the

18321

default setting.

18322

18323

@item -mcode-readable=pcrel

18324

MIPS16 PC-relative load instructions can access executable sections,

18325

but other instructions must not do so. This option is useful on 4KSc

18326

and 4KSd processors when the code TLBs have the Read Inhibit bit set.

18327

It is also useful on processors that can be configured to have a dual

18328

instruction/data SRAM interface and that, like the M4K, automatically

18329

redirect PC-relative loads to the instruction RAM.

18330

18331

@item -mcode-readable=no

18332

Instructions must not access executable sections. This option can be

18333

useful on targets that are configured to have a dual instruction/data

18334

SRAM interface but that (unlike the M4K) do not automatically redirect

18335

PC-relative loads to the instruction RAM.

18336

@end table

18337

18338

@item -msplit-addresses

18339

@itemx -mno-split-addresses

18340

@opindex msplit-addresses

18341

@opindex mno-split-addresses

18342

Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler

18343

relocation operators. This option has been superseded by

18344

@option{-mexplicit-relocs} but is retained for backwards compatibility.

18345

18346

@item -mexplicit-relocs

18347

@itemx -mno-explicit-relocs

18348

@opindex mexplicit-relocs

18349

@opindex mno-explicit-relocs

18350

Use (do not use) assembler relocation operators when dealing with symbolic

18351

addresses. The alternative, selected by @option{-mno-explicit-relocs},

18352

is to use assembler macros instead.

18353

18354

@option{-mexplicit-relocs} is the default if GCC was configured

18355

to use an assembler that supports relocation operators.

18356

18357

@item -mcheck-zero-division

18358

@itemx -mno-check-zero-division

18359

@opindex mcheck-zero-division

18360

@opindex mno-check-zero-division

18361

Trap (do not trap) on integer division by zero.

18362

18363

The default is @option{-mcheck-zero-division}.

18364

18365

@item -mdivide-traps

18366

@itemx -mdivide-breaks

18367

@opindex mdivide-traps

18368

@opindex mdivide-breaks

18369

MIPS systems check for division by zero by generating either a

18370

conditional trap or a break instruction. Using traps results in

18371

smaller code, but is only supported on MIPS II and later. Also, some

18372

versions of the Linux kernel have a bug that prevents trap from

18373

generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to

18374

allow conditional traps on architectures that support them and

18375

@option{-mdivide-breaks} to force the use of breaks.

18376

18377

The default is usually @option{-mdivide-traps}, but this can be

18378

overridden at configure time using @option{--with-divide=breaks}.

18379

Divide-by-zero checks can be completely disabled using

18380

@option{-mno-check-zero-division}.

18381

18382

@item -mmemcpy

18383

@itemx -mno-memcpy

18384

@opindex mmemcpy

18385

@opindex mno-memcpy

18386

Force (do not force) the use of @code{memcpy} for non-trivial block

18387

moves. The default is @option{-mno-memcpy}, which allows GCC to inline

18388

most constant-sized copies.

18389

18390

@item -mlong-calls

18391

@itemx -mno-long-calls

18392

@opindex mlong-calls

18393

@opindex mno-long-calls

18394

Disable (do not disable) use of the @code{jal} instruction. Calling

18395

functions using @code{jal} is more efficient but requires the caller

18396

and callee to be in the same 256 megabyte segment.

18397

18398

This option has no effect on abicalls code. The default is

18399

@option{-mno-long-calls}.

18400

18401

@item -mmad

18402

@itemx -mno-mad

18403

@opindex mmad

18404

@opindex mno-mad

18405

Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}

18406

instructions, as provided by the R4650 ISA@.

18407

18408

@item -mimadd

18409

@itemx -mno-imadd

18410

@opindex mimadd

18411

@opindex mno-imadd

18412

Enable (disable) use of the @code{madd} and @code{msub} integer

18413

instructions. The default is @option{-mimadd} on architectures

18414

that support @code{madd} and @code{msub} except for the 74k

18415

architecture where it was found to generate slower code.

18416

18417

@item -mfused-madd

18418

@itemx -mno-fused-madd

18419

@opindex mfused-madd

18420

@opindex mno-fused-madd

18421

Enable (disable) use of the floating-point multiply-accumulate

18422

instructions, when they are available. The default is

18423

@option{-mfused-madd}.

18424

18425

On the R8000 CPU when multiply-accumulate instructions are used,

18426

the intermediate product is calculated to infinite precision

18427

and is not subject to the FCSR Flush to Zero bit. This may be

18428

undesirable in some circumstances. On other processors the result

18429

is numerically identical to the equivalent computation using

18430

separate multiply, add, subtract and negate instructions.

18431

18432

@item -nocpp

18433

@opindex nocpp

18434

Tell the MIPS assembler to not run its preprocessor over user

18435

assembler files (with a @samp{.s} suffix) when assembling them.

18436

18437

@item -mfix-24k

18438

@item -mno-fix-24k

18439

@opindex mfix-24k

18440

@opindex mno-fix-24k

18441

Work around the 24K E48 (lost data on stores during refill) errata.

18442

The workarounds are implemented by the assembler rather than by GCC@.

18443

18444

@item -mfix-r4000

18445

@itemx -mno-fix-r4000

18446

@opindex mfix-r4000

18447

@opindex mno-fix-r4000

18448

Work around certain R4000 CPU errata:

18449

@itemize @minus

18450

@item

18451

A double-word or a variable shift may give an incorrect result if executed

18452

immediately after starting an integer division.

18453

@item

18454

A double-word or a variable shift may give an incorrect result if executed

18455

while an integer multiplication is in progress.

18456

@item

18457

An integer division may give an incorrect result if started in a delay slot

18458

of a taken branch or a jump.

18459

@end itemize

18460

18461

@item -mfix-r4400

18462

@itemx -mno-fix-r4400

18463

@opindex mfix-r4400

18464

@opindex mno-fix-r4400

18465

Work around certain R4400 CPU errata:

18466

@itemize @minus

18467

@item

18468

A double-word or a variable shift may give an incorrect result if executed

18469

immediately after starting an integer division.

18470

@end itemize

18471

18472

@item -mfix-r10000

18473

@itemx -mno-fix-r10000

18474

@opindex mfix-r10000

18475

@opindex mno-fix-r10000

18476

Work around certain R10000 errata:

18477

@itemize @minus

18478

@item

18479

@code{ll}/@code{sc} sequences may not behave atomically on revisions

18480

prior to 3.0. They may deadlock on revisions 2.6 and earlier.

18481

@end itemize

18482

18483

This option can only be used if the target architecture supports

18484

branch-likely instructions. @option{-mfix-r10000} is the default when

18485

@option{-march=r10000} is used; @option{-mno-fix-r10000} is the default

18486

otherwise.

18487

18488

@item -mfix-rm7000

18489

@itemx -mno-fix-rm7000

18490

@opindex mfix-rm7000

18491

Work around the RM7000 @code{dmult}/@code{dmultu} errata. The

18492

workarounds are implemented by the assembler rather than by GCC@.

18493

18494

@item -mfix-vr4120

18495

@itemx -mno-fix-vr4120

18496

@opindex mfix-vr4120

18497

Work around certain VR4120 errata:

18498

@itemize @minus

18499

@item

18500

@code{dmultu} does not always produce the correct result.

18501

@item

18502

@code{div} and @code{ddiv} do not always produce the correct result if one

18503

of the operands is negative.

18504

@end itemize

18505

The workarounds for the division errata rely on special functions in

18506

@file{libgcc.a}. At present, these functions are only provided by

18507

the @code{mips64vr*-elf} configurations.

18508

18509

Other VR4120 errata require a NOP to be inserted between certain pairs of

18510

instructions. These errata are handled by the assembler, not by GCC itself.

18511

18512

@item -mfix-vr4130

18513

@opindex mfix-vr4130

18514

Work around the VR4130 @code{mflo}/@code{mfhi} errata. The

18515

workarounds are implemented by the assembler rather than by GCC,

18516

although GCC avoids using @code{mflo} and @code{mfhi} if the

18517

VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}

18518

instructions are available instead.

18519

18520

@item -mfix-sb1

18521

@itemx -mno-fix-sb1

18522

@opindex mfix-sb1

18523

Work around certain SB-1 CPU core errata.

18524

(This flag currently works around the SB-1 revision 2

18525

``F1'' and ``F2'' floating-point errata.)

18526

18527

@item -mr10k-cache-barrier=@var{setting}

18528

@opindex mr10k-cache-barrier

18529

Specify whether GCC should insert cache barriers to avoid the

18530

side-effects of speculation on R10K processors.

18531

18532

In common with many processors, the R10K tries to predict the outcome

18533

of a conditional branch and speculatively executes instructions from

18534

the ``taken'' branch. It later aborts these instructions if the

18535

predicted outcome is wrong. However, on the R10K, even aborted

18536

instructions can have side effects.

18537

18538

This problem only affects kernel stores and, depending on the system,

18539

kernel loads. As an example, a speculatively-executed store may load

18540

the target memory into cache and mark the cache line as dirty, even if

18541

the store itself is later aborted. If a DMA operation writes to the

18542

same area of memory before the ``dirty'' line is flushed, the cached

18543

data overwrites the DMA-ed data. See the R10K processor manual

18544

for a full description, including other potential problems.

18545

18546

One workaround is to insert cache barrier instructions before every memory

18547

access that might be speculatively executed and that might have side

18548

effects even if aborted. @option{-mr10k-cache-barrier=@var{setting}}

18549

controls GCC's implementation of this workaround. It assumes that

18550

aborted accesses to any byte in the following regions does not have

18551

side effects:

18552

18553

@enumerate

18554

@item

18555

the memory occupied by the current function's stack frame;

18556

18557

@item

18558

the memory occupied by an incoming stack argument;

18559

18560

@item

18561

the memory occupied by an object with a link-time-constant address.

18562

@end enumerate

18563

18564

It is the kernel's responsibility to ensure that speculative

18565

accesses to these regions are indeed safe.

18566

18567

If the input program contains a function declaration such as:

18568

18569

@smallexample

18570

void foo (void);

18571

@end smallexample

18572

18573

then the implementation of @code{foo} must allow @code{j foo} and

18574

@code{jal foo} to be executed speculatively. GCC honors this

18575

restriction for functions it compiles itself. It expects non-GCC

18576

functions (such as hand-written assembly code) to do the same.

18577

18578

The option has three forms:

18579

18580

@table @gcctabopt

18581

@item -mr10k-cache-barrier=load-store

18582

Insert a cache barrier before a load or store that might be

18583

speculatively executed and that might have side effects even

18584

if aborted.

18585

18586

@item -mr10k-cache-barrier=store

18587

Insert a cache barrier before a store that might be speculatively

18588

executed and that might have side effects even if aborted.

18589

18590

@item -mr10k-cache-barrier=none

18591

Disable the insertion of cache barriers. This is the default setting.

18592

@end table

18593

18594

@item -mflush-func=@var{func}

18595

@itemx -mno-flush-func

18596

@opindex mflush-func

18597

Specifies the function to call to flush the I and D caches, or to not

18598

call any such function. If called, the function must take the same

18599

arguments as the common @code{_flush_func}, that is, the address of the

18600

memory range for which the cache is being flushed, the size of the

18601

memory range, and the number 3 (to flush both caches). The default

18602

depends on the target GCC was configured for, but commonly is either

18603

@code{_flush_func} or @code{__cpu_flush}.

18604

18605

@item mbranch-cost=@var{num}

18606

@opindex mbranch-cost

18607

Set the cost of branches to roughly @var{num} ``simple'' instructions.

18608

This cost is only a heuristic and is not guaranteed to produce

18609

consistent results across releases. A zero cost redundantly selects

18610

the default, which is based on the @option{-mtune} setting.

18611

18612

@item -mbranch-likely

18613

@itemx -mno-branch-likely

18614

@opindex mbranch-likely

18615

@opindex mno-branch-likely

18616

Enable or disable use of Branch Likely instructions, regardless of the

18617

default for the selected architecture. By default, Branch Likely

18618

instructions may be generated if they are supported by the selected

18619

architecture. An exception is for the MIPS32 and MIPS64 architectures

18620

and processors that implement those architectures; for those, Branch

18621

Likely instructions are not be generated by default because the MIPS32

18622

and MIPS64 architectures specifically deprecate their use.

18623

18624

@item -mcompact-branches=never

18625

@itemx -mcompact-branches=optimal

18626

@itemx -mcompact-branches=always

18627

@opindex mcompact-branches=never

18628

@opindex mcompact-branches=optimal

18629

@opindex mcompact-branches=always

18630

These options control which form of branches will be generated. The

18631

default is @option{-mcompact-branches=optimal}.

18632

18633

The @option{-mcompact-branches=never} option ensures that compact branch

18634

instructions will never be generated.

18635

18636

The @option{-mcompact-branches=always} option ensures that a compact

18637

branch instruction will be generated if available. If a compact branch

18638

instruction is not available, a delay slot form of the branch will be

18639

used instead.

18640

18641

This option is supported from MIPS Release 6 onwards.

18642

18643

The @option{-mcompact-branches=optimal} option will cause a delay slot

18644

branch to be used if one is available in the current ISA and the delay

18645

slot is successfully filled. If the delay slot is not filled, a compact

18646

branch will be chosen if one is available.

18647

18648

@item -mfp-exceptions

18649

@itemx -mno-fp-exceptions

18650

@opindex mfp-exceptions

18651

Specifies whether FP exceptions are enabled. This affects how

18652

FP instructions are scheduled for some processors.

18653

The default is that FP exceptions are

18654

enabled.

18655

18656

For instance, on the SB-1, if FP exceptions are disabled, and we are emitting

18657

64-bit code, then we can use both FP pipes. Otherwise, we can only use one

18658

FP pipe.

18659

18660

@item -mvr4130-align

18661

@itemx -mno-vr4130-align

18662

@opindex mvr4130-align

18663

The VR4130 pipeline is two-way superscalar, but can only issue two

18664

instructions together if the first one is 8-byte aligned. When this

18665

option is enabled, GCC aligns pairs of instructions that it

18666

thinks should execute in parallel.

18667

18668

This option only has an effect when optimizing for the VR4130.

18669

It normally makes code faster, but at the expense of making it bigger.

18670

It is enabled by default at optimization level @option{-O3}.

18671

18672

@item -msynci

18673

@itemx -mno-synci

18674

@opindex msynci

18675

Enable (disable) generation of @code{synci} instructions on

18676

architectures that support it. The @code{synci} instructions (if

18677

enabled) are generated when @code{__builtin___clear_cache} is

18678

compiled.

18679

18680

This option defaults to @option{-mno-synci}, but the default can be

18681

overridden by configuring GCC with @option{--with-synci}.

18682

18683

When compiling code for single processor systems, it is generally safe

18684

to use @code{synci}. However, on many multi-core (SMP) systems, it

18685

does not invalidate the instruction caches on all cores and may lead

18686

to undefined behavior.

18687

18688

@item -mrelax-pic-calls

18689

@itemx -mno-relax-pic-calls

18690

@opindex mrelax-pic-calls

18691

Try to turn PIC calls that are normally dispatched via register

18692

@code{$25} into direct calls. This is only possible if the linker can

18693

resolve the destination at link time and if the destination is within

18694

range for a direct call.

18695

18696

@option{-mrelax-pic-calls} is the default if GCC was configured to use

18697

an assembler and a linker that support the @code{.reloc} assembly

18698

directive and @option{-mexplicit-relocs} is in effect. With

18699

@option{-mno-explicit-relocs}, this optimization can be performed by the

18700

assembler and the linker alone without help from the compiler.

18701

18702

@item -mmcount-ra-address

18703

@itemx -mno-mcount-ra-address

18704

@opindex mmcount-ra-address

18705

@opindex mno-mcount-ra-address

18706

Emit (do not emit) code that allows @code{_mcount} to modify the

18707

calling function's return address. When enabled, this option extends

18708

the usual @code{_mcount} interface with a new @var{ra-address}

18709

parameter, which has type @code{intptr_t *} and is passed in register

18710

@code{$12}. @code{_mcount} can then modify the return address by

18711

doing both of the following:

18712

@itemize

18713

@item

18714

Returning the new address in register @code{$31}.

18715

@item

18716

Storing the new address in @code{*@var{ra-address}},

18717

if @var{ra-address} is nonnull.

18718

@end itemize

18719

18720

The default is @option{-mno-mcount-ra-address}.

18721

18722

@item -mframe-header-opt

18723

@itemx -mno-frame-header-opt

18724

@opindex mframe-header-opt

18725

Enable (disable) frame header optimization in the o32 ABI. When using the

18726

o32 ABI, calling functions will allocate 16 bytes on the stack for the called

18727

function to write out register arguments. When enabled, this optimization

18728

will suppress the allocation of the frame header if it can be determined that

18729

it is unused.

18730

18731

This optimization is off by default at all optimization levels.

18732

18733

@end table

18734

18735

@node MMIX Options

18736

@subsection MMIX Options

18737

@cindex MMIX Options

18738

18739

These options are defined for the MMIX:

18740

18741

@table @gcctabopt

18742

@item -mlibfuncs

18743

@itemx -mno-libfuncs

18744

@opindex mlibfuncs

18745

@opindex mno-libfuncs

18746

Specify that intrinsic library functions are being compiled, passing all

18747

values in registers, no matter the size.

18748

18749

@item -mepsilon

18750

@itemx -mno-epsilon

18751

@opindex mepsilon

18752

@opindex mno-epsilon

18753

Generate floating-point comparison instructions that compare with respect

18754

to the @code{rE} epsilon register.

18755

18756

@item -mabi=mmixware

18757

@itemx -mabi=gnu

18758

@opindex mabi=mmixware

18759

@opindex mabi=gnu

18760

Generate code that passes function parameters and return values that (in

18761

the called function) are seen as registers @code{$0} and up, as opposed to

18762

the GNU ABI which uses global registers @code{$231} and up.

18763

18764

@item -mzero-extend

18765

@itemx -mno-zero-extend

18766

@opindex mzero-extend

18767

@opindex mno-zero-extend

18768

When reading data from memory in sizes shorter than 64 bits, use (do not

18769

use) zero-extending load instructions by default, rather than

18770

sign-extending ones.

18771

18772

@item -mknuthdiv

18773

@itemx -mno-knuthdiv

18774

@opindex mknuthdiv

18775

@opindex mno-knuthdiv

18776

Make the result of a division yielding a remainder have the same sign as

18777

the divisor. With the default, @option{-mno-knuthdiv}, the sign of the

18778

remainder follows the sign of the dividend. Both methods are

18779

arithmetically valid, the latter being almost exclusively used.

18780

18781

@item -mtoplevel-symbols

18782

@itemx -mno-toplevel-symbols

18783

@opindex mtoplevel-symbols

18784

@opindex mno-toplevel-symbols

18785

Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly

18786

code can be used with the @code{PREFIX} assembly directive.

18787

18788

@item -melf

18789

@opindex melf

18790

Generate an executable in the ELF format, rather than the default

18791

@samp{mmo} format used by the @command{mmix} simulator.

18792

18793

@item -mbranch-predict

18794

@itemx -mno-branch-predict

18795

@opindex mbranch-predict

18796

@opindex mno-branch-predict

18797

Use (do not use) the probable-branch instructions, when static branch

18798

prediction indicates a probable branch.

18799

18800

@item -mbase-addresses

18801

@itemx -mno-base-addresses

18802

@opindex mbase-addresses

18803

@opindex mno-base-addresses

18804

Generate (do not generate) code that uses @emph{base addresses}. Using a

18805

base address automatically generates a request (handled by the assembler

18806

and the linker) for a constant to be set up in a global register. The

18807

register is used for one or more base address requests within the range 0

18808

to 255 from the value held in the register. The generally leads to short

18809

and fast code, but the number of different data items that can be

18810

addressed is limited. This means that a program that uses lots of static

18811

data may require @option{-mno-base-addresses}.

18812

18813

@item -msingle-exit

18814

@itemx -mno-single-exit

18815

@opindex msingle-exit

18816

@opindex mno-single-exit

18817

Force (do not force) generated code to have a single exit point in each

18818

function.

18819

@end table

18820

18821

@node MN10300 Options

18822

@subsection MN10300 Options

18823

@cindex MN10300 options

18824

18825

These @option{-m} options are defined for Matsushita MN10300 architectures:

18826

18827

@table @gcctabopt

18828

@item -mmult-bug

18829

@opindex mmult-bug

18830

Generate code to avoid bugs in the multiply instructions for the MN10300

18831

processors. This is the default.

18832

18833

@item -mno-mult-bug

18834

@opindex mno-mult-bug

18835

Do not generate code to avoid bugs in the multiply instructions for the

18836

MN10300 processors.

18837

18838

@item -mam33

18839

@opindex mam33

18840

Generate code using features specific to the AM33 processor.

18841

18842

@item -mno-am33

18843

@opindex mno-am33

18844

Do not generate code using features specific to the AM33 processor. This

18845

is the default.

18846

18847

@item -mam33-2

18848

@opindex mam33-2

18849

Generate code using features specific to the AM33/2.0 processor.

18850

18851

@item -mam34

18852

@opindex mam34

18853

Generate code using features specific to the AM34 processor.

18854

18855

@item -mtune=@var{cpu-type}

18856

@opindex mtune

18857

Use the timing characteristics of the indicated CPU type when

18858

scheduling instructions. This does not change the targeted processor

18859

type. The CPU type must be one of @samp{mn10300}, @samp{am33},

18860

@samp{am33-2} or @samp{am34}.

18861

18862

@item -mreturn-pointer-on-d0

18863

@opindex mreturn-pointer-on-d0

18864

When generating a function that returns a pointer, return the pointer

18865

in both @code{a0} and @code{d0}. Otherwise, the pointer is returned

18866

only in @code{a0}, and attempts to call such functions without a prototype

18867

result in errors. Note that this option is on by default; use

18868

@option{-mno-return-pointer-on-d0} to disable it.

18869

18870

@item -mno-crt0

18871

@opindex mno-crt0

18872

Do not link in the C run-time initialization object file.

18873

18874

@item -mrelax

18875

@opindex mrelax

18876

Indicate to the linker that it should perform a relaxation optimization pass

18877

to shorten branches, calls and absolute memory addresses. This option only

18878

has an effect when used on the command line for the final link step.

18879

18880

This option makes symbolic debugging impossible.

18881

18882

@item -mliw

18883

@opindex mliw

18884

Allow the compiler to generate @emph{Long Instruction Word}

18885

instructions if the target is the @samp{AM33} or later. This is the

18886

default. This option defines the preprocessor macro @code{__LIW__}.

18887

18888

@item -mnoliw

18889

@opindex mnoliw

18890

Do not allow the compiler to generate @emph{Long Instruction Word}

18891

instructions. This option defines the preprocessor macro

18892

@code{__NO_LIW__}.

18893

18894

@item -msetlb

18895

@opindex msetlb

18896

Allow the compiler to generate the @emph{SETLB} and @emph{Lcc}

18897

instructions if the target is the @samp{AM33} or later. This is the

18898

default. This option defines the preprocessor macro @code{__SETLB__}.

18899

18900

@item -mnosetlb

18901

@opindex mnosetlb

18902

Do not allow the compiler to generate @emph{SETLB} or @emph{Lcc}

18903

instructions. This option defines the preprocessor macro

18904

@code{__NO_SETLB__}.

18905

18906

@end table

18907

18908

@node Moxie Options

18909

@subsection Moxie Options

18910

@cindex Moxie Options

18911

18912

@table @gcctabopt

18913

18914

@item -meb

18915

@opindex meb

18916

Generate big-endian code. This is the default for @samp{moxie-*-*}

18917

configurations.

18918

18919

@item -mel

18920

@opindex mel

18921

Generate little-endian code.

18922

18923

@item -mmul.x

18924

@opindex mmul.x

18925

Generate mul.x and umul.x instructions. This is the default for

18926

@samp{moxiebox-*-*} configurations.

18927

18928

@item -mno-crt0

18929

@opindex mno-crt0

18930

Do not link in the C run-time initialization object file.

18931

18932

@end table

18933

18934

@node MSP430 Options

18935

@subsection MSP430 Options

18936

@cindex MSP430 Options

18937

18938

These options are defined for the MSP430:

18939

18940

@table @gcctabopt

18941

18942

@item -masm-hex

18943

@opindex masm-hex

18944

Force assembly output to always use hex constants. Normally such

18945

constants are signed decimals, but this option is available for

18946

testsuite and/or aesthetic purposes.

18947

18948

@item -mmcu=

18949

@opindex mmcu=

18950

Select the MCU to target. This is used to create a C preprocessor

18951

symbol based upon the MCU name, converted to upper case and pre- and

18952

post-fixed with @samp{__}. This in turn is used by the

18953

@file{msp430.h} header file to select an MCU-specific supplementary

18954

header file.

18955

18956

The option also sets the ISA to use. If the MCU name is one that is

18957

known to only support the 430 ISA then that is selected, otherwise the

18958

430X ISA is selected. A generic MCU name of @samp{msp430} can also be

18959

used to select the 430 ISA. Similarly the generic @samp{msp430x} MCU

18960

name selects the 430X ISA.

18961

18962

In addition an MCU-specific linker script is added to the linker

18963

command line. The script's name is the name of the MCU with

18964

@file{.ld} appended. Thus specifying @option{-mmcu=xxx} on the @command{gcc}

18965

command line defines the C preprocessor symbol @code{__XXX__} and

18966

cause the linker to search for a script called @file{xxx.ld}.

18967

18968

This option is also passed on to the assembler.

18969

18970

@item -mwarn-mcu

18971

@itemx -mno-warn-mcu

18972

@opindex mwarn-mcu

18973

@opindex mno-warn-mcu

18974

This option enables or disables warnings about conflicts between the

18975

MCU name specified by the @option{-mmcu} option and the ISA set by the

18976

@option{-mcpu} option and/or the hardware multiply support set by the

18977

@option{-mhwmult} option. It also toggles warnings about unrecognized

18978

MCU names. This option is on by default.

18979

18980

@item -mcpu=

18981

@opindex mcpu=

18982

Specifies the ISA to use. Accepted values are @samp{msp430},

18983

@samp{msp430x} and @samp{msp430xv2}. This option is deprecated. The

18984

@option{-mmcu=} option should be used to select the ISA.

18985

18986

@item -msim

18987

@opindex msim

18988

Link to the simulator runtime libraries and linker script. Overrides

18989

any scripts that would be selected by the @option{-mmcu=} option.

18990

18991

@item -mlarge

18992

@opindex mlarge

18993

Use large-model addressing (20-bit pointers, 32-bit @code{size_t}).

18994

18995

@item -msmall

18996

@opindex msmall

18997

Use small-model addressing (16-bit pointers, 16-bit @code{size_t}).

18998

18999

@item -mrelax

19000

@opindex mrelax

19001

This option is passed to the assembler and linker, and allows the

19002

linker to perform certain optimizations that cannot be done until

19003

the final link.

19004

19005

@item mhwmult=

19006

@opindex mhwmult=

19007

Describes the type of hardware multiply supported by the target.

19008

Accepted values are @samp{none} for no hardware multiply, @samp{16bit}

19009

for the original 16-bit-only multiply supported by early MCUs.

19010

@samp{32bit} for the 16/32-bit multiply supported by later MCUs and

19011

@samp{f5series} for the 16/32-bit multiply supported by F5-series MCUs.

19012

A value of @samp{auto} can also be given. This tells GCC to deduce

19013

the hardware multiply support based upon the MCU name provided by the

19014

@option{-mmcu} option. If no @option{-mmcu} option is specified or if

19015

the MCU name is not recognized then no hardware multiply support is

19016

assumed. @code{auto} is the default setting.

19017

19018

Hardware multiplies are normally performed by calling a library

19019

routine. This saves space in the generated code. When compiling at

19020

@option{-O3} or higher however the hardware multiplier is invoked

19021

inline. This makes for bigger, but faster code.

19022

19023

The hardware multiply routines disable interrupts whilst running and

19024

restore the previous interrupt state when they finish. This makes

19025

them safe to use inside interrupt handlers as well as in normal code.

19026

19027

@item -minrt

19028

@opindex minrt

19029

Enable the use of a minimum runtime environment - no static

19030

initializers or constructors. This is intended for memory-constrained

19031

devices. The compiler includes special symbols in some objects

19032

that tell the linker and runtime which code fragments are required.

19033

19034

@item -mcode-region=

19035

@itemx -mdata-region=

19036

@opindex mcode-region

19037

@opindex mdata-region

19038

These options tell the compiler where to place functions and data that

19039

do not have one of the @code{lower}, @code{upper}, @code{either} or

19040

@code{section} attributes. Possible values are @code{lower},

19041

@code{upper}, @code{either} or @code{any}. The first three behave

19042

like the corresponding attribute. The fourth possible value -

19043

@code{any} - is the default. It leaves placement entirely up to the

19044

linker script and how it assigns the standard sections

19045

(@code{.text}, @code{.data}, etc) to the memory regions.

19046

19047

@item -msilicon-errata=

19048

@opindex msilicon-errata

19049

This option passes on a request to assembler to enable the fixes for

19050

the named silicon errata.

19051

19052

@item -msilicon-errata-warn=

19053

@opindex msilicon-errata-warn

19054

This option passes on a request to the assembler to enable warning

19055

messages when a silicon errata might need to be applied.

19056

19057

@end table

19058

19059

@node NDS32 Options

19060

@subsection NDS32 Options

19061

@cindex NDS32 Options

19062

19063

These options are defined for NDS32 implementations:

19064

19065

@table @gcctabopt

19066

19067

@item -mbig-endian

19068

@opindex mbig-endian

19069

Generate code in big-endian mode.

19070

19071

@item -mlittle-endian

19072

@opindex mlittle-endian

19073

Generate code in little-endian mode.

19074

19075

@item -mreduced-regs

19076

@opindex mreduced-regs

19077

Use reduced-set registers for register allocation.

19078

19079

@item -mfull-regs

19080

@opindex mfull-regs

19081

Use full-set registers for register allocation.

19082

19083

@item -mcmov

19084

@opindex mcmov

19085

Generate conditional move instructions.

19086

19087

@item -mno-cmov

19088

@opindex mno-cmov

19089

Do not generate conditional move instructions.

19090

19091

@item -mperf-ext

19092

@opindex mperf-ext

19093

Generate performance extension instructions.

19094

19095

@item -mno-perf-ext

19096

@opindex mno-perf-ext

19097

Do not generate performance extension instructions.

19098

19099

@item -mv3push

19100

@opindex mv3push

19101

Generate v3 push25/pop25 instructions.

19102

19103

@item -mno-v3push

19104

@opindex mno-v3push

19105

Do not generate v3 push25/pop25 instructions.

19106

19107

@item -m16-bit

19108

@opindex m16-bit

19109

Generate 16-bit instructions.

19110

19111

@item -mno-16-bit

19112

@opindex mno-16-bit

19113

Do not generate 16-bit instructions.

19114

19115

@item -misr-vector-size=@var{num}

19116

@opindex misr-vector-size

19117

Specify the size of each interrupt vector, which must be 4 or 16.

19118

19119

@item -mcache-block-size=@var{num}

19120

@opindex mcache-block-size

19121

Specify the size of each cache block,

19122

which must be a power of 2 between 4 and 512.

19123

19124

@item -march=@var{arch}

19125

@opindex march

19126

Specify the name of the target architecture.

19127

19128

@item -mcmodel=@var{code-model}

19129

@opindex mcmodel

19130

Set the code model to one of

19131

@table @asis

19132

@item @samp{small}

19133

All the data and read-only data segments must be within 512KB addressing space.

19134

The text segment must be within 16MB addressing space.

19135

@item @samp{medium}

19136

The data segment must be within 512KB while the read-only data segment can be

19137

within 4GB addressing space. The text segment should be still within 16MB

19138

addressing space.

19139

@item @samp{large}

19140

All the text and data segments can be within 4GB addressing space.

19141

@end table

19142

19143

@item -mctor-dtor

19144

@opindex mctor-dtor

19145

Enable constructor/destructor feature.

19146

19147

@item -mrelax

19148

@opindex mrelax

19149

Guide linker to relax instructions.

19150

19151

@end table

19152

19153

@node Nios II Options

19154

@subsection Nios II Options

19155

@cindex Nios II options

19156

@cindex Altera Nios II options

19157

19158

These are the options defined for the Altera Nios II processor.

19159

19160

@table @gcctabopt

19161

19162

@item -G @var{num}

19163

@opindex G

19164

@cindex smaller data references

19165

Put global and static objects less than or equal to @var{num} bytes

19166

into the small data or BSS sections instead of the normal data or BSS

19167

sections. The default value of @var{num} is 8.

19168

19169

@item -mgpopt=@var{option}

19170

@item -mgpopt

19171

@itemx -mno-gpopt

19172

@opindex mgpopt

19173

@opindex mno-gpopt

19174

Generate (do not generate) GP-relative accesses. The following

19175

@var{option} names are recognized:

19176

19177

@table @samp

19178

19179

@item none

19180

Do not generate GP-relative accesses.

19181

19182

@item local

19183

Generate GP-relative accesses for small data objects that are not

19184

external, weak, or uninitialized common symbols.

19185

Also use GP-relative addressing for objects that

19186

have been explicitly placed in a small data section via a @code{section}

19187

attribute.

19188

19189

@item global

19190

As for @samp{local}, but also generate GP-relative accesses for

19191

small data objects that are external, weak, or common. If you use this option,

19192

you must ensure that all parts of your program (including libraries) are

19193

compiled with the same @option{-G} setting.

19194

19195

@item data

19196

Generate GP-relative accesses for all data objects in the program. If you

19197

use this option, the entire data and BSS segments

19198

of your program must fit in 64K of memory and you must use an appropriate

19199

linker script to allocate them within the addressable range of the

19200

global pointer.

19201

19202

@item all

19203

Generate GP-relative addresses for function pointers as well as data

19204

pointers. If you use this option, the entire text, data, and BSS segments

19205

of your program must fit in 64K of memory and you must use an appropriate

19206

linker script to allocate them within the addressable range of the

19207

global pointer.

19208

19209

@end table

19210

19211

@option{-mgpopt} is equivalent to @option{-mgpopt=local}, and

19212

@option{-mno-gpopt} is equivalent to @option{-mgpopt=none}.

19213

19214

The default is @option{-mgpopt} except when @option{-fpic} or

19215

@option{-fPIC} is specified to generate position-independent code.

19216

Note that the Nios II ABI does not permit GP-relative accesses from

19217

shared libraries.

19218

19219

You may need to specify @option{-mno-gpopt} explicitly when building

19220

programs that include large amounts of small data, including large

19221

GOT data sections. In this case, the 16-bit offset for GP-relative

19222

addressing may not be large enough to allow access to the entire

19223

small data section.

19224

19225

@item -mel

19226

@itemx -meb

19227

@opindex mel

19228

@opindex meb

19229

Generate little-endian (default) or big-endian (experimental) code,

19230

respectively.

19231

19232

@item -march=@var{arch}

19233

@opindex march

19234

This specifies the name of the target Nios II architecture. GCC uses this

19235

name to determine what kind of instructions it can emit when generating

19236

assembly code. Permissible names are: @samp{r1}, @samp{r2}.

19237

19238

The preprocessor macro @code{__nios2_arch__} is available to programs,

19239

with value 1 or 2, indicating the targeted ISA level.

19240

19241

@item -mbypass-cache

19242

@itemx -mno-bypass-cache

19243

@opindex mno-bypass-cache

19244

@opindex mbypass-cache

19245

Force all load and store instructions to always bypass cache by

19246

using I/O variants of the instructions. The default is not to

19247

bypass the cache.

19248

19249

@item -mno-cache-volatile

19250

@itemx -mcache-volatile

19251

@opindex mcache-volatile

19252

@opindex mno-cache-volatile

19253

Volatile memory access bypass the cache using the I/O variants of

19254

the load and store instructions. The default is not to bypass the cache.

19255

19256

@item -mno-fast-sw-div

19257

@itemx -mfast-sw-div

19258

@opindex mno-fast-sw-div

19259

@opindex mfast-sw-div

19260

Do not use table-based fast divide for small numbers. The default

19261

is to use the fast divide at @option{-O3} and above.

19262

19263

@item -mno-hw-mul

19264

@itemx -mhw-mul

19265

@itemx -mno-hw-mulx

19266

@itemx -mhw-mulx

19267

@itemx -mno-hw-div

19268

@itemx -mhw-div

19269

@opindex mno-hw-mul

19270

@opindex mhw-mul

19271

@opindex mno-hw-mulx

19272

@opindex mhw-mulx

19273

@opindex mno-hw-div

19274

@opindex mhw-div

19275

Enable or disable emitting @code{mul}, @code{mulx} and @code{div} family of

19276

instructions by the compiler. The default is to emit @code{mul}

19277

and not emit @code{div} and @code{mulx}.

19278

19279

@item -mbmx

19280

@itemx -mno-bmx

19281

@itemx -mcdx

19282

@itemx -mno-cdx

19283

Enable or disable generation of Nios II R2 BMX (bit manipulation) and

19284

CDX (code density) instructions. Enabling these instructions also

19285

requires @option{-march=r2}. Since these instructions are optional

19286

extensions to the R2 architecture, the default is not to emit them.

19287

19288

@item -mcustom-@var{insn}=@var{N}

19289

@itemx -mno-custom-@var{insn}

19290

@opindex mcustom-@var{insn}

19291

@opindex mno-custom-@var{insn}

19292

Each @option{-mcustom-@var{insn}=@var{N}} option enables use of a

19293

custom instruction with encoding @var{N} when generating code that uses

19294

@var{insn}. For example, @option{-mcustom-fadds=253} generates custom

19295

instruction 253 for single-precision floating-point add operations instead

19296

of the default behavior of using a library call.

19297

19298

The following values of @var{insn} are supported. Except as otherwise

19299

noted, floating-point operations are expected to be implemented with

19300

normal IEEE 754 semantics and correspond directly to the C operators or the

19301

equivalent GCC built-in functions (@pxref{Other Builtins}).

19302

19303

Single-precision floating point:

19304

@table @asis

19305

19306

@item @samp{fadds}, @samp{fsubs}, @samp{fdivs}, @samp{fmuls}

19307

Binary arithmetic operations.

19308

19309

@item @samp{fnegs}

19310

Unary negation.

19311

19312

@item @samp{fabss}

19313

Unary absolute value.

19314

19315

@item @samp{fcmpeqs}, @samp{fcmpges}, @samp{fcmpgts}, @samp{fcmples}, @samp{fcmplts}, @samp{fcmpnes}

19316

Comparison operations.

19317

19318

@item @samp{fmins}, @samp{fmaxs}

19319

Floating-point minimum and maximum. These instructions are only

19320

generated if @option{-ffinite-math-only} is specified.

19321

19322

@item @samp{fsqrts}

19323

Unary square root operation.

19324

19325

@item @samp{fcoss}, @samp{fsins}, @samp{ftans}, @samp{fatans}, @samp{fexps}, @samp{flogs}

19326

Floating-point trigonometric and exponential functions. These instructions

19327

are only generated if @option{-funsafe-math-optimizations} is also specified.

19328

19329

@end table

19330

19331

Double-precision floating point:

19332

@table @asis

19333

19334

@item @samp{faddd}, @samp{fsubd}, @samp{fdivd}, @samp{fmuld}

19335

Binary arithmetic operations.

19336

19337

@item @samp{fnegd}

19338

Unary negation.

19339

19340

@item @samp{fabsd}

19341

Unary absolute value.

19342

19343

@item @samp{fcmpeqd}, @samp{fcmpged}, @samp{fcmpgtd}, @samp{fcmpled}, @samp{fcmpltd}, @samp{fcmpned}

19344

Comparison operations.

19345

19346

@item @samp{fmind}, @samp{fmaxd}

19347

Double-precision minimum and maximum. These instructions are only

19348

generated if @option{-ffinite-math-only} is specified.

19349

19350

@item @samp{fsqrtd}

19351

Unary square root operation.

19352

19353

@item @samp{fcosd}, @samp{fsind}, @samp{ftand}, @samp{fatand}, @samp{fexpd}, @samp{flogd}

19354

Double-precision trigonometric and exponential functions. These instructions

19355

are only generated if @option{-funsafe-math-optimizations} is also specified.

19356

19357

@end table

19358

19359

Conversions:

19360

@table @asis

19361

@item @samp{fextsd}

19362

Conversion from single precision to double precision.

19363

19364

@item @samp{ftruncds}

19365

Conversion from double precision to single precision.

19366

19367

@item @samp{fixsi}, @samp{fixsu}, @samp{fixdi}, @samp{fixdu}

19368

Conversion from floating point to signed or unsigned integer types, with

19369

truncation towards zero.

19370

19371

@item @samp{round}

19372

Conversion from single-precision floating point to signed integer,

19373

rounding to the nearest integer and ties away from zero.

19374

This corresponds to the @code{__builtin_lroundf} function when

19375

@option{-fno-math-errno} is used.

19376

19377

@item @samp{floatis}, @samp{floatus}, @samp{floatid}, @samp{floatud}

19378

Conversion from signed or unsigned integer types to floating-point types.

19379

19380

@end table

19381

19382

In addition, all of the following transfer instructions for internal

19383

registers X and Y must be provided to use any of the double-precision

19384

floating-point instructions. Custom instructions taking two

19385

double-precision source operands expect the first operand in the

19386

64-bit register X. The other operand (or only operand of a unary

19387

operation) is given to the custom arithmetic instruction with the

19388

least significant half in source register @var{src1} and the most

19389

significant half in @var{src2}. A custom instruction that returns a

19390

double-precision result returns the most significant 32 bits in the

19391

destination register and the other half in 32-bit register Y.

19392

GCC automatically generates the necessary code sequences to write

19393

register X and/or read register Y when double-precision floating-point

19394

instructions are used.

19395

19396

@table @asis

19397

19398

@item @samp{fwrx}

19399

Write @var{src1} into the least significant half of X and @var{src2} into

19400

the most significant half of X.

19401

19402

@item @samp{fwry}

19403

Write @var{src1} into Y.

19404

19405

@item @samp{frdxhi}, @samp{frdxlo}

19406

Read the most or least (respectively) significant half of X and store it in

19407

@var{dest}.

19408

19409

@item @samp{frdy}

19410

Read the value of Y and store it into @var{dest}.

19411

@end table

19412

19413

Note that you can gain more local control over generation of Nios II custom

19414

instructions by using the @code{target("custom-@var{insn}=@var{N}")}

19415

and @code{target("no-custom-@var{insn}")} function attributes

19416

(@pxref{Function Attributes})

19417

or pragmas (@pxref{Function Specific Option Pragmas}).

19418

19419

@item -mcustom-fpu-cfg=@var{name}

19420

@opindex mcustom-fpu-cfg

19421

19422

This option enables a predefined, named set of custom instruction encodings

19423

(see @option{-mcustom-@var{insn}} above).

19424

Currently, the following sets are defined:

19425

19426

@option{-mcustom-fpu-cfg=60-1} is equivalent to:

19427

@gccoptlist{-mcustom-fmuls=252 @gol

19428

-mcustom-fadds=253 @gol

19429

-mcustom-fsubs=254 @gol

19430

-fsingle-precision-constant}

19431

19432

@option{-mcustom-fpu-cfg=60-2} is equivalent to:

19433

@gccoptlist{-mcustom-fmuls=252 @gol

19434

-mcustom-fadds=253 @gol

19435

-mcustom-fsubs=254 @gol

19436

-mcustom-fdivs=255 @gol

19437

-fsingle-precision-constant}

19438

19439

@option{-mcustom-fpu-cfg=72-3} is equivalent to:

19440

@gccoptlist{-mcustom-floatus=243 @gol

19441

-mcustom-fixsi=244 @gol

19442

-mcustom-floatis=245 @gol

19443

-mcustom-fcmpgts=246 @gol

19444

-mcustom-fcmples=249 @gol

19445

-mcustom-fcmpeqs=250 @gol

19446

-mcustom-fcmpnes=251 @gol

19447

-mcustom-fmuls=252 @gol

19448

-mcustom-fadds=253 @gol

19449

-mcustom-fsubs=254 @gol

19450

-mcustom-fdivs=255 @gol

19451

-fsingle-precision-constant}

19452

19453

Custom instruction assignments given by individual

19454

@option{-mcustom-@var{insn}=} options override those given by

19455

@option{-mcustom-fpu-cfg=}, regardless of the

19456

order of the options on the command line.

19457

19458

Note that you can gain more local control over selection of a FPU

19459

configuration by using the @code{target("custom-fpu-cfg=@var{name}")}

19460

function attribute (@pxref{Function Attributes})

19461

or pragma (@pxref{Function Specific Option Pragmas}).

19462

19463

@end table

19464

19465

These additional @samp{-m} options are available for the Altera Nios II

19466

ELF (bare-metal) target:

19467

19468

@table @gcctabopt

19469

19470

@item -mhal

19471

@opindex mhal

19472

Link with HAL BSP. This suppresses linking with the GCC-provided C runtime

19473

startup and termination code, and is typically used in conjunction with

19474

@option{-msys-crt0=} to specify the location of the alternate startup code

19475

provided by the HAL BSP.

19476

19477

@item -msmallc

19478

@opindex msmallc

19479

Link with a limited version of the C library, @option{-lsmallc}, rather than

19480

Newlib.

19481

19482

@item -msys-crt0=@var{startfile}

19483

@opindex msys-crt0

19484

@var{startfile} is the file name of the startfile (crt0) to use

19485

when linking. This option is only useful in conjunction with @option{-mhal}.

19486

19487

@item -msys-lib=@var{systemlib}

19488

@opindex msys-lib

19489

@var{systemlib} is the library name of the library that provides

19490

low-level system calls required by the C library,

19491

e.g. @code{read} and @code{write}.

19492

This option is typically used to link with a library provided by a HAL BSP.

19493

19494

@end table

19495

19496

@node Nvidia PTX Options

19497

@subsection Nvidia PTX Options

19498

@cindex Nvidia PTX options

19499

@cindex nvptx options

19500

19501

These options are defined for Nvidia PTX:

19502

19503

@table @gcctabopt

19504

19505

@item -m32

19506

@itemx -m64

19507

@opindex m32

19508

@opindex m64

19509

Generate code for 32-bit or 64-bit ABI.

19510

19511

@item -mmainkernel

19512

@opindex mmainkernel

19513

Link in code for a __main kernel. This is for stand-alone instead of

19514

offloading execution.

19515

19516

@item -moptimize

19517

@opindex moptimize

19518

Apply partitioned execution optimizations. This is the default when any

19519

level of optimization is selected.

19520

19521

@end table

19522

19523

@node PDP-11 Options

19524

@subsection PDP-11 Options

19525

@cindex PDP-11 Options

19526

19527

These options are defined for the PDP-11:

19528

19529

@table @gcctabopt

19530

@item -mfpu

19531

@opindex mfpu

19532

Use hardware FPP floating point. This is the default. (FIS floating

19533

point on the PDP-11/40 is not supported.)

19534

19535

@item -msoft-float

19536

@opindex msoft-float

19537

Do not use hardware floating point.

19538

19539

@item -mac0

19540

@opindex mac0

19541

Return floating-point results in ac0 (fr0 in Unix assembler syntax).

19542

19543

@item -mno-ac0

19544

@opindex mno-ac0

19545

Return floating-point results in memory. This is the default.

19546

19547

@item -m40

19548

@opindex m40

19549

Generate code for a PDP-11/40.

19550

19551

@item -m45

19552

@opindex m45

19553

Generate code for a PDP-11/45. This is the default.

19554

19555

@item -m10

19556

@opindex m10

19557

Generate code for a PDP-11/10.

19558

19559

@item -mbcopy-builtin

19560

@opindex mbcopy-builtin

19561

Use inline @code{movmemhi} patterns for copying memory. This is the

19562

default.

19563

19564

@item -mbcopy

19565

@opindex mbcopy

19566

Do not use inline @code{movmemhi} patterns for copying memory.

19567

19568

@item -mint16

19569

@itemx -mno-int32

19570

@opindex mint16

19571

@opindex mno-int32

19572

Use 16-bit @code{int}. This is the default.

19573

19574

@item -mint32

19575

@itemx -mno-int16

19576

@opindex mint32

19577

@opindex mno-int16

19578

Use 32-bit @code{int}.

19579

19580

@item -mfloat64

19581

@itemx -mno-float32

19582

@opindex mfloat64

19583

@opindex mno-float32

19584

Use 64-bit @code{float}. This is the default.

19585

19586

@item -mfloat32

19587

@itemx -mno-float64

19588

@opindex mfloat32

19589

@opindex mno-float64

19590

Use 32-bit @code{float}.

19591

19592

@item -mabshi

19593

@opindex mabshi

19594

Use @code{abshi2} pattern. This is the default.

19595

19596

@item -mno-abshi

19597

@opindex mno-abshi

19598

Do not use @code{abshi2} pattern.

19599

19600

@item -mbranch-expensive

19601

@opindex mbranch-expensive

19602

Pretend that branches are expensive. This is for experimenting with

19603

code generation only.

19604

19605

@item -mbranch-cheap

19606

@opindex mbranch-cheap

19607

Do not pretend that branches are expensive. This is the default.

19608

19609

@item -munix-asm

19610

@opindex munix-asm

19611

Use Unix assembler syntax. This is the default when configured for

19612

@samp{pdp11-*-bsd}.

19613

19614

@item -mdec-asm

19615

@opindex mdec-asm

19616

Use DEC assembler syntax. This is the default when configured for any

19617

PDP-11 target other than @samp{pdp11-*-bsd}.

19618

@end table

19619

19620

@node picoChip Options

19621

@subsection picoChip Options

19622

@cindex picoChip options

19623

19624

These @samp{-m} options are defined for picoChip implementations:

19625

19626

@table @gcctabopt

19627

19628

@item -mae=@var{ae_type}

19629

@opindex mcpu

19630

Set the instruction set, register set, and instruction scheduling

19631

parameters for array element type @var{ae_type}. Supported values

19632

for @var{ae_type} are @samp{ANY}, @samp{MUL}, and @samp{MAC}.

19633

19634

@option{-mae=ANY} selects a completely generic AE type. Code

19635

generated with this option runs on any of the other AE types. The

19636

code is not as efficient as it would be if compiled for a specific

19637

AE type, and some types of operation (e.g., multiplication) do not

19638

work properly on all types of AE.

19639

19640

@option{-mae=MUL} selects a MUL AE type. This is the most useful AE type

19641

for compiled code, and is the default.

19642

19643

@option{-mae=MAC} selects a DSP-style MAC AE. Code compiled with this

19644

option may suffer from poor performance of byte (char) manipulation,

19645

since the DSP AE does not provide hardware support for byte load/stores.

19646

19647

@item -msymbol-as-address

19648

Enable the compiler to directly use a symbol name as an address in a

19649

load/store instruction, without first loading it into a

19650

register. Typically, the use of this option generates larger

19651

programs, which run faster than when the option isn't used. However, the

19652

results vary from program to program, so it is left as a user option,

19653

rather than being permanently enabled.

19654

19655

@item -mno-inefficient-warnings

19656

Disables warnings about the generation of inefficient code. These

19657

warnings can be generated, for example, when compiling code that

19658

performs byte-level memory operations on the MAC AE type. The MAC AE has

19659

no hardware support for byte-level memory operations, so all byte

19660

load/stores must be synthesized from word load/store operations. This is

19661

inefficient and a warning is generated to indicate

19662

that you should rewrite the code to avoid byte operations, or to target

19663

an AE type that has the necessary hardware support. This option disables

19664

these warnings.

19665

19666

@end table

19667

19668

@node PowerPC Options

19669

@subsection PowerPC Options

19670

@cindex PowerPC options

19671

19672

These are listed under @xref{RS/6000 and PowerPC Options}.

19673

19674

@node RL78 Options

19675

@subsection RL78 Options

19676

@cindex RL78 Options

19677

19678

@table @gcctabopt

19679

19680

@item -msim

19681

@opindex msim

19682

Links in additional target libraries to support operation within a

19683

simulator.

19684

19685

@item -mmul=none

19686

@itemx -mmul=g10

19687

@itemx -mmul=g13

19688

@itemx -mmul=g14

19689

@itemx -mmul=rl78

19690

@opindex mmul

19691

Specifies the type of hardware multiplication and division support to

19692

be used. The simplest is @code{none}, which uses software for both

19693

multiplication and division. This is the default. The @code{g13}

19694

value is for the hardware multiply/divide peripheral found on the

19695

RL78/G13 (S2 core) targets. The @code{g14} value selects the use of

19696

the multiplication and division instructions supported by the RL78/G14

19697

(S3 core) parts. The value @code{rl78} is an alias for @code{g14} and

19698

the value @code{mg10} is an alias for @code{none}.

19699

19700

In addition a C preprocessor macro is defined, based upon the setting

19701

of this option. Possible values are: @code{__RL78_MUL_NONE__},

19702

@code{__RL78_MUL_G13__} or @code{__RL78_MUL_G14__}.

19703

19704

@item -mcpu=g10

19705

@itemx -mcpu=g13

19706

@itemx -mcpu=g14

19707

@itemx -mcpu=rl78

19708

@opindex mcpu

19709

Specifies the RL78 core to target. The default is the G14 core, also

19710

known as an S3 core or just RL78. The G13 or S2 core does not have

19711

multiply or divide instructions, instead it uses a hardware peripheral

19712

for these operations. The G10 or S1 core does not have register

19713

banks, so it uses a different calling convention.

19714

19715

If this option is set it also selects the type of hardware multiply

19716

support to use, unless this is overridden by an explicit

19717

@option{-mmul=none} option on the command line. Thus specifying

19718

@option{-mcpu=g13} enables the use of the G13 hardware multiply

19719

peripheral and specifying @option{-mcpu=g10} disables the use of

19720

hardware multiplications altogether.

19721

19722

Note, although the RL78/G14 core is the default target, specifying

19723

@option{-mcpu=g14} or @option{-mcpu=rl78} on the command line does

19724

change the behavior of the toolchain since it also enables G14

19725

hardware multiply support. If these options are not specified on the

19726

command line then software multiplication routines will be used even

19727

though the code targets the RL78 core. This is for backwards

19728

compatibility with older toolchains which did not have hardware

19729

multiply and divide support.

19730

19731

In addition a C preprocessor macro is defined, based upon the setting

19732

of this option. Possible values are: @code{__RL78_G10__},

19733

@code{__RL78_G13__} or @code{__RL78_G14__}.

19734

19735

@item -mg10

19736

@itemx -mg13

19737

@itemx -mg14

19738

@itemx -mrl78

19739

@opindex mg10

19740

@opindex mg13

19741

@opindex mg14

19742

@opindex mrl78

19743

These are aliases for the corresponding @option{-mcpu=} option. They

19744

are provided for backwards compatibility.

19745

19746

@item -mallregs

19747

@opindex mallregs

19748

Allow the compiler to use all of the available registers. By default

19749

registers @code{r24..r31} are reserved for use in interrupt handlers.

19750

With this option enabled these registers can be used in ordinary

19751

functions as well.

19752

19753

@item -m64bit-doubles

19754

@itemx -m32bit-doubles

19755

@opindex m64bit-doubles

19756

@opindex m32bit-doubles

19757

Make the @code{double} data type be 64 bits (@option{-m64bit-doubles})

19758

or 32 bits (@option{-m32bit-doubles}) in size. The default is

19759

@option{-m32bit-doubles}.

19760

19761

@end table

19762

19763

@node RS/6000 and PowerPC Options

19764

@subsection IBM RS/6000 and PowerPC Options

19765

@cindex RS/6000 and PowerPC Options

19766

@cindex IBM RS/6000 and PowerPC Options

19767

19768

These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:

19769

@table @gcctabopt

19770

@item -mpowerpc-gpopt

19771

@itemx -mno-powerpc-gpopt

19772

@itemx -mpowerpc-gfxopt

19773

@itemx -mno-powerpc-gfxopt

19774

@need 800

19775

@itemx -mpowerpc64

19776

@itemx -mno-powerpc64

19777

@itemx -mmfcrf

19778

@itemx -mno-mfcrf

19779

@itemx -mpopcntb

19780

@itemx -mno-popcntb

19781

@itemx -mpopcntd

19782

@itemx -mno-popcntd

19783

@itemx -mfprnd

19784

@itemx -mno-fprnd

19785

@need 800

19786

@itemx -mcmpb

19787

@itemx -mno-cmpb

19788

@itemx -mmfpgpr

19789

@itemx -mno-mfpgpr

19790

@itemx -mhard-dfp

19791

@itemx -mno-hard-dfp

19792

@opindex mpowerpc-gpopt

19793

@opindex mno-powerpc-gpopt

19794

@opindex mpowerpc-gfxopt

19795

@opindex mno-powerpc-gfxopt

19796

@opindex mpowerpc64

19797

@opindex mno-powerpc64

19798

@opindex mmfcrf

19799

@opindex mno-mfcrf

19800

@opindex mpopcntb

19801

@opindex mno-popcntb

19802

@opindex mpopcntd

19803

@opindex mno-popcntd

19804

@opindex mfprnd

19805

@opindex mno-fprnd

19806

@opindex mcmpb

19807

@opindex mno-cmpb

19808

@opindex mmfpgpr

19809

@opindex mno-mfpgpr

19810

@opindex mhard-dfp

19811

@opindex mno-hard-dfp

19812

You use these options to specify which instructions are available on the

19813

processor you are using. The default value of these options is

19814

determined when configuring GCC@. Specifying the

19815

@option{-mcpu=@var{cpu_type}} overrides the specification of these

19816

options. We recommend you use the @option{-mcpu=@var{cpu_type}} option

19817

rather than the options listed above.

19818

19819

Specifying @option{-mpowerpc-gpopt} allows

19820

GCC to use the optional PowerPC architecture instructions in the

19821

General Purpose group, including floating-point square root. Specifying

19822

@option{-mpowerpc-gfxopt} allows GCC to

19823

use the optional PowerPC architecture instructions in the Graphics

19824

group, including floating-point select.

19825

19826

The @option{-mmfcrf} option allows GCC to generate the move from

19827

condition register field instruction implemented on the POWER4

19828

processor and other processors that support the PowerPC V2.01

19829

architecture.

19830

The @option{-mpopcntb} option allows GCC to generate the popcount and

19831

double-precision FP reciprocal estimate instruction implemented on the

19832

POWER5 processor and other processors that support the PowerPC V2.02

19833

architecture.

19834

The @option{-mpopcntd} option allows GCC to generate the popcount

19835

instruction implemented on the POWER7 processor and other processors

19836

that support the PowerPC V2.06 architecture.

19837

The @option{-mfprnd} option allows GCC to generate the FP round to

19838

integer instructions implemented on the POWER5+ processor and other

19839

processors that support the PowerPC V2.03 architecture.

19840

The @option{-mcmpb} option allows GCC to generate the compare bytes

19841

instruction implemented on the POWER6 processor and other processors

19842

that support the PowerPC V2.05 architecture.

19843

The @option{-mmfpgpr} option allows GCC to generate the FP move to/from

19844

general-purpose register instructions implemented on the POWER6X

19845

processor and other processors that support the extended PowerPC V2.05

19846

architecture.

19847

The @option{-mhard-dfp} option allows GCC to generate the decimal

19848

floating-point instructions implemented on some POWER processors.

19849

19850

The @option{-mpowerpc64} option allows GCC to generate the additional

19851

64-bit instructions that are found in the full PowerPC64 architecture

19852

and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to

19853

@option{-mno-powerpc64}.

19854

19855

@item -mcpu=@var{cpu_type}

19856

@opindex mcpu

19857

Set architecture type, register usage, and

19858

instruction scheduling parameters for machine type @var{cpu_type}.

19859

Supported values for @var{cpu_type} are @samp{401}, @samp{403},

19860

@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{464}, @samp{464fp},

19861

@samp{476}, @samp{476fp}, @samp{505}, @samp{601}, @samp{602}, @samp{603},

19862

@samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{630}, @samp{740},

19863

@samp{7400}, @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},

19864

@samp{860}, @samp{970}, @samp{8540}, @samp{a2}, @samp{e300c2},

19865

@samp{e300c3}, @samp{e500mc}, @samp{e500mc64}, @samp{e5500},

19866

@samp{e6500}, @samp{ec603e}, @samp{G3}, @samp{G4}, @samp{G5},

19867

@samp{titan}, @samp{power3}, @samp{power4}, @samp{power5}, @samp{power5+},

19868

@samp{power6}, @samp{power6x}, @samp{power7}, @samp{power8},

19869

@samp{power9}, @samp{powerpc}, @samp{powerpc64}, @samp{powerpc64le},

19870

and @samp{rs64}.

19871

19872

@option{-mcpu=powerpc}, @option{-mcpu=powerpc64}, and

19873

@option{-mcpu=powerpc64le} specify pure 32-bit PowerPC (either

19874

endian), 64-bit big endian PowerPC and 64-bit little endian PowerPC

19875

architecture machine types, with an appropriate, generic processor

19876

model assumed for scheduling purposes.

19877

19878

The other options specify a specific processor. Code generated under

19879

those options runs best on that processor, and may not run at all on

19880

others.

19881

19882

The @option{-mcpu} options automatically enable or disable the

19883

following options:

19884

19885

@gccoptlist{-maltivec -mfprnd -mhard-float -mmfcrf -mmultiple @gol

19886

-mpopcntb -mpopcntd -mpowerpc64 @gol

19887

-mpowerpc-gpopt -mpowerpc-gfxopt -msingle-float -mdouble-float @gol

19888

-msimple-fpu -mstring -mmulhw -mdlmzb -mmfpgpr -mvsx @gol

19889

-mcrypto -mdirect-move -mpower8-fusion -mpower8-vector @gol

19890

-mquad-memory -mquad-memory-atomic -mmodulo -mfloat128 -mfloat128-hardware @gol

19891

-mpower9-fusion -mpower9-vector}

19892

19893

The particular options set for any particular CPU varies between

19894

compiler versions, depending on what setting seems to produce optimal

19895

code for that CPU; it doesn't necessarily reflect the actual hardware's

19896

capabilities. If you wish to set an individual option to a particular

19897

value, you may specify it after the @option{-mcpu} option, like

19898

@option{-mcpu=970 -mno-altivec}.

19899

19900

On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are

19901

not enabled or disabled by the @option{-mcpu} option at present because

19902

AIX does not have full support for these options. You may still

19903

enable or disable them individually if you're sure it'll work in your

19904

environment.

19905

19906

@item -mtune=@var{cpu_type}

19907

@opindex mtune

19908

Set the instruction scheduling parameters for machine type

19909

@var{cpu_type}, but do not set the architecture type or register usage,

19910

as @option{-mcpu=@var{cpu_type}} does. The same

19911

values for @var{cpu_type} are used for @option{-mtune} as for

19912

@option{-mcpu}. If both are specified, the code generated uses the

19913

architecture and registers set by @option{-mcpu}, but the

19914

scheduling parameters set by @option{-mtune}.

19915

19916

@item -mcmodel=small

19917

@opindex mcmodel=small

19918

Generate PowerPC64 code for the small model: The TOC is limited to

19919

64k.

19920

19921

@item -mcmodel=medium

19922

@opindex mcmodel=medium

19923

Generate PowerPC64 code for the medium model: The TOC and other static

19924

data may be up to a total of 4G in size.

19925

19926

@item -mcmodel=large

19927

@opindex mcmodel=large

19928

Generate PowerPC64 code for the large model: The TOC may be up to 4G

19929

in size. Other data and code is only limited by the 64-bit address

19930

space.

19931

19932

@item -maltivec

19933

@itemx -mno-altivec

19934

@opindex maltivec

19935

@opindex mno-altivec

19936

Generate code that uses (does not use) AltiVec instructions, and also

19937

enable the use of built-in functions that allow more direct access to

19938

the AltiVec instruction set. You may also need to set

19939

@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI

19940

enhancements.

19941

19942

When @option{-maltivec} is used, rather than @option{-maltivec=le} or

19943

@option{-maltivec=be}, the element order for AltiVec intrinsics such

19944

as @code{vec_splat}, @code{vec_extract}, and @code{vec_insert}

19945

match array element order corresponding to the endianness of the

19946

target. That is, element zero identifies the leftmost element in a

19947

vector register when targeting a big-endian platform, and identifies

19948

the rightmost element in a vector register when targeting a

19949

little-endian platform.

19950

19951

@item -maltivec=be

19952

@opindex maltivec=be

19953

Generate AltiVec instructions using big-endian element order,

19954

regardless of whether the target is big- or little-endian. This is

19955

the default when targeting a big-endian platform.

19956

19957

The element order is used to interpret element numbers in AltiVec

19958

intrinsics such as @code{vec_splat}, @code{vec_extract}, and

19959

@code{vec_insert}. By default, these match array element order

19960

corresponding to the endianness for the target.

19961

19962

@item -maltivec=le

19963

@opindex maltivec=le

19964

Generate AltiVec instructions using little-endian element order,

19965

regardless of whether the target is big- or little-endian. This is

19966

the default when targeting a little-endian platform. This option is

19967

currently ignored when targeting a big-endian platform.

19968

19969

The element order is used to interpret element numbers in AltiVec

19970

intrinsics such as @code{vec_splat}, @code{vec_extract}, and

19971

@code{vec_insert}. By default, these match array element order

19972

corresponding to the endianness for the target.

19973

19974

@item -mvrsave

19975

@itemx -mno-vrsave

19976

@opindex mvrsave

19977

@opindex mno-vrsave

19978

Generate VRSAVE instructions when generating AltiVec code.

19979

19980

@item -mgen-cell-microcode

19981

@opindex mgen-cell-microcode

19982

Generate Cell microcode instructions.

19983

19984

@item -mwarn-cell-microcode

19985

@opindex mwarn-cell-microcode

19986

Warn when a Cell microcode instruction is emitted. An example

19987

of a Cell microcode instruction is a variable shift.

19988

19989

@item -msecure-plt

19990

@opindex msecure-plt

19991

Generate code that allows @command{ld} and @command{ld.so}

19992

to build executables and shared

19993

libraries with non-executable @code{.plt} and @code{.got} sections.

19994

This is a PowerPC

19995

32-bit SYSV ABI option.

19996

19997

@item -mbss-plt

19998

@opindex mbss-plt

19999

Generate code that uses a BSS @code{.plt} section that @command{ld.so}

20000

fills in, and

20001

requires @code{.plt} and @code{.got}

20002

sections that are both writable and executable.

20003

This is a PowerPC 32-bit SYSV ABI option.

20004

20005

@item -misel

20006

@itemx -mno-isel

20007

@opindex misel

20008

@opindex mno-isel

20009

This switch enables or disables the generation of ISEL instructions.

20010

20011

@item -misel=@var{yes/no}

20012

This switch has been deprecated. Use @option{-misel} and

20013

@option{-mno-isel} instead.

20014

20015

@item -mspe

20016

@itemx -mno-spe

20017

@opindex mspe

20018

@opindex mno-spe

20019

This switch enables or disables the generation of SPE simd

20020

instructions.

20021

20022

@item -mpaired

20023

@itemx -mno-paired

20024

@opindex mpaired

20025

@opindex mno-paired

20026

This switch enables or disables the generation of PAIRED simd

20027

instructions.

20028

20029

@item -mspe=@var{yes/no}

20030

This option has been deprecated. Use @option{-mspe} and

20031

@option{-mno-spe} instead.

20032

20033

@item -mvsx

20034

@itemx -mno-vsx

20035

@opindex mvsx

20036

@opindex mno-vsx

20037

Generate code that uses (does not use) vector/scalar (VSX)

20038

instructions, and also enable the use of built-in functions that allow

20039

more direct access to the VSX instruction set.

20040

20041

@item -mcrypto

20042

@itemx -mno-crypto

20043

@opindex mcrypto

20044

@opindex mno-crypto

20045

Enable the use (disable) of the built-in functions that allow direct

20046

access to the cryptographic instructions that were added in version

20047

2.07 of the PowerPC ISA.

20048

20049

@item -mdirect-move

20050

@itemx -mno-direct-move

20051

@opindex mdirect-move

20052

@opindex mno-direct-move

20053

Generate code that uses (does not use) the instructions to move data

20054

between the general purpose registers and the vector/scalar (VSX)

20055

registers that were added in version 2.07 of the PowerPC ISA.

20056

20057

@item -mpower8-fusion

20058

@itemx -mno-power8-fusion

20059

@opindex mpower8-fusion

20060

@opindex mno-power8-fusion

20061

Generate code that keeps (does not keeps) some integer operations

20062

adjacent so that the instructions can be fused together on power8 and

20063

later processors.

20064

20065

@item -mpower8-vector

20066

@itemx -mno-power8-vector

20067

@opindex mpower8-vector

20068

@opindex mno-power8-vector

20069

Generate code that uses (does not use) the vector and scalar

20070

instructions that were added in version 2.07 of the PowerPC ISA. Also

20071

enable the use of built-in functions that allow more direct access to

20072

the vector instructions.

20073

20074

@item -mquad-memory

20075

@itemx -mno-quad-memory

20076

@opindex mquad-memory

20077

@opindex mno-quad-memory

20078

Generate code that uses (does not use) the non-atomic quad word memory

20079

instructions. The @option{-mquad-memory} option requires use of

20080

64-bit mode.

20081

20082

@item -mquad-memory-atomic

20083

@itemx -mno-quad-memory-atomic

20084

@opindex mquad-memory-atomic

20085

@opindex mno-quad-memory-atomic

20086

Generate code that uses (does not use) the atomic quad word memory

20087

instructions. The @option{-mquad-memory-atomic} option requires use of

20088

64-bit mode.

20089

20090

@item -mupper-regs-df

20091

@itemx -mno-upper-regs-df

20092

@opindex mupper-regs-df

20093

@opindex mno-upper-regs-df

20094

Generate code that uses (does not use) the scalar double precision

20095

instructions that target all 64 registers in the vector/scalar

20096

floating point register set that were added in version 2.06 of the

20097

PowerPC ISA. @option{-mupper-regs-df} is turned on by default if you

20098

use any of the @option{-mcpu=power7}, @option{-mcpu=power8}, or

20099

@option{-mvsx} options.

20100

20101

@item -mupper-regs-sf

20102

@itemx -mno-upper-regs-sf

20103

@opindex mupper-regs-sf

20104

@opindex mno-upper-regs-sf

20105

Generate code that uses (does not use) the scalar single precision

20106

instructions that target all 64 registers in the vector/scalar

20107

floating point register set that were added in version 2.07 of the

20108

PowerPC ISA. @option{-mupper-regs-sf} is turned on by default if you

20109

use either of the @option{-mcpu=power8} or @option{-mpower8-vector}

20110

options.

20111

20112

@item -mupper-regs

20113

@itemx -mno-upper-regs

20114

@opindex mupper-regs

20115

@opindex mno-upper-regs

20116

Generate code that uses (does not use) the scalar

20117

instructions that target all 64 registers in the vector/scalar

20118

floating point register set, depending on the model of the machine.

20119

20120

If the @option{-mno-upper-regs} option is used, it turns off both

20121

@option{-mupper-regs-sf} and @option{-mupper-regs-df} options.

20122

20123

@item -mfloat128

20124

@itemx -mno-float128

20125

@opindex mfloat128

20126

@opindex mno-float128

20127

Enable/disable the @var{__float128} keyword for IEEE 128-bit floating point

20128

and use either software emulation for IEEE 128-bit floating point or

20129

hardware instructions.

20130

20131

The VSX instruction set (@option{-mvsx}, @option{-mcpu=power7}, or

20132

@option{-mcpu=power8}) must be enabled to use the @option{-mfloat128}

20133

option. The @code{-mfloat128} option only works on PowerPC 64-bit

20134

Linux systems.

20135

20136

@item -mfloat128-hardware

20137

@itemx -mno-float128-hardware

20138

@opindex mfloat128-hardware

20139

@opindex mno-float128-hardware

20140

Enable/disable using ISA 3.0 hardware instructions to support the

20141

@var{__float128} data type.

20142

20143

@item -mmodulo

20144

@itemx -mno-modulo

20145

@opindex mmodulo

20146

@opindex mno-module

20147

Generate code that uses (does not use) the ISA 3.0 integer modulo

20148

instructions. The @option{-mmodulo} option is enabled by default

20149

with the @option{-mcpu=power9} option.

20150

20151

@item -mpower9-fusion

20152

@itemx -mno-power9-fusion

20153

@opindex mpower9-fusion

20154

@opindex mno-power9-fusion

20155

Generate code that keeps (does not keeps) some operations adjacent so

20156

that the instructions can be fused together on power9 and later

20157

processors.

20158

20159

@item -mpower9-vector

20160

@itemx -mno-power9-vector

20161

@opindex mpower9-vector

20162

@opindex mno-power9-vector

20163

Generate code that uses (does not use) the vector and scalar

20164

instructions that were added in version 2.07 of the PowerPC ISA. Also

20165

enable the use of built-in functions that allow more direct access to

20166

the vector instructions.

20167

20168

@item -mfloat-gprs=@var{yes/single/double/no}

20169

@itemx -mfloat-gprs

20170

@opindex mfloat-gprs

20171

This switch enables or disables the generation of floating-point

20172

operations on the general-purpose registers for architectures that

20173

support it.

20174

20175

The argument @samp{yes} or @samp{single} enables the use of

20176

single-precision floating-point operations.

20177

20178

The argument @samp{double} enables the use of single and

20179

double-precision floating-point operations.

20180

20181

The argument @samp{no} disables floating-point operations on the

20182

general-purpose registers.

20183

20184

This option is currently only available on the MPC854x.

20185

20186

@item -m32

20187

@itemx -m64

20188

@opindex m32

20189

@opindex m64

20190

Generate code for 32-bit or 64-bit environments of Darwin and SVR4

20191

targets (including GNU/Linux). The 32-bit environment sets int, long

20192

and pointer to 32 bits and generates code that runs on any PowerPC

20193

variant. The 64-bit environment sets int to 32 bits and long and

20194

pointer to 64 bits, and generates code for PowerPC64, as for

20195

@option{-mpowerpc64}.

20196

20197

@item -mfull-toc

20198

@itemx -mno-fp-in-toc

20199

@itemx -mno-sum-in-toc

20200

@itemx -mminimal-toc

20201

@opindex mfull-toc

20202

@opindex mno-fp-in-toc

20203

@opindex mno-sum-in-toc

20204

@opindex mminimal-toc

20205

Modify generation of the TOC (Table Of Contents), which is created for

20206

every executable file. The @option{-mfull-toc} option is selected by

20207

default. In that case, GCC allocates at least one TOC entry for

20208

each unique non-automatic variable reference in your program. GCC

20209

also places floating-point constants in the TOC@. However, only

20210

16,384 entries are available in the TOC@.

20211

20212

If you receive a linker error message that saying you have overflowed

20213

the available TOC space, you can reduce the amount of TOC space used

20214

with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.

20215

@option{-mno-fp-in-toc} prevents GCC from putting floating-point

20216

constants in the TOC and @option{-mno-sum-in-toc} forces GCC to

20217

generate code to calculate the sum of an address and a constant at

20218

run time instead of putting that sum into the TOC@. You may specify one

20219

or both of these options. Each causes GCC to produce very slightly

20220

slower and larger code at the expense of conserving TOC space.

20221

20222

If you still run out of space in the TOC even when you specify both of

20223

these options, specify @option{-mminimal-toc} instead. This option causes

20224

GCC to make only one TOC entry for every file. When you specify this

20225

option, GCC produces code that is slower and larger but which

20226

uses extremely little TOC space. You may wish to use this option

20227

only on files that contain less frequently-executed code.

20228

20229

@item -maix64

20230

@itemx -maix32

20231

@opindex maix64

20232

@opindex maix32

20233

Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit

20234

@code{long} type, and the infrastructure needed to support them.

20235

Specifying @option{-maix64} implies @option{-mpowerpc64},

20236

while @option{-maix32} disables the 64-bit ABI and

20237

implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.

20238

20239

@item -mxl-compat

20240

@itemx -mno-xl-compat

20241

@opindex mxl-compat

20242

@opindex mno-xl-compat

20243

Produce code that conforms more closely to IBM XL compiler semantics

20244

when using AIX-compatible ABI@. Pass floating-point arguments to

20245

prototyped functions beyond the register save area (RSA) on the stack

20246

in addition to argument FPRs. Do not assume that most significant

20247

double in 128-bit long double value is properly rounded when comparing

20248

values and converting to double. Use XL symbol names for long double

20249

support routines.

20250

20251

The AIX calling convention was extended but not initially documented to

20252

handle an obscure K&R C case of calling a function that takes the

20253

address of its arguments with fewer arguments than declared. IBM XL

20254

compilers access floating-point arguments that do not fit in the

20255

RSA from the stack when a subroutine is compiled without

20256

optimization. Because always storing floating-point arguments on the

20257

stack is inefficient and rarely needed, this option is not enabled by

20258

default and only is necessary when calling subroutines compiled by IBM

20259

XL compilers without optimization.

20260

20261

@item -mpe

20262

@opindex mpe

20263

Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an

20264

application written to use message passing with special startup code to

20265

enable the application to run. The system must have PE installed in the

20266

standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file

20267

must be overridden with the @option{-specs=} option to specify the

20268

appropriate directory location. The Parallel Environment does not

20269

support threads, so the @option{-mpe} option and the @option{-pthread}

20270

option are incompatible.

20271

20272

@item -malign-natural

20273

@itemx -malign-power

20274

@opindex malign-natural

20275

@opindex malign-power

20276

On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option

20277

@option{-malign-natural} overrides the ABI-defined alignment of larger

20278

types, such as floating-point doubles, on their natural size-based boundary.

20279

The option @option{-malign-power} instructs GCC to follow the ABI-specified

20280

alignment rules. GCC defaults to the standard alignment defined in the ABI@.

20281

20282

On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}

20283

is not supported.

20284

20285

@item -msoft-float

20286

@itemx -mhard-float

20287

@opindex msoft-float

20288

@opindex mhard-float

20289

Generate code that does not use (uses) the floating-point register set.

20290

Software floating-point emulation is provided if you use the

20291

@option{-msoft-float} option, and pass the option to GCC when linking.

20292

20293

@item -msingle-float

20294

@itemx -mdouble-float

20295

@opindex msingle-float

20296

@opindex mdouble-float

20297

Generate code for single- or double-precision floating-point operations.

20298

@option{-mdouble-float} implies @option{-msingle-float}.

20299

20300

@item -msimple-fpu

20301

@opindex msimple-fpu

20302

Do not generate @code{sqrt} and @code{div} instructions for hardware

20303

floating-point unit.

20304

20305

@item -mfpu=@var{name}

20306

@opindex mfpu

20307

Specify type of floating-point unit. Valid values for @var{name} are

20308

@samp{sp_lite} (equivalent to @option{-msingle-float -msimple-fpu}),

20309

@samp{dp_lite} (equivalent to @option{-mdouble-float -msimple-fpu}),

20310

@samp{sp_full} (equivalent to @option{-msingle-float}),

20311

and @samp{dp_full} (equivalent to @option{-mdouble-float}).

20312

20313

@item -mxilinx-fpu

20314

@opindex mxilinx-fpu

20315

Perform optimizations for the floating-point unit on Xilinx PPC 405/440.

20316

20317

@item -mmultiple

20318

@itemx -mno-multiple

20319

@opindex mmultiple

20320

@opindex mno-multiple

20321

Generate code that uses (does not use) the load multiple word

20322

instructions and the store multiple word instructions. These

20323

instructions are generated by default on POWER systems, and not

20324

generated on PowerPC systems. Do not use @option{-mmultiple} on little-endian

20325

PowerPC systems, since those instructions do not work when the

20326

processor is in little-endian mode. The exceptions are PPC740 and

20327

PPC750 which permit these instructions in little-endian mode.

20328

20329

@item -mstring

20330

@itemx -mno-string

20331

@opindex mstring

20332

@opindex mno-string

20333

Generate code that uses (does not use) the load string instructions

20334

and the store string word instructions to save multiple registers and

20335

do small block moves. These instructions are generated by default on

20336

POWER systems, and not generated on PowerPC systems. Do not use

20337

@option{-mstring} on little-endian PowerPC systems, since those

20338

instructions do not work when the processor is in little-endian mode.

20339

The exceptions are PPC740 and PPC750 which permit these instructions

20340

in little-endian mode.

20341

20342

@item -mupdate

20343

@itemx -mno-update

20344

@opindex mupdate

20345

@opindex mno-update

20346

Generate code that uses (does not use) the load or store instructions

20347

that update the base register to the address of the calculated memory

20348

location. These instructions are generated by default. If you use

20349

@option{-mno-update}, there is a small window between the time that the

20350

stack pointer is updated and the address of the previous frame is

20351

stored, which means code that walks the stack frame across interrupts or

20352

signals may get corrupted data.

20353

20354

@item -mavoid-indexed-addresses

20355

@itemx -mno-avoid-indexed-addresses

20356

@opindex mavoid-indexed-addresses

20357

@opindex mno-avoid-indexed-addresses

20358

Generate code that tries to avoid (not avoid) the use of indexed load

20359

or store instructions. These instructions can incur a performance

20360

penalty on Power6 processors in certain situations, such as when

20361

stepping through large arrays that cross a 16M boundary. This option

20362

is enabled by default when targeting Power6 and disabled otherwise.

20363

20364

@item -mfused-madd

20365

@itemx -mno-fused-madd

20366

@opindex mfused-madd

20367

@opindex mno-fused-madd

20368

Generate code that uses (does not use) the floating-point multiply and

20369

accumulate instructions. These instructions are generated by default

20370

if hardware floating point is used. The machine-dependent

20371

@option{-mfused-madd} option is now mapped to the machine-independent

20372

@option{-ffp-contract=fast} option, and @option{-mno-fused-madd} is

20373

mapped to @option{-ffp-contract=off}.

20374

20375

@item -mmulhw

20376

@itemx -mno-mulhw

20377

@opindex mmulhw

20378

@opindex mno-mulhw

20379

Generate code that uses (does not use) the half-word multiply and

20380

multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.

20381

These instructions are generated by default when targeting those

20382

processors.

20383

20384

@item -mdlmzb

20385

@itemx -mno-dlmzb

20386

@opindex mdlmzb

20387

@opindex mno-dlmzb

20388

Generate code that uses (does not use) the string-search @samp{dlmzb}

20389

instruction on the IBM 405, 440, 464 and 476 processors. This instruction is

20390

generated by default when targeting those processors.

20391

20392

@item -mno-bit-align

20393

@itemx -mbit-align

20394

@opindex mno-bit-align

20395

@opindex mbit-align

20396

On System V.4 and embedded PowerPC systems do not (do) force structures

20397

and unions that contain bit-fields to be aligned to the base type of the

20398

bit-field.

20399

20400

For example, by default a structure containing nothing but 8

20401

@code{unsigned} bit-fields of length 1 is aligned to a 4-byte

20402

boundary and has a size of 4 bytes. By using @option{-mno-bit-align},

20403

the structure is aligned to a 1-byte boundary and is 1 byte in

20404

size.

20405

20406

@item -mno-strict-align

20407

@itemx -mstrict-align

20408

@opindex mno-strict-align

20409

@opindex mstrict-align

20410

On System V.4 and embedded PowerPC systems do not (do) assume that

20411

unaligned memory references are handled by the system.

20412

20413

@item -mrelocatable

20414

@itemx -mno-relocatable

20415

@opindex mrelocatable

20416

@opindex mno-relocatable

20417

Generate code that allows (does not allow) a static executable to be

20418

relocated to a different address at run time. A simple embedded

20419

PowerPC system loader should relocate the entire contents of

20420

@code{.got2} and 4-byte locations listed in the @code{.fixup} section,

20421

a table of 32-bit addresses generated by this option. For this to

20422

work, all objects linked together must be compiled with

20423

@option{-mrelocatable} or @option{-mrelocatable-lib}.

20424

@option{-mrelocatable} code aligns the stack to an 8-byte boundary.

20425

20426

@item -mrelocatable-lib

20427

@itemx -mno-relocatable-lib

20428

@opindex mrelocatable-lib

20429

@opindex mno-relocatable-lib

20430

Like @option{-mrelocatable}, @option{-mrelocatable-lib} generates a

20431

@code{.fixup} section to allow static executables to be relocated at

20432

run time, but @option{-mrelocatable-lib} does not use the smaller stack

20433

alignment of @option{-mrelocatable}. Objects compiled with

20434

@option{-mrelocatable-lib} may be linked with objects compiled with

20435

any combination of the @option{-mrelocatable} options.

20436

20437

@item -mno-toc

20438

@itemx -mtoc

20439

@opindex mno-toc

20440

@opindex mtoc

20441

On System V.4 and embedded PowerPC systems do not (do) assume that

20442

register 2 contains a pointer to a global area pointing to the addresses

20443

used in the program.

20444

20445

@item -mlittle

20446

@itemx -mlittle-endian

20447

@opindex mlittle

20448

@opindex mlittle-endian

20449

On System V.4 and embedded PowerPC systems compile code for the

20450

processor in little-endian mode. The @option{-mlittle-endian} option is

20451

the same as @option{-mlittle}.

20452

20453

@item -mbig

20454

@itemx -mbig-endian

20455

@opindex mbig

20456

@opindex mbig-endian

20457

On System V.4 and embedded PowerPC systems compile code for the

20458

processor in big-endian mode. The @option{-mbig-endian} option is

20459

the same as @option{-mbig}.

20460

20461

@item -mdynamic-no-pic

20462

@opindex mdynamic-no-pic

20463

On Darwin and Mac OS X systems, compile code so that it is not

20464

relocatable, but that its external references are relocatable. The

20465

resulting code is suitable for applications, but not shared

20466

libraries.

20467

20468

@item -msingle-pic-base

20469

@opindex msingle-pic-base

20470

Treat the register used for PIC addressing as read-only, rather than

20471

loading it in the prologue for each function. The runtime system is

20472

responsible for initializing this register with an appropriate value

20473

before execution begins.

20474

20475

@item -mprioritize-restricted-insns=@var{priority}

20476

@opindex mprioritize-restricted-insns

20477

This option controls the priority that is assigned to

20478

dispatch-slot restricted instructions during the second scheduling

20479

pass. The argument @var{priority} takes the value @samp{0}, @samp{1},

20480

or @samp{2} to assign no, highest, or second-highest (respectively)

20481

priority to dispatch-slot restricted

20482

instructions.

20483

20484

@item -msched-costly-dep=@var{dependence_type}

20485

@opindex msched-costly-dep

20486

This option controls which dependences are considered costly

20487

by the target during instruction scheduling. The argument

20488

@var{dependence_type} takes one of the following values:

20489

20490

@table @asis

20491

@item @samp{no}

20492

No dependence is costly.

20493

20494

@item @samp{all}

20495

All dependences are costly.

20496

20497

@item @samp{true_store_to_load}

20498

A true dependence from store to load is costly.

20499

20500

@item @samp{store_to_load}

20501

Any dependence from store to load is costly.

20502

20503

@item @var{number}

20504

Any dependence for which the latency is greater than or equal to

20505

@var{number} is costly.

20506

@end table

20507

20508

@item -minsert-sched-nops=@var{scheme}

20509

@opindex minsert-sched-nops

20510

This option controls which NOP insertion scheme is used during

20511

the second scheduling pass. The argument @var{scheme} takes one of the

20512

following values:

20513

20514

@table @asis

20515

@item @samp{no}

20516

Don't insert NOPs.

20517

20518

@item @samp{pad}

20519

Pad with NOPs any dispatch group that has vacant issue slots,

20520

according to the scheduler's grouping.

20521

20522

@item @samp{regroup_exact}

20523

Insert NOPs to force costly dependent insns into

20524

separate groups. Insert exactly as many NOPs as needed to force an insn

20525

to a new group, according to the estimated processor grouping.

20526

20527

@item @var{number}

20528

Insert NOPs to force costly dependent insns into

20529

separate groups. Insert @var{number} NOPs to force an insn to a new group.

20530

@end table

20531

20532

@item -mcall-sysv

20533

@opindex mcall-sysv

20534

On System V.4 and embedded PowerPC systems compile code using calling

20535

conventions that adhere to the March 1995 draft of the System V

20536

Application Binary Interface, PowerPC processor supplement. This is the

20537

default unless you configured GCC using @samp{powerpc-*-eabiaix}.

20538

20539

@item -mcall-sysv-eabi

20540

@itemx -mcall-eabi

20541

@opindex mcall-sysv-eabi

20542

@opindex mcall-eabi

20543

Specify both @option{-mcall-sysv} and @option{-meabi} options.

20544

20545

@item -mcall-sysv-noeabi

20546

@opindex mcall-sysv-noeabi

20547

Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.

20548

20549

@item -mcall-aixdesc

20550

@opindex m

20551

On System V.4 and embedded PowerPC systems compile code for the AIX

20552

operating system.

20553

20554

@item -mcall-linux

20555

@opindex mcall-linux

20556

On System V.4 and embedded PowerPC systems compile code for the

20557

Linux-based GNU system.

20558

20559

@item -mcall-freebsd

20560

@opindex mcall-freebsd

20561

On System V.4 and embedded PowerPC systems compile code for the

20562

FreeBSD operating system.

20563

20564

@item -mcall-netbsd

20565

@opindex mcall-netbsd

20566

On System V.4 and embedded PowerPC systems compile code for the

20567

NetBSD operating system.

20568

20569

@item -mcall-openbsd

20570

@opindex mcall-netbsd

20571

On System V.4 and embedded PowerPC systems compile code for the

20572

OpenBSD operating system.

20573

20574

@item -maix-struct-return

20575

@opindex maix-struct-return

20576

Return all structures in memory (as specified by the AIX ABI)@.

20577

20578

@item -msvr4-struct-return

20579

@opindex msvr4-struct-return

20580

Return structures smaller than 8 bytes in registers (as specified by the

20581

SVR4 ABI)@.

20582

20583

@item -mabi=@var{abi-type}

20584

@opindex mabi

20585

Extend the current ABI with a particular extension, or remove such extension.

20586

Valid values are @samp{altivec}, @samp{no-altivec}, @samp{spe},

20587

@samp{no-spe}, @samp{ibmlongdouble}, @samp{ieeelongdouble},

20588

@samp{elfv1}, @samp{elfv2}@.

20589

20590

@item -mabi=spe

20591

@opindex mabi=spe

20592

Extend the current ABI with SPE ABI extensions. This does not change

20593

the default ABI, instead it adds the SPE ABI extensions to the current

20594

ABI@.

20595

20596

@item -mabi=no-spe

20597

@opindex mabi=no-spe

20598

Disable Book-E SPE ABI extensions for the current ABI@.

20599

20600

@item -mabi=ibmlongdouble

20601

@opindex mabi=ibmlongdouble

20602

Change the current ABI to use IBM extended-precision long double.

20603

This is a PowerPC 32-bit SYSV ABI option.

20604

20605

@item -mabi=ieeelongdouble

20606

@opindex mabi=ieeelongdouble

20607

Change the current ABI to use IEEE extended-precision long double.

20608

This is a PowerPC 32-bit Linux ABI option.

20609

20610

@item -mabi=elfv1

20611

@opindex mabi=elfv1

20612

Change the current ABI to use the ELFv1 ABI.

20613

This is the default ABI for big-endian PowerPC 64-bit Linux.

20614

Overriding the default ABI requires special system support and is

20615

likely to fail in spectacular ways.

20616

20617

@item -mabi=elfv2

20618

@opindex mabi=elfv2

20619

Change the current ABI to use the ELFv2 ABI.

20620

This is the default ABI for little-endian PowerPC 64-bit Linux.

20621

Overriding the default ABI requires special system support and is

20622

likely to fail in spectacular ways.

20623

20624

@item -mprototype

20625

@itemx -mno-prototype

20626

@opindex mprototype

20627

@opindex mno-prototype

20628

On System V.4 and embedded PowerPC systems assume that all calls to

20629

variable argument functions are properly prototyped. Otherwise, the

20630

compiler must insert an instruction before every non-prototyped call to

20631

set or clear bit 6 of the condition code register (@code{CR}) to

20632

indicate whether floating-point values are passed in the floating-point

20633

registers in case the function takes variable arguments. With

20634

@option{-mprototype}, only calls to prototyped variable argument functions

20635

set or clear the bit.

20636

20637

@item -msim

20638

@opindex msim

20639

On embedded PowerPC systems, assume that the startup module is called

20640

@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and

20641

@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}

20642

configurations.

20643

20644

@item -mmvme

20645

@opindex mmvme

20646

On embedded PowerPC systems, assume that the startup module is called

20647

@file{crt0.o} and the standard C libraries are @file{libmvme.a} and

20648

@file{libc.a}.

20649

20650

@item -mads

20651

@opindex mads

20652

On embedded PowerPC systems, assume that the startup module is called

20653

@file{crt0.o} and the standard C libraries are @file{libads.a} and

20654

@file{libc.a}.

20655

20656

@item -myellowknife

20657

@opindex myellowknife

20658

On embedded PowerPC systems, assume that the startup module is called

20659

@file{crt0.o} and the standard C libraries are @file{libyk.a} and

20660

@file{libc.a}.

20661

20662

@item -mvxworks

20663

@opindex mvxworks

20664

On System V.4 and embedded PowerPC systems, specify that you are

20665

compiling for a VxWorks system.

20666

20667

@item -memb

20668

@opindex memb

20669

On embedded PowerPC systems, set the @code{PPC_EMB} bit in the ELF flags

20670

header to indicate that @samp{eabi} extended relocations are used.

20671

20672

@item -meabi

20673

@itemx -mno-eabi

20674

@opindex meabi

20675

@opindex mno-eabi

20676

On System V.4 and embedded PowerPC systems do (do not) adhere to the

20677

Embedded Applications Binary Interface (EABI), which is a set of

20678

modifications to the System V.4 specifications. Selecting @option{-meabi}

20679

means that the stack is aligned to an 8-byte boundary, a function

20680

@code{__eabi} is called from @code{main} to set up the EABI

20681

environment, and the @option{-msdata} option can use both @code{r2} and

20682

@code{r13} to point to two separate small data areas. Selecting

20683

@option{-mno-eabi} means that the stack is aligned to a 16-byte boundary,

20684

no EABI initialization function is called from @code{main}, and the

20685

@option{-msdata} option only uses @code{r13} to point to a single

20686

small data area. The @option{-meabi} option is on by default if you

20687

configured GCC using one of the @samp{powerpc*-*-eabi*} options.

20688

20689

@item -msdata=eabi

20690

@opindex msdata=eabi

20691

On System V.4 and embedded PowerPC systems, put small initialized

20692

@code{const} global and static data in the @code{.sdata2} section, which

20693

is pointed to by register @code{r2}. Put small initialized

20694

non-@code{const} global and static data in the @code{.sdata} section,

20695

which is pointed to by register @code{r13}. Put small uninitialized

20696

global and static data in the @code{.sbss} section, which is adjacent to

20697

the @code{.sdata} section. The @option{-msdata=eabi} option is

20698

incompatible with the @option{-mrelocatable} option. The

20699

@option{-msdata=eabi} option also sets the @option{-memb} option.

20700

20701

@item -msdata=sysv

20702

@opindex msdata=sysv

20703

On System V.4 and embedded PowerPC systems, put small global and static

20704

data in the @code{.sdata} section, which is pointed to by register

20705

@code{r13}. Put small uninitialized global and static data in the

20706

@code{.sbss} section, which is adjacent to the @code{.sdata} section.

20707

The @option{-msdata=sysv} option is incompatible with the

20708

@option{-mrelocatable} option.

20709

20710

@item -msdata=default

20711

@itemx -msdata

20712

@opindex msdata=default

20713

@opindex msdata

20714

On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,

20715

compile code the same as @option{-msdata=eabi}, otherwise compile code the

20716

same as @option{-msdata=sysv}.

20717

20718

@item -msdata=data

20719

@opindex msdata=data

20720

On System V.4 and embedded PowerPC systems, put small global

20721

data in the @code{.sdata} section. Put small uninitialized global

20722

data in the @code{.sbss} section. Do not use register @code{r13}

20723

to address small data however. This is the default behavior unless

20724

other @option{-msdata} options are used.

20725

20726

@item -msdata=none

20727

@itemx -mno-sdata

20728

@opindex msdata=none

20729

@opindex mno-sdata

20730

On embedded PowerPC systems, put all initialized global and static data

20731

in the @code{.data} section, and all uninitialized data in the

20732

@code{.bss} section.

20733

20734

@item -mblock-move-inline-limit=@var{num}

20735

@opindex mblock-move-inline-limit

20736

Inline all block moves (such as calls to @code{memcpy} or structure

20737

copies) less than or equal to @var{num} bytes. The minimum value for

20738

@var{num} is 32 bytes on 32-bit targets and 64 bytes on 64-bit

20739

targets. The default value is target-specific.

20740

20741

@item -G @var{num}

20742

@opindex G

20743

@cindex smaller data references (PowerPC)

20744

@cindex .sdata/.sdata2 references (PowerPC)

20745

On embedded PowerPC systems, put global and static items less than or

20746

equal to @var{num} bytes into the small data or BSS sections instead of

20747

the normal data or BSS section. By default, @var{num} is 8. The

20748

@option{-G @var{num}} switch is also passed to the linker.

20749

All modules should be compiled with the same @option{-G @var{num}} value.

20750

20751

@item -mregnames

20752

@itemx -mno-regnames

20753

@opindex mregnames

20754

@opindex mno-regnames

20755

On System V.4 and embedded PowerPC systems do (do not) emit register

20756

names in the assembly language output using symbolic forms.

20757

20758

@item -mlongcall

20759

@itemx -mno-longcall

20760

@opindex mlongcall

20761

@opindex mno-longcall

20762

By default assume that all calls are far away so that a longer and more

20763

expensive calling sequence is required. This is required for calls

20764

farther than 32 megabytes (33,554,432 bytes) from the current location.

20765

A short call is generated if the compiler knows

20766

the call cannot be that far away. This setting can be overridden by

20767

the @code{shortcall} function attribute, or by @code{#pragma

20768

longcall(0)}.

20769

20770

Some linkers are capable of detecting out-of-range calls and generating

20771

glue code on the fly. On these systems, long calls are unnecessary and

20772

generate slower code. As of this writing, the AIX linker can do this,

20773

as can the GNU linker for PowerPC/64. It is planned to add this feature

20774

to the GNU linker for 32-bit PowerPC systems as well.

20775

20776

On Darwin/PPC systems, @code{#pragma longcall} generates @code{jbsr

20777

callee, L42}, plus a @dfn{branch island} (glue code). The two target

20778

addresses represent the callee and the branch island. The

20779

Darwin/PPC linker prefers the first address and generates a @code{bl

20780

callee} if the PPC @code{bl} instruction reaches the callee directly;

20781

otherwise, the linker generates @code{bl L42} to call the branch

20782

island. The branch island is appended to the body of the

20783

calling function; it computes the full 32-bit address of the callee

20784

and jumps to it.

20785

20786

On Mach-O (Darwin) systems, this option directs the compiler emit to

20787

the glue for every direct call, and the Darwin linker decides whether

20788

to use or discard it.

20789

20790

In the future, GCC may ignore all longcall specifications

20791

when the linker is known to generate glue.

20792

20793

@item -mtls-markers

20794

@itemx -mno-tls-markers

20795

@opindex mtls-markers

20796

@opindex mno-tls-markers

20797

Mark (do not mark) calls to @code{__tls_get_addr} with a relocation

20798

specifying the function argument. The relocation allows the linker to

20799

reliably associate function call with argument setup instructions for

20800

TLS optimization, which in turn allows GCC to better schedule the

20801

sequence.

20802

20803

@item -pthread

20804

@opindex pthread

20805

Adds support for multithreading with the @dfn{pthreads} library.

20806

This option sets flags for both the preprocessor and linker.

20807

20808

@item -mrecip

20809

@itemx -mno-recip

20810

@opindex mrecip

20811

This option enables use of the reciprocal estimate and

20812

reciprocal square root estimate instructions with additional

20813

Newton-Raphson steps to increase precision instead of doing a divide or

20814

square root and divide for floating-point arguments. You should use

20815

the @option{-ffast-math} option when using @option{-mrecip} (or at

20816

least @option{-funsafe-math-optimizations},

20817

@option{-ffinite-math-only}, @option{-freciprocal-math} and

20818

@option{-fno-trapping-math}). Note that while the throughput of the

20819

sequence is generally higher than the throughput of the non-reciprocal

20820

instruction, the precision of the sequence can be decreased by up to 2

20821

ulp (i.e.@: the inverse of 1.0 equals 0.99999994) for reciprocal square

20822

roots.

20823

20824

@item -mrecip=@var{opt}

20825

@opindex mrecip=opt

20826

This option controls which reciprocal estimate instructions

20827

may be used. @var{opt} is a comma-separated list of options, which may

20828

be preceded by a @code{!} to invert the option:

20829

20830

@table @samp

20831

20832

@item all

20833

Enable all estimate instructions.

20834

20835

@item default

20836

Enable the default instructions, equivalent to @option{-mrecip}.

20837

20838

@item none

20839

Disable all estimate instructions, equivalent to @option{-mno-recip}.

20840

20841

@item div

20842

Enable the reciprocal approximation instructions for both

20843

single and double precision.

20844

20845

@item divf

20846

Enable the single-precision reciprocal approximation instructions.

20847

20848

@item divd

20849

Enable the double-precision reciprocal approximation instructions.

20850

20851

@item rsqrt

20852

Enable the reciprocal square root approximation instructions for both

20853

single and double precision.

20854

20855

@item rsqrtf

20856

Enable the single-precision reciprocal square root approximation instructions.

20857

20858

@item rsqrtd

20859

Enable the double-precision reciprocal square root approximation instructions.

20860

20861

@end table

20862

20863

So, for example, @option{-mrecip=all,!rsqrtd} enables

20864

all of the reciprocal estimate instructions, except for the

20865

@code{FRSQRTE}, @code{XSRSQRTEDP}, and @code{XVRSQRTEDP} instructions

20866

which handle the double-precision reciprocal square root calculations.

20867

20868

@item -mrecip-precision

20869

@itemx -mno-recip-precision

20870

@opindex mrecip-precision

20871

Assume (do not assume) that the reciprocal estimate instructions

20872

provide higher-precision estimates than is mandated by the PowerPC

20873

ABI. Selecting @option{-mcpu=power6}, @option{-mcpu=power7} or

20874

@option{-mcpu=power8} automatically selects @option{-mrecip-precision}.

20875

The double-precision square root estimate instructions are not generated by

20876

default on low-precision machines, since they do not provide an

20877

estimate that converges after three steps.

20878

20879

@item -mveclibabi=@var{type}

20880

@opindex mveclibabi

20881

Specifies the ABI type to use for vectorizing intrinsics using an

20882

external library. The only type supported at present is @samp{mass},

20883

which specifies to use IBM's Mathematical Acceleration Subsystem

20884

(MASS) libraries for vectorizing intrinsics using external libraries.

20885

GCC currently emits calls to @code{acosd2}, @code{acosf4},

20886

@code{acoshd2}, @code{acoshf4}, @code{asind2}, @code{asinf4},

20887

@code{asinhd2}, @code{asinhf4}, @code{atan2d2}, @code{atan2f4},

20888

@code{atand2}, @code{atanf4}, @code{atanhd2}, @code{atanhf4},

20889

@code{cbrtd2}, @code{cbrtf4}, @code{cosd2}, @code{cosf4},

20890

@code{coshd2}, @code{coshf4}, @code{erfcd2}, @code{erfcf4},

20891

@code{erfd2}, @code{erff4}, @code{exp2d2}, @code{exp2f4},

20892

@code{expd2}, @code{expf4}, @code{expm1d2}, @code{expm1f4},

20893

@code{hypotd2}, @code{hypotf4}, @code{lgammad2}, @code{lgammaf4},

20894

@code{log10d2}, @code{log10f4}, @code{log1pd2}, @code{log1pf4},

20895

@code{log2d2}, @code{log2f4}, @code{logd2}, @code{logf4},

20896

@code{powd2}, @code{powf4}, @code{sind2}, @code{sinf4}, @code{sinhd2},

20897

@code{sinhf4}, @code{sqrtd2}, @code{sqrtf4}, @code{tand2},

20898

@code{tanf4}, @code{tanhd2}, and @code{tanhf4} when generating code

20899

for power7. Both @option{-ftree-vectorize} and

20900

@option{-funsafe-math-optimizations} must also be enabled. The MASS

20901

libraries must be specified at link time.

20902

20903

@item -mfriz

20904

@itemx -mno-friz

20905

@opindex mfriz

20906

Generate (do not generate) the @code{friz} instruction when the

20907

@option{-funsafe-math-optimizations} option is used to optimize

20908

rounding of floating-point values to 64-bit integer and back to floating

20909

point. The @code{friz} instruction does not return the same value if

20910

the floating-point number is too large to fit in an integer.

20911

20912

@item -mpointers-to-nested-functions

20913

@itemx -mno-pointers-to-nested-functions

20914

@opindex mpointers-to-nested-functions

20915

Generate (do not generate) code to load up the static chain register

20916

(@code{r11}) when calling through a pointer on AIX and 64-bit Linux

20917

systems where a function pointer points to a 3-word descriptor giving

20918

the function address, TOC value to be loaded in register @code{r2}, and

20919

static chain value to be loaded in register @code{r11}. The

20920

@option{-mpointers-to-nested-functions} is on by default. You cannot

20921

call through pointers to nested functions or pointers

20922

to functions compiled in other languages that use the static chain if

20923

you use @option{-mno-pointers-to-nested-functions}.

20924

20925

@item -msave-toc-indirect

20926

@itemx -mno-save-toc-indirect

20927

@opindex msave-toc-indirect

20928

Generate (do not generate) code to save the TOC value in the reserved

20929

stack location in the function prologue if the function calls through

20930

a pointer on AIX and 64-bit Linux systems. If the TOC value is not

20931

saved in the prologue, it is saved just before the call through the

20932

pointer. The @option{-mno-save-toc-indirect} option is the default.

20933

20934

@item -mcompat-align-parm

20935

@itemx -mno-compat-align-parm

20936

@opindex mcompat-align-parm

20937

Generate (do not generate) code to pass structure parameters with a

20938

maximum alignment of 64 bits, for compatibility with older versions

20939

of GCC.

20940

20941

Older versions of GCC (prior to 4.9.0) incorrectly did not align a

20942

structure parameter on a 128-bit boundary when that structure contained

20943

a member requiring 128-bit alignment. This is corrected in more

20944

recent versions of GCC. This option may be used to generate code

20945

that is compatible with functions compiled with older versions of

20946

GCC.

20947

20948

The @option{-mno-compat-align-parm} option is the default.

20949

@end table

20950

20951

@node RX Options

20952

@subsection RX Options

20953

@cindex RX Options

20954

20955

These command-line options are defined for RX targets:

20956

20957

@table @gcctabopt

20958

@item -m64bit-doubles

20959

@itemx -m32bit-doubles

20960

@opindex m64bit-doubles

20961

@opindex m32bit-doubles

20962

Make the @code{double} data type be 64 bits (@option{-m64bit-doubles})

20963

or 32 bits (@option{-m32bit-doubles}) in size. The default is

20964

@option{-m32bit-doubles}. @emph{Note} RX floating-point hardware only

20965

works on 32-bit values, which is why the default is

20966

@option{-m32bit-doubles}.

20967

20968

@item -fpu

20969

@itemx -nofpu

20970

@opindex fpu

20971

@opindex nofpu

20972

Enables (@option{-fpu}) or disables (@option{-nofpu}) the use of RX

20973

floating-point hardware. The default is enabled for the RX600

20974

series and disabled for the RX200 series.

20975

20976

Floating-point instructions are only generated for 32-bit floating-point

20977

values, however, so the FPU hardware is not used for doubles if the

20978

@option{-m64bit-doubles} option is used.

20979

20980

@emph{Note} If the @option{-fpu} option is enabled then

20981

@option{-funsafe-math-optimizations} is also enabled automatically.

20982

This is because the RX FPU instructions are themselves unsafe.

20983

20984

@item -mcpu=@var{name}

20985

@opindex mcpu

20986

Selects the type of RX CPU to be targeted. Currently three types are

20987

supported, the generic @samp{RX600} and @samp{RX200} series hardware and

20988

the specific @samp{RX610} CPU. The default is @samp{RX600}.

20989

20990

The only difference between @samp{RX600} and @samp{RX610} is that the

20991

@samp{RX610} does not support the @code{MVTIPL} instruction.

20992

20993

The @samp{RX200} series does not have a hardware floating-point unit

20994

and so @option{-nofpu} is enabled by default when this type is

20995

selected.

20996

20997

@item -mbig-endian-data

20998

@itemx -mlittle-endian-data

20999

@opindex mbig-endian-data

21000

@opindex mlittle-endian-data

21001

Store data (but not code) in the big-endian format. The default is

21002

@option{-mlittle-endian-data}, i.e.@: to store data in the little-endian

21003

format.

21004

21005

@item -msmall-data-limit=@var{N}

21006

@opindex msmall-data-limit

21007

Specifies the maximum size in bytes of global and static variables

21008

which can be placed into the small data area. Using the small data

21009

area can lead to smaller and faster code, but the size of area is

21010

limited and it is up to the programmer to ensure that the area does

21011

not overflow. Also when the small data area is used one of the RX's

21012

registers (usually @code{r13}) is reserved for use pointing to this

21013

area, so it is no longer available for use by the compiler. This

21014

could result in slower and/or larger code if variables are pushed onto

21015

the stack instead of being held in this register.

21016

21017

Note, common variables (variables that have not been initialized) and

21018

constants are not placed into the small data area as they are assigned

21019

to other sections in the output executable.

21020

21021

The default value is zero, which disables this feature. Note, this

21022

feature is not enabled by default with higher optimization levels

21023

(@option{-O2} etc) because of the potentially detrimental effects of

21024

reserving a register. It is up to the programmer to experiment and

21025

discover whether this feature is of benefit to their program. See the

21026

description of the @option{-mpid} option for a description of how the

21027

actual register to hold the small data area pointer is chosen.

21028

21029

@item -msim

21030

@itemx -mno-sim

21031

@opindex msim

21032

@opindex mno-sim

21033

Use the simulator runtime. The default is to use the libgloss

21034

board-specific runtime.

21035

21036

@item -mas100-syntax

21037

@itemx -mno-as100-syntax

21038

@opindex mas100-syntax

21039

@opindex mno-as100-syntax

21040

When generating assembler output use a syntax that is compatible with

21041

Renesas's AS100 assembler. This syntax can also be handled by the GAS

21042

assembler, but it has some restrictions so it is not generated by default.

21043

21044

@item -mmax-constant-size=@var{N}

21045

@opindex mmax-constant-size

21046

Specifies the maximum size, in bytes, of a constant that can be used as

21047

an operand in a RX instruction. Although the RX instruction set does

21048

allow constants of up to 4 bytes in length to be used in instructions,

21049

a longer value equates to a longer instruction. Thus in some

21050

circumstances it can be beneficial to restrict the size of constants

21051

that are used in instructions. Constants that are too big are instead

21052

placed into a constant pool and referenced via register indirection.

21053

21054

The value @var{N} can be between 0 and 4. A value of 0 (the default)

21055

or 4 means that constants of any size are allowed.

21056

21057

@item -mrelax

21058

@opindex mrelax

21059

Enable linker relaxation. Linker relaxation is a process whereby the

21060

linker attempts to reduce the size of a program by finding shorter

21061

versions of various instructions. Disabled by default.

21062

21063

@item -mint-register=@var{N}

21064

@opindex mint-register

21065

Specify the number of registers to reserve for fast interrupt handler

21066

functions. The value @var{N} can be between 0 and 4. A value of 1

21067

means that register @code{r13} is reserved for the exclusive use

21068

of fast interrupt handlers. A value of 2 reserves @code{r13} and

21069

@code{r12}. A value of 3 reserves @code{r13}, @code{r12} and

21070

@code{r11}, and a value of 4 reserves @code{r13} through @code{r10}.

21071

A value of 0, the default, does not reserve any registers.

21072

21073

@item -msave-acc-in-interrupts

21074

@opindex msave-acc-in-interrupts

21075

Specifies that interrupt handler functions should preserve the

21076

accumulator register. This is only necessary if normal code might use

21077

the accumulator register, for example because it performs 64-bit

21078

multiplications. The default is to ignore the accumulator as this

21079

makes the interrupt handlers faster.

21080

21081

@item -mpid

21082

@itemx -mno-pid

21083

@opindex mpid

21084

@opindex mno-pid

21085

Enables the generation of position independent data. When enabled any

21086

access to constant data is done via an offset from a base address

21087

held in a register. This allows the location of constant data to be

21088

determined at run time without requiring the executable to be

21089

relocated, which is a benefit to embedded applications with tight

21090

memory constraints. Data that can be modified is not affected by this

21091

option.

21092

21093

Note, using this feature reserves a register, usually @code{r13}, for

21094

the constant data base address. This can result in slower and/or

21095

larger code, especially in complicated functions.

21096

21097

The actual register chosen to hold the constant data base address

21098

depends upon whether the @option{-msmall-data-limit} and/or the

21099

@option{-mint-register} command-line options are enabled. Starting

21100

with register @code{r13} and proceeding downwards, registers are

21101

allocated first to satisfy the requirements of @option{-mint-register},

21102

then @option{-mpid} and finally @option{-msmall-data-limit}. Thus it

21103

is possible for the small data area register to be @code{r8} if both

21104

@option{-mint-register=4} and @option{-mpid} are specified on the

21105

command line.

21106

21107

By default this feature is not enabled. The default can be restored

21108

via the @option{-mno-pid} command-line option.

21109

21110

@item -mno-warn-multiple-fast-interrupts

21111

@itemx -mwarn-multiple-fast-interrupts

21112

@opindex mno-warn-multiple-fast-interrupts

21113

@opindex mwarn-multiple-fast-interrupts

21114

Prevents GCC from issuing a warning message if it finds more than one

21115

fast interrupt handler when it is compiling a file. The default is to

21116

issue a warning for each extra fast interrupt handler found, as the RX

21117

only supports one such interrupt.

21118

21119

@item -mallow-string-insns

21120

@itemx -mno-allow-string-insns

21121

@opindex mallow-string-insns

21122

@opindex mno-allow-string-insns

21123

Enables or disables the use of the string manipulation instructions

21124

@code{SMOVF}, @code{SCMPU}, @code{SMOVB}, @code{SMOVU}, @code{SUNTIL}

21125

@code{SWHILE} and also the @code{RMPA} instruction. These

21126

instructions may prefetch data, which is not safe to do if accessing

21127

an I/O register. (See section 12.2.7 of the RX62N Group User's Manual

21128

for more information).

21129

21130

The default is to allow these instructions, but it is not possible for

21131

GCC to reliably detect all circumstances where a string instruction

21132

might be used to access an I/O register, so their use cannot be

21133

disabled automatically. Instead it is reliant upon the programmer to

21134

use the @option{-mno-allow-string-insns} option if their program

21135

accesses I/O space.

21136

21137

When the instructions are enabled GCC defines the C preprocessor

21138

symbol @code{__RX_ALLOW_STRING_INSNS__}, otherwise it defines the

21139

symbol @code{__RX_DISALLOW_STRING_INSNS__}.

21140

21141

@item -mjsr

21142

@itemx -mno-jsr

21143

@opindex mjsr

21144

@opindex mno-jsr

21145

Use only (or not only) @code{JSR} instructions to access functions.

21146

This option can be used when code size exceeds the range of @code{BSR}

21147

instructions. Note that @option{-mno-jsr} does not mean to not use

21148

@code{JSR} but instead means that any type of branch may be used.

21149

@end table

21150

21151

@emph{Note:} The generic GCC command-line option @option{-ffixed-@var{reg}}

21152

has special significance to the RX port when used with the

21153

@code{interrupt} function attribute. This attribute indicates a

21154

function intended to process fast interrupts. GCC ensures

21155

that it only uses the registers @code{r10}, @code{r11}, @code{r12}

21156

and/or @code{r13} and only provided that the normal use of the

21157

corresponding registers have been restricted via the

21158

@option{-ffixed-@var{reg}} or @option{-mint-register} command-line

21159

options.

21160

21161

@node S/390 and zSeries Options

21162

@subsection S/390 and zSeries Options

21163

@cindex S/390 and zSeries Options

21164

21165

These are the @samp{-m} options defined for the S/390 and zSeries architecture.

21166

21167

@table @gcctabopt

21168

@item -mhard-float

21169

@itemx -msoft-float

21170

@opindex mhard-float

21171

@opindex msoft-float

21172

Use (do not use) the hardware floating-point instructions and registers

21173

for floating-point operations. When @option{-msoft-float} is specified,

21174

functions in @file{libgcc.a} are used to perform floating-point

21175

operations. When @option{-mhard-float} is specified, the compiler

21176

generates IEEE floating-point instructions. This is the default.

21177

21178

@item -mhard-dfp

21179

@itemx -mno-hard-dfp

21180

@opindex mhard-dfp

21181

@opindex mno-hard-dfp

21182

Use (do not use) the hardware decimal-floating-point instructions for

21183

decimal-floating-point operations. When @option{-mno-hard-dfp} is

21184

specified, functions in @file{libgcc.a} are used to perform

21185

decimal-floating-point operations. When @option{-mhard-dfp} is

21186

specified, the compiler generates decimal-floating-point hardware

21187

instructions. This is the default for @option{-march=z9-ec} or higher.

21188

21189

@item -mlong-double-64

21190

@itemx -mlong-double-128

21191

@opindex mlong-double-64

21192

@opindex mlong-double-128

21193

These switches control the size of @code{long double} type. A size

21194

of 64 bits makes the @code{long double} type equivalent to the @code{double}

21195

type. This is the default.

21196

21197

@item -mbackchain

21198

@itemx -mno-backchain

21199

@opindex mbackchain

21200

@opindex mno-backchain

21201

Store (do not store) the address of the caller's frame as backchain pointer

21202

into the callee's stack frame.

21203

A backchain may be needed to allow debugging using tools that do not understand

21204

DWARF call frame information.

21205

When @option{-mno-packed-stack} is in effect, the backchain pointer is stored

21206

at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,

21207

the backchain is placed into the topmost word of the 96/160 byte register

21208

save area.

21209

21210

In general, code compiled with @option{-mbackchain} is call-compatible with

21211

code compiled with @option{-mmo-backchain}; however, use of the backchain

21212

for debugging purposes usually requires that the whole binary is built with

21213

@option{-mbackchain}. Note that the combination of @option{-mbackchain},

21214

@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order

21215

to build a linux kernel use @option{-msoft-float}.

21216

21217

The default is to not maintain the backchain.

21218

21219

@item -mpacked-stack

21220

@itemx -mno-packed-stack

21221

@opindex mpacked-stack

21222

@opindex mno-packed-stack

21223

Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is

21224

specified, the compiler uses the all fields of the 96/160 byte register save

21225

area only for their default purpose; unused fields still take up stack space.

21226

When @option{-mpacked-stack} is specified, register save slots are densely

21227

packed at the top of the register save area; unused space is reused for other

21228

purposes, allowing for more efficient use of the available stack space.

21229

However, when @option{-mbackchain} is also in effect, the topmost word of

21230

the save area is always used to store the backchain, and the return address

21231

register is always saved two words below the backchain.

21232

21233

As long as the stack frame backchain is not used, code generated with

21234

@option{-mpacked-stack} is call-compatible with code generated with

21235

@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for

21236

S/390 or zSeries generated code that uses the stack frame backchain at run

21237

time, not just for debugging purposes. Such code is not call-compatible

21238

with code compiled with @option{-mpacked-stack}. Also, note that the

21239

combination of @option{-mbackchain},

21240

@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order

21241

to build a linux kernel use @option{-msoft-float}.

21242

21243

The default is to not use the packed stack layout.

21244

21245

@item -msmall-exec

21246

@itemx -mno-small-exec

21247

@opindex msmall-exec

21248

@opindex mno-small-exec

21249

Generate (or do not generate) code using the @code{bras} instruction

21250

to do subroutine calls.

21251

This only works reliably if the total executable size does not

21252

exceed 64k. The default is to use the @code{basr} instruction instead,

21253

which does not have this limitation.

21254

21255

@item -m64

21256

@itemx -m31

21257

@opindex m64

21258

@opindex m31

21259

When @option{-m31} is specified, generate code compliant to the

21260

GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate

21261

code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in

21262

particular to generate 64-bit instructions. For the @samp{s390}

21263

targets, the default is @option{-m31}, while the @samp{s390x}

21264

targets default to @option{-m64}.

21265

21266

@item -mzarch

21267

@itemx -mesa

21268

@opindex mzarch

21269

@opindex mesa

21270

When @option{-mzarch} is specified, generate code using the

21271

instructions available on z/Architecture.

21272

When @option{-mesa} is specified, generate code using the

21273

instructions available on ESA/390. Note that @option{-mesa} is

21274

not possible with @option{-m64}.

21275

When generating code compliant to the GNU/Linux for S/390 ABI,

21276

the default is @option{-mesa}. When generating code compliant

21277

to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.

21278

21279

@item -mhtm

21280

@itemx -mno-htm

21281

@opindex mhtm

21282

@opindex mno-htm

21283

The @option{-mhtm} option enables a set of builtins making use of

21284

instructions available with the transactional execution facility

21285

introduced with the IBM zEnterprise EC12 machine generation

21286

@ref{S/390 System z Built-in Functions}.

21287

@option{-mhtm} is enabled by default when using @option{-march=zEC12}.

21288

21289

@item -mvx

21290

@itemx -mno-vx

21291

@opindex mvx

21292

@opindex mno-vx

21293

When @option{-mvx} is specified, generate code using the instructions

21294

available with the vector extension facility introduced with the IBM

21295

z13 machine generation.

21296

This option changes the ABI for some vector type values with regard to

21297

alignment and calling conventions. In case vector type values are

21298

being used in an ABI-relevant context a GAS @samp{.gnu_attribute}

21299

command will be added to mark the resulting binary with the ABI used.

21300

@option{-mvx} is enabled by default when using @option{-march=z13}.

21301

21302

@item -mzvector

21303

@itemx -mno-zvector

21304

@opindex mzvector

21305

@opindex mno-zvector

21306

The @option{-mzvector} option enables vector language extensions and

21307

builtins using instructions available with the vector extension

21308

facility introduced with the IBM z13 machine generation.

21309

This option adds support for @samp{vector} to be used as a keyword to

21310

define vector type variables and arguments. @samp{vector} is only

21311

available when GNU extensions are enabled. It will not be expanded

21312

when requesting strict standard compliance e.g. with @option{-std=c99}.

21313

In addition to the GCC low-level builtins @option{-mzvector} enables

21314

a set of builtins added for compatibility with AltiVec-style

21315

implementations like Power and Cell. In order to make use of these

21316

builtins the header file @file{vecintrin.h} needs to be included.

21317

@option{-mzvector} is disabled by default.

21318

21319

@item -mmvcle

21320

@itemx -mno-mvcle

21321

@opindex mmvcle

21322

@opindex mno-mvcle

21323

Generate (or do not generate) code using the @code{mvcle} instruction

21324

to perform block moves. When @option{-mno-mvcle} is specified,

21325

use a @code{mvc} loop instead. This is the default unless optimizing for

21326

size.

21327

21328

@item -mdebug

21329

@itemx -mno-debug

21330

@opindex mdebug

21331

@opindex mno-debug

21332

Print (or do not print) additional debug information when compiling.

21333

The default is to not print debug information.

21334

21335

@item -march=@var{cpu-type}

21336

@opindex march

21337

Generate code that runs on @var{cpu-type}, which is the name of a

21338

system representing a certain processor type. Possible values for

21339

@var{cpu-type} are @samp{z900}, @samp{z990}, @samp{z9-109},

21340

@samp{z9-ec}, @samp{z10}, @samp{z196}, @samp{zEC12}, and @samp{z13}.

21341

The default is @option{-march=z900}. @samp{g5} and @samp{g6} are

21342

deprecated and will be removed with future releases.

21343

21344

@item -mtune=@var{cpu-type}

21345

@opindex mtune

21346

Tune to @var{cpu-type} everything applicable about the generated code,

21347

except for the ABI and the set of available instructions.

21348

The list of @var{cpu-type} values is the same as for @option{-march}.

21349

The default is the value used for @option{-march}.

21350

21351

@item -mtpf-trace

21352

@itemx -mno-tpf-trace

21353

@opindex mtpf-trace

21354

@opindex mno-tpf-trace

21355

Generate code that adds (does not add) in TPF OS specific branches to trace

21356

routines in the operating system. This option is off by default, even

21357

when compiling for the TPF OS@.

21358

21359

@item -mfused-madd

21360

@itemx -mno-fused-madd

21361

@opindex mfused-madd

21362

@opindex mno-fused-madd

21363

Generate code that uses (does not use) the floating-point multiply and

21364

accumulate instructions. These instructions are generated by default if

21365

hardware floating point is used.

21366

21367

@item -mwarn-framesize=@var{framesize}

21368

@opindex mwarn-framesize

21369

Emit a warning if the current function exceeds the given frame size. Because

21370

this is a compile-time check it doesn't need to be a real problem when the program

21371

runs. It is intended to identify functions that most probably cause

21372

a stack overflow. It is useful to be used in an environment with limited stack

21373

size e.g.@: the linux kernel.

21374

21375

@item -mwarn-dynamicstack

21376

@opindex mwarn-dynamicstack

21377

Emit a warning if the function calls @code{alloca} or uses dynamically-sized

21378

arrays. This is generally a bad idea with a limited stack size.

21379

21380

@item -mstack-guard=@var{stack-guard}

21381

@itemx -mstack-size=@var{stack-size}

21382

@opindex mstack-guard

21383

@opindex mstack-size

21384

If these options are provided the S/390 back end emits additional instructions in

21385

the function prologue that trigger a trap if the stack size is @var{stack-guard}

21386

bytes above the @var{stack-size} (remember that the stack on S/390 grows downward).

21387

If the @var{stack-guard} option is omitted the smallest power of 2 larger than

21388

the frame size of the compiled function is chosen.

21389

These options are intended to be used to help debugging stack overflow problems.

21390

The additionally emitted code causes only little overhead and hence can also be

21391

used in production-like systems without greater performance degradation. The given

21392

values have to be exact powers of 2 and @var{stack-size} has to be greater than

21393

@var{stack-guard} without exceeding 64k.

21394

In order to be efficient the extra code makes the assumption that the stack starts

21395

at an address aligned to the value given by @var{stack-size}.

21396

The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.

21397

21398

@item -mhotpatch=@var{pre-halfwords},@var{post-halfwords}

21399

@opindex mhotpatch

21400

If the hotpatch option is enabled, a ``hot-patching'' function

21401

prologue is generated for all functions in the compilation unit.

21402

The funtion label is prepended with the given number of two-byte

21403

NOP instructions (@var{pre-halfwords}, maximum 1000000). After

21404

the label, 2 * @var{post-halfwords} bytes are appended, using the

21405

largest NOP like instructions the architecture allows (maximum

21406

1000000).

21407

21408

If both arguments are zero, hotpatching is disabled.

21409

21410

This option can be overridden for individual functions with the

21411

@code{hotpatch} attribute.

21412

@end table

21413

21414

@node Score Options

21415

@subsection Score Options

21416

@cindex Score Options

21417

21418

These options are defined for Score implementations:

21419

21420

@table @gcctabopt

21421

@item -meb

21422

@opindex meb

21423

Compile code for big-endian mode. This is the default.

21424

21425

@item -mel

21426

@opindex mel

21427

Compile code for little-endian mode.

21428

21429

@item -mnhwloop

21430

@opindex mnhwloop

21431

Disable generation of @code{bcnz} instructions.

21432

21433

@item -muls

21434

@opindex muls

21435

Enable generation of unaligned load and store instructions.

21436

21437

@item -mmac

21438

@opindex mmac

21439

Enable the use of multiply-accumulate instructions. Disabled by default.

21440

21441

@item -mscore5

21442

@opindex mscore5

21443

Specify the SCORE5 as the target architecture.

21444

21445

@item -mscore5u

21446

@opindex mscore5u

21447

Specify the SCORE5U of the target architecture.

21448

21449

@item -mscore7

21450

@opindex mscore7

21451

Specify the SCORE7 as the target architecture. This is the default.

21452

21453

@item -mscore7d

21454

@opindex mscore7d

21455

Specify the SCORE7D as the target architecture.

21456

@end table

21457

21458

@node SH Options

21459

@subsection SH Options

21460

21461

These @samp{-m} options are defined for the SH implementations:

21462

21463

@table @gcctabopt

21464

@item -m1

21465

@opindex m1

21466

Generate code for the SH1.

21467

21468

@item -m2

21469

@opindex m2

21470

Generate code for the SH2.

21471

21472

@item -m2e

21473

Generate code for the SH2e.

21474

21475

@item -m2a-nofpu

21476

@opindex m2a-nofpu

21477

Generate code for the SH2a without FPU, or for a SH2a-FPU in such a way

21478

that the floating-point unit is not used.

21479

21480

@item -m2a-single-only

21481

@opindex m2a-single-only

21482

Generate code for the SH2a-FPU, in such a way that no double-precision

21483

floating-point operations are used.

21484

21485

@item -m2a-single

21486

@opindex m2a-single

21487

Generate code for the SH2a-FPU assuming the floating-point unit is in

21488

single-precision mode by default.

21489

21490

@item -m2a

21491

@opindex m2a

21492

Generate code for the SH2a-FPU assuming the floating-point unit is in

21493

double-precision mode by default.

21494

21495

@item -m3

21496

@opindex m3

21497

Generate code for the SH3.

21498

21499

@item -m3e

21500

@opindex m3e

21501

Generate code for the SH3e.

21502

21503

@item -m4-nofpu

21504

@opindex m4-nofpu

21505

Generate code for the SH4 without a floating-point unit.

21506

21507

@item -m4-single-only

21508

@opindex m4-single-only

21509

Generate code for the SH4 with a floating-point unit that only

21510

supports single-precision arithmetic.

21511

21512

@item -m4-single

21513

@opindex m4-single

21514

Generate code for the SH4 assuming the floating-point unit is in

21515

single-precision mode by default.

21516

21517

@item -m4

21518

@opindex m4

21519

Generate code for the SH4.

21520

21521

@item -m4-100

21522

@opindex m4-100

21523

Generate code for SH4-100.

21524

21525

@item -m4-100-nofpu

21526

@opindex m4-100-nofpu

21527

Generate code for SH4-100 in such a way that the

21528

floating-point unit is not used.

21529

21530

@item -m4-100-single

21531

@opindex m4-100-single

21532

Generate code for SH4-100 assuming the floating-point unit is in

21533

single-precision mode by default.

21534

21535

@item -m4-100-single-only

21536

@opindex m4-100-single-only

21537

Generate code for SH4-100 in such a way that no double-precision

21538

floating-point operations are used.

21539

21540

@item -m4-200

21541

@opindex m4-200

21542

Generate code for SH4-200.

21543

21544

@item -m4-200-nofpu

21545

@opindex m4-200-nofpu

21546

Generate code for SH4-200 without in such a way that the

21547

floating-point unit is not used.

21548

21549

@item -m4-200-single

21550

@opindex m4-200-single

21551

Generate code for SH4-200 assuming the floating-point unit is in

21552

single-precision mode by default.

21553

21554

@item -m4-200-single-only

21555

@opindex m4-200-single-only

21556

Generate code for SH4-200 in such a way that no double-precision

21557

floating-point operations are used.

21558

21559

@item -m4-300

21560

@opindex m4-300

21561

Generate code for SH4-300.

21562

21563

@item -m4-300-nofpu

21564

@opindex m4-300-nofpu

21565

Generate code for SH4-300 without in such a way that the

21566

floating-point unit is not used.

21567

21568

@item -m4-300-single

21569

@opindex m4-300-single

21570

Generate code for SH4-300 in such a way that no double-precision

21571

floating-point operations are used.

21572

21573

@item -m4-300-single-only

21574

@opindex m4-300-single-only

21575

Generate code for SH4-300 in such a way that no double-precision

21576

floating-point operations are used.

21577

21578

@item -m4-340

21579

@opindex m4-340

21580

Generate code for SH4-340 (no MMU, no FPU).

21581

21582

@item -m4-500

21583

@opindex m4-500

21584

Generate code for SH4-500 (no FPU). Passes @option{-isa=sh4-nofpu} to the

21585

assembler.

21586

21587

@item -m4a-nofpu

21588

@opindex m4a-nofpu

21589

Generate code for the SH4al-dsp, or for a SH4a in such a way that the

21590

floating-point unit is not used.

21591

21592

@item -m4a-single-only

21593

@opindex m4a-single-only

21594

Generate code for the SH4a, in such a way that no double-precision

21595

floating-point operations are used.

21596

21597

@item -m4a-single

21598

@opindex m4a-single

21599

Generate code for the SH4a assuming the floating-point unit is in

21600

single-precision mode by default.

21601

21602

@item -m4a

21603

@opindex m4a

21604

Generate code for the SH4a.

21605

21606

@item -m4al

21607

@opindex m4al

21608

Same as @option{-m4a-nofpu}, except that it implicitly passes

21609

@option{-dsp} to the assembler. GCC doesn't generate any DSP

21610

instructions at the moment.

21611

21612

@item -mb

21613

@opindex mb

21614

Compile code for the processor in big-endian mode.

21615

21616

@item -ml

21617

@opindex ml

21618

Compile code for the processor in little-endian mode.

21619

21620

@item -mdalign

21621

@opindex mdalign

21622

Align doubles at 64-bit boundaries. Note that this changes the calling

21623

conventions, and thus some functions from the standard C library do

21624

not work unless you recompile it first with @option{-mdalign}.

21625

21626

@item -mrelax

21627

@opindex mrelax

21628

Shorten some address references at link time, when possible; uses the

21629

linker option @option{-relax}.

21630

21631

@item -mbigtable

21632

@opindex mbigtable

21633

Use 32-bit offsets in @code{switch} tables. The default is to use

21634

16-bit offsets.

21635

21636

@item -mbitops

21637

@opindex mbitops

21638

Enable the use of bit manipulation instructions on SH2A.

21639

21640

@item -mfmovd

21641

@opindex mfmovd

21642

Enable the use of the instruction @code{fmovd}. Check @option{-mdalign} for

21643

alignment constraints.

21644

21645

@item -mrenesas

21646

@opindex mrenesas

21647

Comply with the calling conventions defined by Renesas.

21648

21649

@item -mno-renesas

21650

@opindex mno-renesas

21651

Comply with the calling conventions defined for GCC before the Renesas

21652

conventions were available. This option is the default for all

21653

targets of the SH toolchain.

21654

21655

@item -mnomacsave

21656

@opindex mnomacsave

21657

Mark the @code{MAC} register as call-clobbered, even if

21658

@option{-mrenesas} is given.

21659

21660

@item -mieee

21661

@itemx -mno-ieee

21662

@opindex mieee

21663

@opindex mno-ieee

21664

Control the IEEE compliance of floating-point comparisons, which affects the

21665

handling of cases where the result of a comparison is unordered. By default

21666

@option{-mieee} is implicitly enabled. If @option{-ffinite-math-only} is

21667

enabled @option{-mno-ieee} is implicitly set, which results in faster

21668

floating-point greater-equal and less-equal comparisons. The implicit settings

21669

can be overridden by specifying either @option{-mieee} or @option{-mno-ieee}.

21670

21671

@item -minline-ic_invalidate

21672

@opindex minline-ic_invalidate

21673

Inline code to invalidate instruction cache entries after setting up

21674

nested function trampolines.

21675

This option has no effect if @option{-musermode} is in effect and the selected

21676

code generation option (e.g. @option{-m4}) does not allow the use of the @code{icbi}

21677

instruction.

21678

If the selected code generation option does not allow the use of the @code{icbi}

21679

instruction, and @option{-musermode} is not in effect, the inlined code

21680

manipulates the instruction cache address array directly with an associative

21681

write. This not only requires privileged mode at run time, but it also

21682

fails if the cache line had been mapped via the TLB and has become unmapped.

21683

21684

@item -misize

21685

@opindex misize

21686

Dump instruction size and location in the assembly code.

21687

21688

@item -mpadstruct

21689

@opindex mpadstruct

21690

This option is deprecated. It pads structures to multiple of 4 bytes,

21691

which is incompatible with the SH ABI@.

21692

21693

@item -matomic-model=@var{model}

21694

@opindex matomic-model=@var{model}

21695

Sets the model of atomic operations and additional parameters as a comma

21696

separated list. For details on the atomic built-in functions see

21697

@ref{__atomic Builtins}. The following models and parameters are supported:

21698

21699

@table @samp

21700

21701

@item none

21702

Disable compiler generated atomic sequences and emit library calls for atomic

21703

operations. This is the default if the target is not @code{sh*-*-linux*}.

21704

21705

@item soft-gusa

21706

Generate GNU/Linux compatible gUSA software atomic sequences for the atomic

21707

built-in functions. The generated atomic sequences require additional support

21708

from the interrupt/exception handling code of the system and are only suitable

21709

for SH3* and SH4* single-core systems. This option is enabled by default when

21710

the target is @code{sh*-*-linux*} and SH3* or SH4*. When the target is SH4A,

21711

this option also partially utilizes the hardware atomic instructions

21712

@code{movli.l} and @code{movco.l} to create more efficient code, unless

21713

@samp{strict} is specified.

21714

21715

@item soft-tcb

21716

Generate software atomic sequences that use a variable in the thread control

21717

block. This is a variation of the gUSA sequences which can also be used on

21718

SH1* and SH2* targets. The generated atomic sequences require additional

21719

support from the interrupt/exception handling code of the system and are only

21720

suitable for single-core systems. When using this model, the @samp{gbr-offset=}

21721

parameter has to be specified as well.

21722

21723

@item soft-imask

21724

Generate software atomic sequences that temporarily disable interrupts by

21725

setting @code{SR.IMASK = 1111}. This model works only when the program runs

21726

in privileged mode and is only suitable for single-core systems. Additional

21727

support from the interrupt/exception handling code of the system is not

21728

required. This model is enabled by default when the target is

21729

@code{sh*-*-linux*} and SH1* or SH2*.

21730

21731

@item hard-llcs

21732

Generate hardware atomic sequences using the @code{movli.l} and @code{movco.l}

21733

instructions only. This is only available on SH4A and is suitable for

21734

multi-core systems. Since the hardware instructions support only 32 bit atomic

21735

variables access to 8 or 16 bit variables is emulated with 32 bit accesses.

21736

Code compiled with this option is also compatible with other software

21737

atomic model interrupt/exception handling systems if executed on an SH4A

21738

system. Additional support from the interrupt/exception handling code of the

21739

system is not required for this model.

21740

21741

@item gbr-offset=

21742

This parameter specifies the offset in bytes of the variable in the thread

21743

control block structure that should be used by the generated atomic sequences

21744

when the @samp{soft-tcb} model has been selected. For other models this

21745

parameter is ignored. The specified value must be an integer multiple of four

21746

and in the range 0-1020.

21747

21748

@item strict

21749

This parameter prevents mixed usage of multiple atomic models, even if they

21750

are compatible, and makes the compiler generate atomic sequences of the

21751

specified model only.

21752

21753

@end table

21754

21755

@item -mtas

21756

@opindex mtas

21757

Generate the @code{tas.b} opcode for @code{__atomic_test_and_set}.

21758

Notice that depending on the particular hardware and software configuration

21759

this can degrade overall performance due to the operand cache line flushes

21760

that are implied by the @code{tas.b} instruction. On multi-core SH4A

21761

processors the @code{tas.b} instruction must be used with caution since it

21762

can result in data corruption for certain cache configurations.

21763

21764

@item -mprefergot

21765

@opindex mprefergot

21766

When generating position-independent code, emit function calls using

21767

the Global Offset Table instead of the Procedure Linkage Table.

21768

21769

@item -musermode

21770

@itemx -mno-usermode

21771

@opindex musermode

21772

@opindex mno-usermode

21773

Don't allow (allow) the compiler generating privileged mode code. Specifying

21774

@option{-musermode} also implies @option{-mno-inline-ic_invalidate} if the

21775

inlined code would not work in user mode. @option{-musermode} is the default

21776

when the target is @code{sh*-*-linux*}. If the target is SH1* or SH2*

21777

@option{-musermode} has no effect, since there is no user mode.

21778

21779

@item -multcost=@var{number}

21780

@opindex multcost=@var{number}

21781

Set the cost to assume for a multiply insn.

21782

21783

@item -mdiv=@var{strategy}

21784

@opindex mdiv=@var{strategy}

21785

Set the division strategy to be used for integer division operations.

21786

@var{strategy} can be one of:

21787

21788

@table @samp

21789

21790

@item call-div1

21791

Calls a library function that uses the single-step division instruction

21792

@code{div1} to perform the operation. Division by zero calculates an

21793

unspecified result and does not trap. This is the default except for SH4,

21794

SH2A and SHcompact.

21795

21796

@item call-fp

21797

Calls a library function that performs the operation in double precision

21798

floating point. Division by zero causes a floating-point exception. This is

21799

the default for SHcompact with FPU. Specifying this for targets that do not

21800

have a double precision FPU defaults to @code{call-div1}.

21801

21802

@item call-table

21803

Calls a library function that uses a lookup table for small divisors and

21804

the @code{div1} instruction with case distinction for larger divisors. Division

21805

by zero calculates an unspecified result and does not trap. This is the default

21806

for SH4. Specifying this for targets that do not have dynamic shift

21807

instructions defaults to @code{call-div1}.

21808

21809

@end table

21810

21811

When a division strategy has not been specified the default strategy is

21812

selected based on the current target. For SH2A the default strategy is to

21813

use the @code{divs} and @code{divu} instructions instead of library function

21814

calls.

21815

21816

@item -maccumulate-outgoing-args

21817

@opindex maccumulate-outgoing-args

21818

Reserve space once for outgoing arguments in the function prologue rather

21819

than around each call. Generally beneficial for performance and size. Also

21820

needed for unwinding to avoid changing the stack frame around conditional code.

21821

21822

@item -mdivsi3_libfunc=@var{name}

21823

@opindex mdivsi3_libfunc=@var{name}

21824

Set the name of the library function used for 32-bit signed division to

21825

@var{name}.

21826

This only affects the name used in the @samp{call} division strategies, and

21827

the compiler still expects the same sets of input/output/clobbered registers as

21828

if this option were not present.

21829

21830

@item -mfixed-range=@var{register-range}

21831

@opindex mfixed-range

21832

Generate code treating the given register range as fixed registers.

21833

A fixed register is one that the register allocator can not use. This is

21834

useful when compiling kernel code. A register range is specified as

21835

two registers separated by a dash. Multiple register ranges can be

21836

specified separated by a comma.

21837

21838

@item -mbranch-cost=@var{num}

21839

@opindex mbranch-cost=@var{num}

21840

Assume @var{num} to be the cost for a branch instruction. Higher numbers

21841

make the compiler try to generate more branch-free code if possible.

21842

If not specified the value is selected depending on the processor type that

21843

is being compiled for.

21844

21845

@item -mzdcbranch

21846

@itemx -mno-zdcbranch

21847

@opindex mzdcbranch

21848

@opindex mno-zdcbranch

21849

Assume (do not assume) that zero displacement conditional branch instructions

21850

@code{bt} and @code{bf} are fast. If @option{-mzdcbranch} is specified, the

21851

compiler prefers zero displacement branch code sequences. This is

21852

enabled by default when generating code for SH4 and SH4A. It can be explicitly

21853

disabled by specifying @option{-mno-zdcbranch}.

21854

21855

@item -mcbranch-force-delay-slot

21856

@opindex mcbranch-force-delay-slot

21857

Force the usage of delay slots for conditional branches, which stuffs the delay

21858

slot with a @code{nop} if a suitable instruction can't be found. By default

21859

this option is disabled. It can be enabled to work around hardware bugs as

21860

found in the original SH7055.

21861

21862

@item -mfused-madd

21863

@itemx -mno-fused-madd

21864

@opindex mfused-madd

21865

@opindex mno-fused-madd

21866

Generate code that uses (does not use) the floating-point multiply and

21867

accumulate instructions. These instructions are generated by default

21868

if hardware floating point is used. The machine-dependent

21869

@option{-mfused-madd} option is now mapped to the machine-independent

21870

@option{-ffp-contract=fast} option, and @option{-mno-fused-madd} is

21871

mapped to @option{-ffp-contract=off}.

21872

21873

@item -mfsca

21874

@itemx -mno-fsca

21875

@opindex mfsca

21876

@opindex mno-fsca

21877

Allow or disallow the compiler to emit the @code{fsca} instruction for sine

21878

and cosine approximations. The option @option{-mfsca} must be used in

21879

combination with @option{-funsafe-math-optimizations}. It is enabled by default

21880

when generating code for SH4A. Using @option{-mno-fsca} disables sine and cosine

21881

approximations even if @option{-funsafe-math-optimizations} is in effect.

21882

21883

@item -mfsrra

21884

@itemx -mno-fsrra

21885

@opindex mfsrra

21886

@opindex mno-fsrra

21887

Allow or disallow the compiler to emit the @code{fsrra} instruction for

21888

reciprocal square root approximations. The option @option{-mfsrra} must be used

21889

in combination with @option{-funsafe-math-optimizations} and

21890

@option{-ffinite-math-only}. It is enabled by default when generating code for

21891

SH4A. Using @option{-mno-fsrra} disables reciprocal square root approximations

21892

even if @option{-funsafe-math-optimizations} and @option{-ffinite-math-only} are

21893

in effect.

21894

21895

@item -mpretend-cmove

21896

@opindex mpretend-cmove

21897

Prefer zero-displacement conditional branches for conditional move instruction

21898

patterns. This can result in faster code on the SH4 processor.

21899

21900

@item -mfdpic

21901

@opindex fdpic

21902

Generate code using the FDPIC ABI.

21903

21904

@end table

21905

21906

@node Solaris 2 Options

21907

@subsection Solaris 2 Options

21908

@cindex Solaris 2 options

21909

21910

These @samp{-m} options are supported on Solaris 2:

21911

21912

@table @gcctabopt

21913

@item -mclear-hwcap

21914

@opindex mclear-hwcap

21915

@option{-mclear-hwcap} tells the compiler to remove the hardware

21916

capabilities generated by the Solaris assembler. This is only necessary

21917

when object files use ISA extensions not supported by the current

21918

machine, but check at runtime whether or not to use them.

21919

21920

@item -mimpure-text

21921

@opindex mimpure-text

21922

@option{-mimpure-text}, used in addition to @option{-shared}, tells

21923

the compiler to not pass @option{-z text} to the linker when linking a

21924

shared object. Using this option, you can link position-dependent

21925

code into a shared object.

21926

21927

@option{-mimpure-text} suppresses the ``relocations remain against

21928

allocatable but non-writable sections'' linker error message.

21929

However, the necessary relocations trigger copy-on-write, and the

21930

shared object is not actually shared across processes. Instead of

21931

using @option{-mimpure-text}, you should compile all source code with

21932

@option{-fpic} or @option{-fPIC}.

21933

21934

@end table

21935

21936

These switches are supported in addition to the above on Solaris 2:

21937

21938

@table @gcctabopt

21939

@item -pthreads

21940

@opindex pthreads

21941

Add support for multithreading using the POSIX threads library. This

21942

option sets flags for both the preprocessor and linker. This option does

21943

not affect the thread safety of object code produced by the compiler or

21944

that of libraries supplied with it.

21945

21946

@item -pthread

21947

@opindex pthread

21948

This is a synonym for @option{-pthreads}.

21949

@end table

21950

21951

@node SPARC Options

21952

@subsection SPARC Options

21953

@cindex SPARC options

21954

21955

These @samp{-m} options are supported on the SPARC:

21956

21957

@table @gcctabopt

21958

@item -mno-app-regs

21959

@itemx -mapp-regs

21960

@opindex mno-app-regs

21961

@opindex mapp-regs

21962

Specify @option{-mapp-regs} to generate output using the global registers

21963

2 through 4, which the SPARC SVR4 ABI reserves for applications. Like the

21964

global register 1, each global register 2 through 4 is then treated as an

21965

allocable register that is clobbered by function calls. This is the default.

21966

21967

To be fully SVR4 ABI-compliant at the cost of some performance loss,

21968

specify @option{-mno-app-regs}. You should compile libraries and system

21969

software with this option.

21970

21971

@item -mflat

21972

@itemx -mno-flat

21973

@opindex mflat

21974

@opindex mno-flat

21975

With @option{-mflat}, the compiler does not generate save/restore instructions

21976

and uses a ``flat'' or single register window model. This model is compatible

21977

with the regular register window model. The local registers and the input

21978

registers (0--5) are still treated as ``call-saved'' registers and are

21979

saved on the stack as needed.

21980

21981

With @option{-mno-flat} (the default), the compiler generates save/restore

21982

instructions (except for leaf functions). This is the normal operating mode.

21983

21984

@item -mfpu

21985

@itemx -mhard-float

21986

@opindex mfpu

21987

@opindex mhard-float

21988

Generate output containing floating-point instructions. This is the

21989

default.

21990

21991

@item -mno-fpu

21992

@itemx -msoft-float

21993

@opindex mno-fpu

21994

@opindex msoft-float

21995

Generate output containing library calls for floating point.

21996

@strong{Warning:} the requisite libraries are not available for all SPARC

21997

targets. Normally the facilities of the machine's usual C compiler are

21998

used, but this cannot be done directly in cross-compilation. You must make

21999

your own arrangements to provide suitable library functions for

22000

cross-compilation. The embedded targets @samp{sparc-*-aout} and

22001

@samp{sparclite-*-*} do provide software floating-point support.

22002

22003

@option{-msoft-float} changes the calling convention in the output file;

22004

therefore, it is only useful if you compile @emph{all} of a program with

22005

this option. In particular, you need to compile @file{libgcc.a}, the

22006

library that comes with GCC, with @option{-msoft-float} in order for

22007

this to work.

22008

22009

@item -mhard-quad-float

22010

@opindex mhard-quad-float

22011

Generate output containing quad-word (long double) floating-point

22012

instructions.

22013

22014

@item -msoft-quad-float

22015

@opindex msoft-quad-float

22016

Generate output containing library calls for quad-word (long double)

22017

floating-point instructions. The functions called are those specified

22018

in the SPARC ABI@. This is the default.

22019

22020

As of this writing, there are no SPARC implementations that have hardware

22021

support for the quad-word floating-point instructions. They all invoke

22022

a trap handler for one of these instructions, and then the trap handler

22023

emulates the effect of the instruction. Because of the trap handler overhead,

22024

this is much slower than calling the ABI library routines. Thus the

22025

@option{-msoft-quad-float} option is the default.

22026

22027

@item -mno-unaligned-doubles

22028

@itemx -munaligned-doubles

22029

@opindex mno-unaligned-doubles

22030

@opindex munaligned-doubles

22031

Assume that doubles have 8-byte alignment. This is the default.

22032

22033

With @option{-munaligned-doubles}, GCC assumes that doubles have 8-byte

22034

alignment only if they are contained in another type, or if they have an

22035

absolute address. Otherwise, it assumes they have 4-byte alignment.

22036

Specifying this option avoids some rare compatibility problems with code

22037

generated by other compilers. It is not the default because it results

22038

in a performance loss, especially for floating-point code.

22039

22040

@item -muser-mode

22041

@itemx -mno-user-mode

22042

@opindex muser-mode

22043

@opindex mno-user-mode

22044

Do not generate code that can only run in supervisor mode. This is relevant

22045

only for the @code{casa} instruction emitted for the LEON3 processor. This

22046

is the default.

22047

22048

@item -mfaster-structs

22049

@itemx -mno-faster-structs

22050

@opindex mfaster-structs

22051

@opindex mno-faster-structs

22052

With @option{-mfaster-structs}, the compiler assumes that structures

22053

should have 8-byte alignment. This enables the use of pairs of

22054

@code{ldd} and @code{std} instructions for copies in structure

22055

assignment, in place of twice as many @code{ld} and @code{st} pairs.

22056

However, the use of this changed alignment directly violates the SPARC

22057

ABI@. Thus, it's intended only for use on targets where the developer

22058

acknowledges that their resulting code is not directly in line with

22059

the rules of the ABI@.

22060

22061

@item -mstd-struct-return

22062

@itemx -mno-std-struct-return

22063

@opindex mstd-struct-return

22064

@opindex mno-std-struct-return

22065

With @option{-mstd-struct-return}, the compiler generates checking code

22066

in functions returning structures or unions to detect size mismatches

22067

between the two sides of function calls, as per the 32-bit ABI@.

22068

22069

The default is @option{-mno-std-struct-return}. This option has no effect

22070

in 64-bit mode.

22071

22072

@item -mcpu=@var{cpu_type}

22073

@opindex mcpu

22074

Set the instruction set, register set, and instruction scheduling parameters

22075

for machine type @var{cpu_type}. Supported values for @var{cpu_type} are

22076

@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{hypersparc},

22077

@samp{leon}, @samp{leon3}, @samp{leon3v7}, @samp{sparclite}, @samp{f930},

22078

@samp{f934}, @samp{sparclite86x}, @samp{sparclet}, @samp{tsc701}, @samp{v9},

22079

@samp{ultrasparc}, @samp{ultrasparc3}, @samp{niagara}, @samp{niagara2},

22080

@samp{niagara3} and @samp{niagara4}.

22081

22082

Native Solaris and GNU/Linux toolchains also support the value @samp{native},

22083

which selects the best architecture option for the host processor.

22084

@option{-mcpu=native} has no effect if GCC does not recognize

22085

the processor.

22086

22087

Default instruction scheduling parameters are used for values that select

22088

an architecture and not an implementation. These are @samp{v7}, @samp{v8},

22089

@samp{sparclite}, @samp{sparclet}, @samp{v9}.

22090

22091

Here is a list of each supported architecture and their supported

22092

implementations.

22093

22094

@table @asis

22095

@item v7

22096

cypress, leon3v7

22097

22098

@item v8

22099

supersparc, hypersparc, leon, leon3

22100

22101

@item sparclite

22102

f930, f934, sparclite86x

22103

22104

@item sparclet

22105

tsc701

22106

22107

@item v9

22108

ultrasparc, ultrasparc3, niagara, niagara2, niagara3, niagara4

22109

@end table

22110

22111

By default (unless configured otherwise), GCC generates code for the V7

22112

variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler

22113

additionally optimizes it for the Cypress CY7C602 chip, as used in the

22114

SPARCStation/SPARCServer 3xx series. This is also appropriate for the older

22115

SPARCStation 1, 2, IPX etc.

22116

22117

With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC

22118

architecture. The only difference from V7 code is that the compiler emits

22119

the integer multiply and integer divide instructions which exist in SPARC-V8

22120

but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally

22121

optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and

22122

2000 series.

22123

22124

With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of

22125

the SPARC architecture. This adds the integer multiply, integer divide step

22126

and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.

22127

With @option{-mcpu=f930}, the compiler additionally optimizes it for the

22128

Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With

22129

@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu

22130

MB86934 chip, which is the more recent SPARClite with FPU@.

22131

22132

With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of

22133

the SPARC architecture. This adds the integer multiply, multiply/accumulate,

22134

integer divide step and scan (@code{ffs}) instructions which exist in SPARClet

22135

but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally

22136

optimizes it for the TEMIC SPARClet chip.

22137

22138

With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC

22139

architecture. This adds 64-bit integer and floating-point move instructions,

22140

3 additional floating-point condition code registers and conditional move

22141

instructions. With @option{-mcpu=ultrasparc}, the compiler additionally

22142

optimizes it for the Sun UltraSPARC I/II/IIi chips. With

22143

@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the

22144

Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With

22145

@option{-mcpu=niagara}, the compiler additionally optimizes it for

22146

Sun UltraSPARC T1 chips. With @option{-mcpu=niagara2}, the compiler

22147

additionally optimizes it for Sun UltraSPARC T2 chips. With

22148

@option{-mcpu=niagara3}, the compiler additionally optimizes it for Sun

22149

UltraSPARC T3 chips. With @option{-mcpu=niagara4}, the compiler

22150

additionally optimizes it for Sun UltraSPARC T4 chips.

22151

22152

@item -mtune=@var{cpu_type}

22153

@opindex mtune

22154

Set the instruction scheduling parameters for machine type

22155

@var{cpu_type}, but do not set the instruction set or register set that the

22156

option @option{-mcpu=@var{cpu_type}} does.

22157

22158

The same values for @option{-mcpu=@var{cpu_type}} can be used for

22159

@option{-mtune=@var{cpu_type}}, but the only useful values are those

22160

that select a particular CPU implementation. Those are @samp{cypress},

22161

@samp{supersparc}, @samp{hypersparc}, @samp{leon}, @samp{leon3},

22162

@samp{leon3v7}, @samp{f930}, @samp{f934}, @samp{sparclite86x}, @samp{tsc701},

22163

@samp{ultrasparc}, @samp{ultrasparc3}, @samp{niagara}, @samp{niagara2},

22164

@samp{niagara3} and @samp{niagara4}. With native Solaris and GNU/Linux

22165

toolchains, @samp{native} can also be used.

22166

22167

@item -mv8plus

22168

@itemx -mno-v8plus

22169

@opindex mv8plus

22170

@opindex mno-v8plus

22171

With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The

22172

difference from the V8 ABI is that the global and out registers are

22173

considered 64 bits wide. This is enabled by default on Solaris in 32-bit

22174

mode for all SPARC-V9 processors.

22175

22176

@item -mvis

22177

@itemx -mno-vis

22178

@opindex mvis

22179

@opindex mno-vis

22180

With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC

22181

Visual Instruction Set extensions. The default is @option{-mno-vis}.

22182

22183

@item -mvis2

22184

@itemx -mno-vis2

22185

@opindex mvis2

22186

@opindex mno-vis2

22187

With @option{-mvis2}, GCC generates code that takes advantage of

22188

version 2.0 of the UltraSPARC Visual Instruction Set extensions. The

22189

default is @option{-mvis2} when targeting a cpu that supports such

22190

instructions, such as UltraSPARC-III and later. Setting @option{-mvis2}

22191

also sets @option{-mvis}.

22192

22193

@item -mvis3

22194

@itemx -mno-vis3

22195

@opindex mvis3

22196

@opindex mno-vis3

22197

With @option{-mvis3}, GCC generates code that takes advantage of

22198

version 3.0 of the UltraSPARC Visual Instruction Set extensions. The

22199

default is @option{-mvis3} when targeting a cpu that supports such

22200

instructions, such as niagara-3 and later. Setting @option{-mvis3}

22201

also sets @option{-mvis2} and @option{-mvis}.

22202

22203

@item -mcbcond

22204

@itemx -mno-cbcond

22205

@opindex mcbcond

22206

@opindex mno-cbcond

22207

With @option{-mcbcond}, GCC generates code that takes advantage of

22208

compare-and-branch instructions, as defined in the Sparc Architecture 2011.

22209

The default is @option{-mcbcond} when targeting a cpu that supports such

22210

instructions, such as niagara-4 and later.

22211

22212

@item -mpopc

22213

@itemx -mno-popc

22214

@opindex mpopc

22215

@opindex mno-popc

22216

With @option{-mpopc}, GCC generates code that takes advantage of the UltraSPARC

22217

population count instruction. The default is @option{-mpopc}

22218

when targeting a cpu that supports such instructions, such as Niagara-2 and

22219

later.

22220

22221

@item -mfmaf

22222

@itemx -mno-fmaf

22223

@opindex mfmaf

22224

@opindex mno-fmaf

22225

With @option{-mfmaf}, GCC generates code that takes advantage of the UltraSPARC

22226

Fused Multiply-Add Floating-point extensions. The default is @option{-mfmaf}

22227

when targeting a cpu that supports such instructions, such as Niagara-3 and

22228

later.

22229

22230

@item -mfix-at697f

22231

@opindex mfix-at697f

22232

Enable the documented workaround for the single erratum of the Atmel AT697F

22233

processor (which corresponds to erratum #13 of the AT697E processor).

22234

22235

@item -mfix-ut699

22236

@opindex mfix-ut699

22237

Enable the documented workarounds for the floating-point errata and the data

22238

cache nullify errata of the UT699 processor.

22239

@end table

22240

22241

These @samp{-m} options are supported in addition to the above

22242

on SPARC-V9 processors in 64-bit environments:

22243

22244

@table @gcctabopt

22245

@item -m32

22246

@itemx -m64

22247

@opindex m32

22248

@opindex m64

22249

Generate code for a 32-bit or 64-bit environment.

22250

The 32-bit environment sets int, long and pointer to 32 bits.

22251

The 64-bit environment sets int to 32 bits and long and pointer

22252

to 64 bits.

22253

22254

@item -mcmodel=@var{which}

22255

@opindex mcmodel

22256

Set the code model to one of

22257

22258

@table @samp

22259

@item medlow

22260

The Medium/Low code model: 64-bit addresses, programs

22261

must be linked in the low 32 bits of memory. Programs can be statically

22262

or dynamically linked.

22263

22264

@item medmid

22265

The Medium/Middle code model: 64-bit addresses, programs

22266

must be linked in the low 44 bits of memory, the text and data segments must

22267

be less than 2GB in size and the data segment must be located within 2GB of

22268

the text segment.

22269

22270

@item medany

22271

The Medium/Anywhere code model: 64-bit addresses, programs

22272

may be linked anywhere in memory, the text and data segments must be less

22273

than 2GB in size and the data segment must be located within 2GB of the

22274

text segment.

22275

22276

@item embmedany

22277

The Medium/Anywhere code model for embedded systems:

22278

64-bit addresses, the text and data segments must be less than 2GB in

22279

size, both starting anywhere in memory (determined at link time). The

22280

global register %g4 points to the base of the data segment. Programs

22281

are statically linked and PIC is not supported.

22282

@end table

22283

22284

@item -mmemory-model=@var{mem-model}

22285

@opindex mmemory-model

22286

Set the memory model in force on the processor to one of

22287

22288

@table @samp

22289

@item default

22290

The default memory model for the processor and operating system.

22291

22292

@item rmo

22293

Relaxed Memory Order

22294

22295

@item pso

22296

Partial Store Order

22297

22298

@item tso

22299

Total Store Order

22300

22301

@item sc

22302

Sequential Consistency

22303

@end table

22304

22305

These memory models are formally defined in Appendix D of the Sparc V9

22306

architecture manual, as set in the processor's @code{PSTATE.MM} field.

22307

22308

@item -mstack-bias

22309

@itemx -mno-stack-bias

22310

@opindex mstack-bias

22311

@opindex mno-stack-bias

22312

With @option{-mstack-bias}, GCC assumes that the stack pointer, and

22313

frame pointer if present, are offset by @minus{}2047 which must be added back

22314

when making stack frame references. This is the default in 64-bit mode.

22315

Otherwise, assume no such offset is present.

22316

@end table

22317

22318

@node SPU Options

22319

@subsection SPU Options

22320

@cindex SPU options

22321

22322

These @samp{-m} options are supported on the SPU:

22323

22324

@table @gcctabopt

22325

@item -mwarn-reloc

22326

@itemx -merror-reloc

22327

@opindex mwarn-reloc

22328

@opindex merror-reloc

22329

22330

The loader for SPU does not handle dynamic relocations. By default, GCC

22331

gives an error when it generates code that requires a dynamic

22332

relocation. @option{-mno-error-reloc} disables the error,

22333

@option{-mwarn-reloc} generates a warning instead.

22334

22335

@item -msafe-dma

22336

@itemx -munsafe-dma

22337

@opindex msafe-dma

22338

@opindex munsafe-dma

22339

22340

Instructions that initiate or test completion of DMA must not be

22341

reordered with respect to loads and stores of the memory that is being

22342

accessed.

22343

With @option{-munsafe-dma} you must use the @code{volatile} keyword to protect

22344

memory accesses, but that can lead to inefficient code in places where the

22345

memory is known to not change. Rather than mark the memory as volatile,

22346

you can use @option{-msafe-dma} to tell the compiler to treat

22347

the DMA instructions as potentially affecting all memory.

22348

22349

@item -mbranch-hints

22350

@opindex mbranch-hints

22351

22352

By default, GCC generates a branch hint instruction to avoid

22353

pipeline stalls for always-taken or probably-taken branches. A hint

22354

is not generated closer than 8 instructions away from its branch.

22355

There is little reason to disable them, except for debugging purposes,

22356

or to make an object a little bit smaller.

22357

22358

@item -msmall-mem

22359

@itemx -mlarge-mem

22360

@opindex msmall-mem

22361

@opindex mlarge-mem

22362

22363

By default, GCC generates code assuming that addresses are never larger

22364

than 18 bits. With @option{-mlarge-mem} code is generated that assumes

22365

a full 32-bit address.

22366

22367

@item -mstdmain

22368

@opindex mstdmain

22369

22370

By default, GCC links against startup code that assumes the SPU-style

22371

main function interface (which has an unconventional parameter list).

22372

With @option{-mstdmain}, GCC links your program against startup

22373

code that assumes a C99-style interface to @code{main}, including a

22374

local copy of @code{argv} strings.

22375

22376

@item -mfixed-range=@var{register-range}

22377

@opindex mfixed-range

22378

Generate code treating the given register range as fixed registers.

22379

A fixed register is one that the register allocator cannot use. This is

22380

useful when compiling kernel code. A register range is specified as

22381

two registers separated by a dash. Multiple register ranges can be

22382

specified separated by a comma.

22383

22384

@item -mea32

22385

@itemx -mea64

22386

@opindex mea32

22387

@opindex mea64

22388

Compile code assuming that pointers to the PPU address space accessed

22389

via the @code{__ea} named address space qualifier are either 32 or 64

22390

bits wide. The default is 32 bits. As this is an ABI-changing option,

22391

all object code in an executable must be compiled with the same setting.

22392

22393

@item -maddress-space-conversion

22394

@itemx -mno-address-space-conversion

22395

@opindex maddress-space-conversion

22396

@opindex mno-address-space-conversion

22397

Allow/disallow treating the @code{__ea} address space as superset

22398

of the generic address space. This enables explicit type casts

22399

between @code{__ea} and generic pointer as well as implicit

22400

conversions of generic pointers to @code{__ea} pointers. The

22401

default is to allow address space pointer conversions.

22402

22403

@item -mcache-size=@var{cache-size}

22404

@opindex mcache-size

22405

This option controls the version of libgcc that the compiler links to an

22406

executable and selects a software-managed cache for accessing variables

22407

in the @code{__ea} address space with a particular cache size. Possible

22408

options for @var{cache-size} are @samp{8}, @samp{16}, @samp{32}, @samp{64}

22409

and @samp{128}. The default cache size is 64KB.

22410

22411

@item -matomic-updates

22412

@itemx -mno-atomic-updates

22413

@opindex matomic-updates

22414

@opindex mno-atomic-updates

22415

This option controls the version of libgcc that the compiler links to an

22416

executable and selects whether atomic updates to the software-managed

22417

cache of PPU-side variables are used. If you use atomic updates, changes

22418

to a PPU variable from SPU code using the @code{__ea} named address space

22419

qualifier do not interfere with changes to other PPU variables residing

22420

in the same cache line from PPU code. If you do not use atomic updates,

22421

such interference may occur; however, writing back cache lines is

22422

more efficient. The default behavior is to use atomic updates.

22423

22424

@item -mdual-nops

22425

@itemx -mdual-nops=@var{n}

22426

@opindex mdual-nops

22427

By default, GCC inserts nops to increase dual issue when it expects

22428

it to increase performance. @var{n} can be a value from 0 to 10. A

22429

smaller @var{n} inserts fewer nops. 10 is the default, 0 is the

22430

same as @option{-mno-dual-nops}. Disabled with @option{-Os}.

22431

22432

@item -mhint-max-nops=@var{n}

22433

@opindex mhint-max-nops

22434

Maximum number of nops to insert for a branch hint. A branch hint must

22435

be at least 8 instructions away from the branch it is affecting. GCC

22436

inserts up to @var{n} nops to enforce this, otherwise it does not

22437

generate the branch hint.

22438

22439

@item -mhint-max-distance=@var{n}

22440

@opindex mhint-max-distance

22441

The encoding of the branch hint instruction limits the hint to be within

22442

256 instructions of the branch it is affecting. By default, GCC makes

22443

sure it is within 125.

22444

22445

@item -msafe-hints

22446

@opindex msafe-hints

22447

Work around a hardware bug that causes the SPU to stall indefinitely.

22448

By default, GCC inserts the @code{hbrp} instruction to make sure

22449

this stall won't happen.

22450

22451

@end table

22452

22453

@node System V Options

22454

@subsection Options for System V

22455

22456

These additional options are available on System V Release 4 for

22457

compatibility with other compilers on those systems:

22458

22459

@table @gcctabopt

22460

@item -G

22461

@opindex G

22462

Create a shared object.

22463

It is recommended that @option{-symbolic} or @option{-shared} be used instead.

22464

22465

@item -Qy

22466

@opindex Qy

22467

Identify the versions of each tool used by the compiler, in a

22468

@code{.ident} assembler directive in the output.

22469

22470

@item -Qn

22471

@opindex Qn

22472

Refrain from adding @code{.ident} directives to the output file (this is

22473

the default).

22474

22475

@item -YP,@var{dirs}

22476

@opindex YP

22477

Search the directories @var{dirs}, and no others, for libraries

22478

specified with @option{-l}.

22479

22480

@item -Ym,@var{dir}

22481

@opindex Ym

22482

Look in the directory @var{dir} to find the M4 preprocessor.

22483

The assembler uses this option.

22484

@c This is supposed to go with a -Yd for predefined M4 macro files, but

22485

@c the generic assembler that comes with Solaris takes just -Ym.

22486

@end table

22487

22488

@node TILE-Gx Options

22489

@subsection TILE-Gx Options

22490

@cindex TILE-Gx options

22491

22492

These @samp{-m} options are supported on the TILE-Gx:

22493

22494

@table @gcctabopt

22495

@item -mcmodel=small

22496

@opindex mcmodel=small

22497

Generate code for the small model. The distance for direct calls is

22498

limited to 500M in either direction. PC-relative addresses are 32

22499

bits. Absolute addresses support the full address range.

22500

22501

@item -mcmodel=large

22502

@opindex mcmodel=large

22503

Generate code for the large model. There is no limitation on call

22504

distance, pc-relative addresses, or absolute addresses.

22505

22506

@item -mcpu=@var{name}

22507

@opindex mcpu

22508

Selects the type of CPU to be targeted. Currently the only supported

22509

type is @samp{tilegx}.

22510

22511

@item -m32

22512

@itemx -m64

22513

@opindex m32

22514

@opindex m64

22515

Generate code for a 32-bit or 64-bit environment. The 32-bit

22516

environment sets int, long, and pointer to 32 bits. The 64-bit

22517

environment sets int to 32 bits and long and pointer to 64 bits.

22518

22519

@item -mbig-endian

22520

@itemx -mlittle-endian

22521

@opindex mbig-endian

22522

@opindex mlittle-endian

22523

Generate code in big/little endian mode, respectively.

22524

@end table

22525

22526

@node TILEPro Options

22527

@subsection TILEPro Options

22528

@cindex TILEPro options

22529

22530

These @samp{-m} options are supported on the TILEPro:

22531

22532

@table @gcctabopt

22533

@item -mcpu=@var{name}

22534

@opindex mcpu

22535

Selects the type of CPU to be targeted. Currently the only supported

22536

type is @samp{tilepro}.

22537

22538

@item -m32

22539

@opindex m32

22540

Generate code for a 32-bit environment, which sets int, long, and

22541

pointer to 32 bits. This is the only supported behavior so the flag

22542

is essentially ignored.

22543

@end table

22544

22545

@node V850 Options

22546

@subsection V850 Options

22547

@cindex V850 Options

22548

22549

These @samp{-m} options are defined for V850 implementations:

22550

22551

@table @gcctabopt

22552

@item -mlong-calls

22553

@itemx -mno-long-calls

22554

@opindex mlong-calls

22555

@opindex mno-long-calls

22556

Treat all calls as being far away (near). If calls are assumed to be

22557

far away, the compiler always loads the function's address into a

22558

register, and calls indirect through the pointer.

22559

22560

@item -mno-ep

22561

@itemx -mep

22562

@opindex mno-ep

22563

@opindex mep

22564

Do not optimize (do optimize) basic blocks that use the same index

22565

pointer 4 or more times to copy pointer into the @code{ep} register, and

22566

use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}

22567

option is on by default if you optimize.

22568

22569

@item -mno-prolog-function

22570

@itemx -mprolog-function

22571

@opindex mno-prolog-function

22572

@opindex mprolog-function

22573

Do not use (do use) external functions to save and restore registers

22574

at the prologue and epilogue of a function. The external functions

22575

are slower, but use less code space if more than one function saves

22576

the same number of registers. The @option{-mprolog-function} option

22577

is on by default if you optimize.

22578

22579

@item -mspace

22580

@opindex mspace

22581

Try to make the code as small as possible. At present, this just turns

22582

on the @option{-mep} and @option{-mprolog-function} options.

22583

22584

@item -mtda=@var{n}

22585

@opindex mtda

22586

Put static or global variables whose size is @var{n} bytes or less into

22587

the tiny data area that register @code{ep} points to. The tiny data

22588

area can hold up to 256 bytes in total (128 bytes for byte references).

22589

22590

@item -msda=@var{n}

22591

@opindex msda

22592

Put static or global variables whose size is @var{n} bytes or less into

22593

the small data area that register @code{gp} points to. The small data

22594

area can hold up to 64 kilobytes.

22595

22596

@item -mzda=@var{n}

22597

@opindex mzda

22598

Put static or global variables whose size is @var{n} bytes or less into

22599

the first 32 kilobytes of memory.

22600

22601

@item -mv850

22602

@opindex mv850

22603

Specify that the target processor is the V850.

22604

22605

@item -mv850e3v5

22606

@opindex mv850e3v5

22607

Specify that the target processor is the V850E3V5. The preprocessor

22608

constant @code{__v850e3v5__} is defined if this option is used.

22609

22610

@item -mv850e2v4

22611

@opindex mv850e2v4

22612

Specify that the target processor is the V850E3V5. This is an alias for

22613

the @option{-mv850e3v5} option.

22614

22615

@item -mv850e2v3

22616

@opindex mv850e2v3

22617

Specify that the target processor is the V850E2V3. The preprocessor

22618

constant @code{__v850e2v3__} is defined if this option is used.

22619

22620

@item -mv850e2

22621

@opindex mv850e2

22622

Specify that the target processor is the V850E2. The preprocessor

22623

constant @code{__v850e2__} is defined if this option is used.

22624

22625

@item -mv850e1

22626

@opindex mv850e1

22627

Specify that the target processor is the V850E1. The preprocessor

22628

constants @code{__v850e1__} and @code{__v850e__} are defined if

22629

this option is used.

22630

22631

@item -mv850es

22632

@opindex mv850es

22633

Specify that the target processor is the V850ES. This is an alias for

22634

the @option{-mv850e1} option.

22635

22636

@item -mv850e

22637

@opindex mv850e

22638

Specify that the target processor is the V850E@. The preprocessor

22639

constant @code{__v850e__} is defined if this option is used.

22640

22641

If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}

22642

nor @option{-mv850e2} nor @option{-mv850e2v3} nor @option{-mv850e3v5}

22643

are defined then a default target processor is chosen and the

22644

relevant @samp{__v850*__} preprocessor constant is defined.

22645

22646

The preprocessor constants @code{__v850} and @code{__v851__} are always

22647

defined, regardless of which processor variant is the target.

22648

22649

@item -mdisable-callt

22650

@itemx -mno-disable-callt

22651

@opindex mdisable-callt

22652

@opindex mno-disable-callt

22653

This option suppresses generation of the @code{CALLT} instruction for the

22654

v850e, v850e1, v850e2, v850e2v3 and v850e3v5 flavors of the v850

22655

architecture.

22656

22657

This option is enabled by default when the RH850 ABI is

22658

in use (see @option{-mrh850-abi}), and disabled by default when the

22659

GCC ABI is in use. If @code{CALLT} instructions are being generated

22660

then the C preprocessor symbol @code{__V850_CALLT__} is defined.

22661

22662

@item -mrelax

22663

@itemx -mno-relax

22664

@opindex mrelax

22665

@opindex mno-relax

22666

Pass on (or do not pass on) the @option{-mrelax} command-line option

22667

to the assembler.

22668

22669

@item -mlong-jumps

22670

@itemx -mno-long-jumps

22671

@opindex mlong-jumps

22672

@opindex mno-long-jumps

22673

Disable (or re-enable) the generation of PC-relative jump instructions.

22674

22675

@item -msoft-float

22676

@itemx -mhard-float

22677

@opindex msoft-float

22678

@opindex mhard-float

22679

Disable (or re-enable) the generation of hardware floating point

22680

instructions. This option is only significant when the target

22681

architecture is @samp{V850E2V3} or higher. If hardware floating point

22682

instructions are being generated then the C preprocessor symbol

22683

@code{__FPU_OK__} is defined, otherwise the symbol

22684

@code{__NO_FPU__} is defined.

22685

22686

@item -mloop

22687

@opindex mloop

22688

Enables the use of the e3v5 LOOP instruction. The use of this

22689

instruction is not enabled by default when the e3v5 architecture is

22690

selected because its use is still experimental.

22691

22692

@item -mrh850-abi

22693

@itemx -mghs

22694

@opindex mrh850-abi

22695

@opindex mghs

22696

Enables support for the RH850 version of the V850 ABI. This is the

22697

default. With this version of the ABI the following rules apply:

22698

22699

@itemize

22700

@item

22701

Integer sized structures and unions are returned via a memory pointer

22702

rather than a register.

22703

22704

@item

22705

Large structures and unions (more than 8 bytes in size) are passed by

22706

value.

22707

22708

@item

22709

Functions are aligned to 16-bit boundaries.

22710

22711

@item

22712

The @option{-m8byte-align} command-line option is supported.

22713

22714

@item

22715

The @option{-mdisable-callt} command-line option is enabled by

22716

default. The @option{-mno-disable-callt} command-line option is not

22717

supported.

22718

@end itemize

22719

22720

When this version of the ABI is enabled the C preprocessor symbol

22721

@code{__V850_RH850_ABI__} is defined.

22722

22723

@item -mgcc-abi

22724

@opindex mgcc-abi

22725

Enables support for the old GCC version of the V850 ABI. With this

22726

version of the ABI the following rules apply:

22727

22728

@itemize

22729

@item

22730

Integer sized structures and unions are returned in register @code{r10}.

22731

22732

@item

22733

Large structures and unions (more than 8 bytes in size) are passed by

22734

reference.

22735

22736

@item

22737

Functions are aligned to 32-bit boundaries, unless optimizing for

22738

size.

22739

22740

@item

22741

The @option{-m8byte-align} command-line option is not supported.

22742

22743

@item

22744

The @option{-mdisable-callt} command-line option is supported but not

22745

enabled by default.

22746

@end itemize

22747

22748

When this version of the ABI is enabled the C preprocessor symbol

22749

@code{__V850_GCC_ABI__} is defined.

22750

22751

@item -m8byte-align

22752

@itemx -mno-8byte-align

22753

@opindex m8byte-align

22754

@opindex mno-8byte-align

22755

Enables support for @code{double} and @code{long long} types to be

22756

aligned on 8-byte boundaries. The default is to restrict the

22757

alignment of all objects to at most 4-bytes. When

22758

@option{-m8byte-align} is in effect the C preprocessor symbol

22759

@code{__V850_8BYTE_ALIGN__} is defined.

22760

22761

@item -mbig-switch

22762

@opindex mbig-switch

22763

Generate code suitable for big switch tables. Use this option only if

22764

the assembler/linker complain about out of range branches within a switch

22765

table.

22766

22767

@item -mapp-regs

22768

@opindex mapp-regs

22769

This option causes r2 and r5 to be used in the code generated by

22770

the compiler. This setting is the default.

22771

22772

@item -mno-app-regs

22773

@opindex mno-app-regs

22774

This option causes r2 and r5 to be treated as fixed registers.

22775

22776

@end table

22777

22778

@node VAX Options

22779

@subsection VAX Options

22780

@cindex VAX options

22781

22782

These @samp{-m} options are defined for the VAX:

22783

22784

@table @gcctabopt

22785

@item -munix

22786

@opindex munix

22787

Do not output certain jump instructions (@code{aobleq} and so on)

22788

that the Unix assembler for the VAX cannot handle across long

22789

ranges.

22790

22791

@item -mgnu

22792

@opindex mgnu

22793

Do output those jump instructions, on the assumption that the

22794

GNU assembler is being used.

22795

22796

@item -mg

22797

@opindex mg

22798

Output code for G-format floating-point numbers instead of D-format.

22799

@end table

22800

22801

@node Visium Options

22802

@subsection Visium Options

22803

@cindex Visium options

22804

22805

@table @gcctabopt

22806

22807

@item -mdebug

22808

@opindex mdebug

22809

A program which performs file I/O and is destined to run on an MCM target

22810

should be linked with this option. It causes the libraries libc.a and

22811

libdebug.a to be linked. The program should be run on the target under

22812

the control of the GDB remote debugging stub.

22813

22814

@item -msim

22815

@opindex msim

22816

A program which performs file I/O and is destined to run on the simulator

22817

should be linked with option. This causes libraries libc.a and libsim.a to

22818

be linked.

22819

22820

@item -mfpu

22821

@itemx -mhard-float

22822

@opindex mfpu

22823

@opindex mhard-float

22824

Generate code containing floating-point instructions. This is the

22825

default.

22826

22827

@item -mno-fpu

22828

@itemx -msoft-float

22829

@opindex mno-fpu

22830

@opindex msoft-float

22831

Generate code containing library calls for floating-point.

22832

22833

@option{-msoft-float} changes the calling convention in the output file;

22834

therefore, it is only useful if you compile @emph{all} of a program with

22835

this option. In particular, you need to compile @file{libgcc.a}, the

22836

library that comes with GCC, with @option{-msoft-float} in order for

22837

this to work.

22838

22839

@item -mcpu=@var{cpu_type}

22840

@opindex mcpu

22841

Set the instruction set, register set, and instruction scheduling parameters

22842

for machine type @var{cpu_type}. Supported values for @var{cpu_type} are

22843

@samp{mcm}, @samp{gr5} and @samp{gr6}.

22844

22845

@samp{mcm} is a synonym of @samp{gr5} present for backward compatibility.

22846

22847

By default (unless configured otherwise), GCC generates code for the GR5

22848

variant of the Visium architecture.

22849

22850

With @option{-mcpu=gr6}, GCC generates code for the GR6 variant of the Visium

22851

architecture. The only difference from GR5 code is that the compiler will

22852

generate block move instructions.

22853

22854

@item -mtune=@var{cpu_type}

22855

@opindex mtune

22856

Set the instruction scheduling parameters for machine type @var{cpu_type},

22857

but do not set the instruction set or register set that the option

22858

@option{-mcpu=@var{cpu_type}} would.

22859

22860

@item -msv-mode

22861

@opindex msv-mode

22862

Generate code for the supervisor mode, where there are no restrictions on

22863

the access to general registers. This is the default.

22864

22865

@item -muser-mode

22866

@opindex muser-mode

22867

Generate code for the user mode, where the access to some general registers

22868

is forbidden: on the GR5, registers r24 to r31 cannot be accessed in this

22869

mode; on the GR6, only registers r29 to r31 are affected.

22870

@end table

22871

22872

@node VMS Options

22873

@subsection VMS Options

22874

22875

These @samp{-m} options are defined for the VMS implementations:

22876

22877

@table @gcctabopt

22878

@item -mvms-return-codes

22879

@opindex mvms-return-codes

22880

Return VMS condition codes from @code{main}. The default is to return POSIX-style

22881

condition (e.g.@ error) codes.

22882

22883

@item -mdebug-main=@var{prefix}

22884

@opindex mdebug-main=@var{prefix}

22885

Flag the first routine whose name starts with @var{prefix} as the main

22886

routine for the debugger.

22887

22888

@item -mmalloc64

22889

@opindex mmalloc64

22890

Default to 64-bit memory allocation routines.

22891

22892

@item -mpointer-size=@var{size}

22893

@opindex mpointer-size=@var{size}

22894

Set the default size of pointers. Possible options for @var{size} are

22895

@samp{32} or @samp{short} for 32 bit pointers, @samp{64} or @samp{long}

22896

for 64 bit pointers, and @samp{no} for supporting only 32 bit pointers.

22897

The later option disables @code{pragma pointer_size}.

22898

@end table

22899

22900

@node VxWorks Options

22901

@subsection VxWorks Options

22902

@cindex VxWorks Options

22903

22904

The options in this section are defined for all VxWorks targets.

22905

Options specific to the target hardware are listed with the other

22906

options for that target.

22907

22908

@table @gcctabopt

22909

@item -mrtp

22910

@opindex mrtp

22911

GCC can generate code for both VxWorks kernels and real time processes

22912

(RTPs). This option switches from the former to the latter. It also

22913

defines the preprocessor macro @code{__RTP__}.

22914

22915

@item -non-static

22916

@opindex non-static

22917

Link an RTP executable against shared libraries rather than static

22918

libraries. The options @option{-static} and @option{-shared} can

22919

also be used for RTPs (@pxref{Link Options}); @option{-static}

22920

is the default.

22921

22922

@item -Bstatic

22923

@itemx -Bdynamic

22924

@opindex Bstatic

22925

@opindex Bdynamic

22926

These options are passed down to the linker. They are defined for

22927

compatibility with Diab.

22928

22929

@item -Xbind-lazy

22930

@opindex Xbind-lazy

22931

Enable lazy binding of function calls. This option is equivalent to

22932

@option{-Wl,-z,now} and is defined for compatibility with Diab.

22933

22934

@item -Xbind-now

22935

@opindex Xbind-now

22936

Disable lazy binding of function calls. This option is the default and

22937

is defined for compatibility with Diab.

22938

@end table

22939

22940

@node x86 Options

22941

@subsection x86 Options

22942

@cindex x86 Options

22943

22944

These @samp{-m} options are defined for the x86 family of computers.

22945

22946

@table @gcctabopt

22947

22948

@item -march=@var{cpu-type}

22949

@opindex march

22950

Generate instructions for the machine type @var{cpu-type}. In contrast to

22951

@option{-mtune=@var{cpu-type}}, which merely tunes the generated code

22952

for the specified @var{cpu-type}, @option{-march=@var{cpu-type}} allows GCC

22953

to generate code that may not run at all on processors other than the one

22954

indicated. Specifying @option{-march=@var{cpu-type}} implies

22955

@option{-mtune=@var{cpu-type}}.

22956

22957

The choices for @var{cpu-type} are:

22958

22959

@table @samp

22960

@item native

22961

This selects the CPU to generate code for at compilation time by determining

22962

the processor type of the compiling machine. Using @option{-march=native}

22963

enables all instruction subsets supported by the local machine (hence

22964

the result might not run on different machines). Using @option{-mtune=native}

22965

produces code optimized for the local machine under the constraints

22966

of the selected instruction set.

22967

22968

@item i386

22969

Original Intel i386 CPU@.

22970

22971

@item i486

22972

Intel i486 CPU@. (No scheduling is implemented for this chip.)

22973

22974

@item i586

22975

@itemx pentium

22976

Intel Pentium CPU with no MMX support.

22977

22978

@item lakemont

22979

Intel Lakemont MCU, based on Intel Pentium CPU.

22980

22981

@item pentium-mmx

22982

Intel Pentium MMX CPU, based on Pentium core with MMX instruction set support.

22983

22984

@item pentiumpro

22985

Intel Pentium Pro CPU@.

22986

22987

@item i686

22988

When used with @option{-march}, the Pentium Pro

22989

instruction set is used, so the code runs on all i686 family chips.

22990

When used with @option{-mtune}, it has the same meaning as @samp{generic}.

22991

22992

@item pentium2

22993

Intel Pentium II CPU, based on Pentium Pro core with MMX instruction set

22994

support.

22995

22996

@item pentium3

22997

@itemx pentium3m

22998

Intel Pentium III CPU, based on Pentium Pro core with MMX and SSE instruction

22999

set support.

23000

23001

@item pentium-m

23002

Intel Pentium M; low-power version of Intel Pentium III CPU

23003

with MMX, SSE and SSE2 instruction set support. Used by Centrino notebooks.

23004

23005

@item pentium4

23006

@itemx pentium4m

23007

Intel Pentium 4 CPU with MMX, SSE and SSE2 instruction set support.

23008

23009

@item prescott

23010

Improved version of Intel Pentium 4 CPU with MMX, SSE, SSE2 and SSE3 instruction

23011

set support.

23012

23013

@item nocona

23014

Improved version of Intel Pentium 4 CPU with 64-bit extensions, MMX, SSE,

23015

SSE2 and SSE3 instruction set support.

23016

23017

@item core2

23018

Intel Core 2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3

23019

instruction set support.

23020

23021

@item nehalem

23022

Intel Nehalem CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,

23023

SSE4.1, SSE4.2 and POPCNT instruction set support.

23024

23025

@item westmere

23026

Intel Westmere CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,

23027

SSE4.1, SSE4.2, POPCNT, AES and PCLMUL instruction set support.

23028

23029

@item sandybridge

23030

Intel Sandy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,

23031

SSE4.1, SSE4.2, POPCNT, AVX, AES and PCLMUL instruction set support.

23032

23033

@item ivybridge

23034

Intel Ivy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,

23035

SSE4.1, SSE4.2, POPCNT, AVX, AES, PCLMUL, FSGSBASE, RDRND and F16C

23036

instruction set support.

23037

23038

@item haswell

23039

Intel Haswell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,

23040

SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,

23041

BMI, BMI2 and F16C instruction set support.

23042

23043

@item broadwell

23044

Intel Broadwell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,

23045

SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,

23046

BMI, BMI2, F16C, RDSEED, ADCX and PREFETCHW instruction set support.

23047

23048

@item skylake

23049

Intel Skylake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,

23050

SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,

23051

BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, CLFLUSHOPT, XSAVEC and

23052

XSAVES instruction set support.

23053

23054

@item bonnell

23055

Intel Bonnell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3 and SSSE3

23056

instruction set support.

23057

23058

@item silvermont

23059

Intel Silvermont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,

23060

SSE4.1, SSE4.2, POPCNT, AES, PCLMUL and RDRND instruction set support.

23061

23062

@item knl

23063

Intel Knight's Landing CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,

23064

SSSE3, SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,

23065

BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, AVX512F, AVX512PF, AVX512ER and

23066

AVX512CD instruction set support.

23067

23068

@item skylake-avx512

23069

Intel Skylake Server CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,

23070

SSSE3, SSE4.1, SSE4.2, POPCNT, PKU, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,

23071

BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, CLFLUSHOPT, XSAVEC, XSAVES, AVX512F,

23072

AVX512VL, AVX512BW, AVX512DQ and AVX512CD instruction set support.

23073

23074

@item k6

23075

AMD K6 CPU with MMX instruction set support.

23076

23077

@item k6-2

23078

@itemx k6-3

23079

Improved versions of AMD K6 CPU with MMX and 3DNow!@: instruction set support.

23080

23081

@item athlon

23082

@itemx athlon-tbird

23083

AMD Athlon CPU with MMX, 3dNOW!, enhanced 3DNow!@: and SSE prefetch instructions

23084

support.

23085

23086

@item athlon-4

23087

@itemx athlon-xp

23088

@itemx athlon-mp

23089

Improved AMD Athlon CPU with MMX, 3DNow!, enhanced 3DNow!@: and full SSE

23090

instruction set support.

23091

23092

@item k8

23093

@itemx opteron

23094

@itemx athlon64

23095

@itemx athlon-fx

23096

Processors based on the AMD K8 core with x86-64 instruction set support,

23097

including the AMD Opteron, Athlon 64, and Athlon 64 FX processors.

23098

(This supersets MMX, SSE, SSE2, 3DNow!, enhanced 3DNow!@: and 64-bit

23099

instruction set extensions.)

23100

23101

@item k8-sse3

23102

@itemx opteron-sse3

23103

@itemx athlon64-sse3

23104

Improved versions of AMD K8 cores with SSE3 instruction set support.

23105

23106

@item amdfam10

23107

@itemx barcelona

23108

CPUs based on AMD Family 10h cores with x86-64 instruction set support. (This

23109

supersets MMX, SSE, SSE2, SSE3, SSE4A, 3DNow!, enhanced 3DNow!, ABM and 64-bit

23110

instruction set extensions.)

23111

23112

@item bdver1

23113

CPUs based on AMD Family 15h cores with x86-64 instruction set support. (This

23114

supersets FMA4, AVX, XOP, LWP, AES, PCL_MUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A,

23115

SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set extensions.)

23116

@item bdver2

23117

AMD Family 15h core based CPUs with x86-64 instruction set support. (This

23118

supersets BMI, TBM, F16C, FMA, FMA4, AVX, XOP, LWP, AES, PCL_MUL, CX16, MMX,

23119

SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set

23120

extensions.)

23121

@item bdver3

23122

AMD Family 15h core based CPUs with x86-64 instruction set support. (This

23123

supersets BMI, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, XOP, LWP, AES,

23124

PCL_MUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and

23125

64-bit instruction set extensions.

23126

@item bdver4

23127

AMD Family 15h core based CPUs with x86-64 instruction set support. (This

23128

supersets BMI, BMI2, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, AVX2, XOP, LWP,

23129

AES, PCL_MUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1,

23130

SSE4.2, ABM and 64-bit instruction set extensions.

23131

23132

@item znver1

23133

AMD Family 17h core based CPUs with x86-64 instruction set support. (This

23134

supersets BMI, BMI2, F16C, FMA, FSGSBASE, AVX, AVX2, ADCX, RDSEED, MWAITX,

23135

SHA, CLZERO, AES, PCL_MUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3,

23136

SSE4.1, SSE4.2, ABM, XSAVEC, XSAVES, CLFLUSHOPT, POPCNT, and 64-bit

23137

instruction set extensions.

23138

23139

@item btver1

23140

CPUs based on AMD Family 14h cores with x86-64 instruction set support. (This

23141

supersets MMX, SSE, SSE2, SSE3, SSSE3, SSE4A, CX16, ABM and 64-bit

23142

instruction set extensions.)

23143

23144

@item btver2

23145

CPUs based on AMD Family 16h cores with x86-64 instruction set support. This

23146

includes MOVBE, F16C, BMI, AVX, PCL_MUL, AES, SSE4.2, SSE4.1, CX16, ABM,

23147

SSE4A, SSSE3, SSE3, SSE2, SSE, MMX and 64-bit instruction set extensions.

23148

23149

@item winchip-c6

23150

IDT WinChip C6 CPU, dealt in same way as i486 with additional MMX instruction

23151

set support.

23152

23153

@item winchip2

23154

IDT WinChip 2 CPU, dealt in same way as i486 with additional MMX and 3DNow!@:

23155

instruction set support.

23156

23157

@item c3

23158

VIA C3 CPU with MMX and 3DNow!@: instruction set support. (No scheduling is

23159

implemented for this chip.)

23160

23161

@item c3-2

23162

VIA C3-2 (Nehemiah/C5XL) CPU with MMX and SSE instruction set support.

23163

(No scheduling is

23164

implemented for this chip.)

23165

23166

@item geode

23167

AMD Geode embedded processor with MMX and 3DNow!@: instruction set support.

23168

@end table

23169

23170

@item -mtune=@var{cpu-type}

23171

@opindex mtune

23172

Tune to @var{cpu-type} everything applicable about the generated code, except

23173

for the ABI and the set of available instructions.

23174

While picking a specific @var{cpu-type} schedules things appropriately

23175

for that particular chip, the compiler does not generate any code that

23176

cannot run on the default machine type unless you use a

23177

@option{-march=@var{cpu-type}} option.

23178

For example, if GCC is configured for i686-pc-linux-gnu

23179

then @option{-mtune=pentium4} generates code that is tuned for Pentium 4

23180

but still runs on i686 machines.

23181

23182

The choices for @var{cpu-type} are the same as for @option{-march}.

23183

In addition, @option{-mtune} supports 2 extra choices for @var{cpu-type}:

23184

23185

@table @samp

23186

@item generic

23187

Produce code optimized for the most common IA32/@/AMD64/@/EM64T processors.

23188

If you know the CPU on which your code will run, then you should use

23189

the corresponding @option{-mtune} or @option{-march} option instead of

23190

@option{-mtune=generic}. But, if you do not know exactly what CPU users

23191

of your application will have, then you should use this option.

23192

23193

As new processors are deployed in the marketplace, the behavior of this

23194

option will change. Therefore, if you upgrade to a newer version of

23195

GCC, code generation controlled by this option will change to reflect

23196

the processors

23197

that are most common at the time that version of GCC is released.

23198

23199

There is no @option{-march=generic} option because @option{-march}

23200

indicates the instruction set the compiler can use, and there is no

23201

generic instruction set applicable to all processors. In contrast,

23202

@option{-mtune} indicates the processor (or, in this case, collection of

23203

processors) for which the code is optimized.

23204

23205

@item intel

23206

Produce code optimized for the most current Intel processors, which are

23207

Haswell and Silvermont for this version of GCC. If you know the CPU

23208

on which your code will run, then you should use the corresponding

23209

@option{-mtune} or @option{-march} option instead of @option{-mtune=intel}.

23210

But, if you want your application performs better on both Haswell and

23211

Silvermont, then you should use this option.

23212

23213

As new Intel processors are deployed in the marketplace, the behavior of

23214

this option will change. Therefore, if you upgrade to a newer version of

23215

GCC, code generation controlled by this option will change to reflect

23216

the most current Intel processors at the time that version of GCC is

23217

released.

23218

23219

There is no @option{-march=intel} option because @option{-march} indicates

23220

the instruction set the compiler can use, and there is no common

23221

instruction set applicable to all processors. In contrast,

23222

@option{-mtune} indicates the processor (or, in this case, collection of

23223

processors) for which the code is optimized.

23224

@end table

23225

23226

@item -mcpu=@var{cpu-type}

23227

@opindex mcpu

23228

A deprecated synonym for @option{-mtune}.

23229

23230

@item -mfpmath=@var{unit}

23231

@opindex mfpmath

23232

Generate floating-point arithmetic for selected unit @var{unit}. The choices

23233

for @var{unit} are:

23234

23235

@table @samp

23236

@item 387

23237

Use the standard 387 floating-point coprocessor present on the majority of chips and

23238

emulated otherwise. Code compiled with this option runs almost everywhere.

23239

The temporary results are computed in 80-bit precision instead of the precision

23240

specified by the type, resulting in slightly different results compared to most

23241

of other chips. See @option{-ffloat-store} for more detailed description.

23242

23243

This is the default choice for x86-32 targets.

23244

23245

@item sse

23246

Use scalar floating-point instructions present in the SSE instruction set.

23247

This instruction set is supported by Pentium III and newer chips,

23248

and in the AMD line

23249

by Athlon-4, Athlon XP and Athlon MP chips. The earlier version of the SSE

23250

instruction set supports only single-precision arithmetic, thus the double and

23251

extended-precision arithmetic are still done using 387. A later version, present

23252

only in Pentium 4 and AMD x86-64 chips, supports double-precision

23253

arithmetic too.

23254

23255

For the x86-32 compiler, you must use @option{-march=@var{cpu-type}}, @option{-msse}

23256

or @option{-msse2} switches to enable SSE extensions and make this option

23257

effective. For the x86-64 compiler, these extensions are enabled by default.

23258

23259

The resulting code should be considerably faster in the majority of cases and avoid

23260

the numerical instability problems of 387 code, but may break some existing

23261

code that expects temporaries to be 80 bits.

23262

23263

This is the default choice for the x86-64 compiler.

23264

23265

@item sse,387

23266

@itemx sse+387

23267

@itemx both

23268

Attempt to utilize both instruction sets at once. This effectively doubles the

23269

amount of available registers, and on chips with separate execution units for

23270

387 and SSE the execution resources too. Use this option with care, as it is

23271

still experimental, because the GCC register allocator does not model separate

23272

functional units well, resulting in unstable performance.

23273

@end table

23274

23275

@item -masm=@var{dialect}

23276

@opindex masm=@var{dialect}

23277

Output assembly instructions using selected @var{dialect}. Also affects

23278

which dialect is used for basic @code{asm} (@pxref{Basic Asm}) and

23279

extended @code{asm} (@pxref{Extended Asm}). Supported choices (in dialect

23280

order) are @samp{att} or @samp{intel}. The default is @samp{att}. Darwin does

23281

not support @samp{intel}.

23282

23283

@item -mieee-fp

23284

@itemx -mno-ieee-fp

23285

@opindex mieee-fp

23286

@opindex mno-ieee-fp

23287

Control whether or not the compiler uses IEEE floating-point

23288

comparisons. These correctly handle the case where the result of a

23289

comparison is unordered.

23290

23291

@item -msoft-float

23292

@opindex msoft-float

23293

Generate output containing library calls for floating point.

23294

23295

@strong{Warning:} the requisite libraries are not part of GCC@.

23296

Normally the facilities of the machine's usual C compiler are used, but

23297

this can't be done directly in cross-compilation. You must make your

23298

own arrangements to provide suitable library functions for

23299

cross-compilation.

23300

23301

On machines where a function returns floating-point results in the 80387

23302

register stack, some floating-point opcodes may be emitted even if

23303

@option{-msoft-float} is used.

23304

23305

@item -mno-fp-ret-in-387

23306

@opindex mno-fp-ret-in-387

23307

Do not use the FPU registers for return values of functions.

23308

23309

The usual calling convention has functions return values of types

23310

@code{float} and @code{double} in an FPU register, even if there

23311

is no FPU@. The idea is that the operating system should emulate

23312

an FPU@.

23313

23314

The option @option{-mno-fp-ret-in-387} causes such values to be returned

23315

in ordinary CPU registers instead.

23316

23317

@item -mno-fancy-math-387

23318

@opindex mno-fancy-math-387

23319

Some 387 emulators do not support the @code{sin}, @code{cos} and

23320

@code{sqrt} instructions for the 387. Specify this option to avoid

23321

generating those instructions. This option is the default on

23322

OpenBSD and NetBSD@. This option is overridden when @option{-march}

23323

indicates that the target CPU always has an FPU and so the

23324

instruction does not need emulation. These

23325

instructions are not generated unless you also use the

23326

@option{-funsafe-math-optimizations} switch.

23327

23328

@item -malign-double

23329

@itemx -mno-align-double

23330

@opindex malign-double

23331

@opindex mno-align-double

23332

Control whether GCC aligns @code{double}, @code{long double}, and

23333

@code{long long} variables on a two-word boundary or a one-word

23334

boundary. Aligning @code{double} variables on a two-word boundary

23335

produces code that runs somewhat faster on a Pentium at the

23336

expense of more memory.

23337

23338

On x86-64, @option{-malign-double} is enabled by default.

23339

23340

@strong{Warning:} if you use the @option{-malign-double} switch,

23341

structures containing the above types are aligned differently than

23342

the published application binary interface specifications for the x86-32

23343

and are not binary compatible with structures in code compiled

23344

without that switch.

23345

23346

@item -m96bit-long-double

23347

@itemx -m128bit-long-double

23348

@opindex m96bit-long-double

23349

@opindex m128bit-long-double

23350

These switches control the size of @code{long double} type. The x86-32

23351

application binary interface specifies the size to be 96 bits,

23352

so @option{-m96bit-long-double} is the default in 32-bit mode.

23353

23354

Modern architectures (Pentium and newer) prefer @code{long double}

23355

to be aligned to an 8- or 16-byte boundary. In arrays or structures

23356

conforming to the ABI, this is not possible. So specifying

23357

@option{-m128bit-long-double} aligns @code{long double}

23358

to a 16-byte boundary by padding the @code{long double} with an additional

23359

32-bit zero.

23360

23361

In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as

23362

its ABI specifies that @code{long double} is aligned on 16-byte boundary.

23363

23364

Notice that neither of these options enable any extra precision over the x87

23365

standard of 80 bits for a @code{long double}.

23366

23367

@strong{Warning:} if you override the default value for your target ABI, this

23368

changes the size of

23369

structures and arrays containing @code{long double} variables,

23370

as well as modifying the function calling convention for functions taking

23371

@code{long double}. Hence they are not binary-compatible

23372

with code compiled without that switch.

23373

23374

@item -mlong-double-64

23375

@itemx -mlong-double-80

23376

@itemx -mlong-double-128

23377

@opindex mlong-double-64

23378

@opindex mlong-double-80

23379

@opindex mlong-double-128

23380

These switches control the size of @code{long double} type. A size

23381

of 64 bits makes the @code{long double} type equivalent to the @code{double}

23382

type. This is the default for 32-bit Bionic C library. A size

23383

of 128 bits makes the @code{long double} type equivalent to the

23384

@code{__float128} type. This is the default for 64-bit Bionic C library.

23385

23386

@strong{Warning:} if you override the default value for your target ABI, this

23387

changes the size of

23388

structures and arrays containing @code{long double} variables,

23389

as well as modifying the function calling convention for functions taking

23390

@code{long double}. Hence they are not binary-compatible

23391

with code compiled without that switch.

23392

23393

@item -malign-data=@var{type}

23394

@opindex malign-data

23395

Control how GCC aligns variables. Supported values for @var{type} are

23396

@samp{compat} uses increased alignment value compatible uses GCC 4.8

23397

and earlier, @samp{abi} uses alignment value as specified by the

23398

psABI, and @samp{cacheline} uses increased alignment value to match

23399

the cache line size. @samp{compat} is the default.

23400

23401

@item -mlarge-data-threshold=@var{threshold}

23402

@opindex mlarge-data-threshold

23403

When @option{-mcmodel=medium} is specified, data objects larger than

23404

@var{threshold} are placed in the large data section. This value must be the

23405

same across all objects linked into the binary, and defaults to 65535.

23406

23407

@item -mrtd

23408

@opindex mrtd

23409

Use a different function-calling convention, in which functions that

23410

take a fixed number of arguments return with the @code{ret @var{num}}

23411

instruction, which pops their arguments while returning. This saves one

23412

instruction in the caller since there is no need to pop the arguments

23413

there.

23414

23415

You can specify that an individual function is called with this calling

23416

sequence with the function attribute @code{stdcall}. You can also

23417

override the @option{-mrtd} option by using the function attribute

23418

@code{cdecl}. @xref{Function Attributes}.

23419

23420

@strong{Warning:} this calling convention is incompatible with the one

23421

normally used on Unix, so you cannot use it if you need to call

23422

libraries compiled with the Unix compiler.

23423

23424

Also, you must provide function prototypes for all functions that

23425

take variable numbers of arguments (including @code{printf});

23426

otherwise incorrect code is generated for calls to those

23427

functions.

23428

23429

In addition, seriously incorrect code results if you call a

23430

function with too many arguments. (Normally, extra arguments are

23431

harmlessly ignored.)

23432

23433

@item -mregparm=@var{num}

23434

@opindex mregparm

23435

Control how many registers are used to pass integer arguments. By

23436

default, no registers are used to pass arguments, and at most 3

23437

registers can be used. You can control this behavior for a specific

23438

function by using the function attribute @code{regparm}.

23439

@xref{Function Attributes}.

23440

23441

@strong{Warning:} if you use this switch, and

23442

@var{num} is nonzero, then you must build all modules with the same

23443

value, including any libraries. This includes the system libraries and

23444

startup modules.

23445

23446

@item -msseregparm

23447

@opindex msseregparm

23448

Use SSE register passing conventions for float and double arguments

23449

and return values. You can control this behavior for a specific

23450

function by using the function attribute @code{sseregparm}.

23451

@xref{Function Attributes}.

23452

23453

@strong{Warning:} if you use this switch then you must build all

23454

modules with the same value, including any libraries. This includes

23455

the system libraries and startup modules.

23456

23457

@item -mvect8-ret-in-mem

23458

@opindex mvect8-ret-in-mem

23459

Return 8-byte vectors in memory instead of MMX registers. This is the

23460

default on Solaris@tie{}8 and 9 and VxWorks to match the ABI of the Sun

23461

Studio compilers until version 12. Later compiler versions (starting

23462

with Studio 12 Update@tie{}1) follow the ABI used by other x86 targets, which

23463

is the default on Solaris@tie{}10 and later. @emph{Only} use this option if

23464

you need to remain compatible with existing code produced by those

23465

previous compiler versions or older versions of GCC@.

23466

23467

@item -mpc32

23468

@itemx -mpc64

23469

@itemx -mpc80

23470

@opindex mpc32

23471

@opindex mpc64

23472

@opindex mpc80

23473

23474

Set 80387 floating-point precision to 32, 64 or 80 bits. When @option{-mpc32}

23475

is specified, the significands of results of floating-point operations are

23476

rounded to 24 bits (single precision); @option{-mpc64} rounds the

23477

significands of results of floating-point operations to 53 bits (double

23478

precision) and @option{-mpc80} rounds the significands of results of

23479

floating-point operations to 64 bits (extended double precision), which is

23480

the default. When this option is used, floating-point operations in higher

23481

precisions are not available to the programmer without setting the FPU

23482

control word explicitly.

23483

23484

Setting the rounding of floating-point operations to less than the default

23485

80 bits can speed some programs by 2% or more. Note that some mathematical

23486

libraries assume that extended-precision (80-bit) floating-point operations

23487

are enabled by default; routines in such libraries could suffer significant

23488

loss of accuracy, typically through so-called ``catastrophic cancellation'',

23489

when this option is used to set the precision to less than extended precision.

23490

23491

@item -mstackrealign

23492

@opindex mstackrealign

23493

Realign the stack at entry. On the x86, the @option{-mstackrealign}

23494

option generates an alternate prologue and epilogue that realigns the

23495

run-time stack if necessary. This supports mixing legacy codes that keep

23496

4-byte stack alignment with modern codes that keep 16-byte stack alignment for

23497

SSE compatibility. See also the attribute @code{force_align_arg_pointer},

23498

applicable to individual functions.

23499

23500

@item -mpreferred-stack-boundary=@var{num}

23501

@opindex mpreferred-stack-boundary

23502

Attempt to keep the stack boundary aligned to a 2 raised to @var{num}

23503

byte boundary. If @option{-mpreferred-stack-boundary} is not specified,

23504

the default is 4 (16 bytes or 128 bits).

23505

23506

@strong{Warning:} When generating code for the x86-64 architecture with

23507

SSE extensions disabled, @option{-mpreferred-stack-boundary=3} can be

23508

used to keep the stack boundary aligned to 8 byte boundary. Since

23509

x86-64 ABI require 16 byte stack alignment, this is ABI incompatible and

23510

intended to be used in controlled environment where stack space is

23511

important limitation. This option leads to wrong code when functions

23512

compiled with 16 byte stack alignment (such as functions from a standard

23513

library) are called with misaligned stack. In this case, SSE

23514

instructions may lead to misaligned memory access traps. In addition,

23515

variable arguments are handled incorrectly for 16 byte aligned

23516

objects (including x87 long double and __int128), leading to wrong

23517

results. You must build all modules with

23518

@option{-mpreferred-stack-boundary=3}, including any libraries. This

23519

includes the system libraries and startup modules.

23520

23521

@item -mincoming-stack-boundary=@var{num}

23522

@opindex mincoming-stack-boundary

23523

Assume the incoming stack is aligned to a 2 raised to @var{num} byte

23524

boundary. If @option{-mincoming-stack-boundary} is not specified,

23525

the one specified by @option{-mpreferred-stack-boundary} is used.

23526

23527

On Pentium and Pentium Pro, @code{double} and @code{long double} values

23528

should be aligned to an 8-byte boundary (see @option{-malign-double}) or

23529

suffer significant run time performance penalties. On Pentium III, the

23530

Streaming SIMD Extension (SSE) data type @code{__m128} may not work

23531

properly if it is not 16-byte aligned.

23532

23533

To ensure proper alignment of this values on the stack, the stack boundary

23534

must be as aligned as that required by any value stored on the stack.

23535

Further, every function must be generated such that it keeps the stack

23536

aligned. Thus calling a function compiled with a higher preferred

23537

stack boundary from a function compiled with a lower preferred stack

23538

boundary most likely misaligns the stack. It is recommended that

23539

libraries that use callbacks always use the default setting.

23540

23541

This extra alignment does consume extra stack space, and generally

23542

increases code size. Code that is sensitive to stack space usage, such

23543

as embedded systems and operating system kernels, may want to reduce the

23544

preferred alignment to @option{-mpreferred-stack-boundary=2}.

23545

23546

@need 200

23547

@item -mmmx

23548

@opindex mmmx

23549

@need 200

23550

@itemx -msse

23551

@opindex msse

23552

@need 200

23553

@itemx -msse2

23554

@opindex msse2

23555

@need 200

23556

@itemx -msse3

23557

@opindex msse3

23558

@need 200

23559

@itemx -mssse3

23560

@opindex mssse3

23561

@need 200

23562

@itemx -msse4

23563

@opindex msse4

23564

@need 200

23565

@itemx -msse4a

23566

@opindex msse4a

23567

@need 200

23568

@itemx -msse4.1

23569

@opindex msse4.1

23570

@need 200

23571

@itemx -msse4.2

23572

@opindex msse4.2

23573

@need 200

23574

@itemx -mavx

23575

@opindex mavx

23576

@need 200

23577

@itemx -mavx2

23578

@opindex mavx2

23579

@need 200

23580

@itemx -mavx512f

23581

@opindex mavx512f

23582

@need 200

23583

@itemx -mavx512pf

23584

@opindex mavx512pf

23585

@need 200

23586

@itemx -mavx512er

23587

@opindex mavx512er

23588

@need 200

23589

@itemx -mavx512cd

23590

@opindex mavx512cd

23591

@need 200

23592

@itemx -mavx512vl

23593

@opindex mavx512vl

23594

@need 200

23595

@itemx -mavx512bw

23596

@opindex mavx512bw

23597

@need 200

23598

@itemx -mavx512dq

23599

@opindex mavx512dq

23600

@need 200

23601

@itemx -mavx512ifma

23602

@opindex mavx512ifma

23603

@need 200

23604

@itemx -mavx512vbmi

23605

@opindex mavx512vbmi

23606

@need 200

23607

@itemx -msha

23608

@opindex msha

23609

@need 200

23610

@itemx -maes

23611

@opindex maes

23612

@need 200

23613

@itemx -mpclmul

23614

@opindex mpclmul

23615

@need 200

23616

@itemx -mclfushopt

23617

@opindex mclfushopt

23618

@need 200

23619

@itemx -mfsgsbase

23620

@opindex mfsgsbase

23621

@need 200

23622

@itemx -mrdrnd

23623

@opindex mrdrnd

23624

@need 200

23625

@itemx -mf16c

23626

@opindex mf16c

23627

@need 200

23628

@itemx -mfma

23629

@opindex mfma

23630

@need 200

23631

@itemx -mfma4

23632

@opindex mfma4

23633

@need 200

23634

@itemx -mprefetchwt1

23635

@opindex mprefetchwt1

23636

@need 200

23637

@itemx -mxop

23638

@opindex mxop

23639

@need 200

23640

@itemx -mlwp

23641

@opindex mlwp

23642

@need 200

23643

@itemx -m3dnow

23644

@opindex m3dnow

23645

@need 200

23646

@itemx -mpopcnt

23647

@opindex mpopcnt

23648

@need 200

23649

@itemx -mabm

23650

@opindex mabm

23651

@need 200

23652

@itemx -mbmi

23653

@opindex mbmi

23654

@need 200

23655

@itemx -mbmi2

23656

@need 200

23657

@itemx -mlzcnt

23658

@opindex mlzcnt

23659

@need 200

23660

@itemx -mfxsr

23661

@opindex mfxsr

23662

@need 200

23663

@itemx -mxsave

23664

@opindex mxsave

23665

@need 200

23666

@itemx -mxsaveopt

23667

@opindex mxsaveopt

23668

@need 200

23669

@itemx -mxsavec

23670

@opindex mxsavec

23671

@need 200

23672

@itemx -mxsaves

23673

@opindex mxsaves

23674

@need 200

23675

@itemx -mrtm

23676

@opindex mrtm

23677

@need 200

23678

@itemx -mtbm

23679

@opindex mtbm

23680

@need 200

23681

@itemx -mmpx

23682

@opindex mmpx

23683

@need 200

23684

@itemx -mmwaitx

23685

@opindex mmwaitx

23686

@need 200

23687

@itemx -mclzero

23688

@opindex mclzero

23689

@itemx -mpku

23690

@opindex mpku

23691

These switches enable the use of instructions in the MMX, SSE,

23692

SSE2, SSE3, SSSE3, SSE4.1, AVX, AVX2, AVX512F, AVX512PF, AVX512ER, AVX512CD,

23693

SHA, AES, PCLMUL, FSGSBASE, RDRND, F16C, FMA, SSE4A, FMA4, XOP, LWP, ABM,

23694

AVX512VL, AVX512BW, AVX512DQ, AVX512IFMA AVX512VBMI, BMI, BMI2, FXSR,

23695

XSAVE, XSAVEOPT, LZCNT, RTM, MPX, MWAITX, PKU or 3DNow!@:

23696

extended instruction sets. Each has a corresponding @option{-mno-} option

23697

to disable use of these instructions.

23698

23699

These extensions are also available as built-in functions: see

23700

@ref{x86 Built-in Functions}, for details of the functions enabled and

23701

disabled by these switches.

23702

23703

To generate SSE/SSE2 instructions automatically from floating-point

23704

code (as opposed to 387 instructions), see @option{-mfpmath=sse}.

23705

23706

GCC depresses SSEx instructions when @option{-mavx} is used. Instead, it

23707

generates new AVX instructions or AVX equivalence for all SSEx instructions

23708

when needed.

23709

23710

These options enable GCC to use these extended instructions in

23711

generated code, even without @option{-mfpmath=sse}. Applications that

23712

perform run-time CPU detection must compile separate files for each

23713

supported architecture, using the appropriate flags. In particular,

23714

the file containing the CPU detection code should be compiled without

23715

these options.

23716

23717

@item -mdump-tune-features

23718

@opindex mdump-tune-features

23719

This option instructs GCC to dump the names of the x86 performance

23720

tuning features and default settings. The names can be used in

23721

@option{-mtune-ctrl=@var{feature-list}}.

23722

23723

@item -mtune-ctrl=@var{feature-list}

23724

@opindex mtune-ctrl=@var{feature-list}

23725

This option is used to do fine grain control of x86 code generation features.

23726

@var{feature-list} is a comma separated list of @var{feature} names. See also

23727

@option{-mdump-tune-features}. When specified, the @var{feature} is turned

23728

on if it is not preceded with @samp{^}, otherwise, it is turned off.

23729

@option{-mtune-ctrl=@var{feature-list}} is intended to be used by GCC

23730

developers. Using it may lead to code paths not covered by testing and can

23731

potentially result in compiler ICEs or runtime errors.

23732

23733

@item -mno-default

23734

@opindex mno-default

23735

This option instructs GCC to turn off all tunable features. See also

23736

@option{-mtune-ctrl=@var{feature-list}} and @option{-mdump-tune-features}.

23737

23738

@item -mcld

23739

@opindex mcld

23740

This option instructs GCC to emit a @code{cld} instruction in the prologue

23741

of functions that use string instructions. String instructions depend on

23742

the DF flag to select between autoincrement or autodecrement mode. While the

23743

ABI specifies the DF flag to be cleared on function entry, some operating

23744

systems violate this specification by not clearing the DF flag in their

23745

exception dispatchers. The exception handler can be invoked with the DF flag

23746

set, which leads to wrong direction mode when string instructions are used.

23747

This option can be enabled by default on 32-bit x86 targets by configuring

23748

GCC with the @option{--enable-cld} configure option. Generation of @code{cld}

23749

instructions can be suppressed with the @option{-mno-cld} compiler option

23750

in this case.

23751

23752

@item -mvzeroupper

23753

@opindex mvzeroupper

23754

This option instructs GCC to emit a @code{vzeroupper} instruction

23755

before a transfer of control flow out of the function to minimize

23756

the AVX to SSE transition penalty as well as remove unnecessary @code{zeroupper}

23757

intrinsics.

23758

23759

@item -mprefer-avx128

23760

@opindex mprefer-avx128

23761

This option instructs GCC to use 128-bit AVX instructions instead of

23762

256-bit AVX instructions in the auto-vectorizer.

23763

23764

@item -mcx16

23765

@opindex mcx16

23766

This option enables GCC to generate @code{CMPXCHG16B} instructions.

23767

@code{CMPXCHG16B} allows for atomic operations on 128-bit double quadword

23768

(or oword) data types.

23769

This is useful for high-resolution counters that can be updated

23770

by multiple processors (or cores). This instruction is generated as part of

23771

atomic built-in functions: see @ref{__sync Builtins} or

23772

@ref{__atomic Builtins} for details.

23773

23774

@item -msahf

23775

@opindex msahf

23776

This option enables generation of @code{SAHF} instructions in 64-bit code.

23777

Early Intel Pentium 4 CPUs with Intel 64 support,

23778

prior to the introduction of Pentium 4 G1 step in December 2005,

23779

lacked the @code{LAHF} and @code{SAHF} instructions

23780

which are supported by AMD64.

23781

These are load and store instructions, respectively, for certain status flags.

23782

In 64-bit mode, the @code{SAHF} instruction is used to optimize @code{fmod},

23783

@code{drem}, and @code{remainder} built-in functions;

23784

see @ref{Other Builtins} for details.

23785

23786

@item -mmovbe

23787

@opindex mmovbe

23788

This option enables use of the @code{movbe} instruction to implement

23789

@code{__builtin_bswap32} and @code{__builtin_bswap64}.

23790

23791

@item -mcrc32

23792

@opindex mcrc32

23793

This option enables built-in functions @code{__builtin_ia32_crc32qi},

23794

@code{__builtin_ia32_crc32hi}, @code{__builtin_ia32_crc32si} and

23795

@code{__builtin_ia32_crc32di} to generate the @code{crc32} machine instruction.

23796

23797

@item -mrecip

23798

@opindex mrecip

23799

This option enables use of @code{RCPSS} and @code{RSQRTSS} instructions

23800

(and their vectorized variants @code{RCPPS} and @code{RSQRTPS})

23801

with an additional Newton-Raphson step

23802

to increase precision instead of @code{DIVSS} and @code{SQRTSS}

23803

(and their vectorized

23804

variants) for single-precision floating-point arguments. These instructions

23805

are generated only when @option{-funsafe-math-optimizations} is enabled

23806

together with @option{-ffinite-math-only} and @option{-fno-trapping-math}.

23807

Note that while the throughput of the sequence is higher than the throughput

23808

of the non-reciprocal instruction, the precision of the sequence can be

23809

decreased by up to 2 ulp (i.e. the inverse of 1.0 equals 0.99999994).

23810

23811

Note that GCC implements @code{1.0f/sqrtf(@var{x})} in terms of @code{RSQRTSS}

23812

(or @code{RSQRTPS}) already with @option{-ffast-math} (or the above option

23813

combination), and doesn't need @option{-mrecip}.

23814

23815

Also note that GCC emits the above sequence with additional Newton-Raphson step

23816

for vectorized single-float division and vectorized @code{sqrtf(@var{x})}

23817

already with @option{-ffast-math} (or the above option combination), and

23818

doesn't need @option{-mrecip}.

23819

23820

@item -mrecip=@var{opt}

23821

@opindex mrecip=opt

23822

This option controls which reciprocal estimate instructions

23823

may be used. @var{opt} is a comma-separated list of options, which may

23824

be preceded by a @samp{!} to invert the option:

23825

23826

@table @samp

23827

@item all

23828

Enable all estimate instructions.

23829

23830

@item default

23831

Enable the default instructions, equivalent to @option{-mrecip}.

23832

23833

@item none

23834

Disable all estimate instructions, equivalent to @option{-mno-recip}.

23835

23836

@item div

23837

Enable the approximation for scalar division.

23838

23839

@item vec-div

23840

Enable the approximation for vectorized division.

23841

23842

@item sqrt

23843

Enable the approximation for scalar square root.

23844

23845

@item vec-sqrt

23846

Enable the approximation for vectorized square root.

23847

@end table

23848

23849

So, for example, @option{-mrecip=all,!sqrt} enables

23850

all of the reciprocal approximations, except for square root.

23851

23852

@item -mveclibabi=@var{type}

23853

@opindex mveclibabi

23854

Specifies the ABI type to use for vectorizing intrinsics using an

23855

external library. Supported values for @var{type} are @samp{svml}

23856

for the Intel short

23857

vector math library and @samp{acml} for the AMD math core library.

23858

To use this option, both @option{-ftree-vectorize} and

23859

@option{-funsafe-math-optimizations} have to be enabled, and an SVML or ACML

23860

ABI-compatible library must be specified at link time.

23861

23862

GCC currently emits calls to @code{vmldExp2},

23863

@code{vmldLn2}, @code{vmldLog102}, @code{vmldLog102}, @code{vmldPow2},

23864

@code{vmldTanh2}, @code{vmldTan2}, @code{vmldAtan2}, @code{vmldAtanh2},

23865

@code{vmldCbrt2}, @code{vmldSinh2}, @code{vmldSin2}, @code{vmldAsinh2},

23866

@code{vmldAsin2}, @code{vmldCosh2}, @code{vmldCos2}, @code{vmldAcosh2},

23867

@code{vmldAcos2}, @code{vmlsExp4}, @code{vmlsLn4}, @code{vmlsLog104},

23868

@code{vmlsLog104}, @code{vmlsPow4}, @code{vmlsTanh4}, @code{vmlsTan4},

23869

@code{vmlsAtan4}, @code{vmlsAtanh4}, @code{vmlsCbrt4}, @code{vmlsSinh4},

23870

@code{vmlsSin4}, @code{vmlsAsinh4}, @code{vmlsAsin4}, @code{vmlsCosh4},

23871

@code{vmlsCos4}, @code{vmlsAcosh4} and @code{vmlsAcos4} for corresponding

23872

function type when @option{-mveclibabi=svml} is used, and @code{__vrd2_sin},

23873

@code{__vrd2_cos}, @code{__vrd2_exp}, @code{__vrd2_log}, @code{__vrd2_log2},

23874

@code{__vrd2_log10}, @code{__vrs4_sinf}, @code{__vrs4_cosf},

23875

@code{__vrs4_expf}, @code{__vrs4_logf}, @code{__vrs4_log2f},

23876

@code{__vrs4_log10f} and @code{__vrs4_powf} for the corresponding function type

23877

when @option{-mveclibabi=acml} is used.

23878

23879

@item -mabi=@var{name}

23880

@opindex mabi

23881

Generate code for the specified calling convention. Permissible values

23882

are @samp{sysv} for the ABI used on GNU/Linux and other systems, and

23883

@samp{ms} for the Microsoft ABI. The default is to use the Microsoft

23884

ABI when targeting Microsoft Windows and the SysV ABI on all other systems.

23885

You can control this behavior for specific functions by

23886

using the function attributes @code{ms_abi} and @code{sysv_abi}.

23887

@xref{Function Attributes}.

23888

23889

@item -mtls-dialect=@var{type}

23890

@opindex mtls-dialect

23891

Generate code to access thread-local storage using the @samp{gnu} or

23892

@samp{gnu2} conventions. @samp{gnu} is the conservative default;

23893

@samp{gnu2} is more efficient, but it may add compile- and run-time

23894

requirements that cannot be satisfied on all systems.

23895

23896

@item -mpush-args

23897

@itemx -mno-push-args

23898

@opindex mpush-args

23899

@opindex mno-push-args

23900

Use PUSH operations to store outgoing parameters. This method is shorter

23901

and usually equally fast as method using SUB/MOV operations and is enabled

23902

by default. In some cases disabling it may improve performance because of

23903

improved scheduling and reduced dependencies.

23904

23905

@item -maccumulate-outgoing-args

23906

@opindex maccumulate-outgoing-args

23907

If enabled, the maximum amount of space required for outgoing arguments is

23908

computed in the function prologue. This is faster on most modern CPUs

23909

because of reduced dependencies, improved scheduling and reduced stack usage

23910

when the preferred stack boundary is not equal to 2. The drawback is a notable

23911

increase in code size. This switch implies @option{-mno-push-args}.

23912

23913

@item -mthreads

23914

@opindex mthreads

23915

Support thread-safe exception handling on MinGW. Programs that rely

23916

on thread-safe exception handling must compile and link all code with the

23917

@option{-mthreads} option. When compiling, @option{-mthreads} defines

23918

@option{-D_MT}; when linking, it links in a special thread helper library

23919

@option{-lmingwthrd} which cleans up per-thread exception-handling data.

23920

23921

@item -mms-bitfields

23922

@itemx -mno-ms-bitfields

23923

@opindex mms-bitfields

23924

@opindex mno-ms-bitfields

23925

23926

Enable/disable bit-field layout compatible with the native Microsoft

23927

Windows compiler.

23928

23929

If @code{packed} is used on a structure, or if bit-fields are used,

23930

it may be that the Microsoft ABI lays out the structure differently

23931

than the way GCC normally does. Particularly when moving packed

23932

data between functions compiled with GCC and the native Microsoft compiler

23933

(either via function call or as data in a file), it may be necessary to access

23934

either format.

23935

23936

This option is enabled by default for Microsoft Windows

23937

targets. This behavior can also be controlled locally by use of variable

23938

or type attributes. For more information, see @ref{x86 Variable Attributes}

23939

and @ref{x86 Type Attributes}.

23940

23941

The Microsoft structure layout algorithm is fairly simple with the exception

23942

of the bit-field packing.

23943

The padding and alignment of members of structures and whether a bit-field

23944

can straddle a storage-unit boundary are determine by these rules:

23945

23946

@enumerate

23947

@item Structure members are stored sequentially in the order in which they are

23948

declared: the first member has the lowest memory address and the last member

23949

the highest.

23950

23951

@item Every data object has an alignment requirement. The alignment requirement

23952

for all data except structures, unions, and arrays is either the size of the

23953

object or the current packing size (specified with either the

23954

@code{aligned} attribute or the @code{pack} pragma),

23955

whichever is less. For structures, unions, and arrays,

23956

the alignment requirement is the largest alignment requirement of its members.

23957

Every object is allocated an offset so that:

23958

23959

@smallexample

23960

offset % alignment_requirement == 0

23961

@end smallexample

23962

23963

@item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation

23964

unit if the integral types are the same size and if the next bit-field fits

23965

into the current allocation unit without crossing the boundary imposed by the

23966

common alignment requirements of the bit-fields.

23967

@end enumerate

23968

23969

MSVC interprets zero-length bit-fields in the following ways:

23970

23971

@enumerate

23972

@item If a zero-length bit-field is inserted between two bit-fields that

23973

are normally coalesced, the bit-fields are not coalesced.

23974

23975

For example:

23976

23977

@smallexample

23978

struct

23979

@{

23980

unsigned long bf_1 : 12;

23981

unsigned long : 0;

23982

unsigned long bf_2 : 12;

23983

@} t1;

23984

@end smallexample

23985

23986

@noindent

23987

The size of @code{t1} is 8 bytes with the zero-length bit-field. If the

23988

zero-length bit-field were removed, @code{t1}'s size would be 4 bytes.

23989

23990

@item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the

23991

alignment of the zero-length bit-field is greater than the member that follows it,

23992

@code{bar}, @code{bar} is aligned as the type of the zero-length bit-field.

23993

23994

For example:

23995

23996

@smallexample

23997

struct

23998

@{

23999

char foo : 4;

24000

short : 0;

24001

char bar;

24002

@} t2;

24003

24004

struct

24005

@{

24006

char foo : 4;

24007

short : 0;

24008

double bar;

24009

@} t3;

24010

@end smallexample

24011

24012

@noindent

24013

For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1.

24014

Accordingly, the size of @code{t2} is 4. For @code{t3}, the zero-length

24015

bit-field does not affect the alignment of @code{bar} or, as a result, the size

24016

of the structure.

24017

24018

Taking this into account, it is important to note the following:

24019

24020

@enumerate

24021

@item If a zero-length bit-field follows a normal bit-field, the type of the

24022

zero-length bit-field may affect the alignment of the structure as whole. For

24023

example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a

24024

normal bit-field, and is of type short.

24025

24026

@item Even if a zero-length bit-field is not followed by a normal bit-field, it may

24027

still affect the alignment of the structure:

24028

24029

@smallexample

24030

struct

24031

@{

24032

char foo : 6;

24033

long : 0;

24034

@} t4;

24035

@end smallexample

24036

24037

@noindent

24038

Here, @code{t4} takes up 4 bytes.

24039

@end enumerate

24040

24041

@item Zero-length bit-fields following non-bit-field members are ignored:

24042

24043

@smallexample

24044

struct

24045

@{

24046

char foo;

24047

long : 0;

24048

char bar;

24049

@} t5;

24050

@end smallexample

24051

24052

@noindent

24053

Here, @code{t5} takes up 2 bytes.

24054

@end enumerate

24055

24056

24057

@item -mno-align-stringops

24058

@opindex mno-align-stringops

24059

Do not align the destination of inlined string operations. This switch reduces

24060

code size and improves performance in case the destination is already aligned,

24061

but GCC doesn't know about it.

24062

24063

@item -minline-all-stringops

24064

@opindex minline-all-stringops

24065

By default GCC inlines string operations only when the destination is

24066

known to be aligned to least a 4-byte boundary.

24067

This enables more inlining and increases code

24068

size, but may improve performance of code that depends on fast

24069

@code{memcpy}, @code{strlen},

24070

and @code{memset} for short lengths.

24071

24072

@item -minline-stringops-dynamically

24073

@opindex minline-stringops-dynamically

24074

For string operations of unknown size, use run-time checks with

24075

inline code for small blocks and a library call for large blocks.

24076

24077

@item -mstringop-strategy=@var{alg}

24078

@opindex mstringop-strategy=@var{alg}

24079

Override the internal decision heuristic for the particular algorithm to use

24080

for inlining string operations. The allowed values for @var{alg} are:

24081

24082

@table @samp

24083

@item rep_byte

24084

@itemx rep_4byte

24085

@itemx rep_8byte

24086

Expand using i386 @code{rep} prefix of the specified size.

24087

24088

@item byte_loop

24089

@itemx loop

24090

@itemx unrolled_loop

24091

Expand into an inline loop.

24092

24093

@item libcall

24094

Always use a library call.

24095

@end table

24096

24097

@item -mmemcpy-strategy=@var{strategy}

24098

@opindex mmemcpy-strategy=@var{strategy}

24099

Override the internal decision heuristic to decide if @code{__builtin_memcpy}

24100

should be inlined and what inline algorithm to use when the expected size

24101

of the copy operation is known. @var{strategy}

24102

is a comma-separated list of @var{alg}:@var{max_size}:@var{dest_align} triplets.

24103

@var{alg} is specified in @option{-mstringop-strategy}, @var{max_size} specifies

24104

the max byte size with which inline algorithm @var{alg} is allowed. For the last

24105

triplet, the @var{max_size} must be @code{-1}. The @var{max_size} of the triplets

24106

in the list must be specified in increasing order. The minimal byte size for

24107

@var{alg} is @code{0} for the first triplet and @code{@var{max_size} + 1} of the

24108

preceding range.

24109

24110

@item -mmemset-strategy=@var{strategy}

24111

@opindex mmemset-strategy=@var{strategy}

24112

The option is similar to @option{-mmemcpy-strategy=} except that it is to control

24113

@code{__builtin_memset} expansion.

24114

24115

@item -momit-leaf-frame-pointer

24116

@opindex momit-leaf-frame-pointer

24117

Don't keep the frame pointer in a register for leaf functions. This

24118

avoids the instructions to save, set up, and restore frame pointers and

24119

makes an extra register available in leaf functions. The option

24120

@option{-fomit-leaf-frame-pointer} removes the frame pointer for leaf functions,

24121

which might make debugging harder.

24122

24123

@item -mtls-direct-seg-refs

24124

@itemx -mno-tls-direct-seg-refs

24125

@opindex mtls-direct-seg-refs

24126

Controls whether TLS variables may be accessed with offsets from the

24127

TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),

24128

or whether the thread base pointer must be added. Whether or not this

24129

is valid depends on the operating system, and whether it maps the

24130

segment to cover the entire TLS area.

24131

24132

For systems that use the GNU C Library, the default is on.

24133

24134

@item -msse2avx

24135

@itemx -mno-sse2avx

24136

@opindex msse2avx

24137

Specify that the assembler should encode SSE instructions with VEX

24138

prefix. The option @option{-mavx} turns this on by default.

24139

24140

@item -mfentry

24141

@itemx -mno-fentry

24142

@opindex mfentry

24143

If profiling is active (@option{-pg}), put the profiling

24144

counter call before the prologue.

24145

Note: On x86 architectures the attribute @code{ms_hook_prologue}

24146

isn't possible at the moment for @option{-mfentry} and @option{-pg}.

24147

24148

@item -mrecord-mcount

24149

@itemx -mno-record-mcount

24150

@opindex mrecord-mcount

24151

If profiling is active (@option{-pg}), generate a __mcount_loc section

24152

that contains pointers to each profiling call. This is useful for

24153

automatically patching and out calls.

24154

24155

@item -mnop-mcount

24156

@itemx -mno-nop-mcount

24157

@opindex mnop-mcount

24158

If profiling is active (@option{-pg}), generate the calls to

24159

the profiling functions as nops. This is useful when they

24160

should be patched in later dynamically. This is likely only

24161

useful together with @option{-mrecord-mcount}.

24162

24163

@item -mskip-rax-setup

24164

@itemx -mno-skip-rax-setup

24165

@opindex mskip-rax-setup

24166

When generating code for the x86-64 architecture with SSE extensions

24167

disabled, @option{-mskip-rax-setup} can be used to skip setting up RAX

24168

register when there are no variable arguments passed in vector registers.

24169

24170

@strong{Warning:} Since RAX register is used to avoid unnecessarily

24171

saving vector registers on stack when passing variable arguments, the

24172

impacts of this option are callees may waste some stack space,

24173

misbehave or jump to a random location. GCC 4.4 or newer don't have

24174

those issues, regardless the RAX register value.

24175

24176

@item -m8bit-idiv

24177

@itemx -mno-8bit-idiv

24178

@opindex m8bit-idiv

24179

On some processors, like Intel Atom, 8-bit unsigned integer divide is

24180

much faster than 32-bit/64-bit integer divide. This option generates a

24181

run-time check. If both dividend and divisor are within range of 0

24182

to 255, 8-bit unsigned integer divide is used instead of

24183

32-bit/64-bit integer divide.

24184

24185

@item -mavx256-split-unaligned-load

24186

@itemx -mavx256-split-unaligned-store

24187

@opindex mavx256-split-unaligned-load

24188

@opindex mavx256-split-unaligned-store

24189

Split 32-byte AVX unaligned load and store.

24190

24191

@item -mstack-protector-guard=@var{guard}

24192

@opindex mstack-protector-guard=@var{guard}

24193

Generate stack protection code using canary at @var{guard}. Supported

24194

locations are @samp{global} for global canary or @samp{tls} for per-thread

24195

canary in the TLS block (the default). This option has effect only when

24196

@option{-fstack-protector} or @option{-fstack-protector-all} is specified.

24197

24198

@item -mmitigate-rop

24199

@opindex mmitigate-rop

24200

Try to avoid generating code sequences that contain unintended return

24201

opcodes, to mitigate against certain forms of attack. At the moment,

24202

this option is limited in what it can do and should not be relied

24203

on to provide serious protection.

24204

24205

@end table

24206

24207

These @samp{-m} switches are supported in addition to the above

24208

on x86-64 processors in 64-bit environments.

24209

24210

@table @gcctabopt

24211

@item -m32

24212

@itemx -m64

24213

@itemx -mx32

24214

@itemx -m16

24215

@itemx -miamcu

24216

@opindex m32

24217

@opindex m64

24218

@opindex mx32

24219

@opindex m16

24220

@opindex miamcu

24221

Generate code for a 16-bit, 32-bit or 64-bit environment.

24222

The @option{-m32} option sets @code{int}, @code{long}, and pointer types

24223

to 32 bits, and

24224

generates code that runs on any i386 system.

24225

24226

The @option{-m64} option sets @code{int} to 32 bits and @code{long} and pointer

24227

types to 64 bits, and generates code for the x86-64 architecture.

24228

For Darwin only the @option{-m64} option also turns off the @option{-fno-pic}

24229

and @option{-mdynamic-no-pic} options.

24230

24231

The @option{-mx32} option sets @code{int}, @code{long}, and pointer types

24232

to 32 bits, and

24233

generates code for the x86-64 architecture.

24234

24235

The @option{-m16} option is the same as @option{-m32}, except for that

24236

it outputs the @code{.code16gcc} assembly directive at the beginning of

24237

the assembly output so that the binary can run in 16-bit mode.

24238

24239

The @option{-miamcu} option generates code which conforms to Intel MCU

24240

psABI. It requires the @option{-m32} option to be turned on.

24241

24242

@item -mno-red-zone

24243

@opindex mno-red-zone

24244

Do not use a so-called ``red zone'' for x86-64 code. The red zone is mandated

24245

by the x86-64 ABI; it is a 128-byte area beyond the location of the

24246

stack pointer that is not modified by signal or interrupt handlers

24247

and therefore can be used for temporary data without adjusting the stack

24248

pointer. The flag @option{-mno-red-zone} disables this red zone.

24249

24250

@item -mcmodel=small

24251

@opindex mcmodel=small

24252

Generate code for the small code model: the program and its symbols must

24253

be linked in the lower 2 GB of the address space. Pointers are 64 bits.

24254

Programs can be statically or dynamically linked. This is the default

24255

code model.

24256

24257

@item -mcmodel=kernel

24258

@opindex mcmodel=kernel

24259

Generate code for the kernel code model. The kernel runs in the

24260

negative 2 GB of the address space.

24261

This model has to be used for Linux kernel code.

24262

24263

@item -mcmodel=medium

24264

@opindex mcmodel=medium

24265

Generate code for the medium model: the program is linked in the lower 2

24266

GB of the address space. Small symbols are also placed there. Symbols

24267

with sizes larger than @option{-mlarge-data-threshold} are put into

24268

large data or BSS sections and can be located above 2GB. Programs can

24269

be statically or dynamically linked.

24270

24271

@item -mcmodel=large

24272

@opindex mcmodel=large

24273

Generate code for the large model. This model makes no assumptions

24274

about addresses and sizes of sections.

24275

24276

@item -maddress-mode=long

24277

@opindex maddress-mode=long

24278

Generate code for long address mode. This is only supported for 64-bit

24279

and x32 environments. It is the default address mode for 64-bit

24280

environments.

24281

24282

@item -maddress-mode=short

24283

@opindex maddress-mode=short

24284

Generate code for short address mode. This is only supported for 32-bit

24285

and x32 environments. It is the default address mode for 32-bit and

24286

x32 environments.

24287

@end table

24288

24289

@node x86 Windows Options

24290

@subsection x86 Windows Options

24291

@cindex x86 Windows Options

24292

@cindex Windows Options for x86

24293

24294

These additional options are available for Microsoft Windows targets:

24295

24296

@table @gcctabopt

24297

@item -mconsole

24298

@opindex mconsole

24299

This option

24300

specifies that a console application is to be generated, by

24301

instructing the linker to set the PE header subsystem type

24302

required for console applications.

24303

This option is available for Cygwin and MinGW targets and is

24304

enabled by default on those targets.

24305

24306

@item -mdll

24307

@opindex mdll

24308

This option is available for Cygwin and MinGW targets. It

24309

specifies that a DLL---a dynamic link library---is to be

24310

generated, enabling the selection of the required runtime

24311

startup object and entry point.

24312

24313

@item -mnop-fun-dllimport

24314

@opindex mnop-fun-dllimport

24315

This option is available for Cygwin and MinGW targets. It

24316

specifies that the @code{dllimport} attribute should be ignored.

24317

24318

@item -mthread

24319

@opindex mthread

24320

This option is available for MinGW targets. It specifies

24321

that MinGW-specific thread support is to be used.

24322

24323

@item -municode

24324

@opindex municode

24325

This option is available for MinGW-w64 targets. It causes

24326

the @code{UNICODE} preprocessor macro to be predefined, and

24327

chooses Unicode-capable runtime startup code.

24328

24329

@item -mwin32

24330

@opindex mwin32

24331

This option is available for Cygwin and MinGW targets. It

24332

specifies that the typical Microsoft Windows predefined macros are to

24333

be set in the pre-processor, but does not influence the choice

24334

of runtime library/startup code.

24335

24336

@item -mwindows

24337

@opindex mwindows

24338

This option is available for Cygwin and MinGW targets. It

24339

specifies that a GUI application is to be generated by

24340

instructing the linker to set the PE header subsystem type

24341

appropriately.

24342

24343

@item -fno-set-stack-executable

24344

@opindex fno-set-stack-executable

24345

This option is available for MinGW targets. It specifies that

24346

the executable flag for the stack used by nested functions isn't

24347

set. This is necessary for binaries running in kernel mode of

24348

Microsoft Windows, as there the User32 API, which is used to set executable

24349

privileges, isn't available.

24350

24351

@item -fwritable-relocated-rdata

24352

@opindex fno-writable-relocated-rdata

24353

This option is available for MinGW and Cygwin targets. It specifies

24354

that relocated-data in read-only section is put into the @code{.data}

24355

section. This is a necessary for older runtimes not supporting

24356

modification of @code{.rdata} sections for pseudo-relocation.

24357

24358

@item -mpe-aligned-commons

24359

@opindex mpe-aligned-commons

24360

This option is available for Cygwin and MinGW targets. It

24361

specifies that the GNU extension to the PE file format that

24362

permits the correct alignment of COMMON variables should be

24363

used when generating code. It is enabled by default if

24364

GCC detects that the target assembler found during configuration

24365

supports the feature.

24366

@end table

24367

24368

See also under @ref{x86 Options} for standard options.

24369

24370

@node Xstormy16 Options

24371

@subsection Xstormy16 Options

24372

@cindex Xstormy16 Options

24373

24374

These options are defined for Xstormy16:

24375

24376

@table @gcctabopt

24377

@item -msim

24378

@opindex msim

24379

Choose startup files and linker script suitable for the simulator.

24380

@end table

24381

24382

@node Xtensa Options

24383

@subsection Xtensa Options

24384

@cindex Xtensa Options

24385

24386

These options are supported for Xtensa targets:

24387

24388

@table @gcctabopt

24389

@item -mconst16

24390

@itemx -mno-const16

24391

@opindex mconst16

24392

@opindex mno-const16

24393

Enable or disable use of @code{CONST16} instructions for loading

24394

constant values. The @code{CONST16} instruction is currently not a

24395

standard option from Tensilica. When enabled, @code{CONST16}

24396

instructions are always used in place of the standard @code{L32R}

24397

instructions. The use of @code{CONST16} is enabled by default only if

24398

the @code{L32R} instruction is not available.

24399

24400

@item -mfused-madd

24401

@itemx -mno-fused-madd

24402

@opindex mfused-madd

24403

@opindex mno-fused-madd

24404

Enable or disable use of fused multiply/add and multiply/subtract

24405

instructions in the floating-point option. This has no effect if the

24406

floating-point option is not also enabled. Disabling fused multiply/add

24407

and multiply/subtract instructions forces the compiler to use separate

24408

instructions for the multiply and add/subtract operations. This may be

24409

desirable in some cases where strict IEEE 754-compliant results are

24410

required: the fused multiply add/subtract instructions do not round the

24411

intermediate result, thereby producing results with @emph{more} bits of

24412

precision than specified by the IEEE standard. Disabling fused multiply

24413

add/subtract instructions also ensures that the program output is not

24414

sensitive to the compiler's ability to combine multiply and add/subtract

24415

operations.

24416

24417

@item -mserialize-volatile

24418

@itemx -mno-serialize-volatile

24419

@opindex mserialize-volatile

24420

@opindex mno-serialize-volatile

24421

When this option is enabled, GCC inserts @code{MEMW} instructions before

24422

@code{volatile} memory references to guarantee sequential consistency.

24423

The default is @option{-mserialize-volatile}. Use

24424

@option{-mno-serialize-volatile} to omit the @code{MEMW} instructions.

24425

24426

@item -mforce-no-pic

24427

@opindex mforce-no-pic

24428

For targets, like GNU/Linux, where all user-mode Xtensa code must be

24429

position-independent code (PIC), this option disables PIC for compiling

24430

kernel code.

24431

24432

@item -mtext-section-literals

24433

@itemx -mno-text-section-literals

24434

@opindex mtext-section-literals

24435

@opindex mno-text-section-literals

24436

These options control the treatment of literal pools. The default is

24437

@option{-mno-text-section-literals}, which places literals in a separate

24438

section in the output file. This allows the literal pool to be placed

24439

in a data RAM/ROM, and it also allows the linker to combine literal

24440

pools from separate object files to remove redundant literals and

24441

improve code size. With @option{-mtext-section-literals}, the literals

24442

are interspersed in the text section in order to keep them as close as

24443

possible to their references. This may be necessary for large assembly

24444

files. Literals for each function are placed right before that function.

24445

24446

@item -mauto-litpools

24447

@itemx -mno-auto-litpools

24448

@opindex mauto-litpools

24449

@opindex mno-auto-litpools

24450

These options control the treatment of literal pools. The default is

24451

@option{-mno-auto-litpools}, which places literals in a separate

24452

section in the output file unless @option{-mtext-section-literals} is

24453

used. With @option{-mauto-litpools} the literals are interspersed in

24454

the text section by the assembler. Compiler does not produce explicit

24455

@code{.literal} directives and loads literals into registers with

24456

@code{MOVI} instructions instead of @code{L32R} to let the assembler

24457

do relaxation and place literals as necessary. This option allows

24458

assembler to create several literal pools per function and assemble

24459

very big functions, which may not be possible with

24460

@option{-mtext-section-literals}.

24461

24462

@item -mtarget-align

24463

@itemx -mno-target-align

24464

@opindex mtarget-align

24465

@opindex mno-target-align

24466

When this option is enabled, GCC instructs the assembler to

24467

automatically align instructions to reduce branch penalties at the

24468

expense of some code density. The assembler attempts to widen density

24469

instructions to align branch targets and the instructions following call

24470

instructions. If there are not enough preceding safe density

24471

instructions to align a target, no widening is performed. The

24472

default is @option{-mtarget-align}. These options do not affect the

24473

treatment of auto-aligned instructions like @code{LOOP}, which the

24474

assembler always aligns, either by widening density instructions or

24475

by inserting NOP instructions.

24476

24477

@item -mlongcalls

24478

@itemx -mno-longcalls

24479

@opindex mlongcalls

24480

@opindex mno-longcalls

24481

When this option is enabled, GCC instructs the assembler to translate

24482

direct calls to indirect calls unless it can determine that the target

24483

of a direct call is in the range allowed by the call instruction. This

24484

translation typically occurs for calls to functions in other source

24485

files. Specifically, the assembler translates a direct @code{CALL}

24486

instruction into an @code{L32R} followed by a @code{CALLX} instruction.

24487

The default is @option{-mno-longcalls}. This option should be used in

24488

programs where the call target can potentially be out of range. This

24489

option is implemented in the assembler, not the compiler, so the

24490

assembly code generated by GCC still shows direct call

24491

instructions---look at the disassembled object code to see the actual

24492

instructions. Note that the assembler uses an indirect call for

24493

every cross-file call, not just those that really are out of range.

24494

@end table

24495

24496

@node zSeries Options

24497

@subsection zSeries Options

24498

@cindex zSeries options

24499

24500

These are listed under @xref{S/390 and zSeries Options}.

24501

24502

24503

@c man end

24504

24505

@node Spec Files

24506

@section Specifying Subprocesses and the Switches to Pass to Them

24507

@cindex Spec Files

24508

24509

@command{gcc} is a driver program. It performs its job by invoking a

24510

sequence of other programs to do the work of compiling, assembling and

24511

linking. GCC interprets its command-line parameters and uses these to

24512

deduce which programs it should invoke, and which command-line options

24513

it ought to place on their command lines. This behavior is controlled

24514

by @dfn{spec strings}. In most cases there is one spec string for each

24515

program that GCC can invoke, but a few programs have multiple spec

24516

strings to control their behavior. The spec strings built into GCC can

24517

be overridden by using the @option{-specs=} command-line switch to specify

24518

a spec file.

24519

24520

@dfn{Spec files} are plain-text files that are used to construct spec

24521

strings. They consist of a sequence of directives separated by blank

24522

lines. The type of directive is determined by the first non-whitespace

24523

character on the line, which can be one of the following:

24524

24525

@table @code

24526

@item %@var{command}

24527

Issues a @var{command} to the spec file processor. The commands that can

24528

appear here are:

24529

24530

@table @code

24531

@item %include <@var{file}>

24532

@cindex @code{%include}

24533

Search for @var{file} and insert its text at the current point in the

24534

specs file.

24535

24536

@item %include_noerr <@var{file}>

24537

@cindex @code{%include_noerr}

24538

Just like @samp{%include}, but do not generate an error message if the include

24539

file cannot be found.

24540

24541

@item %rename @var{old_name} @var{new_name}

24542

@cindex @code{%rename}

24543

Rename the spec string @var{old_name} to @var{new_name}.

24544

24545

@end table

24546

24547

@item *[@var{spec_name}]:

24548

This tells the compiler to create, override or delete the named spec

24549

string. All lines after this directive up to the next directive or

24550

blank line are considered to be the text for the spec string. If this

24551

results in an empty string then the spec is deleted. (Or, if the

24552

spec did not exist, then nothing happens.) Otherwise, if the spec

24553

does not currently exist a new spec is created. If the spec does

24554

exist then its contents are overridden by the text of this

24555

directive, unless the first character of that text is the @samp{+}

24556

character, in which case the text is appended to the spec.

24557

24558

@item [@var{suffix}]:

24559

Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive

24560

and up to the next directive or blank line are considered to make up the

24561

spec string for the indicated suffix. When the compiler encounters an

24562

input file with the named suffix, it processes the spec string in

24563

order to work out how to compile that file. For example:

24564

24565

@smallexample

24566

.ZZ:

24567

z-compile -input %i

24568

@end smallexample

24569

24570

This says that any input file whose name ends in @samp{.ZZ} should be

24571

passed to the program @samp{z-compile}, which should be invoked with the

24572

command-line switch @option{-input} and with the result of performing the

24573

@samp{%i} substitution. (See below.)

24574

24575

As an alternative to providing a spec string, the text following a

24576

suffix directive can be one of the following:

24577

24578

@table @code

24579

@item @@@var{language}

24580

This says that the suffix is an alias for a known @var{language}. This is

24581

similar to using the @option{-x} command-line switch to GCC to specify a

24582

language explicitly. For example:

24583

24584

@smallexample

24585

.ZZ:

24586

@@c++

24587

@end smallexample

24588

24589

Says that .ZZ files are, in fact, C++ source files.

24590

24591

@item #@var{name}

24592

This causes an error messages saying:

24593

24594

@smallexample

24595

@var{name} compiler not installed on this system.

24596

@end smallexample

24597

@end table

24598

24599

GCC already has an extensive list of suffixes built into it.

24600

This directive adds an entry to the end of the list of suffixes, but

24601

since the list is searched from the end backwards, it is effectively

24602

possible to override earlier entries using this technique.

24603

24604

@end table

24605

24606

GCC has the following spec strings built into it. Spec files can

24607

override these strings or create their own. Note that individual

24608

targets can also add their own spec strings to this list.

24609

24610

@smallexample

24611

asm Options to pass to the assembler

24612

asm_final Options to pass to the assembler post-processor

24613

cpp Options to pass to the C preprocessor

24614

cc1 Options to pass to the C compiler

24615

cc1plus Options to pass to the C++ compiler

24616

endfile Object files to include at the end of the link

24617

link Options to pass to the linker

24618

lib Libraries to include on the command line to the linker

24619

libgcc Decides which GCC support library to pass to the linker

24620

linker Sets the name of the linker

24621

predefines Defines to be passed to the C preprocessor

24622

signed_char Defines to pass to CPP to say whether @code{char} is signed

24623

by default

24624

startfile Object files to include at the start of the link

24625

@end smallexample

24626

24627

Here is a small example of a spec file:

24628

24629

@smallexample

24630

%rename lib old_lib

24631

24632

*lib:

24633

--start-group -lgcc -lc -leval1 --end-group %(old_lib)

24634

@end smallexample

24635

24636

This example renames the spec called @samp{lib} to @samp{old_lib} and

24637

then overrides the previous definition of @samp{lib} with a new one.

24638

The new definition adds in some extra command-line options before

24639

including the text of the old definition.

24640

24641

@dfn{Spec strings} are a list of command-line options to be passed to their

24642

corresponding program. In addition, the spec strings can contain

24643

@samp{%}-prefixed sequences to substitute variable text or to

24644

conditionally insert text into the command line. Using these constructs

24645

it is possible to generate quite complex command lines.

24646

24647

Here is a table of all defined @samp{%}-sequences for spec

24648

strings. Note that spaces are not generated automatically around the

24649

results of expanding these sequences. Therefore you can concatenate them

24650

together or combine them with constant text in a single argument.

24651

24652

@table @code

24653

@item %%

24654

Substitute one @samp{%} into the program name or argument.

24655

24656

@item %i

24657

Substitute the name of the input file being processed.

24658

24659

@item %b

24660

Substitute the basename of the input file being processed.

24661

This is the substring up to (and not including) the last period

24662

and not including the directory.

24663

24664

@item %B

24665

This is the same as @samp{%b}, but include the file suffix (text after

24666

the last period).

24667

24668

@item %d

24669

Marks the argument containing or following the @samp{%d} as a

24670

temporary file name, so that that file is deleted if GCC exits

24671

successfully. Unlike @samp{%g}, this contributes no text to the

24672

argument.

24673

24674

@item %g@var{suffix}

24675

Substitute a file name that has suffix @var{suffix} and is chosen

24676

once per compilation, and mark the argument in the same way as

24677

@samp{%d}. To reduce exposure to denial-of-service attacks, the file

24678

name is now chosen in a way that is hard to predict even when previously

24679

chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}

24680

might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches

24681

the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is

24682

treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}

24683

was simply substituted with a file name chosen once per compilation,

24684

without regard to any appended suffix (which was therefore treated

24685

just like ordinary text), making such attacks more likely to succeed.

24686

24687

@item %u@var{suffix}

24688

Like @samp{%g}, but generates a new temporary file name

24689

each time it appears instead of once per compilation.

24690

24691

@item %U@var{suffix}

24692

Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a

24693

new one if there is no such last file name. In the absence of any

24694

@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share

24695

the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}

24696

involves the generation of two distinct file names, one

24697

for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was

24698

simply substituted with a file name chosen for the previous @samp{%u},

24699

without regard to any appended suffix.

24700

24701

@item %j@var{suffix}

24702

Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is

24703

writable, and if @option{-save-temps} is not used;

24704

otherwise, substitute the name

24705

of a temporary file, just like @samp{%u}. This temporary file is not

24706

meant for communication between processes, but rather as a junk

24707

disposal mechanism.

24708

24709

@item %|@var{suffix}

24710

@itemx %m@var{suffix}

24711

Like @samp{%g}, except if @option{-pipe} is in effect. In that case

24712

@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at

24713

all. These are the two most common ways to instruct a program that it

24714

should read from standard input or write to standard output. If you

24715

need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}

24716

construct: see for example @file{f/lang-specs.h}.

24717

24718

@item %.@var{SUFFIX}

24719

Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args

24720

when it is subsequently output with @samp{%*}. @var{SUFFIX} is

24721

terminated by the next space or %.

24722

24723

@item %w

24724

Marks the argument containing or following the @samp{%w} as the

24725

designated output file of this compilation. This puts the argument

24726

into the sequence of arguments that @samp{%o} substitutes.

24727

24728

@item %o

24729

Substitutes the names of all the output files, with spaces

24730

automatically placed around them. You should write spaces

24731

around the @samp{%o} as well or the results are undefined.

24732

@samp{%o} is for use in the specs for running the linker.

24733

Input files whose names have no recognized suffix are not compiled

24734

at all, but they are included among the output files, so they are

24735

linked.

24736

24737

@item %O

24738

Substitutes the suffix for object files. Note that this is

24739

handled specially when it immediately follows @samp{%g, %u, or %U},

24740

because of the need for those to form complete file names. The

24741

handling is such that @samp{%O} is treated exactly as if it had already

24742

been substituted, except that @samp{%g, %u, and %U} do not currently

24743

support additional @var{suffix} characters following @samp{%O} as they do

24744

following, for example, @samp{.o}.

24745

24746

@item %p

24747

Substitutes the standard macro predefinitions for the

24748

current target machine. Use this when running @command{cpp}.

24749

24750

@item %P

24751

Like @samp{%p}, but puts @samp{__} before and after the name of each

24752

predefined macro, except for macros that start with @samp{__} or with

24753

@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO

24754

C@.

24755

24756

@item %I

24757

Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),

24758

@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),

24759

@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)

24760

and @option{-imultilib} as necessary.

24761

24762

@item %s

24763

Current argument is the name of a library or startup file of some sort.

24764

Search for that file in a standard list of directories and substitute

24765

the full name found. The current working directory is included in the

24766

list of directories scanned.

24767

24768

@item %T

24769

Current argument is the name of a linker script. Search for that file

24770

in the current list of directories to scan for libraries. If the file

24771

is located insert a @option{--script} option into the command line

24772

followed by the full path name found. If the file is not found then

24773

generate an error message. Note: the current working directory is not

24774

searched.

24775

24776

@item %e@var{str}

24777

Print @var{str} as an error message. @var{str} is terminated by a newline.

24778

Use this when inconsistent options are detected.

24779

24780

@item %(@var{name})

24781

Substitute the contents of spec string @var{name} at this point.

24782

24783

@item %x@{@var{option}@}

24784

Accumulate an option for @samp{%X}.

24785

24786

@item %X

24787

Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}

24788

spec string.

24789

24790

@item %Y

24791

Output the accumulated assembler options specified by @option{-Wa}.

24792

24793

@item %Z

24794

Output the accumulated preprocessor options specified by @option{-Wp}.

24795

24796

@item %a

24797

Process the @code{asm} spec. This is used to compute the

24798

switches to be passed to the assembler.

24799

24800

@item %A

24801

Process the @code{asm_final} spec. This is a spec string for

24802

passing switches to an assembler post-processor, if such a program is

24803

needed.

24804

24805

@item %l

24806

Process the @code{link} spec. This is the spec for computing the

24807

command line passed to the linker. Typically it makes use of the

24808

@samp{%L %G %S %D and %E} sequences.

24809

24810

@item %D

24811

Dump out a @option{-L} option for each directory that GCC believes might

24812

contain startup files. If the target supports multilibs then the

24813

current multilib directory is prepended to each of these paths.

24814

24815

@item %L

24816

Process the @code{lib} spec. This is a spec string for deciding which

24817

libraries are included on the command line to the linker.

24818

24819

@item %G

24820

Process the @code{libgcc} spec. This is a spec string for deciding

24821

which GCC support library is included on the command line to the linker.

24822

24823

@item %S

24824

Process the @code{startfile} spec. This is a spec for deciding which

24825

object files are the first ones passed to the linker. Typically

24826

this might be a file named @file{crt0.o}.

24827

24828

@item %E

24829

Process the @code{endfile} spec. This is a spec string that specifies

24830

the last object files that are passed to the linker.

24831

24832

@item %C

24833

Process the @code{cpp} spec. This is used to construct the arguments

24834

to be passed to the C preprocessor.

24835

24836

@item %1

24837

Process the @code{cc1} spec. This is used to construct the options to be

24838

passed to the actual C compiler (@command{cc1}).

24839

24840

@item %2

24841

Process the @code{cc1plus} spec. This is used to construct the options to be

24842

passed to the actual C++ compiler (@command{cc1plus}).

24843

24844

@item %*

24845

Substitute the variable part of a matched option. See below.

24846

Note that each comma in the substituted string is replaced by

24847

a single space.

24848

24849

@item %<@code{S}

24850

Remove all occurrences of @code{-S} from the command line. Note---this

24851

command is position dependent. @samp{%} commands in the spec string

24852

before this one see @code{-S}, @samp{%} commands in the spec string

24853

after this one do not.

24854

24855

@item %:@var{function}(@var{args})

24856

Call the named function @var{function}, passing it @var{args}.

24857

@var{args} is first processed as a nested spec string, then split

24858

into an argument vector in the usual fashion. The function returns

24859

a string which is processed as if it had appeared literally as part

24860

of the current spec.

24861

24862

The following built-in spec functions are provided:

24863

24864

@table @code

24865

@item @code{getenv}

24866

The @code{getenv} spec function takes two arguments: an environment

24867

variable name and a string. If the environment variable is not

24868

defined, a fatal error is issued. Otherwise, the return value is the

24869

value of the environment variable concatenated with the string. For

24870

example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:

24871

24872

@smallexample

24873

%:getenv(TOPDIR /include)

24874

@end smallexample

24875

24876

expands to @file{/path/to/top/include}.

24877

24878

@item @code{if-exists}

24879

The @code{if-exists} spec function takes one argument, an absolute

24880

pathname to a file. If the file exists, @code{if-exists} returns the

24881

pathname. Here is a small example of its usage:

24882

24883

@smallexample

24884

*startfile:

24885

crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s

24886

@end smallexample

24887

24888

@item @code{if-exists-else}

24889

The @code{if-exists-else} spec function is similar to the @code{if-exists}

24890

spec function, except that it takes two arguments. The first argument is

24891

an absolute pathname to a file. If the file exists, @code{if-exists-else}

24892

returns the pathname. If it does not exist, it returns the second argument.

24893

This way, @code{if-exists-else} can be used to select one file or another,

24894

based on the existence of the first. Here is a small example of its usage:

24895

24896

@smallexample

24897

*startfile:

24898

crt0%O%s %:if-exists(crti%O%s) \

24899

%:if-exists-else(crtbeginT%O%s crtbegin%O%s)

24900

@end smallexample

24901

24902

@item @code{replace-outfile}

24903

The @code{replace-outfile} spec function takes two arguments. It looks for the

24904

first argument in the outfiles array and replaces it with the second argument. Here

24905

is a small example of its usage:

24906

24907

@smallexample

24908

%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}

24909

@end smallexample

24910

24911

@item @code{remove-outfile}

24912

The @code{remove-outfile} spec function takes one argument. It looks for the

24913

first argument in the outfiles array and removes it. Here is a small example

24914

its usage:

24915

24916

@smallexample

24917

%:remove-outfile(-lm)

24918

@end smallexample

24919

24920

@item @code{pass-through-libs}

24921

The @code{pass-through-libs} spec function takes any number of arguments. It

24922

finds any @option{-l} options and any non-options ending in @file{.a} (which it

24923

assumes are the names of linker input library archive files) and returns a

24924

result containing all the found arguments each prepended by

24925

@option{-plugin-opt=-pass-through=} and joined by spaces. This list is

24926

intended to be passed to the LTO linker plugin.

24927

24928

@smallexample

24929

%:pass-through-libs(%G %L %G)

24930

@end smallexample

24931

24932

@item @code{print-asm-header}

24933

The @code{print-asm-header} function takes no arguments and simply

24934

prints a banner like:

24935

24936

@smallexample

24937

Assembler options

24938

=================

24939

24940

Use "-Wa,OPTION" to pass "OPTION" to the assembler.

24941

@end smallexample

24942

24943

It is used to separate compiler options from assembler options

24944

in the @option{--target-help} output.

24945

@end table

24946

24947

@item %@{@code{S}@}

24948

Substitutes the @code{-S} switch, if that switch is given to GCC@.

24949

If that switch is not specified, this substitutes nothing. Note that

24950

the leading dash is omitted when specifying this option, and it is

24951

automatically inserted if the substitution is performed. Thus the spec

24952

string @samp{%@{foo@}} matches the command-line option @option{-foo}

24953

and outputs the command-line option @option{-foo}.

24954

24955

@item %W@{@code{S}@}

24956

Like %@{@code{S}@} but mark last argument supplied within as a file to be

24957

deleted on failure.

24958

24959

@item %@{@code{S}*@}

24960

Substitutes all the switches specified to GCC whose names start

24961

with @code{-S}, but which also take an argument. This is used for

24962

switches like @option{-o}, @option{-D}, @option{-I}, etc.

24963

GCC considers @option{-o foo} as being

24964

one switch whose name starts with @samp{o}. %@{o*@} substitutes this

24965

text, including the space. Thus two arguments are generated.

24966

24967

@item %@{@code{S}*&@code{T}*@}

24968

Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options

24969

(the order of @code{S} and @code{T} in the spec is not significant).

24970

There can be any number of ampersand-separated variables; for each the

24971

wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.

24972

24973

@item %@{@code{S}:@code{X}@}

24974

Substitutes @code{X}, if the @option{-S} switch is given to GCC@.

24975

24976

@item %@{!@code{S}:@code{X}@}

24977

Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.

24978

24979

@item %@{@code{S}*:@code{X}@}

24980

Substitutes @code{X} if one or more switches whose names start with

24981

@code{-S} are specified to GCC@. Normally @code{X} is substituted only

24982

once, no matter how many such switches appeared. However, if @code{%*}

24983

appears somewhere in @code{X}, then @code{X} is substituted once

24984

for each matching switch, with the @code{%*} replaced by the part of

24985

that switch matching the @code{*}.

24986

24987

If @code{%*} appears as the last part of a spec sequence then a space

24988

is added after the end of the last substitution. If there is more

24989

text in the sequence, however, then a space is not generated. This

24990

allows the @code{%*} substitution to be used as part of a larger

24991

string. For example, a spec string like this:

24992

24993

@smallexample

24994

%@{mcu=*:--script=%*/memory.ld@}

24995

@end smallexample

24996

24997

@noindent

24998

when matching an option like @option{-mcu=newchip} produces:

24999

25000

@smallexample

25001

--script=newchip/memory.ld

25002

@end smallexample

25003

25004

@item %@{.@code{S}:@code{X}@}

25005

Substitutes @code{X}, if processing a file with suffix @code{S}.

25006

25007

@item %@{!.@code{S}:@code{X}@}

25008

Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.

25009

25010

@item %@{,@code{S}:@code{X}@}

25011

Substitutes @code{X}, if processing a file for language @code{S}.

25012

25013

@item %@{!,@code{S}:@code{X}@}

25014

Substitutes @code{X}, if not processing a file for language @code{S}.

25015

25016

@item %@{@code{S}|@code{P}:@code{X}@}

25017

Substitutes @code{X} if either @code{-S} or @code{-P} is given to

25018

GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and

25019

@code{*} sequences as well, although they have a stronger binding than

25020

the @samp{|}. If @code{%*} appears in @code{X}, all of the

25021

alternatives must be starred, and only the first matching alternative

25022

is substituted.

25023

25024

For example, a spec string like this:

25025

25026

@smallexample

25027

%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}

25028

@end smallexample

25029

25030

@noindent

25031

outputs the following command-line options from the following input

25032

command-line options:

25033

25034

@smallexample

25035

fred.c -foo -baz

25036

jim.d -bar -boggle

25037

-d fred.c -foo -baz -boggle

25038

-d jim.d -bar -baz -boggle

25039

@end smallexample

25040

25041

@item %@{S:X; T:Y; :D@}

25042

25043

If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is

25044

given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can

25045

be as many clauses as you need. This may be combined with @code{.},

25046

@code{,}, @code{!}, @code{|}, and @code{*} as needed.

25047

25048

25049

@end table

25050

25051

The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar

25052

construct may contain other nested @samp{%} constructs or spaces, or

25053

even newlines. They are processed as usual, as described above.

25054

Trailing white space in @code{X} is ignored. White space may also

25055

appear anywhere on the left side of the colon in these constructs,

25056

except between @code{.} or @code{*} and the corresponding word.

25057

25058

The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are

25059

handled specifically in these constructs. If another value of

25060

@option{-O} or the negated form of a @option{-f}, @option{-m}, or

25061

@option{-W} switch is found later in the command line, the earlier

25062

switch value is ignored, except with @{@code{S}*@} where @code{S} is

25063

just one letter, which passes all matching options.

25064

25065

The character @samp{|} at the beginning of the predicate text is used to

25066

indicate that a command should be piped to the following command, but

25067

only if @option{-pipe} is specified.

25068

25069

It is built into GCC which switches take arguments and which do not.

25070

(You might think it would be useful to generalize this to allow each

25071

compiler's spec to say which switches take arguments. But this cannot

25072

be done in a consistent fashion. GCC cannot even decide which input

25073

files have been specified without knowing which switches take arguments,

25074

and it must know which input files to compile in order to tell which

25075

compilers to run).

25076

25077

GCC also knows implicitly that arguments starting in @option{-l} are to be

25078

treated as compiler output files, and passed to the linker in their

25079

proper position among the other output files.

25080

25081

@node Environment Variables

25082

@section Environment Variables Affecting GCC

25083

@cindex environment variables

25084

25085

@c man begin ENVIRONMENT

25086

This section describes several environment variables that affect how GCC

25087

operates. Some of them work by specifying directories or prefixes to use

25088

when searching for various kinds of files. Some are used to specify other

25089

aspects of the compilation environment.

25090

25091

Note that you can also specify places to search using options such as

25092

@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These

25093

take precedence over places specified using environment variables, which

25094

in turn take precedence over those specified by the configuration of GCC@.

25095

@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,

25096

GNU Compiler Collection (GCC) Internals}.

25097

25098

@table @env

25099

@item LANG

25100

@itemx LC_CTYPE

25101

@c @itemx LC_COLLATE

25102

@itemx LC_MESSAGES

25103

@c @itemx LC_MONETARY

25104

@c @itemx LC_NUMERIC

25105

@c @itemx LC_TIME

25106

@itemx LC_ALL

25107

@findex LANG

25108

@findex LC_CTYPE

25109

@c @findex LC_COLLATE

25110

@findex LC_MESSAGES

25111

@c @findex LC_MONETARY

25112

@c @findex LC_NUMERIC

25113

@c @findex LC_TIME

25114

@findex LC_ALL

25115

@cindex locale

25116

These environment variables control the way that GCC uses

25117

localization information which allows GCC to work with different

25118

national conventions. GCC inspects the locale categories

25119

@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do

25120

so. These locale categories can be set to any value supported by your

25121

installation. A typical value is @samp{en_GB.UTF-8} for English in the United

25122

Kingdom encoded in UTF-8.

25123

25124

The @env{LC_CTYPE} environment variable specifies character

25125

classification. GCC uses it to determine the character boundaries in

25126

a string; this is needed for some multibyte encodings that contain quote

25127

and escape characters that are otherwise interpreted as a string

25128

end or escape.

25129

25130

The @env{LC_MESSAGES} environment variable specifies the language to

25131

use in diagnostic messages.

25132

25133

If the @env{LC_ALL} environment variable is set, it overrides the value

25134

of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}

25135

and @env{LC_MESSAGES} default to the value of the @env{LANG}

25136

environment variable. If none of these variables are set, GCC

25137

defaults to traditional C English behavior.

25138

25139

@item TMPDIR

25140

@findex TMPDIR

25141

If @env{TMPDIR} is set, it specifies the directory to use for temporary

25142

files. GCC uses temporary files to hold the output of one stage of

25143

compilation which is to be used as input to the next stage: for example,

25144

the output of the preprocessor, which is the input to the compiler

25145

proper.

25146

25147

@item GCC_COMPARE_DEBUG

25148

@findex GCC_COMPARE_DEBUG

25149

Setting @env{GCC_COMPARE_DEBUG} is nearly equivalent to passing

25150

@option{-fcompare-debug} to the compiler driver. See the documentation

25151

of this option for more details.

25152

25153

@item GCC_EXEC_PREFIX

25154

@findex GCC_EXEC_PREFIX

25155

If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the

25156

names of the subprograms executed by the compiler. No slash is added

25157

when this prefix is combined with the name of a subprogram, but you can

25158

specify a prefix that ends with a slash if you wish.

25159

25160

If @env{GCC_EXEC_PREFIX} is not set, GCC attempts to figure out

25161

an appropriate prefix to use based on the pathname it is invoked with.

25162

25163

If GCC cannot find the subprogram using the specified prefix, it

25164

tries looking in the usual places for the subprogram.

25165

25166

The default value of @env{GCC_EXEC_PREFIX} is

25167

@file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to

25168

the installed compiler. In many cases @var{prefix} is the value

25169

of @code{prefix} when you ran the @file{configure} script.

25170

25171

Other prefixes specified with @option{-B} take precedence over this prefix.

25172

25173

This prefix is also used for finding files such as @file{crt0.o} that are

25174

used for linking.

25175

25176

In addition, the prefix is used in an unusual way in finding the

25177

directories to search for header files. For each of the standard

25178

directories whose name normally begins with @samp{/usr/local/lib/gcc}

25179

(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries

25180

replacing that beginning with the specified prefix to produce an

25181

alternate directory name. Thus, with @option{-Bfoo/}, GCC searches

25182

@file{foo/bar} just before it searches the standard directory

25183

@file{/usr/local/lib/bar}.

25184

If a standard directory begins with the configured

25185

@var{prefix} then the value of @var{prefix} is replaced by

25186

@env{GCC_EXEC_PREFIX} when looking for header files.

25187

25188

@item COMPILER_PATH

25189

@findex COMPILER_PATH

25190

The value of @env{COMPILER_PATH} is a colon-separated list of

25191

directories, much like @env{PATH}. GCC tries the directories thus

25192

specified when searching for subprograms, if it can't find the

25193

subprograms using @env{GCC_EXEC_PREFIX}.

25194

25195

@item LIBRARY_PATH

25196

@findex LIBRARY_PATH

25197

The value of @env{LIBRARY_PATH} is a colon-separated list of

25198

directories, much like @env{PATH}. When configured as a native compiler,

25199

GCC tries the directories thus specified when searching for special

25200

linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking

25201

using GCC also uses these directories when searching for ordinary

25202

libraries for the @option{-l} option (but directories specified with

25203

@option{-L} come first).

25204

25205

@item LANG

25206

@findex LANG

25207

@cindex locale definition

25208

This variable is used to pass locale information to the compiler. One way in

25209

which this information is used is to determine the character set to be used

25210

when character literals, string literals and comments are parsed in C and C++.

25211

When the compiler is configured to allow multibyte characters,

25212

the following values for @env{LANG} are recognized:

25213

25214

@table @samp

25215

@item C-JIS

25216

Recognize JIS characters.

25217

@item C-SJIS

25218

Recognize SJIS characters.

25219

@item C-EUCJP

25220

Recognize EUCJP characters.

25221

@end table

25222

25223

If @env{LANG} is not defined, or if it has some other value, then the

25224

compiler uses @code{mblen} and @code{mbtowc} as defined by the default locale to

25225

recognize and translate multibyte characters.

25226

@end table

25227

25228

@noindent

25229

Some additional environment variables affect the behavior of the

25230

preprocessor.

25231

25232

@include cppenv.texi

25233

25234

@c man end

25235

25236

@node Precompiled Headers

25237

@section Using Precompiled Headers

25238

@cindex precompiled headers

25239

@cindex speed of compilation

25240

25241

Often large projects have many header files that are included in every

25242

source file. The time the compiler takes to process these header files

25243

over and over again can account for nearly all of the time required to

25244

build the project. To make builds faster, GCC allows you to

25245

@dfn{precompile} a header file.

25246

25247

To create a precompiled header file, simply compile it as you would any

25248

other file, if necessary using the @option{-x} option to make the driver

25249

treat it as a C or C++ header file. You may want to use a

25250

tool like @command{make} to keep the precompiled header up-to-date when

25251

the headers it contains change.

25252

25253

A precompiled header file is searched for when @code{#include} is

25254

seen in the compilation. As it searches for the included file

25255

(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the

25256

compiler looks for a precompiled header in each directory just before it

25257

looks for the include file in that directory. The name searched for is

25258

the name specified in the @code{#include} with @samp{.gch} appended. If

25259

the precompiled header file can't be used, it is ignored.

25260

25261

For instance, if you have @code{#include "all.h"}, and you have

25262

@file{all.h.gch} in the same directory as @file{all.h}, then the

25263

precompiled header file is used if possible, and the original

25264

header is used otherwise.

25265

25266

Alternatively, you might decide to put the precompiled header file in a

25267

directory and use @option{-I} to ensure that directory is searched

25268

before (or instead of) the directory containing the original header.

25269

Then, if you want to check that the precompiled header file is always

25270

used, you can put a file of the same name as the original header in this

25271

directory containing an @code{#error} command.

25272

25273

This also works with @option{-include}. So yet another way to use

25274

precompiled headers, good for projects not designed with precompiled

25275

header files in mind, is to simply take most of the header files used by

25276

a project, include them from another header file, precompile that header

25277

file, and @option{-include} the precompiled header. If the header files

25278

have guards against multiple inclusion, they are skipped because

25279

they've already been included (in the precompiled header).

25280

25281

If you need to precompile the same header file for different

25282

languages, targets, or compiler options, you can instead make a

25283

@emph{directory} named like @file{all.h.gch}, and put each precompiled

25284

header in the directory, perhaps using @option{-o}. It doesn't matter

25285

what you call the files in the directory; every precompiled header in

25286

the directory is considered. The first precompiled header

25287

encountered in the directory that is valid for this compilation is

25288

used; they're searched in no particular order.

25289

25290

There are many other possibilities, limited only by your imagination,

25291

good sense, and the constraints of your build system.

25292

25293

A precompiled header file can be used only when these conditions apply:

25294

25295

@itemize

25296

@item

25297

Only one precompiled header can be used in a particular compilation.

25298

25299

@item

25300

A precompiled header can't be used once the first C token is seen. You

25301

can have preprocessor directives before a precompiled header; you cannot

25302

include a precompiled header from inside another header.

25303

25304

@item

25305

The precompiled header file must be produced for the same language as

25306

the current compilation. You can't use a C precompiled header for a C++

25307

compilation.

25308

25309

@item

25310

The precompiled header file must have been produced by the same compiler

25311

binary as the current compilation is using.

25312

25313

@item

25314

Any macros defined before the precompiled header is included must

25315

either be defined in the same way as when the precompiled header was

25316

generated, or must not affect the precompiled header, which usually

25317

means that they don't appear in the precompiled header at all.

25318

25319

The @option{-D} option is one way to define a macro before a

25320

precompiled header is included; using a @code{#define} can also do it.

25321

There are also some options that define macros implicitly, like

25322

@option{-O} and @option{-Wdeprecated}; the same rule applies to macros

25323

defined this way.

25324

25325

@item If debugging information is output when using the precompiled

25326

header, using @option{-g} or similar, the same kind of debugging information

25327

must have been output when building the precompiled header. However,

25328

a precompiled header built using @option{-g} can be used in a compilation

25329

when no debugging information is being output.

25330

25331

@item The same @option{-m} options must generally be used when building

25332

and using the precompiled header. @xref{Submodel Options},

25333

for any cases where this rule is relaxed.

25334

25335

@item Each of the following options must be the same when building and using

25336

the precompiled header:

25337

25338

@gccoptlist{-fexceptions}

25339

25340

@item

25341

Some other command-line options starting with @option{-f},

25342

@option{-p}, or @option{-O} must be defined in the same way as when

25343

the precompiled header was generated. At present, it's not clear

25344

which options are safe to change and which are not; the safest choice

25345

is to use exactly the same options when generating and using the

25346

precompiled header. The following are known to be safe:

25347

25348

@gccoptlist{-fmessage-length= -fpreprocessed -fsched-interblock @gol

25349

-fsched-spec -fsched-spec-load -fsched-spec-load-dangerous @gol

25350

-fsched-verbose=@var{number} -fschedule-insns -fvisibility= @gol

25351

-pedantic-errors}

25352

25353

@end itemize

25354

25355

For all of these except the last, the compiler automatically

25356

ignores the precompiled header if the conditions aren't met. If you

25357

find an option combination that doesn't work and doesn't cause the

25358

precompiled header to be ignored, please consider filing a bug report,

25359

see @ref{Bugs}.

25360

25361

If you do use differing options when generating and using the

25362

precompiled header, the actual behavior is a mixture of the

25363

behavior for the options. For instance, if you use @option{-g} to

25364

generate the precompiled header but not when using it, you may or may

25365

not get debugging information for routines in the precompiled header.