GCC(1)
✨ GCC(1) ✨
Manual name: GNU 🌈 This is the GNU project's page for gcc, and it's honestly such a classic 💅
✨ NAME ✨
Okay so the name is gcc, and it's the GNU project C and C++ compiler 🔥
✨ SYNOPSIS ✨
gcc [-c|-S|-E] [-std=standard]
[-g] [-pg] [-Olevel]
[-Wwarn...] [-Wpedantic]
[-Idir...] [-Ldir...]
[-Dmacro[=defn]...] [-Umacro]
[-foption...] [-mmachine-option...]
[-o outfile] [@file] infile...Only the most useful options are listed up there 👀 Check below for the rest 🦋 And g++ accepts mostly the same options as gcc, so you're basically set 💖
✨ DESCRIPTION ✨
When you invoke GCC, it normally does preprocessing, compilation, assembly, and linking, all in one go 🧚 The "overall options" let you stop that process at an intermediate stage. For example, -c says don't run the linker, so what you get back is object files from the assembler 🍓
Other options get passed along to one or more stages. Some control the preprocessor, some control the compiler itself, and some control the assembler and linker. Most of those last ones aren't documented here, since you rarely need them 😭
Most of the command-line options you can use with GCC are built for C programs. If an option is only useful with another language (usually C++), the explanation will say so out loud. If the description doesn't mention a source language, you can use that option with all supported languages ✨
The usual move is to run the executable called gcc. When you're cross-compiling, it's machine-gcc instead, and if you want one specific version, it's machine-gcc-version. When you compile C++ programs, invoke GCC as g++ instead 💅
The gcc program takes options and file names as operands. Lots of options have multi-letter names, so you can't bundle single-letter options together. -dv is very different from -d -v, so don't try to be clever 🙈
You can mix options and other arguments. For the most part, the order doesn't matter 🫶 But order does matter when you use several options of the same kind. For example, if you specify -L more than once, the directories get searched in the order you gave them. Also, where you put the -l option is significant 🔥
Lots of options have long names that start with -f or with -W---for — for example, -fmove-loop-invariants, -Wformat, and so on 🌸 Most of these have both positive and negative forms, and the negative form of -ffoo is -fno-foo. This manual only documents one of the two forms, whichever one isn't the default 🧠
Some options take one or more arguments, usually separated from the option name by either a space or an equals sign (=). Unless documented otherwise, an argument can be either numeric or a string. Numeric arguments should typically be small unsigned decimal or hexadecimal integers, and hexadecimal arguments must begin with the 0x prefix 🔢
Arguments to options that set a size threshold can be arbitrarily large decimal or hexadecimal integers, followed by a byte size suffix for a multiple of bytes. That includes kB and KiB for kilobyte and kibibyte, MB and MiB for megabyte and mebibyte, and GB and GiB for gigabyte and gigibyte, and so on 💜 These get called byte-size in the rest of the text. If you want the full scoop on the binary and decimal byte size prefixes, check the NIST, IEC, and other relevant national and international standards 🤓
✨ OPTIONS ✨
💅 Option Summary 💅
Here's a quick glance at all the options, grouped by type 🌈 The explanations come in the sections that follow.
🦋 Overall Options
-c -S -E -o file -dumpbase dumpbase -dumpbase-ext auxdropsuf
-dumpdir dumppfx -x language -v -### --help[=class[,...]]
--target-help --version -pass-exit-codes -pipe -specs=file
-wrapper @file -ffile-prefix-map=old=new -fcanon-prefix-map
-fplugin=file -fplugin-arg-name=arg -fdump-ada-spec[-slim]
-fada-spec-parent=unit -fdump-go-spec=file🌸 C Language Options
-ansi -std=standard -aux-info filename -fno-asm -fno-builtin
-fno-builtin-function -fcond-mismatch -ffreestanding -fgimple
-fgnu-tm -fgnu89-inline -fhosted -flax-vector-conversions
-fms-extensions -foffload=arg -foffload-options=arg -fopenacc
-fopenacc-dim=geom -fopenmp -fopenmp-simd
-fopenmp-target-simd-clone[=device-type]
-fpermitted-flt-eval-methods=standard -fplan9-extensions
-fsigned-bitfields -funsigned-bitfields -fsigned-char
-funsigned-char -fstrict-flex-arrays[=n] -fsso-struct=endianness👑 C++ Language Options
-fabi-version=n -fno-access-control -faligned-new=n
-fargs-in-order=n -fchar8_t -fcheck-new -fconstexpr-depth=n
-fconstexpr-cache-depth=n -fconstexpr-loop-limit=n
-fconstexpr-ops-limit=n -fno-elide-constructors
-fno-enforce-eh-specs -fno-gnu-keywords -fno-immediate-escalation
-fno-implicit-templates -fno-implicit-inline-templates
-fno-implement-inlines -fmodule-header[=kind] -fmodule-only
-fmodules-ts -fmodule-implicit-inline -fno-module-lazy
-fmodule-mapper=specification -fmodule-version-ignore
-fms-extensions -fnew-inheriting-ctors -fnew-ttp-matching
-fno-nonansi-builtins -fnothrow-opt -fno-operator-names
-fno-optional-diags -fno-pretty-templates -fno-rtti
-fsized-deallocation -ftemplate-backtrace-limit=n -ftemplate-depth=n
-fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++
-fvisibility-inlines-hidden -fvisibility-ms-compat
-fext-numeric-literals -flang-info-include-translate[=header]
-flang-info-include-translate-not -flang-info-module-cmi[=module]
-stdlib=libstdc++,libc++ -Wabi-tag -Wcatch-value -Wcatch-value=n
-Wno-class-conversion -Wclass-memaccess -Wcomma-subscript
-Wconditionally-supported -Wno-conversion-null
-Wctad-maybe-unsupported -Wctor-dtor-privacy -Wdangling-reference
-Wno-delete-incomplete -Wdelete-non-virtual-dtor
-Wno-deprecated-array-compare -Wdeprecated-copy
-Wdeprecated-copy-dtor -Wno-deprecated-enum-enum-conversion
-Wno-deprecated-enum-float-conversion -Weffc++
-Wno-elaborated-enum-base -Wno-exceptions -Wextra-semi
-Wno-global-module -Wno-inaccessible-base
-Wno-inherited-variadic-ctor -Wno-init-list-lifetime
-Winvalid-constexpr -Winvalid-imported-macros -Wno-invalid-offsetof
-Wno-literal-suffix -Wmismatched-new-delete -Wmismatched-tags
-Wmultiple-inheritance -Wnamespaces -Wnarrowing -Wnoexcept
-Wnoexcept-type -Wnon-virtual-dtor -Wpessimizing-move
-Wno-placement-new -Wplacement-new=n -Wrange-loop-construct
-Wredundant-move -Wredundant-tags -Wreorder -Wregister
-Wstrict-null-sentinel -Wno-subobject-linkage -Wtemplates
-Wno-non-template-friend -Wold-style-cast -Woverloaded-virtual
-Wno-pmf-conversions -Wself-move -Wsign-promo -Wsized-deallocation
-Wsuggest-final-methods -Wsuggest-final-types -Wsuggest-override
-Wno-template-id-cdtor -Wno-terminate -Wno-vexing-parse
-Wvirtual-inheritance -Wno-virtual-move-assign -Wvolatile
-Wzero-as-null-pointer-constant🧚 Objective-C and Objective-C++ Language Options
-fconstant-string-class=class-name -fgnu-runtime -fnext-runtime
-fno-nil-receivers -fobjc-abi-version=n -fobjc-call-cxx-cdtors
-fobjc-direct-dispatch -fobjc-exceptions -fobjc-gc -fobjc-nilcheck
-fobjc-std=objc1 -fno-local-ivars
-fivar-visibility=[public|protected|private|package]
-freplace-objc-classes -fzero-link -gen-decls -Wassign-intercept
-Wno-property-assign-default -Wno-protocol -Wobjc-root-class
-Wselector -Wstrict-selector-match -Wundeclared-selector💖 Diagnostic Message Formatting Options
-fmessage-length=n -fdiagnostics-plain-output
-fdiagnostics-show-location=[once|every-line]
-fdiagnostics-color=[auto|never|always]
-fdiagnostics-urls=[auto|never|always]
-fdiagnostics-format=[text|sarif-stderr|sarif-file|json|json-stderr|json-file]
-fno-diagnostics-json-formatting
-fno-diagnostics-show-option -fno-diagnostics-show-caret
-fno-diagnostics-show-labels -fno-diagnostics-show-line-numbers
-fno-diagnostics-show-cwe -fno-diagnostics-show-rule
-fdiagnostics-minimum-margin-width=width
-fdiagnostics-parseable-fixits -fdiagnostics-generate-patch
-fdiagnostics-show-template-tree -fno-elide-type
-fdiagnostics-path-format=[none|separate-events|inline-events]
-fdiagnostics-show-path-depths -fno-show-column
-fdiagnostics-column-unit=[display|byte]
-fdiagnostics-column-origin=origin
-fdiagnostics-escape-format=[unicode|bytes]
-fdiagnostics-text-art-charset=[none|ascii|unicode|emoji]✨ Warning Options ✨
okay bestie, this is the whole gossip squad 🗣️💅 every single warning option lives here, and I'm not cutting a single one 😭🫶
-fsyntax-only -fmax-errors=n -Wpedantic -pedantic-errors
-fpermissive -w -Wextra -Wall -Wabi=n -Waddress
-Wno-address-of-packed-member -Waggregate-return -Walloc-size
-Walloc-size-larger-than=byte-size -Walloc-zero -Walloca
-Walloca-larger-than=byte-size -Wno-aggressive-loop-optimizations
-Warith-conversion -Warray-bounds -Warray-bounds=n -Warray-compare
-Warray-parameter -Warray-parameter=n -Wno-attributes
-Wattribute-alias=n -Wno-attribute-alias -Wno-attribute-warning
-Wbidi-chars=[none|unpaired|any|ucn] -Wbool-compare
-Wbool-operation -Wno-builtin-declaration-mismatch
-Wno-builtin-macro-redefined -Wc90-c99-compat -Wc99-c11-compat
-Wc11-c23-compat -Wc++-compat -Wc++11-compat -Wc++14-compat
-Wc++17-compat -Wc++20-compat -Wno-c++11-extensions
-Wno-c++14-extensions -Wno-c++17-extensions -Wno-c++20-extensions
-Wno-c++23-extensions -Wcalloc-transposed-args -Wcast-align
-Wcast-align=strict -Wcast-function-type -Wcast-qual
-Wchar-subscripts -Wclobbered -Wcomment
-Wcompare-distinct-pointer-types -Wno-complain-wrong-lang
-Wconversion -Wno-coverage-mismatch -Wno-cpp -Wdangling-else
-Wdangling-pointer -Wdangling-pointer=n -Wdate-time -Wno-deprecated
-Wno-deprecated-declarations -Wno-designated-init
-Wdisabled-optimization -Wno-discarded-array-qualifiers
-Wno-discarded-qualifiers -Wno-div-by-zero -Wdouble-promotion
-Wduplicated-branches -Wduplicated-cond -Wempty-body
-Wno-endif-labels -Wenum-compare -Wenum-conversion
-Wenum-int-mismatch -Werror -Werror=* -Wexpansion-to-defined
-Wfatal-errors -Wflex-array-member-not-at-end -Wfloat-conversion
-Wfloat-equal -Wformat -Wformat=2 -Wno-format-contains-nul
-Wno-format-extra-args -Wformat-nonliteral -Wformat-overflow=n
-Wformat-security -Wformat-signedness -Wformat-truncation=n
-Wformat-y2k -Wframe-address -Wframe-larger-than=byte-size
-Wno-free-nonheap-object -Wno-if-not-aligned
-Wno-ignored-attributes -Wignored-qualifiers
-Wno-incompatible-pointer-types -Whardened -Wimplicit
-Wimplicit-fallthrough -Wimplicit-fallthrough=n
-Wno-implicit-function-declaration -Wno-implicit-int
-Winfinite-recursion -Winit-self -Winline -Wno-int-conversion
-Wint-in-bool-context -Wno-int-to-pointer-cast
-Wno-invalid-memory-model -Winvalid-pch -Winvalid-utf8
-Wno-unicode -Wjump-misses-init -Wlarger-than=byte-size
-Wlogical-not-parentheses -Wlogical-op -Wlong-long
-Wno-lto-type-mismatch -Wmain -Wmaybe-uninitialized
-Wmemset-elt-size -Wmemset-transposed-args -Wmisleading-indentation
-Wmissing-attributes -Wmissing-braces -Wmissing-field-initializers
-Wmissing-format-attribute -Wmissing-include-dirs
-Wmissing-noreturn -Wno-missing-profile -Wno-multichar
-Wmultistatement-macros -Wnonnull -Wnonnull-compare
-Wnormalized=[none|id|nfc|nfkc] -Wnull-dereference -Wno-odr
-Wopenacc-parallelism -Wopenmp -Wopenmp-simd -Wno-overflow
-Woverlength-strings -Wno-override-init-side-effects -Wpacked
-Wno-packed-bitfield-compat -Wpacked-not-aligned -Wpadded
-Wparentheses -Wno-pedantic-ms-format -Wpointer-arith
-Wno-pointer-compare -Wno-pointer-to-int-cast -Wno-pragmas
-Wno-prio-ctor-dtor -Wredundant-decls -Wrestrict
-Wno-return-local-addr -Wreturn-type -Wno-scalar-storage-order
-Wsequence-point -Wshadow -Wshadow=global -Wshadow=local
-Wshadow=compatible-local -Wno-shadow-ivar -Wno-shift-count-negative
-Wno-shift-count-overflow -Wshift-negative-value
-Wno-shift-overflow -Wshift-overflow=n -Wsign-compare
-Wsign-conversion -Wno-sizeof-array-argument -Wsizeof-array-div
-Wsizeof-pointer-div -Wsizeof-pointer-memaccess -Wstack-protector
-Wstack-usage=byte-size -Wstrict-aliasing -Wstrict-aliasing=n
-Wstrict-overflow -Wstrict-overflow=n -Wstring-compare
-Wno-stringop-overflow -Wno-stringop-overread
-Wno-stringop-truncation -Wstrict-flex-arrays
-Wsuggest-attribute=[pure|const|noreturn|format|malloc] -Wswitch
-Wno-switch-bool -Wswitch-default -Wswitch-enum
-Wno-switch-outside-range -Wno-switch-unreachable -Wsync-nand
-Wsystem-headers -Wtautological-compare -Wtrampolines -Wtrigraphs
-Wtrivial-auto-var-init -Wno-tsan -Wtype-limits -Wundef
-Wuninitialized -Wunknown-pragmas -Wunsuffixed-float-constants
-Wunused -Wunused-but-set-parameter -Wunused-but-set-variable
-Wunused-const-variable -Wunused-const-variable=n -Wunused-function
-Wunused-label -Wunused-local-typedefs -Wunused-macros
-Wunused-parameter -Wno-unused-result -Wunused-value
-Wunused-variable -Wuse-after-free -Wuse-after-free=n
-Wuseless-cast -Wno-varargs -Wvariadic-macros
-Wvector-operation-performance -Wvla -Wvla-larger-than=byte-size
-Wno-vla-larger-than -Wvolatile-register-var -Wwrite-strings
-Wno-xor-used-as-pow -Wzero-length-bounds🔬 Static Analyzer Options 🔬
the analyzer crew 🔍🦋 here's the full roster, flags exactly as they appear, no skipping 💜
-fanalyzer -fanalyzer-call-summaries -fanalyzer-checker=name
-fno-analyzer-feasibility -fanalyzer-fine-grained
-fanalyzer-show-events-in-system-headers -fno-analyzer-state-merge
-fno-analyzer-state-purge -fno-analyzer-suppress-followups
-fanalyzer-transitivity -fno-analyzer-undo-inlining
-fanalyzer-verbose-edges -fanalyzer-verbose-state-changes
-fanalyzer-verbosity=level -fdump-analyzer -fdump-analyzer-callgraph
-fdump-analyzer-exploded-graph -fdump-analyzer-exploded-nodes
-fdump-analyzer-exploded-nodes-2 -fdump-analyzer-exploded-nodes-3
-fdump-analyzer-exploded-paths -fdump-analyzer-feasibility
-fdump-analyzer-infinite-loop -fdump-analyzer-json
-fdump-analyzer-state-purge -fdump-analyzer-stderr
-fdump-analyzer-supergraph -fdump-analyzer-untracked
-Wno-analyzer-double-fclose -Wno-analyzer-double-free
-Wno-analyzer-exposure-through-output-file
-Wno-analyzer-exposure-through-uninit-copy
-Wno-analyzer-fd-access-mode-mismatch -Wno-analyzer-fd-double-close
-Wno-analyzer-fd-leak -Wno-analyzer-fd-phase-mismatch
-Wno-analyzer-fd-type-mismatch -Wno-analyzer-fd-use-after-close
-Wno-analyzer-fd-use-without-check -Wno-analyzer-file-leak
-Wno-analyzer-free-of-non-heap -Wno-analyzer-imprecise-fp-arithmetic
-Wno-analyzer-infinite-loop -Wno-analyzer-infinite-recursion
-Wno-analyzer-jump-through-null -Wno-analyzer-malloc-leak
-Wno-analyzer-mismatching-deallocation -Wno-analyzer-null-argument
-Wno-analyzer-null-dereference -Wno-analyzer-out-of-bounds
-Wno-analyzer-overlapping-buffers
-Wno-analyzer-possible-null-argument
-Wno-analyzer-possible-null-dereference
-Wno-analyzer-putenv-of-auto-var -Wno-analyzer-shift-count-negative
-Wno-analyzer-shift-count-overflow -Wno-analyzer-stale-setjmp-buffer
-Wno-analyzer-tainted-allocation-size
-Wno-analyzer-tainted-assertion -Wno-analyzer-tainted-array-index
-Wno-analyzer-tainted-divisor -Wno-analyzer-tainted-offset
-Wno-analyzer-tainted-size -Wanalyzer-symbol-too-complex
-Wanalyzer-too-complex -Wno-analyzer-undefined-behavior-strtok
-Wno-analyzer-unsafe-call-within-signal-handler
-Wno-analyzer-use-after-free
-Wno-analyzer-use-of-pointer-in-stale-stack-frame
-Wno-analyzer-use-of-uninitialized-value
-Wno-analyzer-va-arg-type-mismatch -Wno-analyzer-va-list-exhausted
-Wno-analyzer-va-list-leak -Wno-analyzer-va-list-use-after-va-end
-Wno-analyzer-write-to-const -Wno-analyzer-write-to-string-literal🌸 C and Objective-C-only Warning Options 🌸
these ones are for the C and Objective-C crowd only 🎀 here they are, all of them ✨
-Wbad-function-cast -Wmissing-declarations -Wmissing-parameter-type
-Wdeclaration-missing-parameter-type -Wmissing-prototypes
-Wmissing-variable-declarations -Wnested-externs
-Wold-style-declaration -Wold-style-definition -Wstrict-prototypes
-Wtraditional -Wtraditional-conversion
-Wdeclaration-after-statement -Wpointer-sign🐛 Debugging Options 🐛
okay the debugging section is giving detective energy 🕵️♀️💖 every flag, exactly as written 🫶
-g -glevel -gdwarf -gdwarf-version -gbtf -gctf -gctflevel -ggdb
-grecord-gcc-switches -gno-record-gcc-switches -gstrict-dwarf
-gno-strict-dwarf -gas-loc-support -gno-as-loc-support
-gas-locview-support -gno-as-locview-support -gcodeview
-gcolumn-info -gno-column-info -gdwarf32 -gdwarf64
-gstatement-frontiers -gno-statement-frontiers
-gvariable-location-views -gno-variable-location-views
-ginternal-reset-location-views -gno-internal-reset-location-views
-ginline-points -gno-inline-points -gvms -gz[=type] -gsplit-dwarf
-gdescribe-dies -gno-describe-dies -fdebug-prefix-map=old=new
-fdebug-types-section -fno-eliminate-unused-debug-types
-femit-struct-debug-baseonly -femit-struct-debug-reduced
-femit-struct-debug-detailed[=spec-list]
-fno-eliminate-unused-debug-symbols -femit-class-debug-always
-fno-merge-debug-strings -fno-dwarf2-cfi-asm -fvar-tracking
-fvar-tracking-assignments✨ Optimization Options ✨
okay bestie, this is the glow-up squad 💅 The page doesn't describe these ones, so I'm keeping every flag exactly as written 🫶
-faggressive-loop-optimizations-falign-functions[=n[:m:[n2[:m2]]]]-falign-jumps[=n[:m:[n2[:m2]]]]-falign-labels[=n[:m:[n2[:m2]]]]-falign-loops[=n[:m:[n2[:m2]]]]-fmin-function-alignment=[n]-fno-allocation-dce-fallow-store-data-races-fassociative-math-fauto-profile-fauto-profile[=path]-fauto-inc-dec-fbranch-probabilities-fcaller-saves-fcombine-stack-adjustments-fconserve-stack-ffold-mem-offsets-fcompare-elim-fcprop-registers-fcrossjumping-fcse-follow-jumps-fcse-skip-blocks-fcx-fortran-rules-fcx-limited-range-fdata-sections-fdce-fdelayed-branch-fdelete-null-pointer-checks-fdevirtualize-fdevirtualize-speculatively-fdevirtualize-at-ltrans-fdse-fearly-inlining-fipa-sra-fexpensive-optimizations-ffat-lto-objects-ffast-math-ffinite-math-only-ffloat-store-fexcess-precision=style-ffinite-loops-fforward-propagate-ffp-contract=style-ffunction-sections-fgcse-fgcse-after-reload-fgcse-las-fgcse-lm-fgraphite-identity-fgcse-sm-fhoist-adjacent-loads-fif-conversion-fif-conversion2-findirect-inlining-finline-stringops[=fn]-finline-functions-finline-functions-called-once-finline-limit=n-finline-small-functions-fipa-modref-fipa-cp-fipa-cp-clone-fipa-bit-cp-fipa-vrp-fipa-pta-fipa-profile-fipa-pure-const-fipa-reference-fipa-reference-addressable-fipa-stack-alignment-fipa-icf-fira-algorithm=algorithm-flive-patching=level-fira-region=region-fira-hoist-pressure-fira-loop-pressure-fno-ira-share-save-slots-fno-ira-share-spill-slots-fisolate-erroneous-paths-dereference-fisolate-erroneous-paths-attribute-fivopts-fkeep-inline-functions-fkeep-static-functions-fkeep-static-consts-flimit-function-alignment-flive-range-shrinkage-floop-block-floop-interchange-floop-strip-mine-floop-unroll-and-jam-floop-nest-optimize-floop-parallelize-all-flra-remat-flto-flto-compression-level-flto-partition=alg-fmerge-all-constants-fmerge-constants-fmodulo-sched-fmodulo-sched-allow-regmoves-fmove-loop-invariants-fmove-loop-stores-fno-branch-count-reg-fno-defer-pop-fno-fp-int-builtin-inexact-fno-function-cse-fno-guess-branch-probability-fno-inline-fno-math-errno-fno-peephole-fno-peephole2-fno-printf-return-value-fno-sched-interblock-fno-sched-spec-fno-signed-zeros-fno-toplevel-reorder-fno-trapping-math-fno-zero-initialized-in-bss-fomit-frame-pointer-foptimize-sibling-calls-fpartial-inlining-fpeel-loops-fpredictive-commoning-fprefetch-loop-arrays-fprofile-correction-fprofile-use-fprofile-use=path-fprofile-partial-training-fprofile-values-fprofile-reorder-functions-freciprocal-math-free-frename-registers-freorder-blocks-freorder-blocks-algorithm=algorithm-freorder-blocks-and-partition-freorder-functions-frerun-cse-after-loop-freschedule-modulo-scheduled-loops-frounding-math-fsave-optimization-record-fsched2-use-superblocks-fsched-pressure-fsched-spec-load-fsched-spec-load-dangerous-fsched-stalled-insns-dep[=n]-fsched-stalled-insns[=n]-fsched-group-heuristic-fsched-critical-path-heuristic-fsched-spec-insn-heuristic-fsched-rank-heuristic-fsched-last-insn-heuristic-fsched-dep-count-heuristic-fschedule-fusion-fschedule-insns-fschedule-insns2-fsection-anchors-fselective-scheduling-fselective-scheduling2-fsel-sched-pipelining-fsel-sched-pipelining-outer-loops-fsemantic-interposition-fshrink-wrap-fshrink-wrap-separate-fsignaling-nans-fsingle-precision-constant-fsplit-ivs-in-unroller-fsplit-loops-fsplit-paths-fsplit-wide-types-fsplit-wide-types-early-fssa-backprop-fssa-phiopt-fstdarg-opt-fstore-merging-fstrict-aliasing-fipa-strict-aliasing-fthread-jumps-ftracer-ftree-bit-ccp-ftree-builtin-call-dce-ftree-ccp-ftree-ch-ftree-coalesce-vars-ftree-copy-prop-ftree-dce-ftree-dominator-opts-ftree-dse-ftree-forwprop-ftree-fre-fcode-hoisting-ftree-loop-if-convert-ftree-loop-im-ftree-phiprop-ftree-loop-distribution-ftree-loop-distribute-patterns-ftree-loop-ivcanon-ftree-loop-linear-ftree-loop-optimize-ftree-loop-vectorize-ftree-parallelize-loops=n-ftree-pre-ftree-partial-pre-ftree-pta-ftree-reassoc-ftree-scev-cprop-ftree-sink-ftree-slsr-ftree-sra-ftree-switch-conversion-ftree-tail-merge-ftree-ter-ftree-vectorize-ftree-vrp-ftrivial-auto-var-init-funconstrained-commons-funit-at-a-time-funroll-all-loops-funroll-loops-funsafe-math-optimizations-funswitch-loops-fipa-ra-fvariable-expansion-in-unroller-fvect-cost-model-fvpt-fweb-fwhole-program-fwpa-fuse-linker-plugin-fzero-call-used-regs--param name=value-O-O0-O1-O2-O3-Os-Ofast-Og-Oz
✨ Program Instrumentation Options ✨
this squad is all about watching the code so you can see what it's up to 🔍🦋
-p-pg-fprofile-arcs--coverage-ftest-coverage-fcondition-coverage-fprofile-abs-path-fprofile-dir=path-fprofile-generate-fprofile-generate=path-fprofile-info-section-fprofile-info-section=name-fprofile-note=path-fprofile-prefix-path=path-fprofile-update=method-fprofile-filter-files=regex-fprofile-exclude-files=regex-fprofile-reproducible=[multithreaded|parallel-runs|serial]-fsanitize=style-fsanitize-recover-fsanitize-recover=style-fsanitize-trap-fsanitize-trap=style-fasan-shadow-offset=number-fsanitize-sections=s1,s2,...-fsanitize-undefined-trap-on-error-fbounds-check-fcf-protection=[full|branch|return|none|check]-fharden-compares-fharden-conditional-branches-fhardened-fharden-control-flow-redundancy-fhardcfr-skip-leaf-fhardcfr-check-exceptions-fhardcfr-check-returning-calls-fhardcfr-check-noreturn-calls=[always|no-xthrow|nothrow|never]-fstack-protector-fstack-protector-all-fstack-protector-strong-fstack-protector-explicit-fstack-check-fstack-limit-register=reg-fstack-limit-symbol=sym-fno-stack-limit-fsplit-stack-fstrub=disable-fstrub=strict-fstrub=relaxed-fstrub=all-fstrub=at-calls-fstrub=internal-fvtable-verify=[std|preinit|none]-fvtv-counts-fvtv-debug-finstrument-functions-finstrument-functions-once-finstrument-functions-exclude-function-list=sym,sym,...-finstrument-functions-exclude-file-list=file,file,...-fprofile-prefix-map=old=new-fpatchable-function-entry=N[,M]
✨ Preprocessor Options ✨
the preprocessor is the pre-game warm-up before the compiler even shows up 🌸
-Aquestion=answer-A-question[=answer]-C-CC-Dmacro[=defn]-dD-dI-dM-dN-dU-fdebug-cpp-fdirectives-only-fdollars-in-identifiers-fexec-charset=charset-fextended-identifiers-finput-charset=charset-flarge-source-files-fmacro-prefix-map=old=new-fmax-include-depth=depth-fno-canonical-system-headers-fpch-deps-fpch-preprocess-fpreprocessed-ftabstop=width-ftrack-macro-expansion-fwide-exec-charset=charset-fworking-directory-H-imacros file-include file-M-MD-MF-MG-MM-MMD-MP-MQ-MT-Mno-modules-no-integrated-cpp-P-pthread-remap-traditional-traditional-cpp-trigraphs-Umacro-undef-Wp,option-Xpreprocessor option
✨ Assembler Options ✨
a quick stop at the assembler, bestie 🧚
-Wa,option-Xassembler option
✨ Linker Options ✨
the linker is where everything gets tied together 🎀
object-file-name-fuse-ld=linker-llibrary-nostartfiles-nodefaultlibs-nolibc-nostdlib-nostdlib++-e entry--entry=entry-pie-pthread-r-rdynamic-s-static-static-pie-static-libgcc-static-libstdc++-static-libasan-static-libtsan-static-liblsan-static-libubsan-shared-shared-libgcc-symbolic-T script-Wl,option-Xlinker option-u symbol-z keyword
✨ Directory Options ✨
where GCC goes looking for stuff, the treasure map era 🗺️💖
-Bprefix-Idir-I--idirafter dir-imacros file-imultilib dir-iplugindir=dir-iprefix file-iquote dir-isysroot dir-isystem dir-iwithprefix dir-iwithprefixbefore dir-Ldir-no-canonical-prefixes--no-sysroot-suffix-nostdinc-nostdinc++--sysroot=dir
✨ Code Generation Options ✨
the code generation crew, where the machine code gets made 💅🔥
-fcall-saved-reg-fcall-used-reg-ffixed-reg-fexceptions-fnon-call-exceptions-fdelete-dead-exceptions-funwind-tables-fasynchronous-unwind-tables-fno-gnu-unique-finhibit-size-directive-fcommon-fno-ident-fpcc-struct-return-fpic-fPIC-fpie-fPIE-fno-plt-fno-jump-tables-fno-bit-tests-frecord-gcc-switches-freg-struct-return-fshort-enums-fshort-wchar-fverbose-asm-fpack-struct[=n]-fleading-underscore-ftls-model=model-fstack-reuse=reuse_level-ftrampolines-ftrampoline-impl=[stack|heap]-ftrapv-fwrapv-fvisibility=[default|internal|hidden|protected]-fstrict-volatile-bitfields-fsync-libcalls
✨ Developer Options ✨
last stop, the developer zone, for when you want to see what's happening behind the curtain 💜🧪
-dletters-dumpspecs-dumpmachine-dumpversion-dumpfullversion-fcallgraph-info[=su,da]-fchecking-fchecking=n-fdbg-cnt-list-fdbg-cnt=counter-value-list-fdisable-ipa-pass_name-fdisable-rtl-pass_name-fdisable-rtl-pass-name=range-list-fdisable-tree-pass_name-fdisable-tree-pass-name=range-list-fdump-debug-fdump-earlydebug-fdump-noaddr-fdump-unnumbered-fdump-unnumbered-links-fdump-final-insns[=file]-fdump-ipa-all-fdump-ipa-cgraph-fdump-ipa-inline-fdump-lang-all-fdump-lang-switch-fdump-lang-switch-options-fdump-lang-switch-options=filename-fdump-passes-fdump-rtl-pass-fdump-rtl-pass=filename-fdump-statistics-fdump-tree-all-fdump-tree-switch-fdump-tree-switch-options-fdump-tree-switch-options=filename-fcompare-debug[=opts]-fcompare-debug-second-fenable-kind-pass-fenable-kind-pass=range-list-fira-verbose=n-flto-report-flto-report-wpa-fmem-report-wpa-fmem-report-fpre-ipa-mem-report-fpost-ipa-mem-report-fopt-info-fopt-info-options[=file]-fmultiflags-fprofile-report-frandom-seed=string-fsched-verbose=n-fsel-sched-verbose-fsel-sched-dump-cfg-fsel-sched-pipelining-verbose-fstats-fstack-usage-ftime-report-ftime-report-details-fvar-tracking-assignments-toggle-gtoggle-print-file-name=library-print-libgcc-file-name-print-multi-directory-print-multi-lib-print-multi-os-directory-print-prog-name=program-print-search-dirs-Q-print-sysroot-print-sysroot-headers-suffix-save-temps-save-temps=cwd-save-temps=obj-time[=file]
🌈 Machine-Dependent Options 🌈
Okay bestie, this is the chaotic part 🙈 Every chip family gets its own squad of flags, so I'll go target by target. Don't worry, I'm just listing them out so you can find your fave 💅
🦋 AArch64 Options
AArch64 is absolutely stacked with flags 😭🔥
-mabi=name -mbig-endian -mlittle-endian
-mgeneral-regs-only -mcmodel=tiny -mcmodel=small -mcmodel=large
-mstrict-align -mno-strict-align -momit-leaf-frame-pointer
-mtls-dialect=desc -mtls-dialect=traditional -mtls-size=size
-mfix-cortex-a53-835769 -mfix-cortex-a53-843419
-mlow-precision-recip-sqrt -mlow-precision-sqrt
-mlow-precision-div -mpc-relative-literal-loads
-msign-return-address=scope -mbranch-protection=none|standard|pac-ret[+leaf +b-key]|bti -mharden-sls=opts -march=name -mcpu=name
-mtune=name -moverride=string -mverbose-cost-dump
-mstack-protector-guard=guard -mstack-protector-guard-reg=sysreg
-mstack-protector-guard-offset=offset -mtrack-speculation
-moutline-atomics -mearly-ldp-fusion -mlate-ldp-fusion🐝 Adapteva Epiphany Options
Buzzing in with the Epiphany crew 🐝✨
-mhalf-reg-file -mprefer-short-insn-regs
-mbranch-cost=num -mcmove -mnops=num -msoft-cmpsf -msplit-lohi
-mpost-inc -mpost-modify -mstack-offset=num -mround-nearest
-mlong-calls -mshort-calls -msmall16 -mfp-mode=mode -mvect-double
-max-vect-align=num -msplit-vecmove-early -m1reg-reg🎮 AMD GCN Options
Only three, but they're iconic 👑
-march=gpu -mtune=gpu -mstack-size=bytes🌸 ARC Options
The ARC section is giving main character energy, and it goes on for ages 💀🌸
-mbarrel-shifter -mjli-always -mcpu=cpu -mA6 -mARC600
-mA7 -mARC700 -mdpfp -mdpfp-compact -mdpfp-fast -mno-dpfp-lrsr
-mea -mno-mpy -mmul32x16 -mmul64 -matomic -mnorm -mspfp
-mspfp-compact -mspfp-fast -msimd -msoft-float -mswap -mcrc
-mdsp-packa -mdvbf -mlock -mmac-d16 -mmac-24 -mrtsc -mswape
-mtelephony -mxy -misize -mannotate-align -marclinux
-marclinux_prof -mlong-calls -mmedium-calls -msdata
-mirq-ctrl-saved -mrgf-banked-regs -mlpc-width=width -G num
-mvolatile-cache -mtp-regno=regno -malign-call -mauto-modify-reg
-mbbit-peephole -mno-brcc -mcase-vector-pcrel -mcompact-casesi
-mno-cond-exec -mearly-cbranchsi -mexpand-adddi -mindexed-loads
-mlra -mlra-priority-none -mlra-priority-compact
-mlra-priority-noncompact -mmillicode -mmixed-code -mq-class
-mRcq -mRcw -msize-level=level -mtune=cpu -mmultcost=num
-mcode-density-frame -munalign-prob-threshold=probability
-mmpy-option=multo -mdiv-rem -mcode-density -mll64 -mfpu=fpu
-mrf16 -mbranch-index💪 ARM Options
ARM is the OG and it's still serving 🔥
-mapcs-frame -mno-apcs-frame -mabi=name
-mapcs-stack-check -mno-apcs-stack-check -mapcs-reentrant
-mno-apcs-reentrant -mgeneral-regs-only -msched-prolog
-mno-sched-prolog -mlittle-endian -mbig-endian -mbe8 -mbe32
-mfloat-abi=name -mfp16-format=name -mthumb-interwork
-mno-thumb-interwork -mcpu=name -march=name -mfpu=name -mtune=name
-mprint-tune-info -mstructure-size-boundary=n -mabort-on-noreturn
-mlong-calls -mno-long-calls -msingle-pic-base
-mno-single-pic-base -mpic-register=reg -mnop-fun-dllimport
-mpoke-function-name -mthumb -marm -mflip-thumb -mtpcs-frame
-mtpcs-leaf-frame -mcaller-super-interworking
-mcallee-super-interworking -mtp=name -mtls-dialect=dialect
-mword-relocations -mfix-cortex-m3-ldrd -mfix-cortex-a57-aes-1742098
-mfix-cortex-a72-aes-1655431 -munaligned-access -mneon-for-64bits
-mslow-flash-data -masm-syntax-unified -mrestrict-it
-mverbose-cost-dump -mpure-code -mcmse -mfix-cmse-cve-2021-35465
-mstack-protector-guard=guard -mstack-protector-guard-offset=offset
-mfdpic -mbranch-protection=none|standard|pac-ret[+leaf] [+bti]|bti[+pac-ret[+leaf]]⚡ AVR Options
Tiny chips, big energy ✨
-mmcu=mcu -mabsdata -maccumulate-args
-mbranch-cost=cost -mfuse-add=level -mcall-prologues
-mgas-isr-prologues -mint8 -mflmap -mdouble=bits
-mlong-double=bits -mn_flash=size -mno-interrupts -mmain-is-OS_task
-mrelax -mrmw -mstrict-X -mtiny-stack -mrodata-in-ram
-mfract-convert-truncate -mshort-calls -mskip-bug -nodevicelib
-nodevicespecs -Waddr-space-convert -Wmisspelled-isr🎵 Blackfin Options
Vibing with the Blackfin set 🎵
-mcpu=cpu[-sirevision] -msim
-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer
-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly
-mno-csync-anomaly -mlow-64k -mno-low64k -mstack-check-l1
-mid-shared-library -mno-id-shared-library -mshared-library-id=n
-mleaf-id-shared-library -mno-leaf-id-shared-library -msep-data
-mno-sep-data -mlong-calls -mno-long-calls -mfast-fp -minline-plt
-mmulticore -mcorea -mcoreb -msdram -micplb🧚 C6X Options
Small list, sweet vibes 🧚
-mbig-endian -mlittle-endian -march=cpu -msim
-msdata=sdata-type🍓 CRIS Options
Ooh, CRIS is full of little details 🍓
-mcpu=cpu -march=cpu -mtune=cpu -mmax-stack-frame=n
-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects
-mstack-align -mdata-align -mconst-align -m32-bit -m16-bit
-m8-bit -mno-prologue-epilogue -melf -maout -sim -sim2
-mmul-bug-workaround -mno-mul-bug-workaround🌙 C-SKY Options
The C-SKY list is serving a whole buffet 🌙
-march=arch -mcpu=cpu -mbig-endian -EB
-mlittle-endian -EL -mhard-float -msoft-float -mfpu=fpu
-mdouble-float -mfdivdu -mfloat-abi=name -melrw -mistack -mmp
-mcp -mcache -msecurity -mtrust -mdsp -medsp -mvdsp -mdiv
-msmart -mhigh-registers -manchor -mpushpop -mmultiple-stld
-mconstpool -mstack-size -mccrt -mbranch-cost=n -mcse-cc
-msched-prolog -msim🍎 Darwin Options
Darwin is the longest list here and it's not even close 😭🍎
-all_load -allowable_client -arch
-arch_errors_fatal -arch_only -bind_at_load -bundle
-bundle_loader -client_name -compatibility_version
-current_version -dead_strip -dependency-file -dylib_file
-dylinker_install_name -dynamic -dynamiclib -exported_symbols_list
-filelist -flat_namespace -force_cpusubtype_ALL
-force_flat_namespace -headerpad_max_install_names -iframework
-image_base -init -install_name -keep_private_externs
-multi_module -multiply_defined -multiply_defined_unused
-noall_load -no_dead_strip_inits_and_terms -nodefaultrpaths
-nofixprebinding -nomultidefs -noprebind -noseglinkedit
-pagezero_size -prebind -prebind_all_twolevel_modules
-private_bundle -read_only_relocs -sectalign -sectobjectsymbols
-whyload -seg1addr -sectcreate -sectobjectsymbols -sectorder
-segaddr -segs_read_only_addr -segs_read_write_addr
-seg_addr_table -seg_addr_table_filename -seglinkedit -segprot
-segs_read_only_addr -segs_read_write_addr -single_module -static
-sub_library -sub_umbrella -twolevel_namespace -umbrella
-undefined -unexported_symbols_list -weak_reference_mismatches
-whatsloaded -F -gused -gfull -mmacosx-version-min=version
-mkernel -mone-byte-bool💿 DEC Alpha Options
Retro queen energy, no cap 👑💿
-mno-fp-regs -msoft-float -mieee
-mieee-with-inexact -mieee-conformant -mfp-trap-mode=mode
-mfp-rounding-mode=mode -mtrap-precision=mode -mbuild-constants
-mcpu=cpu-type -mtune=cpu-type -mbwx -mmax -mfix -mcix
-mfloat-vax -mfloat-ieee -mexplicit-relocs -msmall-data
-mlarge-data -msmall-text -mlarge-text -mmemory-latency=time🐚 eBPF Options
eBPF is literally so cute 🐚💜
-mbig-endian -mlittle-endian -mframe-limit=bytes -mxbpf
-mco-re -mno-co-re -mjmpext -mjmp32 -malu32 -mv3-atomics -mbswap
-msdiv -msmov -mcpu=version -masm=dialect
-minline-memops-threshold=bytes🧁 FR30 Options
Sweet and simple 🧁
-msmall-model -mno-lsim🎀 FT32 Options
Bow on top 🎀
-msim -mlra -mnodiv -mft32b -mcompress -mnopm🌺 FRV Options
FRV is a whole mood 🌺
-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 -mhard-float
-msoft-float -malloc-cc -mfixed-cc -mdword -mno-dword -mdouble
-mno-double -mmedia -mno-media -mmuladd -mno-muladd -mfdpic
-minline-plt -mgprel-ro -multilib-library-pic -mlinked-fp
-mlong-calls -malign-labels -mlibrary-pic -macc-4 -macc-8 -mpack
-mno-pack -mno-eflags -mcond-move -mno-cond-move
-moptimize-membar -mno-optimize-membar -mscc -mno-scc -mcond-exec
-mno-cond-exec -mvliw-branch -mno-vliw-branch -mmulti-cond-exec
-mno-multi-cond-exec -mnested-cond-exec -mno-nested-cond-exec
-mtomcat-stats -mTLS -mtls -mcpu=cpu🐧 GNU/Linux Options
Penguin pride 🐧🫶
-mglibc -muclibc -mmusl -mbionic -mandroid
-tno-android-cc -tno-android-ld🕹️ H8/300 Options
Retro gaming era 🕹️
-mrelax -mh -ms -mn -mexr -mno-exr -mint32
-malign-300🏗️ HPPA Options
HPPA is so detailed it's giving architect 🏗️
-march=architecture-type -matomic-libcalls
-mbig-switch -mcaller-copies -mdisable-fpregs -mdisable-indexing
-mordered -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld
-mfixed-range=register-range -mcoherent-ldcw -mjump-in-delay
-mlinker-opt -mlong-calls -mlong-load-store -mno-atomic-libcalls
-mno-disable-fpregs -mno-disable-indexing -mno-fast-indirect-calls
-mno-gas -mno-jump-in-delay -mno-long-load-store
-mno-portable-runtime -mno-soft-float -mno-space-regs -msoft-float
-mpa-risc-1-0 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime
-mschedule=cpu-type -mspace-regs -msoft-mult -msio -mwsio
-munix=unix-std -nolibdld -static -threads🧠 IA-64 Options
The IA-64 list is a full brain workout 🧠🔥
-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld
-mno-pic -mvolatile-asm-stop -mregister-names -msdata -mno-sdata
-mconstant-gp -mauto-pic -mfused-madd
-minline-float-divide-min-latency
-minline-float-divide-max-throughput -mno-inline-float-divide
-minline-int-divide-min-latency -minline-int-divide-max-throughput
-mno-inline-int-divide -minline-sqrt-min-latency
-minline-sqrt-max-throughput -mno-inline-sqrt -mdwarf2-asm
-mearly-stop-bits -mfixed-range=register-range -mtls-size=tls-size
-mtune=cpu-type -milp32 -mlp64 -msched-br-data-spec
-msched-ar-data-spec -msched-control-spec -msched-br-in-data-spec
-msched-ar-in-data-spec -msched-in-control-spec -msched-spec-ldc
-msched-spec-control-ldc -msched-prefer-non-data-spec-insns
-msched-prefer-non-control-spec-insns
-msched-stop-bits-after-every-cycle
-msched-count-spec-in-critical-path
-msel-sched-dont-check-control-spec -msched-fp-mem-deps-zero-cost
-msched-max-memory-insns-hard-limit -msched-max-memory-insns=max-insns🌷 LM32 Options
And last but not least, the LM32 finale 🌷💖
-mbarrel-shift-enabled -mdivide-enabled
-mmultiply-enabled -msign-extend-enabled -muser-enabled🦋 LoongArch Options
-march=cpu-type— pick the CPU type to target 💅-mtune=cpu-type— tune for a CPU type ✨-mabi=base-abi-type— choose the base ABI type 🎀-mfpu=fpu-type— pick the FPU type 🌸-msimd=simd-type— pick the SIMD type 🔥-msoft-float— soft float vibes 🧚-msingle-float— single float 🦋-mdouble-float— double float 💜-mlsx— turn on LSX 🌈-mno-lsx— the opposite of-mlsx🙈-mlasx— turn on LASX ⭐-mno-lasx— the opposite of-mlasx💀-mbranch-cost=n— set the branch cost ton🍓-mcheck-zero-division— check for zero division 🫶-mno-check-zero-division— skip that check 🙅-mcond-move-int— conditional move for ints 👑-mno-cond-move-int— the opposite of-mcond-move-int💅-mcond-move-float— conditional move for floats 🦋-mno-cond-move-float— the opposite of-mcond-move-float🌸-memcpy— use memcpy ✨-mno-memcpy— the opposite of-memcpy🙈-mstrict-align— strict alignment 🔥-mno-strict-align— the opposite of-mstrict-align🧚-mmax-inline-memcpy-size=n— set the max inline memcpy size ton💜-mexplicit-relocs=style— pick an explicit relocs style 🌈-mexplicit-relocs— explicit relocs on ⭐-mno-explicit-relocs— explicit relocs off 💀-mdirect-extern-access— direct extern access 🍓-mno-direct-extern-access— the opposite of-mdirect-extern-access🫶-mcmodel=code-model— pick the code model 👑-mrelax— relax it 💅-mpass-mrelax-to-as— pass the relax toas🦋-mrecip— reciprocal approximations 🌸-mrecip=opt— reciprocal approximations, with options ✨-mfrecipe— frecipe on 🔥-mno-frecipe— frecipe off 🙈-mdiv32— 32-bit div 🧚-mno-div32— the opposite of-mdiv32💜-mlam-bh— lam-bh on 🌈-mno-lam-bh— lam-bh off ⭐-mlamcas— lamcas on 💀-mno-lamcas— lamcas off 🍓-mld-seq-sa— ld-seq-sa on 🫶-mno-ld-seq-sa— ld-seq-sa off 👑-mtls-dialect=opt— pick the TLS dialect 💅
🦋 M32R/D Options
-m32r2— target M32R2 🌸-m32rx— target M32RX ✨-m32r— target M32R 🔥-mdebug— debug mode 🧚-malign-loops— align loops 💜-mno-align-loops— don't align loops 🌈-missue-rate=number— set the issue rate tonumber⭐-mbranch-cost=number— set the branch cost tonumber💀-mmodel=code-size-model-type— pick the code-size model type 🍓-msdata=sdata-type— pick the sdata type 🫶-mno-flush-func— no flush function 👑-mflush-func=name— flush function namedname💅-mno-flush-trap— no flush trap 🦋-mflush-trap=number— flush trap numbernumber🌸-G num— the-Gsize limit, set tonum✨
🦋 M32C Options
-mcpu=cpu— pick the CPU 🔥-msim— simulator mode 🧚-memregs=number— set the number of memregs 💜
🦋 M680x0 Options
-march=arch— pick the arch 🌈-mcpu=cpu— pick the CPU ⭐-mtune=tune— tune it 💀-m68000— 68000 🍓-m68020— 68020 🫶-m68020-40— 68020-40 👑-m68020-60— 68020-60 💅-m68030— 68030 🦋-m68040— 68040 🌸-m68060— 68060 ✨-mcpu32— CPU32 🔥-m5200— 5200 🧚-m5206e— 5206e 💜-m528x— 528x 🌈-m5307— 5307 ⭐-m5407— 5407 💀-mcfv4e— ColdFire v4e 🍓-mbitfield— bitfield on 🫶-mno-bitfield— bitfield off 👑-mc68000— C68000 💅-mc68020— C68020 🦋-mnobitfield— bitfield off (the no-bitfield spelling) 🌸-mrtd— rtd on ✨-mno-rtd— rtd off 🔥-mdiv— div on 🧚-mno-div— div off 💜-mshort— short ints 🌈-mno-short— no short ints ⭐-mhard-float— hard float 💀-m68881— 68881 FPU 🍓-msoft-float— soft float 🫶-mpcrel— PC-relative 👑-malign-int— align ints 💅-mstrict-align— strict alignment 🦋-msep-data— separate data 🌸-mno-sep-data— the opposite of-msep-data✨-mshared-library-id=n— shared library IDn🔥-mid-shared-library— ID shared library on 🧚-mno-id-shared-library— ID shared library off 💜-mxgot— xgot on 🌈-mno-xgot— xgot off ⭐-mlong-jump-table-offsets— long jump table offsets 💀
🦋 MCore Options
-mhardlit— hardlit on 🍓-mno-hardlit— hardlit off 🫶-mdiv— div on 👑-mno-div— div off 💅-mrelax-immediates— relax immediates 🦋-mno-relax-immediates— the opposite of-mrelax-immediates🌸-mwide-bitfields— wide bitfields ✨-mno-wide-bitfields— no wide bitfields 🔥-m4byte-functions— 4-byte functions 🧚-mno-4byte-functions— no 4-byte functions 💜-mcallgraph-data— callgraph data 🌈-mno-callgraph-data— no callgraph data ⭐-mslow-bytes— slow bytes 💀-mno-slow-bytes— no slow bytes 🍓-mno-lsim— no simulator 🫶-mlittle-endian— little endian 👑-mbig-endian— big endian 💅-m210— 210 🦋-m340— 340 🌸-mstack-increment— stack increment ✨
🦋 MicroBlaze Options
-msoft-float— soft float 🔥-mhard-float— hard float 🧚-msmall-divides— small divides 💜-mcpu=cpu— pick the CPU 🌈-mmemcpy— memcpy ⭐-mxl-soft-mul— XL soft mul 💀-mxl-soft-div— XL soft div 🍓-mxl-barrel-shift— XL barrel shift 🫶-mxl-pattern-compare— XL pattern compare 👑-mxl-stack-check— XL stack check 💅-mxl-gp-opt— XL GP opt 🦋-mno-clearbss— no clearbss 🌸-mxl-multiply-high— XL multiply high ✨-mxl-float-convert— XL float convert 🔥-mxl-float-sqrt— XL float sqrt 🧚-mbig-endian— big endian 💜-mlittle-endian— little endian 🌈-mxl-reorder— XL reorder ⭐-mxl-mode-app-model— XL mode app model 💀-mpic-data-is-text-relative— PIC data is text-relative 🍓
🦋 MIPS Options
-EL— little endian 🫶-EB— big endian 👑-march=arch— pick the arch 💅-mtune=arch— tune for the arch 🦋-mips1— MIPS I 🌸-mips2— MIPS II ✨-mips3— MIPS III 🔥-mips4— MIPS IV 🧚-mips32— MIPS32 💜-mips32r2— MIPS32 Release 2 🌈-mips32r3— MIPS32 Release 3 ⭐-mips32r5— MIPS32 Release 5 💀-mips32r6— MIPS32 Release 6 🍓-mips64— MIPS64 🫶-mips64r2— MIPS64 Release 2 👑-mips64r3— MIPS64 Release 3 💅-mips64r5— MIPS64 Release 5 🦋-mips64r6— MIPS64 Release 6 🌸-mips16— MIPS16 ✨-mno-mips16— no MIPS16 🔥-mflip-mips16— flip MIPS16 🧚-minterlink-compressed— interlink compressed 💜-mno-interlink-compressed— no interlink compressed 🌈-minterlink-mips16— interlink MIPS16 ⭐-mno-interlink-mips16— no interlink MIPS16 💀-mabi=abi— pick the ABI 🍓-mabicalls— abicalls on 🫶-mno-abicalls— abicalls off 👑-mshared— shared on 💅-mno-shared— shared off 🦋-mplt— PLT on 🌸-mno-plt— PLT off ✨-mxgot— xgot on 🔥-mno-xgot— xgot off 🧚-mgp32— GP32 💜-mgp64— GP64 🌈-mfp32— FP32 ⭐-mfpxx— FPXX 💀-mfp64— FP64 🍓-mhard-float— hard float 🫶-msoft-float— soft float 👑-mno-float— no float 💅-msingle-float— single float 🦋-mdouble-float— double float 🌸-modd-spreg— odd single regs on ✨-mno-odd-spreg— odd single regs off 🔥-mabs=mode— pick the abs mode 🧚-mnan=encoding— pick the NaN encoding 💜-mdsp— DSP on 🌈-mno-dsp— DSP off ⭐-mdspr2— DSP Rev 2 on 💀-mno-dspr2— DSP Rev 2 off 🍓-mmcu— MCU on 🫶-mmno-mcu— MCU off 👑-meva— EVA on 💅-mno-eva— EVA off 🦋-mvirt— virt on 🌸-mno-virt— virt off ✨-mxpa— XPA on 🔥-mno-xpa— XPA off 🧚-mcrc— CRC on 💜-mno-crc— CRC off 🌈-mginv— ginv on ⭐-mno-ginv— ginv off 💀-mmicromips— microMIPS on 🍓-mno-micromips— microMIPS off 🫶-mmsa— MSA on 👑-mno-msa— MSA off 💅-mloongson-mmi— Loongson MMI on 🦋-mno-loongson-mmi— Loongson MMI off 🌸-mloongson-ext— Loongson EXT on ✨-mno-loongson-ext— Loongson EXT off 🔥-mloongson-ext2— Loongson EXT2 on 🧚-mno-loongson-ext2— Loongson EXT2 off 💜-mfpu=fpu-type— pick the FPU type 🌈-msmartmips— SmartMIPS on ⭐-mno-smartmips— SmartMIPS off 💀-mpaired-single— paired single on 🍓-mno-paired-single— paired single off 🫶-mdmx— DMX on 👑-mno-mdmx— DMX off 💅-mips3d— MIPS-3D on 🦋-mno-mips3d— MIPS-3D off 🌸-mmt— MT on ✨-mno-mt— MT off 🔥-mllsc— LLSC on 🧚-mno-llsc— LLSC off 💜-mlong64— long is 64-bit 🌈-mlong32— long is 32-bit ⭐-msym32— sym32 on 💀-mno-sym32— sym32 off 🍓-Gnum— the-Gsize limit, set tonum🫶-mlocal-sdata— local sdata on 👑-mno-local-sdata— local sdata off 💅-mextern-sdata— extern sdata on 🦋-mno-extern-sdata— extern sdata off 🌸-mgpopt— gpopt on ✨-mno-gopt— gopt off 🔥-membedded-data— embedded data on 🧚-mno-embedded-data— embedded data off 💜-muninit-const-in-rodata— uninit const in rodata on 🌈-mno-uninit-const-in-rodata— uninit const in rodata off ⭐-mcode-readable=setting— pick the code-readable setting 💀-msplit-addresses— split addresses on 🍓-mno-split-addresses— split addresses off 🫶-mexplicit-relocs— explicit relocs on 👑-mno-explicit-relocs— explicit relocs off 💅-mexplicit-relocs=release— explicit relocs withrelease🦋-mcheck-zero-division— check for zero division 🌸-mno-check-zero-division— skip that check ✨-mdivide-traps— divide traps 🔥-mdivide-breaks— divide breaks 🧚-mload-store-pairs— load-store pairs on 💜-mno-load-store-pairs— load-store pairs off 🌈-mstrict-align— strict alignment ⭐-mno-strict-align— no strict alignment 💀-mno-unaligned-access— no unaligned access 🍓-munaligned-access— unaligned access 🫶-mmemcpy— memcpy on 👑-mno-memcpy— memcpy off 💅-mlong-calls— long calls on 🦋-mno-long-calls— long calls off 🌸-mmad— MAD on ✨-mno-mad— MAD off 🔥-mimadd— imadd on 🧚-mno-imadd— imadd off 💜-mfused-madd— fused madd on 🌈-mno-fused-madd— fused madd off ⭐-nocpp— no preprocessing 💀-mfix-24k— fix the 24K 🍓-mno-fix-24k— don't fix the 24K 🫶-mfix-r4000— fix the R4000 👑-mno-fix-r4000— don't fix the R4000 💅-mfix-r4400— fix the R4400 🦋-mno-fix-r4400— don't fix the R4400 🌸-mfix-r5900— fix the R5900 ✨-mno-fix-r5900— don't fix the R5900 🔥-mfix-r10000— fix the R10000 🧚-mno-fix-r10000— don't fix the R10000 💜-mfix-rm7000— fix the RM7000 🌈-mno-fix-rm7000— don't fix the RM7000 ⭐-mfix-vr4120— fix the VR4120 💀-mno-fix-vr4120— don't fix the VR4120 🍓-mfix-vr4130— fix the VR4130 🫶-mno-fix-vr4130— don't fix the VR4130 👑-mfix-sb1— fix the SB-1 💅-mno-fix-sb1— don't fix the SB-1 🦋-mflush-func=func— flush function namedfunc🌸-mno-flush-func— no flush function ✨-mbranch-cost=num— set the branch cost tonum🔥-mbranch-likely— branch likely on 🧚-mno-branch-likely— branch likely off 💜-mcompact-branches=policy— pick the compact branches policy 🌈-mfp-exceptions— FP exceptions on ⭐-mno-fp-exceptions— FP exceptions off 💀-mvr4130-align— VR4130 align on 🍓-mno-vr4130-align— VR4130 align off 🫶-msynci— synci on 👑-mno-synci— synci off 💅-mlxc1-sxc1— lxc1/sxc1 on 🦋-mno-lxc1-sxc1— lxc1/sxc1 off 🌸-mmadd4— madd4 on ✨-mno-madd4— madd4 off 🔥-mrelax-pic-calls— relax PIC calls on 🧚-mno-relax-pic-calls— relax PIC calls off 💜-mmcount-ra-address— mcount RA address 🌈-mframe-header-opt— frame header opt on ⭐-mno-frame-header-opt— frame header opt off 💀
🦋 MMIX Options
-mlibfuncs— library functions on 🍓-mno-libfuncs— library functions off 🫶-mepsilon— epsilon on 👑-mno-epsilon— epsilon off 💅-mabi=gnu— the GNU ABI 🦋-mabi=mmixware— the mmixware ABI 🌸-mzero-extend— zero extend ✨-mknuthdiv— Knuth div 🔥-mtoplevel-symbols— top-level symbols 🧚-melf— ELF 💜-mbranch-predict— branch predict on 🌈-mno-branch-predict— branch predict off ⭐-mbase-addresses— base addresses on 💀-mno-base-addresses— base addresses off 🍓-msingle-exit— single exit 🫶-mno-single-exit— no single exit 👑
🦋 MN10300 Options
-mmult-bug— mult bug on 💅-mno-mult-bug— mult bug off 🦋-mno-am33— no AM33 🌸-mam33— AM33 ✨-mam33-2— AM33-2 🔥-mam34— AM34 🧚-mtune=cpu-type— tune for the CPU type 💜-mreturn-pointer-on-d0— return pointer on D0 🌈-mno-crt0— no crt0 ⭐-mrelax— relax 💀-mliw— LIW on 🍓-msetlb— SETLB on 🫶
🦋 Moxie Options
-meb— big endian 👑-mel— little endian 💅-mmul.x— mul.x on 🦋-mno-crt0— no crt0 🌸
🦋 MSP430 Options
-msim— simulator mode ✨-masm-hex— assembler hex 🔥-mmcu=— pick the MCU 🧚-mcpu=— pick the CPU 💜-mlarge— large model 🌈-msmall— small model ⭐-mrelax— relax 💀-mwarn-mcu— warn about the MCU 🍓-mcode-region=— code region 🫶-mdata-region=— data region 👑-msilicon-errata=— silicon errata 💅-msilicon-errata-warn=— silicon errata warnings 🦋-mhwmult=— hardware multiply 🌸-minrt— minimal runtime ✨-mtiny-printf— tiny printf 🔥-mmax-inline-shift=— max inline shift 🧚
🦋 NDS32 Options
-mbig-endian— big endian 💜-mlittle-endian— little endian 🌈-mreduced-regs— reduced regs ⭐-mfull-regs— full regs 💀-mcmov— cmov on 🍓-mno-cmov— cmov off 🫶-mext-perf— ext-perf on 👑-mno-ext-perf— ext-perf off 💅-mext-perf2— ext-perf2 on 🦋-mno-ext-perf2— ext-perf2 off 🌸-mext-string— ext-string on ✨-mno-ext-string— ext-string off 🔥-mv3push— v3push on 🧚-mno-v3push— v3push off 💜-m16bit— 16-bit on 🌈-mno-16bit— 16-bit off ⭐-misr-vector-size=num— ISR vector sizenum💀-mcache-block-size=num— cache block sizenum🍓-march=arch— pick the arch 🫶-mcmodel=code-model— pick the code model 👑-mctor-dtor— ctor/dtor on 💅-mrelax— relax 🦋
🦋 Nios II Options
-G num— the-Gsize limit, set tonum🌸-mgpopt=option— gpopt withoption✨-mgpopt— gpopt on 🔥-mno-gpopt— gpopt off 🧚-mgprel-sec=regexp— gprel section matchingregexp💜-mr0rel-sec=regexp— r0rel section matchingregexp🌈-mel— little endian ⭐-meb— big endian 💀-mno-bypass-cache— bypass cache off 🍓-mbypass-cache— bypass cache on 🫶-mno-cache-volatile— cache volatile off 👑-mcache-volatile— cache volatile on 💅-mno-fast-sw-div— fast software div off 🦋-mfast-sw-div— fast software div on 🌸-mhw-mul— hardware mul on ✨-mno-hw-mul— hardware mul off 🔥-mhw-mulx— hardware mulx on 🧚-mno-hw-mulx— hardware mulx off 💜-mno-hw-div— hardware div off 🌈-mhw-div— hardware div on ⭐-mcustom-insn=N— custom instructionN💀-mno-custom-insn— no custom instructions 🍓-mcustom-fpu-cfg=name— custom FPU configname🫶-mhal— HAL on 👑-msmallc— smallc on 💅-msys-crt0=name— sys crt0 namedname🦋-msys-lib=name— sys lib namedname🌸-march=arch— pick the arch ✨-mbmx— BMX on 🔥-mno-bmx— BMX off 🧚-mcdx— CDX on 💜-mno-cdx— CDX off 🌈
🦋 Nvidia PTX Options
-m64— 64-bit 💅-mmainkernel— main kernel ✨-moptimize— optimize 🔥
🦋 OpenRISC Options
-mboard=name— board namedname🧚-mnewlib— newlib 💜-mhard-mul— hard mul 🌈-mhard-div— hard div ⭐-msoft-mul— soft mul 💀-msoft-div— soft div 🍓-msoft-float— soft float 🫶-mhard-float— hard float 👑-mdouble-float— double float 💅-munordered-float— unordered float 🦋-mcmov— cmov 🌸-mror— ror ✨-mrori— rori 🔥-msext— sext 🧚-msfimm— sfimm 💜-mshftimm— shftimm 🌈-mcmodel=code-model— pick the code model ⭐
🦋 PDP-11 Options
-mfpu— FPU on 💀-msoft-float— soft float 🍓-mac0— ac0 on 🫶-mno-ac0— ac0 off 👑-m40— 40 💅-m45— 45 🦋-m10— 10 🌸-mint32— int32 ✨-mno-int16— no int16 🔥-mint16— int16 🧚-mno-int32— no int32 💜-msplit— split 🌈-munix-asm— Unix assembler ⭐-mdec-asm— DEC assembler 💀-mgnu-asm— GNU assembler 🍓-mlra— LRA 🫶
🦋 PowerPC Options
See RS/6000 and PowerPC Options. 👑
🦋 PRU Options
-mmcu=mcu— pick the MCUmcu💅-minrt— minimal runtime 🦋-mno-relax— relax off 🌸-mloop— loop on ✨-mabi=variant— pick the ABI variant 🔥
🦋 RISC-V Options
-mbranch-cost=N-instruction— branch cost inN-instruction🧚-mplt— PLT on 💜-mno-plt— PLT off 🌈-mabi=ABI-string— pick the ABI string ⭐-mfdiv— fdiv on 💀-mno-fdiv— fdiv off 🍓-mdiv— div on 🫶-mno-div— div off 👑-misa-spec=ISA-spec-string— pick the ISA spec string 💅-march=ISA-string— pick the ISA string 🦋-mtune=processor-string— tune for the processor string 🌸-mpreferred-stack-boundary=num— preferred stack boundarynum✨-msmall-data-limit=N-bytes— small data limit inN-bytes🔥-msave-restore— save/restore on 🧚-mno-save-restore— save/restore off 💜-mshorten-memrefs— shorten memrefs on 🌈-mno-shorten-memrefs— shorten memrefs off ⭐-mstrict-align— strict alignment 💀-mno-strict-align— no strict alignment 🍓-mcmodel=medlow— medlow code model 🫶-mcmodel=medany— medany code model 👑-mexplicit-relocs— explicit relocs on 💅-mno-explicit-relocs— explicit relocs off 🦋-mrelax— relax on 🌸-mno-relax— relax off ✨-mriscv-attribute— RISC-V attributes on 🔥-mno-riscv-attribute— RISC-V attributes off 🧚-malign-data=type— align data bytype💜-mbig-endian— big endian 🌈-mlittle-endian— little endian ⭐-mstack-protector-guard=guard— stack protector guardguard💀-mstack-protector-guard-reg=reg— stack protector guard registerreg🍓-mstack-protector-guard-offset=offset— stack protector guard offsetoffset🫶-mcsr-check— CSR check on 👑-mno-csr-check— CSR check off 💅-mmovcc— movcc on 🦋-mno-movcc— movcc off 🌸-minline-atomics— inline atomics on ✨-mno-inline-atomics— inline atomics off 🔥-minline-strlen— inline strlen on 🧚-mno-inline-strlen— inline strlen off 💜-minline-strcmp— inline strcmp on 🌈-mno-inline-strcmp— inline strcmp off ⭐-minline-strncmp— inline strncmp on 💀-mno-inline-strncmp— inline strncmp off 🍓-mtls-dialect=desc— TLS dialectdesc🫶-mtls-dialect=trad— TLS dialecttrad👑
🦋 RL78 Options
-msim— simulator mode 💅-mmul=none— no multiply 🦋-mmul=g13— multiply for G13 🌸-mmul=g14— multiply for G14 ✨-mallregs— all regs 🔥-mcpu=g10— CPU G10 🧚-mcpu=g13— CPU G13 💜-mcpu=g14— CPU G14 🌈-mg10— G10 ⭐-mg13— G13 💀-mg14— G14 🍓-m64bit-doubles— 64-bit doubles 🫶-m32bit-doubles— 32-bit doubles 👑-msave-mduc-in-interrupts— save MDUC in interrupts 💅
🦋 RS/6000 and PowerPC Options
-mcpu=cpu-type— pick the CPU type 🦋-mtune=cpu-type— tune for the CPU type 🌸-mcmodel=code-model— pick the code model ✨-mpowerpc64— PowerPC64 🔥-maltivec— AltiVec on 🧚-mno-altivec— AltiVec off 💜-mpowerpc-gpopt— PowerPC gpopt on 🌈-mno-powerpc-gpopt— PowerPC gpopt off ⭐-mpowerpc-gfxopt— PowerPC gfxopt on 💀-mno-powerpc-gfxopt— PowerPC gfxopt off 🍓-mmfcrf— mfcrf on 🫶-mno-mfcrf— mfcrf off 👑-mpopcntb— popcntb on 💅-mno-popcntb— popcntb off 🦋-mpopcntd— popcntd on 🌸-mno-popcntd— popcntd off ✨-mfprnd— fprnd on 🔥-mno-fprnd— fprnd off 🧚-mcmpb— cmpb on 💜-mno-cmpb— cmpb off 🌈-mhard-dfp— hard DFP on ⭐-mno-hard-dfp— hard DFP off 💀-mfull-toc— full TOC 🍓-mminimal-toc— minimal TOC 🫶-mno-fp-in-toc— no FP in TOC 👑-mno-sum-in-toc— no sum in TOC 💅-m64— 64-bit 🦋-m32— 32-bit 🌸-mxl-compat— XL compat on ✨-mno-xl-compat— XL compat off 🔥-mpe— PE on 🧚-malign-power— align power 💜-malign-natural— align natural 🌈-msoft-float— soft float ⭐-mhard-float— hard float 💀-mmultiple— multiple on 🍓-mno-multiple— multiple off 🫶-mupdate— update on 👑-mno-update— update off 💅-mavoid-indexed-addresses— avoid indexed addresses 🦋-mno-avoid-indexed-addresses— don't avoid indexed addresses 🌸-mfused-madd— fused madd on ✨-mno-fused-madd— fused madd off 🔥-mbit-align— bit align on 🧚-mno-bit-align— bit align off 💜-mstrict-align— strict alignment 🌈-mno-strict-align— no strict alignment ⭐-mrelocatable— relocatable on 💀-mno-relocatable— relocatable off 🍓-mrelocatable-lib— relocatable lib on 🫶-mno-relocatable-lib— relocatable lib off 👑-mtoc— TOC on 💅-mno-toc— TOC off 🦋-mlittle— little 🌸-mlittle-endian— little endian ✨-mbig— big 🔥-mbig-endian— big endian 🧚-mdynamic-no-pic— dynamic no PIC 💜-mswdiv— swdiv on 🌈-msingle-pic-base— single PIC base ⭐-mprioritize-restricted-insns=priority— prioritize restricted insns bypriority💀-msched-costly-dep=dependence_type— costly dependence typedependence_type🍓-minsert-sched-nops=scheme— insert sched nops withscheme🫶-mcall-aixdesc— AIX descriptors 👑-mcall-eabi— EABI 💅-mcall-freebsd— FreeBSD calls 🦋-mcall-linux— Linux calls 🌸-mcall-netbsd— NetBSD calls ✨-mcall-openbsd— OpenBSD calls 🔥-mcall-sysv— SysV calls 🧚-mcall-sysv-eabi— SysV EABI calls 💜-mcall-sysv-noeabi— SysV no-EABI calls 🌈-mtraceback=traceback_type— traceback typetraceback_type⭐-maix-struct-return— AIX struct return 💀-msvr4-struct-return— SVR4 struct return 🍓-mabi=abi-type— pick the ABI type 🫶-msecure-plt— secure PLT 👑-mbss-plt— BSS PLT 💅-mlongcall— long call on 🦋-mno-longcall— long call off 🌸-mpltseq— PLT seq on ✨-mno-pltseq— PLT seq off 🔥-mblock-move-inline-limit=num— block move inline limitnum🧚-mblock-compare-inline-limit=num— block compare inline limitnum💜-mblock-compare-inline-loop-limit=num— block compare inline loop limitnum🌈-mno-block-ops-unaligned-vsx— no unaligned VSX block ops ⭐-mstring-compare-inline-limit=num— string compare inline limitnum💀-misel— isel on 🍓-mno-isel— isel off 🫶-mvrsave— vrsave on 👑-mno-vrsave— vrsave off 💅-mmulhw— mulhw on 🦋-mno-mulhw— mulhw off 🌸-mdlmzb— dlmzb on ✨-mno-dlmzb— dlmzb off 🔥-mprototype— prototype on 🧚-mno-prototype— prototype off 💜-msim— simulator mode 🌈-mmvme— MVME ⭐-mads— ADS 💀-myellowknife— Yellowknife 🍓-memb— EMB 🫶-msdata— sdata on 👑-msdata=opt— sdata withopt💅-mreadonly-in-sdata— readonly in sdata 🦋-mvxworks— VxWorks 🌸-G num— the-Gsize limit, set tonum✨-mrecip— reciprocal approximations 🔥-mrecip=opt— reciprocal approximations, with options 🧚-mno-recip— reciprocal approximations off 💜-mrecip-precision— reciprocal precision on 🌈-mno-recip-precision— reciprocal precision off ⭐-mveclibabi=type— vector lib ABItype💀-mfriz— friz on 🍓-mno-friz— friz off 🫶-mpointers-to-nested-functions— pointers to nested functions on 👑-mno-pointers-to-nested-functions— pointers to nested functions off 💅-msave-toc-indirect— save TOC indirect on 🦋-mno-save-toc-indirect— save TOC indirect off 🌸-mpower8-fusion— POWER8 fusion on ✨-mno-mpower8-fusion— POWER8 fusion off 🔥-mcrypto— crypto on 🧚-mno-crypto— crypto off 💜-mhtm— HTM on 🌈-mno-htm— HTM off ⭐-mquad-memory— quad memory on 💀-mno-quad-memory— quad memory off 🍓-mquad-memory-atomic— quad memory atomic on 🫶-mno-quad-memory-atomic— quad memory atomic off 👑-mcompat-align-parm— compat align parm on 💅-mno-compat-align-parm— compat align parm off 🦋-mfloat128— float128 on 🌸-mno-float128— float128 off ✨-mfloat128-hardware— float128 hardware on 🔥-mno-float128-hardware— float128 hardware off 🧚-mgnu-attribute— GNU attribute on 💜-mno-gnu-attribute— GNU attribute off 🌈-mstack-protector-guard=guard— stack protector guardguard⭐-mstack-protector-guard-reg=reg— stack protector guard registerreg💀-mstack-protector-guard-offset=offset— stack protector guard offsetoffset🍓-mprefixed— prefixed on 🫶-mno-prefixed— prefixed off 👑-mpcrel— PC-relative on 💅-mno-pcrel— PC-relative off 🦋-mmma— MMA on 🌸-mno-mmma— MMA off ✨-mrop-protect— ROP protect on 🔥-mno-rop-protect— ROP protect off 🧚-mprivileged— privileged on 💜-mno-privileged— privileged off 🌈
✨ RX Options ✨
RX gets its whole own little flex list 🎀 every flag, no skipping 💅
-m64bit-doubles -m32bit-doubles -fpu -nofpu -mcpu=
-mbig-endian-data -mlittle-endian-data -msmall-data -msim -mno-sim
-mas100-syntax -mno-as100-syntax -mrelax -mmax-constant-size=
-mint-register= -mpid -mallow-string-insns -mno-allow-string-insns
-mjsr -mno-warn-multiple-fast-interrupts -msave-acc-in-interrupts✨ S/390 and zSeries Options ✨
the S/390 crew is giving main character energy 🦋
-mtune=cpu-type -march=cpu-type
-mhard-float -msoft-float -mhard-dfp -mno-hard-dfp
-mlong-double-64 -mlong-double-128 -mbackchain -mno-backchain
-mpacked-stack -mno-packed-stack -msmall-exec -mno-small-exec
-mmvcle -mno-mvcle -m64 -m31 -mdebug -mno-debug -mesa -mzarch
-mhtm -mvx -mzvector -mtpf-trace -mno-tpf-trace -mtpf-trace-skip
-mno-tpf-trace-skip -mfused-madd -mno-fused-madd -mwarn-framesize
-mwarn-dynamicstack -mstack-size -mstack-guard
-mhotpatch=halfwords,halfwords✨ SH Options ✨
SH has so many flags it's lowkey a whole lifestyle 💅🌈
-m1 -m2 -m2e -m2a-nofpu -m2a-single-only -m2a-single
-m2a -m3 -m3e -m4-nofpu -m4-single-only -m4-single -m4
-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al -mb -ml
-mdalign -mrelax -mbigtable -mfmovd -mrenesas -mno-renesas
-mnomacsave -mieee -mno-ieee -mbitops -misize
-minline-ic_invalidate -mpadstruct -mprefergot -musermode
-multcost=number -mdiv=strategy -mdivsi3_libfunc=name
-mfixed-range=register-range -maccumulate-outgoing-args
-matomic-model=atomic-model -mbranch-cost=num -mzdcbranch
-mno-zdcbranch -mcbranch-force-delay-slot -mfused-madd
-mno-fused-madd -mfsca -mno-fsca -mfsrra -mno-fsrra
-mpretend-cmove -mtas✨ Solaris 2 Options ✨
Solaris 2 keeping it short and sweet 🌸
-mclear-hwcap -mno-clear-hwcap -mimpure-text
-mno-impure-text -pthreads✨ SPARC Options ✨
SPARC is a big one, bestie, so grab a snack 🍓
-mcpu=cpu-type -mtune=cpu-type -mcmodel=code-model
-mmemory-model=mem-model -m32 -m64 -mapp-regs -mno-app-regs
-mfaster-structs -mno-faster-structs -mflat -mno-flat -mfpu
-mno-fpu -mhard-float -msoft-float -mhard-quad-float
-msoft-quad-float -mstack-bias -mno-stack-bias -mstd-struct-return
-mno-std-struct-return -munaligned-doubles -mno-unaligned-doubles
-muser-mode -mno-user-mode -mv8plus -mno-v8plus -mvis -mno-vis
-mvis2 -mno-vis2 -mvis3 -mno-vis3 -mvis4 -mno-vis4 -mvis4b
-mno-vis4b -mcbcond -mno-cbcond -mfmaf -mno-fmaf -mfsmuld
-mno-fsmuld -mpopc -mno-popc -msubxc -mno-subxc -mfix-at697f
-mfix-ut699 -mfix-ut700 -mfix-gr712rc -mlra -mno-lra✨ System V Options ✨
old school but still iconic 👑
-Qy -Qn -YP,paths -Ym,dir✨ V850 Options ✨
the V850 list is giving lots of options, babe 💖
-mlong-calls -mno-long-calls -mep -mno-ep
-mprolog-function -mno-prolog-function -mspace -mtda=n -msda=n
-mzda=n -mapp-regs -mno-app-regs -mdisable-callt
-mno-disable-callt -mv850e2v3 -mv850e2 -mv850e1 -mv850es -mv850e
-mv850 -mv850e3v5 -mloop -mrelax -mlong-jumps -msoft-float
-mhard-float -mgcc-abi -mrh850-abi -mbig-switch✨ VAX Options ✨
VAX is tiny and cute 🧚
-mg -mgnu -munix -mlra✨ Visium Options ✨
Visium, you're so put together 💅
-mdebug -msim -mfpu -mno-fpu -mhard-float
-msoft-float -mcpu=cpu-type -mtune=cpu-type -msv-mode -muser-mode✨ VMS Options ✨
VMS flags, serving return codes and malloc drama 🎀
-mvms-return-codes -mdebug-main=prefix -mmalloc64
-mpointer-size=size✨ VxWorks Options ✨
VxWorks is lowkey a vibe check 🦋
-mrtp -msmp -non-static -Bstatic -Bdynamic
-Xbind-lazy -Xbind-now✨ x86 Options ✨
x86 is the biggest girlie of them all and it's not even close 👑💅✨
-mtune=cpu-type -march=cpu-type -mtune-ctrl=feature-list -mdump-tune-features -mno-default -mfpmath=unit -masm=dialect
-mno-fancy-math-387 -mno-fp-ret-in-387 -m80387 -mhard-float
-msoft-float -mno-wide-multiply -mrtd -malign-double
-mpreferred-stack-boundary=num -mincoming-stack-boundary=num -mcld
-mcx16 -msahf -mmovbe -mcrc32 -mmwait -mrecip -mrecip=opt
-mvzeroupper -mprefer-avx128 -mprefer-vector-width=opt
-mpartial-vector-fp-math -mmove-max=bits -mstore-max=bits
-mnoreturn-no-callee-saved-registers -mmmx -msse -msse2 -msse3
-mssse3 -msse4.1 -msse4.2 -msse4 -mavx -mavx2 -mavx512f
-mavx512pf -mavx512er -mavx512cd -mavx512vl -mavx512bw
-mavx512dq -mavx512ifma -mavx512vbmi -msha -maes -mpclmul
-mfsgsbase -mrdrnd -mf16c -mfma -mpconfig -mwbnoinvd -mptwrite
-mprefetchwt1 -mclflushopt -mclwb -mxsavec -mxsaves -msse4a
-m3dnow -m3dnowa -mpopcnt -mabm -mbmi -mtbm -mfma4 -mxop
-madx -mlzcnt -mbmi2 -mfxsr -mxsave -mxsaveopt -mrtm -mhle
-mlwp -mmwaitx -mclzero -mpku -mthreads -mgfni -mvaes
-mwaitpkg -mshstk -mmanual-endbr -mcet-switch -mforce-indirect-call
-mavx512vbmi2 -mavx512bf16 -menqcmd -mvpclmulqdq -mavx512bitalg
-mmovdiri -mmovdir64b -mavx512vpopcntdq -mavx5124fmaps
-mavx512vnni -mavx5124vnniw -mprfchw -mrdpid -mrdseed -msgx
-mavx512vp2intersect -mserialize -mtsxldtrk -mamx-tile -mamx-int8
-mamx-bf16 -muintr -mhreset -mavxvnni -mavx512fp16 -mavxifma
-mavxvnniint8 -mavxneconvert -mcmpccxadd -mamx-fp16 -mprefetchi
-mraoint -mamx-complex -mavxvnniint16 -msm3 -msha512 -msm4 -mapxf
-musermsr -mavx10.1 -mavx10.1-256 -mavx10.1-512 -mevex512 -mcldemote
-mms-bitfields -mno-align-stringops -minline-all-stringops
-minline-stringops-dynamically -mstringop-strategy=alg -mkl
-mwidekl -mmemcpy-strategy=strategy -mmemset-strategy=strategy
-mpush-args -maccumulate-outgoing-args -m128bit-long-double
-m96bit-long-double -mlong-double-64 -mlong-double-80
-mlong-double-128 -mregparm=num -msseregparm -mveclibabi=type
-mvect8-ret-in-mem -mpc32 -mpc64 -mpc80 -mdaz-ftz -mstackrealign
-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs
-mcmodel=code-model -mabi=name -maddress-mode=mode -m32 -m64
-mx32 -m16 -miamcu -mlarge-data-threshold=num -msse2avx -mfentry
-mrecord-mcount -mnop-mcount -m8bit-idiv -minstrument-return=type
-mfentry-name=name -mfentry-section=name
-mavx256-split-unaligned-load -mavx256-split-unaligned-store
-malign-data=type -mstack-protector-guard=guard
-mstack-protector-guard-reg=reg
-mstack-protector-guard-offset=offset
-mstack-protector-guard-symbol=symbol -mgeneral-regs-only
-mcall-ms2sysv-xlogues -mrelax-cmpxchg-loop -mindirect-branch=choice
-mfunction-return=choice -mindirect-branch-register
-mharden-sls=choice -mindirect-branch-cs-prefix -mneeded
-mno-direct-extern-access -munroll-only-small-loops -mlam=choice✨ x86 Windows Options ✨
Windows x86 bringing the drama 🌈
-mconsole -mcrtdll=library -mdll
-mnop-fun-dllimport -mthread -municode -mwin32 -mwindows
-fno-set-stack-executable✨ Xstormy16 Options ✨
Xstormy16 just has the one, but it's a good one 🫶
-msim✨ Xtensa Options ✨
Xtensa has a whole collection going on 🧚💜
-mconst16 -mno-const16 -mfused-madd -mno-fused-madd
-mforce-no-pic -mserialize-volatile -mno-serialize-volatile
-mtext-section-literals -mno-text-section-literals -mauto-litpools
-mno-auto-litpools -mtarget-align -mno-target-align -mlongcalls
-mno-longcalls -mabi=abi-type -mextra-l32r-costs=cycles
-mstrict-align -mno-strict-align✨ zSeries Options ✨
zSeries is just S/390 in a new outfit, so no need to repeat yourself 🙈
See S/390 and zSeries Options.
✨ Options Controlling the Kind of Output ✨
Okay so, compiling can have up to four stages: preprocessing, compilation proper, assembly, and linking, always in that order 💅. GCC can preprocess and compile several files into several assembler input files, or squish them all into one assembler input file. Then each assembler input file makes an object file, and linking glues all the object files together (the ones just compiled and the ones you handed it) into an executable file ✨.
For any given input file, the file name suffix decides what kind of compilation happens:
file.c— C source code that must be preprocessed.file.i— C source code that should not be preprocessed.file.ii— C++ source code that should not be preprocessed.file.m— Objective-C source code. Note that you must link with thelibobjclibrary to make an Objective-C program work.file.mi— Objective-C source code that should not be preprocessed.file.mm,file.M— Objective-C++ source code. Note that you must link with thelibobjclibrary to make an Objective-C++ program work. Note that.Mrefers to a literal capitalM.file.mii— Objective-C++ source code that should not be preprocessed.file.h— C, C++, Objective-C or Objective-C++ header file to be turned into a precompiled header (default), or C, C++ header file to be turned into an Ada spec (via the-fdump-ada-specswitch).file.cc,file.cp,file.cxx,file.cpp,file.CPP,file.c++,file.C— C++ source code that must be preprocessed. Note that in.cxx, the last two letters must both be literallyx. Likewise,.Crefers to a literal capitalC.file.mm,file.M— Objective-C++ source code that must be preprocessed.file.mii— Objective-C++ source code that should not be preprocessed.file.hh,file.H,file.hp,file.hxx,file.hpp,file.HPP,file.h++,file.tcc— C++ header file to be turned into a precompiled header or Ada spec.file.f,file.for,file.ftn,file.fi— Fixed form Fortran source code that should not be preprocessed.file.F,file.FOR,file.fpp,file.FPP,file.FTN— Fixed form Fortran source code that must be preprocessed (with the traditional preprocessor).file.f90,file.f95,file.f03,file.f08,file.fii— Free form Fortran source code that should not be preprocessed.file.F90,file.F95,file.F03,file.F08— Free form Fortran source code that must be preprocessed (with the traditional preprocessor).file.go— Go source code.file.d— D source code.file.di— D interface file.file.dd— D documentation code (Ddoc).file.ads— Ada source code file that contains a library unit declaration (a declaration of a package, subprogram, or generic, or a generic instantiation), or a library unit renaming declaration (a package, generic, or subprogram renaming declaration). Such files are also called specs.file.adb— Ada source code file containing a library unit body (a subprogram or package body). Such files are also called bodies.file.s— Assembler code.file.S,file.sx— Assembler code that must be preprocessed.other— An object file to be fed straight into linking. Any file name with no recognized suffix is treated this way.
You can specify the input language explicitly with the -x option:
-x language— okay bestie, this one lets you spill the tea on what language your next input files are written in, so gcc doesn't have to guess from the file name suffix 🔮 It sticks for every input file after it until the next-xshows up. Your choices for language are:c,c-header,cpp-outputc++,c++-header,c++-system-header,c++-user-header,c++-cpp-outputobjective-c,objective-c-header,objective-c-cpp-outputobjective-c++,objective-c++-header,objective-c++-cpp-outputassembler,assembler-with-cppadadf77,f77-cpp-input,f95,f95-cpp-inputgo
-x none— the main character move to undo all that 💅 It turns off any language specification, so the files after it get handled by their file name suffixes again, exactly like-xnever existed. ✨
Okay so if you only want some of the compilation stages 🧚, you can use -x (or filename suffixes) to tell gcc where to start, and then pick one of -c, -S, or -E to say where it should stop. Heads up though, some combos (like -x cpp-output -E) literally make gcc do nothing at all 💀
-c— compile or assemble the source files, but don't link 🌸 The linking stage just gets skipped, and you end up with an object file for each source file.- By default, the object file name for a source file is made by swapping the suffix
.c,.i,.s, etc. for.o. - Unrecognized input files, which don't need compiling or assembling, get ignored.
- By default, the object file name for a source file is made by swapping the suffix
-S— stop after the compilation proper and don't assemble 🦋 You get an assembler code file for each non-assembler input file you gave it.- By default, the assembler file name is made by swapping the suffix
.c,.i, etc. for.s. - Input files that don't need compilation are ignored.
- By default, the assembler file name is made by swapping the suffix
-E— stop after preprocessing and skip the compiler proper 🍓 The preprocessed source code gets sent to the standard output.- Input files that don't need preprocessing are ignored.
-o file— put the primary output intofile💖 This works for whatever you're making: an executable, an object file, an assembler file, or preprocessed C code.- If you don't specify
-o, here's where things land: an executable goes ina.out, the object file forsource.suffixgoes insource.o, its assembler file goes insource.s, a precompiled header file goes insource.suffix.gch, and all the preprocessed C source gets printed to standard output.
- If you don't specify
Okay, the tea is that -o only names the primary output, but it also changes what your auxiliary and dump outputs get called 👀 See the examples below for the full picture. Unless you override it, both auxiliary and dump outputs get dropped into the same directory as the primary output. For auxiliary outputs, the input file's suffix gets swapped for the suffix of the auxiliary file type. For dump outputs, the dump file's suffix gets tacked onto the input file suffix. In compilation commands, the base name of both auxiliary and dump outputs is the primary output's base name. In compile and link commands, the primary output name (minus the executable suffix) gets combined with the input file name. If both share the same base name, ignoring the suffix, the result is just that base name. Otherwise they get smooshed together with a dash in between 🫶
gcc -c foo.c ...This uses foo.o as the primary output and puts the aux outputs and dumps right next to it. For example, you'd get the aux file foo.dwo for -gsplit-dwarf, and the dump file foo.c.???r.final for -fdump-rtl-final ✨
If you explicitly name a non-linker output file, aux and dump files take the same base name by default:
gcc -c foo.c -o dir/foobar.o ...This names the aux outputs dir/foobar.* and the dump outputs dir/foobar.c.* 🌈
A linker output does things a little differently, prefixing the aux and dump outputs instead:
gcc foo.c bar.c -o dir/foobar ...This will generally name the aux outputs dir/foobar-foo.* and dir/foobar-bar.*, and the dump outputs dir/foobar-foo.c.* and dir/foobar-bar.c.* 💅
The one exception is when the executable shares its base name with the single input:
gcc foo.c -o dir/foo ...In this case the aux outputs are named dir/foo.* and the dump outputs are named dir/foo.c.* 🎀
Want more control over where these land? You can adjust the location and names of auxiliary and dump outputs with -dumpbase, -dumpbase-ext, -dumpdir, -save-temps=cwd, and -save-temps=obj 🔥
-dumpbase dumpbase— this sets the base name for auxiliary and dump output files 🧁 It does not touch the name of the primary output. Intermediate outputs, if you choose to keep them, aren't considered primary outputs. They count as auxiliary outputs instead.
gcc -save-temps -S foo.cThis one saves the (no longer) temporary preprocessed file as foo.i, then compiles to the (implied) output file foo.s. Meanwhile:
gcc -save-temps -dumpbase save-foo -c foo.cThis preprocesses to save-foo.i, compiles to save-foo.s (which is now an intermediate, so it counts as an auxiliary output), and then assembles to the (implied) output file foo.o 🦋
Without this option, dump and aux files take their names from the input file, or from the (non-linker) output file if you explicitly gave one. Dump output files, like the ones requested by -fdump-* options, keep the input name suffix. Aux output files, like the ones requested by other non-dump options (for example -save-temps, -gsplit-dwarf, and -fcallgraph-info), drop it.
You can get similar suffix differentiation for dump and aux outputs with an explicitly given -dumpbase basename.suf by also specifying -dumpbase-ext .suf 🫶
If dumpbase is explicitly given with any directory component, then any dumppfx specification (like -dumpdir or -save-temps=*) gets ignored. Instead of being appended to it, dumpbase fully overrides it:
gcc foo.c -c -o dir/foo.o -dumpbase alt/foo \
-dumpdir pfx- -save-temps=cwd ...This creates aux and dump outputs named alt/foo.*, ignoring dir/ from -o, the ./ prefix implied by -save-temps=cwd, and pfx- from -dumpdir 💜
When -dumpbase shows up in a command that compiles multiple inputs, or that compiles and then links, it can get combined with a dumppfx, as explained under -dumpdir. Each input file then gets compiled using the combined dumppfx, and default values for dumpbase and auxdropsuf get computed for each input file:
gcc foo.c bar.c -c -dumpbase main ...This creates foo.o and bar.o as primary outputs. To avoid overwriting the aux and dump outputs, it uses the dumpbase as a prefix, so the outputs are named main-foo.* and main-bar.* 🌸
An empty string given as dumpbase avoids the influence of the output basename on naming aux and dump outputs during compilation, so the default values get computed instead:
gcc -c foo.c -o dir/foobar.o -dumpbase " ...This names the aux outputs dir/foo.* and the dump outputs dir/foo.c.*. Notice how the basenames come from the input name, but the directory still defaults to the output's directory 🍓
The empty-string dumpbase doesn't stop the output basename from being used for outputs during linking, though:
gcc foo.c bar.c -o dir/foobar -dumpbase " -flto ...The compilation of the source files names the aux outputs dir/foo.* and dir/bar.*, and the dump outputs dir/foo.c.* and dir/bar.c.*. LTO recompilation during linking uses dir/foobar. as the prefix for dumps and aux files 👑
-dumpbase-ext auxdropsuf— when forming the name of an auxiliary output file (but not a dump output), this drops the trailingauxdropsuffromdumpbasebefore any suffixes get appended 💖 If you don't specify it, it defaults to the suffix of a default dumpbase. That means the input file's suffix when-dumpbaseisn't on the command line, or when the dumpbase is combined with adumppfx.
gcc foo.c -c -o dir/foo.o -dumpbase x-foo.c -dumpbase-ext .c ...This creates dir/foo.o as the main output and generates aux outputs in dir/x-foo.*. They take the location of the primary output and drop the .c suffix from the dumpbase. Dump outputs keep the suffix, so they land in dir/x-foo.c.* ✨
This option gets ignored if it doesn't match the suffix of a specified dumpbase. The one exception is when it's used as an alternative to the executable suffix while appending the linker output base name to dumppfx, as described below:
gcc foo.c bar.c -o main.out -dumpbase-ext .out ...This creates main.out as the primary output. To avoid overwriting the aux and dump outputs, it uses the executable name minus auxdropsuf as a prefix. So the aux outputs get named main-foo.* and main-bar.*, and the dump outputs get named main-foo.c.* and main-bar.c.* 🦋
-dumpdir dumppfx— when forming the name of an auxiliary or dump output file, this usesdumppfxas a prefix 🌈
gcc -dumpdir pfx- -c foo.c ...This creates foo.o as the primary output and names the auxiliary outputs pfx-foo.*. It combines the given dumppfx with the default dumpbase, which comes from the default primary output, which in turn comes from the input name. Dump outputs also take the input name suffix, so they become pfx-foo.c.* 💅
If you want to use dumppfx as a directory name, it has to end with a directory separator:
gcc -dumpdir dir/ -c foo.c -o obj/bar.o ...This creates obj/bar.o as the primary output and names the auxiliary outputs dir/bar.*. It combines the given dumppfx with the default dumpbase derived from the primary output name. Dump outputs take the input name suffix too, so they land in dir/bar.c.* 🎀
By default it points at the location of the output file, unless the output file is a special file like /dev/null. The options -save-temps=cwd and -save-temps=obj override this default, just like an explicit -dumpdir option does. If you give multiple of these, the last one wins:
gcc -dumpdir pfx- -c foo.c -save-temps=obj ...This outputs foo.o, with the auxiliary outputs named foo.*, because -save-temps=* overrides the dumppfx from the earlier -dumpdir option. It doesn't matter that =obj is already the default for -save-temps, or that the output directory is implicitly the current directory. The dump outputs are named foo.c.* 🫶
When you compile from multiple input files and -dumpbase is set, the dumpbase name gets glued onto the dumppfx 💅. You drop an auxdropsuf suffix and add a dash. If the name has any directory components, it straight up overrides the explicit or defaulted dumppfx instead 🫶. Either way, each compilation gets differently-named aux and dump outputs ✨, which is giving organized.
gcc foo.c bar.c -c -dumpdir dir/pfx- -dumpbase main ...This one sends auxiliary dumps to dir/pfx-main-foo.* and dir/pfx-main-bar.*, because dumpbase- gets appended to dumppfx 🦋. The dump outputs keep the input file suffix instead: dir/pfx-main-foo.c.* and dir/pfx-main-bar.c.*, respectively.
Now compare that with the single-input version:
gcc foo.c -c -dumpdir dir/pfx- -dumpbase main ...Here -dumpbase is applied to one source, so it doesn't compute and append a separate dumpbase per input file 🙈. Its auxiliary and dump outputs just go in dir/pfx-main.*.
When you compile and then link from multiple input files, a defaulted or explicitly specified dumppfx also gets the dumpbase- transformation from above (like the foo.c and bar.c compile, but without -c). If you don't give -dumpdir or -dumpbase, the linker output base name gets the same treatment instead. You subtract auxdropsuf if it's specified, or the executable suffix otherwise, then add a dash and append the result to the default dumppfx. But heads up, this is different from the earlier linking cases:
gcc foo.c bar.c -dumpdir dir/pfx- -o main ...does not append the output name main to dumppfx, because -dumpdir is explicitly specified 💀. The vibe is that an explicit dumppfx can already include the output name in the prefix if you want it there ✨. Only an explicitly specified -dumpbase gets combined with it, so a meaningful option doesn't just get tossed out 💜.
When you compile and then link from a single input file, the linker output base name only gets appended to the default dumppfx (like above) if it doesn't share the base name with the single input file name. This was covered in the single-input linking cases above, but an explicit -dumpdir inhibits the combination, even if -save-temps=* overrides it:
gcc foo.c -dumpdir alt/pfx- -o dir/main.exe -save-temps=cwd ...Auxiliary outputs are named foo.*, and dump outputs foo.c.*, in the current working directory, as ultimately requested by -save-temps=cwd 🌸.
Summing it all up for an intuitive (though slightly imprecise) data flow 🧠: the primary output name gets split into a directory part and a basename part. dumppfx is set to the directory part, unless -dumpdir or -save-temps=* overrides it. dumpbase is set to the basename, unless -dumpbase overrides it. If there are multiple inputs or linking, this dumpbase may be combined with dumppfx and taken from each input file. Auxiliary output names for each input are formed by combining dumppfx, dumpbase minus its suffix, and the auxiliary output suffix. Dump output names only differ in that they keep the suffix from dumpbase.
When it comes to auxiliary and dump outputs created during LTO recompilation, a combination of dumppfx and dumpbase gets passed down to lto-wrapper as a -dumpdir option 💅. This happens whether it's given or derived from the linker output name (but not from the inputs), even in cases where that combination wouldn't otherwise get used. A trailing period replaces the compiler-added dash, if there is one. Since lto-wrapper is involved in linking, it doesn't normally get any -dumpbase or -dumpbase-ext, and it ignores them if it does.
When running sub-compilers, lto-wrapper appends the LTO stage names to the dumppfx it received. It makes sure that prefix contains a directory component, so it overrides any -dumpdir. Then it passes that along as -dumpbase to the sub-compilers 🎀.
-v— Prints the commands executed to run each stage of compilation to standard error. It also prints the version number of the compiler driver program, plus the version of the preprocessor and the compiler proper 🌈.-###— Like-v, except the commands never actually run, and arguments get quoted unless they only contain alphanumeric characters or"./-_". This is perfect for shell scripts that want to capture the driver-generated command lines 🧚.--help— Prints a description of the command-line optionsgccunderstands to standard output. If-vis also specified,--helpgets passed on to the various processesgccinvokes, so they can display the options they accept 🫶. If-Wextrawas specified prior to--helpon the command line, options with no documentation attached get displayed too 🔍.--target-help— Prints a description of the target-specific command-line options for each tool to standard output. For some targets, extra target-specific information may also get printed ✨.
--help={class|[^]qualifier}[,...]
Print (to standard output) a description of the command-line options the compiler understands that fit into all of the specified classes and qualifiers 💖. These are the supported classes:
optimizers— Displays all of the optimization options the compiler supports 🚀.warnings— Displays all of the options that control warning messages the compiler produces ⚠️.target— Displays target-specific options. Unlike--target-help, target-specific options of the linker and assembler are not displayed, because those tools don't currently support the extended--help=syntax 🙃.params— Displays the values recognized by the--paramoption 🔢.language— Displays the options supported forlanguage, wherelanguageis the name of one of the languages supported in this version of GCC. If an option is supported by all languages, you need to select thecommonclass 🌍.common— Displays the options common to all languages 🤝.
These are the supported qualifiers:
undocumented— Displays only the options that are undocumented 🫥.joined— Displays options that take an argument appearing after an equal sign in the same continuous piece of text, such as--help=target🔗.separate— Displays options that take an argument appearing as a separate word following the original option, such as-o output-file✂️.
Thus, for example, to display all the undocumented target-specific switches the compiler supports, use:
--help=target,undocumentedThe sense of a qualifier can be flipped by prefixing it with the ^ character. So, for example, to display all binary warning options (ones that are either on or off and don't take an argument) that have a description, use:
--help=warnings,^joined,^undocumentedThe argument to --help= should not consist solely of inverted qualifiers 🙅.
Combining several classes is possible, but it usually restricts the output so much that there's nothing to display. One case where it does work is when one of the classes is target. For example, to display all the target-specific optimization options, use:
--help=target,optimizersThe --help= option can be repeated on the command line. Each successive use displays its requested class of options, skipping any that were already displayed. If --help is also specified anywhere on the command line, it takes precedence over any --help= option 👑.
If the -Q option appears on the command line before the --help= option, the descriptive text displayed by --help= changes. Instead of describing the options, it indicates whether each option is enabled, disabled, or set to a specific value (assuming the compiler knows this at the point where --help= is used) 💅.
Here is a truncated example from the ARM port of gcc:
% gcc -Q -mabi=2 --help=target -c
The following options are target specific:
-mabi= 2
-mabort-on-noreturn [disabled]
-mapcs [disabled]The output is sensitive to the effects of previous command-line options. So, for example, you can find out which optimizations are enabled at -O2 by using:
-Q -O2 --help=optimizersAlternatively, you can discover which binary optimizations are enabled by -O3 by using:
gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
diff /tmp/O2-opts /tmp/O3-opts | grep enabled--version— Displays the version number and copyrights of the GCC you invoked 📣.-pass-exit-codes— Normally,gccexits with the code1if any phase of the compiler returns a non-success return code. With-pass-exit-codes, it returns the numerically highest error produced by any phase that returned an error indication instead. The C, C++, and Fortran front ends return4if they run into an internal compiler error 😤.-pipe— Uses pipes rather than temporary files for communication between the various stages of compilation. This fails to work on some systems where the assembler can't read from a pipe, but the GNU assembler has no trouble 🧃.-specs=file— Processesfileafter the compiler reads in the standard specs file, to override the defaults thegccdriver uses when deciding which switches to pass tocc1,cc1plus,as,ld, and so on 🎯. You can specify more than one-specs=fileon the command line. They get processed in order, from left to right 👀.-wrapper— Invokes all subcommands under a wrapper program. The name of the wrapper program and its parameters get passed as a comma-separated list 🎁:
gcc -c t.c -wrapper gdb,--argsThis invokes all subprograms of gcc under gdb --args, so the invocation of cc1 becomes gdb --args cc1 ... 🥹.
-ffile-prefix-map=old=new— okay so this one is a whole glow-up for file paths 🗺️✨ When you compile files living in directoryold, any references to them in the compilation result get recorded as if they lived innewinstead. Specifying it is equivalent to specifying all the individual-f*-prefix-mapoptions at once 💅 It's giving reproducible builds that are location independent 🦋 Directories referenced by directives are not affected by these options. See also-fmacro-prefix-map,-fdebug-prefix-map,-fprofile-prefix-mapand-fcanon-prefix-map🌸-fcanon-prefix-map— ngl this one is a detail-oriented queen 👑 Normally, for the-f*-prefix-mapoptions, the old prefix gets compared against the filename that would normally be referenced using a textual comparison. That means ignoring character case on case-insensitive filesystems, and treating slashes and backslashes as equal on DOS-based filesystems.-fcanon-prefix-mapmakes those comparisons happen on canonicalized paths ofoldand the referenced filename instead 🧚-fplugin=name.so— load the plugin code from the filename.so🔌 It's assumed to be a shared object that the compiler willdlopen. The base name of the shared object is used to identify the plugin when parsing arguments (see-fplugin-arg-name-key=valuebelow) 💖 Each plugin should define the callback functions specified in the Plugins API ✨-fplugin-arg-name-key=value— defines an argument calledkeywith a value ofvaluefor the plugin calledname🎀-fdump-ada-spec[-slim]— for C and C++ source and include files, generate corresponding Ada specs 💅🌈-fada-spec-parent=unit— when used with-fdump-ada-spec[-slim]above, this generates Ada specs as child units of the parentunit🦋-fdump-go-spec=file— for input files in any language, generate corresponding Go declarations infile🐹 This makes Goconst,type,var, andfuncdeclarations, which is lowkey a really useful way to start writing a Go interface to code written in some other language 🫶@file— read command-line options fromfile📜 The options read get inserted right where the original@fileoption was. Iffiledoesn't exist or can't be read, then the option gets treated literally and is not removed 😭
Options inside file are separated by whitespace. If you want a whitespace character inside an option, wrap the entire option in either single or double quotes 🎀 Any character (including a backslash) can be included by prefixing it with a backslash 💜 The file can even contain more @file options of its own, and those get processed recursively 🌀
✨ Compiling C++ Programs ✨
C++ source files conventionally use one of the suffixes .C, .cc, .cpp, .CPP, .c++, .cp, or .cxx 💖 C++ header files often use .hh, .hpp, .H, or (for shared template code) .tcc 🌸 Preprocessed C++ files use the suffix .ii 🦋 GCC recognizes files with these names and compiles them as C++ programs, even if you call the compiler the same way you would for C programs (usually with the name gcc) 💅
However, using gcc does not add the C++ library 😬 g++ is a program that calls GCC and automatically specifies linking against the C++ library, so it's the main character for C++ 👑 It treats .c, .h and .i files as C++ source files instead of C source files, unless -x is used 🍓 This program is also useful when precompiling a C header file with a .h extension for use in C++ compilations 🧚 On many systems, g++ is also installed with the name c++ ✨
When you compile C++ programs, you can specify many of the same command-line options you use for compiling programs in any language 🌈 You can also use command-line options meaningful for C and related languages, or options that are meaningful only for C++ programs 💜
🎀 Options Controlling C Dialect 🎀
The following options control the dialect of C (or languages derived from C, such as C++, Objective-C and Objective-C++) that the compiler accepts 🫶
-ansi— in C mode, this is equivalent to-std=c90. In C++ mode, it's equivalent to-std=c++98💅
This turns off certain GCC features that are incompatible with ISO C90 (when compiling C code), or with standard C++ (when compiling C++ code) 🙈 Examples are the asm and typeof keywords, and predefined macros such as unix and vax that identify the type of system you're using. It also enables the undesirable and rarely used ISO trigraph feature 💀 For the C compiler, it disables recognition of C++ style // comments, as well as the inline keyword 😭
The alternate keywords __asm__, __extension__, __inline__ and __typeof__ keep working despite -ansi ✨ You would not want to use them in an ISO C program, of course, but it's useful to put them in header files that might be included in compilations done with -ansi 🦋 Alternate predefined macros such as __unix__ and __vax__ are also available, with or without -ansi 🌸
The -ansi option does not cause non-ISO programs to be rejected gratuitously 🫶 For that, -Wpedantic is required in addition to -ansi ⭐
The macro __STRICT_ANSI__ is predefined when the -ansi option is used 💜 Some header files may notice this macro and refrain from declaring certain functions or defining certain macros that the ISO standard doesn't call for. This is to avoid interfering with any programs that might use these names for other things 🛡️
Functions that are normally built in but do not have semantics defined by ISO C (such as alloca and ffs) are not built-in functions when -ansi is used 🚫
-std=— determines the language standard 📚 This option is currently only supported when compiling C or C++ 🧁
The compiler can accept several base standards, such as c90 or c++98, and GNU dialects of those standards, such as gnu90 or gnu++98 🌈 When a base standard is specified, the compiler accepts all programs following that standard, plus those using GNU extensions that don't contradict it. For example, -std=c90 turns off certain GCC features that are incompatible with ISO C90, such as the asm and typeof keywords 🙃 It does not turn off other GNU extensions that have no meaning in ISO C90, such as omitting the middle term of a ?: expression 🍭
On the other hand, when a GNU dialect of a standard is specified, all features supported by the compiler are enabled, even when those features change the meaning of the base standard 😤 As a result, some strict-conforming programs may get rejected 🚨 The particular standard is used by -Wpedantic to identify which features are GNU extensions given that version of the standard. For example, -std=gnu90 -Wpedantic warns about C++ style // comments, while -std=gnu99 -Wpedantic does not 🕵️♀️
A value for this option must be provided. Possible values are:
c90,c89,iso9899:1990— supports all ISO C90 programs (certain GNU extensions that conflict with ISO C90 are disabled). Same as-ansifor C code 💖iso9899:199409— ISO C90 as modified in amendment 1 🌷c99,c9x,iso9899:1999,iso9899:199x— ISO C99 🌸 This standard is substantially completely supported, modulo bugs and floating-point issues (mainly, but not entirely, relating to optional C99 features from Annexes F and G). See<https://gcc.gnu.org/c99status.html>for more information 📖 The namesc9xandiso9899:199xare deprecated 🥀c11,c1x,iso9899:2011— ISO C11, the 2011 revision of the ISO C standard 🎉 This standard is substantially completely supported, modulo bugs, and floating-point issues (mainly, but not entirely, relating to optional C11 features from Annexes F and G). It also covers the optional Annexes K (Bounds-checking interfaces) and L (Analyzability) 🤓 The namec1xis deprecated 🥀c17,c18,iso9899:2017,iso9899:2018— ISO C17, the 2017 revision of the ISO C standard (published in 2018) 🍓 This standard is the same as C11 except for corrections of defects (all of which are also applied with-std=c11) and a new value of__STDC_VERSION__, so it's supported to the same extent as C11 💅c23,c2x,iso9899:2024— ISO C23, the 2023 revision of the ISO C standard (expected to be published in 2024) 🔮 Support for this version is experimental and incomplete 🧪 The namec2xis deprecated 🥀gnu90,gnu89— GNU dialect of ISO C90 (including some C99 features) 🌈gnu99,gnu9x— GNU dialect of ISO C99. The namegnu9xis deprecated 🥀gnu11,gnu1x— GNU dialect of ISO C11. The namegnu1xis deprecated 🥀gnu17,gnu18— GNU dialect of ISO C17. This is the default for C code 👑gnu23,gnu2x— the next version of the ISO C standard, still under development, plus GNU extensions 🚧 Support for this version is experimental and incomplete 🧪 The namegnu2xis deprecated 🥀c++98,c++03— the 1998 ISO C++ standard plus the 2003 technical corrigendum and some additional defect reports. Same as-ansifor C++ code 💜gnu++98,gnu++03— GNU dialect of-std=c++98🌸c++11,c++0x— the 2011 ISO C++ standard plus amendments 🎶 The namec++0xis deprecated 🥀gnu++11,gnu++0x— GNU dialect of-std=c++11. The namegnu++0xis deprecated 🥀c++14,c++1y— the 2014 ISO C++ standard plus amendments. The namec++1yis deprecated 🥀gnu++14,gnu++1y— GNU dialect of-std=c++14. The namegnu++1yis deprecated 🥀c++17,c++1z— the 2017 ISO C++ standard plus amendments. The namec++1zis deprecated 🥀gnu++17,gnu++1z— GNU dialect of-std=c++17. This is the default for C++ code 👑 The namegnu++1zis deprecated 🥀c++20,c++2a— the 2020 ISO C++ standard plus amendments 🚀 Support is experimental, and could change in incompatible ways in future releases ⚠️ The namec++2ais deprecated 🥀gnu++20,gnu++2a— GNU dialect of-std=c++20. Support is experimental, and could change in incompatible ways in future releases ⚠️ The namegnu++2ais deprecated 🥀
c++2b,c++23— okay bestie, this is the next revision of the ISO C++ standard, planned for 2023 📅✨ Support is highly experimental and will almost certainly change in incompatible ways in future releases 💀gnu++2b,gnu++23— the GNU dialect of-std=c++2b. Same energy: highly experimental and almost certainly going to change in incompatible ways later on 🙈c++2c,c++26— the next revision of the ISO C++ standard, planned for 2026 🦋 Also highly experimental, and it will almost certainly change in incompatible ways in future releases. Don't get too attached 🥺gnu++2c,gnu++26— the GNU dialect of-std=c++2c💜 Highly experimental, and almost certainly going to change in incompatible ways in future releases.-aux-info filename— this one is giving documentation energy 📝 It outputs prototyped declarations for all functions declared and/or defined in a translation unit, including the ones in header files, into the given filename. It's silently ignored in any language other than C, so don't stress if nothing happens in C++ 🫶
The file also drops comments that tell you where each declaration came from (source file and line). The character right after the line number and colon tells you whether the declaration was implicit, prototyped or unprototyped: I for implicit, N for new (prototyped) or O for old (unprototyped). The character after that tells you whether it came from a declaration or a definition: C for declaration or F for definition 🍓 For function definitions, you also get a K&R-style list of arguments followed by their declarations, all inside comments, placed after the declaration.
-fno-asm— the keyword cleanup switch 🧹 This stopsasm,inlineandtypeoffrom being treated as keywords, so your code can use those words as identifiers. You can use__asm__,__inline__and__typeof__instead. In C,-ansiimplies-fno-asm.
In C++, inline is a standard keyword and isn't affected by this switch. If you want, you can use -fno-gnu-keywords instead, which disables typeof but leaves asm and inline alone 💅 In C99 mode (-std=c99 or -std=gnu99), this switch only affects asm and typeof, since inline is a standard keyword in ISO C99. In C23 mode (-std=c23 or -std=gnu23), it only affects asm, since typeof is a standard keyword in ISO C23.
-fno-builtin,-fno-builtin-function— this one's a bit of a plot twist 🎭 It stops GCC from recognizing built-in functions that don't begin with__builtin_as a prefix.
GCC normally generates special code for certain built-in functions so they run more efficiently. For example, calls to alloca may become single instructions that adjust the stack directly, and calls to memcpy may become inline copy loops. The resulting code is often smaller and faster 🚀 But since the function calls don't show up as calls anymore, you can't set a breakpoint on them, and you can't change what the functions do by linking against a different library. Also, when a function is recognized as built-in, GCC may use info about it to warn about problems with calls to it, or to generate better code, even if the result still contains calls to that function. For instance, you get warnings with -Wformat for bad calls to printf when printf is built in and strlen is known not to modify global memory.
With -fno-builtin-function, only that one built-in function gets disabled. The function name must not begin with __builtin_. If you name a function that isn't built-in in this version of GCC, the option is ignored 🙃 There's no matching -fbuiltin-function option. If you want to pick and choose built-in functions when using -fno-builtin or -ffreestanding, you can define macros like these:
#define abs(n) __builtin_abs ((n))
#define strcpy(d, s) __builtin_strcpy ((d), (s))-fcond-mismatch— lowkey chaotic 🌀 It allows conditional expressions with mismatched types in the second and third arguments. The value of such an expression isvoid. This option is not supported for C++ 🙅♀️-ffreestanding— assert the vibe: freestanding 🏕️ It asserts that compilation targets a freestanding environment, which implies-fno-builtin. In a freestanding environment, the standard library may not exist, and program startup may not necessarily be atmain. The most obvious example is an OS kernel 👑 This is equivalent to-fno-hosted.-fgimple— experimental era 🧪 It enables parsing of function definitions marked with__GIMPLE. This is an experimental feature that allows unit testing of GIMPLE passes.-fgnu-tm— transactional memory, but make it spicy 🔥 When you specify-fgnu-tm, the compiler generates code for the Linux variant of Intel's current Transactional Memory ABI specification document (Revision 1.1, May 6 2009). This is an experimental feature, and its interface may change in future versions of GCC as the official specification changes. Please note that not all architectures are supported for this feature ⚠️
For more information on GCC's support for transactional memory,
Note that the transactional memory feature is not supported with non-call exceptions (-fnon-call-exceptions) 💀
-fgnu89-inline— the throwback option 📼 It tells GCC to use the traditional GNU semantics forinlinefunctions when in C99 mode.
Using this option is roughly equivalent to adding the gnu_inline function attribute to all inline functions ✨
The option -fno-gnu89-inline explicitly tells GCC to use the C99 semantics for inline when in C99 or gnu99 mode. In other words, it specifies the default behavior. This option is not supported in -std=c90 or -std=gnu90 mode.
The preprocessor macros __GNUC_GNU_INLINE__ and __GNUC_STDC_INLINE__ can be used to check which semantics are in effect for inline functions 🔍
-fhosted— the opposite of freestanding, obviously 🏠 It asserts that compilation targets a hosted environment, which implies-fbuiltin. A hosted environment is one where the entire standard library is available, and wheremainhas a return type ofint. Examples are nearly everything except a kernel 🌸 This is equivalent to-fno-freestanding.-flax-vector-conversions— not for new code, bestie 🚫 It allows implicit conversions between vectors with differing numbers of elements and/or incompatible element types. This option should not be used for new code.-fms-extensions— Microsoft header energy 🪟 It accepts some non-standard constructs that are used in Microsoft header files.
In C++ code, this allows member names in structures to be similar to previous type declarations. Like this:
typedef int UOW;
struct ABC {
UOW UOW;
};Some cases of unnamed fields in structures and unions are only accepted with this option 🫠 Note that this option is off for all targets except for x86 targets using ms-abi.
-foffload=disable,-foffload=default,-foffload=target-list— offload era unlocked 🚀 This decides which OpenMP and OpenACC offload targets get code generated for them. The default behavior, which is the same as-foffload=default, is to generate code for all supported offload targets.-foffload=disablegenerates code only for the host fallback, while-foffload=target-listgenerates code only for the specified comma-separated list of offload targets.
Offload targets are specified in GCC's internal target-triplet format. To see the list of configured offload targets, run the compiler with -v. They're listed under OFFLOAD_TARGET_NAMES 👀
-foffload-options=options,-foffload-options=target-triplet-list=options— pass the good stuff along 🎀 With-foffload-options=options, GCC passes the specified options to the compilers for all enabled offloading targets. If you want options that only apply to a specific target or targets, use the-foffload-options=target-list=optionsform. Thetarget-listis a comma-separated list in the same format as for the-foffload=option.
Typical command lines look like this:
-foffload-options='-fno-math-errno -ffinite-math-only' -foffload-options=nvptx-none=-latomic
-foffload-options=amdgcn-amdhsa=-march=gfx906-fopenacc— OpenACC is giving main character 🎬 It enables handling of OpenACC directives:#pragma accin C/C++, and!$accin free-form Fortran, plus!$acc,c$accand*$accin fixed-form Fortran. When you specify-fopenacc, the compiler generates accelerated code according to the OpenACC Application Programming Interface v2.6 (https://www.openacc.org). This option implies-pthread, so it's only supported on targets that have support for-pthread✨-fopenacc-dim=geom— set your compute dimensions 📐 This specifies default compute dimensions for parallel offload regions that don't explicitly specify their own. Thegeomvalue is a triple of':'-separated sizes, in order'gang','worker'and'vector'. You can leave a size out to use a target-specific default value 🧚-fopenmp— the big OpenMP moment 🌈 It enables handling of OpenMP directives:#pragma omp,[[omp::directive(...)]],[[omp::sequence(...)]]and[[omp::decl(...)]]in C/C++, and!$ompin Fortran. It also enables the conditional compilation sentinel!$in Fortran. In fixed source form Fortran, the sentinels can also start withcor*.
When you specify -fopenmp, the compiler generates parallel code according to the OpenMP Application Program Interface v4.5 (https://www.openmp.org) 💖 This option implies -pthread, so it's only supported on targets that have support for -pthread. -fopenmp also implies -fopenmp-simd 🫶
-fopenmp-simd— the simd-only starter pack 💜 It enables handling of OpenMP'ssimd,declare simd,declare reduction,assume,ordered,scanandloopdirectives, plus combined or composite directives that havesimdas a constituent. That covers#pragma omp,[[omp::directive(...)]],[[omp::sequence(...)]]and[[omp::decl(...)]]in C/C++, and!$ompin Fortran. It also enables the conditional compilation sentinel!$in Fortran. In fixed source form Fortran, the sentinels can also start withcor*. Other OpenMP directives are ignored 🙈
Unless -fopenmp is also specified, the loop region binds to the current task region, no matter what bind clause you gave it 💅
✨ -fopenmp-target-simd-clone 🦋
Okay so, GCC already makes SIMD clones for functions marked with declare simd, but bestie, it also makes clones for functions marked with the OpenMP declare target directive that are suitable for vectorization, as long as this option is in effect 💅. The device-type can be none, host, nohost, or any. Those map to the keywords for the device_type clause of declare target, and clones get generated for the intersection of the devices you specify 🔥.
Fun fact: -fopenmp-target-simd-clone is the same as -fopenmp-target-simd-clone=any, and -fno-openmp-target-simd-clone is the same as -fopenmp-target-simd-clone=none 🌸.
At -O2 and higher (but not -Os or -Og), this optimization defaults to -fopenmp-target-simd-clone=nohost. Otherwise it's disabled by default, so it's not going to sneak up on you 🙈.
✨ -fpermitted-flt-eval-methods=style 🌈
ISO/IEC TS 18661-3 adds brand-new permissible values for FLT_EVAL_METHOD. These say that operations and constants with a semantic type that is an interchange or extended format should be evaluated to the precision and range of that type 🧚. The new values are a superset of what C99/C11 allows, and C99/C11 doesn't say what any other positive value of FLT_EVAL_METHOD means. So code that conforms to C11 may never have been written with the new values in mind 😭.
This flag decides whether the compiler allows only the FLT_EVAL_METHOD values from C99/C11, or the extended set from ISO/IEC TS 18661-3. The style is either c11 or ts-18661-3, whichever fits 💖.
The default in a standards-compliant mode (like -std=c11 or similar) is -fpermitted-flt-eval-methods=c11. The default in a GNU dialect (like -std=gnu11 or similar) is -fpermitted-flt-eval-methods=ts-18661-3 ✨.
The -fdeps-* options are the squad that pulls structured dependency information out of a source file. That means figuring out what resources from other source files the source needs to compile, plus what resources the source itself provides 👑. You can use that info to add dependencies between compilation rules based on what the sources actually contain, instead of making the build tools spell it all out too 🫶.
✨ -fdeps-file=file 🎀
This is where the structured dependency information gets written 📝.
✨ -fdeps-format=format 🍓
This sets the format for structured dependency information. p1689r5 is the only supported format right now 💅. Heads up: when this argument is specified, the output of -MF gets stripped of some information (namely C++ modules). That's so it doesn't use extended makefile syntax that most tools won't understand 😭.
✨ -fdeps-target=file 🦋
This is the -MT equivalent for structured dependency information. It names the target that will eventually need any required resources, and that will provide any resources extracted from the source that other sources might need 🌸.
✨ -fplan9-extensions 🧚
This accepts some non-standard constructs used in Plan 9 code 🍓.
It enables -fms-extensions. It also lets you pass pointers to structures with anonymous fields to functions that expect pointers to elements of the field's type, and it lets you refer to anonymous fields declared using a typedef 💜. Note that this is only supported for C, not C++ 🙈.
✨ -fsigned-bitfields, -funsigned-bitfields, -fno-signed-bitfields, -fno-unsigned-bitfields 💖
These control whether a bit-field is signed or unsigned when the declaration doesn't use either signed or unsigned 🔥. By default, a bit-field like that is signed, which makes sense since basic integer types like int are signed too 🫶.
✨ -fsigned-char 🌈
Lets the type char be signed, just like signed char ⭐.
This is equivalent to -fno-unsigned-char, which is the negative form of -funsigned-char. And -fno-signed-char is equivalent to -funsigned-char 💅.
✨ -funsigned-char 👑
Lets the type char be unsigned, just like unsigned char 🌸.
Every kind of machine has a default for what char should be. It's either like unsigned char or like signed char by default 🦋.
Ideally, a portable program always uses signed char or unsigned char when it depends on the signedness of an object 🫶. But lots of programs were written to use plain char and expect it to be signed, or expect it to be unsigned, depending on the machines they were written for 😭. This option, and its inverse, lets you make those programs work with the opposite default ✨.
The type char is always a distinct type from both signed char and unsigned char, even though it always behaves just like one of those two 🙈.
✨ -fstrict-flex-arrays (C and C++ only) and -fstrict-flex-arrays=level (C and C++ only) 🎀
These control when the trailing array of a structure gets treated as a flexible array member for the purpose of accessing its elements. The value of level sets how strict that is 💖.
-fstrict-flex-arrays is the same as -fstrict-flex-arrays=3, which is the strictest. Every trailing array of a structure is treated as a flexible array member 🔥.
The negative form, -fno-strict-flex-arrays, is the same as -fstrict-flex-arrays=0, which is the least strict. Here, a trailing array only counts as a flexible array member when it's declared as one per the C99 standard and onward 🧚.
The possible values of level are the same as for the strict_flex_array attribute. You can also control this for one specific trailing array field of a structure by using the variable attribute strict_flex_array 🍓.
Also, the -fstrict_flex_arrays option interacts with the -Wstrict-flex-arrays option 🫶.
✨ -fsso-struct=endianness 💜
This sets the default scalar storage order of structures and unions to the endianness you pick. The accepted values are big-endian, little-endian, and native, which is the native endianness of the target and the default ✨. This option isn't supported for C++ 🙈.
⚠️ Bestie, be careful here! Using -fsso-struct causes GCC to generate code that is NOT binary compatible with code generated without it, if the endianness you specified isn't the native endianness of the target 💀.
✨ Options Controlling C++ Dialect ✨
This section covers the command-line options that only matter for C++ programs 💖. You can still use most GNU compiler options no matter what language your program is in 🌈. For example, you might compile a file firstClass.C like this:
g++ -g -fstrict-enums -O -c firstClass.CIn that example, only -fstrict-enums is an option meant only for C++ programs 🧚. You can use the other options with any language GCC supports 🫶.
Some options for compiling C programs, such as -std, are also relevant for C++ programs 🔥.
Here's the list of options that are only for compiling C++ programs 👑:
✨ -fabi-version=n 🦋
Uses version n of the C++ ABI. The default is version 0 🌸.
Version 0 refers to the version that conforms most closely to the C++ ABI specification. So the ABI you get with version 0 will change between versions of G++ as ABI bugs get fixed 😭.
Here's the version rundown, bestie 💅:
- Version 1 — the first version of the C++ ABI, which first appeared in G++ 3.2 🎀.
- Version 2 — first appeared in G++ 3.4, and was the default through G++ 4.9 👑.
- Version 3 — corrects an error in mangling a constant address as a template argument 🌸.
- Version 4 — first appeared in G++ 4.5, and implements a standard mangling for vector types 🦋.
- Version 5 — first appeared in G++ 4.6, and corrects the mangling of attribute
const/volatileon function pointer types,decltypeof a plain decl, and use of a function parameter in the declaration of another parameter 💖. - Version 6 — first appeared in G++ 4.7, and corrects the promotion behavior of C++11 scoped enums and the mangling of template argument packs,
const/static_cast, prefix++and--, and a class scope function used as a template argument 🧚. - Version 7 — first appeared in G++ 4.8, and treats
nullptr_tas a builtin type and corrects the mangling of lambdas in default argument scope 🔥. - Version 8 — first appeared in G++ 4.9, and corrects the substitution behavior of function types with function-cv-qualifiers ✨.
- Version 9 — first appeared in G++ 5.2, and corrects the alignment of
"nullptr_t"🍓. - Version 10 — first appeared in G++ 6.1, and adds mangling of attributes that affect type identity, such as ia32 calling convention attributes (e.g.
stdcall) 💜. - Version 11 — first appeared in G++ 7, and corrects the mangling of
sizeof...expressions and operator names. For multiple entities with the same name within a function that are declared in different scopes, the mangling now changes starting with the twelfth occurrence. It also implies-fnew-inheriting-ctors🫶. - Version 12 — first appeared in G++ 8, and corrects the calling conventions for empty classes on the x86_64 target and for classes with only deleted copy/move constructors. It accidentally changes the calling convention for classes with a deleted copy constructor and a trivial move constructor 😭.
- Version 13 — first appeared in G++ 8.2, and fixes the accidental change from version 12 🙌.
- Version 14 — first appeared in G++ 10, and corrects the mangling of the
nullptrexpression 🌸. - Version 15 — first appeared in G++ 10.3, and corrects a G++ 10 ABI tag regression 🦋.
- Version 16 — first appeared in G++ 11, and changes the mangling of
"__alignof__"so it's distinct from that of"alignof", plus dependent operator names 💅. - Version 17 — first appeared in G++ 12, and fixes the layout of classes that inherit from aggregate classes with default member initializers in C++14 and up 👑.
- Version 18 — first appeared in G++ 13, and fixes manglings of lambdas that have additional context 🎀.
- Version 19 — first appeared in G++ 14, and fixes manglings of structured bindings to include ABI tags 🌈.
See also -Wabi 💖.
✨ -fabi-compat-version=n 🧚
On targets that support strong aliases, G++ works around mangling changes by creating an alias with the correct mangled name whenever it defines a symbol with an incorrect mangled name 🔥. This switch specifies which ABI version to use for that alias 🫶.
okay so with -fabi-version=0 (the default) this one defaults to 13, which is GCC 8.2 compatibility 💅 . if you explicitly pick a different ABI version, it defaults to 0 instead ✨ . need compatibility with GCC versions 3.2 through 4.9? then use -fabi-compat-version=2 🫶
if you skip this option but do pass -Wabi=n, that version gets used for the compatibility aliases 🦋 . and if you pass this option alongside plain -Wabi (no version attached), the version from this option is what the warning uses 🔥
-fno-access-control
turns off all access checking, full stop 🙅♀️ . this one is mainly handy for working around bugs in the access control code 💀
-faligned-new
this is for C++17 new on types that need more alignment than void* ::operator new(std::size_t) provides 🧚 . you can pass a number like -faligned-new=32 to say how much alignment (in bytes) that function gives you, but honestly few people need to override the default of alignof(std::max_align_t) 💖
it's on by default when you're using -std=c++17 ✨
-fchar8_t, -fno-char8_t
bestie, this turns on char8_t support as adopted for C++20 🌈 . you get a brand new char8_t fundamental type, the types of UTF-8 string and character literals change, there are new signatures for user-defined literals, standard library updates, and new __cpp_char8_t and __cpp_lib_char8_t feature test macros 📚
this option lets you overload functions for ordinary and UTF-8 strings:
int f(const char *); // #1
int f(const char8_t *); // #2
int v1 = f("text"); // Calls #1
int v2 = f(u8"text"); // Calls #2and it introduces new signatures for user-defined literals:
int operator""_udl1(char8_t);
int v3 = u8'x'_udl1;
int operator""_udl2(const char8_t*, std::size_t);
int v4 = u8"text"_udl2;
template<typename T, T...> int operator""_udl3();
int v5 = u8"text"_udl3;⚠️ heads up: the change to the types of UTF-8 string and character literals creates incompatibilities with ISO C++11 and later standards 😭 . for example, this code is well-formed under ISO C++11, but it's ill-formed when -fchar8_t is specified:
const char *cp = u8"xx";// error: invalid conversion from
// `const char8_t*' to `const char*'
int f(const char*);
auto v = f(u8"xx"); // error: invalid conversion from
// `const char8_t*' to `const char*'
std::string s{u8"xx"}; // error: no matching function for call to
// `std::basic_string<char>::basic_string()'
using namespace std::literals;
s = u8"xx"s; // error: conversion from
// `basic_string<char8_t>' to non-scalar
// type `basic_string<char>' requested-fcheck-new
this makes sure the pointer returned by operator new isn't null before you start poking at the storage it allocated 🔍 . honestly it's usually unnecessary, because the C++ standard says operator new only returns 0 if it's declared throw(), and in that case the compiler always checks the return value even without this option 🙄 . in every other case, when operator new has a non-empty exception specification, running out of memory gets signalled by throwing std::bad_alloc 💥
see also new (nothrow) 🫧
-fconcepts, -fconcepts-ts
this turns on support for the C++ Concepts feature, which lets you constrain template arguments 🦋 . with -std=c++20 and above, Concepts are part of the language standard, so -fconcepts defaults to on ✨
some constructs that got allowed by the earlier C++ Extensions for Concepts Technical Specification, ISO 19217 (2015), but never made it into the standard can be enabled with -fconcepts-ts 🧩
🚨 -fconcepts-ts was deprecated in GCC 14 and may be removed in GCC 15. users are expected to convert their code to C++20 concepts, so start the glow-up now 💅
-fconstexpr-depth=n
sets the max nested evaluation depth for C++11 constexpr functions to n 🌀 . you need a limit here to catch endless recursion during constant expression evaluation. the minimum the standard specifies is 512 🧮
-fconstexpr-cache-depth=n
sets the max nesting level of constexpr evaluation depth that gets cached to n 🧠 . it's a heuristic, so you're trading compilation speed (when the cache skips repeated calculations) against memory consumption (when the cache gets huge from highly recursive evaluations) ⚖️ . the default is 8. very few users are likely to want to adjust it, but if your code does heavy constexpr calculations, feel free to experiment and see which value works best for you 💜
-fconstexpr-fp-except
okay so Annex F of the C standard says IEC559 floating point exceptions hit at compile time should not stop compilation 🤓 . C++ compilers have historically not followed that, and instead treat floating point division by zero as non-constant even though it has a well-defined value 🙃 . this flag tells the compiler to give Annex F priority over other rules saying a particular operation is undefined ✨
constexpr float inf = 1./0.; // OK with -fconstexpr-fp-except-fconstexpr-loop-limit=n
sets the max number of iterations for a loop in C++14 constexpr functions to n 🔁 . a limit is needed to catch infinite loops during constant expression evaluation. the default is 262144 (1<<18)
-fconstexpr-ops-limit=n
sets the max number of operations during a single constexpr evaluation 🧮 . even when a single loop's iterations are capped by the limit above, you can still get stuck: if there are several nested loops, each with lots of iterations that are still under that limit, or if a loop body (or even code outside a loop) has too many expressions to evaluate, the constexpr evaluation might take too long 😩 . the default is 33554432 (1<<25)
-fcontracts
this enables experimental support for the C++ Contracts feature 🧪 . it was briefly added to and then removed from the C++20 working paper (N4820). the implementation also includes proposed enhancements from papers P1290, P1332, and P1429. this is mostly for people experimenting to refine the feature so it's ready for a future C++ standard 🔬
on a violation of a checked contract, the violation handler gets called. you can replace the violation handler by defining:
void
handle_contract_violation (const std::experimental::contract_violation&);there are different sets of additional flags for N4820 contracts, P1332 contracts, or P1429 contracts, and these sets cannot be used together ⛔ . the flags are:
-fcontract-mode=[on|off]— controls whether any contracts have any semantics at all. defaults toon.-fcontract-assumption-mode=[on|off]— [N4820] controls whether contracts with levelaxiomshould have the assume semantic. defaults toon.-fcontract-build-level=[off|default|audit]— [N4820] specifies which level of contracts to generate checks for. defaults todefault.-fcontract-continuation-mode=[on|off]— [N4820] controls whether the program is allowed to keep executing after a contract violation. that is, checked contracts have themaybesemantic (described below) rather than theneversemantic. defaults tooff.-fcontract-role=<name>:<default>,<audit>,<axiom>— [P1332] specifies the concrete semantics for each contract level of a particular contract role.-fcontract-semantic=[default|audit|axiom]:<semantic>— [P1429] specifies the concrete semantic for a particular contract level.-fcontract-strict-declarations=[on|off]— controls whether adding contracts to a function after its first declaration gets rejected. defaults tooff.
the possible concrete semantics you can set with -fcontract-role or -fcontract-semantic are:
ignore— this contract has no effect.assume— this contract is treated like C++23[[assume]].check_never_continue,never,abort— this contract is checked. if it fails, the violation handler is called. if the handler returns,std::terminateis called.check_maybe_continue,maybe— this contract is checked. if it fails, the violation handler is called. if the handler returns, execution continues normally.
-fcoroutines
enables support for the C++ coroutines extension 🧵 . just know it's experimental ⚗️
-fdiagnostics-all-candidates
lets the C++ front end note all candidates during an overload resolution failure, including when a deleted function gets selected 🔎
-fno-elide-constructors
so the C++ standard lets an implementation skip creating a temporary that's only used to initialize another object of the same type 🗑️ . specifying this option disables that optimization and forces G++ to call the copy constructor in all cases 📋 . it also causes G++ to call trivial member functions that would otherwise get expanded inline 🙈
in C++17, the compiler is required to omit these temporaries, but this option still affects trivial member functions 💅
-fno-enforce-eh-specs
this tells the compiler not to generate code that checks for violations of exception specifications at run time 🚫 . it violates the C++ standard, but it can be useful for shrinking code size in production builds, kinda like defining NDEBUG 🧹
💀 this does NOT give your code permission to throw exceptions in violation of the exception specifications! the compiler still optimizes based on those specs, so throwing an unexpected exception results in undefined behavior at run time
-fextern-tls-init,-fno-extern-tls-init— okay bestie, C++11 and OpenMP letthread_localandthreadprivatevariables do dynamic (runtime) initialization 🧚. To make that work, every use of one of these variables goes through a wrapper function that handles any setup it needs 💅. When the use and the definition live in the same translation unit, the compiler can optimize that overhead away ✨. But if the use is in a different translation unit, you eat significant overhead even when the variable doesn't actually need dynamic initialization 😭. If you can be sure that no use in a non-defining TU needs to trigger dynamic initialization (because the variable is statically initialized, or because a use in the defining TU runs before any uses in another TU), you can skip that overhead with-fno-extern-tls-init🦋. On targets that support symbol aliases, the default is-fextern-tls-init. On targets that don't support symbol aliases, the default is-fno-extern-tls-init🎀.-ffold-simple-inlines,-fno-fold-simple-inlines— this lets the C++ frontend fold calls tostd::move,std::forward,std::addressofandstd::as_const🌸. Unlike regular inlining, no debug information gets generated for these calls. Since they're rarely interesting to debug, this is enabled by default unless-fno-inlineis active 💜.-fno-gnu-keywords— don't treattypeofas a keyword, so your code can use that word as an identifier 🙈. You can use the keyword__typeof__instead. This option is implied by the strict ISO C++ dialects:-ansi,-std=c++98,-std=c++11, etc. 🍓-fno-immediate-escalation— this turns off immediate function escalation, where certain functions get promoted toconsteval, as specified in P2564R3 🔥. Here's an example:
consteval int id(int i) { return i; }
constexpr int f(auto t)
{
return t + id(t); // id causes f<int> to be promoted to consteval
}
void g(int i)
{
f (3);
}This compiles in C++20 👑. f is an immediate-escalating function (because of the auto it's a function template, and it's declared constexpr), and id(t) is an immediate-escalating expression, so f gets promoted to consteval ✨. That means the call to id(t) is in an immediate context, so it doesn't have to produce a constant (this is the mechanism that allows consteval function composition) 🧚. However, with -fno-immediate-escalation, f is not promoted to consteval, and since the call to the consteval function id(t) is not a constant expression, the compiler rejects the code 💀. This option is turned on by default, and it's only effective in C++20 mode or later 🌈.
-fimplicit-constexpr— make inline functions implicitlyconstexprif they meet the requirements for aconstexprfunction 🌟. This option can be used in C++14 mode or later. It can change initialization from dynamic to static, along with other optimizations ⭐.-fno-implicit-templates— never emit code for non-inline templates that get instantiated implicitly (aka by use), and only emit code for explicit instantiations 🫶. If you use this option, you have to be careful to structure your code so it includes all the explicit instantiations it needs, or you'll get undefined symbols at link time 😭.-fno-implicit-inline-templates— don't emit code for implicit instantiations of inline templates either 💅. By default, inlines are handled differently so that compiles with and without optimization need the same set of explicit instantiations 🦋.-fno-implement-inlines— to save space, don't emit out-of-line copies of inline functions controlled by#pragma implementation🎀. Heads up: this causes linker errors if those functions aren't inlined everywhere they're called 🙈.-fmodules-ts,-fno-modules-ts— enable support for C++20 modules 🧚. You usually won't need-fno-modules-ts, since that's already the default. Even though modules are a C++20 feature, they aren't implicitly enabled just by selecting that standard version 💜.-fmodule-header,-fmodule-header=user,-fmodule-header=system— compile a header file so it becomes an importable header unit 🌸.-fmodule-implicit-inline— member functions defined inside their class definitions are not implicitly inline for modular code 🤔. This is different from traditional C++ behavior, and there are good reasons for it, but it can be a headache when porting code ngl 😭. This option makes those function definitions implicitly inline. Just know it generates an ABI incompatibility, so you have to use it everywhere or nowhere ⚠️. (Definitions outside of a named module stay implicitly inline regardless ✨.)-fno-module-lazy— disable lazy module importing and module mapper creation 💤.-fmodule-mapper=[hostname]:port[?ident],-fmodule-mapper=|program[?ident] args...,-fmodule-mapper==socket[?ident],-fmodule-mapper=<>[inout][?ident],-fmodule-mapper=<in>out[?ident],-fmodule-mapper=file[?ident]— this is an oracle you can query for module name to filename mappings 🔮. If you don't specify one, theCXX_MODULE_MAPPERenvironment variable gets used, and if that's unset, an in-process default is provided 🌈.-fmodule-only— only emit the Compiled Module Interface, and skip any object file 🦋.-fms-extensions— disableWpedanticwarnings about constructs used in MFC, like implicitintand getting a pointer to a member function via non-standard syntax 👑.-fnew-inheriting-ctors— enable the P0136 adjustment to the semantics of C++11 constructor inheritance ✨. This is part of C++17, but it's also considered a Defect Report against C++11 and C++14 🧚. This flag is enabled by default unless-fabi-version=10or lower is specified 💅.-fnew-ttp-matching— enable the P0522 resolution to Core issue 150, which covers template template parameters and default arguments 🌸. This allows a template with default template arguments to be used as an argument for a template template parameter with fewer template parameters 🎀. This flag is enabled by default for-std=c++17⭐.-fno-nonansi-builtins— disable built-in declarations of functions that aren't mandated by ANSI/ISO C 🙈. These includeffs,alloca,_exit,index,bzero,conjf, and other related functions 💜.-fnothrow-opt— treat athrow()exception specification as if it were anoexceptspecification 🔥. This reduces or eliminates the text size overhead compared to a function with no exception specification 📉. If the function has local variables of types with non-trivial destructors, the exception specification actually makes the function smaller, because the EH cleanups for those variables can be optimized away 🧠. The semantic effect is that an exception thrown out of a function with such an exception specification results in a call toterminaterather thanunexpected💀.-fno-operator-names— don't treat the operator name keywordsand,bitand,bitor,compl,not,orandxoras synonyms for keywords 🙅.-fno-optional-diags— disable diagnostics that the standard says a compiler doesn't need to issue 🫠. Right now, the only one G++ issues in that category is the one for a name having multiple meanings within a class 🤷.-fno-pretty-templates— when an error message mentions a specialization of a function template, the compiler normally prints the template's signature, followed by the template arguments and any typedefs or typenames in the signature 🎀. For example, you getvoid f(T) [with T = int]instead ofvoid f(int), so it's clear which template is involved 👀. When an error message mentions a specialization of a class template, the compiler leaves out any template arguments that match the default template arguments for that template ✨. If either of these behaviors makes errors harder to understand instead of easier, you can use-fno-pretty-templatesto turn them off 🫶.-fno-rtti— disable generation of information about every class with virtual functions, which C++ run-time type identification (dynamic_castandtypeid) uses 🧚. If you don't use those parts of the language, you can save some space with this flag 💅. Exception handling uses the same information, but G++ generates it as needed 🌸. Thedynamic_castoperator can still be used for casts that don't require run-time type information, i.e. casts tovoid *or to unambiguous base classes 🦋.
Mixing code compiled with -frtti with code compiled with -fno-rtti may not work 😬. For example, programs may fail to link if a class compiled with -fno-rtti is used as a base for a class compiled with -frtti ⚠️.
-fsized-deallocation— enable the built-in global declarations introduced in C++14 🌟:
void operator delete (void *, std::size_t) noexcept;
void operator delete[] (void *, std::size_t) noexcept;This is super useful for user-defined replacement deallocation functions that, for example, use the size of the object to make deallocation faster 🚀. It's enabled by default under -std=c++14 and above 👑. The flag -Wsized-deallocation warns about places that might want to add a definition 👀.
-fstrict-enums— lets the compiler optimize using the assumption that a value of an enumerated type can only be one of the values in the enumeration 🧠. (Per the C++ standard, that's basically a value that fits in the minimum number of bits needed to represent all the enumerators.) This assumption may not hold if the program uses a cast to convert an arbitrary integer value to the enumerated type 😬. This option has no effect for an enumeration type with a fixed underlying type 🫠.-fstrong-eval-order— evaluate member access, array subscripting, and shift expressions in left-to-right order, and evaluate assignment in right-to-left order, as adopted for C++17 💖. It's enabled by default with-std=c++17✨.-fstrong-eval-order=someenables just the ordering of member access and shift expressions, and it's the default without-std=c++17🌸.-ftemplate-backtrace-limit=n— set the maximum number of template instantiation notes for a single warning or error ton🧚. The default value is10🔢.-ftemplate-depth=n— 🌀 okay so this sets the max instantiation depth for template classes ton. That limit is what lets the compiler catch endless recursion during template class instantiation, which is honestly a lifesaver. ANSI/ISO C++ conforming programs must not rely on a max depth greater than17(it got bumped to1024in C++11). The default is900, because the compiler can run out of stack space before it ever reaches1024in some situations 😭-fno-threadsafe-statics— skip the extra code that uses the C++ ABI's thread-safe initialization routines for local statics ✨ If your code doesn't need to be thread-safe, this can shave a little off code size.-fuse-cxa-atexit— registers destructors for objects with static storage duration using__cxa_atexitinstead ofatexit🦋 This is required for fully standards-compliant handling of static destructors, but it only works if your C library supports__cxa_atexit.-fno-use-cxa-get-exception-ptr— don't use the__cxa_get_exception_ptrruntime routine. 💀 This makesstd::uncaught_exceptionincorrect, but it's necessary if that runtime routine isn't available.-fvisibility-inlines-hidden— 👑 this switch tells GCC that you won't try to compare pointers to inline functions or methods when their addresses are taken in different shared objects.
GCC can then effectively mark inline methods with __attribute__ ((visibility ("hidden"))), so they don't show up in a DSO's export table and don't need a PLT indirection when used inside that DSO. This can have a dramatic effect on load and link times for a DSO, because it massively shrinks the dynamic export table when a library leans hard on templates 🔥
This isn't quite the same as marking methods hidden directly, because it doesn't affect static variables local to the function, and it doesn't make the compiler deduce that the function is defined in only one shared object.
You can mark a method with an explicit visibility to cancel out the switch for that method. For example, if you do want to compare pointers to a particular inline method, mark it as having default visibility. Marking the enclosing class with explicit visibility has no effect.
Explicitly instantiated inline methods are unaffected by this option, since their linkage might otherwise cross a shared library boundary.
-fvisibility-ms-compat— 🎀 this flag tries to use visibility settings to make GCC's C++ linkage model match Microsoft Visual Studio's. It makes these changes to GCC's linkage model:- It sets the default visibility to
hidden, like-fvisibility=hidden. - Types, but not their members, are not hidden by default.
- The One Definition Rule is relaxed for types without explicit visibility specifications that are defined in more than one shared object. Those declarations are permitted if they'd be permitted when this option isn't used.
- It sets the default visibility to
In new code it's better to use -fvisibility=hidden and export just the classes that are meant to be externally visible. Unfortunately, code might rely on the Visual Studio behavior, perhaps accidentally.
Among the consequences: static data members of the same type, with the same name, defined in different shared objects are different, so changing one doesn't change the other. Pointers to function members defined in different shared objects may also not compare equal.
⚠️ When this flag is given, defining types with the same name differently is a violation of the ODR. Be careful, bestie.
-fno-weak— do not use weak symbol support, even if the linker provides it. By default, G++ uses weak symbols when they're available. This option exists only for testing and should not be used by end-users 🙈 It results in inferior code and has no benefits. It may be removed in a future release of G++.-fext-numeric-literals(C++ and Objective-C++ only) — 🧚 this accepts imaginary, fixed-point, or machine-defined literal number suffixes as GNU extensions. When it's turned off, those suffixes are treated as C++11 user-defined literal numeric suffixes.
It's on by default for all pre-C++11 dialects and all GNU dialects: -std=c++98, -std=gnu++98, -std=gnu++11, -std=gnu++14. It's off by default for ISO C++11 onwards (-std=c++11, ...).
-nostdinc++— don't search for header files in the standard directories specific to C++, but still search the other standard directories. (This option is used when building the C++ library.) 🌸-flang-info-include-translate,-flang-info-include-translate-not,-flang-info-include-translate=header— 🦋 these inform you of include translation events. The first one notes accepted include translations, the second notes declined ones. Theheaderform informs you about include translations relating to that specific header. Ifheaderis of the form"user"or"<system>", it gets resolved to a specific user or system header using the include path.-flang-info-module-cmi,-flang-info-module-cmi=module— 💜 these inform you of Compiled Module Interface (CMI) pathnames. The first one notes all read CMI pathnames. Themoduleform notes reading a specific module's CMI.modulemay be a named module or a header-unit. A header-unit is indicated by either being a pathname containing directory separators, or by being enclosed in<>or"".-stdlib=libstdc++,libc++— 🌈 when G++ is configured to support this option, you can pick an alternate C++ runtime library. There are two choices:libstdc++(the default, native C++ runtime for G++) andlibc++, which is the C++ runtime installed on some operating systems (e.g. Darwin versions from Darwin11 onwards). This switches G++ to use the headers from the specified library, and to emit-lstdc++or-lc++respectively when a C++ runtime is required for linking.
In addition, these warning options have meanings only for C++ programs 💅
-Wabi-tag(C++ and Objective-C++ only) — ⚠️ warns when a type with an ABI tag is used in a context that doesn't have that ABI tag. See C++ Attributes for more information about ABI tags.-Wcomma-subscript(C++ and Objective-C++ only) — 🙈 warns about uses of a comma expression within a subscripting expression. This usage was deprecated in C++20 and is going to be removed in C++23. A comma expression wrapped in( )is not deprecated. Example:
void f(int *a, int b, int c) {
a[b,c]; // deprecated in C++20, invalid in C++23
a[(b,c)]; // OK
}In C++23, it's valid to have comma separated expressions in a subscript when an overloaded subscript operator is found and supports the right number and types of arguments. G++ will accept the formerly valid syntax for code that isn't valid in C++23, but used to be valid (though deprecated) in C++20, with a pedantic warning. That warning can be disabled with -Wno-comma-subscript.
This is enabled by default with -std=c++20 unless -Wno-deprecated is given, and with -std=c++23 regardless of -Wno-deprecated.
This warning is upgraded to an error by -pedantic-errors in C++23 mode or later.
-Wctad-maybe-unsupported(C++ and Objective-C++ only) — 🔍 warns when performing class template argument deduction (CTAD) on a type with no explicitly written deduction guides. This points out cases where CTAD succeeded only because the compiler synthesized the implicit deduction guides, which might not be what the programmer intended. Certain style guides allow CTAD only on types that specifically "opt-in", i.e. types designed to support CTAD. This warning can be suppressed with the following pattern:
struct allow_ctad_t; // any name works
template <typename T> struct S {
S(T) { }
};
// Guide with incomplete parameter type will never be considered.
S(allow_ctad_t) -> S<void>;-Wctor-dtor-privacy(C++ and Objective-C++ only) — 🔒 warns when a class seems unusable because all of its constructors or destructors are private, and it has neither friends nor public static member functions. It also warns if there are no non-private methods, and there's at least one private member function that isn't a constructor or destructor.-Wdangling-reference(C++ and Objective-C++ only) — 🥀 warns when a reference is bound to a temporary whose lifetime has ended. For example:
int n = 1;
const int& r = std::max(n - 1, n + 1); // r is danglingIn the example above, two temporaries are created, one for each argument, and a reference to one of the temporaries is returned. However, both temporaries are destroyed at the end of the full expression, so the reference r is dangling. This warning also detects dangling references in member initializer lists:
const int& f(const int& i) { return i; }
struct S {
const int &r; // r is dangling
S() : r(f(10)) { }
};Member functions are checked as well, but only their object argument:
struct S {
const S& self () { return *this; }
};
const S& s = S().self(); // s is danglingCertain functions are safe in this respect, for example std::use_facet: they take and return a reference, but they don't return one of its arguments, which can fool the warning. Such functions can be excluded from the warning by wrapping them in a #pragma:
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdangling-reference"
const T& foo (const T&) { ... }
#pragma GCC diagnostic popThe #pragma can also surround the class. In that case, the warning will be disabled for all the member functions.
-Wdangling-reference also warns about code like:
auto p = std::minmax(1, 2);Okay so the std::minmax situation is a whole trap, bestie 😭 It returns a std::pair<const int&, const int&>, and both of those references dangle once the full expression that contains the std::minmax call ends 💀
This warning doesn't go off for "std::span"-like classes 🦋 So what counts as span-like? We're talking about a class that looks something like this:
template<typename T>
struct Span {
T* data_;
std::size len_;
};So basically, a non-union class with a pointer data member and a trivial destructor is span-like 🌸 If you really need the warning gone, the gnu::no_dangling attribute turns it off 🙈
And yes, this warning is on under -Wall 💖
-Wdelete-non-virtual-dtor(C++ and Objective-C++ only) — Okay, this one is a red flag 🚩 It warns whendeletedestroys an instance of a class that has virtual functions but a non-virtual destructor. Deleting a derived object through a base-class pointer is unsafe when the base doesn't have a virtual destructor 😬 Enabled by-Wall✨-Wdeprecated-copy(C++ and Objective-C++ only) — This one warns that the implicit copy constructor or copy assignment operator is deprecated when the class has a user-provided copy constructor or copy assignment operator (C++11 and up) 💅 It's enabled by-Wextra. Add-Wdeprecated-copy-dtorand it also deprecates the implicit version when the class has a user-provided destructor 🎀-Wno-deprecated-enum-enum-conversion(C++ and Objective-C++ only) — This turns off the warning for when the usual arithmetic conversions hit operands where one is an enum and the other is a different enum. That conversion got deprecated in C++20 🥀 For example:
enum E1 { e };
enum E2 { f };
int k = f - e;-Wdeprecated-enum-enum-conversion is on by default with -std=c++20. In pre-C++20 dialects, you can turn it on with -Wenum-conversion 🌈
-Wno-deprecated-enum-float-conversion(C++ and Objective-C++ only) — Same energy, but this time the warning is for an enum mixed with a floating-point type in the usual arithmetic conversions. Also deprecated in C++20 🧚 For example:
enum E1 { e };
enum E2 { f };
bool b = e <= 3.7;-Wdeprecated-enum-float-conversion is on by default with -std=c++20. In pre-C++20 dialects, use -Wenum-conversion to enable it 💜
-Wno-elaborated-enum-base— For C++11 and above, this warns if an (invalid) extra enum-base shows up in an elaborated-type-specifier. Basically, that's an enum with a given underlying type and no enumerator list, used in a declaration that isn't just a standalone declaration of the enum 🙃 It's on by default, and-pedantic-errorsupgrades it to an error 🔥-Wno-init-list-lifetime(C++ and Objective-C++ only) — Do not warn aboutstd::initializer_listuses that are likely to leave you with dangling pointers. The array behind aninitializer_listis treated like a normal C++ temporary, so it's super easy to accidentally hold a pointer to it after it's gone 😭 Here are the main ways that goes wrong:- If a function returns a temporary
initializer_list, or a localinitializer_listvariable, the array's lifetime ends at the end of the return statement, so the returned value has a dangling pointer 💀 - If a new-expression creates an
initializer_list, the array only lives until the end of the enclosing full-expression, so theinitializer_liston the heap has a dangling pointer 🫠 - When an
initializer_listvariable gets assigned from a brace-enclosed initializer list, the temporary array made for the right side only lives until the end of the full-expression. So by the next statement, that variable is dangling 🥺
// li's initial underlying array lives as long as li
std::initializer_list<int> li = { 1,2,3 };
// assignment changes li to point to a temporary array
li = { 4, 5 };
// now the temporary is gone and li has a dangling pointer
int i = li.begin()[0] // undefined behavior- When a list constructor stores the
beginpointer from aninitializer_listargument, that does not extend the array's lifetime. So if a class variable gets constructed from a temporaryinitializer_list, the pointer is left dangling by the end of the variable declaration statement 🦋 -Winvalid-constexpr(C++ and Objective-C++ only) — This warns when a function never actually produces a constant expression ✨ In C++20 and earlier, everyconstexprfunction and function template needs at least one set of arguments, in at least one instantiation, where an invocation could be an evaluated subexpression of a core constant expression. C++23 dropped that requirement, so aconstexprfunction or template might end up with no invocation that qualifies, and that's allowed now 🌸 This warning is on by default as a pedantic warning in C++20 and earlier. In C++23, you can turn on-Winvalid-constexpr, and then it's an ordinary warning. For example:
void f (int& i);
constexpr void
g (int& i)
{
// Warns by default in C++20, in C++23 only with -Winvalid-constexpr.
f(i);
}-Winvalid-imported-macros— This checks that all imported macro definitions are valid at the end of compilation 🔍 It's not on by default, because it needs extra processing to figure out. It's handy when you're preparing sets of header-units and want your macros to stay consistent 🎀-Wno-literal-suffix(C++ and Objective-C++ only) — This stops the warning when a string or character literal is followed by a ud-suffix that doesn't start with an underscore 🙈 GCC treats those suffixes as separate preprocessing tokens. It's a conforming extension, done so older code that uses formatting macros from<inttypes.h>keeps working 💖 For example:
#define __STDC_FORMAT_MACROS
#include <inttypes.h>
#include <stdio.h>
int main() {
int64_t i64 = 123;
printf("My int64: %" PRId64"\n", i64);
}In this case, PRId64 is treated as a separate preprocessing token 🧚
This option also handles warnings when a user-defined literal operator is declared with a literal suffix identifier that doesn't begin with an underscore. Those identifiers are reserved for future standardization, so these warnings are enabled by default 🌈
-Wno-narrowing(C++ and Objective-C++ only) — For C++11 and later, narrowing conversions get diagnosed by default, because the standard requires it 📏 A narrowing conversion from a constant is an error, and a narrowing conversion from a non-constant is a warning.-Wno-narrowingsuppresses that diagnostic. Heads up though, this doesn't change the meaning of well-formed code, since narrowing conversions are still ill-formed in SFINAE contexts 💅 With-Wnarrowingin C++98, you get a warning when a narrowing conversion that C++11 prohibits happens inside{ }, like this:
int i = { 2.2 }; // error: narrowing from double to intThis flag is included in -Wall and -Wc++11-compat ✨
-Wnoexcept(C++ and Objective-C++ only) — This warns when anoexceptexpression evaluates to false because of a call to a function that lacks a non-throwing exception specification (throw()ornoexcept), even though the compiler knows that function never throws 🤔-Wnoexcept-type(C++ and Objective-C++ only) — This warns if the C++17 feature that makesnoexceptpart of a function type changes the mangled name of a symbol compared to C++14 🧬 It's enabled by-Wabiand-Wc++17-compat. As an example:
template <class T> void f(T t) { t(); };
void g() noexcept;
void h() { f(g); }In C++14, f calls f<void(*)()>, but in C++17 it calls f<void(*)()noexcept> 🌟
-Wclass-memaccess(C++ and Objective-C++ only) — This warns when the destination of a raw memory function call, likememsetormemcpy, is an object of class type. It also warns when writing into that object might skip a non-trivial or deleted constructor or copy assignment, break const-correctness or encapsulation, or corrupt virtual table pointers 😱 Messing with the representation of these objects can violate invariants the member functions rely on. For example, thememsetcall below is undefined because it modifies a non-trivial class object, so GCC flags it 🚨
std::string str = "abc";
memset (&str, 0, sizeof str);The safe move for initializing or clearing storage for these types is to use the appropriate constructor or assignment operator, if there is one 🫶 -Wclass-memaccess is enabled by -Wall. If you explicitly cast the pointer to the class object to void *, or to a type the raw memory function can safely access, the warning goes away 🦋
-Wnon-virtual-dtor(C++ and Objective-C++ only) — This warns when a class has virtual functions and an accessible non-virtual destructor, either on itself or on an accessible polymorphic base class. Deleting a derived instance through a pointer to the class or its base is possible but unsafe in that case 🙃 This warning is automatically enabled if-Weffc++is specified. Honestly,-Wdelete-non-virtual-dtor(enabled by-Wall) is the one to prefer, because it warns about the unsafe cases without false positives 👑-Wregister(C++ and Objective-C++ only) — This warns on uses of theregisterstorage class specifier, except when it's part of the GNU Explicit Register Variables extension. Theregisterkeyword got deprecated in C++11 and removed in C++17 🥀 It's enabled by default with-std=c++17💀-Wreorder(C++ and Objective-C++ only) — okay bestie, this one is SO relatable 🙈 It warns when the member initializers you wrote are in a different order than they actually run in. You typed them one way and the compiler is like "nah, declaration order only 💅" For instance:
struct A {
int i;
int j;
A(): j (0), i (1) { }
};The compiler rearranges the initializers for i and j so they match the order the members are declared in, and it warns you about it with a little 🫶 This warning is enabled by -Wall.
-Wno-pessimizing-move(C++ and Objective-C++ only) — this one warns when a call tostd::movestops copy elision from happening 😭 A typical copy elision moment is returning from a function with a class return type, where the expression being returned is the name of a non-volatile automatic object, it's not a function parameter, and it has the same type as the function return type. Here's the tea:
struct T {
...
};
T fn()
{
T t;
...
return std::move (t);
}But in this example, the std::move call prevents copy elision, so it's giving main character energy in the wrong way 💀 This warning is enabled by -Wall.
-Wno-redundant-move(C++ and Objective-C++ only) — this one catches redundant calls tostd::move, aka the ones where a move would have happened anyway without thestd::movecall 🦋 That happens because the compiler is forced to treat the object as an rvalue in certain situations, like returning a local variable where copy elision isn't applicable. Consider:
struct T {
...
};
T fn(T t)
{
...
return std::move (t);
}Here, the std::move call is redundant. Because G++ implements Core Issue 1579, another example is:
struct T { // convertible to U
...
};
struct U {
...
};
U fn()
{
T t;
...
return std::move (t);
}In this example, copy elision isn't applicable because the type of the expression being returned and the function return type differ, yet G++ still treats the return value as if it were designated by an rvalue 🌸 This warning is enabled by -Wextra.
-Wrange-loop-construct(C++ and Objective-C++ only) — this one warns when a C++ range-based for-loop is making an unnecessary copy 👀 That usually happens when the range declaration isn't a reference, but it probably should be. For example:
struct S { char arr[128]; };
void fn () {
S arr[5];
for (const auto x : arr) { ... }
}It does not warn when the type being copied is a trivially-copyable type whose size is less than 64 bytes, so no need to panic over tiny stuff 🍓
It also warns when a loop variable in a range-based for-loop is initialized with a value of a different type, which results in a copy. For example:
void fn() {
int arr[10];
for (const double &x : arr) { ... }
}In the example above, every iteration of the loop creates and destroys a temporary value of type double, which the reference const double & is bound to 🫠 This warning is enabled by -Wall.
-Wredundant-tags(C++ and Objective-C++ only) — this one warns about redundant class-key and enum-key stuff in references to class types and enumerated types, in spots where the key could be dropped without causing an ambiguity 🧚 For example:
struct foo;
struct foo *p; // warn that keyword struct can be eliminatedOn the other hand, in this example there is no warning, because the keyword is actually needed:
struct foo;
void foo (); // "hides" struct foo
void bar (struct foo&); // no warning, keyword struct is necessary-Wno-subobject-linkage(C++ and Objective-C++ only) — this one says "don't warn if a class type has a base or a field whose type uses the anonymous namespace or depends on a type with no linkage" 🙅♀️ Here's why it matters: if a type A depends on a type B with no or internal linkage, defining it in multiple translation units would be an ODR violation, because the meaning of B is different in each translation unit. If A only shows up in a single translation unit, the best way to silence the warning is to give it internal linkage by putting it in an anonymous namespace as well. The compiler doesn't give this warning for types defined in the main.Cfile, since those are unlikely to have multiple definitions.-Wsubobject-linkageis enabled by default ✨-Weffc++(C++ and Objective-C++ only) — this one warns about violations of the following style guidelines from Scott Meyers' Effective C++ series of books 📚 Respect the vibes:- Define a copy constructor and an assignment operator for classes with dynamically-allocated memory.
- Prefer initialization to assignment in constructors.
- Have
operator=return a reference to*this. - Don't try to return a reference when you must return an object.
- Distinguish between prefix and postfix forms of increment and decrement operators.
- Never overload
&&,||, or,.
This option also enables -Wnon-virtual-dtor, which is also one of the effective C++ recommendations. However, the check is extended to warn about the lack of virtual destructor in accessible non-polymorphic base classes too 🫶
When you select this option, be aware that the standard library headers don't obey all of these guidelines, so you can use grep -v to filter out those warnings. Not your problem, not your fault 🙄
-Wno-exceptions(C++ and Objective-C++ only) — disables the warning about an exception handler being shadowed by another handler 🫣 That one can point out a wrong ordering of exception handlers, so it's a whole vibe check.-Wstrict-null-sentinel(C++ and Objective-C++ only) — this one warns about using an uncastedNULLas a sentinel 🍒 When you're compiling only with GCC, it's a valid sentinel, sinceNULLis defined to__null. Even though it's a null pointer constant rather than a null pointer, it's guaranteed to be the same size as a pointer. But this use isn't portable across different compilers, so bestie, be careful 🥺-Wno-non-template-friend(C++ and Objective-C++ only) — disables warnings when non-template friend functions are declared within a template 🌈 In very old versions of GCC, from before the ISO standard was implemented, declarations likefriend int foo(int), where the name of the friend is an unqualified-id, could be read as a particular specialization of a template function. The warning exists to diagnose those compatibility problems, and it's enabled by default.-Wold-style-cast(C++ and Objective-C++ only) — warns if an old-style (C-style) cast to a non-void type is used in a C++ program 💅 The new-style casts (dynamic_cast,static_cast,reinterpret_cast, andconst_cast) are way less vulnerable to unintended effects and much easier to search for, so switch over, no cap ✨-Woverloaded-virtual,-Woverloaded-virtual=n(C++ and Objective-C++ only) — these warn when a function declaration hides virtual functions from a base class 👀 Check this drama:
struct A {
virtual void f();
};
struct B: public A {
void f(int); // does not override
};The A class version of f is hidden in B, so code like this:
B* b;
b->f();fails to compile 😭 If the different signatures aren't an accident, the simplest fix is to add a using-declaration to the derived class to un-hide the base function, e.g. add using A::f; to B.
The optional level suffix controls the behavior when all the declarations in the derived class override virtual functions in the base class, even if not all of the base functions are overridden:
struct C {
virtual void f();
virtual void f(int);
};
struct D: public C {
void f(int); // does override
}This pattern is less likely to be a mistake. If D is only used virtually, the user might have decided that the base class semantics for some of the overloads are fine 🧚
At level 1, this case does not warn. At level 2, it does. -Woverloaded-virtual by itself selects level 2. Level 1 is included in -Wall.
-Wno-pmf-conversions(C++ and Objective-C++ only) — disables the diagnostic for converting a bound pointer to member function to a plain pointer 🙈-Wsign-promo(C++ and Objective-C++ only) — warns when overload resolution picks a promotion from an unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size 🔥 Older versions of G++ tried to preserve unsignedness, but the standard mandates the current behavior, so it is what it is.-Wtemplates(C++ and Objective-C++ only) — warns when a primary template declaration is encountered 🎀 Some coding rules disallow templates, and this can be used to enforce that rule. The warning is inactive inside a system header file, like the STL, so you can still use the STL. You may also instantiate or specialize templates.-Wmismatched-new-delete(C++ and Objective-C++ only) — warns about mismatches between calls tooperator neworoperator deleteand the corresponding call to the allocation or deallocation function 🫶 This includes invocations of C++operator deletewith pointers returned from either mismatched forms ofoperator new, or from other functions that allocate objects for whichoperator deleteisn't a suitable deallocator. It also covers calls to other deallocation functions with pointers returned fromoperator newfor which the deallocation function isn't suitable.
For example, the delete expression in the function below gets diagnosed because it doesn't match the array form of the new expression the pointer argument was returned from. Similarly, the call to free is also diagnosed:
void f ()
{
int *a = new int[n];
delete a; // warning: mismatch in array forms of expressionschar *p = new char[n];
free (p); // warning: mismatch between new and free
}Okay so the new/free mix-up above is exactly what this one catches 😭 The related option -Wmismatched-dealloc 🦋 handles mismatches for allocation and deallocation functions other than operator new and operator delete. Different vibe, same energy. Also, -Wmismatched-new-delete is included in -Wall 💅
-Wmismatched-tags(C++ and Objective-C++ only) — 🎀 Warns when a struct, class, or class template (or one of its specializations) gets declared with a class-key that doesn't match the definition, or the first declaration if there's no definition. In this example, thestruct Objectin the argument list ofdrawsets it off. To dodge the warning, either drop the redundantstructor swap it forclassso it matches the definition.
class Object {
public:
virtual ~Object () = 0;
};
void draw (struct Object*);Using struct as a class-key is totally legal, as the example shows 🙈 This option is just here to keep your class declarations looking consistent. If your code is meant to be portable to Windows-based compilers, it also helps prevent unresolved references caused by different mangling of symbols declared with different class-keys ✨ You can use it on its own or together with -Wredundant-tags.
-Wmultiple-inheritance(C++ and Objective-C++ only) — 🦋 Warns when a class is defined with multiple direct base classes. Some coding rules ban multiple inheritance, so this lets you enforce that rule. It stays quiet inside system headers like the STL, so you can still use the STL 💜 You can also define classes that indirectly use multiple inheritance.-Wvirtual-inheritance— 🌸 Warns when a class is defined with a virtual direct base class. Same deal: some coding rules disallow multiple inheritance, so this can enforce that. It's inactive inside system headers like the STL, so the STL is still fair game. You can also define classes that indirectly use virtual inheritance.-Wno-virtual-move-assign— Suppresses warnings about inheriting from a virtual base with a non-trivial C++11 move assignment operator.
💀 This is dangerous! If the virtual base is reachable along more than one path, it gets moved multiple times, which can leave both objects in the moved-from state. If your move assignment operator is written to avoid moving from a moved-from object, you can disable this warning.
-Wnamespaces— ✨ Warns when a namespace definition is opened. Some coding rules ban namespaces, so this can enforce that. It's inactive inside system headers like the STL, so you can still use the STL. You can also use using directives and qualified names.-Wno-template-id-cdtor(C++ and Objective-C++ only) — Disables the warning about using a simple-template-id as the declarator-id of a constructor or destructor. That became invalid in C++20 via DR 2237. Here's an example:
template<typename T> struct S {
S<T>(); // should be S();
~S<T>(); // should be ~S();
};-Wtemplate-id-cdtor is enabled by default with -std=c++20, and it's also enabled by -Wc++20-compat.
-Wno-terminate(C++ and Objective-C++ only) — 🔥 Disables the warning about a throw-expression that will immediately result in a call toterminate.-Wno-vexing-parse(C++ and Objective-C++ only) — 🙈 Warns about the most vexing parse ambiguity. This is when a declaration looks like a variable definition, but C++ requires it to be read as a function declaration. For instance:
void f(double a) {
int i(); // extern int i (void);
int n(int(a)); // extern int n (int);
}Another example:
struct S { S(int); };
void f(double a) {
S x(int(a)); // extern struct S x (int);
S y(int()); // extern struct S y (int (*) (void));
S z(); // extern struct S z (void);
}The warning will suggest ways to deal with the ambiguity, like removing the parentheses or using braces instead. This warning is enabled by default 🫶
-Wno-class-conversion(C++ and Objective-C++ only) — Don't warn when a conversion function converts an object to the same type, to a base class of that type, or tovoid. That kind of conversion function will never be called, so the warning is skipped.-Wvolatile(C++ and Objective-C++ only) — 👑 Warns about deprecated uses of thevolatilequalifier. That covers:- postfix and prefix
++and--expressions ofvolatile-qualified types - simple assignments used for their value, where the left operand is a
volatile-qualified non-class type - compound assignments where the left operand is a
volatile-qualified non-class type volatile-qualified function return typesvolatile-qualified parameter types- structured bindings of a
volatile-qualified type
- postfix and prefix
This usage was deprecated in C++20. It's enabled by default with -std=c++20 💅
-Wzero-as-null-pointer-constant(C++ and Objective-C++ only) — Warns when a literal0gets used as a null pointer constant. This can help you move over tonullptrin C++11 ✨-Waligned-new— 🦋 Warns about a new-expression of a type that needs greater alignment thanalignof(std::max_align_t), but uses an allocation function without an explicit alignment parameter. This option is enabled by-Wall. Normally it only warns about global allocation functions, but-Waligned-new=allalso warns about class member allocation functions.-Wno-placement-new,-Wplacement-new=n— 💖 Warns about placement new expressions with undefined behavior, like constructing an object in a buffer that's smaller than the object's type. For example, the placement new expression below gets flagged, because it tries to construct an array of 64 integers in a buffer that's only 64 bytes large:
char buf [64];
new (buf) int[64];This warning is enabled by default.
-Wplacement-new=1— This is the default level for-Wplacement-new. At this level, the warning isn't issued for some strictly undefined constructs that GCC allows as extensions for compatibility with legacy code. For example, the followingnewexpression isn't diagnosed at this level, even though the C++ standard says it has undefined behavior, because it writes past the end of the one-element array:
struct S { int n, a[1]; };
S *s = (S *)malloc (sizeof *s + 31 * sizeof s->a[0]);
new (s->a)int [32]();-Wplacement-new=2— 🔥 At this level, you get all the same diagnostics as level 1, plus a diagnostic for placement new expressions that construct an object in the last member of a structure. That member has to be an array of a single element, and its size has to be smaller than the object being constructed. The previous example gets flagged here, but the following construct uses the flexible member array extension to avoid the warning at level 2:
struct S { int n, a[]; };
S *s = (S *)malloc (sizeof *s + 32 * sizeof s->a[0]);
new (s->a)int [32]();-Wcatch-value,-Wcatch-value=n(C++ and Objective-C++ only) — 🎀 Warns about catch handlers that don't catch via reference. With-Wcatch-value=1(or just-Wcatch-value), it warns about polymorphic class types caught by value. With-Wcatch-value=2, it warns about all class types caught by value. With-Wcatch-value=3, it warns about all types that aren't caught by reference.-Wcatch-valueis enabled by-Wall.-Wconditionally-supported(C++ and Objective-C++ only) — Warns for conditionally-supported constructs (C++11[intro.defs]).-Wno-delete-incomplete(C++ and Objective-C++ only) — Don't warn when deleting a pointer to an incomplete type, which may cause undefined behavior at runtime. This warning is enabled by default.-Wextra-semi(C++, Objective-C++ only) — Warns about redundant semicolons after in-class function definitions 🧚-Wno-global-module(C++ and Objective-C++ only) — Disables the diagnostic for when the global module fragment of a module unit doesn't consist only of preprocessor directives.-Wno-inaccessible-base(C++, Objective-C++ only) — 🌈 Controls warnings when a base class is inaccessible in a class derived from it because of ambiguity. This warning is enabled by default. The warning for ambiguous virtual bases is enabled by-Wextra. Here's an example:
struct A { int a; };
struct B : A { };
struct C : B, A { };-Wno-inherited-variadic-ctor— Suppresses warnings about using C++11 inheriting constructors when the base class being inherited from has a C variadic constructor. The warning is on by default because the ellipsis is not inherited.-Wno-invalid-offsetof(C++ and Objective-C++ only) — 🙈 Suppresses warnings from applying theoffsetofmacro to a non-POD type. According to the 2014 ISO C++ standard, applyingoffsetofto a non-standard-layout type is undefined. In existing C++ implementations, though,offsetoftypically gives meaningful results. This flag is for people who know they're writing nonportable code and have deliberately chosen to ignore the warning about it. The restrictions onoffsetofmay be relaxed in a future version of the C++ standard.-Wsized-deallocation(C++ and Objective-C++ only) — ⭐ Warns about a definition of an unsized deallocation function:
void operator delete (void *) noexcept;
void operator delete[] (void *) noexcept;without a definition of the corresponding sized deallocation function:
void operator delete (void *, std::size_t) noexcept;
void operator delete[] (void *, std::size_t) noexcept;or vice versa. It's enabled by -Wextra along with -fsized-deallocation.
-Wsuggest-final-types: okay bestie, this one warns you about types with virtual methods that would be cleaner marked with the C++11finalspecifier, or, if possible, declared in an anonymous namespace 🦋. It lets GCC devirtualize polymorphic calls more aggressively ✨. It works best with link-time optimization, since LTO has a fuller picture of the class hierarchy graph 🔥.-Wsuggest-final-methods: same energy, but for individual virtual methods 💅. It warns when a method would be improved by thefinalspecifier, or when its type could go in an anonymous namespace or getfinal🌸. Again, LTO makes this more accurate because it knows more about the class hierarchy graph 🧚. The move is to check the-Wsuggest-final-typessuggestions first, then rebuild with the new annotations 💖.-Wsuggest-override: flags virtual functions that override something without theoverridekeyword 🎀.-Wno-conversion-null(C++ and Objective-C++ only): turns off warnings for conversions betweenNULLand non-pointer types 🙈. Heads up,-Wconversion-nullis already on by default 👑.
🌈 Options Controlling Objective-C and Objective-C++ Dialects 🌈
NOTE: this manual doesn't teach you the Objective-C and Objective-C++ languages themselves 🙈. What it does cover is the command-line options that only matter for those languages. You can still use most of the language-independent GNU compiler options too 💜.
Here's a quick example of compiling a file called some_class.m:
gcc -g -fgnu-runtime -O -c some_class.mIn that example, -fgnu-runtime is only meant for Objective-C and Objective-C++ 💅. The other options work with any language GCC supports ✨.
Since Objective-C is basically an extension of C, Objective-C compiles can also use C front-end options, like -Wtraditional 🦋. Objective-C++ compiles can use C++-specific options too, like -Wabi 🔥.
Here's the list of options that are only for Objective-C and Objective-C++ programs 🫶:
-fconstant-string-class=class-name: picks the class that gets instantiated for each literal string written as"@"...""💖. The default isNXConstantStringwith the GNU runtime andNSConstantStringwith the NeXT runtime 🍓. On Darwin / macOS, if-fconstant-cfstringsis also present, it overrides this setting and makes"@"...""literals laid out as constant CoreFoundation strings 🌈. Also,-fconstant-cfstringsis just an alias for the target-specific-mconstant-cfstrings✨.-fgnu-runtime: generates object code that works with the standard GNU Objective-C runtime 💜. This is the default on most systems 👑.-fnext-runtime: generates output that works with the NeXT runtime 🍎. It's the default on NeXT-based systems, including Darwin / macOS 🌸. The macro__NEXT_RUNTIME__is predefined if, and only if, you use this option 🧚.-fno-nil-receivers: tells the compiler to assume every Objective-C message dispatch ([receiver message:arg]) in this translation unit has a receiver that isn'tnil🙈. That lets the runtime use more efficient entry points 🔥. It only works with the NeXT runtime and ABI version 0 or 1 🫶.-fobjc-abi-version=n: uses versionnof the Objective-C ABI for the selected runtime 💅. Right now this is only supported for the NeXT runtime 🦋. Version 0 is the traditional (32-bit) ABI with no support for properties or other Objective-C 2.0 additions 🥺. Version 1 is the traditional (32-bit) ABI with properties and other Objective-C 2.0 additions 💖. Version 2 is the modern (64-bit) ABI ✨. If you don't specify anything, the default is Version 0 on 32-bit targets and Version 2 on 64-bit targets 👑.-fobjc-call-cxx-cdtors: for each Objective-C class, it checks whether any instance variable is a C++ object with a non-trivial default constructor 🎀. If one is, it synthesizes a special- (id) .cxx_constructinstance method that runs those constructors in order, then returnsself🌈. It also checks for C++ objects with a non-trivial destructor, and if it finds any, synthesizes a- (void) .cxx_destructmethod that runs those destructors in reverse order 💀.
These generated - (id) .cxx_construct and - (void) .cxx_destruct methods only touch instance variables declared in the current Objective-C class, not the ones inherited from superclasses 🧚. It's the Objective-C runtime's job to call all of these methods across an object's inheritance hierarchy 💜. The runtime calls - (id) .cxx_construct right after a new object instance is allocated, and calls - (void) .cxx_destruct right before it deallocates the instance 🫶.
As of this writing, only the NeXT runtime on Mac OS X 10.4 and later can invoke - (id) .cxx_construct and - (void) .cxx_destruct 🍎.
-fobjc-direct-dispatch: allows fast jumps to the message dispatcher ⚡. On Darwin, this happens through the comm page 🌸.-fobjc-exceptions: turns on syntax for structured exception handling in Objective-C, kind of like C++ 🦋. You need this to use the Objective-C keywords@try,@throw,@catch,@finallyand@synchronized💅. It works with both the GNU runtime and the NeXT runtime, but not with the NeXT runtime on Mac OS X 10.2 and earlier 🙈.-fobjc-gc: enables garbage collection (GC) in Objective-C and Objective-C++ programs 🗑️. This is only available with the NeXT runtime 🍎. The GNU runtime has its own, different garbage collection setup that doesn't need special compiler flags 💖.-fobjc-nilcheck: for the NeXT runtime with version 2 of the ABI, checks for anilreceiver in method invocations before making the actual call 🫶. This is the default, and you can turn it off with-fno-objc-nilcheck🙅. Class methods and super calls never get this nil check, no matter what this flag is set to 💅. Right now this flag does nothing with the GNU runtime or an older version of the NeXT runtime ABI 🥲.-fobjc-std=objc1: makes the compiler follow the language syntax of Objective-C 1.0, the one GCC 4.0 recognized 🕰️. This only affects the Objective-C additions to C/C++, so it doesn't change conformance to C/C++ standards, which the separate C/C++ dialect flags control 🌈. With this option on, any Objective-C or Objective-C++ syntax that GCC 4.0 doesn't recognize gets rejected 🙅. It's super handy if you need to be sure your Objective-C code compiles with older versions of GCC 🎀.-freplace-objc-classes: emits a special marker that tellsld(1)not to statically link the resulting object file, and letsdyld(1)load it at run time instead 🧚. This pairs with the Fix-and-Continue debugging mode, where the object file can be recompiled and dynamically reloaded while the program is running, no restart needed 🔄. For now, Fix-and-Continue only works with the NeXT runtime on Mac OS X 10.3 and later 🍎.-fzero-link: when compiling for the NeXT runtime, the compiler normally swaps calls toobjc_getClass("...")(when the class name is known at compile time) for static class references that get initialized at load time, which makes things faster ⚡. Using-fzero-linkturns that off and keeps theobjc_getClass("...")calls 🫶. That's useful in Zero-Link debugging mode, since it lets you modify individual class implementations while the program runs 🛠️. The GNU runtime always keepsobjc_get_class("...")calls, no matter what command-line options you pass 💀.-fno-local-ivars: by default, Objective-C instance variables can be accessed like local variables inside the methods of the class they're declared in 🙈. That can cause shadowing between instance variables and other variables with the same name, whether they're declared locally in a class method or globally 😭. Using-fno-local-ivarsturns this behavior off and avoids those shadowing problems 🫶.-fivar-visibility=[public|protected|private|package]: sets the default instance variable visibility to whichever option you pick 🦋. Any instance variables declared outside the scope of an access modifier directive will default to that visibility 💅.-gen-decls: dumps the interface declarations for all classes seen in the source file into a file namedsourcename.decl📜.-Wassign-intercept(Objective-C and Objective-C++ only): warns whenever the garbage collector intercepts an Objective-C assignment 🗑️.-Wno-property-assign-default(Objective-C and Objective-C++ only): stops the warning for an Objective-C object property that doesn't have assign semantics specified 🙈.-Wno-protocol(Objective-C and Objective-C++ only): if a class says it implements a protocol, GCC normally warns for every protocol method the class doesn't implement 🧐. Even if a method is inherited from the superclass, that still counts as a warning by default 😤. With-Wno-protocol, inherited methods count as implemented, so no warning shows up for them 🫶.-Wobjc-root-class(Objective-C and Objective-C++ only): warns if a class interface has no superclass 🌳. Most classes inherit fromNSObject(orObject), for example 💜. If you're declaring classes that are meant to be root classes, you can silence the warning by marking their interfaces with__attribute__((objc_root_class))👑.
💖 Objective-C Warnings 💖
-Wselector(Objective-C and Objective-C++ only) — okay so this one warns you if the same selector shows up with different method types during compilation 👀. The check runs on the method list at the very end of compilation. It also checks every selector used in a@selector(...)expression that matches a method found during compilation 🧚. Since all of this only happens at the end, these warnings won't show up if the final stage never gets reached, like when an error stops compilation early, or when-fsyntax-onlyis in use 😭.-Wstrict-selector-match(Objective-C and Objective-C++ only) — this one is giving strict 💅. It warns when you send a message with a selector to a receiver of typeidorClass, and multiple methods for that selector have different argument and/or return types. By default this flag is off 🙈, and when it's off the compiler skips these warnings if the only differences are between types that share the same size and alignment.-Wundeclared-selector(Objective-C and Objective-C++ only) — warns if you use a@selector(...)expression for a selector that was never declared 🫶. A selector counts as undeclared if no method with that name was declared before the@selector(...)expression, whether explicitly in an@interfaceor@protocoldeclaration, or implicitly in an@implementationsection. This one checks right away when it spots a@selector(...)expression, while-Wselectorwaits until the final stage of compilation 🦋. It also backs up the coding style rule that methods and selectors need to be declared before they're used. Main character energy 👑.-print-objc-runtime-info— generates a C header describing the largest structure that gets passed by value, if there is one 🌈.
✨ Options to Control Diagnostic Messages Formatting ✨
Okay so traditionally, diagnostic messages were formatted without caring what the output device looked like (its width, and so on) 💀. These options let you control the formatting algorithm, like how many characters go on each line and how often source location info gets reported 🎀. Heads up that some language front ends might not honor these options 🙈.
-fmessage-length=n— tries to format error messages so they fit on lines about n characters wide 🍓. If n is zero, no line-wrapping happens, and each error message stays on a single line. This is the default for all front ends.
Note: this option also affects the display of the#errorand#warningpre-processor directives, and the deprecated function/type/variable attribute. It does not affect thepragma GCC warningandpragma GCC errorpragmas 😭.
-fdiagnostics-plain-output— requests that diagnostic output look as plain as possible 🧼. This is handy when you're running dejagnu or other tools that parse diagnostics and need the output to stay stable over time.-fdiagnostics-plain-outputis currently equivalent to these options:
-fno-diagnostics-show-caret -fno-diagnostics-show-line-numbers
-fdiagnostics-color=never -fdiagnostics-urls=never
-fdiagnostics-path-format=separate-events
-fdiagnostics-text-art-charset=noneIf GCC ever changes the default look of its diagnostics in the future, the matching option to turn off the new behavior will get added to this list 🔮.
-fdiagnostics-show-location=once— only matters in line-wrapping mode 🌸. It tells the reporter to emit source location info once. So if a message is too long and has to be wrapped, the location won't get repeated as a prefix on every continuation line. This is the default behavior.-fdiagnostics-show-location=every-line— also only matters in line-wrapping mode ✨. This one tells the reporter to put the same source location info (as a prefix) on every physical line created when a too-long message gets broken up.-fdiagnostics-color[=WHEN],-fno-diagnostics-color— turns colors on in diagnostics 🌈. WHEN can benever,always, orauto. The default depends on how the compiler was configured. It can be any of thoseWHENoptions, orneverif theGCC_COLORSenvironment variable isn't in the environment, andautootherwise.autoonly uses color when standard error is a terminal and you're not running in an emacs shell 🧚. The forms-fdiagnostics-colorand-fno-diagnostics-colorare aliases for-fdiagnostics-color=alwaysand-fdiagnostics-color=never, respectively.
The colors are set by the GCC_COLORS environment variable 💅. Its value is a colon-separated list of capabilities and Select Graphic Rendition (SGR) substrings. SGR commands get interpreted by the terminal or terminal emulator. Check the section in your text terminal's documentation for the permitted values and what they mean as character attributes 📖. These substring values are integers written in decimal, and they can be stacked together with semicolons. Common ones you might stack include:
1for bold4for underline5for blink7for inverse39for default foreground color30to37for foreground colors90to97for 16-color mode foreground colors38;5;0to38;5;255for 88-color and 256-color mode foreground colors49for default background color40to47for background colors100to107for 16-color mode background colors48;5;0to48;5;255for 88-color and 256-color mode background colors
The default GCC_COLORS is this giant vibe 🎨:
error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\
quote=01:path=01;36:fixit-insert=32:fixit-delete=31:\
diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
type-diff=01;32:fnname=01;32:targs=35:valid=01;31:invalid=01;32Here 01;31 is bold red, 01;35 is bold magenta, 01;36 is bold cyan, 32 is green, 34 is blue, 01 is bold, and 31 is red. Setting GCC_COLORS to the empty string turns colors off completely 🚫. These are the supported capabilities:
error=— SGR substring forerror:markers.warning=— SGR substring forwarning:markers.note=— SGR substring fornote:markers.path=— SGR substring for coloring paths of control-flow events printed via-fdiagnostics-path-format=, like the identifiers of individual events and the lines showing interprocedural calls and returns.range1=— SGR substring for the first additional range.range2=— SGR substring for the second additional range.locus=— SGR substring for location info, likefile:lineorfile:line:columnetc.quote=— SGR substring for info printed within quotes.fnname=— SGR substring for names of C++ functions.targs=— SGR substring for C++ function template parameter bindings.fixit-insert=— SGR substring for fix-it hints suggesting text to be inserted or replaced.fixit-delete=— SGR substring for fix-it hints suggesting text to be deleted.diff-filename=— SGR substring for filename headers within generated patches.diff-hunk=— SGR substring for the starts of hunks within generated patches.diff-delete=— SGR substring for deleted lines within generated patches.diff-insert=— SGR substring for inserted lines within generated patches.type-diff=— SGR substring for highlighting mismatching types within template arguments in the C++ frontend.valid=— SGR substring for highlighting valid elements within text art diagrams.invalid=— SGR substring for highlighting invalid elements within text art diagrams.-fdiagnostics-urls[=WHEN]— uses escape sequences to embed URLs in diagnostics 🔗. For example, when-fdiagnostics-show-optionshows the command-line option controlling a diagnostic, it embeds a URL pointing to the docs for that option.
WHEN can be never, always, or auto. auto only uses URL escape sequences when standard error is a terminal, and you're not running in an emacs shell or any graphical terminal known to be incompatible with this feature (see below) 🙅♀️.
The default depends on how the compiler was configured, and it can be any of the WHEN options above. GCC can also be configured with the --with-diagnostics-urls=auto-if-env configure-time option, so the default depends on environment variables. In that setup, GCC defaults to auto if either the GCC_URLS or TERM_URLS environment variable is present and non-empty in the compiler's environment, or never if neither is.
Even with -fdiagnostics-urls=always, the behavior still depends on those environment variables 👀:
- If
GCC_URLSis set to empty orno, URLs don't get embedded in diagnostics. - If it's set to
st, URLs use ST escape sequences. - If it's set to
bel, the default, URLs use BEL escape sequences. - Any other non-empty value enables the feature.
- If
GCC_URLSisn't set,TERM_URLSis used as a fallback.
Quick aside: ST is an ANSI escape sequence whose string terminator is ESC \. BEL is an ASCII character, CTRL-G, that usually sounds like a beep 🔔.
At this point GCC also tries to detect a few terminals that don't implement the URL feature, and that have had bugs in some versions still in use, where URL escapes are likely to misbehave and print garbage on the screen 😭. That list currently includes xfce4-terminal, certain known-buggy gnome-terminal versions, the linux console, and mingw. You can skip this check with -fdiagnostics-urls=always.
-fno-diagnostics-show-option— by default, every diagnostic emitted includes text showing the command-line option that directly controls it (if that option is known to the diagnostic machinery) 🧾. Using-fno-diagnostics-show-optionturns that off.-fno-diagnostics-show-caret— bye, source line and caret 🙈
By default, every diagnostic comes with the original source line and a caret ^ pointing at the column 💅 This option suppresses that info. If you pass -fmessage-length=n, the source line gets chopped to n characters ✂️ When the output goes to the terminal, the width is limited by the COLUMNS environment variable or, if that isn't set, the terminal width 🖥️
-fno-diagnostics-show-labels— no more little labels on the code 🏷️
By default, when printing source code (via -fdiagnostics-show-caret), diagnostics can label ranges of source code with useful info, like the types of expressions. It's giving detective energy 🔍
printf ("foo %s bar", long_i + long_j);
~^ ~~~~~~~~~~~~~~~
| |
char * long intThis option suppresses those labels (in the example above, the vertical bars and the "char *" and "long int" text) 🙅
-fno-diagnostics-show-cwe— hide the CWE tags 🎀
Diagnostic messages can optionally have a CWE identifier attached (see https://cwe.mitre.org/index.html) ✨ GCC itself only provides that metadata for some -fanalyzer diagnostics, and GCC plugins may also add it. By default, if the info is there, it gets printed with the diagnostic. This option suppresses the printing of this metadata 🫶
-fno-diagnostics-show-rules— no rule tags either 📜
Diagnostic messages can optionally have rules attached to them, like rules from a coding standard or a specification. GCC itself doesn't do this for any of its diagnostics, but plugins can. By default, if that info is present, it gets printed with the diagnostic. This option suppresses the printing of this metadata 💖
-fno-diagnostics-show-line-numbers— kill the left margin 🌸
By default, when printing source code (via -fdiagnostics-show-caret), a left margin is printed, showing line numbers. This option suppresses that left margin 🦋
-fdiagnostics-minimum-margin-width=width— set the minimum margin width 📏
This option controls the minimum width of the left margin printed by -fdiagnostics-show-line-numbers. It defaults to 6 🍓
-fdiagnostics-parseable-fixits— fix-its that IDEs can actually read 🧚
This one is for IDEs, bestie 💻 Fix-it hints get emitted in a machine-parseable format. For each fix-it, a line gets printed after the relevant diagnostic, starting with the string fix-it:. For example:
fix-it:"test.c":{45:3-45:21}:"gtk_widget_show_all"The location is a half-open range, expressed as a count of bytes, starting at byte 1 for the initial column. In the example above, bytes 3 through 20 of line 45 of "test.c" get replaced with the given string 🔄
00000000011111111112222222222
12345678901234567890123456789
gtk_widget_showall (dlg);
^^^^^^^^^^^^^^^^^^
gtk_widget_show_allThe filename and replacement string escape backslash as "\\", tab as "\t", newline as "\n", double quotes as "\"", and non-printable characters as octal (for example, vertical tab as "\013") 🫧
An empty replacement string means the given range gets removed 🗑️ An empty range (for example "45:3-45:3") means the string gets inserted at the given position ➕
-fdiagnostics-generate-patch— get a diff, no cap 📝
This prints fix-it hints to stderr in unified diff format, after any diagnostics are printed. For example:
--- test.c
+++ test.c
@ -42,5 +42,5 @
void show_cb(GtkDialog *dlg)
{
- gtk_widget_showall(dlg);
+ gtk_widget_show_all(dlg);
}The diff may or may not be colorized, following the same rules as for diagnostics (see -fdiagnostics-color) 🌈
-fdiagnostics-show-template-tree— C++ template types, but make it a tree 🌳
In the C++ frontend, when printing diagnostics about mismatching template types, such as:
could not convert 'std::map<int, std::vector<double> >()'
from 'map<[...],vector<double>>' to 'map<[...],vector<float>>this flag enables printing a tree-like structure that shows the common and differing parts of the types, like this:
map<
[...],
vector<
[double != float]>>The parts that differ are highlighted with color ("double" and "float" in this case) 🎨
-fno-elide-type— stop the[...]shortcuts 🙅♀️
By default, when the C++ frontend prints diagnostics about mismatching template types, the common parts of the types get printed as "[...]" to keep the error message short. For example:
could not convert 'std::map<int, std::vector<double> >()'
from 'map<[...],vector<double>>' to 'map<[...],vector<float>>Specifying -fno-elide-type suppresses that behavior 💅 This flag also affects the output of the -fdiagnostics-show-template-tree flag ✨
-fdiagnostics-path-format=KIND— how control-flow paths get shown 🛤️
This specifies how to print paths of control-flow events for diagnostics that have one attached. KIND is none, separate-events, or inline-events, which is the default 👑
none means don't print diagnostic paths at all 🚫
separate-events means print a separate "note" diagnostic for each event within the diagnostic. For example:
test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter
test.c:25:10: note: (1) when 'PyList_New' fails, returning NULL
test.c:27:3: note: (2) when 'i < count'
test.c:29:5: note: (3) when calling 'PyList_Append', passing NULL from (1) as argument 1inline-events means print the events "inline" within the source code. This view tries to consolidate the events into runs of sufficiently close events, printing them as labelled ranges within the source 🪄
For example, the same events as above might be printed as:
'test': events 1-3
|
| 25 | list = PyList_New(0);
| | ^~~~~~~~~~~~~
| | |
| | (1) when 'PyList_New' fails, returning NULL
| 26 |
| 27 | for (i = 0; i < count; i++) {
| | ~~~
| | |
| | (2) when 'i < count'
| 28 | item = PyLong_FromLong(random());
| 29 | PyList_Append(list, item);
| | ~~~~~~~~~~~~~~~~~~~~~~~~~
| | |
| | (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
|Interprocedural control flow is shown by grouping the events by stack frame, and using indentation to show how stack frames are nested, pushed, and popped 🧠
'test': events 1-2
|
| 133 | {
| | ^
| | |
| | (1) entering 'test'
| 134 | boxed_int *obj = make_boxed_int (i);
| | ~~~~~~~~~~~~~~~~~~
| | |
| | (2) calling 'make_boxed_int'
|
+--> 'make_boxed_int': events 3-4
|
| 120 | {
| | ^
| | |
| | (3) entering 'make_boxed_int'
| 121 | boxed_int *result = (boxed_int *)wrapped_malloc (sizeof (boxed_int));
| | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| | |
| | (4) calling 'wrapped_malloc'
|
+--> 'wrapped_malloc': events 5-6
|
| 7 | {
| | ^
| | |
| | (5) entering 'wrapped_malloc'
| 8 | return malloc (size);
| | ~~~~~~~~~~~~~
| | |
| | (6) calling 'malloc'
|
<-------------+
|
'test': event 7
|
| 138 | free_boxed_int (obj);
| | ^~~~~~~~~~~~~~~~~~~~
| | |
| | (7) calling 'free_boxed_int'
|
(etc)-fdiagnostics-show-path-depths— extra depth info for path debugging 🔬
This option provides additional info when printing control-flow paths associated with a diagnostic 🦋
If this option is provided, the stack depth will be printed for each run of events within -fdiagnostics-path-format=inline-events. If it's provided with -fdiagnostics-path-format=separate-events, then the stack depth and function declaration will be appended when printing each event 🪜
This one is intended for GCC developers and plugin developers who are debugging diagnostics that report interprocedural control flow 🛠️
-fno-show-column— no column numbers, please 🙈
Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that doesn't understand column numbers, such as dejagnu 🤖
-fdiagnostics-column-unit=UNIT— pick how columns get counted 🔢
This selects the units for the column number. It affects traditional diagnostics (when -fno-show-column isn't in play), as well as JSON format diagnostics if requested 📊
The default UNIT, display, counts the number of display columns each character occupies. That can be bigger than the number of bytes needed to encode the character (like with tab characters), or smaller (like with multibyte characters). For example, the character "GREEK SMALL LETTER PI (U+03C0)" occupies one display column, but its UTF-8 encoding needs two bytes. The character "SLIGHTLY SMILING FACE (U+1F642)" occupies two display columns, and its UTF-8 encoding needs four bytes 🌈
Setting UNIT to byte makes the column number count raw bytes in every case, which is how GCC did it before version 11.1.0. 🧮 Very old-school, bestie. 🕰️
-fdiagnostics-column-origin=ORIGIN— picks which number the first column gets 🦋
The default of 1 is the classic GCC vibe and matches the GNU style guide, so it's the safe pick ✨. Some utilities actually work better with an origin of 0, and any non-negative value is allowed, so you have options 💅.
-fdiagnostics-escape-format=FORMAT— decides how weird bytes get displayed when GCC prints source lines 🌸
Normally GCC just prints the source bytes straight up. But some diagnostics are about encoding drama in the source file, like malformed UTF-8 or Unicode normalization issues 😭. Those get flagged, so GCC escapes any byte that isn't printable ASCII when it prints the relevant source lines. This option controls how those bytes get escaped 🫶.
The default FORMAT is unicode. It shows non-printable-ASCII Unicode characters as <U+XXXX>, and any bytes that don't form a validly UTF-8-encoded Unicode character show up as hex in the form <XX> 🍓.
For example, say a source line has the string before, then the Unicode character U+03C0 ("GREEK SMALL LETTER PI", with UTF-8 encoding 0xCF 0x80), then the byte 0xBF (a stray UTF-8 trailing byte), then the string after. For that diagnostic, you'd get:
before<U+03C0><BF>afterSetting FORMAT to bytes shows every non-printable-ASCII byte as <XX>, so you can see the underlying encoding of non-ASCII Unicode characters 🔍. For the example above, this gets printed:
before<CF><80><BF>after-fdiagnostics-text-art-charset=CHARSET— picks which characters get used for "text art" diagrams 🎨
Some diagnostics include text art, which are visualizations made out of text and meant to be viewed in a monospaced font 🧚. This option picks the characters used for those diagrams, if any. CHARSET can be none, ascii, unicode, or emoji.
none turns the diagrams off completely. ascii keeps everything pure ASCII, aka "ASCII art" 🖤. unicode lets the diagrams use a conservative amount of Unicode drawing characters, like box-drawing characters 📦. emoji goes further and adds emoji to the mix too, like emitting U+26A0 WARNING SIGN followed by U+FE0F VARIATION SELECTOR-16 to select the emoji variant of the character ⚠️.
The default is emoji, except when the environment variable LANG is set to C. In that case the default is ascii 🌈.
-fdiagnostics-format=FORMAT— switches up how diagnostics get printed 💜
FORMAT can be text, sarif-stderr, sarif-file, json, json-stderr, or json-file. The default is text 💖.
The sarif-stderr and sarif-file formats both emit diagnostics in SARIF Version 2.1.0 format. sarif-stderr sends them to stderr, and sarif-file writes them to a file named source.sarif ✨.
json is just a synonym for json-stderr. The json-stderr and json-file formats are identical, apart from where the JSON goes: the former emits to stderr, while json-file writes it to source.gcc.json 🎀.
The emitted JSON is a top-level JSON array, and inside it are JSON objects representing the diagnostics 🫶.
Diagnostics can have child diagnostics too. For example, this error and note:
misleading-indentation.c:15:3: warning: this 'if' clause does not
guard... [-Wmisleading-indentation]
15 | if (flag)
| ^~
misleading-indentation.c:17:5: note: ...this statement, but the latter
is misleadingly indented as if it were guarded by the 'if'
17 | y = 2;
| ^might be printed in JSON form (after formatting) like this:
[
{
"kind": "warning",
"locations": [
{
"caret": {
"display-column": 3,
"byte-column": 3,
"column": 3,
"file": "misleading-indentation.c",
"line": 15
},
"finish": {
"display-column": 4,
"byte-column": 4,
"column": 4,
"file": "misleading-indentation.c",
"line": 15
}
}
],
"message": "this \u2018if\u2019 clause does not guard...",
"option": "-Wmisleading-indentation",
"option_url": "https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wmisleading-indentation",
"children": [
{
"kind": "note",
"locations": [
{
"caret": {
"display-column": 5,
"byte-column": 5,
"column": 5,
"file": "misleading-indentation.c",
"line": 17
}
}
],
"escape-source": false,
"message": "...this statement, but the latter is ..."
}
]
"escape-source": false,
"column-origin": 1,
}
]Here the "note" is a child of the "warning" 🌷.
A diagnostic has a "kind". If that's "warning", then there's an "option" key describing the command-line option controlling the warning 🚨.
A diagnostic can contain zero or more locations. Each location has an optional "label" string and up to three positions within it: a "caret" position and optional "start" and "finish" positions. A position is described by a "file" name, a "line" number, and three numbers indicating a column position:
"display-column"counts display columns, accounting for tabs and multibyte characters."byte-column"counts raw bytes."column"is equal to one of the previous two, as dictated by the-fdiagnostics-column-unitoption.
All three columns are relative to the origin set by -fdiagnostics-column-origin. That's usually 1, but it can be set to 0 for compatibility with other utilities that number columns from 0 🧚. The column origin gets recorded in the JSON output under the "column-origin" tag. In the remaining examples below, the extra column number outputs have been left out for brevity 🙈.
For example, this error:
bad-binary-ops.c:64:23: error: invalid operands to binary + (have 'S' {aka
'struct s'} and 'T' {aka 'struct t'})
64 | return callee_4a () + callee_4b ();
| ~~~~~~~~~~~~ ^ ~~~~~~~~~~~~
| | |
| | T {aka struct t}
| S {aka struct s}has three locations 👑. Its primary location is at the "+" token at column 23. It also has two secondary locations, describing the left and right-hand sides of the expression, and those have labels 💅. It might be printed in JSON form as:
{
"children": [],
"kind": "error",
"locations": [
{
"caret": {
"column": 23, "file": "bad-binary-ops.c", "line": 64
}
},
{
"caret": {
"column": 10, "file": "bad-binary-ops.c", "line": 64
},
"finish": {
"column": 21, "file": "bad-binary-ops.c", "line": 64
},
"label": "S {aka struct s}"
},
{
"caret": {
"column": 25, "file": "bad-binary-ops.c", "line": 64
},
"finish": {
"column": 36, "file": "bad-binary-ops.c", "line": 64
},
"label": "T {aka struct t}"
}
],
"escape-source": false,
"message": "invalid operands to binary + ..."
}If a diagnostic contains fix-it hints, it has a "fixits" array made of half-open intervals, similar to the output of -fdiagnostics-parseable-fixits 🔧. For example, this diagnostic with a replacement fix-it hint:
demo.c:8:15: error: 'struct s' has no member named 'colour'; did you
mean 'color'?
8 | return ptr->colour;
| ^~~~~~
| colormight be printed in JSON form as:
{
"children": [],
"fixits": [
{
"next": {
"column": 21,
"file": "demo.c",
"line": 8
},
"start": {
"column": 15,
"file": "demo.c",
"line": 8
},
"string": "color"
}
],
"kind": "error",
"locations": [
{
"caret": {
"column": 15,
"file": "demo.c",
"line": 8
},
"finish": {
"column": 20,
"file": "demo.c",
"line": 8
}
}
],
"escape-source": false,
"message": "\u2018struct s\u2019 has no member named ..."
}okay so the fix-it hint is basically saying "swap this chunk out for that." 💅 It replaces the text from "start" up to but not including "next" with the "string" value. Want to delete something? Give "string" an empty value 🧹. Want to insert something? Make "start" equal "next" ✨. So cute, so precise, no notes.
If the diagnostic has a path of control-flow events attached to it, you'll see a "path" array full of event objects 🦋. Each event has a "description" string, a "location" object, plus a "function" string and a "depth" number for tracking interprocedural paths. The "function" tells you which function is running at that event, and the "depth" is the stack depth relative to some baseline. Higher depth means more frames on the stack. Main character stack energy 🌸.
For example, the intraprocedural example shown for -fdiagnostics-path-format= might have this JSON for its path:
"path": [
{
"depth": 0,
"description": "when 'PyList_New' fails, returning NULL",
"function": "test",
"location": {
"column": 10,
"file": "test.c",
"line": 25
}
},
{
"depth": 0,
"description": "when 'i < count'",
"function": "test",
"location": {
"column": 3,
"file": "test.c",
"line": 27
}
},
{
"depth": 0,
"description": "when calling 'PyList_Append', passing NULL from (1) as argument 1",
"function": "test",
"location": {
"column": 5,
"file": "test.c",
"line": 29
}
}
]Diagnostics also have a boolean attribute called escape-source 🙈. It's a hint for whether non-ASCII bytes should be escaped when the pertinent lines of source code get printed. It's true for diagnostics involving source encoding issues, so that's your red flag, bestie 🚩.
-fno-diagnostics-json-formatting— okay so by default, when JSON gets emitted for diagnostics (via-fdiagnostics-format=sarif-stderr,-fdiagnostics-format=sarif-file,-fdiagnostics-format=json,-fdiagnostics-format=json-stderr, or-fdiagnostics-format=json-file), GCC adds newlines and indentation so the hierarchy looks pretty and readable 💖. Use-fno-diagnostics-json-formattingto strip that whitespace out. It must be passed before the option it is to affect ⚠️. This is meant for tools that don't expect newlines in the output, like the kind older GCC releases spit out 🧓.
🎀 Options to Request or Suppress Warnings 🎀
Okay, warnings are diagnostic messages about stuff that isn't technically broken but is risky or hints that there might be a mistake lurking 👀.
The following language-independent options don't turn on specific warnings. Instead, they control what kinds of diagnostics GCC produces 💅.
-fsyntax-only— checks your code for syntax errors and then stops right there. No extra fuss 🧼.-fmax-errors=n— caps the number of error messages atn, and once you hit that, GCC bails instead of trying to keep going through the source code 🛑. Ifnis0(the default), there's no limit on how many error messages get printed. If-Wfatal-errorsis also specified, then-Wfatal-errorstakes precedence over this option 👑.-w— inhibits all warning messages. Silence is golden 🤫.-Werror— turns every warning into an error 😤.-Werror=— turns one specific warning into an error. You append the warning's specifier, so for example-Werror=switchturns the warnings controlled by-Wswitchinto errors. This one also has a negative form, used to negate-Werrorfor specific warnings. For example,-Wno-error=switchmakes-Wswitchwarnings not be errors, even when-Werroris in effect 🙅♀️.-Wfatal-errors— makes the compiler abort compilation on the first error it runs into, instead of trying to keep going and printing more error messages 🛑.
The warning message for each controllable warning includes the option that controls it 🔍. You can then use that option with -Werror= and -Wno-error= like we just covered. (Printing of the option in the warning message can be disabled using the -fno-diagnostics-show-option flag.)
Note that specifying -Werror=foo automatically implies -Wfoo. However, -Wno-error=foo does not imply anything 🧐.
You can request many specific warnings with options that begin with -W. For example, -Wimplicit requests warnings on implicit declarations 🍓. Each of these specific warning options also has a negative form that begins with -Wno- to turn the warnings off. For example, -Wno-implicit. This manual only lists one of the two forms, whichever one is not the default 🌈. For further language-specific options, also refer to C++ Dialect Options and Objective-C and Objective-C++ Dialect Options. Additional warnings can be produced by enabling the static analyzer;
Some options, such as -Wall and -Wextra, turn on other options, such as -Wunused, which may turn on further options, such as -Wunused-value. The combined effect of positive and negative forms is that more specific options have priority over less specific ones, independently of their position on the command-line 🧠. For options of the same specificity, the last one takes effect. Options enabled or disabled via pragmas take effect as if they appeared at the end of the command-line 📌.
When an unrecognized warning option is requested (e.g., -Wunknown-warning), GCC emits a diagnostic stating that the option is not recognized 🤷♀️. However, if the -Wno- form is used, the behavior is slightly different: no diagnostic is produced for -Wno-unknown-warning unless other diagnostics are being produced. This lets you use new -Wno- options with old compilers, but if something goes wrong, the compiler warns that an unrecognized option is present 🫶.
The effectiveness of some warnings depends on optimizations also being enabled. For example, -Wsuggest-final-types is more effective with link-time optimization, and some instances of other warnings may not be issued at all unless optimization is enabled 🔥. While optimization in general improves the efficacy of control and data flow sensitive warnings, in some cases it may also cause false positives 💀.
-Wpedantic,-pedantic— issues all the warnings demanded by strict ISO C and ISO C++, and diagnoses all programs that use forbidden extensions, plus some other programs that don't follow ISO C and ISO C++ 📏. This follows the version of the ISO C or C++ standard specified by any-stdoption used.
Valid ISO C and ISO C++ programs should compile properly with or without this option (though a rare few require -ansi or a -std option specifying the version of the standard) ✨. However, without this option, certain GNU extensions and traditional C and C++ features are supported as well. With this option, they get diagnosed, or rejected entirely with -pedantic-errors 🙅♀️.
-Wpedantic doesn't cause warning messages for use of the alternate keywords whose names begin and end with __. This alternate format can also be used to disable warnings for non-ISO __intN types, i.e. __intN__ 🎀. Pedantic warnings are also disabled in the expression that follows __extension__. However, only system header files should use these escape routes, so application programs should avoid them 🚫.
Some warnings about non-conforming programs are controlled by options other than -Wpedantic. In many cases they're implied by -Wpedantic but can be disabled separately by their specific option, e.g. -Wpedantic -Wno-pointer-sign 🧚.
Where the standard specified with -std represents a GNU extended dialect of C, such as gnu90 or gnu99, there is a corresponding base standard: the version of ISO C that the GNU extended dialect is based on. Warnings from -Wpedantic are given where the base standard requires them. (It doesn't make sense for those warnings to only be given for features outside the specified GNU C dialect, since by definition the GNU dialects of C include every feature the compiler supports with the given option, so there would be nothing to warn about 🤓.)
-pedantic-errors— okay bestie, this one is STRICT 💅 It turns the stuff the base standard (see-Wpedantic) says must be diagnosed into errors. That covers some spots with undefined behavior at compile-time, plus some other spots that won't stop a program that's valid under the standard from compiling 🫶
Heads up, this is not the same as -Werror=pedantic 👀 ngl that one is kinda pointless, since it only turns -Wpedantic diagnostics into errors. -pedantic-errors goes further and also hits the required diagnostics that are always on, or controlled by options other than -Wpedantic. Main character energy 👑
Want the required diagnostics that are warnings by default to become errors, but without turning on the -Wpedantic diagnostics? Then use -pedantic-errors -Wno-pedantic. Or -pedantic-errors -Wno-error=pedantic if you want those enabled but still just as warnings 🌸
Some required diagnostics are errors by default, but you can knock them down to warnings with -fpermissive or their own specific warning option, like -Wno-error=narrowing 🦋
Some diagnostics for non-ISO practices are controlled by specific warning options other than -Wpedantic, but -pedantic-errors makes those into errors too. For instance:
-Wattributes (for standard attributes), -Wchanges-meaning (C++), -Wcomma-subscript (C++23 or later), -Wdeclaration-after-statement (C90 or earlier), -Welaborated-enum-base (C++11 or later), -Wimplicit-int (C99 or later), -Wimplicit-function-declaration (C99 or later), -Wincompatible-pointer-types, -Wint-conversion, -Wlong-long (C90 or earlier), -Wmain, -Wnarrowing (C++11 or later), -Wpointer-arith, -Wpointer-sign, -Wincompatible-pointer-types, -Wregister (C++17 or later), -Wvla (C90 or earlier), -Wwrite-strings (C++11 or later)
-fpermissive— the chill option 🧚 It downgrades some required diagnostics about nonconformant code from errors to warnings, so yes, it lets some nonconforming code compile. Some C++ diagnostics are controlled only by this flag, and it also downgrades some C and C++ diagnostics that have their own flag:
-Wdeclaration-missing-parameter-type (C and Objective-C only), -Wimplicit-function-declaration (C and Objective-C only), -Wimplicit-int (C and Objective-C only), -Wincompatible-pointer-types (C and Objective-C only), -Wint-conversion (C and Objective-C only), -Wnarrowing (C++ and Objective-C++ only), -Wreturn-mismatch (C and Objective-C only)
-fpermissive is the default for the historic C language modes (-std=c89, -std=gnu89, -std=c90, -std=gnu90) 🕰️
-Wall— this one flags all the warnings about constructions some users find questionable, and that are easy to avoid (or easy to tweak so the warning goes away), even when macros are involved 🔥 It also turns on some language-specific warnings described in the C++ Dialect Options and the Objective-C and Objective-C++ Dialect Options sections.
-Wall turns on the following warning flags:
-Waddress, -Waligned-new (C++ and Objective-C++ only), -Warray-bounds=1 (only with -O2), -Warray-compare, -Warray-parameter=2, -Wbool-compare, -Wbool-operation, -Wc++11-compat, -Wc++14-compat, -Wc++17compat, -Wc++20compat, -Wcatch-value (C++ and Objective-C++ only), -Wchar-subscripts, -Wclass-memaccess (C++ and Objective-C++ only), -Wcomment, -Wdangling-else, -Wdangling-pointer=2, -Wdelete-non-virtual-dtor (C++ and Objective-C++ only), -Wduplicate-decl-specifier (C and Objective-C only), -Wenum-compare (in C/ObjC; this is on by default in C++), -Wenum-int-mismatch (C and Objective-C only), -Wformat=1, -Wformat-contains-nul, -Wformat-diag, -Wformat-extra-args, -Wformat-overflow=1, -Wformat-truncation=1, -Wformat-zero-length, -Wframe-address, -Wimplicit (C and Objective-C only), -Wimplicit-function-declaration (C and Objective-C only), -Wimplicit-int (C and Objective-C only), -Winfinite-recursion, -Winit-self (C++ and Objective-C++ only), -Wint-in-bool-context, -Wlogical-not-parentheses, -Wmain (only for C/ObjC and unless -ffreestanding), -Wmaybe-uninitialized, -Wmemset-elt-size, -Wmemset-transposed-args, -Wmisleading-indentation (only for C/C++), -Wmismatched-dealloc, -Wmismatched-new-delete (C++ and Objective-C++ only), -Wmissing-attributes, -Wmissing-braces (only for C/ObjC), -Wmultistatement-macros, -Wnarrowing (C++ and Objective-C++ only), -Wnonnull, -Wnonnull-compare, -Wopenmp-simd (C and C++ only), -Woverloaded-virtual=1 (C++ and Objective-C++ only), -Wpacked-not-aligned, -Wparentheses, -Wpessimizing-move (C++ and Objective-C++ only), -Wpointer-sign (only for C/ObjC), -Wrange-loop-construct (C++ and Objective-C++ only), -Wreorder (C++ and Objective-C++ only), -Wrestrict, -Wreturn-type, -Wself-move (C++ and Objective-C++ only), -Wsequence-point, -Wsign-compare (C++ and Objective-C++ only), -Wsizeof-array-div, -Wsizeof-pointer-div, -Wsizeof-pointer-memaccess, -Wstrict-aliasing, -Wstrict-overflow=1, -Wswitch, -Wtautological-compare, -Wtrigraphs, -Wuninitialized, -Wunknown-pragmas, -Wunused, -Wunused-but-set-variable, -Wunused-const-variable=1 (only for C/ObjC), -Wunused-function, -Wunused-label, -Wunused-local-typedefs, -Wunused-value, -Wunused-variable, -Wuse-after-free=2, -Wvla-parameter, -Wvolatile-register-var, -Wzero-length-bounds
Now, a fair warning 🙈 some warning flags are not implied by -Wall. Some of them flag stuff users generally don't see as questionable, but which you might occasionally want to check for. Others flag constructions that are necessary or hard to avoid in some cases, with no simple way to rewrite the code to shush the warning. Some of them are turned on by -Wextra, but lots of them have to be enabled one by one 💖
-Wextra— this turns on some extra warning flags that-Walldoesn't enable ✨ (Fun fact: this option used to be called-W. The older name still works, but-Wextrais way more descriptive, so we stan 🎀)
-Wabsolute-value (only for C/ObjC), -Walloc-size, -Wcalloc-transposed-args, -Wcast-function-type, -Wclobbered, -Wdeprecated-copy (C++ and Objective-C++ only), -Wempty-body, -Wenum-conversion (only for C/ObjC), -Wexpansion-to-defined, -Wignored-qualifiers (only for C/C++), -Wimplicit-fallthrough=3, -Wmaybe-uninitialized, -Wmissing-field-initializers, -Wmissing-parameter-type (C/ObjC only), -Wold-style-declaration (C/ObjC only), -Woverride-init (C/ObjC only), -Wredundant-move (C++ and Objective-C++ only), -Wshift-negative-value (in C++11 to C++17 and in C99 and newer), -Wsign-compare (C++ and Objective-C++ only), -Wsized-deallocation (C++ and Objective-C++ only), -Wstring-compare, -Wtype-limits, -Wuninitialized, -Wunused-parameter (only with -Wunused or -Wall), -Wunused-but-set-parameter (only with -Wunused or -Wall)
-Wextra also prints warning messages for these cases too 👀
- A pointer is compared against integer zero with
<,<=,>, or>=. - (C++ only) An enumerator and a non-enumerator both appear in a conditional expression.
- (C++ only) Ambiguous virtual bases.
- (C++ only) Subscripting an array that has been declared
register. - (C++ only) Taking the address of a variable that has been declared
register. - (C++ only) A base class is not initialized in the copy constructor of a derived class.
-Wabi(C, Objective-C, C++ and Objective-C++ only) — okay this one is about ABI drama 🧐 It warns about code affected by ABI changes, which includes code that might not be compatible with the vendor-neutral C++ ABI, as well as the psABI for the particular target.
Since G++ now defaults to updating the ABI with each major release, -Wabi normally only warns about C++ ABI compatibility problems if a check got added later in a release series for an ABI issue found after the initial release. It warns about more things if an older ABI version is selected with -fabi-version=n 💅
-Wabi can also take an explicit version number, to warn about C++ ABI compatibility with a particular -fabi-version level. For example, -Wabi=2 warns about changes relative to -fabi-version=2.
If an explicit version number is provided and -fabi-compat-version is not specified, the version number from this option gets used for compatibility aliases. If no explicit version number is given with this option, but -fabi-compat-version is specified, that version number is used for C++ ABI warnings 🌈
Now, real talk no check is perfect 🥺 Although an effort has been made to warn about all such cases, there are probably some that go unwarned, even though G++ is generating incompatible code. There may also be cases where warnings fire even though the generated code is actually compatible.
If you're worried that G++ code might not be binary compatible with code from other compilers, you should rewrite your code to avoid these warnings 🫶
Known incompatibilities in -fabi-version=2 (which was the default from GCC 3.4 to 4.9) include:
- A template with a non-type template parameter of reference type was mangled incorrectly:
extern int N;
template <int &> struct S {};
void n (S<N>) {2}This was fixed in -fabi-version=3.
- SIMD vector types declared using
__attribute ((vector_size))were mangled in a non-standard way that doesn't allow for overloading of functions taking vectors of different sizes.
The mangling was changed in -fabi-version=4.
__attribute ((const))andnoreturnwere mangled as type qualifiers, anddecltypeof a plain declaration got folded away.
These mangling issues were fixed in -fabi-version=5.
- Scoped enumerators passed as arguments to a variadic function get promoted like unscoped enumerators, causing
va_argto complain. On most targets this doesn't actually affect the parameter passing ABI, since there's no way to pass an argument smaller thanint. The ABI also changed the mangling of template argument packs,const_cast,static_cast, prefix increment/decrement, and a class scope function used as a template argument.
These issues were corrected in -fabi-version=6.
- Lambdas in default argument scope were mangled incorrectly, and the ABI changed the mangling of
nullptr_t.
These issues were corrected in -fabi-version=7. 💖
- When mangling a function type that has function-cv-qualifiers, the un-qualified function type was wrongly counted as a substitution candidate 😭. This was fixed in
-fabi-version=8, the default for GCC 5.1 💅. decltype(nullptr)had an alignment of 1, which led to unaligned accesses 🙈. It didn't change the ABI of a function with anullptr_tparameter, since parameters already get a minimum alignment 🫶. This was fixed in-fabi-version=9, the default for GCC 5.2 🔥.- Target-specific attributes that change what a type is, like ia32 calling conventions on a function type (
stdcall,regparm, etc.), weren't reflected in the mangled name 💀. That caused name collisions whenever function pointers were used as template arguments. This was fixed in-fabi-version=10, the default for GCC 6.1 👑. - For SysV/x86-64, unions with
long doublemembers are passed in memory, as the psABI specifies 🧚. Before GCC 4.4 that wasn't the case. For example:
union U {
long double ld;
int i;
};union U is now always passed in memory 🦋.
-Wno-changes-meaning(C++ and Objective-C++ only) — C++ wants unqualified uses of a name inside a class to mean the same thing across the whole class scope, so using a name first and declaring it later is ill-formed 🙅♀️:
struct A;
struct B1 { A a; typedef A A; }; // warning, 'A' changes meaning
struct B2 { A a; struct A { }; }; // error, 'A' changes meaningBy default the B1 case is only a warning, because both declarations have the same type. The B2 case is an error. Both diagnostics can be turned off with -Wno-changes-meaning. If you'd rather the error be a warning, use -Wno-error=changes-meaning or -fpermissive ✨. Both diagnostics are also suppressed by -fms-extensions 🌸.
-Wchar-subscripts— warns if an array subscript has typechar🍓. This is a super common mistake, since people forget thatcharis signed on some machines. This warning is enabled by-Wall💜.-Wno-coverage-mismatch— warns if feedback profiles don't match when you use-fprofile-use🔍. If a source file changes between-fprofile-generateand-fprofile-use, the profile feedback files can stop matching the source, and GCC can't use the feedback info. By default this warning is on and treated as an error. Use-Wno-coverage-mismatchto silence the warning, or-Wno-error=coverage-mismatchto silence the error.
Turning off the error can lead to poorly optimized code. It's only really useful for very minor changes, like bug fixes in an existing code-base. Completely disabling the warning is not recommended 🙃.
-Wno-coverage-too-many-conditions— warns if-fcondition-coverageis used and an expression has too many terms, so GCC gives up on coverage 🥺. Coverage is given up when the conditional has more terms than there are bits in agcov_type_unsigned. This warning is enabled by default 🌈.-Wno-coverage-invalid-line-number— warns if a function ends before it begins because of invalid linenum macros 🤯. The warning is only emitted when--coverageis enabled.
By default this warning is enabled and treated as an error. -Wno-coverage-invalid-line-number disables the warning, and -Wno-error=coverage-invalid-line-number disables the error 🫠.
-Wno-cpp(C, Objective-C, C++, Objective-C++ and Fortran only) — silences the warnings that#warningdirectives spit out 🤫.-Wdouble-promotion(C, C++, Objective-C and Objective-C++ only) — warns when afloatvalue gets implicitly promoted todouble📈. CPUs with a 32-bit single-precision floating-point unit dofloatin hardware but emulatedoublein software. So doing math withdoubleon those machines is way more expensive because of the emulation overhead 🐢.
It's super easy to accidentally do math in double, because floating-point literals are implicitly double 😩. For example:
float area(float radius)
{
return 3.14159 * radius * radius;
}The compiler does the whole computation in double, because the floating-point literal is a double 💀.
-Wduplicate-decl-specifier(C and Objective-C only) — warns if a declaration has a duplicateconst,volatile,restrictor_Atomicspecifier 🧁. This warning is enabled by-Wall💅.-Wformat,-Wformat=n— checks calls toprintfandscanf(and friends) 🖨️. It makes sure the arguments match the types the format string expects, and that the conversions in the format string actually make sense 🧐. This covers standard functions plus anything else marked with format attributes, in theprintf,scanf,strftimeandstrfmonfamilies (strfmonis an X/Open extension and isn't in the C standard), or other target-specific families 🌷. Which functions get checked without a format attribute depends on the standard version you picked. Those checks are turned off by-ffreestandingor-fno-builtin🚫.
The formats are checked against the features in GNU libc version 2.2 ✨. That includes all of ISO C90 and C99, plus stuff from the Single Unix Specification and some BSD and GNU extensions. Other library implementations might not support all of these, and GCC won't warn about features that go beyond a particular library's limits 🫶. But if you use -Wpedantic together with -Wformat, you'll get warnings about format features that aren't in the standard version you selected. That doesn't apply to strfmon formats, since those aren't in any version of the C standard 🙈.
-Wformat=1,-Wformat—-Wformatis the same as-Wformat=1, and-Wno-formatis the same as-Wformat=0🎀. Since-Wformatalso checks for null format arguments in several functions, it implies-Wnonnulltoo 💖. Some parts of this level of checking can be turned off with-Wno-format-contains-nul,-Wno-format-extra-args, and-Wno-format-zero-length.-Wformatis enabled by-Wall🌸.-Wformat=2— turns on-Wformatplus extra format checks 🔥. Right now it's the same as-Wformat -Wformat-nonliteral -Wformat-security -Wformat-y2k👑.
-Wno-format-contains-nul— if-Wformatis on, don't warn about format strings that contain NUL bytes 🙅♀️.-Wno-format-extra-args— if-Wformatis on, don't warn about extra arguments passed to aprintforscanfformat function 🦋. The C standard says those extra arguments are just ignored 🫠.
If the unused arguments sit between used arguments that are given with $ operand number specifications, warnings still come out by default. That's because the compiler can't know what type to pass to va_arg to skip the unused ones 😵💫. For scanf formats, though, this option does suppress the warning when all the unused arguments are pointers. The Single Unix Specification says those unused pointer arguments are allowed 🧚.
-Wformat-overflow,-Wformat-overflow=level— warns about calls to formatted output functions likesprintfandvsprintfthat might overflow the destination buffer 💥. If the exact number of bytes a format directive writes can't be figured out at compile time, GCC estimates it with heuristics. Those depend on thelevelargument and on optimization. Turning on optimization usually makes the warning more accurate, but it can also cause false positives 🙃.-Wformat-overflow,-Wformat-overflow=1— level 1 is enabled by-Wformatand takes a conservative approach 🧸. It only warns about calls that will most likely overflow the buffer. At this level, numeric arguments with unknown values are assumed to be one, and strings of unknown length are assumed to be empty 🌱. Numeric arguments known to be bounded to a subrange of their type, or string arguments whose output is bounded by the directive's precision or by a finite set of string literals, are assumed to take whatever value in their range produces the most bytes of output 📏. For example, this call tosprintfgets flagged. Even with bothaandbequal to zero, the terminating NUL character ('\0') that the function appends to the destination buffer gets written past its end 😱. Making the buffer one byte bigger is enough to dodge the warning, though it might not be enough to actually avoid the overflow 🙈.
void f (int a, int b)
{
char buf [13];
sprintf (buf, "a = %i, b = %i\n", a, b);
}-Wformat-overflow=2— level 2 warns about calls that might overflow the destination buffer if an argument is long enough or large enough in magnitude 📣. At level 2, unknown numeric arguments are assumed to have the minimum representable value for signed types with a precision greater than 1, and the maximum representable value otherwise 🔢. Unknown string arguments whose length can't be assumed bounded, either by the directive's precision, by a finite set of string literals they might evaluate to, or by the character array they may point to, are assumed to be 1 character long 🧩.
Okay so we're picking up right where that sprintf example left off 😭🎀 At level 2, that same call gets flagged again, but this time it's because if a is equal to a 32-bit INT_MIN, the first %i directive will write some of its digits past the end of the destination buffer 💀. To make the call safe no matter what the two variables hold, the destination buffer has to be at least 34 bytes. GCC even drops the minimum buffer size into an informational note right after the warning, so you don't have to do the math yourself 💅
If resizing the buffer isn't your vibe, you can limit the range of the formatted values instead ✨ You can cap the maximum length of string arguments by putting a precision in the format directive. And if you can assume numeric arguments are bounded by less than the precision of their type, picking an appropriate length modifier for the format specifier will shrink the buffer you need. For example, if a and b in the example above are guaranteed to be within the precision of the short int type, then either using the %hi format directive or casting the argument to short drops the maximum required size of the buffer to 24 bytes 🦋
void f (int a, int b)
{
char buf [23];
sprintf (buf, "a = %hi, b = %i\n", a, (short)b);
}-Wno-format-zero-length— Okay, so if-Wformatis on, this tells GCC to chill and not warn about zero-length formats 🌸 The C standard says zero-length formats are totally allowed, so no drama needed.-Wformat-nonliteral— If-Wformatis on, GCC will also warn when the format string isn't a string literal, since it can't check that kind of format 👀. The exception is when the format function takes its format arguments as ava_list.-Wformat-security— If-Wformatis on, this one also flags format function calls that could be a security problem 🔥. Right now it warns aboutprintfandscanfcalls where the format string isn't a string literal and there are no format arguments, likeprintf (foo);. That's a potential security hole if the format string came from untrusted input and contains%n. (This is currently a subset of what-Wformat-nonliteralwarns about, but future warnings may be added to-Wformat-securitythat aren't included in-Wformat-nonliteral.)-Wformat-signedness— If-Wformatis on, this warns when the format string wants an unsigned argument but you pass a signed one, and vice versa 🌈-Wformat-truncation,-Wformat-truncation=level— Okay this one is giving output truncation drama 💅 It warns about calls to formatted input/output functions likesnprintfandvsnprintfthat might cut off the output. When GCC can't figure out the exact number of bytes a format directive writes at compile time, it guesses using heuristics that depend on the level argument and on optimization. Turning on optimization usually makes the warning more accurate, but it can also cause false positives ⚠️. Unless noted otherwise, this option uses the same logic as-Wformat-overflow.-Wformat-truncationor-Wformat-truncation=1— Level 1 is enabled by-Wformatand is the conservative option 🧁. It only warns about calls to bounded functions whose return value is unused and that will most likely truncate the output.-Wformat-truncation=2— Level 2 is spicier and also warns about bounded functions whose return value is used, if they might truncate given an argument of big enough length or magnitude 🔥.
-Wformat-y2k— If-Wformatis on, this warns aboutstrftimeformats that might only give you a two-digit year 📅-Wnonnull— Warns when you pass a null pointer to an argument that thenonnullfunction attribute says must be non-null 🚫.-Wnonnullis included in-Walland-Wformat, and you can turn it off with-Wno-nonnull.-Wnonnull-compare— Warns when you compare an argument marked with thenonnullfunction attribute against null inside the function 🙈. It's included in-Wall, and you can disable it with-Wno-nonnull-compare.-Wnull-dereference— Warns if the compiler finds paths that trigger erroneous or undefined behavior from dereferencing a null pointer 💀. This only works when-fdelete-null-pointer-checksis active, which optimizations enable on most targets. How precise the warnings are depends on the optimization options you use.-Wnrvo(C++ and Objective-C++ only) — Warns if the compiler doesn't elide the copy from a local variable to the return value, even though[class.copy.elision]allows it 💖. This is commonly called the Named Return Value Optimization. In the example below, the compiler can't elide copies from bothv1andv2, so it doesn't elide either one.
std::vector<int> f()
{
std::vector<int> v1, v2;
// ...
if (cond) return v1;
else return v2; // warning: not eliding copy
}-Winfinite-recursion— Warns about infinitely recursive calls 🔁. It works at all optimization levels, but you need optimization to catch infinite recursion across two or more functions. It's included in-Wall.
Compare this with -Wanalyzer-infinite-recursion, which gives a similar diagnostic but is implemented differently (as part of -fanalyzer).
-Winit-self(C, C++, Objective-C and Objective-C++ only) — Warns about uninitialized variables that get initialized with themselves 🪞. This option can only be used together with-Wuninitialized.
In the following snippet, GCC warns about i being uninitialized only when -Winit-self is specified:
int f()
{
int i = i;
return i;
}This warning is enabled by -Wall in C++.
-Wno-implicit-int(C and Objective-C only) — This controls warnings when a declaration doesn't specify a type 🤔. It's enabled by default as an error in C99 and later C dialects, and also by-Wall. You can downgrade the error to a warning with-fpermissive(along with certain other errors), or for this error alone with-Wno-error=implicit-int.
This warning gets upgraded to an error by -pedantic-errors.
-Wno-implicit-function-declaration(C and Objective-C only) — This controls warnings when a function is used before it's declared 📣. It's enabled by default as an error in C99 and later C dialects, and also by-Wall. You can downgrade the error to a warning with-fpermissive(along with certain other errors), or for this error alone with-Wno-error=implicit-function-declaration.
This warning gets upgraded to an error by -pedantic-errors.
-Wimplicit(C and Objective-C only) — Same as-Wimplicit-intand-Wimplicit-function-declarationcombined 🧩. This warning is enabled by-Wall.-Whardened— Warns when-fhardeneddidn't enable an option from its set (see-fhardenedfor the full list) 🛡️. For instance, if you use-fhardenedand-fstack-protectorat the same time on the command line,-Whardenedwarns because-fstack-protector-strongisn't enabled by-fhardened.
This warning is enabled by default and only has an effect when -fhardened is enabled.
-Wimplicit-fallthrough— This is the same as-Wimplicit-fallthrough=3, and-Wno-implicit-fallthroughis the same as-Wimplicit-fallthrough=0😌.-Wimplicit-fallthrough=n— Warns when a switch case falls through 🍓. For example:
switch (cond)
{
case 1:
a = 1;
break;
case 2:
a = 2;
case 3:
a = 3;
break;
}This warning doesn't fire when the last statement of a case can't fall through, like when there's a return statement or a call to a function declared with the noreturn attribute 🙌. -Wimplicit-fallthrough= also takes control flow statements, like ifs, into account, and only warns when it's actually appropriate. For example:
switch (cond)
{
case 1:
if (i > 3) {
bar (5);
break;
} else if (i < 1) {
bar (0);
} else
return;
default:
...
}Sometimes a fallthrough is exactly what you want, so GCC gives you an attribute, __attribute__ ((fallthrough)), to use along with a null statement to suppress the warning that would otherwise show up 🧚:
switch (cond)
{
case 1:
bar (0);
__attribute__ ((fallthrough));
default:
...
}C++17 has a standard way to suppress -Wimplicit-fallthrough using [[fallthrough]]; instead of the GNU attribute ✨. In C++11 or C++14, you can use [[gnu::fallthrough]];, which is a GNU extension. Instead of these attributes, you can also add a fallthrough comment to silence the warning 💬. The whole body of the C or C++ style comment has to match the regular expressions listed below. The option argument n decides what kinds of comments are accepted:
-Wimplicit-fallthrough=0disables the warning altogether 🚫.-Wimplicit-fallthrough=1matches the".*"regular expression, so any comment counts as a fallthrough comment 🫶.-Wimplicit-fallthrough=2case insensitively matches the".*falls?[ \t-]*thr(ough|u).*"regular expression 🌸.-Wimplicit-fallthrough=3case sensitively matches one of the following regular expressions:
okay so -Wimplicit-fallthrough=3 is the pickiest level 💅 the comment has to match one of these patterns, and GCC checks them exactly like this 🔍
*<"-fallthrough">
*<"@fallthrough@">
*<"lint -fallthrough[ \t]*">
*<"[ \t.!]*(ELSE,? |INTENTIONAL(LY)? )?FALL(S | |-)?THR(OUGH|U)[
\t.!]*(-[^\n\r]*)?">
*<"[ \t.!]*(Else,? |Intentional(ly)? )?Fall((s |
|-)[Tt]|t)hr(ough|u)[ \t.!]*(-[^\n\r]*)?">
*<"[ \t.!]*([Ee]lse,? |[Ii]ntentional(ly)? )?fall(s |
|-)?thr(ough|u)[ \t.!]*(-[^\n\r]*)?">-Wimplicit-fallthrough=4 is a bit more chill 🌸 it matches case sensitively against this shorter list:
*<"-fallthrough">
*<"@fallthrough@">
*<"lint -fallthrough[ \t]*">
*<"[ \t]*FALLTHR(OUGH|U)[ \t]*">-Wimplicit-fallthrough=5 doesn't recognize any comments as fallthrough comments at all 💀 only attributes can turn the warning off, so no comment-based escape hatch for you, bestie 🙈
The comment also needs to sit right before case or default, with only whitespace and other comments in between, or before a user label that comes right before a case or default label ✨ like this:
switch (cond)
{
case 1:
bar (0);
/* FALLTHRU */
default:
...
}The -Wimplicit-fallthrough=3 warning is turned on by -Wextra 🔥
🎀 -Wno-if-not-aligned (C, C++, Objective-C and Objective-C++ only)
This one controls whether warnings triggered by the warn_if_not_aligned attribute get issued 🦋 they're on by default, so you have to actively turn them off with -Wno-if-not-aligned if you don't want them.
🌈 -Wignored-qualifiers (C and C++ only)
Warns if a function's return type has a type qualifier like const ✨ in ISO C that qualifier does nothing, since the returned value isn't an lvalue, so it's giving "pointless" 😭 For C++, the warning only shows up for scalar types or void. ISO C doesn't allow qualified void return types on function definitions, so those always get a warning even without this option, no cap.
This warning is also turned on by -Wextra.
💜 -Wno-ignored-attributes (C and C++ only)
This controls warnings for when an attribute gets ignored 👑 it's different from -Wattributes, which is about attributes being unknown or used in the wrong place. This one fires whenever the compiler decides to drop an attribute. It's on by default.
👑 -Wmain
Warns if the type of main looks suspicious 👀 main should be a function with external linkage that returns int and takes either zero arguments, two, or three arguments of the right types. This is on by default in C++, and it's turned on by either -Wall or -Wpedantic.
⚠️ -pedantic-errors upgrades this warning into an error, so it stops being just a warning, bestie 😱
🧚 -Wmisleading-indentation (C and C++ only)
Warns when the indentation doesn't match the real block structure 🙈 specifically, it fires for if, else, while, and for clauses that have a guarded statement without braces, followed by an unguarded statement at the same indentation level. Gotcha energy 💀
In this example, bar is misleadingly indented like it's guarded by the if, but it isn't:
if (some_condition ())
foo ();
bar (); /* Gotcha: this is not guarded by the "if". */If you mix tabs and spaces, the warning uses -ftabstop= to figure out whether the statements actually line up, and it defaults to 8 🍓
It won't warn about code with multiline preprocessor logic like this one 🌸
if (flagA)
foo (0);
#if SOME_CONDITION_THAT_DOES_NOT_HOLD
if (flagB)
#endif
foo (1);It also skips anything after a #line directive 🧚 that usually means the code was autogenerated, and nobody can assume anything about the file layout that the directive points to.
This warning is turned on by -Wall in C and C++ ✨
🦋 -Wmissing-attributes
Warns when a function declaration is missing one or more attributes that a related function is declared with 🔍 this matters because leaving them out can hurt correctness or efficiency of the generated code. For example, it fires for declarations of aliases that use attributes to set less restrictive requirements than their targets. That usually means a potential optimization opportunity 💖
The option -Wattribute-alias=2 is kind of the opposite 🙃 it warns when an alias is more restrictive than its target, which could lead to incorrect code generation. The attributes considered here include "alloc_align", "alloc_size", "cold", "const", "hot", "leaf", "malloc", "nonnull", "noreturn", "nothrow", "pure", "returns_nonnull", and "returns_twice".
In C++, the warning fires when an explicit specialization of a primary template is declared without an attribute that the primary template has. The attributes that count are "alloc_align", "alloc_size", "assume_aligned", "format", "format_arg", "malloc", or "nonnull". The attributes "deprecated", "error", and "warning" suppress the warning..
You can use the "copy" attribute to apply the same set of attributes to a declaration as another declaration has, without listing them all out 🫶 it works on declarations of functions, variables, or types.
-Wmissing-attributes is turned on by -Wall 🔥
For example, the primary function template below uses both "malloc" and "alloc_size", so the explicit specialization gets flagged because it's missing one of them 👀
template <class T>
T* __attribute__ ((malloc, alloc_size (1)))
allocate (size_t);
template <>
void* __attribute__ ((malloc)) // missing alloc_size
allocate<void> (size_t);🌸 -Wmissing-braces
Warns if an aggregate or union initializer isn't fully bracketed 💅 in this example, the initializer for a isn't fully bracketed, but the one for b is.
int a[2][2] = { 0, 1, 2, 3 };
int b[2][2] = { { 0, 1 }, { 2, 3 } };This warning is turned on by -Wall ✨
🎀 -Wmissing-include-dirs (C, C++, Objective-C, Objective-C++ and Fortran only)
Warns if a user-supplied include directory doesn't exist 📂 this option is disabled by default for C, C++, Objective-C, and Objective-C++. For Fortran, it's partially on by default, but only for -I and -J 💖
🫧 -Wno-missing-profile
This controls warnings about missing feedback profiles when you use -fprofile-use 📊 it catches cases where a new function or a new file got added between compiling with -fprofile-generate and -fprofile-use, without regenerating the profiles. In those cases, the profile feedback data files don't have any info for the new function or file, bestie.
Also, if profile count data (.gcda) files get removed, GCC can't use any profile feedback information at all 😭 in every one of these cases, you get warnings reminding you that a profile generation step is due. Ignoring them can give you poorly optimized code, so be careful 🙈
-Wno-missing-profile turns the warning off, but it's not recommended 🚫 only do it when the missing profile data is actually justified.
💀 -Wmismatched-dealloc
Warns about calls to deallocation functions with pointer arguments that came from allocation functions the deallocator doesn't match 🧠 you can pair up matching allocators and deallocators with the malloc attribute. Unless -fno-builtin turns it off, the standard functions "calloc", "malloc", "realloc", and "free", plus the C++ "operator new" and "operator delete" forms, are implicitly matched up already ✨
In this example, mydealloc is the deallocator for pointers returned by myalloc 🍓
void mydealloc (void*);
__attribute__ ((malloc (mydealloc, 1))) void*
myalloc (size_t);
void f (void)
{
void *p = myalloc (32);
// ...use p...
free (p); // warning: not a matching deallocator for myalloc
mydealloc (p); // ok
}In C++, the related option -Wmismatched-new-delete catches mismatches involving either "operator new" or "operator delete" 💜
-Wmismatched-dealloc is included in -Wall 👑
🌈 -Wmultistatement-macros
Warns about unsafe multi-statement macros that look guarded by a clause like if, else, for, switch, or while 😬 the problem is that after the macro expands, only the first statement is actually guarded.
For example:
#define DOIT x++; y++
if (c)
DOIT;This increments y unconditionally, not just when c holds 💀 It can usually be fixed by wrapping the macro in a do-while loop:
#define DOIT do { x++; y++; } while (0)
if (c)
DOIT;This warning is turned on by -Wall in C and C++ 🫶
🧠 -Wparentheses
Warns when parentheses are left out in certain spots 🔍 like when there's an assignment where a truth value is expected, or when nested operators have precedence that people often mix up.
It also warns if a comparison like x<=y<=z shows up 👀 that's equivalent to (x<=y ? 1 : 0) <= z, which is a different reading from ordinary math notation, so it's giving confusing 😭
It also warns about dangerous uses of the GNU extension to ?: with the middle operand omitted 🙈 when the condition is a boolean expression, the omitted value is always 1. Programmers often expect it to be a value computed inside the conditional expression instead.
For C++, this also warns about some unnecessary parentheses in declarations, which can mean you meant a function call instead of a declaration 💖
{
// Declares a local variable called mymutex.
std::unique_lock<std::mutex> (mymutex);
// User meant std::unique_lock<std::mutex> lock (mymutex);
}This warning is turned on by -Wall 🎀
-Wno-self-move(C++ and Objective-C++ only) — okay bestie 🫶 this one screams when youstd::movea value into itself. That usually does absolutely nothing, so it's lowkey a red flag 🚩. Here's the sus code:
struct T {
...
};
void fn()
{
T t;
...
t = std::move (t);
}This warning is enabled by -Wall 💅
-Wsequence-point— ohhh this one is the drama queen 👑 It warns about code that might have undefined semantics because it breaks the sequence point rules in the C and C++ standards. Sequence points are like little checkpoints where the program has finished certain stuff. They happen after a full expression finishes (one that isn't part of a bigger expression), after the first operand of&&,||,? :or,(comma) operator gets evaluated, before a function is called (but after its arguments and the expression naming the called function are evaluated), and in a few other spots. Outside those checkpoints, the order that subexpressions get evaluated is not specified 🤷♀️ The rules only give a partial order, not a total one. For example, if two functions get called in one expression with no sequence point between them, the order they run in is not specified. The standards committee did rule that function calls don't overlap though 🌸
It's also not specified when, between sequence points, changes to object values take effect. Programs that depend on that have undefined behavior. The standards basically say that between two sequence points, an object can only have its stored value changed once, and the old value can only be read to figure out the new value being stored.
💀 If a program breaks these rules, the results on any particular implementation are entirely unpredictable. Not a vibe.
Examples of undefined-behavior code are a = a++;, a[n] = b[n++] and a[i++] = i;. Some more complicated cases aren't diagnosed by this option, and it may give an occasional false positive, but overall it's been found pretty effective at catching this sort of problem 🔍
C++17 is going to define the order of evaluation of operands in more cases. In particular, it requires the right-hand side of an assignment to be evaluated before the left-hand side, so the examples above are no longer undefined. But this option will still warn about them, to help people avoid writing code that's undefined in C and earlier revisions of C++ 🧚
The standard is worded confusingly, so there's some debate over the precise meaning of the sequence point rules in subtle cases. Links to discussions of the problem, including proposed formal definitions, can be found on the GCC readings page at <https://gcc.gnu.org/readings.html> 📚
This warning is enabled by -Wall for C and C++ 🎀
-Wno-return-local-addr— bestie, this one turns off the warning for returning a pointer (or a reference, in C++) to a variable that goes out of scope once the function returns 🦋-Wreturn-mismatch— this one checks yourreturnstatements 🧐 It warns aboutreturnstatements without an expression in functions that don't returnvoid. It also warns about areturnwith an expression in avoidfunction, unless the expression's type is alsovoid. As a GNU extension, that last case is accepted without a warning unless-Wpedanticis used.
⚠️ Trying to use the return value of a non-voidfunction other thanmainthat flows off the end by reaching the closing curly brace that ends the function is undefined. Yikes 😭
This warning is specific to C and enabled by default. In C99 and later dialects it's treated as an error 💀 If you want to downgrade it to a warning, you can use -fpermissive (which also downgrades other warnings), or just this one with -Wno-error=return-mismatch 🌈
-Wreturn-type— warns whenever a function is defined with a return type that defaults toint(unless-Wimplicit-intis active, which takes precedence). It also warns if execution may reach the end of the function body, or if the function doesn't contain anyreturnstatement at all 👀
⚠️ Trying to use the return value of a non-voidfunction other thanmainthat flows off the end by reaching the closing curly brace that ends the function is undefined.
Unlike in C, in C++, flowing off the end of a non-void function other than main results in undefined behavior even when the value of the function isn't used. Scary stuff 😱
This warning is enabled by default in C++ and by -Wall otherwise ✨
-Wno-shift-count-negative— controls warnings if a shift count is negative. This warning is enabled by default 🫶-Wno-shift-count-overflow— controls warnings if a shift count is greater than or equal to the bit width of the type. This warning is enabled by default 💖-Wshift-negative-value— warns if you left shift a negative value. This warning is enabled by-Wextrain C99 (and newer) and C++11 to C++17 modes 🍓-Wno-shift-overflow,-Wshift-overflow=n— these options control warnings about left shift overflows 🌊-Wshift-overflow=1— this is the warning level of-Wshift-overflowand is enabled by default in C99 and C++11 modes (and newer). This level does not warn about left-shifting1into the sign bit. (However, in C, such an overflow is still rejected in contexts where an integer constant expression is required.) No warning is emitted in C++20 mode (and newer), since signed left shifts always wrap 🧚-Wshift-overflow=2— this warning level also warns about left-shifting1into the sign bit, unless C++14 mode (or newer) is active 🔥
-Wswitch— warns whenever aswitchstatement has an index of enumerated type and lacks acasefor one or more of the named codes of that enumeration. (Having adefaultlabel prevents this warning.)caselabels outside the enumeration range also trigger warnings when this option is used, even if there's adefaultlabel. This warning is enabled by-Wall🎀-Wswitch-default— warns whenever aswitchstatement doesn't have adefaultcase 🌸-Wswitch-enum— the same vibe as-Wswitch, withcaselabels outside the enumeration range also provoking warnings. The only real difference is that this one warns about an omitted enumeration code even when there's adefaultlabel 💅-Wno-switch-bool— don't warn when aswitchstatement has an index of boolean type and the case values are outside the range of a boolean type. You can suppress this warning by casting the controlling expression to a type other thanbool. For example:
switch ((int) (a == 4))
{
...
}This warning is enabled by default for C and C++ programs 🦋
-Wno-switch-outside-range— controls warnings when aswitchcasehas a value outside its respective type range. This warning is enabled by default for C and C++ programs 🌈-Wno-switch-unreachable— don't warn when aswitchstatement contains statements between the controlling expression and the firstcaselabel, since those will never be executed. For example:
switch (cond)
{
i = 15;
...
case 5:
...
}-Wswitch-unreachable does not warn if the statement between the controlling expression and the first case label is just a declaration:
switch (cond)
{
int i;
...
case 5:
i = 5;
...
}This warning is enabled by default for C and C++ programs 🙈
-Wsync-nand(C and C++ only) — warns when the__sync_fetch_and_nandand__sync_nand_and_fetchbuilt-in functions are used. These functions changed semantics in GCC 4.4 ⭐-Wtrivial-auto-var-init— warns when-ftrivial-auto-var-initcan't initialize an automatic variable. A common situation is an automatic variable declared between the controlling expression and the firstcaselabel of aswitchstatement 🧁
-Wunused-but-set-parameter— warns whenever a function parameter is assigned to but otherwise unused (aside from its declaration). To suppress this warning, use theunusedattribute. This warning is also enabled by-Wunusedtogether with-Wextra🌷-Wunused-but-set-variable— warns whenever a local variable is assigned to but otherwise unused (aside from its declaration). This warning is enabled by-Wall. To suppress it, use theunusedattribute. It's also enabled by-Wunused, which is enabled by-Wall💜-Wunused-function— warns whenever astaticfunction is declared but not defined, or when a non-inlinestaticfunction is unused. This warning is enabled by-Wall🌸-Wunused-label— warns whenever a label is declared but not used. This warning is enabled by-Wall. To suppress it, use theunusedattribute 🍓-Wunused-local-typedefs(C, Objective-C, C++ and Objective-C++ only) — warns when atypedeflocally defined in a function is not used. This warning is enabled by-Wall🫶-Wunused-parameter— warns whenever a function parameter is unused aside from its declaration. This option is not enabled by-Wunusedunless-Wextrais also specified. To suppress this warning, use theunusedattribute ✨-Wno-unused-result— don't warn if a caller of a function marked with the attributewarn_unused_resultdoesn't use its return value. The default is-Wunused-result👑-Wunused-variable— okay bestie, this one sounds the alarm whenever a local or static variable is just sitting there doing nothing except its declaration 💀. This option implies-Wunused-const-variable=1for C, but not for C++ 🙅♀️. It's enabled by-Wall✨. To shush this warning, slap the"unused"attribute on it 💅.-Wunused-const-variable,-Wunused-const-variable=n— the sequel 🎬. This warns whenever a constant static variable is unused aside from its declaration 🌸. To suppress it, use the"unused"attribute 🫶.-Wunused-const-variable=1— warns about unused static const variables defined in the main compilation unit, but NOT about static const variables declared in any header that gets included 🧚. It's enabled by either-Wunused-variableor-Wunusedfor C, but not for C++. In C this declares variable storage, but in C++ it isn't an error, since const variables take the place of"#define"s 🤷♀️.-Wunused-const-variable=2— this level also warns about unused constant static variables in headers (excluding system headers) 📚. It's equivalent to the short form-Wunused-const-variable. You have to explicitly request this level in both C and C++, because it might be hard to clean up all the headers you've included 😭.
-Wunused-value— warns whenever a statement computes a result that's explicitly not used 🧐. To suppress it, cast the unused expression to"void"🫶. It catches an expression-statement, or the left-hand side of a comma expression, that contains no side effects. For example, an expression such asx[i,j]causes a warning, whilex[(void)i,j]does not 👀. This warning is enabled by-Wall🌈.-Wunused— the combo meal 🍟. It's all the above-Wunusedoptions combined, except the ones documented as needing to be specified explicitly 🍓. If you want a warning about an unused function parameter, you must either specify-Wextra -Wunused(note that-Wallimplies-Wunused), or separately specify-Wunused-parameterand/or-Wunused-but-set-parameter🎀.-Wunusedenables only-Wunused-const-variable=1rather than-Wunused-const-variable, and only for C, not C++ 🙅♀️.-Wuse-after-free,-Wuse-after-free=n— only for C, Objective-C, C++ and Objective-C++ 🦋. This one warns about uses of pointers to dynamically allocated objects that have been made indeterminate by a call to a deallocation function 💀. It's enabled at all optimization levels, but it may give different results with optimization than without ⚠️.-Wuse-after-free=1— at level 1, the warning only tries to diagnose unconditional uses of pointers made indeterminate by a deallocation call or a successful call to"realloc", regardless of whether that call actually resulted in a reallocation of memory 🧠. This includes double-"free"calls, as well as uses in arithmetic and relational expressions. Although undefined, uses of indeterminate pointers in equality (or inequality) expressions are not diagnosed at this level 🙈.-Wuse-after-free=2— at level 2, on top of unconditional uses, the warning also diagnoses conditional uses of pointers made indeterminate by a deallocation call. As at level 2, uses in equality (or inequality) expressions are not diagnosed. For example, the second call to"free"in the following function is diagnosed at this level 👑:
struct A { int refcount; void *data; };
void release (struct A *p)
{
int refcount = --p->refcount;
free (p);
if (refcount == 0)
free (p->data); // warning: p may be used after free
}-Wuse-after-free=3— at level 3, the warning also diagnoses uses of indeterminate pointers in equality expressions 🔥. All uses of indeterminate pointers are undefined, but equality tests sometimes show up after calls to"realloc"as an attempt to figure out whether the call relocated the object to a different address 🤔. They get their own level so legacy code can gradually transition to safe alternatives 🌱. For example, the equality test in the function below is diagnosed at this level:
void adjust_pointers (int**, int);
void grow (int **p, int n)
{
int **q = (int**)realloc (p, n *= 2);
if (q == p)
return;
adjust_pointers ((int**)q, n);
}To avoid the warning at this level, store offsets into allocated memory instead of pointers 🧚♀️. That obviates needing to adjust the stored pointers after reallocation ✨. -Wuse-after-free=2 is included in -Wall 💅.
-Wuseless-cast— only for C, Objective-C, C++ and Objective-C++ 🙄. It warns when an expression is cast to its own type. It does not occur when a class object is converted to a non-reference type, because that's a way to create a temporary 🧃:
struct S { };
void g (S&&);
void f (S&& arg)
{
g (S(arg)); // make arg prvalue so that it can bind to S&&
}-Wuninitialized— warns if an object with automatic or allocated storage duration is used without having been initialized 😭. In C++, it also warns if a non-static reference or non-static"const"member appears in a class without constructors 🫠.
In addition, passing a pointer (or in C++, a reference) to an uninitialized object into a "const"-qualified argument of a built-in function known to read the object is also diagnosed by this warning 🔍. (-Wmaybe-uninitialized is issued for ordinary functions 🙌.)
If you want to warn about code that uses the uninitialized value of the variable in its own initializer, use the -Winit-self option 🪞.
These warnings occur for individual uninitialized elements of structure, union or array variables, as well as for variables that are uninitialized as a whole 🧩. They do not occur for variables or elements declared "volatile" 🚫. Because these warnings depend on optimization, the exact variables or elements that get warned about depend on the precise optimization options and version of GCC you're using 🎲.
Note that there may be no warning about a variable that's only used to compute a value that itself is never used, because such computations may be deleted by data flow analysis before the warnings are printed 🗑️.
In C++, this warning also warns about using uninitialized objects in member-initializer-lists. For example, GCC warns about "b" being uninitialized in the following snippet 👀:
struct A {
int a;
int b;
A() : a(b) { }
};-Wno-invalid-memory-model— this option controls warnings for invocations of__atomicbuiltins,__syncbuiltins, and the C11 atomic generic functions with a memory consistency argument that is either invalid for the operation or outside the range of values of the"memory_order"enumeration 🧵. For example, since the"__atomic_store"and"__atomic_store_n"built-ins are only defined for the relaxed, release, and sequentially consistent memory orders, the following code is diagnosed 🙅:
void store (int *i)
{
__atomic_store_n (i, 0, memory_order_consume);
}-Winvalid-memory-model is enabled by default 💜.
-Wmaybe-uninitialized— for an object with automatic or allocated storage duration, if there's a path from the function entry to a use of the object that is initialized, but some other paths where it isn't, the compiler emits a warning if it can't prove the uninitialized paths aren't executed at run time 🌀. In addition, passing a pointer (or in C++, a reference) to an uninitialized object into a"const"-qualified function argument is also diagnosed by this warning 🔎. (-Wuninitializedis issued for built-in functions known to read the object.) Annotating the function with attribute"access (none)"indicates that the argument isn't used to access the object, and avoids the warning 🫶.
These warnings are only possible in optimizing compilation, because otherwise GCC doesn't keep track of the state of variables 🧠.
These warnings are made optional because GCC may not be able to determine when the code is correct in spite of appearing to have an error 🙃. Here is one example of how this can happen:
{
int x;
switch (y)
{
case 1: x = 1;
break;
case 2: x = 4;
break;
case 3: x = 5;
}
foo (x);
}If the value of "y" is always 1, 2 or 3, then "x" is always initialized, but GCC doesn't know this 🤷♀️. To suppress the warning, you need to provide a default case with assert(0) or similar code 💅.
This option also warns when a non-volatile automatic variable might be changed by a call to "longjmp". The compiler sees only the calls to "setjmp". It cannot know where "longjmp" will be called; in fact, a signal handler could call it at any point in the code 😱. As a result, you may get a warning even when there is in fact no problem, because "longjmp" cannot actually be called at the place that would cause a problem 🙈.
Some spurious warnings can be avoided if you declare all the functions you use that never return as "noreturn" 🧹.
This warning is enabled by -Wall or -Wextra ✨.
-Wunknown-pragmas— warns when a"#pragma"directive is encountered that GCC doesn't understand 🤨. If this command-line option is used, warnings are even issued for unknown pragmas in system header files 📂. That is not the case if the warnings are only enabled by the-Wallcommand-line option 🙅♀️.-Wno-pragmas— do not warn about misuses of pragmas, such as incorrect parameters, invalid syntax, or conflicts between pragmas 🫡. See also-Wunknown-pragmas🎀.-Wno-prio-ctor-dtor: okay so this is a don't yell at me switch 💅 GCC won't warn if you give a constructor or destructor a priority from 0 to 100. The constructor and destructor attributes let you set a priority to control when they run, either beforemainis called or after it returns 🧚 But the compiler keeps 0–100 for itself, so your priority values have to be greater than 100 ✨-Wstrict-aliasing: this one only works when-fstrict-aliasingis turned on 👑 It warns about code that might break the strict aliasing rules the compiler uses for optimization. It doesn't catch every case, but it goes after the more common pitfalls 🫶 It's included in-Wall, and it's equivalent to-Wstrict-aliasing=3🦋-Wstrict-aliasing=n: also only active when-fstrict-aliasingis on ✨ It warns about the same kind of sketchy code, and higher levels are more accurate (fewer false positives) but take more effort, kinda like how-Oworks 🔥-Wstrict-aliasingis equivalent to-Wstrict-aliasing=3.- Level 1: most aggressive, quick, and least accurate 💀 It's possibly useful when the higher levels don't warn but
-fstrict-aliasingstill breaks your code, since it has very few false negatives. The tradeoff is it has many false positives 🙈 It warns for all pointer conversions between possibly incompatible types, even if the pointer is never dereferenced. It runs in the front end only. - Level 2: aggressive, quick, and not too precise 😭 It may still have many false positives (not as many as level 1 though) and few false negatives (possibly more than level 1). Unlike level 1, it only warns when an address is taken. It warns about incomplete types, and it runs in the front end only.
- Level 3 (default for
-Wstrict-aliasing): this is the one that should have very few false positives and few false negatives 💖 It's slightly slower than levels 1 or 2 when optimization is enabled. It takes care of the common pun+dereference pattern in the front end, like*(int*)&some_float. If optimization is enabled, it also runs in the back end, where it handles multiple statement cases using flow-sensitive points-to information. It only warns when the converted pointer is dereferenced, and it does not warn about incomplete types.
- Level 1: most aggressive, quick, and least accurate 💀 It's possibly useful when the higher levels don't warn but
-Wstrict-overflow,-Wstrict-overflow=n: this is only active when signed overflow is undefined 🌈 It warns about cases where the compiler optimizes based on the assumption that signed overflow never happens. It doesn't warn about every spot where the code might overflow, just the spots where the compiler actually does an optimization, so this warning depends on your optimization level 🤓
An optimization that assumes no signed overflow is perfectly safe if the variables involved never actually overflow, so this warning can easily give a false positive (a warning about code that isn't really a problem) 🥺 To help you focus on the important stuff, there are several warning levels. No warnings get issued for undefined signed overflow when estimating how many iterations a loop needs, especially when figuring out whether a loop runs at all.
-Wstrict-overflow=1: warns about cases that are both questionable and easy to avoid, like the compiler simplifyingx + 1 > xto1. This level is enabled by-Wall. Higher levels aren't, so you have to request them explicitly 🎀-Wstrict-overflow=2: also warns about other cases where a comparison gets simplified to a constant, likeabs (x) >= 0. That can only be simplified when signed integer overflow is undefined, becauseabs (INT_MIN)overflows toINT_MIN, which is less than zero 🧠-Wstrict-overflowwith no level is the same as-Wstrict-overflow=2.-Wstrict-overflow=3: also warns about other cases where a comparison is simplified, likex + 1 > 1getting simplified tox > 0🍓-Wstrict-overflow=4: also warns about other simplifications not covered above, like(x * 10) / 5getting simplified tox * 2✨-Wstrict-overflow=5: also warns when the compiler reduces the magnitude of a constant involved in a comparison, likex + 2 > ygetting simplified tox + 1 >= y. This only shows up at the highest warning level because the simplification applies to so many comparisons that this level gives a very large number of false positives 💀
-Wstring-compare: warns for calls tostrcmpandstrncmpwhose result is determined to be always zero or always non-zero in equality tests, because one argument is longer than the array the other argument is stored in (or the bound, forstrncmp) 🫧 Calls like that could be mistakes. In the example below, thestrcmpcall gets flagged because its result is necessarily non-zero no matter what's in the arraya. This one is enabled by-Wextra💅
extern char a[4];
void f (char *d)
{
strcpy (d, "string");
...
if (0 == strcmp (a, d)) // cannot be true
puts ("a and d are the same");
}-Wno-stringop-overflow,-Wstringop-overflow,-Wstringop-overflow=type: warns for calls to string manipulation functions likememcpyandstrcpythat are determined to overflow the destination buffer 🚨 The optional argument is one greater than the type of Object Size Checking used to figure out the size of the destination 🦋 It only matters for functions that operate on character arrays, not raw memory functions likememcpy, which always use Object Size type-0. This option also warns for calls that specify a size bigger than the largest possible object, or at mostSIZE_MAX / 2bytes 🌸
It gives the best results with optimization enabled, but it can detect a small subset of simple buffer overflows even without optimization in calls to GCC built-in functions like __builtin_memcpy that correspond to the standard functions. Either way, it only warns about a subset of the buffer overflows that the matching overflow checking built-ins would catch. In the example below, the strcpy call gets a warning because it copies at least 5 characters (the string "blue" including the terminating NUL) into a buffer of size 4 👑
enum Color { blue, purple, yellow };
const char* f (enum Color clr)
{
static char buf [4];
const char *str;
switch (clr)
{
case blue: str = "blue"; break;
case purple: str = "purple"; break;
case yellow: str = "yellow"; break;
}
return strcpy (buf, str); // warning here
}-Wstringop-overflow,-Wstringop-overflow=1: this uses type-zero Object Size Checking to figure out the sizes of destination objects 🌈 At this setting, it doesn't warn for writes past the end of subobjects of larger objects accessed through pointers, unless the size of the largest surrounding object is known. When the destination might be one of several objects, it's assumed to be the largest one of them. On Linux systems, when optimization is enabled at this setting, the option warns for the same code as when the_FORTIFY_SOURCEmacro is defined to a non-zero value 🧚-Wstringop-overflow=2: this uses type-one Object Size Checking to figure out the sizes of destination objects 🎀 At this setting, it warns about overflows when writing to members of the largest complete objects whose exact size is known. It does not warn for excessive writes to the same members of unknown objects referenced by pointers, since they might point to arrays with an unknown number of elements. This is the default setting for the option 💖-Wstringop-overflow=3: this uses type-two Object Size Checking to figure out the sizes of destination objects 🍓 At this setting, it warns about overflowing the smallest object or data member. It's the most restrictive setting that can still give warnings for safe code 😬-Wstringop-overflow=4: this uses type-three Object Size Checking to figure out the sizes of destination objects 🔥 At this setting, it warns about overflowing any data members. When the destination is one of several objects, it uses the size of the largest of them to decide whether to warn. Just like-Wstringop-overflow=3, this setting may result in warnings for benign code 🙈-Wno-stringop-overread: warns for calls to string manipulation functions likememchrorstrcpythat are determined to read past the end of the source sequence 👀-Wstringop-overreadis enabled by default, so this is the switch to flip if you want it quiet 🫶-Wno-stringop-truncation: don't warn for calls to bounded string manipulation functions likestrncat,strncpy, andstpncpythat might either truncate the copied string or leave the destination unchanged 🦋 In the example below, thestrncatcall sets a bound that's less than the length of the source string. That means the copy gets truncated, so the call is flagged. To avoid the warning, usebufsize - strlen (buf) - 1)as the bound ✨
void append (char *buf, size_t bufsize)
{
strncat (buf, ".txt", 3);
}Okay, so bestie, this next example is a whole vibe 💅 The strncpy call below copies only the characters before the terminating NUL into d, and it does not tack the NUL onto the end. Assuming strncpy always gives you a NUL-terminated string is a super common mistake 😭, so GCC calls it out. If you don't need the result to be NUL-terminated, use memcpy instead 🎀
void copy (char *d, const char *s)
{
strncpy (d, s, strlen (s));
}Next up, the strncpy call here uses the size of the destination buffer as its bound. If the source string is equal to or longer than that size, the copy won't be NUL-terminated, so this one gets flagged too 🙈 To dodge the warning, pass sizeof buf - 1 as the bound and set the last element of the buffer to NUL. Main character energy 👑
void copy (const char *s)
{
char buf[80];
strncpy (buf, s, sizeof buf);
...
}If a character array is meant to hold a sequence of bytes with no terminating NUL, you can annotate it with the attribute nonstring so GCC stops yelling about it 🦋 Just know these arrays aren't suitable for functions that expect NUL-terminated strings 💀 To help catch accidental misuse, GCC warns unless it can prove the use is safe.
-Wstrict-flex-arrays(C and C++ only) — Okay, this one checks for improper usage of flexible array members. The level comes from thestrict_flex_array (level)attribute on the trailing array field of a struct if it's available, otherwise from the-fstrict-flex-arrays=leveloption.-Wstrict-flex-arraysis only effective when level is greater than 0 🌸
The levels stack up like this:
level=1: warnings are issued for a trailing array reference of a structure that has 2 or more elements, if that trailing array is referenced as a flexible array member.level=2: in addition tolevel=1, extra warnings are issued for a trailing one-element array reference of a structure if the array is referenced as a flexible array member.level=3: in addition tolevel=2, extra warnings are issued for a trailing zero-length array reference of a structure if the array is referenced as a flexible array member.
This option hits harder when -ftree-vrp is active (the default for -O2 and above), but some warnings can show up even without optimization ✨
-Wsuggest-attribute=[pure|const|noreturn|format|cold|malloc]returns_nonnull|— Warns when adding an attribute might be a good idea 🧚 The attributes this covers are listed below:
-Wsuggest-attribute=pure
-Wsuggest-attribute=const
-Wsuggest-attribute=noreturn
-Wmissing-noreturn
-Wsuggest-attribute=malloc
-Wsuggest-attribute=returns_nonnull
-Wno-suggest-attribute=returns_nonnullThese flag functions that could be candidates for the pure, const, noreturn, malloc or returns_nonnull attributes. GCC only warns for functions visible in other compilation units, or (for pure and const) if it can't prove the function returns normally. A function returns normally if it doesn't contain an infinite loop or return abnormally by throwing, calling abort or trapping. This analysis needs -fipa-pure-const, which is on by default at -O and higher. Higher optimization levels make the analysis more accurate 🔥
-Wsuggest-attribute=format,-Wmissing-format-attribute— Warns about function pointers that might be candidates forformatattributes 🎀 These are only possible candidates, not absolute ones. GCC guesses that function pointers withformatattributes used in assignment, initialization, parameter passing or return statements should have a matchingformatattribute in the resulting type. In other words, the left-hand side of the assignment or initialization, the type of the parameter variable, or the return type of the containing function should also have aformatattribute to avoid the warning.
GCC also warns about function definitions that might be candidates for format attributes. Again, these are only possible candidates 🫶 GCC guesses that format attributes might fit any function that calls something like vprintf or vscanf, but that's not always the case, and some functions where format attributes are appropriate might not get detected.
-Wsuggest-attribute=cold— Warns about functions that might be candidates for thecoldattribute 🧊 This is based on static detection and usually only warns about functions that always lead to a call to anothercoldfunction, like wrappers of C++throwor fatal error reporting functions that end up atabort.-Walloc-size— Warns about calls to allocation functions decorated with thealloc_sizeattribute that specify an insufficient size for the target type of the pointer the result gets assigned to. This includes the built-in forms ofaligned_alloc,alloca,calloc,malloc, andrealloc💖-Walloc-zero— Warns about calls to allocation functions decorated withalloc_sizethat specify zero bytes, including the built-in forms ofaligned_alloc,alloca,calloc,malloc, andrealloc😭 The behavior of these functions with a zero size differs between implementations (and forreallocit's been deprecated), so relying on it can cause subtle portability bugs. Please avoid it 🙅-Wcalloc-transposed-args— A coding style warning 💅 It flags calls to allocation functions decorated withalloc_sizethat have two arguments, usesizeofas the earlier size argument, and don't use it as the later one. The first argument tocallocis documented as the number of elements in the array, and the second is the size of each element, socalloc (n, sizeof (int))is preferred overcalloc (sizeof (int), n). Ifsizeofin the earlier argument (and not the latter) is intentional, you can suppress the warning withcalloc (sizeof (struct S) + 0, n)orcalloc (1 * sizeof (struct S), 4), or by usingsizeofin the later argument as well ✨-Walloc-size-larger-than=byte-size— Warns about calls to functions decorated withalloc_sizethat try to allocate objects larger than the specified number of bytes. It also fires when the size computation, done in an integer type with infinite precision, would exceed the value ofPTRDIFF_MAXon the target.-Walloc-size-larger-than=PTRDIFF_MAXis on by default 🌈 You can turn off these warnings either by specifying a byte-size ofSIZE_MAXor more, or with-Wno-alloc-size-larger-than.-Wno-alloc-size-larger-than— Disables the-Walloc-size-larger-than=warnings 🙈 It's the same as-Walloc-size-larger-than=SIZE_MAXor larger.-Walloca— Warns on all uses ofallocain the source 😬-Walloca-larger-than=byte-size— This one warns on calls toallocawhere the integer argument is either zero, or isn't bounded by a controlling predicate that limits its value to at most byte-size. It also warns for calls toallocawhere the bound value is unknown. Arguments of non-integer types count as unbounded, even if they look like they're constrained to the expected range 💀
A bounded use of alloca could look like this:
void func (size_t n)
{
void *p;
if (n <= 1000)
p = alloca (n);
else
p = malloc (n);
f (p);
}Passing -Walloca-larger-than=1000 won't warn here, because the call to alloca is known to be at most 1000 bytes. But if -Walloca-larger-than=500 were passed, the compiler would emit a warning 🦋
Unbounded uses, on the other hand, are uses of alloca with no controlling predicate constraining its integer argument. For example:
void func ()
{
void *p = alloca (n);
f (p);
}If -Walloca-larger-than=500 were passed, the above would trigger a warning, this time because of the lack of bounds checking 🙃
Note that even seemingly correct code using signed integers can cause a warning:
void func (signed int n)
{
if (n < 500)
{
p = alloca (n);
f (p);
}
}In the above example, n could be negative, which would cause a larger than expected argument to be implicitly cast into the alloca call 🫠
This option also warns when alloca is used in a loop.
-Walloca-larger-than=PTRDIFF_MAX is enabled by default, but it's usually only effective when -ftree-vrp is active (the default for -O2 and above). See also -Wvla-larger-than=byte-size.
-Wno-alloca-larger-than— Disables the-Walloca-larger-than=warnings 🌸 It's equivalent to-Walloca-larger-than=SIZE_MAXor larger.-Warith-conversion— Do warn about implicit conversions from arithmetic operations, even when converting the operands to the same type can't change their values 🧠 This affects warnings from-Wconversion,-Wfloat-conversion, and-Wsign-conversion.
void f (char c, int i)
{
c = c + i; // warns with -Wconversion
c = c + 1; // only warns with -Warith-conversion
}-Warray-bounds,-Warray-bounds=n— Warns about out-of-bounds subscripts or offsets into arrays 🍓 This warning is enabled by-Wall. It's more effective when-ftree-vrpis active (the default for-O2and above), but a subset of instances are issued even without optimization 💜
By default, bestie, the trailing array of a structure gets treated as a flexible array member by -Warray-bounds or -Warray-bounds=n if it's declared as any of these: a flexible array member per the C99 standard onwards ([]), a GCC zero-length array extension ([0]), or a one-element array ([1]). 💅 So out of bounds subscripts or offsets into zero-length arrays or one-element arrays are not warned about by default 🙈
You can add -fstrict-flex-arrays or -fstrict-flex-arrays=level to control how this option treats the trailing array of a structure as a flexible array member. ✨ Here's the tea:
- when
level<=1, nothing changes from the default behavior 🌸 - when
level=2, you get additional warnings for out of bounds subscripts or offsets into one-element arrays 🦋 - when
level=3, you get everything fromlevel=2plus additional warnings for out of bounds subscripts or offsets into zero-length arrays 👑 -Warray-bounds=1— This is the default warning level of-Warray-bounds, and it's enabled by-Wall. The higher levels aren't, so you've gotta ask for them explicitly 💖-Warray-bounds=2— This level also warns about the intermediate results of pointer arithmetic that may yield out of bounds values. Expect a bigger pile of false positives here, and it's deactivated by default 🥲
🎀 -Warray-compare
Warn about equality and relational comparisons between two operands of array type. Bestie, this comparison was deprecated in C++20 🥀 For example:
int arr1[5];
int arr2[5];
bool same = arr1 == arr2;-Warray-compare is enabled by -Wall ✨
🌈 -Warray-parameter, -Warray-parameter=n
Warn about redeclarations of functions involving parameters of array or pointer types of inconsistent kinds or forms, and enable the detection of out-of-bounds accesses to such parameters by warnings such as -Warray-bounds 🔥
If the first function declaration uses the array form for a parameter declaration, the bound specified in the array is assumed to be the minimum number of elements expected to be provided in calls to the function and the maximum number of elements accessed by it. Failing to provide arguments of sufficient size, or accessing more than the maximum number of elements, may be diagnosed by warnings such as -Warray-bounds or -Wstringop-overflow. At level 1, the warning diagnoses inconsistencies involving array parameters declared using the "T[static N]" form 🧚
For example, the warning triggers for the second declaration of f, because the first one with the keyword static specifies that the array argument must have at least four elements, while the second allows an array of any size to be passed to f 💀
void f (int[static 4]);
void f (int[]); // warning (inconsistent array form)
void g (void)
{
int *p = (int *)malloc (1 * sizeof (int));
f (p); // warning (array too small)
...
}At level 2, the warning also triggers for redeclarations involving any other inconsistency in array or pointer argument forms denoting array sizes. Pointers and arrays of unspecified bound are considered equivalent and do not trigger a warning, so no drama there 🫶
void g (int*);
void g (int[]); // no warning
void g (int[8]); // warning (inconsistent array bound)-Warray-parameter=2 is included in -Wall. The -Wvla-parameter option triggers warnings for similar inconsistencies involving Variable Length Array arguments 🍓
The short form of the option, -Warray-parameter, is equivalent to -Warray-parameter=2. The negative form, -Wno-array-parameter, is equivalent to -Warray-parameter=0 💜
🦋 -Wattribute-alias=n, -Wno-attribute-alias
Warn about declarations using the "alias" and similar attributes whose target is incompatible with the type of the alias 🌸
-Wattribute-alias=1— This is the default warning level of the-Wattribute-aliasoption. It diagnoses incompatibilities between the type of the alias declaration and that of its target. Such incompatibilities are typically indicative of bugs 🐛-Wattribute-alias=2— At this level,-Wattribute-aliasalso diagnoses cases where the attributes of the alias declaration are more restrictive than the attributes applied to its target. These mismatches can potentially result in incorrect code generation. In other cases they may be benign and could be resolved simply by adding the missing attribute to the target. For comparison, see the-Wmissing-attributesoption, which controls diagnostics when the alias declaration is less restrictive than the target, rather than more restrictive 🔍
Attributes considered include "alloc_align", "alloc_size", "cold", "const", "hot", "leaf", "malloc", "nonnull", "noreturn", "nothrow", "pure", "returns_nonnull", and "returns_twice" 👑
-Wattribute-alias is equivalent to -Wattribute-alias=1. This is the default. You can disable these warnings with either -Wno-attribute-alias or -Wattribute-alias=0 🙅♀️
🌸 -Wbidi-chars=[none|unpaired|any|ucn]
Warn about possibly misleading UTF-8 bidirectional control characters in comments, string literals, character constants, and identifiers. Bestie, these characters are sneaky 😭 They can change left-to-right writing direction into right-to-left (and vice versa), which can cause confusion between the logical order and the visual order. This may be dangerous. For instance, it may seem that a piece of code is not commented out, whereas it in fact is 💀
There are three levels of warning supported by GCC. The default is -Wbidi-chars=unpaired, which warns about improperly terminated bidi contexts. -Wbidi-chars=none turns the warning off. -Wbidi-chars=any warns about any use of bidirectional control characters ✨
By default, this warning does not warn about UCNs. It is, however, possible to turn on such checking by using -Wbidi-chars=unpaired,ucn or -Wbidi-chars=any,ucn. Using -Wbidi-chars=ucn is valid, and is equivalent to -Wbidi-chars=unpaired,ucn, if no previous -Wbidi-chars=any was specified 🦋
💅 -Wbool-compare
Warn about a boolean expression compared with an integer value different from "true"/"false". For instance, the following comparison is always false 🙃
int n = 5;
...
if ((n > 1) == 2) { ... }This warning is enabled by -Wall 🌈
🧚 -Wbool-operation
Warn about suspicious operations on expressions of a boolean type. For instance, bitwise negation of a boolean is very likely a bug in the program 🐛 For C, this warning also warns about incrementing or decrementing a boolean, which rarely makes sense. (In C++, decrementing a boolean is always invalid. Incrementing a boolean is invalid in C++17, and deprecated otherwise.) 🫠
This warning is enabled by -Wall 💖
🍓 -Wduplicated-branches
Warn when an if-else has identical branches. This warning detects cases like this:
if (p != NULL)
return 0;
else
return 0;It doesn't warn when both branches contain just a null statement. This warning also warns for conditional operators:
int i = x ? *p : *p;🫧 -Wduplicated-cond
Warn about duplicated conditions in an if-else-if chain. For instance, warn for the following code:
if (p->q != NULL) { ... }
else if (p->q != NULL) { ... }👑 -Wframe-address
Warn when __builtin_frame_address or __builtin_return_address is called with an argument greater than 0. Such calls may return indeterminate values or crash the program 😱 The warning is included in -Wall 🔥
🌷 -Wno-discarded-qualifiers (C and Objective-C only)
Do not warn if type qualifiers on pointers are being discarded. Typically, the compiler warns if a const char * variable is passed to a function that takes a char * parameter. This option can be used to suppress such a warning 🤫
🌷 -Wno-discarded-array-qualifiers (C and Objective-C only)
Do not warn if type qualifiers on arrays which are pointer targets are being discarded. Typically, the compiler warns if a const int (*)[] variable is passed to a function that takes an int (*)[] parameter. This option can be used to suppress such a warning 🎀
🌺 -Wno-incompatible-pointer-types (C and Objective-C only)
Do not warn when there is a conversion between pointers that have incompatible types. This warning is for cases not covered by -Wno-pointer-sign, which warns for pointer argument passing or assignment with different signedness 🦄
By default, in C99 and later dialects of C, GCC treats this issue as an error. The error can be downgraded to a warning using -fpermissive (along with certain other errors), or for this error alone, with -Wno-error=incompatible-pointer-types 🫶
This warning is upgraded to an error by -pedantic-errors 🚨
🫠 -Wno-int-conversion (C and Objective-C only)
Do not warn about incompatible integer to pointer and pointer to integer conversions. This warning is about implicit conversions. For explicit conversions, the warnings -Wno-int-to-pointer-cast and -Wno-pointer-to-int-cast may be used 🍒
By default, in C99 and later dialects of C, GCC treats this issue as an error. The error can be downgraded to a warning using -fpermissive (along with certain other errors), or for this error alone, with -Wno-error=int-conversion 🌸
This warning is upgraded to an error by -pedantic-errors ⭐
🕳️ -Wzero-length-bounds
Warn about accesses to elements of zero-length array members that might overlap other members of the same object. Declaring interior zero-length arrays is discouraged, because accesses to them are undefined. Undefined behavior, bestie, so please don't 🙅♀️
For example, the first two stores in function bad are diagnosed because the array elements overlap the subsequent members b and c. The third store is diagnosed by -Warray-bounds because it is beyond the bounds of the enclosing object 🧐
struct X { int a[0]; int b, c; };
struct X x;void bad (void)
{
x.a[0] = 0; // -Wzero-length-bounds
x.a[1] = 1; // -Wzero-length-bounds
x.a[2] = 2; // -Warray-bounds
}Okay so -Wzero-length-bounds is automatically switched on whenever you enable -Warray-bounds 💅✨
-Wno-div-by-zero— bestie, this one's a vibe 🙄 GCC stops yelling about compile-time integer division by zero. Floating-point division by zero never gets flagged, since it can be a totally legit way to get infinities and NaNs 🌈-Wsystem-headers— normally GCC keeps quiet about warnings in system header files, since those usually aren't real problems and would just make the output messier 🙈 This flag tells GCC to treat those headers like your own code and print their warnings. Heads up though:-Wallcombined with this flag still won't warn about unknown pragmas in system headers 💀 For that, you also need-Wunknown-pragmas.-Wtautological-compare— no cap, this catches sneaky mistakes 🔍 It warns if a self-comparison always evaluates to true or false, like this:
int i = 1;
...
if (i > i) { ... }It also warns about bitwise comparisons that always come out true or false, for instance:
if ((a & 16) == 10) { ... }That one is always false, so 😭 This warning is enabled by -Wall.
-Wtrampolines— warns about trampolines generated for pointers to nested functions 🦋 A trampoline is a small piece of data or code created at run time on the stack when the address of a nested function is taken, and it's used to call that nested function indirectly. On some targets it's only data, so it needs no special treatment. But on most targets it's code, which means the stack has to be made executable for the program to work properly.-Wfloat-equal— warns if floating-point values are used in equality comparisons 🧚 Sometimes it's convenient to treat floats as approximations of infinitely precise real numbers, and if you're doing that, you need to figure out (by analyzing the code, or some other way) the maximum or likely maximum error the computation introduces, then allow for it in your comparisons (and when producing output, but that's a different problem). Instead of testing for equality, check whether the two values have overlapping ranges. That's done with relational operators, so equality comparisons are probably mistaken 🙅♀️-Wtraditional(C and Objective-C only) — this one is the ultimate throwback check 🕰️ It warns about constructs that behave differently in traditional and ISO C. It also flags ISO C constructs with no traditional C equivalent, and/or problematic constructs you should avoid. Here's what it's watching for:- Macro parameters that appear within string literals in the macro body. Traditional C does macro replacement inside string literals, but ISO C does not.
- Some preprocessor directives didn't exist in traditional C. Traditional preprocessors only considered a line a directive if the
#appeared in column 1, so-Wtraditionalwarns about directives that traditional C understands but ignores because the#isn't the first character on the line. It also suggests hiding directives like#pragma, which traditional C doesn't understand, by indenting them. Some traditional implementations don't recognize#elif, so this option suggests avoiding it altogether. - A function-like macro that appears without arguments.
- The unary plus operator.
- The
Uinteger constant suffix, or theForLfloating-point constant suffixes. (Traditional C does support theLsuffix on integer constants.) These suffixes show up in macros defined in the system headers of most modern systems, e.g. the_MIN/_MAXmacros in<limits.h>. Using these macros in user code might normally lead to spurious warnings, but GCC's integrated preprocessor has enough context to avoid warning in these cases ✨ - A function declared external in one block and then used after the end of the block.
- A
switchstatement with an operand of typelong. - A non-
staticfunction declaration that follows astaticone. Some traditional C compilers don't accept this. - The ISO type of an integer constant has a different width or signedness from its traditional type. This warning is only issued if the base of the constant is ten, so hexadecimal or octal values, which typically represent bit patterns, aren't warned about.
- Use of ISO string concatenation.
- Initialization of automatic aggregates.
- Identifier conflicts with labels. Traditional C lacks a separate namespace for labels.
- Initialization of unions. If the initializer is zero, the warning is omitted. This is done under the assumption that a zero initializer in user code is conditioned on something like
__STDC__to avoid missing-initializer warnings, and that it relies on default initialization to zero in the traditional C case. - Conversions by prototypes between fixed and floating-point values and vice versa. The absence of these prototypes when compiling with traditional C causes serious problems. This is a subset of the possible conversion warnings; for the full set, use
-Wtraditional-conversion. - Use of ISO C style function definitions. This warning is intentionally not issued for prototype declarations or variadic functions, because those ISO C features appear in your code when you use libiberty's traditional C compatibility macros,
PARAMSandVPARAMS. It's also bypassed for nested functions, because that feature is already a GCC extension and isn't relevant to traditional C compatibility.
-Wtraditional-conversion(C and Objective-C only) — warns if a prototype causes a type conversion that's different from what would happen to the same argument in the absence of a prototype 🔄 That includes conversions between fixed-point and floating-point values and vice versa, plus conversions that change the width or signedness of a fixed-point argument, except when it matches the default promotion.-Wdeclaration-after-statement(C and Objective-C only) — warns when a declaration is found after a statement in a block 📝 This construct comes from C++, was introduced with ISO C99, and is allowed by default in GCC. It's not supported by ISO C90. This warning is upgraded to an error by-pedantic-errors.-Wshadow— main character energy, but make it a warning 👑 It warns whenever a local variable or type declaration shadows another variable, parameter, type, class member (in C++), or instance variable (in Objective-C), or whenever a built-in function is shadowed. In C++, the compiler warns if a local variable shadows an explicit typedef, but not if it shadows astruct/class/enum. If this warning is enabled, it also includes all instances of local shadowing. That means-Wno-shadow=localand-Wno-shadow=compatible-localare ignored when-Wshadowis used. Same as-Wshadow=global.-Wno-shadow-ivar(Objective-C only) — don't warn when a local variable shadows an instance variable in an Objective-C method 🙈-Wshadow=global— warns for any shadowing. Same as-Wshadow🌸-Wshadow=local— warns when a local variable shadows another local variable or parameter 🍓-Wshadow=compatible-local— warns when a local variable shadows another local variable or parameter whose type is compatible with that of the shadowing variable. In C++, type compatibility here means the shadowing variable's type can be converted to the shadowed variable's type. The creation of this flag (in addition to-Wshadow=local) is based on the idea that when a local variable shadows another one of incompatible type, it's most likely intentional, not a bug or typo. Check out this example:
for (SomeIterator i = SomeObj.begin(); i != SomeObj.end(); ++i)
{
for (int i = 0; i < N; ++i)
{
...
}
...
}Since the two i variables above have incompatible types, enabling only -Wshadow=compatible-local does not emit a warning. Because their types are incompatible, if a programmer accidentally uses one in place of the other, type checking is expected to catch that and emit an error or warning. Using this flag instead of -Wshadow=local can possibly reduce the number of warnings triggered by intentional shadowing. Note that this also means shadowing const char *i by char *i does not emit a warning.
This warning is also enabled by -Wshadow=local.
-Wlarger-than=byte-size— warns whenever an object is defined whose size exceeds byte-size 📏-Wlarger-than=PTRDIFF_MAXis enabled by default. Warnings controlled by this option can be disabled either by specifying a byte-size ofSIZE_MAXor more, or by-Wno-larger-than. Also warns for calls to bounded functions such asmemchrorstrnlenthat specify a bound greater than the largest possible object, which isPTRDIFF_MAXbytes by default. These warnings can only be disabled by-Wno-larger-than🧚-Wno-larger-than— disables-Wlarger-than=warnings 💖 It's equivalent to-Wlarger-than=SIZE_MAXor larger.-Wframe-larger-than=byte-size— okay so this one warns you if a function's stack frame gets bigger than byte-size 📏🔥. The compiler's guess at the frame size is approximate and not conservative 🙈, so the real needs might be somewhat bigger than byte-size even when you get no warning at all. Also, space fromalloca, variable-length arrays, or related constructs doesn't get counted when the compiler decides whether to warn 💀.-Wframe-larger-than=PTRDIFF_MAXis on by default ✨. You can switch these warnings off by giving a byte-size ofSIZE_MAXor more, or by using-Wno-frame-larger-than🦋.-Wno-frame-larger-than— bye bye,-Wframe-larger-than=warnings 👋🌸. It works the same as-Wframe-larger-than=SIZE_MAXor anything bigger.-Wfree-nonheap-object— this one catches you trying to free something that was never on the heap, or freeing a pointer that didn't come straight from the matching allocation function 🧚. Like,stpcpyhands back a pointer to the terminating nul character instead of the start of your object, so thefreebelow gets flagged 😭.-Wfree-nonheap-objectis part of-Wall💜.
void f (char *p)
{
p = stpcpy (p, "abc");
// ...
free (p); // warning
}-Wstack-usage=byte-size— warns if a function's stack usage might go over byte-size 🥞. This math is conservative, so any space fromalloca, variable-length arrays, or related constructs gets counted 🫶. The message matches what-fstack-usageprints 💅. Here's what you'll see:- If the stack usage is fully static but goes over the limit, it says:
warning: stack usage is 1120 bytes - If the stack usage is partly dynamic but bounded, it says:
warning: stack usage might be 1648 bytes - If the stack usage is partly dynamic and not bounded, it says:
warning: stack usage might be unbounded
- If the stack usage is fully static but goes over the limit, it says:
-Wstack-usage=PTRDIFF_MAX is on by default 🌈. You can turn these warnings off by giving a byte-size of SIZE_MAX or more, or by using -Wno-stack-usage 🎀.
-Wno-stack-usage— no more-Wstack-usage=warnings, periodt 🙅♀️. Same as-Wstack-usage=SIZE_MAXor bigger.-Wunsafe-loop-optimizations— warns when a loop can't be optimized because the compiler can't assume anything about its index bounds 🌀. Pair it with-funsafe-loop-optimizationsand it'll warn you whenever the compiler does make those assumptions 👀.-Wno-pedantic-ms-format(MinGW targets only) — when you use it together with-Wformatand-pedantic(without GNU extensions), it silences the warnings about the non-ISOprintf/scanfwidth specifiersI32,I64, andIon Windows targets 🪟✨. Those depend on the MS runtime, so they're not standard, but if that's what you're going for, you can chill 🧊.-Wpointer-arith— heads up for anything that depends on the "size of" a function type or ofvoid📐. GNU C gives those types a size of 1, which is handy for math withvoid *pointers and pointers to functions 🍓. In C++, it also warns when an arithmetic operation involvesNULL💖. This warning is also turned on by-Wpedantic🔥. It gets upgraded to an error by-pedantic-errors🚨.-Wno-pointer-compare— don't warn when a pointer gets compared with a zero character constant 🙃. That usually means the pointer was meant to be dereferenced, so the warning is usually helpful 🤷♀️. Here's an example:
const char *p = foo ();
if (p == '\0')
return 42;Just so you know, the code above is invalid in C++11 💀. This warning is enabled by default ✅.
-Wno-tsan— shuts up the warnings about unsupported features in ThreadSanitizer 🧵. Real talk, ThreadSanitizer doesn't supportstd::atomic_thread_fenceand can report false positives 🙈.-Wtype-limits— warns if a comparison is always true or always false because of the limited range of the data type 📏. Constant expressions don't get the warning, though 💅. For example, it warns if an unsigned variable gets compared against zero with<or>=👑. This warning is also enabled by-Wextra✨.-Wabsolute-value(C and Objective-C only) — warns when you call a standard function that computes an absolute value when there's a better standard function for the job 🧮. For example,abs(3.14)triggers it becausefabsis the right call for a double 💖. It also warns if the argument to one of those functions has an unsigned type 🙈. You can suppress it with an explicit type cast, and it's also enabled by-Wextra🫶.-Wcomment,-Wcomments— warns whenever a comment-start sequence/*shows up inside a/*comment, or whenever a backslash-newline shows up in a//comment 🧐. This warning is enabled by-Wall🌸.-Wtrigraphs— warns if any trigraphs get encountered that might change what your program means 🔮. Trigraphs inside comments don't get warned about, except the ones that would form escaped newlines 🦋. This option is implied by-Wall. If-Wallisn't given, this option is still on unless trigraphs are enabled 🌈. Want trigraph conversion with no warnings but still get the other-Wallwarnings? Use-trigraphs -Wall -Wno-trigraphs🍓.-Wundef— warns if an undefined identifier gets evaluated in an#ifdirective 🕵️♀️. Those identifiers get replaced with zero, which can be sneaky 😭.-Wexpansion-to-defined— warns wheneverdefinedshows up in the expansion of a macro, including when the macro gets expanded by an#ifdirective 🌀. That usage isn't portable 🙅♀️. This warning is also enabled by-Wpedanticand-Wextra💜.-Wunused-macros— warns about macros defined in the main file that never get used 🧹. A macro counts as used if it gets expanded or tested for existence at least once 👀. The preprocessor also warns if the macro hasn't been used by the time it gets redefined or undefined ✨.
Built-in macros, macros defined on the command line, and macros defined in include files don't get warned about 🙌.
Heads up: if a macro is actually used, but only inside skipped conditional blocks, the preprocessor still reports it as unused 🙈. To dodge the warning in that case, you could improve the scope of the macro's definition, like moving it into the first skipped block 🦋. Or you could add a dummy use with something like this:
#if defined the_macro_causing_the_warning
#endif-Wno-endif-labels— don't warn when an#elseor an#endifgets followed by text 🎀. This happens sometimes in older programs with code that looks like this:
#if FOO
...
#else FOO
...
#endif FOOThe second and third FOO are supposed to be in comments 😭. This warning is on by default ✅.
-Wbad-function-cast(C and Objective-C only) — warns when a function call gets cast to a non-matching type 🎭. For example, it warns if a call to a function returning an integer type gets cast to a pointer type 💀.-Wc90-c99-compat(C and Objective-C only) — warns about features that are in ISO C99 but not in ISO C90 🕰️. Examples include variable length arrays, thelong longtype, thebooltype, compound literals, designated initializers, and so on 🧸. This option doesn't depend on the standards mode 🌈. Warnings are disabled in the expression that follows__extension__🫶.-Wc99-c11-compat(C and Objective-C only) — warns about features that are in ISO C11 but not in ISO C99 ✨. Think anonymous structures and unions, the_Atomictype qualifier, the_Thread_localstorage-class specifier, the_Alignasspecifier, theAlignofoperator, the_Generickeyword, and so on 💅. This option doesn't depend on the standards mode 👑. Warnings are disabled in the expression that follows__extension__🌸.-Wc11-c23-compat,-Wc11-c2x-compat(C and Objective-C only) — warns about features that are in ISO C23 but not in ISO C11 🔮. Examples are omitting the string in_Static_assert, using[[]]attribute syntax, using decimal floating-point types, and so on 🧁. This option doesn't depend on the standards mode 🌈. Warnings are disabled in the expression that follows__extension__🫶. The name-Wc11-c2x-compatis deprecated, so use-Wc11-c23-compatinstead 🥹.
When you're not compiling in C23 mode, these warnings get upgraded to errors by -pedantic-errors 🚨.
-Wc++-compat(C and Objective-C only) — warns about ISO C constructs that sit outside the common subset of ISO C and ISO C++ 🧩. One example is asking for an implicit conversion fromvoid *to a pointer to a non-voidtype 💜.-Wc++11-compat(C++ and Objective-C++ only) — warns about C++ constructs whose meaning changed between ISO C++ 1998 and ISO C++ 2011 🕰️. For example, identifiers that were fine in ISO C++ 1998 but are keywords in ISO C++ 2011 💀. This warning turns on-Wnarrowingand is enabled by-Wall🌟.-Wc++14-compat(C++ and Objective-C++ only) — warns about C++ constructs whose meaning changed between ISO C++ 2011 and ISO C++ 2014 🎀. This warning is enabled by-Wall✅.-Wc++17-compat(C++ and Objective-C++ only) — warns about C++ constructs whose meaning changed between ISO C++ 2014 and ISO C++ 2017 🦋. This warning is enabled by-Wall✅.-Wc++20-compat(C++ and Objective-C++ only) — warns about C++ constructs whose meaning changed between ISO C++ 2017 and ISO C++ 2020 🌈. This warning is enabled by-Wall✅.-Wno-c++11-extensions(C++ and Objective-C++ only) — don't warn about C++11 constructs when you're compiling with an older C++ standard 🙌. Even without this option, some C++11 constructs only get flagged if you use-Wpedantic🧐.-Wno-c++14-extensions(C++ and Objective-C++ only) — don't warn about C++14 constructs when you're compiling with an older C++ standard 🌸. Even without this option, some C++14 constructs only get flagged if you use-Wpedantic🧐.-Wno-c++17-extensions(C++ and Objective-C++ only) — don't warn about C++17 constructs when you're compiling with an older C++ standard ✨. Even without this option, some C++17 constructs only get flagged if you use-Wpedantic🧐.-Wno-c++20-extensions(C++ and Objective-C++ only) — okay bestie, this one tells the compiler to chill about C++20 stuff when your code is written for an older C++ standard 🙈 Even without it, some C++20 constructs only get flagged if you turn on-Wpedantic.-Wno-c++23-extensions(C++ and Objective-C++ only) — same energy, but for C++23 ✨ It stops the warnings about C++23 constructs when you're compiling with an older C++ standard. Some C++23 constructs still only get called out with-Wpedantic.-Wno-c++26-extensions(C++ and Objective-C++ only) — and yes, C++26 gets the same treatment 💅 No warnings about C++26 constructs in code built with an older C++ standard. Some C++26 constructs will only be diagnosed if-Wpedanticis used.-Wcast-qual— this one catches you when a pointer gets cast so it drops a type qualifier from the target type. For example, it warns if aconst char *gets cast to a plainchar *👀
It also warns when a cast adds a type qualifier in an unsafe way. Casting char ** to const char ** is the classic example, and it's a whole mess:
/* p is char ** value. */
const char **q = (const char **) p;
/* Assignment of readonly string to const char * is OK. */
*q = "string";
/* Now char** pointer points to read-only memory. */
**p = 'b';-Wcast-align— warns whenever a pointer cast increases the alignment the target needs. For example, it warns if achar *gets cast to anint *on machines where integers can only be accessed at two- or four-byte boundaries 🦋-Wcast-align=strict— the no-excuses version of the one above 😤 It warns whenever a pointer cast increases the required alignment, no matter the target machine. So achar *cast to anint *gets flagged everywhere.-Wcast-function-type— warns when a function pointer gets cast to an incompatible function pointer type. A few vibes to know about:- With function types that take a variable argument list, only the types of the initial arguments that are actually provided get considered.
- Any pointer-type parameter matches any other pointer-type.
- Benign differences in integral types get ignored, like
intvs.longon ILP32 targets. - Type qualifiers get ignored too.
- The function type
void (*) (void)is special and matches everything, so you can use it to suppress this warning 🤫 - For casts involving pointer to member types, it warns whenever the cast changes the pointer to member type.
This warning is enabled by -Wextra.
-Wwrite-strings— in C, string constants get the typeconst char[length], so copying one's address into a non-constchar *pointer gives a warning. These help you find, at compile time, code that might try to write into a string constant. The catch is they only work well if you've been super careful withconstin your declarations and prototypes. Otherwise they're just annoying 🙄 That's why-Walldoesn't ask for them.
In C++, it warns about the deprecated conversion from string literals to char *. This one is enabled by default for C++ programs.
Heads up: in C++11 mode or later, this warning gets upgraded to an error by -pedantic-errors.
-Wclobbered— warns about variables that might get changed bylongjmporvfork🧟 This warning is also enabled by-Wextra.-Wno-complain-wrong-lang— by default, language front ends complain when a command-line option is valid but doesn't apply to that front end. This flag shuts that down. It's mostly useful when you're invoking one compiler driver for multiple source files written in different languages, like this:
$ g++ -fno-rtti a.cc b.f90The g++ driver uses the C++ front end to compile a.cc and the Fortran front end to compile b.f90. The Fortran front end then complains with this message:
f951: Warning: command-line option '-fno-rtti' is valid for C++/D/ObjC++ but not for Fortran, which may be disabled with -Wno-complain-wrong-lang.-Wcompare-distinct-pointer-types(C and Objective-C only) — warns if pointers of distinct types get compared without a cast. This warning is enabled by default 💖-Wconversion— warns about implicit conversions that might change a value 👀 That includes:- conversions between real and integer, like
abs (x)whenxis adouble; - conversions between signed and unsigned, like
unsigned ui = -1; - conversions to smaller types, like
sqrtf (M_PI).
- conversions between real and integer, like
It doesn't warn about explicit casts like abs ((int) x) and ui = (unsigned) -1, or about conversions that don't change the value, like abs (2.0). If you want to silence warnings about signed and unsigned integer conversions, use -Wno-sign-conversion.
In C++, it also warns about confusing overload resolution for user-defined conversions. It also covers conversions that never use a type conversion operator: conversions to void, to the same type, to a base class, or to a reference to them. In C++, warnings about signed and unsigned integer conversions are disabled by default unless you explicitly enable -Wsign-conversion.
Warnings about conversions from arithmetic on a small type back to that same type only show up with -Warith-conversion 🌸
-Wdangling-else— warns about constructions where it's unclear whichifstatement anelsebranch belongs to 🫠 Here's a sneaky example:
{
if (a)
if (b)
foo ();
else
bar ();
}In C and C++, every else branch belongs to the innermost possible if statement, which here is if (b). That's often not what the programmer meant, and the indentation in the example above shows exactly that trap. When there's potential for this confusion, GCC issues a warning if this flag is specified. To get rid of the warning, add explicit braces around the innermost if statement, so the else can't possibly belong to the enclosing if. The fixed code looks like this:
{
if (a)
{
if (b)
foo ();
else
bar ();
}
}This warning is enabled by -Wparentheses.
-Wdangling-pointer,-Wdangling-pointer=n— ✨ these warn about uses of pointers (or C++ references) to objects with automatic storage duration after their lifetime has ended. That includes local variables declared in nested blocks, compound literals, and other unnamed temporary objects. It also warns about storing the address of such objects in escaped pointers 🧚 This warning is enabled at all optimization levels, but it may give different results with optimization than without.-Wdangling-pointer=1— at level 1, the warning only diagnoses unconditional uses of dangling pointers.-Wdangling-pointer=2— at level 2, the warning also diagnoses conditional uses of dangling pointers, on top of the unconditional ones.
The short form -Wdangling-pointer is the same as -Wdangling-pointer=2. Meanwhile, -Wno-dangling-pointer and -Wdangling-pointer=0 both turn the warnings off. -Wdangling-pointer=2 is included in -Wall.
This example triggers the warning at level 1, because the address of the unnamed temporary is unconditionally referenced outside of its scope:
char f (char c1, char c2, char c3)
{
char *p;
{
p = (char[]) { c1, c2, c3 };
}
// warning: using dangling pointer 'p' to an unnamed temporary
return *p;
}In the next function, storing the address of the local variable x into the escaped pointer *p triggers the warning at level 1 💅
void g (int **p)
{
int x = 7;
// warning: storing the address of local variable 'x' in '*p'
*p = &x;
}In this one, the array a is out of scope by the time the pointer s gets used. Since the code that sets s is conditional, the warning triggers at level 2:
extern void frob (const char *);
void h (char *s)
{
if (!s)
{
char a[12] = "tmpname";
s = a;
}
// warning: dangling pointer 's' to 'a' may be used
frob (s);
}-Wdate-time— warns when the macros__TIME__,__DATE__or__TIMESTAMP__show up, since they might stop your builds from being bit-wise-identical and reproducible ⏰-Wempty-body— warns if an empty body shows up in anif,elseordo whilestatement. This warning is also enabled by-Wextra🫶-Wno-endif-labels— stops the warnings about stray tokens after#elseand#endif🙈-Wenum-compare— warns about a comparison between values of different enumerated types. In C++, enumerated type mismatches in conditional expressions also get diagnosed, and this warning is enabled by default there. In C, it's enabled by-Wall🔥-Wenum-conversion— warns when a value of enumerated type gets implicitly converted to a different enumerated type. In C, this warning is enabled by-Wextra🌈-Wenum-int-mismatch(C and Objective-C only) — warns about mismatches between an enumerated type and an integer type in declarations. For example:
enum E { l = -1, z = 0, g = 1 };
int foo(void);
enum E foo(void);In C, an enumerated type is compatible with char, a signed integer type, or an unsigned integer type. But since the choice of the underlying type of an enumerated type is implementation-defined, these mismatches can cause portability issues. In C++, such mismatches are an error. In C, this warning is enabled by -Wall and -Wc++-compat 👑
okay so this one is about jumping over variables 🦋
-Wjump-misses-init(C, Objective-C only) — this warns if agotoor aswitchhops forward past the initialization of a variable, or jumps backward to a label after that variable has already been set up. It only cares about variables that get initialized right where they're declared. This one is only for C and Objective-C, because in C++ this kind of jump is already an error anyway 💅-Wjump-misses-initis part of-Wc++-compat🫶 and you can switch it off with the-Wno-jump-misses-initoption 🌸-Wsign-compare— compare vibes check 👑 this warns when you compare signed and unsigned values and the result could be wrong because the signed one gets converted to unsigned. In C++ it's also turned on by-Wall, and in C it's turned on by-Wextra✨-Wsign-conversion— this one catches implicit conversions that might flip the sign of an integer, like shoving a signed integer expression into an unsigned integer variable 🙈 An explicit cast will shut it up. In C,-Wconversionalso turns this on 🎀-Wflex-array-member-not-at-end(C and C++ only) — not it 💀 this warns when a struct with a C99 flexible array member as its last field ends up sitting in the middle of another struct. Here's the kind of thing it's talking about:
struct flex { int length; char data[]; };
struct mid_flex { int m; struct flex flex_data; int n; };-Wfloat-conversion— warns about implicit conversions that lower the precision of a real value. That covers real to integer, and higher precision real to lower precision real 🧚 This one is also enabled by-Wconversion🍓-Wno-scalar-storage-order— bye bye suspicious stuff 🌈 this stops the warnings about questionable constructs involving reverse scalar storage order ✨-Wsizeof-array-div— warns when you divide twosizeofoperators and the first one is applied to an array, but the divisor isn't the size of an array element. The math won't give you the number of elements, which is almost definitely not what you meant 😭 Here's an example it would flag:
int fn ()
{
int arr[10];
return sizeof (arr) / sizeof (short);
}This warning is enabled by -Wall 💖
-Wsizeof-pointer-div— this flags suspicious divisions of twosizeofexpressions that divide the pointer size by the element size. That's the usual trick for getting an array's length, but it totally falls apart with pointers 💀 It warns about"sizeof (ptr) / sizeof (ptr[0])"when"ptr"is a pointer and not an array. This warning is enabled by-Wall🔥-Wsizeof-pointer-memaccess— warns about sketchy length arguments to certain string and memory built-in functions when the argument usessizeof. It goes off for things likememset (ptr, 0, sizeof (ptr));whenptris really a pointer, and it even suggests a possible fix. It also catchesmemcpy (&foo, ptr, sizeof (&foo));🙈 This option also warns about bounded string copy functions likestrncatorstrncpywhen the bound is asizeofon the source array. Check out this one:
void make_file (const char *name)
{
char path[PATH_MAX];
strncpy (path, name, sizeof path - 1);
strncat (path, ".text", sizeof ".text");
...
}In that function, the strncat call uses the size of the source string as its bound. That's almost certainly a mistake, so it gets diagnosed 🚨
This option is enabled by -Wall 🎀
-Wno-sizeof-array-argument— chill, it's fine 🌸 this turns off the warning for whensizeofis applied to a parameter that's declared as an array in a function definition. This warning is on by default for C and C++ programs 🫶-Wmemset-elt-size— warns about shadymemsetbuilt-in calls where the first argument points to an array, and the third argument is a number equal to the element count but not equal to the array's full size in memory. That usually means you forgot to multiply by the element size 💅 This one is enabled by-Wall✨-Wmemset-transposed-args— warns about suspiciousmemsetbuilt-in calls where the second argument isn't zero and the third argument is zero. For example,memset (buf, sizeof buf, 0)gets flagged, becausememset (buf, 0, sizeof buf)was what you meant 👑 The diagnostic only shows up if the third argument is a literal zero. If it's an expression that folds down to zero, or a cast of zero to some type, the arguments are way less likely to be transposed by mistake, so no warning is emitted 🦋 This warning is enabled by-Wall🍓-Waddress— suspicious address alert 🚨 this warns about dodgy address expressions. That includes comparing the address of a function or a declared object to a null pointer constant, like this:
void f (void);
void g (void)
{
if (!f) // warning: expression evaluates to false
abort ();
}It also includes comparing a pointer to a string literal:
void f (const char *x)
{
if (x == "abc") // warning: expression evaluates to false
puts ("equal");
}And testing the result of pointer addition or subtraction for equality to null:
void f (const int *p, int i)
{
return p + i == NULL;
}These uses usually point to a programmer error. The address of most functions and objects always evaluates to true (weak symbols are the exception), so using them in a conditional might mean you're missing parentheses in a function call or a dereference in an array expression 😭
The part about object pointers can be silenced by casting the pointer operand to an integer type like intptr_t or uintptr_t 🫶 Comparing against string literals leads to unspecified behavior and isn't portable, and it suggests you probably meant to call strcmp 💜 The warning is also suppressed if the suspicious expression came from macro expansion. The -Waddress warning is enabled by -Wall 🌈
-Wno-address-of-packed-member— don't warn about this one 🧚 this stops the warning for when the address of a packed member of a struct or union gets taken, which usually ends up as an unaligned pointer value. This is enabled by default 🍓-Wlogical-op— warns about suspicious uses of logical operators in expressions, including places where a bitwise operator was probably what you wanted 🤔 It also warns when both operands of a logical operator are the same:
extern int a;
if (a < 0 && a < 0) { ... }-Wlogical-not-parentheses— warns when a logical not is used on the left-hand side of a comparison. It won't warn if the right operand is a boolean expression. The whole point is catching sus code like this 🙈
int a;
...
if (!a > 1) { ... }You can make the warning go away by wrapping the left-hand side in parentheses:
if ((!a) > 1) { ... }This warning is enabled by -Wall 💅
-Waggregate-return— warns if any functions that return structs or unions are defined or called 💖 (In languages where you can return an array, this also triggers a warning.)-Wno-aggressive-loop-optimizations— this one is about loops 🔁 it warns if, in a loop with a constant number of iterations, the compiler detects undefined behavior in some statement during one or more of the iterations ✨-Wno-attributes— attribute drama 💜 this stops the warning when an unexpected__attribute__shows up, like unrecognized attributes, function attributes slapped onto variables, and so on. It doesn't stop errors for incorrectly using attributes that are supported 🫶
Warnings about ill-formed uses of standard attributes get upgraded to errors by -pedantic-errors 😭
You can also use -Wno-attributes= to suppress warnings about unknown scoped attributes (in C++11 and C23) 🧚 For example, -Wno-attributes=vendor::attr disables the warning for this declaration:
[[vendor::attr]] void f();Or you can disable warnings about all attributes in a namespace with -Wno-attributes=vendor::, which covers both of these declarations:
[[vendor::safe]] void f();
[[vendor::unsafe]] void f2();Just remember that -Wno-attributes= does not imply -Wno-attributes 💀
-Wno-builtin-declaration-mismatch— built-in beef 🍋 this warns if a built-in function is declared with an incompatible signature, or as something that isn't a function. It also fires when a built-in function declared without a prototype gets called with arguments whose promoted types don't match what the function expects. With-Wextra, it also warns when a built-in that takes arguments is declared without a prototype. The-Wbuiltin-declaration-mismatchwarning is on by default 🌸 To dodge it, include the right header so the built-in prototypes are in scope ✨
In this example, the memset call gets flagged because the function expects a size_t argument, but 32 is an int. With -Wextra, the declaration of the function gets flagged too 👑
extern void* memset ();
void f (void *d)
{
memset (d, '\0', 32);
}-Wno-builtin-macro-redefined— stops warnings when certain built-in macros get redefined 🦋 This silences redefinitions of__TIMESTAMP__,__TIME__,__DATE__,__FILE__, and__BASE_FILE__💜-Wstrict-prototypes(C and Objective-C only) — warns if a function is declared or defined without specifying its argument types 🎀 An old-style function definition is fine without a warning, as long as it's preceded by a declaration that does specify the argument types 💅-Wold-style-declaration(C and Objective-C only) — this one goes after old C habits 🕰️ It warns about declarations the C Standard calls obsolescent, like a storage-class specifier such asstaticshowing up somewhere other than the very front of the declaration. It's also turned on by-Wextra✨-Wold-style-definition(C and Objective-C only) — warns whenever you write an old-style function definition, and it still speaks up even if you already gave that function a prototype 🙄 Quick heads up: a definition using()isn't treated as old-style in C23 mode, since it means the same thing as(void)there. For older standards, though, it does count as old-style. 💅-Wmissing-parameter-type(C and Objective-C only) — catches K&R-style functions where a parameter is declared without a type specifier, like this:
void foo(bar) { }This warning is also enabled by -Wextra 🎀
-Wno-declaration-missing-parameter-type(C and Objective-C only) — the "don't yell at me" flag for function declarations that have a parameter name but no type. Those declarations don't give you a function prototype, so they block most type checking in function calls, which is literally chaos 💀
This warning is enabled by default. In C99 and later dialects of C, it's treated as an error 🚨 You can downgrade it to a warning with -fpermissive (along with certain other errors), or downgrade this one error alone with -Wno-error=declaration-missing-parameter-type.
This warning gets upgraded to an error by -pedantic-errors 😭
-Wmissing-prototypes(C and Objective-C only) — warns if a global function is defined without a previous prototype declaration. It still warns even when the definition itself has a prototype, so it's a great way to catch global functions that don't have a matching prototype in a header file 🦋
This option isn't valid for C++, because all function declarations there provide prototypes, and a non-matching declaration just declares an overload instead of conflicting with an earlier one. For missing declarations in C++, use -Wmissing-declarations instead 🧚
-Wmissing-variable-declarations(C and Objective-C only) — warns if a global variable is defined without a previous declaration. Use it to catch global variables that don't have a matchingexterndeclaration in a header file 🌸-Wmissing-declarations— warns if a global function is defined without a previous declaration, and does so even if the definition provides a prototype. Use it to find global functions that aren't declared in header files 🔍
In C, there are no warnings for functions with previous non-prototype declarations, so use -Wmissing-prototypes to catch missing prototypes there. In C++, there are no warnings for function templates, inline functions, or functions in anonymous namespaces ✨
-Wmissing-field-initializers— warns if a structure's initializer is missing some fields. In this example,x.his implicitly zero, so it triggers the warning:
struct s { int f, g, h; };
struct s x = { 3, 4 };In C, this option doesn't warn about designated initializers, so this modification doesn't trigger a warning:
struct s { int f, g, h; };
struct s x = { .f = 3, .g = 4 };In C, this option also doesn't warn about the universal zero initializer { 0 }:
struct s { int f, g, h; };
struct s x = { 0 };Likewise, in C++ this option doesn't warn about the empty { } initializer:
struct s { int f, g, h; };
s x = { };This warning is included in -Wextra. To get the other -Wextra warnings without this one, use -Wextra -Wno-missing-field-initializers 🫶
-Wno-missing-requires— by default, the compiler warns about a concept-id showing up as a C++20 simple-requirement, like this:
bool satisfied = requires { C<T> };Here, satisfied will be true if C<T> is a valid expression, which it is for all T. Presumably the user meant to write this:
bool satisfied = requires { requires C<T> };That way, satisfied is only true if concept C is satisfied for type T 👑
This warning can be disabled with -Wno-missing-requires.
-Wno-missing-template-keyword— the member access tokens.,->and::have to be followed by thetemplatekeyword if the parent object is dependent and the member being named is a template. Check out the vibe:
template <class X>
void DoStuff (X x)
{
x.template DoSomeOtherStuff<X>(); // Good.
x.DoMoreStuff<X>(); // Warning, x is dependent.
}In rare cases, you can get false positives. To silence that, wrap the expression in parentheses. For example, the following is treated as a template, even where m and N are integers:
void NotATemplate (my_class t)
{
int N = 5;
bool test = t.m < N > (0); // Treated as a template.
test = (t.m < N) > (0); // Same meaning, but not treated as a template.
}This warning can be disabled with -Wno-missing-template-keyword 🙈
-Wno-multichar— don't warn if a multicharacter constant ('FOOF') is used. These usually signal a typo in your code, since they have implementation-defined values and shouldn't be used in portable code 🍓-Wnormalized=[none|id|nfc|nfkc]— okay, this one is a whole mood 🌈 In ISO C and ISO C++, two identifiers are different if they're different sequences of characters. But sometimes, when characters outside basic ASCII are used, you can get two different character sequences that look exactly the same. To avoid that confusion, the ISO 10646 standard sets normalization rules that turn look-alike sequences into the same sequence. GCC can warn you if your identifiers haven't been normalized, and this option controls that warning.
There are four levels of warning. The default is -Wnormalized=nfc, which warns about any identifier that isn't in the ISO 10646 "C" normalized form, NFC. NFC is the recommended form for most uses, and it's equivalent to -Wnormalized.
Unfortunately, some characters that ISO C and ISO C++ allow in identifiers stop being allowed once they're turned into NFC. So there's no way to use those symbols in portable ISO C or C++ and still have all your identifiers in NFC. -Wnormalized=id suppresses the warning for those characters. The hope is that future versions of the standards will fix this, which is why this option isn't the default 🥺
You can switch the warning off for all characters with -Wnormalized=none or -Wno-normalized.
⚠️ Only do this if you're using some other normalization scheme (like "D"), because otherwise you can easily create bugs that are literally impossible to see 👀
Some characters in ISO 10646 have distinct meanings but look identical in some fonts or display methods, especially once formatting has been applied. For instance, "\u207F", "SUPERSCRIPT LATIN SMALL LETTER N", displays just like a regular "n" that's been placed in a superscript. ISO 10646 defines the NFKC normalization scheme to convert all of these into a standard form too, and GCC warns if your code isn't in NFKC when you use -Wnormalized=nfkc. This is comparable to warning about every identifier that contains the letter O, because it might be confused with the digit 0. So it isn't the default, but it can be a useful local coding convention if your programming environment can't be fixed to display these characters distinctly 🔤
-Wno-attribute-warning— don't warn about usage of functions declared with the "warning" attribute. This warning is enabled by default. Use-Wno-attribute-warningto disable the warning, or-Wno-error=attribute-warningto disable the error when compiled with the-Werrorflag 🫧-Wno-deprecated— don't warn about usage of deprecated features 🦋-Wno-deprecated-declarations— don't warn about uses of functions, variables, and types marked as deprecated with the "deprecated" attribute 🌷-Wno-overflow— don't warn about compile-time overflow in constant expressions 🔢-Wno-odr— warns about One Definition Rule violations during link-time optimization. It's enabled by default ⭐-Wopenacc-parallelism— warns about potentially suboptimal choices related to OpenACC parallelism 🚀-Wno-openmp— warns about suspicious OpenMP code 🧐-Wopenmp-simd— warns if the vectorizer cost model overrides the OpenMP simd directive you set. The-fsimd-cost-model=unlimitedoption can be used to relax the cost model 🌈-Woverride-init(C and Objective-C only) — warns if an initialized field without side effects gets overridden when you're using designated initializers 💜
This warning is included in -Wextra. To get the other -Wextra warnings without this one, use -Wextra -Wno-override-init 🎀
-Wno-override-init-side-effects(C and Objective-C only) — don't warn if an initialized field with side effects gets overridden when you're using designated initializers. This warning is enabled by default 🍭-Wpacked— warns if a structure is given thepackedattribute, but that attribute has no effect on the layout or size of the structure. Those structures may end up misaligned for little benefit 😬 Here, the variablef.xinstruct baris misaligned, even thoughstruct bardoesn't have the packed attribute itself:
struct foo {
int x;
char a, b, c, d;
} __attribute__((packed));
struct bar {
char z;
struct foo f;
};-Wnopacked-bitfield-compat— the 4.1, 4.2 and 4.3 series of GCC ignore thepackedattribute on bit-fields of typechar. That got fixed in GCC 4.4, but the change can lead to differences in structure layout. GCC tells you when the offset of such a field has changed in GCC 4.4. For example, in this structure there's no longer a 4-bit padding between fieldaandb:
struct foo
{
char a:4;
char b:8;
} __attribute__ ((packed));This one's on by default, bestie 💖 but if it's being extra, you can mute it with -Wno-packed-bitfield-compat 🙈
-Wpacked-not-aligned— C, C++, Objective-C and Objective-C++ only 💅 Warns if a field with an explicitly set alignment, sitting inside a packed struct or union, ends up misaligned. In this code you'll get"warning: alignment 1 of 'struct S' is less than 8", so watch out 👀
struct __attribute__ ((aligned (8))) S8 { char a[8]; };
struct __attribute__ ((packed)) S {
struct S8 s8;
};This one is enabled by -Wall ✨
-Wpadded— Flags any padding the compiler sneaks into a struct, whether it's lining up one element or the whole struct. Sometimes you can shuffle the fields around to cut the padding and make the struct smaller 🦋-Wredundant-decls— Warns if something gets declared more than once in the same scope, even when that's legal and changes nothing 🙄-Wrestrict— Warns when an object referenced by arestrict-qualified parameter (or a__restrict-qualified one in C++) gets aliased by another argument, or when copies between those objects overlap. In the example below,strcpyis trying to chop off the front of the string by copying the last four characters over the first ones. But the call also writes the terminating NUL intoa[4], so the copies overlap and GCC catches it 🚨
void foo (void)
{
char a[] = "abcd1234";
strcpy (a, a + 4);
...
}-Wrestrict can catch some simple overlaps even without optimization, but it works best at -O2 and above. It's included in -Wall 💜
-Wnested-externs— C and Objective-C only 🌸 Warns if anexterndeclaration shows up inside a function-Winline— Warns if a function declaredinlinecan't actually be inlined. Even with this on, GCC won't warn about failures to inline functions declared in system headers 🙃
GCC uses a whole bag of heuristics to decide whether to inline something. It looks at things like how big the function being inlined is, and how much inlining has already happened in the current function. So even seemingly tiny edits to your source can make -Winline warnings appear or disappear 🌀
-Winterference-size— Warns about using C++17'sstd::hardware_destructive_interference_sizewithout setting its value with--param destructive-interference-size. It also warns about questionable values for that option 🧐
This is meant for class layout, so concurrent code doesn't suffer from false sharing 🫶
struct independent_fields {
alignas(std::hardware_destructive_interference_size)
std::atomic<int> one;
alignas(std::hardware_destructive_interference_size)
std::atomic<int> two;
};The whole idea is that one and two are far enough apart that a store to one won't force a reload of the cache line two lives on 💅
By default, --param destructive-interference-size and --param constructive-interference-size are set based on the current -mtune option. That's typically the L1 cache line size for the particular target CPU, though sometimes it's a range if you're tuning for a generic target.
So every translation unit that depends on ABI compatibility for these variables must be compiled with the same-mtune(or-mcpu). ⚠️
If ABI stability matters, like if you're using this in a header for a library, you should probably not use the hardware interference size variables at all. Alternatively, you can force a particular value with --param 🎀
If you're confident your use of the variable doesn't affect ABI outside a single build of your project, you can turn off the warning with -Wno-interference-size 🧚
-Wint-in-bool-context— Warns about sus integer usage where a boolean is expected 👀 Think conditional expressions (?:) using non-boolean integer constants in a boolean context, likeif (a <= b ? 2 : 3). Or left-shifting signed integers in a boolean context, likefor (a = 0; 1 << a; a++);. The same goes for all kinds of multiplications, no matter the data type. Enabled by-Wall🔥-Wno-int-to-pointer-cast— Suppresses warnings about casts to a pointer type from an integer of a different size.
In C++, casting to a pointer type of smaller size is an error. 💀
-Wint-to-pointer-cast is enabled by default 🍓
-Wno-pointer-to-int-cast— C and Objective-C only 🌈 Suppresses warnings about casts from a pointer to an integer type of a different size-Winvalid-pch— Warns if a precompiled header is found in the search path but can't be used 🥲-Winvalid-utf8— Warns if an invalid UTF-8 character is found. This one's on by default for C++23 when-finput-charset=UTF-8is used, and it gets turned into an error with-pedantic-errors🌸-Wno-unicode— Stops GCC from diagnosing invalid forms of delimited or named escape sequences that get treated as separate tokens.-Wunicodeis enabled by default ✨-Wlong-long— Warns if thelong longtype is used. This is enabled by either-Wpedanticor-Wtraditionalin ISO C90 and C++98 modes. To inhibit the messages, use-Wno-long-long📏
This warning gets upgraded to an error by -pedantic-errors 🚫
-Wvariadic-macros— Warns if variadic macros are used in ISO C90 mode, or if the GNU alternate syntax is used in ISO C99 mode. This is enabled by either-Wpedanticor-Wtraditional. To inhibit the warning messages, use-Wno-variadic-macros🧩-Wno-varargs— Stops warnings about questionable usage of the macros that handle variable arguments, likeva_start. These warnings are enabled by default 🙅-Wvector-operation-performance— Warns if a vector operation isn't implemented via the SIMD capabilities of the architecture. It's mainly useful for performance tuning 🏎️ A vector operation can be implemented "piecewise", meaning the scalar operation runs on every vector element. It can be implemented "in parallel", meaning it uses scalars of a wider type, which is normally more performance efficient. Or it can be implemented "as a single scalar", meaning the vector fits into a scalar type.-Wvla— Warns if a variable-length array is used in the code.-Wno-vlaprevents the-Wpedanticwarning about variable-length arrays. This warning is upgraded to an error by-pedantic-errors🚫-Wvla-larger-than=byte-size— If you use this, the compiler warns for declarations of variable-length arrays whose size is either unbounded, or bounded by an argument that lets the array size exceedbyte-sizebytes. It's kind of like how-Walloca-larger-than=byte-sizeworks, but for VLAs 📐
GCC may optimize small variable-length arrays of a known value into plain arrays, so this warning may not get triggered for those 🤓
-Wvla-larger-than=PTRDIFF_MAX is enabled by default, but it's typically only effective when -ftree-vrp is active, which is the default for -O2 and above 🧠
See also -Walloca-larger-than=byte-size 👀
-Wno-vla-larger-than— Disables-Wvla-larger-than=warnings. The option is equivalent to-Wvla-larger-than=SIZE_MAXor larger 🛑-Wvla-parameter— Warns about redeclarations of functions involving arguments of Variable Length Array types with inconsistent kinds or forms. It also enables detection of out-of-bounds accesses to those parameters by warnings like-Warray-bounds🧮 If the first function declaration uses the VLA form, the bound in the array is assumed to be the minimum number of elements expected in calls to the function, and the maximum number of elements it accesses. Passing arguments that are too small, or accessing more than that maximum, may be diagnosed.
For example, the warning triggers for these redeclarations. The first one allows an array of any size to be passed to f, while the second one says the array argument must have at least n elements. Calling f with the associated VLA bound parameter in excess of the actual VLA bound triggers a warning as well 🫠
void f (int n, int[n]);
// warning: argument 2 previously declared as a VLA
void f (int, int[]);
void g (int n)
{
if (n > 4)
return;
int a[n];
// warning: access to a by f may be out of bounds
f (sizeof a, a);
...
}-Wvla-parameter is included in -Wall. -Warray-parameter triggers warnings for similar problems involving ordinary array arguments 🌈
-Wvolatile-register-var— Warns if a register variable is declaredvolatile. Heads up, thevolatilemodifier doesn't inhibit all optimizations that may eliminate reads and/or writes to register variables. This warning is enabled by-Wall💅-Wno-xor-used-as-pow— C, C++, Objective-C and Objective-C++ only 🤔 Disables warnings about uses of^, the exclusive or operator, where it looks like you meant exponentiation. Specifically, the warning happens when the left-hand side is the decimal constant2or10and the right-hand side is also a decimal constant.
In C and C++, ^ means exclusive or, whereas in some other languages (like TeX and some versions of BASIC) it means exponentiation ✨
This warning can be silenced by converting one of the operands to hexadecimal, as well as by compiling with -Wno-xor-used-as-pow 🫶
-Wdisabled-optimization— Warns if a requested optimization pass is disabled. This doesn't generally mean anything is wrong with your code. It just means GCC's optimizers can't handle the code effectively 🐢 Often the problem is that your code is too big or too complex, since GCC refuses to optimize programs when the optimization itself would likely take inordinate amounts of time.-Wpointer-sign(C and Objective-C only) — okay bestie, this one yells when a pointer gets passed or assigned with a different signedness 💅- This only works for C and Objective-C 🎀
- It's already switched on by
-Walland-Wpedantic, and you can turn it off with-Wno-pointer-sign🙈 -pedantic-errorsupgrades it into an error 💀
-Wstack-protector— this one is only active when-fstack-protectoris on 🛡️ It warns about functions that aren't protected against stack smashing 😭-Woverlength-strings— this one warns about string constants that go past the "minimum maximum" length from the C standard ✨- Modern compilers are super chill and let strings get way longer than that minimum, but very portable programs should avoid longer strings 🧚
- The limit applies after string concatenation, and it doesn't count the trailing NUL. In C90 the limit was 509 characters, and in C99 it got raised to 4095 📏
- C++98 doesn't set a normative minimum maximum, so GCC doesn't diagnose overlength strings in C++ 🌈
-Wpedanticimplies it, and you can disable it with-Wno-overlength-strings🫶
-Wunsuffixed-float-constants(C and Objective-C only) — this warns for any floating constant that doesn't have a suffix 🦋- Add
-Wsystem-headersand it'll also warn about those constants in system header files 👀 - It's giving prep work for the
"FLOAT_CONST_DECIMAL64"pragma from the decimal floating-point extension to C99 💜
- Add
-Wno-lto-type-mismatch— during link-time optimization, this stops GCC from warning about type mismatches in global declarations across different compilation units 🌸 It needs-fltoto be enabled, and it's enabled by default ✨-Wno-designated-init(C and Objective-C only) — this suppresses warnings when a positional initializer is used on a structure marked with the"designated_init"attribute 🎀
🔍 Options That Control Static Analysis
-fanalyzer— okay this one is the big boss 👑 It enables a static analysis of program flow that hunts for "interesting" interprocedural paths through the code, and it warns you about problems it finds on them 🔥- It's way more expensive than other GCC warnings, so be patient bestie ⏳
- In technical terms, it does coverage-guided symbolic execution of the code being compiled 🤓
- It is neither sound nor complete, so it can have false positives and false negatives 🙈 It's a bug-finding tool, not a tool for proving program correctness 💅
- In this release, the analyzer is only suitable for use on C code 🌸
- Turning this on effectively enables these warnings:
-Wanalyzer-allocation-size -Wanalyzer-deref-before-check
-Wanalyzer-double-fclose -Wanalyzer-double-free
-Wanalyzer-exposure-through-output-file
-Wanalyzer-exposure-through-uninit-copy
-Wanalyzer-fd-access-mode-mismatch -Wanalyzer-fd-double-close
-Wanalyzer-fd-leak -Wanalyzer-fd-phase-mismatch
-Wanalyzer-fd-type-mismatch -Wanalyzer-fd-use-after-close
-Wanalyzer-fd-use-without-check -Wanalyzer-file-leak
-Wanalyzer-free-of-non-heap -Wanalyzer-imprecise-fp-arithmetic
-Wanalyzer-infinite-loop -Wanalyzer-infinite-recursion
-Wanalyzer-jump-through-null -Wanalyzer-malloc-leak
-Wanalyzer-mismatching-deallocation -Wanalyzer-null-argument
-Wanalyzer-null-dereference -Wanalyzer-out-of-bounds
-Wanalyzer-overlapping-buffers -Wanalyzer-possible-null-argument
-Wanalyzer-possible-null-dereference -Wanalyzer-putenv-of-auto-var
-Wanalyzer-shift-count-negative -Wanalyzer-shift-count-overflow
-Wanalyzer-stale-setjmp-buffer -Wanalyzer-tainted-allocation-size
-Wanalyzer-tainted-array-index -Wanalyzer-tainted-assertion
-Wanalyzer-tainted-divisor -Wanalyzer-tainted-offset
-Wanalyzer-tainted-size -Wanalyzer-undefined-behavior-strtok
-Wanalyzer-unsafe-call-within-signal-handler
-Wanalyzer-use-after-free
-Wanalyzer-use-of-pointer-in-stale-stack-frame
-Wanalyzer-use-of-uninitialized-value
-Wanalyzer-va-arg-type-mismatch -Wanalyzer-va-list-exhausted
-Wanalyzer-va-list-leak -Wanalyzer-va-list-use-after-va-end
-Wanalyzer-write-to-const -Wanalyzer-write-to-string-literal- This only works if GCC was configured with analyzer support enabled 🔧
-Wanalyzer-symbol-too-complex— the analyzer uses heuristics to track the state of memory, but sufficiently complicated code can totally defeat them 😵💫- By default, if an expression goes past the threshold set by
--param analyzer-max-svalue-depth=value, the analysis quietly stops tracking its values and falls back to an imprecise representation 🫠 - This option warns you when that happens 🚨
- By default, if an expression goes past the threshold set by
-Wanalyzer-too-complex— the analyzer tries to explore control flow and data flow, but again, sufficiently complicated code can defeat it 🌀- By default the analysis silently stops if the code is too complicated and it hits an internal limit 🤐
- This option warns you when that happens 📣
-Wno-analyzer-allocation-size— this warning needs-fanalyzerto be enabled, and you can switch it off with-Wno-analyzer-allocation-size🙅♀️- It warns for paths through the code where a pointer to a buffer gets assigned to point at a buffer whose size isn't a multiple of
sizeof (*pointer)📐 - See CWE-131: Incorrect Calculation of Buffer Size,
"https://cwe.mitre.org/data/definitions/131.html"🔗
- It warns for paths through the code where a pointer to a buffer gets assigned to point at a buffer whose size isn't a multiple of
-Wno-analyzer-deref-before-check— this one needs-fanalyzertoo, and you disable it with-Wno-analyzer-deref-before-check🙃- It warns for paths where a pointer gets checked for
NULLafter it's already been dereferenced, which suggests the pointer could've been NULL all along 😳 Either the check is redundant, or it needs to move to before the dereference 💁♀️ - It also treats values passed to a function argument marked with
__attribute__((nonnull))as needing to be non-NULL, so it'll complain if those values get checked forNULLafter the function call returns 🧐 - > This one is unlikely to show up when any level of optimization is on, because GCC's optimizer usually sees those
NULLchecks as redundant and deletes them before the analyzer gets a look 🙈 So turn optimization off if you're trying to trigger it 💀
- It warns for paths where a pointer gets checked for
-Wno-analyzer-double-fclose— needs-fanalyzer, and you can disable it with-Wno-analyzer-double-fclose🎀- It warns for paths where a
FILE *can havefclosecalled on it more than once 📁 - See CWE-1341: Multiple Releases of Same Resource or Handle,
"https://cwe.mitre.org/data/definitions/1341.html"🔗
- It warns for paths where a
-Wno-analyzer-double-free— needs-fanalyzer, and use-Wno-analyzer-double-freeto disable it 🧹- It warns for paths where a pointer can have a deallocator called on it more than once, either
free, or a deallocator referenced by attributemalloc🗑️ - See CWE-415: Double Free,
"https://cwe.mitre.org/data/definitions/415.html"🔗
- It warns for paths where a pointer can have a deallocator called on it more than once, either
-Wno-analyzer-exposure-through-output-file— needs-fanalyzer, and you turn it off with-Wno-analyzer-exposure-through-output-file🤫- It warns for paths where a security-sensitive value gets written to an output file, like writing a password to a log file 🔐
- See CWE-532: Information Exposure Through Log Files,
"https://cwe.mitre.org/data/definitions/532.html"🔗
-Wanalyzer-exposure-through-uninit-copy— this one needs both-fanalyzerand a plugin that specifies a function copying across a "trust boundary" 🧩 Use-Wno-analyzer-exposure-through-uninit-copyto disable it 🙅♀️- It warns about "infoleaks", which are paths where uninitialized values get copied across a security boundary, like code inside an OS kernel copying a partially-initialized struct from the stack over to user space 😱
- See CWE-200: Exposure of Sensitive Information to an Unauthorized Actor,
"https://cwe.mitre.org/data/definitions/200.html"🔗
-Wno-analyzer-fd-access-mode-mismatch— needs-fanalyzer, and you can disable it with-Wno-analyzer-fd-access-mode-mismatch📂- It warns for paths where a "read" is attempted on a write-only file descriptor, or the other way around 🔄
- It also warns for code paths where a function with attribute
fd_arg_read (N)is called with a file descriptor opened withO_WRONLYat referenced argumentN, or where a function with attributefd_arg_write (N)is called with a file descriptor opened withO_RDONLYat referenced argument N 🧾
-Wno-analyzer-fd-double-close— needs-fanalyzer, and you disable it with-Wno-analyzer-fd-double-close✌️- It warns for paths where a file descriptor can be closed more than once 🚪
- See CWE-1341: Multiple Releases of Same Resource or Handle,
"https://cwe.mitre.org/data/definitions/1341.html"🔗
-Wno-analyzer-fd-leak— needs-fanalyzer, and use-Wno-analyzer-fd-leakto disable it 💧- It warns for paths where an open file descriptor gets leaked 🫗
- See CWE-775: Missing Release of File Descriptor or Handle after Effective Lifetime,
"https://cwe.mitre.org/data/definitions/775.html"🔗
-Wno-analyzer-fd-phase-mismatch— needs-fanalyzer, and you disable it with-Wno-analyzer-fd-phase-mismatch⏰- It warns for paths where an operation gets attempted in the wrong phase of a file descriptor's lifetime 🕰️ For example, it'll warn if you try to call
accepton a stream socket that hasn't hadlistensuccessfully called on it yet 🧦 - See CWE-666: Operation on Resource in Wrong Phase of Lifetime,
"https://cwe.mitre.org/data/definitions/666.html"🔗
- It warns for paths where an operation gets attempted in the wrong phase of a file descriptor's lifetime 🕰️ For example, it'll warn if you try to call
-Wno-analyzer-fd-type-mismatch 🦋
Okay so this one needs -fanalyzer to be switched on, which turns it on for you. To silence it, use -Wno-analyzer-fd-type-mismatch. 💅
It catches paths through your code where an operation gets run on the wrong type of file descriptor. Like trying socket operations on an fd you got from open, or doing a stream socket operation on a datagram socket. Not it. 🙅♀️
-Wno-analyzer-fd-use-after-close 🌸
Also needs -fanalyzer to be enabled. Use -Wno-analyzer-fd-use-after-close to turn it off. 🫶
This one flags paths where a read or write gets called on a file descriptor that's already been closed. 💀 It also catches functions with the attribute fd_arg (N), fd_arg_read (N), or fd_arg_write (N) getting called with a closed fd at the referenced argument N. Main character energy, but make it a closed file descriptor and it's a whole mess. 😭
-Wno-analyzer-fd-use-without-check 🧚
Needs -fanalyzer, obviously. Disable it with -Wno-analyzer-fd-use-without-check. ✨
This warns on paths where a file descriptor gets used without anyone checking whether it's valid first. 🙈 It also warns when a function marked with fd_arg (N), fd_arg_read (N), or fd_arg_write (N) gets handed a file descriptor at referenced argument N without a validity check. Always check your fds, bestie. 🔥
-Wno-analyzer-file-leak 🍓
Requires -fanalyzer. Use -Wno-analyzer-file-leak to turn it off. 🎀
This one lights up paths through the code where a FILE * stream object from <stdio.h> gets leaked. Like, you opened it and just... never let it go. 😤
Go peep CWE-775: Missing Release of File Descriptor or Handle after Effective Lifetime, which is at https://cwe.mitre.org/data/definitions/775.html. 💜
-Wno-analyzer-free-of-non-heap 💖
Needs -fanalyzer to run. Silence it with -Wno-analyzer-free-of-non-heap. 🦋
It warns on paths where free gets called on a pointer that isn't on the heap. Think an on-stack buffer, or a global. You can't free something that was never heap-allocated, sweetie. 💀
See CWE-590: Free of Memory not on the Heap at https://cwe.mitre.org/data/definitions/590.html. 🌈
-Wno-analyzer-imprecise-fp-arithmetic ⭐
Requires -fanalyzer. Turn it off with -Wno-analyzer-imprecise-fp-arithmetic. 🌸
This one catches paths where floating-point arithmetic shows up in places that really need precise computation. 🧐 Right now, it only warns about floating-point operands used inside the calculation of an allocation size. That's the whole vibe for now. ✨
-Wno-analyzer-infinite-loop 🔥
Needs -fanalyzer. Disable it with -Wno-analyzer-infinite-loop. 💅
This diagnostic warns on paths that seem to lead into an infinite loop. 🌀
Specifically, the analyzer will throw this warning when it notices a loop where all of these are true:
- nothing externally visible can actually get done inside the loop
- there's no way to escape from the loop
- the analyzer is confident enough about the program state throughout the loop to know both of the above are true
One way this shows up is when there's a path through a loop where taking it on one iteration means the same path gets taken on every iteration after that. Honestly iconic, but also a trap. 🪤
Here's an example:
while (1)
{
char opcode = *cpu_state.pc;
switch (opcode)
{
case OPCODE_FOO:
handle_opcode_foo (&cpu_state);
break;
case OPCODE_BAR:
handle_opcode_bar (&cpu_state);
break;
}
}The analyzer will absolutely side-eye this one. If opcode ever matches none of the cases, the switch falls through to its implicit default case. That makes the loop body a no-op, cpu_state.pc never changes, and opcode stays the same on every iteration after. Now you're stuck in an infinite loop forever. 😭
See CWE-835: Loop with Unreachable Exit Condition ('Infinite Loop') at https://cwe.mitre.org/data/definitions/835.html. 🫶
-Wno-analyzer-infinite-recursion 🌀
Needs -fanalyzer. Use -Wno-analyzer-infinite-recursion to turn it off. 🎀
This one flags paths that look like they're headed for infinite recursion. 🔁 Here's how it works: whenever the analyzer sees a recursive call, it compares the state of memory at the entry of the new frame with the state at the entry of the previous frame for that same function on the stack. If nothing in memory seems to be changing, it warns. But if it spots any changes to parameters or globals, it assumes the recursion will eventually end and keeps quiet. 🤫
Heads up: this diagnostic is likely to miss infinite recursion that the optimizer turns into iteration before the analyzer gets a look. So if you're trying to trigger this one on purpose, disable optimization first. 🙃
Compare this with -Winfinite-recursion, which gives you a similar diagnostic but is implemented in a totally different way. 💜
See CWE-674: Uncontrolled Recursion at https://cwe.mitre.org/data/definitions/674.html. 🌸
-Wno-analyzer-jump-through-null 🦋
Requires -fanalyzer. Disable it with -Wno-analyzer-jump-through-null. 💅
This warns on paths where a NULL function pointer gets called. Calling nothing is not a vibe. 🙅♀️
-Wno-analyzer-malloc-leak 🍓
Needs -fanalyzer. Use -Wno-analyzer-malloc-leak to silence it. ✨
It warns on paths where a pointer allocated through an allocator gets leaked. The allocator can be malloc, or any function marked with the attribute malloc. 💀
See CWE-401: Missing Release of Memory after Effective Lifetime at https://cwe.mitre.org/data/definitions/401.html. 🫶
-Wno-analyzer-mismatching-deallocation 🧚
Requires -fanalyzer. Turn it off with -Wno-analyzer-mismatching-deallocation. 🌈
This one warns on paths where the wrong deallocation function gets called on a pointer, based on which function originally allocated it. 🙃 It will warn about mismatches between free, scalar delete, and vector delete[]. It also covers anything marked as an allocator/deallocator pair using the attribute malloc. Pair your allocs and deallocs properly, bestie. 🫶
See CWE-762: Mismatched Memory Management Routines at https://cwe.mitre.org/data/definitions/762.html. 💖
-Wno-analyzer-out-of-bounds 🔥
Needs -fanalyzer. Disable it with -Wno-analyzer-out-of-bounds. 💅
This diagnostic warns on paths where a buffer is definitely read or written out-of-bounds. It applies when the analyzer can work out a constant offset, and for accesses past the end of a buffer with a constant capacity. It also does some limited checking for accesses past the end when both the offset and the capacity are symbolic. 🧠
See CWE-119: Improper Restriction of Operations within the Bounds of a Memory Buffer at https://cwe.mitre.org/data/definitions/119.html. 🌸
When the analyzer can manage it, it'll even draw you a text art diagram of the memory involved. 🎨 It shows how the region the analyzer thinks gets accessed compares to the range that's actually valid: whether they overlap, touch, or sit far apart, which one comes first in memory, the relative sizes, whether it's a read or a write, and sometimes the data values involved. Lowkey the coolest part. ✨ You can hide the diagram with -fdiagnostics-text-art-charset=none. 🙈
-Wno-analyzer-overlapping-buffers 🌈
Needs -fanalyzer. Use -Wno-analyzer-overlapping-buffers to turn it off. 🦋
This one warns on paths where overlapping buffers get passed to an API that has undefined behaviour for that kind of input. 😬 Specifically, it fires on calls to these functions:
memcpystrcatstrcpy
...but only when the buffers are known to overlap. 🫶
-Wno-analyzer-possible-null-argument 🍓
Requires -fanalyzer. Disable it with -Wno-analyzer-possible-null-argument. 🎀
This warns on paths where a value that might be NULL gets passed to a function argument marked with __attribute__((nonnull)), which says it needs a non-NULL value. 🤔
See CWE-690: Unchecked Return Value to NULL Pointer Dereference at https://cwe.mitre.org/data/definitions/690.html. 💜
-Wno-analyzer-possible-null-dereference 🌸
Needs -fanalyzer. Silence it with -Wno-analyzer-possible-null-dereference. ✨
This one warns on paths where a value that might be NULL gets dereferenced. 😬
See CWE-690: Unchecked Return Value to NULL Pointer Dereference at https://cwe.mitre.org/data/definitions/690.html. 🫶
-Wno-analyzer-null-argument 🦋
Requires -fanalyzer. Use -Wno-analyzer-null-argument to turn it off. 💅
This warns on paths where a value the analyzer knows is NULL gets passed to a function argument marked with __attribute__((nonnull)). 🚫
See CWE-476: NULL Pointer Dereference at https://cwe.mitre.org/data/definitions/476.html. 🔥
-Wno-analyzer-null-dereference 💖
Needs -fanalyzer. Disable it with -Wno-analyzer-null-dereference. 🌈
This one warns on paths where a value known to be NULL gets dereferenced. Big yikes. 💀
See CWE-476: NULL Pointer Dereference at https://cwe.mitre.org/data/definitions/476.html. 🧚
-Wno-analyzer-putenv-of-auto-var ⭐
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-putenv-of-auto-var to disable it. 🌸
Okay so this bit is all about putenv 🌸 It warns about paths through the code where a call to putenv gets handed a pointer to an automatic variable or an on-stack buffer. Big nope, bestie 🙅♀️
See POS34-C. The rule is "Do not call putenv() with a pointer to an automatic variable as the argument" 💅 (https://wiki.sei.cmu.edu/confluence/x/6NYxBQ).
-Wno-analyzer-shift-count-negative— 🔥 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-shift-count-negative. It flags paths where a shift is attempted with a negative count. It's the sibling of the-Wshift-count-negativewarning from the C/C++ front ends, except it works by analyzing interprocedural paths instead of just reading the syntax tree. Lowkey, the analyzer doesn't prioritise finding these, so false negatives are more likely than with other warnings 🙈-Wno-analyzer-shift-count-overflow— ✨ Also requires-fanalyzer, which enables it, and you disable it with-Wno-analyzer-shift-count-overflow. This one catches paths where a shift count is greater than or equal to the precision of the operand's type. It's the analyzer's take on-Wshift-count-overflowfrom the C/C++ front ends, again built on interprocedural paths rather than the syntax tree. Same deal as before: the analyzer doesn't prioritise these, so false negatives are more likely compared to other warnings 💀-Wno-analyzer-stale-setjmp-buffer— 🦋 Needs-fanalyzer, which enables it, and-Wno-analyzer-stale-setjmp-bufferturns it off. It warns for paths wherelongjmpis called to rewind to ajmp_buftied to asetjmpcall in a function that has already returned. Whensetjmprecords a rewind location on ajmp_buf, it records the stack frame, and that frame becomes invalid once the function containing thesetjmpcall returns. Trying to rewind to it withlongjmpmeans referencing a stack frame that doesn't exist anymore, which will likely lead to a crash (or worse) 😭-Wno-analyzer-tainted-allocation-size— 🧚 Requires-fanalyzer, which enables it, and you can silence it with-Wno-analyzer-tainted-allocation-size. It warns for paths where a value an attacker could control gets used as the size of an allocation without being sanitised, so an attacker could inject a massively huge allocation and cause a denial of service attack. See CWE-789: Memory Allocation with Excessive Size Value (https://cwe.mitre.org/data/definitions/789.html) 🫶-Wno-analyzer-tainted-assertion— 👑 This one also needs-fanalyzer, and-Wno-analyzer-tainted-assertionis how you disable it. It warns for paths where an attacker-controllable value gets used as part of a condition without being sanitised first, and that condition guards a call to a function marked with thenoreturnattribute (like__builtin_unreachable). Those functions usually mean the program is terminating abnormally, like assertion failure handlers. For example:
assert (some_tainted_value < SOME_LIMIT);In such cases:
- when assertion-checking is enabled: an attacker could trigger a denial of service by injecting an assertion failure
- when assertion-checking is disabled, such as by defining
NDEBUG, an attacker could inject data that subverts the process, since it presumably violates a precondition that is being assumed by the code.
Note that when assertion-checking is disabled, the assertions are typically removed by the preprocessor before the analyzer has a chance to "see" them, so this diagnostic can only generate warnings on builds in which assertion-checking is enabled 🎀
For the purpose of this warning, any function marked with the noreturn attribute counts as a possible assertion failure handler, including __builtin_unreachable. These functions are sometimes removed by the optimizer before the analyzer "sees" them, so optimization should be disabled when you're trying to trigger this diagnostic.
See CWE-617: Reachable Assertion (https://cwe.mitre.org/data/definitions/617.html).
The warning can also report problematic constructions such as:
switch (some_tainted_value) {
case 0:
/* [...etc; various valid cases omitted...] */
break;
default:
__builtin_unreachable (); /* BUG: attacker can trigger this */
}despite the above not being an assertion failure, strictly speaking 🙃
-Wno-analyzer-tainted-array-index— 🌈 Needs-fanalyzer, which enables it, and-Wno-analyzer-tainted-array-indexswitches it off. It warns for paths where an attacker-controllable value is used as the index of an array access without being sanitised, so an attacker could inject an out-of-bounds access. See CWE-129: Improper Validation of Array Index (https://cwe.mitre.org/data/definitions/129.html) 💖-Wno-analyzer-tainted-divisor— ⭐ Requires-fanalyzer, which enables it, and you disable it with-Wno-analyzer-tainted-divisor. It warns for paths where an attacker-controllable value is used as the divisor in a division or modulus operation without being sanitised, so an attacker could inject a division-by-zero. See CWE-369: Divide By Zero (https://cwe.mitre.org/data/definitions/369.html) 🍓-Wno-analyzer-tainted-offset— 🌸 Needs-fanalyzer, which enables it, and-Wno-analyzer-tainted-offsetturns it off. It warns for paths where an attacker-controllable value is used as a pointer offset without being sanitised, so an attacker could inject an out-of-bounds access. See CWE-823: Use of Out-of-range Pointer Offset (https://cwe.mitre.org/data/definitions/823.html) ✨-Wno-analyzer-tainted-size— 💜 Requires-fanalyzer, which enables it, and you can silence it with-Wno-analyzer-tainted-size. It warns for paths where an attacker-controllable value is used as the size of an operation such asmemsetwithout being sanitised, so an attacker could inject an out-of-bounds access. See CWE-129: Improper Validation of Array Index (https://cwe.mitre.org/data/definitions/129.html) 🫶-Wno-analyzer-undefined-behavior-strtok— 🔥 Needs-fanalyzer, which enables it, and-Wno-analyzer-undefined-behavior-strtokdisables it. It warns for paths where a call is made tostrtokthat has undefined behavior. Specifically, passing NULL as the first parameter for the initial call tostrtokwithin a process is undefined behavior, so watch out 👀-Wno-analyzer-unsafe-call-within-signal-handler— 🦋 Requires-fanalyzer, which enables it, and you turn it off with-Wno-analyzer-unsafe-call-within-signal-handler. It warns for paths where a function known to be async-signal-unsafe (likefprintf) gets called from a signal handler. See CWE-479: Signal Handler Use of a Non-reentrant Function (https://cwe.mitre.org/data/definitions/479.html) 🧚-Wno-analyzer-use-after-free— 🌈 Needs-fanalyzer, which enables it, and-Wno-analyzer-use-after-freeis your off switch. It warns for paths where a pointer is used after a deallocator has been called on it, eitherfreeor a deallocator referenced by themallocattribute. See CWE-416: Use After Free (https://cwe.mitre.org/data/definitions/416.html) 💀-Wno-analyzer-use-of-pointer-in-stale-stack-frame— 🙈 Requires-fanalyzer, which enables it, and you disable it with-Wno-analyzer-use-of-pointer-in-stale-stack-frame. It warns for paths where a pointer is dereferenced that points to a variable in a stale stack frame.-Wno-analyzer-va-arg-type-mismatch— 👑 Needs-fanalyzer, which enables it, and-Wno-analyzer-va-arg-type-mismatchturns it off. It warns for interprocedural paths where the analyzer detects an attempt to useva_argto extract a value passed to a variadic call, but the type used doesn't match the type of the expression passed to the call. See CWE-686: Function Call With Incorrect Argument Type (https://cwe.mitre.org/data/definitions/686.html) 💅-Wno-analyzer-va-list-exhausted— 🍓 Requires-fanalyzer, which enables it, and you can silence it with-Wno-analyzer-va-list-exhausted. It warns for interprocedural paths where the analyzer detects an attempt to useva_argto access the next value passed to a variadic call, but every value in theva_listhas already been consumed. See CWE-685: Function Call With Incorrect Number of Arguments (https://cwe.mitre.org/data/definitions/685.html) 🌸-Wno-analyzer-va-list-leak— ✨ Needs-fanalyzer, which enables it, and-Wno-analyzer-va-list-leakdisables it. It warns for interprocedural paths where the analyzer detects thatva_startorva_copyhas been called on ava_listwithout a corresponding call tova_end.-Wno-analyzer-va-list-use-after-va-end— 🧚 Requires-fanalyzer, which enables it, and you turn it off with-Wno-analyzer-va-list-use-after-va-end. It warns for interprocedural paths where the analyzer detects an attempt to use ava_listafterva_endhas been called on it.va_list.-Wno-analyzer-write-to-const— 💜 This warning requires-fanalyzer, which enables it; use-Wno-analyzer-write-to-constto disable it.
Okay bestie, this one's the analyzer side-eyeing your writes 👀. It warns about paths where it spots an attempt to write through a pointer to a const object 🎀 The catch is that the analyzer doesn't prioritize hunting these down, so false negatives (missed issues) are more likely than with other warnings 💀
-Wno-analyzer-write-to-string-literal🌸 This one needs-fanalyzerto be on, since that's what turns it on. Use-Wno-analyzer-write-to-string-literalto switch it off. It warns about paths where the analyzer sees a write through a pointer to a string literal. Same deal as before: it doesn't prioritize these paths, so false negatives are more likely than with other warnings.-Wno-analyzer-use-of-uninitialized-value🦋 Also requires-fanalyzer(which enables it), and you can disable it with-Wno-analyzer-use-of-uninitialized-value. It warns about paths where an uninitialized value gets used.
See CWE-457: Use of Uninitialized Variable (https://cwe.mitre.org/data/definitions/457.html).
The analyzer already has hardcoded knowledge about how these memory-management functions behave 🧠✨
alloca- The built-in functions
__builtin_alloc,__builtin_alloc_with_align,__builtin_calloc,__builtin_free,__builtin_malloc,__builtin_memcpy,__builtin_memcpy_chk,__builtin_memset,__builtin_memset_chk,__builtin_realloc,__builtin_stack_restore, and__builtin_stack_save callocfreemallocmemsetoperator deleteoperator delete []operator newoperator new []reallocstrdupstrndup
It also knows about these file descriptor functions 🫶
openclosecreatdup,dup2anddup3isattypipe, andpipe2readwritesocket,bind,listen,accept, andconnect
And these <stdio.h> stream functions 🌈
- The built-in functions
__builtin_fprintf,__builtin_fprintf_unlocked,__builtin_fputc,__builtin_fputc_unlocked,__builtin_fputs,__builtin_fputs_unlocked,__builtin_fwrite,__builtin_fwrite_unlocked,__builtin_printf,__builtin_printf_unlocked,__builtin_putc,__builtin_putchar,__builtin_putchar_unlocked,__builtin_putc_unlocked,__builtin_puts,__builtin_puts_unlocked,__builtin_vfprintf, and__builtin_vprintf fopenfcloseferrorfgetsfgets_unlockedfilenofreadgetcgetcharfprintfprintffwrite
And finally, a grab bag of other functions 💅
- The built-in functions
__builtin_expect,__builtin_expect_with_probability,__builtin_strchr,__builtin_strcpy,__builtin_strcpy_chk,__builtin_strlen,__builtin_va_copy, and__builtin_va_start - The GNU extensions
erroranderror_at_line getpasslongjmpputenvsetjmpsiglongjmpsignalsigsetjmpstrcatstrchrstrlen
Also, various functions with an __analyzer_ prefix have special meaning to the analyzer. Those are described in the GCC Internals manual 📖🔥
Pertinent parameters for controlling the exploration (aka how far the analyzer digs) are:
--param analyzer-bb-explosion-factor=value--param analyzer-max-enodes-per-program-point=value--param analyzer-max-recursion-depth=value--param analyzer-min-snodes-for-call-summary=value
The following options control the analyzer, so let's get into it 🍓
-fanalyzer-call-summaries— This simplifies interprocedural analysis (checking across function calls) by computing the effect of certain calls, instead of exploring every path through the function from the callsite to each possible return. 🧚
If enabled, call summaries are only used for functions with more than one call site, and that are sufficiently complicated (as per --param analyzer-min-snodes-for-call-summary=value).
-fanalyzer-checker=name— Restricts the analyzer to running just the named checker, and enables it 🎯-fanalyzer-debug-text-art-headings— This one's for analyzer developers 🛠️ When enabled, the analyzer adds extra annotations to any diagrams it generates.-fno-analyzer-feasibility— Also for analyzer developers. By default the analyzer checks that there's a feasible control flow path for each diagnostic it emits, meaning the conditions that hold aren't mutually exclusive. Diagnostics where no feasible path can be found get rejected. This filtering can be suppressed with-fno-analyzer-feasibility, which is handy for debugging issues in this code 🙈-fanalyzer-fine-grained— Developer-only again 💜 Internally the analyzer builds an "exploded graph" that combines control flow graphs with data flow information. By default, an edge in this graph can contain the effects of a run of multiple statements within a basic block. With-fanalyzer-fine-grained, each statement gets its own edge.-fanalyzer-show-duplicate-count— For analyzer developers: if multiple diagnostics have been detected as duplicates of each other, it emits a note when reporting the best diagnostic. That note gives the number of additional diagnostics the deduplication logic suppressed ✨-fanalyzer-show-events-in-system-headers— By default the analyzer emits simplified diagnostic paths by hiding events fully located within a system header. With-fanalyzer-show-events-in-system-headers, those events are no longer suppressed 👑-fno-analyzer-state-merge— Developer territory 🧑💻 By default the analyzer tries to simplify things by merging sufficiently similar states at each program point as it builds its "exploded graph". With-fno-analyzer-state-merge, that merging gets suppressed, which is useful for debugging state-handling issues.-fno-analyzer-state-purge— Also for developers 🫠 By default the analyzer purges aspects of state at a program point that seem no longer relevant. For example, that's the values of locals that aren't accessed later in the function and aren't relevant to leak analysis. With-fno-analyzer-state-purge, that purging gets suppressed, for debugging state-handling issues.-fno-analyzer-suppress-followups— Developer-only 🧪 By default the analyzer stops exploring an execution path after hitting certain diagnostics, so it doesn't spam a cascade of follow-up diagnostics. The diagnostics that end analysis along a path are:-Wanalyzer-null-argument-Wanalyzer-null-dereference-Wanalyzer-use-after-free-Wanalyzer-use-of-pointer-in-stale-stack-frame-Wanalyzer-use-of-uninitialized-value
With -fno-analyzer-suppress-followups, the analyzer keeps exploring those paths even after such diagnostics. That can help with debugging the analyzer, or with microbenchmarks for detecting undefined behavior.
-fanalyzer-transitivity— Turns on transitivity of constraints within the analyzer 🔗-fno-analyzer-undo-inlining— Developer-only 🧩-fanalyzerruns relatively late compared to other code analysis tools, and some optimizations may have already been applied. In particular, function inlining may have happened, which can leave the interprocedural execution paths with function frames that don't match the original source code. By default the analyzer tries to reconstruct the original function frames and emits events showing the inlined calls. With-fno-analyzer-undo-inlining, that attempt to reconstruct the original frame information gets disabled, which can help when debugging analyzer issues.-fanalyzer-verbose-edges— For analyzer developers. It enables more verbose, lower-level detail in the descriptions of control flow within diagnostic paths 🌀-fanalyzer-verbose-state-changes— Also for analyzer developers. It enables more verbose, lower-level detail in the descriptions of state machine events within diagnostic paths 🌙-fanalyzer-verbosity=level— This controls how complex the control flow paths emitted for analyzer diagnostics are. The level can be one of:0— At this level, interprocedural call and return events are displayed, along with the most pertinent state-change events for a diagnostic. For example, for a double-"free" diagnostic, both calls tofreewill be shown.1— Same as the previous level, but it also shows events for the entry to each function.2— Same as the previous level, but it also shows control flow events that are significant to triggering the issue (e.g. "true path taken" at a conditional). This level is the default. 💖3— Same as the previous level, but shows all control flow events, not just significant ones.4— For analyzer developers. It adds various other events intended for debugging the analyzer 🧯
-fdump-analyzer— Dumps internal details about what the analyzer is doing tofile.analyzer.txt.-fdump-analyzer-stderroverrides this option.-fdump-analyzer-stderr— Dumps internal details about what the analyzer is doing to stderr. This option overrides-fdump-analyzer.-fdump-analyzer-callgraph— Dumps a representation of the call graph that's suitable for viewing with GraphViz tofile.callgraph.dot🗺️-fdump-analyzer-exploded-graph— Dumps a representation of the "exploded graph" suitable for viewing with GraphViz tofile.eg.dot. Nodes are color-coded based on state-machine states to emphasize state changes 🎨-fdump-analyzer-exploded-nodes— Emits diagnostics showing where nodes in the "exploded graph" sit in relation to the program source 📍-fdump-analyzer-exploded-nodes-2— Dumps a textual representation of the "exploded graph" tofile.eg.txt📝-fdump-analyzer-exploded-nodes-3— okay so this one dumps a textual version of the "exploded graph" with one dump file per node, namedfile.eg-id.txt📂. Heads up bestie, that's usually a huge pile of files 😭💀.-fdump-analyzer-exploded-paths— dumps a textual "exploded path" for every diagnostic, intofile.idx.kind.epath.txt✨.-fdump-analyzer-feasibility— this spills the tea on the analyzer's search for feasible paths 🔍. It's written so you can view it with GraphViz, intofile.*.fg.dot,file.*.tg.dot, andfile.*.fpath.txt🦋.-fdump-analyzer-infinite-loop— internal details about the analyzer's hunt for infinite loops 🌀. Also GraphViz-friendly, saved asfile.*.infinite-loop.dot💜.-fdump-analyzer-json— a compressed JSON version of analyzer internals, saved tofile.analyzer.json.gz🎀. The precise format is subject to change, so don't build your whole life on it 💅.-fdump-analyzer-state-purge— same vibe as-fdump-analyzer-supergraph, a GraphViz-ready supergraph 🧚, but this one is annotated with what state gets purged at each node 🫶. It's written tofile.state-purge.dot.-fdump-analyzer-supergraph— gives you GraphViz dumps of the "supergraph" infile.supergraph.dotandfile.supergraph-eg.dot🌈. These show every control flow graph in the program, with interprocedural edges for calls and returns 👑. The second dump also has annotations showing nodes in the "exploded graph" and the diagnostics attached to them ✨.-fdump-analyzer-untracked— emits custom warnings packed with internal details, made for analyzer developers only 🙈.
✨ Options for Debugging Your Program ✨
Okay so if you want GCC to hand your debugger all the info, bestie, you really only need to add -g to your other options 💖. Some debug formats can hang out together (like DWARF with CTF) as long as you turn each one on explicitly with its own command line option 🌸.
You're allowed to use -g with -O, and it's honestly kinda iconic 💅. Optimized code gets a little sneaky though 👻: some variables you declared may not exist at all, flow of control might briefly jump somewhere you didn't expect 😭, some statements won't run because they compute constant results or their values are already at hand 💀, and some statements may run in different places since they got moved out of loops 🌀. Still, you can debug optimized output, which makes the optimizer totally reasonable for programs that might have bugs 🔥.
If you aren't using some other optimization option, consider using -Og with -g 🧚. With no -O option at all, some compiler passes that collect debugging-friendly info don't run, so -Og may give you a better debugging experience 🦋.
-g— this makes debugging info in the operating system's native format (stabs, COFF, XCOFF, or DWARF), and GDB can work with it 💜.- On most systems that use stabs,
-gturns on extra info that only GDB can use 🙈. That makes debugging way better in GDB, but other debuggers might crash or refuse to read the program 😭. If you want to be 100% certain whether the extra info gets generated, use-gvms(see below).
- On most systems that use stabs,
-ggdb— debugging info made for GDB 🌈. It uses the most expressive format available (DWARF, stabs, or the native format if neither of those are supported), and it includes GDB extensions if at all possible ✨.-gdwarf,-gdwarf-version— debugging info in DWARF format, if that's supported 🦋. Theversioncan be 2, 3, 4 or 5. The default is 5 for most targets, except VxWorks, TPF and Darwin / macOS (which default to version 2) and AIX (which defaults to version 4) 🍓.- With DWARF Version 2, some ports require and always use some non-conflicting DWARF 3 extensions in the unwind tables 🧚.
- Version 4 may require GDB 7.0 and
-fvar-tracking-assignmentsto get the maximum benefit 💅. Version 5 requires GDB 8.0 or higher 🔥. - GCC no longer supports DWARF Version 1, which is substantially different from Version 2 and later 💀. For historical reasons, some other DWARF-related options such as
-fno-dwarf2-cfi-asm)still have a reference to DWARF Version 2 in their names, but they apply to all currently-supported versions of DWARF 🫶.
-gbtf— requests BTF debug info 🎀. BTF is the default debugging format for the eBPF target 👑. On other targets, like x86, BTF debug info can be generated along with DWARF debug info when both formats are enabled explicitly through their respective command line options 💖.-gctf,-gctflevel— requests CTF debug info, and theleveldecides how much CTF info you get 🌸. If you use-gctfwithout a value forlevel, the default level is 2 ✨.- CTF debug info can be generated along with DWARF debug info when both formats are enabled explicitly through their respective command line options 🦋.
- Level 0 produces no CTF debug info at all, so
-gctf0negates-gctf💀. - Level 1 produces CTF info for tracebacks only. That includes callsite info, but not type info 🧚.
- Level 2 produces type info for entities (functions, data objects etc.) at file-scope or global-scope only 🌈.
-gvms— produces debugging info in the Alpha/VMS debug format (if that's supported) 🍓. It's the format used by DEBUG on Alpha/VMS systems 💜.-gcodeview— produces debugging info in the CodeView debug format (if that's supported) 🪟. It's the format Microsoft Visual C++ uses on Windows 👑.-glevel,-ggdblevel,-gvmslevel— requests debugging info and useslevelto decide how much info you get 🫶. The default level is 2 💅.- Level 0 produces no debug info at all, so
-g0negates-g💀. - Level 1 produces minimal info, enough for making backtraces in parts of the program you don't plan to debug 🔍. That includes descriptions of functions and external variables, plus line number tables, but no info about local variables 🙈.
- Level 3 includes extra info, such as all the macro definitions present in the program 🎀. Some debuggers support macro expansion when you use
-g3✨. - If you use multiple
-goptions, with or without level numbers, the last one is the one that takes effect ⭐. -gdwarfdoes not accept a concatenated debug level, to avoid confusion with-gdwarf-level. Instead, use an additional-gleveloption to change the debug level for DWARF 🦋.
- Level 0 produces no debug info at all, so
-fno-eliminate-unused-debug-symbols— by default, no debug info is produced for symbols that aren't actually used 🧹. Use this if you want debug info for all symbols 🌸.-femit-class-debug-always— instead of emitting debugging info for a C++ class in only one object file, this emits it in all object files that use the class 💜. Only use this with debuggers that can't handle the way GCC normally emits class debug info, because it increases the size of debugging info by as much as a factor of two 😭.-fno-merge-debug-strings— tells the linker not to merge together strings in the debugging info that are identical across different object files 🧵. Merging isn't supported by all assemblers or linkers 💀. It decreases the size of the debug info in the output file, at the cost of longer link processing time 🐢. Merging is enabled by default ✨.-fdebug-prefix-map=old=new— when compiling files in directoryold, debugging info describes them as if they lived in directorynewinstead 🗺️. This is handy for swapping a build-time path for an install-time path in the debug info 🫶. You can also turn an absolute path into a relative one by using.fornew🦋. This can give you more reproducible builds, which are location independent, but you might need an extra command to tell GDB where to find the source files 🔍. See also-ffile-prefix-mapand-fcanon-prefix-map💖.-fvar-tracking— runs the variable tracking pass, which computes where variables are stored at each position in the code 🧠. Better debug info gets generated afterwards (if the debugging info format supports it) 👑.- It's enabled by default when compiling with optimization (
-Os,-O,-O2, ...), debugging info (-g), and a debug info format that supports it 🌈.
- It's enabled by default when compiling with optimization (
-fvar-tracking-assignments— annotates assignments to user variables early in compilation and tries to carry those annotations all the way to the end, to improve debug info while optimizing 🪄. Using-gdwarf-4is recommended alongside it 💅.- It can be enabled even if var-tracking is disabled. In that case the annotations are created and maintained, but discarded at the end 🧹.
- By default, this flag is enabled together with
-fvar-tracking, except when selective scheduling is enabled 🙈.
-gsplit-dwarf— if DWARF debug info is enabled, this separates as much of it as possible into a separate output file with the.dwoextension 📦. This lets the build system avoid linking files with debug info 🧵. To be useful, it requires a debugger that can read.dwofiles 🔍.-gdwarf32,-gdwarf64— if DWARF debug info is enabled,-gdwarf32selects the 32-bit DWARF format and-gdwarf64selects the 64-bit one 🌸. The default is target specific, but on most targets it's-gdwarf32💜.- The 32-bit format is smaller, but it can't support more than 2GiB of debug info in any of the DWARF debug info sections 😭.
- The 64-bit format allows larger debug info, but it might not be well supported by all consumers yet 🐢.
-gdescribe-dies— adds description attributes to some DWARF DIEs that have no name attribute 🧚. Examples are artificial variables, external references and call site parameter DIEs ✨.-gpubnames— generates the DWARF ".debug_pubnames" and ".debug_pubtypes" sections 🎀.-ggnu-pubnames— okay bestie, this one makes the.debug_pubnamesand.debug_pubtypessections in a format that can get turned into a GDB index 🧚. Heads up though, it's only useful if your linker can produce GDB index version 7 💅-fdebug-types-section— when you're on DWARF Version 4 or higher, type DIEs can get their own.debug_typessection instead of living in.debug_info🦋 It's more efficient to stick them in a separate comdat section, since the linker can then remove duplicates ✨ But not every DWARF consumer supports.debug_typesyet, and on some objects it makes the debugging info bigger instead of smaller 💀-grecord-gcc-switches,-gno-record-gcc-switches— this one tacks the command-line options that might affect code generation onto theDW_AT_producerattribute in your DWARF debugging info 🎀 They're joined with spaces, separating them from each other and from the compiler version. It's on by default! Also see-frecord-gcc-switchesif you want another way to store compiler options in the object file 🌸-gstrict-dwarf— no extensions from a later DWARF standard version than the one you picked with-gdwarf-version🙅♀️ On most targets, using non-conflicting extensions from later standard versions is totally allowed.-gno-strict-dwarf— the opposite energy: you are allowed to use extensions from a later DWARF standard version than the one picked with-gdwarf-version🌈-gas-loc-support— tells the compiler that your assembler supports.locdirectives, so it can use them to generate DWARF2+ line number tables 🧚 This is usually the move, because assembler-generated line-number tables are way more compact than the ones the compiler makes itself 💖 It's enabled by default if the assembler was found to support these directives when GCC was configured ✨-gno-as-loc-support— forces GCC to generate DWARF2+ line number tables internally, if they're going to be generated at all 🙈-gas-locview-support— tells the compiler your assembler supports "view" assignment and reset assertion checking in.locdirectives 🦋 It's enabled by default if the assembler was found to support them at configure time 💅-gno-as-locview-support— forces GCC to assign view numbers internally, if you've explicitly asked for-gvariable-location-views🫶-gcolumn-info,-gno-column-info— puts location column information into your DWARF debugging info, not just file and line 📍 It's on by default, bestie 🍓-gstatement-frontiers,-gno-statement-frontiers— GCC drops markers in its internal representation at the start of statements and keeps them roughly in place through the whole compile 🧚 It uses them to guide where theis_stmtmarkers show up in the line number table. This is enabled by default when you compile with optimization (-Os,-O1,-O2, ...) and output DWARF 2 debug info at the normal level 👑-gvariable-location-views,-gvariable-location-views=incompat5,-gno-variable-location-views— augments variable location lists with progressive view numbers implied by the line number table 🔥 This lets debug info consumers inspect state at certain points in the program, even when no instructions tied to those source locations exist there 👀 If the assembler can't handle view numbers in line number tables, the compiler has to emit the line number table itself, which makes things a little less compact 😭 The augmented tables and location lists are fully backward-compatible, so older consumers can read them, but they also won't get any benefit from them 🫠
This is enabled by default at the normal level of DWARF 2 debug output, as long as the assembler supports it, -fvar-tracking-assignments is enabled, and -gstrict-dwarf isn't. If the assembler doesn't support it, the option can still be on, but it forces GCC to output internal line number tables. And if -ginternal-reset-location-views isn't enabled too, that will most certainly lead to silently mismatching location views 🚨
There's also a proposed representation for view numbers that isn't backward compatible with the location list format introduced in DWARF 5. You can turn it on with -gvariable-location-views=incompat5 🧪 This option may be removed in the future, and it's only a reference implementation of the proposed representation. Debug info consumers aren't expected to support this extended format, so they'd be unable to decode location lists that use it 💀
-ginternal-reset-location-views,-gno-internal-reset-location-views— this one tries to figure out which location views can be dropped from the location view lists ✂️ It needs the compiler to have very accurate insn length estimates, which isn't always the case. It may silently generate incorrect view lists when you're using an assembler that doesn't support location view lists. The GNU assembler will flag any such error as a "view number mismatch" 🙃 It's only enabled on ports that define a reliable estimation function 🔒-ginline-points,-gno-inline-points— generates extended debug info for inlined functions 🧚 Location view tracking markers get inserted at inlined entry points, so address and view numbers can be computed and output in the debug info. This can be turned on independently of location views, in which case the view numbers won't be output. It can only be enabled along with statement frontiers, and it's only enabled by default if location views are enabled 💜-gz[=type]— produces compressed debug sections in DWARF format, if that's supported 🗜️ If you don't give a type, the default depends on what the assembler and linker can do. type can benone(don't compress debug sections) orzlib(use zlib compression in ELF gABI format). If the linker can't write compressed debug sections, the option gets rejected. Otherwise, if the assembler doesn't support them,-gzis silently ignored when producing object files 🫧-femit-struct-debug-baseonly— only emits debug info for struct-like types when the base name of the compilation source file matches the base name of the file where the struct is defined 🎯 This drastically shrinks your debug info, but there can be a big loss in the type info the debugger gets 😬 For a less aggressive option, check out-femit-struct-debug-reduced, and for more detailed control, see-femit-struct-debug-detailed. This option only works with DWARF debug output 🌸-femit-struct-debug-reduced— only emits debug info for struct-like types when the base name of the compilation source file matches the base name of the file where the type is defined. The exception is if the struct is a template or is defined in a system header 🧸 This significantly shrinks your debug info, with some potential loss in type info. For a more aggressive option, see-femit-struct-debug-baseonly, and for more detailed control, see-femit-struct-debug-detailed. Only works with DWARF debug output 💖-femit-struct-debug-detailed[=spec-list]— lets you pick which struct-like types the compiler generates debug info for ✨ The goal is to cut down on duplicate struct debug info across different object files in the same program 🫶 This is the detailed version of-femit-struct-debug-reducedand-femit-struct-debug-baseonly, and it covers most needs 👑
A specification uses this syntax: [dir:|ind:][ord:|gen:](any|sys|base|none)
The optional first word limits the spec to structs that are used directly (dir:) or used indirectly (ind:). A struct type is used directly when it's the type of a variable or a member. Indirect uses come through pointers to structs. In other words, when using an incomplete struct is valid, the use is indirect. For example: struct one direct; struct two * indirect;
The optional second word limits the spec to ordinary structs (ord:) or generic structs (gen:). Generic structs are a little complicated to explain 🤓 In C++, these are non-explicit specializations of template classes, or non-template classes within the above. Other programming languages have generics too, but -femit-struct-debug-detailed doesn't implement them yet 🙃
The third word says which source files the structs should get debug info for. none and any have their normal meanings. base means the base of the name of the file where the type declaration appears has to match the base of the name of the main compilation file. In practice, that means when you compile foo.c, debug info gets generated for types declared in that file and in foo.h, but not in other header files 📄 sys means those types that satisfy base, or that are declared in system or compiler headers, count too.
You may need to experiment to find the best settings for your app 🧪 The default is -femit-struct-debug-detailed=all. This option only works with DWARF debug output 🌈
-fno-dwarf2-cfi-asm— emits DWARF unwind info as a compiler-generated.eh_framesection, instead of using the GAS.cfi_*directives 🧚-fno-eliminate-unused-debug-types— okay so, normally when producing DWARF output, GCC skips debug symbol output for types that are nowhere used in the source file being compiled 🙅♀️ Sometimes you actually want debug info for every type declared in the compilation unit, even unused ones. For example, if you want to cast a value to a type in the debugger that's declared but never used in your program 🔮 More often, though, this just wastes a ton of space 💀
✨ Options That Control Optimization ✨
These options control various sorts of optimizations 🔥 They're the glow-up knobs, bestie 💅
🌸 The Vibe Without Any -O Flag 🌸
Okay so, bestie, if you don't pass any optimization flag at all, the compiler's whole thing is keeping compilation cheap and making debugging act the way you expect 🎀. Statements are basically their own little islands 🏝️. Stop at a breakpoint between statements and you can change a variable's value or move the program counter to any other statement in the function, and you'll get exactly what the source code promised ✨.
Turning on optimization flags is a total glow-up 💅. The compiler tries to boost performance and/or shrink the code size, but the tradeoff is longer compile times and maybe a harder time debugging 😭.
The compiler optimizes based on what it knows about your program 🧠. If you compile multiple files at once into a single output file, it can use info from all of those files when it works on each one 🫶.
Not every optimization has its own flag 🙈. This section only covers the ones that do.
Most optimizations are completely switched off at -O0, or whenever no -O level is set on the command line, even if you add individual optimization flags yourself 💀. And -Og skips plenty of optimization passes too 🦋.
Depending on the target and how GCC was configured, the set of optimizations enabled at each -O level might be a little different from what's listed here 🌈. If you want the exact lineup for your setup, invoke GCC with -Q --help=optimizers and it'll spill every enabled optimization at each level 👑.
🍓 -O and -O1 🍓
-O,-O1— Optimize! This one takes a bit more time to compile, and a lot more memory for a big function 🧠.
With -O, the compiler tries to shrink the code and speed up execution 🏃♀️, but it skips any optimization that would take forever to compile ✨.
-O turns on the following optimization flags:
-fauto-inc-dec -fbranch-count-reg -fcombine-stack-adjustments
-fcompare-elim -fcprop-registers -fdce -fdefer-pop -fdelayed-branch
-fdse -fforward-propagate -fguess-branch-probability -fif-conversion
-fif-conversion2 -finline-functions-called-once -fipa-modref
-fipa-profile -fipa-pure-const -fipa-reference
-fipa-reference-addressable -fmerge-constants -fmove-loop-invariants
-fmove-loop-stores -fomit-frame-pointer -freorder-blocks
-fshrink-wrap -fshrink-wrap-separate -fsplit-wide-types
-fssa-backprop -fssa-phiopt -ftree-bit-ccp -ftree-ccp -ftree-ch
-ftree-coalesce-vars -ftree-copy-prop -ftree-dce
-ftree-dominator-opts -ftree-dse -ftree-forwprop -ftree-fre
-ftree-phiprop -ftree-pta -ftree-scev-cprop -ftree-sink -ftree-slsr
-ftree-sra -ftree-ter -funit-at-a-time💖 -O2 💖
-O2— Optimize even more! GCC does nearly every supported optimization that doesn't involve a space-speed tradeoff 🔥. Compared to-O, it makes compilation slower but gives you faster generated code 🚀.
-O2 turns on all optimization flags specified by -O1. It also turns on the following optimization flags:
-falign-functions -falign-jumps -falign-labels -falign-loops
-fcaller-saves -fcode-hoisting -fcrossjumping -fcse-follow-jumps
-fcse-skip-blocks -fdelete-null-pointer-checks -fdevirtualize
-fdevirtualize-speculatively -fexpensive-optimizations
-ffinite-loops -fgcse -fgcse-lm -fhoist-adjacent-loads
-finline-functions -finline-small-functions -findirect-inlining
-fipa-bit-cp -fipa-cp -fipa-icf -fipa-ra -fipa-sra -fipa-vrp
-fisolate-erroneous-paths-dereference -flra-remat
-foptimize-sibling-calls -foptimize-strlen -fpartial-inlining
-fpeephole2 -freorder-blocks-algorithm=stc
-freorder-blocks-and-partition -freorder-functions
-frerun-cse-after-loop -fschedule-insns -fschedule-insns2
-fsched-interblock -fsched-spec -fstore-merging -fstrict-aliasing
-fthread-jumps -ftree-builtin-call-dce -ftree-loop-vectorize
-ftree-pre -ftree-slp-vectorize -ftree-switch-conversion
-ftree-tail-merge -ftree-vrp -fvect-cost-model=very-cheapHeads up, bestie 🫣: please read the warning under-fgcseabout turning on-O2for programs that use computed gotos. It's important!
NOTE 💅: On Ubuntu 8.10 and later,-D_FORTIFY_SOURCE=2is set by default. On Ubuntu 24.04 and later,-D_FORTIFY_SOURCE=3is set by default instead. Either one kicks in when-Ois set to 2 or higher and adds extra compile-time and run-time checks for several libc functions 🛡️. Want it gone? Specify either-U_FORTIFY_SOURCEor-D_FORTIFY_SOURCE=0🙅♀️.
NOTE 🌈: On Debian 13 and Ubuntu 24.04 and later,-D_TIME_BITS=64together with-D_FILE_OFFSET_BITS=64is set by default on the 32bit architectures armel, armhf, hppa, m68k, mips, mipsel, powerpc and sh4 🧚.
🔥 -O3 🔥
-O3— Optimize yet more!-O3turns on everything-O2does, plus the following optimization flags 👑:
-fgcse-after-reload -fipa-cp-clone -floop-interchange
-floop-unroll-and-jam -fpeel-loops -fpredictive-commoning
-fsplit-loops -fsplit-paths -ftree-loop-distribution
-ftree-partial-pre -funswitch-loops -fvect-cost-model=dynamic
-fversion-loops-for-strides🎀 -O0 🎀
-O0— Reduce compilation time and make debugging produce the expected results ✨. This is the default! 💖
🧚 -Os 🧚
-Os— Optimize for size 🦋.-Osenables all-O2optimizations except the ones that often make code bigger 🙈:
-falign-functions -falign-jumps -falign-labels -falign-loops
-fprefetch-loop-arrays -freorder-blocks-algorithm=stcIt also enables -finline-functions, tells the compiler to tune for code size instead of execution speed, and runs extra optimizations designed to shrink the code 🌸.
🌈 -Ofast 🌈
-Ofast— Disregard strict standards compliance 😤.-Ofastenables all-O3optimizations, plus optimizations that aren't valid for every standard-compliant program 💀. It turns on-ffast-math,-fallow-store-data-racesand the Fortran-specific-fstack-arrays(unless-fmax-stack-var-sizeis specified), and-fno-protect-parens. It turns off-fsemantic-interposition🙃.
🦋 -Og 🦋
-Og— Optimize the debugging experience 🔍.-Ogshould be your go-to level for the standard edit-compile-debug cycle 💖. You get a reasonable amount of optimization while keeping compilation fast and debugging smooth 🫶. It's a better pick than-O0for debuggable code, because some compiler passes that collect debug information are disabled at-O0😭.
Like -O0, -Og completely disables a number of optimization passes, so the individual options that control them do nothing. Otherwise, -Og enables all -O1 optimization flags except the ones that might get in the way of debugging 🧐:
-fbranch-count-reg -fdelayed-branch -fdse -fif-conversion
-fif-conversion2 -finline-functions-called-once
-fmove-loop-invariants -fmove-loop-stores -fssa-phiopt
-ftree-bit-ccp -ftree-dse -ftree-pta -ftree-sra🫧 -Oz 🫧
-Oz— Optimize aggressively for size rather than speed 🍰. This may increase the number of instructions executed if those instructions take fewer bytes to encode.-Ozbehaves similarly to-Os, including turning on most-O2optimizations ✨.
If you use multiple -O options, with or without level numbers, the last one is the one that counts 👑. Periodt 💅.
💜 -f Flags 💜
Options of the form -fflag are machine-independent flags 🫶. Most flags have both a positive and a negative form, and the negative form of -ffoo is -fno-foo 🔄. The table below only lists the form you'll typically use, but you can figure out the other one by either removing no- or adding it 🙌.
The following options control specific optimizations. They're either turned on by -O options or related to ones that are. You only need these in the rare cases where you want to "fine-tune" which optimizations get performed 🎀.
-fno-defer-pop— For machines that have to pop arguments after a function call, this always pops the arguments as soon as each function returns 🧹. At-O1and higher,-fdefer-popis the default, which lets the compiler let arguments pile up on the stack across several function calls and pop them all at once 📚.-fforward-propagate— Performs a forward propagation pass on RTL 🔁. The pass tries to combine two instructions and checks whether the result can be simplified ✨. If loop unrolling is active, two passes run, and the second one is scheduled after loop unrolling 🌀.
This option is enabled by default at optimization levels -O1, -O2, -O3, -Os 💖.
-ffp-contract=style—-ffp-contract=offdisables floating-point expression contraction 🚫.-ffp-contract=fastenables it, such as forming fused multiply-add operations if the target has native support for them 🔥.-ffp-contract=onenables contraction if the language standard allows it 🙆♀️. This is implemented for C and C++, where it allows contraction within one expression, but not across different statements 🧠.
The default is -ffp-contract=off for C in a standards-compliant mode (-std=c11 or similar), and -ffp-contract=fast otherwise 🌈.
-fomit-frame-pointer— Omits the frame pointer in functions that don't need one 🦋. That skips the instructions that save, set up and restore the frame pointer, and on many targets it also frees up an extra register 🫧.
On some targets this flag does nothing, because the standard calling sequence always uses a frame pointer, so it can't be omitted 🙃.
Heads up: -fno-omit-frame-pointer doesn't guarantee the frame pointer gets used in every function. Several targets always omit it in leaf functions 👀.
Enabled by default at -O1 and higher 💖.
-foptimize-sibling-calls— Optimizes sibling and tail recursive calls 🔁. Enabled at levels-O2,-O3,-Os✨.-foptimize-strlen— Optimizes various standard C string functions (e.g."strlen","strchr"or"strcpy") and their_FORTIFY_SOURCEcounterparts into faster alternatives 🏎️. Enabled at levels-O2,-O3💅.-finline-stringops[=fn]— Expands memory and string operations inline (for now, only"memset"), even when the length is variable or big enough to need looping 🧵. This is most useful along with-ffreestandingand-fno-builtin🎀.
In some circumstances it lets the compiler generate code that takes advantage of known alignment and length multipliers. But even then, it may be less efficient than optimized runtime implementations, and it can grow the code so much that a less performant but shared implementation runs faster thanks to better use of code caches 😭. This option is disabled by default 🙈.
-fno-inline— ✨ Okay bestie, this one says don't inline anything unless it's marked with thealways_inlineattribute 🙅♀️. It's the default when you're not optimizing 💅. If you want one specific function to sit out, tag it with thenoinlineattribute 🫶.-finline-small-functions— 🦋 The compiler copies a function into its callers when the body is smaller than the code it'd take to call it, so the whole program actually gets smaller 💖. The compiler makes this call heuristically 🧠, and it applies to every function, even the ones that aren't declaredinline. Enabled at levels-O2,-O3,-Os🔥.-findirect-inlining— 👑 This one inlines indirect calls that become known at compile time because of earlier inlining. It only does anything when inlining is already switched on by-finline-functionsor-finline-small-functions🙈. Enabled at levels-O2,-O3,-Os✨.-finline-functions— 🌈 Every function is up for inlining, even the ones not declaredinline💅. The compiler heuristically picks which ones are worth it. If every call to a given function gets inlined and that function isstatic, it normally won't be emitted as its own assembler code 🧚. Enabled at levels-O2,-O3,-Os, and also turned on by-fprofile-useand-fauto-profile💜.-finline-functions-called-once— 🍓 Anystaticfunction that's called exactly once gets inlined into its caller, even if it isn't markedinline🫶. Once that call is inlined, the function isn't output as assembler code on its own 💀. Enabled at levels-O1,-O2,-O3, and-Os, but not-Og🙅♀️.-fearly-inlining— ⭐ Functions markedalways_inline, plus functions whose body looks smaller than the call overhead, get inlined early, before-fprofile-generateinstrumentation and the real inlining pass 🌸. That makes profiling way cheaper and usually makes inlining faster for programs with big chains of nested wrapper functions 😭. Enabled by default 💖.-fipa-sra— 🔥 Interprocedural scalar replacement of aggregates 🧁, removal of unused parameters 🗑️, and swapping parameters passed by reference for parameters passed by value 🔁. Enabled at levels-O2,-O3,-Os✨.-finline-limit=n— 🎀 This gives you a coarse dial for how big a function can be and still get inlined.nis the size measured in pseudo instructions 📏. Inlining is really controlled by a bunch of parameters you can set one at a time with--param name=value. The-finline-limit=noption sets a couple of them for you:max-inline-insns-singleis set ton/2.max-inline-insns-autois set ton/2.
Check out the individual inlining parameters below for their docs and defaults 📚.
Heads up: there may be no value of -finline-limit that gives you the default behavior 🙈.
Also, a "pseudo instruction" is just an abstract measure of how big a function is 🧚♀️. It has nothing to do with counting assembly instructions, so what it means can change from one release to another 💀.
-fno-keep-inline-dllexport— 🦋 This is the more fine-grained cousin of-fkeep-inline-functions. It only touches functions declared with thedllexportattribute ordeclspec💅.-fkeep-inline-functions— 💜 In C,staticfunctions declaredinlinestill get emitted into the object file, even if they were inlined into every single caller 📦. This doesn't change functions using theextern inlineextension in GNU C90 🙅♀️. In C++, it emits any and all inline functions into the object file 🌈.-fkeep-static-functions— 🫶 Emitsstaticfunctions into the object file even if nothing ever uses them 🧹.-fkeep-static-consts— ✨ Emits variables declaredstatic constwhen optimization is off, even if nothing references them 🎀. GCC turns this on by default 💖. If you want the compiler to check whether a variable is referenced no matter what optimization level you're on, use-fno-keep-static-consts🔍.-fmerge-constants— 🌸 Tries to merge identical constants (string constants and floating-point constants) across compilation units 🧩. This is the default for optimized builds if the assembler and linker support it 👑. To stop it, use-fno-merge-constants🙅♀️. Enabled at levels-O1,-O2,-O3,-Os✨.-fmerge-all-constants— 😭 Tries to merge identical constants and identical variables 🧨. It implies-fmerge-constants, and on top of that it looks at things like constant initialized arrays and initialized constant variables with integral or floating-point types 🧱.
Danger zone 💀: C and C++ require each variable to have its own distinct location, including multiple instances of the same variable in recursive calls. Using this option results in non-conforming behavior, so it's not a vibe 🙈.
-fmodulo-sched— 🔁 Runs swing modulo scheduling right before the first scheduling pass 🎢. It looks at the innermost loops and reorders their instructions by overlapping different iterations 💫.-fmodulo-sched-allow-regmoves— 🚀 This goes harder with SMS-based modulo scheduling and lets register moves happen 💅. Turning it on deletes certain anti-dependence edges, which triggers reg-move generation based on life-range analysis 🧠. It only works if-fmodulo-schedis also on 🫶.-fno-branch-count-reg— 🙅♀️ Turns off the pass that hunts for chances to use "decrement and branch" instructions on a count register 🔢. Those replace the usual sequence of decrementing a register, comparing it to zero, then branching on the result 🌀. This only matters on architectures that have those instructions, like x86, PowerPC, IA-64, and S/390 🖥️. Heads up:-fno-branch-count-regdoesn't remove decrement and branch instructions that other optimization passes already put into the stream 💁♀️. The default is-fbranch-count-regat-O1and higher, except for-Og✨.-fno-function-cse— 🧊 Don't stash function addresses in registers. Instead, every instruction that calls a constant function spells out the function's address explicitly 📍. This makes the code less efficient 😩, but some strange hacks that mess with the assembler output can get confused by the optimizations you'd get without this flag 🙈. The default is-ffunction-cse💜.-fno-zero-initialized-in-bss— 🧸 If the target has a BSS section, GCC normally tosses zero-initialized variables in there, which can save space 📦. This option turns that off 🚫. Why? Some programs explicitly count on variables landing in the data section 🫣, like when the executable needs to find the start of that section or makes assumptions based on it 🗺️. The default is-fzero-initialized-in-bss💖.-fthread-jumps— 🧵 Checks whether a jump lands on a spot where another comparison that the first one already covers shows up 👀. If it does, the first branch gets redirected to the second branch's destination or to the spot right after it 🏃♀️. Which one depends on whether the condition is known to be true or false 🎯. Enabled at levels-O1,-O2,-O3,-Os✨.-fsplit-wide-types— 🧩 When a type takes up multiple registers, likelong longon a 32-bit system, this splits those registers apart and allocates them independently 🍰. That usually makes better code for those types 🚀, but debugging can get harder 😵💫. Enabled at levels-O1,-O2,-O3,-Os💅.-fsplit-wide-types-early— ⏰ Fully splits wide types early instead of waiting until very late 🌅. It does nothing unless-fsplit-wide-typesis on 🙅♀️. This one is the default on some targets 👑.-fcse-follow-jumps— 🦋 During common subexpression elimination (CSE), this scans through jump instructions when nothing else reaches the jump's target 🔍. Like, when CSE hits anifwith anelseclause, it follows the jump when the tested condition is false 🪄. Enabled at levels-O2,-O3,-Os✨.-fcse-skip-blocks— 🌷 Kind of like-fcse-follow-jumps, but this one follows jumps that conditionally skip over blocks 🙃. When CSE sees a simpleifwith no else clause, it follows the jump around the body of theif🎀. Enabled at levels-O2,-O3,-Os🔥.-frerun-cse-after-loop— 🔄 Re-runs common subexpression elimination after loop optimizations are done 🎢. Enabled at levels-O2,-O3,-Os💖.-fgcse— 🌍 Performs a global common subexpression elimination pass 🧠. This pass also does global constant and copy propagation 📋.
Note 💅: If your program uses computed gotos (a GCC extension), you might get better run-time performance by disabling the global CSE pass with -fno-gcse on the command line 🏎️.
Enabled at levels -O2, -O3, -Os ✨.
-fgcse-lm— 🌙 When this is on, global CSE tries to move loads that only get killed by stores into themselves 🧲. That lets a loop with a load/store sequence turn into a load outside the loop and a copy/store inside it 🫶. Enabled by default whenever-fgcseis on 💜.-fgcse-sm— 🚚 When this is on, a store motion pass runs after global CSE 📦. It tries to move stores out of loops 🏃♀️. Combined with-fgcse-lm, loops with a load/store sequence can become a load before the loop and a store after it 🎁. Not enabled at any optimization level 🙈.-fgcse-las— 🧹 When this is on, the global CSE pass gets rid of redundant loads that come right after stores to the same memory location 🧼. That covers both partial and full redundancies 💯. Not enabled at any optimization level 💀.-fgcse-after-reload— okay so when this is turned on, a redundant load elimination pass runs after reload 💅. Its whole job is cleaning up redundant spilling ✨- Enabled by
-O3,-fprofile-useand-fauto-profile🎀
- Enabled by
-faggressive-loop-optimizations— the loop optimizer gets bold and uses language constraints to figure out bounds for how many times a loop runs 🔥 Those bounds steer loop unrolling, peeling and loop exit test optimizations- It assumes your loop code never triggers undefined behavior, like signed integer overflows or out-of-bound array accesses 🙈
- This option is enabled by default 💜
-funconstrained-commons— tells the compiler that variables in common blocks (e.g. Fortran) might get overridden later with longer trailing arrays 🦋 Because of that, certain optimizations that rely on knowing the array bounds get switched off-fcrossjumping— performs the cross-jumping transformation, which unifies equivalent code and saves code size 🌸 Heads up, bestie: the result may or may not run better than without it 🤷♀️- Enabled at levels
-O2,-O3,-Os
- Enabled at levels
-fauto-inc-dec— combines increments or decrements of addresses with memory accesses ✨ This pass is always skipped on architectures that don't have instructions to support it- Enabled by default at
-O1and higher on architectures that support this 👑
- Enabled by default at
-fdce— performs dead code elimination (DCE) on RTL 🧹- Enabled by default at
-O1and higher
- Enabled by default at
-fdse— performs dead store elimination (DSE) on RTL 💖- Enabled by default at
-O1and higher
- Enabled by default at
-fif-conversion— attempts to turn conditional jumps into branch-less equivalents 🦋 That includes conditional moves, min, max, set flags and abs instructions, plus some tricks you can pull off with standard arithmetic 🧚 Whether conditional execution gets used on chips that have it is controlled by-fif-conversion2- Enabled at levels
-O1,-O2,-O3,-Os, but not with-Og🙅♀️
- Enabled at levels
-fif-conversion2— uses conditional execution (where available) to turn conditional jumps into branch-less equivalents 🫶- Enabled at levels
-O1,-O2,-O3,-Os, but not with-Og
- Enabled at levels
-fdeclone-ctor-dtor— the C++ ABI wants multiple entry points for constructors and destructors: one for a base subobject, one for a complete object, and one for a virtual destructor that callsoperator deleteafterwards 😭 For a hierarchy with virtual bases, the base and complete variants are clones, meaning two copies of the function. With this option, those base and complete variants become thunks that call a common implementation 🎀- Enabled by
-Os
- Enabled by
-fdelete-null-pointer-checks— assumes programs can't safely dereference null pointers, and that no code or data element lives at address zero 💅 This option turns on simple constant folding optimizations at all optimization levels. On top of that, other optimization passes in GCC use this flag to control global dataflow analyses that axe useless null pointer checks 🔪 Those analyses assume a memory access to address zero always results in a trap, so if a pointer gets checked after it's already been dereferenced, it can't be null- > 💀 Note however that in some environments this assumption is not true. Use
-fno-delete-null-pointer-checksto disable this optimization for programs that depend on that behavior. - This option is enabled by default on most targets. On Nios II ELF, it defaults to off. On AVR and MSP430, this option is completely disabled 🙈
- Passes that use the dataflow information are enabled independently at different optimization levels 🌈
- > 💀 Note however that in some environments this assumption is not true. Use
-fdevirtualize— attempts to convert calls to virtual functions into direct calls 🦋 This happens both within a procedure and interprocedurally, as part of indirect inlining (-findirect-inlining) and interprocedural constant propagation (-fipa-cp)- Enabled at levels
-O2,-O3,-Os
- Enabled at levels
-fdevirtualize-speculatively— attempts to convert calls to virtual functions into speculative direct calls 🧠 Based on analysis of the type inheritance graph, GCC figures out the set of likely targets for a given call. If the set is small, preferably of size 1, the call gets changed into a conditional that decides between a direct and an indirect call 🍓 Speculative calls unlock more optimizations, like inlining. If they seem useless after further optimization, they get converted back into their original form-fdevirtualize-at-ltrans— streams extra information needed for aggressive devirtualization when the link-time optimizer runs in local transformation mode 🌸 This gives you more devirtualization, but it significantly increases the size of the streamed data 😤 For that reason it's disabled by default-fexpensive-optimizations— performs a bunch of minor optimizations that are relatively expensive 💸- Enabled at levels
-O2,-O3,-Os
- Enabled at levels
-free— attempts to remove redundant extension instructions 🧼 This is especially helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit registers after writing to their lower 32-bit half 💜- Enabled for Alpha, AArch64, LoongArch, PowerPC, RISC-V, SPARC, h83000 and x86 at levels
-O2,-O3,-Os
- Enabled for Alpha, AArch64, LoongArch, PowerPC, RISC-V, SPARC, h83000 and x86 at levels
-fno-lifetime-dse— in C++, an object's value is only affected by changes within its lifetime 🦋 When the constructor begins, the object has an indeterminate value, and any changes made during its lifetime are dead once the object is destroyed. Normally dead store elimination takes advantage of this. If your code relies on the value of the object storage sticking around beyond the object's lifetime, use this flag to turn that optimization off 🙅♀️- To keep stores made before the constructor starts (e.g. because your
operator newclears the object storage) but still treat the object as dead after the destructor, use-flifetime-dse=1🎀 - The default behavior can be explicitly selected with
-flifetime-dse=2✨ -flifetime-dse=0is equivalent to-fno-lifetime-dse🫶
- To keep stores made before the constructor starts (e.g. because your
-flive-range-shrinkage— attempts to decrease register pressure through register live range shrinkage 🌷 This is helpful for fast processors with small or moderate-size register sets 🏎️-fira-algorithm=algorithm— picks the coloring algorithm for the integrated register allocator 🎨 Thealgorithmargument can bepriority, which means Chow's priority coloring, orCB, which means Chaitin-Briggs coloring- Chaitin-Briggs coloring isn't implemented for every architecture, but for targets that do support it, it's the default because it generates better code 👑
-fira-region=region— picks the regions used by the integrated register allocator 🗺️ Theregionargument should be one of the following:all— uses all loops as register allocation regions 💅 This can give the best results for machines with a small and/or irregular register setmixed— uses all loops except loops with small register pressure as the regions ✨ This usually gives the best results in most cases and for most architectures, and it's enabled by default when compiling with optimization for speed (-O,-O2, ...) 🔥one— uses all functions as a single region 🍰 This typically results in the smallest code size, and it's enabled by default for-Osor-O0
-fira-hoist-pressure— uses IRA to evaluate register pressure in the code hoisting pass when deciding whether to hoist expressions 🧺 This usually results in smaller code, but it can slow the compiler down 🐢- This option is enabled at level
-Osfor all targets
- This option is enabled at level
-fira-loop-pressure— uses IRA to evaluate register pressure in loops when deciding whether to move loop invariants 🚀 This usually results in faster and smaller code on machines with large register files (>= 32 registers), but it can slow the compiler down 🐌- This option is enabled at level
-O3for some targets
- This option is enabled at level
-fno-ira-share-save-slots— disables sharing of stack slots used for saving call-used hard registers that live through a call 🙅♀️ Each hard register gets its own stack slot, so function stack frames end up larger 📦-fno-ira-share-spill-slots— disables sharing of stack slots allocated for pseudo-registers 🙅♀️ Each pseudo-register that doesn't get a hard register gets its own stack slot, so function stack frames end up larger 📦-flra-remat— enables CFG-sensitive rematerialization in LRA 🌀 Instead of loading the values of spilled pseudos, LRA tries to rematerialize (recalculate) values when that's profitable- Enabled at levels
-O2,-O3,-Os
- Enabled at levels
-fdelayed-branch— if the target machine supports it, GCC tries to reorder instructions to take advantage of instruction slots available after delayed branch instructions 🧩- Enabled at levels
-O1,-O2,-O3,-Os, but not at-Og
- Enabled at levels
-fschedule-insns— if the target machine supports it, GCC tries to reorder instructions to eliminate execution stalls caused by required data being unavailable 🥱 This helps machines with slow floating point or memory load instructions, by letting other instructions issue until the result of the load or floating-point instruction is actually needed 💫- Enabled at levels
-O2,-O3
- Enabled at levels
-fschedule-insns2— similar to-fschedule-insns, but it requests an additional pass of instruction scheduling after register allocation is done 📅 This is especially useful on machines with a relatively small number of registers, where memory load instructions take more than one cycle 🐌- Enabled at levels
-O2,-O3,-Os
- Enabled at levels
-fno-sched-interblock— disables instruction scheduling across basic blocks 🚫 This is normally enabled when scheduling happens before register allocation, i.e. with-fschedule-insnsor at-O2or higher 🫠-fno-sched-spec— disables speculative motion of non-load instructions 🙅♀️ This is normally enabled when scheduling happens before register allocation, i.e. with-fschedule-insnsor at-O2or higher ✨-fsched-pressure— okay bestie, this one turns on register-pressure-aware scheduling 💅 before register allocation even starts 🌸. It only slaps when scheduling before register allocation is on, so think-fschedule-insnsor-O2or higher. The payoff is that your code can get better and smaller 🦋 because it stops register pressure from climbing past the number of available hard registers, which means fewer annoying spills during register allocation 🥹.-fsched-spec-load— lowkey a spicy one ✨. It lets some load instructions get speculatively moved around. Same rule as before: this only makes sense when scheduling happens before register allocation, so-fschedule-insnsor-O2or higher 🫶.-fsched-spec-load-dangerous— the more chaotic sibling 💀. This one allows speculative motion of more load instructions. Same vibe check applies, though: it only makes sense when scheduling before register allocation, aka-fschedule-insnsor-O2or higher 🔥.-fsched-stalled-insns,-fsched-stalled-insns=n— this one controls how many stalled instructions can be yeeted early from the stalled queue into the ready list during the second scheduling pass 🎀.-fno-sched-stalled-insnsmeans no instructions get moved early at all 🙅♀️.-fsched-stalled-insns=0means there's no limit on how many queued instructions can jump the line ✨. And if you just write-fsched-stalled-insnswith no value, it's the same as-fsched-stalled-insns=1💖.-fsched-stalled-insns-dep,-fsched-stalled-insns-dep=n— this one decides how many instruction groups (cycles) get checked for a dependency on a stalled instruction that's a candidate for early removal from the queue 🧚. It only matters during the second scheduling pass, and only if-fsched-stalled-insnsis being used 🌈.-fno-sched-stalled-insns-depis the same as-fsched-stalled-insns-dep=0🙈. Writing-fsched-stalled-insns-depwith no value is the same as-fsched-stalled-insns-dep=1🍓.-fsched2-use-superblocks— when scheduling after register allocation, this one uses superblock scheduling 🦋. The glow-up is that instructions can move across basic block boundaries, which gives you faster schedules ✨. BUT it's experimental 💀, because not every machine description GCC uses models the CPU closely enough to avoid unreliable results. This only makes sense when scheduling after register allocation, so-fschedule-insns2or-O2or higher.
⚠️ bestie, read that experimental part twice. Some machine descriptions don't model the CPU closely enough, so results can be unreliable. Proceed with caution 😭.
-fsched-group-heuristic— turns on the group heuristic in the scheduler 🌸. It favors the instruction that belongs to a schedule group. This one is on by default whenever scheduling is enabled, so-fschedule-insns,-fschedule-insns2, or-O2or higher 👑.-fsched-critical-path-heuristic— enables the critical-path heuristic, which favors instructions sitting on the critical path 🛣️. Also on by default whenever scheduling is enabled, aka-fschedule-insns,-fschedule-insns2, or-O2or higher 💜.-fsched-spec-insn-heuristic— enables the speculative instruction heuristic, which favors speculative instructions with greater dependency weakness 🧠. Enabled by default when scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher 🎀.-fsched-rank-heuristic— enables the rank heuristic, which favors instructions belonging to a basic block with greater size or frequency 📊. On by default whenever scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher 🌈.-fsched-last-insn-heuristic— enables the last-instruction heuristic 🫧. It favors the instruction that's less dependent on the last instruction scheduled. It's on by default when scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher 🍓.-fsched-dep-count-heuristic— enables the dependent-count heuristic, which favors the instruction that has more instructions depending on it 🧚♀️. Enabled by default when scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher 💖.-freschedule-modulo-scheduled-loops— here's the tea ☕: modulo scheduling happens before traditional scheduling 🫖. If a loop gets modulo scheduled, later scheduling passes might change its schedule 🙈. Use this option to control that behavior 💅.-fselective-scheduling— schedules instructions using the selective scheduling algorithm 🦋. It runs instead of the first scheduler pass ✨.-fselective-scheduling2— same energy, but this one schedules instructions with the selective scheduling algorithm and runs instead of the second scheduler pass 🌟.-fsel-sched-pipelining— turns on software pipelining of innermost loops during selective scheduling 🔁. Heads up, though: it does absolutely nothing unless-fselective-schedulingor-fselective-scheduling2is on 🙃.-fsel-sched-pipelining-outer-loops— when pipelining loops during selective scheduling, this one also pipelines the outer loops 🪆. It has no effect unless-fsel-sched-pipeliningis turned on 🥲.-fsemantic-interposition— okay, this one is a lot, so get comfy 🧸. Some object formats, like ELF, let the dynamic linker interpose symbols. So for symbols exported from the DSO, the compiler can't do interprocedural propagation, inlining, or other optimizations, because the function or variable might get swapped out later 😩. That's actually useful, like if you want to swap in a debugging version of a memory allocation function 🛠️, but it's expensive when it comes to code quality 💸.
With -fno-semantic-interposition, the compiler assumes that if interposition happens for functions, the overwriting function will have precisely the same semantics (and side effects) 🫶. Same deal for variables: the constructor of the variable will be the same 🌸. This flag has no effect on functions explicitly declared inline, where interposition is never allowed to change semantics ✨, and it also does nothing for symbols explicitly declared weak 🙅♀️.
-fshrink-wrap— emits function prologues only before the parts of the function that actually need them, instead of at the very top 🎀. It's enabled by default at-Oand higher 🔥.-fshrink-wrap-separate— shrink-wraps the prologue and epilogue parts separately, so those parts only run when they're needed 🌙. It's on by default, but it does nothing unless-fshrink-wrapis also on and the target supports this 🫠.-fcaller-saves— this one lets values live in registers that get clobbered by function calls 🧺. To make that work, it emits extra instructions to save and restore those registers around the calls 💅. The allocation only happens when it seems to result in better code ✨. It's always on by default on certain machines, usually the ones that don't have call-preserved registers to use instead 🦋. Enabled at levels-O2,-O3,-Os👑.-fcombine-stack-adjustments— tracks stack adjustments (pushes and pops) and stack memory references, then tries to find ways to combine them 🧩. Enabled by default at-O1and higher 🌈.-fipa-ra— uses caller-save registers for allocation if those registers aren't used by any called function 🧠. The payoff is that they don't have to be saved and restored around calls 🙌. This is only possible if the called functions are part of the same compilation unit as the current function and they're compiled before it 📦. It's enabled at-O2,-O3,-Os, however it gets switched off if the generated code will be instrumented for profiling (-p, or-pg) 😭, or if the callee's register usage can't be known exactly (which happens on targets that don't expose prologues and epilogues in RTL) 🫥.-fconserve-stack— tries to minimize stack usage, even if that makes the program slower 🐢. This one implies setting thelarge-stack-frameparameter to100and thelarge-stack-frame-growthparameter to400🧮.-ftree-reassoc— performs reassociation on trees 🌳. Enabled by default at-O1and higher 💖.-fcode-hoisting— performs code hoisting 🪝. It tries to move the evaluation of expressions that get executed on all paths to the function exit as early as possible ⏰. It's especially useful as a code size optimization, but it often helps code speed too 🚀. Enabled by default at-O2and higher ✨.-ftree-pre— performs partial redundancy elimination (PRE) on trees 🧹. Enabled by default at-O2and-O3💜.-ftree-partial-pre— makes partial redundancy elimination (PRE) more aggressive 😈. Enabled by default at-O3🔥.-ftree-forwprop— performs forward propagation on trees ➡️. Enabled by default at-O1and higher 🦋.-ftree-fre— performs full redundancy elimination (FRE) on trees 🧽. Here's the difference between FRE and PRE 🤓: FRE only considers expressions computed on all paths leading to the redundant computation. That makes it faster than PRE, though it exposes fewer redundancies 🐇. Enabled by default at-O1and higher 🌸.-ftree-phiprop— performs hoisting of loads from conditional pointers on trees 🪄. This pass is enabled by default at-O1and higher ✨.-fhoist-adjacent-loads— speculatively hoists loads from both branches of an if-then-else, but only if the loads are from adjacent locations in the same structure AND the target architecture has a conditional move instruction 🍭. Enabled by default at-O2and higher 💅.-ftree-copy-prop— performs copy propagation on trees 📋. This pass gets rid of unnecessary copy operations, which is so iconic 👑. Enabled by default at-O1and higher 🫶.-fipa-pure-const— discovers which functions are pure or constant 🔍. Enabled by default at-O1and higher 🌈.-fipa-reference— discovers which static variables do not escape the compilation unit 🚪. Enabled by default at-O1and higher 🦋.-fipa-reference-addressable— discovers read-only, write-only, and non-addressable static variables 🕵️♀️. Enabled by default at-O1and higher 💜.-fipa-stack-alignment— reduces stack alignment on call sites if possible 📏. Enabled by default 🌟.-fipa-pta— performs interprocedural pointer analysis, plus interprocedural modification and reference analysis 🔬. Fair warning, though 🚨: this can cause excessive memory and compile-time usage on large compilation units. It is not enabled by default at any optimization level 🙈.
🚨 bestie, -fipa-pta can absolutely eat your memory and your compile time on big compilation units. It's off by default at every optimization level, so you have to ask for it on purpose 😭💀.
-fipa-profile— okay so this one does interprocedural profile propagation 🔮✨ Functions that are only called from cold functions get marked as cold 🧊, and functions that run once (like "cold", "noreturn", static constructors or destructors) get identified too 🎯. Then the cold functions and the loop-less parts of run-once functions get optimized for size 📏. It's enabled by default at-O1and higher 💅.-fipa-modref— this is giving interprocedural mod/ref analysis 🕵️♀️ It looks at the side effects of functions (the memory locations they modify or reference) so the compiler can optimize better across the function call boundary 🦋. Enabled by default at-O1and higher 🌸.-fipa-cp— interprocedural constant propagation 💖 The compiler checks when the values passed into functions are constants and optimizes around that 🧠. This can seriously boost performance if your app is passing constants into functions 🔥. Enabled by default at-O2,-Osand-O3, and also turned on by-fprofile-useand-fauto-profile💜.-fipa-cp-clone— function cloning to make interprocedural constant propagation even stronger 👯♀️ When it's on, the compiler clones externally visible functions that can be called with constant arguments 🧬. Because it can make multiple copies of functions, it may significantly increase code size (see--param ipa-cp-unit-growth=value) 📦. Enabled by default at-O3, and also by-fprofile-useand-fauto-profile🌈.-fipa-bit-cp— when enabled, you get interprocedural bitwise constant propagation 🎀 Enabled by default at-O2, and by-fprofile-useand-fauto-profile✨. It requires that-fipa-cpis enabled 🫶.-fipa-vrp— when enabled, the compiler does interprocedural propagation of value ranges 📐 Enabled by default at-O2💅. It requires that-fipa-cpis enabled 🫶.-fipa-icf— Identical Code Folding for functions and read-only variables 🧹 It reduces code size, but it can disturb unwind stacks because it swaps a function out for an equivalent one with a different name 😬. It works better with link-time optimization turned on 🔗.
Okay so this is similar to the Gold Linker's ICF optimization, but GCC's ICF works on different levels, so the optimizations aren't the same. There are equivalences only GCC finds and equivalences only Gold finds 🤓.
Enabled by default at -O2 and -Os 💖.
-flive-patching=level — tells GCC to control its optimizations so the output is suitable for live-patching 🩹✨
If an optimization uses a function's body (or info pulled from that body) to change another function, that other function is called an impacted function of the first one. If a function gets patched, its impacted functions should get patched too 🚨. Which functions count as impacted is decided by the interprocedural optimizations. For example, a caller is impacted when a function gets inlined into it, when a function gets cloned and its caller is changed to call the clone, or when a function's pureness/constness info is used to optimize its direct or indirect callers, and so on 🧩.
Usually, the more IPA optimizations you have on, the more impacted functions each function has. To keep that number under control and make the list easier to compute, IPA optimizations can be partially enabled at two different levels 🎚️.
The level argument should be one of the following:
inline-clone— only inlining and cloning optimizations are enabled, which covers inlining, cloning, interprocedural scalar replacement of aggregates and partial inlining 🌷. So when you patch a function, all its callers and its clones' callers are impacted and need patching too 📌.
⚠️-flive-patching=inline-clonedisables these optimization flags:-fwhole-program -fipa-pta -fipa-reference -fipa-ra -fipa-icf -fipa-icf-functions -fipa-icf-variables -fipa-bit-cp -fipa-vrp -fipa-pure-const -fipa-reference-addressable -fipa-stack-alignment -fipa-modref
inline-only-static— only inlining of static functions is enabled 🧚. So when you patch a static function, all its callers are impacted and need patching as well 🫠.
On top of everything -flive-patching=inline-clone disables, -flive-patching=inline-only-static also disables these extra flags: -fipa-cp-clone -fipa-sra -fpartial-inlining -fipa-cp 🙅♀️.
When -flive-patching is specified without any value, the default value is inline-clone 💜.
This flag is disabled by default 🥀.
🚫-flive-patchingis not supported with link-time optimization (-flto). Do not mix these two, bestie 💀.
-fisolate-erroneous-paths-dereference— this one detects paths that trigger erroneous or undefined behavior by dereferencing a null pointer 🕳️. It isolates those paths from the main control flow and turns the statement with the erroneous or undefined behavior into a trap 🪤. Enabled by default at-O2and higher, and it depends on-fdelete-null-pointer-checksalso being enabled 🔗.-fisolate-erroneous-paths-attribute— similar vibe, but this one detects paths where a null value gets used in a way forbidden by a "returns_nonnull" or "nonnull" attribute 🙅. It isolates those paths and turns the statement into a trap 🪤. This is not currently enabled, but it may be enabled by-O2in the future 🔮.-ftree-sink— performs forward store motion on trees 🌊. Enabled by default at-O1and higher 💖.-ftree-bit-ccp— sparse conditional bit constant propagation on trees, plus it propagates pointer alignment information 📏. This pass only operates on local scalar variables 🔍. It's enabled by default at-O1and higher, except for-Og🙃. It requires that-ftree-ccpis enabled 🫶.-ftree-ccp— sparse conditional constant propagation (CCP) on trees 🌟. It only operates on local scalar variables and is enabled by default at-O1and higher 💅.-fssa-backprop— propagates info about how a value gets used back up the definition chain so the definitions can be simplified 🪄. For example, this pass strips sign operations if the sign of a value never matters 🧽. Enabled by default at-O1and higher 🌸.-fssa-phiopt— pattern matching on SSA PHI nodes to optimize conditional code 🧩. It's enabled by default at-O1and higher, except for-Og🙈.-ftree-switch-conversion— turns simple initializations in a switch into initializations from a scalar array 🎲. Enabled by default at-O2and higher 💜.-ftree-tail-merge— looks for identical code sequences, and when it finds them it replaces one with a jump to the other 🦘. This is known as tail merging or cross jumping 🫶. Enabled by default at-O2and higher 🌈. The compilation time in this pass can be limited with themax-tail-merge-comparisonsparameter and themax-tail-merge-iterationsparameter ⏱️.-ftree-dce— dead code elimination (DCE) on trees 🗑️ Enabled by default at-O1and higher ✨.-ftree-builtin-call-dce— conditional dead code elimination (DCE) for calls to built-in functions that may set "errno" but are otherwise free of side effects 🧹. Enabled by default at-O2and higher, if-Osis not also specified 🫠.-ffinite-loops— the compiler assumes that a loop with an exit will eventually take the exit and won't loop forever 🔁✅. This lets it remove loops that otherwise have no side effects, without treating eventual endless looping as a side effect 🗑️.
This option is enabled by default at -O2 for C++ with -std=c++11 or higher 💅.
-ftree-dominator-opts— a bunch of simple scalar cleanups (constant/copy propagation, redundancy elimination, range propagation and expression simplification) based on a dominator tree traversal 🌳. It also does jump threading (to reduce jumps to jumps) 🦋. Enabled by default at-O1and higher 🌸.-ftree-dse— dead store elimination (DSE) on trees 💀. A dead store is a store into a memory location that gets overwritten later by another store with no loads in between, so the earlier store can be deleted 🗑️. Enabled by default at-O1and higher 💖.-ftree-ch— loop header copying on trees 🔄. This is great because it increases the effectiveness of code motion optimizations, and it also saves one jump 🫶. Enabled by default at-O1and higher. It's not enabled for-Os, since it usually increases code size 📈.-ftree-loop-optimize— loop optimizations on trees 🔁 Enabled by default at-O1and higher 💅.-ftree-loop-linear,-floop-strip-mine,-floop-block— loop nest optimizations 🪆. These are the same as-floop-nest-optimize. To use this code transformation, GCC has to be configured with--with-islto enable the Graphite loop transformation infrastructure 🛠️.-fgraphite-identity— enables the identity transformation for Graphite 🪞. For every SCoP, it generates the polyhedral representation and transforms it back to GIMPLE 🔄. You can use-fgraphite-identityto check the costs or benefits of the GIMPLE -> GRAPHITE -> GIMPLE transformation 🧐. Some minimal optimizations are also performed by the isl code generator, like index splitting and dead code elimination in loops ✨.-floop-nest-optimize— turns on the isl based loop nest optimizer 🌀. It's a generic loop nest optimizer based on the Pluto optimization algorithms, and it calculates a loop structure optimized for data locality and parallelism 🧠💕. This option is experimental 🧪.-floop-parallelize-all— uses the Graphite data dependence analysis to find loops that can be parallelized 🧵. It parallelizes all the loops that can be analyzed to not contain loop carried dependences, without checking whether parallelizing them is profitable 🫣. Yikes, bestie, that's a bold move 💅.-ftree-coalesce-vars— okay so when GCC is turning the program out of SSA form, it tries to cut down on copying by merging versions of different user-defined variables, not just compiler temporaries 🧚. Heads up though, this can seriously limit your ability to debug an optimized program compiled with-fno-var-tracking-assignments😭. In the negated form, this flag stops SSA coalescing of user variables. It's enabled by default if optimization is on, and it does very little otherwise 💅.-ftree-loop-if-convert— this one tries to turn conditional jumps in the innermost loops into branch-less equivalents 🦋. The whole point is to strip control flow out of those loops so the vectorization pass can handle them better ✨. It's enabled by default if vectorization is enabled.-ftree-loop-distribution— loop distribution, bestie 🌸. It can improve cache performance on big loop bodies and open the door for more loop optimizations, like parallelization or vectorization, to take place 🔥. This flag is enabled by default at-O3, and also by-fprofile-useand-fauto-profile. Here's the glow-up:
DO I = 1, N
A(I) = B(I) + C
D(I) = E(I) * F
ENDDObecomes
DO I = 1, N
A(I) = B(I) + C
ENDDO
DO I = 1, N
D(I) = E(I) * F
ENDDO-ftree-loop-distribute-patterns— this one distributes loops that can be code generated as calls to a library 💖. It's enabled by default at-O2and higher, and by-fprofile-useand-fauto-profile. This pass splits up the initialization loops and generates a call tomemsetzero 🧸. Check out the vibe:
DO I = 1, N
A(I) = 0
B(I) = A(I) + I
ENDDObecomes
DO I = 1, N
A(I) = 0
ENDDO
DO I = 1, N
B(I) = A(I) + I
ENDDOThe initialization loop gets transformed into a call to memset zero. This flag is enabled by default at -O3. It is also enabled by -fprofile-use and -fauto-profile ✨.
-floop-interchange— loop interchange outside of graphite, and it's giving performance 🔥. It can improve cache performance on loop nests and let further loop optimizations, like vectorization, take place 🌈. Look at this swap:
for (int i = 0; i < N; i++)
for (int j = 0; j < N; j++)
for (int k = 0; k < N; k++)
c[i][j] = c[i][j] + a[i][k]*b[k][j];is transformed to
for (int i = 0; i < N; i++)
for (int k = 0; k < N; k++)
for (int j = 0; j < N; j++)
c[i][j] = c[i][j] + a[i][k]*b[k][j];This flag is enabled by default at -O3. It is also enabled by -fprofile-use and -fauto-profile 👑.
-floop-unroll-and-jam— applies unroll and jam transformations on feasible loops 🧚. In a loop nest, this unrolls the outer loop by some factor and fuses the resulting multiple inner loops 🎀. It's enabled by default at-O3, and also by-fprofile-useand-fauto-profile.-ftree-loop-im— loop invariant motion on trees, and it's lowkey picky about what it moves 🙈. It only moves invariants that are hard to handle at the RTL level, like function calls or operations that expand into nontrivial sequences of insns. With-funswitch-loops, it also moves operands of conditions that are invariant out of the loop, so loop unswitching can use just trivial invariantness analysis 🦋. The pass also includes store motion 💜.-ftree-loop-ivcanon— creates a canonical counter for the number of iterations in loops where figuring out that number needs complicated analysis 🌸. Later optimizations can then determine the number easily. It's especially useful in connection with unrolling 🫶.-ftree-scev-cprop— performs final value replacement 💅. If a variable gets modified in a loop in such a way that its value on exit can be determined using only its initial value and the number of loop iterations, uses of the final value get replaced by that computation, as long as it's sufficiently cheap ✨. This reduces data dependencies and may allow further simplifications. It's enabled by default at-O1and higher.-fivopts— performs induction variable optimizations on trees, which means strength reduction, induction variable merging, and induction variable elimination 🔥.-ftree-parallelize-loops=n— parallelizes loops by splitting their iteration space to run innthreads 🧵. This is only possible for loops whose iterations are independent and can be arbitrarily reordered 💖. It's only profitable on multiprocessor machines, for loops that are CPU-intensive, rather than constrained by things like memory bandwidth 🌈. This option implies-pthread, so it's only supported on targets that have support for-pthread🫶.-ftree-pta— performs function-local points-to analysis on trees 🧠. It's enabled by default at-O1and higher, except for-Og.-ftree-sra— performs scalar replacement of aggregates 💎. This pass swaps structure references for scalars so structures don't get committed to memory too early 🦋. It's enabled by default at-O1and higher, except for-Og.-fstore-merging— merges narrow stores to consecutive memory addresses 🍓. It squishes contiguous stores of immediate values, narrower than a word, into fewer wider stores, which cuts down on the number of instructions 💅. This is enabled by default at-O2and higher, as well as-Os.-ftree-ter— performs temporary expression replacement during the SSA->normal phase 🧚. Single use/single def temporaries get replaced at their use location with their defining expression ✨. This results in non-GIMPLE code, but it gives the expanders much more complex trees to work on, which leads to better RTL generation 👑. This is enabled by default at-O1and higher.-ftree-slsr— performs straight-line strength reduction on trees 🌸. It recognizes related expressions involving multiplications and replaces them with less expensive calculations when possible 💜. This is enabled by default at-O1and higher.-ftree-vectorize— performs vectorization on trees, and it's the main character of this group 👑. This flag enables-ftree-loop-vectorizeand-ftree-slp-vectorizeif they aren't explicitly specified 🌈.-ftree-loop-vectorize— performs loop vectorization on trees 🎀. It's enabled by default at-O2, and also by-ftree-vectorize,-fprofile-use, and-fauto-profile🫶.-ftree-slp-vectorize— performs basic block vectorization on trees 🔥. It's enabled by default at-O2, and also by-ftree-vectorize,-fprofile-use, and-fauto-profile💖.
-ftrivial-auto-var-init=choice— okay this one is a whole security glow-up 🛡️💅. It initializes automatic variables with either a pattern or zeroes, so your program is more secure and predictable by preventing uninitialized memory from being disclosed and used 😭. GCC still considers an automatic variable without an explicit initializer to be uninitialized, and-Wuninitializedand-Wanalyzer-use-of-uninitialized-valuewill still report warnings on those variables. The compiler will also still optimize as if the variable were uninitialized 🙈. With this option, GCC will also initialize any padding of automatic variables that have structure or union types to zeroes ✨. However, the current implementation cannot initialize automatic variables declared between the controlling expression and the firstcaseof a"switch"statement, so use-Wtrivial-auto-var-initto report all such cases 💀.
The three values of choice are:
uninitializeddoesn't initialize any automatic variables. This is C and C++'s default 🥱.patterninitializes automatic variables with values that will likely turn logic bugs into crashes down the line 💥. They're easy to spot in a crash dump and aren't values programmers can rely on for useful program semantics 🔍. The current value is a byte-repeatable pattern with byte0xFE. The values used for pattern initialization might be changed in the future 🌀.zeroinitializes automatic variables with zeroes 🫧.
The default is uninitialized.
Note that the initializer values, whether zero or pattern, refer to data representation (in memory or machine registers), rather than to their interpretation as numerical values. This distinction may be important in languages that support types with biases or implicit multipliers, and with extensions such as hardbool. For example, a variable that uses 8 bits to represent (biased) quantities in the range 160..400 will be initialized with the bit patterns 0x00 or 0xFE, depending on choice. That's true whether or not these representations stand for values in that range. And even if they do, the interpretation of the value held by the variable will depend on the bias 🧮. A hardbool variable that uses, say, 0X5A and 0xA5 for "false" and "true", respectively, will trap with either choice of trivial initializer. In other words, zero initialization will not convert to the representation for "false", even if it would for a static variable of the same type 🚨. This means the initializer pattern doesn't generally depend on the type of the initialized variable. One notable exception is that (non-hardened) boolean variables that fit in registers are initialized with "false" (zero), even when pattern is requested 🫶.
You can control this behavior for a specific variable by using the variable attribute uninitialized 💜.
-fvect-cost-model=model— okay bestie, this one lets you tweak the cost model the vectorizer uses 🦋 Themodelargument has to beunlimited,dynamic,cheaporvery-cheap. Withunlimited, the vectorized code path is just assumed to be profitable, no questions asked 💅 Withdynamic, a runtime check guards the vectorized path so it only switches on for iteration counts that will likely run faster than the original scalar loop ✨
The cheap model is the cautious one 🧸 It turns off vectorization for loops where it would be cost prohibitive, like when it needs runtime checks for data dependence or alignment, but otherwise it's exactly the same as dynamic. Then there's very-cheap, the most picky of the bunch 🙈 It only allows vectorization if the vector code would entirely replace the scalar code being vectorized. For example, if each iteration of a vectorized loop can only handle exactly four iterations of the scalar loop, very-cheap only says yes if the scalar iteration count is known to be a multiple of four.
The default cost model depends on your other optimization flags and is either dynamic or cheap 🌸
-fsimd-cost-model=model— same vibe, but for loops marked with the OpenMPsimddirective 💜 Themodelargument should beunlimited,dynamicorcheap(novery-cheaphere, sorry bestie 🫶). All of them mean the same thing as in-fvect-cost-model, and by default, the cost model you set with-fvect-cost-modelis the one that gets used 🎀-ftree-vrp— this one does Value Range Propagation on trees 🌈 It's kinda like constant propagation, except instead of tracking single values, it tracks ranges of values. That lets the optimizers delete stuff like array bound checks and null pointer checks when they're unnecessary 😭 It's on by default at-O2and higher. Heads up, though: null pointer check elimination only happens if-fdelete-null-pointer-checksis turned on 💅-fsplit-paths— splits paths that lead to loop backedges ✂️ This can level up your dead code elimination and common subexpression elimination. It's enabled by default at-O3and above 👑-fsplit-ivs-in-unroller— when a loop gets unrolled, this lets the compiler express the values of induction variables in later iterations using the value from the first iteration 🧚 That breaks up long dependency chains, which helps the scheduling passes run more efficiently.
A combo of -fweb and CSE is often enough to get the same effect. Still, it's not reliable when the loop body is more complicated than a single basic block 🙈 And on some architectures, it doesn't work at all because of restrictions in the CSE pass.
This optimization is enabled by default ✨
-fvariable-expansion-in-unroller— with this one, the compiler makes multiple copies of some local variables when it unrolls a loop, which can give you superior code 🍓
It's enabled by default for PowerPC targets, but disabled by default everywhere else 💀
-fpartial-inlining— inlines parts of functions 🦋 This only does anything if inlining itself is turned on with-finline-functionsor-finline-small-functions.
Enabled at levels -O2, -O3, -Os 🌈
-fpredictive-commoning— performs predictive commoning, which means reusing computations (especially memory loads and stores) that were done in previous iterations of loops 💖
This is enabled at level -O3. It's also enabled by -fprofile-use and -fauto-profile 🫶
-fprefetch-loop-arrays— if the target machine supports it, this generates instructions to prefetch memory, which can improve loops that access large arrays 🔥
Fair warning: this may generate better or worse code, because the results are highly dependent on how the loops are structured in your source code 🙈
Disabled at level -Os 💅
-fno-printf-return-value— do not substitute constants for the known return value of formatted output functions like"sprintf","snprintf","vsprintf"and"vsnprintf"(but not"printf"or"fprintf") 🧁 This substitution lets GCC optimize or even eliminate branches based on the known return value of these functions, as long as the arguments are either constant or have values known to be in a range that makes the exact return value possible.
For example, when -fprintf-return-value is in effect, both the branch and the body of the if statement (but not the call to snprint) can be optimized away when i is a 32-bit or smaller integer, because the return value is guaranteed to be at most 8 ✨
char buf[9];
if (snprintf (buf, "%08x", i) >= sizeof buf)
...The -fprintf-return-value option relies on other optimizations and gives the best results with -O2 and above 👑 It works in tandem with the -Wformat-overflow and -Wformat-truncation options. The -fprintf-return-value option is enabled by default 💖
-fno-peephole,-fno-peephole2— these disable any machine-specific peephole optimizations 🧚 The difference between them is how they're implemented in the compiler: some targets use one, some use the other, and a few use both 🌸
-fpeephole is enabled by default. -fpeephole2 is enabled at levels -O2, -O3, -Os 🎀
-fno-guess-branch-probability— do not guess branch probabilities using heuristics 🙃
GCC uses heuristics to guess branch probabilities when they aren't provided by profiling feedback (-fprofile-arcs). These heuristics are based on the control flow graph. If some branch probabilities are specified by "__builtin_expect", then the heuristics guess the probabilities for the rest of the control flow graph, taking the "__builtin_expect" info into account 🧠 The interactions between the heuristics and "__builtin_expect" can get messy, so sometimes it's helpful to turn the heuristics off so the effects of "__builtin_expect" are easier to understand 🫶
You can also specify the expected probability of an expression with the "__builtin_expect_with_probability" built-in function 🦋
The default is -fguess-branch-probability at levels -O, -O2, -O3, -Os ✨
-freorder-blocks— reorders basic blocks in the compiled function to reduce the number of taken branches and improve code locality 🌈
Enabled at levels -O1, -O2, -O3, -Os 💅
-freorder-blocks-algorithm=algorithm— picks the algorithm used for basic block reordering 🍓 Thealgorithmargument can besimple, which doesn't increase code size (except sometimes because of secondary effects like alignment), orstc, the "software trace cache" algorithm.stctries to put all the often executed code together, which minimizes the number of branches executed, but it does this by making extra copies of code 🔥
The default is simple at levels -O1, -Os, and stc at levels -O2, -O3 ✨
-freorder-blocks-and-partition— on top of reordering basic blocks, this one partitions hot and cold basic blocks into separate sections of the assembly and.ofiles, to improve paging and cache locality performance 🧊
This optimization gets turned off automatically in a few situations: when there's exception handling or unwind tables (on targets using setjump/longjump or a target specific scheme), for linkonce sections, for functions with a user-defined section attribute, and on any architecture that doesn't support named sections 😭 When -fsplit-stack is used, this option isn't enabled by default (to avoid linker errors), but you can still enable it explicitly if you're using a working linker 🫶
Enabled for x86 at levels -O2, -O3, -Os 👑
-freorder-functions— reorders functions in the object file to improve code locality 💜 It's done using special subsections:".text.hot"for the most frequently executed functions, and".text.unlikely"for the unlikely executed ones. The linker does the reordering, so the object file format must support named sections and the linker has to place them in a reasonable way 🧚
This option isn't effective unless you either provide profile feedback (see -fprofile-arcs for details) or manually annotate functions with "hot" or "cold" attributes 🙈
Enabled at levels -O2, -O3, -Os 🌸
-fstrict-aliasing— lets the compiler assume the strictest aliasing rules that apply to the language being compiled 🔥 For C (and C++), this turns on optimizations based on the type of expressions. In particular, an object of one type is assumed never to live at the same address as an object of a different type, unless the types are almost the same. For example, an"unsigned int"can alias an"int", but not a"void*"or a"double". A character type may alias any other type 🎀
Pay special attention to code like this 👀
union a_union {
int i;
double d;
};
int f() {
union a_union t;
t.d = 3.0;
return t.i;
}Reading from a different union member than the one most recently written to (called "type-punning") is super common 💅 Even with -fstrict-aliasing, type-punning is allowed, as long as the memory is accessed through the union type. So the code above works as expected. However, this code might not 😬
int f() {
union a_union t;
int* ip;
t.d = 3.0;
ip = &t.i;
return *ip;
}Similarly, accessing something by taking its address, casting the resulting pointer and dereferencing the result has undefined behavior, even if the cast uses a union type 🚨 For example:
int f() {
double d = 3.0;
return ((union a_union *) &d)->i;
}The -fstrict-aliasing option is enabled at levels -O2, -O3, -Os 🌈
-fipa-strict-aliasing— controls whether the rules of-fstrict-aliasingare applied across function boundaries 🧁 Keep in mind that if multiple functions get inlined into a single function, the memory accesses are no longer considered to be crossing a function boundary 💖
The -fipa-strict-aliasing option is enabled by default, and it's only effective in combination with -fstrict-aliasing 🫶
-falign-functions,-falign-functions=n,-falign-functions=n:m,-falign-functions=n:m:n2,-falign-functions=n:m:n2:m2— okay bestie, this one lines up the start of your functions 💅 It nudges them to the next power-of-two boundary that's greater than or equal to n, skipping up tom-1bytes 🦋 The goal is that at least the first m bytes of the function can be fetched by the CPU without crossing an n-byte alignment boundary 🧚 It's a code performance optimization ✨ and alignment gets ignored for functions considered cold 🧊 If you need alignment on every function, reach for-fmin-function-alignmentinstead 👑- If m isn't specified, it defaults to n 🍓
- Examples 🌸:
-falign-functions=32aligns functions to the next 32-byte boundary-falign-functions=24aligns to the next 32-byte boundary only if that can be done by skipping 23 bytes or less-falign-functions=32:7aligns to the next 32-byte boundary only if that can be done by skipping 6 bytes or less
- The second n2:m2 pair gives you a secondary alignment 🎀
-falign-functions=64:7:32:3aligns to the next 64-byte boundary if that can be done by skipping 6 bytes or less, otherwise it aligns to the next 32-byte boundary if that can be done by skipping 2 bytes or less - If m2 isn't specified, it defaults to n2 💜
- Some assemblers only support this flag when n is a power of two. In that case, the value gets rounded up 🙈
-fno-align-functionsand-falign-functions=1are equivalent and mean functions are not aligned 💀- If n isn't specified or is zero, the compiler uses a machine-dependent default 🤖 The max allowed n value is
65536 - Enabled at levels
-O2,-O3✨
-flimit-function-alignment— if this one's on, the compiler tries not to overalign functions when it doesn't need to 🙅♀️ It asks the assembler to align by the amount set with-falign-functions, but it won't skip more bytes than the size of the function itself 🌈-falign-labels,-falign-labels=n,-falign-labels=n:m,-falign-labels=n:m:n2,-falign-labels=n:m:n2:m2— aligns all branch targets to a power-of-two boundary 🎯 The parameters work just like the ones for-falign-functions💖-fno-align-labelsand-falign-labels=1are equivalent and mean labels aren't aligned 🫶- If
-falign-loopsor-falign-jumpsapply and are greater than this value, their values get used instead 👑 - If n isn't specified or is zero, a machine-dependent default is used. That default is very likely
1, which means no alignment 💅 The max allowed n value is65536 - Enabled at levels
-O2,-O3🔥
- If
-falign-loops,-falign-loops=n,-falign-loops=n:m,-falign-loops=n:m:n2,-falign-loops=n:m:n2:m2— aligns loops to a power-of-two boundary 🔁 If the loops run many times, this makes up for the cost of the dummy padding instructions 😭 It's a code performance optimization, and alignment is ignored for loops considered cold 🧊- If
-falign-labelsis greater than this value, its value is used instead 🎀 - The parameters are analogous to the
-falign-functionsoption 💜-fno-align-loopsand-falign-loops=1are equivalent and mean loops are not aligned 💀 The max allowed n value is65536 - If n isn't specified or is zero, a machine-dependent default is used 🤖
- Enabled at levels
-O2,-O3✨
- If
-falign-jumps,-falign-jumps=n,-falign-jumps=n:m,-falign-jumps=n:m:n2,-falign-jumps=n:m:n2:m2— aligns branch targets to a power-of-two boundary, but only for branch targets that can only be reached by jumping 🦘 In that case, no dummy operations need to be executed 🙌 It's a code performance optimization, and alignment is ignored for jumps considered cold 🧊- If
-falign-labelsis greater than this value, its value is used instead 🎀 - The parameters are analogous to the
-falign-functionsoption 💖-fno-align-jumpsand-falign-jumps=1are equivalent and mean that loops are not aligned 🙈 - If n isn't specified or is zero, a machine-dependent default is used. The max allowed n value is
65536 - Enabled at levels
-O2,-O3🌸
- If
-fmin-function-alignment— sets the minimal alignment of functions to the next power-of-two boundary greater than or equal to n 📏 Unlike-falign-functions, this applies to all functions, even the cold ones 🥶 It also isn't affected by-flimit-function-alignment🙌-fno-allocation-dce— don't remove unused C++ allocations during dead code elimination 🗑️-fallow-store-data-races— lets the compiler do optimizations that might introduce new data races on stores, without proving the variable can't be accessed by other threads at the same time 🧵 It doesn't affect optimization of local data 🏠 It's only safe to use if you know global data won't be accessed by multiple threads 😬- Examples include hoisting, or if-conversions that might cause a value already in memory to be written back with that same value. That rewriting is safe in a single-threaded context but may be unsafe in a multi-threaded one 🧠
- Note that on some processors, if-conversions may be required to enable vectorization ⚡
- Enabled at level
-Ofast🔥
-funit-at-a-time— only here for compatibility reasons 🕰️ It has no effect.-fno-unit-at-a-time, on the other hand, implies-fno-toplevel-reorderand-fno-section-anchors👀 Enabled by default 💅-fno-toplevel-reorder— don't reorder top-level functions, variables, and"asm"statements. Output them in the same order they appear in the input file 📜 When this is used, unreferenced static variables are not removed 🙅♀️ It's meant to support existing code that relies on a particular ordering. For new code, attributes are the better move when possible 💡-ftoplevel-reorderis the default at-O1and higher, and also at-O0if-fsection-anchorsis explicitly requested ✨-fno-toplevel-reorderalso implies-fno-section-anchors🫶
-funreachable-traps— turns calls to"__builtin_unreachable"into traps, instead of using them for optimization 🚨 This also affects any such calls the compiler generates implicitly 🙈 It has the same effect as-fsanitize=unreachable -fsanitize-trap=unreachable, but it doesn't change the values of those options. If-fsanitize=unreachableis enabled, that option takes priority over this one 👑 Enabled by default at-O0and-Og🌈-fweb— constructs webs, the way they're commonly used for register allocation, and gives each web its own pseudo register 🕸️ That lets the register allocation pass work on pseudos directly, and it also strengthens several other passes like CSE, the loop optimizer, and the trivial dead code remover 💪 The catch: it can make debugging impossible, since variables no longer stay in a "home register" 😭 Enabled by default with-funroll-loops🎀-fwhole-program— assumes the current compilation unit is the whole program being compiled 👑 All public functions and variables, exceptmainand anything merged by the attribute"externally_visible", become static functions. That means the interprocedural optimizers can go harder on them ⚡- With
-flto, this option has limited use 🥱 In most cases, the precise list of symbols used or exported from the binary is already known from the resolution info the linker plugin passes to the link-time optimizer 🧩 - It's still useful if no linker plugin is used, or during the incremental link step when the final code is produced (with
-flto -flinker-output=nolto-rel) 🦋
- With
-flto[=n]— runs the standard link-time optimizer 🧠 When it's invoked with source code, it generates GIMPLE (one of GCC's internal representations) and writes it into special ELF sections in the object file ✨ When the object files get linked together, all the function bodies are read back from those ELF sections and instantiated as if they had been part of the same translation unit 🦋
To use link-time optimization, -flto and your optimization options should be specified at compile time and during the final link 🫶 It's recommended that you compile all the files in the same link with the same options, and also specify those options at link time. For example:
gcc -c -O2 -flto foo.c
gcc -c -O2 -flto bar.c
gcc -o myprog -flto -O2 foo.o bar.oThe first two invocations save a bytecode representation of GIMPLE into special ELF sections inside foo.o and bar.o 🍓 The final invocation reads that GIMPLE bytecode from foo.o and bar.o, merges the two files into a single internal image, and compiles the result as usual. Since both files get merged into one image, all the interprocedural analyses and optimizations in GCC work across the two files as if they were a single one 🔥 So, for example, the inliner can inline functions in bar.o into functions in foo.o, and vice-versa 💖
Another (simpler) way to enable link-time optimization is:
gcc -o myprog -flto -O2 foo.c bar.cThat generates bytecode for foo.c and bar.c, merges them together into a single GIMPLE representation, and optimizes them as usual to produce myprog ✨
The important thing to keep in mind: to enable link-time optimizations, you need to use the GCC driver to perform the link step 🚨 GCC automatically performs link-time optimization if any of the objects involved were compiled with the-fltocommand-line option. You can always override that automatic decision by passing-fno-ltoto the link command 🙅♀️
Okay so bestie, whole program optimization is a total main character move, but it needs some big assumptions 💅. The compiler has to know which functions and variables outside the link-time optimized unit can reach them, like libraries and runtime stuff. When your linker supports it, the linker plugin (see -fuse-linker-plugin) hands the compiler a list of used and externally visible symbols, which is so helpful 🫶. If there's no linker plugin, use -fwhole-program so the compiler can make those assumptions and go way more aggressive with its optimization choices 🔥.
When you compile with -flto and skip -fuse-linker-plugin, the object file ends up bigger than a regular one 🍓. That's because it has GIMPLE bytecodes and the usual final code (see -ffat-lto-objects). The upside is that these LTO-aware objects can still be linked like normal objects. Just know that if you pass -fno-lto to the linker, no interprocedural optimizations happen at all 💀. Also, if -fno-fat-lto-objects is on, the compile stage is faster, but you can't do a regular, non-LTO link with those files.
When GCC builds the final binary, it only runs link-time optimizations on the files that have bytecode in them ✨. So you can totally mix and match object files and libraries, with GIMPLE bytecode and final object code living side by side. GCC figures out on its own which files get the LTO treatment and which ones just link straight through 🧚.
Generally, options you give at link time beat the ones you gave at compile time 👑. Sometimes though, GCC tries to guess link-time options from the settings used to compile the input files, so it's giving detective energy 🙈.
If you don't pass an optimization level -O at link time, GCC uses the highest level that was used when compiling the object files 🦋. Heads up, though: it's pretty ineffective to set an optimization level only at link time and not at compile time. There are two reasons for this. First, compiling without optimization skips the compiler passes that collect the info needed for good link-time optimization. Second, some early optimization passes can only run at compile time, not at link time 😭.
GCC keeps some code generation flags around inside the bytecode, because they're needed during the final link 💜. Right now, these are taken from the first object file that explicitly sets them: -fcommon, -fexceptions, -fnon-call-exceptions, -fgnu-tm and all the -m target flags.
The PIC and PIE flags (-fPIC, -fpic, -fpie and -fPIE) get combined using this scheme, and it's kind of a vibe 🌈:
-fPIC + -fpic = -fpic
-fPIC + -fno-pic = -fno-pic
-fpic/-fPIC + (no option) = (no option)
-fPIC + -fPIE = -fPIE
-fpic + -fPIE = -fpie
-fPIC/-fpic + -fpie = -fpieSome ABI-changing flags have to match across all compilation units. If you try to override them at link time with a conflicting value, it gets ignored 🙅♀️. This includes stuff like -freg-struct-return and -fpcc-struct-return.
Other options, like -ffp-contract, -fno-strict-overflow, -fwrapv, -fno-trapv or -fno-strict-aliasing, get passed through to the link stage and merged conservatively when translation units conflict 🌸. Specifically, -fno-strict-overflow, -fwrapv and -fno-trapv take precedence. For example, -ffp-contract=off beats -ffp-contract=fast. You can still override these at link time if you need to.
Diagnostic options like -Wstringop-overflow also get passed through to the link stage, and their setting matches the compile step at function granularity 🎀. This only matters for diagnostics emitted during optimization. Also, code transforms like inlining can end up turning warnings on or off for regions when the code doesn't match the compile-time setting, so keep an eye on that 👀.
If you need to pass options to the assembler using -Wa or -Xassembler, you have two choices. You can either compile those translation units with -fno-lto, or use the same assembler options on every translation unit consistently 🧚. You can also specify assembler options at LTO link time instead.
To get debug info, you need to supply -g at compile time 🔍. If any input file at link time was built with debug info, the link turns debug info generation on too. Fancy debug info settings, like the DWARF level -gdwarf-5, need to be repeated explicitly on the linker command line. Mixing different settings across translation units is discouraged, so don't do it, bestie 🙅♀️.
💀 If LTO runs into objects with C linkage that are declared with incompatible types across separate translation units being linked together, that's undefined behavior according to ISO C99 6.2.7. A non-fatal diagnostic may be issued, but the behavior is still undefined at run time. Similar diagnostics may pop up for other languages too.
Another feature of LTO is that you can apply interprocedural optimizations to files written in different languages 🌍:
gcc -c -flto foo.c
g++ -c -flto bar.cc
gfortran -c -flto baz.f90
g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortranNotice the final link is done with g++ to pull in the C++ runtime libraries, and -lgfortran is added to get the Fortran runtime libraries 🦋. In general, when you mix languages in LTO mode, use the same link command options you'd use when mixing languages in a regular, non-LTO compilation.
If object files with GIMPLE bytecode are stored in a library archive, like libfoo.a, you can extract and use them in an LTO link as long as you're using a linker with plugin support 🫶. To make static libraries that work with LTO, use gcc-ar and gcc-ranlib instead of ar and ranlib. To see the symbols in object files with GIMPLE bytecode, use gcc-nm. These commands need ar, ranlib and nm to have been compiled with plugin support. At link time, use -fuse-linker-plugin so the library joins the LTO optimization process ✨:
gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfooWith the linker plugin on, the linker pulls the needed GIMPLE files out of libfoo.a and hands them to the running GCC so they become part of the aggregated GIMPLE image that gets optimized 🌈.
If you aren't using a linker with plugin support, and/or you don't enable the linker plugin, the objects inside libfoo.a get extracted and linked as usual. They just won't take part in the LTO optimization process 😭. To make a static library that works for both LTO optimization and usual linkage, compile its object files with -flto -ffat-lto-objects 💖.
Link-time optimizations don't need the whole program to be present in order to work 🌸. If your program doesn't need any symbols exported, you can combine -flto and -fwhole-program so the interprocedural optimizers can use more aggressive assumptions, which may lead to better optimization opportunities 🔥. You don't need -fwhole-program when the linker plugin is active (see -fuse-linker-plugin).
The current LTO implementation doesn't try to make bytecode that's portable between different host types 🙈. The bytecode files are versioned with a strict version check, so bytecode generated by one GCC version won't work with an older or newer GCC version. Not a vibe!
Link-time optimization doesn't work super well with debug info generation on systems other than the ones using ELF and DWARF together 💀.
If you specify the optional n, the optimization and code generation done at link time runs in parallel using n jobs, by using an installed make program 🧚. You can use the environment variable MAKE to override which program gets used.
You can also use -flto=jobserver to let GNU make's job server mode decide how many parallel jobs to run 👑. This is clutch when the Makefile calling GCC is already running in parallel. You have to prepend a + to the command recipe in the parent Makefile for this to work. This option likely only works if MAKE is GNU make. Even without the option value, GCC tries to automatically detect a running GNU make's job server ✨.
Use -flto=auto to use GNU make's job server if it's available, or otherwise fall back to autodetecting the number of CPU threads on your system 🦋.
-flto-partition=alg— Okay, this one picks the partitioning algorithm the link-time optimizer uses 🎀. Your choices are1to1, which mirrors the original source files,balanced, which splits things into equally sized chunks whenever that's possible, ormax, which makes a new partition for every symbol where possible. Pickingnoneturns partitioning and streaming off completely 💅. The default isbalanced.1to1can be used as a workaround for various code ordering issues, butmaxpartitioning is only meant for internal testing, so don't go there 🙈. The valueonemeans exactly one partition gets used, whilenoneskips partitioning and runs the link-time optimization step straight from the WPA phase 🌸.-flto-compression-level=n— This one controls how much the intermediate language written to LTO object files gets compressed 🍓. It only matters when you're in LTO mode (-flto). GCC currently supports two LTO compression algorithms. Forzstd, valid values are0(no compression) up to19(maximum compression), andzlibsupports values from0to9. Values outside the range get clamped to the minimum or maximum of whatever's supported. If you don't give the option, a default balanced compression setting gets used 💖.-fuse-linker-plugin— This turns on a linker plugin during link-time optimization 🔌. It relies on plugin support in the linker, which is available ingoldor in GNUld2.21 or newer ✨.
The -fuse-linker-plugin deal is that GCC can dig into library archives and pull out the object files carrying GIMPLE bytecode 🧚. That gives the link-time optimizer way more code to work with, so the results are glow-up levels ✨. The info also says which symbols can be accessed from outside, by non-LTO object files or during dynamic linking 🦋. Binaries (and shared libraries that use hidden visibility) get code quality improvements that are similar to -fwhole-program 🔥. Check -flto for the full tea on what this flag does and how to use it 🫶.
This option is on by default when LTO support is enabled in GCC and GCC was set up for a linker that supports plugins (GNU ld 2.21 or newer, or gold) 💖.
-ffat-lto-objects— okay so fat LTO objects are object files that hold both the intermediate language and the object code 🍓. That makes them usable for LTO linking and normal linking, which is so iconic. This only matters when you're compiling with-flto, and it gets ignored at link time 💀.
-fno-fat-lto-objects improves compilation time over plain LTO, but the complete toolchain has to be aware of LTO for it to work 🧐. It needs a linker with linker plugin support for basic functionality. nm, ar and ranlib also need to support linker plugins if you want a full-featured build environment (one that can build static libraries etc). GCC gives you the gcc-ar, gcc-nm, gcc-ranlib wrappers to pass the right options to these tools. With non fat LTO, makefiles need to be modified to use them.
Modern binutils has a plugin auto-load mechanism, so installing the linker plugin into $libdir/bfd-plugins has the same effect as using the command wrappers (gcc-ar, gcc-nm and gcc-ranlib) 🌈.
The default is -fno-fat-lto-objects on targets with linker plugin support.
-fcompare-elim— after register allocation and post-register allocation instruction splitting, GCC hunts down arithmetic instructions that compute processor flags in a way that looks like a comparison based on that arithmetic 🔍. If possible, it eliminates the explicit comparison operation 💅.
This pass only applies to certain targets that can't explicitly represent the comparison operation before register allocation is complete.
Enabled at levels -O1, -O2, -O3, -Os.
-ffold-mem-offsets,-fno-fold-mem-offsets— tries to eliminate add instructions by folding them into memory loads and stores 🧚.
Enabled at levels -O2, -O3.
-fcprop-registers— after register allocation and post-register allocation instruction splitting, GCC runs a copy-propagation pass to try to reduce scheduling dependencies and occasionally eliminate the copy 🌸.
Enabled at levels -O1, -O2, -O3, -Os.
-fprofile-correction— profiles collected from an instrumented binary for multi-threaded programs can be inconsistent because of missed counter updates 🙈. With this option, GCC uses heuristics to correct or smooth out those inconsistencies. By default, GCC emits an error message when it detects an inconsistent profile.
This option is enabled by -fauto-profile.
-fprofile-partial-training— with"-fprofile-use", all portions of the program that weren't executed during the train run get optimized aggressively for size rather than speed 📏. Sometimes it's not practical to train every possible hot path. For example, a program may contain functions specific to certain hardware, and training may not cover every hardware configuration the program runs on 🖥️. With"-fprofile-partial-training", profile feedback is ignored for all functions not executed during the train run, so they're optimized as if they were compiled without profile feedback. This leads to better performance when the train run isn't representative, but it also leads to significantly bigger code 📦.-fprofile-use,-fprofile-use=path— turns on profile feedback-directed optimizations, plus the following optimizations, many of which are usually only worth it when profile feedback is available 👑:
-fbranch-probabilities -fprofile-values -funroll-loops
-fpeel-loops -ftracer -fvpt -finline-functions -fipa-cp
-fipa-cp-clone -fipa-bit-cp -fpredictive-commoning -fsplit-loops
-funswitch-loops -fgcse-after-reload -ftree-loop-vectorize
-ftree-slp-vectorize -fvect-cost-model=dynamic
-ftree-loop-distribute-patterns -fprofile-reorder-functionsBefore you can use this option, you must generate profiling information first 📝.
By default, GCC emits an error message if the feedback profiles don't match the source code. You can turn that error into a warning with -Wno-error=coverage-mismatch.
Note this may result in poorly optimized code 😬.
Also by default, GCC emits a warning message if the feedback profiles don't exist (see -Wmissing-profile).
If path is specified, GCC looks there for the profile feedback data files. See -fprofile-dir.
-fauto-profile,-fauto-profile=path— turns on sampling-based feedback-directed optimizations, plus the following optimizations, many of which are usually only worth it when profile feedback is available ✨:
-fbranch-probabilities -fprofile-values -funroll-loops
-fpeel-loops -ftracer -fvpt -finline-functions -fipa-cp
-fipa-cp-clone -fipa-bit-cp -fpredictive-commoning -fsplit-loops
-funswitch-loops -fgcse-after-reload -ftree-loop-vectorize
-ftree-slp-vectorize -fvect-cost-model=dynamic
-ftree-loop-distribute-patterns -fprofile-correctionpath is the name of a file containing AutoFDO profile information. If you leave it out, it defaults to fbdata.afdo in the current directory 📂.
Producing an AutoFDO profile data file requires running your program with the perf utility on a supported GNU/Linux target system. For more info, check https://perf.wiki.kernel.org/ 🔗.
E.g.
perf record -e br_inst_retired:near_taken -b -o perf.data \
-- your_programThen use the create_gcov tool to convert the raw profile data into a format GCC can use. You also have to hand this tool the unstripped binary for your program. See https://github.com/google/autofdo 🛠️.
E.g.
create_gcov --binary=your_program.unstripped --profile=perf.data \
--gcov=profile.afdoThe following options control compiler behavior around floating-point arithmetic 🧮. They trade off speed against correctness, and you have to turn every single one of them on yourself 🎀.
-ffloat-store— do not store floating-point variables in registers, and stop other options that might change whether a floating-point value is pulled from a register or from memory 🧊.
This option prevents the undesirable excess precision you get on machines like the 68000, where the floating registers (of the 68881) keep more precision than a "double" is supposed to have 😭. The same goes for the x86 architecture. For most programs the excess precision only does good, but a few programs rely on the precise definition of IEEE floating point. For those, use -ffloat-store after modifying them to store all pertinent intermediate computations into variables.
-fexcess-precision=style— this gives you more control over excess precision on machines where floating-point operations happen in a format with more precision or range than the IEEE standard and interchange floating-point types 🧠. By default,-fexcess-precision=fastis in effect, which means operations may be carried out in a wider precision than the types in the source if that makes the code faster, and it's unpredictable when rounding to the source types takes place.
When compiling C or C++, if -fexcess-precision=standard is specified, excess precision follows the rules of ISO C99 or C++. In particular, both casts and assignments cause values to be rounded to their semantic types (whereas -ffloat-store only affects assignments). This option is enabled by default for C or C++ if a strict conformance option such as -std=c99 or -std=c++17 is used. -ffast-math enables -fexcess-precision=fast by default regardless of whether a strict conformance option is used. If -fexcess-precision=16 is specified, constants and the results of expressions with types "_Float16" and "__bf16" are computed without excess precision.
-fexcess-precision=standard isn't implemented for languages other than C or C++. On x86, it has no effect if -mfpmath=sse or -mfpmath=sse+387 is specified. In the former case, IEEE semantics apply without excess precision, and in the latter, rounding is unpredictable.
-ffast-math— sets-fno-math-errno,-funsafe-math-optimizations,-ffinite-math-only,-fno-rounding-math,-fno-signaling-nans,-fcx-limited-rangeand-fexcess-precision=fast🚀.
This option causes the preprocessor macro "__FAST_MATH__" to be defined.
This option is not turned on by any-Ooption besides-Ofast, since it can result in incorrect output for programs that depend on an exact implementation of IEEE or ISO rules/specifications for math functions. It may, however, yield faster code for programs that don't need the guarantees of those specifications 💀.
-fno-math-errno— do not seterrnoafter calling math functions that are executed with a single instruction, e.g.,sqrt. A program that relies on IEEE exceptions for math error handling may want this flag for speed while keeping IEEE arithmetic compatibility 🏎️.
This option is not turned on by any -O option, since it can result in incorrect output for programs that depend on an exact implementation of IEEE or ISO rules/specifications for math functions. It may, however, yield faster code for programs that don't need the guarantees of those specifications.
The default is -fmath-errno.
On Darwin systems, the math library never sets errno. There's therefore no reason for the compiler to consider the possibility that it might, so -fno-math-errno is the default there 🍎.
-funsafe-math-optimizations— allows optimizations for floating-point arithmetic that (a) assume arguments and results are valid and (b) may violate IEEE or ANSI standards.
Be careful with this one 😱. When used at link time, it may include libraries or startup files that change the default FPU control word or other similar optimizations.
This one's the "not turned on by any -O option" energy again, bestie 🙈 -funsafe-math-optimizations is never switched on by an -O flag because it can give you wrong output for programs that depend on the exact IEEE or ISO math rules 💀 It might make faster code for programs that don't need those guarantees though ✨ and it turns on -fno-signed-zeros, -fno-trapping-math, -fassociative-math and -freciprocal-math all at once 🫶
The default is -fno-unsafe-math-optimizations 💖
-fassociative-math— okay so this lets the compiler regroup operands in a chain of floating-point operations 🦋 It breaks the ISO C and C++ standard because the result can change ngl 😭- NOTE: reordering can flip the sign of zero, ignore NaNs, and cause or hide underflow and overflow 💀 So it's a no-go for code that relies on rounding tricks like
(x + 2**52) - 2**52. It can also reorder floating-point comparisons, so don't use it where ordered comparisons are required 🙅♀️ - It requires both
-fno-signed-zerosand-fno-trapping-mathto be in effect, and it doesn't really make sense with-frounding-math🌸 - For Fortran, it gets switched on automatically when both
-fno-signed-zerosand-fno-trapping-mathare in effect ✨ - The default is
-fno-associative-math.
- NOTE: reordering can flip the sign of zero, ignore NaNs, and cause or hide underflow and overflow 💀 So it's a no-go for code that relies on rounding tricks like
-freciprocal-math— this one lets the compiler use the reciprocal of a value instead of dividing, if that unlocks some optimizations 🧚 Sox / ycan becomex * (1/y), which is super handy when(1/y)can be pulled out as a common subexpression 💅 The catch is that it loses precision and adds more flops on the value 😬- The default is
-fno-reciprocal-math.
- The default is
-ffinite-math-only— allows optimizations that assume arguments and results are never NaNs or+-Infs🌈- It's not turned on by any
-Ooption, same as before, because it can give wrong output for programs that need the exact IEEE or ISO math rules 💀 It might still give faster code for programs that don't need those guarantees 🦋 - The default is
-fno-finite-math-only.
- It's not turned on by any
-fno-signed-zeros— allows optimizations that don't care about whether zero is signed 🫧 IEEE says distinct+0.0and-0.0have their own behaviour, which stops the compiler from simplifying things likex+0.0or0.0*x(even with-ffinite-math-only) 🙈 This option basically says the sign of a zero result doesn't matter 💖- The default is
-fsigned-zeros.
- The default is
-fno-trapping-math— tells the compiler to assume floating-point operations can't cause user-visible traps 🎀 Those traps are division by zero, overflow, underflow, inexact result and invalid operation 😱 It requires-fno-signaling-nansto be in effect, and it can make faster code if you rely on "non-stop" IEEE arithmetic 🏎️- > Warning: this should never be turned on by any
-Ooption, because it can give wrong output for programs that depend on the exact IEEE or ISO math rules 💀 - The default is
-ftrapping-math. - Future GCC versions might give finer control over this using C99's
FENV_ACCESSpragma 🔮 This flag will then be used along with-frounding-mathto set the default state forFENV_ACCESS✨
- > Warning: this should never be turned on by any
-frounding-math— disables transformations and optimizations that assume the default floating-point rounding behaviour 🌸 That default is round-to-zero for all floating-point to integer conversions, and round-to-nearest for all other arithmetic truncations 🍓 Use this if your program changes the FP rounding mode dynamically, or might run with a non-default rounding mode 🫶- It turns off compile-time constant folding of floating-point expressions (since rounding mode can change those), plus arithmetic transformations that are unsafe with sign-dependent rounding modes 🙅♀️
- The default is
-fno-rounding-math. - > Experimental: this doesn't currently guarantee to disable every GCC optimization affected by rounding mode 🥺
- Future versions might give finer control using C99's
FENV_ACCESSpragma 🔮 This flag will be used along with-ftrapping-mathto set the default state forFENV_ACCESS✨
-fsignaling-nans— compiles assuming IEEE signaling NaNs may cause user-visible traps during floating-point operations 💥 Turning it on disables optimizations that might change how many exceptions are visible with signaling NaNs 👀 It implies-ftrapping-math, and it defines the preprocessor macro__SUPPORT_SNAN__🧚- The default is
-fno-signaling-nans. - > Experimental: this doesn't currently guarantee to disable every GCC optimization that affects signaling NaN behaviour 🙈
- The default is
-fno-fp-int-builtin-inexact— stops the built-in functionsceil,floor,roundandtrunc(plus theirfloatandlong doublevariants) from generating code that raises theinexactfloating-point exception for non-integer arguments 🪄 ISO C99 and C11 let these raiseinexact, but ISO/IEC TS 18661-1:2014 (the C bindings to IEEE 754-2008, now part of ISO C23) doesn't 🙅♀️- The default is
-ffp-int-builtin-inexact, which lets the exception be raised, unless C23 or a later C standard is selected 💅 - This option does nothing unless
-ftrapping-mathis in effect 🤷♀️ - Even with
-fno-fp-int-builtin-inexact, if these functions end up calling a library function,inexactmay still be raised if that library doesn't follow TS 18661 😭
- The default is
-fsingle-precision-constant— treats floating-point constants as single precision, instead of quietly converting them to double-precision constants 🦋-fcx-limited-range— when this is on, the compiler is told that a range reduction step isn't needed for complex division 🌈 It also skips checking whether the result of a complex multiplication or division isNaN + I*NaNand trying to rescue it 🫧- The default is
-fno-cx-limited-range, but-ffast-mathturns it on ✨ - This controls the default setting of the ISO C99
CX_LIMITED_RANGEpragma 💖 It applies to all languages, though 🌍
- The default is
-fcx-fortran-rules— complex multiplication and division follow Fortran rules 🧚 Range reduction happens as part of complex division, but there's still no checking for aNaN + I*NaNresult or any attempt to rescue it 🙈- The default is
-fno-cx-fortran-rules.
- The default is
The following options control optimizations that may improve performance, but none of them are enabled by any -O option 🍓 This section also includes experimental options that may produce broken code, so be careful bestie ⚠️
-fbranch-probabilities— okay this one is a whole glow-up 🌟 First you run a program compiled with-fprofile-arcs, then you compile it a second time with-fbranch-probabilitiesso the optimizations can use how many times each branch was taken 📊 When the-fprofile-arcsprogram exits, it saves arc execution counts to a file calledsourcename.gcdafor each source file 💾 That data is super dependent on the structure of the generated code, so you must use the same source code and the same optimization options for both compilations 🫶 Check-fprofile-arcsfor the details on file naming 🔍- With
-fbranch-probabilities, GCC puts aREG_BR_PROBnote on eachJUMP_INSNandCALL_INSN🧠 These can be used to improve optimization 📈 Right now they're only used in one place: inreorg.cc, where instead of guessing which path a branch is most likely to take, theREG_BR_PROBvalues are used to figure out exactly which path is taken more often 🎯 - Enabled by
-fprofile-useand-fauto-profile.
- With
-fprofile-values— if you combine it with-fprofile-arcs, it adds code that gathers some data about the values of expressions in the program 📥 With-fbranch-probabilities, it reads that data back and uses it for optimizations 🔁- Enabled by
-fprofile-generate,-fprofile-use, and-fauto-profile.
- Enabled by
-fprofile-reorder-functions— function reordering based on profile instrumentation records the first time each function runs, then sorts those functions in ascending order 🗂️- Enabled with
-fprofile-use.
- Enabled with
-fvpt— with-fprofile-arcs, this tells the compiler to add code that gathers information about expression values 🕵️♀️ With-fbranch-probabilities, it reads that data back and actually performs optimizations based on it 🎀 Right now those optimizations include specialising division operations using what it knows about the denominator's value 💅- Enabled with
-fprofile-useand-fauto-profile.
- Enabled with
-frename-registers— tries to avoid false dependencies in scheduled code by using registers left over after register allocation 🌈 It mostly helps processors with loads of registers 💪 Heads up though: depending on the debug information format the target uses, it can make debugging impossible, because variables no longer stay in a "home register" 😭- Enabled by default with
-funroll-loops.
- Enabled by default with
-fschedule-fusion— runs a target-dependent pass over the instruction stream to group instructions of the same type together 🧩 The target machine can run them more efficiently when they're next to each other in the flow 🏃♀️- Enabled at levels
-O2,-O3,-Os.
- Enabled at levels
-ftracer— performs tail duplication to enlarge the superblock size 🍰 This simplifies the function's control flow, so other optimizations can do a better job 👑- Enabled by
-fprofile-useand-fauto-profile.
- Enabled by
-funroll-loops— okay bestie, this one unrolls loops whose number of iterations is known at compile time or when the loop gets entered 💖 It also implies-frerun-cse-after-loop,-fweband-frename-registers, so it brings its whole squad ✨ It also switches on complete loop peeling, which fully removes loops that only run a small constant number of times. > Heads up: this makes your code bigger, and it may or may not make it run faster 💀 It's enabled by-fprofile-useand-fauto-profile.-funroll-all-loops— the no-chill version 💅 This unrolls every loop, even when the iteration count is still a mystery when the loop starts. > This usually makes programs run more slowly 😭 It implies the same options as-funroll-loops.-fpeel-loops— this peels loops that don't roll much, going off profile feedback or static analysis 🌸 It also turns on complete loop peeling, meaning loops with a small constant number of iterations get fully removed. It's enabled by-O3,-fprofile-use, and-fauto-profile.-fmove-loop-invariants— turns on the loop invariant motion pass in the RTL loop optimizer 🧚 It's enabled at level-O1and higher, except for-Og.-fmove-loop-stores— enables the loop store motion pass in the GIMPLE loop optimizer 🦋 It moves invariant stores to after the end of the loop, trading that for keeping the stored value in a register across each iteration. Note that for this to actually do anything,-ftree-loop-imhas to be enabled too. It's enabled at level-O1and higher, except for-Og.-fsplit-loops— if a loop has a condition that's always true on one side of the iteration space and always false on the other, this splits the loop into two ✂️ It's enabled by-fprofile-useand-fauto-profile.-funswitch-loops— this yanks branches with loop invariant conditions out of the loop 🫶 You get duplicates of the loop on both branches, each tweaked to match what the condition came out to be. It's enabled by-fprofile-useand-fauto-profile.-fversion-loops-for-strides— if a loop walks an array with a variable stride, GCC makes a second copy of the loop that assumes the stride is always one 👑 Here's the vibe:
for (int i = 0; i < n; ++i)
x[i * stride] = ...;becomes:
if (stride == 1)
for (int i = 0; i < n; ++i)
x[i] = ...;
else
for (int i = 0; i < n; ++i)
x[i * stride] = ...;This is especially iconic for Fortran's assumed-shape arrays, since it lets the compiler vectorize better when it can assume contiguous access 🌈 It's enabled by default at -O3, and it's also enabled by -fprofile-use and -fauto-profile.
-ffunction-sections,-fdata-sections— these put each function or data item into its own section in the output file, but only if the target supports arbitrary sections 🧩 The function or data item's name decides the section name.- Use these where the linker can optimize for locality of reference in the instruction space. Most ELF object format systems have linkers that can do this. On AIX, the linker rearranges sections (CSECTs) based on the call graph, and the performance impact varies 🔥
- Paired with linker garbage collection (the
linker --gc-sectionsoption), these can lead to smaller statically-linked executables (after stripping) 💖 - On ELF/DWARF systems, these don't make the debug info worse. Other object file or debug info formats might have issues 🙈
- > Only use these when there are significant benefits, bestie 🫶 They make the assembler and linker produce larger object and executable files, and they're also slower. They also affect code generation: they stop the compiler and assembler from using relative locations inside a translation unit, since those aren't known until link time. One example of an optimization that gets blocked is relaxing calls to short call instructions.
-fstdarg-opt— optimizes the prologue of variadic argument functions based on how those arguments are actually used ✨-fsection-anchors— this tries to cut down on symbolic address calculations by using shared "anchor" symbols to reach nearby objects 🦋 It can reduce GOT entries and GOT accesses on some targets. Say you have this function "foo":
static int a, b, c;
int foo (void) { return a + b + c; }Normally it calculates the addresses of all three variables, but with -fsection-anchors it reads them from one common anchor point instead. The effect is similar to this pseudocode (which isn't valid C, so don't try it 🙈):
int foo (void)
{
register int *xr = &x;
return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
}Not every target supports this one, so check before you get too attached 💅
-fzero-call-used-regs=choice— zeroes the call-used registers when a function returns, which boosts program security 🔐 It either helps mitigate Return-Oriented Programming (ROP) attacks or stops information from leaking out through registers. The possible values ofchoiceare the same as for thezero_call_used_regsattribute, and the default isskip. You can control this per function with the function attributezero_call_used_regs💜--param name=value— GCC uses a bunch of internal constants to decide how much optimization to do. For example, it won't inline functions that have more than a certain number of instructions 👀 You can tweak some of these from the command line with--param. Heads up: the names and meanings are tied to compiler internals and can change without notice in future releases 😭 To see the minimal, maximal, and default value of a parameter, use--help=param -Q. The value is always an integer, and these names are recognized for all targets:predictable-branch-outcome— if a branch is predicted to be taken with a probability lower than this threshold (in percent), it counts as well predictable 🎯max-rtl-if-conversion-insns— RTL if-conversion tries to get rid of conditional branches around a block by swapping them for conditionally executed instructions. This sets the max number of instructions in a block that get considered for if-conversion. The compiler also uses other heuristics to decide whether it's actually worth it ✨max-rtl-if-conversion-predictable-cost— RTL if-conversion will try to remove conditional branches around a block the same way. These parameters cap the cost of the sequence it would generate, depending on whether the branch is statically determined to be predictable or not. The units match GCC's internal seq_cost metric. The compiler tries to pick a reasonable default for this using theBRANCH_COSTtarget macro 💖max-crossjump-edges— the max number of incoming edges to consider for cross-jumping. The algorithm behind-fcrossjumpingisO(N^2)in the number of edges coming into each block 🫠 Bigger values mean more aggressive optimization, with compile time going up for probably a small size win.min-crossjump-insns— the min number of instructions that must match at the end of two blocks before cross-jumping happens on them. This gets ignored when every instruction in the block being cross-jumped from is already matched 🌸max-grow-copy-bb-insns— the max code size expansion factor when copying basic blocks instead of jumping. The expansion is measured relative to a jump instruction 🧚max-goto-duplication-insns— the max number of instructions to duplicate into a block that jumps to a computed goto. To avoidO(N^2)behavior in several passes, GCC factors computed gotos early and unfactors them as late as possible. Only computed jumps at the end of a basic block with no more thanmax-goto-duplication-insnsinstructions get unfactored 🦋max-delay-slot-insn-search— the max number of instructions to check when hunting for something to fill a delay slot. If you search past this arbitrary number, the time saved by filling the slot is tiny, so GCC just stops searching 🛑 Bigger values mean more aggressive optimization, with compile time going up for probably a small execution time win.max-delay-slot-live-search— when filling delay slots, the max number of instructions to check while looking for a block with valid live register information. Raising this arbitrarily chosen value means more aggressive optimization but longer compile times. This parameter should get removed once the delay slot code is rewritten to maintain the control-flow graph 🧹max-gcse-memory— the approximate max amount of memory inkBthat can be allocated for global common subexpression elimination. If the optimization needs more memory than this, it just doesn't happen 🧠max-gcse-insertion-ratio— if the ratio of expression insertions to deletions is bigger than this value for any expression, RTL PRE inserts or removes that expression, which leaves partially redundant computations sitting in the instruction stream 👀
max-pending-list-length— bestie, this is the cap on how many pending dependencies scheduling is allowed to hold 💅 Once it hits the limit, it flushes the current state and starts over. Huge functions with barely any branches or calls can build up massive lists that waste memory and resources for no reason 😭max-modulo-backtrack-attempts— the max number of backtrack attempts the scheduler will make while modulo scheduling a loop 🔁 Go too high and your compile time can blow up exponentially 💀max-inline-functions-called-once-loop-depth— the maximal loop depth of a call that the inline heuristics will consider when they're trying to inline every function that's called once 🧚max-inline-functions-called-once-insns— the maximal estimated size of functions that come out of inlining the functions called once 🌸max-inline-insns-single— okay so the tree inliner has a whole squad of parameters 👑 This one sets the max number of instructions (counted in GCC's internal representation) in a single function that the tree inliner will even look at for inlining. It only affects functions declaredinlineand methods implemented right inside a class declaration (C++) 🎀max-inline-insns-auto— when you turn on-finline-functions(which comes with-O3), a whole bunch of functions that the compiler wouldn't normally think about inlining suddenly get checked 👀 For those, a different, more restrictive limit applies than for functions declaredinline(--param max-inline-insns-auto) 🦋max-inline-insns-small— the bound that applies to calls considered relevant when you use-finline-small-functions🍓max-inline-insns-size— the bound that applies to calls being optimized for size 📏 A little bit of growth can actually be a good thing here, since it can open up optimization opportunities that inlining exposes ✨uninlined-function-insns— the number of instructions the inliner counts as overhead for a function, like its prologue and epilogue 🫶uninlined-function-time— the extra time the inliner counts as overhead for a function, like the time it takes to run that prologue and epilogue ⏱️inline-heuristics-hint-percent— the scale (in percents) applied toinline-insns-single,inline-insns-single-O2, andinline-insns-autowhen the inline heuristics hint that inlining is super profitable and will enable later optimizations 🔥uninlined-thunk-insns,uninlined-thunk-time— same deal as--param uninlined-function-insnsand--param uninlined-function-time, except these are applied to function thunks 🧵inline-min-speedup— if the estimated performance improvement of caller + callee runtime goes over this threshold (in percent), the function can be inlined no matter what the limits on--param max-inline-insns-singleand--param max-inline-insns-autosay 🚀 Main character move, honestly 👑large-function-insns— the limit that defines a really large function 🐘 For functions bigger than this after inlining, inlining gets constrained by--param large-function-growth. This one is mostly there to stop extreme compile times caused by the non-linear algorithms the back end uses 🙈large-function-growth— the max growth of a large function caused by inlining, in percents 📈 For example, a value of100limits large function growth to 2.0 times the original size 💖large-unit-insns— the limit that defines a large translation unit 📦 Growth from inlining into units bigger than this is limited by--param inline-unit-growth. For small units, that limit might be too tight 😬 Say you've got a unit with function A (inline) and function B that just calls A three times. If B is small compared to A, the unit's growth is 300%, and honestly that kind of inlining is totally sane 🙌 But for huge units full of tiny inlineable functions, the overall unit growth limit is what stops an exponential explosion of code size 💀 So for smaller units, the size gets bumped up to--param large-unit-insnsbefore the--param inline-unit-growthlimit gets applied 🧠lazy-modules— the max number of C++ module files that can be open at the same time when lazy loading 🌈inline-unit-growth— the max overall growth of the compilation unit caused by inlining 🌱 For example, a value of20limits unit growth to 1.2 times the original size. Cold functions (either marked cold with an attribute or flagged by profile feedback) don't count toward the unit size 🧊ipa-cp-unit-growth— the max overall growth of the compilation unit caused by interprocedural constant propagation 💜 For example, a value of10limits unit growth to 1.1 times the original size ✨ipa-cp-large-unit-insns— the size at which the IPA-CP pass considers a translation unit to be large 🔍large-stack-frame— the limit that defines large stack frames 🥞 While it's inlining, the algorithm tries really hard not to grow past this limit too much 🫣large-stack-frame-growth— the max growth of large stack frames caused by inlining, in percents 📚 For example, a value of1000limits large stack frame growth to 11 times the original size 😭max-inline-insns-recursive,max-inline-insns-recursive-auto— the max number of instructions an out-of-line copy of a self-recursive inline function is allowed to grow into by doing recursive inlining 🔄--param max-inline-insns-recursiveapplies to functions declaredinline. For functions not declaredinline, recursive inlining only happens when-finline-functions(included in-O3) is enabled, and then--param max-inline-insns-recursive-autois the one that applies instead 🎀max-inline-recursive-depth,max-inline-recursive-depth-auto— the max recursion depth used for recursive inlining 🪞--param max-inline-recursive-depthapplies to functions declaredinline. For functions not declaredinline, recursive inlining only happens when-finline-functions(included in-O3) is enabled, and--param max-inline-recursive-depth-autoapplies instead 💅min-inline-recursive-probability— recursive inlining is only worth it for functions that recurse deeply on average 🌀 For functions with a shallow recursion depth it can actually hurt, because it bumps up the prologue size or makes the function body more complicated for other optimizers 😵 When profile feedback is available (see-fprofile-generate), the real recursion depth can be guessed from how likely a function is to recurse through a given call expression 🔮 This parameter limits inlining to only those call expressions whose probability goes over the threshold (in percent) 🎯early-inlining-insns— how much growth the early inliner is allowed to make 🌷 Basically, it ramps up the amount of inlining for code that has a large abstraction penalty 🏗️max-early-inliner-iterations— the limit on how many iterations the early inliner runs 🔁 This basically caps how many nested indirect calls the early inliner can resolve 🧩 Deeper chains still get handled later, by late inlining 🦋comdat-sharing-probability— the probability (in percent) that C++ inline functions with comdat visibility get shared across multiple compilation units 🤝modref-max-bases,modref-max-refs,modref-max-accesses— the max number of base pointers, references, and accesses stored for a single function by mod/ref analysis 🗂️modref-max-tests— the max number of tests the alias oracle can run to tell memory locations apart using the mod/ref info 🕵️♀️ This one ought to be bigger than--param modref-max-basesand--param modref-max-refs, so keep that in mind 🫶modref-max-depth— the max depth of the DFS walk used by modref escape analysis 🌊 Setting it to0disables the analysis completely 🚫modref-max-escape-points— the max number of escape points tracked by modref per SSA-name 📍modref-max-adjustments— the max amount the access range gets enlarged during modref dataflow analysis 📐profile-func-internal-id— controls whether the function's internal id gets used in the profile database lookup 🗃️ If the value is0, the compiler uses an id based on the function's assembler name and filename instead 🧠 That makes old profile data way more forgiving of source changes, like function reordering and stuff 🫠min-vect-loop-bound— the min number of iterations below which loops don't get vectorized when-ftree-vectorizeis in use 🎶 The iteration count after vectorization has to be greater than this value for vectorization to happen 💪gcse-cost-distance-ratio— a scaling factor used when calculating how far an expression can get moved by GCSE optimizations 🚚 It's only supported in the code hoisting pass for now 🪝 The bigger the ratio, the more aggressively code gets hoisted for simple expressions (ones that cost less thangcse-unrestricted-cost) 🔥 Setting it to0disables hoisting of simple expressions completely 🙅♀️gcse-unrestricted-cost— the cost, roughly measured as the cost of a single typical machine instruction, at which GCSE optimizations stop constraining how far an expression can travel 🌍 Also only supported in the code hoisting pass 🪄 The lower the cost, the more aggressive the hoisting gets 📉 Setting it to0lets every expression travel an unrestricted distance 🦅max-hoist-depth— the depth of the search in the dominator tree for expressions to hoist 🌳 It's there to avoid quadratic behavior in the hoisting algorithm 🧮 A value of0doesn't limit the search at all, but it might slow down compilation of huge functions 🐢max-tail-merge-comparisons— the max number of similar basic blocks to compare any one basic block against 🧁 It's used to avoid quadratic behavior in tree tail merging 💖max-tail-merge-iterations— the cap on how many passes over the function the tree tail merging can make 🔁 It's basically a compile-time leash so this doesn't go on forever ⏱️store-merging-allow-unaligned— lets the store merging pass create unaligned stores, but only when that's legal 🧩max-stores-to-merge— how many stores the store merging pass will try to squish together into wider stores 🫶max-store-chains-to-track— how many store chains the store merging pass can track at once while trying to merge them into wider stores 🔗max-stores-to-track— how many stores get tracked at the same time while the store merging pass tries to merge them into wider stores 👀max-unrolled-insns— the most instructions a loop can have and still get unrolled 🔁 If the loop does get unrolled, this same number also decides how many times the loop body is copied 🎀max-average-unrolled-insns— like the one above, but counts instructions weighted by how likely they are to run 📊 Again, if a loop gets unrolled, this value also sets how many times the loop code is unrolled 🌸max-unroll-times— the max number of times a single loop can be unrolled 🦋max-peeled-insns— the most instructions a loop can have and still get peeled 🍓 If it does get peeled, this also decides how many times the loop code is peeled 🧚max-peel-times— the max number of times a single loop can be peeled 🫧max-peel-branches— the max number of branches allowed on the hot path through the peeled sequence 🌈max-completely-peeled-insns— the max number of instructions a completely peeled loop can have 💜max-completely-peel-times— the max number of iterations a loop can have and still be a good candidate for complete peeling ⭐max-completely-peel-loop-nest-depth— the deepest a loop nest can be and still be suitable for complete peeling 🪆max-unswitch-insns— the max number of instructions an unswitched loop can have 🔀max-unswitch-depth— the deepest a loop nest can be and still get unswitched 🌊lim-expensive— the minimum cost for an expression to count as expensive in loop invariant motion 💸min-loop-cond-split-prob— when FDO profile information is available, this sets the minimum probability a semi-invariant condition statement needs before it triggers a loop split ✂️iv-consider-all-candidates-bound— if there are this many induction variable candidates or fewer, every candidate gets considered for each use in the induction variable optimizations 🧠 If there are more than that, only the most relevant ones get looked at, so the time complexity doesn't go quadratic 😭iv-max-considered-uses— the induction variable optimizations just give up on any loop that has more induction variable uses than this 🏳️iv-always-prune-cand-set-bound— if the candidate set is smaller than this value, the compiler always tries to clear out unnecessary ivs from the set whenever it adds a new one 🧹avg-loop-niter— the average number of iterations a loop is expected to run 🔢dse-max-object-size— the biggest object (in bytes) that dead store elimination will track byte by byte 📦 Bigger values can mean bigger compilation times, so keep that in mind 🐢dse-max-alias-queries-per-store— the max number of queries sent to the alias oracle for each store 🔍 Larger values can take longer to compile but may remove more dead stores 💀scev-max-expr-size— the upper bound on how big expressions can be in the scalar evolutions analyzer 📏 Big expressions slow the analyzer down 🐌scev-max-expr-complexity— the upper bound on how complex expressions can be in the scalar evolutions analyzer 🧶 Complicated expressions slow the analyzer down too 😩max-tree-if-conversion-phi-args— the max number of arguments a PHI can have and still be supported by TREE if conversion, unless the loop is marked with a simd pragma 🎀vect-max-layout-candidates— the max number of possible vector layouts, such as permutations, that get considered when optimizing code that's about to be vectorized 🎨vect-max-version-for-alignment-checks— the max number of run-time checks allowed when the vectorizer does loop versioning for alignment 🛠️vect-max-version-for-alias-checks— the max number of run-time checks allowed when the vectorizer does loop versioning for alias 🕵️vect-max-peeling-for-alignment— the max number of loop peels the vectorizer can do to improve access alignment 🫧 A value of-1means there's no limit 🔓max-iterations-to-track— the max number of iterations of a loop that the brute-force algorithm for figuring out a loop's iteration count will try to evaluate 🧮hot-bb-count-fraction— thenin the fraction1/nof the maximal execution count of a basic block in the whole program. A basic block has to hit at least that to count as hot 🔥 The default is10000, which means a basic block is hot if its execution count is greater than1/10000of the maximal execution count 💖 A value of0means it's never considered hot 🥶 This one is used in non-LTO mode 🧃hot-bb-count-ws-permille— how many of the most-executed permilles, from0to1000, of the profiled execution of the whole program a basic block's execution count has to be part of to count as hot 🌡️ The default is990, which means a basic block is hot if its count contributes to the upper 990 permilles, or 99.0%, of the profiled execution of the whole program ✨ A value of0means it's never hot 🚫 This one is used in LTO mode 🌐hot-bb-frequency-fraction— thenin the fraction1/nof the entry block's execution frequency in a function that a basic block in that function has to reach to be hot 🌟 The default is1000, which means a basic block is hot in a function if it runs more often than1/1000of the entry block's frequency 💅 A value of0means it's never hot 🙅♀️unlikely-bb-count-fraction— thenin the fraction1/nof the number of profiled runs of the whole program. If a basic block's execution count is below that, it counts as unlikely to run 😴 The default is20, meaning a basic block is unlikely if it runs in fewer than1/20, or 5%, of the program's runs 🐌 A value of0means it's always considered unlikely 🫠max-predicted-iterations— the max number of loop iterations the compiler predicts statically 🔮 This comes in clutch when a function has one loop with a known bound and another with an unknown bound 🫶 The known count gets predicted correctly, but the unknown one averages out to roughly 10, so the unbounded loop looks artificially cold next to the other one 🥶builtin-expect-probability— controls how likely it is that an expression has the specified value 🎯 This takes a percentage, from 0 to 100 💯builtin-string-cmp-inline-length— the max length of a constant string for a builtin string cmp call that's eligible for inlining 🧵align-threshold— picks a fraction of the maximal execution frequency of a basic block in a function to decide whether that block gets aligned 📐align-loop-iterations— any loop expected to iterate at least this many times gets aligned 🪄tracer-dynamic-coverage,tracer-dynamic-coverage-feedback— these limit superblock formation once the given percentage of executed instructions is covered 🧃 That keeps the code from ballooning in size for no reason 🎈
The tracer-dynamic-coverage-feedback parameter only gets used when profile feedback is available 📈 Real profiles, unlike statically estimated ones, are much less balanced, so the threshold can be set to a larger value 💪
tracer-max-code-growth— stops tail duplication once code growth reaches the given percentage 🌱 It's a pretty artificial limit, since most of the duplicates get cleaned up later in cross jumping, so it can be set way higher than the code growth you actually want 🙃tracer-min-branch-ratio— stops reverse growth when the reverse probability of the best edge drops below this threshold, given as a percent 📉tracer-min-branch-probability,tracer-min-branch-probability-feedback— stops forward growth if the best edge has a probability lower than this threshold 🚦
Like tracer-dynamic-coverage, there are two versions of this one. tracer-min-branch-probability-feedback is for compiling with profile feedback, and tracer-min-branch-probability is for compiling without it 🧠 The feedback value needs to be more conservative, meaning higher, so the tracer actually works well 💜
stack-clash-protection-guard-size— the size of the operating system's stack guard, written as 2 raised to num bytes 🛡️ Higher values can reduce the number of explicit probes ✨
⚠️ If this value is larger than the operating system's guard, the code is left vulnerable to stack clash style attacks. Not it! 🙅♀️
stack-clash-protection-probe-interval— stack clash protection probes the stack space as it gets allocated 🔎 This sets the max distance between probes into the stack, written as 2 raised to num bytes 📏 Higher values can reduce the number of explicit probes 🌷
⚠️ If this value is larger than the operating system's guard, the code is left vulnerable to stack clash style attacks. Bestie, don't let that happen 😭
max-cse-path-length— ✨ okay so this is the max number of basic blocks on a path that CSE is allowed to look at 🧚max-cse-insns— 💅 the max number of instructions CSE chews through before it flushes everything and starts fresh 🫧ggc-min-expand— 🧠 GCC runs its own garbage collector to handle its memory, and this one sets the minimum percentage the GC heap can grow by between collections. Tuning it might speed up compilation, but it has zero effect on code generation, so no cap 💖- Default:
30% + 70% * (RAM/1GB), with an upper bound of 100% when RAM >= 1GB. Ifgetrlimitis available, "RAM" means the smallest of actual RAM andRLIMIT_DATAorRLIMIT_AS. If GCC can't work out RAM on a platform, the 30% lower bound kicks in. - Setting this and
ggc-min-heapsizeto zero forces a full collection at every opportunity. That's extremely slow 💀 but it can be useful for debugging 🔍
- Default:
ggc-min-heapsize— 🌸 the minimum size the GC heap has to reach before it even starts bothering to collect garbage. The first collection happens once the heap grows byggc-min-expand% beyondggc-min-heapsize. Again, tuning this may speed up compilation and has no effect on code generation 🦋- Default: the smaller of RAM/8,
RLIMIT_RSS, or a limit that tries to make sureRLIMIT_DATAorRLIMIT_ASdon't get exceeded. It has a lower bound of 4096 (four megabytes) and an upper bound of 131072 (128 megabytes). If GCC can't calculate RAM on a platform, the lower bound is used. - Setting this very large effectively disables garbage collection 🙈
- Setting this and
ggc-min-expandto zero causes a full collection at every opportunity.
- Default: the smaller of RAM/8,
max-reload-search-insns— 🔎 the max number of instructions reload will look backward through to find an equivalent register. Higher numbers mean more aggressive optimization, so compile time goes up for probably slightly better performance 🎀max-cselib-memory-locations— 🧩 the max number of memory locations cselib will take into account. Higher values mean more aggressive optimization, which bumps up compile time for probably slightly better performance ✨max-sched-ready-insns— 🍓 the max number of instructions that are ready to be issued that the scheduler will consider at any given moment during the first scheduling pass. Higher values mean more thorough searches, so compile time climbs with probably little benefit 🥱max-sched-region-blocks— 🗺️ the max number of blocks in a region that gets considered for interblock scheduling 🩷max-pipeline-region-blocks— 🚰 the max number of blocks in a region that gets considered for pipelining in the selective scheduler 💜max-sched-region-insns— 🎯 the max number of insns in a region that gets considered for interblock scheduling 🌈max-pipeline-region-insns— 🛠️ the max number of insns in a region that gets considered for pipelining in the selective scheduler 🫶min-spec-prob— 🎲 the minimum probability (in percents) of reaching a source block for interblock speculative scheduling 🔮max-sched-extend-regions-iters— 🔁 the max number of iterations through the CFG when extending regions. Setting this to0disables region extensions completely 🚫max-sched-insn-conflict-delay— ⏳ the max conflict delay an insn can have and still be considered for speculative motion 🌷sched-spec-prob-cutoff— ✂️ the minimal probability of speculation success (in percents) needed before speculative insns actually get scheduled 🦄sched-state-edge-prob-cutoff— 🌊 the minimum probability an edge has to have before the scheduler saves its state across it 🐚sched-mem-true-dep-cost— 🕰️ the minimal distance (in CPU cycles) between a store and a load that target the same memory locations 💾selsched-max-lookahead— 👀 the max size of the lookahead window for selective scheduling. Basically, it's how deep the search for available instructions goes 🕵️♀️selsched-max-sched-times— 🔂 the max number of times an instruction gets scheduled during selective scheduling. This is the cap on how many iterations an instruction can be pipelined through 🧃selsched-insns-to-rename— ✏️ the max number of best instructions in the ready list that get considered for renaming in the selective scheduler 💫sms-min-sc— 🎀 the minimum stage count value that the swing modulo scheduler generates 🌟max-last-value-rtl— 📏 the max size, counted as the number of RTLs, that the combiner can record in an expression for a pseudo register as that register's last known value 🧶max-combine-insns— 🧃 the max number of instructions the RTL combiner tries to combine together 🍹integer-share-limit— 🤝 small integer constants can use a shared data structure, which saves the compiler memory and makes it faster. This sets the max value of a shared integer constant 🔢ssp-buffer-size— 🛡️ the minimum size of buffers (aka arrays) that get stack smashing protection when-fstack-protectoris used- Before Ubuntu 10.10 the default was "8". Right now it's "4", so more functions get protected 🥹
min-size-for-stack-sharing— 🥞 the minimum size of variables that take part in stack slot sharing when you're not optimizing 🙃max-jump-thread-duplication-stmts— 🧵 the max number of statements a block can have and still be allowed to get duplicated when threading jumps 🪡max-jump-thread-paths— 🛤️ the max number of paths to consider when hunting for jump threading opportunities. When the compiler arrives at a block, it only considers incoming edges if (paths searched so far) × (number of incoming edges) doesn't blow past this max 🚦max-fields-for-field-sensitive— 🏷️ the max number of fields in a structure that gets treated in a field-sensitive way during pointer analysis 🔬prefetch-latency— ⏱️ an estimate of the average number of instructions executed before a prefetch finishes. The distance prefetched ahead is proportional to this number. Increasing it may also mean fewer streams get prefetched (seesimultaneous-prefetches) 🏃♀️simultaneous-prefetches— 🚀 the max number of prefetches that can run at the same time 💥l1-cache-line-size— 📐 the size of a cache line in the L1 data cache, in bytes 🧱l1-cache-size— 🗃️ the size of the L1 data cache, in kilobytes 🍰l2-cache-size— 🗂️ the size of the L2 data cache, in kilobytes 🧁prefetch-dynamic-strides— 🌀 whether the loop array prefetch pass should issue software prefetch hints for strides that aren't constant. Sometimes that's a win, but a non-constant stride can make it hard to tell when the hints will actually help 🤔- Set to
1if prefetch hints should be issued for non-constant strides. - Set to
0if prefetch hints should only be issued for strides that are known to be constant and belowprefetch-minimum-stride.
- Set to
prefetch-minimum-stride— 🛣️ the minimum constant stride, in bytes, before prefetch hints start getting used. If the stride is under this threshold, no prefetch hints get issued 🚧- This one's super useful for processors with hardware prefetchers, since the hardware and software prefetchers can clash. If the hardware prefetchers have a max stride they can handle, put that number here so the software prefetchers get used better 🤝
- A value of
-1means there's no threshold, so prefetch hints can go out for any constant stride ✨ - This only matters for strides that are known and constant.
destructive-interference-size,constructive-interference-size— 🧲 these are the values behind the C++17 variablesstd::hardware_destructive_interference_sizeandstd::hardware_constructive_interference_size. The destructive interference size is the minimum recommended offset between two independent objects that are accessed concurrently. The constructive interference size is the maximum recommended size of contiguous memory that gets accessed together. Usually both match the size of an L1 cache line for the target, in bytes. For a generic target that covers a range of L1 cache line sizes, the constructive size is the small end of the range and the destructive size is the large end 🌈- The destructive interference size is meant for layout, so it has ABI impact. Its default isn't expected to be stable, and on some targets it changes with
-mtune. So using it somewhere ABI stability really matters, like a library's public interface, is strongly discouraged 😭 If you do use it there, you can lock the value in place with this option. - The constructive interference size is way less sensitive. It's usually only used in a
static_assertto make sure a type fits inside a cache line 💅 - See also
-Winterference-size.
- The destructive interference size is meant for layout, so it has ABI impact. Its default isn't expected to be stable, and on some targets it changes with
loop-interchange-max-num-stmts— 🔄 the max number of statements in a loop that can be interchanged 🧮loop-interchange-stride-ratio— ⚖️ the minimum ratio between the strides of two loops for an interchange to be profitable 📈min-insn-to-prefetch-ratio— 🧮 the minimum ratio between the number of instructions and the number of prefetches needed to enable prefetching in a loop 🎯prefetch-min-insn-to-mem-ratio— 🧠 the minimum ratio between the number of instructions and the number of memory references needed to enable prefetching in a loop 💖use-canonical-types— okay so this one is a toggle for whether the compiler uses the "canonical" type system 💅 It should always be1, because that's the more efficient internal way of comparing types in C++ and Objective-C++ ✨ But if bugs in the canonical type system are causing compilation failures, set it to0to turn canonical types off 🙈switch-conversion-max-branch-ratio— switch initialization conversion won't create arrays bigger thanswitch-conversion-max-branch-ratiotimes the number of branches in the switch 🎀max-partial-antic-length— caps the length of the partial antic set built during tree partial redundancy elimination (-ftree-pre) when you're optimizing at-O3and up 🔥 Some code makes this optimization run totally wild and eat all the memory on the host machine 💀 This limit stops that runaway behavior. Setting it to0means the set length is unlimited 🦋rpo-vn-max-loop-depth— the maximum loop depth that gets value-numbered optimistically 🌈 When the limit is hit, the innermostrpo-vn-max-loop-depthloops and the outermost loop in the loop nest get value-numbered optimistically, and the remaining ones don'tsccvn-max-alias-queries-per-access— the max number of alias-oracle queries allowed while hunting for redundancies in loads and stores 🧚 If the limit is hit, the search is aborted and that load or store isn't considered redundant. The number of queries is algorithmically capped at the number of stores on all paths from the load to the function entryira-max-loops-num— IRA uses regional register allocation by default ✨ If a function has more loops than this number, only that many of the most frequently executed loops form regions for regional register allocationira-max-conflict-table-size— IRA is super smart about compressing its conflict table, but huge functions can still eat way too much memory 😭 If the conflict table for a function could be bigger than this many MB, the register allocator switches to a faster, simpler, lower-quality algorithm that doesn't build a pseudo-register conflict tableira-loop-reserved-regs— IRA can estimate more accurate register pressure in loops, which helps it decide when to move loop invariants (see-O3) 💜 This sets how many available registers are reserved for other purposes. The default is the best value found from numerous experimentsira-consider-dup-in-all-alts— makes IRA take matching constraints (duplicated operand numbers) seriously across all available alternatives for the preferred register class 👑 When set to zero, IRA only respects the matching constraint when it's the only available alternative with an appropriate register class. Otherwise, IRA checks every available alternative for the preferred register class, even after it has found a qualified choice, and respects that qualified matching constraintira-simple-lra-insn-threshold— the approximate number of function insns, counted in 1K units, that triggers simple local RA 🌸lra-inheritance-ebb-probability-cutoff— LRA tries to reuse values that were reloaded into registers in later insns, and this trick is called inheritance 🫶 EBB is the region used for this optimization. This parameter sets the minimum fall-through edge probability, as a percentage, needed to add a BB to an inheritance EBB in LRA. The default was picked from numerous SPEC2000 runs onx86-64loop-invariant-max-bbs-in-loop— loop invariant motion can get really expensive for very large loops, both in compile time and in compile-time memory 💀 Loops with more basic blocks than this parameter won't get loop invariant motion performed on themloop-max-datarefs-for-datadeps— building data dependencies is expensive for huge loops 🙈 This caps the number of data references in loops that get considered for data dependence analysis. Those big loops aren't handled by the optimizations that use loop data dependenciesmax-vartrack-size— the max number of hash table slots allowed while variable tracking dataflow analysis runs on any function 🧠 If this limit gets exceeded with variable tracking at assignments enabled, the analysis for that function is retried without it, after removing all debug insns from the function. If the limit is still exceeded without debug insns, var tracking analysis is completely disabled for that function. Setting it to zero makes it unlimitedmax-vartrack-expr-depth— the max number of recursion levels when mapping variable names or debug temporaries to value expressions 🦋 This trades compile time for more complete debug information. If it's set too low, value expressions that are available and could go in the debug info might not get used. Setting it higher may let the compiler find more complex debug expressions, but compile time and memory use may growmax-debug-marker-count— a threshold on the number of debug markers (like begin stmt markers) so things don't blow up at inlining or RTL expansion 💅 If a function has more of these gimple stmts than the limit, they get dropped from the inlined copy of the function, and from its RTL expansionmin-nondebug-insn-uid— uids start at this value for nondebug insns ✨ The range below it is reserved exclusively for debug insns created by-fvar-tracking-assignments. Debug insns can still get (non-overlapping) uids above it if that reserved range runs outipa-sra-deref-prob-threshold— IPA-SRA swaps a pointer that's known not to be NULL for one or more new parameters only when the probability of it being dereferenced (in percent, relative to function entry) is higher than this parameter 🔥ipa-sra-ptr-growth-factor— IPA-SRA swaps a pointer to an aggregate for one or more new parameters only when their cumulative size is less than or equal toipa-sra-ptr-growth-factortimes the size of the original pointer parameter 🌈ipa-sra-ptrwrap-growth-factor— the extra maximum growth allowed in the total size of new parameters that ipa-sra swaps a pointer to an aggregate for 🎀 This applies when the pointer points to a local variable that the caller only writes to and passes along as an argument to other functionsipa-sra-max-replacements— the max number of pieces of an aggregate that IPA-SRA tracks 🧚 That also makes it the max number of replacements for a formal parametersra-max-scalarization-size-Ospeed,sra-max-scalarization-size-Osize— the two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) try to swap scalar parts of aggregates for uses of independent scalar variables 🫶 These parameters set the max size, in storage units, of an aggregate considered for replacement when compiling for speed (sra-max-scalarization-size-Ospeed) or for size (sra-max-scalarization-size-Osize), respectivelysra-max-propagations— the max number of artificial accesses that Scalar Replacement of Aggregates (SRA) tracks per local variable, so copy propagation can happen 💖tm-max-aggregate-size— when making copies of thread-local variables inside a transaction, this is the size in bytes after which variables get saved with the logging functions instead of save/restore code sequence pairs 🔥 This only applies when using-fgnu-tmgraphite-max-nb-scop-params— to avoid exponential effects in the Graphite loop transforms, the number of parameters in a Static Control Part (SCoP) is capped 🦋 A value of zero lifts the cap. A variable whose value is unknown at compile time and is defined outside a SCoP counts as a parameter of the SCoPhardcfr-max-blocks— disables-fharden-control-flow-redundancyfor functions with more blocks than this value 🙈 Zero removes any limithardcfr-max-inline-blocks— forces-fharden-control-flow-redundancyto use out-of-line checking for functions with more basic blocks than this value 👑loop-block-tile-size— loop blocking or strip mining (turned on with-floop-blockor-floop-strip-mine) strip mines each loop in the loop nest by a given number of iterations 🌸 You can change that strip length with this parameteripa-jump-function-lookups— the number of statements visited during jump function offset discovery 🧚ipa-cp-value-list-size— IPA-CP tries to track every possible value and type passed to a function's parameter so it can propagate them and do devirtualization 💜 This is the max number of values and types it stores for each formal parameter of a functionipa-cp-eval-threshold— IPA-CP calculates its own score for cloning profitability, and it goes ahead with the cloning opportunities whose scores exceedipa-cp-eval-threshold🔥ipa-cp-max-recursive-depth— the max depth of recursive cloning for a self-recursive function 🌈ipa-cp-min-recursive-probability— recursive cloning only happens when the probability of the call being executed is higher than this parameter 💅ipa-cp-profile-count-base— okay bestie, 💖 when you compile with-fprofile-use, IPA-CP looks at the measured execution count of a call graph edge at this percentage spot in its histogram and uses that as the basis for its heuristics 📊✨ipa-cp-recursive-freq-factor— the number of times interprocedural copy propagation expects recursive functions to call themselves 🔁🌸ipa-cp-recursion-penalty— the percentage penalty recursive functions take when they're being evaluated for cloning 📉🦋ipa-cp-single-call-penalty— the percentage penalty that functions containing a single call to another function get when they're evaluated for cloning 📉🎀ipa-max-agg-items— IPA-CP can also propagate a bunch of scalar values passed inside an aggregate 🧺, and this one caps how many of those values you get per parameter 🙈ipa-cp-loop-hint-bonus— when IPA-CP realizes a cloning candidate would make a loop's number of iterations known, it adds this bonus to the candidate's profitability score ⭐🔥ipa-max-loop-predicates— the max number of different predicates IPA uses to describe when loops in a function have known properties 🧠💜ipa-max-aa-steps— while IPA-CP analyzes function bodies, it uses alias analysis to track values pointed to by function parameters 👀. To avoid spending forever on huge functions, it gives up after examining this many statements that modify memory and just treats all memory as clobbered 💀ipa-max-switch-predicate-bounds— the max number of boundary endpoints of case ranges in a switch statement 🍓. If a switch goes over this limit, IPA-CP won't build the cloning cost predicate for its default case 🙅♀️ipa-max-param-expr-ops— IPA-CP looks at conditional statements that reference a function parameter to estimate the benefit of cloning for a certain constant value 🔍. But if a parameter expression has more operations than this, it's considered too complicated and IPA analysis skips it 🚫
lto-partitions— the desired number of partitions made during WHOPR compilation 🧩. It should be bigger than the number of CPUs you're compiling with 💻lto-min-partition— the minimum size of a WHOPR partition, measured in estimated instructions 📏. This stops tiny programs from getting chopped into way too many pieces 🙃lto-max-partition— the max size of a WHOPR partition, in estimated instructions 📐. It's basically an upper bound for how big any single partition can get 🫶. It's only meant to be used with balanced partitioning ⚖️lto-max-streaming-parallelism— the max number of parallel processes used for LTO streaming 🌊✨cxx-max-namespaces-for-diagnostic-help— when C++ name lookup fails for an identifier, this is the max number of namespaces the compiler will check for suggestions 🔎💅
sink-frequency-threshold— the max relative execution frequency (in percent) of the target block compared to a statement's original block, which decides whether a statement can get sunk 🛁. Bigger numbers mean more aggressive sinking 🔥. Statements with memory operands get a small positive adjustment, since sinking them is even more profitable 💜max-stores-to-sink— the max number of conditional store pairs that can be sunk 🕳️. It's set to0if either vectorization (-ftree-vectorize) or if-conversion (-ftree-loop-if-convert) is turned off 🚫case-values-threshold— the smallest number of different values where a jump table is the better move over a tree of conditional branches 🌳. If it's0, the compiler uses the default for the machine 🖥️jump-table-max-growth-ratio-for-size— the max code size growth ratio (in percent) when expanding into a jump table 📦. This one is used when you're optimizing for size 🤏jump-table-max-growth-ratio-for-speed— same deal as above: the max code size growth ratio (in percent) when expanding into a jump table 📈. This one is used when you're optimizing for speed 🏎️tree-reassoc-width— sets the max number of instructions executed in parallel in a reassociated tree 🧵. If it has a non-zero value, it overrides the target-dependent heuristics that would normally be used 👑sched-pressure-algorithm— picks between the two available implementations of-fsched-pressure🧠. Algorithm 1 is the original one, and it's the more likely of the two to stop instructions from getting reordered 🙅. Algorithm 2 was designed as a compromise between algorithm 1's pretty conservative approach and the rather aggressive approach of the default scheduler 🎢. It leans harder on having a regular register file and accurate register pressure classes 📚. For more details, check outhaifa-sched.ccin the GCC sources 🗂️
The default choice depends on the target 🎯.
max-slsr-cand-scan— the max number of existing candidates considered when hunting for a basis for a new straight-line strength reduction candidate 🔍✨
asan-globals— turns on buffer overflow detection for global objects 🌍. This protection is on by default when you use-fsanitize=address. To turn off global objects protection, use--param asan-globals=0🙅♀️asan-stack— turns on buffer overflow detection for stack objects 🥞. This is on by default when using-fsanitize=address. To turn off stack protection, use--param asan-stack=0🚫asan-instrument-reads— turns on buffer overflow detection for memory reads 👀. It's on by default when using-fsanitize=address. To turn off memory reads protection, use--param asan-instrument-reads=0🙈asan-instrument-writes— turns on buffer overflow detection for memory writes ✍️. It's on by default when using-fsanitize=address. To turn off memory writes protection, use--param asan-instrument-writes=0🫠asan-memintrin— turns on detection for built-in functions 🧰. It's on by default when using-fsanitize=address. To turn off built-in functions protection, use--param asan-memintrin=0❌asan-use-after-return— turns on detection of use-after-return 🔙. This is on by default when you use the-fsanitize=addressoption. To turn it off, use--param asan-use-after-return=0💅
Heads up: this check is disabled at run time by default 😭. To enable it, add"detect_stack_use_after_return=1"to theASAN_OPTIONSenvironment variable 🌸.
asan-instrumentation-with-call-threshold— if a function being instrumented has at least this many memory accesses, the compiler uses callbacks instead of inline checks 📞. For example, to disable inline code, use--param asan-instrumentation-with-call-threshold=0🧚asan-kernel-mem-intrinsic-prefix— if it's nonzero, calls to"memcpy","memset"and"memmove"get prefixed with__asan_or__hwasan_for-fsanitize=kernel-addressor-fsanitize=kernel-hwaddress, respectively 🧩
hwasan-instrument-stack— turns on hwasan instrumentation for statically sized stack-allocated variables 🥞. This is enabled by default with-fsanitize=hwaddressand disabled by default with-fsanitize=kernel-hwaddress🔄. To turn stack instrumentation off, use--param hwasan-instrument-stack=0, and to turn it on, use--param hwasan-instrument-stack=1💖hwasan-random-frame-tag— when stack instrumentation is on, tags for stack variables come from a deterministic sequence that starts at a random tag for each frame 🎲. If this parameter isn't set, the tags use the same sequence but start from11️⃣. It's enabled by default for-fsanitize=hwaddressand unavailable for-fsanitize=kernel-hwaddress🙅. To turn it off, use--param hwasan-random-frame-tag=0🫶hwasan-instrument-allocas— turns on hwasan instrumentation for dynamically sized stack-allocated variables 🌀. Like the stack one, it's enabled by default with-fsanitize=hwaddressand disabled by default with-fsanitize=kernel-hwaddress🔁. To turn it off, use--param hwasan-instrument-allocas=0, and to turn it on, use--param hwasan-instrument-allocas=1🦋hwasan-instrument-reads— turns on hwasan checks on memory reads 👁️. Read instrumentation is enabled by default for both-fsanitize=hwaddressand-fsanitize=kernel-hwaddress✨. To stop checking memory reads, use--param hwasan-instrument-reads=0🙈hwasan-instrument-writes— turns on hwasan checks on memory writes ✍️. Write instrumentation is enabled by default for both-fsanitize=hwaddressand-fsanitize=kernel-hwaddress💅. To stop checking memory writes, use--param hwasan-instrument-writes=0🫠hwasan-instrument-mem-intrinsics— turns on hwasan instrumentation for built-in functions 🧰. This is enabled by default for both-fsanitize=hwaddressand-fsanitize=kernel-hwaddress💜. To turn off instrumentation of built-in functions, use--param hwasan-instrument-mem-intrinsics=0❌
use-after-scope-direct-emission-threshold— if a local variable's size in bytes is less than or equal to this number, the shadow memory gets poisoned (or unpoisoned) directly 🪄, instead of going through run-time callbacks 📞tsan-distinguish-volatile— emits special instrumentation for accesses to volatiles ⚡🌈tsan-instrument-func-entry-exit— emits instrumentation calls to__tsan_func_entry()and__tsan_func_exit()🦋🔥
🎀 Parloops, Vectorizer, and Friends 🎀
okay bestie, this next batch is all --param knobs, and they're giving tuning fork energy 🎶 each one controls how a specific optimization pass behaves 💅
max-fsm-thread-path-insns🦋 — the max number of instructions copied when duplicating blocks on a finite state automaton jump thread path.threader-debug🔍 —threader-debug=[none|all]turns on verbose dumping for the threader solver. Super useful when you're trying to see what it's thinking 🧠parloops-chunk-size🧩 — the chunk size of the omp schedule for loops thatparloopsparallelizes.parloops-schedule📅 — the schedule type of the omp schedule for those same parallelized loops. You can pickstatic,dynamic,guided,auto, orruntime🌈parloops-min-per-thread🧵 — the minimum number of iterations per thread for an innermost parallelized loop, where the parallel version beats the single-threaded one. Heads up: for a parallelized loop nest, the minimum iterations of the outermost loop per thread is two ✨max-ssa-name-query-depth🌀 — how deep the recursion can go when querying properties of SSA names in things like fold routines. One level of recursion means following a use-def chain 🔗max-speculative-devirt-maydefs👀 — the max number of may-defs we analyze while hunting for a must-def that tells us the dynamic type of an object making a virtual call we might speculatively devirtualize. Big brain stuff 🧠💜ranger-debug🖨️ — picks the type of debug output printed for ranges.unroll-jam-min-percent📉 — the minimum percentage of memory references that have to get optimized away for unroll-and-jam to count as profitable.unroll-jam-max-unroll🔁 — the max number of times the outer loop can be unrolled by unroll-and-jam.max-rtl-if-conversion-unpredictable-cost💸 — the most expensive the sequence from the RTL if-conversion pass can be for a branch that's considered unpredictable.max-variable-expansions-in-unroller🪞 — if-fvariable-expansion-in-unrolleris on, this caps how many times one variable gets expanded during loop unrolling.partial-inlining-entry-probability🎯 — the max probability of the entry BB of a split region (as a percent, relative to the function's entry BB) that still lets partial inlining happen.max-tracked-strlens📏 — how many strings the strlen optimization pass will track lengths for.gcse-after-reload-partial-fraction⚖️ — the threshold ratio for doing partial redundancy elimination after reload.gcse-after-reload-critical-fraction🛤️ — the threshold ratio of critical edge execution count that lets redundancy elimination happen after reload.max-loop-header-insns🧾 — the max number of insns in a loop header that the copy loop headers pass will duplicate.vect-epilogues-nomask🧁 — turns on loop epilogue vectorization using a smaller vector size.vect-partial-vector-usage🧩 — decides when the loop vectorizer will use partial vector loads and stores instead of falling back to scalar code:0means the vectorizer never uses partial vector loads and stores 🚫1allows them only if vectorizing removes the need for the code to iterate2allows them in all loops
This only does something on targets that actually support partial vector loads and stores 🎯
vect-inner-loop-cost-factor🧮 — the max factor the loop vectorizer applies to the cost of statements in an inner loop, compared to the loop being vectorized. The factor used is the max of the estimated inner loop iteration count and this parameter. The default value is50💯vect-induction-float🌊 — enables loop vectorization of floating point inductions.vrp-sparse-threshold🕸️ — the max number of basic blocks before VRP switches to a sparse bitmap cache.vrp-switch-limit🔀 — the max number of outgoing edges in a switch before VRP just skips it.vrp-vector-threshold📦 — the max number of basic blocks for VRP to use a basic cache vector.avoid-fma-max-bits🙅♀️ — the max number of bits for which we avoid creating FMAs.fully-pipelined-fma🚰 — whether the target fully pipelines FMA instructions. If it's non-zero, reassociation weighs the benefit of parallelizing the FMUL part and the FADD part, assuming FMUL and FMA use the same units that can also do FADD 🧠sms-loop-average-count-threshold🔢 — a threshold on the average loop count the swing modulo scheduler considers.sms-dfa-history🕰️ — how many cycles the swing modulo scheduler looks at when checking for conflicts using DFA.graphite-allow-codegen-errors🚨 — whether codegen errors should be ICEs when-fcheckingis on.sms-max-ii-factor🎚️ — a factor for tuning the upper bound the swing modulo scheduler uses when scheduling a loop.lra-max-considered-reload-pseudos🔎 — the max number of reload pseudos considered while spilling a non-reload pseudo.max-pow-sqrt-depth🌳 — the max depth of sqrt chains used when synthesizing exponentiation by a real constant.max-dse-active-local-stores🗃️ — the max number of active local stores in RTL dead store elimination.asan-instrument-allocas🛡️ — turns on asan protection for allocas and VLAs.max-iterations-computation-cost💰 — a bound on the cost of an expression used to compute the number of iterations.max-isl-operations♾️ — the max number of isl operations.0means unlimited.graphite-max-arrays-per-scop🧺 — the max number of arrays per scop.max-vartrack-reverse-op-size📐 — the max size of a loc list for which reverse ops should be added.fsm-scale-path-stmts⚖️ — a scale factor applied to the number of statements in a threading path that crosses a loop backedge, when comparing against--param=max-jump-thread-duplication-stmts.uninit-control-dep-attempts🔁 — the max number of nested calls used to search for control dependencies during uninitialized variable analysis.uninit-max-chain-len⛓️ — the max number of predicates anded together for each predicate ored in the normalized predicate chain.uninit-max-num-chains🔗 — the max number of predicates ored together in the normalized predicate chain.sched-autopref-queue-depth🧭 — a control flag for the hardware autoprefetcher scheduler model. It's the number of lookahead cycles the model looks into. At' ', it only enables the instruction sorting heuristic 🙈loop-versioning-max-inner-insns🪆 — the max number of instructions an inner loop can have before the loop versioning pass decides it's too big to copy.loop-versioning-max-outer-insns🪆 — the max number of instructions an outer loop can have before the loop versioning pass decides it's too big to copy. Any instructions in inner loops that directly benefit from versioning don't count toward this 🙌ssa-name-def-chain-limit⛓️💥 — the max number of SSA_NAME assignments to follow when figuring out a property of a variable, like its value. This caps the iterations or recursive calls GCC makes when optimizing certain statements or checking whether they're valid before issuing diagnostics 🧐store-merging-max-size📦 — the max size of a single store merging region, in bytes.hash-table-verification-limit✅ — the number of elements that get hash table verification for each searched element.max-find-base-term-values🔍 — the max number of VALUEs handled during a singlefind_base_termcall.analyzer-max-enodes-per-program-point🌐 — the max number of exploded nodes per program point in the analyzer. Once it hits this, analysis of that point stops 🛑analyzer-max-constraints🧱 — the max number of constraints per state.analyzer-min-snodes-for-call-summary📝 — the min number of supernodes inside a function before the analyzer considers summarizing its effects at call sites.analyzer-max-enodes-for-full-dump🗺️ — the max depth of exploded nodes that should show up in a dot dump before it switches to a less verbose format.analyzer-max-recursion-depth🌀 — the max number of times a callsite can appear in a call stack within the analyzer. Past that, analysis of a call that would recurse deeper gets terminated 🛑analyzer-max-svalue-depth🪜 — the max depth of a symbolic value before the analyzer approximates it as unknown ❔analyzer-max-infeasible-edges🚫 — the max number of infeasible edges to put up with before a diagnostic gets declared infeasible.gimple-fe-computed-hot-bb-threshold🔥 — the number of executions of a basic block that counts as hot. This parameter is only used in the GIMPLE FE 🧪analyzer-bb-explosion-factor💥 — the max number of "after supernode" exploded nodes per supernode in the analyzer, before analysis gets terminated.analyzer-text-art-string-ellipsis-threshold✂️ — the number of bytes where string literals get ellipsized in analyzer text art diagrams.analyzer-text-art-ideal-canvas-width🖼️ — the ideal width, in characters, of text art diagrams the analyzer generates.analyzer-text-art-string-ellipsis-head-len⏪ — the number of literal bytes shown at the head of a string literal in text art when it gets ellipsized.analyzer-text-art-string-ellipsis-tail-len⏩ — the number of literal bytes shown at the tail of a string literal in text art when it gets ellipsized.ranger-logical-depth🧠 — the max depth of logical expression evaluation that ranger looks through when evaluating outgoing edge ranges.ranger-recompute-depth🔄 — the max depth of instruction chains considered for recomputation in the outgoing range calculator.relation-block-limit🚧 — the max number of relations the oracle will register in a basic block.min-pagesize— the minimum page size, used for warning purposes 📄✨openacc-kernels— this one decides how OpenACCkernelsconstructs get handled 🌈--param=openacc-kernels=decompose— thekernelsconstructs get split into parts, a sequence of compute constructs, and each part is handled individually. This is work in progress 🚧--param=openacc-kernels=parloops— thekernelsconstructs are handled by the parloops pass, en bloc. This is the current default 👑
openacc-privatization— controls whether-fopt-info-omp-noteand applicable-fdump-tree-*-detailsoptions print OpenACC privatization diagnostics 🔍--param=openacc-privatization=quiet— no diagnostics. This is the current default 🤫--param=openacc-privatization=noisy— yep, do diagnose 📢
The following choices of name are available on AArch64 targets 🦾
aarch64-vect-compare-costs— when vectorizing, GCC can try a bunch of different approaches and let the cost model pick the cheapest one 💅 That includes:- trying both SVE and Advanced SIMD, when SVE is available
- trying to use 64-bit Advanced SIMD vectors for the smallest data elements, instead of using 128-bit vectors for everything
- trying to use "unpacked" SVE vectors for smaller elements. This includes storing smaller elements in larger containers and accessing elements with extending loads and truncating stores
aarch64-float-recp-precision— the number of Newton iterations used to calculate the reciprocal for thefloattype. The precision of division is proportional to this param when division approximation is enabled. The default value is1🎀aarch64-double-recp-precision— the number of Newton iterations used to calculate the reciprocal for thedoubletype. The precision of division is proportional to this param when division approximation is enabled. The default value is2🌸aarch64-autovec-preference— forces an ISA selection strategy for auto-vectorization. It accepts values from0to4, inclusive 🧚0— use the default heuristics1— use only Advanced SIMD for auto-vectorization2— use only SVE for auto-vectorization3— use both Advanced SIMD and SVE, and prefer Advanced SIMD when the costs are deemed equal4— use both Advanced SIMD and SVE, and prefer SVE when the costs are deemed equal
The default value is 0.
aarch64-ldp-policy— the fine-grained policy for load pairs 🔗--param=aarch64-ldp-policy=default— use the policy of the tuning structure. This is the current default 👑--param=aarch64-ldp-policy=always— emitldpregardless of alignment--param=aarch64-ldp-policy=never— do not emitldp--param=aarch64-ldp-policy=aligned— emitldponly if the source pointer is aligned to at least double the alignment of the type
aarch64-stp-policy— the fine-grained policy for store pairs 💜--param=aarch64-stp-policy=default— use the policy of the tuning structure. This is the current default 👑--param=aarch64-stp-policy=always— emitstpregardless of alignment--param=aarch64-stp-policy=never— do not emitstp--param=aarch64-stp-policy=aligned— emitstponly if the source pointer is aligned to at least double the alignment of the type
aarch64-ldp-alias-check-limit— the limit on the number of alias checks the AArch64 load/store pair fusion pass performs when it's trying to form anldp/stp🧠 Higher values make the pass more aggressive about re-ordering loads over stores, but at the cost of increased compile time ⏳aarch64-ldp-writeback— controls which writeback opportunities get handled in the AArch64 load/store pair fusion pass 🦋- a value of
0disables writeback handling - a value of
1means it tries to form pairs involving one or more existing individual writeback accesses where possible - a value of
2means it also tries to opportunistically form writeback opportunities by folding in trailing destructive updates of the base register used by a pair
- a value of
aarch64-loop-vect-issue-rate-niters— some AArch64 CPU tuning tries to weigh both latencies and issue rates when deciding whether a loop gets vectorized with SVE, vectorized with Advanced SIMD, or not vectorized at all 🤔 If this parameter is set ton, GCC will not use this heuristic for loops that are known to execute in fewer thannAdvanced SIMD iterationsaarch64-vect-unroll-limit— the vectorizer uses available tuning information to figure out whether it would be beneficial to unroll the main vectorized loop, and by how much. This param sets the upper bound on how much the vectorizer will unroll the main loop. The default value is four 🌷
The following choices of name are available on GCN targets 🎮
gcn-preferred-vectorization-factor— the preferred vectorization factor:default,32, or64🔥
The following choices of name are available on i386 and x86_64 targets 💻
x86-stlf-window-ninsns— the number of instructions above which an STFL stall penalty can be compensated 🫶x86-stv-max-visits— the maximum number of use and def visits when discovering an STV chain. If that count gets hit before discovery finishes, the discovery is aborted 🛑
✨ Program Instrumentation Options ✨
okay so GCC can add a whole bunch of run-time instrumentation to the code it normally generates 🕵️♀️💅 One reason to do this is to collect profiling stats so you can find program hot spots, do code coverage analysis, or run profile-guided optimizations 📊 Another kind is run-time checking, which catches programming errors like invalid pointer dereferences or out-of-bounds array accesses. It also helps against deliberately hostile attacks like stack smashing or C++ vtable hijacking 🛡️ And there's a general hook you can use to build other forms of tracing or function-level instrumentation for debugging or program analysis 🧩
-p,-pg— generates extra code to write profile information suitable for the analysis programprof(for-p) orgprof(for-pg) 📈 You must use this option when compiling the source files you want data about, and you must also use it when linking- you can use the function attribute
no_instrument_functionto suppress profiling of individual functions when compiling with these options 🙈
- you can use the function attribute
-fprofile-arcs— adds code so that program flow arcs are instrumented 🏹- during execution, the program records how many times each branch and call is executed, and how many times it is taken or returns. On targets that support constructors with priority support, profiling properly handles constructors, destructors, and C++ constructors (and destructors) of classes that are used as the type of a global variable 🧱
- when the compiled program exits, it saves this data to a file called
auxname.gcdafor each source file. The data may be used for profile-directed optimizations (-fbranch-probabilities), or for test coverage analysis (-ftest-coverage) 💖 - each object file's
auxnameis generated from the name of the output file, if it's explicitly specified and it is not the final executable. Otherwise it's the basename of the source file. In both cases any suffix is removed. For example,foo.gcdafor input filedir/foo.c, ordir/foo.gcdafor output file specified as-o dir/foo.o🍓 - note that if a command line directly links source files, the corresponding
.gcdafiles will be prefixed with the unsuffixed name of the output file. E.g.gcc a.c b.c -o binarywould generatebinary-a.gcdaandbinary-b.gcdafiles 🌈
-fcondition-coverage— adds code so that program conditions are instrumented 🧪 During execution, the program records which terms in a conditional contribute to a decision. You can use this to verify that all terms in a Boolean function are tested and have an independent effect on the outcome of a decision. The result can be read withgcov --conditions🦋--coverage— the option you use to compile and link code instrumented for coverage analysis 🎀 It's a synonym for-fprofile-arcs-ftest-coverage(when compiling) and-lgcov(when linking). See the documentation for those options for more details 📚- Compile the source files with
-fprofile-arcsplus optimization and code generation options. For test coverage analysis, use the additional-ftest-coverageoption. You don't need to profile every source file in a program 💅 - Compile the source files additionally with
-fprofile-abs-pathto create absolute path names in the.gcnofiles. This lets gcov find the correct sources in projects where compilations happen with different working directories 🗺️ - Link your object files with
-lgcovor-fprofile-arcs(the latter implies the former) 🔗 - Run the program on a representative workload to generate the arc profile information. This may be repeated any number of times. You can run concurrent instances of your program, and provided that the file system supports locking, the data files will be correctly updated. Unless a strict ISO C dialect option is in effect, "fork" calls are detected and correctly handled without double counting 🍴
- Compile the source files with
Moreover, an object file can be recompiled multiple times, and the corresponding .gcda file merges as long as the source file and the compiler options are unchanged 🫶
- For profile-directed optimizations, compile the source files again with the same optimization and code generation options plus
-fbranch-probabilities👑 - For test coverage analysis, use
gcovto produce human-readable information from the.gcnoand.gcdafiles. Refer to the gcov documentation for further information 🧁
With -fprofile-arcs, GCC builds a program flow graph for every function in your program and then finds a spanning tree for it ✨ Only the arcs that aren't on that tree need instrumenting, so the compiler just adds code to count how many times those arcs get executed 🧚 If an arc is the only exit or only entrance to a block, the counting code can go right into that block. Otherwise GCC has to make a brand new basic block to hold it 🫶
And with -fcondition-coverage, GCC creates a bitset for each conditional in your program and records the exercised boolean values that have an independent effect on the outcome of that expression 🦋
-ftest-coverage— okay bestie, this one makes a notes file that thegcovcode-coverage utility can use to show your program coverage 📊 Each source file's notes file is calledauxname.gcno. Check the-fprofile-arcsentry above for what auxname means and how to generate test coverage data. Also, coverage data matches your source files way more closely if you don't optimize 💅-fprofile-abs-path— this automatically turns relative source file names into absolute path names inside the.gcnofiles 🗺️ That waygcovcan find the right sources even in projects that compile from different working directories 💖-fprofile-dir=path— sets the directory where profile data files get searched for to path 📁 This only affects the profile data made by-fprofile-generate,-ftest-coverage, and-fprofile-arcs, and used by-fprofile-useand-fbranch-probabilitiesplus its related options. Both absolute and relative paths work. By default GCC uses the current directory, so the profile data file lands in the same directory as the object file. To avoid file name clashes, if the object file name isn't an absolute path, GCC mangles the absolute path of the sourcename.gcdafile and uses that as the name of the.gcdafile. Peek-fprofile-arcsfor the full file naming details. There's also a similar option,-fprofile-note. When an executable runs in a massive parallel environment, it's recommended to save profiles to different folders 🌈 You can do that with variables in path that get exported at run-time:%p— the process ID 🆔%q{VAR}— the value of the environment variableVAR🌸
-fprofile-generate,-fprofile-generate=path— this turns on the options you usually want for instrumenting an app so it can produce a profile for later recompilation with profile feedback based optimization 🔥 You must use-fprofile-generateboth when compiling and when linking your program 🚨 It enables-fprofile-arcs,-fprofile-values,-finline-functions, and-fipa-bit-cp. If path is specified, GCC looks there for the profile feedback data files (see-fprofile-dir). To optimize the program based on the collected profile information, use-fprofile-use✨-fprofile-info-section,-fprofile-info-section=name— this registers the profile information in a specified section instead of using a constructor/destructor 🧩 The section name is name if you give one, otherwise it defaults to.gcov_info. A pointer to the profile information made by-fprofile-arcsgets placed in that section for each translation unit. This option turns off the profile information registration through a constructor, and it also turns off the profile information processing through a destructor. Heads up: this is not meant for hosted environments like GNU/Linux 🙅♀️ It targets freestanding environments (like embedded systems) with limited resources that don't support constructors/destructors or C library file I/O.
The linker could collect the input sections into one continuous memory block and define start and end symbols 🧠 Here's a GNU linker script example that defines a linker output section:
.gcov_info :
{
PROVIDE (__gcov_info_start = .);
KEEP (*(.gcov_info))
PROVIDE (__gcov_info_end = .);
}The program could then dump the profiling information registered in this linker set. For example, like this 🎀
#include <gcov.h>
#include <stdio.h>
#include <stdlib.h>
extern const struct gcov_info *const __gcov_info_start[];
extern const struct gcov_info *const __gcov_info_end[];
static void
dump (const void *d, unsigned n, void *arg)
{
const unsigned char *c = d;
for (unsigned i = 0; i < n; ++i)
printf ("%02x", c[i]);
}
static void
filename (const char *f, void *arg)
{
__gcov_filename_to_gcfn (f, dump, arg );
}
static void *
allocate (unsigned length, void *arg)
{
return malloc (length);
}
static void
dump_gcov_info (void)
{
const struct gcov_info *const *info = __gcov_info_start;
const struct gcov_info *const *end = __gcov_info_end;
/* Obfuscate variable to prevent compiler optimizations. */
__asm__ ("" : "+r" (info));
while (info != end)
{
void *arg = NULL;
__gcov_info_to_gcda (*info, filename, dump, allocate, arg);
putchar ('\n');
++info;
}
}
int
main (void)
{
dump_gcov_info ();
return 0;
}The merge-stream subcommand of gcov-tool can deserialize the data stream generated by the __gcov_filename_to_gcfn and __gcov_info_to_gcda functions, then merge the profile information into .gcda files on the host filesystem 💜
-fprofile-note=path— if path is specified, GCC saves the.gcnofile into that location 📝 Heads up: if you combine this with multiple source files, the.gcnofile will get overwritten 😭-fprofile-prefix-path=path— use this withprofile-generate=profile_dirandprofile-use=profile_dirto tell GCC where the base directory of your built source tree is 🌳 By default, profile_dir will contain files with mangled absolute paths of all object files in the built project. That's not ideal when the directory used to build the instrumented binary is different from the one used to build the binary optimized with profile feedback, because the profile data won't be found during the optimized build 💀 In setups like that,-fprofile-prefix-path=path, with path pointing to the base directory of the build, strips the irrelevant part of the path and keeps all file names relative to the main build directory ✨-fprofile-prefix-map=old=new— when compiling files living in directory old, GCC records their profiling information (with--coverage) as if they lived in directory new instead 🗺️ See also-ffile-prefix-mapand-fcanon-prefix-map.-fprofile-update=method— this changes the update method for an app instrumented for profile feedback based optimization 🔄 The method argument should be one ofsingle,atomic, orprefer-atomic. The first one is good for single-threaded apps, and the second one prevents profile corruption by emitting thread-safe code 🧵
Warning: When an application doesn't properly join all threads (or creates a detached thread), a profile file can still get corrupted 😱
Using prefer-atomic gets transformed either into atomic (when the target supports it) or into single otherwise. The GCC driver automatically picks prefer-atomic when -pthread is in the command line. Otherwise the default method is single 🎀
If atomic is selected, the profile information is updated using atomic operations on a best-effort basis. Ideally, it's updated through atomic operations in hardware. If the target platform doesn't support the required atomic operations in hardware, but libatomic is available, the profile information gets updated through calls to libatomic. If the target platform supports neither the required hardware atomics nor libatomic, the profile information is not atomically updated and a warning is issued. In that case, the profiling information may be corrupt for multi-threaded applications 🥲
For performance reasons, if 64-bit counters are used for the profiling information and the target platform only supports 32-bit atomic operations in hardware, then the performance critical profiling updates are done using two 32-bit atomic operations for each counter update. If a signal interrupts these two operations while updating a counter, the profiling information may end up in an inconsistent state 🙈
-fprofile-filter-files=regex— instruments only the functions from files whose name matches any of the regular expressions (separated by semicolons) 🔍 For example,-fprofile-filter-files=main\.c;module.*\.cwill instrument onlymain.cand all C files starting with 'module' 🧚-fprofile-exclude-files=regex— instruments only the functions from files whose name does not match any of the regular expressions (separated by semicolons) 🚫 For example,-fprofile-exclude-files=/usr/.*will prevent instrumentation of all files located in the/usr/folder 🙅♀️-fprofile-reproducible=[multithreaded|parallel-runs|serial]— controls the level of reproducibility of the profile gathered by-fprofile-generate🧁 This makes it possible to rebuild a program with the same outcome, which is super useful for things like distribution packages 📦 With-fprofile-reproducible=serial, the profile gathered by-fprofile-generateis reproducible, provided the trained program behaves the same at each invocation of the train run, it is not multi-threaded, and profile data streaming is always done in the same order 💅 Note that profile streaming happens at the end of the program run, but also before theforkfunction is invoked 🫶
Okay so bestie, here's the deal with reproducibility 🧚✨: execution counts in some parts of a program can depend on stuff like how long temporary file names are, or on memory space randomization (which can shift the hash-table collision rate) 🙈. That non-reproducible bit can be marked with the "no_instrument_function" function attribute 💅. And if you want to check that your gathered data is actually reproducible, gcov-dump with -l can dump it out so you can see for yourself 🔍.
With -fprofile-reproducible=parallel-runs, the collected profile stays reproducible no matter what order the data gets streamed into the gcda files 💖. This is the move if you want to run multiple instances of your instrumented program in parallel, like with make -j 🏃♀️. Just know it's a trade-off: it reduces the quality of the gathered data, especially for indirect call profiling 😭.
-fsanitize=address— Turns on AddressSanitizer 🦋, a super fast memory error detector. Memory access instructions get instrumented to catch out-of-bounds and use-after-free bugs, and it also enables-fsanitize-address-use-after-scope. More details live athttps://github.com/google/sanitizers/wiki/AddressSanitizer. Run-time behavior can be tweaked with theASAN_OPTIONSenvironment variable, and if you set it to "help=1", the available options get shown when your instrumented program starts. For the full list of supported options, peephttps://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags. This one can't be combined with-fsanitize=threador-fsanitize=hwaddress🙅♀️, and the only target-fsanitize=hwaddressis currently supported on is AArch64.
To get more accurate stack traces 🔥, you can use options like -O0, -O1, or -Og (which, for instance, prevent most function inlining), -fno-optimize-sibling-calls (which stops sibling and tail recursive calls from getting optimized; this option is implicit for -O0, -O1, or -Og), or -fno-ipa-icf (which disables Identical Code Folding for functions). Since multiple runs of the program can give you backtraces with different addresses thanks to ASLR (Address Space Layout Randomization), it may be desirable to turn ASLR off 🌈. On Linux, you can do that with:
setarch `uname -m` -R ./prog-fsanitize=kernel-address— Enables AddressSanitizer for the Linux kernel 🐧. Check outhttps://github.com/google/kernel-sanitizersfor more details.-fsanitize=hwaddress— Hardware-assisted AddressSanitizer 🛠️ uses a hardware ability to ignore the top byte of a pointer, so it can catch memory errors with a low memory overhead 💜. Memory access instructions get instrumented to detect out-of-bounds and use-after-free bugs. It enables-fsanitize-address-use-after-scope. Seehttps://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.htmlfor more details. Run-time behavior is influenced through theHWASAN_OPTIONSenvironment variable, and when it's set to "help=1", the available options show at startup of the instrumented program. It can't be combined with-fsanitize=threador-fsanitize=address, and it's currently only available on AArch64 🙃.-fsanitize=kernel-hwaddress— Enables Hardware-assisted AddressSanitizer for compiling the Linux kernel 🐧✨. It's similar to-fsanitize=kernel-addressbut uses an alternate instrumentation method, and it's similar to-fsanitize=hwaddressbut with the instrumentation differences the kernel needs. Those differences exist to avoid hwasan library initialization calls, and to account for the stack pointer having a different value in its top byte.
Note: This option has different defaults to-fsanitize=hwaddress. Instrumenting the stack and alloca calls is not on by default, but it's still possible by specifying the command-line options--param hwasan-instrument-stack=1and--param hwasan-instrument-allocas=1respectively. Using a random frame tag is not implemented for kernel instrumentation.
-fsanitize=pointer-compare— Instruments comparison operations (<,<=,>,>=) with pointer operands 🔍. It must be combined with either-fsanitize=kernel-addressor-fsanitize=address, and it can't be combined with-fsanitize=thread. Note: by default the check is disabled at run time 😴. To turn it on, add "detect_invalid_pointer_pairs=2" to theASAN_OPTIONSenvironment variable. Using "detect_invalid_pointer_pairs=1" only detects invalid operation when both pointers are non-null.-fsanitize=pointer-subtract— Instruments subtraction with pointer operands ➖. It must be combined with either-fsanitize=kernel-addressor-fsanitize=address, and it can't be combined with-fsanitize=thread. Note: by default the check is disabled at run time 😴. To enable it, add "detect_invalid_pointer_pairs=2" to theASAN_OPTIONSenvironment variable. Using "detect_invalid_pointer_pairs=1" only detects invalid operation when both pointers are non-null.-fsanitize=shadow-call-stack— Enables ShadowCallStack 🛡️, a security enhancement that protects programs against return address overwrites (like stack buffer overflows.) It works by saving a function's return address to a separately allocated shadow call stack in the function prologue, then restoring the return address from the shadow call stack in the function epilogue. Instrumentation only happens in functions that need to save the return address to the stack.
Heads up, this one's picky 💅: it's currently only supported on the aarch64 platform. It's specifically designed for Linux kernels that enable the CONFIG_SHADOW_CALL_STACK option. For user space programs, runtime support isn't currently provided in libc and libgcc, so if you want this feature in user space, you need to provide your own runtime support. It should be noted that this may cause the ABI rules to be broken 🚨.
On aarch64, the instrumentation makes use of the platform register "x18" 🧠. That generally means any code that may run on the same thread as code compiled with ShadowCallStack must be compiled with the flag -ffixed-x18. Otherwise, functions compiled without -ffixed-x18 might clobber "x18" and corrupt the shadow stack pointer 💀.
Also, because there's no userspace runtime support, code compiled with ShadowCallStack can't use exception handling. Use -fno-exceptions to turn off exceptions 🙅♀️. See https://clang.llvm.org/docs/ShadowCallStack.html for more details.
-fsanitize=thread— Enables ThreadSanitizer 🧵, a fast data race detector. Memory access instructions get instrumented to detect data race bugs. Seehttps://github.com/google/sanitizers/wiki#threadsanitizerfor more details. The run-time behavior can be influenced using theTSAN_OPTIONSenvironment variable; seehttps://github.com/google/sanitizers/wiki/ThreadSanitizerFlagsfor a list of supported options. It can't be combined with-fsanitize=addressor-fsanitize=leak🚫.
Note that sanitized atomic builtins cannot throw exceptions when operating on invalid memory addresses with non-call exceptions (-fnon-call-exceptions).
-fsanitize=leak— Enables LeakSanitizer 💧, a memory leak detector. This option only matters for linking executables. The executable gets linked against a library that overrides "malloc" and other allocator functions. Seehttps://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizerfor more details. The run-time behavior can be influenced using theLSAN_OPTIONSenvironment variable. It can't be combined with-fsanitize=thread.-fsanitize=undefined— Enables UndefinedBehaviorSanitizer 🌀, a fast undefined behavior detector. Various computations get instrumented to catch undefined behavior at runtime. Seehttps://clang.llvm.org/docs/UndefinedBehaviorSanitizer.htmlfor more details. The run-time behavior can be influenced using theUBSAN_OPTIONSenvironment variable. These are the current suboptions:-fsanitize=shift— Checks that the result of a shift operation isn't undefined 🫶. What's considered undefined differs slightly between C and C++, as well as between ISO C90 and C99, etc. This option has two suboptions,-fsanitize=shift-baseand-fsanitize=shift-exponent.-fsanitize=shift-exponent— Checks that the second argument of a shift operation isn't negative and is smaller than the precision of the promoted first argument.-fsanitize=shift-base— If the second argument of a shift operation is within range, checks that the result of the shift isn't undefined. What's considered undefined differs slightly between C and C++, as well as between ISO C90 and C99, etc.-fsanitize=integer-divide-by-zero— Detects integer division by zero ➗.-fsanitize=unreachable— The compiler turns the__builtin_unreachablecall into a diagnostics message call instead. When you reach the__builtin_unreachablecall, the behavior is undefined 💀.-fsanitize=vla-bound— Tells the compiler to check that the size of a variable length array is positive 📏.-fsanitize=null— Enables pointer checking 👀. Apps built with this on will throw an error message when they try to dereference a NULL pointer, when a reference (possibly an rvalue reference) gets bound to a NULL pointer, or when a method is invoked on an object pointed to by a NULL pointer.-fsanitize=return— Enables return statement checking 🔙. Programs built with this on will throw an error message when the end of a non-void function is reached without actually returning a value. This option works in C++ only.-fsanitize=signed-integer-overflow— Enables signed integer overflow checking ➕. It checks that the result of "+", "*", and both unary and binary "-" doesn't overflow in signed arithmetic. This also detectsINT_MIN / -1signed division. Heads up, integer promotion rules have to be taken into account, which means the following is not an overflow 🙈:
signed char a = SCHAR_MAX;
a++;-fsanitize=bounds— okay so this one turns on array bounds instrumentation 🎀 and catches a bunch of out-of-bounds accesses 💅. Flexible array members, flexible-array-member-like arrays, and initializers of variables with static storage are not instrumented, with one exception: flexible-array-member-like arrays that-fstrict-flex-arrays,-fstrict-flex-arrays=, or thestrict_flex_arrayattribute say shouldn't be treated that way do get checked 🦋-fsanitize=bounds-strict— the stricter, no-excuses version 🔥 It catches most out-of-bounds accesses, including flexible-array-member-like arrays. Initializers of variables with static storage still aren't instrumented 🙈-fsanitize=alignment— checks pointer alignment when a pointer gets dereferenced 🌸 It also checks when a reference is bound to an insufficiently aligned target, and when a method or constructor gets called on an insufficiently aligned object ✨-fsanitize=object-size— instruments memory references using the__builtin_dynamic_object_sizefunction 🧚 It's how various out-of-bounds pointer accesses get detected 👑-fsanitize=float-divide-by-zero— detects floating-point division by zero 🌈 Unlike other similar options, this one is not turned on by-fsanitize=undefined, because dividing by zero in floating point can be a legit way to get infinities and NaNs 🤷♀️-fsanitize=float-cast-overflow— enables checking whenever a floating-point value gets converted to an integer 💖 It makes sure the result of that conversion doesn't overflow ✨ Also, this one is not turned on by-fsanitize=undefined, just like the other special ones 🍓
Heads up bestie: this option does not work well with FE_INVALID exceptions enabled 😭
-fsanitize=nonnull-attribute— instruments calls to check that null values aren't passed to arguments marked as requiring a non-null value by thenonnullfunction attribute 🫶-fsanitize=returns-nonnull-attribute— instruments return statements in functions marked with thereturns_nonnullfunction attribute 🦋 It catches those functions returning null values, which is a big no-no 💀-fsanitize=bool— instruments loads frombool💜 If a value other than 0/1 gets loaded, you get a run-time error 🚨-fsanitize=enum— instruments loads from an enum type 🍓 If a value outside the enum's range of values gets loaded, a run-time error is issued 💅-fsanitize=vptr— instruments C++ member function calls, member accesses, and some conversions between pointers to base and derived classes 👑 It verifies the referenced object has the correct dynamic type, so nothing sneaky happens 🧚-fsanitize=pointer-overflow— instruments pointer arithmetic 🌸 If the pointer arithmetic overflows, a run-time error is issued 🔥-fsanitize=builtin— instruments the arguments to selected builtin functions 🎀 If an invalid value gets passed to one of those arguments, a run-time error is issued ⭐ For example, passing0as the argument to__builtin_ctzor__builtin_clzinvokes undefined behavior, and this option diagnoses it 🙈
Quick vibe check on sanitizers in general: they tend to bring along extra false positive warnings, especially the ones around -Wmaybe-uninitialized 😭 We recommend against combining -Werror and the use of sanitizers, so you don't get stuck on warnings that aren't even real 🫶
While -ftrapv causes traps for signed overflows to be emitted, -fsanitize=undefined gives a diagnostic message instead 💖 This currently works only for the C family of languages 🌈
-fno-sanitize=all— disables all the sanitizers you turned on before 🧹 Note that-fsanitize=allis not allowed, because some sanitizers can't be used together 💀-fasan-shadow-offset=number— forces GCC to use a custom shadow offset in AddressSanitizer checks ✨ It's super useful for experimenting with different shadow memory layouts in Kernel AddressSanitizer 🧪-fsanitize-sections=s1,s2,...— sanitizes global variables in selected user-defined sections 🦋 Eachsimay contain wildcards 🌸-fsanitize-recover[=opts]— okay this one controls the error recovery mode for the sanitizers in the comma-separated list ofopts💅 When recovery is enabled for a sanitizer, the program keeps running like no error happened 🫠 That means multiple runtime errors can get reported in one run, and the exit code may say success even when errors were reported 🙈
The -fno-sanitize-recover= option flips that around: only the first detected error gets reported, and then the program exits with a non-zero exit code 🚫
Right now this feature only works for -fsanitize=undefined (and its suboptions, except -fsanitize=unreachable and -fsanitize=return), -fsanitize=float-cast-overflow, -fsanitize=float-divide-by-zero, -fsanitize=bounds-strict, -fsanitize=kernel-address, and -fsanitize=address 🌈 For these sanitizers, error recovery is turned on by default, except for -fsanitize=address, where it's still experimental 🧪
-fsanitize-recover=all and -fno-sanitize-recover=all are also accepted 💜 The first enables recovery for all sanitizers that support it, and the second disables recovery for all sanitizers that support it ✨
Even if recovery mode is turned on at the compiler side, it also needs to be enabled on the runtime library side, otherwise the failures are still fatal 😭 The runtime library defaults to halt_on_error=0 for ThreadSanitizer and UndefinedBehaviorSanitizer, while the default value for AddressSanitizer is halt_on_error=1 🎀 You can override this by setting the halt_on_error flag in the corresponding environment variable 🌸
Syntax without an explicit opts parameter is deprecated 🙅♀️ It's equivalent to specifying this opts list:
undefined,float-cast-overflow,float-divide-by-zero,bounds-strict-fsanitize-address-use-after-scope— enables sanitization of local variables so you can catch use-after-scope bugs 🕵️♀️ This option sets-fstack-reusetonone🫶-fsanitize-trap[=opts]— this one tells the compiler to report undefined behavior for the sanitizers in the comma-separatedoptslist using__builtin_trapinstead of alibubsanlibrary routine 🪤 If it's enabled for a sanitizer, it takes precedence over-fsanitizer-recover=for that sanitizer, so__builtin_trapgets emitted and it's fatal whether recovery is on or off 💀- The big perk is that the
libubsanlibrary isn't needed and isn't linked in, so this works even in freestanding environments 🧚 - Right now it works with
-fsanitize=undefined(and its suboptions, except-fsanitize=vptr),-fsanitize=float-cast-overflow,-fsanitize=float-divide-by-zero, and-fsanitize=bounds-strict🌈 -fsanitize-trap=allcan also be specified, which enables it for theundefinedsuboptions,-fsanitize=float-cast-overflow,-fsanitize=float-divide-by-zero, and-fsanitize=bounds-strict💖- If
-fsanitize-trap=undefinedor-fsanitize-trap=allis used and-fsanitize=vptris enabled on the command line, the instrumentation is silently ignored 🤐 That's because the instrumentation always needslibubsansupport 📚 -fsanitize-trap=vptris not allowed 🚫
- The big perk is that the
-fsanitize-undefined-trap-on-error— this one is deprecated, but it's an equivalent of-fsanitize-trap=all🥀-fsanitize-coverage=trace-pc— enables coverage-guided fuzzing code instrumentation 🐛 It inserts a call to__sanitizer_cov_trace_pcinto every basic block 🧩-fsanitize-coverage=trace-cmp— enables dataflow guided fuzzing code instrumentation 🔍 Here's who gets called when:__sanitizer_cov_trace_cmp1,__sanitizer_cov_trace_cmp2,__sanitizer_cov_trace_cmp4, or__sanitizer_cov_trace_cmp8for integral comparisons where both operands are variables 🔢__sanitizer_cov_trace_const_cmp1,__sanitizer_cov_trace_const_cmp2,__sanitizer_cov_trace_const_cmp4, or__sanitizer_cov_trace_const_cmp8for integral comparisons where one operand is a constant 🎯__sanitizer_cov_trace_cmpfor__sanitizer_cov_trace_cmpdfor float or double comparisons 🦋__sanitizer_cov_trace_switchfor switch statements 🔀
-fcf-protection=[full|branch|return|none|check]— enables code instrumentation of control-flow transfers to boost program security 🛡️ It checks that the target addresses of control-flow transfer instructions (like indirect function calls, function returns, and indirect jumps) are valid, so the flow of control can't get diverted to some unexpected target 👑 This is meant to protect against threats like Return-oriented Programming (ROP), and similarly call/jmp-oriented programming (COP/JOP) 😈branchchecks validity of control-flow transfers at indirect branch instructions, i.e. call/jmp instructions 🌿returnchecks validity at the point of returning from a function 🔙fullis an alias for specifying bothbranchandreturn💜noneturns off instrumentation 🚫checkis used for the final link with link-time optimization (LTO) 🔗 An error is issued if LTO object files were compiled with different-fcf-protectionvalues 🚨 It's ignored at compile time 🙃
To override -fcf-protection, you need to add -fcf-protection=none and then add -fcf-protection=xxx after it 🔁
The __CET__ macro is defined when -fcf-protection is used ✨ The first bit of __CET__ is set to 1 for the value branch, and the second bit of __CET__ is set to 1 for return 🧠
You can also use the nocf_check attribute to identify which functions and calls should be skipped from instrumentation 🙅♀️
Currently, the x86 GNU/Linux target provides an implementation based on Intel Control-flow Enforcement Technology (CET), which works for i686 processors or newer 💻
NOTE: NOTE: In Ubuntu 19.10 and later versions, -fcf-protection gets turned on by default for C, C++, ObjC, and ObjC++ 🌈, as long as neither -fno-cf-protection nor -fcf-protection=* shows up in your command 🫶.
🎀 -fharden-compares
okay so this one goes after every logical test that makes it through gimple optimizations and isn't the condition in a conditional branch 👀. Think conditional moves, or tests stored in boolean variables. GCC adds extra code that computes and verifies the reversed condition, and if the results don't match it calls __builtin_trap 💀. Pair it with -fharden-conditional-branches to cover all the conditionals, bestie ✨.
🦋 -fharden-conditional-branches
For every non-vectorized conditional branch that survives gimple optimizations, GCC adds extra code that computes and verifies the reversed condition 🔥. If the result is unexpected, it calls __builtin_trap. Use it with -fharden-compares so nothing slips through 💅.
🌸 -fharden-control-flow-redundancy
this one is giving main character energy 👑. GCC emits extra code that sets booleans when it enters basic blocks, then at function exits it verifies them and traps if they don't form an execution path that matches the control flow graph 😭.
The verification happens before returns, and before mandatory tail calls (more on those below). It can also happen, if you ask for it, before escaping exceptions with -fhardcfr-check-exceptions, before returning calls with -fhardcfr-check-returning-calls, and before noreturn calls with -fhardcfr-check-noreturn-calls. There are tuning knobs too: --param hardcfr-max-blocks and --param hardcfr-max-inline-blocks ⚙️.
Tail call optimization happens too late to mess with control flow redundancy 🙈. Calls that language front-ends mark as mandatory tail calls, and any calls marked early enough as potential tail calls, would also get verification before the call. But honestly these cases are merely theoretical, since they can only come up when you're using custom compiler plugins 🧚.
🧚 -fhardcfr-skip-leaf
Disables -fharden-control-flow-redundancy in leaf functions 🌿.
💜 -fhardcfr-check-exceptions
When -fharden-control-flow-redundancy is active, the recorded execution path gets checked against the control flow graph at exception escape points 🦋. It's like the function body is wrapped in a cleanup handler that does the check and then reraises. This one is enabled by default ✨. If you want it gone, use -fno-hardcfr-check-exceptions.
🍓 -fhardcfr-check-returning-calls
When -fharden-control-flow-redundancy is active, the recorded path gets checked before any function call that's immediately followed by a return of its result (if it has one) 💅. This keeps tail-call optimization working, whether or not the call actually ends up optimized into a tail call.
This option is enabled by default whenever sibling call optimizations are on (see -foptimize-sibling-calls) 🫶. But you can flip it on or off explicitly with its negated form, no matter what the optimizations are doing.
🌈 -fhardcfr-check-noreturn-calls=[always|no-xthrow|nothrow|never]
When -fharden-control-flow-redundancy is active, the recorded path gets checked before noreturn calls. You get to pick which ones:
always— checks before all of them 🔒no-xthrow— checks before those not expected to return control to the caller through an exception. This is the default 💖nothrow— checks before those that may not return control to the caller through an exception either 🌸never— checks before none of them 🙅
Checking before a noreturn function that may return control through an exception can get you checked more than once, if the caller catches that exception with a handler or a cleanup 😭. When -fhardcfr-check-exceptions is also on, the compiler skips associating a noreturn call with the implicit cleanup handler, since it'd be redundant with the check before the call ✨. Other handlers or cleanups in the function, if they're activated, will modify the recorded path and check it again when another checkpoint gets hit. That checkpoint could even be another noreturn call, so the checking may end up happening multiple times 🔁.
Okay here's the tea ☕. Various optimizers may cause calls to be marked noreturn and/or nothrow even without the matching attributes, and that can shift where checks land before calls, as well as which implicit cleanup handlers get added 🙈. That unpredictability, plus the fact that raising and reraising exceptions often amounts to implicitly calling noreturn functions, is why no-xthrow is the default. It excludes from the noreturn treatment only the internal functions used to (re)raise exceptions, which those optimizations don't touch 💅.
👑 -fhardened
Enables a set of flags for C and C++ that boost the security of the generated code without messing with its ABI 🛡️. The exact flags can change between major GCC releases, but right now they are:
-D_FORTIFY_SOURCE=3 -D_GLIBCXX_ASSERTIONS
-ftrivial-auto-var-init=zero -fPIE -pie -Wl,-z,relro,-z,now
-fstack-protector-strong -fstack-clash-protection
-fcf-protection=full (x86 GNU/Linux only)You can see the whole list yourself with --help=hardened 👀.
If the system glibc is older than 2.35, -D_FORTIFY_SOURCE=2 gets used instead 🧸.
This option is meant for production builds, not just debug builds. It's not a debug-only vibe 💀.
Right now -fhardened only works on GNU/Linux targets 🐧.
Also, -fhardened only turns on a particular option if you haven't already specified it somewhere on the command line 🙅. For example, -fhardened -fstack-protector will only enable -fstack-protector, but not -fstack-protector-strong ✨.
🛡️ -fstack-protector
Emits extra code to check for buffer overflows, like stack smashing attacks 🚨. It works by adding a guard variable to functions with vulnerable objects. That includes functions that call alloca, and functions with buffers larger than or equal to 8 bytes. The guards get initialized when the function is entered and checked when it exits. If a guard check fails, an error message is printed and the program exits 💀. Only variables that are actually allocated on the stack count. Optimized-away variables or variables living in registers don't 🧠.
🛡️ -fstack-protector-all
Like -fstack-protector, except all functions get protected 🫡.
🛡️ -fstack-protector-strong
Like -fstack-protector, but it also protects extra functions: the ones with local array definitions, or ones that reference local frame addresses 🍓. Same rule as before, only variables actually allocated on the stack count, and optimized-away or register variables don't.
NOTE: In Ubuntu 14.10 and later versions, -fstack-protector-strong is enabled by default for C, C++, ObjC, ObjC++, if none of -fno-stack-protector, -nostdlib, nor -ffreestanding are found 🌸.
🛡️ -fstack-protector-explicit
Like -fstack-protector, but it only protects functions that have the stack_protect attribute 🎯.
🧭 -fstack-check
Generates code to verify that you don't go past the boundary of the stack 🧭. You should specify this if you're running in an environment with multiple threads 🧵. In a single-threaded environment you rarely need it, because stack overflow is automatically detected on nearly all systems if there's only one stack 💅.
Here's the tea: this switch doesn't actually do the checking 🫠. The operating system or the language runtime has to do that. The switch just makes the code that ensures they see the stack being extended 👀.
You can also pass a string parameter 🎀:
no— no checking at all 🙅generic— forces the use of old-style checking 🕰️specific— uses the best checking method, and is equivalent to bare-fstack-check✨
Old-style checking is a generic mechanism. It doesn't need any specific target support in the compiler, but it comes with some drawbacks 😭:
- Modified allocation strategy for large objects. They're always allocated dynamically if their size goes over a fixed threshold. Note this may change the semantics of some code ⚠️.
- Fixed limit on the size of the static frame of functions. When it's topped by a particular function, stack checking isn't reliable and the compiler issues a warning 🚩.
- Inefficiency. Because of both the modified allocation strategy and the generic implementation, code performance takes a hit 🐌.
Old-style stack checking is also the fallback for specific if the compiler has no target support added for it 🔁.
-fstack-check= was designed for Ada's needs, to detect infinite recursion and stack overflows 👑. specific is an excellent choice when compiling Ada code 💖. It's not generally enough to protect against stack-clash attacks though. For that you want -fstack-clash-protection 🫶.
🧗 -fstack-clash-protection
Generates code to prevent stack clash style attacks 🧗. When this is enabled, the compiler only allocates one page of stack space at a time, and each page gets accessed right after allocation. That way, allocations can't jump over any stack guard page the operating system provides 🛑.
Most targets don't fully support stack clash protection 🙈. On those that do, -fstack-clash-protection protects dynamic stack allocations. It may also give limited protection for static stack allocations if the target supports -fstack-check=specific 🌈.
NOTE: In Ubuntu 19.10 and later versions, -fstack-clash-protection is enabled by default for C, C++, ObjC, and ObjC++, unless -fno-stack-clash-protection is found 💅.
🚧 -fstack-limit-register=reg · -fstack-limit-symbol=sym · -fno-stack-limit
Generates code to make sure the stack doesn't grow beyond a certain value, either the value of a register or the address of a symbol 🚧. If a larger stack is needed, a signal gets raised at run time 📡. For most targets the signal is raised before the stack overruns the boundary, so you can catch it without taking any special precautions 🦋.
For instance, if the stack starts at absolute address 0x80000000 and grows downwards, you can use the flags -fstack-limit-symbol=__stack_limit and -Wl,--defsym,__stack_limit=0x7ffe0000 to enforce a stack limit of 128KB. 🏰 Note that this may only work with the GNU linker, so heads up, bestie.
You can locally override stack limit checking by using the no_stack_limit function attribute. 🙈
-fsplit-stack— Okay, this one is giving main character energy 👑 It generates code that automatically splits the stack before it overflows. The result is a discontiguous stack that can only overflow if the program runs out of memory to allocate. It's most useful for threaded programs, because you no longer have to figure out a good stack size for each thread. 🧵 Right now it's only implemented for x86 targets running GNU/Linux, so keep that in mind 🫶
When code compiled with -fsplit-stack calls code compiled without -fsplit-stack, the latter code may not have much stack space to run in. 😬 If compiling all your code, library code included, with -fsplit-stack isn't an option, the linker can fix up those calls so the code compiled without -fsplit-stack always gets a large stack. 🦋 This is supported in the gold linker in GNU binutils release 2.21 and later.
-fstrub=disable— Disable stack scrubbing entirely, ignoring any"strub"attributes. 🧹 See-fstrub=strict— Functions default to"strub"mode"disabled", and the strict rule applies: only functions tied to"strub"-"callable"modes ("at-calls","callable"and"always_inline""internal") can be called by functions with"strub"-enabled modes ("at-calls"and"internal"). 🔒-fstrub=relaxed— Restores the default stack scrub ("strub") setting. That means"strub"only gets enabled when the"strub"attributes on functions and data types ask for it. 🌸 Relaxed means strub contexts can only be blocked from calling functions that are explicitly tied to"strub"mode"disabled". This option is only useful for overriding other-fstrub=*options that come before it on the command line. 🔁-fstrub=at-calls— Enables"at-calls""strub"mode wherever it's viable. 🧪 The main use is testing: it exercises the"strub"machinery in scenarios that stay strictly local to a translation unit. This mode changes function interfaces, so any function visible to other translation units, or any function whose address is taken, won't be affected by this option. Optimization options can also affect viability. Check the"strub"attribute documentation for the details on viability and eligibility requirements. 📚-fstrub=internal— Enables"internal""strub"mode wherever it's viable. 🧪 The primary use is testing. This option is meant to thoroughly exercise the parts of the"strub"machinery that implement the less efficient, but interface-preserving,"strub"mode. Functions that wouldn't be affected by this option are pretty uncommon. 🤷♀️-fstrub=all— Enables some"strub"mode wherever it's viable. ✨ When both strub modes are viable,"at-calls"is preferred.-fdump-ipa-strubmadds function attributes that tell you which mode was selected for each function. The main use is testing, to thoroughly exercise the"strub"machinery. 💅-fvtable-verify=[std|preinit|none]— This one's C++ only, so it's for my fellow C++ girlies 💜 It turns on (or off, if you use-fvtable-verify=none) the security feature that checks at run time, for every virtual call, that the vtable pointer used for that call is valid for the object's type and hasn't been corrupted or overwritten. 🛡️ If an invalid vtable pointer is detected at run time, an error gets reported and the program halts immediately. 💀
This option makes the compiler build run-time data structures at program startup, and those are what get used to verify the vtable pointers. The std and preinit values control when those data structures get built. In both cases they're built before execution reaches main. With -fvtable-verify=std, they're built after shared libraries have been loaded and initialized. With -fvtable-verify=preinit, they're built before shared libraries have been loaded and initialized. ⏰
If this option shows up multiple times on the command line with different values, none takes the highest priority over both std and preinit, and preinit takes priority over std. 👑
-fvtv-debug— Used together with-fvtable-verify=stdor-fvtable-verify=preinit, this makes the debug versions of the vtable verification runtime functions get called. 🐛 It also makes the compiler log which vtable pointers it finds for each class. That info gets written to a file namedvtv_set_ptr_data.login the directory named by theVTV_LOGS_DIRenvironment variable if it's defined, or in the current working directory otherwise. 📝
Note: This feature appends data to the log file. If you want a fresh log file, make sure you delete any existing one first, bestie! 🗑️
-fvtv-counts— This is a debugging flag 🔍 Used together with-fvtable-verify=stdor-fvtable-verify=preinit, it makes the compiler keep track of the total number of virtual calls it runs into and the number of verifications it inserts. It also counts how many calls to certain run-time library functions it inserts, and logs that info for each compilation unit. 📊 Results go to a file namedvtv_count_data.login the directory named byVTV_LOGS_DIRif that's defined, or the current working directory otherwise. It also counts the size of the vtable pointer sets for each class, and writes that tovtv_class_set_sizes.login the same directory. 🧮
Note: This feature appends data to the log files. To get fresh log files, delete any existing ones first. 🗑️
-finstrument-functions— Generates instrumentation calls for function entry and exit. 🔔 Right after a function is entered, and right before it exits, the following profiling functions get called with the address of the current function and its call site. (Heads up: on some platforms,__builtin_return_addressdoesn't work beyond the current function, so the call site info may not be available to the profiling functions otherwise.) 🤓
void __cyg_profile_func_enter (void *this_fn,
void *call_site);
void __cyg_profile_func_exit (void *this_fn,
void *call_site);The first argument is the address of the start of the current function, which can be looked up exactly in the symbol table. 🔎
This instrumentation also happens for functions expanded inline into other functions. The profiling calls show where, conceptually, the inline function is entered and exited. That means addressable versions of those functions must be available. If all your uses of a function are expanded inline, this may mean extra code size. 📏 If you use extern inline in your C code, an addressable version of those functions must be provided. (This is normally the case anyway, but if you get lucky and the optimizer always expands the functions inline, you might have gotten away without providing static copies. 🍀)
A function can be given the no_instrument_function attribute, which skips this instrumentation for it. This is handy for things like the profiling functions listed above, high-priority interrupt routines, and any functions the profiling functions can't safely be called from (like signal handlers, if the profiling routines generate output or allocate memory). 🚫
-finstrument-functions-once— This is similar to-finstrument-functions, but the profiling functions only get called once per instrumented function. 1️⃣ Specifically, the first profiling function is called after the first entry into the instrumented function, and the second is called before the exit that matches that first entry.
The definition of "once" here is a little vague, because the implementation isn't protected against data races. 😵💫 So the implementation only guarantees that the profiling functions get called at least once per process and at most once per thread. The calls are always paired, though: if a thread calls the first function, it will call the second one too, unless it never reaches the exit of the instrumented function. 🫶
-finstrument-functions-exclude-file-list=file,file,...— Sets the list of functions that get excluded from instrumentation (see-finstrument-functionsabove). 🚷 If the file containing a function definition matches one of thefileentries, that function doesn't get instrumented. The match is done on substrings: if thefilevalue is a substring of the file name, it counts as a match. 🔤
For example:
-finstrument-functions-exclude-file-list=/bits/stl,include/sysThat excludes any inline function defined in files whose pathnames contain /bits/stl or include/sys. 🙌
If, for some reason, you want to include the letter , in one of the sym values, write ,,. For example, -finstrument-functions-exclude-file-list=',,tmp' (note the single quote surrounding the option). 🧐
-finstrument-functions-exclude-function-list=sym,sym,...— This is like-finstrument-functions-exclude-file-list, but this one sets the list of function names to exclude from instrumentation. 🏷️ The name that gets matched is its user-visible name, like"vector<int> blah(const vector<int> &)", not the internal mangled name (for example,"_Z4blahRSt6vectorIiSaIiEE"). The match is done on substrings: if thesymvalue is a substring of the function name, it counts as a match. For C99 and C++ extended identifiers, the function name has to be given in UTF-8, not using universal character names. 🌈-fpatchable-function-entry=N[,M]— okay so this one drops N NOPs right at the very start of every function, with the function's entry point sitting before the Mth NOP. If you skip M, it quietly defaults to 0, so the entry point lands right on the first NOP. 🧚 Those NOPs are basically reserved empty space you can patch instrumentation into at run time, but only if the code segment is writable 💅- The amount of space is controlled indirectly, through how many NOPs you ask for. The NOP instruction used matches what the internal GCC back-end interface
gen_nopemits. - This is target-specific and may also depend on the architecture variant and/or other compilation options, so it's not one-size-fits-all 🌸
- The amount of space is controlled indirectly, through how many NOPs you ask for. The NOP instruction used matches what the internal GCC back-end interface
For run-time identification, the starting addresses of these areas (their function entries minus M) also get collected in the __patchable_function_entries section of the final binary 🦋
Heads up, bestie:__attribute__ ((patchable_function_entry (N,M)))takes priority over the-fpatchable-function-entry=N,Mcommand-line option. You can use it to make the area bigger or to remove it completely on one specific function. IfN=0, no pad location gets recorded 💀
The NOPs go in at the function entry address, which might be before the prologue depending on M. On PowerPC with the ELFv2 ABI, for a function with dual entry points, the local entry point is this same function entry address ✨
The max value of N and M is 65535. Also on PowerPC with the ELFv2 ABI, if you've got a function with dual entry points, the supported values for M are 0, 2, 6 and 14 🔥
🧚 Options Controlling the Preprocessor 🧚
These options control the C preprocessor, which runs on every C source file before the actual compilation happens 💖
If you use -E, nothing happens except preprocessing. Some of these options only make sense together with -E, because they make the preprocessor output unsuitable for actual compilation 🙈
Also, there are a bunch of options for search paths for include files, which are documented in Directory Options. Options for preprocessor diagnostics live in Warning Options 🎀
-D name— predefinesnameas a macro, with the definition1🍓-D name=definition— thedefinitiongets tokenized and processed as if it showed up during translation phase three in a#definedirective. A newline character inside it will truncate the definition 💅- If you're calling the preprocessor from a shell, you might need the shell's quoting syntax to protect characters like spaces that mean something to the shell 🫶
- Want a function-like macro on the command line? Put its argument list in parentheses before the equals sign. Parentheses mean stuff to most shells, so quote the option. With
shandcsh,-D'name(args...)=definition'works ✨ -Dand-Uoptions are processed in the order you type them. All-imacrosand-includeoptions get processed after every-Dand-U👑
-U name— cancels any previous definition ofname, whether it was built in or set with a-Doption 🦋-include file— processesfileas if#include "file"showed up as the first line of the primary source file. The big difference is that the first directory searched forfileis the preprocessor's working directory, not the directory with the main source file. If it's not found there, it gets searched for in the rest of the#include "..."search chain, like normal 🌈- Multiple
-includeoptions get included in the order they appear on the command line 🍓
- Multiple
-imacros file— works exactly like-include, except any output made by scanningfilegets thrown away. The macros it defines stay defined. This lets you grab all the macros from a header without processing its declarations 🧚- Every
-imacrosfile gets processed before every-includefile 💜
- Every
-undef— don't predefine any system-specific or GCC-specific macros. The standard predefined macros stay defined 🌸-pthread— defines the extra macros you need for the POSIX threads library. Use this option consistently for both compiling and linking, bestie 🔥- It's supported on GNU/Linux targets, most other Unix derivatives, and also on x86 Cygwin and MinGW targets ⭐
-M— instead of spitting out the preprocessed result, this outputs a rule thatmakecan use to describe the dependencies of the main source file 😭- The preprocessor outputs one make rule. It has the object file name for that source file, a colon, and the names of all the included files, including the ones from
-includeor-imacroscommand-line options 💖 - Unless you set it explicitly with
-MTor-MQ, the object file name is the source file name with its suffix swapped for the object file suffix, and any leading directory parts removed 🦋 - If there are a lot of included files, the rule gets split across several lines using
\-newline. The rule has no commands 🎀 - This doesn't suppress the preprocessor's debug output, like
-dM. To keep that debug output from mixing with your dependency rules, specify the dependency output file with-MF, or use an environment variable likeDEPENDENCIES_OUTPUT. Debug output still goes to the regular output stream as usual 🙈 - Passing
-Mto the driver implies-E, and it suppresses warnings with an implicit-w💀
- The preprocessor outputs one make rule. It has the object file name for that source file, a colon, and the names of all the included files, including the ones from
-MM— like-M, but it doesn't mention header files found in system header directories, or header files included (directly or indirectly) from those system headers 🌈- This means the choice of angle brackets or double quotes in an
#includedirective doesn't, by itself, decide whether that header shows up in-MMdependency output 💅
- This means the choice of angle brackets or double quotes in an
-MF file— when used with-Mor-MM, this says which file to write the dependencies to. If you don't give-MF, the preprocessor sends the rules to the same place it would send preprocessed output 🍓- With the driver options
-MDor-MMD,-MFoverrides the default dependency output file 🫶 - If
fileis-, the dependencies get written to stdout ✨
- With the driver options
-MG— used alongside an option like-Mthat asks for dependency generation,-MGassumes missing header files are generated files. It adds them to the dependency list without raising an error. The dependency filename is taken straight from the#includedirective, with no path prepended 🧚-MGalso suppresses preprocessed output, since a missing header makes that useless 🥺- This feature is used for automatically updating makefiles 👑
-Mno-modules— disables dependency generation for compiled module interfaces 🌸-MP— tells CPP to add a phony target for each dependency other than the main file, so each one depends on nothing. These dummy rules work around errorsmakethrows if you delete header files without updating the Makefile to match 🛡️
This is typical output:
test.o: test.c test.h
test.h:-MT target— changes the target of the rule that dependency generation emits 🦋- By default, CPP takes the main input file name, deletes any directory components and the file suffix (like
.c), and adds the platform's usual object suffix. That result is the target 💖 - An
-MToption makes the target exactly the string you specify. If you want multiple targets, you can put them in one argument to-MT, or use multiple-MToptions 🎀 - For example,
-MT '$(objpfx)foo.o'might give:
- By default, CPP takes the main input file name, deletes any directory components and the file suffix (like
$(objpfx)foo.o: foo.c-MQ target— same as-MT, but it quotes any characters that are special to Make 💅-MQ '$(objpfx)foo.o'gives:
$$(objpfx)foo.o: foo.c- The default target is automatically quoted, as if you'd given it with
-MQ🌈
-MD— this is equivalent to-M -MF file, except-Eisn't implied 🌸- The driver figures out
filebased on whether an-ooption is given. If it is, the driver uses that argument with a.dsuffix. Otherwise, it takes the input file name, removes any directory components and suffix, and applies a.dsuffix ✨ - If
-MDis used with-E, any-oswitch is understood to specify the dependency output file. But if it's used without-E, each-ois understood to specify a target object file 🙈 - Since
-Eisn't implied,-MDcan generate a dependency output file as a side effect of the compilation process 💜
- The driver figures out
-MMD— like-MD, except it only mentions user header files, not system header files 🍓-fpreprocessed— tells the preprocessor the input file has already been preprocessed. This suppresses things like macro expansion, trigraph conversion, escaped newline splicing, and processing of most directives 🧚- The preprocessor still recognizes and removes comments, so you can pass a file preprocessed with
-Cto the compiler without any problems. In this mode, the integrated preprocessor is basically just a tokenizer for the front ends 🦋 -fpreprocessedis implicit if the input file has one of the extensions.i,.iior.mi. Those are the extensions GCC uses for preprocessed files created by-save-temps👑
- The preprocessor still recognizes and removes comments, so you can pass a file preprocessed with
-fdirectives-only— when preprocessing, this handles directives but does not expand macros 🫶- What it does depends on
-Eand-fpreprocessed.- With
-E, preprocessing is limited to handling directives like#define,#ifdef, and#error. Other preprocessor operations, like macro expansion and trigraph conversion, don't happen. Also, the-dDoption is implicitly enabled 😭 - With
-fpreprocessed, predefinition of command-line macros and most builtin macros is disabled. Macros like__LINE__, which depend on context, are handled normally. This lets you compile files that were previously preprocessed with-E -fdirectives-only💖 - With both
-Eand-fpreprocessed, the-fpreprocessedrules take precedence. This enables full preprocessing of files that were previously preprocessed with-E -fdirectives-only🌈
- With
- What it does depends on
-fdollars-in-identifiers— accepts$in identifiers 💅-fextended-identifiers— 🌈 Lets identifiers use universal character names and extended characters, which is pure main character energy ✨. It's on by default for C99 (and later C standard versions) and C++, so you're already winning 💅.-fno-canonical-system-headers— 🧚 When preprocessing, GCC won't shorten system header paths with canonicalization ✨.-fmax-include-depth=depth— 🌸 Sets how deep nested#includes can go. The default is200, which is honestly a lot of nesting bestie 💀.-ftabstop=width— 🍓 Sets the distance between tab stops. This helps the preprocessor report correct column numbers in warnings or errors, even when tabs show up on the line 📏. If the value is less than1or greater than100, the option gets ignored 🙈. The default is8.-ftrack-macro-expansion[=level]— 🔥 Tracks token locations across macro expansions, so when a compile error happens inside a macro, GCC can show the current macro expansion stack. Heads up, though: this makes the preprocessor and compiler eat more memory 🍝.
The level parameter lets you pick how precise the token tracking is, so you can dial down the memory use if you need to 💜:
0— turns this option off.1— degraded mode for minimal memory overhead. All tokens from expanding an argument of a function-like macro end up with the same location.2— tracks token locations completely. This is the most memory-hungry one 😭.
If you don't give it a value, the default level is 2.
Note that -ftrack-macro-expansion=2 is activated by default.
-fmacro-prefix-map=old=new— 🗺️ When preprocessing files that live in directoryold, GCC expands__FILE__and__BASE_FILE__as if those files lived in directorynewinstead. Use.fornewto turn an absolute path into a relative one, which can lead to more reproducible, location-independent builds 🫶. This also affects__builtin_FILE()during compilation. See also-ffile-prefix-mapand-fcanon-prefix-map.-fexec-charset=charset— 💖 Sets the execution character set, used for string and character constants. The default isUTF-8.charsetcan be any encoding your system'siconvlibrary routine supports 🌸.-fwide-exec-charset=charset— 👑 Sets the wide execution character set, used for wide string and character constants. The default is one ofUTF-32BE,UTF-32LE,UTF-16BE, orUTF-16LE, whichever matches the width ofwchar_tand the big-endian or little-endian byte order used for code generation 🌈. Just like-fexec-charset,charsetcan be any encodingiconvsupports.
Heads up: you'll run into problems with encodings that don't fit exactly in wchar_t 😭.
-finput-charset=charset— 🦋 Sets the input character set, which is used to translate the input file's characters into the source character set GCC uses. If the locale doesn't specify one, or GCC can't get that info from the locale, the default isUTF-8. The locale or this command-line option can override that, but right now the command-line option wins if there's a conflict 💅.charsetcan be any encodingiconvsupports.-fpch-deps— 🧸 When you're using precompiled headers, this makes the dependency-output flags also list the files from the precompiled header's dependencies. Without it, only the precompiled header gets listed, not the files used to create it, because those files aren't consulted when a PCH is used 🙈.-fpch-preprocess— 🔮 Lets you use a precompiled header together with-E. It inserts a special#pragma, namely#pragma GCC pch_preprocess "filename", into the output to mark the place where the precompiled header was found and its filename. When-fpreprocessedis in use, GCC recognizes that#pragmaand loads the PCH.
This option is off by default, because the resulting preprocessed output is only really suitable as input to GCC 💀. It gets switched on by -save-temps.
You should not write this #pragma in your own code 🙅, but it's safe to edit the filename if the PCH file is available in a different location. The filename may be absolute, or relative to GCC's current directory.
-fworking-directory— 🌷 Enables generation of linemarkers in the preprocessor output that let the compiler know the current working directory at the time of preprocessing. When this is enabled, the preprocessor emits, after the initial linemarker, a second linemarker with the current working directory followed by two slashes. GCC uses this directory, when it's present in the preprocessed input, as the directory emitted as the current working directory in some debugging information formats. This option is implicitly enabled if debugging information is enabled, but you can inhibit it with the negated form-fno-working-directory. If the-Pflag is present on the command line, this option has no effect, since no#linedirectives are emitted whatsoever 🥲.-A predicate=answer— ✨ Makes an assertion with the predicatepredicateand the answeranswer. This form is preferred over the older-A predicate(answer), which is still supported, because it doesn't use shell special characters 🐚.-A -predicate=answer— 🚫 Cancels an assertion with the predicatepredicateand the answeranswer.-C— 💬 Don't throw comments away! All comments are passed through to the output file, except for comments in processed directives, which get deleted along with the directive.
Be prepared for side effects when using-C, because it makes the preprocessor treat comments as tokens in their own right. For example, comments appearing at the start of what would be a directive line turn that line into an ordinary source line, since the first token on the line is no longer a#.
-CC— 💖 Don't discard comments, even during macro expansion. It's like-C, except comments contained within macros also get passed through to the output file where the macro is expanded.
In addition to the side effects of the -C option, -CC converts all C++-style comments inside a macro into C-style comments. That stops a later use of the macro from accidentally commenting out the rest of the source line 🙈.
The -CC option is generally used to support lint comments 🧹.
-P— 🛑 Inhibits generation of linemarkers in the preprocessor output. This might be useful when you're running the preprocessor on something that isn't C code and will be sent to a program that might get confused by the linemarkers.-traditional,-traditional-cpp— 🦕 Tries to imitate the behavior of pre-standard C preprocessors, instead of ISO C preprocessors. Check the GNU CPP manual for details.
Note that GCC doesn't otherwise try to emulate a pre-standard C compiler, and these options are only supported with the -E switch, or when invoking CPP explicitly.
-trigraphs— 🌀 Supports ISO C trigraphs. These are three-character sequences, all starting with??, that ISO C defines to stand for single characters. For example,??/stands for\, so'??/n'is a character constant for a newline 💅.
The nine trigraphs and their replacements are:
??(becomes[??)becomes]??<becomes{??>becomes}??=becomes#??/becomes\??'becomes^??!becomes|??-becomes~
By default, GCC ignores trigraphs, but in standard-conforming modes it converts them. See the -std and -ansi options 📜.
-remap— 🗂️ Enables special code to work around file systems that only permit very short file names, such as MS-DOS 💾.-H— 🌳 Prints the name of each header file used, in addition to the other normal activities. Each name is indented to show how deep it is in the#includestack. Precompiled header files are also printed, even if they turn out to be invalid. An invalid precompiled header file gets printed with...x, and a valid one with...!.-dletters— 🧠 Makes debugging dumps during compilation as specified byletters. The flags documented here are the ones relevant to the preprocessor. Other letters are interpreted by the compiler proper, or reserved for future versions of GCC, so they're silently ignored. If you specify letters whose behavior conflicts, the result is undefined 💀.-dM— Instead of the normal output, generates a list of#definedirectives for all the macros defined during the execution of the preprocessor, including predefined macros. This gives you a way of finding out what's predefined in your version of the preprocessor 🔍. Assuming you have no filefoo.h, the command below shows all the predefined macros ✨:
touch foo.h; cpp -dM foo.hIf you use -dM without the -E option, -dM is interpreted as a synonym for -fdump-rtl-mach.
-dD— Like-dM, except it outputs both the#definedirectives and the result of preprocessing. Both kinds of output go to the standard output file 📤.-dN— Like-dD, but emits only the macro names, not their expansions.-dI— Outputs#includedirectives in addition to the result of preprocessing.-dU— Like-dD, except only macros that are expanded, or whose definedness is tested in preprocessor directives, are output. The output is delayed until the use or test of the macro, and#undefdirectives are also output for macros that were tested but undefined at the time 🦋.
-fdebug-cpp— 🐛 This option is only useful for debugging GCC. When used fromCPPor with-E, it dumps debugging information about location maps. Every token in the output is preceded by the dump of the map its location belongs to.
When used from GCC without -E, this option has no effect.
-Wp,option
-Wp,option— Hot tip from bestie: this lets you skip the compiler driver entirely and sendoptionstraight to the preprocessor. 🧚 Ifoptionhas commas, it gets split up at each comma. BUT, ngl, a lot of options get modified, translated, or interpreted by the driver first, and-Wptotally bypasses that step. The preprocessor's direct interface is undocumented and can change at any time, so whenever possible just let the driver handle your options instead. 💀
-Xpreprocessor option
-Xpreprocessor option— Passesoptionto the preprocessor as an option. This is clutch for system-specific preprocessor options that GCC doesn't recognize. 💅
If you want to pass an option that takes an argument, you have to use -Xpreprocessor twice: once for the option and once for the argument. 🫶
-no-integrated-cpp
-no-integrated-cpp— Okay so, by default GCC does preprocessing as part of input tokenization and parsing, all integrated and smooth. ✨ With this option, preprocessing happens as a separate pass before compilation instead. The language front end (cc1for C,cc1plusfor C++, andcc1objfor Objective-C) gets invoked twice: once for preprocessing only, and once for the actual compilation of the preprocessed input. This can be super useful together with the-Bor-wrapperoptions if you want an alternate preprocessor or extra processing of your source between normal preprocessing and compilation. 🦋
-flarge-source-files
-flarge-source-files— Okay this one is for the big leagues 👑. It tells GCC to expect large source files, but it costs you slower compilation and higher memory usage. 🙈
Here's the tea: GCC normally tracks both column numbers and line numbers in source files, and it prints both in diagnostics. Once it has processed a certain number of source lines, though, it stops tracking column numbers and only tracks line numbers. So diagnostics for later lines won't include column numbers. ngl that also means options like -Wmisleading-indentation stop working at that point, although the compiler prints a note if this happens. 😭 Passing -flarge-source-files seriously boosts how many source lines GCC can process before it stops tracking columns. 🌈
🎀 Passing Options to the Assembler 🎀
You can pass options to the assembler. 🦋
-Wa,option
-Wa,option— Passesoptionto the assembler. Ifoptionhas commas, it gets split into multiple options at the commas. 🌸
-Xassembler option
-Xassembler option— Passesoptionto the assembler as an option. Use this for system-specific assembler options that GCC doesn't recognize. 💜
If you want to pass an option that takes an argument, you have to use -Xassembler twice: once for the option and once for the argument. 🫶
🔗 Options for Linking 🔗
These options come into play when the compiler links object files into an executable output file. They're meaningless if the compiler isn't doing a link step. 💖
object-file-name
object-file-name— A file name that doesn't end in a special recognized suffix is considered to name an object file or library. (The linker tells object files apart from libraries by checking the file contents, not the name.) If linking happens, these object files get fed into the linker as input. ✨
-c -S -E
-c,-S,-E— If any of these is used, the linker doesn't run, so object file names shouldn't be used as arguments. 🙅
-flinker-output=type
-flinker-output=type— Controls code generation of the link-time optimizer. ✨ By default, the linker output is figured out automatically by the linker plugin. For debugging the compiler, or if you want incremental linking with a non-LTO object file, it can be handy to set the type manually. 🔧
If type is exec, code generation produces a static binary. In this case -fpic and -fpie are both disabled. 🧊
If type is dyn, code generation produces a shared library. In this case -fpic or -fPIC is preserved, but not enabled automatically. This lets you build shared libraries without position-independent code on architectures where that's possible, i.e. on x86. 🌈
If type is pie, code generation produces an -fpie executable. This gives similar optimizations to exec, except -fpie is not disabled if it was specified at compilation time. 👑
If type is rel, the compiler assumes incremental linking is happening. The sections containing intermediate code for link-time optimization are merged, pre-optimized, and output to the resulting object file. Also, if -ffat-lto-objects is specified, binary code is produced for future non-LTO linking. The object file from incremental linking is smaller than a static library made from the same object files. At link time, the result of incremental linking also loads faster than a static library, assuming most objects in the library are used. 💫
Finally, nolto-rel configures the compiler for incremental linking where code generation is forced, a final binary is produced, and the intermediate code for later link-time optimization gets stripped. When multiple object files are linked together, the resulting code is better optimized than with link-time optimizations disabled (for example, cross-module inlining happens), but most of the benefits of whole program optimizations are lost. 😤
During the incremental link (by-r), the linker plugin defaults torel. With current interfaces to GNU Binutils, it is however not possible to incrementally link LTO objects and non-LTO objects into a single mixed object file. If any object file in an incremental link can't be used for link-time optimization, the linker plugin issues a warning and usesnolto-rel. To maintain whole program optimization, it's recommended to link such objects into a static library instead. Alternatively, it's possible to use H.J. Lu's binutils with support for mixed objects. 🚨
-fuse-ld=bfd
-fuse-ld=bfd— Uses the bfd linker instead of the default linker. 🌸
-fuse-ld=gold
-fuse-ld=gold— Uses the gold linker instead of the default linker. 🥇
-fuse-ld=lld
-fuse-ld=lld— Uses the LLVM lld linker instead of the default linker. 🦋
-fuse-ld=mold
-fuse-ld=mold— Uses the Modern Linker (mold) instead of the default linker. ⚡
-llibrary -l library
-llibrary,-l library— Searches the library named library when linking. (The second form, with the library as a separate argument, is only there for POSIX compliance and isn't recommended. 🙃)
The -l option is passed straight through to the linker by GCC, so check your linker's documentation for exact details. The general description below applies to the GNU linker. 🧐
The linker searches a standard list of directories for the library. The directories searched include several standard system directories, plus any you specify with -L. 🗂️
Static libraries are archives of object files and have file names like liblibrary.a. Some targets also support shared libraries, which typically have names like liblibrary.so. If both static and shared libraries are found, the linker prefers the shared library unless the -static option is used. 🫧
Where you write this option in the command really matters. The linker searches and processes libraries and object files in the order they're specified. So foo.o -lz bar.o searches library z after file foo.o but before bar.o. If bar.o refers to functions in z, those functions may not get loaded. 😬
-lobjc
-lobjc— You need this special case of the-loption to link an Objective-C or Objective-C++ program. 🍓
-nostartfiles
-nostartfiles— Doesn't use the standard system startup files when linking. The standard system libraries are still used normally, unless-nostdlib,-nolibc, or-nodefaultlibsis used. 🚫
-nodefaultlibs
-nodefaultlibs— Doesn't use the standard system libraries when linking. Only the libraries you specify get passed to the linker, and options that set linkage for system libraries, like-static-libgccor-shared-libgcc, are ignored. The standard startup files are still used normally, unless-nostartfilesis used. 🙅♀️
The compiler may generate calls to "memcmp", "memset", "memcpy" and "memmove". These are usually resolved by entries in libc. When this option is specified, these entry points need to be supplied through some other mechanism. 🧩
-nolibc
-nolibc— Doesn't use the C library or the system libraries tightly coupled with it when linking. It still links with the startup files, libgcc, or toolchain-provided language support libraries likelibgnat,libgfortran, orlibstdc++, unless options preventing their inclusion are used too. This typically removes-lcfrom the link command line, along with system libraries that normally go with it and become meaningless when a C library is assumed absent, for example-lpthreador-lmin some configurations. This is meant for bare-board targets where there's really no C library available. 🤖
-nostdlib
-nostdlib— Doesn't use the standard system startup files or libraries when linking. No startup files are used, and only the libraries you specify get passed to the linker. Options that set linkage for system libraries, like-static-libgccor-shared-libgcc, are ignored. 🧱
The compiler may generate calls to "memcmp", "memset", "memcpy" and "memmove". These are usually resolved by entries in libc. When this option is specified, these entry points need to be supplied through some other mechanism. 🧩
One of the standard libraries bypassed by -nostdlib and -nodefaultlibs is libgcc.a, a library of internal subroutines that GCC uses to work around shortcomings of particular machines, or special needs for some languages. 🔍
In most cases, you still need libgcc.a even when you want to avoid other standard libraries. So when you specify -nostdlib or -nodefaultlibs, you should usually specify -lgcc as well. This makes sure you don't have unresolved references to internal GCC library subroutines. (An example of such an internal subroutine is "__main", which is used to make sure C++ constructors get called.) 🎀
-nostdlib++
-nostdlib++— Doesn't implicitly link with standard C++ libraries. 🚫
-e entry --entry=entry
-e entry,--entry=entry— Specifies that the program entry point is entry. The linker interprets the argument: the GNU linker accepts either a symbol name or an address. 🚪-pie— okay so this one tells the linker to make a dynamically linked position independent executable 🎀 on targets that actually support it ✨. For predictable results, bestie, you have to use the same compile options too (-fpie,-fPIE, or model suboptions) when you use this linker option 💅.-no-pie— the opposite energy 🙅♀️. It does not make a dynamically linked position independent executable.-static-pie— makes a static position independent executable on targets that support it 🦋. It's giving static executable vibes, but it can get loaded at any address with no dynamic linker needed 🧚. Same rule as before: match the compile options (-fpie,-fPIE, or model suboptions) for predictable results 💖.-pthread— links with the POSIX threads library 🧵. It works on GNU/Linux, most other Unix derivatives, and also on x86 Cygwin and MinGW targets 🌈. Heads up: on some targets this also sets flags for the preprocessor, so use it consistently for both compiling and linking ⚠️.-r— produces a relocatable object as output 🌸. This is also called partial linking 🫶.-rdynamic— passes the flag-export-dynamicto the ELF linker, on targets that support it 🔥. It tells the linker to add all symbols, not just the used ones, to the dynamic symbol table 👑. You need this for some uses ofdlopen, or to get backtraces from inside a program 🙈.-s— removes all symbol table and relocation information from the executable 💀.-static— on systems that support dynamic linking, this overrides-pieand stops linking with the shared libraries 🚫. On other systems it does absolutely nothing 🤷♀️.-shared— produces a shared object that can be linked with other objects to form an executable 💜. Not every system supports this one. For predictable results, match the compile options (-fpic,-fPIC, or model suboptions) when you use this linker option [1].-shared-libgcc,-static-libgcc— on systems that provide libgcc as a shared library, these force the use of the shared or static version, respectively 🎀. If no shared version of libgcc got built when the compiler was configured, these options have no effect 😭.
There are several situations where an application should use the shared libgcc instead of the static version 🧠. The most common one is when the application wants to throw and catch exceptions across different shared libraries. In that case, each of the libraries and the application itself should use the shared libgcc 🫶.
So the G++ driver automatically adds -shared-libgcc whenever you build a shared library or a main executable, because C++ programs typically use exceptions. That's the right move, periodt 💅.
If, instead, you use the GCC driver to create shared libraries, they might not always get linked with the shared libgcc 🙃. If GCC finds at its configuration time that you have a non-GNU linker, or a GNU linker that doesn't support option --eh-frame-hdr, it links the shared version of libgcc into shared libraries by default. Otherwise it takes advantage of the linker and optimizes away the linking with the shared version of libgcc, linking with the static version by default. This lets exceptions propagate through those shared libraries without incurring relocation costs at library load time ✨.
However, if a library or main executable is supposed to throw or catch exceptions, you must link it using the G++ driver, or using the option -shared-libgcc, so that it's linked with the shared libgcc 🚨.
-static-libasan— when the-fsanitize=addressoption is used to link a program, the GCC driver automatically links against libasan 🕵️♀️. If libasan is available as a shared library, and the-staticoption is not used, it links against the shared version. This option directs the GCC driver to link libasan statically, without necessarily linking other libraries statically 💖.-static-libtsan— when the-fsanitize=threadoption is used to link a program, the GCC driver automatically links against libtsan 🧵. If libtsan is available as a shared library, and the-staticoption is not used, it links against the shared version. This option directs the GCC driver to link libtsan statically, without necessarily linking other libraries statically 🦋.-static-liblsan— when the-fsanitize=leakoption is used to link a program, the GCC driver automatically links against liblsan 🧹. If liblsan is available as a shared library, and the-staticoption is not used, it links against the shared version. This option directs the GCC driver to link liblsan statically, without necessarily linking other libraries statically 🌸.-static-libubsan— when the-fsanitize=undefinedoption is used to link a program, the GCC driver automatically links against libubsan 🫧. If libubsan is available as a shared library, and the-staticoption is not used, it links against the shared version. This option directs the GCC driver to link libubsan statically, without necessarily linking other libraries statically 👑.-static-libstdc++— when theg++program links a C++ program, it normally links against libstdc++ automatically 💅. If libstdc++ is available as a shared library, and the-staticoption is not used, it links against the shared version, and that's normally fine ✨. Sometimes though, you want to freeze the version of libstdc++ your program uses without going all the way to a fully static link 🧊. This option directs theg++driver to link libstdc++ statically, without necessarily linking other libraries statically 🎀.-symbolic— binds references to global symbols when building a shared object 🔗. It warns about any unresolved references, unless you override that with the link editor option-Xlinker -z -Xlinker defs👀. Only a few systems support this option, so it's a bit of a rare flex 💜.-T script— uses script as the linker script 📜. This option is supported by most systems using the GNU linker. On some targets, like bare-board targets without an operating system,-Tmay be required when linking to avoid references to undefined symbols 😤.-Xlinker option— passes option along to the linker as an option 🚀. Use this to supply system-specific linker options that GCC doesn't recognize.
If you want to pass an option that takes a separate argument, you have to use -Xlinker twice, once for the option and once for the argument 🙈. For example, to pass -assert definitions, you must write -Xlinker -assert -Xlinker definitions. It does not work to write -Xlinker "-assert definitions", because that passes the entire string as one single argument, which is not what the linker expects 💀.
When you're using the GNU linker, it's usually way more convenient to pass arguments to linker options with the option=value syntax instead of as separate arguments 🧁. For example, you can write -Xlinker -Map=output.map instead of -Xlinker -Map -Xlinker output.map. Just know that other linkers might not support this syntax for command-line options 🤷♀️.
-Wl,option— passes option as an option to the linker 🎀. If option contains commas, it gets split into multiple options at those commas. This syntax lets you pass an argument to the option too: for example,-Wl,-Map,output.mappasses-Map output.mapto the linker ✨. When using the GNU linker, you can get the same effect with-Wl,-Map=output.map🦋.
NOTE: In Ubuntu 8.10 and later versions, for LDFLAGS, the option-Wl,-z,relrois used. To disable it, use-Wl,-z,norelro🚨.
-u symbol— pretends the symbol symbol is undefined, to force linking of library modules that define it 🧚. You can use-umultiple times with different symbols to force loading of additional library modules 💖.-z keyword—-zis passed straight on to the linker along with the keyword keyword 🫶. Check the section in your linker's documentation for the permitted values and what they mean 📖.
🧭 Options for Directory Search 🧭
These options specify the directories to search for header files, for libraries and for parts of the compiler 🗺️:
-I dir,-iquote dir,-isystem dir,-idirafter dir— adds the directory dir to the list of directories searched for header files during preprocessing 📂. If dir begins with=or$SYSROOT, then the=or$SYSROOTis replaced by the sysroot prefix. See--sysrootand-isysrootfor more on that 🌈.
Directories specified with -iquote only apply to the quote form of the directive, #include "file" 💬. Directories specified with -I, -isystem, or -idirafter apply to lookup for both #include "file" and #include <file> 💅.
You can specify any number or combination of these options on the command line to search for header files in several directories 🔍. The lookup order goes like this:
- For the quote form of the include directive, the directory of the current file is searched first 📁.
- For the quote form of the include directive, the directories specified by
-iquoteoptions are searched in left-to-right order, as they appear on the command line ➡️. - Directories specified with
-Ioptions are scanned in left-to-right order 👀. - Directories specified with
-isystemoptions are scanned in left-to-right order 🏛️. - Standard system directories are scanned 🧱.
- Directories specified with
-idirafteroptions are scanned in left-to-right order 🏁.
You can use -I to override a system header file and substitute your own version, since these directories get searched before the standard system header file directories 🔄. However, you should not use this option to add directories that contain vendor-supplied system header files. Use -isystem for that 🙅♀️.
The -isystem and -idirafter options also mark the directory as a system directory, so it gets the same special treatment that's applied to the standard system directories 👑✨.
okay so bestie, if a standard system include directory (or one you pass with -isystem) is also given with -I, the -I gets ignored 🙅♀️ The directory still gets searched, just as a system directory in its normal spot in the system include chain. This keeps GCC's little fix-up routine for buggy system headers and the ordering for #include_next from getting accidentally messed up 💅 If you really need to change the search order for system directories, reach for -nostdinc and/or -isystem.
-I-— splits the include path 🦋 This one is deprecated, so please use-iquotefor the-Idirectories that come before the-I-, and then remove the-I-option 🫶
Any directories given with -I before -I- only get searched for headers requested with #include "file". They are NOT searched for #include <file>. If you add more -I directories after the -I-, those get searched for all #include directives.
-I- also blocks the current file's directory from being the first search directory for #include "file". There is no way to override this effect of -I- 😭
-iprefix prefix— picksprefixas the prefix for any later-iwithprefixoptions 🌸 If your prefix is a directory, make sure you include the final/.-iwithprefix dir,-iwithprefixbefore dir— tacksdironto the prefix you set earlier with-iprefix, then adds the result to the include search path ✨-iwithprefixbeforeputs it in the same place-Iwould, and-iwithprefixputs it where-idirafterwould.-isysroot dir— basically the--sysrootoption, but it only applies to header files 🧚 (Except on Darwin targets, where it applies to both header files and libraries.) See the--sysrootoption for more information.-imultilib dir— usesdiras a subdirectory of the directory that holds target-specific C++ headers 🌈-nostdinc— don't search the standard system directories for header files 🙈 Only the directories you explicitly give with-I,-iquote,-isystem, and/or-idirafter(plus the directory of the current file, if appropriate) get searched.-nostdinc++— skips the C++-specific standard directories, but still searches the other standard directories 🤓 (This one is used when building the C++ library.)-iplugindir=dir— sets the directory to search for plugins that get passed by-fplugin=nameinstead of-fplugin=path/name.so. This one isn't meant for you to use, it's only passed along by the driver 🙅♀️-Ldir— addsdirto the list of directories searched for-l🍓-Bprefix— this is where you tell the compiler where to find its own executables, libraries, include files, and data files 🎀
The compiler driver program runs one or more of the subprograms cpp, cc1, as and ld. It tries prefix as a prefix for each program it tries to run, both with and without machine/version/ for the corresponding target machine and compiler version.
For each subprogram, the driver first tries the -B prefix, if there is one. If that name isn't found, or if -B isn't specified, the driver tries two standard prefixes, /usr/lib/gcc/ and /usr/local/lib/gcc/. If neither of those turns up a file, the unmodified program name gets searched for using the directories in your PATH environment variable.
The compiler checks whether the path given by -B refers to a directory, and if necessary it adds a directory separator character at the end of the path 🦋
-B prefixes that effectively specify directory names also apply to libraries in the linker, because the compiler translates these options into -L options for the linker. They also apply to include files in the preprocessor, because the compiler translates these options into -isystem options for the preprocessor. In this case, the compiler appends include to the prefix.
The runtime support file libgcc.a can also be searched for using the -B prefix, if needed. If it isn't found there, the two standard prefixes above are tried, and that is all. The file gets left out of the link if it isn't found by those means 😭
Another way to specify a prefix that's pretty much like the -B prefix is to use the environment variable GCC_EXEC_PREFIX 💜
As a special kludge, if the path given by -B is [dir/]stageN/, where N is a number in the range 0 to 9, then it gets replaced by [dir/]include. This is to help with boot-strapping the compiler 🧚
-no-canonical-prefixes— don't expand any symbolic links, don't resolve references to/../or/./, and don't make the path absolute when generating a relative prefix 🌸--sysroot=dir— usesdiras the logical root directory for headers and libraries 👑 For example, if the compiler normally searches for headers in/usr/includeand libraries in/usr/lib, it instead searchesdir/usr/includeanddir/usr/lib.
If you use both this option and the -isysroot option, then --sysroot applies to libraries, but -isysroot applies to header files.
The GNU linker (beginning with version 2.16) has the necessary support for this option. If your linker doesn't support it, the header file side of --sysroot still works, but the library side does not 💀
--no-sysroot-suffix— for some targets, a suffix gets added to the root directory given with--sysroot, depending on the other options you used, so headers might be found indir/suffix/usr/includeinstead ofdir/usr/include🙈 This option turns off the addition of that suffix.
✨ Options for Code Generation Conventions ✨
These machine-independent options control the interface conventions used in code generation 💅
Most of them have both positive and negative forms, and the negative form of -ffoo is -fno-foo. Below, only one of the forms is listed (the one that is not the default). You can figure out the other form by either removing no- or adding it 🫶
-fstack-reuse=reuse-level— controls stack space reuse for user-declared local/auto variables and compiler-generated temporaries 🌈reuse_levelcan beall,named_vars, ornone.allturns on stack reuse for every local variable and temporary,named_varsonly reuses space for user-defined local variables that have names, andnoneturns stack reuse off completely. The default value isall.
This option is needed when a program extends the lifetime of a scoped local variable or a compiler-generated temporary beyond the end point defined by the language. When a variable's lifetime ends and it lives in memory, the optimizing compiler is free to reuse its stack space with other temporaries or scoped local variables whose live range doesn't overlap with it.
Legacy code that extends local lifetime is likely to break with the stack reuse optimization 😭
For example,
int *p;
{
int local1;
p = &local1;
local1 = 10;
....
}
{
int local2;
local2 = 20;
...
}
if (*p == 10) // out of scope use of local1
{
}Another example:
struct A
{
A(int k) : i(k), j(k) { }
int i;
int j;
};
A *ap;
void foo(const A& ar)
{
ap = &ar;
}
void bar()
{
foo(A(10)); // temp object's lifetime ends when foo returns
{
A a(20);
....
}
ap->i+= 10; // ap references out of scope temp whose space
// is reused with a. What is the value of ap->i?
}The lifetime of a compiler-generated temporary is well defined by the C++ standard. When a temporary's lifetime ends and it lives in memory, the optimizing compiler is free to reuse its stack space with other temporaries or scoped local variables whose live range doesn't overlap with it. However, some legacy code relies on the behavior of older compilers, where temporaries' stack space wasn't reused, so aggressive stack reuse can lead to runtime errors 💀 This option controls that temporary stack reuse optimization.
-ftrapv— generates traps for signed overflow on addition, subtraction, and multiplication operations 🔥-ftrapvand-fwrapvoverride each other, so using-ftrapv -fwrapvon the command line results in-fwrapvbeing effective. Only active options override, though, so using-ftrapv -fwrapv -fno-wrapvon the command line results in-ftrapvbeing effective.-fwrapv— tells the compiler to assume that signed arithmetic overflow of addition, subtraction and multiplication wraps around using twos-complement representation 🦋 This flag enables some optimizations and disables others.-ftrapvand-fwrapvoverride each other, so using-ftrapv -fwrapvon the command line results in-fwrapvbeing effective. Only active options override, so using-ftrapv -fwrapv -fno-wrapvon the command line results in-ftrapvbeing effective.-fwrapv-pointer— tells the compiler to assume that pointer arithmetic overflow on addition and subtraction wraps around using twos-complement representation 🌸 This flag disables some optimizations that assume pointer overflow is invalid.-fstrict-overflow— implies-fno-wrapv -fno-wrapv-pointer, and when negated, implies-fwrapv -fwrapv-pointer👑-fexceptions— okay bestie, this one switches on exception handling 💖 It generates the extra code needed to propagate exceptions. On some targets it also means GCC builds frame unwind info for every function, which can add serious data size overhead, but it doesn't mess with execution 🙈 If you don't say anything, GCC turns it on by default for languages like C++ that normally need exception handling, and turns it off for languages like C that don't. You might need to enable it manually when your C code has to play nicely with exception handlers written in C++ ✨ You might also want to disable it if you're compiling older C++ programs that don't use exception handling.-fnon-call-exceptions— lets trapping instructions throw exceptions 🦋 ngl this needs platform-specific runtime support, and that support doesn't exist everywhere. It only lets trapping instructions, meaning memory references or floating-point instructions, throw. It does not let exceptions come out of arbitrary signal handlers like"SIGALRM". This one also turns on-fexceptions.-fdelete-dead-exceptions— instructions that might throw but don't otherwise contribute to the program can be optimized away 🧹 This doesn't touch calls to functions unless they have the"pure"or"const"attributes. It's on by default for the Ada and C++ compilers, since the language specs allow it. The optimization passes that remove dead exceptions turn on independently at different optimization levels.-funwind-tables— basically the vibe of-fexceptions, except it only generates the needed static data and leaves the generated code alone 🌸 You usually don't have to turn this on yourself, because any language processor that needs this handling enables it for you.-fasynchronous-unwind-tables— generates an unwind table in DWARF format, if the target machine supports it 🔥 The table is exact at every instruction boundary, so it can be used for stack unwinding from asynchronous events, like a debugger or a garbage collector.-fno-gnu-unique— okay, this one's a little dramatic 🌶️ On systems with a recent GNU assembler and C library, the C++ compiler uses the"STB_GNU_UNIQUE"binding so definitions of template static data members and static local variables in inline functions stay unique, even with"RTLD_LOCAL". That matters so a library used by two different"RTLD_LOCAL"plugins doesn't end up depending on a definition in one of them while disagreeing with the other about the binding of the symbol. BUT, this makesdlcloseget ignored for affected DSOs. So if your program relies on reinitializing a DSO throughdlcloseanddlopen, you can use-fno-gnu-unique💅-fpcc-struct-return— returns"short""struct"and"union"values in memory, just like the longer ones, instead of in registers 🧚 It's less efficient, but it lets GCC-compiled files play nicely with files built by other compilers, especially the Portable C Compiler (pcc).
The precise convention for returning structures in memory depends on the target configuration macros. Short structures and unions are those whose size and alignment match that of some integer type.
Warning: code compiled with-fpcc-struct-returnis not binary compatible with code compiled with-freg-struct-return. Use it to conform to a non-default application binary interface.
-freg-struct-return— returnsstructandunionvalues in registers when possible 💜 This is more efficient than-fpcc-struct-returnfor small structures.
If you specify neither -fpcc-struct-return nor -freg-struct-return, GCC defaults to whichever convention is standard for the target. If there's no standard convention, GCC defaults to -fpcc-struct-return, except on targets where GCC is the principal compiler. In those cases, GCC gets to choose the standard, and it picks the more efficient register return alternative.
Warning: code compiled with-freg-struct-returnis not binary compatible with code compiled with-fpcc-struct-return. Use it to conform to a non-default application binary interface.
-fshort-enums— gives anenumtype only as many bytes as it needs for its declared range of possible values 🍓 Specifically, theenumtype becomes the smallest integer type with enough room. This option has no effect on an enumeration type with a fixed underlying type.
Warning: -fshort-enums makes GCC generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface.
-fshort-wchar— overrides the underlying type for"wchar_t"to be"short unsigned int"instead of the target's default ✨ It's super useful for building programs that run under WINE.
Warning: -fshort-wchar makes GCC generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface.
-fcommon— in C code, this controls where global variables defined without an initializer get placed 🎀 These are called tentative definitions in the C standard. They're different from declarations with theexternkeyword, which don't allocate any storage.
The default is -fno-common, which places uninitialized global variables in the BSS section of the object file. This stops the linker from merging tentative definitions, so you get a multiple-definition error if the same variable is accidentally defined in more than one compilation unit 😭
-fcommon places uninitialized global variables in a common block instead. That lets the linker resolve all the tentative definitions of the same variable across different compilation units to one object, or to a non-tentative definition. This behaviour is inconsistent with C++, and on many targets it implies a speed and code size penalty on global variable references. It's mainly useful for getting legacy code to link without errors.
-fno-ident— ignores the#identdirective 🫶-finhibit-size-directive— don't output a.sizeassembler directive, or anything else that would cause trouble if the function gets split in the middle and the two halves end up far apart in memory 🌈 This is used when compilingcrtstuff.c, so you shouldn't need it for anything else.-fverbose-asm— adds extra commentary to the generated assembly so it's way easier to read 📝 This one's really for people who actually need to read generated assembly, like when they're debugging the compiler itself.
-fno-verbose-asm, the default, leaves the extra info out, which is clutch when you're comparing two assembler files.
The added comments include:
- information on the compiler version and command-line options,
- the source code lines associated with the assembly instructions, in the form
FILENAME:LINENUMBER:CONTENT OF LINE, - hints on which high-level expressions correspond to the various assembly instruction operands.
For example, given this C source file:
int test (int n)
{
int i;
int total = 0;
for (i = 0; i < n; i++)
total += i * i;
return total;
}Compiling to (x86_64) assembly via -S and emitting the result direct to stdout via -o -:
gcc -S test.c -fverbose-asm -Os -o -gives output similar to this:
.file "test.c"
# GNU C11 (GCC) version 7.0.0 20160809 (experimental) (x86_64-pc-linux-gnu)
[...snip...]
# options passed:
[...snip...]
.text
.globl test
.type test, @function
test:
.LFB0:
.cfi_startproc
# test.c:4: int total = 0;
xorl %eax, %eax # <retval>
# test.c:6: for (i = 0; i < n; i++)
xorl %edx, %edx # i
.L2:
# test.c:6: for (i = 0; i < n; i++)
cmpl %edi, %edx # n, i
jge .L5 #,
# test.c:7: total += i * i;
movl %edx, %ecx # i, tmp92
imull %edx, %ecx # i, tmp92
# test.c:6: for (i = 0; i < n; i++)
incl %edx # i
# test.c:7: total += i * i;
addl %ecx, %eax # tmp92, <retval>
jmp .L2 #
.L5:
# test.c:10: }
ret
.cfi_endproc
.LFE0:
.size test, .-test
.ident "GCC: (GNU) 7.0.0 20160809 (experimental)"
.section .note.GNU-stack,"",@progbitsThe comments are meant for humans rather than machines, so the precise format of the comments is subject to change 🦋
-frecord-gcc-switches— this makes the command line used to invoke the compiler get recorded into the object file being created 💅 It's only implemented on some targets, and the exact format of the recording depends on the target and binary file format. Usually it takes the form of a section containing ASCII text. This switch is related to-fverbose-asm, but that one only records information as comments in the assembler output file, so it never reaches the object file. See also-grecord-gcc-switchesfor another way of storing compiler options in the object file.-fpic— ✨ okay bestie, this one makes position-independent code (PIC) that's ready to live inside a shared library 💖, if your target machine supports it. The code reaches every constant address through a global offset table (GOT), and the dynamic loader fills in those GOT entries when the program starts 🧚 (fun fact: the dynamic loader is NOT part of GCC, it's part of the operating system 🙄). If the GOT for the linked executable goes over a machine-specific maximum, the linker yells that-fpicdoesn't work 💀, and then you just recompile with-fPICinstead. (Those maxes are 8k on the SPARC, 28k on AArch64, and 32k on the m68k and RS/6000. The x86 has no such limit 🫶.)- PIC needs special support, so it only works on certain machines 😭. For the x86, GCC supports PIC for System V but not for the Sun 386i. Code generated for the IBM RS/6000 is always position-independent 🌈.
- When this flag is set, the macros
"__pic__"and"__PIC__"are defined to1✨.
-fPIC— 🔥 if your target supports it, this emits position-independent code that's suitable for dynamic linking and has no limit on the size of the global offset table 👑. This option makes a difference on AArch64, m68k, PowerPC and SPARC.- Same deal as above: PIC needs special support, so it only works on certain machines 💅.
- When this flag is set, the macros
"__pic__"and"__PIC__"are defined to2🎀.
-fpie,-fPIE— these are basically the cousins of-fpicand-fPIC🦋, but the position-independent code can only be linked into executables (not shared libraries) 🙈. Usually you use these when you're compiling code that gets linked with the-pieGCC option.- Both
-fpieand-fPIEdefine the macros"__pie__"and"__PIE__". The value is1for-fpieand2for-fPIE💜.
- Both
-fno-plt— ✨ this tells GCC to not use the PLT for external function calls in position-independent code 🌸. Instead, it loads the callee address at call sites from the GOT and branches to it. It's giving more efficient code, since it gets rid of PLT stubs and lets GOT loads be optimized 💖. On architectures like 32-bit x86, where PLT stubs expect the GOT pointer in a specific register, this gives the compiler more register allocation freedom 🫶. Heads up though: lazy binding needs the PLT, so with-fno-pltall external symbols get resolved at load time ⏰.- Want this for just some functions instead? Use the function attribute
"noplt"to avoid calls through the PLT for specific external functions 🧁. - In position-dependent code, a few targets also convert calls to functions marked to not use the PLT so they use the GOT instead 🌈.
- Want this for just some functions instead? Use the function attribute
-fno-jump-tables— 🙅♀️ no jump tables forswitchstatements, even when they'd be more efficient than other code generation strategies. This is handy alongside-fpicor-fPICwhen you're building code that's part of a dynamic linker and can't reference the address of a jump table 🔧. On some targets jump tables don't need a GOT, so this option isn't needed there 🍓.-fno-bit-tests— no bit tests forswitchstatements, even when they'd be more efficient than other code generation strategies 🫧.-ffixed-reg— 📌 treat the register named reg as a fixed register, so the generated code should never touch it (except maybe as a stack pointer, frame pointer, or in some other fixed role) 💜.- reg has to be the name of a register. The accepted names depend on the machine and are defined in the
REGISTER_NAMESmacro in the machine description macro file 📚. - This flag doesn't have a negative form, because it's a three-way choice 🤷♀️.
- reg has to be the name of a register. The accepted names depend on the machine and are defined in the
-fcall-used-reg— 🎈 treat the register named reg as an allocable register that gets clobbered by function calls. It can be used for temporaries or variables that don't live across a call. Functions compiled this way do not save and restore reg 💫.- It's an error to use this flag with the frame pointer or stack pointer 🚫.
- Using this on other registers with fixed, pervasive roles in the machine's execution model produces disastrous results 💀.
- No negative form here either, since it's a three-way choice 💅.
-fcall-saved-reg— 🛡️ treat the register named reg as an allocable register that's saved by functions. It can be allocated even for temporaries or variables that live across a call. Functions compiled this way save and restore reg if they use it 🫶.- Same rule: it's an error to use this with the frame pointer or stack pointer 🚫.
- Using it on other registers with fixed pervasive roles produces disastrous results 😭.
- A different kind of disaster happens if you use this flag on a register that function values may be returned in 🌪️.
- No negative form, three-way choice 🦋.
-fpack-struct[=n]— 📦 without a value, this packs all structure members together with no holes. With a value (which has to be a small power of two), it packs structure members according to that value, which is the maximum alignment. So objects with default alignment requirements bigger than that get output potentially unaligned at the next fitting location 🧩.
⚠️ Warning, bestie: -fpack-struct makes GCC generate code that is not binary compatible with code generated without it. It also makes the code suboptimal 😬. Only use it to conform to a non-default application binary interface.
-fleading-underscore— 🎀 this one and its counterpart-fno-leading-underscoreforcibly change how C symbols are represented in the object file. One use is to help link with legacy assembly code 🧓.
⚠️ Warning: -fleading-underscore makes GCC generate code that is not binary compatible with code generated without it 💔. Use it only to conform to a non-default application binary interface. And not every target fully supports this switch, so check before you count on it 🙈.
-ftls-model=model— 🧵 alter the thread-local storage model. The model argument should be one ofglobal-dynamic,local-dynamic,initial-execorlocal-exec🌷. The choice is subject to optimization though, so the compiler might use a more efficient model for symbols that aren't visible outside the translation unit, or if-fpicisn't given on the command line 🧠.- The default without
-fpicisinitial-exec. With-fpic, the default isglobal-dynamic✨.
- The default without
-ftrampolines— 🎠 for targets that normally need trampolines for nested functions, this always generates them instead of using descriptors. For targets that don't need them, like HP-PA or IA-64, it does nothing 🌿.- A trampoline is a tiny piece of code that gets created at run time on the stack when the address of a nested function is taken. It's used to call the nested function indirectly 🦄. That means the stack has to be made executable for the program to work properly 😳.
-fno-trampolinesis enabled by default on a language-by-language basis, so the compiler can skip generating trampolines when it figures that's safe and swap in descriptors instead 🧁. Descriptors are made up of data only, but the generated code has to be ready to deal with them 💜. As of this writing,-fno-trampolinesis enabled by default only for Ada 👑.- Code compiled with
-ftrampolinesand code compiled with-fno-trampolinesare not binary compatible if nested functions are present. So this option has to be used program-wide, and it needs extreme care 😤. - For languages other than Ada,
-ftrampolinesand-fno-trampolinescurrently have no effect. Trampolines are always generated on platforms that need them for nested functions 🌸.
-ftrampoline-impl=[stack|heap]— 🏠 by default, trampolines get generated on the stack. But some platforms (like the Apple M1) don't allow an executable stack 🙅♀️. Compiling with-ftrampoline-impl=heapgenerates calls to__gcc_nested_func_ptr_createdand__gcc_nested_func_ptr_deleted, which allocate and deallocate trampoline space on the executable heap 🧺. These functions are implemented in libgcc and only get provided on specific targets: x86_64 Darwin, and x86_64 and aarch64 Linux 🐧.
🚨 PLEASE NOTE: heap trampolines are not guaranteed to be correctly deallocated if yousetjmp, instantiate nested functions, and thenlongjmpback to a state prior to having allocated those nested functions. Be careful, bestie 💀.
-fvisibility=[default|internal|hidden|protected]— 👀 this sets the default ELF image symbol visibility to the option you pick. Every symbol gets marked with it unless the code overrides it 💖. Using this can massively improve linking and load times of shared object libraries, produce more optimized code, give you near-perfect API export, and prevent symbol clashes 🔥. It's strongly recommended that you use this in any shared objects you distribute 🫶.- Despite the name,
defaultalways means public, meaning it's available to be linked against from outside the shared object 🌈.protectedandinternalare pretty useless in real-world usage, so the only other one people commonly use ishidden🙈. - If you don't specify
-fvisibility, the default isdefault, which makes every symbol public 🧚. - A great explanation of why correct ELF symbol visibility matters is "How To Write Shared Libraries" by Ulrich Drepper, which you can find at
https://www.akkadia.org/drepper/📖. But here's the superior move 👑: instead of marking thingshiddenwhen the default is public, make the defaulthiddenand mark the things you want public. That's the norm with DLLs on Windows. With-fvisibility=hiddenand__attribute__ ((visibility("default")))instead of__declspec(dllexport), you get almost identical semantics with identical syntax 🦋. It's a total boon for anyone working on cross-platform projects 💅✨.
- Despite the name,
Okay so, if you're adding visibility support to existing code, #pragma GCC visibility is literally your new bestie 🫶. You wrap the declarations you want to control with #pragma GCC visibility push(hidden) and close it off with #pragma GCC visibility pop. ✨
Real talk though: symbol visibility is part of the API interface contract 📜, so all new code should always specify visibility whenever it isn't the default. Declarations that are only for use within the local DSO should ALWAYS be explicitly marked as hidden 🙈, so you dodge PLT indirection overheads. Being super clear about it also helps readability and makes the code self-documenting. Iconic behavior 💅. Heads up though: due to ISO C++ specification requirements, operator new and operator delete must always be of default visibility. Nonnegotiable 😭.
Watch out for headers from outside your project 👀, especially system headers and headers from any other library you use. They might not be expecting to be compiled with any visibility other than the default. If that's the case, you may need to explicitly say #pragma GCC visibility push(default) before including them. 🌸
extern declarations are NOT affected by -fvisibility 🧚, which means a lot of code can be recompiled with -fvisibility=hidden with zero modifications. Lowkey amazing. But here's the catch: calls to extern functions with no explicit visibility use the PLT, so it's way more effective to use __attribute ((visibility)) and/or #pragma GCC visibility to tell the compiler which extern declarations should be treated as hidden 💖.
Also, -fvisibility does affect C++ vague linkage entities 🌈. So, for instance, an exception class that gets thrown between DSOs must be explicitly marked with default visibility so the type_info nodes get unified between the DSOs. Don't skip this one bestie 💀.
If you want the full tea on all these techniques, their benefits, and how to use them, check out the overview at https://gcc.gnu.org/wiki/Visibility. 🦋
-fstrict-volatile-bitfields 🍓
This one is for when accesses to volatile bit-fields (or other structure fields, although the compiler usually honors those types anyway) should use a single access of the width of the field's type, aligned to a natural alignment if possible. For example, targets with memory-mapped peripheral registers might require all such accesses to be 16 bits wide. With this flag you can declare all peripheral bit-fields as unsigned short (assuming short is 16 bits on these targets) to force GCC to use 16-bit accesses instead of, perhaps, a more efficient 32-bit access. 🎀
If this option is disabled, the compiler uses the most efficient instruction. In the previous example, that might be a 32-bit load instruction, even though that accesses bytes that don't contain any part of the bit-field, or memory-mapped registers unrelated to the one being updated. Yikes 😬.
In some cases, such as when the packed attribute is applied to a structure field, it may not be possible to access the field with a single read or write that is correctly aligned for the target machine. In this case GCC falls back to generating multiple accesses rather than code that will fault or truncate the result at run time. Safe and sound 💜.
Note: Due to restrictions of the C/C++11 memory model, write accesses are not allowed to touch non bit-field members. It is therefore recommended to define all bits of the field's type as bit-field members. 🙏
The default value of this option is determined by the application binary interface for the target processor. ✨
-fsync-libcalls 🔥
This option controls whether any out-of-line instance of the __sync family of functions may be used to implement the C++11 __atomic family of functions.
The default value of this option is enabled, so the only useful form of the option is -fno-sync-libcalls. This option is used in the implementation of the libatomic runtime library. 👑
🦋 GCC Developer Options 🦋
This section covers command-line options that are mainly of interest to GCC developers, including options for compiler testing and for investigating compiler bugs and compile-time performance problems. That includes options that produce debug dumps at various points in the compilation, options that print statistics like memory use and execution time, and options that print info about GCC's configuration, like where it searches for libraries. You should rarely need any of these for ordinary compilation and linking tasks. 🤓
Lots of developer options that make GCC dump output to a file take an optional =filename suffix. You can specify stdout or - to dump to standard output, and stderr for standard error. 📝
If =filename is omitted, a default dump file name is built by concatenating the base dump file name, a pass number, a phase letter, and the pass name. The base dump file name is the name of the output file produced by the compiler if it was explicitly specified and isn't an executable; otherwise it's the source file name. The pass number is determined by the order passes are registered with the compiler's pass manager. This is generally the same as the order of execution, but passes registered by plugins, target-specific passes, or passes that are otherwise registered late are numbered higher than the pass named final, even if they're executed earlier. The phase letter is one of i (inter-procedural analysis), l (language-specific), r (RTL), or t (tree). The files are created in the directory of the output file. 📂
-fcallgraph-info, -fcallgraph-info=MARKERS 🕸️
Makes the compiler output callgraph information for the program, on a per-object-file basis. The information is generated in the common VCG format. It can be decorated with additional, per-node and/or per-edge information, if a list of comma-separated markers is also specified. When the su marker is specified, the callgraph is decorated with stack usage information; it's equivalent to -fstack-usage. When the da marker is specified, the callgraph is decorated with information about dynamically allocated objects. 💅
When compiling with -flto, no callgraph information is output along with the object file. At LTO link time, -fcallgraph-info may generate multiple callgraph information files next to the intermediate LTO output files. 🌙
-dletters, -fdump-rtl-pass, -fdump-rtl-pass=filename 🧚♀️
Says to make debugging dumps during compilation at the times specified by letters. This is used for debugging the RTL-based passes of the compiler. 🔍
Some -dletters switches have a different meaning when -E is used for preprocessing. 🙃
Debug dumps can be enabled with a -fdump-rtl switch or some -d option letters. Here's the lineup of possible letters for use in pass and letters, and what each one means 👇
-fdump-rtl-alignments— Dumps after branch alignments have been computed. 📏-fdump-rtl-asmcons— Dumps after fixing RTL statements that have unsatisfied in/out constraints. 🛠️-fdump-rtl-auto_inc_dec— Dumps after auto-inc-dec discovery. This pass is only run on architectures that have auto inc or auto dec instructions. 🦋-fdump-rtl-barriers— Dumps after cleaning up the barrier instructions. 🧹-fdump-rtl-bbpart— Dumps after partitioning hot and cold basic blocks. 🔥❄️-fdump-rtl-bbro— Dumps after block reordering. 🔀-fdump-rtl-btl1,-fdump-rtl-btl2— Enable dumping after the two branch target load optimization passes. 🎯-fdump-rtl-bypass— Dumps after jump bypassing and control flow optimizations. 🛤️-fdump-rtl-combine— Dumps after the RTL instruction combination pass. 🧩-fdump-rtl-compgotos— Dumps after duplicating the computed gotos. 🪄-fdump-rtl-ce1,-fdump-rtl-ce2,-fdump-rtl-ce3— Enable dumping after the three if conversion passes. 🔁-fdump-rtl-cprop_hardreg— Dumps after hard register copy propagation. 📋-fdump-rtl-csa— Dumps after combining stack adjustments. 🥞-fdump-rtl-cse1,-fdump-rtl-cse2— Enable dumping after the two common subexpression elimination passes. 🌸-fdump-rtl-dce— Dumps after the standalone dead code elimination passes. 🗑️-fdump-rtl-dbr— Dumps after delayed branch scheduling. ⏳-fdump-rtl-dce1,-fdump-rtl-dce2— Enable dumping after the two dead store elimination passes. 💀-fdump-rtl-eh— Dumps after finalization of EH handling code. 🚨-fdump-rtl-eh_ranges— Dumps after conversion of EH handling range regions. 🗺️-fdump-rtl-expand— Dumps after RTL generation. 🌱-fdump-rtl-fwprop1,-fdump-rtl-fwprop2— Enable dumping after the two forward propagation passes. ➡️-fdump-rtl-gcse1,-fdump-rtl-gcse2— Enable dumping after global common subexpression elimination. 🌍-fdump-rtl-init-regs— Dumps after the initialization of the registers. 🏁-fdump-rtl-initvals— Dumps after the computation of the initial value sets. 🌱-fdump-rtl-into_cfglayout— Dumps after converting to cfglayout mode. 🧭-fdump-rtl-ira— Dumps after iterated register allocation. 🗂️-fdump-rtl-jump— Dumps after the second jump optimization. 🦘-fdump-rtl-loop2— Enables dumping after the RTL loop optimization passes. 🔄-fdump-rtl-mach— Dumps after performing the machine dependent reorganization pass, if that pass exists. 🤖-fdump-rtl-mode_sw— Dumps after removing redundant mode switches. 🎚️-fdump-rtl-rnreg— Dumps after register renumbering. 🔢-fdump-rtl-outof_cfglayout— Dumps after converting from cfglayout mode. 🧭-fdump-rtl-peephole2— Dumps after the peephole pass. 🔍-fdump-rtl-postreload— Dumps after post-reload optimizations. 🔧-fdump-rtl-pro_and_epilogue— Dumps after generating the function prologues and epilogues. 🎬-fdump-rtl-sched1,-fdump-rtl-sched2— Enable dumping after the basic block scheduling passes. 🗓️
-fdump-rtl-ree Dump after sign/zero extension elimination.
Hm bestie, I'm not even sure I need to show you a -fdump-rtl-ree example. Okay wait, no, let's get into it 💅
Okay, -fdump-rtl-ree is the one that dumps right after the sign/zero extension elimination pass. Lowkey iconic.
-fdump-rtl-seqabstr Dump after common sequence discovery.
Okay so -fdump-rtl-seqabstr gives you a dump after common sequence discovery. It's giving pattern-finding energy 🔍✨
-fdump-rtl-shorten Dump after shortening branches.
-fdump-rtl-shorten dumps after the branch-shortening pass. Main character energy for branches 🦋
-fdump-rtl-sibling Dump after sibling call optimizations.
-fdump-rtl-sibling is the one for after sibling call optimizations. Slay 💖
-fdump-rtl-split1 -fdump-rtl-split2 -fdump-rtl-split3 -fdump-rtl-split4 -fdump-rtl-split5 These options enable dumping after five rounds of instruction splitting.
Okay bestie, these five are the splits. -fdump-rtl-split1 through -fdump-rtl-split5 each give you a dump after one of the five rounds of instruction splitting. Five rounds, no cap 🌈
-fdump-rtl-sms Dump after modulo scheduling. This pass is only run on some architectures.
-fdump-rtl-sms dumps after modulo scheduling. Heads up, this one only runs on some architectures, so if it's not showing up, that's why 🙈
-fdump-rtl-stack Dump after conversion from GCC's "flat register file" registers to the x87's stack-like registers. This pass is only run on x86 variants.
-fdump-rtl-stack is the dump after GCC turns its "flat register file" registers into the x87's stack-like registers. This pass only runs on x86 variants, so don't be surprised if it's missing elsewhere 🎀
-fdump-rtl-subreg1 -fdump-rtl-subreg2 -fdump-rtl-subreg1 and -fdump-rtl-subreg2 enable dumping after the two subreg expansion passes.
Okay so -fdump-rtl-subreg1 and -fdump-rtl-subreg2 both give you dumps after the two subreg expansion passes. Two passes, two dumps, we love a matching set 🧚
-fdump-rtl-unshare Dump after all rtl has been unshared.
-fdump-rtl-unshare dumps after all the RTL has been unshared. Unshared and iconic 👑
-fdump-rtl-vartrack Dump after variable tracking.
-fdump-rtl-vartrack is the one for after variable tracking 🫶
-fdump-rtl-vregs Dump after converting virtual registers to hard registers.
-fdump-rtl-vregs dumps after virtual registers have been converted to hard registers. Virtual to hard, the ultimate glow-up ✨
-fdump-rtl-web Dump after live range splitting.
-fdump-rtl-web dumps after live range splitting. It's giving web-weaving vibes 🕸️💜
-fdump-rtl-regclass -fdump-rtl-subregs_of_mode_init -fdump-rtl-subregs_of_mode_finish -fdump-rtl-dfinit -fdump-rtl-dfinish These dumps are defined but always produce empty files.
Bestie, I have to warn you about these five: -fdump-rtl-regclass, -fdump-rtl-subregs_of_mode_init, -fdump-rtl-subregs_of_mode_finish, -fdump-rtl-dfinit, and -fdump-rtl-dfinish are defined but always produce empty files. Don't waste your time staring at them 💀
-da -fdump-rtl-all Produce all the dumps listed above.
-da and -fdump-rtl-all both produce all the dumps listed above. The whole buffet 🍓
-dA Annotate the assembler output with miscellaneous debugging information.
-dA adds miscellaneous debugging information to the assembler output. Extra annotations, extra cute 🎀
-dD Dump all macro definitions, at the end of preprocessing, in addition to normal output.
-dD dumps all macro definitions at the end of preprocessing, on top of the normal output. Every macro, served 💅
-dH Produce a core dump whenever an error occurs.
-dH makes GCC produce a core dump whenever an error occurs. Errors, hit different now 😭
-dp Annotate the assembler output with a comment indicating which pattern and alternative is used. The length and cost of each instruction are also printed.
-dp annotates the assembler output with a comment saying which pattern and alternative got used. It also prints the length and cost of each instruction. Receipts for every instruction 🧾🌸
-dP Dump the RTL in the assembler output as a comment before each instruction. Also turns on -dp annotation.
-dP puts the RTL in the assembler output as a comment before each instruction. It also turns on the -dp annotation, so you get both 🦋
-dx Just generate RTL for a function instead of compiling it. Usually used with -fdump-rtl-expand.
-dx just generates RTL for a function instead of compiling it all the way. It's usually paired with -fdump-rtl-expand 🧚✨
-fdump-debug Dump debugging information generated during the debug generation phase.
-fdump-debug dumps the debugging information generated during the debug generation phase. Debug tea, spilled ☕
-fdump-earlydebug Dump debugging information generated during the early debug generation phase.
-fdump-earlydebug does the same thing but for the early debug generation phase. Early bird debug gets the worm 🐛
-fdump-noaddr When doing debugging dumps, suppress address output. This makes it more feasible to use diff on debugging dumps for compiler invocations with different compiler binaries and/or different text / bss / data / heap / stack / dso start locations.
Okay this one is so useful, bestie. -fdump-noaddr hides address output in debugging dumps, which makes it way easier to diff dumps when your compiler invocations use different compiler binaries, or different text, bss, data, heap, stack, or dso start locations. Less noise, more vibes 🫶💖
-freport-bug Collect and dump debug information into a temporary file if an internal compiler error (ICE) occurs.
-freport-bug collects and dumps debug information into a temporary file if an internal compiler error (ICE) happens. Ate that ICE, and left no crumbs 🥹
-fdump-unnumbered When doing debugging dumps, suppress instruction numbers and address output. This makes it more feasible to use diff on debugging dumps for compiler invocations with different options, in particular with and without -g.
-fdump-unnumbered suppresses instruction numbers and address output in debugging dumps. That makes diff way more feasible when your invocations use different options, especially with and without -g 🌈
-fdump-unnumbered-links When doing debugging dumps (see -d option above), suppress instruction numbers for the links to the previous and next instructions in a sequence.
-fdump-unnumbered-links is for when you're doing debugging dumps (see the -d option above). It suppresses instruction numbers for the links to the previous and next instructions in a sequence. Links with no numbers, no drama 🔗💜
-fdump-ipa-switch -fdump-ipa-switch-options Control the dumping at various stages of inter-procedural analysis language tree to a file. The file name is generated by appending a switch specific suffix to the source file name, and the file is created in the same directory as the output file. The following dumps are possible:
Okay so -fdump-ipa-switch and -fdump-ipa-switch-options control dumping at various stages of inter-procedural analysis language tree to a file. The file name comes from appending a switch-specific suffix to the source file name, and the file gets created in the same directory as the output file. Here are the dumps you can pick from:
all Enables all inter-procedural analysis dumps.
cgraph Dumps information about call-graph optimization, unused function removal, and inlining decisions.
inline Dump after function inlining.
strubm Dump after selecting "strub" modes, and recording the selections as function attributes.
strub Dump "strub" transformations: interface changes, function wrapping, and insertion of builtin calls for stack scrubbing and watermarking.
Additionally, the options -optimized, -missed, -note, and -all can be provided, with the same meaning as for -fopt-info, defaulting to -optimized.
For example, -fdump-ipa-inline-optimized-missed will emit information on callsites that were inlined, along with callsites that were not inlined.
By default, the dump will contain messages about successful optimizations (equivalent to -optimized) together with low-level details about the analysis.
-fdump-lang Dump language-specific information. The file name is made by appending .lang to the source file name.
-fdump-lang dumps language-specific information. The file name is made by appending .lang to the source file name 🌸
-fdump-lang-all -fdump-lang-switch -fdump-lang-switch-options -fdump-lang-switch-options=filename Control the dumping of language-specific information. The options and filename portions behave as described in the -fdump-tree option. The following switch values are accepted:
-fdump-lang-all, -fdump-lang-switch, -fdump-lang-switch-options, and -fdump-lang-switch-options=filename control the dumping of language-specific information. The options and filename parts work the same way as described under -fdump-tree. These switch values are accepted:
all Enable all language-specific dumps.
class Dump class hierarchy information. Virtual table information is emitted unless 'slim' is specified. This option is applicable to C++ only.
module Dump module information. Options lineno (locations), graph (reachability), blocks (clusters), uid (serialization), alias (mergeable), asmname (Elrond), eh (mapper) & vops (macros) may provide additional information. This option is applicable to C++ only.
raw Dump the raw internal tree data. This option is applicable to C++ only.
-fdump-passes Print on stderr the list of optimization passes that are turned on and off by the current command-line options.
-fdump-passes prints to stderr the list of optimization passes that are turned on and off by your current command-line options 📋✨
-fdump-statistics-option Enable and control dumping of pass statistics in a separate file. The file name is generated by appending a suffix ending in .statistics to the source file name, and the file is created in the same directory as the output file. If the -option form is used, -stats causes counters to be summed over the whole compilation unit while -details dumps every event as the passes generate them. The default with no option is to sum counters for each function compiled.
-fdump-statistics-option turns on and controls pass statistics dumping into a separate file. The file name comes from appending a suffix ending in .statistics to the source file name, and it gets created in the same directory as the output file. With the -option form, -stats sums counters over the whole compilation unit, while -details dumps every event as the passes generate them. With no option, the default is to sum counters for each function compiled 📊💅
-fdump-tree-all -fdump-tree-switch -fdump-tree-switch-options -fdump-tree-switch-options=filename Control the dumping at various stages of processing the intermediate language tree to a file. If the -options form is used, options is a list of - separated options which control the details of the dump. Not all options are applicable to all dumps; those that are not meaningful are ignored. The following options are available
Okay, -fdump-tree-all, -fdump-tree-switch, -fdump-tree-switch-options, and -fdump-tree-switch-options=filename control dumping at various stages of processing the intermediate language tree to a file. If you use the -options form, options is a list of - separated options that control the details of the dump. Not every option works with every dump, and the ones that don't apply just get ignored. These are the options available:
address Print the address of each node. Usually this is not meaningful as it changes according to the environment and source file. Its primary use is for tying up a dump file with a debug environment.
asmname If "DECL_ASSEMBLER_NAME" has been set for a given decl, use that in the dump instead of "DECL_NAME". Its primary use is ease of use working backward from mangled names in the assembly file.
slim When dumping front-end intermediate representations, inhibit dumping of members of a scope or body of a function merely because that scope has been reached. Only dump such items when they are directly reachable by some other path.
When dumping pretty-printed trees, this option inhibits dumping the bodies of control structures.
When dumping RTL, print the RTL in slim (condensed) form instead of the default LISP-like representation.
raw Print a raw representation of the tree. By default, trees are pretty-printed into a C-like representation.
details Enable more detailed dumps (not honored by every dump option). Also include information from the optimization passes.
stats Enable dumping various statistics about the pass (not honored by every dump option).
blocks Enable showing basic block boundaries (disabled in raw dumps).
graph For each of the other indicated dump files (-fdump-rtl-pass), dump a representation of the control flow graph suitable for viewing with GraphViz to file.passid.pass.dot. Each function in the file is pretty-printed as a subgraph, so that GraphViz can render them all in a single plot.
This option currently only works for RTL dumps, and the RTL is always dumped in slim form.
vops Enable showing virtual operands for every statement.
lineno Enable showing line numbers for statements.
uid Enable showing the unique ID ("DECL_UID") for each variable.
verbose Enable showing the tree dump for each statement.
eh Enable showing the EH region number holding each statement.
scev Enable showing scalar evolution analysis details.
optimized Enable showing optimization information (only available in certain passes).
missed Enable showing missed optimization information (only available in certain passes).
note Enable other detailed optimization information (only available in certain passes).
all Turn on all options, except raw, slim, verbose and lineno.
optall Turn on all optimization options, i.e., optimized, missed, and note.
To determine what tree dumps are available or find the dump for a pass of interest follow the steps below.
- Invoke GCC with -fdump-passes and in the stderr output look for a code that corresponds to the pass you are interested in. For example, the codes "tree-evrp", "tree-vrp1", and "tree-vrp2" correspond to the three Value Range Propagation passes. The number at the end distinguishes distinct invocations of the same pass.
- To enable the creation of the dump file, append the pass code to the -fdump- option prefix and invoke GCC with it. For example, to enable the dump from the Early Value Range Propagation pass, invoke GCC with the -fdump-tree-evrp option. Optionally, you may specify the name of the dump file. If you don't specify one, GCC creates as described below.
- Hunt down the pass dump in a file whose name has three parts joined by periods: the name of the source file GCC was invoked to compile, a numeric suffix for the pass number followed by
tfor tree passes (orrfor RTL passes), and finally the pass code. For example, the Early VRP pass dump might be in a file namedmyfile.c.038t.evrpin the current working directory. ngl, the numeric codes are not stable, so they can change from one version of GCC to another 🙈
-fopt-info, -fopt-info-options, -fopt-info-options=filename
Okay so this one controls the optimization dumps coming out of the various optimization passes 💅. If you use the -options form, options is a list of --separated keywords that pick the dump details and the optimizations you want. Think of it as building a little playlist 🎀
The options come in three groups 👑:
- options describing what kinds of messages should be emitted,
- options describing the verbosity of the dump, and
- options describing which optimizations should be included.
You can mix options from each group freely because they don't overlap 🫶. If there's ever a conflict, the later option on the command line wins.
These options control which kinds of messages get emitted:
optimized— Prints information when an optimization is successfully applied. Each pass gets to decide what's relevant. For example, the vectorizer passes print the source location of loops that were successfully vectorized.missed— Prints info about missed optimizations. Individual passes decide what goes in the output.note— Prints verbose info about optimizations, like certain transformations and more detailed messages about decisions.all— Prints detailed optimization info. This includesoptimized,missed, andnote.
This one controls the dump verbosity:
internals— By default, only "high-level" messages are emitted. This turns on extra, more detailed messages that are mostly of interest to GCC developers 🤓.
One or more of these option keywords can be used to describe a group of optimizations:
ipa— Enables dumps from all interprocedural optimizations.loop— Enables dumps from all loop optimizations.inline— Enables dumps from all inlining optimizations.omp— Enables dumps from all OMP (Offloading and Multi Processing) optimizations.vec— Enables dumps from all vectorization optimizations.optall— Enables dumps from all optimizations. This is a superset of the optimization groups listed above.
If options is left out, it defaults to optimized-optall, which means dumping messages about successful optimizations from all the passes while skipping anything marked as "internals" ✨.
If you give a filename, the dumps from all the applicable optimizations get concatenated into it. Otherwise, the dump goes to stderr. You can use several -fopt-info options, but only one of them can include a filename. If other filenames are provided, all but the first such option get ignored.
Heads up: the output filename gets overwritten when there are multiple translation units. If you want combined output from several of them, use stderr instead.
Here's the example where the optimization info goes to stderr:
gcc -O3 -fopt-infoThis one outputs the missed optimization report from all the passes into missed.all:
gcc -O3 -fopt-info-missed=missed.allAnd this one prints info about missed optimization opportunities from the vectorization passes on stderr. Fun fact: -fopt-info-vec-missed is equivalent to -fopt-info-missed-vec, and the order of the optimization group names and message types after -fopt-info doesn't matter 💖:
gcc -O2 -ftree-vectorize -fopt-info-vec-missedAs another example, this outputs info about missed optimizations as well as optimized locations from all the inlining passes into inline.txt 🦋:
gcc -O3 -fopt-info-inline-optimized-missed=inline.txtFinally, consider this one 👀:
gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.optHere, the two output filenames vec.miss and loop.opt are in conflict, since only one output file is allowed. In this case, only the first option takes effect and the subsequent options are ignored. So only vec.miss gets produced, and it contains dumps from the vectorizer about missed opportunities 💅.
-fsave-optimization-record
This writes a SRCFILE.opt-record.json.gz file detailing what optimizations were performed, for the ones that support -fopt-info 📜.
⚠️ This option is experimental, and the format of the data inside the compressed JSON file is subject to change.
It's roughly a machine-readable version of -fopt-info-all, as a collection of messages with source file, line number and column number. Each message also comes with this extra data:
- the execution count of the code being optimized, along with metadata about whether it came from actual profile data or just an estimate, so you can prioritize messages by code hotness 🔥,
- the function name of the code being optimized, where applicable,
- the "inlining chain" for the code being optimized, so that when a function is inlined into several different places (which might themselves be inlined), you can tell the copies apart,
- objects identifying those parts of the message that refer to expressions, statements or symbol-table nodes, which of these categories they are, and, when available, their source code location,
- the GCC pass that emitted the message, and
- the location in GCC's own code from which the message was emitted
Additionally, some messages are logically nested within other messages, reflecting implementation details of the optimization passes 🧩.
-fsched-verbose=n
On targets that use instruction scheduling, this controls how much debugging output the scheduler prints to the dump files 🧠. The levels stack up like this:
- For
ngreater than zero,-fsched-verboseoutputs the same information as-fdump-rtl-sched1and-fdump-rtl-sched2. - For
ngreater than one, it also outputs basic block probabilities, detailed ready list information, and unit/insn info. - For
ngreater than two, it includes RTL at the abort point, control-flow, and regions info. - For
nover four,-fsched-verbosealso includes dependence info.
-fenable-kind-pass, -fdisable-kind-pass=range-list
This is a whole set of options for explicitly disabling and enabling optimization passes 🔧. They're meant for debugging GCC itself, so regular compiler users should use the regular options for enabling and disabling passes instead 💀.
-fdisable-ipa-pass— Disables the IPA pass pass, where pass is the pass name. If the same pass is statically invoked in the compiler multiple times, the pass name should be appended with a sequential number starting from 1.-fdisable-rtl-pass,-fdisable-rtl-pass=range-list— Disables the RTL pass pass, where pass is the pass name. If the same pass is statically invoked in the compiler multiple times, the pass name should be appended with a sequential number starting from 1. range-list is a comma-separated list of function ranges or assembler names. Each range is a number pair separated by a colon, and the range is inclusive at both ends. If the range is trivial, the number pair can be simplified to a single number. If the function's call graph node's uid falls within one of the specified ranges, the pass is disabled for that function. The uid is shown in the function header of a dump file, and the pass names can be dumped by using option-fdump-passes.-fdisable-tree-pass,-fdisable-tree-pass=range-list— Disables the tree pass pass. See-fdisable-rtlfor the description of option arguments.-fenable-ipa-pass— Enables the IPA pass pass, where pass is the pass name. If the same pass is statically invoked in the compiler multiple times, the pass name should be appended with a sequential number starting from 1.-fenable-rtl-pass,-fenable-rtl-pass=range-list— Enables the RTL pass pass. See-fdisable-rtlfor option argument description and examples.-fenable-tree-pass,-fenable-tree-pass=range-list— Enables the tree pass pass. See-fdisable-rtlfor the description of option arguments.
Here are some examples showing how these options get used 🌈:
# disable ccp1 for all functions
-fdisable-tree-ccp1
# disable complete unroll for function whose cgraph node uid is 1
-fenable-tree-cunroll=1
# disable gcse2 for functions at the following ranges [1,1],
# [300,400], and [400,1000]
# disable gcse2 for functions foo and foo2
-fdisable-rtl-gcse2=foo,foo2
# disable early inlining
-fdisable-tree-einline
# disable ipa inlining
-fdisable-ipa-inline
# enable tree full unroll
-fenable-tree-unroll-fchecking, -fchecking=n
This turns on internal consistency checking 🧐. The default depends on the compiler configuration. -fchecking=2 turns on further internal consistency checking, which might affect code generation.
-frandom-seed=string
This option gives GCC a seed to use in place of random numbers when it generates certain symbol names that have to be different in every compiled file 🎲. The seed is also used to place unique stamps in coverage data files and in the object files that produce them. You can use the -frandom-seed option to produce reproducibly identical object files 🌸.
The string can be a number (decimal, octal or hex) or an arbitrary string. An arbitrary string gets converted to a number by computing CRC32 💜.
The string has to be different for every single file you compile, no repeats 🫶
-save-temps— okay so this one keeps all the usual "temporary" intermediate files permanently 💾 instead of tossing them. They get named as auxiliary output files, the same way as described under-dumpbaseand-dumpdir.
When you pair it with -x, -save-temps is smart enough to avoid overwriting an input source file that shares an extension with an intermediate file 🧠 If you want that intermediate file, you can rename the source file before using -save-temps.
-save-temps=cwd— the same as-save-temps -dumpdir ./.📂-save-temps=obj— the same as-save-temps -dumpdir outdir/, whereoutdir/is the directory of the output file given after-o, including any directory separators 🗂️ If you don't use-o, then-save-temps=objacts just like-save-temps=cwd.-time[=file]— reports the CPU time each subprocess in the compilation sequence takes ⏱️ For C source files, that's the compiler proper and the assembler (plus the linker if linking happens).
Without an output file, the output looks like this:
# cc1 0.12 0.01
# as 0.00 0.01The first number on each line is the "user time," which is the time spent executing the program itself. The second is the "system time," which is the time spent in operating system routines on behalf of the program. Both numbers are in seconds ⌛
With an output file, the output gets appended to the named file and looks like this:
0.12 0.01 cc1 <options>
0.00 0.01 as <options>The "user time" and "system time" get moved in front of the program name, and the options passed to the program are shown too. That way you can always tell later what file got compiled and with which options 🔍
-fdump-final-insns[=file]— dumps the final internal representation (RTL) to file 📜 If you leave out the optional argument (or file is.), the dump file name is made by appending.gkdto the dump base name. See-dumpbase.-fcompare-debug[=opts]— if no error happens during compilation, the compiler runs a second time with opts and-fcompare-debug-secondadded to its arguments 🔁 It dumps the final internal representation in both compilations and prints an error if they differ. If you leave off the equal sign, the default-gtoggleis used.
The environment variable GCC_COMPARE_DEBUG, if it's defined, non-empty and nonzero, implicitly enables -fcompare-debug 🌸 If GCC_COMPARE_DEBUG is defined to a string starting with a dash, that string gets used for opts. Otherwise, the default -gtoggle is used.
-fcompare-debug=, with the equal sign but without opts, is the same as -fno-compare-debug 🙅 That turns off dumping the final representation and the second compilation, and it even stops GCC_COMPARE_DEBUG from taking effect.
To verify full coverage during -fcompare-debug testing, set GCC_COMPARE_DEBUG to -fcompare-debug-not-overridden. GCC rejects that as an invalid option in any actual compilation (rather than preprocessing, assembly or linking) 💀 If you just want a warning, setting GCC_COMPARE_DEBUG to -w%n-fcompare-debug not overridden will do the job.
-fcompare-debug-second— this one gets implicitly passed to the compiler for the second compilation requested by-fcompare-debug, along with options to silence warnings 🔇 It skips any other options that would make the compiler write output to files or to standard output as a side effect. Dump files and preserved temporary files get renamed to include the extra ".gk" extension during the second compilation, so they don't overwrite the ones from the first run.
When you pass this option to the compiler driver, the first compilation gets skipped. That makes it pretty much only useful for debugging the compiler proper 🙈
-gtoggle— turns off debug info generation if leaving out this option would generate it, or turns it on at level 2 otherwise 🔀 Its position in the command line doesn't matter. It takes effect after all other options are processed, and it only does this once, no matter how many times you give it. It's mainly meant to be used with-fcompare-debug.-fvar-tracking-assignments-toggle— toggles-fvar-tracking-assignmentsthe same way-gtoggletoggles-g🎀-Q— makes the compiler print out each function name as it's compiled, and print some statistics about each pass when it finishes 🖨️-ftime-report— makes the compiler print some statistics to stderr about the time consumed by each pass when it finishes ⏰
If SARIF output of diagnostics was requested via -fdiagnostics-format=sarif-file or -fdiagnostics-format=sarif-stderr, then the -ftime-report info gets emitted as JSON inside the SARIF output instead 🧾 The exact format of that JSON is subject to change. The values might not match exactly what goes to stderr, since they're written out at a slightly different spot inside the compiler.
-ftime-report-details— records the time consumed by infrastructure parts separately for each pass 🔬-fira-verbose=n— controls how verbose the dump file for the integrated register allocator is 🧩 The default value is 5. If n is 10 or greater, the dump output goes to stderr in the same format as n minus 10.-flto-report— prints a report with internal details on how the link-time optimizer works 🔧 What's in the report changes from version to version. It's meant to be helpful to GCC developers when they're processing object files in LTO mode (via-flto). It's disabled by default.-flto-report-wpa— like-flto-report, but only prints for the WPA phase of link-time optimization 🎯-fmem-report— makes the compiler print some statistics about permanent memory allocation when it finishes 🧠-fmem-report-wpa— makes the compiler print some statistics about permanent memory allocation for the WPA phase only 🎯-fpre-ipa-mem-report,-fpost-ipa-mem-report— makes the compiler print some statistics about permanent memory allocation before or after interprocedural optimization 📊
-fmultiflags— this option enables multilib-aware "TFLAGS" to be used to build target libraries with options that are different from the ones the compiler is configured to use by default 🛠️ It works through specs set up by compiler internals, by the target, or by builders at configure time.
Like "TFLAGS," this lets target libraries be built for portable baseline environments, while the compiler defaults to more demanding ones 💅 That's useful because users can easily override the compiler's defaults to build their own programs when those defaults aren't ideal for their target environment. Rebuilding the runtime libraries is usually not as easy or desirable, though.
Unlike "TFLAGS," using specs lets different flags be selected for different multilibs ✨ The way to do that is to build with make TFLAGS=-fmultiflags, after configuring --with-specs=%{fmultiflags:...}.
This option is discarded by the driver once it's done processing driver self spec.
It's also handy for checking that "TFLAGS" are being used to build all target libraries 🔍 Just configure a non-bootstrap compiler with --with-specs='%{!fmultiflags:%emissing TFLAGS}', then build the compiler and target libraries.
-fprofile-report— makes the compiler print some statistics about the consistency of the (estimated) profile and the effect of individual passes 📈-fstack-usage— makes the compiler output stack usage information for the program, on a per-function basis 🥞 The filename for the dump is made by appending.suto the auxname. The auxname comes from the name of the output file if it's explicitly specified and isn't an executable. Otherwise, it's the basename of the source file. Each entry has three fields:- The name of the function.
- A number of bytes.
- One or more qualifiers: "static", "dynamic", "bounded".
The qualifier "static" means the function manages the stack statically: a fixed number of bytes gets allocated for the frame on function entry and released on function exit, and no other stack adjustments happen in the function. The second field is that fixed number of bytes 🧱
The qualifier "dynamic" means the function manages the stack dynamically. On top of the static allocation, stack adjustments get made in the body of the function, like pushing and popping arguments around function calls 🌀 If "bounded" is also present, the amount of those adjustments is bounded at compile time, and the second field is an upper bound on the total stack used by the function. If "bounded" isn't present, the amount of adjustments isn't bounded at compile time, and the second field only represents the bounded part.
-fstats— emits statistics about front-end processing at the end of the compilation 📋 Only the C++ front end supports this, and the info is generally only useful to the G++ development team 🤓-fdbg-cnt-list— prints the name and the counter upper bound for all debug counters 🔢-fdbg-cnt=counter-value-list— sets the internal debug counter lower and upper bounds 🎚️ counter-value-list is a comma-separated list ofname:lower_bound1-upper_bound1 [:lower_bound2-upper_bound2...]tuples. These set the name of the counter and a list of closed intervals. Thelower_boundis optional and is zero initialized if it isn't set.
For example, with -fdbg-cnt=dce:2-4:10-11,tail_call:10, dbg_cnt(dce) returns true only for the second, third, fourth, tenth and eleventh invocation 🎯 For dbg_cnt(tail_call), true is returned for the first 10 invocations.
-print-file-name=library— prints the full absolute name of the library file library that would be used when linking, and then that's it 🗺️ With this option, GCC doesn't compile or link anything. It just prints the file name 💖-print-multi-directory: Prints the directory name for whichever multilib gets picked by any other switches on your command line 📂 It's supposed to exist insideGCC_EXEC_PREFIX✨-print-multi-lib: Prints the map from multilib directory names to the switches that turn them on 🗺️ The directory name is separated from the switches by;, and each switch starts with@instead of-, with no spaces between multiple switches. This is supposed to make shell processing way easier 💅-print-multi-os-directory: Prints the path to OS libraries for the selected multilib, relative to somelibsubdirectory 🌸 If OS libraries sit in thelibsubdirectory and no multilibs are used, it's usually just.. If they're inlibsuffixsibling directories, you'll see things like../lib64,../libor../lib32. If they're inlib/subdirsubdirectories, you'll get stuff likeamd64,sparcv9orev6🦋-print-multiarch: Prints the path to OS libraries for the selected multiarch, relative to somelibsubdirectory 🧚-print-prog-name=program: Basically-print-file-name, but it searches for a program likecppinstead 🔍-print-libgcc-file-name: Same as-print-file-name=libgcc.a💜
This one is lowkey clutch when you use -nostdlib or -nodefaultlibs but still want to link with libgcc.a. You can do:
gcc -nostdlib <files>... `gcc -print-libgcc-file-name`-print-search-dirs: Prints the name of the configured installation directory and a list of the program and library directoriesgccsearches. It doesn't do anything else, so don't expect a compile 🙈
This is the one you want when gcc yells installation problem, cannot exec cpp0: No such file or directory. To fix that, you either put cpp0 and the other compiler components where gcc expects to find them, or you set the environment variable GCC_EXEC_PREFIX to the directory where you installed them. And don't forget the trailing / 🫶
-print-sysroot: Prints the target sysroot directory used during compilation 🏰 That's the one set at configure time or with--sysroot, possibly with an extra suffix that depends on your compilation options. If no target sysroot is specified, this prints nothing at all 🤷♀️-print-sysroot-headers-suffix: Prints the suffix added to the target sysroot when searching for headers. If the compiler wasn't configured with one, you'll get an error instead, and it won't do anything else 💀-dumpmachine: Prints the compiler's target machine, likei686-pc-linux-gnu. Then it stops, no other business 🌈-dumpversion: Prints the compiler version, like3.0,6.3.0or7, and then it's done ✨ This is the version used in filesystem paths and specs. Depending on how the compiler was configured, it can be one number (the major version), two numbers separated by a dot (major and minor), or three numbers separated by dots (major, minor and patchlevel) 🔥-dumpfullversion: Prints the full compiler version, then stops. The output is always three numbers separated by dots: major, minor and patchlevel 👑-dumpspecs: Prints the compiler's built-in specs and then stops 🧠 (This is used when GCC itself is being built, so it's mostly for the compiler devs, bestie 🫶)
🦋 Machine-Dependent Options 🦋
Each target machine GCC supports can have its own options. For example, you might use them to compile for a particular processor variant or ABI, or to control optimizations that are specific to that machine. By convention, the names of machine-specific options start with -m 💖
Some configurations of the compiler also support additional target-specific options, usually so it plays nicely with other compilers on the same platform ✨
AArch64 Options
These options are defined for AArch64 implementations 💅
-mabi=name: Generates code for the specified data model 🎀 The permissible values areilp32, which is a SysV-like data model whereint,long intand pointers are 32 bits, andlp64, which is a SysV-like data model whereintis 32 bits butlong intand pointers are 64 bits.
The default depends on the specific target configuration. Also, the LP64 and ILP32 ABIs are not link-compatible, so you have to compile your entire program with the same ABI and link it with a compatible set of libraries 🙈
-mbig-endian: Generates big-endian code 🍓 This is the default when GCC is configured for anaarch64_be-*-*target.-mgeneral-regs-only: Generates code that only uses the general-purpose registers 🧚 This stops the compiler from using floating-point and Advanced SIMD registers, but it won't put any restrictions on the assembler.-mlittle-endian: Generates little-endian code 🦋 This is the default when GCC is configured for anaarch64-*-*target but not anaarch64_be-*-*target.-mcmodel=tiny: Generates code for the tiny code model 🌸 The program and its statically defined symbols must be within 1MB of each other. Programs can be statically or dynamically linked.-mcmodel=small: Generates code for the small code model 🌷 The program and its statically defined symbols must be within 4GB of each other. Programs can be statically or dynamically linked. This is the default code model.-mcmodel=large: Generates code for the large code model 🌌 This makes no assumptions about addresses and sizes of sections. Programs can be statically linked only.
The-mcmodel=largeoption is incompatible with-mabi=ilp32,-fpicand-fPIC. Don't mix them up, bestie 🚫
-mtp=name: Specifies the system register to use as a thread pointer 🧵 The valid values aretpidr_el0,tpidrro_el0,tpidr_el1,tpidr_el2andtpidr_el3. For backwards compatibility, the aliasesel0,el1,el2andel3are also accepted. The default setting istpidr_el0.
It's recommended to compile all code that's meant to interoperate with the same value of this option, so you don't accidentally access a different thread pointer from the wrong exception level 😭
-mstrict-align,-mno-strict-align: Avoids or allows generating memory accesses that may not be aligned on a natural object boundary, as described in the architecture specification 📐-momit-leaf-frame-pointer,-mno-omit-leaf-frame-pointer: Omits or keeps the frame pointer in leaf functions 🍃 The former behavior is the default.-mstack-protector-guard=guard,-mstack-protector-guard-reg=reg,-mstack-protector-guard-offset=offset: Generates stack protection code using a canary atguard. The supported locations areglobalfor a global canary, orsysregfor a canary in an appropriate system register 🛡️
With the sysreg choice, the options -mstack-protector-guard-reg=reg and -mstack-protector-guard-offset=offset specify which system register to use as the base register for reading the canary, and what offset from that base register to use. There is no default register or offset, because this is entirely for use within the Linux kernel 🐧
-mtls-dialect=desc: Uses TLS descriptors as the thread-local storage mechanism for dynamic accesses of TLS variables. This is the default 💜-mtls-dialect=traditional: Uses traditional TLS as the thread-local storage mechanism for dynamic accesses of TLS variables 🕰️-mtls-size=size: Specifies the bit size of immediate TLS offsets. The valid values are12,24,32and48. This option requires binutils 2.26 or newer 🔧-mfix-cortex-a53-835769,-mno-fix-cortex-a53-835769: Enables or disables the workaround for ARM Cortex-A53 erratum number 835769 🩹 This involves inserting a NOP instruction between memory instructions and 64-bit integer multiply-accumulate instructions.-mfix-cortex-a53-843419,-mno-fix-cortex-a53-843419: Enables or disables the workaround for ARM Cortex-A53 erratum number 843419 🩹 This erratum workaround is made at link time, so this option only passes the corresponding flag to the linker.-mlow-precision-recip-sqrt,-mno-low-precision-recip-sqrt: Enables or disables the reciprocal square root approximation ⚡ This option only has an effect if-ffast-mathor-funsafe-math-optimizationsis used as well. Enabling it reduces the precision of reciprocal square root results to about 16 bits for single precision and about 32 bits for double precision.-mlow-precision-sqrt,-mno-low-precision-sqrt: Enables or disables the square root approximation 🌀 This option only has an effect if-ffast-mathor-funsafe-math-optimizationsis used as well. Enabling it reduces the precision of square root results to about 16 bits for single precision and about 32 bits for double precision. If enabled, it implies-mlow-precision-recip-sqrt.-mlow-precision-div,-mno-low-precision-div: Enables or disables the division approximation ➗ This option only has an effect if-ffast-mathor-funsafe-math-optimizationsis used as well. Enabling it reduces the precision of division results to about 16 bits for single precision and about 32 bits for double precision.-mtrack-speculation,-mno-track-speculation: Enables or disables generation of additional code to track speculative execution through conditional branches 👀 The tracking state can then be used by the compiler when expanding calls to"__builtin_speculation_safe_copy", so it can generate a more efficient code sequence.-moutline-atomics,-mno-outline-atomics: Enables or disables calls to out-of-line helpers that implement atomic operations 🧩 At runtime, these helpers figure out whether the LSE instructions from ARMv8.1-A can be used. If not, they fall back to the load/store-exclusive instructions that are present in the base ARMv8.0 ISA.
This option is only applicable when compiling for the base ARMv8.0 instruction set. If you're using a later revision, like -march=armv8.1-a or -march=armv8-a+lse, the ARMv8.1-Atomics instructions get used directly. The same goes for -mcpu= when the selected CPU supports the lse feature. This option is on by default 🔥
-march=name: Specifies the name of the target architecture and, optionally, one or more feature modifiers 🏗️ This option has the form-march=arch{+[no]feature}*.
The table just below sums up the permissible values for arch and the features that each one enables by default 💅
okay so here's the whole architecture lineup, bestie 💖 each row reads arch value : Architecture : Includes by default, so you can see what every value is and what extra bits come along with it ✨
arch value : Architecture : Includes by default
armv8-a : Armv8-A : +fp, +simd
armv8.1-a : Armv8.1-A : armv8-a, +crc, +lse, +rdma
armv8.2-a : Armv8.2-A : armv8.1-a
armv8.3-a : Armv8.3-A : armv8.2-a, +pauth
armv8.4-a : Armv8.4-A : armv8.3-a, +flagm, +fp16fml, +dotprod
armv8.5-a : Armv8.5-A : armv8.4-a, +sb, +ssbs, +predres
armv8.6-a : Armv8.6-A : armv8.5-a, +bf16, +i8mm
armv8.7-a : Armv8.7-A : armv8.6-a, +ls64
armv8.8-a : Armv8.8-a : armv8.7-a, +mops
armv8.9-a : Armv8.9-a : armv8.8-a
armv9-a : Armv9-A : armv8.5-a, +sve, +sve2
armv9.1-a : Armv9.1-A : armv9-a, +bf16, +i8mm
armv9.2-a : Armv9.2-A : armv9.1-a, +ls64
armv9.3-a : Armv9.3-A : armv9.2-a, +mops
armv9.4-a : Armv9.4-A : armv9.3-a
armv8-r : Armv8-R : armv8-rThe value native is available on native AArch64 GNU/Linux and makes the compiler pick the architecture of the host system 🌈 If the compiler can't recognize the host system's architecture, this option just does nothing, so no drama 🫶
The permissible values for feature are listed in the sub-section on aarch64-feature-modifiers,,-march and -mcpu Feature Modifiers. If you specify conflicting feature modifiers, the right-most one wins 👑
GCC looks at name to decide what kind of instructions it's allowed to emit when generating assembly code 💅 If you use -march without also using -mtune or -mcpu, the code gets tuned to perform well across a whole range of target processors that implement the target architecture ✨
🎀 -mtune=name
Here you tell GCC the name of the target processor it should tune the performance of your code for 💖 The permissible values are: generic, cortex-a35, cortex-a53, cortex-a55, cortex-a57, cortex-a72, cortex-a73, cortex-a75, cortex-a76, cortex-a76ae, cortex-a77, cortex-a65, cortex-a65ae, cortex-a34, cortex-a78, cortex-a78ae, cortex-a78c, ares, exynos-m1, emag, falkor, neoverse-512tvb, neoverse-e1, neoverse-n1, neoverse-n2, neoverse-v1, neoverse-v2, qdf24xx, saphira, phecda, xgene1, vulcan, octeontx, octeontx81, octeontx83, octeontx2, octeontx2t98, octeontx2t96, octeontx2t93, octeontx2f95, octeontx2f95n, octeontx2f95mm, a64fx, thunderx, thunderxt88, thunderxt88p1, thunderxt81, tsv110, thunderxt83, thunderx2t99, thunderx3t110, zeus, cortex-a57.cortex-a53, cortex-a72.cortex-a53, cortex-a73.cortex-a35, cortex-a73.cortex-a53, cortex-a75.cortex-a55, cortex-a76.cortex-a55, cortex-r82, cortex-x1, cortex-x1c, cortex-x2, cortex-x3, cortex-x4, cortex-a510, cortex-a520, cortex-a710, cortex-a715, cortex-a720, ampere1, ampere1a, ampere1b, cobalt-100 and native.
The values cortex-a57.cortex-a53, cortex-a72.cortex-a53, cortex-a73.cortex-a35, cortex-a73.cortex-a53, cortex-a75.cortex-a55 and cortex-a76.cortex-a55 tell GCC to tune for a big.LITTLE system 🧚
The value neoverse-512tvb tells GCC to tune for Neoverse cores that (a) implement SVE and (b) have a total vector bandwidth of 512 bits per cycle 🔥 Basically, the option tells GCC to tune for Neoverse cores that can execute 4 128-bit Advanced SIMD arithmetic instructions a cycle, and that can execute an equivalent number of SVE arithmetic instructions per cycle (2 for 256-bit SVE, 4 for 128-bit SVE). It's more general than tuning for a specific core like Neoverse V1, but more specific than the default tuning described below 🦋
Additionally, on native AArch64 GNU/Linux systems, the value native tunes performance to the host system. If the compiler can't recognize the processor of the host system, this option has no effect 🌸
If none of -mtune=, -mcpu= or -march= are specified, the code is tuned to perform well across a range of target processors 💜
This option cannot be suffixed by feature modifiers 🙈
🌷 -mcpu=name
Here you name the target processor, and you can optionally suffix it with one or more feature modifiers ✨ The form is -mcpu=cpu{+[no]feature}*, where the permissible values for cpu are the same as the ones for -mtune 💖 The permissible values for feature are documented in the sub-section on aarch64-feature-modifiers,,-march and -mcpu Feature Modifiers. Again, if feature modifiers conflict, the right-most feature is used 👑
GCC uses name to figure out what kind of instructions it can emit when generating assembly code (just like -march does) and to figure out which target processor to tune for performance (just like -mtune does) 💅 If you use this option together with -march or -mtune, those options take precedence over the matching part of this option 🫶
-mcpu=neoverse-512tvb is special, because it doesn't refer to one specific core. Instead it refers to all Neoverse cores that (a) implement SVE and (b) have a total vector bandwidth of 512 bits a cycle 😭 Unless you override it with -march, -mcpu=neoverse-512tvb generates code that can run on a Neoverse V1 core, since Neoverse V1 is the first Neoverse core with these properties 🦄 Unless you override it with -mtune, -mcpu=neoverse-512tvb tunes code in the same way as for -mtune=neoverse-512tvb 🌈
🫧 -moverride=string
This lets you override the tuning decisions the back-end makes in response to a -mtune= switch 🍓
⚠️ The syntax, semantics, and accepted values for string in this option are not guaranteed to be consistent across releases. It's only intended to be useful when developing GCC, so maybe don't go wild with it 💀
🔍 -mverbose-cost-dump
This turns on verbose cost model dumping in the debug dump files 🧁 It's provided for debugging the compiler, so it's more of a GCC-dev thing 💜
🌙 -mpc-relative-literal-loads / -mno-pc-relative-literal-loads
These enable or disable PC-relative literal loads 🌸 With this option on, literal pools get accessed using a single instruction and are emitted after each function. The catch is that this limits the maximum size of functions to 1MB ✨ It's enabled by default for -mcmodel=tiny 🦋
🪽 -msign-return-address=scope
This picks the function scope that return address signing gets applied to 💅 The permissible values are none, which disables return address signing; non-leaf, which enables pointer signing for functions that aren't leaf functions; and all, which enables pointer signing for all functions 🫶 The default value is none.
⚠️ This option has been deprecated by -mbranch-protection, so switch over when you can 😭
🛡️ -mbranch-protection=none|standard|pac-ret[+leaf+b-key]|bti
This selects which branch protection features to use 🔐 none is the default and turns off all types of branch protection. standard turns on all types of branch protection features, and if a feature has additional tuning options, standard sets it to its standard level 👑
pac-ret[+leaf] turns on return address signing to its standard level, which means signing functions that save the return address to memory (non-leaf functions will practically always do this) using the a-key 🌈 The optional argument leaf can be used to extend the signing to include leaf functions. The optional argument b-key can be used to sign the functions with the B-key instead of the A-key 🙈
bti turns on the branch target identification mechanism 🎀
🧱 -mharden-sls=opts
This enables compiler hardening against straight line speculation (SLS) 💖 opts is a comma-separated list of the following options:
retbrblr
On top of that, -mharden-sls=all enables all SLS hardening, while -mharden-sls=none disables all SLS hardening 🫧
🕰️ -mearly-ra=scope
This determines when to enable an early register allocation pass ✨ The pass runs before instruction scheduling and tries to find a spill-free allocation of floating-point and vector code. It also tries to make use of strided multi-register instructions, such as SME2's strided LD1 and ST1 💅
The possible values of scope are:
all— runs the pass on all functionsstrided— runs the pass on functions that have access to strided multi-register instructionsnone— disables the pass
-mearly-ra=all is the default for -O2 and above, and for -Os. -mearly-ra=none is the default otherwise 🌸
⚡ -mearly-ldp-fusion
This enables the copy of the AArch64 load/store pair fusion pass that runs before register allocation 🔥 It's enabled by default at -O and above 💖
⚡ -mlate-ldp-fusion
This enables the copy of the AArch64 load/store pair fusion pass that runs after register allocation 🔥 It's also enabled by default at -O and above 💜
📏 -msve-vector-bits=bits
This specifies the number of bits in an SVE vector register 🦋 It only has an effect when SVE is enabled, so no SVE, no vibes 🙈
GCC supports two forms of SVE code generation. "Vector-length agnostic" output works with any size of vector register, and "vector-length specific" output lets GCC make assumptions about the vector length when that's useful for optimization reasons 🧚 The possible values of bits are scalable, 128, 256, 512, 1024 and 2048. Specifying scalable selects vector-length agnostic output. At present, -msve-vector-bits=128 also generates vector-length agnostic output for big-endian targets. All other values generate vector-length specific code 🌈
⚠️ The behaviour of these values may change in future releases, and no value except scalable should be relied on for producing code that's portable across different hardware SVE vector lengths. Be careful out there, bestie 😭
The default is -msve-vector-bits=scalable, which produces vector-length agnostic code 🫶
✨ -march and -mcpu Feature Modifiers ✨
Feature modifiers used with -march and -mcpu can be any of the following, and each one also has an inverse, nofeature 🌷
crc— enables the CRC extension. This is on by default for-march=armv8.1-a🔥crypto— enables the Crypto extension. This also enables Advanced SIMD and floating-point instructions 🔐fp— enables floating-point instructions. This is on by default for all possible values for options-marchand-mcpu💜simd— enables Advanced SIMD instructions. This also enables floating-point instructions. This is on by default for all possible values for options-marchand-mcpu🦋sve— enables Scalable Vector Extension instructions. This also enables Advanced SIMD and floating-point instructions 🧜lse— enables Large System Extension instructions. This is on by default for-march=armv8.1-a🌸rdma— enables Round Double Multiply Accumulate instructions. This is on by default for-march=armv8.1-a✨
Okay bestie, the AArch64 feature list is giving main character energy 💅 Every +feature you can flip on, plus which ones come bundled 🌈
fp16— Turns on the FP16 extension ✨ and brings the floating-point instructions along for the ride 🔥fp16fml— Turns on the FP16fmlaextension 💖. It also switches on the FP16 extensions and floating-point instructions. It's on by default for-march=armv8.4-a. Using it with anything older than Armv8.2-A is not supported 🙈rcpc— Turns on the RCpc extension 🦋. That means theLDAPRinstructions get used for load-acquire atomic semantics, and it's passed along to the assembler so inline asm statements can use RCpc instructions toodotprod— Turns on the Dot Product extension 🎀. It also enables Advanced SIMD instructionsaes— Turns on the Armv8-aaesandpmullcrypto extension 🔐. Advanced SIMD instructions come with itsha2— Turns on the Armv8-asha2crypto extension 🌸. Advanced SIMD instructions come with it toosha3— Turns on thesha512andsha3crypto extension 🍓. Advanced SIMD instructions come along. Using it with architectures prior to Armv8.2-A is not supported 💀sm4— Turns on thesm3andsm4crypto extension 🧚. Advanced SIMD instructions come along. Using it with architectures prior to Armv8.2-A is not supported 💀profile— Turns on the Statistical Profiling extension 📊. This only enables it at the assembler level, so code generation stays the samerng— Turns on the Armv8.5-a Random Number instructions 🎲. Assembler level only, so code generation isn't affectedmemtag— Turns on the Armv8.5-a Memory Tagging Extensions 🏷️. Using it with architectures prior to Armv8.5-A is not supported 💀sb— Turns on the Armv8-a Speculation Barrier instruction 🚧. This only enables it at the assembler level and doesn't change code generation. It's on by default for-march=armv8.5-assbs— Turns on the Armv8-a Speculative Store Bypass Safe instruction 🛡️. Assembler level only, no change to code generation. It's on by default for-march=armv8.5-apredres— Turns on the Armv8-a Execution and Data Prediction Restriction instructions 🔒. Assembler level only, no change to code generation. It's on by default for-march=armv8.5-asve2— Turns on the Armv8-a Scalable Vector Extension 2 📐. It also enables SVE instructionssve2-bitperm— Turns on SVE2 bitperm instructions 🪄. It also enables SVE2 instructionssve2-sm4— Turns on SVE2 sm4 instructions 🌊. It also enables SVE2 instructionssve2-aes— Turns on SVE2 aes instructions 🔑. It also enables SVE2 instructionssve2-sha3— Turns on SVE2 sha3 instructions 🌙. It also enables SVE2 instructionstme— Turns on the Transactional Memory Extension 🧠i8mm— Turns on 8-bit Integer Matrix Multiply instructions 🧮. It also enables Advanced SIMD and floating-point instructions. It's on by default for-march=armv8.6-a. Using it with architectures prior to Armv8.2-A is not supported 💀f32mm— Turns on 32-bit Floating point Matrix Multiply instructions 📈. It also enables SVE instructions. Using it with architectures prior to Armv8.2-A is not supported 💀f64mm— Turns on 64-bit Floating point Matrix Multiply instructions 📉. It also enables SVE instructions. Using it with architectures prior to Armv8.2-A is not supported 💀bf16— Turns on brain half-precision floating-point instructions 🧠✨. It also enables Advanced SIMD and floating-point instructions. It's on by default for-march=armv8.6-a. Using it with architectures prior to Armv8.2-A is not supported 💀ls64— Turns on the 64-byte atomic load and store instructions for accelerators 🚀. It's on by default for-march=armv8.7-amops— Turns on the instructions that speed up memory operations like"memcpy","memmove", and"memset"🧹. It's on by default for-march=armv8.8-aflagm— Turns on the Flag Manipulation instructions Extension 🏳️pauth— Turns on the Pointer Authentication Extension 🔏cssc— Turns on the Common Short Sequence Compression instructions 🗜️sme— Turns on the Scalable Matrix Extension 🧊sme-i16i64— Turns on the FEAT_SME_I16I64 extension to SME 🔢sme-f64f64— Turns on the FEAT_SME_F64F64 extension to SME 🔣
Quick heads up: the source has a stray+@itemglitch stuck onto thesme-f64f64entry, sosme2gets its own bullet below 🙈
sme2— Turns on the Scalable Matrix Extension 2 🌟. It also enables SME instructionslse128— Turns on the LSE128 128-bit atomic instructions extension ⚛️. It also enables LSE instructionsd128— Turns on support for 128-bit system register read/write instructions 💿. It also enables the LSE128 extensiongcs— Turns on support for the Armv9.4-a Guarded Control Stack extension 🏰the— Turns on support for the Armv8.9-a/9.4-a translation hardening extension 🛠️rcpc3— Turns on the RCpc3 (Release Consistency) extension 🌺
Feature bundles are linked, so crypto implies aes, sha2, and simd, which implies fp. Going the other way, nofp implies nosimd, which implies nocrypto, noaes and nosha2 🔗
🧚 Adapteva Epiphany Options 🧚
These -m options are defined for Adapteva Epiphany 🦋
-mhalf-reg-file— Don't hand out any register in the range"r32"..."r63"🫶. That lets your code run on hardware variants that don't have those registers-mprefer-short-insn-regs— Gives priority to registers that allow short instruction generation ⚡. This can bump up the instruction count, so overall code size could go either way-mbranch-cost=num— Sets the cost of branches to roughlynum"simple" instructions 🌿. It's only a heuristic, so it isn't guaranteed to give consistent results across releases-mcmove— Turns on the generation of conditional moves 🎀-mnops=num— EmitsnumNOPs before every other generated instruction 😴-mno-soft-cmpsf— For single-precision floating-point comparisons, this emits anfsubinstruction and tests the flags 🏎️. It's faster than a software comparison, but it can give incorrect results in the presence of NaNs, or when two different small numbers are compared and their difference is calculated as zero. The default is-msoft-cmpsf, which uses slower but IEEE-compliant software comparisons 🐢-mstack-offset=num— Sets the offset between the top of the stack and the stack pointer 🥞. E.g., a value of8means the eight bytes in the range"sp+0...sp+7"can be used by leaf functions without stack allocation. Values other than8or16are untested and unlikely to work 💀
Heads up: this option changes the ABI! Compiling a program with a different stack offset than the libraries were built with generally does not work. It can help you check whether a different stack offset would give you better code, but if you want to actually build working programs with a different stack offset, it's recommended to configure the toolchain with the appropriate --with-stack-offset=num option.
-mno-round-nearest— Makes the scheduler assume the rounding mode has been set to truncating 🔄. The default is-mround-nearest-mlong-calls— Unless an attribute says otherwise, this assumes all calls might be beyond the offset range of the"b"/"bl"instructions 📞. So the function address gets loaded into a register before the (otherwise direct) call. This is the default-mshort-calls— Unless an attribute says otherwise, this assumes all direct calls are in the range of the"b"/"bl"instructions 📲, so those instructions get used for direct calls. The default is-mlong-calls-msmall16— Assumes addresses can be loaded as 16-bit unsigned values 🔢. This doesn't apply to function addresses where-mlong-callssemantics are in effect-mfp-mode=mode— Sets the prevailing mode of the floating-point unit 🧭. This decides which floating-point mode gets provided and expected at function call and return time. Matching this to the mode you mostly need at function start can make your programs smaller and faster by avoiding unnecessary mode switches ✨
mode can be set to one of the following values:
caller— Any mode at function entry is valid, and it gets retained or restored when the function returns and when it calls other functions 🫧. This is handy for compiling libraries or other compilation units you might want to link into programs with different prevailing FPU modes. The convenience of one single object file outweighs the size and speed overhead of any extra mode switching, compared with a more specific choice of prevailing FPU modetruncate— The mode used for floating-point calculations with truncating (i.e. round towards zero) rounding 🪵. That includes conversion from floating point to integerround-nearest— The mode used for floating-point calculations with round-to-nearest-or-even rounding 🎯int— The mode used to perform integer calculations in the FPU 🧮, e.g. integer multiply, or integer multiply-and-accumulate
The default is -mfp-mode=caller 💜
-mno-split-lohi,-mno-postinc,-mno-postmodify— Code generation tweaks that disable, respectively, splitting of 32-bit loads, generation of post-increment addresses, and generation of post-modify addresses 🛠️. The defaults aremsplit-lohi,-mpost-inc, and-mpost-modify-mnovect-double— Changes the preferred SIMD mode toSImode🌷. The default is-mvect-double, which usesDImodeas the preferred SIMD mode-max-vect-align=num— The maximum alignment for SIMD vector mode types 📏.nummay be4or8, and the default is8
Heads up: this is an ABI change! Many library function interfaces are unaffected, as long as they don't use SIMD vector modes in places that affect the size and/or alignment of relevant types.
-msplit-vecmove-early— Splits vector moves into single word moves before reload 🪄. In theory this can give better register allocation, but so far the reverse seems to be generally the case 🙃
✨ AMD GCN Options ✨
okay so these ones are made specifically for the AMD GCN port 💅🖥️
-m1reg-reg— okay bestie, this one lets you pick a register to hold the constant-1💖 which makes loading small negative constants and certain bitmasks faster ✨ The allowed values forregare:r43andr63— use that register as a fixed register 🎀none— no register gets used for this purpose 🫶- The default is
-m1reg-none🌸
-march=gpu,-mtune=gpu— set the architecture type or tuning forgpu👑 Supported values forgpuare:fiji— compile for GCN3 Fiji devices (gfx803) 🦋
Support is deprecated 😭 Whether it's available depends on how GCC was configured, so check--with-archand--with-multilib-list.
gfx900— compile for GCN5 Vega 10 devices (gfx900) ✨gfx906— compile for GCN5 Vega 20 devices (gfx906) 🔥gfx908— compile for CDNA1 Instinct MI100 series devices (gfx908) 💜gfx90a— compile for CDNA2 Instinct MI200 series devices (gfx90a) 🌈gfx1030— compile for RDNA2gfx1030devices (GFX10 series) 🧚gfx1036— compile for RDNA2gfx1036devices (GFX10 series) 🍓gfx1100— compile for RDNA3gfx1100devices (GFX11 series) ⭐gfx1103— compile for RDNA3gfx1103devices (GFX11 series) 🦋
-msram-ecc=on,-msram-ecc=off,-msram-ecc=any— compile binaries for devices with SRAM-ECC enabled, disabled, or either mode 🛡️ This feature can be turned on per-process on some devices, and the compiled code must match the device mode 💀 The default isany, for devices that support it.-mstack-size=bytes— specify how many bytes of stack space get requested for each GPU thread (wave-front) 🧵
Heads up, there can be a lot of threads and not much memory, so be careful 😭 The stack size can also affect run-time performance. The default is 32KB when using OpenACC or OpenMP, and 1MB otherwise.
-mxnack=on,-mxnack=off,-mxnack=any— compile binaries for devices with the XNACK feature enabled, disabled, or either mode 🌸 Some devices always need XNACK, and some let the user configure it. The compiled code must match the device mode. The default is-mxnack=anyon devices that support Unified Shared Memory, and-mxnack=nootherwise.
🌈 ARC Options 🌈
these options are all about controlling which architecture variant your ARC code gets compiled for 🎀 the following are the vibes:
-mbarrel-shifter— generate instructions supported by the barrel shifter ⚙️ This is the default unless-mcpu=ARC601or-mcpu=ARCEMis in effect.-mjli-always— force a function call to use thejli_sinstruction 🦋 This option is only valid for the ARCv2 architecture.-mcpu=cpu— set the architecture type, register usage, and instruction scheduling parameters forcpu👑 There are also shortcut alias options for backward compatibility and convenience. Supported values forcpuare:arc600— compile for ARC600. Aliases:-mA6,-mARC600🧚arc601— compile for ARC601. Alias:-mARC601🍓arc700— compile for ARC700. Aliases:-mA7,-mARC700⭐ This is the default when configured with--with-cpu=arc700.arcem— compile for ARC EM 💜archs— compile for ARC HS 🔥em— compile for ARC EM CPU with no hardware extensions 🌸em4— compile for ARC EM4 CPU ✨em4_dmips— compile for ARC EM4 DMIPS CPU 🦋em4_fpus— compile for ARC EM4 DMIPS CPU with the single-precision floating-point extension 🫶em4_fpuda— compile for ARC EM4 DMIPS CPU with single-precision floating-point and double assist instructions 💅hs— compile for ARC HS CPU with no hardware extensions except the atomic instructions 🎀hs34— compile for ARC HS34 CPU 🌈hs38— compile for ARC HS38 CPU 🍓hs38_linux— compile for ARC HS38 CPU with all hardware extensions on 🔥hs4x— compile for ARC HS4x CPU 👑hs4xd— compile for ARC HS4xD CPU 🧚hs4x_rel31— compile for ARC HS4x CPU release 3.10a ⭐arc600_norm— compile for ARC 600 CPU with"norm"instructions enabled 💖arc600_mul32x16— compile for ARC 600 CPU with"norm"and 32x16-bit multiply instructions enabled 💜arc600_mul64— compile for ARC 600 CPU with"norm"and"mul64"-family instructions enabled 🦋arc601_norm— compile for ARC 601 CPU with"norm"instructions enabled 🌸arc601_mul32x16— compile for ARC 601 CPU with"norm"and 32x16-bit multiply instructions enabled ✨arc601_mul64— compile for ARC 601 CPU with"norm"and"mul64"-family instructions enabled 🎀nps400— compile for ARC 700 on the NPS400 chip 🌈em_mini— compile for ARC EM minimalist configuration featuring a reduced register set 🧚
-mdpfp,-mdpfp-compact— generate double-precision FPX instructions, tuned for the compact implementation 💅-mdpfp-fast— generate double-precision FPX instructions, tuned for the fast implementation ⚡-mno-dpfp-lrsr— disable"lr"and"sr"instructions from using FPX extension aux registers 🙅♀️-mea— generate extended arithmetic instructions 🧮 Currently only"divaw","adds","subs", and"sat16"are supported. This is only valid for-mcpu=ARC700.-mno-mpy— do not generate"mpy"-family instructions for ARC700 💀
This option is deprecated, so maybe don't build your whole life around it 😭
-mmul32x16— generate 32x16-bit multiply and multiply-accumulate instructions ✖️-mmul64— generate"mul64"and"mulu64"instructions 🔢 This is only valid for-mcpu=ARC600.-mnorm— generate"norm"instructions 🎯 This is the default if-mcpu=ARC700is in effect.-mspfp,-mspfp-compact— generate single-precision FPX instructions, tuned for the compact implementation 🌸-mspfp-fast— generate single-precision FPX instructions, tuned for the fast implementation 🔥-msimd— enable generation of ARC SIMD instructions via target-specific builtins 🎀 This is only valid for-mcpu=ARC700.-msoft-float— this option gets ignored 🙈 It's only here for compatibility purposes. Software floating-point code is emitted by default, and that default can be overridden by the FPX options:-mspfp,-mspfp-compact, or-mspfp-fastfor single precision, and-mdpfp,-mdpfp-compact, or-mdpfp-fastfor double precision.-mswap— generate"swap"instructions 🔄-matomic— enables the use of the locked load/store conditional extension to implement atomic memory built-in functions 🔒 Not available for ARC 6xx or ARC EM cores.-mdiv-rem— enable"div"and"rem"instructions for ARCv2 cores ➗-mcode-density— enable code density instructions for ARC EM ✨ This option is on by default for ARC HS.-mll64— enable double load/store operations for ARC HS cores 📦-mtp-regno=regno— specify the thread pointer register number 🧵-mmpy-option=multo— compile ARCv2 code with a multiplier design option 🧮 You can specify the option using either a string or a numeric value formulto.wlh1is the default. The recognized values are:0ornone— no multiplier available 🙅♀️1orw— 16x16 multiplier, fully pipelined. The following instructions are enabled:"mpyw"and"mpyuw"🌸2orwlh1— 32x32 multiplier, fully pipelined (1 stage). The following instructions are additionally enabled:"mpy","mpyu","mpym","mpymu", and"mpy_s"💖3orwlh2— 32x32 multiplier, fully pipelined (2 stages). The following instructions are additionally enabled:"mpy","mpyu","mpym","mpymu", and"mpy_s"🦋4orwlh3— two 16x16 multipliers, blocking, sequential. The following instructions are additionally enabled:"mpy","mpyu","mpym","mpymu", and"mpy_s"🧚5orwlh4— one 16x16 multiplier, blocking, sequential. The following instructions are additionally enabled:"mpy","mpyu","mpym","mpymu", and"mpy_s"🍓6orwlh5— one 32x4 multiplier, blocking, sequential. The following instructions are additionally enabled:"mpy","mpyu","mpym","mpymu", and"mpy_s"⭐7orplus_dmpy— ARC HS SIMD support 👑8orplus_macd— ARC HS SIMD support 🔥9orplus_qmacw— ARC HS SIMD support 🌈
This option is only available for ARCv2 cores 🫶
-mfpu=fpu— enables support for specific floating-point hardware extensions for ARCv2 cores 🧮 Supported values forfpuare:fpus— enables support for single-precision floating-point hardware extensions ✨fpud— enables support for double-precision floating-point hardware extensions. The single-precision floating-point extension is also enabled. Not available for ARC EM 💜fpuda— enables support for double-precision floating-point hardware extensions using double-precision assist instructions. The single-precision floating-point extension is also enabled. This option is only available for ARC EM 🦋fpuda_div— enables support for double-precision floating-point hardware extensions using double-precision assist instructions. The single-precision floating-point, square-root, and divide extensions are also enabled. This option is only available for ARC EM 🌸fpuda_fma— enables support for double-precision floating-point hardware extensions using double-precision assist instructions. The single-precision floating-point and fused multiply and add hardware extensions are also enabled. This option is only available for ARC EM 🧚fpuda_all— enables support for double-precision floating-point hardware extensions using double-precision assist instructions. All single-precision floating-point hardware extensions are also enabled. This option is only available for ARC EM 🔥fpus_div— enables support for single-precision floating-point, square-root, and divide hardware extensions 🎀
fpud_div💅 is the double-precision bundle: double-precision floating-point plus the square-root and divide hardware extensions. It also includesfpus_div. Not available for ARC EM 💀fpus_fma✨ gives you single-precision floating-point and the fused multiply and add hardware extensions. Lowkey the cutest combo 🦋fpud_fma🔥 gives you double-precision floating-point and the fused multiply and add hardware extensions. This one includesfpus_fma. Not available for ARC EM.fpus_all🌸 turns on all the single-precision floating-point hardware extensions. Every single one, no skipping.fpud_all👑 is the whole buffet: all the single- and double-precision floating-point hardware extensions. Not available for ARC EM 😭-mirq-ctrl-saved=register-range, blink, lp_count🧚 tells the compiler which general-purpose registers the processor automatically saves and restores on interrupt entry and exit. The register-range is two registers joined by a dash. It always starts atr0, and the upper limit is thefpregister.blinkandlp_countare optional. Only valid for ARC EM and ARC HS cores.-mrgf-banked-regs=number⚡ sets how many registers get replicated into the second register bank when a fast interrupt fires. Fast interrupts are the highest-priority P0 ones, and they only save thePCandSTATUS32registers so they can skip memory transactions during entry and exit. Use this when you're running fast interrupts on an ARC V2 family processor. Permitted values are4,8,16, and32.-mlpc-width=width🎀 sets the width of thelp_countregister. Valid widths are8,16,20,24,28, and32bits. The default is fixed at 32 bits. If the width is less than 32, the compiler won't transform your loops into the zero-delay loop mechanism unless it knowslp_countcan actually hold the loop-counter value. Depending on the width, the compiler and run-time library might still use the loop mechanism for various needs. This option defines the__ARC_LPC_WIDTH__macro with the value of width.-mrf16💜 tells the compiler to generate code for a 16-entry register file. It defines the__ARC_RF16__preprocessor macro.-mbranch-index🍓 enables use ofbiorbihinstructions to implement jump tables.
Next up, these ones get passed along to the assembler and set preprocessor macro symbols 🫶
-mdsp-packa🌈 gets passed down to the assembler to enable the DSP Pack A extensions. It also sets the__Xdsp_packapreprocessor symbol. Deprecated. 💀-mdvbfgets passed down to the assembler to enable the dual Viterbi butterfly extension. It also sets__Xdvbf. Deprecated.-mlockgets passed down to the assembler to enable the locked load/store conditional extension. It also sets__Xlock.-mmac-d16gets passed down to the assembler and sets__Xxmac_d16. Deprecated.-mmac-24gets passed down to the assembler and sets__Xxmac_24. Deprecated.-mrtscgets passed down to the assembler to enable the 64-bit time-stamp counter extension instruction. It also sets__Xrtsc. Deprecated.-mswapegets passed down to the assembler to enable the swap byte ordering extension instruction. It also sets__Xswape.-mtelephonygets passed down to the assembler to enable dual- and single-operand instructions for telephony. It also sets__Xtelephony. Deprecated.-mxygets passed down to the assembler to enable the XY memory extension. It also sets__Xxy.
These next ones control how the assembly code gets annotated 📝
-misizeannotates assembler instructions with estimated addresses.-mannotate-aligndoes nothing. It's only hanging around for backward compatibility 🙈
These ones get passed through to the linker 🔗
-marclinuxgets passed through to the linker to specify use of thearclinuxemulation. It's enabled by default in toolchains built forarc-linux-uclibcandarceb-linux-uclibctargets when profiling is not requested.-marclinux_profgets passed through to the linker to specify use of thearclinux_profemulation. It's enabled by default in those same toolchains when profiling is requested.
Now the options that control the semantics of the generated code 🧠
-mlong-callsgenerates calls as register indirect calls, which gives you access to the full 32-bit address range.-mmedium-callsmeans don't use less than a 25-bit addressing range for calls, which is the offset available for an unconditional branch-and-link instruction. Conditional execution of function calls gets suppressed so you can use that 25-bit range instead of the 21-bit range you'd get with conditional branch-and-link. This is the default for toolchains built forarc-linux-uclibcandarceb-linux-uclibctargets.-G numputs definitions of externally-visible data in a small data section if that data is no bigger thannumbytes. The default value ofnumis 4 for any ARC configuration, or 8 when there are double load/store operations.-mno-sdatameans no sdata references. This is the default for toolchains built forarc-linux-uclibcandarceb-linux-uclibctargets.-mvolatile-cacheuses ordinarily cached memory accesses for volatile references. This is the default 💖-mno-volatile-cacheenables cache bypass for volatile references.
These fine-tune code generation 🎀
-malign-calldoes nothing. Preserved for backward compatibility.-mauto-modify-regenables the use of pre/post modify with register displacement.-mbbit-peepholedoes nothing. Preserved for backward compatibility.-mno-brccdisables a target-specific pass inarc_reorgthat generates compare-and-branch (brcc) instructions. It has no effect on the generation of these instructions when they're driven by the combiner pass.-mcase-vector-pcreluses PC-relative switch case tables to enable case table shortening. This is the default for-Os.-mcompact-casesienables the compactcasesipattern. This is the default for-Os, and it's only available for ARCv1 cores. Deprecated.-mno-cond-execdisables the ARCompact-specific pass that generates conditional execution instructions.
Okay, the tea ☕ is that delay slot scheduling and the interactions between operand numbers, literal sizes, instruction lengths, and conditional execution support mean the target-independent pass for conditional execution is often lacking. So the ARC port keeps a special pass around that tries to find more conditional execution opportunities after register allocation, branch shortening, and delay slot scheduling have been done. This pass generally, but not always, improves performance and code size, at the cost of extra compilation time, which is why there's an option to switch it off. If you have a problem with call instructions exceeding their allowable offset range because they've been conditionalized, you should consider using -mmedium-calls instead 🫠
-mearly-cbranchsienables pre-reload use of thecbranchsipattern.-mexpand-adddiexpandsadddi3andsubdi3at RTL generation time intoadd.f,adcetc. Deprecated.-mindexed-loadsenables the use of indexed loads. This can be problematic because some optimizers then assume that indexed stores exist, which is not the case ❌-mlraenables Local Register Allocation. It's still experimental for ARC, so by default the compiler uses standard reload (i.e.-mno-lra) 🧪-mlra-priority-nonedoesn't indicate any priority for target registers.-mlra-priority-compactindicates target register priority forr0..r3/r12..r15.-mlra-priority-noncompactreduces target register priority forr0..r3/r12..r15.-mmillicode🌙 when you're optimizing for size (using-Os), prologues and epilogues that have to save or restore a large number of registers are often shortened by calling a special function in libgcc. This is called a millicode call. Since these calls can pose performance issues, and/or cause linking issues when linking in a nonstandard way, this option lets you turn millicode call generation on or off.-mcode-density-frameenables the compiler to emitenterandleaveinstructions. These are only valid for CPUs with the code-density feature.-mmixed-codedoes nothing. Preserved for backward compatibility.-mq-classis deprecated. It enables q instruction alternatives. This is the default for-Os.-mRcqdoes nothing. Preserved for backward compatibility.-mRcwdoes nothing. Preserved for backward compatibility.-msize-level=levelfine-tunes size optimization with regards to instruction lengths and alignment. The recognized values forlevelare:0means no size optimization. This level is deprecated and treated like1.1means short instructions are used opportunistically.2means that, in addition, alignment of loops and of code after barriers is dropped.3means that, in addition, optional data alignment is dropped, and the optionOsis enabled.
This defaults to 3 when -Os is in effect. Otherwise, the behavior when this is not set is equivalent to level 1 ✨
-mtune=cpusets instruction scheduling parameters for cpu, overriding any that are implied by-mcpu=.
Supported values for cpu are:
ARC600tunes for the ARC600 CPU.ARC601tunes for the ARC601 CPU.ARC700tunes for the ARC700 CPU with the standard multiplier block.ARC700-xmactunes for the ARC700 CPU with the XMAC block.ARC725Dtunes for the ARC725D CPU 👑
ARC750D— ok this one's for the ARC750D CPU 💅 tuning just for it, no cap ✨core3— tunes for the ARCv2 core3 type CPU 🦋 and this one unlocks thedbnzinstruction, so it's giving main character energy 👑release31a— tunes for ARC4x release 3.10a 🌸-mmultcost=num— sets the cost GCC assumes for a multiply instruction 🧮 where4means it's the same cost as a normal instruction 💖-munalign-prob-threshold=probability— literally does nothing 🙈 it's just kept around so older code doesn't cry 😭
The following options are still around for backward compatibility, but they're deprecated now, so bestie don't build new stuff with them 💀
These options will be removed in a future release, so start switching now before they vanish! 🫶
-margonaut— obsolete FPX, retired and gone 🧚-mbig-endian,-EB— compiles code for big-endian targets 🌈 but using these is deprecated now. Big-endian is supported by configuring GCC to build thearceb-elf32andarceb-linux-uclibctargets instead, and big endian is the default for those 💜-mlittle-endian,-EL— compiles code for little-endian targets 🍓 also deprecated. Little-endian is supported by configuring GCC to build thearc-elf32andarc-linux-uclibctargets, where little endian is the default ✨-mbarrel_shifter— replaced by-mbarrel-shifter🔥-mdpfp_compact— replaced by-mdpfp-compact💅-mdpfp_fast— replaced by-mdpfp-fast🎀-mdsp_packa— replaced by-mdsp-packa🦋-mEA— replaced by-mea🌸-mmac_24— replaced by-mmac-24💖-mmac_d16— replaced by-mmac-d16⭐-mspfp_compact— replaced by-mspfp-compact🧚-mspfp_fast— replaced by-mspfp-fast🫶-mtune=cpu— the valuesarc600,arc601,arc700andarc700-xmacgot replaced byARC600,ARC601,ARC700andARC700-xmacrespectively 👑-multcost=num— replaced by-mmultcost🌈
✨ ARM Options ✨
These -m options are defined for the ARM port 🦋 so if you're on ARM, these are your lowkey best friends 💜
-mabi=name— generates code for the ABI you pick 🎀. The permissible values areapcs-gnu,atpcs,aapcs,aapcs-linuxandiwmmxt💅-mapcs-frame— makes a stack frame that follows the ARM Procedure Call Standard for all functions 🫶, even when it's not strictly needed for the code to run right. If you pair this with-fomit-frame-pointer, stack frames won't get generated for leaf functions 🌸. The default is-mno-apcs-frame, and this option is deprecated 💀-mapcs— just a synonym for-mapcs-frame🧚 and it's deprecated too 😭-mthumb-interwork— generates code that can call between the ARM and Thumb instruction sets 🌈. Without it, on pre-v5 architectures, the two sets can't be reliably used inside one program 🙈. The default is-mno-thumb-interwork, because-mthumb-interworkmakes slightly larger code 🍓. In AAPCS configurations this option is meaningless 💀-mno-sched-prolog— stops GCC from reordering instructions in the function prologue, or merging them with the instructions in the function's body 🔥. So every function starts with a recognizable set of instructions (or one from a small set of prologues), and you can use that to find where functions start inside an executable 👑. The default is-msched-prolog✨-mfloat-abi=name— picks which floating-point ABI to use 💖. The values aresoft,softfpandhard🦋.softmakes GCC emit library calls for floating-point operations 🧮softfplets you use hardware floating-point instructions but still uses the soft-float calling conventions 🌸hardgives you floating-point instructions and FPU-specific calling conventions 🔥
The default depends on the specific target configuration 💅. Heads up: the hard-float and soft-float ABIs are not link-compatible, so you have to compile your entire program with the same ABI and link with a compatible set of libraries 🙈
-mgeneral-regs-only— generates code that only uses the general-purpose registers 🎀. This stops the compiler from using floating-point and Advanced SIMD registers, but it doesn't put any restrictions on the assembler 🫶-mlittle-endian— generates code for a processor running in little-endian mode 🍓. This is the default for all standard configurations 💜-mbig-endian— generates code for a processor running in big-endian mode 🌈. The default is to compile for a little-endian processor 💖-mbe8,-mbe32— when linking a big-endian image, these pick between the BE8 and BE32 formats 🧚. They have no effect on little-endian images and get ignored there 🙈. The default depends on the target architecture: ARMv6 and later default to BE8, and older architectures default to BE32 ⭐. BE32 has been deprecated by ARM 💀-march=name[+extension...]— specifies the name of the target ARM architecture 👑. GCC uses this name to figure out what kinds of instructions it can emit when generating assembly code ✨. You can use it together with-mcpu=, or instead of it 🦋.
The permissible names are armv4t, armv5t, armv5te, armv6, armv6j, armv6k, armv6kz, armv6t2, armv6z, armv6zk, armv7, armv7-a, armv7ve, armv8-a, armv8.1-a, armv8.2-a, armv8.3-a, armv8.4-a, armv8.5-a, armv8.6-a, armv9-a, armv7-r, armv8-r, armv6-m, armv6s-m, armv7-m, armv7e-m, armv8-m.base, armv8-m.main, armv8.1-m.main, armv9-a, iwmmxt and iwmmxt2 💅
Also, armv4 is recognized but its support is deprecated 💀. It's one of the architectures that doesn't support the Thumb execution state 🙈.
Lots of these architectures support extensions 🌈. You add one by appending +extension to the architecture name 💜. Extension options get processed in order and their capabilities stack up 🧮. An extension also turns on any base extensions it needs 🫶. For example, +crypto will always enable +simd 🔥. The exception to all that stacking is the extensions prefixed with +no...: those turn off the option and any other extensions that depend on it 😭.
For example, -march=armv7-a+simd+nofp+vfpv4 is the same as writing -march=armv7-a+vfpv4, because the +simd option gets totally disabled by the +nofp that comes after it 🙈.
Most extension names are generic, but what they do depends on the architecture they're applied to 🦋. For example, +simd works on both armv7-a and armv8-a, but it turns on the original ARMv7-A Advanced SIMD (Neon) extensions for armv7-a, and the ARMv8-A variant for armv8-a 🎀.
The table below lists the supported extensions for each architecture 🧚. Architectures that aren't mentioned don't support any extensions 💖.
✨ armv5te, armv6, armv6j, armv6k, armv6kz, armv6t2, armv6z, armv6zk 🌸
+fp— the VFPv2 floating-point instructions 🧮. The extension+vfpv2can be used as an alias for this one 💜+nofp— disables the floating-point instructions 🙅
✨ armv7 🔥
This is the common subset of the ARMv7-A, ARMv7-R and ARMv7-M architectures 👑.
+fp— the VFPv3 floating-point instructions, with 16 double-precision registers 🦋. The extension+vfpv3-d16can be used as an alias for this one 🌈. Heads up: floating-point isn't supported by the base ARMv7-M architecture, but it's compatible with both ARMv7-A and ARMv7-R 💀+nofp— disables the floating-point instructions 🙅
✨ armv7-a 💜
+mp— the multiprocessing extension 🫶+sec— the security extension 🔐+fp— the VFPv3 floating-point instructions, with 16 double-precision registers 🍓. The extension+vfpv3-d16can be used as an alias for this one 💅+simd— the Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions 🎀. The extensions+neonand+neon-vfpv3can be used as aliases for this one ✨+vfpv3— the VFPv3 floating-point instructions, with 32 double-precision registers 🧚+vfpv3-d16-fp16— the VFPv3 floating-point instructions, with 16 double-precision registers and the half-precision floating-point conversion operations 🌸+vfpv3-fp16— the VFPv3 floating-point instructions, with 32 double-precision registers and the half-precision floating-point conversion operations 💖+vfpv4-d16— the VFPv4 floating-point instructions, with 16 double-precision registers 🦋+vfpv4— the VFPv4 floating-point instructions, with 32 double-precision registers 👑+neon-fp16— the Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions, with the half-precision floating-point conversion operations 🔥+neon-vfpv4— the Advanced SIMD (Neon) v2 and the VFPv4 floating-point instructions 🌈+nosimd— disables the Advanced SIMD instructions (it doesn't disable floating point) 🙈+nofp— disables the floating-point and Advanced SIMD instructions 😭
✨ armv7ve 🌈
This is the extended version of the ARMv7-A architecture, with support for virtualization 🧚.
+fp— the VFPv4 floating-point instructions, with 16 double-precision registers 🫶. The extension+vfpv4-d16can be used as an alias for this one 💜+simd— the Advanced SIMD (Neon) v2 and the VFPv4 floating-point instructions 🎀. The extension+neon-vfpv4can be used as an alias for this one 💅+vfpv3-d16— the VFPv3 floating-point instructions, with 16 double-precision registers 🌸+vfpv3— the VFPv3 floating-point instructions, with 32 double-precision registers 🍓+vfpv3-d16-fp16— the VFPv3 floating-point instructions, with 16 double-precision registers and the half-precision floating-point conversion operations ✨+vfpv3-fp16— okay so this one gets you the VFPv3 floating-point instructions with 32 double-precision registers, plus the half-precision floating-point conversion operations 💖✨+vfpv4-d16— the VFPv4 floating-point instructions, but with 16 double-precision registers 🎀+vfpv4— the VFPv4 floating-point instructions with 32 double-precision registers, so it's the full-fat version 🦋+neon— the Advanced SIMD (Neon) v1 along with the VFPv3 floating-point instructions. You can also write+neon-vfpv3and it's the same thing, an alias 🌈+neon-fp16— the Advanced SIMD (Neon) v1 and VFPv3 floating-point instructions, plus the half-precision floating-point conversion operations 🔥+nosimd— disables the Advanced SIMD instructions. Floating point is still on though, so don't panic 🙈+nofp— disables the floating-point and Advanced SIMD instructions 💀
🌸 armv8-a
+crc— the Cyclic Redundancy Check (CRC) instructions 🧚+simd— the ARMv8-A Advanced SIMD and floating-point instructions 💜+crypto— the cryptographic instructions 🔐+nocrypto— disables the cryptographic instructions 🙅♀️+nofp— disables the floating-point, Advanced SIMD and cryptographic instructions. Big yikes energy 😭+sb— the Speculation Barrier Instruction 🛡️+predres— the Execution and Data Prediction Restriction Instructions 🫶
🌸 armv8.1-a
+simd— the ARMv8.1-A Advanced SIMD and floating-point instructions 💅+crypto— the cryptographic instructions. This one also turns on the Advanced SIMD and floating-point instructions, so it's giving bundle deal 🎁+nocrypto— disables the cryptographic instructions 🙅♀️+nofp— disables the floating-point, Advanced SIMD and cryptographic instructions 😭+sb— the Speculation Barrier Instruction 🛡️+predres— the Execution and Data Prediction Restriction Instructions 🫶
🌸 armv8.2-a and armv8.3-a
+fp16— the half-precision floating-point data processing instructions. This also enables the Advanced SIMD and floating-point instructions 🍓+fp16fml— the half-precision floating-pointfmlaextension. This also enables the half-precision floating-point extension and the Advanced SIMD and floating-point instructions, so it's a whole vibe 🌟+simd— the ARMv8.1-A Advanced SIMD and floating-point instructions 💅+crypto— the cryptographic instructions. This also enables the Advanced SIMD and floating-point instructions 🔐+dotprod— enables the Dot Product extension. This also enables Advanced SIMD instructions ✨+nocrypto— disables the cryptographic extension 🙅♀️+nofp— disables the floating-point, Advanced SIMD and cryptographic instructions 😭+sb— the Speculation Barrier Instruction 🛡️+predres— the Execution and Data Prediction Restriction Instructions 🫶+i8mm— the 8-bit Integer Matrix Multiply instructions. This also enables Advanced SIMD and floating-point instructions 🧮+bf16— the Brain half-precision floating-point instructions. This also enables Advanced SIMD and floating-point instructions 🧠
🌸 armv8.4-a
+fp16— the half-precision floating-point data processing instructions. This also enables the Advanced SIMD and floating-point instructions, plus the Dot Product extension and the half-precision floating-pointfmlaextension. Triple threat 👑+simd— the ARMv8.3-A Advanced SIMD and floating-point instructions, plus the Dot Product extension 💜+crypto— the cryptographic instructions. This also enables the Advanced SIMD and floating-point instructions, plus the Dot Product extension 🔐+nocrypto— disables the cryptographic extension 🙅♀️+nofp— disables the floating-point, Advanced SIMD and cryptographic instructions 😭+sb— the Speculation Barrier Instruction 🛡️+predres— the Execution and Data Prediction Restriction Instructions 🫶+i8mm— the 8-bit Integer Matrix Multiply instructions. This also enables Advanced SIMD and floating-point instructions 🧮+bf16— the Brain half-precision floating-point instructions. This also enables Advanced SIMD and floating-point instructions 🧠
🌸 armv8.5-a
+fp16— the half-precision floating-point data processing instructions. This also enables the Advanced SIMD and floating-point instructions, plus the Dot Product extension and the half-precision floating-pointfmlaextension 🍓+simd— the ARMv8.3-A Advanced SIMD and floating-point instructions, plus the Dot Product extension 💜+crypto— the cryptographic instructions. This also enables the Advanced SIMD and floating-point instructions, plus the Dot Product extension 🔐+nocrypto— disables the cryptographic extension 🙅♀️+nofp— disables the floating-point, Advanced SIMD and cryptographic instructions 😭+i8mm— the 8-bit Integer Matrix Multiply instructions. This also enables Advanced SIMD and floating-point instructions 🧮+bf16— the Brain half-precision floating-point instructions. This also enables Advanced SIMD and floating-point instructions 🧠
🌸 armv8.6-a
+fp16— the half-precision floating-point data processing instructions. This also enables the Advanced SIMD and floating-point instructions, plus the Dot Product extension and the half-precision floating-pointfmlaextension 🍓+simd— the ARMv8.3-A Advanced SIMD and floating-point instructions, plus the Dot Product extension 💜+crypto— the cryptographic instructions. This also enables the Advanced SIMD and floating-point instructions, plus the Dot Product extension 🔐+nocrypto— disables the cryptographic extension 🙅♀️+nofp— disables the floating-point, Advanced SIMD and cryptographic instructions 😭+i8mm— the 8-bit Integer Matrix Multiply instructions. This also enables Advanced SIMD and floating-point instructions 🧮+bf16— the Brain half-precision floating-point instructions. This also enables Advanced SIMD and floating-point instructions 🧠
🌸 armv7-r
+fp.sp— the single-precision VFPv3 floating-point instructions. The extension+vfpv3xdcan be used as an alias for this extension 🦋+fp— the VFPv3 floating-point instructions with 16 double-precision registers. The extension+vfpv3-d16can be used as an alias for this extension 🎀+vfpv3xd-d16-fp16— the single-precision VFPv3 floating-point instructions with 16 double-precision registers and the half-precision floating-point conversion operations 🍓+vfpv3-d16-fp16— the VFPv3 floating-point instructions with 16 double-precision registers and the half-precision floating-point conversion operations 🌸+nofp— disables the floating-point extension 🙅♀️+idiv— the ARM-state integer division instructions ➗+noidiv— disables the ARM-state integer division extension 🚫
🌸 armv7e-m
+fp— the single-precision VFPv4 floating-point instructions 🌟+fpv5— the single-precision FPv5 floating-point instructions ⭐+fp.dp— the single- and double-precision FPv5 floating-point instructions 👑+nofp— disables the floating-point extensions 🙅♀️
🌸 armv8.1-m.main
+dsp— the DSP instructions 🎶+mve— the M-Profile Vector Extension (MVE) integer instructions 🧚+mve.fp— the M-Profile Vector Extension (MVE) integer and single-precision floating-point instructions 💖+fp— the single-precision floating-point instructions ✨+fp.dp— the single- and double-precision floating-point instructions 👑+nofp— disables the floating-point extension 🙅♀️+cdecp0,+cdecp1, ... ,+cdecp7— enables the Custom Datapath Extension (CDE) on selected coprocessors, according to the numbers given in the options in the range 0 to 7 🧩+pacbti— enables the Pointer Authentication and Branch Target Identification Extension 🔒
🌸 armv8-m.main
+dsp— the DSP instructions 🎶+nodsp— disables the DSP extension 🙅♀️+fp— the single-precision floating-point instructions ✨+fp.dp— the single- and double-precision floating-point instructions 👑+nofp— disables the floating-point extension 🙅♀️+cdecp0,+cdecp1, ... ,+cdecp7— enables the Custom Datapath Extension (CDE) on selected coprocessors, according to the numbers given in the options in the range 0 to 7 🧩
🌸 armv8-r
+crc— the Cyclic Redundancy Check (CRC) instructions 🧚+fp.sp— the single-precision FPv5 floating-point instructions 🦋+simd— the ARMv8-A Advanced SIMD and floating-point instructions 💜+crypto— the cryptographic instructions 🔐+nocrypto— disables the cryptographic instructions 🙅♀️+nofp— disables the floating-point, Advanced SIMD and cryptographic instructions 😭
Okay bestie, -march=native is giving auto-detect 🔍. It tells the compiler to figure out the architecture of the build computer all by itself. ngl, this only works on GNU/Linux right now, and not every architecture gets recognized 💀. If the auto-detect doesn't work out, the option just has no effect 🫶.
🎀 -mtune=name
This is how you tell GCC which target ARM processor to tune your code's performance for ✨ For some ARM implementations you can get better performance with this option 🦋. The permissible names are arm7tdmi, arm7tdmi-s, arm710t, arm720t, arm740t, strongarm, strongarm110, strongarm1100, strongarm1110, arm8, arm810, arm9, arm9e, arm920, arm920t, arm922t, arm946e-s, arm966e-s, arm968e-s, arm926ej-s, arm940t, arm9tdmi, arm10tdmi, arm1020t, arm1026ej-s, arm10e, arm1020e, arm1022e, arm1136j-s, arm1136jf-s, mpcore, mpcorenovfp, arm1156t2-s, arm1156t2f-s, arm1176jz-s, arm1176jzf-s, generic-armv7-a, cortex-a5, cortex-a7, cortex-a8, cortex-a9, cortex-a12, cortex-a15, cortex-a17, cortex-a32, cortex-a35, cortex-a53, cortex-a55, cortex-a57, cortex-a72, cortex-a73, cortex-a75, cortex-a76, cortex-a76ae, cortex-a77, cortex-a78, cortex-a78ae, cortex-a78c, cortex-a710, ares, cortex-r4, cortex-r4f, cortex-r5, cortex-r7, cortex-r8, cortex-r52, cortex-r52plus, cortex-m0, cortex-m0plus, cortex-m1, cortex-m3, cortex-m4, cortex-m7, cortex-m23, cortex-m33, cortex-m35p, cortex-m52, cortex-m55, cortex-m85, cortex-x1, cortex-x1c, cortex-m1.small-multiply, cortex-m0.small-multiply, cortex-m0plus.small-multiply, exynos-m1, marvell-pj4, neoverse-n1, neoverse-n2, neoverse-v1, xscale, iwmmxt, iwmmxt2, ep9312, fa526, fa626, fa606te, fa626te, fmp626, fa726te, star-mc1, xgene1.
Okay, and this option can also say "tune this for a big.LITTLE system" 🧚 The permissible names for that are cortex-a15.cortex-a7, cortex-a17.cortex-a7, cortex-a57.cortex-a53, cortex-a72.cortex-a53, cortex-a72.cortex-a35, cortex-a73.cortex-a53, cortex-a75.cortex-a55, cortex-a76.cortex-a55.
-mtune=generic-arch is the move if you want code that runs well on the current most popular processors 💅 It's a blend across the processors within arch, balancing optimizations that help some CPUs in the range while avoiding performance pitfalls on others. Just know the effects may change in future GCC versions as CPU models come and go 🌸
-mtune takes the same extension options as -mcpu, but those extensions don't change the tuning of the generated code 💜
-mtune=native auto-detects the CPU of the build computer 👑 Same deal as before: GNU/Linux only, not all architectures are recognized, and if the auto-detect fails, the option has no effect 🙈
🌸 -mcpu=name[+extension...]
This one specifies the target ARM processor. GCC uses that name to work out the target ARM architecture (as if you'd passed -march) and the ARM processor type to tune for (as if you'd passed -mtune). If you use this alongside -march or -mtune, those two win for their part of the job 👑
Lots of the supported CPUs have optional architectural extensions, and those are normally enabled by default 🧚 If implementations that lack the extension exist, you can use the extension syntax to switch off the ones that got left out. For floating-point and Advanced SIMD (Neon) instructions, keep -mfloat-abi and -mfpu in mind too: floating-point and Advanced SIMD instructions are only used if -mfloat-abi isn't set to soft, and any -mfpu setting other than auto overrides the available floating-point and SIMD extension instructions 🔥
For example, cortex-a9 comes in three major configs: integer only, with just a floating-point unit, or with floating-point and Advanced SIMD. The default is to enable all of the instructions, but +nosimd and +nofp can disable just the SIMD, or both the SIMD and floating-point instructions, respectively 💖
Permissible names for this option are the same as for -mtune.
The following extension options are common to the listed CPUs:
+nodsp— Disables the DSP instructions oncortex-m33,cortex-m35p,cortex-m52,cortex-m55andcortex-m85. It also disables the M-Profile Vector Extension (MVE) integer and single precision floating-point instructions oncortex-m52,cortex-m55andcortex-m85🎀+nopacbti— Disables the Pointer Authentication and Branch Target Identification Extension oncortex-m52andcortex-m85🦋+nomve— Disables the M-Profile Vector Extension (MVE) integer and single precision floating-point instructions oncortex-m52,cortex-m55andcortex-m85🌈+nomve.fp— Disables the M-Profile Vector Extension (MVE) single precision floating-point instructions oncortex-m52,cortex-m55andcortex-m85✨+cdecp0,+cdecp1, ... ,+cdecp7— Enables the Custom Datapath Extension (CDE) on selected coprocessors, picked by the numbers in the options from 0 to 7, oncortex-m52andcortex-m55🧚+nofp— Disables the floating-point instructions onarm9e,arm946e-s,arm966e-s,arm968e-s,arm10e,arm1020e,arm1022e,arm926ej-s,arm1026ej-s,cortex-r5,cortex-r7,cortex-r8,cortex-m4,cortex-m7,cortex-m33,cortex-m35p,cortex-m52,cortex-m55andcortex-m85. Ongeneric-armv7-a,cortex-a5,cortex-a7,cortex-a8,cortex-a9,cortex-a12,cortex-a15,cortex-a17,cortex-a15.cortex-a7,cortex-a17.cortex-a7,cortex-a32,cortex-a35,cortex-a53andcortex-a55, it disables the floating-point and SIMD instructions instead 💅+nofp.dp— Disables the double-precision component of the floating-point instructions oncortex-r5,cortex-r7,cortex-r8,cortex-r52,cortex-r52plusandcortex-m7🌸+nosimd— Disables the SIMD (but not floating-point) instructions ongeneric-armv7-a,cortex-a5,cortex-a7andcortex-a9💜+crypto— Enables the cryptographic instructions oncortex-a32,cortex-a35,cortex-a53,cortex-a55,cortex-a57,cortex-a72,cortex-a73,cortex-a75,exynos-m1,xgene1,cortex-a57.cortex-a53,cortex-a72.cortex-a53,cortex-a73.cortex-a35,cortex-a73.cortex-a53andcortex-a75.cortex-a55🔐
Also, the generic-armv7-a pseudo target defaults to VFPv3 with 16 double-precision registers 🦋 It supports these extension options: mp, sec, vfpv3-d16, vfpv3, vfpv3-d16-fp16, vfpv3-fp16, vfpv4-d16, vfpv4, neon, neon-vfpv3, neon-fp16, neon-vfpv4. The meanings are the same as for the extensions to -march=armv7-a.
-mcpu=generic-arch is also allowed, and it's equivalent to -march=arch -mtune=generic-arch. Check out -mtune for more info ✨
-mcpu=native auto-detects the CPU of the build computer 👑 Again, GNU/Linux only, not every architecture is recognized, and if the auto-detect is unsuccessful the option has no effect 🙈
🔥 -mfpu=name
This specifies what floating-point hardware (or hardware emulation) is available on the target. The permissible names are auto, vfpv2, vfpv3, vfpv3-fp16, vfpv3-d16, vfpv3-d16-fp16, vfpv3xd, vfpv3xd-fp16, neon-vfpv3, neon-fp16, vfpv4, vfpv4-d16, fpv4-sp-d16, neon-vfpv4, fpv5-d16, fpv5-sp-d16, fp-armv8, neon-fp-armv8 and crypto-neon-fp-armv8. Heads up: neon is an alias for neon-vfpv3, and vfp is an alias for vfpv2 💖
auto is the default and it's a special one 🧚 It makes the compiler pick the floating-point and Advanced SIMD instructions based on the settings of -mcpu and -march.
⚠️ If the selected floating-point hardware includes the NEON extension (e.g.-mfpu=neon), GCC's auto-vectorization pass won't generate floating-point operations unless-funsafe-math-optimizationsis also specified. That's because NEON hardware doesn't fully implement the IEEE 754 standard for floating-point arithmetic (denormal values get treated as zero, in particular), so using NEON instructions may lead to a loss of precision 💀
You can also set the fpu name at function level using the target("fpu=") function attributes or pragmas 🌈
🦋 -mfp16-format=name
This specifies the format of the "__fp16" half-precision floating-point type ✨ The permissible names are none, ieee and alternative. The default is none, which means the "__fp16" type is not defined at all 🙈
🧚 -mstructure-size-boundary=n
The sizes of all structures and unions get rounded up to a multiple of the number of bits set by this option 🍓 The permissible values are 8, 32 and 64. The default varies between toolchains. For the COFF targeted toolchain, the default is 8. A value of 64 is only allowed if the underlying ABI supports it.
Going bigger can produce faster, more efficient code, but it can also increase the size of the program 💅 Different values are potentially incompatible, too. Code compiled with one value can't necessarily work with code or libraries compiled with another value, if they swap information using structures or unions 😭
💀 This option is deprecated, so maybe don't build new stuff around it.
🌈 -mabort-on-noreturn
This generates a call to the function "abort" at the end of a "noreturn" function 🔥 It gets executed if the function tries to return.
👑 -mlong-calls and -mno-long-calls
These tell the compiler to make function calls by first loading the address of the function into a register, and then performing a subroutine call on that register 🫶 You need this switch if the target function lies outside of the 64-megabyte addressing range of the offset-based version of the subroutine call instruction.
Okay so even if this switch is on, bestie, not every function call gets turned into a long call 💅 The heuristic (aka the vibe check the compiler runs) says that static functions, functions with the short_call attribute, functions inside the scope of a #pragma no_long_calls directive, and functions whose definitions have already been compiled within the current compilation unit are not turned into long calls 🙅♀️. The exceptions are the main character moments: weak function definitions, functions with the long_call attribute or the section attribute, and functions inside the scope of a #pragma long_calls directive are always turned into long calls 👑.
This feature is not enabled by default ✨ Specifying -mno-long-calls restores the default behavior, and so does putting the function calls inside the scope of a #pragma long_calls_off directive. Also, these switches have zero effect on how the compiler handles function calls made through function pointers, so don't expect them to reach that part 🙈
-msingle-pic-base— Treats the register used for PIC addressing as read-only, instead of loading it in the prologue for each function 🔒 The runtime system has to set this register to a proper value before execution starts, so that's on it 🫶-mpic-register=reg— Picks the register used for PIC addressing. For the standard PIC base case, the default is any suitable register the compiler decides on. For the single PIC base case, the default isR9if the target is EABI based or stack-checking is enabled, otherwise it'sR10🎀-mpic-data-is-text-relative— Assumes the displacement between the text and data segments is fixed at static link time 🦋 This lets PC-relative addressing operations access data known to be in the data segment. For non-VxWorks RTP targets, this option is on by default. When it's disabled on those targets,-msingle-pic-basegets enabled by default instead ✨-mpoke-function-name— Writes the name of each function into the text section, right before the function prologue 🧚 The generated code looks kind of like this:
t0
.ascii "arm_poke_function_name", 0
.align
t1
.word 0xff000000 + (t1 - t0)
arm_poke_function_name
mov ip, sp
stmfd sp!, {fp, ip, lr, pc}
sub fp, ip, #4When you're doing a stack backtrace, code can check the value of pc stored at fp + 0. If the trace function then looks at location pc - 12 and the top 8 bits are set, we know there's a function name embedded right before that location, and its length is ((pc[-3]) & 0xff000000) 🔍
-mthumb,-marm— Pick between generating code that runs in ARM state or Thumb state 🌸 Most configurations default to ARM state, but you can change that default by configuring GCC with the--with-mode=stateconfigure option. You can also override ARM or Thumb mode for each function using thetarget("thumb")andtarget("arm")function attributes or pragmas 💜-mflip-thumb— Switches ARM and Thumb modes on alternating functions 🔀 This one exists for regression testing of mixed Thumb/ARM code generation, so it's not meant for ordinary code compiling 🙅♀️-mtpcs-frame— Generates a stack frame that follows the Thumb Procedure Call Standard for all non-leaf functions. (A leaf function is one that does not call any other functions.) The default is-mno-tpcs-frame🍓-mtpcs-leaf-frame— Generates a stack frame that follows the Thumb Procedure Call Standard for all leaf functions. (A leaf function is one that does not call any other functions.) The default is-mno-apcs-leaf-frame🌈-mcallee-super-interworking— Gives all externally visible functions in the file being compiled an ARM instruction set header that switches to Thumb mode before the rest of the function runs ✨ That means these functions can be called from non-interworking code. This option is not valid in AAPCS configurations, because interworking is already enabled by default there 🙃-mcaller-super-interworking— Lets calls through function pointers (including virtual functions) run correctly no matter whether the target code was compiled for interworking or not 🫧 There's a small overhead when running a function pointer if you turn this on. Same deal as above: this option is not valid in AAPCS configurations because interworking is enabled by default 💀-mtp=name— Picks the access model for the thread local storage pointer 🧵 Thesoftmodel generates calls to__aeabi_read_tp. The other accepted models aretpidrurw,tpidruroandtpidrprw, which grab the thread pointer straight from the matching system register (supported from the arm6k architecture and later). Those system registers are accessed through the CP15 co-processor interface, andcp15is also accepted as a convenient alias oftpidruro💖 Theautoargument uses the best available method for the processor you've selected, andautois the default setting 👑-mtls-dialect=dialect— Picks the dialect used for accessing thread local storage. There are two:gnuandgnu2🎀 Thegnudialect selects the original GNU scheme for supporting local and global dynamic TLS models. Thegnu2dialect selects the GNU descriptor scheme, which gives better performance for shared libraries 🚀 The GNU descriptor scheme is compatible with the original scheme, but it does need new assembler, linker and library support 🫠 Initial and local exec TLS models aren't affected by this option and always use the original scheme.-mword-relocations— Only generates absolute relocations on word-sized values (i.e.R_ARM_ABS32) 🧱 This is on by default on targets (uClinux, SymbianOS) where the runtime loader imposes that restriction, and whenever-fpicor-fPICis specified. This option conflicts with-mslow-flash-data❌-mfix-cortex-m3-ldrd— Some Cortex-M3 cores can corrupt data whenldrdinstructions with overlapping destination and base registers are used 😭 This option avoids generating those instructions. It's enabled by default when-mcpu=cortex-m3is specified 🛠️-mfix-cortex-a57-aes-1742098,-mno-fix-cortex-a57-aes-1742098,-mfix-cortex-a72-aes-1655431,-mno-fix-cortex-a72-aes-1655431— Enables (or disables) the mitigation for an erratum on Cortex-A57 and Cortex-A72 that affects the AES cryptographic instructions 🔐 This option is enabled by default when either-mcpu=cortex-a57or-mcpu=cortex-a72is specified 💅-munaligned-access,-mno-unaligned-access— Enables (or disables) reading and writing of 16- and 32-bit values from addresses that aren't 16- or 32-bit aligned 🙈 By default, unaligned access is disabled for all pre-ARMv6, all ARMv6-M and for ARMv8-M Baseline architectures, and enabled for all other architectures. If unaligned access isn't enabled, words in packed data structures get accessed one byte at a time 🐢
The ARM attribute Tag_CPU_unaligned_access gets set in the generated object file to either true or false, depending on how this option is set 🏷️ If unaligned access is enabled, the preprocessor symbol __ARM_FEATURE_UNALIGNED is also defined ✨
-mneon-for-64bits— This option is deprecated and has no effect 🥀-mslow-flash-data— Assumes loading data from flash is slower than fetching instructions, so literal loads get minimized for better performance 🐌 This option is only supported when compiling for ARMv7 M-profile, and it's off by default. It conflicts with-mword-relocations❌-masm-syntax-unified— Assumes inline assembler uses unified asm syntax 🧩 The default is currently off, which implies divided syntax. This option has no impact on Thumb2, but that might change in future GCC releases. Divided syntax should be considered deprecated 🙃-mrestrict-it— Restricts generation of IT blocks so they follow the rules of ARMv8-A 📏 IT blocks can only contain a single 16-bit instruction from a select set of instructions. This option is on by default for ARMv8-A Thumb mode 💜-mprint-tune-info— Prints CPU tuning information as a comment in the assembler file 🖨️ This one is only for regression testing of the compiler and isn't intended for ordinary code compiling. It's disabled by default 🙅♀️-mverbose-cost-dump— Enables verbose cost model dumping in the debug dump files 🕵️♀️ It's provided for debugging the compiler, so that's its whole job 🫶-mpure-code— Doesn't allow constant data to be placed in code sections 🧊 When compiling for ELF object format, it also gives all text sections the ELF processor-specific section attributeSHF_ARM_PURECODE. This option is only available when generating non-PIC code for M-profile targets 💎-mcmse— Generates secure code as per the "ARMv8-M Security Extensions: Requirements on Development Tools Engineering Specification", which you can find athttps://developer.arm.com/documentation/ecm0359818/latest/🔒-mfix-cmse-cve-2021-35465— Mitigates a potential security issue with theVLLDMinstruction on some M-profile devices when using CMSE (CVE-2021-365465) 🛡️ This option is enabled by default when-mcpu=is used withcortex-m33,cortex-m35p,cortex-m52,cortex-m55,cortex-m85orstar-mc1. You can use-mno-fix-cmse-cve-2021-35465to disable the mitigation 🙅♀️-mstack-protector-guard=guard,-mstack-protector-guard-offset=offset— Generates stack protection code using a canary atguard. Supported locations areglobalfor a global canary, ortlsfor a canary accessible via the TLS register 🧷 The option-mstack-protector-guard-offset=is for use with-fstack-protector-guard=tlsand is not for use in user-land code 🙈-mfdpic,-mno-fdpic— okay bestie, this one picks the FDPIC ABI 💅 which uses 64-bit function descriptors to represent pointers to functions ✨. When the compiler is configured for"arm-*-uclinuxfdpiceabi"targets, it's on by default and implies-fPIEif none of the PIC/PIE-related options is provided 🔥. On other targets it only turns on the FDPIC-specific code generation features, so you have to explicitly pass the PIC/PIE-related options yourself 🫶.
Heads up 🙈 static linking is not supported, because it would still involve the dynamic linker when the program self-relocates. If that's acceptable to you, use -static and -Wl,-dynamic-linker options instead.
The opposite -mno-fdpic option is useful (and required) for building the Linux kernel with the same "arm-*-uclinuxfdpiceabi" toolchain you used for your userland programs 🧚.
-mbranch-protection=none|standard|pac-ret[+leaf][+bti]|bti[+pac-ret[+leaf]]— branch protection features 🦋 (armv8.1-m.main only). Here's the vibe check on each value:none— generate code without branch protection or return address signing 🙅♀️.standard[+leaf]— generate code with all branch protection features enabled at their standard level ✨.pac-ret[+leaf]— generate code with return address signing set to its standard level, which means signing all functions that save the return address to memory 🔐.leaf— when return address signing is enabled, also sign leaf functions, even if they don't write the return address to memory 🍃.+bti— add landing-pad instructions at the permitted targets of indirect branch instructions 🌸.
If the +pacbti architecture extension is not enabled, then all branch protection and return address signing operations are constrained to use only the instructions defined in the architectural-NOP space. The generated code stays backwards-compatible with earlier versions of the architecture, but the extra security can be turned on at run time on processors that support the PACBTI extension 💜.
Branch target enforcement using BTI can only be enabled at runtime if all code in the application has been compiled with at least -mbranch-protection=bti 🎀.
Any setting other than none is supported only on armv8-m.main or later 💀.
The default is to generate code without branch protection or return address signing 🌈.
✨ AVR Options ✨
These options are defined for AVR implementations 🐝.
-mmcu=mcu— pick your AVR instruction set architecture (ISA) or device type 💖. The default for this option is"avr2".
The following AVR devices and ISAs are supported. Note 📝: a complete device support setup consists of startup code crtmcu.o, a device header avr/io*.h, a device library libmcu.a, and a device-specs file specs-mcu (https://gcc.gnu.org/wiki/avr-gcc#spec-files). Only that last one, the device-specs file, is provided by the compiler, according to the supported mcus listed below. The rest comes from AVR-LibC (https://www.nongnu.org/avr-libc/) or from atpack files (https://gcc.gnu.org/wiki/avr-gcc#atpack) supplied by the hardware manufacturer 🫶.
avr2— "Classic" devices with up to 8 KiB of program memory 🍓. mcu ="attiny22", "attiny26", "at90s2313", "at90s2323", "at90s2333", "at90s2343", "at90s4414", "at90s4433", "at90s4434", "at90c8534", "at90s8515", "at90s8535".avr25— "Classic" devices with up to 8 KiB of program memory and with the "MOVW" instruction 🦋. mcu ="attiny13", "attiny13a", "attiny24", "attiny24a", "attiny25", "attiny261", "attiny261a", "attiny2313", "attiny2313a", "attiny43u", "attiny44", "attiny44a", "attiny45", "attiny48", "attiny441", "attiny461", "attiny461a", "attiny4313", "attiny84", "attiny84a", "attiny85", "attiny87", "attiny88", "attiny828", "attiny841", "attiny861", "attiny861a", "ata5272", "ata6616c", "at86rf401".avr3— "Classic" devices with 16 KiB up to 64 KiB of program memory 🌷. mcu ="at76c711", "at43usb355".avr31— "Classic" devices with 128 KiB of program memory 🔥. mcu ="atmega103", "at43usb320".avr35— "Classic" devices with 16 KiB up to 64 KiB of program memory and with the "MOVW" instruction 🌈. mcu ="attiny167", "attiny1634", "atmega8u2", "atmega16u2", "atmega32u2", "ata5505", "ata6617c", "ata664251", "at90usb82", "at90usb162".avr4— "Enhanced" devices with up to 8 KiB of program memory ⭐. mcu ="atmega48", "atmega48a", "atmega48p", "atmega48pa", "atmega48pb", "atmega8", "atmega8a", "atmega8hva", "atmega88", "atmega88a", "atmega88p", "atmega88pa", "atmega88pb", "atmega8515", "atmega8535", "ata5795", "ata6285", "ata6286", "ata6289", "ata6612c", "at90pwm1", "at90pwm2", "at90pwm2b", "at90pwm3", "at90pwm3b", "at90pwm81".avr5— "Enhanced" devices with 16 KiB up to 64 KiB of program memory 👑. mcu ="atmega16", "atmega16a", "atmega16hva", "atmega16hva2", "atmega16hvb", "atmega16hvbrevb", "atmega16m1", "atmega16u4", "atmega161", "atmega162", "atmega163", "atmega164a", "atmega164p", "atmega164pa", "atmega165", "atmega165a", "atmega165p", "atmega165pa", "atmega168", "atmega168a", "atmega168p", "atmega168pa", "atmega168pb", "atmega169", "atmega169a", "atmega169p", "atmega169pa", "atmega32", "atmega32a", "atmega32c1", "atmega32hvb", "atmega32hvbrevb", "atmega32m1", "atmega32u4", "atmega32u6", "atmega323", "atmega324a", "atmega324p", "atmega324pa", "atmega324pb", "atmega325", "atmega325a", "atmega325p", "atmega325pa", "atmega328", "atmega328p", "atmega328pb", "atmega329", "atmega329a", "atmega329p", "atmega329pa", "atmega3250", "atmega3250a", "atmega3250p", "atmega3250pa", "atmega3290", "atmega3290a", "atmega3290p", "atmega3290pa", "atmega406", "atmega64", "atmega64a", "atmega64c1", "atmega64hve", "atmega64hve2", "atmega64m1", "atmega64rfr2", "atmega640", "atmega644", "atmega644a", "atmega644p", "atmega644pa", "atmega644rfr2", "atmega645", "atmega645a", "atmega645p", "atmega649", "atmega649a", "atmega649p", "atmega6450", "atmega6450a", "atmega6450p", "atmega6490", "atmega6490a", "atmega6490p", "ata5790", "ata5790n", "ata5791", "ata6613c", "ata6614q", "ata5782", "ata5831", "ata8210", "ata8510", "ata5787", "ata5835", "ata5700m322", "ata5702m322", "at90pwm161", "at90pwm216", "at90pwm316", "at90can32", "at90can64", "at90scr100", "at90usb646", "at90usb647", "at94k", "m3000".avr51— "Enhanced" devices with 128 KiB of program memory 💅. mcu ="atmega128", "atmega128a", "atmega128rfa1", "atmega128rfr2", "atmega1280", "atmega1281", "atmega1284", "atmega1284p", "atmega1284rfr2", "at90can128", "at90usb1286", "at90usb1287".avr6— "Enhanced" devices with 3-byte PC, i.e. with more than 128 KiB of program memory 🚀. mcu ="atmega256rfr2", "atmega2560", "atmega2561", "atmega2564rfr2".avrxmega2— "XMEGA" devices with more than 8 KiB and up to 64 KiB of program memory 🧚. mcu ="atxmega8e5", "atxmega16a4", "atxmega16a4u", "atxmega16c4", "atxmega16d4", "atxmega16e5", "atxmega32a4", "atxmega32a4u", "atxmega32c3", "atxmega32c4", "atxmega32d3", "atxmega32d4", "atxmega32e5", "avr64da28", "avr64da32", "avr64da48", "avr64da64", "avr64db28", "avr64db32", "avr64db48", "avr64db64", "avr64dd14", "avr64dd20", "avr64dd28", "avr64dd32", "avr64du28", "avr64du32", "avr64ea28", "avr64ea32", "avr64ea48".avrxmega3— "XMEGA" devices with up to 64 KiB of combined program memory and RAM, and with program memory visible in the RAM address space 🌸. mcu ="attiny202", "attiny204", "attiny212", "attiny214", "attiny402", "attiny404", "attiny406", "attiny412", "attiny414", "attiny416", "attiny416auto", "attiny417", "attiny424", "attiny426", "attiny427", "attiny804", "attiny806", "attiny807", "attiny814", "attiny816", "attiny817", "attiny824", "attiny826", "attiny827", "attiny1604", "attiny1606", "attiny1607", "attiny1614", "attiny1616", "attiny1617", "attiny1624", "attiny1626", "attiny1627", "attiny3214", "attiny3216", "attiny3217", "attiny3224", "attiny3226", "attiny3227", "atmega808", "atmega809", "atmega1608", "atmega1609", "atmega3208", "atmega3209", "atmega4808", "atmega4809", "avr16dd14", "avr16dd20", "avr16dd28", "avr16dd32", "avr16ea28", "avr16ea32", "avr16ea48", "avr16eb14", "avr16eb20", "avr16eb28", "avr16eb32", "avr32da28", "avr32da32", "avr32da48", "avr32db28", "avr32db32", "avr32db48", "avr32dd14", "avr32dd20", "avr32dd28", "avr32dd32", "avr32ea28", "avr32ea32", "avr32ea48".avrxmega4— "XMEGA" devices with more than 64 KiB and up to 128 KiB of program memory 🦄. mcu ="atxmega64a3", "atxmega64a3u", "atxmega64a4u", "atxmega64b1", "atxmega64b3", "atxmega64c3", "atxmega64d3", "atxmega64d4", "avr128da28", "avr128da32", "avr128da48", "avr128da64", "avr128db28", "avr128db32", "avr128db48", "avr128db64".avrxmega5— "XMEGA" devices with more than 64 KiB and up to 128 KiB of program memory and more than 64 KiB of RAM 🍒. mcu ="atxmega64a1", "atxmega64a1u".avrxmega6— "XMEGA" devices with more than 128 KiB of program memory 💜. mcu ="atxmega128a3", "atxmega128a3u", "atxmega128b1", "atxmega128b3", "atxmega128c3", "atxmega128d3", "atxmega128d4", "atxmega192a3", "atxmega192a3u", "atxmega192c3", "atxmega192d3", "atxmega256a3", "atxmega256a3b", "atxmega256a3bu", "atxmega256a3u", "atxmega256c3", "atxmega256d3", "atxmega384c3", "atxmega384d3".avrxmega7— "XMEGA" devices with more than 128 KiB of program memory and more than 64 KiB of RAM 🔮. mcu ="atxmega128a1", "atxmega128a1u", "atxmega128a4u".avrtiny— "Reduced Tiny" Tiny core devices with only 16 general purpose registers and 512 B up to 4 KiB of program memory 🐣. mcu ="attiny4", "attiny5", "attiny9", "attiny10", "attiny102", "attiny104", "attiny20", "attiny40".avr1— this ISA is implemented by the minimal AVR core and is supported for assembler only 🙈. mcu ="attiny11", "attiny12", "attiny15", "attiny28", "at90s1200".
-mabsdata— okay so this one tells the compiler to assume all data in static storage can be reached withLDS/STSinstructions 💖. It only has an effect on reduced Tiny devices, like ATtiny40 🧚. See also the "absdata" AVR Variable Attributes, which is a variable attribute ✨.-maccumulate-args— this one collects outgoing function arguments and grabs the stack space for them once, in the function prologue, then releases it in the epilogue 🎀. Without it, outgoing arguments get pushed before each call and popped right after, which is the default vibe.
Popping arguments after a function call can be expensive on AVR, so accumulating the stack space can lead to smaller executables. The arguments don't need to be removed from the stack after each call. It can shrink code for functions that make several calls to functions taking arguments on the stack, like printf-like functions 🖨️.
-mbranch-cost=cost— sets the branch costs for conditional branch instructions tocost💅. Reasonable values forcostare small, non-negative integers. The default branch cost is0.-mcall-prologues— function prologues and epilogues get expanded as calls to the appropriate subroutines, so the code size comes out smaller 🌸.-mfuse-add,-mno-fuse-add,-mfuse-add=level— optimizes indirect memory accesses on reduced Tiny devices 🔥. The default useslevel=1for-Ogand-O1, andlevel=2for higher optimizations. Valid values forlevelare0,1and2.-mdouble=bits,-mlong-double=bits— sets the size in bits of thedoubleorlong doubletype, respectively 🦋. Possible values forbitsare32and64. Whether a specific value is allowed depends on the--with-double=and--with-long-double=configure options (https://gcc.gnu.org/install/configure.html#avr), and the same goes for the default values of the options 🌈.-mgas-isr-prologues— interrupt service routines (ISRs) are allowed to use the__gcc_isrpseudo instruction, which GNU Binutils supports 💜. If this option is on, you can still turn the feature off for individual ISRs with the AVR Function Attributes"no_gccisr"function attribute. The feature is turned on by default if optimization is on (but not with-Og, see@pxref{Optimize Options}), and only if GNU Binutils supports PR21683 (https://sourceware.org/PR21683) ⭐.-mint8— tells the compiler to assumeintis an 8-bit integer 🙈. This changes the sizes of all types: acharis 1 byte, anintis 1 byte, alongis 2 bytes, and along longis 4 bytes.
Heads up, bestie: this option does not conform to the C standards. It does result in smaller code size, though 💀.
-mmain-is-OS_task— do not save registers inmain👑. The effect is the same as attaching the AVR Function Attributes"OS_task"attribute tomain. It is turned on by default if optimization is on.-mno-interrupts— generated code is not compatible with hardware interrupts 🙅. The upside is that code size comes out smaller.
Careful: generated code with this option will not work alongside hardware interrupts, so only use it when you're sure your code doesn't need them 😭.
-mrelax— tries to swap aCALLorJMPfor the shorterRCALLorRJMPinstruction, where that's allowed 🦋. Setting-mrelaxjust adds--mlink-relaxto the assembler's command line and--relaxto the linker's command line.
Jump relaxing is done by the linker, because jump offsets aren't known until the code is located. So the assembler code the compiler generates stays the same, but the instructions in the executable may differ from the ones in the assembler code 🧠.
Relaxing must be turned on if linker stubs are needed. See the section on "EIND" and linker stubs below 👀.
-mrodata-in-ram,-mno-rodata-in-ram— puts the.rodatasections for read-only data in RAM or in program memory, respectively 🌷. For most devices there's no real choice here, so this option acts more like an assertion.
Since v14, and for the AVR64* and AVR128* devices, .rodata lives in flash memory by default, as long as the required GNU Binutils support (PR31124, https://sourceware.org/PR31124) is available. In that case, -mrodata-in-ram can be used to go back to the old layout with .rodata in RAM 🔙.
-mstrict-X— uses the address registerXin the way the hardware intends 🧚. That meansXis only used for indirect, post-increment or pre-decrement addressing.
Without this option, the X register can be used the same way as Y or Z, which then gets emulated with extra instructions 🙃. For example, loading a value with X+const addressing (with a small non-negative const < 64) into a register Rn is done like this:
adiw r26, const ; X += const
ld <Rn>, X ; <Rn> = *X
sbiw r26, const ; X -= const-mtiny-stack— only changes the lower 8 bits of the stack pointer 🌙.-mfract-convert-truncate— lets fractional fixed-point types use truncation instead of rounding towards zero 🍓.-nodevicelib— don't link against AVR-LibC's device specific librarylib<mcu>.a📚.-nodevicespecs— don't add-specs=device-specs/specs-mcuto the compiler driver's command line. You're taking full responsibility for giving the subprocesses (compiler proper, assembler and linker) the right command line options 🫶. That means you have to supply your own private device specs file with-specs=path-to-specs-file. There's no more need for-mmcu=mcu.
This option can also replace the older way of making custom device-specs files. That method needed -B some-path to point to a directory containing a folder named "device-specs", which in turn contained a specs file named "specs-mcu", where mcu was specified by -mmcu=mcu 🗂️.
-Waddr-space-convert— warns about conversions between address spaces when the resulting address space is not contained in the incoming address space 👀.-Wmisspelled-isr— warns if the ISR is misspelled, i.e. without the__vectorprefix. This is enabled by default 💅.
✨ "EIND" and Devices with More Than 128 Ki Bytes of Flash ✨
Pointers in the implementation are 16 bits wide 🌸. The address of a function or label is represented as a word address, so indirect jumps and calls can target any code address in the range of 64 Ki words.
To make indirect jumps work on devices with more than 128 Ki bytes of flash, there's a special function register called EIND 👑. It acts as the most significant part of the target address whenever EICALL or EIJMP instructions are used.
Indirect jumps and calls on these devices are handled as follows by the compiler, and they come with some limitations 🫠:
- The compiler never sets
EIND. - The compiler uses
EINDimplicitly inEICALL/EIJMPinstructions, or might readEINDdirectly in order to emulate an indirect call/jump by means of aRETinstruction. - The compiler assumes that
EINDnever changes during the startup code or during the application. In particular,EINDis not saved/restored in function or interrupt service routine prologue/epilogue. - For indirect calls to functions and computed goto, the linker generates stubs 🧸. Stubs are jump pads, sometimes also called trampolines. So the indirect call/jump lands on such a stub, and the stub contains a direct jump to the desired address.
- Linker relaxation must be turned on so that the linker generates the stubs correctly in all situations. See the compiler option
-mrelaxand the linker option--relax. Watch out: there are corner cases where the linker is supposed to generate stubs but aborts without relaxation and without a helpful error message 😱. - The default linker script is arranged for code with
EIND = 0. If code is supposed to work for a setup withEIND != 0, a custom linker script has to be used to place the sections whose name starts with.trampolinesinto the segment whereEINDpoints to 🗺️. - The startup code from libgcc never sets
EIND. Notice that startup code is a blend of code from libgcc and AVR-LibC. For the impact of AVR-LibC onEIND, see the AVR-LibC user manual (https://www.nongnu.org/avr-libc/user-manual/) 📖. - It is legitimate for user-specific startup code to set up
EINDearly, for example by means of initialization code located in section.init3. That code runs prior to the general startup code that initializes RAM and calls constructors, but after the bit of AVR-LibC startup code that setsEINDto the segment where the vector table is located 🧚.
#include <avr/io.h>
static void
__attribute__((section(".init3"),naked,used,no_instrument_function))
init3_set_eind (void)
{
__asm volatile ("ldi r24,pm_hh8(__trampolines_start)\n\t"
"out %i0,r24" :: "n" (&EIND) : "r24","memory");
}The __trampolines_start symbol is defined in the linker script.
- Stubs are generated automatically by the linker if the following two conditions are met 🪄:
- The address of a label is taken by means of the
gsmodifier (short for generate stubs), like so:
LDI r24, lo8(gs(<func>))
LDI r25, hi8(gs(<func>))- The final location of that label is in a code segment outside the segment where the stubs are located.
- The compiler emits such
gsmodifiers for code labels in the following situations:- Taking the address of a function or code label.
- Computed goto.
- If the prologue-save function is used, see the
-mcall-prologuescommand-line option. - Switch/case dispatch tables. If you do not want such dispatch tables, you can specify the
-fno-jump-tablescommand-line option. - C and C++ constructors/destructors called during startup/shutdown.
- If the tools hit a
gs()modifier explained above.
- Jumping to non-symbolic addresses like so is not supported 🙅:
int main (void)
{
/* Call function at word address 0x2 */
return ((int(*)(void)) 0x2)();
}Instead, a stub has to be set up, i.e. the function has to be called through a symbol (func_4 in the example) 💖:
int main (void)
{
extern int func_4 (void);
/* Call function at byte address 0x4 */
return func_4();
}...and the application be linked with -Wl,--defsym,func_4=0x4. Alternatively, func_4 can be defined in the linker script. 🧚
💖 Handling of the "RAMPD", "RAMPX", "RAMPY" and "RAMPZ" Special Function Registers 💖
okay so some AVR devices have more memory than a 16-bit pointer can reach, which is anything past the 64 KiB range 😭. To get to those higher spots, the content of a RAMP register is used as the high part of the address. The X, Y, and Z address registers get paired with RAMPX, RAMPY, and RAMPZ respectively to make a wide address. RAMPD does the same job for direct addressing. ✨
- The startup code sets the
RAMPspecial function registers to zero. 🌸 - If a named address space other than generic or
__flashis used (see AVR Named Address Spaces), thenRAMPZgets set as needed before the operation. 💅 - If the device supports RAM larger than 64 KiB and the compiler needs to change
RAMPZto pull off an operation,RAMPZgets reset to zero afterwards. 🔁 - If the device has a specific
RAMPregister, the ISR prologue and epilogue save and restore that SFR, and initialize it with zero in case the ISR code might (implicitly) use it. 🛡️ - RAM larger than 64 KiB is not supported by GCC for AVR targets.
💀 Big warning, bestie: if you use inline assembler to read from locations outside the 16-bit address range and change one of the RAMP registers, you MUST reset it to zero after the access, or things get messy.
🧚 AVR Built-in Macros 🧚
GCC defines a bunch of built-in macros so your code can check whether a feature is there or not. Almost all of the following built-in macros are deduced from device capabilities, so they get triggered by the -mmcu= command-line option. 🌈
For even more AVR-specific built-in macros, check out AVR Named Address Spaces and AVR Built-in Functions. 💜
__AVR_ARCH__— This built-in macro resolves to a decimal number that identifies the architecture, and it depends on the-mmcu=mcuoption. The possible values are2, 25, 3, 31, 35, 4, 5, 51, 6, which map to these mcus in order:"avr2"=2,"avr25"=25,"avr3"=3,"avr31"=31,"avr35"=35,"avr4"=4,"avr5"=5,"avr51"=51,"avr6"=6- And
100, 102, 103, 104, 105, 106, 107for the xmega and tiny ones, in order:"avrtiny"=100,"avrxmega2"=102,"avrxmega3"=103,"avrxmega4"=104,"avrxmega5"=105,"avrxmega6"=106,"avrxmega7"=107
- If mcu specifies a device, this macro gets set accordingly. For example, with
-mmcu=atmega8the macro is defined to4. 🎀
__AVR_Device__— Setting-mmcu=devicedefines this macro, which reflects the device's name. For example,-mmcu=atmega8defines__AVR_ATmega8__, and-mmcu=attiny261adefines__AVR_ATtiny261A__, and so on. 🦋- The names follow the scheme
__AVR_Device__, where Device is the device name as it appears in the AVR user manual. The difference between Device in the macro and device in-mmcu=deviceis that the latter is always lowercase. - If device isn't a device but only a core architecture like
avr51, this macro is not defined.
- The names follow the scheme
__AVR_DEVICE_NAME__— Setting-mmcu=devicedefines this macro to the device's name. For example, with-mmcu=atmega8it's defined to"atmega8". If device is only a core architecture likeavr51, this macro is not defined. 🍓__AVR_XMEGA__— The device or architecture belongs to the XMEGA family of devices. ⭐__AVR_HAVE_ADIW__— The device has theADIWandSBIWinstructions. 💅__AVR_HAVE_ELPM__— The device has theELPMinstruction. 🌸__AVR_HAVE_ELPMX__— The device has theELPM Rn,ZandELPM Rn,Z+instructions. 🫶__AVR_HAVE_LPMX__— The device has theLPM Rn,ZandLPM Rn,Z+instructions. 🫶__AVR_HAVE_MOVW__— The device has theMOVWinstruction, which does 16-bit register-to-register moves. 🔥__AVR_HAVE_MUL__— The device has a hardware multiplier. 👑__AVR_HAVE_JMP_CALL__— The device has theJMPandCALLinstructions. This is the case for devices with more than 8 KiB of program memory. 🌈__AVR_HAVE_EIJMP_EICALL__and__AVR_3_BYTE_PC__— The device has theEIJMPandEICALLinstructions. This is the case for devices with more than 128 KiB of program memory. It also means the program counter (PC) is 3 bytes wide. 🧚__AVR_2_BYTE_PC__— The program counter (PC) is 2 bytes wide. This is the case for devices with up to 128 KiB of program memory. 🦋__AVR_HAVE_8BIT_SP__and__AVR_HAVE_16BIT_SP__— The compiler treats the stack pointer (SP) register as an 8-bit or 16-bit register, respectively. Defining these macros is affected by-mtiny-stack. 💜__AVR_HAVE_SPH__and__AVR_SP8__— The device has the SPH (high part of stack pointer) special function register, or it has an 8-bit stack pointer, respectively. Defining these macros is affected by-mmcu=, and for-mmcu=avr2and-mmcu=avr25it's also affected by-msp8. 🎀__AVR_HAVE_RAMPD__,__AVR_HAVE_RAMPX__,__AVR_HAVE_RAMPY__and__AVR_HAVE_RAMPZ__— The device has theRAMPD,RAMPX,RAMPY, andRAMPZspecial function registers, respectively. 🌸__NO_INTERRUPTS__— This macro reflects the-mno-interruptscommand-line option. 🙈__AVR_ERRATA_SKIP__and__AVR_ERRATA_SKIP_JMP_CALL__— Some AVR devices (AT90S8515, ATmega103) must not skip 32-bit instructions because of a hardware erratum. The skip instructions areSBRS,SBRC,SBIS,SBIC, andCPSE. The second macro is only defined if__AVR_HAVE_JMP_CALL__is also set.
⚠️ Those devices really can't skip 32-bit instructions, so keep that in mind when you're writing skip logic. 💀
__AVR_ISA_RMW__— The device has Read-Modify-Write instructions (XCH,LAC,LAS, andLAT). 🔥__AVR_SFR_OFFSET__=offset— Instructions that can address I/O special function registers directly, likeIN,OUT,SBI, and so on, may use a different address than an instruction that accesses RAM, likeLDorSTS. This offset depends on the device architecture, and you have to subtract it from the RAM address to get the matching I/O address. 🧮__AVR_SHORT_CALLS__— The-mshort-callscommand-line option is set. 📞__AVR_PM_BASE_ADDRESS__=addr— Some devices can read from flash memory usingLD*instructions. The flash memory shows up in the data address space at an offset of__AVR_PM_BASE_ADDRESS__. If this macro isn't defined, the feature isn't available. If it is defined, the address space is linear, so there's no need to put.rodatainto RAM. The default linker description file handles this, and it's currently available foravrtinyandavrxmega3. Even better, you don't need address spaces like__flashor attributes likeprogmemandpgm_read_*. 💖__AVR_HAVE_FLMAP__— This macro is defined when all of these conditions are met:- The device has the
NVMCTRL_CTRLB.FLMAPbitfield. This applies to the AVR64* and AVR128* devices. - It's not known at assembler-time which emulation will be used.
- The device has the
This implies the compiler was configured with GNU Binutils that implement PR31124 (https://sourceware.org/PR31124). 🔍
__AVR_RODATA_IN_RAM__— This macro is undefined when the code is compiled for a core architecture. When the code is compiled for a device, the macro is defined to1if the.rodatasections for read-only data are located in RAM, and defined to0otherwise. 🌈__WITH_AVRLIBC__— The compiler is configured to be used together with AVR-Libc. See the--with-avrlibcconfigure option. 🫶__HAVE_DOUBLE_MULTILIB__— Defined if-mdouble=acts as a multilib option. ✨__HAVE_DOUBLE32__and__HAVE_DOUBLE64__— Defined if the compiler supports 32-bit double or 64-bit double, respectively. The actual layout is specified by option-mdouble=. 🦋__DEFAULT_DOUBLE__— The size in bits ofdoubleif-mdouble=is not set. To test the layout ofdoublein a program, use the built-in macro__SIZEOF_DOUBLE__. 📏__HAVE_LONG_DOUBLE32__,__HAVE_LONG_DOUBLE64__,__HAVE_LONG_DOUBLE_MULTILIB__and__DEFAULT_LONG_DOUBLE__— Same as above, but forlong doubleinstead ofdouble. 🌸__WITH_DOUBLE_COMPARISON__— Reflects the--with-double-comparison={tristate|bool|libf7}configure option (https://gcc.gnu.org/install/configure.html#avr), and is defined to2or3. 💜__WITH_LIBF7_LIBGCC__,__WITH_LIBF7_MATH__and__WITH_LIBF7_MATH_SYMBOLS__— Reflect the--with-libf7={libgcc|math|math-symbols}configure option (https://gcc.gnu.org/install/configure.html#avr). 👑
🔥 AVR Internal Options 🔥
These options are used internally by the compiler and to communicate between device specs files and the compiler proper. You don't need to set them by hand, and they are definitely not optimization options. Using them the wrong way may lead to sub-optimal or wrong code. They're documented for completeness, and so you can better understand device specs files (https://gcc.gnu.org/wiki/avr-gcc#spec-files). 🧐
💀 Seriously, don't go poking these unless you know exactly what you're doing, or your code could come out sub-optimal or just plain wrong.
-mn-flash=num— Assumes the flash memory has a size ofnumtimes 64 KiB. This determines which__flashNaddress spaces are available. 🧩-mflmap— The device has theFLMAPbit field, located in the special function registerNVMCTRL_CTRLB. 🗺️-mrmw— Assumes the device supports the Read-Modify-Write instructionsXCH,LAC,LAS, andLAT. 🔥-mshort-calls— AssumesRJMPandRCALLcan target the whole program memory. This option is used for multilib generation and selection for devices from architectureavrxmega3. 📞-mskip-bug— Generates code without skips (CPSE,SBRS,SBRC,SBIS,SBIC) over 32-bit instructions. 🙈-msp8— Treats the stack pointer register as an 8-bit register, meaning it assumes the high byte of the stack pointer is zero. The compiler uses this option to select and build multilibs for architecturesavr2andavr25, since these architectures mix devices with and withoutSPH. 🎀
🌈 Blackfin Options 🌈
-mcpu=cpu[-sirevision]— Specifies the name of the target Blackfin processor. Currently, cpu can be one ofbf512, bf514, bf516, bf518, bf522, bf523, bf524, bf525, bf526, bf527, bf531, bf532, bf533, bf534, bf536, bf537, bf538, bf539, bf542, bf544, bf547, bf548, bf549, bf542m, bf544m, bf547m, bf548m, bf549m, bf561, bf592. ✨
Okay so the optional sirevision lets you tell GCC exactly which silicon revision of the Blackfin processor you're targeting 🦋. Every workaround for that revision gets switched on ✨. If sirevision is none, no workarounds are enabled at all 🙈. If it's any, every workaround for the targeted processor gets enabled 💖.
GCC also defines the __SILICON_REVISION__ macro as two hexadecimal digits that represent the major and minor numbers of the silicon revision 🌸. With none, that macro isn't defined at all 💀. With any, it's defined to be 0xffff 🔥. And if you skip the optional sirevision completely, GCC just assumes the latest known silicon revision of the targeted Blackfin processor 👑.
GCC defines a preprocessor macro for the specified cpu 🧚. For the bfin-elf toolchain, this option causes the hardware BSP from libgloss to get linked in, as long as -msim isn't given 🎀.
Without this option, bf532 is the default processor 💅.
Heads up, though: support for bf561 is incomplete 😭. For bf561, only the preprocessor macro gets defined.
-msim— Okay, this one's for the simulator 🖥️. It links in the simulator BSP fromlibgloss. It only does anything for thebfin-elftoolchain. Some other options, like-mid-shared-libraryand-mfdpic, imply-msimon their own 🫶.-momit-leaf-frame-pointer— Don't keep the frame pointer in a register for leaf functions 🍓. You skip the instructions that save, set up, and restore frame pointers, and you get an extra register to play with in leaf functions ✨.-mspecld-anomaly— When this is on, the compiler makes sure the generated code has no speculative loads right after jump instructions 🛡️. If you use it,__WORKAROUND_SPECULATIVE_LOADSgets defined.-mno-specld-anomaly— Don't generate the extra code that stops speculative loads from happening 🙅♀️.-mcsync-anomaly— When this is on, the compiler makes sure noCSYNCorSSYNCinstructions show up too soon after conditional branches 🌈. If you use it,__WORKAROUND_SPECULATIVE_SYNCSgets defined.-mno-csync-anomaly— Don't generate the extra code that stopsCSYNCorSSYNCinstructions from landing too soon after a conditional branch 💀.-mlow64k— When enabled, the compiler can take advantage of knowing the whole program fits into the low 64k of memory 🧠.-mno-low64k— Assume the program could be arbitrarily large. This is the default 🌸.-mstack-check-l1— Do stack checking using the info that the uClinux kernel puts into L1 scratchpad memory 🧚.-mid-shared-library— Generate code that supports shared libraries through the library ID method ✨. This lets you do execute in place and shared libraries in an environment without virtual memory management 🦋. It implies-fPIC, and with abfin-elftarget it also implies-msim💖.-mno-id-shared-library— Generate code that doesn't assume ID-based shared libraries are in use. This is the default 🍓.-mleaf-id-shared-library— Generate code that supports shared libraries through the library ID method, but assumes this library or executable won't link against any other ID shared libraries 🫶. That lets the compiler use faster code for jumps and calls 🔥.-mno-leaf-id-shared-library— Don't assume the code won't link against any ID shared libraries 🙈. You get slower code for jump and call instructions 🐢.-mshared-library-id=n— Specifies the identification number of the ID-based shared library you're compiling 🆔. A value of0gives you more compact code 💅. Other values force that number onto the current library, but it's no more space- or time-efficient than leaving this option out 😭.-msep-data— Generate code that lets the data segment sit in a different area of memory from the text segment 🌈. This allows execute in place in an environment without virtual memory management, because it gets rid of relocations against the text section ✨.-mno-sep-data— Generate code that assumes the data segment follows the text segment. This is the default 💜.-mlong-calls,-mno-long-calls—-mlong-callstells the compiler to make function calls by first loading the function's address into a register, then doing a subroutine call on that register 📞. You need this if the target function is outside the 24-bit addressing range of the offset-based subroutine call instruction 🌍. It's not enabled by default, and-mno-long-callsputs you back to the default behavior 🎀. Heads up, these switches have no effect on how function calls through function pointers get generated 🙈.-mfast-fp— Link with the fast floating-point library ⚡. It relaxes some of the IEEE floating-point standard's rules for checking inputs against Not-a-Number (NAN), all in the name of performance 🔥.-minline-plt— Enable inlining of PLT entries in function calls to functions that aren't known to bind locally 🧩. It has no effect without-mfdpic💀.-mmulticore— Build a standalone application for multicore Blackfin processors 🧠. This option uses the proper start files and link scripts for multicore, and it defines the__BFIN_MULTICOREmacro 💖. It can only be used with-mcpu=bf561[-sirevision]🌸.
This option can go with -mcorea or -mcoreb, which pick the one-application-per-core programming model 👑. Without either of those, you get the single-application/dual-core programming model 🦋. In that model, the main function of Core B should be named coreb_main 🫶.
Without this option, you get the single-core application programming model 🍓.
-mcorea— Build a standalone application for Core A of BF561 when you're using the one-application-per-core programming model 🅰️. Proper start files and link scripts support Core A, and the__BFIN_COREAmacro gets defined 🌈. This can only be used together with-mmulticore💅.-mcoreb— Build a standalone application for Core B of BF561 when you're using the one-application-per-core programming model 🅱️. Proper start files and link scripts support Core B, and the__BFIN_COREBmacro gets defined 💜. When you use this option,coreb_mainshould be used instead ofmain✨. This can only be used together with-mmulticore🔥.-msdram— Build a standalone application for SDRAM 🧸. Proper start files and link scripts put the application into SDRAM, and the__BFIN_SDRAMmacro gets defined 🦋. The loader should initialize SDRAM before it loads the application 😭.-micplb— Assume ICPLBs are enabled at run time. This affects certain anomaly workarounds 🧠. For Linux targets, the default is to assume ICPLBs are enabled 🐧. For standalone applications, the default is off 🙈.
🧚 C6X Options 🧚
-march=name— This specifies the name of the target architecture 🏗️. GCC uses this name to figure out which kinds of instructions it can emit when generating assembly code 💖. The permissible names arec62x,c64x,c64x+,c67x,c67x+, andc674x✨.-mbig-endian— Generate code for a big-endian target 🌸.-mlittle-endian— Generate code for a little-endian target. This is the default 💜.-msim— Choose startup files and a linker script that suit the simulator 🖥️.-msdata=default— Put small global and static data in the.neardatasection, which is pointed to by registerB14🎀. Put small uninitialized global and static data in the.bsssection, which sits right next to.neardata🫶. Put small read-only data into the.rodatasection 📖. The matching sections for large chunks of data are.fardata,.far, and.const🧳.-msdata=all— Put all data, not just the small stuff, into the sections reserved for small data 🌈. Then use addressing relative to theB14register to get at them 🔥.-msdata=none— Don't use the sections reserved for small data at all 🙅♀️. Use absolute addresses to access all data 📍. Put all initialized global and static data in.fardata, and all uninitialized data in.far💀. Put all constant data into.const🍓.
🦋 CRIS Options 🦋
These options are defined specifically for the CRIS ports 💅.
-march=architecture-type,-mcpu=architecture-type— Generate code for the specified architecture 🏛️. The choices for architecture-type arev3,v8, andv10, which are for ETRAX 4, ETRAX 100, and ETRAX 100 LX respectively ✨. The default isv0💜.-mtune=architecture-type— Tune everything that applies to the generated code for architecture-type, except for the ABI and the set of available instructions 🎶. The choices are the same as for-march=architecture-type🫶.-mmax-stack-frame=n— Warn when a function's stack frame goes overnbytes 🚨.-metrax4,-metrax100— These are synonyms for-march=v3and-march=v8respectively 🔁.-mmul-bug-workaround,-mno-mul-bug-workaround— Work around a bug in themulsandmuluinstructions, for the CPU models where it applies 🐛. This option is disabled by default 🙈.-mpdebug— Enable CRIS-specific verbose debug info in the assembly code 🔍. This also turns off the#NO_APPformatted-code indicator that goes to the assembler at the start of the assembly file 🫠.-mcc-init— Don't use condition-code results from the previous instruction. Always emit compare and test instructions before condition codes get used 🧼.-mno-side-effects— Don't emit instructions with side effects in addressing modes other than post-increment 🌿.-mstack-align,-mno-stack-align,-mdata-align,-mno-data-align,-mconst-align,-mno-const-align— These no- options eliminate the alignment arrangements, and the others arrange alignment 📐. Arrangement means the stack frame, individual data, and constants get aligned to the maximum single data access size for the chosen CPU model ✨. The default is to arrange for 32-bit alignment 💖. ABI details such as structure layout aren't affected by these options 🙌.-m32-bit,-m16-bit,-m8-bit— Same energy as the stack-, data- and const-align options from up above 💅 These make the stack frame, writable data and constants all 32-bit, 16-bit or 8-bit aligned. The default is 32-bit alignment 🌸-mno-prologue-epilogue,-mprologue-epilogue— With-mno-prologue-epilogue, the usual function prologue and epilogue that set up the stack frame get skipped, and no return instructions or return sequences show up in the code 🙈
Bestie, use this one ONLY if you're going to visually inspect the compiled code yourself. No warnings or errors pop up when call-saved registers need saving or when storage for local variables needs allocating. Read your output!! 💀
-melf— Legacy no-op option. It does nothing, but it's still here 🦋-sim— This one links with input-output functions from a simulator library 🧚 Code, initialized data and zero-initialized data all get allocated back-to-back, consecutively.-sim2— Like-sim, but it also passes linker options so initialized data lands at0x40000000and zero-initialized data lands at0x80000000✨
🌵 C-SKY Options 🌵
GCC supports these options when you're compiling for C-SKY V2 processors 💖
-march=arch— Picks the C-SKY target architecture. The valid values forarchareck801,ck802,ck803,ck807, andck810. The default isck810👑-mcpu=cpu— Picks the C-SKY target processor. The valid values forcpuareck801,ck801t,ck802,ck802t,ck802j,ck803,ck803h,ck803t,ck803ht,ck803f,ck803fh,ck803e,ck803eh,ck803et,ck803eht,ck803ef,ck803efh,ck803ft,ck803eft,ck803efht,ck803r1,ck803hr1,ck803tr1,ck803htr1,ck803fr1,ck803fhr1,ck803er1,ck803ehr1,ck803etr1,ck803ehtr1,ck803efr1,ck803efhr1,ck803ftr1,ck803eftr1,ck803efhtr1,ck803s,ck803st,ck803se,ck803sf,ck803sef,ck803seft,ck807e,ck807ef,ck807,ck807f,ck810e,ck810et,ck810ef,ck810eft,ck810,ck810v,ck810f,ck810t,ck810fv,ck810tv,ck810ft, andck810ftv🎀-mbig-endian,-EB,-mlittle-endian,-EL— Pick big-endian or little-endian code. Little-endian is the default 🌈-mfloat-abi=name— Chooses which floating-point ABI to use. The permissible values aresoft,softfpandhard🔥soft— GCC generates output full of library calls for floating-point operations 🫶softfp— Lets you generate code that uses hardware floating-point instructions, but it still sticks with the soft-float calling conventions ✨hard— Allows floating-point instructions and uses FPU-specific calling conventions 💅
The default depends on the specific target configuration. Heads up: the hard-float and soft-float ABIs are NOT link-compatible. You have to compile your entire program with the same ABI and link it with a compatible set of libraries 😭
-mhard-float,-msoft-float— Pick hardware or software floating-point implementations. The default is soft float 🦋-mdouble-float,-mno-double-float— When-mhard-floatis in effect, this turns on generation of double-precision float instructions. It's the default except when you're compiling for CK803 🌸-mfdivdu,-mno-fdivdu— When-mhard-floatis in effect, this turns on generation of"frecipd","fsqrtd", and"fdivd"instructions. It's the default except when you're compiling for CK803 💖-mfpu=fpu— Selects the floating-point processor. This option can ONLY be used with-mhard-float. The values forfpuarefpv2_sf(equivalent to-mno-double-float -mno-fdivdu),fpv2(-mdouble-float -mno-divdu), andfpv2_divd(-mdouble-float -mdivdu) 🧚-melrw,-mno-elrw— Enables the extended"lrw"instruction. This defaults to on for CK801 and off otherwise 👑-mistack,-mno-istack— Enables interrupt stack instructions. The default is off 🌈
The -mistack option is required if you want to handle the "interrupt" and "isr" function attributes 🫶
-mmp— Enables multiprocessor instructions. The default is off 🍓-mcp— Enables coprocessor instructions. The default is off ⭐-mcache— Enables coprocessor instructions. The default is off 🎀-msecurity— Enables C-SKY security instructions. The default is off 🔥-mtrust— Enables C-SKY trust instructions. The default is off 💜-mdsp,-medsp,-mvdsp— Enable C-SKY DSP, Enhanced DSP, or Vector DSP instructions, respectively. All of these default to off 🦋-mdiv,-mno-div— Generates divide instructions. The default is off 🌸-msmart,-mno-smart— Generates code for Smart Mode, which only uses registers numbered 0-7 so you can use 16-bit instructions 💅 This option is ignored for CK801, where this is the required behavior, and it defaults to on for CK802. For other targets, the default is off.-mhigh-registers,-mno-high-registers— Generates code using the high registers numbered 16-31 ✨ This option is not supported on CK801, CK802, or CK803, and it's enabled by default for other processors.-manchor,-mno-anchor— Generates code using global anchor symbol addresses 🧚-mpushpop,-mno-pushpop— Generates code using"push"and"pop"instructions. This option defaults to on 🍓-mmultiple-stld,-mstm,-mno-multiple-stld,-mno-stm— Generates code using"stm"and"ldm"instructions. This option isn't supported on CK801, but it's enabled by default on other processors 💖-mconstpool,-mno-constpool— Creates constant pools in the compiler instead of handing that job off to the assembler 🫶 This option is the default and is required for correct code generation on CK801 and CK802. It's optional on other processors.-mstack-size,-mno-stack-size— Emits".stack_size"directives for each function in the assembly output. This option defaults to off 🌈-mccrt,-mno-ccrt— Generates code for the C-SKY compiler runtime instead of libgcc. This option defaults to off 👑-mbranch-cost=n— Sets the branch costs to roughly"n"instructions. The default is 1 🦋-msched-prolog,-mno-sched-prolog— Permits scheduling of function prologue and epilogue sequences. It's disabled by default.
Warning, bestie!! Using this option can result in code that isn't compliant with the C-SKY V2 ABI prologue requirements, and that code can't be debugged or backtraced. Proceed with caution 😭
-msim— Links the librarylibsemi.a, which is compatible with the simulator. This only applies to the ELF compiler 🔥
🍎 Darwin Options 🍎
These options are defined for all architectures running the Darwin operating system 🌸
FSF GCC on Darwin does NOT create "fat" object files. Instead, it creates an object file for the single architecture that GCC was built to target. Apple's GCC on Darwin, on the other hand, DOES create "fat" files if you use multiple -arch options. It does this by running the compiler or linker multiple times and then joining the results together with lipo 💅
The subtype of the file it creates (like ppc7400 or ppc970 or i686) is determined by the flags that specify the ISA GCC is targeting, like -mcpu or -march. The -force_cpusubtype_ALL option can be used to override this 👑
The Darwin tools behave differently when they're presented with an ISA mismatch. The assembler, as, only lets you use instructions that are valid for the subtype of the file it's generating, so you can't put 64-bit instructions in a ppc750 object file 💀 The linker for shared libraries, /usr/bin/libtool, fails and prints an error if you ask it to create a shared library with a less restrictive subtype than its input files. For instance, trying to put a ppc970 object file in a ppc7400 library will get rejected 🙈 The linker for executables, ld, quietly gives the executable the most restrictive subtype of any of its input files 🤫
-Fdir— Adds the framework directorydirto the HEAD of the list of directories searched for header files 🧚 These directories are interleaved with the ones specified by-Ioptions, and they're scanned in a left-to-right order.
So what even is a framework directory? It's a directory with frameworks in it 💖 A framework is a directory that has a Headers and/or PrivateHeaders directory sitting directly inside it, and its name ends in .framework. The name of a framework is the name of that directory minus the .framework part. Headers for the framework are found in one of those two directories, and Headers gets searched first ✨
A subframework is a framework directory that lives inside a framework's Frameworks directory. Includes of subframework headers can only show up in a header of the framework that contains the subframework, or in a sibling subframework header. Two subframeworks are siblings if they occur in the same framework 🫶 A subframework should NOT have the same name as a framework, and a warning is issued if that rule gets broken 😭 Right now a subframework can't have subframeworks of its own, but the mechanism may be extended to support that in the future 🌈
The standard frameworks live in /System/Library/Frameworks and /Library/Frameworks 👑 An example include looks like #include <Framework/header.h>, where Framework is the name of the framework and header.h is found in the PrivateHeaders or Headers directory 🦋
-iframeworkdir— This is like-F, except the directory is treated as a system directory 🌸 The main difference is that with-iframework, the compiler does NOT warn about constructs contained within header files found viadir. This option is only valid for the C family of languages 💅-gused— Emits debugging information for symbols that are used. For the stabs debugging format, this enables-feliminate-unused-debug-symbols. This is ON by default ⭐-gfull— Emits debugging information for ALL symbols and types 🔥-fconstant-cfstrings— This is an alias for-mconstant-cfstrings🎀-mconstant-cfstrings— When the NeXT runtime is being used (which is the default on these systems), this overrides any-fconstant-string-classsetting and makes"@"...""literals get laid out as constant CoreFoundation strings 💖-mmacosx-version-min=version— The earliest version of MacOS X that this executable will run on isversion🍓 Typical values supported forversioninclude12,10.12, and10.5.8.
If the compiler was built to use the system's headers by default, then the default for this option is the system version the compiler is running on 🧚 Otherwise, the default is to make choices that are compatible with as many systems and code bases as possible 🌈
-mkernel— 🧚 Okay bestie, this one switches on kernel development mode ✨. It sets-static,-fno-common,-fno-use-cxa-atexit,-fno-exceptions,-fno-non-call-exceptions,-fapple-kext,-fno-weakand-fno-rttiwhere applicable. For PowerPC targets it also sets-mno-altivec,-msoft-float,-fno-builtinand-mlong-branch💅-mone-byte-bool— 🦋 This one overrides the defaults forboolso thatsizeof(bool)==1. By default, sizeof(bool) is 4 when compiling for Darwin/PowerPC and 1 when compiling for Darwin/x86, so it does absolutely nothing on x86 🙈
Warning: The -mone-byte-bool switch causes GCC to generate code that is not binary compatible with code generated without that switch. Using this switch may require recompiling all other modules in a program, including system libraries. Use this switch to conform to a non-default data model. 💀
-mfix-and-continue,-ffix-and-continue,-findirect-data— 🔥 These generate code built for fast turnaround development, like letting GDB dynamically load.ofiles into programs that are already running 🌈-findirect-dataand-ffix-and-continueonly stick around for backwards compatibility, so bestie, you probably want-mfix-and-continue🫶-all_load— 🌸 Loads every member of static archive libraries. Check outman ld(1)for the full tea ☕-arch_errors_fatal— 💀 Makes the errors about files with the wrong architecture fatal. No warnings-and-keep-going, it's game over 🎀-bind_at_load— ⭐ Marks the output file so the dynamic linker binds all undefined references when the file gets loaded or launched 🧚-bundle— 🍓 Produces a Mach-o bundle format file. Peek atman ld(1)for more info 💜-bundle_loaderexecutable — 👑 Specifies the executable that will load the build output file being linked. Again,man ld(1)has the details ✨-dynamiclib— 🌈 Passes the Darwin libtool command so GCC makes a dynamic library instead of an executable when linking 🦋-force_cpusubtype_ALL— 💅 Gives GCC's output file the ALL subtype, instead of the one controlled by the-mcpuor-marchoption 🫶-nodefaultrpaths— 🙈 Stops default run paths for the compiler library directories from getting added to executables, modules or dynamic libraries. On macOS 10.5 and later, the embedded runpath gets added by default unless you pass-nodefaultrpathson the link line. Run paths are needed (and therefore enforced) to build on macOS 10.11 or later 🍓
These options are passed to the Darwin linker, and the Darwin linker man page describes them in detail. Here's the whole lineup 💖
-allowable_clientclient_name — 🌸 Passed to the Darwin linker, which has the full details-client_name— 🌸 Passed to the Darwin linker, which has the full details-compatibility_version— 🌸 Passed to the Darwin linker, which has the full details-current_version— 🌸 Passed to the Darwin linker, which has the full details-dead_strip— 🌸 Passed to the Darwin linker, which has the full details-dependency-file— 🌸 Passed to the Darwin linker, which has the full details-dylib_file— 🌸 Passed to the Darwin linker, which has the full details-dylinker_install_name— 🌸 Passed to the Darwin linker, which has the full details-dynamic— 🌸 Passed to the Darwin linker, which has the full details-exported_symbols_list— 🌸 Passed to the Darwin linker, which has the full details-filelist— 🌸 Passed to the Darwin linker, which has the full details-flat_namespace— 🌸 Passed to the Darwin linker, which has the full details-force_flat_namespace— 🌸 Passed to the Darwin linker, which has the full details-headerpad_max_install_names— 🌸 Passed to the Darwin linker, which has the full details-image_base— 🌸 Passed to the Darwin linker, which has the full details-init— 🌸 Passed to the Darwin linker, which has the full details-install_name— 🌸 Passed to the Darwin linker, which has the full details-keep_private_externs— 🌸 Passed to the Darwin linker, which has the full details-multi_module— 🌸 Passed to the Darwin linker, which has the full details-multiply_defined— 🌸 Passed to the Darwin linker, which has the full details-multiply_defined_unused— 🌸 Passed to the Darwin linker, which has the full details-noall_load— 🌸 Passed to the Darwin linker, which has the full details-no_dead_strip_inits_and_terms— 🌸 Passed to the Darwin linker, which has the full details-nofixprebinding— 🌸 Passed to the Darwin linker, which has the full details-nomultidefs— 🌸 Passed to the Darwin linker, which has the full details-noprebind— 🌸 Passed to the Darwin linker, which has the full details-noseglinkedit— 🌸 Passed to the Darwin linker, which has the full details-pagezero_size— 🌸 Passed to the Darwin linker, which has the full details-prebind— 🌸 Passed to the Darwin linker, which has the full details-prebind_all_twolevel_modules— 🌸 Passed to the Darwin linker, which has the full details-private_bundle— 🌸 Passed to the Darwin linker, which has the full details-read_only_relocs— 🌸 Passed to the Darwin linker, which has the full details-sectalign— 🌸 Passed to the Darwin linker, which has the full details-sectobjectsymbols— 🌸 Passed to the Darwin linker, which has the full details-whyload— 🌸 Passed to the Darwin linker, which has the full details-seg1addr— 🌸 Passed to the Darwin linker, which has the full details-sectcreate— 🌸 Passed to the Darwin linker, which has the full details-sectobjectsymbols— 🌸 Passed to the Darwin linker, which has the full details-sectorder— 🌸 Passed to the Darwin linker, which has the full details-segaddr— 🌸 Passed to the Darwin linker, which has the full details-segs_read_only_addr— 🌸 Passed to the Darwin linker, which has the full details-segs_read_write_addr— 🌸 Passed to the Darwin linker, which has the full details-seg_addr_table— 🌸 Passed to the Darwin linker, which has the full details-seg_addr_table_filename— 🌸 Passed to the Darwin linker, which has the full details-seglinkedit— 🌸 Passed to the Darwin linker, which has the full details-segprot— 🌸 Passed to the Darwin linker, which has the full details-segs_read_only_addr— 🌸 Passed to the Darwin linker, which has the full details-segs_read_write_addr— 🌸 Passed to the Darwin linker, which has the full details-single_module— 🌸 Passed to the Darwin linker, which has the full details-static— 🌸 Passed to the Darwin linker, which has the full details-sub_library— 🌸 Passed to the Darwin linker, which has the full details-sub_umbrella— 🌸 Passed to the Darwin linker, which has the full details-twolevel_namespace— 🌸 Passed to the Darwin linker, which has the full details-umbrella— 🌸 Passed to the Darwin linker, which has the full details-undefined— 🌸 Passed to the Darwin linker, which has the full details-unexported_symbols_list— 🌸 Passed to the Darwin linker, which has the full details-weak_reference_mismatches— 🌸 Passed to the Darwin linker, which has the full details-whatsloaded— 🌸 Passed to the Darwin linker, which has the full details
🦋 DEC Alpha Options 🦋
These -m options are defined for the DEC Alpha implementations 💎
-mno-soft-float,-msoft-float— ✨ Use (or don't use) the hardware floating-point instructions for floating-point operations. With-msoft-float, functions inlibgcc.ado the floating-point work. Unless they're replaced by routines that emulate those operations, or compiled to call such emulation routines, these routines issue floating-point operations. If you're compiling for an Alpha without floating-point operations, you must make sure the library is built so it doesn't call them 🙈
Note that Alpha implementations without floating-point operations are required to have floating-point registers 🫶
-mfp-reg,-mno-fp-regs— 🌈 Generate code that uses (or doesn't use) the floating-point register set.-mno-fp-regsimplies-msoft-float. If the floating-point register set isn't used, floating-point operands get passed in integer registers as if they were integers, and floating-point results get passed in$0instead of$f0. This is a non-standard calling sequence, so any function with a floating-point argument or return value called by code compiled with-mno-fp-regsmust also be compiled with that option 💀
A typical use of this option is building a kernel that doesn't use, and so doesn't need to save and restore, any floating-point registers 👑
-mieee— 💖 The Alpha architecture has floating-point hardware tuned for maximum performance, and it's mostly IEEE compliant. For full compliance, though, it needs software help. This option generates fully IEEE-compliant code, except the inexact-flag isn't maintained (see below). When it's turned on, the preprocessor macro_IEEE_FPgets defined during compilation. The resulting code is less efficient, but it can correctly support denormalized numbers and exceptional IEEE values like not-a-number and plus/minus infinity. Other Alpha compilers call this option-ieee_with_no_inexact🔥
DEBIAN SPECIFIC: This option is on by default for alpha-linux-gnu, unless -ffinite-math-only (which is part of the -ffast-math set) is specified. The reason is that the software functions in the GNU libc math libraries generate denormalized numbers, NaNs, and infs, and all of those will cause a program to SIGFPE when it tries to use the results without -mieee 😭
-mieee-with-inexact— 🍓 This is like-mieee, except the generated code also maintains the IEEE inexact-flag. Turning it on makes the generated code fully-compliant IEEE math. Along with_IEEE_FP, the preprocessor macro_IEEE_FP_EXACTis defined. On some Alpha implementations the resulting code may run significantly slower than the default. Very little code depends on the inexact-flag, so you should normally not specify this option 🧚 Other Alpha compilers call this option-ieee_with_inexact✨-mfp-trap-mode=trap-mode— 🎀 Controls which floating-point related traps are enabled. Other Alpha compilers call this option-fptm trap-mode. The trap mode can be set to one of four values:n— The default (normal) setting. The only traps enabled are the ones that can't be disabled in software (for example, the division by zero trap) 💅u— In addition to the traps enabled byn, underflow traps are enabled as well 🌸su— Likeu, but the instructions are marked as safe for software completion (see the Alpha architecture manual for details) 🦋sui— Likesu, but inexact traps are enabled as well 🔥
-mfp-rounding-mode=rounding-mode— 🌈 Selects the IEEE rounding mode. Other Alpha compilers call this option-fprm rounding-mode. The rounding-mode can be one of:n— Normal IEEE rounding mode. Floating-point numbers are rounded towards the nearest machine number, or towards the even machine number in case of a tie 💖m— Round towards minus infinity 📉c— Chopped rounding mode. Floating-point numbers are rounded towards zero ✂️d— Dynamic rounding mode. A field in the floating-point control register (fpcr, see the Alpha architecture reference manual) controls the rounding mode in effect. The C library initializes this register for rounding towards plus infinity. So unless your program modifies the fpcr,dcorresponds to round towards plus infinity 🧚
-mtrap-precision=trap-precision— 🌸 On the Alpha architecture, floating-point traps are imprecise. Without software help, that means it's impossible to recover from a floating trap, and program execution normally has to be terminated. GCC can generate code that helps operating system trap handlers figure out the exact location that caused a floating-point trap. Depending on what your application needs, you can pick different levels of precision:p— Program precision. This is the default, and it means a trap handler can only identify which program caused a floating-point exception 🙈f— Function precision. The trap handler can determine the function that caused a floating-point exception 🫶i— Instruction precision. The trap handler can determine the exact instruction that caused a floating-point exception 👑
Other Alpha compilers provide the equivalent options called -scope_safe and -resumption_safe ✨
-mieee-conformant— 💜 Marks the generated code as IEEE conformant. You must not use this option unless you also specify-mtrap-precision=iand either-mfp-trap-mode=suor-mfp-trap-mode=sui. Its only effect is to emit the line.eflag 48in the function prologue of the generated assembly file 💀-mbuild-constants— 🧚 Normally, GCC examines a 32- or 64-bit integer constant to see if it can build it from smaller constants in two or three instructions. If it can't, it outputs the constant as a literal and generates code to load it from the data segment at run time. Use this option to make GCC build all integer constants using code, even if it takes more instructions (the maximum is six). You typically use this option to build a shared library dynamic loader. Since it's itself a shared library, it has to relocate itself in memory before it can find the variables and constants in its own data segment 🌈-mbwx,-mno-bwx,-mcix,-mno-cix,-mfix,-mno-fix,-mmax,-mno-max— okay so these are your on/off switches for the optional BWX, CIX, FIX and MAX instruction sets ✨. By default GCC uses whatever the CPU type from-mcpu=supports, or the CPU GCC was built on if you didn't pick one 🫶.-mfloat-vax,-mfloat-ieee— this one decides whether the code uses VAX F and G floating-point arithmetic (-mfloat-vax) or sticks with IEEE single and double precision (-mfloat-ieee) 🌸.-mexplicit-relocs,-mno-explicit-relocs— ngl this one has a whole backstory 📖. Older Alpha assemblers couldn't make symbol relocations except through assembler macros, and those macros don't let the instruction scheduling be optimal 💀. GNU binutils 2.12 and newer has a new syntax that lets the compiler explicitly mark which relocations go with which instructions. This is mostly a debugging tool, since GCC checks what the assembler can do when it's built and sets the default to match 🔥.-msmall-data,-mlarge-data— when-mexplicit-relocsis on, static data is reached through gp-relative relocations 🧚.- With
-msmall-data, objects 8 bytes or smaller get tucked into a small data area (the".sdata"and".sbss"sections) and are accessed through 16-bit relocations off the$gpregister. That caps the small data area at 64KB, but the variables can be reached with a single instruction 💖. - The default is
-mlarge-data. With this option the data area is limited to just below 2GB. Programs that need more than 2GB of data have to use"malloc"or"mmap"to put the data on the heap instead of in the program's data segment 😭. - When generating code for shared libraries,
-fpicimplies-msmall-dataand-fPICimplies-mlarge-data🌈.
- With
-msmall-text,-mlarge-text— with-msmall-text, the compiler assumes the code for the whole program (or shared library) fits in 4MB, so it's reachable with a branch instruction 🦋. If-msmall-datais also used, the compiler can assume all local symbols share the same$gpvalue, which cuts the instructions needed for a function call from 4 down to 1 ✨.- The default is
-mlarge-text.
- The default is
-mcpu=cpu_type— sets the instruction set and instruction scheduling parameters for the machine typecpu_type👑. You can use either the EV style name or the matching chip number. GCC has scheduling parameters for the EV4, EV5 and EV6 families and picks the default instruction set from the processor you name. No processor type? GCC defaults to the one it was built on.- Supported values for
cpu_typeare:ev4,ev45,21064— schedules as an EV4 and has no instruction set extensions.ev5,21164— schedules as an EV5 and has no instruction set extensions.ev56,21164a— schedules as an EV5 and supports the BWX extension.pca56,21164pc,21164PC— schedules as an EV5 and supports the BWX and MAX extensions.ev6,21264— schedules as an EV6 and supports the BWX, FIX, and MAX extensions.ev67,21264a— schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
- Native toolchains also support
native, which picks the best architecture option for the host processor.-mcpu=nativedoes nothing if GCC doesn't recognize the processor 🙈.
- Supported values for
-mtune=cpu_type— only sets the instruction scheduling parameters forcpu_type. The instruction set stays exactly the same 🍓.- Native toolchains also support
native, which picks the best architecture option for the host processor.-mtune=nativedoes nothing if GCC doesn't recognize the processor.
- Native toolchains also support
-mmemory-latency=time— sets the latency the scheduler should assume for typical memory references as the application sees them ⏱️. That number really depends on the app's memory access patterns and the size of the machine's external cache.- Valid options for
timeare:number— a decimal number of clock cycles.L1,L2,L3,main— GCC has estimates of clock cycles for "typical" EV4 & EV5 hardware at the Level 1, 2 & 3 caches (also called Dcache, Scache, and Bcache), plus main memory. Heads up:L3is only valid for EV5 ⚠️.
- Valid options for
🦋 eBPF Options 🦋
-mframe-limit=bytes— sets the hard limit for frame sizes, in bytes 🧁. The value you give should be less than or equal to32767. If you don't set it, the limit is whatever the targeted version of the Linux kernel imposes.-mbig-endian— generates code for a big-endian target 🌈.-mlittle-endian— generates code for a little-endian target. This is the default 💜.-mjmpext,-mno-jmpext— turns the extra conditional-branch instructions on or off. Enabled for CPU v2 and above 🔥.-mjmp32,-mno-jmp32— turns 32-bit jump instructions on or off. Enabled for CPU v3 and above.-malu32,-mno-alu32— turns 32-bit ALU instructions on or off. Enabled for CPU v3 and above.-mv3-atomics,-mno-v3-atomics— turns the general atomic operations introduced in CPU v3 on or off. Enabled for CPU v3 and above.-mbswap,-mno-bswap— turns byte swap instructions on or off. Enabled for CPU v4 and above.-msdiv,-mno-sdiv— turns signed division and modulus instructions on or off. Enabled for CPU v4 and above.-msmov,-mno-smov— turns sign-extending move and memory load instructions on or off. Enabled for CPU v4 and above.-mcpu=version— picks which version of the eBPF ISA you're targeting 💅. Newer versions might not be supported by every kernel. The default isv4.- Supported values for
versionare:v1— the first stable eBPF ISA, with no special features or extensions.v2— supports the jump extensions, as in-mjmpext.v3— all the features of v2, plus:-<32-bit jump operations, as in -mjmp32>-<32-bit ALU operations, as in -malu32>-<general atomic operations, as in -mv3-atomics>
v4— all the features of v3, plus:-<Byte swap instructions, as in -mbswap>-<Signed division and modulus instructions, as in -msdiv>-<Sign-extending move and memory load instructions, as in -msmov>
- Supported values for
-mco-re— enables BPF Compile Once - Run Everywhere (CO-RE) support 🧩. Requires and is implied by-gbtf.-mno-co-re— disables BPF CO-RE support 🙅. BPF CO-RE support is turned on by default when you generate BTF debug information for the BPF target.-mxbpf— generates code for an expanded version of BPF that relaxes some of the usual BPF restrictions ✨.-<Save and restore callee-saved registers at function entry and exit, respectively.>
-masm=dialect— outputs assembly instructions in the eBPF dialect you select. The default isnormal.- Supported values for
dialectare:normal— outputs the normal assembly dialect.pseudoc— outputs the pseudo-c assembly dialect.
- Supported values for
-minline-memops-threshold=bytes— sets a size threshold in bytes, at or below whichmemmove,memcpyandmemsetalways get expanded inline 🧠. Anything bigger would need a library call instead of inline expansion, but BPF doesn't allow libcalls, so going over the threshold gives a compile-time error. The default is1024bytes.
Going over this threshold is a compile-time error 💀, because BPF doesn't allow libcalls.
🌈 FR30 Options 🌈
These options are defined specifically for the FR30 port 🎀.
-msmall-model— uses the small address space model 🧸. This can produce smaller code, but it assumes that all symbolic values and addresses fit into a 20-bit range.-mno-lsim— assumes runtime support has already been provided, so there's no need to include the simulator library (libsim.a) on the linker command line.
💜 FT32 Options 💜
These options are defined specifically for the FT32 port 🦋.
-msim— says the program will run on the simulator. This links in an alternate runtime startup and library.
You must not use this option when generating programs that will run on real hardware 🚫. You have to provide your own runtime library for whatever I/O functions you need.
-mlra— enables Local Register Allocation. It's still experimental for FT32, so by default the compiler uses standard reload.-mnodiv— don't usedivandmodinstructions.-mft32b— enables the extended instructions of the FT32B processor.-mcompress— compresses all code using the Ft32B code compression scheme 🗜️.-mnopm— don't generate code that reads program memory.
🍓 FRV Options 🍓
-mgpr-32— only use the first 32 general-purpose registers.-mgpr-64— use all 64 general-purpose registers.-mfpr-32— only use the first 32 floating-point registers.-mfpr-64— use all 64 floating-point registers.-mhard-float— use hardware instructions for floating-point operations.-msoft-float— use library routines for floating-point operations.-malloc-cc— dynamically allocate condition code registers.-mfixed-cc— don't try to dynamically allocate condition code registers. Only use"icc0"and"fcc0".-mdword— changes the ABI to use double word instructions.-mno-dword— don't use double word instructions.-mdouble— use floating-point double instructions.-mno-double— don't use floating-point double instructions.-mmedia— use media instructions.-mno-media— don't use media instructions.-mmuladd— use multiply and add/subtract instructions.-mno-muladd— don't use multiply and add/subtract instructions.-mfdpic— 🦋 Okay so this picks the FDPIC ABI, which uses function descriptors to stand in for pointers to functions. With no PIC/PIE options at all, it implies-fPIE. With-fpicor-fpie, GOT entries and small data are assumed to sit within a 12-bit range from the GOT base address. With-fPICor-fPIE, GOT offsets get computed with 32 bits. On a bfin-elf target, this also implies-msim💅-minline-plt— ✨ This turns on inlining of PLT entries for function calls to functions that aren't known to bind locally. It does nothing without-mfdpic. It's on by default when you're optimizing for speed and compiling shared libraries (that's-fPICor-fpic), or when something like-O3or higher shows up on the command line 🔥-mTLS— 🌸 Assumes a large TLS segment when generating thread-local code.-mtls— 🍓 The opposite energy: does not assume a large TLS segment when generating thread-local code.-mgprel-ro— 🧚 This enables "GPREL" relocations in the FDPIC ABI for data known to be in read-only sections. It's on by default, except with-fpicor-fpie. Even though it might shrink the global offset table, it trades 1 instruction for 4 there. With-fPICor-fPIE, it trades 3 instructions for 4 (one of which can be shared by multiple symbols), and it skips needing a GOT entry for the referenced symbol, so it's more likely to be a win 👑 If it isn't,-mno-gprel-roturns it off.-multilib-library-pic— 📚 Links with the (library, not FD) pic libraries. It's implied by-mlibrary-pic, and also by-fPICand-fpicwithout-mfdpic. You should basically never have to use it explicitly 🙈-mlinked-fp— 🎀 Follows the EABI rule of always creating a frame pointer whenever a stack frame gets allocated. It's on by default, and you can turn it off with-mno-linked-fp.-mlong-calls— 🌈 Uses indirect addressing to call functions outside the current compilation unit. This lets those functions live anywhere in the 32-bit address space.-malign-labels— 🫶 Tries to align labels to an 8-byte boundary by slipping NOPs into the previous packet. This only does anything when VLIW packing is enabled. It doesn't make new packets, it just adds NOPs to packets that already exist.-mlibrary-pic— 💜 Generates position-independent EABI code.-macc-4— 🦋 Uses only the first four media accumulator registers.-macc-8— 🔥 Uses all eight media accumulator registers.-mpack— 💖 Packs VLIW instructions.-mno-pack— 🙅♀️ Does not pack VLIW instructions.-mno-eflags— 🌸 Does not mark ABI switches ine_flags.-mcond-move— ✨ Enables conditional-move instructions (this is the default). 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mno-cond-move— 💅 Disables conditional-move instructions. 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mscc— 🧠 Enables conditional set instructions (default). 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mno-scc— 🚫 Disables conditional set instructions. 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mcond-exec— 🍓 Enables conditional execution (default). 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mno-cond-exec— 🙈 Disables conditional execution. 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mvliw-branch— 🧚 Runs a pass that packs branches into VLIW instructions (default). 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mno-vliw-branch— 🌈 Does not run the pass that packs branches into VLIW instructions. 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mmulti-cond-exec— 👑 Enables optimization of"&&"and"||"in conditional execution (default). 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mno-multi-cond-exec— 💀 Disables optimization of"&&"and"||"in conditional execution. 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mnested-cond-exec— 🦋 Enables nested conditional execution optimizations (default). 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-mno-nested-cond-exec— 🫶 Disables nested conditional execution optimizations. 🛠️ This switch is mainly for debugging the compiler and will likely be removed in a future version.-moptimize-membar— 🧹 This one cleans house by removing redundant"membar"instructions from the compiler-generated code. It's enabled by default.-mno-optimize-membar— 🙅♀️ Turns off that automatic removal of redundant"membar"instructions from the generated code.-mtomcat-stats— 📊 Makes gas print out tomcat statistics.-mcpu=cpu— 💖 Picks the processor type you want code generated for. The possible values arefrv,fr550,tomcat,fr500,fr450,fr405,fr400,fr300andsimple💅
✨ GNU/Linux Options ✨
Okay, these -m options are defined just for GNU/Linux targets 🐧
-mglibc— 👑 Uses the GNU C library. This is the default, except on*-*-linux-*uclibc*,*-*-linux-*musl*and*-*-linux-*android*targets.-muclibc— 🌸 Uses the uClibc C library. This is the default on*-*-linux-*uclibc*targets.-mmusl— 🦋 Uses the musl C library. This is the default on*-*-linux-*musl*targets.-mbionic— 🤖 Uses the Bionic C library. This is the default on*-*-linux-*android*targets.-mandroid— 📱 Compiles code that's compatible with the Android platform. This is the default on*-*-linux-*android*targets. When compiling, this option turns on-mbionic,-fPIC,-fno-exceptionsand-fno-rttiby default. When linking, it makes the GCC driver pass Android-specific options to the linker. It also causes the preprocessor macro"__ANDROID__"to be defined 🫶-tno-android-cc— 🙅♀️ Turns off the compilation effects of-mandroid. So it does not enable-mbionic,-fPIC,-fno-exceptionsand-fno-rttiby default.-tno-android-ld— 🔗 Turns off the linking effects of-mandroid, so standard Linux linking options get passed to the linker.
✨ H8/300 Options ✨
These -m options are defined for the H8/300 implementations 🧚
-mrelax— 💜 Shortens some address references at link time, when that's possible. It uses the linker option-relax.-mh— 🌈 Generates code for the H8/300H.-ms— 🔥 Generates code for the H8S.-mn— 🎀 Generates code for the H8S and H8/300H in the normal mode. This switch has to be used with either-mhor-ms.-ms2600— ⭐ Generates code for the H8S/2600. This switch has to be used with-ms.-mexr— 🧠 Extended registers get stored on the stack before a function with the monitor attribute runs. The default is-mexr. This option is only valid for H8S targets.-mno-exr— 🚫 Extended registers do not get stored on the stack before a function with the monitor attribute runs. The default is-mno-exr. This option is only valid for H8S targets.-mint32— 💖 Makes"int"data 32 bits by default.-malign-300— 📏 On the H8/300H and H8S, this uses the same alignment rules as the H8/300. By default, the H8/300H and H8S align longs and floats on 4-byte boundaries, but-malign-300makes them align on 2-byte boundaries instead. It has no effect on the H8/300.
✨ HPPA Options ✨
These -m options are defined for the HPPA family of computers 🖥️
-march=architecture-type— 🦋 Generates code for the specified architecture. The choices for architecture-type are1.0for PA 1.0,1.1for PA 1.1, and2.0for PA 2.0 processors. To figure out the right architecture option for your machine, check/usr/lib/sched.modelson an HP-UX system. Code compiled for lower numbered architectures runs on higher numbered ones, but not the other way around 💅-mpa-risc-1-0,-mpa-risc-1-1,-mpa-risc-2-0— 👯 These are synonyms for-march=1.0,-march=1.1, and-march=2.0respectively.-matomic-libcalls— ⚛️ Generates libcalls for atomic loads and stores when sync libcalls are disabled. This is enabled by default, and it only affects atomic libcall generation by the HPPA backend. Both the sync and libatomic libcall implementations use locking, so processor stores aren't atomic with respect to other atomic operations. Processor loads up to DImode are atomic with respect to other atomic operations, as long as they're implemented as a single access. The PA-RISC architecture doesn't support any atomic operations in hardware except for the"ldcw"instruction. So all atomic support is implemented using sync and atomic libcalls. Sync libcall support lives inlibgcc.a, and atomic libcall support lives inlibatomic. This option generates"__atomic_exchange"calls for atomic stores. It also gives special handling to atomic DImode accesses on 32-bit targets 🔥-mbig-switch— 🤷♀️ Does nothing. It's only kept around for backward compatibility.-mcaller-copies— 📦 The caller copies function arguments that get passed by hidden reference. Use this with care, because it isn't compatible with the default 32-bit runtime. Only aggregates larger than eight bytes are passed by hidden reference, though, and this option gives better compatibility with OpenMP 🫶-mcoherent-ldcw— 🧊 Uses theldcw/ldcdcoherent cache-control hint.-mdisable-fpregs— 🚫 Disables floating-point registers. It's equivalent to"-msoft-float".-mdisable-indexing— 🙈 Stops the compiler from using indexing address modes. This avoids some pretty obscure problems when compiling MIG generated code under MACH.-mfast-indirect-calls— 🚀 Generates code that assumes calls never cross space boundaries, so GCC can emit code that makes indirect calls faster.
⚠️ Heads up, bestie: this option does not work in the presence of shared libraries or nested functions. Don't use it there!
-mfixed-range=register-range— okay so this one tells GCC to treat the register range you give it as fixed registers 🔒, which means the register allocator is not allowed to touch them. It's super handy when compiling kernel code 💻. A register range is two registers separated by a dash, and you can list several ranges separated by a comma ✨.-mgas— turns on assembler directives that only GAS understands 🧚-mgnu-ld— this one uses options specific to GNU ld 🦋 and passes-sharedto ld when you build a shared library. It's the default when GCC is configured (explicitly or implicitly) with the GNU linker. Just so you know, it doesn't change which ld gets called. It only changes the parameters that get passed to it 🙈- The ld that gets called is decided by the
--with-ldconfigure option, then GCC's program search path, and finally yourPATH. - You can print the linker GCC uses with which
gcc -print-prog-name=ld. - This option is only available on the 64-bit HP-UX GCC, i.e. configured with
hppa*64*-*-hpux*.
- The ld that gets called is decided by the
-mhp-ld— the HP version of the GNU ld vibe 💅 It passes-bto ld when building a shared library and passes+Accept TypeMismatchto ld on all links. It's the default when GCC is configured (explicitly or implicitly) with the HP linker 🌸- Same deal as above: this doesn't change which ld is called, only the parameters passed to it.
- The ld that is called is determined by the
--with-ldconfigure option, GCC's program search path, and finally by the user'sPATH. - The linker GCC uses can be printed using which
gcc -print-prog-name=ld. - This option is only available on the 64-bit HP-UX GCC, i.e. configured with
hppa*64*-*-hpux*.
-mlinker-opt— enables the optimization pass in the HP-UX linker 🔥
⚠️ bestie, this makes symbolic debugging impossible 😭 It also triggers a bug in the HP-UX 8 and HP-UX 9 linkers, where they give bogus error messages when linking some programs. Not it. 💀
-mlong-calls— generates code that uses long call sequences 📞 This makes sure a call can always reach linker-generated stubs ✨ By default, long calls are only generated when the distance from the call site to the beginning of the function or translation unit (whichever applies) goes over a predefined limit set by the branch type being used.- The limits for normal calls are 7,600,000 and 240,000 bytes, respectively, for the PA 2.0 and PA 1.X architectures. Sibcalls are always limited at 240,000 bytes.
- Distances are measured from the beginning of functions when using the
-ffunction-sectionsoption, or when using the-mgasand-mno-portable-runtimeoptions together under HP-UX with the SOM linker. - It's normally not desirable to use this option, since it degrades performance 📉 However, it may be useful in large applications, particularly when partial linking is used to build the application 🧩
- The types of long calls used depend on the capabilities of the assembler and linker, and on the type of code being generated. The impact on systems that support long absolute calls, and long pic symbol-difference or pc-relative calls, should be relatively small. However, an indirect call is used on 32-bit ELF systems in pic code, and it is quite long 🥲
-mlong-load-store— generates 3-instruction load and store sequences, which are sometimes required by the HP-UX 10 linker 🛠️ This is equivalent to the+koption to the HP compilers.-mjump-in-delay— this one is ignored and only here for compatibility purposes 🫶-mno-space-regs— generates code that assumes the target has no space registers 🚀 This lets GCC generate faster indirect calls and use unscaled index address modes. Such code is suitable for level 0 PA systems and kernels 👑-mordered— assumes memory references are ordered, so barriers are not needed 🍓-mportable-runtime— uses the portable calling conventions HP proposed for ELF systems 🌈-mschedule=cpu-type— schedules code according to the constraints for the machine type cpu-type 🗓️ The choices for cpu-type are 700 7100, 7100LC, 7200, 7300 and 8000. If you want to figure out the right scheduling option for your machine, check out/usr/lib/sched.modelson an HP-UX system 🔍 The default scheduling is 8000.-msio— generates the predefine_SIOfor server IO 🖥️ The default is-mwsio. This generates the predefines__hp9000s700,__hp9000s700__and_WSIOfor workstation IO. These options are available under HP-UX and HI-UX 💖-msoft-float— generates output containing library calls for floating point 🎀
⚠️ the requisite libraries are not available for all HPPA targets. Normally the facilities of the machine's usual C compiler are used, but this can't be done directly in cross-compilation. You have to make your own arrangements to provide suitable library functions for cross-compilation 😬
Also, -msoft-float changes the calling convention in the output file, so it's only useful if you compile all of a program with this option 🙅 In particular, you need to compile libgcc.a, the library that comes with GCC, with -msoft-float for this to work.
-msoft-mult— uses software integer multiplication 🧮 This disables the use of thexmpyuinstruction.-munix=unix-std— generates compiler predefines and selects a startfile for the UNIX standard you pick 📚 The choices for unix-std are 93, 95 and 98. 93 is supported on all HP-UX versions. 95 is available on HP-UX 10.10 and later. 98 is available on HP-UX 11.11 and later. The defaults are 93 for HP-UX 10.00, 95 for HP-UX 10.10 through 11.00, and 98 for HP-UX 11.11 and later 🗂️-munix=93provides the same predefines as GCC 3.3 and 3.4.-munix=95provides additional predefines for"XOPEN_UNIX"and"_XOPEN_SOURCE_EXTENDED", and the startfileunix95.o.-munix=98provides additional predefines for"_XOPEN_UNIX","_XOPEN_SOURCE_EXTENDED","_INCLUDE__STDC_A1_SOURCE"and"_INCLUDE_XOPEN_SOURCE_500", and the startfileunix98.o.
🚨 this option changes the interfaces for various library routines, and it also affects the operational behavior of the C library. Thus, extreme care is needed when using it, bestie 💀
Library code that is meant to work with more than one UNIX standard has to test, set and restore the variable "__xpg4_extended_mask" as appropriate. Most GNU software doesn't provide this capability 🥺
-nolibdld— suppresses the generation of link options that searchlibdld.slwhen-staticis specified on HP-UX 10 and later 🙅♀️-static— okay so the HP-UX implementation ofsetlocalein libc depends onlibdld.sl, and there isn't an archive version oflibdld.sl😩 That means when-staticis specified, special link options are needed to resolve this dependency.- On HP-UX 10 and later, the GCC driver adds the necessary options to link with
libdld.slwhen-staticis specified. This causes the resulting binary to be dynamic. On the 64-bit port, the linkers generate dynamic binaries by default in any case. - The
-nolibdldoption can be used to stop the GCC driver from adding these link options.
- On HP-UX 10 and later, the GCC driver adds the necessary options to link with
-threads— adds support for multithreading with the dce thread library under HP-UX 🧵 This option sets flags for both the preprocessor and the linker.
🦋 IA-64 Options 🦋
These are the -m options defined for the Intel IA-64 architecture 💜
-mbig-endian— generates code for a big-endian target 🍑 This is the default for HP-UX.-mlittle-endian— generates code for a little-endian target 🌷 This is the default for AIX5 and GNU/Linux.-mgnu-as,-mno-gnu-as— generates (or doesn't) code for the GNU assembler ✨ This is the default.-mgnu-ld,-mno-gnu-ld— generates (or doesn't) code for the GNU linker 🔗 This is the default.-mno-pic— generates code that does not use a global pointer register 🙃
🚫 the result is not position independent code, and it violates the IA-64 ABI. Use with caution, babe.
-mvolatile-asm-stop,-mno-volatile-asm-stop— generates (or doesn't) a stop bit immediately before and after volatileasmstatements 🛑-mregister-names,-mno-register-names— generates (or doesn't)in,loc, andoutregister names for the stacked registers 📝 This may make assembler output more readable, and honestly it's giving clarity 🧠-mno-sdata,-msdata— disables (or enables) optimizations that use the small data section 🗃️ This may be useful for working around optimizer bugs 🐛-mconstant-gp— generates code that uses a single constant global pointer value 📌 This is useful when compiling kernel code 👩💻-mauto-pic— generates code that is self-relocatable 🔁 This implies-mconstant-gp. It's useful when compiling firmware code 🔧-minline-float-divide-min-latency— generates code for inline divides of floating-point values using the minimum latency algorithm ⚡-minline-float-divide-max-throughput— generates code for inline divides of floating-point values using the maximum throughput algorithm 🚄-mno-inline-float-divide— does not generate inline code for divides of floating-point values 🙅-minline-int-divide-min-latency— generates code for inline divides of integer values using the minimum latency algorithm ⚡-minline-int-divide-max-throughput— generates code for inline divides of integer values using the maximum throughput algorithm 🚄-mno-inline-int-divide— does not generate inline code for divides of integer values 🙅-minline-sqrt-min-latency— generates code for inline square roots using the minimum latency algorithm ⚡-minline-sqrt-max-throughput— generates code for inline square roots using the maximum throughput algorithm 🚄-mno-inline-sqrt— does not generate inline code for"sqrt"🫠-mfused-madd,-mno-fused-madd— does (or doesn't) generate code that uses the fused multiply/add or multiply/subtract instructions 🧪 The default is to use these instructions 💅-mno-dwarf2-asm,-mdwarf2-asm— doesn't (or does) generate assembler code for the DWARF line number debugging info 🗺️ This may be useful when not using the GNU assembler.-mearly-stop-bits,-mno-early-stop-bits— allows stop bits to be placed earlier than immediately preceding the instruction that triggered the stop bit ⏩ This can improve instruction scheduling, but it does not always do so 🤷♀️-mfixed-range=register-range— okay so this one tells the compiler to treat the register range you give it as fixed registers 🔒. A fixed register is one the register allocator isn't allowed to touch. It's super useful when you're compiling kernel code 💻. You write a range as two registers joined by a dash, and you can list several ranges separated by commas ✨.-mtls-size=tls-size— this sets the bit size of immediate TLS offsets 🎀. The valid values are14,22, and64.-mtune=cpu-type— tunes the instruction scheduling for one particular CPU 🦋. The valid values areitanium,itanium1,merced,itanium2, andmckinley.-milp32,-mlp64— these make code for a 32-bit or 64-bit environment 🌸. The 32-bit one setsint,long, and pointers to 32 bits. The 64-bit one setsintto 32 bits andlongand pointers to 64 bits. Heads up: these are HP-UX specific flags 🙈.-mno-sched-br-data-spec,-msched-br-data-spec— the-mno-one disables data speculative scheduling before reload and the plain one turns it on 💅. When it's on you getld.ainstructions plus their check instructions (ld.c/chk.a). It's disabled by default.-msched-ar-data-spec,-mno-sched-ar-data-spec— plain turns on data speculative scheduling after reload, and-mno-turns it off 🔥. This also gives yould.ainstructions with the matching check instructions (ld.c/chk.a). It's enabled by default ✨.-mno-sched-control-spec,-msched-control-spec— the-mno-one disables control speculative scheduling and plain turns it on 🧠. It only works during region scheduling (aka before reload). When it's active you getld.sinstructions pluschk.scheck instructions. It's disabled by default.-msched-br-in-data-spec,-mno-sched-br-in-data-spec— plain enables and-mno-disables speculative scheduling of instructions that depend on data speculative loads before reload 🌈. This only does anything if-msched-br-data-specis turned on. It's enabled by default.-msched-ar-in-data-spec,-mno-sched-ar-in-data-spec— same vibe, but for after reload 💜. Plain enables it and-mno-disables it. It only matters when-msched-ar-data-specis enabled, and it's enabled by default.-msched-in-control-spec,-mno-sched-in-control-spec— plain enables and-mno-disables speculative scheduling of instructions that depend on control speculative loads ⭐. It's only effective when-msched-control-specis enabled, and the default is enabled.-mno-sched-prefer-non-data-spec-insns,-msched-prefer-non-data-spec-insns— if you turn the plain one on, data-speculative instructions only get picked for scheduling when there are no other choices at the moment 🙃. This makes data speculation way more conservative. It's disabled by default.-mno-sched-prefer-non-control-spec-insns,-msched-prefer-non-control-spec-insns— same energy, but for control-speculative instructions 🍓. Turn on the plain one and they're only scheduled when nothing else is available, which makes control speculation much more conservative. It's disabled by default.-mno-sched-count-spec-in-critical-path,-msched-count-spec-in-critical-path— if the plain one is enabled, speculative dependencies get counted when the instruction priorities are computed 🧮. That makes speculation a bit more conservative. It's disabled by default.-msched-spec-ldc— uses a simple data speculation check 🫶. It's on by default.-msched-control-spec-ldc— uses a simple check for control speculation 🌸. It's on by default too.-msched-stop-bits-after-every-cycle— places a stop bit after every cycle when scheduling ⏹️. It's on by default.-msched-fp-mem-deps-zero-cost— assumes floating-point stores and loads won't likely conflict when they end up in the same instruction group 🤞. It's disabled by default.-msel-sched-dont-check-control-spec— generates checks for control speculation in selective scheduling 🔍. Disabled by default.-msched-max-memory-insns=max-insns— puts a limit on how many memory insns can go in one instruction group 🧁. Later memory insns trying to schedule into the same group get lower priority. This is often handy for stopping cache bank conflicts 💀. The default value is1.-msched-max-memory-insns-hard-limit— turns themsched-max-memory-insnslimit into a hard limit 🚫, so you can't go over that number in an instruction group. Without it, the limit is "soft", which means non-memory operations get preferred once the limit is hit, but memory operations can still get scheduled 🌷.
🌈 LM32 Options
These -m options are defined for the LatticeMico32 architecture 👑:
-mbarrel-shift-enabled— enables barrel-shift instructions 🌀.-mdivide-enabled— enables divide and modulus instructions ➗.-mmultiply-enabled— enables multiply instructions ✖️.-msign-extend-enabled— enables sign extend instructions ➕.-muser-enabled— enables user-defined instructions 🧑💻.
🧚 LoongArch Options
These command-line options are defined for LoongArch targets 💖:
-march=cpu-type— tells GCC to generate instructions for a specific machine type 🚀. Here's the tea:-mtune=cpu-typeonly tunes the code for that CPU, but-march=cpu-typelets GCC generate code that might not run at all on other processors 😭. Specifying-march=cpu-typeimplies-mtune=cpu-type, unless noted otherwise. The choices forcpu-typeare:native— picks the CPU to generate code for at compile time by checking the processor type of the machine doing the compiling 🖥️.-march=nativeenables every instruction subset the local machine supports, so the result might not run on other machines.-mtune=nativegives code optimized for the local machine within the limits of the chosen instruction set.loongarch64— a generic CPU with 64-bit extensions 🌟.la464— the LoongArch LA464 CPU, with LBT, LSX, LASX, and LVZ 💅.
-mtune=cpu-type— optimizes the output for the given processor, specified by its microarchitecture name 🎯.-mabi=base-abi-type— generates code for the calling convention you pick 📞.base-abi-typecan be one of:lp64d— uses 64-bit general purpose registers and 32/64-bit floating-point registers for parameter passing 💜. The data model is LP64, whereintis 32 bits andlong intand pointers are 64 bits.lp64f— uses 64-bit general purpose registers and 32-bit floating-point registers for parameter passing 🌸. The data model is LP64, whereintis 32 bits andlong intand pointers are 64 bits.lp64s— uses 64-bit general purpose registers and no floating-point registers for parameter passing 🫧. The data model is LP64, whereintis 32 bits andlong intand pointers are 64 bits.
-mfpu=fpu-type— generates code for the FPU type you specify, which can be one of these 🔧:64— allows hardware floating-point instructions for 32-bit and 64-bit operations 💪.32— allows hardware floating-point instructions for 32-bit operations only 🌙.none,0— stops hardware floating-point instructions from being used 🙅♀️.
-msimd=simd-type— turns on LoongArch SIMD instructions for vectorization and builtin functions ⚡. The value can be one of:lasx— enables generating instructions from the 256-bit LoongArch Advanced SIMD Extension (LASX) and the 128-bit LoongArch SIMD Extension (LSX) 🦄.lsx— enables generating instructions from the 128-bit LoongArch SIMD Extension (LSX) only 🎀.none— no LoongArch SIMD instruction may be generated 🚫.
-msoft-float— forces-mfpu=noneand stops floating-point registers from being used for parameter passing 🫠. This one may change the target ABI.-msingle-float— forces-mfpu=32and lets you use 32-bit floating-point registers for parameter passing 🦋. This one may change the target ABI too.-mdouble-float— forces-mfpu=64and lets you use 32/64-bit floating-point registers for parameter passing 🌈. Also may change the target ABI.-mlasx,-mno-lasx,-mlsx,-mno-lsx— these tweak the scope of the SIMD extensions (none / LSX / LASX) the compiler can use for code generation, one step at a time 🧩. Enabling LASX withmlasxautomatically enables LSX, and disabling LSX withmno-lsxautomatically disables LASX. These are driver-only options. They act on the finalmsimdconfiguration and make incremental changes in the order they show up on the GCC driver's command line, which gives the final, canonicalizedmsimdoption passed to the compiler proper ✨.-mbranch-cost=n— sets the cost of branches to roughlyninstructions 🛣️.-mcheck-zero-division,-mno-check-zero-divison— the first one traps on integer division by zero, and the-mno-one doesn't trap ⚠️. The default is-mcheck-zero-divisionfor-O0or-Og, and-mno-check-zero-divisionfor other optimization levels 🧁.-mcond-move-int,-mno-cond-move-int— conditional moves for integral data in general-purpose registers are enabled by plain and disabled by-mno-🌷. The default is-mcond-move-int.-mcond-move-float,-mno-cond-move-float— same deal for floating-point registers 🌼. Plain enables them and-mno-disables them. The default is-mcond-move-float.-mmemcpy,-mno-memcpy— plain forces the use ofmemcpyfor non-trivial block moves, and-mno-makes sure it isn't forced 🧠. The default is-mno-memcpy, which lets GCC inline most constant-sized copies. Setting the optimization level to-Osalso forcesmemcpy, but-mno-memcpycan override that if you set it explicitly, no matter what order the options appear on the command line 👑.-mstrict-align,-mno-strict-align— the plain one avoids generating memory accesses that might not be aligned on a natural object boundary, as described in the architecture specification, and-mno-allows them 🫶. The default is-mno-strict-align.-msmall-data-limit=number— puts global and static data smaller thannumberbytes into a special section (on some targets) 🍓. The default value is0.-mmax-inline-memcpy-size=*n*— okay bestie, this one tells GCC to inline all block moves (likememcpycalls or structure copies) that are less than or equal to n bytes 📦✨ The default for n is1024.-mcmodel=code-model— lets you pick your code model 💅 The options are:tiny-static— not implemented yet 🙈tiny— not implemented yet 🙈normal— the text segment has to live within a 128MB addressing space, and the data segment has to live within a 2GB addressing space 🌸medium— both the text segment and the data segment have to fit within a 2GB addressing space 🦋large— not implemented yet 🙈extreme— no limits on how big the code segment and data segment can be 🌈
Heads up, bestie:-mcmodel=extremedoes NOT play nicely with-fpltand/or-mexplicit-relocs=none💀
The default code model is normal 💖
-mexplicit-relocs=*style*— this decides when GCC uses assembler relocation operators for symbolic addresses ✨ The other option is assembler macros, which can limit instruction scheduling but still let the linker relax things 🧚 The styles are:none— assembler macros are always used 🙅♀️always— assembler relocation operators are always used 💜auto— the compiler uses relocation operators where linker relaxation is impossible and it helps the code quality, and macros everywhere else 🫶
The default depends on what the assembler can do when GCC gets built, plus the setting of -mrelax. It's -mexplicit-relocs=none if the assembler doesn't support relocation operators at all. It's -mexplicit-relocs=always if the assembler supports them but -mrelax isn't enabled. And it's -mexplicit-relocs=auto if the assembler supports them AND -mrelax is enabled 🔥
-mexplicit-relocs— an alias of-mexplicit-relocs=always, kept around for backward compatibility 🎀-mno-explicit-relocs— an alias of-mexplicit-relocs=none, also kept for backward compatibility 🎀-mdirect-extern-access,-mno-direct-extern-access— this one controls whether the GOT gets used to access external symbols 🧐 The default is-mno-direct-extern-access, so the GOT is used for external symbols with default visibility, but not for other external symbols. With-mdirect-extern-access, the GOT is skipped completely and every external symbol gets PC-relative addressing. This is only suitable where no dynamic linking happens, like firmware, OS kernels, or executables linked with-staticor-static-pie👑 And-mdirect-extern-accessis not compatible with-fPICor-fpic.-mrelax,-mno-relax— takes (or doesn't take) advantage of linker relaxations ✨ If-mpass-mrelax-to-asis enabled, this option gets passed to the assembler too. The default gets figured out when GCC is built, by checking what the assembler supports. It's-mrelaxif the assembler supports both the-mrelaxoption AND conditional branch relaxation. That second part is required, otherwise the.aligndirectives and conditional branch instructions in GCC's assembly output might get rejected by the assembler because of a relocation overflow 😭 Otherwise the default is-mno-relax.-mpass-mrelax-to-as,-mno-pass-mrelax-to-as— passes (or doesn't pass) the-mrelaxor-mno-relaxoption to the assembler 🦋 The default is found at GCC build-time too. It's-mpass-mrelax-to-asif the assembler supports the-mrelaxoption, and-mno-pass-mrelax-to-asotherwise. This one is mostly useful for debugging, or for playing nice with assemblers that aren't the same one used at build-time 🔍-mrecip— this turns on the reciprocal estimate and reciprocal square root estimate instructions, with extra Newton-Raphson steps to boost precision 🧮 It's used instead of doing a divide, or a square root and then a divide, on floating-point arguments. These instructions only get generated when-funsafe-math-optimizationsis enabled together with-ffinite-math-onlyand-fno-trapping-math. It's off by default. Before you use it, make sure the target CPU supports thefrecipeandfrsqrteinstructions 💅 The sequence has higher throughput than the non-reciprocal instruction, BUT the precision can drop by up to 2 ulp (i.e. the inverse of1.0comes out as0.99999994) 💀-mrecip=*opt*— this controls which reciprocal estimate instructions are allowed to be used 🌈 opt is a comma-separated list of options, and any of them can get a!in front to invert it. The choices are:all— enables every estimate instruction 🔥default— enables the default instructions, same as-mrecip🌸none— disables all estimate instructions, same as-mno-recip🙅♀️div— enables the approximation for scalar division ✨vec-div— enables the approximation for vectorized division 🧚sqrt— enables the approximation for scalar square root 🦋vec-sqrt— enables the approximation for vectorized square root 💜rsqrt— enables the approximation for scalar reciprocal square root 🫶vec-rsqrt— enables the approximation for vectorized reciprocal square root 👑
So for example, -mrecip=all,!sqrt turns on ALL of the reciprocal approximations EXCEPT scalar square root 😭
-mfrecipe,-mno-frecipe— uses (or doesn't use) thefrecipe.{s/d}andfrsqrte.{s/d}instructions 🎀 When you build with-march=la664, this is enabled by default. The default otherwise is-mno-frecipe💖-mdiv32,-mno-div32— uses (or doesn't use) thediv.w[u]andmod.w[u]instructions with input that is NOT sign-extended 🧠 When you build with-march=la664, it's enabled by default. The default otherwise is-mno-div32✨-mlam-bh,-mno-lam-bh— uses (or doesn't use) theam{swap/add}[_db].{b/h}instructions 🌸 When you build with-march=la664, it's enabled by default. The default is-mno-lam-bh💅-mlamcas,-mno-lamcas— uses (or doesn't use) theamcas[_db].{b/h/w/d}instructions 🔥 When you build with-march=la664, it's enabled by default. The default is-mno-lamcas🦋-mld-seq-sa,-mno-ld-seq-sa— decides whether a load-load barrier (dbar 0x700) is needed 🧐 When you build with-march=la664, it's enabled by default. The default is-mno-ld-seq-sa, which means the load-load barrier IS needed 🫶-mtls-dialect=*opt*— controls which TLS dialect can be used for the general dynamic and local dynamic TLS models 🌈 The choices are:trad— uses traditional TLS, and this is the default ✨desc— uses TLS descriptors 💜
loongarch-vect-unroll-limit— the vectorizer uses the available tuning info to figure out whether it'd be worth unrolling the main vectorized loop, and by how much 🧚 This sets the upper bound on how much the vectorizer will unroll the main loop. The default value issix🎀
🌸 M32C Options 🌸
-mcpu=name— picks the CPU that code gets generated for 💖 name can be one ofr8cfor the R8C/Tiny series,m16cfor the M16C (up to /60) series,m32cmfor the M16C/80 series, orm32cfor the M32C/80 series ✨-msim— tells GCC the program will run on the simulator 🖥️ This links in an alternate runtime library that supports stuff like file I/O, for example.
Warning, bestie: do NOT use this option when generating programs that will run on real hardware 💀 You have to provide your own runtime library for whatever I/O functions you need.
-memregs=*number*— specifies how many memory-based pseudo-registers GCC uses during code generation 🧠 These get used like real registers, so there's a tradeoff between GCC fitting your code into the available registers and the performance penalty of using memory instead 💅 Every module in a program has to be compiled with the same value for this option. Because of that, you must NOT use this option with GCC's default runtime libraries 🙈
🦋 M32R/D Options 🦋
These -m options are defined for Renesas M32R/D architectures 🧚
-m32r2— generates code for the M32R/2 🌸-m32rx— generates code for the M32R/X 💜-m32r— generates code for the M32R 👑 This is the default ✨-mmodel=small— assumes all objects live in the lower 16MB of memory, so their addresses can be loaded with theld24instruction, and assumes all subroutines are reachable with theblinstruction 🫶 This is the default ✨
The addressability of a particular object can be set with the model attribute 💖
-mmodel=medium— assumes objects may be anywhere in the 32-bit address space (the compiler generatesseth/add3instructions to load their addresses), and assumes all subroutines are reachable with theblinstruction 🌈-mmodel=large— assumes objects may be anywhere in the 32-bit address space (the compiler generatesseth/add3instructions to load their addresses), and assumes subroutines may NOT be reachable with theblinstruction 🐢 In that case the compiler generates the much slowerseth/add3/jlinstruction sequence 😭-msdata=none— disables use of the small data area 🙅♀️ Variables get put into one of.data,.bss, or.rodata(unless thesectionattribute has been specified). This is the default 💅
The small data area consists of the .sdata and .sbss sections. Objects can be explicitly put in the small data area with the section attribute, using one of these sections 🧁
-msdata=sdata— puts small global and static data in the small data area, but doesn't generate any special code to reference them 🌸-msdata=use— puts small global and static data in the small data area AND generates special instructions to reference them 🔥-G *num*— puts global and static objects less than or equal to num bytes into the small data or BSS sections, instead of the normal data or BSS sections 📦 The default value of num is8. The-msdataoption has to be set to eithersdataorusefor this option to do anything ✨
All modules should be compiled with the same -G num value 🫶 Compiling with different values of num may or may not work. If it doesn't, the linker gives an error message, so incorrect code is NOT generated 🛡️
-mdebug— makes the M32R-specific code in the compiler display some statistics that might help you debug your programs 🔍-malign-loops— aligns all loops to a 32-byte boundary 🌟-mno-align-loops— Skip the 32-byte alignment for loops 💅 This is already the default, so you're basically set ✨-missue-rate=number— Tells the compiler how many instructions to issue per cycle 🔥numbercan only be1or2, no other vibes allowed.-mbranch-cost=number—numbercan only be1or2🌸 If it's1, branches get the VIP pass over conditional code. If it's2, it's the opposite.-mflush-trap=number— Picks the trap number used to flush the cache 🧚 The default is12, and valid numbers are0through15inclusive.-mno-flush-trap— Says the cache can't be flushed by using a trap 🙈-mflush-func=name— Names the operating system function to call for flushing the cache 💜 The default is_flush_cache, but the function call only gets used if a trap isn't available.-mno-flush-func— Says there's no OS function for flushing the cache 💀
✨ M680x0 Options ✨
These are the -m options for M680x0 and ColdFire processors 🦋 The defaults depend on which architecture was picked when the compiler was configured, so the defaults for the most common choices are listed below.
-march=arch— Generates code for a specific M680x0 or ColdFire instruction set architecture 👑 For M680x0, the allowed values ofarchare68000,68010,68020,68030,68040,68060andcpu32. ColdFire architectures get picked using Freescale's ISA classification, and the allowed values areisaa,isaaplus,isabandisac.
GCC defines the macro __mcfarch__ whenever it's generating code for a ColdFire target 🧚 The arch in that macro is one of the -march arguments from above.
When you use -march and -mtune together, you get code that runs on a whole family of similar processors but is optimized for one particular microarchitecture ✨
-mcpu=cpu— Generates code for a specific M680x0 or ColdFire processor 🎀 The M680x0 cpus are68000,68010,68020,68030,68040,68060,68302,68332andcpu32. The ColdFire cpus are in the table below, which also sorts them into families:
Family : -mcpu arguments
51 : 51 51ac 51ag 51cn 51em 51je 51jf 51jg 51jm 51mm 51qe 51qm
5206 : 5202 5204 5206
5206e : 5206e
5208 : 5207 5208
5211a : 5210a 5211a
5213 : 5211 5212 5213
5216 : 5214 5216
52235 : 52230 52231 52232 52233 52234 52235
5225 : 5224 5225
52259 : 52252 52254 52255 52256 52258 52259
5235 : 5232 5233 5234 5235 523x
5249 : 5249
5250 : 5250
5271 : 5270 5271
5272 : 5272
5275 : 5274 5275
5282 : 5280 5281 5282 528x
53017 : 53011 53012 53013 53014 53015 53016 53017
5307 : 5307
5329 : 5327 5328 5329 532x
5373 : 5372 5373 537x
5407 : 5407
5475 : 5470 5471 5472 5473 5474 5475 547x 5480 5481 5482 5483 5484
5485-mcpu=cpu overrides -march=arch if arch is compatible with cpu 💖 Any other combos of -mcpu and -march get rejected 🙅
GCC defines the macro __mcf_cpu_cpu when a ColdFire target cpu is selected. It also defines __mcf_family_family, where the value of family comes from the table above 🌈
-mtune=tune— Tunes the code for a particular microarchitecture, but still within the limits set by-marchand-mcpu🦋 The M680x0 microarchitectures are68000,68010,68020,68030,68040,68060andcpu32. The ColdFire microarchitectures arecfv1,cfv2,cfv3,cfv4andcfv4e.
You can also use -mtune=68020-40 for code that needs to run relatively well on 68020, 68030 and 68040 targets 🍓 -mtune=68020-60 is similar, but it also includes 68060 targets. These two options select the same tuning decisions as -m68020-40 and -m68020-60 respectively.
GCC defines the macros __mcarch and __mcarch__ when tuning for 680x0 architecture arch. It also defines mcarch unless either -ansi or a non-GNU -std option is used. If GCC is tuning for a range of architectures, as selected by -mtune=68020-40 or -mtune=68020-60, it defines the macros for every architecture in that range 🫶
GCC also defines the macro __muarch__ when tuning for ColdFire microarchitecture uarch, where uarch is one of the arguments listed above 💅
-m68000,-mc68000— Generates output for a 68000 💖 This is the default when the compiler is configured for 68000-based systems, and it's equivalent to-march=68000.
Use this one for microcontrollers with a 68000 or EC000 core, including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356 🧚
-m68010— Generates output for a 68010 ✨ This is the default when the compiler is configured for 68010-based systems. It's equivalent to-march=68010.-m68020,-mc68020— Generates output for a 68020 🌸 This is the default when the compiler is configured for 68020-based systems. It's equivalent to-march=68020.-m68030— Generates output for a 68030 🎀 This is the default when the compiler is configured for 68030-based systems. It's equivalent to-march=68030.-m68040— Generates output for a 68040 🔥 This is the default when the compiler is configured for 68040-based systems. It's equivalent to-march=68040.
This option stops the use of 68881/68882 instructions that would have to be emulated in software on the 68040. Use it if your 68040 doesn't have code to emulate those instructions 🙈
-m68060— Generates output for a 68060 👑 This is the default when the compiler is configured for 68060-based systems. It's equivalent to-march=68060.
This option stops the use of 68020 and 68881/68882 instructions that would have to be emulated in software on the 68060. Use it if your 68060 doesn't have code to emulate those instructions 💜
-mcpu32— Generates output for a CPU32 🦋 This is the default when the compiler is configured for CPU32-based systems. It's equivalent to-march=cpu32.
Use this one for microcontrollers with a CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334, 68336, 68340, 68341, 68349 and 68360 🌈
-m5200— Generates output for a 520X ColdFire CPU 🍓 This is the default when the compiler is configured for 520X-based systems. It's equivalent to-mcpu=5206, and it's now deprecated in favor of that option 🥀
Use this one for microcontrollers with a 5200 core, including the MCF5202, MCF5203, MCF5204 and MCF5206 🧚
-m5206e— Generates output for a 5206e ColdFire CPU 🙃 It's now deprecated in favor of the equivalent-mcpu=5206e.-m528x— Generates output for a member of the ColdFire 528X family 🫠 It's now deprecated in favor of the equivalent-mcpu=528x.-m5307— Generates output for a ColdFire 5307 CPU 💀 It's now deprecated in favor of the equivalent-mcpu=5307.-m5407— Generates output for a ColdFire 5407 CPU ✨ It's now deprecated in favor of the equivalent-mcpu=5407.-mcfv4e— Generates output for a ColdFire V4e family CPU (e.g. 547x/548x) 🔥 This includes hardware floating-point instructions. It's equivalent to-mcpu=547x, and it's now deprecated in favor of that option.-m68020-40— Generates output for a 68040, without using any of the new instructions 🌸 This gives code that can run relatively efficiently on a 68020/68881, a 68030 or a 68040. The generated code does use the 68881 instructions that get emulated on the 68040.
The option is equivalent to -march=68020 -mtune=68020-40.
-m68020-60— Generates output for a 68060, without using any of the new instructions 🎀 This gives code that can run relatively efficiently on a 68020/68881, a 68030 or a 68040. The generated code does use the 68881 instructions that get emulated on the 68060.
The option is equivalent to -march=68020 -mtune=68020-60.
-mhard-float,-m68881— Generates floating-point instructions 💖 This is the default for 68020 and above, and for ColdFire devices that have an FPU. It defines the macro__HAVE_68881__on M680x0 targets and__mcffpu__on ColdFire targets.-msoft-float— Doesn't generate floating-point instructions; uses library calls instead 🧚 This is the default for 68000, 68010, and 68832 targets. It's also the default for ColdFire devices that have no FPU.-mdiv,-mno-div— Generates (or doesn't generate) ColdFire hardware divide and remainder instructions ➗ If-marchis used without-mcpu, the default is "on" for ColdFire architectures and "off" for M680x0 architectures. Otherwise, the default comes from the target CPU (either the default CPU, or the one specified by-mcpu). For example, the default is "off" for-mcpu=5206and "on" for-mcpu=5206e.
GCC defines the macro __mcfhwdiv__ when this option is enabled 🌈
-mshort— Treats type "int" as 16 bits wide, like "short int" 🦋 Parameters passed on the stack are also aligned to a 16-bit boundary, even on targets whose API mandates promotion to 32-bit.-mno-short— Doesn't treat type "int" as 16 bits wide 💅 This is the default.-mnobitfield,-mno-bitfield— Doesn't use the bit-field instructions 🙈 The-m68000,-mcpu32and-m5200options imply-mnobitfield.-mbitfield— Does use the bit-field instructions 🫶 The-m68020option implies-mbitfield. This is the default if you use a configuration designed for a 68020.-mrtd— Uses a different function-calling convention ✨ Functions that take a fixed number of arguments return with the "rtd" instruction, which pops their arguments while returning. This saves one instruction in the caller, since there's no need to pop the arguments there 🍓
This calling convention is incompatible with the one normally used on Unix, so you can't use it if you need to call libraries compiled with the Unix compiler 🥺
Also, you must provide function prototypes for all functions that take variable numbers of arguments (including "printf"). Otherwise, incorrect code is generated for calls to those functions 🚨
In addition, seriously incorrect code results if you call a function with too many arguments. (Normally, extra arguments are harmlessly ignored.) 💀
The "rtd" instruction is supported by the 68010, 68020, 68030, 68040, 68060 and CPU32 processors, but not by the 68000 or 5200 🌸
The default is -mno-rtd, bestie, so you only get it if you ask. 💅
-malign-int,-mno-align-int— Okay so this one decides whetherint,long,long long,float,double, andlong doublevariables get lined up on a 32-bit boundary (-malign-int) or a 16-bit boundary (-mno-align-int). The 32-bit version runs somewhat faster on processors with 32-bit busses, but it eats more memory. Trade-offs, babe 🧚
⚠️ Warning: if you use -malign-int, GCC lines up structures containing those types differently than most published application binary interface specifications for the m68k. Not me being dramatic, this is a real heads-up 💀
-mpcrel— Uses the 68000's pc-relative addressing mode directly, so there's no global offset table. For now this implies-fpic, which allows at most a 16-bit offset for pc-relative addressing.-fPICisn't supported alongside-mpcrelyet, though it could be for 68020 and higher processors 🌸-mno-strict-align,-mstrict-align— Doesn't assume (-mno-strict-align) or does assume (-mstrict-align) that the system handles unaligned memory references for you 🫶-msep-data— Generates code where the data segment can live in a totally different area of memory from the text segment. This is what makes execute-in-place work without virtual memory management. It implies-fPIC🦋-mno-sep-data— Generates code that assumes the data segment follows the text segment. This is the default 🍓-mid-shared-library— Generates code that supports shared libraries through the library ID method. That means execute-in-place and shared libraries, again without virtual memory management. It implies-fPIC✨-mno-id-shared-library— Generates code that doesn't assume ID-based shared libraries are in use. This is the default 💜-mshared-library-id=n— Sets the identification number of the ID-based shared library being compiled. Using0gives you more compact code. Other values force that number onto the current library, but it's no more space- or time-efficient than skipping this option 🎀-mxgot,-mno-xgot— When you're making position-independent code for ColdFire,-mxgotgenerates code that still works if the GOT has more than 8192 entries. It's bigger and slower than the normal stuff. On M680x0 processors you don't need it, since-fPICis enough 🌈
GCC normally loads values from the GOT with a single instruction. That's pretty efficient, but it only works if the GOT is smaller than about 64k. Anything bigger and the linker throws an error that looks something like this:
relocation truncated to fit: R_68K_GOT16O foobarIf you see that, recompile your code with -mxgot. It should then work with very large GOTs. Just know that code built with -mxgot is less efficient, because it takes 4 instructions to fetch the value of a global symbol 😭
Some linkers, including newer versions of the GNU linker, can create multiple GOTs and sort GOT entries. If you've got one of those, you should only need -mxgot when compiling a single object file that accesses more than 8192 GOT entries. Very few linkers need it, honestly iykyk 👑
These options have no effect unless GCC is generating position-independent code.
-mlong-jump-table-offsets— Uses 32-bit offsets in"switch"tables. The default is 16-bit offsets 🔥
✨ MCore Options ✨
These are the -m options defined for the Motorola M*Core processors. Main character energy 👑
-mhardlit,-mno-hardlit— Inlines constants into the code stream if it can be done in two instructions or less 🌸-mdiv,-mno-div— Uses the divide instruction. (Enabled by default). ✨-mrelax-immediate,-mno-relax-immediate— Allows arbitrary-sized immediates in bit operations 🦋-mwide-bitfields,-mno-wide-bitfields— Always treats bit-fields as"int"-sized 🎀-m4byte-functions,-mno-4byte-functions— Forces all functions to be aligned to a 4-byte boundary 🍓-mcallgraph-data,-mno-callgraph-data— Emits callgraph information 🧚-mslow-bytes,-mno-slow-bytes— Prefers word access when reading byte quantities 💅-mlittle-endian,-mbig-endian— Generates code for a little-endian target 💖-m210,-m340— Generates code for the 210 processor 🌈-mno-lsim— Assumes runtime support has already been provided, so it leaves the simulator library (libsim.a) off the linker command line 🫶-mstack-increment=size— Sets the maximum amount for a single stack increment operation. Big values can speed up programs with functions that need a lot of stack space, but they can also trigger a segmentation fault if the stack gets extended too much. The default value is0x1000😭
✨ MicroBlaze Options ✨
-msoft-float— Uses software emulation for floating point (default) 🌸-mhard-float— Uses hardware floating-point instructions 🔥-mmemcpy— Doesn't optimize block moves, and uses"memcpy"instead 💜-mno-clearbss— Deprecated. Use-fno-zero-initialized-in-bssinstead 💀-mcpu=cpu-type— Uses the features of, and schedules code for, the given CPU. Supported values are in the formatvX.YY.Z, whereXis a major version,YYis the minor version, andZis compatibility code. Example values arev3.00.a,v4.00.b,v5.00.a,v5.00.b,v6.00.a✨-mxl-soft-mul— Uses software multiply emulation (default) 🎀-mxl-soft-div— Uses software emulation for divides (default) 🧚-mxl-barrel-shift— Uses the hardware barrel shifter 🦋-mxl-pattern-compare— Uses pattern compare instructions 💖-msmall-divides— Uses table lookup optimization for small signed integer divisions 🍓-mxl-stack-check— Deprecated. Use-fstack-checkinstead 💀-mxl-gp-opt— Uses GP-relative".sdata"/".sbss"sections 🌈-mxl-multiply-high— Uses multiply high instructions for the high part of a 32x32 multiply 🔥-mxl-float-convert— Uses hardware floating-point conversion instructions 🫶-mxl-float-sqrt— Uses the hardware floating-point square root instruction 👑-mbig-endian— Generates code for a big-endian target 💜-mlittle-endian— Generates code for a little-endian target 🌸-mxl-reorder— Uses reorder instructions (swap and byte reversed load/store) ✨-mxl-mode-app-model— Selects the application modelapp-model. The valid models are:executable— normal executable (default), uses the startup codecrt0.o.xmdstub— for use with the Xilinx Microprocessor Debugger (XMD) based software intrusive debug agent calledxmdstub. This uses the startup filecrt1.oand sets the start address of the program to0x800.bootstrap— for applications that are loaded using a bootloader. This model uses the startup filecrt2.o, which does not contain a processor reset vector handler. It's suitable for handing control to the bootloader on a processor reset instead of the application 🧚novectors— for applications that don't need any of the MicroBlaze vectors. This can be useful for apps running inside a monitoring application. This model usescrt3.oas its startup file 🦋
Heads up: -xl-mode-app-model is a deprecated alias for -mxl-mode-app-model 💀
-mpic-data-is-text-relative— Assumes the displacement between the text and data segments is fixed at static link time. This lets data be referenced by offset from the start of the text address instead of through the GOT, since PC-relative addressing isn't supported 🌈
✨ MIPS Options ✨
-EB— Generates big-endian code 💖-EL— Generates little-endian code. This is the default formips*el-*-*configurations 🌸-march=arch— Generates code that runs onarch, which can be the name of a generic MIPS ISA or the name of a particular processor 🫶
The ISA names are: mips1, mips2, mips3, mips4, mips32, mips32r2, mips32r3, mips32r5, mips32r6, mips64, mips64r2, mips64r3, mips64r5 and mips64r6.
The processor names are: 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 4kep, 4ksd, 5kc, 5kf, 20kc, 24kc, 24kf2_1, 24kf1_1, 24kec, 24kef2_1, 24kef1_1, 34kc, 34kf2_1, 34kf1_1, 34kn, 74kc, 74kf2_1, 74kf1_1, 74kf3_2, 1004kc, 1004kf2_1, 1004kf1_1, i6400, i6500, interaptiv, loongson2e, loongson2f, loongson3a, gs464, gs464e, gs264e, m4k, m14k, m14kc, m14ke, m14kec, m5100, m5101, octeon, octeon+, octeon2, octeon3, orion, p5600, p6600, r2000, r3000, r3900, r4000, r4400, r4600, r4650, r4700, r5900, r6000, r8000, rm7000, rm9000, r10000, r12000, r14000, r16000, sb1, sr71000, vr4100, vr4111, vr4120, vr4130, vr4300, vr5000, vr5400, vr5500, xlr and xlp. The special value from-abi selects the most compatible architecture for the selected ABI (that is, mips1 for 32-bit ABIs and mips3 for 64-bit ABIs) 👑
The native Linux/GNU toolchain also supports the value native, which selects the best architecture option for the host processor. -march=native has no effect if GCC does not recognize the processor 🔥
In processor names, a final 000 can be abbreviated as k (for example, -march=r2k). Prefixes are optional, and vr may be written r 🦋
Names of the form nf2_1 refer to processors with FPUs clocked at half the rate of the core, names of the form nf1_1 refer to processors with FPUs clocked at the same rate as the core, and names of the form nf3_2 refer to processors with FPUs clocked at a ratio of 3:2 with respect to the core. For compatibility reasons, nf is accepted as a synonym for nf2_1, while nx and bfx are accepted as synonyms for nf1_1 🎀
GCC defines two macros based on the value of this option. The first is "_MIPS_ARCH", which gives the name of the target architecture as a string. The second has the form "_MIPS_ARCH_foo", where foo is the capitalized value of "_MIPS_ARCH". For example, -march=r2000 sets "_MIPS_ARCH" to "r2000" and defines the macro "_MIPS_ARCH_R2000" 🧚
Note that the "_MIPS_ARCH" macro uses the processor names given above. In other words, it has the full prefix and does not abbreviate 000 as k. In the case of from-abi, the macro names the resolved architecture (either "mips1" or "mips3"). It names the default architecture when no -march option is given 💖
-mtune=arch— okay so this one is all about tuning for one specific chip 💅 It optimizes forarch, and among other things it controls how instructions get scheduled and the perceived cost of arithmetic operations. The list ofarchvalues is the same as for-march.
When you skip this flag, GCC optimizes for whatever processor -march picked. Using -march and -mtune together is the move if you want code that runs on a whole family of processors but gets optimized for one particular member of that family 🦋
-mtune also defines the macros _MIPS_TUNE and _MIPS_TUNE_foo, which work the same way as the -march ones we covered above ✨
-mips1— same as-march=mips1🌸-mips2— same as-march=mips2🌸-mips3— same as-march=mips3🌸-mips4— same as-march=mips4🌸-mips32— same as-march=mips32🌸-mips32r3— same as-march=mips32r3🌸-mips32r5— same as-march=mips32r5🌸-mips32r6— same as-march=mips32r6🌸-mips64— same as-march=mips64🌸-mips64r2— same as-march=mips64r2🌸-mips64r3— same as-march=mips64r3🌸-mips64r5— same as-march=mips64r5🌸-mips64r6— same as-march=mips64r6🌸-mips16,-mno-mips16— okay this is the MIPS16 toggle 🧚-mips16makes GCC generate MIPS16 code, and-mno-mips16says "absolutely not" to it. If you're targeting MIPS32 or MIPS64, GCC uses the MIPS16e ASE to get there.
MIPS16 generation can also be controlled per function with the "mips16" and "nomips16" attributes, so you can be extra specific about which functions get the treatment 💜
-mmips16e2,-mno-mips16e2— use (or don't use) the MIPS16e2 ASE. This one changes how-mips16behaves, because it makes that flag target the MIPS16e2 ASE instead 🎀-mflip-mips16— generates MIPS16 code on alternating functions. This is only here for regression testing of mixed MIPS16/non-MIPS16 code generation, so please don't use it for your everyday code. It is not intended for ordinary use in compiling user code 🙈-minterlink-compressed,-mno-interlink-compressed— require (or don't require) that code using the standard (uncompressed) MIPS ISA be link-compatible with MIPS16 and microMIPS code, and the other way around too 🔗
For example, code using the standard ISA encoding can't jump directly to MIPS16 or microMIPS code. It has to use a call or an indirect jump instead. So -minterlink-compressed disables direct jumps unless GCC knows the jump target isn't compressed 💅
-minterlink-mips16,-mno-interlink-mips16— these are just aliases of-minterlink-compressedand-mno-interlink-compressed. They're older than the microMIPS ASE and only hang around for backwards compatibility 🧓-mabi=32,-mabi=o64,-mabi=n32,-mabi=64,-mabi=eabi— generate code for the ABI you pick 👑
Heads up: the EABI comes in a 32-bit and a 64-bit variant. GCC normally makes 64-bit code when you pick a 64-bit architecture, but if you want 32-bit code anyway, use -mgp32 🫶
If you want the details on the O64 ABI, check out <https://gcc.gnu.org/projects/mipso64-abi.html> 📚
GCC also supports a version of the o32 ABI where the floating-point registers are 64 bits wide instead of 32. You get this combo with -mabi=32 -mfp64. This ABI depends on the mthc1 and mfhc1 instructions, so it's only supported for MIPS32R2, MIPS32R3, and MIPS32R5 processors 🔥
The register assignments for arguments and return values stay the same, but each scalar value rides in a single 64-bit register instead of a pair of 32-bit ones. So for example, scalar floating-point values get returned in $f0 only, not a $f0/$f1 pair. The set of call-saved registers also stays the same, meaning the even-numbered double-precision registers are the ones that get saved ✨
Two more variants of the o32 ABI exist to help with the jump from 32-bit to 64-bit registers. They're FPXX (-mfpxx) and FP64A (-mfp64 -mno-odd-spreg) 🦋 The FPXX extension says all code has to run correctly with 32-bit or 64-bit registers. It can be interlinked with either FP32 or FP64, but never both at once. FP64A is kind of like FP64, except it forbids the use of odd-numbered single-precision registers. It can be paired with the "FRE" mode of FPUs in MIPS32R5 processors, which lets FP32 and FP64A code interlink and run in the same process without changing FPU modes 🌈
-mabicalls,-mno-abicalls— generate (or don't generate) code that works with SVR4-style dynamic objects.-mabicallsis the default on SVR4-based systems 🍓-mshared,-mno-shared— generate (or don't generate) code that's fully position-independent, so it can be linked into shared libraries. This option only affects-mabicalls🧚
All -mabicalls code has traditionally been position-independent, no matter what you pass like -fPIC or -fpic. BUT, as an extension, the GNU toolchain lets executables use absolute accesses for locally-binding symbols. It can also use shorter GP initialization sequences and generate direct calls to locally-defined functions. That mode gets selected by -mno-shared 💖
-mno-shared depends on binutils 2.16 or higher, and it generates objects that can only be linked by the GNU linker. The good news is it doesn't change the ABI of the final executable. It only changes the ABI of relocatable objects. Using -mno-shared generally makes executables both smaller and quicker 🏎️
-mshared is the default ✨
-mplt,-mno-plt— assume (or don't assume) that the static and dynamic linkers support PLTs and copy relocations. This only affects-mno-shared -mabicalls. For the n64 ABI, this option does nothing without-msym32🤷♀️
You can make -mplt the default by configuring GCC with --with-mips-plt. Otherwise the default is -mno-plt 💅
-mxgot,-mno-xgot— lift (or don't lift) the usual restrictions on the size of the global offset table 🌸
GCC normally uses a single instruction to load values from the GOT. It's pretty efficient, but it only works if the GOT is smaller than about 64k. Anything bigger makes the linker report an error like this:
relocation truncated to fit: R_MIPS_GOT16 foobarIf that happens, recompile your code with -mxgot. It works with very large GOTs, but the code is less efficient because it takes three instructions to fetch the value of a global symbol 😭
Some linkers can create multiple GOTs. If you have one of those, you should only need -mxgot when a single object file accesses more than 64k's worth of GOT entries. Very few linkers do that, honestly 🙈
These options have no effect unless GCC is generating position-independent code 🫶
-mgp32— assumes general-purpose registers are 32 bits wide 🎀-mgp64— assumes general-purpose registers are 64 bits wide 🎀-mfp32— assumes floating-point registers are 32 bits wide 🌈-mfp64— assumes floating-point registers are 64 bits wide 🌈-mfpxx— doesn't assume anything about the width of floating-point registers 🦋-mhard-float— use the floating-point coprocessor instructions 💪-msoft-float— don't use the floating-point coprocessor instructions. Floating-point math gets done with library calls instead 📚-mno-float— same as-msoft-float, but it also swears that the program being compiled does zero floating-point operations 🙅♀️ Right now this is only supported by some bare-metal MIPS configurations, where it might pick a special set of libraries that have no floating-point support at all. That includes stuff like the floating-point"printf"formats.
If code compiled with -mno-float accidentally has floating-point operations in it, it's likely to fail at link time or at run time. Be careful, bestie 💀
-msingle-float— assumes the floating-point coprocessor only supports single-precision operations 🌸-mdouble-float— assumes the floating-point coprocessor supports double-precision operations. This is the default 💖-modd-spreg,-mno-odd-spreg— enable (or disable) the use of odd-numbered single-precision floating-point registers for the o32 ABI. Enabled is the default for processors known to support these registers. When you're using the o32 FPXX ABI,-mno-odd-spreggets set by default 🧚-mabs=2008,-mabs=legacy— these control how the special not-a-number (NaN) IEEE 754 floating-point data gets treated by theabs.fmtandneg.fmtmachine instructions 🔍
By default, or when you use -mabs=legacy, you get the legacy treatment. Here those instructions count as arithmetic, so GCC avoids them wherever correct operation matters and the input might be a NaN. Instead it uses a longer sequence of instructions that manually manipulates the sign bit of the floating-point datum, unless -ffinite-math-only was also specified 🫠
-mabs=2008 selects the IEEE 754-2008 treatment. In this case those instructions count as non-arithmetic, so they work correctly in all cases, including when the input operand is a NaN. That means these instructions are always used for the respective operations 🔥
-mnan=2008,-mnan=legacy— these control how the special not-a-number (NaN) IEEE 754 floating-point data gets encoded 🌈
-mnan=legacy selects the legacy encoding. Here, quiet NaNs (qNaNs) are marked by the first bit of their trailing significand field being 0, while signaling NaNs (sNaNs) are marked by that first bit being 1 💜
-mnan=2008 selects the IEEE 754-2008 encoding. Here, qNaNs are marked by the first bit of their trailing significand field being 1, while sNaNs are marked by that first bit being 0 ✨
The default is -mnan=legacy, unless GCC was configured with --with-nan=2008 🍓
-mllsc,-mno-llsc— use (or don't use) thell,sc, andsyncinstructions to implement the atomic memory built-in functions. If you specify neither option, GCC uses those instructions as long as the target architecture supports them 💅
Okay so -mllsc is clutch when the runtime can emulate those instructions, and -mno-llsc slays when you're compiling for nonstandard ISAs 🔧. You can make either one the default by configuring GCC with --with-llsc or --without-llsc, respectively. Heads up: --with-llsc is already the default for some configurations, so check the installation docs for the deets 📚.
-mdsp,-mno-dsp— Use (do not use) revision 1 of the MIPS DSP ASE 💖- This option defines the preprocessor macro
__mips_dsp. It also defines__mips_dsp_revto 1.
- This option defines the preprocessor macro
-mdspr2,-mno-dspr2— Use (do not use) revision 2 of the MIPS DSP ASE ✨- This option defines the preprocessor macros
__mips_dspand__mips_dspr2. It also defines__mips_dsp_revto 2.
- This option defines the preprocessor macros
-msmartmips,-mno-smartmips— Use (do not use) the MIPS SmartMIPS ASE 🎀-mpaired-single,-mno-paired-single— Use (do not use) paired-single floating-point instructions 🦋- This option requires hardware floating-point support to be enabled.
-mdmx,-mno-mdmx— Use (do not use) MIPS Digital Media Extension instructions 🌸- This option can only be used when generating 64-bit code and requires hardware floating-point support to be enabled.
-mips3d,-mno-mips3d— Use (do not use) the MIPS-3D ASE 🧚- The option
-mips3dimplies-mpaired-single.
- The option
-mmicromips,-mno-micromips— Generate (do not generate) microMIPS code 💜- MicroMIPS code generation can also be controlled on a per-function basis by means of
micromipsandnomicromipsattributes.
- MicroMIPS code generation can also be controlled on a per-function basis by means of
-mmt,-mno-mt— Use (do not use) MT Multithreading instructions 🫶-mmcu,-mno-mcu— Use (do not use) the MIPS MCU ASE instructions 🍓-meva,-mno-eva— Use (do not use) the MIPS Enhanced Virtual Addressing instructions 👑-mvirt,-mno-virt— Use (do not use) the MIPS Virtualization (VZ) instructions 🌈-mxpa,-mno-xpa— Use (do not use) the MIPS eXtended Physical Address (XPA) instructions ⭐-mcrc,-mno-crc— Use (do not use) the MIPS Cyclic Redundancy Check (CRC) instructions 💅-mginv,-mno-ginv— Use (do not use) the MIPS Global INValidate (GINV) instructions 🔥-mloongson-mmi,-mno-loongson-mmi— Use (do not use) the MIPS Loongson MultiMedia extensions Instructions (MMI) 🎀-mloongson-ext,-mno-loongson-ext— Use (do not use) the MIPS Loongson EXTensions (EXT) instructions 🦋-mloongson-ext2,-mno-loongson-ext2— Use (do not use) the MIPS Loongson EXTensions r2 (EXT2) instructions 🌸-mlong64— Forcelongtypes to be 64 bits wide 💖- See
-mlong32for an explanation of the default and the way that the pointer size is determined.
- See
-mlong32— Forcelong,int, and pointer types to be 32 bits wide 🧚- The default size of
ints,longs and pointers depends on the ABI. All the supported ABIs use 32-bitints. The n64 ABI uses 64-bitlongs, as does the 64-bit EABI; the others use 32-bitlongs. Pointers are the same size aslongs, or the same size as integer registers, whichever is smaller.
- The default size of
-msym32,-mno-sym32— Assume (do not assume) that all symbols have 32-bit values, regardless of the selected ABI 🌈- This option is useful in combination with
-mabi=64and-mno-abicallsbecause it allows GCC to generate shorter and faster references to symbolic addresses.
- This option is useful in combination with
-G num— Put definitions of externally-visible data in a small data section if that data is no bigger than num bytes 💜- GCC can then generate more efficient accesses to the data; see
-mgpoptfor details. - The default
-Goption depends on the configuration.
- GCC can then generate more efficient accesses to the data; see
-mlocal-sdata,-mno-local-sdata— Extend (do not extend) the-Gbehavior to local data too, such as to static variables in C ✨-mlocal-sdatais the default for all configurations.- If the linker complains that an application is using too much small data, you might want to try rebuilding the less performance-critical parts with
-mno-local-sdata. You might also want to build large libraries with-mno-local-sdata, so that the libraries leave more room for the main program.
-mextern-sdata,-mno-extern-sdata— Assume (do not assume) that externally-defined data is in a small data section if the size of that data is within the-Glimit 🫶-mextern-sdatais the default for all configurations.- If you compile a module Mod with
-mextern-sdata -G num -mgpopt, and Mod references a variable Var that is no bigger than num bytes, you must make sure that Var is placed in a small data section. If Var is defined by another module, you must either compile that module with a high-enough-Gsetting or attach asectionattribute to Var's definition. If Var is common, you must link the application with a high-enough-Gsetting. - The easiest way of satisfying these restrictions is to compile and link every module with the same
-Goption. However, you may wish to build a library that supports several different small data limits. You can do this by compiling the library with the highest supported-Gsetting and additionally using-mno-extern-sdatato stop the library from making assumptions about externally-defined data.
-mgpopt,-mno-gpopt— Use (do not use) GP-relative accesses for symbols that are known to be in a small data section; see-G,-mlocal-sdataand-mextern-sdata🔥-mgpoptis the default for all configurations.-mno-gpoptis useful for cases where the$gpregister might not hold the value of_gp. For example, if the code is part of a library that might be used in a boot monitor, programs that call boot monitor routines pass an unknown value in$gp. (In such situations, the boot monitor itself is usually compiled with-G0.)-mno-gpoptimplies-mno-local-sdataand-mno-extern-sdata.
-membedded-data,-mno-embedded-data— Allocate variables to the read-only data section first if possible, then next in the small data section if possible, otherwise in data 🌸- This gives slightly slower code than the default, but reduces the amount of RAM required when executing, and thus may be preferred for some embedded systems.
-muninit-const-in-rodata,-mno-uninit-const-in-rodata— Put uninitializedconstvariables in the read-only data section 🍓- This option is only meaningful in conjunction with
-membedded-data.
- This option is only meaningful in conjunction with
-mcode-readable=setting— Specify whether GCC may generate code that reads from executable sections 💖- There are three possible settings:
-mcode-readable=yes— Instructions may freely access executable sections. This is the default setting. 🦋-mcode-readable=pcrel— MIPS16 PC-relative load instructions can access executable sections, but other instructions must not do so. This option is useful on 4KSc and 4KSd processors when the code TLBs have the Read Inhibit bit set. It is also useful on processors that can be configured to have a dual instruction/data SRAM interface and that, like the M4K, automatically redirect PC-relative loads to the instruction RAM. 🧚-mcode-readable=no— Instructions must not access executable sections. This option can be useful on targets that are configured to have a dual instruction/data SRAM interface but that (unlike the M4K) do not automatically redirect PC-relative loads to the instruction RAM. 💜
- There are three possible settings:
-msplit-addresses,-mno-split-addresses— Enable (disable) use of the%hi()and%lo()assembler relocation operators 🌈- This option has been superseded by
-mexplicit-relocsbut is retained for backwards compatibility.
- This option has been superseded by
-mexplicit-relocs=none,-mexplicit-relocs=base,-mexplicit-relocs=pcrel,-mexplicit-relocs,-mno-explicit-relocs— These options control whether explicit relocs (such as%gp_rel) are used ⭐- The default value depends on the version of GAS when GCC itself was built.
- The
baseexplicit-relocs support was introduced into GAS in 2001. - The
pcrelexplicit-relocs support was introduced into GAS in 2014, and it supports%pcrel_hiand%pcrel_lo.
-mcheck-zero-division,-mno-check-zero-division— Trap (do not trap) on integer division by zero 💅- The default is
-mcheck-zero-division.
- The default is
-mdivide-traps,-mdivide-breaks— MIPS systems check for division by zero by generating either a conditional trap or abreakinstruction 🔥- Using traps results in smaller code, but is only supported on MIPS II and later. Also, some versions of the Linux kernel have a bug that prevents
trapfrom generating the proper signal (SIGFPE). Use-mdivide-trapsto allow conditional traps on architectures that support them and-mdivide-breaksto force the use ofbreaks. - The default is usually
-mdivide-traps, but this can be overridden at configure time using--with-divide=breaks. Divide-by-zero checks can be completely disabled using-mno-check-zero-division.
- Using traps results in smaller code, but is only supported on MIPS II and later. Also, some versions of the Linux kernel have a bug that prevents
-mload-store-pairs,-mno-load-store-pairs— Enable (disable) an optimization that pairs consecutive load or store instructions to enable load/store bonding 🎀- This option is enabled by default but only takes effect when the selected architecture is known to support bonding.
-mstrict-align,-mno-strict-align,-munaligned-access,-mno-unaligned-access— Disable (enable) direct unaligned access for MIPS Release 6 🦋- MIPSr6 requires load/store unaligned-access support, by hardware or
trap&emulate. So-mstrict-alignmay be needed by kernel. - > The options
-munaligned-accessand-mno-unaligned-accessare obsoleted, and only for backward-compatible.
- MIPSr6 requires load/store unaligned-access support, by hardware or
-mmemcpy,-mno-memcpy— Force (do not force) the use ofmemcpyfor non-trivial block moves 🌸- The default is
-mno-memcpy, which allows GCC to inline most constant-sized copies.
- The default is
-mlong-calls,-mno-long-calls— Disable (do not disable) use of thejalinstruction 🧚- Calling functions using
jalis more efficient but requires the caller and callee to be in the same 256 megabyte segment. - This option has no effect on
abicallscode. The default is-mno-long-calls.
- Calling functions using
-mmad,-mno-mad— Enable (disable) use of themad,maduandmulinstructions, as provided by the R4650 ISA 💜-mimadd,-mno-imadd— okay so these turn themaddandmsubinteger instructions on (-mimadd) or off (-mno-imadd) 💅 The default is-mimaddon architectures that supportmaddandmsub, except the 74k architecture, where it was found to generate slower code 🐢-mfused-madd,-mno-fused-madd— this one enables or disables the floating-point multiply-accumulate instructions whenever they're available ✨ The default is-mfused-madd.- Heads up, bestie 💀 On the R8000 CPU, when multiply-accumulate instructions are used, the intermediate product is calculated to infinite precision and is not subject to the FCSR Flush to Zero bit. This may be undesirable in some circumstances.
- On other processors, the result is numerically identical to the equivalent computation using separate multiply, add, subtract and negate instructions.
-nocpp— tells the MIPS assembler to skip its preprocessor when it assembles user assembler files with a.ssuffix 🧚-mfix-24k,-mno-fix-24k— works around the 24K E48 errata (lost data on stores during refill) 🛠️ The assembler handles these workarounds, not GCC.-mfix-r4000,-mno-fix-r4000— works around certain R4000 CPU errata 😭- A double-word or a variable shift may give an incorrect result if executed immediately after starting an integer division.
- A double-word or a variable shift may give an incorrect result if executed while an integer multiplication is in progress.
- An integer division may give an incorrect result if started in a delay slot of a taken branch or a jump.
-mfix-r4400,-mno-fix-r4400— works around certain R4400 CPU errata 🌸- A double-word or a variable shift may give an incorrect result if executed immediately after starting an integer division.
-mfix-r10000,-mno-fix-r10000— works around certain R10000 errata 🎀"ll"/"sc"sequences may not behave atomically on revisions prior to 3.0. They may deadlock on revisions 2.6 and earlier.- This option can only be used if the target architecture supports branch-likely instructions.
-mfix-r10000is the default when-march=r10000is used;-mno-fix-r10000is the default otherwise.
-mfix-r5900,-mno-fix-r5900— basically, don't try to schedule the preceding instruction into the delay slot of a branch sitting at the end of a short loop of six instructions or fewer. Always put anopthere instead 🙈 The short loop bug can make loops run only once or twice because of a hardware bug in the R5900 chip. The assembler does this workaround, not GCC.-mfix-rm7000,-mno-fix-rm7000— works around the RM7000dmult/dmultuerrata 💜 The assembler handles the workarounds, not GCC.-mfix-vr4120,-mno-fix-vr4120— works around certain VR4120 errata 🦋dmultudoes not always produce the correct result.divandddivdo not always produce the correct result if one of the operands is negative.- The workarounds for the division errata rely on special functions in
libgcc.a. At present, these functions are only provided by themips64vr*-elfconfigurations. - Other VR4120 errata require a NOP to be inserted between certain pairs of instructions. These are handled by the assembler, not by GCC itself.
-mfix-vr4130— works around the VR4130mflo/mfhierrata ✨ The assembler does the workarounds, although GCC avoids usingmfloandmfhiif the VR4130macc,macchi,dmaccanddmacchiinstructions are available instead.-mfix-sb1,-mno-fix-sb1— works around certain SB-1 CPU core errata 🔥 (This flag currently only works around the SB-1 revision 2"F1"and"F2"floating-point errata.)-mr10k-cache-barrier=setting— decides whether GCC should insert cache barriers to avoid the side effects of speculation on R10K processors 👑- Like lots of processors, the R10K tries to guess the outcome of a conditional branch and speculatively runs instructions from the "taken" branch. It later aborts them if the guess was wrong. But on the R10K, even aborted instructions can leave side effects behind.
- This problem only affects kernel stores and, depending on the system, kernel loads. For example, a speculatively-executed store may load the target memory into cache and mark the cache line as dirty, even if the store itself is later aborted. If a DMA operation writes to the same area of memory before the "dirty" line is flushed, the cached data overwrites the DMA-ed data. See the R10K processor manual for a full description, including other potential problems.
- One workaround is to insert cache barrier instructions before every memory access that might be speculatively executed and that might have side effects even if aborted.
-mr10k-cache-barrier=settingcontrols GCC's implementation of this workaround. It assumes that aborted accesses to any byte in the following regions do not have side effects:- the memory occupied by the current function's stack frame;
- the memory occupied by an incoming stack argument;
- the memory occupied by an object with a link-time-constant address.
- It is the kernel's responsibility to ensure that speculative accesses to these regions are indeed safe.
- If the input program contains a function declaration such as
void foo (void);, then the implementation offoomust allowj fooandjal footo be executed speculatively. GCC honors this restriction for functions it compiles itself. It expects non-GCC functions (such as hand-written assembly code) to do the same. - The option has three forms:
-mr10k-cache-barrier=load-store— inserts a cache barrier before a load or store that might be speculatively executed and that might have side effects even if aborted.-mr10k-cache-barrier=store— inserts a cache barrier before a store that might be speculatively executed and that might have side effects even if aborted.-mr10k-cache-barrier=none— disables the insertion of cache barriers. This is the default setting.
-mflush-func=func,-mno-flush-func— picks the function to call to flush the I and D caches, or tells GCC to not call any such function 🧹 If it's called, the function must take the same arguments as the common_flush_func: the address of the memory range being flushed, the size of that memory range, and the number 3 (to flush both caches). The default depends on the target GCC was configured for, but it's commonly either_flush_funcor__cpu_flush.-mbranch-cost=num— sets the cost of branches to roughly num "simple" instructions 💖 This cost is only a heuristic and isn't guaranteed to produce consistent results across releases. A zero cost redundantly selects the default, which is based on the-mtunesetting.-mbranch-likely,-mno-branch-likely— enables or disables Branch Likely instructions, no matter what the default is for the selected architecture 🌈 By default, Branch Likely instructions may be generated if the selected architecture supports them. The exception is the MIPS32 and MIPS64 architectures, plus processors that implement those architectures. For those, Branch Likely instructions are not generated by default, because the MIPS32 and MIPS64 architectures specifically deprecate their use.-mcompact-branches=never,-mcompact-branches=optimal,-mcompact-branches=always— these control which form of branches gets generated 🦄 The default is-mcompact-branches=optimal.-mcompact-branches=neverensures that compact branch instructions are never generated.-mcompact-branches=alwaysensures that a compact branch instruction is generated if one is available, for MIPS Release 6 onwards. If a compact branch instruction is not available (or the target is pre-R6), a delay slot form of the branch is used instead.- If it's used for MIPS16/microMIPS targets, it will just be ignored for now. The behaviour for MIPS16/microMIPS may change in the future, since they do have some compact branch instructions.
-mcompact-branches=optimalcauses a delay slot branch to be used if one is available in the current ISA and the delay slot is successfully filled. If the delay slot isn't filled, a compact branch is chosen if one is available.
-mfp-exceptions,-mno-fp-exceptions— specifies whether FP exceptions are enabled ⭐ This affects how FP instructions get scheduled for some processors. The default is that FP exceptions are enabled.- For instance, on the SB-1, if FP exceptions are disabled and we're emitting 64-bit code, then we can use both FP pipes. Otherwise, we can only use one FP pipe.
-mvr4130-align,-mno-vr4130-align— the VR4130 pipeline is two-way superscalar, but it can only issue two instructions together if the first one is 8-byte aligned 🍓 When this option is enabled, GCC aligns pairs of instructions that it thinks should execute in parallel.- This option only has an effect when optimizing for the VR4130. It normally makes code faster, but at the expense of making it bigger. It is enabled by default at optimization level
-O3.
- This option only has an effect when optimizing for the VR4130. It normally makes code faster, but at the expense of making it bigger. It is enabled by default at optimization level
-msynci,-mno-synci— enables (or disables) generation ofsynciinstructions on architectures that support it 🔥 Thesynciinstructions (if enabled) are generated when__builtin___clear_cacheis compiled.- This option defaults to
-mno-synci, but the default can be overridden by configuring GCC with--with-synci. - > When compiling code for single-processor systems, it is generally safe to use
synci. However, on many multi-core (SMP) systems, it does not invalidate the instruction caches on all cores and may lead to undefined behavior. 💀
- This option defaults to
-mrelax-pic-calls,-mno-relax-pic-calls— tries to turn PIC calls that are normally dispatched via register$25into direct calls 💅 This is only possible if the linker can resolve the destination at link time and if the destination is within range for a direct call.
Okay so -mrelax-pic-calls is the default 💅 if GCC was configured to use an assembler and a linker that support the .reloc assembly directive, and -mexplicit-relocs is in effect. With -mno-explicit-relocs, the assembler and linker can handle this optimization all on their own, no compiler help needed 🦋
-mmcount-ra-address,-mno-mcount-ra-address— Okay, this one is giving return address drama 🎀 With-mmcount-ra-address, GCC emits code that lets_mcountchange the calling function's return address. It basically extends the usual_mcountinterface with a new ra-address parameter. That parameter is typeintptr_t *and gets passed in register$12. So_mcountcan change the return address by doing both of these:- Returning the new address in register
$31. - Storing the new address in
*ra-address, but only if ra-address is nonnull.
- Returning the new address in register
The default is -mno-mcount-ra-address 💖
-mframe-header-opt,-mno-frame-header-opt— This one is a lil bit of stack tidying ✨ In the o32 ABI, calling functions normally reserve 16 bytes on the stack so the called function has somewhere to write out its register arguments. With-mframe-header-opt, GCC skips reserving that frame header if it can tell it's unused.-mno-frame-header-optturns that off. This optimization is off by default at all optimization levels 🌸-mlxc1-sxc1,-mno-lxc1-sxc1— When it applies,-mlxc1-sxc1lets GCC generatelwxc1,swxc1,ldxc1andsdxc1instructions, and-mno-lxc1-sxc1stops it. It's enabled by default 🦋-mmadd4,-mno-madd4— When it applies,-mmadd4lets GCC generate 4-operandmadd.s,madd.dand related instructions.-mno-madd4says no thanks. Enabled by default 💜
🌸 MMIX Options 🌸
These options are defined for the MMIX 🧚
-mlibfuncs,-mno-libfuncs—-mlibfuncssays you're compiling intrinsic library functions, so every value gets passed in registers, no matter how big it is.-mno-libfuncsis the opposite vibe 🍓-mepsilon,-mno-epsilon—-mepsilonmakes GCC generate floating-point comparison instructions that compare with respect to therEepsilon register.-mno-epsilonskips that ✨-mabi=mmixware,-mabi=gnu—-mabi=mmixwaregenerates code where function parameters and return values are seen as registers$0and up, in the called function. The GNU ABI, on the other hand, uses global registers$231and up. Pick your fighter 👑-mzero-extend,-mno-zero-extend— When reading data from memory in sizes shorter than 64 bits,-mzero-extenduses zero-extending load instructions by default, instead of sign-extending ones.-mno-zero-extendmeans don't use them 🌈-mknuthdiv,-mno-knuthdiv—-mknuthdivmakes the remainder of a division have the same sign as the divisor. With the default,-mno-knuthdiv, the remainder's sign follows the sign of the dividend. Both methods are arithmetically valid, but the latter is the one almost everyone uses 🧮-mtoplevel-symbols,-mno-toplevel-symbols—-mtoplevel-symbolsputs a:in front of all global symbols, so your assembly code can work with thePREFIXassembly directive.-mno-toplevel-symbolsdoesn't add the colon 💅-melf— Generates an executable in the ELF format, instead of the default mmo format that the mmix simulator uses 🦋-mbranch-predict,-mno-branch-predict—-mbranch-predictuses the probable-branch instructions when static branch prediction says a branch is probable.-mno-branch-predictdoesn't use them 🔥-mbase-addresses,-mno-base-addresses—-mbase-addressesgenerates code that uses base addresses. Using a base address automatically makes a request, which the assembler and linker take care of, for a constant to be set up in a global register. That register then gets used for one or more base address requests within the range 0 to 255 from the value held in the register. This generally leads to short and fast code, but the number of different data items you can address is limited. So if your program has lots of static data, you might need-mno-base-addresses🙈-msingle-exit,-mno-single-exit—-msingle-exitforces the generated code to have a single exit point in each function.-mno-single-exitdoesn't force that 🎀
🍓 MN10300 Options 🍓
These -m options are defined for Matsushita MN10300 architectures 🌈
-mmult-bug— Generates code that avoids bugs in the multiply instructions for MN10300 processors. This is the default 💖-mno-mult-bug— Does not generate code to avoid those multiply bugs for MN10300 processors ⭐-mam33— Generates code using features specific to the AM33 processor ✨-mno-am33— Does not generate code using AM33-specific features. This is the default 🫶-mam33-2— Generates code using features specific to the AM33/2.0 processor 🦋-mam34— Generates code using features specific to the AM34 processor 🌸-mtune=cpu-type— Uses the timing characteristics of the CPU type you give when scheduling instructions. This does not change the targeted processor type. The CPU type must be one ofmn10300,am33,am33-2oram34🧚-mreturn-pointer-on-d0— When generating a function that returns a pointer, the pointer gets returned in botha0andd0. Otherwise, the pointer is only returned ina0, and trying to call those functions without a prototype results in errors. Note that this option is on by default, so use-mno-return-pointer-on-d0to turn it off 💅-mno-crt0— Does not link in the C run-time initialization object file 🙈-mrelax— Tells the linker to run a relaxation optimization pass that shortens branches, calls and absolute memory addresses. This option only has an effect when it's used on the command line for the final link step.
Heads up: this option makes symbolic debugging impossible 💀
-mliw— Lets the compiler generate Long Instruction Word instructions if the target is AM33 or later. This is the default. This option defines the preprocessor macro__LIW__🔥-mno-liw— Stops the compiler from generating Long Instruction Word instructions. This option defines the preprocessor macro__NO_LIW__🌈-msetlb— Lets the compiler generate SETLB and Lcc instructions if the target is AM33 or later. This is the default. This option defines the preprocessor macro__SETLB__👑-mno-setlb— Stops the compiler from generating SETLB or Lcc instructions. This option defines the preprocessor macro__NO_SETLB__💜
🧚 Moxie Options 🧚
-meb— Generates big-endian code. This is the default formoxie-*-*configurations 🌸-mel— Generates little-endian code 🦋-mmul.x— Generatesmul.xandumul.xinstructions. This is the default formoxiebox-*-*configurations ✨-mno-crt0— Does not link in the C run-time initialization object file 🎀
💜 MSP430 Options 💜
These options are defined for the MSP430 🫶
-masm-hex— Forces assembly output to always use hex constants. Normally these constants are signed decimals, but this option is there for testsuite and/or aesthetic purposes 💅-mmcu=— Selects the MCU to target. This creates a C preprocessor symbol based on the MCU name, converted to upper case and pre- and post-fixed with__. Themsp430.hheader file then uses that symbol to pick an MCU-specific supplementary header file 🧚
This option also sets the ISA to use. If the MCU name is one that's known to only support the 430 ISA, that one gets selected. Otherwise, the 430X ISA is selected. The generic MCU name msp430 can also be used to select the 430 ISA, and the generic msp430x MCU name selects the 430X ISA 🌈
On top of that, an MCU-specific linker script gets added to the linker command line. The script's name is the MCU name with .ld appended. So -mmcu=xxx on the gcc command line defines the C preprocessor symbol __XXX__ and makes the linker search for a script called xxx.ld 🦋
The ISA and hardware multiply supported for the different MCUs are hard-coded into GCC. However, an external devices.csv file can extend device support beyond those hard-coded ones 🍓
GCC searches for devices.csv using the methods below, in this precedence order. The first method beats the second, and the second beats the third 👑
- Include path specified with
-Iand-L:devices.csvgets searched for in each of the directories specified by include paths and linker library search paths. - Path specified by the environment variable
MSP430_GCC_INCLUDE_DIR: Set the global environment variableMSP430_GCC_INCLUDE_DIRto the full path of the directory containingdevices.csv, and GCC will search that directory fordevices.csv. Ifdevices.csvis found there, the directory also gets registered as an include path and a linker library path. Header files and linker scripts in this directory can then be used without manually specifying-Iand-Lon the command line ✨ - The
msp430-elf{,bare}/include/devicesdirectory: GCC will examinemsp430-elf{,bare}/include/devicesfrom the toolchain root directory. This directory doesn't exist in a default installation, but if you've created it and copieddevices.csvinto it, the MCU data gets read. As above, this directory also gets registered as an include path and a linker library path 🌸
If none of the above search methods find devices.csv, the hard-coded MCU data is used 💖
-mwarn-mcu,-mno-warn-mcu—-mwarn-mcuturns on warnings about conflicts between the MCU name set by-mmcuand the ISA set by-mcpuand/or the hardware multiply support set by-mhwmult. It also toggles warnings about unrecognized MCU names. This option is on by default.-mno-warn-mcuturns all of those warnings off 🙈-mcpu=— Specifies the ISA to use. Accepted values aremsp430,msp430xandmsp430xv2.
Deprecated: this option is deprecated. The -mmcu= option should be used to select the ISA 💀
-msim— Links to the simulator runtime libraries and linker script. This overrides any scripts that would be selected by the-mmcu=option 🔥-mlarge— Uses large-model addressing, with 20-bit pointers and a 20-bitsize_t👑-msmall— Uses small-model addressing, with 16-bit pointers and a 16-bitsize_t🌈-mrelax— This option gets passed to the assembler and linker, and it lets the linker do certain optimizations that can't happen until the final link 🦋-mhwmult=— okay so this one tells GCC what kind of hardware multiply your chip actually has 🧮✨ The accepted values are:none— no hardware multiply, bestie 💀16bit— the original 16-bit-only multiply from the early MCUs 🌸32bit— the 16/32-bit multiply on the later MCUs 🔥f5series— the 16/32-bit multiply on F5-series MCUs 👑auto— the default 💅 It tells GCC to figure out the hardware multiply support from the MCU name you gave to-mmcu. If you skip-mmcuor the MCU name isn't recognized, GCC assumes no hardware multiply support at all.
Hardware multiplies usually get handled by calling a library routine, which saves space in the generated code 🎀 But when you compile at -O3 or higher, the hardware multiplier gets invoked inline instead. That makes the code bigger but faster, so it's a total glow-up trade-off 🦋
The hardware multiply routines turn off interrupts while they run and then restore the previous interrupt state when they're done 🫶 That's the reason they're safe to use inside interrupt handlers as well as in normal code ✨
-minrt— enables a minimum runtime environment, which means no static initializers or constructors 🧚 It's made for memory-constrained devices. The compiler slips special symbols into some objects so the linker and runtime know which code fragments are required 💜-mtiny-printf— enables reduced code sizeprintfandputslibrary functions 🌈 Heads up though: these tiny versions are not reentrant, so you have to be careful with them in multi-threaded apps 😭
Stream support has been removed, so the string you print always goes to stdout through the write syscall. It isn't buffered before it gets sent to write 💅 This option requires Newlib Nano IO, which means GCC must be configured with --enable-newlib-nano-formatted-io 🍓
-mmax-inline-shift=— takes an integer from 0 to 64 inclusive and sets the maximum number of inline shift instructions that can be emitted for a shift by a constant amount 🦋 Once that limit would be exceeded, anmspabihelper function gets used instead. The default is 4 ✨
This only matters when a shift by multiple positions can't be done with one instruction, like all shifts greater than 1 on the 430 ISA 🙈 Shifts of a 32-bit value are at least twice as costly, so the value you pass gets divided by 2 and that result is used instead 🧮
-mcode-region=and-mdata-region=— these tell the compiler where to put functions and data that don't have one of thelower,upper,either, orsectionattributes 💖 The possible values arelower,upper,either, orany. The first three behave like the matching attribute, andanyis the default 🌸 Withany, placement is left entirely up to the linker script and how it assigns the standard sections (.text,.data, etc.) to the memory regions 🫶-msilicon-errata=— passes a request to the assembler to enable the fixes for the named silicon errata 🔧✨-msilicon-errata-warn=— passes a request to the assembler to turn on warning messages for when a silicon errata might need to be applied 👀-mwarn-devices-csvand-mno-warn-devices-csv— warn ifdevices.csvisn't found or there are problems parsing it (default: on) 📄💜
✨ NDS32 Options ✨
These options are defined for NDS32 implementations 🌈
-mbig-endian— generates code in big-endian mode 🐳-mlittle-endian— generates code in little-endian mode 🌷-mreduced-regs— uses reduced-set registers for register allocation 🦋-mfull-regs— uses full-set registers for register allocation 👑-mcmov— generates conditional move instructions 💅-mno-cmov— does not generate conditional move instructions 🙅♀️-mext-perf— generates performance extension instructions 🔥-mno-ext-perf— does not generate performance extension instructions 💀-mext-perf2— generates performance extension 2 instructions 🚀-mno-ext-perf2— does not generate performance extension 2 instructions 🥀-mext-string— generates string extension instructions 🧵-mno-ext-string— does not generate string extension instructions 🙈-mv3push— generates v3push25/pop25instructions 🧚-mno-v3push— does not generate v3push25/pop25instructions 💜-m16-bit— generates 16-bit instructions 🍓-mno-16-bit— does not generate 16-bit instructions 🌸-misr-vector-size=num— specifies the size of each interrupt vector, which must be4or16⭐-mcache-block-size=num— specifies the size of each cache block, which must be a power of 2 between4and512🧊-march=arch— specifies the name of the target architecture 🏹-mcmodel=code-model— sets the code model to one of these:small— all the data and read-only data segments must be within 512KB of addressing space, and the text segment must be within 16MB of addressing space 🌷medium— the data segment must be within 512KB, while the read-only data segment can be within 4GB of addressing space. The text segment should still be within 16MB of addressing space 🦋large— all the text and data segments can be within 4GB of addressing space 👑
-mctor-dtor— enables the constructor/destructor feature 🧚-mrelax— guides the linker to relax instructions 🫶
✨ Nios II Options ✨
These are the options defined for the Altera Nios II processor 💖
-G num— puts global and static objects less than or equal tonumbytes into the small data or BSS sections instead of the normal data or BSS sections 🎀 The default value ofnumis 8 ✨-mgpopt=option,-mgpopt, and-mno-gpopt— generate (or don't generate) GP-relative accesses 🧭 The following option names are recognized:none— does not generate GP-relative accesses 🙅♀️local— generates GP-relative accesses for small data objects that are not external, weak, or uninitialized common symbols. It also uses GP-relative addressing for objects that have been explicitly placed in a small data section via asectionattribute 🌸global— works likelocal, but also generates GP-relative accesses for small data objects that are external, weak, or common. If you use this option, you must make sure that all parts of your program (including libraries) are compiled with the same-Gsetting 🫶data— generates GP-relative accesses for all data objects in the program. If you use this option, the entire data and BSS segments of your program must fit in 64K of memory, and you must use an appropriate linker script to allocate them within the addressable range of the global pointer 🔥all— generates GP-relative addresses for function pointers as well as data pointers. If you use this option, the entire text, data, and BSS segments of your program must fit in 64K of memory, and you must use an appropriate linker script to allocate them within the addressable range of the global pointer 💀
-mgpopt is equivalent to -mgpopt=local, and -mno-gpopt is equivalent to -mgpopt=none 🧚
The default is -mgpopt unless -fpic or -fPIC is specified to generate position-independent code 🌈 Note that the Nios II ABI does not permit GP-relative accesses from shared libraries 😭
You may need to specify -mno-gpopt explicitly when building programs that include large amounts of small data, including large GOT data sections. In this case, the 16-bit offset for GP-relative addressing may not be large enough to allow access to the entire small data section 🙈
-mgprel-sec=regexp— specifies additional section names that can be accessed via GP-relative addressing 🍓 It's most useful alongsidesectionattributes on variable declarations and a custom linker script. Theregexpis a POSIX Extended Regular Expression 💜
This option doesn't affect how -G behaves. The specified sections are in addition to the standard .sdata and .sbss small-data sections that are recognized by -mgpopt 🦋
-mr0rel-sec=regexp— specifies names of sections that can be accessed via a 16-bit offset fromr0, meaning in the low 32K or high 32K of the 32-bit address space 🧊 It's most useful alongsidesectionattributes on variable declarations and a custom linker script. Theregexpis a POSIX Extended Regular Expression 🎀
Unlike GP-relative addressing for small data, zero-based addressing is never generated by default, and there are no conventional section names used in standard linker scripts for sections in the low or high areas of memory 🙅♀️
-meland-meb— generate little-endian (default) or big-endian (experimental) code, respectively 🌷-march=arch— specifies the name of the target Nios II architecture 🏹 GCC uses this name to figure out what kind of instructions it can emit when generating assembly code. The permissible names arer1andr2✨
The preprocessor macro __nios2_arch__ is available to programs, with a value of 1 or 2, indicating the targeted ISA level 🧠
-mbypass-cacheand-mno-bypass-cache— force all load and store instructions to always bypass the cache by using I/O variants of the instructions 🚀 The default is not to bypass the cache 💅-mno-cache-volatileand-mcache-volatile— volatile memory access bypasses the cache using the I/O variants of the load and store instructions 🧊 The default is not to bypass the cache 🥀-mno-fast-sw-divand-mfast-sw-div—-mno-fast-sw-divstops the use of table-based fast divide for small numbers 🙈 The default is to use the fast divide at-O3and above ⚡-mno-hw-mul,-mhw-mul,-mno-hw-mulx,-mhw-mulx,-mno-hw-div, and-mhw-div— enable or disable emitting themul,mulx, anddivfamily of instructions by the compiler 🧮 The default is to emitmuland not emitdivandmulx💖-mbmx,-mno-bmx,-mcdx, and-mno-cdx— enable or disable generation of Nios II R2 BMX (bit manipulation) and CDX (code density) instructions 🦋 Enabling these instructions also requires-march=r2. Since they're optional extensions to the R2 architecture, the default is not to emit them 🌈
-mcustom-insn=N, -mno-custom-insn
Okay bestie, so -mcustom-insn=N lets you hand a custom instruction with encoding N to any insn you pick 💅 For example, -mcustom-fadds=253 makes single-precision float adds use custom instruction 253 instead of the default library call. Iconic 🦋
The supported values of insn are below. Unless noted otherwise, floating-point ops are expected to follow normal IEEE 754 semantics and match the C operators or the equivalent GCC built-in functions ✨
💖 Single-precision floating point
fadds,fsubs,fdivs,fmuls— binary arithmetic ops 🧮fnegs— unary negationfabss— unary absolute valuefcmpeqs,fcmpges,fcmpgts,fcmples,fcmplts,fcmpnes— comparisons 👀fmins,fmaxs— floating-point min and max. These only get generated if-ffinite-math-onlyis specified 🙈fsqrts— unary square rootfcoss,fsins,ftans,fatans,fexps,flogs— floating-point trig and exponential functions. These only get generated if-funsafe-math-optimizationsis also specified ⚠️
🌈 Double-precision floating point
faddd,fsubd,fdivd,fmuld— binary arithmetic ops 🧮fnegd— unary negationfabsd— unary absolute valuefcmpeqd,fcmpged,fcmpgtd,fcmpled,fcmpltd,fcmpned— comparisons 👀fmind,fmaxd— double-precision min and max. These only get generated if-ffinite-math-onlyis specified 🙈fsqrtd— unary square rootfcosd,fsind,ftand,fatand,fexpd,flogd— double-precision trig and exponential functions. These only get generated if-funsafe-math-optimizationsis also specified ⚠️
🎀 Conversions
fextsd— single precision to double precision 🦋ftruncds— double precision to single precision 🦋fixsi,fixsu,fixdi,fixdu— floating point to signed or unsigned integers, truncating toward zero ✂️round— single-precision float to signed integer, rounding to the nearest integer with ties going away from zero. This matches the"__builtin_lroundf"function when-fno-math-errnois used 🍓floatis,floatus,floatid,floatud— signed or unsigned integers to floating point 🌸
Also, ngl, every double-precision instruction needs these transfer instructions for the internal registers X and Y to be provided first 🫶 Custom instructions that take two double-precision source operands expect the first operand in the 64-bit register X. The other operand (or the only operand of a unary op) goes to the custom arithmetic instruction with the least significant half in source register src1 and the most significant half in src2. A custom instruction that returns a double-precision result gives back the most significant 32 bits in the destination register, and the other half lands in the 32-bit register Y. GCC handles the setup code for writing X and/or reading Y automatically whenever you use double-precision instructions, so you don't have to 💅
fwrx— writessrc1into the least significant half ofXandsrc2into the most significant half ofXfwry— writessrc1intoYfrdxhi,frdxlo— reads the most or least significant half ofX(respectively) and stores it indestfrdy— readsYand stores it intodest
Note that you can get more local control over Nios II custom instruction generation with the target("custom-insn=N") and target("no-custom-insn") function attributes or pragmas 🔥
-mcustom-fpu-cfg=name— this enables a predefined, named set of custom instruction encodings (see-mcustom-insnabove). Currently these sets are defined 👑
-mcustom-fpu-cfg=60-1 is equivalent to: -mcustom-fmuls=252 -mcustom-fadds=253 -mcustom-fsubs=254 -fsingle-precision-constant
-mcustom-fpu-cfg=60-2 is equivalent to: -mcustom-fmuls=252 -mcustom-fadds=253 -mcustom-fsubs=254 -mcustom-fdivs=255 -fsingle-precision-constant
-mcustom-fpu-cfg=72-3 is equivalent to: -mcustom-floatus=243 -mcustom-fixsi=244 -mcustom-floatis=245 -mcustom-fcmpgts=246 -mcustom-fcmples=249 -mcustom-fcmpeqs=250 -mcustom-fcmpnes=251 -mcustom-fmuls=252 -mcustom-fadds=253 -mcustom-fsubs=254 -mcustom-fdivs=255 -fsingle-precision-constant
-mcustom-fpu-cfg=fph2 is equivalent to: -mcustom-fabss=224 -mcustom-fnegs=225 -mcustom-fcmpnes=226 -mcustom-fcmpeqs=227 -mcustom-fcmpges=228 -mcustom-fcmpgts=229 -mcustom-fcmples=230 -mcustom-fcmplts=231 -mcustom-fmaxs=232 -mcustom-fmins=233 -mcustom-round=248 -mcustom-fixsi=249 -mcustom-floatis=250 -mcustom-fsqrts=251 -mcustom-fmuls=252 -mcustom-fadds=253 -mcustom-fsubs=254 -mcustom-fdivs=255Heads up, bestie 🙈 Custom instruction assignments from individual -mcustom-insn= options always beat the ones from -mcustom-fpu-cfg=, no matter what order they show up in on the command line 💅
Note that you can get more local control over which FPU configuration gets picked by using the target("custom-fpu-cfg=name") function attribute or pragma 🎀
The name fph2 is short for Nios II Floating Point Hardware 2 Component 🧚 Also, the custom instructions enabled by -mcustom-fmins=233 and -mcustom-fmaxs=234 only get generated if -ffinite-math-only is specified. The custom instruction enabled by -mcustom-round=248 only gets generated if -fno-math-errno is specified. Unlike the other configurations, -fsingle-precision-constant is not set here 😭
These extra -m options are available for the Altera Nios II ELF (bare-metal) target 🦋
-mhal— links with the HAL BSP. This skips the GCC-provided C runtime startup and termination code, and it's usually paired with-msys-crt0=to point at the alternate startup code from the HAL BSP 🧚-msmallc— links with a limited version of the C library,-lsmallc, instead of Newlib 🌸-msys-crt0=startfile—startfileis the file name of the startfile (crt0) to use when linking. This only works together with-mhal💜-msys-lib=systemlib—systemlibis the library name for the low-level system calls the C library needs, like"read"and"write". This is usually used to link with a library from a HAL BSP ✨
💜 Nvidia PTX Options
These options are defined for Nvidia PTX 🦋
-m64— ignored, but kept around for backward compatibility. Only the 64-bit ABI is supported 🫶-march=architecture-string— generates code for the specified PTX ISA target architecture (e.g.sm_35). Valid architecture strings aresm_30,sm_35,sm_53,sm_70,sm_75andsm_80. The default depends on how the compiler was configured, see--with-arch🔥
This option also sets the preprocessor macro "__PTX_SM__". For example, for sm_35 it has the value 350 🍓
-misa=architecture-string— alias of-march=💅-march-map=architecture-string— picks the closest available-march=value that isn't more capable. For instance,-march-map=sm_50selects-march=sm_35, and-march-map=sm_53selects-march=sm_53🧠-mptx=version-string— generates code for the specified PTX ISA version (e.g.7.0). Valid version strings include3.1,6.0,6.3, and7.0. The default PTX ISA version is6.0, unless a higher version is needed for the PTX ISA target architecture given via-march=👑
This option sets the values of the preprocessor macros "__PTX_ISA_VERSION_MAJOR__" and "__PTX_ISA_VERSION_MINOR__". For instance, for 3.1 the macros have the values 3 and 1, respectively 🌈
-mmainkernel— links in code for a__mainkernel. This is for stand-alone execution instead of offloading 🧚-moptimize— applies partitioned execution optimizations. This is the default whenever any level of optimization is selected ✨-msoft-stack— generates code that doesn't use".local"memory directly for stack storage. Instead, a per-warp stack pointer gets maintained explicitly. This enables variable-length stack allocation (with variable-length arrays or"alloca"), and when global memory is used as the underlying storage, it makes it possible to access automatic variables from other threads, or with atomic instructions. This codegen variant is used for OpenMP offloading, but the option is exposed on its own so you can test the compiler. To generate code suitable for linking into programs that use OpenMP offloading, use-mgompinstead 🫶-muniform-simt— switches to a codegen variant that lets all threads in each warp execute, while keeping memory state and side effects as if only one thread in each warp were active outside of OpenMP SIMD regions. All atomic operations and calls to the runtime (malloc,free,vprintf) are conditionally executed (iff the current lane index equals the master lane index), and the register being assigned is copied via a shuffle instruction from the master lane. Outside of SIMD regions, lane 0 is the master; inside, each thread sees itself as the master. The shared memory arrayint __nvptx_uni[]stores all-zeros or all-ones bitmasks for each warp, indicating the current mode (0 outside of SIMD regions). Each thread can bitwise-and the bitmask at positiontid.ywith the current lane index to compute the master lane index 🌸-mgomp— generates code for OpenMP offloading. It enables-msoft-stackand-muniform-simtand selects the corresponding multilib variant 💖
🌸 OpenRISC Options
These options are defined for OpenRISC 🧚
-mboard=name— configures a board-specific runtime. This gets passed to the linker for newlib board library linking. The default is"or1ksim"🍓-mnewlib— Total ghost energy 👻 This option is ignored and only hangs around for compatibility. It used to pick linker and preprocessor options for newlib 🎀-msoft-div,-mhard-div— Choose software or hardware divide (l.div,l.divu) instructions 💅 Hardware divide is the default, so you're already getting the good stuff ✨-msoft-mul,-mhard-mul— Choose software or hardware multiply (l.mul,l.muli) instructions 🔥 Hardware multiply is the default, no notes 💖-msoft-float,-mhard-float— Pick software or hardware for floating point operations 🦋 Software is the default, so it's a whole vibe.-mdouble-float— When-mhard-floatis selected, this turns on double-precision floating point instructions 🌸 By default, functions fromlibgcchandle double-precision floating point operations.-munordered-float— When-mhard-floatis selected, this unlocks unordered floating point compare and set flag (lf.sfun*) instructions 🫶 By default, functions fromlibgcchandle unordered floating point compare and set flag operations.-mcmov— Turns on conditional move (l.cmov) instructions ⭐ Without it, the same result is made with set and branch.-mror— Turns on rotate right (l.ror) instructions 🌈 By default, functions fromlibgcchandle rotate right operations.-mrori— Turns on rotate right with immediate (l.rori) instructions 🧚 By default, functions fromlibgcchandle rotate right with immediate operations.-msext— Turns on sign extension (l.ext*) instructions 💜 By default, memory loads do the sign extension work.-msfimm— Turns on compare and set flag with immediate (l.sf*i) instructions 🍓 By default, extra instructions get generated to store the immediate in a register first.-mshftimm— Turns on shift with immediate (l.srai,l.srli,l.slli) instructions 🎀 By default, extra instructions get generated to store the immediate in a register first.-mcmodel=small— Generates OpenRISC code for the small model 🦋 The GOT is limited to 64k. This is the default model.-mcmodel=large— Generates OpenRISC code for the large model 👑 The GOT may grow up to 4G in size.
🧚 PDP-11 Options 🧚
These options are defined for the PDP-11:
-mfpu— Uses hardware FPP floating point 💅 This is the default. (FIS floating point on the PDP-11/40 is not supported.) Implies-m45.-msoft-float— Does not use hardware floating point 🫠-mac0— Returns floating-point results inac0(fr0in Unix assembler syntax) ✨-mno-ac0— Returns floating-point results in memory 🌸 This is the default.-m40— Generates code for a PDP-11/40 💖 Implies-msoft-float -mno-split.-m45— Generates code for a PDP-11/45 🔥 This is the default.-m10— Generates code for a PDP-11/10 🍓 Implies-msoft-float -mno-split.-mint16,-mno-int32— Uses 16-bitint👑 This is the default.-mint32,-mno-int16— Uses 32-bitint🌈-msplit— The target has split instruction and data space 🦋 Implies-m45.-munix-asm— Uses Unix assembler syntax 🧚-mdec-asm— Uses DEC assembler syntax 💜-mgnu-asm— Uses GNU assembler syntax 🎀 This is the default.-mlra— Uses the new LRA register allocator ⭐ By default, the oldreloadallocator is used.
💖 PowerPC Options 💖
These are listed under
🌈 PRU Options 🌈
These command-line options are defined for PRU target:
-minrt— Links with a minimum runtime environment 🫶 This can significantly shrink the final ELF binary, but some standard C runtime features get removed.
This option disables support for static initializers and constructors 💀 Beware that the compiler could still generate code with static initializers and constructors. It is up to the programmer to make sure the source program won't use those features.
The minimal startup code would not pass argc and argv arguments to main, so main must be declared as int main (void). This is already the norm for most firmware projects ✨
-mmcu=mcu— Specifies the PRU hardware variant to use 🔥 A correspondingly named spec file would be loaded, passing the memory region sizes to the linker and defining hardware-specific C macros.
Newlib provides only the sim spec, which is meant for running regression tests using a simulator 🧪 Specs for real hardware can be obtained by installing the GnuPruMcu (https://github.com/dinuxbg/gnuprumcu/) package.
-mno-relax— Makes GCC pass the--no-relaxcommand-line option to the linker instead of the--relaxoption 🌸-mloop— Allows (or does not allow) GCC to use theLOOPinstruction 🍓-mabi=variant— Specifies the ABI variant to output code for 💅-mabi=tiselects the unmodified TI ABI, while-mabi=gnuselects a GNU variant that copes more naturally with certain GCC assumptions. These are the differences:- Function Pointer Size — TI ABI specifies that function (code) pointers are 16-bit, whereas GNU supports only 32-bit data and code pointers 🦋
- Optional Return Value Pointer — Function return values larger than 64 bits are passed by using a hidden pointer as the first argument of the function. TI ABI, though, mandates that the pointer can be
NULLin case the caller is not using the returned value. GNU always passes and expects a valid return value pointer 👑
The current -mabi=ti implementation simply raises a compile error when any of the above code constructs is detected 🙈 As a consequence, the standard C library cannot be built, and it is omitted when linking with -mabi=ti.
Relaxation is a GNU feature, and for safety reasons it is disabled when using -mabi=ti 💀 The TI toolchain does not emit relocations for QBBx instructions, so the GNU linker cannot adjust them when shortening adjacent LDI32 pseudo instructions.
🦋 RISC-V Options 🦋
These command-line options are defined for RISC-V targets:
-mbranch-cost=n— Sets the cost of branches to roughlyninstructions 💜-mplt,-mno-plt— When generating PIC code, do or don't allow the use of PLTs 🎀 Ignored for non-PIC. The default is-mplt.-mabi=ABI-string— Specifies the integer and floating-point calling convention 🌈ABI-stringhas two parts: the size of integer types and the registers used for floating-point types. For example,-march=rv64ifd -mabi=lp64dmeans thatlongand pointers are 64-bit (implicitly definingintto be 32-bit), and that floating-point values up to 64 bits wide are passed in F registers. Contrast this with-march=rv64ifd -mabi=lp64f, which still lets the compiler generate code that uses the F and D extensions, but only allows floating-point values up to 32 bits long to be passed in registers. Or there's-march=rv64ifd -mabi=lp64, where no floating-point arguments get passed in registers 🧚
The default for this argument is system dependent, so users who want a specific calling convention should specify one explicitly 💖 The valid calling conventions are: ilp32, ilp32f, ilp32d, lp64, lp64f, and lp64d. Some calling conventions are impossible to implement on some ISAs: for example, -march=rv32if -mabi=ilp32d is invalid, because the ABI requires 64-bit values to be passed in F registers, but F registers are only 32 bits wide 🙅♀️ There's also the ilp32e ABI, which can only be used with the rv32e architecture, and the lp64e ABI, which can only be used with rv64e. Those ABIs are not well specified at present and are subject to change.
-mfdiv,-mno-fdiv— Do or don't use hardware floating-point divide and square root instructions ⭐ This requires the F or D extensions for floating-point registers. The default is to use them if the specified architecture has these instructions.-mdiv,-mno-div— Do or don't use hardware instructions for integer division 🔥 This requires the M extension. The default is to use them if the specified architecture has these instructions.-misa-spec=ISA-spec-string— Specifies the version of the RISC-V Unprivileged (formerly User-Level) ISA specification to produce code conforming to 🫶 The possibilities forISA-spec-stringare:2.2— Produce code conforming to version 2.2.20190608— Produce code conforming to version 20190608.20191213— Produce code conforming to version 20191213.
The default is -misa-spec=20191213, unless GCC has been configured with --with-isa-spec= specifying a different default version 🌸
-march=ISA-string— Generates code for the given RISC-V ISA (e.g.rv64im) 💅 ISA strings must be lower-case. Examples includerv64i,rv32g,rv32e, andrv32imaf. There's also a special value,help(-march=help), that lists all supported extensions 🦋
The syntax of the ISA string is defined as follows:
- "The string must start with rv32 or rv64, followed by"
i,e, org, referred to as the base ISA 🧚 - "The subsequent part of the string is a list of extension names. Extension names" can be categorized as multi-letter (e.g.
zba) and single-letter (e.g.v). Single-letter extensions can appear consecutively, but multi-letter extensions must be separated by underscores 🌈 - "An underscore can appear anywhere after the base ISA. It has no specific effect" but is used to improve readability and can act as a separator 💜
- "Extension names may include an optional version number, following the syntax"
<major>p<minor>or<major>, (e.g.m2p1orm2) 🎀
Supported extensions are listed below 👑
Extension Name : Supported Version : Description
i @tab 2.0, 2.1 @tab Base integer extension.
e @tab 2.0 @tab Reduced base integer extension.
g @tab - @tab General-purpose computing base extension, g will expand to i, m, a, f, d, zicsr and zifencei.
m @tab 2.0 @tab Integer multiplication and division extension.
a @tab 2.0, 2.1 @tab Atomic extension.
f @tab 2.0, 2.2 @tab Single-precision floating-point extension.
d @tab 2.0, 2.2 @tab Double-precision floating-point extension.
c @tab 2.0 @tab Compressed extension.
h @tab 1.0 @tab Hypervisor extension.v(1.0) — 🌈 the Vector extension, the main vibe for all things vector! ✨zicsr(2.0) — 💅 control and status register access, literally the CSR stuff 🔥zifencei(2.0) — 🧚 the instruction-fetch fence extension 🫶zicond(1.0) — 💖 integer conditional operations, lowkey so usefulza64rs(1.0) — 🎀 reservation set size of 64 bytesza128rs(1.0) — 🎀 reservation set size of 128 bytes, the bigger siblingzawrs(1.0) — ⏳ wait-on-reservation-set extension, patience is a vibe 🌸zba(1.0) — 🦋 address calculation extensionzbb(1.0) — 🧠 basic bit manipulation, very smart energy 💜zbc(1.0) — ✨ carry-less multiplication extensionzbs(1.0) — 🍓 single-bit operation extensionzfinx(1.0) — 🔥 single-precision floating-point in integer registers extensionzdinx(1.0) — 🔥 double-precision floating-point in integer registers extensionzhinx(1.0) — 🔥 half-precision floating-point in integer registers extensionzhinxmin(1.0) — 🔥 the minimal half-precision version of the integer-register floating-point extensionzbkb(1.0) — 🔐 cryptography bit-manipulation extensionzbkc(1.0) — 🔐 cryptography carry-less multiply extensionzbkx(1.0) — 🔐 cryptography crossbar permutation extensionzkne(1.0) — 🗝️ AES encryption extensionzknd(1.0) — 🗝️ AES decryption extensionzknh(1.0) — 🫶 hash function extensionzkr(1.0) — 🎲 entropy source extension, very random, very cutezksed(1.0) — 🔐 SM4 block cipher extensionzksh(1.0) — 🔐 SM3 hash function extensionzkt(1.0) — ⏱️ data independent execution latency extensionzk(1.0) — 💜 standard scalar cryptography extension, the whole crypto packagezkn(1.0) — 💜 NIST algorithm suite extensionzks(1.0) — 💜 ShangMi algorithm suite extensionzihintntl(1.0) — 🌷 non-temporal locality hints extensionzihintpause(1.0) — ⏸️ pause hint extension, chill momentzicboz(1.0) — 🧊 cache-block zero extensionzicbom(1.0) — 🧊 cache-block management extensionzicbop(1.0) — 🧊 cache-block prefetch extensionzic64b(1.0) — 🧊 the cache block size is 64 bytes, no capziccamoa(1.0) — 🧠 main memory supports all atomics in Aziccif(1.0) — 🧠 main memory supports instruction fetch with an atomicity requirementzicclsm(1.0) — 🧠 main memory supports misaligned loads and storesziccrse(1.0) — 🧠 main memory supports forward progress on LR/SC sequenceszicntr(2.0) — ⏰ standard extension for base counters and timerszihpm(2.0) — 📈 standard extension for hardware performance countersztso(1.0) — 🧱 total store ordering extensionzve32x(1.0) — 🌸 vector extensions for embedded processorszve32f(1.0) — 🌸 vector extensions for embedded processorszve64x(1.0) — 🌸 vector extensions for embedded processorszve64f(1.0) — 🌸 vector extensions for embedded processorszve64d(1.0) — 🌸 vector extensions for embedded processorszvl32b(1.0) — 📏 minimum vector length standard extensionzvl64b(1.0) — 📏 minimum vector length standard extensionzvl128b(1.0) — 📏 minimum vector length standard extensionzvl256b(1.0) — 📏 minimum vector length standard extensionzvl512b(1.0) — 📏 minimum vector length standard extensionzvl1024b(1.0) — 📏 minimum vector length standard extensionzvl2048b(1.0) — 📏 minimum vector length standard extensionzvl4096b(1.0) — 📏 minimum vector length standard extensionzvbb(1.0) — 🧠 vector basic bit-manipulation extensionzvbc(1.0) — ✨ vector carry-less multiplication extensionzvkb(1.0) — 🔐 vector cryptography bit-manipulation extensionzvkg(1.0) — 🔐 vector GCM/GMAC extensionzvkned(1.0) — 🗝️ vector AES block cipher extensionzvknha(1.0) — 🫶 vector SHA-2 secure hash extensionzvknhb(1.0) — 🫶 vector SHA-2 secure hash extensionzvksed(1.0) — 🔐 vector SM4 block cipher extensionzvksh(1.0) — 🔐 vector SM3 secure hash extensionzvkn(1.0) — 💜 vector NIST algorithm suite extension, and it expands tozvkned,zvknhb,zvkbandzvkt👑zvknc(1.0) — 💜 vector NIST algorithm suite with carry-less multiply extension, and it expands tozvknandzvbc👑zvkng(1.0) — 💜 vector NIST algorithm suite with GCM extension, and it expands tozvknandzvkg👑zvks(1.0) — 💜 vector ShangMi algorithm suite extension, and it expands tozvksed,zvksh,zvkbandzvkt👑zvksc(1.0) — 💜 vector ShangMi algorithm suite with carry-less multiplication extension, and it expands tozvksandzvbc👑zvksg(1.0) — 💜 vector ShangMi algorithm suite with GCM extension, and it expands tozvksandzvkg👑zvkt(1.0) — ⏱️ vector data independent execution latency extensionzfh(1.0) — 🔥 half-precision floating-point extensionzfhmin(1.0) — 🔥 minimal half-precision floating-point extensionzvfh(1.0) — 🔥 vector half-precision floating-point extensionzvfhmin(1.0) — 🔥 vector minimal half-precision floating-point extensionzvfbfmin(1.0) — 🔥 vector BF16 converts extensionzfa(1.0) — ➕ additional floating-point extensionzmmul(1.0) — ✖️ integer multiplication extensionzca(1.0) — 🗜️ integer compressed instruction extensionzcf(1.0) — 🗜️ compressed single-precision floating-point loads and stores extensionzcd(1.0) — 🗜️ compressed double-precision floating-point loads and stores extensionzcb(1.0) — 🗜️ simple compressed instruction extensionzce(1.0) — 🗜️ compressed instruction extensions for embedded processorszcmp(1.0) — 📚 compressed push and pop extensionzcmt(1.0) — 📚 table jump instruction extensionsmaia(1.0) — 🛎️ advanced interrupt architecture extensionsmepmp(1.0) — 🛡️ PMP enhancements for memory access and execution prevention in machine modesmstateen(1.0) — 🌈 state enable extensionssaia(1.0) — 🛎️ advanced interrupt architecture extension for supervisor modesscofpmf(1.0) — 📈 count overflow and filtering extensionssstateen(1.0) — 🌈 state-enable extension for supervisor modesstc(1.0) — ⏰ supervisor-mode timer interrupts extensionsvinval(1.0) — 🧹 fine-grained address-translation cache invalidation extensionsvnapot(1.0) — 🗺️ NAPOT translation contiguity extensionsvpbmt(1.0) — 🗺️ page-based memory types extensionxcvmac(1.0) — 🤖 Core-V multiply-accumulate extensionxcvalu(1.0) — 🤖 Core-V miscellaneous ALU extensionxcvelw(1.0) — 🤖 Core-V event load word extensionxtheadba(1.0) — 🐉 T-Head address calculation extensionxtheadbb(1.0) — 🐉 T-Head basic bit-manipulation extensionxtheadbs(1.0) — 🐉 T-Head single-bit instructions extensionxtheadcmo(1.0) — 🐉 T-Head cache management operations extensionxtheadcondmov(1.0) — 🐉 T-Head conditional move extensionxtheadfmemidx(1.0) — 🐉 T-Head indexed memory operations for floating-point registers extensionxtheadfmv(1.0) — 🐉 T-Head double floating-point high-bit data transmission extensionxtheadint(1.0) — 🐉 T-Head acceleration interruption extensionxtheadmac(1.0) — 🐉 T-Head multiply-accumulate extensionxtheadmemidx(1.0) — 🐉 T-Head indexed memory operation extensionxtheadmempair(1.0) — 🐉 T-Head two-GPR memory operation extensionxtheadsync(1.0) — 🐉 T-Head multi-core synchronization extensionxventanacondops(1.0) — 🌟 Ventana integer conditional operations extension
When -march= is not specified, use the setting from -mcpu. 🫶
If both -march and -mcpu= are not specified, the default for this argument is system dependent, so bestie, if you want a specific architecture extension, you should specify one explicitly. 💅
✨ -mcpu=processor-string
Use the architecture of, and optimize the output for, the given processor, specified by a particular CPU name. 🎀 Permissible values for this option are: sifive-e20, sifive-e21, sifive-e24, sifive-e31, sifive-e34, sifive-e76, sifive-s21, sifive-s51, sifive-s54, sifive-s76, sifive-u54, sifive-u74, sifive-x280, sifive-xp450 and sifive-x670. 🦋
Note that -mcpu does not override -march or -mtune. 🙈
🌸 -mtune=processor-string
Optimize the output for the given processor, specified by microarchitecture or a particular CPU name. ⭐ Permissible values for this option are: rocket, sifive-3-series, sifive-5-series, sifive-7-series, thead-c906, size, sifive-p400-series, sifive-p600-series, and all valid options for -mcpu=. 💖
When -mtune= is not specified, use the setting from -mcpu. The default is rocket if both are not specified. 🧚
⚠️ Thesizechoice is not intended for use by end-users, bestie, so hands off! 🙅 It is used when-Osis specified. It overrides the instruction cost info provided by-mtune=, but it does not override the pipeline info. This helps reduce code size while still giving good performance. 👑
-mpreferred-stack-boundary=num— okay so this one tries to keep the stack boundary lined up to a2raised to num byte boundary 📏✨. If you don't specify it, the default is4(that's 16 bytes or 128-bits) 💅.
⚠️ Warning, bestie 🚨: if you use this switch, you HAVE to build every single module with the same value, libraries included. That covers the system libraries and startup modules too 😭.
-msmall-data-limit=n— puts global and static data smaller thannbytes into a special section 🧚, but only on some targets 🌈.-msave-restore,-mno-save-restore— these decide whether you get the smaller-but-slower prologue and epilogue code that calls library functions 🐢. The default is the fast inline prologues and epilogues ⚡, so you're only switching to the slow lane if you ask for it 💜.-mmovcc,-mno-movcc— this one is giving branchless conditional-move code sequences 🦋, even on targets that don't have special instructions for conditional operations. If it's enabled, sequences of ALU operations get built from base integer ISA instructions wherever that's profitable 🔥.-minline-atomics,-mno-inline-atomics— choose between smaller but slower subword atomic emulation that callslibatomicfunctions 🐌, or the fast inline subword atomics that don't needlibatomicat all 💖. The default is the fast inline version, obviously 👑.-minline-strlen,-mno-inline-strlen— you can ask GCC to try inliningstrlencalls if it's possible 🌸. It'll only actually do it if the string is properly aligned and the accelerated instructions are around ✨. By default, it does NOT inlinestrlencalls 🙈.-minline-strcmp,-mno-inline-strcmp— same vibe asstrlen, but forstrcmpcalls 💅. Inlining only happens when the strings are properly aligned and the accelerated instructions are available 🔥. The default is to not inlinestrcmpcalls 🫶.
The --param riscv-strcmp-inline-limit=n parameter controls the maximum number of bytes compared by the inlined code 📏. Its default value is 64 🌈.
-minline-strncmp,-mno-inline-strncmp— thestrncmpversion of the same story 🎀. Inlining only happens when the strings are properly aligned and the accelerated instructions exist ✨. Default is to not inlinestrncmpcalls 🦋.
Same deal with --param riscv-strcmp-inline-limit=n: it sets the maximum number of bytes compared by the inlined code, and the default is 64 💜.
-mshorten-memrefs,-mno-shorten-memrefs— this one is lowkey genius 🧠. It tries to use more compressed load/store instructions by swapping a load/store ofbase register + large offsetfor a new load/store ofnew base + small offset🪄. If that new base lands in a compressed register, the new load/store can be compressed too 🗜️. Right now it only targets 32-bit integer load/stores 🎯.-mstrict-align,-mno-strict-align— decides whether unaligned memory accesses get generated or not 🙅♀️. The default depends on whether the processor you're optimizing for supports fast unaligned access 🏃♀️.-mcmodel=medlow— generates code for the medium-low code model 🌙. The program and its statically defined symbols have to live inside a single 2 GiB address range, sitting between absolute addresses-2 GiBand+2 GiB📍. Programs can be statically or dynamically linked 🔗. This is the default code model 👑.-mcmodel=medany— generates code for the medium-any code model 🌍. The program and its statically defined symbols just need to be within any single 2 GiB address range 💫. Programs can be statically or dynamically linked 🧚.
Heads up though 🚨: the code from medium-any is position-independent, but it's NOT guaranteed to work correctly when linked into position-independent executables or libraries 💀.
-mexplicit-relocs,-mno-exlicit-relocs— you either use assembler relocation operators when dealing with symbolic addresses 🧩, or you don't. The alternative is assembler macros instead, and those might limit optimization 🙈.-mrelax,-mno-relax— takes advantage of linker relaxations 🪶 to cut down on the number of instructions needed to materialize symbol addresses ✂️. The default is to take advantage of linker relaxations 💖.-mriscv-attribute,-mno-riscv-attribute— emits (or doesn't emit) a RISC-V attribute that records extra information into ELF objects 📦. This feature needs at least binutils 2.32 🛠️.-mcsr-check,-mno-csr-check— enables or disables the CSR checking 🔍.-malign-data=type— controls how GCC aligns variables and constants of array, structure, or union types 📐. The supported values for type arexlen, which uses the x register width as the alignment value, andnatural, which uses natural alignment 🎀.xlenis the default 💅.-mbig-endian— generates big-endian code 🐘. This is the default when GCC is configured for ariscv64be-*-*orriscv32be-*-*target 🌊.-mlittle-endian— generates little-endian code 🐣. This is the default when GCC is configured for ariscv64-*-*orriscv32-*-*target, but NOT ariscv64be-*-*orriscv32be-*-*target 🦋.-mstack-protector-guard=guard,-mstack-protector-guard-reg=reg,-mstack-protector-guard-offset=offset— generates stack protection code using a canary at guard 🛡️. The supported locations areglobalfor a global canary, ortlsfor a per-thread canary in the TLS block 🧵.
With the tls choice, -mstack-protector-guard-reg=reg and -mstack-protector-guard-offset=offset get to decide which register is used as the base register for reading the canary 🎯, and what offset from that base register it's read from 📍. There's no default register or offset here, because this is entirely for use within the Linux kernel 🐧.
-mtls-dialect=desc— uses TLS descriptors as the thread-local storage mechanism for dynamic accesses of TLS variables 🧵✨.-mtls-dialect=trad— uses traditional TLS as the thread-local storage mechanism for dynamic accesses of TLS variables 🕰️. This is the default 👑.
🌸 RL78 Options 🌸
-msim— links in additional target libraries so things can run inside a simulator 🎮.-mmul=none,-mmul=g10,-mmul=g13,-mmul=g14,-mmul=rl78— picks the type of hardware multiplication and division support you want 🧮. The simplest is"none", which uses software for both multiplication and division, and it's the default 💅. The"g13"value is for the hardware multiply/divide peripheral on the RL78/G13 (S2 core) targets 🔧. The"g14"value selects the multiplication and division instructions supported by the RL78/G14 (S3 core) parts 🚀. The value"rl78"is an alias for"g14", and the value"mg10"is an alias for"none"🦋.
Also, a C preprocessor macro gets defined based on this setting 🪄. The possible values are "__RL78_MUL_NONE__", "__RL78_MUL_G13__", or "__RL78_MUL_G14__" ✨.
-mcpu=g10,-mcpu=g13,-mcpu=g14,-mcpu=rl78— specifies which RL78 core you're targeting 🎯. The default is the G14 core, which is also known as an S3 core or just RL78 👑. The G13 (or S2) core doesn't have multiply or divide instructions, so it uses a hardware peripheral for those operations instead 🔧. The G10 (or S1) core doesn't have register banks, so it uses a different calling convention 🙃.
If you set this option, it also picks the type of hardware multiply support to use 💖, unless you override it with an explicit -mmul=none on the command line. So -mcpu=g13 turns on the G13 hardware multiply peripheral, and -mcpu=g10 turns hardware multiplications off altogether 🙅♀️.
Now, the RL78/G14 core is the default target, BUT specifying -mcpu=g14 or -mcpu=rl78 on the command line really does change how the toolchain behaves 😭, because it also enables G14 hardware multiply support. If you don't specify these on the command line, software multiplication routines get used even though the code targets the RL78 core 🐢. That's there for backwards compatibility with older toolchains that didn't have hardware multiply and divide support 🫶.
And yep, a C preprocessor macro gets defined based on this setting too 🌈. The possible values are "__RL78_G10__", "__RL78_G13__", or "__RL78_G14__" 💜.
-mg10,-mg13,-mg14,-mrl78— these are aliases for the matching-mcpu=option 🔁. They only exist for backwards compatibility 🕰️.-mallregs— lets the compiler use all of the available registers 🧠. By default, registersr24..r31are reserved for interrupt handlers 🚧. With this option on, those registers can be used in ordinary functions as well 🔓.-m64bit-doubles,-m32bit-doubles— makes thedoubledata type 64 bits (-m64bit-doubles) or 32 bits (-m32bit-doubles) in size 📏. The default is-m32bit-doubles💅.-msave-mduc-in-interrupts,-mno-save-mduc-in-interrupts— says whether interrupt handler functions should preserve the MDUC registers 🛡️. This is only necessary if normal code might use the MDUC registers, like when it does multiplication and division operations ✖️➗. The default is to ignore the MDUC registers, because that makes the interrupt handlers faster ⚡. The target option-mg13needs to be passed for this to work, since this feature is only available on the G13 target (S2 core) 🔧. The MDUC registers only get saved if the interrupt handler performs a multiplication or division operation, or if it calls another function 🫧.
🦋 IBM RS/6000 and PowerPC Options 🦋
These -m options are defined for the IBM RS/6000 and PowerPC 🖥️:
-mpowerpc-gpopt
-mno-powerpc-gpopt
-mpowerpc-gfxopt
-mno-powerpc-gfxopt
-mpowerpc64
-mno-powerpc64
-mmfcrf
-mno-mfcrf
-mpopcntb
-mno-popcntb
-mpopcntd
-mno-popcntd
-mfprnd
-mno-fprnd
-mcmpb
-mno-cmpb
-mhard-dfp
-mno-hard-dfpYou use these options to say which instructions are available on the processor you're using 🎀. The default value of these options gets determined when GCC is configured 🛠️. Specifying -mcpu=cpu_type overrides whatever you set with these options 🙅♀️, so we recommend using the -mcpu=cpu_type option instead of the options listed above 🫶.
Specifying -mpowerpc-gpopt lets GCC use the optional PowerPC architecture instructions in the General Purpose group, including floating-point square root 🔥. Specifying -mpowerpc-gfxopt lets GCC use the optional PowerPC architecture instructions in the Graphics group, including floating-point select ✨.
The POWER feature flags are next, bestie, and they're a whole vibe 🌸 Each one switches on an instruction set that a specific chip family shipped with 🦋
-mmfcrf— lets GCC emit the move from condition register field instruction 💅 That's the one from the POWER4 processor, plus other chips that support the PowerPC V2.01 architecture.-mpopcntb— unlocks the popcount and double-precision FP reciprocal estimate instruction ✨ That's from the POWER5 processor, plus other chips that support the PowerPC V2.02 architecture.-mpopcntd— unlocks the popcount instruction 🔥 That's from the POWER7 processor, plus other chips that support the PowerPC V2.06 architecture.-mfprnd— unlocks the FP round to integer instructions 🌈 That's from the POWER5+ processor, plus other chips that support the PowerPC V2.03 architecture.-mcmpb— unlocks the compare bytes instruction 🍓 That's from the POWER6 processor, plus other chips that support the PowerPC V2.05 architecture.-mhard-dfp— unlocks the decimal floating-point instructions, which show up on some POWER processors 🧚
The -mpowerpc64 option lets GCC generate the extra 64-bit instructions from the full PowerPC64 architecture, and it treats GPRs as 64-bit doubleword quantities 💖 GCC defaults to -mno-powerpc64, so you have to ask for it on purpose.
-mcpu=cpu_type— this one sets the architecture type, register usage, and instruction scheduling parameters for the machine type you name 👑 The supported values are:
401, 403, 405, 405fp, 440, 440fp, 464, 464fp, 476, 476fp, 505, 601, 602, 603, 603e, 604, 604e, 620, 630, 740, 7400, 7450, 750, 801, 821, 823, 860, 970, 8540, a2, e300c2, e300c3, e500mc, e500mc64, e5500, e6500, ec603e, G3, G4, G5, titan, power3, power4, power5, power5+, power6, power6x, power7, power8, power9, power10, powerpc, powerpc64, powerpc64le, rs64, and native.
Bestie, -mcpu=powerpc, -mcpu=powerpc64, and -mcpu=powerpc64le are the generic ones 🫶 They give you pure 32-bit PowerPC (either endian), 64-bit big endian PowerPC, and 64-bit little endian PowerPC architecture machine types. GCC assumes an appropriate, generic processor model for scheduling purposes.
Specifying native as the cpu type detects the host processor of the system doing the compilation and picks the architecture option that matches it 🦋 -mcpu=native has no effect if GCC doesn't recognize the processor, so it just does nothing, which is fine.
The other values name one specific processor. Code generated for those runs best on that chip, and it may not run at all on others.
Heads up, babe: if you target a specific processor, the code might not run on anything else at all 💀 Keep that in mind before you ship it.
The -mcpu options automatically enable or disable the following options 🌸
-maltivec -mfprnd -mhard-float -mmfcrf -mmultiple -mpopcntb
-mpopcntd -mpowerpc64 -mpowerpc-gpopt -mpowerpc-gfxopt -mmulhw
-mdlmzb -mmfpgpr -mvsx -mcrypto -mhtm -mpower8-fusion
-mquad-memory -mquad-memory-atomic -mfloat128 -mfloat128-hardware
-mprefixed -mpcrel -mmma -mrop-protectThe exact set for each CPU changes between compiler versions. GCC picks whatever seems to produce the best code for that CPU, so it doesn't always match what the hardware can actually do 🙈 If you want to set one individual option to a specific value, put it after the -mcpu option, like -mcpu=970 -mno-altivec. Main character move 💅
On AIX, -maltivec and -mpowerpc64 aren't enabled or disabled by -mcpu right now, because AIX doesn't have full support for those options yet 😭 You can still turn them on or off one at a time if you're sure it'll work in your environment.
-mtune=cpu_type— this sets only the instruction scheduling parameters for the machine type you name ✨ It does not set the architecture type or register usage the way-mcpu=cpu_typedoes. The same values forcpu_typework for-mtuneas for-mcpu. If you specify both, the code uses the architecture and registers from-mcpu, but the scheduling parameters come from-mtune.-mcmodel=small— generates PowerPC64 code for the small model, where the TOC is limited to 64k 🧚-mcmodel=medium— generates PowerPC64 code for the medium model, where the TOC and other static data can total up to 4G in size. This is the default for 64-bit Linux 🌈-mcmodel=large— generates PowerPC64 code for the large model, where the TOC can be up to 4G in size. Other data and code is only limited by the 64-bit address space 👑-maltivec,-mno-altivec— makes GCC generate (or not generate) AltiVec instructions, and also turns on (or off) built-in functions that give you more direct access to the AltiVec instruction set 💖 You might also need to set-mabi=altivecto adjust the current ABI with AltiVec ABI enhancements.
When you use -maltivec, the element order for AltiVec intrinsics like vec_splat, vec_extract, and vec_insert matches the array element order for the target's endianness 🫶 On a big-endian target, element zero is the leftmost element in a vector register. On a little-endian target, element zero is the rightmost element in a vector register.
-mvrsave,-mno-vrsave— makes GCC generate (or not generate) VRSAVE instructions when it's generating AltiVec code 💅-msecure-plt— generates code that letsldandld.sobuild executables and shared libraries with non-executable.pltand.gotsections 🔒 This is a PowerPC 32-bit SYSV ABI option.-mbss-plt— generates code that uses a BSS.pltsection thatld.sofills in. It requires.pltand.gotsections that are both writable and executable 🙈 This is a PowerPC 32-bit SYSV ABI option.-misel,-mno-isel— turns the generation of ISEL instructions on or off ✨-mvsx,-mno-vsx— makes GCC generate (or not generate) vector/scalar (VSX) instructions, and also turns on (or off) built-in functions that give you more direct access to the VSX instruction set 🔥-mcrypto,-mno-crypto— enables (or disables) the built-in functions that give you direct access to the cryptographic instructions added in version 2.07 of the PowerPC ISA 🦋-mhtm,-mno-htm— enables (or disables) the built-in functions that give you direct access to the Hardware Transactional Memory (HTM) instructions added in version 2.07 of the PowerPC ISA 🌸-mpower8-fusion,-mno-power8-fusion— the first one generates code that keeps some integer operations adjacent, so the instructions can be fused together on POWER8 and later processors 🧚 The second one generates code that does not keep them adjacent.-mquad-memory,-mno-quad-memory— makes GCC generate (or not generate) the non-atomic quad word memory instructions 🍓-mquad-memoryrequires 64-bit mode.-mquad-memory-atomic,-mno-quad-memory-atomic— makes GCC generate (or not generate) the atomic quad word memory instructions 🍓-mquad-memory-atomicrequires 64-bit mode.-mfloat128,-mno-float128— enables or disables the__float128keyword for IEEE 128-bit floating point, and picks either software emulation or hardware instructions for it 💜
The VSX instruction set (-mvsx) has to be enabled before you can use IEEE 128-bit floating point support 🫶 Also, IEEE 128-bit floating point is only supported on Linux.
Only Linux gets IEEE 128-bit floating point support, so it's a no-go anywhere else 💀
The default for -mfloat128 is enabled on PowerPC Linux systems that use the VSX instruction set, and disabled on other systems ✨
If you use the ISA 3.0 instruction set (-mcpu=power9) on a 64-bit system, IEEE 128-bit floating point support also enables the generation of ISA 3.0 IEEE 128-bit floating point instructions 🌈 Otherwise, if you don't ask for ISA 3.0 instructions, or you're targeting a 32-bit big endian system, IEEE 128-bit floating point is done with software emulation.
-mfloat128-hardware,-mno-float128-hardware— enables (or disables) using ISA 3.0 hardware instructions to support the__float128data type 🔥
The default for -mfloat128-hardware is enabled on PowerPC Linux systems that use the ISA 3.0 instruction set, and disabled on other systems 👑
-m32,-m64— generates code for 32-bit or 64-bit environments on Darwin and SVR4 targets, including GNU/Linux 🌈 The 32-bit environment setsint,long, and pointer to 32 bits, and generates code that runs on any PowerPC variant. The 64-bit environment setsintto 32 bits, setslongand pointer to 64 bits, and generates code for PowerPC64, as if you'd used-mpowerpc64.-mfull-toc,-mno-fp-in-toc,-mno-sum-in-toc,-mminimal-toc— these change how the TOC (Table Of Contents) is generated. Every executable file gets one 🧚-mfull-tocis selected by default. With it, GCC allocates at least one TOC entry for each unique non-automatic variable reference in your program, and it also puts floating-point constants in the TOC. The catch is that only 16,384 entries are available in the TOC 😭
If the linker tells you that you've overflowed the available TOC space, you can shrink the TOC usage with -mno-fp-in-toc and -mno-sum-in-toc 🫶 -mno-fp-in-toc stops GCC from putting floating-point constants in the TOC. -mno-sum-in-toc makes GCC generate code that calculates the sum of an address and a constant at run time, instead of storing that sum in the TOC. You can use one or both. Each one makes the code very slightly slower and larger, which is the price of saving TOC space.
If you still run out of TOC space even with both of those, use -mminimal-toc instead 💀 It makes GCC create only one TOC entry for every file. The code is slower and larger, but it uses extremely little TOC space. You might only want to use it on files with less frequently-executed code.
-maix64,-maix32— enables the 64-bit AIX ABI and calling convention, with 64-bit pointers, a 64-bitlongtype, and the infrastructure needed to support them ✨ Specifying-maix64implies-mpowerpc64, while-maix32disables the 64-bit ABI and implies-mno-powerpc64. GCC defaults to-maix32.-mxl-compat,-mno-xl-compat— okay so this one makes your code act more like IBM XL compiler output when you're on the AIX-compatible ABI 💅✨ It passes floating-point arguments to prototyped functions past the register save area (RSA) on the stack, in addition to the argument FPRs 🦋 It also stops assuming that the most significant double in a 128-bitlong doubleis properly rounded when you compare values and convert todouble🙈 And it uses XL symbol names forlong doublesupport routines 🫶
The AIX calling convention got extended, but that wasn't documented at first. It was for an obscure K&R C situation: calling a function that takes the address of its arguments with fewer arguments than it declares 💀 IBM XL compilers read floating-point arguments that don't fit in the RSA from the stack when a subroutine is compiled without optimization. Storing floating-point arguments on the stack all the time is inefficient and rarely needed, so this is not on by default. You only need it when calling subroutines that IBM XL compiled without optimization 🌸
-mpe— slay, support for the IBM RS/6000 SP Parallel Environment (PE) 🌈 It links an app that uses message passing with special startup code so it can actually run. Your system needs PE installed in the standard location (/usr/lpp/ppe.poe/), or you need to override the specs file with-specs=to point at the right directory 🗺️ Heads up: PE doesn't support threads, so-mpeand-pthreadare incompatible 🚫-malign-natural,-malign-power— on AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux,-malign-naturaloverrides the ABI-defined alignment of bigger types (like floating-point doubles) and puts them on their natural size-based boundary 📏-malign-powertells GCC to follow the ABI-specified alignment rules instead. GCC defaults to the standard alignment from the ABI 🍓
On 64-bit Darwin, natural alignment is the default, and -malign-power is not supported there 🙅♀️
-msoft-float,-mhard-float—-msoft-floatgenerates code that doesn't touch the floating-point register set, and-mhard-floatgenerates code that does use it 🔧 With-msoft-float, software floating-point emulation is provided, but you have to pass the option to GCC when linking too 💖-mmultiple,-mno-multiple—-mmultiplegenerates code that uses the load multiple word and store multiple word instructions, and-mno-multiplegenerates code that doesn't 🧩 These are generated by default on POWER systems, and not on PowerPC systems. Do not use-mmultipleon little-endian PowerPC systems, since those instructions don't work when the processor is in little-endian mode 😭 The exceptions are PPC740 and PPC750, which do permit these instructions in little-endian mode 🦋-mupdate,-mno-update—-mupdategenerates code that uses load or store instructions that update the base register to the address of the calculated memory location, and-mno-updategenerates code that doesn't 💅 These instructions are generated by default. If you use-mno-update, there's a small window between the time the stack pointer gets updated and the time the address of the previous frame is stored.
Careful bestie! With -mno-update, code that walks the stack frame across interrupts or signals may end up with corrupted data 💀
-mavoid-indexed-addresses,-mno-avoid-indexed-addresses—-mavoid-indexed-addressestries to avoid indexed load or store instructions, and-mno-avoid-indexed-addressesdoes not avoid them 🌊 Indexed instructions can take a performance hit on Power6 processors in certain situations, like stepping through big arrays that cross a 16M boundary. This option is enabled by default when targeting Power6 and disabled otherwise ✨-mfused-madd,-mno-fused-madd—-mfused-maddgenerates code that uses floating-point multiply and accumulate instructions, and-mno-fused-maddgenerates code that doesn't 🧚 These are generated by default if hardware floating point is used. The machine-dependent-mfused-maddis now mapped to the machine-independent-ffp-contract=fastoption, and-mno-fused-maddis mapped to-ffp-contract=off🔥-mmulhw,-mno-mulhw—-mmulhwgenerates code that uses the half-word multiply and multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors, and-mno-mulhwgenerates code that doesn't 🌸 These are generated by default when targeting those processors 💜-mdlmzb,-mno-dlmzb—-mdlmzbgenerates code that uses the string-searchdlmzbinstruction on the IBM 405, 440, 464 and 476 processors, and-mno-dlmzbgenerates code that doesn't 🔍 This instruction is generated by default when targeting those processors 🎀-mno-bit-align,-mbit-align— on System V.4 and embedded PowerPC systems,-mno-bit-aligndoes not force structures and unions containing bit-fields to be aligned to the base type of the bit-field, and-mbit-aligndoes 🧸
Here's the tea ☕ By default, a structure with nothing but 8 "unsigned" bit-fields of length 1 is aligned to a 4-byte boundary and has a size of 4 bytes. With -mno-bit-align, that same structure is aligned to a 1-byte boundary and is only 1 byte in size 🤯
-mno-strict-align,-mstrict-align— on System V.4 and embedded PowerPC systems,-mno-strict-aligndoes not assume that unaligned memory references are handled by the system, and-mstrict-aligndoes assume that 🫶-mrelocatable,-mno-relocatable—-mrelocatablegenerates code that allows a static executable to be relocated to a different address at run time, and-mno-relocatablegenerates code that doesn't 🦋 A simple embedded PowerPC system loader should relocate the entire contents of.got2and the 4-byte locations listed in the.fixupsection, which is a table of 32-bit addresses this option generates 🧚 For this to work, every object linked together must be compiled with-mrelocatableor-mrelocatable-lib. Also,-mrelocatablecode aligns the stack to an 8-byte boundary 📏-mrelocatable-lib,-mno-relocatable-lib— just like-mrelocatable,-mrelocatable-libgenerates a.fixupsection so static executables can be relocated at run time 🌈 The difference is that it does not use the smaller stack alignment of-mrelocatable. Objects compiled with-mrelocatable-libcan be linked with objects compiled with any combination of the-mrelocatableoptions 💖-mno-toc,-mtoc— on System V.4 and embedded PowerPC systems,-mno-tocdoes not assume that register 2 contains a pointer to a global area pointing to the addresses used in the program, and-mtocdoes assume it 🧭-mlittle,-mlittle-endian— on System V.4 and embedded PowerPC systems, this compiles code for the processor in little-endian mode 💜-mlittle-endianis the same as-mlittle🍓-mbig,-mbig-endian— on System V.4 and embedded PowerPC systems, this compiles code for the processor in big-endian mode 🌊-mbig-endianis the same as-mbig🎀-mdynamic-no-pic— on Darwin / macOS systems, this compiles code so that it is not relocatable, but its external references are relocatable 🍎 The resulting code is suitable for applications, but not for shared libraries 🙅♀️-msingle-pic-base— this treats the register used for PIC addressing as read-only, instead of loading it in the prologue for each function 🔒 The runtime system is responsible for initializing this register with an appropriate value before execution begins 🫶-mprioritize-restricted-insns=priority— this controls the priority assigned to dispatch-slot restricted instructions during the second scheduling pass 🗂️ The argument priority takes the value0,1, or2, which assigns no priority, highest priority, or second-highest priority (respectively) to dispatch-slot restricted instructions ✨-msched-costly-dep=dependence_type— this controls which dependences the target considers costly during instruction scheduling 💅 The argument dependence_type takes one of these values:no— no dependence is costly 🙅♀️all— all dependences are costly 🔥true_store_to_load— a true dependence from store to load is costly 🧠store_to_load— any dependence from store to load is costly 📦number— any dependence whose latency is greater than or equal to number is costly 📊
-minsert-sched-nops=scheme— this controls which NOP insertion scheme is used during the second scheduling pass 🌸 The argument scheme takes one of these values:no— don't insert NOPs 🙈pad— pad with NOPs any dispatch group that has vacant issue slots, according to the scheduler's grouping 🧸regroup_exact— insert NOPs to force costly dependent insns into separate groups. Insert exactly as many NOPs as needed to force an insn to a new group, according to the estimated processor grouping 🎯number— insert NOPs to force costly dependent insns into separate groups. Insert number NOPs to force an insn to a new group 🧚
-mcall-sysv— on System V.4 and embedded PowerPC systems, this compiles code using calling conventions that follow the March 1995 draft of the System V Application Binary Interface, PowerPC processor supplement 📜 This is the default unless you configured GCC usingpowerpc-*-eabiaix🌈-mcall-sysv-eabi,-mcall-eabi— these specify both-mcall-sysvand-meabioptions 💜-mcall-sysv-noeabi— this specifies both-mcall-sysvand-mno-eabioptions 🦋-mcall-aixdesc— on System V.4 and embedded PowerPC systems, this compiles code for the AIX operating system 🍎-mcall-linux— on System V.4 and embedded PowerPC systems, this compiles code for the Linux-based GNU system 🐧-mcall-freebsd— on System V.4 and embedded PowerPC systems, this compiles code for the FreeBSD operating system 😈-mcall-netbsd— on System V.4 and embedded PowerPC systems, this compiles code for the NetBSD operating system 🐡-mcall-openbsd— on System V.4 and embedded PowerPC systems, this compiles code for the OpenBSD operating system 🐡-mtraceback=traceback_type— this selects the type of traceback table 🧾 Valid values for traceback_type arefull,part, andno✨-maix-struct-return— returns all structures in memory, as specified by the AIX ABI 📦-msvr4-struct-return— returns structures smaller than 8 bytes in registers, as specified by the SVR4 ABI 🧺-mabi=abi-type— this extends the current ABI with a particular extension, or removes that extension 🌈 Valid values are:altivec,no-altivec,ibmlongdouble,ieeelongdouble,elfv1,elfv2, and for AIX:vec-extabi,vec-default👑-mabi=ibmlongdouble— okay so this one switches the ABI over to IBM extended-precisionlong double💅. Heads up though, it's not likely to work if your system already defaults to IEEE extended-precisionlong double😭. If you changelong doubleaway from IEEE extended-precision, the compiler will warn you unless you add-Wno-psabi. You also need-mlong-double-128enabled for this to work 🫶.-mabi=ieeelongdouble— the mirror image of the one above ✨. It switches the ABI to IEEE extended-precisionlong double, but it's not likely to work if your system defaults to IBM extended-precisionlong double💀. Switching away from IBM extended-precision gets you a warning unless you use-Wno-psabi, and-mlong-double-128has to be enabled too 🌸.-mabi=elfv1— this sets the ABI to ELFv1, which is the default for big-endian PowerPC 64-bit Linux 🍓. Overriding the default needs special system support, and it's likely to fail in spectacular ways 💀🔥.-mabi=elfv2— this one sets the ABI to ELFv2, the default for little-endian PowerPC 64-bit Linux 🧚. Overriding the default also needs special system support, and it's likely to fail in spectacular ways 🙈.-mgnu-attribute,-mno-gnu-attribute— the first one emits.gnu_attributeassembly directives that set tag/value pairs in a.gnu.attributessection. Those pairs spell out ABI variations in function parameters or return values 🦋.-mprototype,-mno-prototype— on System V.4 and embedded PowerPC systems,-mprototypetells the compiler to assume every call to a variable argument function is properly prototyped 👑. Without it, the compiler has to slip in an instruction before every non-prototyped call to set or clear bit 6 of the condition code register ("CR"), so it can tell whether floating-point values get passed in the floating-point registers 😭. With-mprototype, only calls to prototyped variable argument functions set or clear that bit ✨.-msim— on embedded PowerPC systems, this assumes the startup module is calledsim-crt0.oand the standard C libraries arelibsim.aandlibc.a🎀. It's the default forpowerpc-*-eabisimconfigurations 🌈.-mmvme— on embedded PowerPC systems, this assumes the startup module is calledcrt0.oand the standard C libraries arelibmvme.aandlibc.a💜.-mads— on embedded PowerPC systems, this assumes the startup module is calledcrt0.oand the standard C libraries arelibads.aandlibc.a🦋.-myellowknife— on embedded PowerPC systems, this assumes the startup module is calledcrt0.oand the standard C libraries arelibyk.aandlibc.a🌸.-mvxworks— on System V.4 and embedded PowerPC systems, this tells the compiler you're building for a VxWorks system 🧚.-memb— on embedded PowerPC systems, this sets the "PPC_EMB" bit in the ELF flags header, which signals that eabi extended relocations are being used 🫶.-meabi,-mno-eabi— on System V.4 and embedded PowerPC systems,-meabimakes the compiler adhere to the Embedded Applications Binary Interface (EABI), a set of modifications to the System V.4 specs 💅. With it, the stack is aligned to an 8-byte boundary, a function__eabigets called frommainto set up the EABI environment, and the-msdataoption can use bothr2andr13to point to two separate small data areas ✨.-mno-eabidoes the opposite: the stack is aligned to a 16-byte boundary, no EABI initialization function gets called frommain, and-msdataonly usesr13to point to a single small data area 🙈.-meabiis on by default if you configured GCC with one of thepowerpc*-*-eabi*options 👑.-msdata=eabi— on System V.4 and embedded PowerPC systems, small initializedconstglobal and static data goes in the.sdata2section, whichr2points to 🌈. Small initialized non-constglobal and static data goes in.sdata, whichr13points to 💖. Small uninitialized global and static data goes in.sbss, which sits right next to.sdata⭐. Heads up:-msdata=eabiis incompatible with-mrelocatable💀. It also sets-memb🔥.-msdata=sysv— on System V.4 and embedded PowerPC systems, small global and static data goes in.sdata, whichr13points to 🍓. Small uninitialized global and static data goes in.sbss, next to.sdata🧚. This one's incompatible with-mrelocatabletoo 🙈.-msdata=default,-msdata— on System V.4 and embedded PowerPC systems, if-meabiis used, this compiles the code the same way as-msdata=eabi💅. Otherwise, it compiles it the same way as-msdata=sysv✨.-msdata=data— on System V.4 and embedded PowerPC systems, small global data goes in.sdata🦋. Small uninitialized global data goes in.sbss🌸. The catch is thatr13doesn't get used to address small data here 🫶. This is the default behaviour unless other-msdataoptions are used 👑.-msdata=none,-mno-sdata— on embedded PowerPC systems, all initialized global and static data goes in.data, and all uninitialized data goes in.bss💜.-mreadonly-in-sdata— puts read-only objects in.sdataas well 🎀. This is the default ✨.-mblock-move-inline-limit=num— inlines all block moves (like calls tomemcpyor structure copies) that are less than or equal to num bytes 🔥. The minimum value for num is 32 bytes on 32-bit targets and 64 bytes on 64-bit targets 💅. The default is target-specific 🌈.-mblock-compare-inline-limit=num— generates non-looping inline code for all block compares (like calls tomemcmpor structure compares) that are less than or equal to num bytes 🫶. If num is0, all inline expansion (both non-loop and loop) of block compare gets disabled 💀. The default is target-specific ✨.-mblock-compare-inline-loop-limit=num— generates an inline expansion using loop code for all block compares that are less than or equal to num bytes, but greater than the limit for non-loop inline block compare expansion 🧚. If the block length isn't constant, at most num bytes get compared beforememcmpis called to handle the rest of the block 🙈. The default is target-specific 🦋.-mstring-compare-inline-limit=num— compares at most num string bytes with inline code 🍓. If the difference or end of string isn't found by the end of the inline compare, a call tostrcmporstrncmptakes care of the rest 🌸. The default is 64 bytes 💖.-G num— on embedded PowerPC systems, puts global and static items that are less than or equal to num bytes into the small data or BSS sections, instead of the normal data or BSS section 🌈. By default, num is 8 ⭐. The-G numswitch also gets passed to the linker 🔥. All modules should be compiled with the same-G numvalue, bestie, or things get messy 💅.-mregnames,-mno-regnames— on System V.4 and embedded PowerPC systems,-mregnamesmakes the compiler emit register names in the assembly output using symbolic forms, and-mno-regnamesmakes it not do that 🦋.-mlongcall,-mno-longcall— by default, the compiler assumes every call is far away, so it uses a longer and more expensive calling sequence 💜. This is required for calls farther than 32 megabytes (33,554,432 bytes) from the current location 🫶. A short call only gets generated if the compiler knows the call can't be that far away ✨. This setting can be overridden by theshortcallfunction attribute, or by#pragma longcall(0)👑.
Some linkers can spot out-of-range calls and generate glue code on the fly 🔥. On those systems, long calls are unnecessary and generate slower code 💀. As of this writing, the AIX linker can do this, and so can the GNU linker for PowerPC/64 🌸. Adding this feature to the GNU linker for 32-bit PowerPC systems is planned too 🧚.
On PowerPC64 ELFv2 and 32-bit PowerPC systems with newer GNU linkers, GCC can generate long calls using an inline PLT call sequence (see -mpltseq) ✨. PowerPC with -mbss-plt and PowerPC64 ELFv1 (big-endian) do not support inline PLT calls 😭.
On Darwin/PPC systems, #pragma longcall generates jbsr callee, L42, plus a branch island (glue code) 🍓. The two target addresses represent the callee and the branch island 🦋. The Darwin/PPC linker prefers the first address and generates bl callee if the PPC bl instruction reaches the callee directly 💖. Otherwise, the linker generates bl L42 to call the branch island 🙈. The branch island gets appended to the body of the calling function, and it computes the full 32-bit address of the callee and jumps to it 💅.
On Mach-O (Darwin) systems, this option tells the compiler to emit the glue for every direct call, and then the Darwin linker decides whether to use it or discard it 🌈.
In the future, GCC may ignore all longcall specifications when the linker is known to generate glue 🔮.
-mpltseq,-mno-pltseq—-mpltseqimplements-fno-pltand long calls using an inline PLT call sequence, which supports lazy linking and long calls to functions indlopen'd shared libraries 👑.-mno-pltseqmeans it doesn't implement them that way 🫶. Inline PLT calls are only supported on PowerPC64 ELFv2 and on 32-bit PowerPC systems with newer GNU linkers 🔥. They're enabled by default if support gets detected when configuring GCC, and, for 32-bit PowerPC, if GCC is configured with--enable-secureplt⭐. Heads up:-mpltseqcode and-mbss-plt32-bit PowerPC relocatable objects may not be linked together 💀.-mtls-markers,-mno-tls-markers—-mtls-markersmarks calls to__tls_get_addrwith a relocation that specifies the function argument 🧚.-mno-tls-markersdoesn't do the marking 🙈. The relocation lets the linker reliably associate the function call with the argument setup instructions for TLS optimization 🦋, which in turn lets GCC schedule the sequence better 💜✨.-mrecip,-mno-recip— okay bestie, this one turns on the reciprocal estimate and reciprocal square root estimate instructions, then adds extra Newton-Raphson steps to win back precision 🧮✨ So instead of doing a full divide (or square root and then divide) for floating-point args, GCC can take the faster route 🏎️. You should pair-mrecipwith-ffast-math💅 (or at least-funsafe-math-optimizations,-ffinite-math-only,-freciprocal-mathand-fno-trapping-math). The catch: the throughput is usually higher than the non-reciprocal instruction, but the precision can slip by up to 2 ulp for reciprocal square roots 😭 (like, the inverse of1.0comes out as0.99999994). Not a vibe for every app, so check your math 🤓-mrecip=opt— this lets you pick exactly which estimate instructions are allowed 🎀optis a comma-separated list, and you can put a!in front of any item to flip it 🙃all— enable all the estimate instructions, every single one 🔥default— enable the default instructions, same as-mrecip🌸none— disable all estimate instructions, same as-mno-recip🙅♀️div— enable the reciprocal approximation instructions for both single and double precision 💖divf— enable the single-precision reciprocal approximation instructions 🦋divd— enable the double-precision reciprocal approximation instructions 🧚rsqrt— enable the reciprocal square root approximation instructions for both single and double precision ✨rsqrtf— enable the single-precision reciprocal square root approximation instructions 💜rsqrtd— enable the double-precision reciprocal square root approximation instructions 🌈
So, for example, -mrecip=all,!rsqrtd turns on every reciprocal estimate instruction except the FRSQRTE, XSRSQRTEDP, and XVRSQRTEDP ones, which handle the double-precision reciprocal square root math 👑 that's a whole main character move right there 💅
-mrecip-precision,-mno-recip-precision— this tells GCC whether to assume (or not assume) that the reciprocal estimate instructions give you higher precision than the PowerPC ABI requires 🌷 Picking-mcpu=power6,-mcpu=power7or-mcpu=power8turns-mrecip-precisionon automatically 🫶 Also, the double-precision square root estimate instructions aren't generated by default on low-precision machines, because they don't converge after three steps 🙈-mveclibabi=type— this picks the ABI type for vectorizing intrinsics using an external library 📚 The only type supported right now ismass, which means using IBM's Mathematical Acceleration Subsystem (MASS) libraries to vectorize intrinsics 🔥 When you're generating code for power7, GCC emits calls to these functions (that's the whole squad 💅):
acosd2, acosf4, acoshd2, acoshf4, asind2, asinf4, asinhd2, asinhf4, atan2d2, atan2f4, atand2, atanf4, atanhd2, atanhf4, cbrtd2, cbrtf4, cosd2, cosf4, coshd2, coshf4, erfcd2, erfcf4, erfd2, erff4, exp2d2, exp2f4, expd2, expf4, expm1d2, expm1f4, hypotd2, hypotf4, lgammad2, lgammaf4, log10d2, log10f4, log1pd2, log1pf4, log2d2, log2f4, logd2, logf4, powd2, powf4, sind2, sinf4, sinhd2, sinhf4, sqrtd2, sqrtf4, tand2, tanf4, tanhd2, tanhf4Both -ftree-vectorize and -funsafe-math-optimizations also have to be on 🎀 And the MASS libraries must be specified at link time, no skipping that step 🙅♀️
-mfriz,-mno-friz— this tells GCC whether to generate thefrizinstruction 🦋 It only kicks in when-funsafe-math-optimizationsis on, and it speeds up rounding floating-point values to 64-bit integers and back again ✨ Heads up though:frizdoesn't give back the same value if the float is too big to fit in an integer 😭 so be careful, bestie-mpointers-to-nested-functions,-mno-pointers-to-nested-functions— this makes GCC generate (or skip) code that loads the static chain register (r11) when calling through a pointer on AIX and 64-bit Linux systems 🌸 That's when a function pointer points to a 3-word descriptor holding the function address, the TOC value to load intor2, and the static chain value to load intor11🧚-mpointers-to-nested-functionsis on by default 💖 But if you use-mno-pointers-to-nested-functions, you can't call through pointers to nested functions, or through pointers to functions compiled in other languages that use the static chain 🙃-msave-toc-indirect,-mno-save-toc-indirect— this decides whether GCC saves the TOC value in the reserved stack location in the function prologue, when the function calls through a pointer on AIX and 64-bit Linux 🌈 If it isn't saved in the prologue, it gets saved just before the call through the pointer 🫶-mno-save-toc-indirectis the default, so that's your baseline 💅-mcompat-align-parm,-mno-compat-align-parm— this makes GCC generate (or not generate) code that passes structure parameters with a max alignment of 64 bits, so it matches older versions of GCC 🕰️
Older GCC versions (before 4.9.0) messed up by not aligning a structure parameter on a 128-bit boundary when that structure had a member needing 128-bit alignment 💀 Newer versions fixed it, but if you need to play nice with functions compiled by the older ones, this option is your friend 🫶
-mno-compat-align-parm is the default 🌸
-mstack-protector-guard=guard,-mstack-protector-guard-reg=reg,-mstack-protector-guard-offset=offset,-mstack-protector-guard-symbol=symbol— these generate stack protection code using a canary at the guard 🛡️ The supported locations areglobal(for a global canary) ortls(for a per-thread canary in the TLS block, which is the default with GNU libc 2.4 or later) 🧵
With tls, -mstack-protector-guard-reg=reg and -mstack-protector-guard-offset=offset pick the base register used to read the canary, plus the offset from that base register 🎯 If you don't set them, the defaults come from the relevant ABI 🙂 And -mstack-protector-guard-symbol=symbol overrides the offset with a symbol reference to a canary in the TLS block 🔥
-mpcrel,-mno-pcrel— this makes GCC generate (or not generate) pc-relative addressing 📍-mpcrelneeds the medium code model (-mcmodel=medium) and prefixed addressing (-mprefixed) to be enabled first 🧚-mprefixed,-mno-prefixed— this makes GCC generate (or not generate) addressing modes that use prefixed load and store instructions ✨-mprefixedrequires-mcpu=power10(or later) to be enabled 👑-mmma,-mno-mma— this makes GCC generate (or not generate) the MMA instructions 💜 The-mmaoption requires-mcpu=power10(or later) to be enabled 🌈-mrop-protect,-mno-rop-protect— this makes GCC generate (or not generate) ROP protection instructions when the target processor supports them 🛡️ Heads up: right now this option disables the shrink-wrap optimization (-fshrink-wrap) 😭-mprivileged,-mno-privileged— this makes GCC generate (or not generate) code that runs in privileged state 👑 Use with care, bestie 💀-mblock-ops-unaligned-vsx,-mno-block-ops-unaligned-vsx— this makes GCC generate (or not generate) unaligned VSX loads and stores for inline expansion ofmemcpyandmemmove🚀--param rs6000-vect-unroll-limit=— the vectorizer checks with target info to decide whether unrolling the main vectorized loop would help, and by how much 🔁 This parameter sets the upper bound on how much it'll unroll the main loop 🌸 The default value isfour🍓
🌸 RX Options 🌸
These command-line options are defined for RX targets 🦋
-m64bit-doubles,-m32bit-doubles— this makes thedoubledata type 64 bits (-m64bit-doubles) or 32 bits (-m32bit-doubles) 💖 The default is-m32bit-doubles, and the reason is that RX floating-point hardware only works on 32-bit values 🤓-fpu,-nofpu—-fpuenables the use of RX floating-point hardware, and-nofpudisables it 🔌 The default is enabled for the RX600 series and disabled for the RX200 series 🧚
Floating-point instructions only get generated for 32-bit floating-point values, though, so the FPU hardware isn't used for doubles if -m64bit-doubles is in play 🙈
If-fpuis enabled,-funsafe-math-optimizationsgets turned on automatically too 💀 That's because the RX FPU instructions are themselves unsafe.
-mcpu=name— this picks which type of RX CPU you're targeting 🎯 Three types are supported right now: the generic RX600 and RX200 series hardware, and the specific RX610 CPU 💜 The default is RX600 🌈
The only difference between RX600 and RX610 is that the RX610 doesn't support the MVTIPL instruction 🙃
The RX200 series doesn't have a hardware floating-point unit, so -nofpu is enabled by default when you select it 🫶
-mbig-endian-data,-mlittle-endian-data— this stores data (but not code) in big-endian format ✨ The default is-mlittle-endian-data, which means data gets stored in little-endian format 🌷-msmall-data-limit=N— this sets the max size in bytes of global and static variables that can be placed into the small data area 📦 Using the small data area can lead to smaller and faster code 🏎️ But the area is limited, so it's on the programmer to make sure it doesn't overflow 😬 Also, when the small data area is used, one of the RX's registers (usuallyr13) gets reserved to point to that area, so the compiler can't use it anymore 💀 That can mean slower and/or larger code if variables get pushed onto the stack instead of being held in that register 🙈
Note: common variables (ones that haven't been initialized) and constants aren't placed into the small data area, because they get assigned to other sections in the output executable 🧐
okay so the default is 0, which means this feature is switched off 🙅♀️ it's NOT turned on at higher optimization levels (-O2 etc) bc reserving a register can be detrimental 😭 so it's up to you to experiment and see if it actually helps your program 🔬 for how the register that holds the small data area pointer gets picked, check out the -mpid entry 👀
-msim,-mno-sim— use the simulator runtime 🖥️ the default is the libgloss board-specific runtime-mas100-syntax,-mno-as100-syntax— when making assembler output, this makes it use a syntax that's compatible with Renesas's AS100 assembler 🧵 GAS can handle it too, but it has some restrictions, so it's not generated by default-mmax-constant-size=N— sets the max size, in bytes, of a constant that can be used as an operand in an RX instruction 💅 RX lets you use constants up to 4 bytes, but a bigger value = a bigger instruction, so sometimes it's smart to limit this 🧠 constants that are too big get tossed into a constant pool and referenced via register indirection 📦
The value N can be between 0 and 4. A value of 0 (the default) or 4 means constants of any size are allowed ✨
-mrelax— turns on linker relaxation 🪄 this is where the linker tries to shrink your program by finding shorter versions of instructions. It's disabled by default-mint-register=N— sets how many registers get reserved for fast interrupt handler functions 🔒Ncan be between0and41reserves"r13"for the exclusive use of fast interrupt handlers2reserves"r13"and"r12"3reserves"r13","r12"and"r11"4reserves"r13"through"r10"
0 (the default) doesn't reserve any registers 🫶
-msave-acc-in-interrupts— tells interrupt handler functions to preserve the accumulator register 💜 this is only needed if normal code might use the accumulator, like if it does 64-bit multiplications 🔢 the default is to ignore the accumulator, bc that makes the interrupt handlers faster 🏎️-mpid,-mno-pid— turns on generation of position independent data 🦋 when it's on, any access to constant data is done via an offset from a base address held in a register. This lets the location of constant data get figured out at run time without the executable needing to be relocated, which is a huge win for embedded apps with tight memory constraints 🌸 data that can be modified isn't affected by this option
heads up: using this feature reserves a register, usually "r13", for the constant data base address 💀 this can make code slower and/or larger, especially in complicated functions
Which register actually gets picked for the constant data base address depends on whether -msmall-data-limit and/or -mint-register are turned on 🧩 starting at "r13" and going downwards, registers are allocated first to satisfy -mint-register, then -mpid, and finally -msmall-data-limit. So it's totally possible for the small data area register to be "r8" if both -mint-register=4 and -mpid are on the command line 🤯
By default this feature is NOT enabled. You can restore the default with the -mno-pid command-line option 🔄
-mno-warn-multiple-fast-interrupts,-mwarn-multiple-fast-interrupts— stops GCC from giving a warning if it finds more than one fast interrupt handler while compiling a file 🙈 the default is to warn for each extra fast interrupt handler it finds, bc the RX only supports one such interrupt-mallow-string-insns,-mno-allow-string-insns— enables or disables the string manipulation instructions"SMOVF","SCMPU","SMOVB","SMOVU","SUNTIL""SWHILE"and also the"RMPA"instruction 🧵 these might prefetch data, which is NOT safe if you're accessing an I/O register 🚫 (see section 12.2.7 of the RX62N Group User's Manual for more info 📖)
The default is to allow these instructions. BUT GCC can't reliably detect every situation where a string instruction might touch an I/O register, so they can't be disabled automatically 😬 it's on you to use -mno-allow-string-insns if your program accesses I/O space 🫠
When the instructions are enabled, GCC defines the C preprocessor symbol "__RX_ALLOW_STRING_INSNS__". Otherwise it defines "__RX_DISALLOW_STRING_INSNS__" 🏷️
-mjsr,-mno-jsr— uses only (or not only)JSRinstructions to access functions 🎯 you can use this when code size goes beyond the range ofBSRinstructions. Note that-mno-jsrdoesn't mean "don't useJSR" 🙅♀️ it just means any type of branch may be used
Note: the generic GCC command-line option -ffixed-reg has special significance to the RX port when it's used with the "interrupt" function attribute 👑 that attribute marks a function meant to process fast interrupts. GCC makes sure it only uses the registers "r10", "r11", "r12" and/or "r13", and only if the normal use of the corresponding registers has been restricted via the -ffixed-reg or -mint-register command-line options 🔐
✨ S/390 and zSeries Options ✨
These are the -m options defined for the S/390 and zSeries architecture 🧚
-mhard-float,-msoft-float— use (or don't use) the hardware floating-point instructions and registers for floating-point operations ⚡ with-msoft-float, functions inlibgcc.ado the floating-point work. With-mhard-float, the compiler generates IEEE floating-point instructions. This is the default 💖-mhard-dfp,-mno-hard-dfp— use (or don't use) the hardware decimal-floating-point instructions for decimal-floating-point operations 🔢 with-mno-hard-dfp, functions inlibgcc.aare used instead. With-mhard-dfp, the compiler generates decimal-floating-point hardware instructions. This is the default for-march=z9-ecor higher 🌈-mlong-double-64,-mlong-double-128— these control the size of the"long double"type 📏 a size of 64 bits makes"long double"equivalent to"double". This is the default 🍓-mbackchain,-mno-backchain— stores (or doesn't store) the address of the caller's frame as a backchain pointer into the callee's stack frame 🔗 a backchain may be needed to allow debugging with tools that don't understand DWARF call frame information 🔍 with-mno-packed-stackin effect, the backchain pointer is stored at the bottom of the stack frame. With-mpacked-stackin effect, the backchain is placed into the topmost word of the 96/160 byte register save area 🧱
In general, code compiled with -mbackchain is call-compatible with code compiled with -mno-backchain. However, using the backchain for debugging usually requires the whole binary to be built with -mbackchain 🛠️ the combination of -mbackchain, -mpacked-stack and -mhard-float is NOT supported ❌ to build a linux kernel, use -msoft-float 🐧
The default is to not maintain the backchain 🙅♀️
-mpacked-stack,-mno-packed-stack— uses (or doesn't use) the packed stack layout 📚 with-mno-packed-stack, the compiler uses all the fields of the 96/160 byte register save area only for their default purpose, so unused fields still take up stack space. With-mpacked-stack, register save slots are densely packed at the top of the register save area, and unused space gets reused for other purposes, which is way more efficient with the stack space 🧠 however, when-mbackchainis also in effect, the topmost word of the save area is always used to store the backchain, and the return address register is always saved two words below the backchain 📍
As long as the stack frame backchain isn't used, code generated with -mpacked-stack is call-compatible with code generated with -mno-packed-stack. Heads up: some non-FSF releases of GCC 2.95 for S/390 or zSeries generated code that uses the stack frame backchain at run time, not just for debugging 😳 that code is NOT call-compatible with code compiled with -mpacked-stack. Also, the combination of -mbackchain, -mpacked-stack and -mhard-float is NOT supported. For a linux kernel, use -msoft-float 🐧
The default is to not use the packed stack layout 🙅♀️
-msmall-exec,-mno-small-exec— generates (or doesn't generate) code using the"bras"instruction to do subroutine calls 📞 this only works reliably if the total executable size does not exceed 64k 📉 the default is to use the"basr"instruction instead, which doesn't have that limitation 💫-m64,-m31— when-m31is specified, code gets generated compliant to the GNU/Linux for S/390 ABI 🧭 when-m64is specified, code is generated compliant to the GNU/Linux for zSeries ABI. This lets GCC in particular generate 64-bit instructions 🚀 for the s390 targets, the default is-m31, while the s390x targets default to-m64🎀-mzarch,-mesa— with-mzarch, code is generated using the instructions available on z/Architecture 🏛️ with-mesa, code is generated using the instructions available on ESA/390. Note that-mesais NOT possible with-m64❌ when generating code compliant to the GNU/Linux for S/390 ABI, the default is-mesa. When generating code compliant to the GNU/Linux for zSeries ABI, the default is-mzarch🍰-mhtm,-mno-htm—-mhtmenables a set of builtins that make use of instructions available with the transactional execution facility, introduced with the IBM zEnterprise EC12 machine generation 🌸 see S/390 System z Built-in Functions for the details 📚-mhtmis enabled by default when using-march=zEC12💜
Okay so bestie, -mvx turns on the vector extension facility that came with the IBM z13 machine generation 💖. It's giving ABI drama though, because it changes how some vector type values get aligned and how they're passed around in calls 💅. If vector types show up somewhere the ABI cares about, GCC adds a GAS .gnu_attribute command so the binary gets marked with the ABI it used 🫶. And -mvx is switched on by default whenever you use -march=z13 ✨.
-mvx,-mno-vx— generate code with the vector extension facility (the one from IBM z13) 🦋. This changes the ABI for some vector type values, so it's a whole vibe with alignment and calling conventions. Adds a GAS.gnu_attributemarker for the ABI in ABI-relevant contexts.-mvxis on by default with-march=z13.-mzvector,-mno-zvector— enables vector language extensions and builtins using those same z13 vector instructions 💜. It makesvectorwork as a keyword for declaring vector type variables and arguments 🎀. Heads up:vectoronly works when GNU extensions are on, and it won't expand if you ask for strict standard compliance like-std=c99🙈. On top of the GCC low-level builtins,-mzvectoralso adds a set of builtins made for compatibility with AltiVec-style implementations like Power and Cell 🧚. To actually use those, you need to include the header filevecintrin.h📚.-mzvectoris disabled by default.-mmvcle,-mno-mvcle— generate code using the"mvcle"instruction for block moves 🚚. With-mno-mvcle, GCC uses an"mvc"loop instead 🔁. Using"mvcle"is the default unless you're optimizing for size.-mdebug,-mno-debug— print extra debug info while compiling 🐛. The default is to not print it 🙅.-march=cpu-type— generate code that runs oncpu-type, which is the name of a system representing a certain processor type 🖥️. The valid values arez900/arch5,z990/arch6,z9-109,z9-ec/arch7,z10/arch8,z196/arch9,zEC12,z13/arch11,z14/arch12,z15/arch13,z16/arch14, andnative. The default is-march=z900. Pickingnativeselects the best architecture option for your host processor 🧠.-march=nativehas no effect if GCC doesn't recognize the processor 😬.-mtune=cpu-type— tune everything applicable in the generated code forcpu-type, except for the ABI and the set of available instructions 🎯. It takes the same list of values as-march. The default is whatever value-marchis using.-mtpf-trace,-mno-tpf-trace— adds (or doesn't add) TPF OS specific branches to trace routines in the operating system 🛤️. This is off by default, even when you're compiling for TPF OS.-mtpf-trace-skip,-mno-tpf-trace-skip— changes (or doesn't change) the default branch targets enabled by-mtpf-traceso they point to specialized trace routines ⏭️. That gives you the ability to selectively skip function trace entries for TPF OS. This is off by default, even when you're compiling for TPF OS and specifying-mtpf-trace.-mfused-madd,-mno-fused-madd— uses (or doesn't use) the floating-point multiply and accumulate instructions 🧮. These are generated by default if hardware floating point is in use.-mwarn-framesize=framesize— emits a warning if the current function exceeds the given frame size ⚠️. It's a compile-time check, so it doesn't have to be a real problem when the program runs 🫠. It's meant to spot functions that are most likely to cause a stack overflow, which makes it super useful in environments with a limited stack size, like the Linux kernel 🐧.-mwarn-dynamicstack— emits a warning if the function callsallocaor uses dynamically-sized arrays 🚨. That's generally a bad idea when the stack size is limited.-mstack-guard=stack-guard,-mstack-size=stack-size— debugging stack overflow problems 🐞. When these are provided, the S/390 back end adds extra instructions to the function prologue that trigger a trap if the stack goesstack-guardbytes abovestack-size. (Remember, the stack on S/390 grows downward 📉.) If you leave outstack-guard, GCC picks the smallest power of 2 larger than the frame size of the compiled function 🔢. The extra code causes only a little overhead, so it's fine for production-like systems too 🚀. The values have to be exact powers of 2, andstack-sizehas to be greater thanstack-guardwithout going over 64k 📏. To be efficient, the extra code assumes the stack starts at an address aligned to the value given bystack-size🧩. Thestack-guardoption can only be used together withstack-size.-mhotpatch=pre-halfwords,post-halfwords— if the hotpatch option is enabled, a "hot-patching" function prologue gets generated for all functions in the compilation unit 🔥. The function label is prepended with the given number of two-byte NOP instructions (pre-halfwords, maximum 1000000) 🫧. After the label, 2 *post-halfwordsbytes are appended, using the largest NOP-like instructions the architecture allows (maximum 1000000) 🧸. If both arguments are zero, hotpatching is disabled 🚫. You can override this for individual functions with the"hotpatch"attribute 👑.
🌸 SH Options 🌸
These -m options are defined for the SH implementations 💜:
-m1— generate code for the SH1.-m2— generate code for the SH2.-m2e— generate code for the SH2e.-m2a-nofpu— generate code for the SH2a without FPU, or for an SH2a-FPU in a way that the floating-point unit isn't used.-m2a-single-only— generate code for the SH2a-FPU so that no double-precision floating-point operations are used.-m2a-single— generate code for the SH2a-FPU, assuming the floating-point unit is in single-precision mode by default.-m2a— generate code for the SH2a-FPU, assuming the floating-point unit is in double-precision mode by default.-m3— generate code for the SH3.-m3e— generate code for the SH3e.-m4-nofpu— generate code for the SH4 without a floating-point unit.-m4-single-only— generate code for the SH4 with a floating-point unit that only supports single-precision arithmetic.-m4-single— generate code for the SH4, assuming the floating-point unit is in single-precision mode by default.-m4— generate code for the SH4.-m4-100— generate code for SH4-100.-m4-100-nofpu— generate code for SH4-100 in a way that the floating-point unit isn't used.-m4-100-single— generate code for SH4-100, assuming the floating-point unit is in single-precision mode by default.-m4-100-single-only— generate code for SH4-100 so that no double-precision floating-point operations are used.-m4-200— generate code for SH4-200.-m4-200-nofpu— generate code for SH4-200 without the floating-point unit being used.-m4-200-single— generate code for SH4-200, assuming the floating-point unit is in single-precision mode by default.-m4-200-single-only— generate code for SH4-200 so that no double-precision floating-point operations are used.-m4-300— generate code for SH4-300.-m4-300-nofpu— generate code for SH4-300 without the floating-point unit being used.-m4-300-single— generate code for SH4-300 so that no double-precision floating-point operations are used.-m4-300-single-only— generate code for SH4-300 so that no double-precision floating-point operations are used.-m4-340— generate code for SH4-340 (no MMU, no FPU) 🙈.-m4-500— generate code for SH4-500 (no FPU). It passes-isa=sh4-nofputo the assembler 🧩.-m4a-nofpu— generate code for the SH4al-dsp, or for an SH4a in a way that the floating-point unit isn't used.-m4a-single-only— generate code for the SH4a so that no double-precision floating-point operations are used.-m4a-single— generate code for the SH4a, assuming the floating-point unit is in single-precision mode by default.-m4a— generate code for the SH4a.-m4al— same as-m4a-nofpu, except it implicitly passes-dspto the assembler. GCC doesn't generate any DSP instructions at the moment 🫠.-mb— compile code for the processor in big-endian mode 🌊.-ml— compile code for the processor in little-endian mode 🌊.-mdalign— align doubles at 64-bit boundaries. Heads up: this changes the calling conventions, so some functions from the standard C library won't work unless you recompile them first with-mdalign🚨.-mrelax— shorten some address references at link time, when possible. It uses the linker option-relax🔗.-mbigtable— use 32-bit offsets in"switch"tables. The default is to use 16-bit offsets 📏.-mbitops— enables the use of bit manipulation instructions on SH2A 🧠.-mfmovd— enables the use of the instruction"fmovd". Check-mdalignfor alignment constraints 📐.-mrenesas— comply with the calling conventions defined by Renesas 🏷️.-mno-renesas— comply with the calling conventions defined for GCC before the Renesas conventions were available. This is the default for all targets of the SH toolchain 🕰️.-mnomacsave— marks the"MAC"register as call-clobbered, even if-mrenesasis given 🧷.-mieee,-mno-ieee— control the IEEE compliance of floating-point comparisons, which affects how cases with unordered comparison results are handled 🧮. By default,-mieeeis implicitly enabled. If-ffinite-math-onlyis enabled,-mno-ieeeis implicitly set, which gives you faster floating-point greater-equal and less-equal comparisons 🏎️. The implicit settings can be overridden by specifying either-mieeeor-mno-ieeeexplicitly 💅.-minline-ic_invalidate— okay bestie, this one inlines code that invalidates instruction cache entries right after it sets up nested function trampolines 🧚✨ It does nothing if-musermodeis on and your code gen option (like-m4) doesn't allow theicbiinstruction 🙈 If your code gen option doesn't allowicbiand-musermodeis not on, the inlined code pokes the instruction cache address array directly with an associative write.
💀 That write needs privileged mode at run time, AND it fails if the cache line got mapped via the TLB and then became unmapped. Be careful out there, babe!
-misize— dump instruction size and location in the assembly code 📏🎀-mpadstruct— this one is deprecated, so let's not be doing it 🙅♀️ It pads structures to a multiple of 4 bytes, which is incompatible with the SH ABI.-matomic-model=model— this is where you set the model for atomic operations, plus any extra parameters, as a comma separated list 💅 For the full tea on atomic built-in functions, check __atomic Builtins. Here are the models and parameters that are supported:none— turns off compiler generated atomic sequences and emits library calls for atomic operations instead 😌 This is the default if the target is notsh*-*-linux*.soft-gusa— generates GNU/Linux compatible gUSA software atomic sequences for the atomic built-in functions 🦋 These need extra help from the system's interrupt/exception handling code and are only suitable for SH3* and SH4* single-core systems. This is turned on by default when the target issh*-*-linux*and SH3* or SH4*. On SH4A, it also partially uses the hardware atomic instructionsmovli.landmovco.lfor more efficient code, unlessstrictis specified.soft-tcb— generates software atomic sequences that use a variable in the thread control block 🧠 It's a variation of the gUSA sequences that can also be used on SH1* and SH2* targets. It needs extra support from the interrupt/exception handling code and is only suitable for single-core systems. When you use this model, thegbr-offset=parameter has to be specified too.soft-imask— generates software atomic sequences that temporarily disable interrupts by settingSR.IMASK = 1111🔒 This model only works when the program runs in privileged mode and is only suitable for single-core systems. You don't need extra support from the interrupt/exception handling code for this one. It's enabled by default when the target issh*-*-linux*and SH1* or SH2*.hard-llcs— generates hardware atomic sequences using only themovli.landmovco.linstructions 🔥 This is only available on SH4A and is suitable for multi-core systems. The hardware instructions only support 32 bit atomic variables, so access to 8 or 16 bit variables gets emulated with 32 bit accesses. Code compiled with this option is also compatible with other software atomic model interrupt/exception handling systems if it runs on an SH4A system. No additional support from the interrupt/exception handling code is required for this model.gbr-offset=— this parameter sets the offset in bytes of the variable in the thread control block structure that the generated atomic sequences should use when thesoft-tcbmodel is selected 🎯 For other models this parameter gets ignored. The value must be an integer multiple of four and in the range 0-1020.strict— prevents mixing multiple atomic models, even if they're compatible, and makes the compiler generate atomic sequences of the specified model only 🚫
-mtas— generates thetas.bopcode for__atomic_test_and_set💫 Notice that depending on your hardware and software setup, this can hurt overall performance because of the operand cache line flushes that thetas.binstruction implies.
⚠️ On multi-core SH4A processors, the tas.b instruction has to be used with caution, since it can cause data corruption with certain cache configurations. Not the vibe!
-mprefergot— when generating position-independent code, emits function calls using the Global Offset Table instead of the Procedure Linkage Table 🌸-musermode,-mno-usermode—-musermodemeans don't let the compiler generate privileged mode code 🙅♀️-mno-usermodemeans go ahead and allow it 🙌 Specifying-musermodealso implies-mno-inline-ic_invalidateif the inlined code wouldn't work in user mode.-musermodeis the default when the target issh*-*-linux*. If the target is SH1* or SH2*,-musermodehas no effect, since there's no user mode there 🤷♀️-multcost=number— sets the cost to assume for a multiply insn 🧮-mdiv=strategy— sets the division strategy used for integer division operations 🍰strategycan be one of:call-div1— calls a library function that uses the single-step division instructiondiv1to do the operation 🫶 Division by zero calculates an unspecified result and does not trap. This is the default except for SH4, SH2A and SHcompact.call-fp— calls a library function that does the operation in double precision floating point 💥 Division by zero causes a floating-point exception. This is the default for SHcompact with FPU. Specifying this for targets that don't have a double precision FPU defaults tocall-div1.call-table— calls a library function that uses a lookup table for small divisors and thediv1instruction with case distinction for larger divisors 📚 Division by zero calculates an unspecified result and does not trap. This is the default for SH4. Specifying this for targets that don't have dynamic shift instructions defaults tocall-div1.
When a division strategy hasn't been specified, the default gets picked based on the current target 🎯 For SH2A, the default strategy is to use the divs and divu instructions instead of library function calls ✨
-maccumulate-outgoing-args— reserves space once for outgoing arguments in the function prologue instead of around each call 📦 This is generally beneficial for performance and size. It's also needed for unwinding, so the stack frame doesn't change around conditional code 🌈-mdivsi3_libfunc=name— sets the name of the library function used for 32-bit signed division toname🏷️ This only changes the name used in the call division strategies. The compiler still expects the same sets of input/output/clobbered registers as if this option weren't there.-mfixed-range=register-range— makes the compiler treat the given register range as fixed registers, which means the register allocator can't use them 🔐 This is useful when compiling kernel code. A register range is two registers separated by a dash, and you can specify multiple ranges separated by a comma.-mbranch-cost=num— assumesnumis the cost for a branch instruction 🌿 Higher numbers make the compiler try to generate more branch-free code if possible. If you don't specify it, the value is picked based on the processor type being compiled for.-mzdcbranch,-mno-zdcbranch—-mzdcbranchassumes that zero displacement conditional branch instructionsbtandbfare fast ⚡ With it, the compiler prefers zero displacement branch code sequences. This is enabled by default when generating code for SH4 and SH4A. You can explicitly turn it off with-mno-zdcbranch🙅♀️ (-mno-zdcbranchmeans do not assume they're fast.)-mcbranch-force-delay-slot— forces the use of delay slots for conditional branches, which stuffs the delay slot with anopif a suitable instruction can't be found 😴 This is disabled by default. You can enable it to work around hardware bugs like the ones found in the original SH7055 🛠️-mfused-madd,-mno-fused-madd—-mfused-maddgenerates code that uses the floating-point multiply and accumulate instructions 🧁-mno-fused-maddgenerates code that does not use them 🙅♀️ These instructions are generated by default if hardware floating point is used. The machine-dependent-mfused-maddoption is now mapped to the machine-independent-ffp-contract=fastoption, and-mno-fused-maddis mapped to-ffp-contract=off🔄-mfsca,-mno-fsca— allows (-mfsca) or disallows (-mno-fsca) the compiler from emitting thefscainstruction for sine and cosine approximations 📐 The option-mfscamust be used in combination with-funsafe-math-optimizations. It's enabled by default when generating code for SH4A. Using-mno-fscadisables sine and cosine approximations even if-funsafe-math-optimizationsis in effect.-mfsrra,-mno-fsrra— allows (-mfsrra) or disallows (-mno-fsrra) the compiler from emitting thefsrrainstruction for reciprocal square root approximations 🌟 The option-mfsrramust be used with-funsafe-math-optimizationsand-ffinite-math-only. It's enabled by default when generating code for SH4A. Using-mno-fsrradisables reciprocal square root approximations even if-funsafe-math-optimizationsand-ffinite-math-onlyare in effect.-mpretend-cmove— prefers zero-displacement conditional branches for conditional move instruction patterns 🏃♀️ This can result in faster code on the SH4 processor.-mfdpic— generates code using the FDPIC ABI 🧚
✨ Solaris 2 Options ✨
These -m options are supported on Solaris 2 🌞
-mclear-hwcap— tells the compiler to remove the hardware capabilities generated by the Solaris assembler 🧹 This is only necessary when object files use ISA extensions that the current machine doesn't support, but check at runtime whether or not to use them.-mimpure-text— used in addition to-shared, this tells the compiler to not pass-z textto the linker when linking a shared object 🦄 With this option, you can link position-dependent code into a shared object. Iconic, honestly.
bestie, okay so -mimpure-text silences the "relocations remain against allocatable but non-writable sections" linker error 🙈 but ngl it's a total trap 💀. The necessary relocations trigger copy-on-write, and the shared object is NOT actually shared across processes 😭. So instead of reaching for -mimpure-text, compile all your source code with -fpic or -fPIC 🫶✨.
On Solaris 2, you also get this one in addition to the above:
-pthreads— literally just a synonym for-pthread💜
🌸 SPARC Options 🌸
These -m options are supported on the SPARC 🦋
-mno-app-regs,-mapp-regs— Okay,-mapp-regsmakes the output use global registers 2 through 4, which the SPARC SVR4 ABI reserves for applications 💅 Like global register 1, each of 2 through 4 is then treated as an allocable register that gets clobbered by function calls. This is the default ✨. If you want to be fully SVR4 ABI-compliant (with a bit of a performance hit, sadly 🥲), use-mno-app-regs. You should compile libraries and system software with this one 🫶.-mflat,-mno-flat— With-mflat, the compiler skips the save/restore instructions and uses a "flat" or single register window model 🧚 This model is compatible with the regular register window model. The local registers and the input registers (0--5) are still treated as "call-saved" registers and get saved on the stack as needed. With-mno-flat(the default 👑), the compiler generates save/restore instructions, except for leaf functions. This is the normal operating mode.-mfpu,-mhard-float— Generates output with floating-point instructions. This is the default, obviously 💖.-mno-fpu,-msoft-float— Generates output with library calls for floating point instead 🌈.
⚠️ Warning: the requisite libraries are NOT available for all SPARC targets 💀. Normally the facilities of the machine's usual C compiler are used, but that can't be done directly in cross-compilation. You have to make your own arrangements to provide suitable library functions for cross-compilation. The embedded targetssparc-*-aoutandsparclite-*-*DO provide software floating-point support 🎀.
-msoft-float changes the calling convention in the output file, so it's only useful if you compile ALL of a program with this option 😭. In particular, you need to compile libgcc.a (the library that comes with GCC) with -msoft-float for this to work.
-mhard-quad-float— Generates output with quad-word (long double) floating-point instructions 🔥.-msoft-quad-float— Generates output with library calls for quad-word (long double) floating-point instructions. The functions called are the ones specified in the SPARC ABI. This is the default 💅.
As of this writing, there are no SPARC implementations with hardware support for the quad-word floating-point instructions 😭. They all invoke a trap handler for one of these instructions, and then the trap handler emulates the effect. Because of that trap handler overhead, it's MUCH slower than calling the ABI library routines. Which is exactly why -msoft-quad-float is the default 🙈.
-mno-unaligned-doubles,-munaligned-doubles—-mno-unaligned-doublesassumes doubles have 8-byte alignment. This is the default ✨.
With -munaligned-doubles, GCC only assumes doubles have 8-byte alignment if they're contained in another type, or if they have an absolute address. Otherwise, it assumes 4-byte alignment 🦋. Using this option avoids some rare compatibility problems with code generated by other compilers. It's not the default though, because it costs performance, especially for floating-point code 🥲.
-muser-mode,-mno-user-mode—-mno-user-modeis the default 👑. It means no code that can only run in supervisor mode gets generated. This is only relevant for thecasainstruction emitted for the LEON3 processor 🧚.-mfaster-structs,-mno-faster-structs— With-mfaster-structs, the compiler assumes structures should have 8-byte alignment. That lets it use pairs oflddandstdinstructions for copies in structure assignment, instead of twice as manyldandstpairs 🚀. BUT this changed alignment directly violates the SPARC ABI 💀. So it's only meant for targets where the developer acknowledges their code isn't directly in line with the ABI rules.-mstd-struct-return,-mno-std-struct-return— With-mstd-struct-return, the compiler generates checking code in functions that return structures or unions. It detects size mismatches between the two sides of function calls, as per the 32-bit ABI 🔍. The default is-mno-std-struct-return. This option has no effect in 64-bit mode.-mlra,-mno-lra— Enables Local Register Allocation 🌸. This has been the default for SPARC since GCC 7, so you need to pass-mno-lraif you want the old Reload.-mcpu=cpu_type— Sets the instruction set, register set, and instruction scheduling parameters for machine type cpu_type 💖. Supported values arev7,cypress,v8,supersparc,hypersparc,leon,leon3,leon3v7,leon5,sparclite,f930,f934,sparclite86x,sparclet,tsc701,v9,ultrasparc,ultrasparc3,niagara,niagara2,niagara3,niagara4,niagara7andm8.
Native Solaris and GNU/Linux toolchains also support the value native, which picks the best architecture option for the host processor ✨. -mcpu=native has no effect if GCC doesn't recognize the processor 💀.
Default instruction scheduling parameters get used for values that select an architecture rather than an implementation. Those are v7, v8, sparclite, sparclet, and v9 🧚.
Here's the lineup of each supported architecture and its implementations 👑:
v7:cypress,leon3v7v8:supersparc,hypersparc,leon,leon3,leon5sparclite:f930,f934,sparclite86xsparclet:tsc701v9:ultrasparc,ultrasparc3,niagara,niagara2,niagara3,niagara4,niagara7,m8
By default (unless configured otherwise), GCC generates code for the V7 variant of SPARC 🌈. With -mcpu=cypress, the compiler also optimizes for the Cypress CY7C602 chip, as used in the SPARCStation/SPARCServer 3xx series. This is also appropriate for the older SPARCStation 1, 2, IPX etc. 🦋
With -mcpu=v8, GCC generates code for the V8 variant. The only difference from V7 code is that the compiler emits the integer multiply and integer divide instructions that exist in SPARC-V8 but not in SPARC-V7 💅. With -mcpu=supersparc, it's additionally optimized for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and 2000 series.
With -mcpu=sparclite, GCC generates code for the SPARClite variant. This adds the integer multiply, integer divide step, and scan ("ffs") instructions that exist in SPARClite but not in SPARC-V7 🔥. With -mcpu=f930, the compiler also optimizes for the Fujitsu MB86930 chip, which is the original SPARClite, with no FPU. With -mcpu=f934, it's optimized for the Fujitsu MB86934, the more recent SPARClite with FPU.
With -mcpu=sparclet, GCC generates code for the SPARClet variant. This adds the integer multiply, multiply/accumulate, integer divide step, and scan ("ffs") instructions that exist in SPARClet but not in SPARC-V7 🧚. With -mcpu=tsc701, it's additionally optimized for the TEMIC SPARClet chip.
With -mcpu=v9, GCC generates code for the V9 variant 💜. This adds 64-bit integer and floating-point move instructions, 3 additional floating-point condition code registers, and conditional move instructions. Then the chip-specific extras stack up: -mcpu=ultrasparc optimizes for the Sun UltraSPARC I/II/IIi chips, -mcpu=ultrasparc3 for the Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips, -mcpu=niagara for Sun UltraSPARC T1 chips, -mcpu=niagara2 for Sun UltraSPARC T2 chips, -mcpu=niagara3 for Sun UltraSPARC T3 chips, and -mcpu=niagara4 for Sun UltraSPARC T4 chips 😭. -mcpu=niagara7 optimizes for Oracle SPARC M7 chips, and -mcpu=m8 optimizes for Oracle M8 chips 👑.
-mtune=cpu_type— Sets the instruction scheduling parameters for machine type cpu_type, but does NOT set the instruction set or register set the way-mcpu=cpu_typedoes 🎀.
The same values work for -mtune=cpu_type as for -mcpu=cpu_type, but the only useful ones are the values that select a particular CPU implementation 🙈. Those are cypress, supersparc, hypersparc, leon, leon3, leon3v7, leon5, f930, f934, sparclite86x, tsc701, ultrasparc, ultrasparc3, niagara, niagara2, niagara3, niagara4, niagara7 and m8. With native Solaris and GNU/Linux toolchains, native can be used too ✨.
-mv8plus,-mno-v8plus— With-mv8plus, GCC generates code for the SPARC-V8+ ABI 🦋. The difference from the V8 ABI is that the global and out registers are considered 64 bits wide. This is enabled by default on Solaris in 32-bit mode for all SPARC-V9 processors 💅.-mvis,-mno-vis— With-mvis, GCC generates code that takes advantage of the UltraSPARC Visual Instruction Set extensions 🔥. The default is-mno-vis.-mvis2,-mno-vis2— With-mvis2, GCC generates code that takes advantage of version 2.0 of the UltraSPARC Visual Instruction Set extensions 🌈. The default is-mvis2when targeting a CPU that supports such instructions, like UltraSPARC-III and later. Setting-mvis2also sets-mvis.-mvis3,-mno-vis3— With-mvis3, GCC generates code that takes advantage of version 3.0 of the UltraSPARC Visual Instruction Set extensions 🧚. The default is-mvis3when targeting a CPU that supports such instructions, like niagara-3 and later. Setting-mvis3also sets-mvis2and-mvis💖.-mvis4,-mno-vis4— okay so-mvis4makes GCC write code that uses version 4.0 of the UltraSPARC Visual Instruction Set extensions 💖 It's on by default when you target a cpu that has them, like niagara-7 and later ✨ Turning on-mvis4also turns on-mvis3,-mvis2and-mvis🦋-mvis4b,-mno-vis4b— with-mvis4b, GCC uses version 4.0 of the UltraSPARC VIS extensions plus the extra VIS instructions added in the Oracle SPARC Architecture 2017 🔥 The default is-mvis4bfor cpus that support them, like m8 and later 💅 Setting-mvis4balso sets-mvis4,-mvis3,-mvis2and-mvis🫶-mcbcond,-mno-cbcond— with-mcbcond, GCC uses the UltraSPARC Compare-and-Branch-on-Condition instructions 🌸 It's the default when targeting a CPU that has them, like Niagara-4 and later 💜-mfmaf,-mno-fmaf— with-mfmaf, GCC uses the UltraSPARC Fused Multiply-Add Floating-point instructions 🧚 Default when targeting a CPU that supports them, like Niagara-3 and later ⭐-mfsmuld,-mno-fsmuld— with-mfsmuld, GCC uses the Floating-point Multiply Single to Double (FsMULd) instruction 🦋 The default is-mfsmuldwhen targeting a CPU that supports the architecture versions V8 or V9 with FPU, except-mcpu=leon🙈-mpopc,-mno-popc— with-mpopc, GCC uses the UltraSPARC Population Count instruction 🍓 Default when targeting a CPU that has it, like Niagara-2 and later 👑-msubxc,-mno-subxc— with-msubxc, GCC uses the UltraSPARC Subtract-Extended-with-Carry instruction 💅 It's the default for a CPU that has it, like Niagara-7 and later ✨-mfix-at697f— turns on the documented workaround for the single erratum of the Atmel AT697F processor (which is erratum #13 of the AT697E processor) 🎀-mfix-ut699— turns on the documented workarounds for the floating-point errata and the data cache nullify errata of the UT699 processor 🌈-mfix-ut700— turns on the documented workaround for the back-to-back store errata of the UT699E/UT700 processor 🧚-mfix-gr712rc— turns on the documented workaround for the back-to-back store errata of the GR712RC processor 💖
These -m options are supported in addition to the above on SPARC-V9 processors in 64-bit environments ✨
-m32,-m64— generate code for a 32-bit or 64-bit environment 🔥 The 32-bit one setsint,longand pointer to 32 bits. The 64-bit one setsintto 32 bits andlongand pointer to 64 bits 💅-mcmodel=which— set the code model to one of these 🫶medlow— the Medium/Low code model: 64-bit addresses, and programs must be linked in the low 32 bits of memory 🌸 Programs can be statically or dynamically linked 💜medmid— the Medium/Middle code model: 64-bit addresses, and programs must be linked in the low 44 bits of memory 🦋 The text and data segments must each be less than 2GB in size, and the data segment must be located within 2GB of the text segment ⭐medany— the Medium/Anywhere code model: 64-bit addresses, and programs can be linked anywhere in memory 🌈 The text and data segments must be less than 2GB in size, and the data segment must be located within 2GB of the text segment 🎀embmedany— the Medium/Anywhere code model for embedded systems: 64-bit addresses, and the text and data segments must be less than 2GB in size 🧚 Both can start anywhere in memory, which gets decided at link time 🙈 The global register%g4points to the base of the data segment 👑 Programs are statically linked, and PIC is not supported 💀
-mmemory-model=mem-model— set the memory model the processor runs with, to one of these 💖default— the default memory model for the processor and operating system ✨rmo— Relaxed Memory Order 🦋pso— Partial Store Order 🔥tso— Total Store Order 💅sc— Sequential Consistency 🫶
These memory models are formally defined in Appendix D of the SPARC-V9 architecture manual, as set in the processor's PSTATE.MM field 🌸
-mstack-bias,-mno-stack-bias— with-mstack-bias, GCC assumes the stack pointer (and the frame pointer, if there is one) is offset by-2047, which has to be added back when making stack frame references 💜 This is the default in 64-bit mode 🦋 Otherwise, GCC assumes no such offset is present ⭐
✨ Options for System V ✨
These additional options are available on System V Release 4 for compatibility with other compilers on those systems 🌈
-G— creates a shared object 🎀 It's recommended to use-symbolicor-sharedinstead 🧚-Qy— identifies the versions of each tool used by the compiler, in a.identassembler directive in the output 💖-Qn— refrains from adding.identdirectives to the output file (this is the default) ✨-YP,dirs— searches the directoriesdirs, and no others, for libraries specified with-l🔥-Ym,dir— looks in the directorydirto find the M4 preprocessor 💅 The assembler uses this option 🫶
✨ V850 Options ✨
These -m options are defined for V850 implementations 🌸
-mlong-calls,-mno-long-calls— treats all calls as being far away (near) 💜 If calls are assumed to be far away, the compiler always loads the function's address into a register, and calls indirect through the pointer 🦋-mno-ep,-mep— does not optimize (or does optimize) basic blocks that use the same index pointer 4 or more times to copy the pointer into theepregister, and use the shortersldandsstinstructions ⭐ The-mepoption is on by default if you optimize 🌈-mno-prolog-function,-mprolog-function— does not use (or does use) external functions to save and restore registers at the prologue and epilogue of a function 🎀 The external functions are slower, but they use less code space if more than one function saves the same number of registers 🧚 The-mprolog-functionoption is on by default if you optimize 💖-mspace— tries to make the code as small as possible 🔥 At present, this just turns on the-mepand-mprolog-functionoptions 💅-mtda=n— puts static or global variables whose size isnbytes or less into the tiny data area that theepregister points to 🫶 The tiny data area can hold up to 256 bytes in total (128 bytes for byte references) 🌸-msda=n— puts static or global variables whose size isnbytes or less into the small data area that thegpregister points to 💜 The small data area can hold up to 64 kilobytes 🦋-mzda=n— puts static or global variables whose size isnbytes or less into the first 32 kilobytes of memory ⭐-mv850— specifies that the target processor is the V850 🌈-mv850e3v5— specifies that the target processor is the V850E3V5 🎀 The preprocessor constant__v850e3v5__is defined if this option is used 🧚-mv850e2v4— specifies that the target processor is the V850E3V5 💖 This is an alias for the-mv850e3v5option ✨-mv850e2v3— specifies that the target processor is the V850E2V3 🔥 The preprocessor constant__v850e2v3__is defined if this option is used 💅-mv850e2— specifies that the target processor is the V850E2 🫶 The preprocessor constant__v850e2__is defined if this option is used 🌸-mv850e1— specifies that the target processor is the V850E1 💜 The preprocessor constants__v850e1__and__v850e__are defined if this option is used 🦋-mv850es— specifies that the target processor is the V850ES ⭐ This is an alias for the-mv850e1option 🌈-mv850e— specifies that the target processor is the V850E 🎀 The preprocessor constant__v850e__is defined if this option is used 🧚
If neither -mv850 nor -mv850e nor -mv850e1 nor -mv850e2 nor -mv850e2v3 nor -mv850e3v5 are defined, then a default target processor is chosen and the relevant __v850*__ preprocessor constant is defined 💖
The preprocessor constants __v850 and __v851__ are always defined, no matter which processor variant is the target 🔥
-mdisable-callt,-mno-disable-callt— suppresses generation of theCALLTinstruction for the v850e, v850e1, v850e2, v850e2v3 and v850e3v5 flavors of the v850 architecture 💅
This option is enabled by default when the RH850 ABI is in use (see -mrh850-abi), and disabled by default when the GCC ABI is in use 🫶 If CALLT instructions are being generated, then the C preprocessor symbol __V850_CALLT__ is defined 🌸
-mrelax,-mno-relax— passes on (or does not pass on) the-mrelaxcommand-line option to the assembler 💜-mlong-jumps,-mno-long-jumps— disables (or re-enables) the generation of PC-relative jump instructions 🦋-msoft-float,-mhard-float— disables (or re-enables) the generation of hardware floating point instructions ⭐ This option only matters when the target architecture is V850E2V3 or higher 🌈 If hardware floating point instructions are being generated, then the C preprocessor symbol__FPU_OK__is defined; otherwise, the symbol__NO_FPU__is defined 🎀-mloop— enables the use of the e3v5LOOPinstruction 🧚 This instruction is not enabled by default when the e3v5 architecture is selected, because its use is still experimental 💖-mrh850-abi,-mghs— enables support for the RH850 version of the V850 ABI 🔥 This is the default 💅 With this version of the ABI, the following rules apply 🫶- Integer sized structures and unions are returned via a memory pointer rather than a register 🌸
- Large structures and unions (more than 8 bytes in size) are passed by value 💜
- Functions are aligned to 16-bit boundaries 🦋
- The
-m8byte-aligncommand-line option is supported ⭐ - The
-mdisable-calltcommand-line option is enabled by default. The-mno-disable-calltcommand-line option is not supported 🌈
When this version of the ABI is enabled, the C preprocessor symbol __V850_RH850_ABI__ is defined 🎀
-mgcc-abi— okay so this one turns on the old GCC flavour of the V850 ABI 💅 With this version, the rules are:- Integer sized structures and unions get returned in register
r10🎀 - Large structures and unions (more than 8 bytes in size) get passed by reference 🦋
- Functions get aligned to 32-bit boundaries, unless you're optimizing for size 🌸
- The
-m8byte-aligncommand-line option is not supported 💀 - The
-mdisable-calltcommand-line option is supported, but it's not enabled by default 🙈
- Integer sized structures and unions get returned in register
When this version of the ABI is on, the C preprocessor symbol __V850_GCC_ABI__ gets defined ✨
-m8byte-align,-mno-8byte-align— this letsdoubleandlong longget aligned on 8-byte boundaries 🍓 By default, everything gets capped at 4-byte alignment, so this is the glow-up option. When-m8byte-alignis in effect, the C preprocessor symbol__V850_8BYTE_ALIGN__is defined 💖-mbig-switch— generates code that's suitable for big switch tables 🧚 Only use this if the assembler or linker is yelling about out of range branches inside a switch table 😭-mapp-regs— this makes the compiler user2andr5in its generated code. This is the default, so you're already set 🫶-mno-app-regs— this one treatsr2andr5as fixed registers instead 🔒
✨ VAX Options ✨
These -m options are defined for the VAX 🦋
-munix— don't output certain jump instructions (aobleqand so on) that the Unix assembler for the VAX can't handle across long ranges 🙅♀️-mgnu— do output those jump instructions, on the assumption that the GNU assembler is being used 💜-mg— outputs code for G-format floating-point numbers instead of D-format 🌈-mlra,-mno-lra— these enable Local Register Allocation. It's still experimental for the VAX, so by default the compiler uses standard reload 🧪
✨ Visium Options ✨
These -m options are defined for the Visium 🛸
-mdebug— if your program does file I/O and is headed for an MCM target, link it with this option 🔧 It causes the librarieslibc.aandlibdebug.ato be linked. The program should be run on the target under the control of the GDB remote debugging stub 🐛-msim— if your program does file I/O and is destined for the simulator, link it with this option 🖥️ It causes the librarieslibc.aandlibsim.ato be linked ✨-mfpu,-mhard-float— generates code containing floating-point instructions. This is the default 🔥-mno-fpu,-msoft-float— generates code containing library calls for floating-point instead 🧮
-msoft-floatchanges the calling convention in the output file, so it's only useful if you compile all of a program with this option 🚨 In particular, you need to compilelibgcc.a, the library that comes with GCC, with-msoft-floatin order for this to work.
-mcpu=cpu_type— sets the instruction set, register set, and instruction scheduling parameters for machine typecpu_type. The supported values forcpu_typearemcm,gr5andgr6👑mcmis a synonym ofgr5, kept around for backward compatibility 🕰️- By default (unless configured otherwise), GCC generates code for the GR5 variant of the Visium architecture 💅
- With
-mcpu=gr6, GCC generates code for the GR6 variant of the Visium architecture. The only difference from GR5 code is that the compiler will generate block move instructions 🚚
-mtune=cpu_type— sets the instruction scheduling parameters for machine typecpu_type, but doesn't set the instruction set or register set that-mcpu=cpu_typewould 🎯-msv-mode— generates code for supervisor mode, where there are no restrictions on access to general registers. This is the default 👑-muser-mode— generates code for user mode, where access to some general registers is forbidden. On the GR5, registersr24tor31can't be accessed in this mode. On the GR6, only registersr29tor31are affected 🚫
✨ VMS Options ✨
These -m options are defined for the VMS implementations 💻
-mvms-return-codes— returns VMS condition codes frommain. The default is to return POSIX-style condition (e.g. error) codes 🔁-mdebug-main=prefix— flags the first routine whose name starts withprefixas the main routine for the debugger 🔍-mmalloc64— defaults to 64-bit memory allocation routines 🧠-mpointer-size=size— sets the default size of pointers. The possible options forsizeare32orshortfor 32-bit pointers,64orlongfor 64-bit pointers, andnofor supporting only 32-bit pointers. The latter option disablespragma pointer_size🙃
✨ VxWorks Options ✨
The options in this section are defined for all VxWorks targets 🌸 Options specific to the target hardware are listed with the other options for that target.
-mrtp— GCC can generate code for both VxWorks kernels and real time processes (RTPs). This option switches from the former to the latter 🔀 It also defines the preprocessor macro__RTP__🧚-msmp— selects SMP runtimes for linking. This isn't available on architectures other than PowerPC, nor on VxWorks version 7 or later, where the selection is part of the VxWorks build configuration and the library paths are the same for either choice 🙅♀️-non-static— links an RTP executable against shared libraries rather than static libraries 🔗 The options-staticand-sharedcan also be used for RTPs, and-staticis the default 💜-Bstatic,-Bdynamic— these options are passed down to the linker. They're defined for compatibility with Diab 🤝-Xbind-lazy— enables lazy binding of function calls. This option is equivalent to-Wl,-z,nowand is defined for compatibility with Diab 🦥-Xbind-now— disables lazy binding of function calls. This option is the default, and it's defined for compatibility with Diab ⚡
✨ x86 Options ✨
These -m options are defined for the x86 family of computers 💖
-march=cpu-type— generates instructions for the machine typecpu-type. Unlike-mtune=cpu-type, which merely tunes the generated code for the specifiedcpu-type,-march=cpu-typelets GCC generate code that may not run at all on processors other than the one indicated 😬 Specifying-march=cpu-typeimplies-mtune=cpu-type, except where noted otherwise.
The choices for cpu-type are:
native— selects the CPU to generate code for at compilation time by figuring out the processor type of the compiling machine 🖥️ Using-march=nativeenables all instruction subsets supported by the local machine, so the result might not run on different machines. Using-mtune=nativeproduces code optimized for the local machine under the constraints of the selected instruction set.x86-64— a generic CPU with 64-bit extensions 🌐x86-64-v2,x86-64-v3,x86-64-v4— these choices select the corresponding micro-architecture level from the x86-64 psABI. On ABIs other than the x86-64 psABI, they select the same CPU features as the x86-64 psABI documents for that micro-architecture level 📜 Since thesecpu-typevalues don't have a corresponding-mtunesetting, using-marchwith them enables generic tuning. Specific tuning can be enabled using the-mtune=other-cpu-typeoption with an appropriateother-cpu-typevalue 🎛️i386— the original Intel i386 CPU 🦕i486— the Intel i486 CPU. (No scheduling is implemented for this chip 🤷♀️)i586,pentium— the Intel Pentium CPU with no MMX support 🍭lakemont— the Intel Lakemont MCU, based on the Intel Pentium CPU 🔧pentium-mmx— the Intel Pentium MMX CPU, based on the Pentium core with MMX instruction set support 🎶pentiumpro— the Intel Pentium Pro CPU 🌟i686— when used with-march, the Pentium Pro instruction set is used, so the code runs on all i686 family chips 💜 When used with-mtune, it has the same meaning asgeneric.pentium2— the Intel Pentium II CPU, based on the Pentium Pro core with MMX and FXSR instruction set support ✨pentium3,pentium3m— the Intel Pentium III CPU, based on the Pentium Pro core with MMX, FXSR and SSE instruction set support 🌷pentium-m— the Intel Pentium M, a low-power version of the Intel Pentium III CPU with MMX, SSE, SSE2 and FXSR instruction set support. It's used by Centrino notebooks 💻pentium4,pentium4m— the Intel Pentium 4 CPU with MMX, SSE, SSE2 and FXSR instruction set support 🌀prescott— an improved version of the Intel Pentium 4 CPU with MMX, SSE, SSE2, SSE3 and FXSR instruction set support 📈nocona— an improved version of the Intel Pentium 4 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and FXSR instruction set support 🌙core2— the Intel Core 2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, CX16, SAHF and FXSR instruction set support ☕nehalem— the Intel Nehalem CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF and FXSR instruction set support 🌿westmere— the Intel Westmere CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR and PCLMUL instruction set support 🍒sandybridge— the Intel Sandy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE and PCLMUL instruction set support 🌅ivybridge— the Intel Ivy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND and F16C instruction set support 🍃haswell— the Intel Haswell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, AVX, XSAVE, PCLMUL, FSGSBASE, RDRND, F16C, AVX2, BMI, BMI2, LZCNT, FMA, MOVBE and HLE instruction set support 🌈
broadwell🌸: Intel Broadwell CPU is giving 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCXandPREFETCHWinstruction set support 💅skylake🦋: Intel Skylake CPU brings 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVESandSGXinstruction set support ✨bonnell🧚: Intel Bonnell CPU has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3andSSSE3instruction set support, and that's the whole vibe 🍓silvermont💜: Intel Silvermont CPU comes with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,PCLMUL,PREFETCHWandRDRNDinstruction set support 🌈goldmont👑: Intel Goldmont CPU is so extra with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,PCLMUL,PREFETCHW,RDRND,AES,SHA,RDSEED,XSAVE,XSAVEC,XSAVES,XSAVEOPT,CLFLUSHOPTandFSGSBASEinstruction set support 🔥goldmont-plus⭐: Intel Goldmont Plus CPU keeps the glow up going with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,PCLMUL,PREFETCHW,RDRND,AES,SHA,RDSEED,XSAVE,XSAVEC,XSAVES,XSAVEOPT,CLFLUSHOPT,FSGSBASE,PTWRITE,RDPIDandSGXinstruction set support 💅tremont🎀: Intel Tremont CPU has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,PCLMUL,PREFETCHW,RDRND,AES,SHA,RDSEED,XSAVE,XSAVEC,XSAVES,XSAVEOPT,CLFLUSHOPT,FSGSBASE,PTWRITE,RDPID,SGX,CLWB,GFNI-SSE,MOVDIRI,MOVDIR64B,CLDEMOTEandWAITPKGinstruction set support 🫶sierraforest🌈: Intel Sierra Forest CPU is literally a whole forest of features, with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,AES,PREFETCHW,PCLMUL,RDRND,XSAVE,XSAVEC,XSAVES,XSAVEOPT,FSGSBASE,PTWRITE,RDPID,SGX,GFNI-SSE,CLWB,MOVDIRI,MOVDIR64B,CLDEMOTE,WAITPKG,ADCX,AVX,AVX2,BMI,BMI2,F16C,FMA,LZCNT,PCONFIG,PKU,VAES,VPCLMULQDQ,SERIALIZE,HRESET,KL,WIDEKL,AVX-VNNI,AVXIFMA,AVXVNNIINT8,AVXNECONVERT,CMPCCXADD,ENQCMDandUINTRinstruction set support 🦋grandridge🧚: Intel Grand Ridge CPU has the exact same feature set as Sierra Forest, so 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,AES,PREFETCHW,PCLMUL,RDRND,XSAVE,XSAVEC,XSAVES,XSAVEOPT,FSGSBASE,PTWRITE,RDPID,SGX,GFNI-SSE,CLWB,MOVDIRI,MOVDIR64B,CLDEMOTE,WAITPKG,ADCX,AVX,AVX2,BMI,BMI2,F16C,FMA,LZCNT,PCONFIG,PKU,VAES,VPCLMULQDQ,SERIALIZE,HRESET,KL,WIDEKL,AVX-VNNI,AVXIFMA,AVXVNNIINT8,AVXNECONVERT,CMPCCXADD,ENQCMDandUINTRinstruction set support 💖clearwaterforest💅: Intel Clearwater Forest CPU is the newest glow up on this list, with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,AES,PREFETCHW,PCLMUL,RDRND,XSAVE,XSAVEC,XSAVES,XSAVEOPT,FSGSBASE,PTWRITE,RDPID,SGX,GFNI-SSE,CLWB,MOVDIRI,MOVDIR64B,CLDEMOTE,WAITPKG,ADCX,AVX,AVX2,BMI,BMI2,F16C,FMA,LZCNT,PCONFIG,PKU,VAES,VPCLMULQDQ,SERIALIZE,HRESET,KL,WIDEKL,AVX-VNNI,ENQCMD,UINTR,AVXIFMA,AVXVNNIINT8,AVXNECONVERT,CMPCCXADD,AVXVNNIINT16,SHA512,SM3,SM4,USER_MSRandPREFETCHIinstruction set support 👑knl🌸: Intel Knight's Landing CPU brings 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AVX512PF,AVX512ER,AVX512F,AVX512CDandPREFETCHWT1instruction set support 🔥knm🦋: Intel Knights Mill CPU has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AVX512PF,AVX512ER,AVX512F,AVX512CDandPREFETCHWT1,AVX5124VNNIW,AVX5124FMAPSandAVX512VPOPCNTDQinstruction set support ✨skylake-avx512🧚: Intel Skylake Server CPU comes with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,CLWB,AVX512VL,AVX512BW,AVX512DQandAVX512CDinstruction set support 💜cannonlake💀: Intel Cannonlake Server CPU has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMAandSHAinstruction set support 🌈icelake-client🎀: Intel Icelake Client CPU is serving 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMA,SHA,AVX512VNNI,GFNI,VAES,AVX512VBMI2,VPCLMULQDQ,AVX512BITALG,RDPIDandAVX512VPOPCNTDQinstruction set support 🫶icelake-server💖: Intel Icelake Server CPU has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMA,SHA,AVX512VNNI,GFNI,VAES,AVX512VBMI2,VPCLMULQDQ,AVX512BITALG,RDPID,AVX512VPOPCNTDQ,PCONFIG,WBNOINVDandCLWBinstruction set support 🌸cascadelake🍓: Intel Cascadelake CPU comes with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,CLWB,AVX512VL,AVX512BW,AVX512DQ,AVX512CDandAVX512VNNIinstruction set support 👑cooperlake🔥: Intel cooperlake CPU is serving 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,CLWB,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,AVX512VNNIandAVX512BF16instruction set support ⭐tigerlake🧚: Intel Tigerlake CPU has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMA,SHA,AVX512VNNI,GFNI,VAES,AVX512VBMI2,VPCLMULQDQ,AVX512BITALG,RDPID,AVX512VPOPCNTDQ,MOVDIRI,MOVDIR64B,CLWB,AVX512VP2INTERSECTandKEYLOCKERinstruction set support 💜sapphirerapids💅: Intel sapphirerapids CPU is the main character with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMA,SHA,AVX512VNNI,GFNI,VAES,AVX512VBMI2,VPCLMULQDQ,AVX512BITALG,RDPID,AVX512VPOPCNTDQ,PCONFIG,WBNOINVD,CLWB,MOVDIRI,MOVDIR64B,ENQCMD,CLDEMOTE,PTWRITE,WAITPKG,SERIALIZE,TSXLDTRK,UINTR,AMX-BF16,AMX-TILE,AMX-INT8,AVX-VNNI,AVX512-FP16andAVX512BF16instruction set support 🫶alderlake🌈: Intel Alderlake CPU has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,AES,PREFETCHW,PCLMUL,RDRND,XSAVE,XSAVEC,XSAVES,XSAVEOPT,FSGSBASE,PTWRITE,RDPID,SGX,GFNI-SSE,CLWB,MOVDIRI,MOVDIR64B,CLDEMOTE,WAITPKG,ADCX,AVX,AVX2,BMI,BMI2,F16C,FMA,LZCNT,PCONFIG,PKU,VAES,VPCLMULQDQ,SERIALIZE,HRESET,KL,WIDEKLandAVX-VNNIinstruction set support 🦋rocketlake🌸: Intel Rocketlake CPU comes with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMA,SHA,AVX512VNNI,GFNI,VAES,AVX512VBMI2,VPCLMULQDQ,AVX512BITALG,RDPIDandAVX512VPOPCNTDQinstruction set support ✨graniterapids👑: Intel graniterapids CPU is the newest queen on the list, with 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMA,SHA,AVX512VNNI,GFNI,VAES,AVX512VBMI2,VPCLMULQDQ,AVX512BITALG,RDPID,AVX512VPOPCNTDQ,PCONFIG,WBNOINVD,CLWB,MOVDIRI,MOVDIR64B,ENQCMD,CLDEMOTE,PTWRITE,WAITPKG,SERIALIZE,TSXLDTRK,UINTR,AMX-BF16,AMX-TILE,AMX-INT8,AVX-VNNI,AVX512-FP16,AVX512BF16,AMX-FP16andPREFETCHIinstruction set support 💖graniterapids-d— 🌸 okay bestie, this is the Intel graniterapids D CPU and it is loaded. You get 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,CX16,SAHF,FXSR,AVX,XSAVE,PCLMUL,FSGSBASE,RDRND,F16C,AVX2,BMI,BMI2,LZCNT,FMA,MOVBE,HLE,RDSEED,ADCX,PREFETCHW,AES,CLFLUSHOPT,XSAVEC,XSAVES,SGX,AVX512F,AVX512VL,AVX512BW,AVX512DQ,AVX512CD,PKU,AVX512VBMI,AVX512IFMA,SHA,AVX512VNNI,GFNI,VAES,AVX512VBMI2,VPCLMULQDQ,AVX512BITALG,RDPID,AVX512VPOPCNTDQ,PCONFIG,WBNOINVD,CLWB,MOVDIRI,MOVDIR64B,ENQCMD,CLDEMOTE,PTWRITE,WAITPKG,SERIALIZE,TSXLDTRK,UINTR,AMX-BF16,AMX-TILE,AMX-INT8,AVX-VNNI,AVX512FP16,AVX512BF16,AMX-FP16,PREFETCHIandAMX-COMPLEXinstruction set support. 💅✨arrowlake— 🦋 the Intel Arrow Lake CPU, also giving main character energy. It has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,AES,PREFETCHW,PCLMUL,RDRND,XSAVE,XSAVEC,XSAVES,XSAVEOPT,FSGSBASE,PTWRITE,RDPID,SGX,GFNI-SSE,CLWB,MOVDIRI,MOVDIR64B,CLDEMOTE,WAITPKG,ADCX,AVX,AVX2,BMI,BMI2,F16C,FMA,LZCNT,PCONFIG,PKU,VAES,VPCLMULQDQ,SERIALIZE,HRESET,KL,WIDEKL,AVX-VNNI,UINTR,AVXIFMA,AVXVNNIINT8,AVXNECONVERTandCMPCCXADDinstruction set support. 🎀arrowlake-s— 💖 the Intel Arrow Lake S CPU, which is basically arrowlake's glow-up. It has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,AES,PREFETCHW,PCLMUL,RDRND,XSAVE,XSAVEC,XSAVES,XSAVEOPT,FSGSBASE,PTWRITE,RDPID,SGX,GFNI-SSE,CLWB,MOVDIRI,MOVDIR64B,CLDEMOTE,WAITPKG,ADCX,AVX,AVX2,BMI,BMI2,F16C,FMA,LZCNT,PCONFIG,PKU,VAES,VPCLMULQDQ,SERIALIZE,HRESET,KL,WIDEKL,AVX-VNNI,UINTR,AVXIFMA,AVXVNNIINT8,AVXNECONVERT,CMPCCXADD,AVXVNNIINT16,SHA512,SM3andSM4instruction set support. 🧚pantherlake— 👑 the Intel Panther Lake CPU, and it's giving a lot. It has 64-bit extensions plusMOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,POPCNT,AES,PREFETCHW,PCLMUL,RDRND,XSAVE,XSAVEC,XSAVES,XSAVEOPT,FSGSBASE,PTWRITE,RDPID,SGX,GFNI-SSE,CLWB,MOVDIRI,MOVDIR64B,CLDEMOTE,WAITPKG,ADCX,AVX,AVX2,BMI,BMI2,F16C,FMA,LZCNT,PCONFIG,PKU,VAES,VPCLMULQDQ,SERIALIZE,HRESET,KL,WIDEKL,AVX-VNNI,UINTR,AVXIFMA,AVXVNNIINT8,AVXNECONVERT,CMPCCXADD,AVXVNNIINT16,SHA512,SM3,SM4andPREFETCHIinstruction set support. 🔥k6— 🌈 the AMD K6 CPU, a classic withMMXinstruction set support. Vintage queen. 🍓k6-2,k6-3— 🧁 improved versions of the AMD K6 CPU, withMMXand3DNow!instruction set support.athlon,athlon-tbird— ⭐ the AMD Athlon CPU withMMX,3dNOW!, enhanced3DNow!andSSEprefetch instructions support. Iconic.athlon-4,athlon-xp,athlon-mp— 🔥 upgraded AMD Athlon CPUs withMMX,3DNow!, enhanced3DNow!and fullSSEinstruction set support. Level up, no cap.k8,opteron,athlon64,athlon-fx— 👑 processors based on the AMD K8 core withx86-64instruction set support, including the AMD Opteron, Athlon 64, and Athlon 64 FX processors. (This one supersetsMMX,SSE,SSE2,3DNow!, enhanced3DNow!and 64-bit instruction set extensions.) 🫶k8-sse3,opteron-sse3,athlon64-sse3— 💜 improved versions of the AMD K8 cores withSSE3instruction set support.amdfam10,barcelona— 🌸 CPUs based on AMD Family 10h cores withx86-64instruction set support. (This supersetsMMX,SSE,SSE2,SSE3,SSE4A,3DNow!, enhanced3DNow!,ABMand 64-bit instruction set extensions.) ✨bdver1— 🦋 CPUs based on AMD Family 15h cores withx86-64instruction set support. (This supersetsFMA4,AVX,XOP,LWP,AES,PCLMUL,CX16,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABMand 64-bit instruction set extensions.) 💅bdver2— 🎀 AMD Family 15h core based CPUs withx86-64instruction set support. (This supersetsBMI,TBM,F16C,FMA,FMA4,AVX,XOP,LWP,AES,PCLMUL,CX16,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABMand 64-bit instruction set extensions.) 🔥bdver3— 🌈 AMD Family 15h core based CPUs withx86-64instruction set support. (This supersetsBMI,TBM,F16C,FMA,FMA4,FSGSBASE,AVX,XOP,LWP,AES,PCLMUL,CX16,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABMand 64-bit instruction set extensions.) 🫶bdver4— 💖 AMD Family 15h core based CPUs withx86-64instruction set support. (This supersetsBMI,BMI2,TBM,F16C,FMA,FMA4,FSGSBASE,AVX,AVX2,XOP,LWP,AES,PCLMUL,CX16,MOVBE,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABMand 64-bit instruction set extensions.) 😭znver1— 🧚 AMD Family 17h core based CPUs withx86-64instruction set support. (This supersetsBMI,BMI2,F16C,FMA,FSGSBASE,AVX,AVX2,ADCX,RDSEED,MWAITX,SHA,CLZERO,AES,PCLMUL,CX16,MOVBE,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABM,XSAVEC,XSAVES,CLFLUSHOPT,POPCNT, and 64-bit instruction set extensions.) 💜znver2— 🍓 AMD Family 17h core based CPUs withx86-64instruction set support. (This supersetsBMI,BMI2,CLWB,F16C,FMA,FSGSBASE,AVX,AVX2,ADCX,RDSEED,MWAITX,SHA,CLZERO,AES,PCLMUL,CX16,MOVBE,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABM,XSAVEC,XSAVES,CLFLUSHOPT,POPCNT,RDPID,WBNOINVD, and 64-bit instruction set extensions.) 🌸znver3— 🎀 AMD Family 19h core based CPUs withx86-64instruction set support. (This supersetsBMI,BMI2,CLWB,F16C,FMA,FSGSBASE,AVX,AVX2,ADCX,RDSEED,MWAITX,SHA,CLZERO,AES,PCLMUL,CX16,MOVBE,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABM,XSAVEC,XSAVES,CLFLUSHOPT,POPCNT,RDPID,WBNOINVD,PKU,VPCLMULQDQ,VAES, and 64-bit instruction set extensions.) ✨znver4— 🔥 AMD Family 19h core based CPUs withx86-64instruction set support. (This supersetsBMI,BMI2,CLWB,F16C,FMA,FSGSBASE,AVX,AVX2,ADCX,RDSEED,MWAITX,SHA,CLZERO,AES,PCLMUL,CX16,MOVBE,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABM,XSAVEC,XSAVES,CLFLUSHOPT,POPCNT,RDPID,WBNOINVD,PKU,VPCLMULQDQ,VAES,AVX512F,AVX512DQ,AVX512IFMA,AVX512CD,AVX512BW,AVX512VL,AVX512BF16,AVX512VBMI,AVX512VBMI2,AVX512VNNI,AVX512BITALG,AVX512VPOPCNTDQ,GFNIand 64-bit instruction set extensions.) 👑znver5— 🦋 AMD Family 1ah core based CPUs withx86-64instruction set support. (This supersetsBMI,BMI2,CLWB,F16C,FMA,FSGSBASE,AVX,AVX2,ADCX,RDSEED,MWAITX,SHA,CLZERO,AES,PCLMUL,CX16,MOVBE,MMX,SSE,SSE2,SSE3,SSE4A,SSSE3,SSE4.1,SSE4.2,ABM,XSAVEC,XSAVES,CLFLUSHOPT,POPCNT,RDPID,WBNOINVD,PKU,VPCLMULQDQ,VAES,AVX512F,AVX512DQ,AVX512IFMA,AVX512CD,AVX512BW,AVX512VL,AVX512BF16,AVX512VBMI,AVX512VBMI2,AVX512VNNI,AVX512BITALG,AVX512VPOPCNTDQ,GFNI,AVXVNNI,MOVDIRI,MOVDIR64B,AVX512VP2INTERSECT,PREFETCHIand 64-bit instruction set extensions.) 🌈btver1— 🌸 CPUs based on AMD Family 14h cores withx86-64instruction set support. (This supersetsMMX,SSE,SSE2,SSE3,SSSE3,SSE4A,CX16,ABMand 64-bit instruction set extensions.) 🫶btver2— 💅 CPUs based on AMD Family 16h cores withx86-64instruction set support. This includesMOVBE,F16C,BMI,AVX,PCLMUL,AES,SSE4.2,SSE4.1,CX16,ABM,SSE4A,SSSE3,SSE3,SSE2,SSE,MMXand 64-bit instruction set extensions. ✨winchip-c6— 🧁 the IDT WinChip C6 CPU, which gets treated the same way as ani486but with extraMMXinstruction set support. 🍓winchip2— 🎀 the IDT WinChip 2 CPU, also handled the same way as ani486, plus extraMMXand3DNow!instruction set support. 💜c3— 🌈 the VIA C3 CPU withMMXand3DNow!instruction set support. (No scheduling is implemented for this chip.) 😭c3-2— 🦋 the VIA C3-2 (Nehemiah/C5XL) CPU withMMXandSSEinstruction set support. (No scheduling is implemented for this chip.) 🌸c7— ✨ the VIA C7 (Esther) CPU withMMX,SSE,SSE2andSSE3instruction set support. (No scheduling is implemented for this chip.) 🫶samuel-2— 💖 the VIA Eden Samuel 2 CPU withMMXand3DNow!instruction set support. (No scheduling is implemented for this chip.) 🧚nehemiah— 🔥 the VIA Eden Nehemiah CPU withMMXandSSEinstruction set support. (No scheduling is implemented for this chip.) 👑esther— 💜 the VIA Eden Esther CPU withMMX,SSE,SSE2andSSE3instruction set support. (No scheduling is implemented for this chip.) 🍓eden-x2— 🌸 the VIA Eden X2 CPU withx86-64,MMX,SSE,SSE2andSSE3instruction set support. (No scheduling is implemented for this chip.) ✨eden-x4— 🎀 the VIA Eden X4 CPU withx86-64,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,AVXandAVX2instruction set support. (No scheduling is implemented for this chip.) 🔥nano— 💅 the generic VIA Nano CPU withx86-64,MMX,SSE,SSE2,SSE3andSSSE3instruction set support. (No scheduling is implemented for this chip.) 🌈nano-1000— 🦋 the VIA Nano 1xxx CPU withx86-64,MMX,SSE,SSE2,SSE3andSSSE3instruction set support. (No scheduling is implemented for this chip.) 🫶nano-2000— 🧚 the VIA Nano 2xxx CPU withx86-64,MMX,SSE,SSE2,SSE3andSSSE3instruction set support. (No scheduling is implemented for this chip.) 💖nano-3000— ⭐ the VIA Nano 3xxx CPU withx86-64,MMX,SSE,SSE2,SSE3,SSSE3andSSE4.1instruction set support. (No scheduling is implemented for this chip.) 👑nano-x2— 🌸 the VIA Nano Dual Core CPU withx86-64,MMX,SSE,SSE2,SSE3,SSSE3andSSE4.1instruction set support. (No scheduling is implemented for this chip.) 💜nano-x4— 🍓 the VIA Nano Quad Core CPU withx86-64,MMX,SSE,SSE2,SSE3,SSSE3andSSE4.1instruction set support. (No scheduling is implemented for this chip.) 🎀lujiazui— 🌈 the ZHAOXIN lujiazui CPU withx86-64,MOVBE,MMX,SSE,SSE2,SSE3,SSSE3,SSE4.1,SSE4.2,AVX,POPCNT,AES,PCLMUL,RDRND,XSAVE,XSAVEOPT,FSGSBASE,CX16,ABM,BMI,BMI2,F16C,FXSR,RDSEEDinstruction set support. 🫶✨yongfeng— okay this one is a ZHAOXIN yongfeng CPU 💖 It supports thex86-64, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, POPCNT, AES, PCLMUL, RDRND, XSAVE, XSAVEOPT, FSGSBASE, CX16, ABM, BMI, BMI2, F16C, FXSR, RDSEED, AVX2, FMA, SHA, LZCNTinstruction sets, so it's giving full loadout ✨geode— AMD Geode embedded processor withMMXand3DNow!instruction set support 🌸
🎀 -mtune=cpu-type
-mtune=cpu-type— tune everything applicable in the generated code to cpu-type, but leave the ABI and the set of available instructions alone 🦋 Picking a specific cpu-type schedules things properly for that exact chip. The compiler still won't generate code that can't run on the default machine type, unless you also use a-march=cpu-typeoption. For example, if GCC is configured fori686-pc-linux-gnu, then-mtune=pentium4gives you code tuned for Pentium 4 that still runs on i686 machines. Slay 💅
The choices for cpu-type are the same as for -march. On top of that, -mtune has 2 extra choices:
generic— produces code optimized for the most common IA32/AMD64/EM64T processors 🌈 If you know the CPU your code will run on, use the matching-mtuneor-marchoption instead of-mtune=generic. But if you have no idea what CPU your users will have, this is the one to pick.- As new processors hit the market, this option's behavior changes. So if you upgrade to a newer GCC, the code generation controlled by this option shifts to match whichever processors are most common when that GCC version gets released 🍓
- There's no
-march=genericbecause-marchis about the instruction set the compiler can use, and there's no generic instruction set that works on every processor.-mtune, on the other hand, is about the processor (or, in this case, the collection of processors) the code is optimized for.
intel— produces code optimized for the most current Intel processors, which for this version of GCC are Haswell and Silvermont 🧚 If you know the CPU your code will run on, use the matching-mtuneor-marchoption instead of-mtune=intel. But if you want your app to perform well on both Haswell and Silvermont, this is your option.- As new Intel processors get deployed, this option's behavior changes. So if you upgrade GCC, the code generation controlled by it will reflect the most current Intel processors at the time that GCC version is released 👑
- There's no
-march=inteloption because-marchis about the instruction set the compiler can use, and there's no common instruction set that works on all processors.-mtuneis about the processor (or collection of processors) the code is optimized for.
-mcpu=cpu-type— a deprecated synonym for-mtune💀 Old habit, new vibes, so maybe switch to-mtune.
🌸 -mfpmath=unit
-mfpmath=unit— generates floating-point arithmetic for the selected unit ✨ The choices for unit are:387— uses the standard 387 floating-point coprocessor, which is on the majority of chips and emulated on the rest 🫶 Code compiled this way runs almost everywhere. The temporary results are computed in 80-bit precision instead of the precision the type specifies, so you can get slightly different results compared to most other chips. Check-ffloat-storefor the more detailed rundown.- This is the default choice for non-Darwin x86-32 targets 💜
sse— uses scalar floating-point instructions from the SSE instruction set 🔥 This set is supported by Pentium III and newer chips, and on the AMD side by Athlon-4, Athlon XP and Athlon MP chips. The earlier version of the SSE instruction set only does single-precision arithmetic, so double and extended-precision arithmetic still go through 387. A later version, found only in Pentium 4 and AMD x86-64 chips, supports double-precision arithmetic too.- For the x86-32 compiler, you must use
-march=cpu-type,-msseor-msse2switches to enable SSE extensions and make this option work. For the x86-64 compiler, these extensions are enabled by default 🌈 - The resulting code should be considerably faster in most cases and avoid the numerical instability problems of 387 code. Heads up though: it may break some existing code that expects temporaries to be 80 bits 😭
- This is the default choice for the x86-64 compiler and Darwin x86-32 targets. It's also the default choice for x86-32 targets with the SSE2 instruction set when
-ffast-mathis enabled 👑
- For the x86-32 compiler, you must use
sse,387,sse+387,both— these try to use both instruction sets at once 🦋 That effectively doubles the amount of available registers and, on chips with separate execution units for 387 and SSE, the execution resources too. Use this one with care, because it's still experimental. The GCC register allocator doesn't model separate functional units well, which can lead to unstable performance 💀
🧁 Assembly, IEEE, and 80387 vibes
-masm=dialect— outputs assembly instructions in the selected dialect, and also decides which dialect is used for basicasmand extendedasm💅 Supported choices (in dialect order) areattorintel. The default isatt. Darwin doesn't supportintel🙈-mieee-fp,-mno-ieee-fp— control whether or not the compiler uses IEEE floating-point comparisons 🍓 These handle the case where the result of a comparison is unordered correctly.-m80387,-mhard-float— generate output containing 80387 instructions for floating point ⭐-mno-80387,-msoft-float— generate output that uses library calls for floating point instead 🌸
Warning: the requisite libraries are NOT part of GCC, bestie 😭 Normally the facilities of the machine's usual C compiler get used, but that can't be done directly in cross-compilation. You have to make your own arrangements to provide suitable library functions for cross-compilation.
On machines where a function returns floating-point results in the 80387 register stack, some floating-point opcodes may still get emitted even if -msoft-float is used. Plot twist 🙈
-mno-fp-ret-in-387— don't use the FPU registers for return values of functions 🦋 The usual calling convention has functions returnfloatanddoublevalues in an FPU register, even when there's no FPU. The idea is that the operating system should emulate an FPU. Using-mno-fp-ret-in-387makes those values come back in ordinary CPU registers instead 🧚-mno-fancy-math-387— some 387 emulators don't support thesin,cosandsqrtinstructions for the 387, so this option tells GCC to avoid generating those instructions 🫶 It gets overridden when-marchsays the target CPU always has an FPU, since then the instruction doesn't need emulation. These instructions also aren't generated unless you use the-funsafe-math-optimizationsswitch too.
🎀 Alignment and long double drama
-malign-double,-mno-align-double— control whether GCC alignsdouble,long double, andlong longvariables on a two-word boundary or a one-word boundary 💖 Aligningdoublevariables on a two-word boundary gives code that runs somewhat faster on a Pentium, at the expense of more memory. On x86-64,-malign-doubleis enabled by default ✨
Warning: if you use -malign-double, structures containing the above types get aligned differently than the published application binary interface specs for x86-32. They won't be binary compatible with structures in code compiled without that switch 💀
-m96bit-long-double,-m128bit-long-double— these control the size of thelong doubletype 🌈 The x86-32 application binary interface specifies the size as 96 bits, so-m96bit-long-doubleis the default in 32-bit mode.- Modern architectures (Pentium and newer) prefer
long doubleto be aligned to an 8- or 16-byte boundary. In arrays or structures that conform to the ABI, that isn't possible. So-m128bit-long-doublealignslong doubleto a 16-byte boundary by padding it with an additional 32-bit zero 🍓 - In the x86-64 compiler,
-m128bit-long-doubleis the default, since its ABI sayslong doubleis aligned on a 16-byte boundary 👑 - Heads up: neither of these options gives you any extra precision over the x87 standard of 80 bits for a
long double🙈
- Modern architectures (Pentium and newer) prefer
Warning: if you override the default value for your target ABI, this changes the size of structures and arrays containinglong doublevariables. It also modifies the function calling convention for functions takinglong double. So they aren't binary-compatible with code compiled without that switch 😭
-mlong-double-64,-mlong-double-80,-mlong-double-128— these also control the size of thelong doubletype 💜 A size of 64 bits makeslong doubleequivalent todouble. That's the default for the 32-bit Bionic C library. A size of 128 bits makeslong doubleequivalent to__float128, which is the default for the 64-bit Bionic C library 🔥
Warning: if you override the default value for your target ABI, this changes the size of structures and arrays containinglong doublevariables. It also modifies the function calling convention for functions takinglong double. So they aren't binary-compatible with code compiled without that switch 💀
-malign-data=type— controls how GCC aligns variables 🧁 The supported values for type are:compat— uses an increased alignment value that's compatible with GCC 4.8 and earlier 🌸 This is the default.abi— uses the alignment value specified by the psABI 🦋cacheline— uses an increased alignment value to match the cache line size ✨
-mlarge-data-threshold=threshold— when-mcmodel=mediumor-mcmodel=largeis specified, data objects larger than threshold get placed in large data sections 🫶 The default is65535💅-mrtd— okay bestie, this one switches to a whole different function-calling convention 💅 Functions with a fixed number of arguments return using theret numinstruction, which pops their arguments on the way out ✨ That saves the caller one instruction, since it doesn't have to pop them itself 🧚
You can make one specific function use this calling sequence with the function attribute "stdcall" 🎀 And if -mrtd is on but you want a function to go back to normal, the function attribute "cdecl" overrides it 🫶
⚠️ Warning: this calling convention is incompatible with the one normally used on Unix, so don't use it if you need to call libraries compiled with the Unix compiler 💀
You also must provide function prototypes for all functions that take variable numbers of arguments (including printf), or incorrect code gets generated for calls to those functions 😭
And honestly, seriously incorrect code results if you call a function with too many arguments 🙈 Normally the extra arguments are just harmlessly ignored, but not here.
-mregparm=num— controls how many registers get used to pass integer arguments 👑 By default no registers are used for this, and at most 3 registers can be used. You can control this for a specific function with the function attributeregparm🌸
Warning: if you use this switch and num is nonzero, then you must build all modules with the same value, including any libraries. That includes the system libraries and startup modules too 😭
-msseregparm— uses SSE register passing conventions for float and double arguments and return values 🦋 You can control this for a specific function with the function attributesseregparm.
Warning: same energy here. If you use this switch, you must build all modules with the same value, including any libraries, the system libraries and startup modules 🫠
-mvect8-ret-in-mem— returns 8-byte vectors in memory instead of MMX registers 🍓 This is the default on VxWorks, so it matches the ABI of the Sun Studio compilers until version 12. Only use this if you need to stay compatible with existing code made by those older compiler versions or older versions of GCC 🧸-mpc32,-mpc64,-mpc80— set the 80387 floating-point precision to 32, 64 or 80 bits 🔥 With-mpc32, the significands of floating-point results get rounded to 24 bits (single precision).-mpc64rounds them to 53 bits (double precision), and-mpc80rounds them to 64 bits (extended double precision), which is the default. When you use this option, higher-precision floating-point operations aren't available to the programmer unless you set the FPU control word explicitly.
Dropping the rounding below the default 80 bits can speed some programs up by 2% or more ⚡ But ngl, some mathematical libraries assume extended-precision (80-bit) floating-point operations are enabled by default. Routines in those libraries could lose a ton of accuracy, typically through so-called "catastrophic cancellation" 💀 when this option sets the precision below extended precision.
-mdaz-ftz— the flush-to-zero (FTZ) and denormals-are-zero (DAZ) flags in the MXCSR register control floating-point calculations 🌈 SSE and AVX instructions, including scalar and vector ones, could benefit from turning on FTZ and DAZ when you specify-mdaz-ftz. Just know that FTZ/DAZ won't get set when-mno-daz-ftzor-sharedis specified, except that-mdaz-ftzwill set them even with-shared. Plot twist 🙃-mstackrealign— realigns the stack at entry 🧚 On the x86, this generates an alternate prologue and epilogue that realigns the run-time stack if necessary. It lets legacy code that keeps 4-byte stack alignment mix with modern code that keeps 16-byte stack alignment for SSE compatibility 🫶 See also the attributeforce_align_arg_pointer, which applies to individual functions.-mpreferred-stack-boundary=num— tries to keep the stack boundary aligned to a 2 raised to num byte boundary 📐 If you don't specify-mpreferred-stack-boundary, the default is 4 (16 bytes or 128 bits).
Warning: when generating code for the x86-64 architecture with SSE extensions disabled,-mpreferred-stack-boundary=3can keep the stack boundary aligned to an 8 byte boundary. But the x86-64 ABI requires 16 byte stack alignment, so this is ABI incompatible and only meant for a controlled environment where stack space is a seriously important limitation 🚨 This option leads to wrong code when functions compiled with 16 byte stack alignment (like functions from a standard library) get called with a misaligned stack. In that case, SSE instructions may lead to misaligned memory access traps. Variable arguments also get handled incorrectly for 16 byte aligned objects (including x87long doubleand__int128), which leads to wrong results. You must build all modules with-mpreferred-stack-boundary=3, including any libraries, the system libraries and startup modules.
-mincoming-stack-boundary=num— assumes the incoming stack is aligned to a 2 raised to num byte boundary 🛬 If you don't specify-mincoming-stack-boundary, the one specified by-mpreferred-stack-boundaryis used.
On Pentium and Pentium Pro, double and long double values should be aligned to an 8-byte boundary (see -malign-double), or you'll take significant run time performance penalties 🐌 On Pentium III, the SSE data type __m128 may not work properly if it isn't 16-byte aligned.
To make sure these values are aligned on the stack, the stack boundary has to be as aligned as whatever value needs the most alignment on the stack. Every function also has to be generated so it keeps the stack aligned. So calling a function compiled with a higher preferred stack boundary from a function compiled with a lower one most likely misaligns the stack 😵💫 It's recommended that libraries that use callbacks always use the default setting 💖
This extra alignment does eat extra stack space and generally increases code size. If your code is sensitive to stack usage, like embedded systems and operating system kernels, you may want to reduce the preferred alignment to -mpreferred-stack-boundary=2 🧠
-mmmx,-msse,-msse2,-msse3,-mssse3,-msse4,-msse4a,-msse4.1,-msse4.2,-mavx,-mavx2,-mavx512f,-mavx512pf,-mavx512er,-mavx512cd,-mavx512vl,-mavx512bw,-mavx512dq,-mavx512ifma,-mavx512vbmi,-msha,-maes,-mpclmul,-mclflushopt,-mclwb,-mfsgsbase,-mptwrite,-mrdrnd,-mf16c,-mfma,-mpconfig,-mwbnoinvd,-mfma4,-mprfchw,-mrdpid,-mprefetchwt1,-mrdseed,-msgx,-mxop,-mlwp,-m3dnow,-m3dnowa,-mpopcnt,-mabm,-madx,-mbmi,-mbmi2,-mlzcnt,-mfxsr,-mxsave,-mxsaveopt,-mxsavec,-mxsaves,-mrtm,-mhle,-mtbm,-mmwaitx,-mclzero,-mpku,-mavx512vbmi2,-mavx512bf16,-mavx512fp16,-mgfni,-mvaes,-mwaitpkg,-mvpclmulqdq,-mavx512bitalg,-mmovdiri,-mmovdir64b,-menqcmd,-muintr,-mtsxldtrk,-mavx512vpopcntdq,-mavx512vp2intersect,-mavx5124fmaps,-mavx512vnni,-mavxvnni,-mavx5124vnniw,-mcldemote,-mserialize,-mamx-tile,-mamx-int8,-mamx-bf16,-mhreset,-mkl,-mwidekl,-mavxifma,-mavxvnniint8,-mavxneconvert,-mcmpccxadd,-mamx-fp16,-mprefetchi,-mraoint,-mamx-complex,-mavxvnniint16,-msm3,-msha512,-msm4,-mapxf,-musermsr,-mavx10.1,-mavx10.1-256,-mavx10.1-512— these switches turn on the instruction sets for MMX, SSE, AVX512ER, AVX512CD, AVX512VL, AVX512BW, AVX512DQ, AVX512IFMA, AVX512VBMI, SHA, AES, PCLMUL, CLFLUSHOPT, CLWB, FSGSBASE, PTWRITE, RDRND, F16C, FMA, PCONFIG, WBNOINVD, FMA4, PREFETCHW, RDPID, PREFETCHWT1, RDSEED, SGX, XOP, LWP, 3DNow!, enhanced 3DNow!, POPCNT, ABM, ADX, BMI, BMI2, LZCNT, FXSR, XSAVE, XSAVEOPT, XSAVEC, XSAVES, RTM, HLE, TBM, MWAITX, CLZERO, PKU, AVX512VBMI2, GFNI, VAES, WAITPKG, VPCLMULQDQ, AVX512BITALG, MOVDIRI, MOVDIR64B, AVX512BF16, ENQCMD, AVX512VPOPCNTDQ, AVX5124FMAPS, AVX512VNNI, AVX5124VNNIW, SERIALIZE, UINTR, HRESET, AMXTILE, AMXINT8, AMXBF16, KL, WIDEKL, AVXVNNI, AVX512-FP16, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AMX-FP16, PREFETCHI, RAOINT, AMX-COMPLEX, AVXVNNIINT16, SM3, SHA512, SM4, APX_F, USER_MSR, AVX10.1 or CLDEMOTE extended instruction sets 🌟 Each one has a matching-mno-option to turn that instruction use back off 🙅♀️
These extensions are also available as built-in functions, so check out x86 Built-in Functions to see which functions get enabled and disabled by these switches 🧩
If you want SSE/SSE2 instructions generated automatically from floating-point code (instead of 387 instructions), look at -mfpmath=sse 💜
GCC basically ghosts the SSEx instructions when -mavx is used. Instead, it generates new AVX instructions, or AVX equivalents for all the SSEx instructions, when needed ✨
These options let GCC use these extended instructions in generated code, even without -mfpmath=sse. If your app does run-time CPU detection, you have to compile separate files for each supported architecture using the right flags 🫠 In particular, the file with the CPU detection code should be compiled without these options.
-mdump-tune-features— tells GCC to dump the names of the x86 performance tuning features and their default settings 📜 You can use those names in-mtune-ctrl=feature-list🎀-mtune-ctrl=feature-list— okay so this is the fine-grain dial for x86 code generation features 🎛️✨ You pass in a comma separated list of feature names. A feature gets turned on when it's written plainly, but if you put a^in front of it, it gets turned off 🙅♀️ Also check out-mdump-tune-featureswhile you're at it 🔍
⚠️ BESTIE, READ THIS ⚠️ -mtune-ctrl=feature-list is intended for GCC developers only 🧑💻 Using it may lead to code paths that never got covered by testing, and it can potentially result in compiler ICEs or runtime errors 💀
-mno-default— this one turns off ALL the tunable features in one go 🧹 See also-mtune-ctrl=feature-listand-mdump-tune-features.-mcld— okay this one's a whole story 🚨 GCC emits acldinstruction in the prologue of functions that use string instructions. String instructions rely on the DF flag to decide between autoincrement and autodecrement mode. The ABI says DF gets cleared on function entry, but some operating systems don't clear it in their exception dispatchers 😭 So the exception handler can run with DF set, and then string instructions go in the wrong direction. This option can be turned on by default for 32-bit x86 targets by configuring GCC with the--enable-cldconfigure option 🎀 In that case, you can suppress generation ofcldinstructions with the-mno-cldcompiler option.-mvzeroupper— this instructs GCC to emit avzeroupperinstruction before control flow leaves the function 🦋 It's there to cut down the AVX to SSE transition penalty, and it also removes unnecessaryzeroupperintrinsics 🧹-mprefer-avx128— this tells the auto-vectorizer to use 128-bit AVX instructions instead of 256-bit AVX instructions 💜-mprefer-vector-width=opt— this one makes GCC useopt-bit vector width in instructions instead of the default for the selected platform 🌈-mpartial-vector-fp-math— this lets GCC generate floating-point operations that might affect the floating-point status flags on partial vectors 🧠 (those are the ones where vector elements live in the low part of the 128-bit SSE register). Unless-fno-trapping-mathis specified, the compiler keeps things correct by sanitizing all input operands so there are zeroes in the unused upper part of the vector register ✨ Heads up though: if you use built-in functions or inline assembly with partial vector arguments, NaNs, denormal or invalid values can leak into the upper part of the vector 🙈 That can cause performance issues when-fno-trapping-mathis in effect. These issues can be mitigated by manually sanitizing the upper part of the partial vector argument register, or by using-mdaz-ftzto set the denormals-are-zero (DAZ) flag in the MXCSR register 🫶 This option is enabled by default ✅-mmove-max=bits— sets the maximum number of bits that can be moved from memory to memory efficiently 📦 tobits. The valid values are128,256and512.-mstore-max=bits— same energy, but for storing: this sets the maximum number of bits that can be stored to memory efficiently tobits💾 The valid values are128,256and512.- Here's the rundown on the possible values 📋:
none— no extra limitations applied to GCC other than what's defined by the selected platform.128— prefer 128-bit vector width for instructions.256— prefer 256-bit vector width for instructions.512— prefer 512-bit vector width for instructions.
-mnoreturn-no-callee-saved-registers— this optimizes functions with thenoreturnattribute or the_Noreturnspecifier 🪦 by not saving callee-saved registers in the function prologue, as long as the function uses them (except for theBPregister). Just know it can interfere with debugging the caller of thenoreturnfunction, or any function further up in the call stack 🙃 so it is not enabled by default.-mcx16— this lets GCC generateCMPXCHG16Binstructions in 64-bit code 💜 to implement compare-and-exchange operations on 16-byte aligned 128-bit objects. It's super useful for atomic updates of data structures that are bigger than one machine word 🫧 GCC uses this instruction to implement__syncBuiltins. For__atomicBuiltins operating on 128-bit integers, though, a library call is always used 📞-msahf— this enables generation ofSAHFinstructions in 64-bit code 🧪 History tea: early Intel Pentium 4 CPUs with Intel 64 support, before the Pentium 4 G1 step in December 2005, didn't have theLAHFandSAHFinstructions that AMD64 supports 🙈 These are load and store instructions, respectively, for certain status flags. In 64-bit mode, theSAHFinstruction is used to optimize thefmod,drem, andremainderbuilt-in functions; see Other Builtins for details 🔍-mmovbe— enables use of themovbeinstruction to optimize byte swapping of four and eight byte entities 🔄-mshstk— this one enables shadow stack built-in functions from x86 Control-flow Enforcement Technology (CET) 🛡️-mcrc32— this enables the built-in functions__builtin_ia32_crc32qi,__builtin_ia32_crc32hi,__builtin_ia32_crc32siand__builtin_ia32_crc32dito generate thecrc32machine instruction 🔢-mmwait— this enables the built-in functions__builtin_ia32_monitorand__builtin_ia32_mwaitto generate themonitorandmwaitmachine instructions ⏳-mrecip— this enablesRCPSSandRSQRTSS(plus their vectorized buddiesRCPPSandRSQRTPS) 🧮 with an extra Newton-Raphson step to boost precision. They get used instead ofDIVSSandSQRTSS(and their vectorized variants) for single-precision floating-point arguments. These instructions are only generated when-funsafe-math-optimizationsis enabled together with-ffinite-math-onlyand-fno-trapping-math. Warning, bestie 🙈 while the throughput of the sequence is higher than the non-reciprocal instruction, the precision can drop by up to 2 ulp (i.e. the inverse of 1.0 equals0.99999994).
💡 Note that GCC implements 1.0f/sqrtf(x) in terms of RSQRTSS (or RSQRTPS) already with -ffast-math (or the above option combination), so it doesn't need -mrecip.
💡 Also, GCC emits the above sequence with the additional Newton-Raphson step for vectorized single-float division and vectorized sqrtf(x) already with -ffast-math (or the above option combination), so it doesn't need -mrecip either.
-mrecip=opt— this controls which reciprocal estimate instructions are allowed to be used 🎯optis a comma-separated list of options, and any option can be preceded by a!to invert it:all— enable all estimate instructions.default— enable the default instructions, equivalent to-mrecip.none— disable all estimate instructions, equivalent to-mno-recip.div— enable the approximation for scalar division.vec-div— enable the approximation for vectorized division.sqrt— enable the approximation for scalar square root.vec-sqrt— enable the approximation for vectorized square root.
So, for example, -mrecip=all,!sqrt enables all of the reciprocal approximations, except for square root ✨
-mveclibabi=type— this specifies the ABI type to use when vectorizing intrinsics with an external library 📚 Fortype, the supported values aresvmlfor the Intel short vector math library andacmlfor the AMD math core library. To use it, both-ftree-vectorizeand-funsafe-math-optimizationshave to be enabled, and an SVML or ACML ABI-compatible library must be specified at link time 🔗
GCC currently emits calls to vmldExp2, vmldLn2, vmldLog102, vmldPow2, vmldTanh2, vmldTan2, vmldAtan2, vmldAtanh2, vmldCbrt2, vmldSinh2, vmldSin2, vmldAsinh2, vmldAsin2, vmldCosh2, vmldCos2, vmldAcosh2, vmldAcos2, vmlsExp4, vmlsLn4, vmlsLog104, vmlsPow4, vmlsTanh4, vmlsTan4, vmlsAtan4, vmlsAtanh4, vmlsCbrt4, vmlsSinh4, vmlsSin4, vmlsAsinh4, vmlsAsin4, vmlsCosh4, vmlsCos4, vmlsAcosh4 and vmlsAcos4 for the corresponding function type when -mveclibabi=svml is used 🌸 It also emits calls to __vrd2_sin, __vrd2_cos, __vrd2_exp, __vrd2_log, __vrd2_log2, __vrd2_log10, __vrs4_sinf, __vrs4_cosf, __vrs4_expf, __vrs4_logf, __vrs4_log2f, __vrs4_log10f and __vrs4_powf for the corresponding function type when -mveclibabi=acml is used 🦋
-mabi=name— this generates code for the specified calling convention 📜 Permissible values aresysvfor the ABI used on GNU/Linux and other systems, andmsfor the Microsoft ABI. The default is the Microsoft ABI when targeting Microsoft Windows, and the SysV ABI on all other systems. You can control this for specific functions with the function attributesms_abiandsysv_abi🎀-mforce-indirect-call— this forces all calls to functions to be indirect 🔁 It's handy when you're using Intel Processor Trace, since that gives more precise timing information for function calls ⏱️-mmanual-endbr— this inserts anENDBRinstruction at function entry only via thecf_checkfunction attribute 🚪 It's useful when you pair it with-fcf-protection=branch, so you can controlENDBRinsertion at the function entry 🧚-mcet-switch— by default, CET instrumentation is turned off on switch statements that use a jump table, and indirect branch track is disabled 🔀 Since jump tables live in read-only memory, this doesn't cause a direct loss of hardening. But if the jump table index is attacker-controlled, the indirect jump may not be constrained by CET 😱 This option turns CET instrumentation on, so indirect branch track is enabled for switch statements with jump tables, which leads to the jump targets being reachable via any indirect jumps 🛡️💖-mcall-ms2sysv-xlogues— okay so 64-bit ABIs don't agree on everything, which means any Microsoft ABI function that calls a System V ABI function has to treatRSI,RDIandXMM6-15as clobbered 💀. By default the code that saves and restores those registers gets dumped inline, making prologues and epilogues pretty lengthy. Turn this on and they use stubs in the static portion oflibgccinstead, so your functions get smaller 📉 for the price of a few extra instructions ✨-mtls-dialect=type— generates thread-local storage access code using thegnuorgnu2conventions.gnuis the conservative default 🛡️, whilegnu2is more efficient 🚀 but may add compile- and run-time requirements that can't be satisfied on every system 😬-mpush-args,-mno-push-args— uses PUSH operations to store outgoing parameters 📦. It's shorter and usually just as fast as the SUB/MOV method, and it's on by default. Sometimes turning it off actually helps performance thanks to better scheduling and fewer dependencies 🧚-maccumulate-outgoing-args— if enabled, the maximum space needed for outgoing arguments gets computed in the function prologue 🧮. This is faster on most modern CPUs because of reduced dependencies, improved scheduling and reduced stack usage when the preferred stack boundary isn't equal to 2. The catch is a notable jump in code size 📈. This switch implies-mno-push-args🫶-mthreads— supports thread-safe exception handling on MinGW 🧵. Programs that rely on it have to compile and link all their code with-mthreads. When compiling, it defines-D_MT, and when linking, it pulls in the special thread helper library-lmingwthrd, which cleans up per-thread exception-handling data 🧹-mms-bitfields,-mno-ms-bitfields— turns bit-field layout that's compatible with the native Microsoft Windows compiler on or off 🎀
If packed is used on a structure, or if bit-fields are used, the Microsoft ABI might lay the structure out differently from how GCC normally does it 👀. This gets especially messy when you're moving packed data between GCC-compiled functions and the native Microsoft compiler, whether through a function call or as data in a file, so you may need to access either format 💅
This option is enabled by default for Microsoft Windows targets 🪟. You can also control this locally with variable or type attributes. For more information, check out x86 Variable Attributes and x86 Type Attributes 🦋
The Microsoft structure layout algorithm is pretty simple, except for the bit-field packing 🤓. The padding and alignment of structure members, and whether a bit-field can straddle a storage-unit boundary, are determined by these rules:
- Structure members are stored sequentially in the order they're declared. The first member has the lowest memory address and the last member has the highest.
- Every data object has an alignment requirement. For everything except structures, unions, and arrays, that requirement is either the size of the object or the current packing size (set with the
alignedattribute or thepackpragma), whichever is less. For structures, unions, and arrays, the alignment requirement is the largest alignment requirement of any of its members. Every object gets an offset so that:
offset % alignment_requirement == 0- Adjacent bit-fields get packed into the same 1-, 2-, or 4-byte allocation unit if the integral types are the same size, and the next bit-field fits into the current allocation unit without crossing the boundary set by the bit-fields' common alignment requirements 🧩
MSVC interprets zero-length bit-fields in the following ways 🙈:
- If a zero-length bit-field is inserted between two bit-fields that would normally be coalesced, the bit-fields are not coalesced.
For example:
struct
{
unsigned long bf_1 : 12;
unsigned long : 0;
unsigned long bf_2 : 12;
} t1;The size of t1 is 8 bytes with the zero-length bit-field. If the zero-length bit-field were removed, t1's size would be 4 bytes 💀
- If a zero-length bit-field is inserted after a bit-field,
foo, and the alignment of the zero-length bit-field is greater than that of the member that follows it,bar, thenbaris aligned as the type of the zero-length bit-field 🌈
For example:
struct
{
char foo : 4;
short : 0;
char bar;
} t2;
struct
{
char foo : 4;
short : 0;
double bar;
} t3;For t2, bar is placed at offset 2 instead of offset 1, so the size of t2 is 4. For t3, the zero-length bit-field doesn't affect the alignment of bar or, as a result, the size of the structure ✨
Taking this into account, it's important to note the following:
- If a zero-length bit-field follows a normal bit-field, the type of the zero-length bit-field may affect the alignment of the structure as a whole. For example,
t2has a size of 4 bytes, since the zero-length bit-field follows a normal bit-field and is of typeshort🎯 - Even if a zero-length bit-field isn't followed by a normal bit-field, it may still affect the alignment of the structure:
struct
{
char foo : 6;
long : 0;
} t4;Here, t4 takes up 4 bytes 🧠
- Zero-length bit-fields that follow non-bit-field members are ignored:
struct
{
char foo;
long : 0;
char bar;
} t5;Here, t5 takes up 2 bytes 🌸
-mno-align-stringops— doesn't align the destination of inlined string operations 🫧. This shrinks code size and speeds things up when the destination is already aligned but GCC doesn't know it-minline-all-stringops— by default GCC only inlines string operations when the destination is known to be aligned to at least a 4-byte boundary 📏. This option allows more inlining 🔥 and increases code size, but it may boost performance for code that depends on fastmemcpyandmemseton short lengths. It also enables inline expansion ofstrlenfor all pointer alignments 💜-minline-stringops-dynamically— for string operations of unknown size, it uses run-time checks with inline code for small blocks and a library call for large blocks 🧚♀️-mstringop-strategy=alg— overrides GCC's internal decision heuristic for which algorithm gets used to inline string operations 🎛️. The allowed values foralgare:rep_byte,rep_4byte,rep_8byte— expand using the i386repprefix of the specified size 🔁byte_loop,loop,unrolled_loop— expand into an inline loop 🌀libcall— always use a library call 📞
-mmemcpy-strategy=strategy— overrides the internal heuristic that decides whether__builtin_memcpyshould be inlined and which inline algorithm to use when the expected size of the copy is known 🪄.strategyis a comma-separated list ofalg:max_size:dest_aligntriplets.algis specified in-mstringop-strategy, andmax_sizeis the max byte size that the inline algorithmalgis allowed to handle. For the last triplet,max_sizemust be-1. Themax_sizevalues in the list must be given in increasing order. The minimal byte size foralgis 0 for the first triplet, andmax_size + 1of the preceding range for every triplet after that 📐-mmemset-strategy=strategy— pretty much the same as-mmemcpy-strategy=except it controls__builtin_memsetexpansion 🧸-momit-leaf-frame-pointer— stops keeping the frame pointer in a register for leaf functions 🍃. This skips the instructions for saving, setting up and restoring frame pointers, and frees up an extra register in leaf functions. The option-fomit-leaf-frame-pointerdrops the frame pointer for leaf functions too, but that might make debugging harder 🐛-mtls-direct-seg-refs,-mno-tls-direct-seg-refs— controls whether TLS variables can be accessed with offsets from the TLS segment register (%gsfor 32-bit,%fsfor 64-bit), or whether the thread base pointer has to be added 🧵. Whether that's valid depends on the operating system and on whether it maps the segment to cover the entire TLS area 🗺️. For systems that use the GNU C Library, the default is on ✅-msse2avx,-mno-sse2avx— tells the assembler to encode SSE instructions with a VEX prefix 🌊. The option-mavxturns this on by default 💫-mfentry,-mno-fentry— if profiling is active (-pg), puts the profiling counter call before the prologue 📊. Heads up: on x86 architectures the attribute"ms_hook_prologue"isn't possible at the moment for-mfentryand-pg⚠️-mrecord-mcount,-mno-record-mcount— if profiling is active (-pg), generates a__mcount_locsection that holds pointers to each profiling call 🗂️. This is handy for automatically patching calls in and out 🩹-mnop-mcount,-mno-nop-mcount— if profiling is active (-pg), generates the calls to the profiling functions as NOPs 😴. This is useful when they should be patched in later, dynamically. It's likely only useful together with-mrecord-mcount🫶-minstrument-return=type— instruments function exit in-pg -mfentryinstrumented functions by calling the specified function 🚪. This only instruments true returns that end withret, not sibling calls that end with a jump. Valid types arenoneto not instrument,callto generate a call to__return__, ornop5to generate a 5-byte NOP 🌟
okay so this part is a whole buffet of -m switches, and we're going through every single one 💅🎀
-mrecord-return,-mno-record-return— this one makes a__return_locsection that points at all the return instrumentation code 🧚-mfentry-name=name— picks the name of the__fentry__symbol that gets called at function entry for-pg-mfentryfunctions ✨-mfentry-section=name— sets the section name where-mrecord-mcountcalls get recorded. The default is__mcount_loc🌸-mskip-rax-setup,-mno-skip-rax-setup— bestie, this is for x86-64 code with SSE extensions turned off.-mskip-rax-setuplets you skip setting up the RAX register when no variable arguments get passed in vector registers 🦋
Warning: RAX is used to avoid saving vector registers on the stack for no reason when passing variable arguments, so the impacts here are that callees may waste some stack space, misbehave, or jump to a random location. GCC 4.4 or newer don't have those issues, regardless of the RAX register value 💀
-m8bit-idiv,-mno-8bit-idiv— on some processors like Intel Atom, 8-bit unsigned integer divide is way faster than 32-bit or 64-bit integer divide. This option adds a run-time check. If both the dividend and divisor are within 0 to 255, it uses 8-bit unsigned integer divide instead of 32-bit/64-bit integer divide 🔥-mavx256-split-unaligned-load,-mavx256-split-unaligned-store— splits 32-byte AVX unaligned loads and stores into smaller pieces 🫶-mstack-protector-guard=guard— generates stack protection code using a canary at the guard location. The supported locations areglobalfor a global canary ortlsfor a per-thread canary in the TLS block, andtlsis the default. This option only does something when-fstack-protectoror-fstack-protector-allis specified 👑-mstack-protector-guard-reg=reg,-mstack-protector-guard-offset=offset— with the latter choice of guard, these two decide which segment register (%fsor%gs) gets used as the base register for reading the canary, and what offset from that base it reads from. Their defaults are whatever the relevant ABI says 🌈-mgeneral-regs-only— only generates code that uses general-purpose registers. The compiler is blocked from touching floating-point, vector, mask, and bound registers 🍓-mrelax-cmpxchg-loop— when making a compare-and-swap loop for__syncBuiltins and__atomicBuiltins that don't have a native instruction, this optimizes for the super contended case. It issues an atomic load before the"CMPXCHG"instruction, and uses the"PAUSE"instruction to save CPU power when restarting the loop 💜-mindirect-branch=choice— converts indirect calls and jumps based on the choice. The default iskeep, which leaves indirect calls and jumps alone.thunkconverts them into call and return thunks.thunk-inlineconverts them into inlined call and return thunks.thunk-externconverts them into external call and return thunks that live in a separate object file. You can control this for a specific function with the function attribute"indirect_branch"🦋
Note:-mcmodel=largeis incompatible with-mindirect-branch=thunkand-mindirect-branch=thunk-extern, since the thunk function may not be reachable in the large code model 🙈
Note:-mindirect-branch=thunk-externis compatible with-fcf-protection=branch, since the external thunk can be made to enable control-flow check ✨
-mfunction-return=choice— converts function returns based on the choice. The default iskeep, which leaves function returns unmodified.thunkconverts them into call and return thunks.thunk-inlineconverts them into inlined call and return thunks.thunk-externconverts them into external call and return thunks in a separate object file. You can control this for a specific function with the function attribute"function_return"🌸
Note:-mindirect-return=thunk-externis compatible with-fcf-protection=branch, since the external thunk can be made to enable control-flow check 🫶
Note:-mcmodel=largeis incompatible with-mfunction-return=thunkand-mfunction-return=thunk-extern, since the thunk function may not be reachable in the large code model 💀
-mindirect-branch-register— forces indirect calls and jumps to go through a register 🧚-mharden-sls=choice— generates code to mitigate straight line speculation (SLS) based on the choice. The default isnone, which disables all SLS hardening.returnenables it for function returns,indirect-jmpenables it for indirect jumps, andallturns on all SLS hardening 🔥-mindirect-branch-cs-prefix— adds a CS prefix to call and jmp instructions going to an indirect thunk, where the branch target is in ther8-r15registers. This makes the call and jmp instruction length 6 bytes, so they can be swapped at run-time forlfence; call *%r8-r15orlfence; jmp *%r8-r15👑-mapx-inline-asm-use-gpr32— for inline asm support with APX, the EGPR feature is disabled by default to prevent a possible illegal instruction from EGPR showing up. To turn on EGPR usage in inline asm, use this option, and you need to make sure the instruction actually supports EGPR 🙈-mevex512,-mno-evex512— enables or disables 512-bit vectors. It's on by default if AVX512F is enabled 🌈
These -m switches are supported in addition to the above on x86-64 processors in 64-bit environments.
-m32,-m64,-mx32,-m16,-miamcu— generates code for a 16-bit, 32-bit, or 64-bit environment.-m32sets"int","long", and pointer types to 32 bits, and generates code that runs in 32-bit mode 🎀-m64sets"int"to 32 bits and"long"and pointer types to 64 bits, and generates code for the x86-64 architecture. For Darwin only,-m64also turns off the-fno-picand-mdynamic-no-picoptions 🍓-mx32sets"int","long", and pointer types to 32 bits, and generates code for the x86-64 architecture 🦋-m16is the same as-m32, except it outputs the".code16gcc"assembly directive at the start of the assembly output so the binary can run in 16-bit mode 💜-miamcugenerates code that conforms to the Intel MCU psABI. It requires-m32to be turned on ✨-mno-red-zone— don't use a so-called "red zone" for x86-64 code. The red zone is mandated by the x86-64 ABI. It's a 128-byte area beyond the stack pointer that signal or interrupt handlers don't modify, so it can be used for temporary data without adjusting the stack pointer. This flag disables that red zone 🌸-mcmodel=small— generates code for the small code model, where the program and its symbols must be linked in the lower 2 GB of the address space. Pointers are 64 bits. Programs can be statically or dynamically linked. This is the default code model 👑-mcmodel=kernel— generates code for the kernel code model. The kernel runs in the negative 2 GB of the address space. This model has to be used for Linux kernel code 🧚-mcmodel=medium— generates code for the medium model, where the program is linked in the lower 2 GB of the address space. Small symbols get placed there too. Symbols bigger than-mlarge-data-thresholdgo into large data or BSS sections and can live above 2GB. Programs can be statically or dynamically linked 🫶-mcmodel=large— generates code for the large model, which makes no assumptions about addresses and sizes of sections 🌈-maddress-mode=long— generates code for long address mode. This is only supported for 64-bit and x32 environments, and it's the default address mode for 64-bit environments 🔥-maddress-mode=short— generates code for short address mode. This is only supported for 32-bit and x32 environments, and it's the default address mode for 32-bit and x32 environments 🎀-mneeded,-mno-needed— emits theGNU_PROPERTY_X86_ISA_1_NEEDEDGNU property for Linux targets. This tells you the micro-architecture ISA level needed to run the binary 💅-mno-direct-extern-access— without-fpicor-fPIC, always uses the GOT pointer to access external symbols. With-fpicor-fPIC, access to protected symbols is treated as local symbols. The default is-mdirect-extern-access🍓
Warning: shared libraries compiled with-mno-direct-extern-accessand executables compiled with-mdirect-extern-accessmay not be binary compatible if protected symbols are used in shared libraries and executables 😭
-munroll-only-small-loops— controls conservative small loop unrolling. It's enabled by default withO2, and unrolls loops with fewer than 4 insns by 1 time. Explicitly using-f[no-]unroll-[all-]loopsturns this flag off, so you don't get any unrolling you didn't ask for 🦋-mlam=choice— LAM (linear-address masking) lets special bits in the pointer be used for metadata. The default isnone. Withu48, pointer bits in positions 62:48 can be used for metadata. Withu57, pointer bits in positions 62:57 can be used for metadata 💜
✨ x86 Windows Options ✨
These additional options are available for Microsoft Windows targets:
-mconsole— this option makes a console application, by telling the linker to set the PE header subsystem type that console applications need. It's available for Cygwin and MinGW targets and is enabled by default on those targets 🎀-mcrtdll=library: okay bestie, this one is a whole vibe 💅 It lets you preprocess, compile, or link with the C RunTime DLL library you pick. It adjusts the predefined macros__CRTDLL__,__MSVCRT__and__MSVCRT_VERSION__for that CRT, chooses its start file, and links it in 🎀. The names the preprocessor recognizes are"crtdll","msvcrt10","msvcrt20","msvcrt40","msvcrt-os","msvcr70","msvcr80","msvcr90","msvcr100","msvcr110","msvcr120"and"ucrt"✨. If you skip this flag, the default MinGW import librarymsvcrtgets linked and the preprocessor isn't touched at all 🙈. Thatmsvcrtimport library is just a symlink to (or a copy of) whichever MinGW CRT import library was picked when MinGW got compiled.msvcrt-osis the one for the Windows system CRT DLLmsvcrt.dll, and in most cases it's the default MinGW import library 👑.
Heads up, bestie: switching the CRT DLL usually means recompiling the entire MinGW CRT 💀. This option is strictly for experimental and testing purposes. It's available for MinGW targets.
-mdll: this one's for Cygwin and MinGW targets 🦋. It tells GCC to generate a DLL (a dynamic link library), which lets you pick the runtime startup object and entry point you need.-mnop-fun-dllimport: also for Cygwin and MinGW 🌸. It tells GCC to ignore thedllimportattribute. Bye, attribute 👋.-mthreads: MinGW only 🧵. It switches on MinGW-specific thread support.-municode: MinGW-w64 only 💜. It predefines theUNICODEpreprocessor macro and picks Unicode-capable runtime startup code, so your strings are giving full Unicode energy 🌈.-mwin32: Cygwin and MinGW 🍓. It sets up the typical Microsoft Windows predefined macros in the preprocessor, but it does not change which runtime library or startup code gets chosen.-mwindows: Cygwin and MinGW again 🪟. It makes a GUI application by telling the linker to set the PE header subsystem type to match.-fno-set-stack-executable: MinGW only 🔒. The executable flag doesn't get set on the stack that nested functions use. This is needed for binaries running in kernel mode of Microsoft Windows, since the User32 API (the thing used to set executable privileges) isn't available there.-fwritable-relocated-rdata: MinGW and Cygwin 🧚. Relocated data in a read-only section gets put into the".data"section. This is necessary for older runtimes that don't support modifying".rdata"sections for pseudo-relocation.-mpe-aligned-commons: Cygwin and MinGW 💖. It uses the GNU extension to the PE file format that lets COMMON variables be aligned correctly when code is generated. This is enabled by default if GCC detects that the target assembler found during configuration supports the feature.
See also under x86 Options for standard options. That's where the regular stuff lives, bestie 🫶.
✨ Xstormy16 Options ✨
These options are defined for Xstormy16 🌟.
-msim: pick startup files and a linker script that suit the simulator 🎮.
✨ Xtensa Options ✨
These options are supported for Xtensa targets 🦋.
-mconst16,-mno-const16: turn the use ofCONST16instructions for loading constant values on or off 🔛.CONST16isn't a standard Tensilica option right now. When it's enabled,CONST16instructions are always used in place of the standardL32Rinstructions. It's only on by default whenL32Risn't available 🙈.-mfused-madd,-mno-fused-madd: enable or disable fused multiply/add and multiply/subtract instructions in the floating-point option 🔥. This does nothing if the floating-point option isn't also on. Turning fused ops off makes the compiler use separate instructions for the multiply and the add/subtract. That can be the move when you need strict IEEE 754-compliant results 💅, since fused multiply add/subtract doesn't round the intermediate result, so it ends up with more bits of precision than the IEEE standard specifies. Turning them off also means your program output isn't affected by how well the compiler can combine multiply and add/subtract operations 🧠.-mserialize-volatile,-mno-serialize-volatile: when this is enabled, GCC insertsMEMWinstructions beforevolatilememory references to guarantee sequential consistency 🔐. The default is-mserialize-volatile. Use-mno-serialize-volatileif you want to leave out theMEMWinstructions.-mforce-no-pic: for targets like GNU/Linux, where all user-mode Xtensa code has to be position-independent code (PIC) 🧩, this disables PIC when compiling kernel code.-mtext-section-literals,-mno-text-section-literals: these control how literal pools are treated 🗂️. The default is-mno-text-section-literals, which puts literals in a separate section of the output file. That lets the literal pool live in data RAM/ROM, and it lets the linker merge literal pools from separate object files to kill redundant literals and shrink code size ✂️. With-mtext-section-literals, literals are interspersed in the text section so they sit as close as possible to where they're referenced 📍. This might be necessary for large assembly files. Literals for each function get placed right before that function.-mauto-litpools,-mno-auto-litpools: also about literal pools, bestie 🌊. The default is-mno-auto-litpools, which puts literals in a separate section of the output file unless-mtext-section-literalsis used. With-mauto-litpools, the assembler interweaves the literals into the text section itself. The compiler doesn't emit explicit.literaldirectives and loads literals into registers withMOVIinstead ofL32R, so the assembler can do relaxation and place literals wherever they need to go 🪄. This lets the assembler make several literal pools per function and assemble very big functions, which might not be possible with-mtext-section-literals.-mtarget-align,-mno-target-align: when enabled, GCC tells the assembler to automatically align instructions to cut down on branch penalties, even though you lose a bit of code density 🎯. The assembler tries to widen density instructions so branch targets and the instructions right after call instructions get aligned. If there aren't enough safe density instructions before a target to line it up, no widening happens. The default is-mtarget-align. These options don't change how auto-aligned instructions likeLOOPget treated, since the assembler always aligns those, either by widening density instructions or by insertingNOPinstructions 🙌.-mlongcalls,-mno-longcalls: when enabled, GCC tells the assembler to turn direct calls into indirect calls, unless it can tell the target of the direct call is within range of the call instruction 📞. This usually happens for calls to functions in other source files. Specifically, the assembler turns a directCALLinto anL32Rfollowed by aCALLX. The default is-mno-longcalls. Use this in programs where the call target could possibly be out of range 🚀. Fun fact, this option is implemented in the assembler, not the compiler, so the assembly GCC generates still shows direct call instructions. If you want to see what's actually running, look at the disassembled object code 🔍. The assembler uses an indirect call for every cross-file call, not just the ones that are really out of range.-mabi=name: generate code for the ABI you specify 📜. The permissible values arecall0andwindowed. The default ABI is chosen by the Xtensa core configuration.-mabi=call0: when this is enabled, function parameters get passed in registersa2througha7, registersa12througha15are caller-saved, and registera15may be used as a frame pointer 🌷. When this version of the ABI is on, the C preprocessor symbol"__XTENSA_CALL0_ABI__"is defined.-mabi=windowed: when this is enabled, function parameters get passed in registersa10througha15. The called function rotates the register window by 8 registers on entry, so its arguments show up in registersa2througha7🌀. Registera7may be used as a frame pointer. The register window gets rotated 8 registers back upon return. When this version of the ABI is on, the C preprocessor symbol"__XTENSA_WINDOWED_ABI__"is defined.-mextra-l32r-costs=n: specify an extra cost, in clock cycles, for instruction RAM/ROM access onL32Rinstructions 🐢. When you're optimizing for speed, this affects whether a constant gets loaded from the literal pool usingL32Ror built from a small one with a couple of arithmetic instructions. The default value is0.-mstrict-align,-mno-strict-align: this controls whether GCC avoids or allows generating memory accesses that might not be aligned on a natural object boundary, as described in the architecture specification 📐. The default is-mno-strict-alignfor cores that support both unaligned loads and stores in hardware, and-mstrict-alignfor all other cores.
✨ zSeries Options ✨
These are listed under
✨ ENVIRONMENT ✨
okay so this section is all about environment variables that change how GCC behaves 💅 Some of them point it at directories or prefixes to search for files, and others tweak the compilation setup itself 🌸
Note that you can also specify places to search using options such as -B, -I and -L 🧚 These take precedence over places set with environment variables, which in turn beat whatever GCC's configuration says 👑
LANG, LC_CTYPE, LC_MESSAGES, LC_ALL 🌈
These environment variables control the localization info that lets GCC work with different national conventions 🌍 GCC looks at the locale categories LC_CTYPE and LC_MESSAGES if it's been configured to do so. These categories can be set to any value your installation supports. A typical value is en_GB.UTF-8, which means English in the United Kingdom, encoded in UTF-8 🇬🇧
LC_CTYPE is the character classification one 🦋 GCC uses it to figure out where character boundaries are in a string. This matters for some multibyte encodings that have quote and escape characters which would otherwise be read as the end of a string or as an escape 😭
LC_MESSAGES decides which language is used in diagnostic messages 💬
If the LC_ALL variable is set, it overrides LC_CTYPE and LC_MESSAGES 👑 Otherwise, LC_CTYPE and LC_MESSAGES default to whatever LANG says. If none of these are set, GCC defaults to traditional C English behavior 🍓
TMPDIR 🗂️
If TMPDIR is set, it tells GCC which directory to use for temporary files 🌸 GCC uses temp files to hold the output of one stage of compilation so the next stage can use it as input. For example, the output of the preprocessor is the input to the compiler proper ✨
GCC_COMPARE_DEBUG 🐞
Setting GCC_COMPARE_DEBUG is nearly the same as passing -fcompare-debug to the compiler driver 🙈 Check the docs for that option if you want the full tea ☕
GCC_EXEC_PREFIX 🧁
If GCC_EXEC_PREFIX is set, it gives a prefix to use in the names of the subprograms the compiler runs 🎀 No slash gets added when the prefix is combined with a subprogram name, so if you want that slash, end your prefix with one yourself 🦋
If GCC_EXEC_PREFIX isn't set, GCC tries to figure out a sensible prefix based on the pathname it was invoked with 🔍
If GCC can't find the subprogram using the prefix you gave it, it goes looking in the usual places instead 🏃♀️
The default value of GCC_EXEC_PREFIX is prefix/lib/gcc/, where prefix is the prefix of the installed compiler 💅 In a lot of cases, prefix is whatever "prefix" was set to when you ran the configure script 🌷
Prefixes given with -B take precedence over this one 👑
This prefix is also used to find files like crt0.o, which are used for linking 🔗
The prefix also gets used in a pretty unusual way when hunting for header file directories 🤯 For each standard directory whose name normally starts with /usr/local/lib/gcc (or, more precisely, with the value of GCC_INCLUDE_DIR), GCC tries swapping that beginning out for your specified prefix to make an alternate directory name. So with -Bfoo/, GCC searches foo/bar just before it searches the standard directory /usr/local/lib/bar 🌈 If a standard directory starts with the configured prefix, then that prefix gets replaced by GCC_EXEC_PREFIX when GCC looks for header files 🧚
COMPILER_PATH 🛤️
The value of COMPILER_PATH is a colon-separated list of directories, very much like PATH 💖 GCC tries these directories when searching for subprograms, but only if it can't find them using GCC_EXEC_PREFIX first 🫶
LIBRARY_PATH 📚
The value of LIBRARY_PATH is also a colon-separated list of directories, just like PATH ✨ When GCC is configured as a native compiler, it tries these directories when searching for special linker files, if it can't find them using GCC_EXEC_PREFIX 🔧 Linking with GCC also searches these directories for ordinary libraries when you use the -l option. The directories given with -L come first though 👑
LANG (again, but for the compiler) 🇯🇵
This variable passes locale info to the compiler 🎌 One thing it's used for is deciding which character set to use when parsing character literals, string literals and comments in C and C++ 💅 When the compiler is configured to allow multibyte characters, these values for LANG are recognized:
C-JIS— Recognize JIS characters.C-SJIS— Recognize SJIS characters.C-EUCJP— Recognize EUCJP characters.
If LANG isn't defined, or it has some other value, the compiler uses "mblen" and "mbtowc" as defined by the default locale to recognize and translate multibyte characters 🌸
GCC_EXTRA_DIAGNOSTIC_OUTPUT 🩹
If GCC_EXTRA_DIAGNOSTIC_OUTPUT is set to one of these values, extra text gets printed to stderr whenever fix-it hints are emitted 💬 Just know that -fdiagnostics-parseable-fixits and -fno-diagnostics-parseable-fixits take precedence over this env var 👑
fixits-v1— Emits parseable fix-it hints, the same as-fdiagnostics-parseable-fixits. Columns are counted in bytes, starting at byte 1 for the first column 🧮fixits-v2— Same asfixits-v1, except the columns are expressed as display columns, like-fdiagnostics-column-unit=displaydoes 📐
Some additional environment variables affect how the preprocessor behaves 🧚♀️
CPATH, C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH 🗺️
Each of these variables holds a list of directories, separated by a special character (much like PATH), where GCC looks for header files 🦋 That special character, PATH_SEPARATOR, depends on the target and gets set when GCC is built. For Microsoft Windows-based targets it's a semicolon, and for almost every other target it's a colon 🪟
CPATH specifies directories to search as if you'd used -I, but they come after any paths given with -I on the command line 💖 This variable gets used no matter which language is being preprocessed 🌈
The other three only apply when preprocessing the particular language they name 🎯 Each one lists directories to search as if you'd used -isystem, again placed after any -isystem paths on the command line 🧁
In all of these variables, an empty element tells the compiler to search its current working directory 📂 Empty elements can show up at the beginning or end of a path. For instance, if the value of CPATH is :/special/include, that's the same as -I. -I/special/include 🫶
DEPENDENCIES_OUTPUT 🕸️
If this variable is set, its value says how to output Make dependencies based on the non-system header files the compiler processes 🔨 System header files get ignored in the dependency output 🙅♀️
The value of DEPENDENCIES_OUTPUT can just be a file name, in which case the Make rules get written to that file, with the target name guessed from the source file name 📝 Or the value can look like file target, in which case the rules are written to file using target as the target name 🎯
Put simply, this env var is equivalent to combining the options -MM and -MF, with an optional -MT switch too ✨
SUNPRO_DEPENDENCIES ☀️
This one is the same as DEPENDENCIES_OUTPUT (see above), except system header files are not ignored 😤 So it implies -M rather than -MM 🙃 The dependence on the main input file is left out though 🙈
SOURCE_DATE_EPOCH ⏰
If this variable is set, its value is a UNIX timestamp used in place of the current date and time in the "__DATE__" and "__TIME__" macros 🕰️ That way embedded timestamps stay reproducible 🔁
The value of SOURCE_DATE_EPOCH has to be a UNIX timestamp, which means the number of seconds (not counting leap seconds) since 01 Jan 1970 00:00:00, written in ASCII 🔢 It's the same output you'd get from date +%s on GNU/Linux and other systems that support the %s extension in the date command 🐧
The value should be a known timestamp, like the last modification time of the source or package, and the build process should set it 🛠️
🐛 BUGS 🐛
For instructions on reporting bugs, see <file:///usr/share/doc/gcc-14/README.Bugs> 💌
🧾 FOOTNOTES 🧾
- On some systems,
gcc -sharedneeds to build supplementary stub code for constructors to work 🧱 On multi-libbed systems,gcc -sharedhas to select the correct support libraries to link against 📚
Failing to supply the correct flags may lead to subtle defects. Supplying them in cases where they are not necessary is innocuous.-sharedsuppresses the addition of startup code that alters the floating-point environment, as done with-ffast-math,-Ofastor-funsafe-math-optimizationson some targets. ⚠️
🔗 SEE ALSO 🔗
gpl(7), gfdl(7), fsf-funding(7), cpp(1), gcov(1), as(1), ld(1), gdb(1) and the Info entries for gcc, cpp, as, ld, binutils and gdb 📖💕
👩💻 AUTHOR 👩💻
See the Info entry for gcc, or <https://gcc.gnu.org/onlinedocs/gcc/Contributors.html>, for contributors to GCC 🫶 The whole squad that made this happen deserves a standing ovation 👏
⚖️ COPYRIGHT ⚖️
Copyright (c) 1988-2024 Free Software Foundation, Inc. 🌷
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation 📜 with the Invariant Sections being "GNU General Public License" and "Funding Free Software", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the gfdl(7) man page 💜
(a) The FSF's Front-Cover Text is:
A GNU Manual
(b) The FSF's Back-Cover Text is:
You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development. 💖
And that's the whole page, bestie 🎀 GCC 14, dated April 12, 2024, and we are DONE with this one ✨💅🦋
📦 where this page comes from
- ubuntu noble: gcc-14-hppa-linux-gnu 14-20240412-0ubuntu1cross1
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms