GCC(1)
📜 GCC(1) from GNU ✨ (part 1 of 130)
🧚 NAME 🧚
okay so gcc is the GNU project's C and C++ compiler 💅 literally the main character of compiling 👑
🎀 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 here, bestie 🫶 see below for the rest. g++ accepts mostly the same options as gcc ✨
💖 DESCRIPTION 💖
okay so when you invoke GCC, it normally does preprocessing, compilation, assembly and linking 🔥 The "overall options" let you stop this process at an intermediate stage. For example, the -c option says not to run the linker, so the output is the object files the assembler spits out 🦋
Other options get passed on to one or more stages of processing. Some control the preprocessor, some control the compiler itself, and yet other options control the assembler and linker. Most of those aren't documented here because you rarely need to touch them 💅
Most of the command-line options you can use with GCC are useful for C programs. When an option is only useful with another language (usually C++), the explanation says so explicitly. If an option's description doesn't mention a source language, you can use it with all supported languages 🌈
The usual way to run GCC is the executable called gcc, or machine-gcc when cross-compiling, or machine-gcc-version if you want a specific version of GCC. 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 😭
You can mix options and other arguments, and for the most part the order doesn't matter 🌸 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 specified them. Also, the placement of the -l option is significant ⭐
Lots of options have long names starting 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 is not the default 🧚
Some options take one or more arguments, usually separated from the option name by either a space or the equals sign (=). Unless documented otherwise, an argument can be either numeric or a string. Numeric arguments must typically be small unsigned decimal or hexadecimal integers, and hexadecimal arguments must begin with the 0x prefix 🔢
Arguments to options that specify a size threshold can be arbitrarily large decimal or hexadecimal integers followed by a byte size suffix for a multiple of bytes. That's kB and KiB for kilobyte and kibibyte, MB and MiB for megabyte and mebibyte, GB and GiB for gigabyte and gigibyte, and so on. These are called byte-size in the rest of the text. For the full listing and explanation of the binary and decimal byte size prefixes, check the NIST, IEC, and other relevant national and international standards 📚
👑 OPTIONS 👑
🌸 Option Summary
Here's a summary of all the options, grouped by type 💖 The explanations live in the following sections.
🦋 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 -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 --assemble --compile --dumpbase dumpbase
--dumpbase-ext auxdropsuf --dumpdir dumppfx --language=language
--output=file --pass-exit-codes --pipe --preprocess --verbose💅 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 -fpermitted-flt-eval-methods=standard
-fplan9-extensions -fsigned-bitfields -funsigned-bitfields
-fsigned-char -funsigned-char -fstrict-flex-arrays[=n]
-fsso-struct=endianness --ansi🔮 C++ Language Options
--compile-std-module -fabi-compat-version=n -fabi-version=n
-fno-access-control -faligned-new=[n]
-fno-assume-sane-operators-new-delete -fchar8_t -fcheck-new
-fconcepts -fconcepts-diagnostics-depth=n -fconstexpr-depth=n
-fconstexpr-cache-depth=n -fconstexpr-loop-limit=n
-fconstexpr-ops-limit=n -fcontracts
-fcontract-evaluation-semantic=[ignore|observe|enforce|quick_enforce]
-fcontracts-conservative-ipa -fcontract-checks-outlined
-fcontract-disable-optimized-checks
-fcontracts-client-check=[none|pre|all]
-fcontracts-definition-check=[on|off] -fcoroutines
-fdiagnostics-all-candidates -fno-elide-constructors
-fno-enforce-eh-specs -fext-numeric-literals -fno-gnu-keywords
-fno-immediate-escalation -fno-implement-inlines
-fimplicit-constexpr -fno-implicit-inline-templates
-fno-implicit-templates -fmodule-header[=kind]
-fmodule-implicit-inline -fno-module-lazy
-fmodule-mapper=specification -fmodule-only -fmodules
-fms-extensions -fnew-inheriting-ctors -fnew-ttp-matching
-fno-nonansi-builtins -fnothrow-opt -fno-operator-names
-fno-optional-diags -fno-pretty-templates -frange-for-ext-temps
-freflection -fno-rtti -fsized-deallocation -fstrict-enums
-fstrong-eval-order[=kind] -ftemplate-backtrace-limit=n
-ftemplate-depth=n -fno-threadsafe-statics -fuse-cxa-atexit
-fno-use-cxa-get-exception-ptr -fno-weak -nostdinc++
-fvisibility-inlines-hidden -fvisibility-ms-compat
-flang-info-include-translate[=header]
-flang-info-include-translate-not -flang-info-module-cmi[=module]
-stdlib=libstdc++,libc++ -Wabbreviated-auto-in-template-arg
-Wabi-tag -Waligned-new[=kind] -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-defaulted-function-deleted -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
-Wno-deprecated-literal-operator
-Wdeprecated-variadic-comma-omission -Weffc++
-Wno-elaborated-enum-base -Wno-exceptions
-Wno-expose-global-module-tu-local -Wno-external-tu-local
-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
-Wno-sfinae-incomplete -Wstrict-null-sentinel
-Wno-subobject-linkage -Wtemplates -Wno-non-c-typedef-for-linkage
-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-body -Wno-template-id-cdtor -Wtemplate-names-tu-local
-Wno-terminate -Wno-vexing-parse -Wvirtual-inheritance
-Wno-virtual-move-assign -Wvolatile🍓 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🧜 OpenMP and OpenACC Options
-foffload=arg -foffload-options=arg -fopenacc -fopenacc-dim=geom
-fopenmp -fopenmp-simd -fopenmp-target-simd-clone[=device-type]💜 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]
-fdiagnostics-add-output=DIAGNOSTICS-OUTPUT-SPEC
-fdiagnostics-set-output=DIAGNOSTICS-OUTPUT-SPEC
-fno-diagnostics-json-formatting -fno-diagnostics-show-option
-fno-diagnostics-show-caret -fno-diagnostics-show-event-links
-fno-diagnostics-show-labels -fno-diagnostics-show-line-numbers
-fno-diagnostics-show-cwe -fno-diagnostics-show-rules
-fno-diagnostics-show-highlight-colors -fno-diagnostics-show-nesting
-fno-diagnostics-show-nesting-locations
-fdiagnostics-show-nesting-levels
-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]
-fdiagnostics-show-context[=depth]✨ Warning Options ✨
okay bestie, this is the whole warnings wardrobe 💅 every single one of these is listed below, no cap 🫶
-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-Wauto-profile-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-Wc23-c2y-compat-Wc++-compat-Wc++11-compat-Wc++14-compat-Wc++17-compat-Wc++20-compat-Wc++26-compat-Wno-c++11-extensions-Wno-c++14-extensions-Wno-c++17-extensions-Wno-c++20-extensions-Wno-c++23-extensions-Wcalloc-transposed-args-Wcannot-profile-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-Wno-deprecated-openmp-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-diag-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-Wheader-guard-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-Wkeyword-macro-Wlarger-than=byte-size-Wleading-whitespace=kind-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-Wmusttail-local-addr-Wmaybe-musttail-local-addr-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-pragma-once-outside-header-Wno-prio-ctor-dtor-Wno-psabi-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=attribute-name-Wswitch-Wno-switch-bool-Wswitch-default-Wswitch-enum-Wno-switch-outside-range-Wno-switch-unreachable-Wsync-nand-Wsystem-headers-Wtautological-compare-Wtrailing-whitespace-Wtrailing-whitespace=kind-Wtrampolines-Wtrigraphs-Wtrivial-auto-var-init-Wno-tsan-Wtype-limits-Wundef-Wuninitialized-Wunknown-pragmas-Wunsuffixed-float-constants-Wunterminated-string-initialization-Wunused-Wunused-but-set-parameter-Wunused-but-set-parameter=n-Wunused-but-set-variable-Wunused-but-set-variable=n-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-as-null-pointer-constant-Wzero-length-bounds--all-warnings--extra-warnings--no-warnings--pedantic--pedantic-errors
🔍 Static Analyzer Options 🔍
the analyzer squad has arrived 🦋 here's every flag they came with, iykyk ✨
-fanalyzer-fanalyzer-assume-nothrow-fanalyzer-call-summaries-fanalyzer-checker=name-fno-analyzer-feasibility-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-Wno-analyzer-throw-of-unexpected-type-Wanalyzer-symbol-too-complex-Wanalyzer-too-complex-Wno-analyzer-undefined-behavior-ptrdiff-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 C and Objective-C only, so they're a little picky 🎀
-Wbad-function-cast-Wdeprecated-non-prototype-Wfree-labels-Wmissing-declarations-Wmissing-parameter-name-Wmissing-parameter-type-Wdeclaration-missing-parameter-type-Wmissing-prototypes-Wmissing-variable-declarations-Wmultiple-parameter-fwd-decl-lists-Wnested-externs-Wold-style-declaration-Wold-style-definition-Wstrict-prototypes-Wtraditional-Wtraditional-conversion-Wdeclaration-after-statement-Wpointer-sign
🐛 Debugging Options 🐛
the debug drip is UNREAL 💜 every flag is here, no skipping 🧚
-g-glevel-gdwarf-gdwarf-version-gbtf-gctf-gctflevel-gno-prune-btf-ggdb-gno-record-gcc-switches-gstrict-dwarf-gas-loc-support-gas-locview-support-gcodeview-gcolumn-info-gdwarf32-gdwarf64-gno-statement-frontiers-gno-variable-location-views-gvariable-location-views=incompat5-ginternal-reset-location-views-ginline-points-gvms-gz[=type]-gsplit-dwarf-gdescribe-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-fvar-tracking-uninit--debug
✨ Optimization Options ✨
okay bestie, the optimization drawer is SO full 🔥 here's every single flag, no cap 💅
-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-profile-inlining-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-fcx-method-fdata-sections-fdce-fdelayed-branch-fdelete-null-pointer-checks-fdep-fusion-fdevirtualize-fdevirtualize-speculatively-fdevirtualize-at-ltrans-fdse-fearly-inlining-fexcess-precision=style-fexpensive-optimizations-fext-dce-ffast-math-ffat-lto-objects-ffinite-loops-ffinite-math-only-ffloat-store-fforward-propagate-ffp-contract=style-ffp-int-builtin-inexact-ffunction-sections-ffuse-ops-with-volatile-access-fgcse-fgcse-after-reload-fgcse-las-fgcse-lm-fgraphite-identity-fgcse-sm-fhoist-adjacent-loads-fif-conversion-fif-conversion2-findirect-inlining-finline-atomics-finline-functions-finline-functions-called-once-finline-limit=n-finline-small-functions-finline-stringops[=fn]-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-reorder-for-locality-fipa-sra-fipa-stack-alignment-fipa-icf-fipa-icf-functions-fipa-icf-variables-fira-algorithm=algorithm-flate-combine-instructions-flifetime-dse-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=n-flto-toplevel-asm-heuristics-flto-partition=alg-flto-incremental=path-flto-incremental-cache-size=n-fmalloc-dce-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-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-crc-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-fspeculatively-call-stored-functions-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-cselim-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-O-O0-O1-O2-O3-Os-Ofast-Og-Oz--optimize
✨ Program Instrumentation Options ✨
the instrumentation drawer is next, bestie 🔍💜 profiling, coverage, sanitizers, hardening, the whole glam squad 🫶
-p-pg-fprofile-arcs-coverage-ftest-coverage-fcondition-coverage-fpath-coverage-fprofile-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-fcf-protection-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]--coverage--profile
✨ Preprocessor Options ✨
the preprocessor drawer 🎀 let's see what's in here, bestie 🧚
-C-CC-Dmacro[=defn]-dD-dI-dM-dN-dU-fdebug-cpp-fdirectives-only-fdollars-in-identifiers-fexec-charset=charset-fextended-identifiers-finput-charset=charset-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--comments--comments-in-macros--define-macro=macro[=defn]--dependencies--dump=letters--imacros=file--include=file--no-integrated-cpp--no-line-commands--print-missing-file-dependencies--traditional--traditional-cpp--trigraphs--trace-includes--undefine-macro=macro--user-dependencies--write-dependencies--write-user-dependencies
✨ Assembler Options ✨
-Wa,option-Xassembler option--for-assembler=option
✨ Linker Options ✨
object-file-name-flink-libatomic-fuse-ld=linker-llibrary-nostartfiles-nodefaultlibs-nolibc-nostdlib-nostdlib++-e 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-Tbss=addr-Tdata=addr-Ttext=addr-N-n-t-Z-z keyword--entry=entry--for-linker=option--force-link=symbol--no-standard-library--pie--static--static-pie--symbolic
✨ Directory Options ✨
-Bprefix-Idir-I--idirafter dir-imacros file-imultilib dir-imultiarch dir-iplugindir=dir-iprefix file-iquote dir-isysroot dir-isystem dir-iwithprefix dir-iwithprefixbefore dir-Ldir-no-canonical-prefixes--no-sysroot-suffix-nostdinc-nostdinc++--embed-dir=dir--embed-directory=dir--include-barrier--include-directory=dir--include-directory-after=dir--include-prefix=prefix--include-with-prefix=prefix--include-with-prefix-after=prefix--include-with-prefix-before=prefix--no-canonical-prefixes--no-standard-includes--prefix=prefix--sysroot=dir
✨ Picolibc Options ✨
--oslib=library--crt0=[none|minimal|hosted|semihost]--printf=[d|f|l|i|m]--scanf=[d|f|l|i|m]
✨ Code Generation Options ✨
-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-fwrapv-pointer-fvisibility=[default|internal|hidden|protected]-fstrict-volatile-bitfields-fsync-libcalls-fzero-init-padding-bits=value-Qy-Qn
🎀 Developer Options 🎀
okay bestie, this is the dev-only lineup 💖 Every flag below is copied exactly as the page lists it, so you can pick them out without any guesswork ✨
-dletters— bestie, look at this one 💅-dumpspecs— main character flag 👑-dumpmachine— iykyk 🫶-dumpversion— not me staring at this 🙈-dumpfullversion— the vibe is immaculate ✨-fcallgraph-info[=su,da]— a total slay 💖-fchecking— lowkey dev-only energy 🔥-fchecking=n— iconic 🦋-fdbg-cnt-list— periodt 💅-fdbg-cnt=counter-value-list— pretty little option 🌸-fdisable-ipa-pass_name— extremely on brand 🧚-fdisable-rtl-pass_name— sparkle moment ⭐-fdisable-rtl-pass-name=range-list— bestie, look at this one 💅-fdisable-tree-pass_name— main character flag 👑-fdisable-tree-pass-name=range-list— iykyk 🫶-fdump-debug— not me staring at this 🙈-fdump-earlydebug— the vibe is immaculate ✨-fdump-noaddr— a total slay 💖-fdump-unnumbered— lowkey dev-only energy 🔥-fdump-unnumbered-links— iconic 🦋-fdump-final-insns[=file]— periodt 💅-fdump-internal-locations— pretty little option 🌸-fdump-ipa-all— extremely on brand 🧚-fdump-ipa-cgraph— sparkle moment ⭐-fdump-ipa-inline— bestie, look at this one 💅-fdump-lang-all— main character flag 👑-fdump-lang-switch— iykyk 🫶-fdump-lang-switch-options— not me staring at this 🙈-fdump-lang-switch-options=filename— the vibe is immaculate ✨-fdump-passes— a total slay 💖-fdump-rtl-pass— lowkey dev-only energy 🔥-fdump-rtl-pass=filename— iconic 🦋-fdump-statistics— periodt 💅-fdump-tree-all— pretty little option 🌸-fdump-tree-switch— extremely on brand 🧚-fdump-tree-switch-options— sparkle moment ⭐-fdump-tree-switch-options=filename— bestie, look at this one 💅-fcompare-debug[=opts]— main character flag 👑-fcompare-debug-second— iykyk 🫶-fenable-kind-pass— not me staring at this 🙈-fenable-kind-pass=range-list— the vibe is immaculate ✨-fira-verbose=n— a total slay 💖-flto-report— lowkey dev-only energy 🔥-flto-report-wpa— iconic 🦋-fmem-report-wpa— periodt 💅-fmem-report— pretty little option 🌸-fpre-ipa-mem-report— extremely on brand 🧚-fpost-ipa-mem-report— sparkle moment ⭐-fopt-info— bestie, look at this one 💅-fopt-info-options[=file]— main character flag 👑-fmultiflags— iykyk 🫶-fprofile-report— not me staring at this 🙈-frandom-seed=string— the vibe is immaculate ✨-fsched-verbose=n— a total slay 💖-fsel-sched-verbose— lowkey dev-only energy 🔥-fsel-sched-dump-cfg— iconic 🦋-fsel-sched-pipelining-verbose— periodt 💅-fstats— pretty little option 🌸-fstack-usage— extremely on brand 🧚-ftime-report— sparkle moment ⭐-ftime-report-details— bestie, look at this one 💅-fvar-tracking-assignments-toggle— main character flag 👑-gtoggle— iykyk 🫶-print-autofdo-gcov-version— not me staring at this 🙈-print-file-name=library— the vibe is immaculate ✨-print-libgcc-file-name— a total slay 💖-print-multi-directory— lowkey dev-only energy 🔥-print-multi-lib— iconic 🦋-print-multi-os-directory— periodt 💅-print-multiarch— pretty little option 🌸-print-prog-name=program— extremely on brand 🧚-print-search-dirs— sparkle moment ⭐-Q— bestie, look at this one 💅-print-sysroot— main character flag 👑-print-sysroot-headers-suffix— iykyk 🫶-save-temps— not me staring at this 🙈-save-temps=cwd— the vibe is immaculate ✨-save-temps=obj— a total slay 💖-specs=file— lowkey dev-only energy 🔥-time[=file]— iconic 🦋--dump=letters— periodt 💅--print-autofdo-gcov-version— pretty little option 🌸--print-file-name=library— extremely on brand 🧚--print-libgcc-file-file-name— sparkle moment ⭐--print-multi-directory— bestie, look at this one 💅--print-multi-lib— main character flag 👑--print-multi-os-directory— iykyk 🫶--print-multiarch— not me staring at this 🙈--print-prog-name=program— the vibe is immaculate ✨--print-search-dirs— a total slay 💖--print-sysroot— lowkey dev-only energy 🔥--print-sysroot-headers-suffix— iconic 🦋--save-temps— periodt 💅--specs=file— pretty little option 🌸--param name=value— extremely on brand 🧚
the page spells this one --print-libgcc-file-file-name with the doubled "file", so copy it exactly 👀
🌈 Machine-Dependent Options 🌈
these are the target-specific ones, and each chip family gets its own little list 🦋
✨ AArch64 Options ✨
-mabi=name— bestie, look at this one 💅-mbig-endian— main character flag 👑-mlittle-endian— iykyk 🫶-menable-sysreg-checking— not me staring at this 🙈-mgeneral-regs-only— the vibe is immaculate ✨-mcmodel=tiny— a total slay 💖-mcmodel=small— lowkey dev-only energy 🔥-mcmodel=large— iconic 🦋-mstrict-align— periodt 💅-momit-leaf-frame-pointer— pretty little option 🌸-mtls-dialect=desc— extremely on brand 🧚-mtls-dialect=traditional— sparkle moment ⭐-mtls-size=size— bestie, look at this one 💅-mtp=name— main character flag 👑-mfix-cortex-a53-835769— iykyk 🫶-mfix-cortex-a53-843419— not me staring at this 🙈-mlow-precision-recip-sqrt— the vibe is immaculate ✨-mlow-precision-sqrt— a total slay 💖-mlow-precision-div— lowkey dev-only energy 🔥-mmax-vectorization— iconic 🦋-mautovec-preference=name— periodt 💅-mpc-relative-literal-loads— pretty little option 🌸-msign-return-address=scope— extremely on brand 🧚-mbranch-protection=features— sparkle moment ⭐-mharden-sls=opts— bestie, look at this one 💅-march=name— main character flag 👑-mcpu=name— iykyk 🫶-mtune=name— not me staring at this 🙈-moverride=string— the vibe is immaculate ✨-mstack-protector-guard=guard— a total slay 💖-mstack-protector-guard-reg=sysreg— lowkey dev-only energy 🔥-mstack-protector-guard-offset=offset— iconic 🦋-mtrack-speculation— periodt 💅-moutline-atomics— pretty little option 🌸-mearly-ra— extremely on brand 🧚-mearly-ldp-fusion— sparkle moment ⭐-mlate-ldp-fusion— bestie, look at this one 💅-msve-vector-bits=bits— main character flag 👑
✨ Adapteva Epiphany Options ✨
-mhalf-reg-file— iykyk 🫶-mprefer-short-insn-regs— not me staring at this 🙈-mbranch-cost=num— the vibe is immaculate ✨-mcmove— a total slay 💖-mnops=num— lowkey dev-only energy 🔥-msoft-cmpsf— iconic 🦋-msplit-lohi— periodt 💅-mpost-inc— pretty little option 🌸-mpost-modify— extremely on brand 🧚-mstack-offset=num— sparkle moment ⭐-mround-nearest— bestie, look at this one 💅-mlong-calls— main character flag 👑-mshort-calls— iykyk 🫶-msmall16— not me staring at this 🙈-mfp-mode=mode— the vibe is immaculate ✨-mmay-round-for-trunc— a total slay 💖-mfp-iarith— lowkey dev-only energy 🔥-mvect-double— iconic 🦋-max-vect-align=num— periodt 💅-msplit-vecmove-early— pretty little option 🌸-m1reg-reg— extremely on brand 🧚
✨ AMD GCN Options ✨
-march=gpu— sparkle moment ⭐-mtune=gpu— bestie, look at this one 💅-mgang-private-size=bytes— main character flag 👑-msram-ecc=[on|off|any]— iykyk 🫶-mxnack=[on|off|any]— not me staring at this 🙈-Wopenacc-dims— the vibe is immaculate ✨
✨ ARC Options ✨
-mbarrel-shifter— a total slay 💖-mjli-always— lowkey dev-only energy 🔥-mcpu=cpu— iconic 🦋-mA6— periodt 💅-mARC600— pretty little option 🌸-mA7— extremely on brand 🧚-mARC700— sparkle moment ⭐-mdpfp— bestie, look at this one 💅-mdpfp-compact— main character flag 👑-mdpfp-fast— iykyk 🫶-mno-dpfp-lrsr— not me staring at this 🙈-mea— the vibe is immaculate ✨-mmul32x16— a total slay 💖-mmul64— lowkey dev-only energy 🔥-matomic— iconic 🦋-mnorm— periodt 💅-mspfp— pretty little option 🌸-mspfp-compact— extremely on brand 🧚-mspfp-fast— sparkle moment ⭐-msimd— bestie, look at this one 💅-msoft-float— main character flag 👑-mswap— iykyk 🫶-mlock— not me staring at this 🙈-mswape— the vibe is immaculate ✨-mxy— a total slay 💖-misize— lowkey dev-only energy 🔥-marclinux— iconic 🦋-marclinux_prof— periodt 💅-mlong-calls— pretty little option 🌸-mmedium-calls— extremely on brand 🧚-msdata— sparkle moment ⭐-mirq-ctrl-saved— bestie, look at this one 💅-mrgf-banked-regs— main character flag 👑-mlpc-width=width— iykyk 🫶-G num— not me staring at this 🙈-mvolatile-cache— the vibe is immaculate ✨-mtp-regno=regno— a total slay 💖-mbitops— lowkey dev-only energy 🔥-mcmem— iconic 🦋-munaligned-access— periodt 💅-mauto-modify-reg— pretty little option 🌸-mno-brcc— extremely on brand 🧚-mcase-vector-pcrel— sparkle moment ⭐-mno-cond-exec— bestie, look at this one 💅-mearly-cbranchsi— main character flag 👑-mindexed-loads— iykyk 🫶-mlra-priority-none— not me staring at this 🙈-mlra-priority-compact— the vibe is immaculate ✨-mlra-priority-noncompact— a total slay 💖-mmillicode— lowkey dev-only energy 🔥-msize-level=level— iconic 🦋-mtune=cpu— periodt 💅-mmultcost=num— pretty little option 🌸-mcode-density-frame— extremely on brand 🧚-mmpy-option=multo— sparkle moment ⭐-mdiv-rem— bestie, look at this one 💅-mcode-density— main character flag 👑-mll64— iykyk 🫶-mfpu=fpu— not me staring at this 🙈-mrf16— the vibe is immaculate ✨-mbranch-index— a total slay 💖
✨ ARM Options ✨
-mapcs-frame— lowkey dev-only energy 🔥-mapcs— iconic 🦋-mabi=name— periodt 💅-mgeneral-regs-only— pretty little option 🌸-mno-sched-prolog— extremely on brand 🧚-mlittle-endian— sparkle moment ⭐-mbig-endian— bestie, look at this one 💅-mbe8— main character flag 👑-mbe32— iykyk 🫶-mfloat-abi=name— not me staring at this 🙈-mfp16-format=name— the vibe is immaculate ✨-mthumb-interwork— a total slay 💖-mcpu=name— lowkey dev-only energy 🔥-march=name— iconic 🦋-mfpu=name— periodt 💅-mtune=name— pretty little option 🌸-mstructure-size-boundary=n— extremely on brand 🧚-mabort-on-noreturn— sparkle moment ⭐-mlong-calls— bestie, look at this one 💅-msingle-pic-base— main character flag 👑-mpic-register=reg— iykyk 🫶-mpic-data-is-text-relative— not me staring at this 🙈-mnop-fun-dllimport— the vibe is immaculate ✨-mpoke-function-name— a total slay 💖-mthumb— lowkey dev-only energy 🔥-marm— iconic 🦋-mtpcs-frame— periodt 💅-mtpcs-leaf-frame— pretty little option 🌸-mcaller-super-interworking— extremely on brand 🧚-mcallee-super-interworking— sparkle moment ⭐-mtp=name— bestie, look at this one 💅-mtls-dialect=dialect— main character flag 👑-mword-relocations— iykyk 🫶-mfix-cortex-m3-ldrd— not me staring at this 🙈-mfix-cortex-a57-aes-1742098— the vibe is immaculate ✨-mfix-cortex-a72-aes-1655431— a total slay 💖-munaligned-access— lowkey dev-only energy 🔥-mslow-flash-data— iconic 🦋-masm-syntax-unified— periodt 💅-mrestrict-it— pretty little option 🌸-mpure-code— extremely on brand 🧚-mcmse— sparkle moment ⭐-mfix-cmse-cve-2021-35465— bestie, look at this one 💅-mstack-protector-guard=guard— main character flag 👑-mstack-protector-guard-offset=offset— iykyk 🫶-mfdpic— not me staring at this 🙈-mbranch-protection=features— the vibe is immaculate ✨-mvectorize-with-neon-quad— a total slay 💖-mvectorize-with-neon-double— lowkey dev-only energy 🔥
✨ AVR Options ✨
-mmcu=mcu— iconic 🦋-mabsdata— periodt 💅-maccumulate-args— pretty little option 🌸-mcvt— extremely on brand 🧚-mbranch-cost=cost— sparkle moment ⭐-mfuse-add=level— bestie, look at this one 💅-mfuse-move=level— main character flag 👑-mfuse-move2— iykyk 🫶-mcall-prologues— not me staring at this 🙈-mgas-isr-prologues— the vibe is immaculate ✨-mint8— a total slay 💖-mflmap— lowkey dev-only energy 🔥-mdouble=bits— iconic 🦋-mlong-double=bits— periodt 💅-mno-call-main— pretty little option 🌸-mn_flash=size— extremely on brand 🧚-mfract-convert-truncate— sparkle moment ⭐-mno-interrupts— bestie, look at this one 💅-mmain-is-OS_task— main character flag 👑-mrelax— iykyk 🫶-mpmem-wrap-around— not me staring at this 🙈-mrmw— the vibe is immaculate ✨-mstrict-X— a total slay 💖-mtiny-stack— lowkey dev-only energy 🔥-mrodata-in-ram— iconic 🦋-msplit-bit-shift— periodt 💅-msplit-ldst— pretty little option 🌸-mshort-calls— extremely on brand 🧚-mskip-bug— sparkle moment ⭐-muse-nonzero-bits— bestie, look at this one 💅-nodevicelib— main character flag 👑-nodevicespecs— iykyk 🫶-Waddr-space-convert— not me staring at this 🙈-Wmisspelled-isr— the vibe is immaculate ✨
✨ Blackfin Options ✨
-mcpu=cpu[-sirevision]— a total slay 💖-msim— lowkey dev-only energy 🔥-momit-leaf-frame-pointer— iconic 🦋-mspecld-anomaly— periodt 💅-mcsync-anomaly— pretty little option 🌸-mlow-64k— extremely on brand 🧚-mstack-check-l1— sparkle moment ⭐-mid-shared-library— bestie, look at this one 💅-mleaf-id-shared-library— main character flag 👑-mshared-library-id=n— iykyk 🫶-msep-data— not me staring at this 🙈-mlong-calls— the vibe is immaculate ✨-mfast-fp— a total slay 💖-minline-plt— lowkey dev-only energy 🔥-mmulticore— iconic 🦋-mcorea— periodt 💅-mcoreb— pretty little option 🌸-msdram— extremely on brand 🧚-micplb— sparkle moment ⭐
✨ C6X Options ✨
-mbig-endian— bestie, look at this one 💅-mlittle-endian— main character flag 👑-march=cpu— iykyk 🫶-msim— not me staring at this 🙈-msdata=sdata-type— the vibe is immaculate ✨-mdsbt— a total slay 💖-mlong-calls— lowkey dev-only energy 🔥
✨ CRIS Options ✨
-mcpu=cpu— iconic 🦋-march=cpu— periodt 💅-mtune=cpu— pretty little option 🌸-mmax-stackframe=n— extremely on brand 🧚-metrax4— sparkle moment ⭐-metrax100— bestie, look at this one 💅-mpdebug— main character flag 👑-mcc-init— iykyk 🫶-mno-side-effects— not me staring at this 🙈-mstack-align— the vibe is immaculate ✨-mdata-align— a total slay 💖-mconst-align— lowkey dev-only energy 🔥-m32-bit— iconic 🦋-m16-bit— periodt 💅-m8-bit— pretty little option 🌸-mno-prologue-epilogue— extremely on brand 🧚-mbest-lib-options— sparkle moment ⭐-moverride-best-lib-options— bestie, look at this one 💅-mtrap-using-break8— main character flag 👑-mtrap-unaligned-atomic— iykyk 🫶-munaligned-atomic-may-use-library— not me staring at this 🙈-sim— the vibe is immaculate ✨-sim2— a total slay 💖-mmul-bug-workaround— lowkey dev-only energy 🔥
✨ C-SKY Options ✨
-march=arch— iconic 🦋-mcpu=cpu— periodt 💅-mbig-endian— pretty little option 🌸-mlittle-endian— extremely on brand 🧚-mfpu=fpu— sparkle moment ⭐-mdouble-float— bestie, look at this one 💅-mfdivdu— main character flag 👑-mfloat-abi=name— iykyk 🫶-melrw— not me staring at this 🙈-mistack— the vibe is immaculate ✨-mmp— a total slay 💖-mcp— lowkey dev-only energy 🔥-mcache— iconic 🦋-msecurity— periodt 💅-mtrust— pretty little option 🌸-mdsp— extremely on brand 🧚-medsp— sparkle moment ⭐-mvdsp— bestie, look at this one 💅-mdiv— main character flag 👑-msmart— iykyk 🫶-mhigh-registers— not me staring at this 🙈-manchor— the vibe is immaculate ✨-mpushpop— a total slay 💖-mmultiple-stld— lowkey dev-only energy 🔥-mconstpool— iconic 🦋-mstack-size— periodt 💅-mccrt— pretty little option 🌸-mbranch-cost=n— extremely on brand 🧚-msched-prolog— sparkle moment ⭐-msim— bestie, look at this one 💅
✨ Cygwin and MinGW Options ✨
-mconsole— main character flag 👑-mcrtdll=library— iykyk 🫶-mdll— not me staring at this 🙈-mnop-fun-dllimport— the vibe is immaculate ✨-mthreads— a total slay 💖-municode— lowkey dev-only energy 🔥-mwin32— iconic 🦋-mwindows— periodt 💅-fno-set-stack-executable— pretty little option 🌸-fwritable-relocated-rdata— extremely on brand 🧚-mpe-aligned-commons— sparkle moment ⭐-muse-libstdc-wrappers— bestie, look at this one 💅
✨ Darwin Options ✨
-all_load— main character flag 👑-allowable_client— iykyk 🫶-arch name— not me staring at this 🙈-arch_errors_fatal— the vibe is immaculate ✨-asm_macosx_version_min=version— a total slay 💖-bind_at_load— lowkey dev-only energy 🔥-bundle— iconic 🦋-bundle_loader— periodt 💅-client_name— pretty little option 🌸-compatibility_version— extremely on brand 🧚-current_version— sparkle moment ⭐-dead_strip— bestie, look at this one 💅-dependency-file— main character flag 👑-dylib_file— iykyk 🫶-dylinker— not me staring at this 🙈-dylinker_install_name— the vibe is immaculate ✨-dynamic— a total slay 💖-dynamiclib— lowkey dev-only energy 🔥-exported_symbols_list— iconic 🦋-fapple-kext— periodt 💅-fconstant-cfstrings— pretty little option 🌸-ffix-and-continue— extremely on brand 🧚-filelist— sparkle moment ⭐-findirect-data— bestie, look at this one 💅-flat_namespace— main character flag 👑-force_cpusubtype_ALL— iykyk 🫶-force_flat_namespace— not me staring at this 🙈-framework name— the vibe is immaculate ✨-gfull— a total slay 💖-gused— lowkey dev-only energy 🔥-headerpad_max_install_names— iconic 🦋-iframework— periodt 💅-image_base— pretty little option 🌸-init symbol-name— extremely on brand 🧚-install_name— sparkle moment ⭐-keep_private_externs— bestie, look at this one 💅-matt-stubs— main character flag 👑-mconstant-cfstrings— iykyk 🫶-mdynamic-no-pic— not me staring at this 🙈-mfix-and-continue— the vibe is immaculate ✨-mkernel— a total slay 💖-mmacosx-version-min=version— lowkey dev-only energy 🔥-mone-byte-bool— iconic 🦋-msymbol-stubs— periodt 💅-mtarget-linker[=]version— pretty little option 🌸-nodefaultexport— extremely on brand 🧚-nodefaultrpaths— sparkle moment ⭐-pagezero_size— bestie, look at this one 💅-preload— main character flag 👑-read_only_relocs— iykyk 🫶-sectalign— not me staring at this 🙈-sectcreate— the vibe is immaculate ✨-seg_addr_table— a total slay 💖-seg1addr— lowkey dev-only energy 🔥-segaddr— iconic 🦋-segprot— periodt 💅-segs_read_only_addr— pretty little option 🌸-segs_read_write_addr— extremely on brand 🧚-sub_library— sparkle moment ⭐-sub_umbrella— bestie, look at this one 💅-twolevel_namespace— main character flag 👑-twolevel_namespace_hints— iykyk 🫶-umbrella— not me staring at this 🙈-undefined— the vibe is immaculate ✨-unexported_symbols_list— a total slay 💖-weak_framework name— lowkey dev-only energy 🔥-weak_reference_mismatches— iconic 🦋-whatsloaded— periodt 💅-whyload— pretty little option 🌸-F— extremely on brand 🧚-ObjC— sparkle moment ⭐-ObjC++— bestie, look at this one 💅-Wnonportable-cfstrings— main character flag 👑
✨ DEC Alpha Options ✨
-mno-fp-regs— iykyk 🫶-msoft-float— not me staring at this 🙈-mieee— the vibe is immaculate ✨-mieee-with-inexact— a total slay 💖-mieee-conformant— lowkey dev-only energy 🔥-mfp-trap-mode=mode— iconic 🦋-mfp-rounding-mode=mode— periodt 💅-mtrap-precision=mode— pretty little option 🌸-mbuild-constants— extremely on brand 🧚-mcpu=cpu-type— sparkle moment ⭐-mtune=cpu-type— bestie, look at this one 💅-mbwx— main character flag 👑-mmax— iykyk 🫶-mfix— not me staring at this 🙈-mcix— the vibe is immaculate ✨-msafe-bwa— a total slay 💖-msafe-partial— lowkey dev-only energy 🔥-mfloat-vax— iconic 🦋-mfloat-ieee— periodt 💅-mexplicit-relocs— pretty little option 🌸-msmall-data— extremely on brand 🧚-mlarge-data— sparkle moment ⭐-msmall-text— bestie, look at this one 💅-mlarge-text— main character flag 👑-mmemory-latency=time— iykyk 🫶-mtls-kernel— not me staring at this 🙈-mtls-size=bitsize— the vibe is immaculate ✨-mlong-double-128— a total slay 💖-mlong-double-64— lowkey dev-only energy 🔥
✨ eBPF Options ✨
-mbig-endian— iconic 🦋-mlittle-endian— periodt 💅-mframe-limit=bytes— pretty little option 🌸-mxbpf— extremely on brand 🧚-mco-re— sparkle moment ⭐-mjmpext— bestie, look at this one 💅-mjmp32— main character flag 👑-malu32— iykyk 🫶-mv3-atomics— not me staring at this 🙈-mbswap— the vibe is immaculate ✨-msdiv— a total slay 💖-msmov— lowkey dev-only energy 🔥-mcpu=version— iconic 🦋-masm=dialect— periodt 💅-minline-memops-threshold=bytes— pretty little option 🌸-Wco-re— extremely on brand 🧚
✨ FR30 Options ✨
-msmall-model— sparkle moment ⭐-mno-lsim— bestie, look at this one 💅
✨ FRV Options ✨
-mgpr-32— main character flag 👑-mgpr-64— iykyk 🫶-mfpr-32— not me staring at this 🙈-mfpr-64— the vibe is immaculate ✨-mhard-float— a total slay 💖-msoft-float— lowkey dev-only energy 🔥-malloc-cc— iconic 🦋-mfixed-cc— periodt 💅-mdword— pretty little option 🌸-mdouble— extremely on brand 🧚-mmedia— sparkle moment ⭐-mmuladd— bestie, look at this one 💅-mfdpic— main character flag 👑-minline-plt— iykyk 🫶-mgprel-ro— not me staring at this 🙈-multilib-library-pic— the vibe is immaculate ✨-mlinked-fp— a total slay 💖-mlong-calls— lowkey dev-only energy 🔥-malign-labels— iconic 🦋-mlibrary-pic— periodt 💅-macc-4— pretty little option 🌸-macc-8— extremely on brand 🧚-mpack— sparkle moment ⭐-mno-eflags— bestie, look at this one 💅-mno-cond-move— main character flag 👑-mno-optimize-membar— iykyk 🫶-mno-scc— not me staring at this 🙈-mno-cond-exec— the vibe is immaculate ✨-mno-vliw-branch— a total slay 💖-mno-multi-cond-exec— lowkey dev-only energy 🔥-mno-nested-cond-exec— iconic 🦋-mtomcat-stats— periodt 💅-mTLS— pretty little option 🌸-mtls— extremely on brand 🧚-mcpu=cpu— sparkle moment ⭐
✨ FT32 Options ✨
-msim— bestie, look at this one 💅-mnodiv— main character flag 👑-mft32b— iykyk 🫶-mcompress— not me staring at this 🙈-mnopm— the vibe is immaculate ✨
✨ GNU/Linux Options ✨
-mglibc— a total slay 💖-muclibc— lowkey dev-only energy 🔥-mmusl— iconic 🦋-mbionic— periodt 💅-mandroid— pretty little option 🌸-tno-android-cc— extremely on brand 🧚-tno-android-ld— sparkle moment ⭐
✨ H8/300 Options ✨
-mrelax— bestie, look at this one 💅-mh— main character flag 👑-ms— iykyk 🫶-mn— not me staring at this 🙈-msx— the vibe is immaculate ✨-ms2600— a total slay 💖-mquickcall— lowkey dev-only energy 🔥-mslowbyte— iconic 🦋-mexr— periodt 💅-mint32— pretty little option 🌸-malign-300— extremely on brand 🧚
🌸 HPPA Options (HPPA Options) 🌸
Okay bestie, the HPPA flags are literally so iconic 💅 Here's the whole squad:
-march=architecture-type-mno-atomic-libcalls-mcaller-copies-mdisable-fpregs-mdisable-indexing-mordered-mfast-indirect-calls-mgas-mgnu-ld-mhp-ld-mfixed-range=register-range-mcoherent-ldcw-mlinker-opt-mlong-calls-mlong-load-store-mno-space-regs-msoft-float-mpa-risc-1-0-mpa-risc-1-1-mpa-risc-2-0-mportable-runtime-mschedule=cpu-type-msoft-mult-msio-mwsio-munix=unix-std-nolibdld-static-threads
🦋 IA-64 Options (IA-64 Options) 🦋
The IA-64 crew is huge, so grab a snack 🍓
-mbig-endian-mlittle-endian-mgnu-as-mgnu-ld-mno-pic-mvolatile-asm-stop-mregister-names-msdata-mconstant-gp-mauto-pic-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-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 (LM32 Options) 🧚
Small but mighty ✨
-mbarrel-shift-enabled-mdivide-enabled-mmultiply-enabled-msign-extend-enabled-muser-enabled
💜 LoongArch Options (LoongArch Options) 💜
The LoongArch list is giving main character energy 👑
-march=arch-type-mtune=tune-type-mabi=base-abi-type-mfpu=fpu-type-msimd=simd-type-msoft-float-msingle-float-mdouble-float-mlsx-mlasx-mbranch-cost=n-maddr-reg-reg-cost=n-mcheck-zero-division-mbreak-code=code-mcond-move-int-mcond-move-float-memcpy-mstrict-align-G num-mmax-inline-memcpy-size=n-mexplicit-relocs=style-mexplicit-relocs-mno-explicit-relocs-mdirect-extern-access-mcmodel=code-model-mrelax-mpass-mrelax-to-as-mrecip-mrecip=opt-mfrecipe-mdiv32-mlam-bh-mlamcas-mld-seq-sa-mscq-mtls-dialect=opt-mannotate-tablejump
🌈 LynxOS Options (LynxOS Options) 🌈
-mshared-mthreads-mlegacy-threads
🎀 M32C Options (M32C Options) 🎀
-mcpu=cpu-msim-memregs=number
🍓 M32R/D Options (M32R/D Options) 🍓
-m32r2-m32rx-m32r-mdebug-malign-loops-missue-rate=number-mbranch-cost=number-mmodel=code-size-model-type-msdata=sdata-type-mno-flush-func-mflush-func=name-mno-flush-trap-mflush-trap=number-G num
🫶 M680x0 Options (M680x0 Options) 🫶
The M680x0 lineup is absolutely stacked 🔥
-march=arch-mcpu=cpu-mtune=tune-m68000-m68020-m68020-40-m68020-60-m68030-m68040-m68060-m68302-m68332-m68851-mcpu32-mfidoa-m5200-m5206e-m528x-m5307-m5407-mcfv4e-mbitfield-mc68000-mc68020-mrtd-mdiv-mshort-mhard-float-m68881-msoft-float-mpcrel-malign-int-mstrict-align-msep-data-mshared-library-id=n-mid-shared-library-mxgot-mxtls-mlong-jump-table-offsets
🌸 MCore Options (MCore Options) 🌸
-mhardlit-mdiv-mrelax-immediates-mwide-bitfields-m4byte-functions-mcallgraph-data-mslow-bytes-mno-lsim-mlittle-endian-mbig-endian-m210-m340-mstack-increment
🦋 MicroBlaze Options (MicroBlaze Options) 🦋
-msoft-float-mhard-float-msmall-divides-mcpu=cpu-mmemcpy-mxl-soft-mul-mxl-soft-div-mxl-barrel-shift-mxl-pattern-compare-mxl-gp-opt-mxl-multiply-high-mxl-float-convert-mxl-float-sqrt-mbig-endian-mlittle-endian-mxl-reorder-mxl-mode-app-model-mxl-prefetch-mpic-data-is-text-relative
💖 MIPS Options (MIPS Options) 💖
Okay the MIPS section is the longest one, so get comfy bestie 🛋️✨
-EL-EB-mel-meb-march=arch-mtune=arch-mips1-mips2-mips3-mips4-mips32-mips32r2-mips32r3-mips32r5-mips32r6-mips64-mips64r2-mips64r3-mips64r5-mips64r6-mips16-mmips16e2-mflip-mips16-minterlink-compressed-minterlink-mips16-mabi=abi-mabicalls-mshared-mplt-mxgot-mgp32-mgp64-mfp32-mfpxx-mfp64-mhard-float-msoft-float-mno-float-msingle-float-mdouble-float-modd-spreg-mabs=mode-mnan=encoding-mdsp-mdspr2-mmcu-meva-mvirt-mxpa-mcrc-mginv-mmicromips-mmsa-mloongson-mmi-mloongson-ext-mloongson-ext2-mfpu=fpu-type-msmartmips-mpaired-single-mdmx-mips3d-mmt-mllsc-mlong64-mlong32-msym32-Gnum-mno-local-sdata-mno-extern-sdata-mno-gopt-membedded-data-muninit-const-in-rodata-mcode-readable=setting-mno-data-in-code-mcode-xonly-msplit-addresses-mexplicit-relocs-mexplicit-relocs=release-mno-check-zero-division-mdivide-traps-mdivide-breaks-mno-load-store-pairs-mstrict-align-mno-unaligned-access-mmemcpy-mlong-calls-mmad-mimadd-mno-fused-madd-nocpp-mfix-24k-mfix-r4000-mfix-r4400-mfix-r5900-mfix-r10000-mfix-rm7000-mfix-vr4120-mfix-vr4130-mfix-sb1-mfix4300-mr10k-cache-barrier=setting-mflush-func=func-mno-flush-func-mbranch-cost=num-mbranch-likely-mcompact-branches=policy-mno-fp-exceptions-mvr4130-align-msynci-mno-lxc1-sxc1-mno-madd4-mno-relax-pic-calls-mmcount-ra-address-mframe-header-opt
🧚 MMIX Options (MMIX Options) 🧚
-mlibfuncs-mepsilon-mabi=gnu-mabi=mmixware-mzero-extend-mknuthdiv-mtoplevel-symbols-melf-mbranch-predict-mbase-addresses-msingle-exit-mset-data-start=address-mset-program-start=address-mno-set-program-start
💜 MN10300 Options (MN10300 Options) 💜
-mmult-bug-mno-mult-bug-mam33-mam33-2-mam34-mtune=cpu-type-mno-return-pointer-on-d0-mno-crt0-mrelax-mno-liw-mno-setlb
👑 Moxie Options (Moxie Options) 👑
-meb-mel-mmul.x-mno-crt0
🌈 MSP430 Options (MSP430 Options) 🌈
Okay the MSP430 list has some seriously specific vibes 🔥
-msim-masm-hex-mmcu=name-mlarge-msmall-mrelax-mwarn-mcu-mwarn-devices-csv-mcode-region=where-mdata-region=where-muse-lower-region-prefix-msilicon-errata=name[,name...]-msilicon-errata-warn=name[,name...]-mhwmult=type-minrt-mtiny-printf-mmax-inline-shift=n
🫶 NDS32 Options (NDS32 Options) 🫶
-mbig-endian-mlittle-endian-EB-EL-mabi=name-mfloat-abi=name-mreduced-regs-mfull-regs-malways-align-malign-functions-mfp-as-gp-mcmov-mhw-abs-mext-perf-mext-perf2-mext-string-mext-dsp-mext-fpu-fma-mext-fpu-sp-mext-fpu-dp-mv3push-m16-bit-mvh-misr-vector-size=num-misr-secure=num-mcache-block-size=num-march=arch-mcpu=cpu-mconfig-fpu=num-mconfig-mul=type-mconfig-register-ports=kind-mcmodel=code-model-mctor-dtor-mrelax-mrelax-hint-msched-prolog-epilog-mno-ret-in-naked-func-malways-save-lp-munaligned-access-minline-asm-r15
💅 Nvidia PTX Options (Nvidia PTX Options) 💅
-m64-march=arch-misa=arch-march-map=arch-mptx=version-mmainkernel-moptimize-msoft-stack-msoft-stack-reserve-local=size-muniform-simt-mgomp
🦋 OpenRISC Options (OpenRISC Options) 🦋
-mboard=name-mhard-mul-mhard-div-msoft-mul-msoft-div-msoft-float-mhard-float-mdouble-float-munordered-float-mcmov-mror-mrori-msext-msfimm-mshftimm-mcmodel=code-model
🎀 PDP-11 Options (PDP-11 Options) 🎀
-mfpu-msoft-float-mac0-m40-m45-m10-mint32-mint16-msplit-munix-asm-mdec-asm-mgnu-asm-mlra
🧚 PowerPC Options 🧚
Soooo the PowerPC stuff lives somewhere else, bestie. Check out RS/6000 and PowerPC Options 💖
🌸 PRU Options (PRU Options) 🌸
-mmcu=mcu-minrt-mno-relax-mloop-mmul-mfillzero-mabi=variant
💜 RISC-V Options (RISC-V Options) 💜
The RISC-V list is a whole vibe, iykyk 🔥✨
-mbranch-cost=N-instruction-mabi=ABI-string-mfdiv-mdiv-mno-fence-tso-misa-spec=ISA-spec-string-march=[ISA|Profile|Profile_ISA|processor-string]-mcpu=processor-string-mtune=processor-string-mpreferred-stack-boundary=num-msmall-data-limit=N-bytes-msave-restore-mno-shorten-memrefs-mstrict-align-mscalar-strict-align-mno-vector-strict-align-mcmodel=medlow-mcmodel=medany-mcmodel=large-mexplicit-relocs-mrelax-mriscv-attribute-malign-data=type-mbig-endian-mlittle-endian-mstack-protector-guard=guard-mstack-protector-guard-reg=reg-mstack-protector-guard-offset=offset-mcsr-check-momit-leaf-frame-pointer-mmovcc-mno-inline-atomics-mno-inline-strlen-mno-inline-strcmp-mno-inline-strncmp-mstringop-strategy=strategy-mtls-dialect=desc-mtls-dialect=trad-mrvv-vector-bits=value-mrvv-max-lmul=value-madjust-lmul-cost-mmax-vectorization-mno-autovec-segment
🫶 RL78 Options (RL78 Options) 🫶
Last but not least, the RL78 crew 🦋💖
-msim-mallregs-mrelax-mes0-mmul=none-mmul=g13-mmul=g14-mmul=rl78-mcpu=g10-mcpu=g13-mcpu=g14-mcpu=rl78-mg10-mg13-mg14-mrl78-msave-mduc-in-interrupts
💅 RS/6000 and PowerPC Options
Okay bestie, this list is absolutely massive 💀 These are the flags for the PowerPC family, so they only matter when you're targeting that chip 🧚
-mcpu=cpu-type -mtune=cpu-type -mcmodel=code-model -mprofile-kernel -mpowerpc64 -maltivec -mpowerpc-gpopt -mpowerpc-gfxopt -mmfcrf -mpopcntb -mpopcntd -mfprnd -mcmpb -mhard-dfp -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc -maix64 -maix32 -m64 -m32 -mxl-compat -mpe -malign-power -malign-natural -msoft-float -mhard-float -mmultiple -mupdate -mavoid-indexed-addresses -mfused-madd -mbit-align -mbit-word -mstrict-align -mrelocatable -mrelocatable-lib -mlittle -mlittle-endian -mbig -mbig-endian -mdynamic-no-pic -msingle-pic-base -mprioritize-restricted-insns=priority -msched-costly-dep=dependence_type -minsert-sched-nops=scheme -mcall-aixdesc -mcall-eabi -mcall-freebsd -mcall-linux -mcall-netbsd -mcall-openbsd -mcall-sysv -mcall-sysv-eabi -mcall-sysv-noeabi -mtraceback=traceback_type -maix-struct-return -msvr4-struct-return -mabi=abi-type -msecure-plt -mbss-plt -msplit-patch-nops -mregnames -mlongcall -mpltseq -mtls-markers -mblock-move-inline-limit=num -mblock-compare-inline-limit=num -mblock-compare-inline-loop-limit=num -mblock-ops-unaligned-vsx -mstring-compare-inline-limit=num -misel -mvsx -mvrsave -mmulhw -mdlmzb -mprototype -msim -mmvme -mads -myellowknife -memb -meabi -msdata -msdata=opt -mreadonly-in-sdata -mvxworks -G num -mrecip -mrecip=opt -mno-recip -mrecip-precision -mveclibabi=type -mfriz -mpointers-to-nested-functions -msave-toc-indirect -mpower8-fusion -mcrypto -mhtm -mquad-memory -mquad-memory-atomic -mcompat-align-parm -mfloat128 -mfloat128-hardware -mgnu-attribute -mstack-protector-guard=guard -mstack-protector-guard-reg=reg -mstack-protector-guard-offset=offset -mprefixed -mpcrel -mmma -mrop-protect -mprivileged -mno-splat-word-constant -mno-splat-float-constant -mno-ieee128-constant -mno-warn-altivec-long
🌸 RX Options
Heads up: these are the RX chip flags, so they're only for RX targets 🎀
-m64bit-doubles -m32bit-doubles -fpu -nofpu -mcpu=name -mbig-endian-data -mlittle-endian-data -msmall-data-limit=N -msim -mas100-syntax -mrelax -mmax-constant-size=N -mint-register=N -mpid -mno-allow-string-insns -mjsr -mno-warn-multiple-fast-interrupts -msave-acc-in-interrupts -mlra
🧚 S/390 and zSeries Options
-mtune=cpu-type -march=cpu-type -mhard-float -msoft-float -mhard-dfp -mlong-double-64 -mlong-double-128 -mbackchain -mpacked-stack -msmall-exec -mmvcle -m64 -m31 -mdebug -mesa -mzarch -mhtm -mvx -mzvector -mtpf-trace -mtpf-trace-skip -mmain -mfused-madd -mno-fused-madd -mwarn-framesize=framesize -mwarn-dynamicstack -mstack-size=stack-size -mno-stack-size -mstack-guard=stack-guard -mno-stack-guard -mstack-protector-guard=guard -mstack-protector-guard-record -mhotpatch=pre-halfwords,post-halfwords -mno-pic-data-is-text-relative -mindirect-branch=choice -mindirect-branch-jump=choice -mindirect-branch-call=choice -mfunction-return=choice -mfunction-return-mem=choice -mfunction-return-reg=choice -mindirect-branch-table -mfentry -mrecord-mcount -mnop-mcount -mpreserve-args -munaliged-symbols
🍓 SH Options
-m1 -m2 -m2e -m2a -m2a-nofpu -m2a-single -m2a-single-only -m3 -m3e -m4 -m4-nofpu -m4-single -m4-single-only -m4-100 -m4-100-nofpu -m4-100-single -m4-100-single-only -m4-200 -m4-200-nofpu -m4-200-single -m4-200-single-only -m4-300 -m4-300-nofpu -m4-300-single -m4-300-single-only -m4-340 -m4-400 -m4-500 -m4a -m4al -m4a-nofpu -m4a-single -m4a-single-only -mb -ml -mdalign -mrelax -mbigtable -mbitops -mfmovd -mrenesas -mnomacsave -mieee -misize -minline-ic_invalidate -mprefergot -musermode -multcost=number -mdiv=strategy -mdivsi3_libfunc=name -mfixed-range=register-range -maccumulate-outgoing-args -matomic-model=atomic-model -mbranch-cost=num -mzdcbranch -mcbranch-force-delay-slot -mfsca -mfsrra -mpretend-cmove -mfdpic -mtas -mlra
🌈 Solaris 2 Options
-mclear-hwcap -mno-clear-hwcap -mimpure-text -mno-impure-text -gsctf
💜 SPARC Options
-mcpu=cpu-type -mtune=cpu-type -mcmodel=code-model -mmemory-model=mem-model -m32 -m64 -mptr32 -mptr64 -mapp-regs -mfaster-structs -mflat -mfpu -mhard-float -msoft-float -mhard-quad-float -msoft-quad-float -mstack-bias -mstd-struct-return -munaligned-doubles -muser-mode -mv8plus -mvis -mvis2 -mvis3 -mvis3b -mvis4 -mvis4b -mcbcond -mfmaf -mfsmuld -mpopc -msubxc -mfix-at697f -mfix-ut699 -mfix-ut700 -mfix-gr712rc
🫶 System V Options
-YP,paths -Ym,dir
🔥 V850 Options
-mlong-calls -mep -mprolog-function -mspace -mtda=n -msda=n -mzda=n -mv850 -mv850e3v5 -m850e2v4 -mv850e2v3 -mv850e2 -mv850e1 -mv850es -mv850e -mdisable-callt -mrelax -mlong-jumps -msoft-float -mhard-float -mloop -mrh850-abi -mghs -mgcc-abi -m8byte-align -mbig-switch -mapp-regs -msmall-sld -mno-strict-align -mjump-tables-in-data-section
🦋 VAX Options
-munix -mgnu -md -md-float -mg -mg-float -mlra -mvaxc-alignment -mqmath
✨ Visium Options
-mdebug -msim -mfpu -mhard-float -msoft-float -mcpu=cpu-type -mtune=cpu-type -msv-mode -muser-mode
👑 VMS Options
-mvms-return-codes -mdebug-main=prefix -mmalloc64 -mpointer-size=size
💖 VxWorks Options
-mrtp -msmp -mvthreads -non-static -Bstatic -Bdynamic -Xbind-lazy -Xbind-now
💅 x86 Options
-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 -mieee-fp -mrtd -malign-double -mpreferred-stack-boundary=num -mincoming-stack-boundary=num -mcld -mcx16 -msahf -mmovbe -mcrc32 -mmwait -mrecip -mrecip=opt -mvzeroupper -mstv -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 -mavx512cd -mavx512vl -mavx512bw -mavx512dq -mavx512ifma -mavx512vbmi -msha -maes -mpclmul -mfsgsbase -mrdrnd -mf16c -mfma -mpconfig -mwbnoinvd -mptwrite -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 -mgfni -mvaes -mwaitpkg -mshstk -mmanual-endbr -mcet-switch -mforce-indirect-call -mavx512vbmi2 -mavx512bf16 -menqcmd -mvpclmulqdq -mavx512bitalg -mmovdiri -mmovdir64b -mavx512vpopcntdq -mavx512vnni -mprfchw -mrdpid -mrdseed -msgx -mavx512vp2intersect -mserialize -mtsxldtrk -mamx-tile -mamx-int8 -mamx-bf16 -muintr -mhreset -mavxvnni -mamx-fp8 -mavx512fp16 -mavxifma -mavxvnniint8 -mavxneconvert -mcmpccxadd -mamx-fp16 -mprefetchi -mraoint -mamx-complex -mavxvnniint16 -msm3 -msha512 -msm4 -mapxf -musermsr -mavx10.1 -mavx10.2 -mamx-avx512 -mamx-tf32 -mmovrs -mamx-movrs -mavx512bmm -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 -mstack-arg-probe -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 -mrecord-return -mfentry-name=name -mfentry-section=name -mskip-rax-setup -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 -mtls-dialect=type -mrelax-cmpxchg-loop -mindirect-branch=choice -mfunction-return=choice -mindirect-branch-register -mharden-sls=choice -mindirect-branch-cs-prefix -mapx-inline-asm-use-gpr32 -mgather -mscatter -mneeded -mno-direct-extern-access -munroll-only-small-loops -mdispatch-scheduler -mlam=choice
🎀 x86 Windows Options
See Cygwin and MinGW Options.
🌷 Xstormy16 Options
-msim
🌙 Xtensa Options
-mconst16 -mforce-no-pic -mno-serialize-volatile -mtext-section-literals -mauto-litpools -mno-target-align -mlongcalls -mabi=abi-type -mextra-l32r-costs=cycles -mstrict-align
🧁 zSeries Options
See S/390 and zSeries Options.
✨ Options Controlling the Kind of Output
Okay, so compilation 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 into just one assembler input file. Then each assembler input file makes an object file, and linking mashes all the object files together (the ones just compiled and the ones you passed in) into one executable file 🔥
The file name suffix decides what kind of compilation happens for each input file 💅
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 capital M 🙈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) 🌸
okay bestie, this is the file-suffix cheat sheet 💅 gcc looks at the ending of each filename to decide what kind of source it's dealing with 🎀
- C++ source that must be preprocessed 🌸:
file.cc,file.cp,file.cxx,file.cpp,file.CPP,file.c++,file.C. Heads up: in.cxx, the last two letters must both be a literal lowercasex, and.Cmeans a literal capitalC. - Objective-C++ source that must be preprocessed 🦋:
file.mm,file.M. - Objective-C++ source that should not be preprocessed 🧚:
file.mii. - C++ header file 💜, which gets turned into a precompiled header or an Ada spec:
file.hh,file.H,file.hp,file.hxx,file.hpp,file.HPP,file.h++,file.tcc. - Fixed form Fortran that should not be preprocessed 🍓:
file.f,file.for,file.ftn,file.fi. - Fixed form Fortran that must be preprocessed (with the traditional preprocessor) ✨:
file.F,file.FOR,file.fpp,file.FPP,file.FTN. - Free form Fortran that should not be preprocessed 🌈:
file.f90,file.f95,file.f03,file.f08,file.fii. - Free form Fortran that must be preprocessed (with the traditional preprocessor) 👑:
file.F90,file.F95,file.F03,file.F08. - COBOL source code 💾:
file.cob,file.COB,file.cbl,file.CBL. - Go source code 🐹:
file.go. - D source code 🔥:
file.d. - D interface file ⭐:
file.di. - D documentation code (Ddoc) 📖:
file.dd. - Ada source code with a library unit declaration 🌸, meaning 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). These files are also called specs:
file.ads. - Ada source code with a library unit body 🦋, meaning a subprogram or package body. These files are also called bodies:
file.adb. - Assembler code 🫶:
file.s. - Assembler code that must be preprocessed 💅:
file.S,file.sx. - other 🎀: an object file that gets fed straight into linking. Any filename with no recognized suffix is treated this way.
You can also name the input language yourself with the -x option, so gcc doesn't have to guess from the suffix 🧠
-x language,--language=language,--language language✨ — explicitly sets the language for the input files that come after it, instead of letting the compiler pick a default from the filename suffix. This applies to every following input file until the next-xoption shows up. The possible values for language are:
c c-header cpp-output
c++ c++-header c++-system-header c++-user-header c++-cpp-output
c++-system-module
objective-c objective-c-header objective-c-cpp-output objc-cpp-output
objective-c++ objective-c++-header objective-c++-cpp-output
objc++-cpp-output
assembler assembler-with-cpp
ada adascil adawhy
cobol
d
f77 f77-cpp-input f95 f95-cpp-input
go
modula-2 modula-2-cpp-output
rust
algol68
lto⚠️ bestie,-xdoes not pick a language standard for you 🙈 For example,-x f77may also need-std=legacyfor some older source code.
-x none💀 — turns off any language specification, so the files after it get handled by their filename suffixes, exactly like-xwas never used at all.
If you only want some stages of compilation, you can use -x (or filename suffixes) to say where gcc should start, and one of -c, -S, or -E to say where it should stop 🛑 Heads up, some combos (like -x cpp-output -E) make gcc do absolutely nothing 😭
-c,--compile🌷 — compiles or assembles the source files but does not link. The linking stage just doesn't happen. The final output is 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 that don't need compiling or assembling get quietly ignored.
-S,--assemble🌙 — stops after the compilation proper and does not assemble. The output is an assembler code file for each input file that isn't already assembler code.
By default, the assembler file name for a source file is made by swapping .c, .i, etc. for .s.
Input files that don't need compiling get ignored.
-E,--preprocess🔮 — stops after preprocessing and doesn't run the compiler proper. The output is preprocessed source code, sent straight to standard output.
Input files that don't need preprocessing get ignored.
-o file,--output=file,--output file🎯 — puts the primary output in file. This works for whatever you're making, whether that's an executable, an object file, an assembler file, or preprocessed C.
If you don't specify -o, the defaults are: an executable goes in a.out, the object file for source.suffix goes in source.o, its assembler file goes in source.s, a precompiled header file goes in source.suffix.gch, and all the preprocessed C source goes to standard output 🧁
Even though -o only names the primary output, it also affects how the auxiliary and dump outputs get named. Check the examples below! Unless overridden, both auxiliary and dump outputs land in the same directory as the primary output. For auxiliary outputs, the input file's suffix gets replaced with the suffix of the auxiliary output's file type. For dump outputs, the dump file's suffix gets tacked onto the input file's 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 concatenated with a dash in between 💖
gcc -c foo.c ...This will use foo.o as the primary output and put the aux outputs and dumps right next to it, for example the aux file foo.dwo for -gsplit-dwarf, and the dump file foo.c.???r.final for -fdump-rtl-final.
If a non-linker output file is explicitly specified, aux and dump files by default take the same base name:
gcc -c foo.c -o dir/foobar.o ...This will name the aux outputs dir/foobar.* and the dump outputs dir/foobar.c.*.
A linker output does things a little differently and prefixes 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 the base name with the single input:
gcc foo.c -o dir/foo ...In that case the aux outputs are named dir/foo.* and the dump outputs are named dir/foo.c.*.
You can tweak the location and names of auxiliary and dump outputs with the options -dumpbase, -dumpbase-ext, -dumpdir, -save-temps=cwd, and -save-temps=obj 🛠️
-dumpbase dumpbase,--dumpbase dumpbase🎀 — sets the base name for auxiliary and dump output files. It does not change the name of the primary output file. Intermediate outputs, when they get preserved, don't count as primary outputs. They count as auxiliary outputs instead:
gcc -save-temps -S foo.cThis saves the (no longer temporary) preprocessed file in 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 (now an intermediate, so 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 one is explicitly specified. Dump output files, like the ones requested by -fdump-* options, keep the input name's suffix. Aux output files, like the ones requested by other non-dump options (for example -save-temps, -gsplit-dwarf, -fcallgraph-info), drop it.
You can get similar suffix differentiation between dump and aux outputs for an explicitly given -dumpbase basename.suf by also specifying -dumpbase-ext .suf 🦋
If dumpbase is explicitly specified with any directory component, any dumppfx specification (like -dumpdir or -save-temps=*) gets ignored. Instead of appending to it, dumpbase fully overrides it:
gcc foo.c -c -o dir/foo.o -dumpbase alt/foo \
-dumpdir pfx- -save-temps=cwd ...This creates auxiliary and dump outputs named alt/foo.*, ignoring the dir/ in -o, the ./ prefix implied by -save-temps=cwd, and the pfx- in -dumpdir.
When -dumpbase is specified in a command that compiles multiple inputs, or one that compiles and then links, it can be combined with dumppfx, as described under -dumpdir. Then each input file 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. It also avoids overwriting the aux and dump outputs by using the dumpbase as a prefix, creating aux and dump outputs 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, and default values get computed instead:
gcc -c foo.c -o dir/foobar.o -dumpbase " ...This will name the aux outputs dir/foo.* and the dump outputs dir/foo.c.*. Notice how their basenames come from the input name, but the directory still defaults to the output's directory.
An empty-string dumpbase does not stop the output basename from being used for outputs during linking:
gcc foo.c bar.c -o dir/foobar -dumpbase " -flto ...The compilation of the source files will name the aux outputs dir/foo.* and dir/bar.*, and the dump outputs dir/foo.c.* and dir/bar.c.*. LTO recompilation during linking will use dir/foobar. as the prefix for dumps and aux files 🌈
-dumpbase-ext auxdropsuf,--dumpbase-ext auxdropsuf— the suffix-dropper for aux files 🦋
Okay so when gcc is forming the name of an auxiliary output file (not a dump file, those are different, bestie), it drops the trailing auxdropsuf from dumpbase before it tacks on any suffixes. If you don't specify it, it defaults to the suffix of a default dumpbase. That means the suffix of the input file when -dumpbase isn't on the command line, or when dumpbase is combined with dumppfx. Literally so sneaky, but it works 💅
gcc foo.c -c -o dir/foo.o -dumpbase x-foo.c -dumpbase-ext .c ...This one is giving main character energy 👑 It creates dir/foo.o as the main output, puts the auxiliary outputs in dir/x-foo.* (using the location of the primary output), and drops the .c suffix from the dumpbase. Dump outputs keep the suffix though, so you get dir/x-foo.c.* ✨
This option gets ignored if it doesn't match the suffix of a specified dumpbase, except as an alternative to the executable suffix when gcc is appending the linker output base name to dumppfx. Here's how that slays:
gcc foo.c bar.c -o main.out -dumpbase-ext .out ...This creates main.out as the primary output. It also avoids overwriting the auxiliary and dump outputs by using the executable name minus auxdropsuf as a prefix. So you get auxiliary outputs named main-foo.* and main-bar.*, and dump outputs named main-foo.c.* and main-bar.c.* 🌈
-dumpdir dumppfx,--dumpdir dumppfx— the prefix princess 🎀
When gcc forms the name of an auxiliary or dump output file, it uses dumppfx as a prefix. Iconic.
gcc -dumpdir pfx- -c foo.c ...This creates foo.o as the primary output, with auxiliary outputs named 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 you get pfx-foo.c.* 🧚
If you want dumppfx to act as a directory name, it has to end with a directory separator. Don't skip this part, it's lowkey important 🙈
gcc -dumpdir dir/ -c foo.c -o obj/bar.o ...This creates obj/bar.o as the primary output, and auxiliary outputs named 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: dir/bar.c.* 💜
By default, dumppfx is 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 more than one of these, the last one prevails:
gcc -dumpdir pfx- -c foo.c -save-temps=obj ...This one outputs foo.o, with auxiliary outputs named foo.*, because -save-temps=* overrides the dumppfx from the earlier -dumpdir option. It doesn't matter that =obj is the default for -save-temps, or that the output directory is implicitly the current directory. Dump outputs are named foo.c.* 🍓
When you compile from multiple input files and specify -dumpbase, the dumpbase (minus an auxdropsuf suffix) plus a dash gets appended to the dumppfx. This happens whether that dumppfx is explicit or defaulted. If the dumpbase has any directory components, it overrides the dumppfx instead of getting appended. This way every compilation gets its own differently-named aux and dump outputs, which is so organized 🫶
gcc foo.c bar.c -c -dumpdir dir/pfx- -dumpbase main ...This sends auxiliary dumps to dir/pfx-main-foo.* and dir/pfx-main-bar.*, appending dumpbase- to dumppfx. Dump outputs keep the input file suffix: dir/pfx-main-foo.c.* and dir/pfx-main-bar.c.*, respectively.
Now contrast that with a single-input compilation:
gcc foo.c -c -dumpdir dir/pfx- -dumpbase main ...Applying -dumpbase to a single source 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 goes through the dumpbase- transformation above. For example, that's the compilation of foo.c and bar.c from before, just without -c. If you specify neither -dumpdir nor -dumpbase, the linker output base name gets appended to the default dumppfx instead, plus a dash. That base name has the auxdropsuf removed if you specified it, or the executable suffix removed otherwise. Now, careful, because this is where it gets different:
gcc foo.c bar.c -dumpdir dir/pfx- -o main ...This one does not append the output name main to dumppfx, because -dumpdir was explicitly specified. The idea is that an explicit dumppfx can include the output name as part of the prefix, if you want that. Only an explicitly specified -dumpbase would get combined with it, so gcc doesn't just throw away a meaningful option 🦋
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 earlier, but it's different with an explicit -dumpdir that stops the combination. That's true even if -save-temps=* overrides it:
gcc foo.c -dumpdir alt/pfx- -o dir/main.exe -save-temps=cwd ...Here the auxiliary outputs are foo.*, and the dump outputs are foo.c.*. They end up in the current working directory, as requested by -save-temps=cwd 🌸
Okay, here's the whole thing summed up in a slightly imprecise but super intuitive way. The primary output name gets split into a directory part and a basename part. The dumppfx is set to the directory part, unless -dumpdir or -save-temps=* overrides it. The dumpbase is set to the basename part, unless -dumpbase overrides it. If there are multiple inputs or you're linking, this dumpbase can combine with dumppfx and get 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 because they keep the suffix from dumpbase 💖
When it comes to auxiliary and dump outputs created during LTO recompilation, here's the tea. 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 inputs), and even in cases where the combination wouldn't normally get used. The trailing period replaces the compiler-added dash, if there is one. Since this program is involved in linking, it doesn't normally get any -dumpbase or -dumpbase-ext, and it ignores them if it does 💅
When lto-wrapper runs sub-compilers, it appends the LTO stage names to the dumppfx it received. It makes sure the dumppfx contains a directory component so that it overrides any -dumpdir. Then it passes that along as -dumpbase to the sub-compilers 🧚
-v,--verbose— the show-your-work option 🔥
This prints (on standard error output) the commands executed to run the stages of compilation. It also prints the version number of the compiler driver program, plus the version of the preprocessor and the compiler proper. Very receipts-y 🧾
-###— the "what would you run" option 🙈
This is like -v, except the commands are not executed. Arguments get quoted unless they only contain alphanumeric characters or "./-_". It's super useful for shell scripts that want to capture the command lines the driver generates, so they can keep track of what's going on behind the scenes ✨
--help— the menu, but make it cute 💜
This prints (on the standard output) a description of the command-line options that gcc understands. If you also specify -v, then --help gets passed on to the various processes gcc invokes, so each one can show you the command-line options it accepts. And if you specify -Wextra (before the --help option), command-line options that have no documentation attached are shown too. Undocumented options get to come to the party 🎉
--target-help— the target-specific menu 🌈
This prints (on the standard output) a description of the target-specific command-line options for each tool. For some targets, extra target-specific information may also be printed 🦋
--help={class|[^]qualifier}[,...]— the filtered menu, bestie 🎀
This prints (on the standard output) a description of the command-line options the compiler understands that fit into all of the specified classes and qualifiers. Here are the supported classes:
optimizers— shows every optimization option the compiler supports ⭐warnings— shows every option that controls the warning messages the compiler produces 🔥target— shows target-specific options. Unlike--target-help, though, target-specific options of the linker and assembler are not displayed. Those tools don't currently support the extended--help=syntax, so they get left out 🙈params— shows the values the--paramoption recognizes 💅language— shows the options supported for language, where language is the name of one of the languages supported in this version of GCC. If an option is supported by all languages, you need to pick thecommonclass to see it 👑common— shows the options that are common to all languages 🫶
Here are the supported qualifiers:
undocumented— only shows the options that are undocumented 🌸joined— shows options that take an argument appearing after an equal sign in the same continuous piece of text, like--help=target💖separate— shows options that take an argument appearing as a separate word after the original option, like-o output-file🧚
So if you want every undocumented target-specific switch the compiler supports, you'd type:
--help=target,undocumentedYou can invert the sense of a qualifier by putting the ^ character in front of it. For example, to display all binary warning options (the 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. Don't be that person 🙅♀️
Combining several classes is possible, but it usually restricts the output so much that there's nothing to display. There's one case where it totally works, though: 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 (the main character always wins) 👑
If you slip -Q in before --help= on the command line, the text --help= spits out gets a total glow-up ✨. Instead of describing the options, it tells you whether each one is enabled, disabled, or set to a specific value 💖. This only works if the compiler actually knows that value at the point where --help= shows up 🫶.
Here's 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 reacts to whatever command-line options came before it, so you can totally find out which optimizations are on at -O2 with:
-Q -O2 --help=optimizersOr if you want the receipts 🧾, you can figure out which binary optimizations are enabled by -O3 by running:
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— Shows the version number and copyrights of the GCC you invoked 🌸.-pass-exit-codes,--pass-exit-codes— Okay, so normallygccexits with the code of 1 if any phase of the compiler returns a non-success return code 😬. With this flag, it instead returns the numerically highest error from any phase that reported an error 👑. The C, C++, and Fortran front ends return 4 if they hit an internal compiler error 💀.-pipe,--pipe— Uses pipes instead of temporary files to pass stuff between the different stages of compilation 🧚.
This one is a little risky bestie 🙈. It fails to work on some systems where the assembler can't read from a pipe. The GNU assembler has no trouble though ✨.
-wrapper— Invokes all subcommands under a wrapper program 🎀. You pass the wrapper's name and its parameters as a comma separated list 💅.
gcc -c t.c -wrapper gdb,--argsThis runs all the subprograms of gcc under gdb --args, so the invocation of cc1 becomes gdb --args cc1 .... 🍓.
-ffile-prefix-map=old=new— When you compile files living in the directoryold, any references to them in the compilation result get recorded as if those files lived innewinstead 🦋. Specifying this is the same as specifying all the individual-f*-prefix-mapoptions 💜. It's a great way to make reproducible builds that don't care about location 🌈. 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— Normally, for the-f*-prefix-mapoptions, the old prefix gets compared against the filename that would be referenced in the result using textual comparison of the prefixes 📝. That comparison ignores character case on case insensitive filesystems, and treats slashes and backslashes as equal on DOS based filesystems 🫠.-fcanon-prefix-mapmakes those comparisons happen on canonicalized paths ofoldand the referenced filename ✨.-fplugin=name.so— Loads the plugin code in the filename.so, which is assumed to be a shared object that the compiler willdlopen'd 🔌. The base name of the shared object file 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, generates the matching Ada specs 🌸.-fada-spec-parent=unit— Works together with-fdump-ada-spec[-slim]above, and generates Ada specs as child units of the parentunit👑.-fdump-go-spec=file— For input files in any language, generates matching Go declarations infile🐹. This makes "const", "type", "var", and "func" declarations, which can be a super useful way to start writing a Go interface to code written in some other language 🫶.@file— Reads command-line options fromfile📜. The options read get inserted in place of the original@fileoption 🦋.- If
filedoes not exist, or can't be read, then the option is treated literally and does not get removed 🙈. - Options in
fileare separated by whitespace 💖. A whitespace character can be included in an option by surrounding the entire option in either single or double quotes 🎀. - Any character (including a backslash) can be included by prefixing the character to be included with a backslash 🌈.
- The file may itself contain additional
@fileoptions, and any such options get processed recursively 🔁.
- If
✨ 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 🧚, and C++20 module interface units sometimes use .ixx, .cppm, .cxxm, .c++m, or .ccm 🌸.
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 😭. That's where g++ comes in 💖. It's a program that calls GCC and automatically specifies linking against the C++ library 🔗. 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'd 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,--ansi— In C mode, this is the same as-std=c90. In C++ mode, it's the same as-std=c++98🌸.-std=— Determines the language standard 👑. This option is currently only supported when compiling C or C++ 🫶.
The compiler can accept several base standards, like c90 or c++98, plus GNU dialects of those standards, like gnu90 or gnu++98 ✨. When you specify a base standard, 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, like the "asm" and "typeof" keywords 🙈. It does not turn off other GNU extensions that have no meaning in ISO C90, like omitting the middle term of a "?:" expression 🦋.
On the other hand, when you specify a GNU dialect of a standard, every feature the compiler supports gets 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 figure out which features are GNU extensions for 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/projects/c-status.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, floating-point issues (mainly, but not entirely, relating to optional C11 features from Annexes F and G), and 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 (published in 2024) 🌈. The namec2xis deprecated 🙈.c2y— The next version of the ISO C standard, still under development 🚧. The support for this version is experimental and incomplete 🧪.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 ✨.gnu23,gnu2x— GNU dialect of ISO C23 👑. This is the default for C code 💖. The namegnu2xis deprecated 🙈.gnu2y— The next version of the ISO C standard, still under development, plus GNU extensions 🚧. The 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 🙈.
Okay, the -std list keeps going, and bestie, these are the ones that get a little spicy 🌶️
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. The namegnu++1zis deprecated.c++20,c++2a— 👑 The 2020 ISO C++ standard plus amendments. C++20 modules support is still experimental and needs to be enabled with-fmodulesoption. The namec++2ais deprecated.gnu++20,gnu++2a— 🔥 GNU dialect of-std=c++20. This is the default for C++ code. C++20 modules support is still experimental and needs to be enabled with-fmodulesoption. The namegnu++2ais deprecated.c++23,c++2b— 🧪 The 2023 ISO C++ standard plus amendments (published in 2024). Support is experimental, and could change in incompatible ways in future releases. The namec++2bis deprecated.gnu++23,gnu++2b— 🧪 GNU dialect of-std=c++23. Support is experimental, and could change in incompatible ways in future releases. The namegnu++2bis deprecated.c++2c,c++26— 🔮 The next revision of the ISO C++ standard, planned for 2026. Support is highly experimental, and will almost certainly change in incompatible ways in future releases.gnu++2c,gnu++26— 🔮 GNU dialect of-std=c++2c. Support is highly experimental, and will almost certainly change in incompatible ways in future releases.-aux-info filename— 📝 Dumps prototyped declarations for every function declared and/or defined in a translation unit, header files included, into the file you name. It's silently ignored in any language other than C.
Besides the declarations, the file leaves comments that tell you where each one 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 or O for old. 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 and placed after the declaration. 🫶
-fno-asm— 🙅♀️ Stopsasm,inlineandtypeoffrom being treated as keywords, so you 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 this switch doesn't touch it. You might want -fno-gnu-keywords instead, which turns off 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), this switch only affects asm, since typeof is a standard keyword in ISO C23. 💅
-fno-builtin,-fno-builtin-function— 🚫 Don't recognize built-in functions that do not begin with__builtin_as prefix.
Normally GCC generates special code for certain built-in functions so they run more efficiently. For instance, calls to alloca can turn into single instructions that adjust the stack directly, and calls to memcpy can become inline copy loops. The result is often both smaller and faster, but the function calls don't show up as calls anymore. That means you can't set a breakpoint on them, and you can't change what the functions do by linking against a different library. 🙃 Also, once a function is recognized as built-in, GCC may use what it knows about that function to warn you about problems with calls to it, or to generate more efficient code, even if the result still contains calls to that function. For example, 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 the built-in function is disabled. function must not begin with __builtin_. If you name a function that isn't built-in in this version of GCC, this option is ignored. There is no corresponding -fbuiltin-function option. If you want to enable built-in functions selectively 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— 🤷♀️ Allows conditional expressions with mismatched types in the second and third arguments. The value of such an expression is void. This option is not supported for C++.-ffreestanding— 🛸 Asserts that compilation targets a freestanding environment. This implies-fno-builtin. A freestanding environment is one where 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— 🧠 Enables parsing of function definitions marked with__GIMPLE. It's an experimental feature that allows unit testing of GIMPLE passes.-fgnu-tm— 🧵 When-fgnu-tmis specified, 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 whose interface may change in future versions of GCC, as the official specification changes. Heads up: not all architectures are supported for this feature.
For more information on GCC's support for transactional memory,
⚠️ The transactional memory feature is not supported with non-call exceptions (-fnon-call-exceptions).
-fgnu89-inline— 🕰️ 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 (aka 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— 🏠 Asserts that compilation targets a hosted environment. This 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— 🫠 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— 🪟 Accepts some non-standard constructs used in Microsoft header files.
In C++ code, this lets member names in structures be similar to previous type declarations:
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.
-fpermitted-flt-eval-methods=style— 🎯 ISO/IEC TS 18661-3 defines new permissible values forFLT_EVAL_METHODthat indicate 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. These new values are a superset of those permitted under C99/C11, which doesn't specify the meaning of other positive values ofFLT_EVAL_METHOD. So code that conforms to C11 may not have been written expecting the possibility of the new values.
-fpermitted-flt-eval-methods decides whether the compiler should allow only the values of FLT_EVAL_METHOD specified in C99/C11, or the extended set of values specified in ISO/IEC TS 18661-3.
style is either c11 or ts-18661-3, as appropriate.
The default in a standards compliant mode (-std=c11 or similar) is -fpermitted-flt-eval-methods=c11. The default in a GNU dialect (-std=gnu11 or similar) is -fpermitted-flt-eval-methods=ts-18661-3.
The -fdeps-* options are used to extract structured dependency information for a source. This involves figuring out what resources provided by other source files will be required to compile the source, as well as what resources the source itself provides. This information can be used to add required dependencies between compilation rules of dependent sources based on their contents, rather than requiring that such information be reflected within the build tools as well. 🧩
-fdeps-file=file— 📂 Where to write structured dependency information.-fdeps-format=format— 📐 The format to use for structured dependency information.p1689r5is the only supported format right now. Note that when this argument is specified, the output of-MFis stripped of some information (namely C++ modules) so that it doesn't use extended makefile syntax that most tools don't understand.-fdeps-target=file— 🎯 Analogous to-MTbut for structured dependency information. This indicates the target that will ultimately need any required resources and provide any resources extracted from the source that may be required by other sources.-fplan9-extensions— 🐹 Accepts some non-standard constructs used in Plan 9 code.
This enables -fms-extensions, permits passing pointers to structures with anonymous fields to functions that expect pointers to elements of the type of the field, and permits referring to anonymous fields declared using a typedef. This is only supported for C, not C++. 💜
-fsigned-bitfields,-funsigned-bitfields,-fno-signed-bitfields,-fno-unsigned-bitfields— okay so these decide if a bit-field is signed or unsigned, but only when your declaration doesn't already saysignedorunsigned🎀. By default a bit-field is signed, and honestly that's the consistent move because basic integer types likeintare signed too ✨.-fsigned-char— letcharbe signed, just likesigned char💖. This is the same thing as-fno-unsigned-char, which is the negative form of-funsigned-char. And-fno-signed-charis the same as-funsigned-char🫶.-funsigned-char— flip it and letcharbe unsigned, likeunsigned char🦋. Every machine has its own default for whatcharshould be: either likeunsigned charor likesigned char🌈.- Ideally a portable program always uses
signed charorunsigned charwhenever it depends on the signedness of an object 💅. - But a ton of programs were written with plain
charand 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 👑. charis always a distinct type from each ofsigned charorunsigned char, even though it behaves exactly like one of those two 🧚.
- Ideally a portable program always uses
-fstrict-flex-arrays(C and C++ only),-fstrict-flex-arrays=level(C and C++ only) — this controls when the trailing array of a structure counts as a flexible array member when you're accessing its elements 🌸. The value oflevelsets how strict it is 💜.-fstrict-flex-arraysis the same as-fstrict-flex-arrays=3, which is the strictest 🔥. A trailing array only counts as flexible when it's declared as a flexible array member per C99 and onwards 📜.- The negative form
-fno-strict-flex-arraysis the same as-fstrict-flex-arrays=0, which is the least strict 🍓. In this case, all trailing arrays of structures are treated as flexible array members 🌈. - Levels 1 and 2 live in between 0 and 3. They exist to support older code that uses the GCC zero-length array extension (
[0]) or one-element arrays ([1]) as flexible array members 🙈. At level 1, the trailing array counts as flexible when it's declared as either[],[0], or[1]⭐. At level 2, it counts when it's declared as either[]or[0]🦋. - You can control this for one specific trailing array field of a structure with the variable attribute "strict_flex_array" attribute 💅.
- The
-fstrict_flex_arraysoption interacts with the-Wstrict-flex-arraysoption 🫶.
-fsso-struct=endianness— sets the default scalar storage order of structures and unions to the endianness you choose 🎀. The accepted values arebig-endian,little-endian, andnative, which is the native endianness of the target and the default 💖. This option is not supported for C++ 💀.
Warning: the -fsso-struct switch makes GCC 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 is all about the command-line options that only matter for C++ programs 💜. Good news: you can use most of the GNU compiler options no matter what language your program is in 🌸. For example, you could compile a file firstClass.C like this 🧚:
g++ -g -fstrict-enums -O -c firstClass.CIn this example, only -fstrict-enums is meant only for C++ programs 👑. You can use the other options with any language GCC supports 🫶.
Some options for compiling C programs, like -std, are also relevant for C++ programs ⭐.
Here's a list of options that are only for compiling C++ programs 🌈:
--compile-std-module— this one builds the compiled module interfaces for the<bits/stdc++.h>header unit and thestdandstd.compatmodules before compiling any source files you explicitly pass on the command line 🦋. It's meant for building simple programs that useimport std;with a single command 💅.-fabi-version=n— use versionnof 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 across G++ versions as ABI bugs get fixed 😭.
- Version 1 is the version of the C++ ABI that first showed up in G++ 3.2 🌸.
- Version 2 is the version that first showed up in G++ 3.4, and it was the default all the way through G++ 4.9 👑.
- Version 3 fixes an error in mangling a constant address used as a template argument 💖.
- Version 4, first seen in G++ 4.5, implements a standard mangling for vector types 🧚.
- Version 5, first seen in G++ 4.6, fixes 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 seen in G++ 4.7, fixes 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 seen in G++ 4.8, treats
nullptr_tas a builtin type and fixes the mangling of lambdas in default argument scope 🍓. - Version 8, first seen in G++ 4.9, fixes the substitution behavior of function types with function-cv-qualifiers 🫶.
- Version 9, first seen in G++ 5.2, fixes the alignment of
nullptr_t⭐. - Version 10, first seen in G++ 6.1, adds mangling of attributes that affect type identity, like ia32 calling convention attributes (e.g.
stdcall) 🦋. - Version 11, first seen in G++ 7, fixes the mangling of
sizeof...expressions and operator names 🔥. For multiple entities with the same name within a function, declared in different scopes, the mangling now changes starting with the twelfth occurrence 😭. It also implies-fnew-inheriting-ctors🌸. - Version 12, first seen in G++ 8, fixes 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 seen in G++ 8.2, fixes that accidental change from version 12 💖.
- Version 14, first seen in G++ 10, fixes the mangling of the
nullptrexpression 🧚. - Version 15, first seen in G++ 10.3, fixes the G++ 10 ABI tag regression 💅.
- Version 16, first seen in G++ 11, changes the mangling of
__alignof__so it's distinct fromalignof, plus dependent operator names 🌈. - Version 17, first seen in G++ 12, fixes the layout of classes that inherit from aggregate classes with default member initializers in C++14 and up 🎀.
- Version 18, first seen in G++ 13, fixes manglings of lambdas that have additional context ✨.
- Version 19, first seen in G++ 14, fixes manglings of structured bindings to include ABI tags, handles cv-qualified
[[no_unique_address]]members, and adds mangling of C++20 constraints on function templates 🔥. - Version 20, first seen in G++ 15, fixes manglings of lambdas in static data member initializers 🌸.
- Version 21, first seen in G++ 16, fixes unnecessary captures in
noexceptlambdas (c++/119764), the layout of a base class with all explicitly defaulted constructors (c++/120012), and the mangling of class and array objects with implicitly zero-initialized non-trailing subobjects (c++/121231) 👑. - 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 picks which ABI version to use for that alias 💖.- With
-fabi-version=0(the default), this defaults to 13 (GCC 8.2 compatibility) 🧚. If another ABI version is explicitly selected, it defaults to 0 💅. - For compatibility with GCC versions 3.2 through 4.9, use
-fabi-compat-version=2🌈. - If this option isn't provided but
-Wabi=nis, that version is used for compatibility aliases 🎀. If this option is provided along with-Wabi(without the version), the version from this option is used for the warning ✨.
- With
-fno-access-control— turns off all access checking 🔥. This switch is mainly useful for working around bugs in the access control code 💀.-faligned-new,-faligned-new=alignment— enables support for C++17newof types that need more alignment thanvoid* ::operator new(std::size_t)provides 🌸. A numeric argument like-faligned-new=32can specify how much alignment (in bytes) that function provides 👑. But honestly, few users will need to override the default ofalignof(std::max_align_t)🫶.- This flag is enabled by default for
-std=c++17⭐.
- This flag is enabled by default for
✨ OPTIONS ✨ (continued)
-fno-assume-sane-operators-new— okay so, the C++ standard lets you swap out the globalnew,new[],delete, anddelete[]operators 🧚, but ngl most programs don't bother and just use the built-in ones. The standard also lets the compiler skip those calls when they come fromnewordeleteexpressions (and by extension the same is assumed if__builtin_operator_newor__builtin_operator_deletefunctions are used). This option gives you control over some optimizations around calls to those operators. With-fassume-sane-operators-new-delete, GCC may assume that calls to the replaceable global operators from new or delete expressions, or from__builtin_operator_newor__builtin_operator_deletecalls, don't read or modify any global variables or variables whose address could escape to the operators (global state; except forerrnofor thenewandnew[]operators). This lets most optimizations happen across those calls, and it's something the implementation-provided operators satisfy unlessmallocimplementation details are observable in the code ormallochooks are used. It might not be satisfied if a program replaces those operators. This behavior is enabled by default 💜. With-fno-assume-sane-operators-new-delete, GCC must assume all these calls (whether from new or delete expressions or called directly) may read and write global state unless proven otherwise (e.g. when GCC compiles their implementation). Use this option if those operators are or may be replaced and your code needs to expect that behavior 🫶.-fchar8_t,-fno-char8_t— ooh, this one's giving C++20 realness 🌸. It enables support forchar8_t, including a brand newchar8_tfundamental type, changes to the types of UTF-8 string and character literals, new signatures for user-defined literals, associated standard library updates, and the new__cpp_char8_tand__cpp_lib_char8_tfeature test macros.
This option also lets you overload functions for ordinary strings 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 #2It also 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;⚠️ bestie, heads up: the change to the types of UTF-8 string and character literals breaks things that were fine under ISO C++11 and later. The code below 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— the vibe here is double-checking 🔍. It makes sure the pointer returned byoperator newis non-null before you try to modify the storage allocated. This check is normally unnecessary, because the C++ standard saysoperator newonly returns 0 if it is declaredthrow(). In that case the compiler always checks the return value, even without this option. In all other cases, whenoperator newhas a non-empty exception specification, memory exhaustion is signalled by throwingstd::bad_alloc. See alsonew (nothrow)✨.-fconcepts— concepts, the main character energy of templates 👑. This enables support for the C++ Concepts feature for constraining template arguments. With-std=c++20and above, Concepts are part of the language standard, so-fconceptsdefaults to on.
Some constructs that were allowed by the earlier C++ Extensions for Concepts Technical Specification, ISO 19217 (2015), but never made it into the standard, could additionally be enabled by -fconcepts-ts. The option -fconcepts-ts was deprecated in GCC 14 and removed in GCC 15 💀. Users are expected to convert their code to C++20 concepts.
-fconcepts-diagnostics-depth=n— this controls how deep the error replay goes when GCC recursively diagnoses a constraint satisfaction failure 🦋. You set the maximum error replay depth withn. The default is1.-fconstexpr-depth=n— this sets the maximum nested evaluation depth for C++11constexprfunctions ton. A limit is needed to detect endless recursion during constant expression evaluation. The minimum specified by the standard is512🌈.-fconstexpr-cache-depth=n— this sets the maximum level of nested evaluation depth for C++11constexprfunctions that will be cached ton. It's a heuristic that trades off compilation speed (when the cache avoids repeated calculations) against memory consumption (when the cache grows very large from highly recursive evaluations). The default is8. Very few users are likely to want to adjust it, but if your code does heavyconstexprcalculations, you might want to experiment to find which value works best for you 🧠.-fconstexpr-fp-except— 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 this guidance 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— this sets the maximum number of iterations for a loop in C++14constexprfunctions ton. A limit is needed to catch infinite loops during constant expression evaluation. The default is262144(1<<18) 🔁.-fconstexpr-ops-limit=n— this caps the maximum number of operations during a singleconstexprevaluation. Even when the number of iterations of a single loop is limited by the loop limit above, you can still get trouble. If there are several nested loops, each with lots of iterations that are still smaller than that limit, or if too many expressions need to be evaluated in the body of some loop (or even outside of a loop), theconstexprevaluation might take way too long 😩. The default is33554432(1<<25).-fcontracts— enables support for the C++ Contracts feature, as specified in the C++26 working draft (N5003) 🎀. On violation of an enforced or observed contract (see-fcontract-evaluation-semanticbelow), a violation handler gets called. The standard library provides a default handler that emits information about the contract that failed.
You can replace the default violation handler by defining:
void
handle_contract_violation (const std::contracts::contract_violation&);-fcontract-evaluation-semantic=semantic— sets the semantic that contracts get evaluated with tosemantic. The available evaluation modes are:"ignored"— the contract checks get elided, with no checking added at either compile time or runtime 🙈."observed"— the contract checks are performed at runtime. If one fails, a handler is called that lets you do things like logging or emitting runtime warnings. When the handler returns, execution of the code continues. At compile time, the checks are performed forconstexprevaluations, and in that case a diagnostic is emitted if the check fails."enforce"— the contract checks are performed and the handler is called if one fails. When the handler returns, execution of the code is terminated so it can't keep going past the failed case 🛑. At compile time, the checks are applied toconstexpr, and if one fails, the program is ill-formed and an error is emitted."quick_enforce"— the contract checks are performed at runtime and, if one fails, execution is terminated immediately, without calling any handler ⚡. At compile time there's no difference between this and the"enforce"case, since no handler is invoked at compile time.
-fcontracts-conservative-ipa— this stops inter-procedural analysis from taking action when the body of an inline function is visible in a given translation unit. It allows for the case where contract evaluation conditions are permitted to differ between translation units, which means those actions could be potentially incorrect 🫠.-fcontract-checks-outlined— by default, the contract checks forpreandpostconditions are expanded in-line into function bodies. This option makes a small function instead (containing the checks), which then gets called at the relevant position. That lets different criteria apply to the compilation of the checks and to the rest of the function body 💅.-fcontract-disable-optimized-checks— whenpreandpostcondition checks are outlined (using-fcontract-checks-outlined), this option disables the optimization steps for those functions that can otherwise avoid unwanted elision of checking steps 🙅♀️.-fcontracts-client-check=mode— this option enables insertion of checks at call sites, which is called caller-side checking 📞. The value ofmodedecides which contract checks get made:"none"— no caller or client side checking (this is the default)."pre"— preconditions are checked at the caller or client side."all"— both pre- and post-conditions are checked at the caller or client side.
-fcontracts-definition-check=mode— this option lets you disable callee or definition-side checks, which are otherwise enabled by default whenever the contracts feature is active 🌸. The variablemodehas the values"on"and"off".
Okay bestie, this batch is where the C++ stuff gets spicy 🌶️ Let's go 🧚
-fcoroutines— turns on support for the C++ coroutines extension ✨. With-std=c++20and above, coroutines are literally part of the language standard, so-fcoroutinesdefaults to on 💖.-fdiagnostics-all-candidates— lets the C++ front end list every candidate during an overload resolution failure 👀. That includes the times when a deleted function is the one that got picked 💀.-fdump-lang-,-fdump-lang-switch,-fdump-lang-switch-options,-fdump-lang-switch-options=filename— this is the C++ debug dump squad 🦋. It controls how C++-specific info gets dumped. The options and filename parts work the same way as in-fdump-tree. These switch values are the vibes you can pick:all— turns on everything listed below 🌈.class— dumps the class hierarchy info 🌸. Virtual table info gets dumped too, unlessslimis specified.module— dumps module info 🧩. The optionslineno(locations),graph(reachability),blocks(clusters),uid(serialization),alias(mergeable),asmname(Elrond),eh(mapper) &vops(macros) can add extra details.raw— dumps the raw internal tree data 🍓.tinst— dumps the sequence of template instantiations, indented so you can see how deep the recursion goes 🪞. Thelinenooption adds the source location where the instantiation got triggered. Thedetailsoption also dumps the pre-instantiation substitutions, like the ones done during template argument deduction.
Lines in the .tinst dump start with I for an instantiation, S for another substitution, and R[IS] for the reopened context of a deferred instantiation 📜.
-fno-elide-constructors— the C++ standard lets the compiler skip making a temporary that only exists to initialize another object of the same type 🙈. This flag turns that optimization OFF and makes G++ call the copy constructor every single time 😤. It also makes G++ call trivial member functions that would otherwise get expanded inline.
In C++17, the compiler is required to skip those temporaries, but this flag still affects trivial member functions 💅.
-fno-enforce-eh-specs— skips generating the run-time code that checks for exception specification violations 🙅♀️. Heads up, this breaks the C++ standard 🚨. It can still be handy for shrinking code size in production builds, kinda like definingNDEBUG✨. It does NOT give your code permission to throw exceptions that break the exception specs 🛑. The compiler still optimizes based on those specs, so if an unexpected exception gets thrown, you get undefined behavior at run time 💀.-fextern-tls-init,-fno-extern-tls-init— okay this one is a lot 🫶. The C++11 and OpenMP standards letthread_localandthreadprivatevariables have dynamic (run-time) initialization. To make that work, every use of one of these variables goes through a wrapper function that does any needed initialization. When the use and the definition live in the same translation unit, the compiler can optimize that overhead away 🪄. But when the use is in a different translation unit, there's a big overhead even if the variable doesn't actually need dynamic initialization 😭.
If you're 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 the 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— lets the C++ front end fold calls tostd::move,std::forward,std::addressof,std::to_underlyingandstd::as_const🧚♀️. Unlike inlining, folding means no debug info gets generated for those calls. Since nobody really needs to debug these, this flag is on by default unless-fno-inlineis active 💅.-fno-gnu-keywords— stopstypeoffrom being treated as a keyword, so you can use the word as a regular identifier 🌈. You can use__typeof__as the keyword instead ✨. This is implied by the strict ISO C++ dialects:-ansi,-std=c++98,-std=c++11, etc.-fno-immediate-escalation— skips immediate function escalation, which is when certain functions get promoted toconsteval🪄. This is specified in P2564R3. Check out this 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) sits in an immediate context, so it doesn't have to produce a constant (that's the mechanism that allows consteval function composition) 🧩. But with -fno-immediate-escalation, f does NOT get promoted to consteval. Since the call to the consteval function id(t) isn't a constant expression, the compiler rejects the code 🙅♀️.
This option is turned on by default, and it only does anything in C++20 mode or later 💖.
-fimplicit-constexpr— makes inline functions implicitlyconstexprif they meet the requirements for aconstexprfunction ✨. You can use it in C++14 mode or later. This can change initialization from dynamic to static, plus other optimizations 🚀.-fno-implicit-templates— never emits code for non-inline templates that get instantiated implicitly (aka by use) 🙈. Only explicit instantiations get code emitted. If you use this flag, you HAVE to structure your code so it includes all the explicit instantiations you need, 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 get handled differently so that compiles with and without optimization need the same set of explicit instantiations 🫶.-fno-implement-inlines— to save space, this skips emitting 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 get called 💀.-fmodules,-fno-modules— enables support for C++20 modules 🧚.-fno-modulesis usually not needed, since that's the default 🙌. Even though modules are a C++20 feature, selecting that standard version doesn't implicitly turn them on yet 🤔.-fmodule-header,-fmodule-header=user,-fmodule-header=system— compiles a header file into 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 🧠. It can still cause some trouble when porting code 😬. This option makes those function definitions implicitly inline. BUT it generates an ABI incompatibility, so you have to use it everywhere or nowhere 🚨. (Definitions outside of a named module stay implicitly inline no matter what 🌈.)-fno-module-lazy— disables 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 that answers queries for module name to filename mappings 🔮. If you don't specify one, theCXX_MODULE_MAPPERenvironment variable gets used. If that's unset too, an in-process default is provided 🧚♀️.-fmodule-only— only emits the Compiled Module Interface and skips any object file 📜.-fms-extensions— disablesWpedanticwarnings about constructs used in MFC, like implicitintand getting a pointer to a member function through non-standard syntax 🎀.-fnew-inheriting-ctors— enables the P0136 change to the semantics of C++11 constructor inheritance 🦋. It's part of C++17, but it's also considered a Defect Report against C++11 and C++14 🧾. This flag is on by default unless-fabi-version=10or lower is specified.-fnew-ttp-matching— enables the P0522 resolution to Core issue 150, which covers template template parameters and default arguments 🧩. This lets a template with default template arguments be used as an argument for a template template parameter that has fewer template parameters 🌸. This flag is on by default for-std=c++17💖.-fno-nonansi-builtins— disables built-in declarations of functions that aren't required by ANSI/ISO C 🙅♀️. These includeffs,alloca,_exit,index,bzero,conjf, and other related functions 🍓.-fnothrow-opt— treats athrow()exception specification as if it were anoexceptspecification 🪄. This reduces or gets rid of the text size overhead compared to a function with no exception specification 📉. If the function has local variables with non-trivial destructors, the exception spec 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 this kind of exception specification results in a call toterminateinstead ofunexpected⚠️.
-fno-operator-names— stops the operator name keywordsand,bitand,bitor,compl,not,orandxorfrom being treated as synonyms for keywords 🙅♀️.-fno-optional-diags— disables diagnostics that the standard says a compiler doesn't need to issue 🫠. Right now, the only one G++ issues like that is the one for a name that has multiple meanings within a class 🌈.-fno-pretty-templates— 💅 When an error mentions a function template specialization, GCC normally prints the template signature along with the template arguments and any typedefs or typenames in it. So you get something likevoid f(T) [with T = int]instead ofvoid f(int), which makes it clear which template is involved ✨. For class template specializations, GCC leaves out any template arguments that match the defaults for that template. If either of these makes errors harder to read instead of easier 🙈, use-fno-pretty-templatesto turn them off.-frange-for-ext-temps— 🔁 This turns on lifetime extension for temporaries in C++ range-basedforloops. With-std=c++23and newer it's already part of the language standard, so the temporaries live until the end of the loop by default 💖. This flag lets you get that same behavior in earlier versions of the standard.-freflection— 🧪 Turns on experimental C++26 Reflection 🦋.-fno-rtti— 🪶 This disables generating the info for every class with virtual functions that C++ run-time type identification relies on (the stuff behinddynamic_castandtypeid). If you don't use those features, this can save you some space 💜. Exception handling uses the same info, but G++ only generates it when it's actually needed. Thedynamic_castoperator still works for casts that don't need run-time type information, which means casts tovoid *or to unambiguous base classes 🌸.
⚠️ Mixing code compiled with-frttiand code compiled with-fno-rttimay not work. For example, your program might fail to link if a class compiled with-fno-rttiis used as a base for a class compiled with-frtti😭.
-fsized-deallocation— 🧹 This turns on the built-in global declarations below, which were 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 your own replacement deallocation functions, like ones that use the size of the object to make deallocation faster 🚀. It's on by default under -std=c++14 and above. The -Wsized-deallocation flag warns you about spots that might want to add a definition 👀.
-fstrict-enums— 🎯 This lets the compiler optimize based on the assumption that a value of an enumerated type can only be one of the enumeration's values. Basically, it's a value that fits in the minimum number of bits needed to represent all the enumerators, as defined by the C++ standard 📏. This assumption might not hold if your program uses a cast to turn an arbitrary integer into the enumerated type, so be careful 💀. This option does nothing for an enumeration type with a fixed underlying type.-fstrong-eval-order,-fstrong-eval-order=kind — 👑 This makes member access, array subscripting, and shift expressions evaluate left to right, while assignment evaluates right to left, just like it was adopted for C++17 🫶.-fstrong-eval-orderis the same as-fstrong-eval-order=all, and it's on by default with-std=c++17or later.
-fstrong-eval-order=some only turns on the ordering for member access and shift expressions, and it's the default for C++ dialects before C++17 🌈.
-fstrong-eval-order=none is the same as -fno-strong-eval-order 🧃.
-ftemplate-backtrace-limit=n — 📚 Sets the maximum number of template instantiation notes shown for a single warning or error to n. The default is 10 🔟.-ftemplate-depth=n — 🌀 Sets the maximum instantiation depth for template classes to n. You need a limit like this so that endless recursion during template class instantiation can be caught 🛑. ANSI/ISO C++ conforming programs must not rely on a maximum depth greater than 17, which was changed to 1024 in C++11 📜. The default is 900, because in some situations the compiler can run out of stack space before it ever hits 1024 🥲.-fno-threadsafe-statics— 🧵 Skips the extra code that uses the routines from the C++ ABI for thread-safe initialization of local statics. If your code doesn't need to be thread-safe, this can shave off a bit of code size ✂️.-fuse-cxa-atexit— 🚪 Registers destructors for objects with static storage duration using the__cxa_atexitfunction instead 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— 🙅 Stops the use of the__cxa_get_exception_ptrruntime routine. This makesstd::uncaught_exceptionincorrect, but you need it if that runtime routine isn't available on your system 🫠.-fvisibility-inlines-hidden— 🫥 This switch tells GCC that you won't try to compare pointers to inline functions or methods when the two functions' addresses are taken in different shared objects 🤝.
With this on, GCC may effectively mark inline methods with __attribute__ ((visibility ("hidden"))), so they don't show up in the export table of a DSO and don't need a PLT indirection when they're used inside that DSO 🦋. This can make a huge difference to load and link times for a DSO, since it massively shrinks the dynamic export table when a library leans heavily on templates 🚀.
This isn't exactly the same as marking methods as hidden directly, because it doesn't affect static variables local to the function, and it doesn't make the compiler decide the function is defined in only one shared object 🤔.
You can give a method 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 with default visibility 💅. Marking the enclosing class with explicit visibility has no effect ✨. Explicitly instantiated inline methods aren't affected 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 compatible with Microsoft Visual Studio's. It makes these changes to GCC's linkage model:- It sets the default visibility to
hidden, like-fvisibility=hidden🙈. - Types are not hidden by default, but their members are 🫣.
- The One Definition Rule is relaxed for types without explicit visibility specifications that are defined in more than one shared object. Those declarations are allowed if they'd be allowed without this option 🌷.
- It sets the default visibility to
In new code, it's better to use -fvisibility=hidden and export the classes you actually want to be externally visible 🧁. Unfortunately, code might rely on the Visual Studio behavior, perhaps by accident 😬.
Some consequences of these changes: 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 🧩. Also, pointers to function members defined in different shared objects may not compare equal 🙃. When this flag is given, defining types with the same name differently is a violation of the ODR. So don't do it, bestie 🚫.
-fno-weak— 🕸️ Don't use weak symbol support, even if the linker provides it. By default, G++ uses weak symbols when they're available. This option only exists for testing and shouldn't be used by end users, since 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) — 🔢 Accepts imaginary, fixed-point, or machine-defined literal number suffixes as GNU extensions. When this option is 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, and-std=gnu++14. It's off by default for ISO C++11 onwards (-std=c++11, ...) 🌙.-nostdinc++— 🚫 Doesn't search for header files in the standard directories specific to C++, but it still searches 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 about include translation events. The first one notes accepted include translations, and the second notes declined ones 🙅. The header form informs you about include translations relating to that specific header. If header is 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 tell you about Compiled Module Interface pathnames. The first notes all CMI pathnames that get read ✅. The module form notes when a specific module's CMI is read. module can be a named module or a header-unit, which is indicated by either being a pathname containing directory separators or 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++, which is the default and the native C++ runtime for G++, andlibc++, which is the C++ runtime installed on some operating systems (for example, Darwin versions from Darwin11 onwards 🍎). This option switches G++ to use headers from the library you specify, and it emits-lstdc++or-lc++respectively when a C++ runtime is needed for linking 🔗.
In addition, these warning options only have meanings 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. Check out C++ Attributes for more info about ABI tags 📖.-Wno-abbreviated-auto-in-template-arg— 🙈 Disables the error for anautoplaceholder type used within a template argument list to declare a C++20 abbreviated function template. For example:
void f(S<auto>);Okay so this feature was proposed in the Concepts TS, but it did not make it into C++20 💅. In the actual standard, a placeholder in a parameter declaration has to show up as a decl-specifier, so anything else is an error 🙈. If you need to chill, -fpermissive or -Wno-error=abbreviated-auto-in-template-arg can downgrade it to a warning 🫶.
-Wcomma-subscript(C++ and Objective-C++ only) — Warns about a comma expression sitting inside a subscript 💀. This was deprecated in C++20 and is getting removed in C++23, but a comma expression wrapped in( )is still totally fine ✨. Here's the vibe:
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 exists and supports the right number and types of arguments 👑. G++ will still accept the older syntax for code that's invalid in C++23 but used to be valid-yet-deprecated in C++20, and it gives you a pedantic warning you can turn off with -Wno-comma-subscript 🌸.
Enabled by default with -std=c++20 unless -Wno-deprecated, and after -std=c++23 regardless of -Wno-deprecated. Before -std=c++20, it's enabled with explicit -Wdeprecated 🎀. This warning gets upgraded to an error by -pedantic-errors in C++23 mode or later 😭.
-Wctad-maybe-unsupported(C++ and Objective-C++ only) — Warns when you do class template argument deduction (CTAD) on a type that has no explicitly written deduction guides 🔍. It's the "wait, did this succeed only because the compiler made up the guides?" warning, which might not be what you meant 🙈. Some style guides only allow CTAD on types that specifically opt in, meaning types designed to support it 🦋. You can suppress this 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 totally unusable because all 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 gets bound to a temporary whose lifetime has already ended 😭. Here's a classic:
int n = 1;
const int& r = std::max(n - 1, n + 1); // r is danglingIn that example, two temporaries get created, one for each argument, and a reference to one of them is returned 💀. Both temporaries get destroyed at the end of the full expression, so the reference r is dangling 🥀. This warning also catches 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 get checked too, but only their object argument 🧐:
struct S {
const S& self () { return *this; }
};
const S& s = S().self(); // s is danglingSome functions are actually safe here, like std::use_facet. They take and return a reference but don't return one of their arguments, which can fool the warning 🙃. You can exclude functions like that 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, and then the warning is disabled for all of its member functions ✨.
-Wdangling-reference also warns about code like this 👑:
auto p = std::minmax(1, 2);Here std::minmax returns std::pair<const int&, const int&>, and both references dangle after the end of the full expression that contains the call to std::minmax 💀.
It does not warn for std::span-like classes 🫶. We consider classes of this form:
template<typename T>
struct Span {
T* data_;
std::size len_;
};as std::span-like, meaning the class is a non-union class that has a pointer data member and a trivial destructor 🌈. The warning can be disabled with the gnu::no_dangling attribute 🦋. This warning is enabled by -Wextra ⭐.
-Wdelete-non-virtual-dtor(C++ and Objective-C++ only) — Warns whendeleteis used to destroy an instance of a class that has virtual functions but a non-virtual destructor 🙈. It's unsafe to delete a derived-class instance through a base-class pointer if the base class doesn't have a virtual destructor 😬. This warning is enabled by-Wall💖.-Wdeprecated-copy(C++ and Objective-C++ only) — Warns that the implicit declaration of a copy constructor or copy assignment operator is deprecated if the class has a user-provided copy constructor or copy assignment operator, in C++11 and up 📝. This warning is enabled by-Wextra✨.-Wdeprecated-copy-dtor(C++ and Objective-C++ only) — Basically the same deal as-Wdeprecated-copy, but it also deprecates the implicit copy operations if the class has a user-provided destructor 💅.
-Wno-deprecated-enum-enum-conversion(C++ and Objective-C++ only) — Turns off the warning for when the usual arithmetic conversions get applied to operands where one is an enum and the other is a different enum 🙅♀️. This conversion was deprecated in C++20 🧃. Example:
enum E1 { e };
enum E2 { f };
int k = f - e;-Wdeprecated-enum-enum-conversion is enabled by default with -std=c++20 🔥. In pre-C++20 dialects, this warning can be enabled by -Wenum-conversion or -Wdeprecated 🌸.
-Wno-deprecated-enum-float-conversion(C++ and Objective-C++ only) — Turns off the warning for when the usual arithmetic conversions get applied to operands where one is an enum and the other is a floating-point type 🌊. This conversion was deprecated in C++20 🥹. Example:
enum E1 { e };
enum E2 { f };
bool b = e <= 3.7;-Wdeprecated-enum-float-conversion is enabled by default with -std=c++20 💜. In pre-C++20 dialects, this warning can be enabled by -Wenum-conversion or -Wdeprecated 🎀.
-Wdeprecated-literal-operator(C++ and Objective-C++ only) — Warns that declaring a user-defined literal operator with a space before the suffix is deprecated 📏. This warning is enabled by default in C++23, or with explicit-Wdeprecated🌈. Look at the difference:
string operator "" _i18n(const char*, std::size_t); // deprecated
string operator ""_i18n(const char*, std::size_t); // preferred-Wdeprecated-variadic-comma-omission(C++ and Objective-C++ only) — Warns that leaving out the comma before the varargs...at the end of a function parameter list is deprecated 🙈. This warning is enabled by default in C++26, or with explicit-Wdeprecated🔮. Here's the breakdown:
void f1(int...); // deprecated
void f1(int, ...); // preferred
template <typename ...T>
void f2(T...); // ok
template <typename ...T>
void f3(T......); // deprecated-Wno-elaborated-enum-base— For C++11 and above, this warns if an (invalid) additional enum-base gets used in an elaborated-type-specifier 🧩. That means an enum with a given underlying type and no enumerator list, used in a declaration other than just a standalone declaration of the enum 🫠. It's enabled by default ✅. This warning gets upgraded to an error with-pedantic-errors😭.-Wno-init-list-lifetime(C++ and Objective-C++ only) — Turns off the warning about uses ofstd::initializer_listthat are likely to end up with dangling pointers 🫣. The underlying array for aninitializer_listgets treated like a normal C++ temporary object, so it's super easy to accidentally keep a pointer to the array after its lifetime is over 💀. Here are the sneaky cases:- 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 value returned 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 is assigned from a brace-enclosed initializer list, the temporary array created for the right side of the assignment only lives until the end of the full-expression, so at the next statement theinitializer_listvariable has a dangling pointer 😵. - When a list constructor stores the
beginpointer from theinitializer_listargument, that doesn't 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 🙃.
- If a function returns a temporary
// 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-Winvalid-constexpr— Warns when a function never produces a constant expression 🧊. In C++20 and earlier, everyconstexprfunction and function template has to have at least one set of function arguments, in at least one instantiation, where an invocation could be an evaluated subexpression of a core constant expression 📐. C++23 removed this restriction, so it's now possible to have aconstexprfunction or function template where no invocation satisfies the requirements of a core constant expression 🌸.
This one's tricky in C++20 🙈. It's enabled as a pedantic warning by default in C++20 and earlier, but in C++23 you can turn on -Winvalid-constexpr and it becomes an ordinary warning ✨. Like this:
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 ✨
Okay so this one checks that every imported macro definition is still valid once compilation finishes 🔍. It's not on by default, because figuring that out takes extra processing. It's super useful when you're putting together sets of header-units and want your macros to stay consistent across them 💜.
🎀 -Wno-literal-suffix 🎀 (C++ and Objective-C++ only)
Bestie, this one stops the warning when a string or character literal gets followed by a ud-suffix that doesn't start with an underscore 🙅♀️. GCC treats those suffixes as separate preprocessing tokens, which is a conforming extension that keeps old code working, especially code that uses the formatting macros from <inttypes.h> 🧚. 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 controls the warnings you get when a user-defined literal operator is declared with a literal suffix identifier that doesn't begin with an underscore. Those names are reserved for future standardization, so GCC is looking out for you 🫶. 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 says so 👑. A narrowing conversion from a constant is an error, and a narrowing conversion from a non-constant is a warning. -Wno-narrowing quiets that diagnostic 🙈. Just know that it doesn't change the meaning of well-formed code, since narrowing is still ill-formed in SFINAE contexts ⚠️.
With -Wnarrowing in C++98, you get a warning when a narrowing conversion that C++11 prohibits shows up inside { }. For example:
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 one warns when a noexcept-expression evaluates to false because of a call to a function that doesn't have a non-throwing exception specification (throw() or "noexcept"), even though the compiler knows that function never throws 🤔.
🌈 -Wnoexcept-type 🌈 (C++ and Objective-C++ only)
It's giving C++17 plot twist 🌀. This warns if the C++17 feature that makes noexcept part of a function type changes the mangled name of a symbol compared to C++14. It's enabled by -Wabi and -Wc++17-compat. Here's the 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)
Okay, this one is a lot, but it's important 😭. It warns when the destination of a call to a raw memory function like memset or memcpy is an object of class type. It also warns when writing into that object could bypass 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 that the class's member functions depend on 💀.
For example, the memset call below is undefined, because it modifies a non-trivial class object, so it gets diagnosed:
std::string str = "abc";
memset (&str, 0, sizeof str);The safe way to initialize or clear the storage of these types is to use the right constructor or assignment operator, if one exists 🫶.
-Wclass-memaccess is enabled by -Wall. If you explicitly cast the pointer to the class object to void *, or to a type that 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 the class itself or on an accessible polymorphic base class. In that situation, deleting a derived instance through a pointer to the class or its base is possible but unsafe 😬. This warning is automatically enabled if -Weffc++ is specified.
Heads up: the -Wdelete-non-virtual-dtor option (enabled by -Wall) is the one you should reach for, because it warns about the unsafe cases without false positives 💖.
🌸 -Wregister 🌸 (C++ and Objective-C++ only)
This warns on uses of the "register" storage class specifier, except when it's part of the GNU Explicit Register Variables extension 🔍. Using "register" as a storage class specifier was deprecated in C++11 and removed in C++17. It's enabled by default with -std=c++17 👑.
👑 -Wreorder 👑 (C++ and Objective-C++ only)
This warns when the order of member initializers in your code doesn't match the order they actually get executed in 📋. For instance:
struct A {
int i;
int j;
A(): j (0), i (1) { }
};The compiler rearranges the member initializers for "i" and "j" to match the declaration order of the members, and it emits a warning about that 🙈. This warning is enabled by -Wall ✨.
🔥 -Wno-pessimizing-move 🔥 (C++ and Objective-C++ only)
This one warns when a call to std::move prevents copy elision 🚫. The typical copy elision scenario is returning from a function with a class return type, where the returned expression is the name of a non-volatile automatic object that isn't a function parameter and has the same type as the function's return type. Like:
struct T {
...
};
T fn()
{
T t;
...
return std::move (t);
}But in this example, the std::move call is the thing that stops copy elision 😭. This warning is enabled by -Wall 💅.
🦋 -Wno-redundant-move 🦋 (C++ and Objective-C++ only)
This warns about redundant calls to std::move. In other words, it's when a move would have happened even without the std::move call 🙄. 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 doesn't apply. Consider:
struct T {
...
};
T fn(T t)
{
...
return std::move (t);
}Here, the std::move call is redundant 💀. Since 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 returned expression and the function's return type differ. Even so, G++ 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 warns when a C++ range-based for-loop creates an unnecessary copy 🫧. That can happen when the range declaration isn't a reference but probably should be. For example:
struct S { char arr[128]; };
void fn () {
S arr[5];
for (const auto x : arr) { ... }
}It won't warn when the copied type is trivially-copyable and smaller than 64 bytes 🧚.
It also warns when a loop variable in a range-based for-loop gets 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 creates and destroys a temporary value of type "double", and the reference "const double &" is bound to it 😵. This warning is enabled by -Wall ✨.
💜 -Wredundant-tags 💜 (C++ and Objective-C++ only)
This warns about redundant class-key and enum-key in references to class types and enumerated types, in contexts where the key can be dropped without causing ambiguity 🙃. For example:
struct foo;
struct foo *p; // warn that keyword struct can be eliminatedIn this example, there's no warning:
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)
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 🙌. If type A depends on type B with no linkage or internal linkage, defining A in multiple translation units is an ODR violation, because what B means is different in each one 😬. 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 too. The compiler doesn't give this warning for types defined in the main .C file, since those are unlikely to have multiple definitions 🫶. -Wsubobject-linkage is enabled by default 💅.
🔥 -Weffc++ 🔥 (C++ and Objective-C++ only)
This warns about violations of the following style guidelines from Scott Meyers' Effective C++ series of books. Literally every C++ girlie should know these 📚👑:
- 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 switches on -Wnon-virtual-dtor 💅, which is one of the effective C++ recommendations, and the check gets extended to flag a missing virtual destructor in accessible non-polymorphic base classes too 👀✨.
Heads up though 🙈 the standard library headers don't follow all of these guidelines, so you'll get noise from them. Use grep -v to filter those warnings out 🧹💜
-Wno-exceptions(C++ and Objective-C++ only) — 🙅♀️ Turns off the warning for when one exception handler gets shadowed by another, which can be a sign your handlers are in the wrong order 🎀-Wsfinae-incomplete(C++ and Objective-C++ only) — 👀 Warns when a class is incomplete, or a function with an auto return type hasn't been deduced yet, in a spot where that causes substitution failure instead of an error, and then the class or function gets defined later in the translation unit. This is messy because template instantiations or concept checks could give different results depending on whether they happen before or after the definition 😭. This warning is on by default 🌸.-Wsfinae-incomplete=2adds a warning at the point of substitution failure, so it's easier to track down the problems the default mode flags 🔍.-Wstrict-null-sentinel(C++ and Objective-C++ only) — 🧐 Warns about using an uncastedNULLas a sentinel. When you compile with only GCC, this counts as a valid sentinel, sinceNULLis defined to__null💖. It's a null pointer constant rather than a null pointer, but it's guaranteed to be the same size as a pointer. Just know this isn't portable across different compilers 🙃.-Wno-non-c-typedef-for-linkage(C++ and Objective-C++ only) — 🙅 Disables the pedwarn for unnamed classes that have a typedef name for linkage purposes and contain C++-specific stuff: members, base classes, default member initializers, or lambda expressions, including those on nested member classes 🧚
typedef struct {
int a; // non-static data members are ok
struct T { int b; }; // member classes too
enum E { E1, E2, E3 }; // member enumerations as well
int c = 42; // default member initializers are not ok
struct U : A { int c; }; // classes with base classes are not ok
typedef int V; // typedef is not ok
using W = int; // using declaration is not ok
decltype([](){}) x; // lambda expressions not ok
} S;In all of these cases, you need to add the tag name S after the struct keyword 🫶
-Wno-non-template-friend(C++ and Objective-C++ only) — 🦋 Disables warnings for non-template friend functions declared inside a template. In super old GCC versions that came before the ISO standard was implemented, something likefriend int foo(int), where the friend's name is an unqualified-id, could get read as a specific specialization of a template function. This warning exists to catch those compatibility problems, and it's enabled by default 💅-Wold-style-cast(C++ and Objective-C++ only) — 👀 Warns if you use an old-style (C-style) cast to a non-void type 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 🔎✨-Woverloaded-virtual,-Woverloaded-virtual=n(C++ and Objective-C++ only) — 🚨 Warns when a function declaration hides virtual functions from a base class. For example:
struct A {
virtual void f();
};
struct B: public A {
void f(int); // does not override
};So the A class version of f gets hidden in B, and code like this:
B* b;
b->f();fails to compile 😭
If the different signatures are on purpose and not an accident, the simplest fix is adding a using-declaration to the derived class to un-hide the base function, like using A::f; in B 🦋
The optional level suffix controls what happens when all the declarations in the derived class override virtual functions in the base class, even if not every base function is 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 ever used virtually, the user might have decided the base class semantics for some of the overloads are totally fine 💜
At level 1, this case doesn't warn. At level 2, it does. -Woverloaded-virtual by itself selects level 2, and 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 into 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, instead of a conversion to an unsigned type of the same size. Older versions of G++ tried to keep the unsignedness, but the standard mandates the current behavior, so no cap, that's the rule now 🙃-Wtemplates(C++ and Objective-C++ only) — 📜 Warns when a primary template declaration shows up. Some coding rules ban templates, so this can help enforce that rule 💅. The warning is inactive inside system header files like the STL, so you can still use the STL 🫶. You can also still instantiate or specialize templates ✨-Wmismatched-new-delete(C++ and Objective-C++ only) — 💀 Warns about mismatches between calls tooperator neworoperator deleteand the matching allocation or deallocation function. This coversoperator deletebeing called on pointers returned from mismatched forms ofoperator new, or from other functions that allocate objects whereoperator deleteisn't a suitable deallocator, plus calls to other deallocation functions on pointers returned fromoperator newwhere that deallocation function isn't suitable 😭
For example, the delete expression in this function gets diagnosed because it doesn't match the array form of the new expression that the pointer came from. The call to free gets diagnosed too 🧹
void f ()
{
int *a = new int[n];
delete a; // warning: mismatch in array forms of expressions
char *p = new char[n];
free (p); // warning: mismatch between new and free
}The related option -Wmismatched-dealloc handles mismatches involving allocation and deallocation functions other than operator new and operator delete 🦋. And -Wmismatched-new-delete is included in -Wall 💜
-Wmismatched-tags(C++ and Objective-C++ only) — 🎀 Warns about declarations of structs, classes, and class templates (plus their specializations) where the class-key doesn't match the definition, or the first declaration if no definition is given. In the example below, thestruct Objectin the argument list ofdrawsets it off. To avoid it, either remove the redundantstructclass-key or swap it forclassso it matches the definition 💅
class Object {
public:
virtual ~Object () = 0;
};
void draw (struct Object*);To be clear, declaring a class with the class-key struct isn't wrong, as the example above shows 🙂. -Wmismatched-tags is just there to help you keep a consistent style for class declarations 🌈. In code meant to be portable to Windows-based compilers, the warning helps prevent unresolved references caused by different name mangling for symbols declared with different class-keys 🧚. You can use this option 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 disallow multiple inheritance, so this can help enforce that rule 💖. It's inactive inside system header files like the STL, so the STL is still fair game 🌸. You can still define classes that indirectly use multiple inheritance ✨-Wvirtual-inheritance— 👑 Warns when a class is defined with a virtual direct base class. Some coding rules disallow multiple inheritance, so this can enforce that rule 📏. Inactive inside system header files like the STL, so you can still use the STL 🫶. You can also define classes that indirectly use virtual inheritance 💜-Wno-virtual-move-assign(C++ and Objective-C++ only) — ⚠️ Suppresses warnings about inheriting from a virtual base with a non-trivial C++11 move assignment operator. This is dangerous 😭 because 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 disallow namespaces, so this can help enforce that rule 💅. Inactive inside system header files like the STL, so you can still use the STL 🫶. You can also use using directives and qualified names 🌸-Wno-template-body(C++ and Objective-C++ only) — 🧚 Disables diagnosing errors when parsing a template. Instead, an error only gets issued when the template is instantiated 🦋. This flag can also downgrade those errors into warnings with-Wno-error=or-fpermissive✨-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 😭. For 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 🌈💜
-Wtemplate-names-tu-local— okay bestie, this one warns when a template body quietly ends up exposing a translation-unit-local entity 🫣 Usually, pointing at a TU-local thing (like an internal linkage declaration) from inside something emitted into a module's CMI is an error ❌. BUT inside a variable's initializer, or in the body of a non-inline function, it's not counted as an exposure, so no error pops up 🤷♀️
This can quietly make variable or function templates unusable 💀 if they reference such an entity, because other translation units that import the template will never be able to instantiate it. This warning tries to sniff out cases where that might happen 🕵️♀️ An explicit instantiation silences it 🤫
This flag is enabled by -Wextra ✨
-Wno-expose-global-module-tu-local— an exposure of a TU-local entity from a module interface is invalid 🚫 because it can cause ODR violations and show up as link errors or other unexpected behaviour. The annoying part is that lots of existing libraries declare TU-local entities in their interface, and dodging those exposures can be genuinely tricky 😩
As an extension, GCC lets you expose internal variables and functions that were declared in the global module fragment 👀 This warning tells you when that kind of invalid exposure happens, and you can silence it with diagnostic pragmas either right at the exposure site or at the point where the internal declaration is declared.
When combined with -Wtemplate-names-tu-local, GCC will also warn about non-exposure references to TU-local entities in template bodies 📣 Those templates can still be instantiated in other TUs, but the exposure risks above still apply.
This warning is enabled by default, and gets upgraded to an error by -pedantic-errors 🔥
-Wno-external-tu-local— warn when naming a TU-local entity outside the translation unit it was declared in 🙅♀️ These declarations get ignored during name lookup. This can happen when doing ADL from a template declared in the same TU as the internal function:
export module M;
template <typename T> void foo(T t) {
bar(t);
}
struct S {} s;
static void bar(S) {} // internal linkage
// instantiating foo(s) from outside this TU can see ::bar,
// but naming it there is ill-formed.Workaround alert 🧠 this can be fixed by making "bar" attached to the global module, using extern "C++".
This warning is enabled by default, and gets upgraded to an error by -pedantic-errors 💅
-Wno-terminate(C++ and Objective-C++ only) — turns off the warning about a throw-expression that will immediately result in a call to "terminate" 🙈-Wno-vexing-parse(C++ and Objective-C++ only) — the most vexing parse 😭 This warns when a declaration looks like a variable definition, but C++ says it has to be read as a function declaration. Iconic behaviour, honestly:
void f(double a) {
int i(); // extern int i (void);
int n(int(a)); // extern int n (int);
}Another example, because once is never enough 🙃
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 🛠️ for example, it can suggest 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 to void 🫠 Such a conversion function will never be called, so the warning is kinda pointless.-Wvolatile(C++ and Objective-C++ only) — warns about deprecated uses of thevolatilequalifier 🥀 This covers a bunch of vibes:- postfix and prefix
++and--expressions onvolatile-qualified types - simple assignments where the left operand is a
volatile-qualified non-class type, for their value - compound assignments where the left operand is a
volatile-qualified non-class type - a
volatile-qualified function return type - a
volatile-qualified parameter type - structured bindings of a
volatile-qualified type
- postfix and prefix
This usage was deprecated in C++20, so it's giving "retire this habit" 💀
Enabled by default with -std=c++20. Before -std=c++20, it's enabled with an explicit -Wdeprecated 📜
-Waligned-new,-Waligned-new=[none|global|all]— warn about a new-expression of a type that needs more alignment thanalignof(std::max_align_t), but uses an allocation function without an explicit alignment parameter 📐 This option is enabled by-Wall🌸
Normally this only warns about global allocation functions, but -Waligned-new=all also warns about class member allocation functions 👑
-Wno-placement-new,-Wplacement-new=n— warn about placement new expressions with undefined behavior 🚨 For example, the placement new below gets diagnosed 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 🧁 At this level, the warning skips some strictly undefined constructs that GCC allows as extensions for compatibility with legacy code. For example, thenewexpression below is not diagnosed here, even though it's undefined behaviour according to the C++ standard, 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— this level diagnoses everything level 1 does, plus placement new expressions that construct an object in the last member of a structure, where that member is an array of a single element and its size is less than the size of the object being constructed 📏 The previous example gets flagged here, but the flexible member array extension below slides past 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) — warn about catch handlers that don't catch via reference 🎀-Wcatch-value=1(or just-Wcatch-valuefor short) warns about polymorphic class types caught by value.-Wcatch-value=2warns about all class types caught by value.-Wcatch-value=3warns about all types that aren't caught by reference.-Wcatch-valueis enabled by-Wall🫶-Wconditionally-supported(C++ and Objective-C++ only) — warn for conditionally-supported (C++11 [intro.defs]) constructs 🧚-Wno-defaulted-function-deleted(C++ and Objective-C++ only) — warn when an explicitly defaulted function gets deleted by the compiler 😤 That can happen when the function's declared type doesn't match the type of the function that would've been implicitly declared. This warning is enabled by default ✅-Wno-delete-incomplete(C++ and Objective-C++ only) — don't warn when deleting a pointer to an incomplete type, which may cause undefined behaviour at runtime 🫣 This warning is enabled by default ✅-Wextra-semi(C++, Objective-C++ only) — warn about redundant semicolons 🧵 There are a few sneaky contexts where an extra semicolon can show up:- a semicolon after in-class function definitions. This is valid in all C++ dialects and is never a pedwarn 🙄
struct S {
void foo () {};
};- an extra semicolon at namespace scope. This has been allowed since C++11, so it's a pedwarn in C++98 📝
struct S {
};
;- an extra semicolon in class definitions. This has also been allowed since C++11, so it's a pedwarn in C++98 💅
struct S {
int a;
;
};-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 due to ambiguity 🕵️ This warning is enabled by default. Note that the warning for ambiguous virtual bases is enabled by the-Wextraoption ✨
struct A { int a; };
struct B : A { };
struct C : B, A { };-Wno-inherited-variadic-ctor— suppresses warnings about the use of C++11 inheriting constructors when the base class being inherited from has a C variadic constructor 🦄 This 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,offsetofusually gives meaningful results. This flag is for users who know they're writing nonportable code and who've deliberately chosen to ignore the warning about it 🧠
The restrictions on offsetof may 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, like these:
void operator delete (void *) noexcept;
void operator delete[] (void *) noexcept;…that shows up 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 🙈 This one's switched on by -Wextra along with -fsized-deallocation 💅
-Wsuggest-final-types— Okay so this one warns about types with virtual methods that would be way cleaner if they were declared with the C++11finalspecifier, or, if it's possible, declared in an anonymous namespace 🧚 It's giving devirtualization, because it lets GCC more aggressively devirtualize the polymorphic calls ✨ It hits harder with link-time optimization, since the class hierarchy graph info is more complete there 💜-Wsuggest-final-methods— Warns about virtual methods that would glow up if they were declared withfinal, or, if possible, if their type were declared in an anonymous namespace or with thefinalspecifier 🌸 Same deal as above: it's more effective with link-time optimization, where the class hierarchy graph is more complete. Bestie tip straight from the manual: consider the-Wsuggest-final-typessuggestions first, then rebuild with the new annotations 🫶-Wsuggest-override— Warns about overriding virtual functions that aren't marked with theoverridekeyword 🦋-Wno-conversion-null(C++ and Objective-C++ only) — Do not warn for conversions betweenNULLand non-pointer types. Just so you know,-Wconversion-nullis enabled by default 🙄
✨ Options Controlling Objective-C and Objective-C++ Dialects ✨
(NOTE: This manual does not describe the Objective-C and Objective-C++ languages themselves.
This section is all about the command-line options that only matter for Objective-C and Objective-C++ programs 🌈 You can still use most of the language-independent GNU compiler options too! For example, you might compile a file some_class.m like this:
gcc -g -fgnu-runtime -O -c some_class.mIn this example, -fgnu-runtime is an option meant only for Objective-C and Objective-C++ programs, but you can use the other options with any language GCC supports 💖
Note that since Objective-C is an extension of the C language, Objective-C compilations may also use options specific to the C front-end (e.g., -Wtraditional). Similarly, Objective-C++ compilations may use C++-specific options (e.g., -Wabi) 🎀
Here is a list of options that are only for compiling Objective-C and Objective-C++ programs 👑
-fconstant-string-class=class-name— Use class-name as the name of the class to instantiate for each literal string written with the syntax"@"...""🧚 The default class name is"NXConstantString"if the GNU runtime is being used, and"NSConstantString"if the NeXT runtime is being used (see below). On Darwin / macOS platforms, the-fconstant-cfstringsoption, if also present, overrides the-fconstant-string-classsetting and causes"@"...""literals to be laid out as constant CoreFoundation strings. Note that-fconstant-cfstringsis an alias for the target-specific-mconstant-cfstringsequivalent 🍓-fgnu-runtime— Generate object code compatible with the standard GNU Objective-C runtime. This is the default for most types of systems 🌸-fnext-runtime— Generate output compatible with the NeXT runtime. This is the default for NeXT-based systems, including Darwin / macOS 🍎 The macro"__NEXT_RUNTIME__"is predefined if (and only if) this option is used.-fno-nil-receivers— Assume that all Objective-C message dispatches ("[receiver message:arg]") in this translation unit make sure the receiver is not"nil". This lets the runtime use more efficient entry points 🚀 This option is only available in conjunction with the NeXT runtime and ABI version 0 or 1.-fobjc-abi-version=n— Use version n of the Objective-C ABI for the selected runtime. Right now this is only supported for the NeXT runtime 🙈 In that case, Version 0 is the traditional (32-bit) ABI without support for properties and other Objective-C 2.0 additions. Version 1 is the traditional (32-bit) ABI with support for properties and other Objective-C 2.0 additions. Version 2 is the modern (64-bit) ABI. If nothing is specified, the default is Version 0 on 32-bit target machines, and Version 2 on 64-bit target machines.-fobjc-call-cxx-cdtors— Okay, this one's a whole vibe 💅 For each Objective-C class, it checks if any of its instance variables is a C++ object with a non-trivial default constructor. If so, it synthesizes a special"- (id) .cxx_construct"instance method, which runs non-trivial default constructors on any such instance variables, in order, and then returnsself. Similarly, it checks if any instance variable is a C++ object with a non-trivial destructor, and if so, it synthesizes a special"- (void) .cxx_destruct"method, which runs all such default destructors, in reverse order. The"- (id) .cxx_construct"and"- (void) .cxx_destruct"methods generated this way only operate on instance variables declared in the current Objective-C class, and not the ones inherited from superclasses. It's the responsibility of the Objective-C runtime to invoke all such methods in an object's inheritance hierarchy. The"- (id) .cxx_construct"methods are invoked by the runtime immediately after a new object instance is allocated, and the"- (void) .cxx_destruct"methods are invoked immediately before the runtime deallocates an object instance. As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has support for invoking the"- (id) .cxx_construct"and"- (void) .cxx_destruct"methods 😭-fobjc-direct-dispatch— Allow fast jumps to the message dispatcher. On Darwin, this is accomplished via the comm page ⚡-fobjc-exceptions— Enable syntactic support for structured exception handling in Objective-C, similar to what C++ offers 🫶 This option is required to use the Objective-C keywords@try,@throw,@catch,@finallyand@synchronized. It's available with both the GNU runtime and the NeXT runtime (but not in conjunction with the NeXT runtime on Mac OS X 10.2 and earlier) 💀-fobjc-gc— Enable garbage collection (GC) in Objective-C and Objective-C++ programs. This option is only available with the NeXT runtime. The GNU runtime has a different garbage collection implementation that doesn't require special compiler flags 🧹-fobjc-nilcheck— For the NeXT runtime with version 2 of the ABI, check for a nil receiver in method invocations before doing the actual method call. This is the default, and it can be disabled using-fno-objc-nilcheck. Class methods and super calls are never checked for nil in this way, no matter what this flag is set to. Currently this flag does nothing when the GNU runtime, or an older version of the NeXT runtime ABI, is used 🙃-fobjc-std=objc1— Conform to the language syntax of Objective-C 1.0, the language recognized by GCC 4.0 🕰️ This only affects the Objective-C additions to the C/C++ language. It does not affect conformance to C/C++ standards, which is controlled by the separate C/C++ dialect option flags. When this option is used with the Objective-C or Objective-C++ compiler, any Objective-C syntax that GCC 4.0 doesn't recognize is rejected. This is useful if you need to make sure your Objective-C code can be compiled with older versions of GCC 🧸-freplace-objc-classes— Emit a special marker tellingld(1)not to statically link in the resulting object file, and allowdyld(1)to load it at run time instead 🦋 This is used with the Fix-and-Continue debugging mode, where the object file may be recompiled and dynamically reloaded during program execution, without restarting the program itself. Right now, Fix-and-Continue is only available with the NeXT runtime on Mac OS X 10.3 and later.-fzero-link— When compiling for the NeXT runtime, the compiler usually swaps calls toobjc_getClass("...")(when the class name is known at compile time) for static class references that get initialized at load time, which boosts run-time performance 🔥 Specifying-fzero-linksuppresses this and keeps the calls toobjc_getClass("..."). That's useful in Zero-Link debugging mode, since it lets you modify individual class implementations during program execution. The GNU runtime currently always retains calls toobjc_get_class("..."), regardless of command-line options 👀-fno-local-ivars— By default, instance variables in Objective-C can be accessed as if they were local variables from within the methods of the class they're declared in. This can cause shadowing between instance variables and other variables declared either locally inside a class method or globally with the same name 😵 Specifying-fno-local-ivarsdisables this behavior, which avoids variable shadowing issues 💅-fivar-visibility=[public|protected|private|package]— Sets the default instance variable visibility to the specified option, so that instance variables declared outside the scope of any access modifier directives default to that visibility 👁️-gen-decls— Dumps interface declarations for all classes seen in the source file to a file namedsourcename.decl📜-Wassign-intercept(Objective-C and Objective-C++ only) — Warns whenever an Objective-C assignment is being intercepted by the garbage collector 🚨-Wno-property-assign-default(Objective-C and Objective-C++ only) — Don't warn if a property for an Objective-C object has no assign semantics specified 🙌-Wno-protocol(Objective-C and Objective-C++ only) — Okay, so if a class is declared to implement a protocol, a warning gets issued for every method in the protocol that the class doesn't implement. The default behavior is to warn for every method not explicitly implemented in the class, even if the method implementation is inherited from the superclass 🥺 If you use-Wno-protocol, then methods inherited from the superclass are considered implemented, and no warning is issued for them 🌷-Wobjc-root-class(Objective-C and Objective-C++ only) — okay so this one yells if a class interface has no superclass 👀 Most classes inherit fromNSObject(orObject), for example. If you're making a class that's supposed to be a root class, you can silence the warning by marking its interface with__attribute__((objc_root_class))💅-Wselector(Objective-C and Objective-C++ only) — this one flags when you've got multiple methods with different types sharing the same selector 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, if a matching method was found during compilation. Because all of this only happens at the final stage, these warnings won't show up if that stage never gets reached, like when there's an error during compilation or when-fsyntax-onlyis in use 🙈-Wstrict-selector-match(Objective-C and Objective-C++ only) — warns if a selector has multiple methods with different argument and/or return types when you try to send a message with it to a receiver of typeidorClass📨 By default this flag is off, and in that case the compiler skips these warnings if the only differences are between types that share the same size and alignment. Sneaky, but chill 🦋-Wundeclared-selector(Objective-C and Objective-C++ only) — warns when 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, either explicitly in an@interfaceor@protocoldeclaration, or implicitly in an@implementationsection. This option checks right away as soon as it spots a@selector(...)expression, while-Wselectoronly checks at the final stage of compilation. It also backs up the style rule that methods and selectors need to be declared before they get used 📝-print-objc-runtime-info— generates a C header describing the largest structure that gets passed by value, if there is one 🧚
✨ Options Controlling OpenMP and OpenACC ✨
okay so GCC supports OpenMP extensions for C, C++, and Fortran with -fopenmp 🌈 And OpenACC extensions work in all three languages with -fopenacc 💜
-foffload=disable,-foffload=default,-foffload=target-list— this is how you choose 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=disableonly generates code for the host fallback, and-foffload=target-listonly generates code for the comma-separated list of offload targets you give it 🫶
Offload targets are written in GCC's internal target-triplet format. If you run the compiler with -v, it'll show you the list of configured offload targets under "OFFLOAD_TARGET_NAMES" 👀
-foffload-options=options,-foffload-options=target-triplet-list=options— with-foffload-options=options, GCC passes your options to the compilers for every enabled offloading target 🚀 If you want options that only apply to certain targets, use the-foffload-options=target-list=optionsform instead. The target-list is a comma-separated list in the same format as 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— turns on handling of OpenACC directives:#pragma accin C/C++, and!$accin free-form Fortran, plus!$acc,c$acc, and*$accin fixed-form Fortran 🎀 Heads up, this option implies-pthread, so it's only supported on targets that actually support-pthread⚠️-fopenacc-dim=geom— sets default compute dimensions for parallel offload regions that don't specify their own 📐 The geom value is a triple of:-separated sizes, in the order gang, worker, and vector. You can leave a size out to use a target-specific default value ✨-fopenmp— turns on handling of OpenMP directives like#pragma omp,[[omp::decl(...)]],[[omp::directive(...)]], and[[omp::sequence(...)]]in C/C++ 💖 In Fortran, it enables!$ompand the conditional compilation sentinel!$. In fixed source form Fortran, those sentinels can also start withcor*.
This option implies -pthread, so it's only supported on targets that have -pthread support 🧵 -fopenmp also implies -fopenmp-simd.
-fopenmp-simd— enables handling of OpenMP's"simd","declare simd","declare reduction","assume","ordered","scan", and"loop"directives, plus combined or composite directives that have"simd"as a constituent 🌸 This works with#pragma omp,[[omp::directive(...)]],[[omp::sequence(...)]], and[[omp::decl(...)]]in C/C++, and with!$ompin Fortran. It also turns on the!$conditional compilation sentinel in Fortran. In fixed source form Fortran, the sentinels can also start withcor*. Other OpenMP directives get ignored 🙈 Unless-fopenmpis also specified, the"loop"region binds to the current task region, no matter what"bind"clause you wrote.-fopenmp-target-simd-clone,-fopenmp-target-simd-clone=device-type— on top of generating SIMD clones for functions marked with"declare simd", GCC also makes clones for functions marked with the OpenMP"declare target"directive that are good for vectorization when this option is on 🦋 The device-type can be one of"none","host","nohost", or"any". These match the keywords for the"device_type"clause of"declare target", and clones get generated for the intersection of the devices you specify.-fopenmp-target-simd-cloneis the same as-fopenmp-target-simd-clone=any, and-fno-openmp-target-simd-cloneis 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 💅
✨ Options to Control Diagnostic Messages Formatting ✨
traditionally, diagnostic messages got formatted without caring about the output device's aspect (like its width, and so on) 🙄 You can use the options below to control the formatting algorithm, like how many characters go on a line, or 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 long 📏 If n is zero, no line-wrapping happens, and each error message shows up on a single line. This is the default for all front ends.
Note: this option also affects the display of the #error and #warning preprocessor directives, and the deprecated function/type/variable attribute. It does not affect the pragma GCC warning and pragma GCC error pragmas ⚠️
-fdiagnostics-plain-output— makes diagnostic output look as plain as possible 🧼 This is handy when you're running dejagnu or other utilities that parse diagnostics output and need it to stay stable over time.-fdiagnostics-plain-outputis currently the same as 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=none
-fno-diagnostics-show-event-links
-fno-diagnostics-show-nestingIf GCC ever changes the default look of its diagnostics in the future, the matching option to turn off the new behavior will be added to this list 🔮
-fdiagnostics-show-location=once— only matters in line-wrapping mode 🎀 It tells the diagnostic reporter to emit source location info once. So if a message is too long for one physical line and has to wrap, the location won't keep getting stuck on 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 that comes out of breaking up a message that's too long to fit on one line 📍-fdiagnostics-color[=WHEN],-fno-diagnostics-color— uses color 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.automakes GCC use color only when standard error is a terminal and it's not running in an emacs shell 🧠 The forms-fdiagnostics-colorand-fno-diagnostics-colorare aliases for-fdiagnostics-color=alwaysand-fdiagnostics-color=never, respectively.
The colors get defined 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 decimal integers and can be concatenated with semicolons. Common values to concatenate include 1 for bold, 4 for underline, 5 for blink, 7 for inverse, 39 for default foreground color, 30 to 37 for foreground colors, 90 to 97 for 16-color mode foreground colors, 38;5;0 to 38;5;255 for 88-color and 256-color modes foreground colors, 49 for default background color, 40 to 47 for background colors, 100 to 107 for 16-color mode background colors, and 48;5;0 to 48;5;255 for 88-color and 256-color modes background colors 🫧
The default GCC_COLORS is
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;32\ highlight-a=01;32:highlight-b=01;34
okay so here's your little decoder ring 💅 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 capabilities you can tweak, bestie ✨
error=— the SGR color code forerror:markers 💥warning=— the SGR color code forwarning:markers ⚠️note=— the SGR color code fornote:markers 📝path=— colors the paths of control-flow events when they're printed via-fdiagnostics-path-format=, like the IDs of individual events and the lines showing interprocedural calls and returns 🛤️range1=— the first additional range 🎀range2=— the second additional range 🎀locus=— location info, likefile:lineorfile:line:columnetc. 📍quote=— info printed within quotes 💬fnname=— names of C++ functions 🧚targs=— C++ function template parameter bindings 🌸fixit-insert=— fix-it hints suggesting text to be inserted or replaced ➕fixit-delete=— fix-it hints suggesting text to be deleted ➖diff-filename=— filename headers within generated patches 📁diff-hunk=— the starts of hunks within generated patches 🧩diff-delete=— deleted lines within generated patches ❌diff-insert=— inserted lines within generated patches ✅type-diff=— highlights mismatching types within template arguments in the C++ frontend 🙈valid=— highlights valid elements within text art diagrams 💚invalid=— highlights invalid elements within text art diagrams 💔highlight-a=andhighlight-b=— the SGR substrings for contrasting two different things within diagnostics, like a pair of mismatching types. See-fdiagnostics-show-highlight-colors🎨
-fdiagnostics-urls[=WHEN]— embeds URL escape sequences 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 🔗WHENisnever,always, orauto.automakes GCC use URL escape sequences only when standard error is a terminal, and when it's not running in an emacs shell or any graphical terminal known to be incompatible with this feature (more on that below) 🫶- The default depends on how the compiler was configured, and it can be any of the above
WHENoptions. - GCC can also be configured with
--with-diagnostics-urls=auto-if-envso the default is affected by environment variables. Under that setup, GCC defaults toautoif eitherGCC_URLSorTERM_URLSis present and non-empty in the compiler's environment, orneverif neither is. - Even with
-fdiagnostics-urls=always, the behavior still depends on those environment variables:- If
GCC_URLSis set to empty orno, URLs are not embedded in diagnostics. - If set to
st, URLs use ST escape sequences. - If set to
bel, which is the default, URLs use BEL escape sequences. - Any other non-empty value enables the feature.
- If
GCC_URLSis not set,TERM_URLSis used as a fallback.
- If
- Note: ST is an ANSI escape sequence with the string terminator
ESC \. BEL is an ASCII character, CTRL-G, that usually sounds like a beep 🔔 - GCC tries to detect a few terminals that don't implement the URL feature, or that had bugs in versions still in use, where URL escapes are likely to misbehave. That list is currently xfce4-terminal, certain known buggy gnome-terminal versions, the linux console, and mingw. This check can be skipped with
-fdiagnostics-urls=always.
bestie, on those glitchy terminals the URL escapes can print garbage all over the screen 😭 that's why GCC tries to dodge them!
-fno-diagnostics-show-option— by default, each diagnostic includes text showing the command-line option that directly controls it (if that option is known to the diagnostic machinery). This flag suppresses that behavior 🙈-fno-diagnostics-show-caret— by default, each diagnostic includes the original source line and a caret^pointing at the column. This option suppresses that info 🙅. The source line is truncated toncharacters if the-fmessage-length=noption is given. When the output goes to the terminal, the width is limited to the width given by theCOLUMNSenvironment variable or, if that isn't set, the terminal width 📏-fno-diagnostics-show-labels— by default, when source code is printed (via-fdiagnostics-show-caret), diagnostics can label ranges of source code with pertinent info, like the types of expressions. Here's the vibe:
printf ("foo %s bar", long_i + long_j);
~^ ~~~~~~~~~~~~~~~
| |
char * long intThis option suppresses the labels, so in the example above, the vertical bars and the "char *" and "long int" text are gone 👋
-fno-diagnostics-show-event-links— by default, when execution paths are printed (via-fdiagnostics-path-format=inline-events), GCC prints lines connecting related events, like the line connecting events 1 and 2 in this example:
3 | if (p)
| ^
| |
| (1) following `false' branch (when `p' is NULL)... ->-+
| |
| |
|+------------------------------------------------------------+
4 || return 0;
5 || return *p;
|| ~
|| |
|+-------->(2) ...to here
| (3) dereference of NULL `p'This option suppresses those connector lines 🧵
-fno-diagnostics-show-cwe— diagnostic messages can optionally have an associated CWE ("https://cwe.mitre.org/index.html") identifier. GCC itself only provides this metadata for some of the-fanalyzerdiagnostics, and GCC plugins may also provide diagnostics with it. By default, if this info is present, it gets printed with the diagnostic. This option suppresses that metadata 🛡️-fno-diagnostics-show-rules— diagnostic messages can optionally have rules attached, like ones from a coding standard or a specification. GCC itself doesn't do this for any of its diagnostics, but plugins may. By default, if the info is present, it gets printed with the diagnostic. This option suppresses that metadata 📜-fno-diagnostics-show-highlight-colors— GCC can use color for emphasis and contrast when printing diagnostic messages and quoting your source. For example, in this message:
demo.c: In function `test_bad_format_string_args':
../../src/demo.c:25:18: warning: format `%i' expects argument of type `int', but argument 2 has type `const char *' [-Wformat=]
25 | printf("hello %i", msg);
| ~^ ~~~
| | |
| int const char *
| %s- the
%iand "int" in the message, plus the "int" in the quoted source, are colored usinghighlight-a(bold green by default) ✅ - the "const char *" in the message and in the quoted source are both colored using
highlight-b(bold blue by default) 💙
The vibe is to draw your eyes to how the different parts of the message and the source relate, using color to group related stuff and distinguish mismatched stuff 👀 This extra colorization is enabled by default if color printing is on (per -fdiagnostics-color=), but you can turn it off separately with -fno-diagnostics-show-highlight-colors 🎨
-fno-diagnostics-show-line-numbers— by default, when source code is printed (via-fdiagnostics-show-caret), a left margin showing line numbers is printed. This option suppresses that left margin 🔢-fdiagnostics-minimum-margin-width=width— controls the minimum width of the left margin printed by-fdiagnostics-show-line-numbers. It defaults to6📐-fdiagnostics-show-context[=depth]and-fno-diagnostics-show-context— with this option, the compiler might print the interesting control-flow chain that guards the basic block of the statement with the warning.depthis the maximum depth of that chain. The warning options currently affected are-Warray-bounds,-Wstringop-overflow,-Wstringop-overread,-Wstringop-truncation, and-Wrestrict. More warning options might join the list in future releases 🔍 The forms-fdiagnostics-show-contextand-fno-diagnostics-show-contextare aliases for-fdiagnostics-show-context=1and-fdiagnostics-show-context=0, respectively-fdiagnostics-parseable-fixits— emits fix-it hints in a machine-parseable format that IDEs can gobble up 🤖 For each fix-it, a line gets printed after the relevant diagnostic, starting with the stringfix-it:. For example:
fix-it:"test.c":{45:3-45:21}:"gtk_widget_show_all"the location is a half-open range 🎀 counted in bytes, and byte counting starts at 1 for the initial column (very precise, no notes). In the example below, bytes 3 through 20 of line 45 of "test.c" get swapped out for the new string 🦋:
00000000011111111112222222222
12345678901234567890123456789
gtk_widget_showall (dlg);
^^^^^^^^^^^^^^^^^^
gtk_widget_show_allThe filename and replacement string escape a backslash as "\\", a tab as "\t", a newline as "\n", a double quote as "\"", and non-printable characters as octal, so a vertical tab shows up as "\013" 💅
An empty replacement string means the range gets deleted 🗑️, and an empty range like "45:3-45:3" means the string gets inserted right at that spot ✨
✨ -fdiagnostics-generate-patch ✨
Prints the fix-it hints to stderr in unified diff format, after all the diagnostics have been printed 🌸 Here's what that looks like:
--- 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 🌈, and it follows the same rules as regular diagnostics (see -fdiagnostics-color).
✨ -fdiagnostics-show-template-tree ✨
This one is for the C++ frontend 💜 When diagnostics show mismatching template types, like this:
could not convert 'std::map<int, std::vector<double> >()'
from 'map<[...],vector<double>>' to 'map<[...],vector<float>>passing -fdiagnostics-show-template-tree turns on a tree-like structure that shows the common and differing parts of the types, like this:
map<
[...],
vector<
[double != float]>>The parts that differ get highlighted with color, which is "double" and "float" in this case 🔥
✨ -fno-elide-type ✨
By default, when the C++ frontend prints mismatching template types, the common parts get squished down to [...] so the error message stays short and sweet 🍓 For example:
could not convert 'std::map<int, std::vector<double> >()'
from 'map<[...],vector<double>>' to 'map<[...],vector<float>>Adding -fno-elide-type turns that squishing off 🙅♀️ This flag also affects the output of -fdiagnostics-show-template-tree.
✨ -fdiagnostics-path-format=KIND ✨
This one decides how the control-flow event paths get printed for diagnostics that have one attached 🦋
KIND can be none, separate-events, or inline-events, and the default is inline-events 👑
none— no diagnostic paths get printed at all 🙈separate-events— each event in the diagnostic gets its own "note" 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— the events get printed "inline" right inside the source code 🧚 It tries to group the events into runs of close-together events and prints them as labelled ranges in the source. For example, those same events might look like this:
'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 1Interprocedural control flow gets shown by grouping the events by stack frame, with indentation showing how stack frames are nested, pushed, and popped 🌀 For example:
'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 ✨
This option adds extra info when printing the control-flow paths attached to a diagnostic 🔍
If you pass it, the stack depth gets printed for each run of events within -fdiagnostics-path-format=inline-events. If you pass it together with -fdiagnostics-path-format=separate-events, then the stack depth and function declaration get tacked onto the end of each event 📌
This one is intended for GCC developers and plugin developers 🧑💻 who are debugging diagnostics that report interprocedural control flow.
✨ -fno-show-column ✨
Don't print column numbers in diagnostics 🙅♀️ This might be necessary if your diagnostics are being scanned by a program that doesn't understand column numbers, such as dejagnu.
✨ -fdiagnostics-column-unit=UNIT ✨
Picks the units used for the column number 📏 This affects traditional diagnostics (unless you've also passed -fno-show-column).
UNIT can be:
display— the default 💖 It counts the number of display columns each character takes up. That can be more than the bytes needed to encode the character (tabs, for example) or fewer (multibyte characters, for example). For instance,GREEK SMALL LETTER PI (U+03C0)takes up one display column but needs two bytes in UTF-8, andSLIGHTLY SMILING FACE (U+1F642)takes up two display columns but needs four bytes in UTF-8.byte— the column number becomes the raw byte count in every case, which is how GCC used to output it before version 11.1.0 🕰️
✨ -fdiagnostics-column-origin=ORIGIN ✨
Picks the origin for column numbers, meaning the column number given to the very first column 🎯 The default value of 1 matches traditional GCC behavior and the GNU style guide. Some utilities may work better with an origin of 0, and any non-negative value is allowed.
✨ -fdiagnostics-escape-format=FORMAT ✨
When GCC prints the relevant source lines for a diagnostic, it normally tries to print the source bytes straight up 💅 But some diagnostics are about encoding problems in the source file, like malformed UTF-8 or issues with Unicode normalization. Those diagnostics get flagged so GCC escapes any bytes that aren't printable ASCII when it prints their source lines.
This option controls how those bytes get escaped 🫶
FORMAT can be:
unicode— the default ✨ Unicode characters that aren't printable ASCII show up as<U+XXXX>, and bytes that don't form a validly UTF-8-encoded Unicode character show up as hexadecimal in the form<XX>.
For example, say a source line contains before, then the Unicode character U+03C0 (GREEK SMALL LETTER PI, which is UTF-8 encoded as 0xCF 0x80), then the stray UTF-8 trailing byte 0xBF, then after. With the default, that diagnostic prints as:
before<U+03C0><BF>afterbytes— 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 prints:
before<CF><80><BF>after✨ -fdiagnostics-text-art-charset=CHARSET ✨
Some diagnostics can include "text art" diagrams 🎨: visualizations made out of text and meant to be viewed in a monospaced font.
This option picks which characters get used to print those diagrams, if any 🖼️ CHARSET can be none, ascii, unicode, or emoji.
none— suppresses the printing of these diagrams entirely 🙈ascii— makes sure the diagrams are pure ASCII ("ASCII art") 🧸unicode— allows conservative use of Unicode drawing characters, like box-drawing characters 📦emoji— adds the option of emoji too, such as emitting U+26A0WARNING SIGNfollowed by U+FE0FVARIATION SELECTOR-16to pick the emoji version of the character ⚠️
The default is emoji, except when the environment variable LANG is set to C, in which case the default is ascii 🌸
-fno-diagnostics-show-nesting— okay so some diagnostics are nested, like a little tree 🌳 of sub-diagnostics, and it's usually when C++ templates get instantiated 💀. By default GCC makes these look cute with indentation and bullet points ✨, moves the location info onto its own lines so the structure is easier to read, and cuts out repeated info 🧹. Passing-fno-diagnostics-show-nestingturns off all that indenting, reformatting, and eliding and brings back the older "look" of the diagnostics 🕰️.-fno-diagnostics-show-nesting-locations— whenfdiagnostics-show-nestingis on, file names and line and column numbers get their own lines apart from the messages 📍. You can hide that location info completely with-fno-diagnostics-show-nesting-locations. This one is for the GCC devs writing DejaGnu test cases 🧪, so it's not really for us, bestie 🫶.-fdiagnostics-show-nesting-levels— whenfdiagnostics-show-nestingis on, this also prints numbers showing how deep each nesting level goes 🔢. It's a debugging thing for GCC devs who are digging into nested diagnostics, but plugin authors might find it useful too 🧚.-fdiagnostics-format=FORMAT— pick a different way to print diagnostics 🎀.FORMATcan betext,sarif-stderr, orsarif-file. Using this replaces any extra "output sinks" added by-fdiagnostics-add-output=or set by-fdiagnostics-set-output=🙅♀️. The default istext💖. Bothsarif-stderrandsarif-filespit out diagnostics in SARIF Version 2.1.0 format 🦋, either to stderr or to a file calledsource.sarif, respectively.-fdiagnostics-add-output=DIAGNOSTICS-OUTPUT-SPEC— add an extra "output sink" for diagnostics 🚰. The spec starts with a scheme, optionally followed by:and one or moreKEY=VALUEpairs, looking like this:
<SCHEME>
<SCHEME>:<KEY>=<VALUE>
<SCHEME>:<KEY>=<VALUE>,<KEY2>=<VALUE2>etc. ✨
Heads up 🚨: schemes, keys, or values with a name starting with "experimental" might change or get removed without notice 🙈. Keys can belong to one specific scheme or be GCC-wide 🌈. Here are the schemes you can use:
🖥️ text
Emits diagnostics to stderr using GCC's classic text output format 📟. These keys are supported for text:
color=[yes|no]— overrides the colour settings from-fdiagnostics-colorfor this text output 🎨.show-nesting=[yes|no]— turns on a mode that shows the hierarchy within diagnostics, same as-fdiagnostics-show-nesting🌳. Defaults to "yes".show-nesting-locations=[yes|no]— ifshow-nesting=yes, locations are shown by default 📍. Set this to "no" to hide them. Again, this is for GCC devs writing DejaGnu test cases 🧪.show-nesting-levels=[yes|no]— a debugging option that works withshow-nesting=yes🔍. Set it to "yes" to print explicit nesting levels in the output. Also GCC-dev territory 👩💻.
📦 sarif
Emits diagnostics to a file in SARIF format 🗂️. These keys are supported for sarif:
file=FILENAME— the name of the file the SARIF output gets written to, which can include a leading absolute or relative path 📁. If you don't specify it, it defaults tosource.sarif💅.serialization=[json]— the serialization format for writing the SARIF out 🧾. Right now it can only be "json", but it's there as an extension point for trying out other serializations 🔧.version=[2.1|2.2-prerelease]— the SARIF version for the output 🏷️. If you don't pick one, it defaults to 2.1. "2.2-prerelease" uses an unofficial draft of the future SARIF 2.2 spec, so it should only be used for experimenting in this release 🧪.
There's also this key meant for GCC devs, not end-users, and it can change or disappear without notice 👀:
state-graphs=[yes|no]— a debugging feature that defaults to "no" 🐛. If you set "yes", GCC tries to capture detailed state info from-fanalyzerin the generated SARIF 🔬.
🌐 experimental-html
Emits diagnostics to a file in HTML format 💻. This scheme is experimental and may go away in future GCC releases 🫣. The keys and output details can change too. These keys are supported for experimental-html:
css=[yes|no]— adds an embedded<style>to the generated HTML 💅. Defaults to yes.file=FILENAME— the name of the file the HTML output gets written to, which can include a leading absolute or relative path 📁. If you don't specify it, it defaults tosource.html🌸.javascript=[yes|no]— adds an embedded<script>to the generated HTML, giving you a barebones UI for viewing results 🖱️. Defaults to yes.
These keys are also for GCC devs and not end-users, and they can change or be removed without notice 🙃:
show-state-diagrams=[yes|no]— a debugging feature that defaults to "no" 🐞. If you set "yes", GCC tries to usedotto make SVG diagrams in the HTML, showing the state at each event in a diagnostic path 🗺️. You view them by pressing "j" and "k" to step forward and backward through events ⬆️⬇️. Turning this on will slow down HTML generation 🐌.show-graph-dot-src=[yes|no]— another debugging feature that defaults to "no" 🔬. If you setshow-graph-dot-src=yesandshow-state-diagrams=yes, the state diagrams also show the.dotsource input to GraphViz used for the diagram 📜.show-graph-sarif=[yes|no]— a debugging feature that defaults to "no" 🧠. If you setshow-graph-sarif=yesandshow-state-diagrams=yes, the state diagrams also show a SARIF representation of the state 🧩.
Besides the scheme-specific keys, this GCC-related key works on sinks of any scheme 🌈:
cfgs=[yes|no]— if you setcfgs=yesfor a sink, GCC tries to send info about the control flow graphs for the functions it's compiling 🕸️. Text sinks ignore this info. SARIF sinks add the graphs withintheRun.graphs📊. HTML sinks generate SVG showing the graphs 🖼️. The exact form of the info can change without notice ⚠️.
Here's a cute example 🎀:
-fdiagnostics-add-output=sarif:version=2.1,file=foo.2.1.sarif
-fdiagnostics-add-output=sarif:version=2.2-prerelease,file=foo.2.2.sarifThis adds a pair of outputs, each writing to a different file, using versions 2.1 and 2.2 of the SARIF standard respectively 👯♀️.
And here's the EBNF, for the nerds 🤓:
<diagnostics-output-specifier> = <diagnostics-output-name>
| <diagnostics-output-name>, ":", <key-value-pairs>;
<diagnostics-output-name> = "text" | "sarif" | "experimental-html";
<key-value-pairs> = <key-value-pair>
| <key-value-pair> "," <key-value-pairs>;
<key-value-pair> = <key> "=" <value>;
<key> = ? string without a '=' ? ;
<value> = ? string without a ',' ? ;-fdiagnostics-set-output=DIAGNOSTICS-OUTPUT-SPEC— this works like-fdiagnostics-add-output=, except instead of adding an extra sink 🔄, it replaces all the existing output sinks 💥. That includes sinks from-fdiagnostics-format=,-fdiagnostics-add-output=, or a previous-fdiagnostics-set-output=call 🧹.-fno-diagnostics-json-formatting— by default, when JSON is emitted for diagnostics (via-fdiagnostics-format=sarif-stderror-fdiagnostics-format=sarif-file), GCC adds newlines and indentation so the JSON structure is easier to see 👀. Use-fno-diagnostics-json-formattingto suppress that whitespace 🫧. It must be passed before the option it's supposed to affect ⚠️. This is meant for compatibility with tools that don't expect newlines in the output, like the output from older GCC releases 🕰️.
✨ Options to Request or Suppress Warnings ✨
Warnings are diagnostic messages that report constructions that aren't inherently wrong but are risky or suggest there might have been an error ⚠️. The language-independent options below don't turn on specific warnings 🙅♀️. Instead, they control the kinds of diagnostics GCC produces 🎛️.
-fsyntax-only— checks the code for syntax errors and doesn't do anything beyond that 🔍.-fmax-errors=n— limits the maximum number of error messages ton🧱. Once it hits that number, GCC bails out instead of trying to keep processing the source code 🏃♀️. Ifnis 0 (the default), there's no limit on how many error messages get produced ♾️. If-Wfatal-errorsis also specified,-Wfatal-errorstakes precedence over this option 👑.-w,--no-warnings— inhibits all warning messages 🔇.-Werror— turns all warnings into errors 💥.-Werror=— turns the specified warning into an error 🎯. You append the warning's specifier, so for example-Werror=switchturns the warnings controlled by-Wswitchinto errors 🚨. This switch also has a negative form, which negates-Werrorfor specific warnings. For example,-Wno-error=switchmakes-Wswitchwarnings not be errors, even when-Werroris in effect 🫶.
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 described above 🔁. (Printing the option in the warning message can be disabled with the -fno-diagnostics-show-option flag 🙈.)
Note that specifying-Werror=fooautomatically implies-Wfoo💅. However,-Wno-error=foodoes not imply anything 🙅♀️.
-Wfatal-errors— okay bestie, this one is a whole mood 💀 It makes the compiler stop dead at the very first error it finds, instead of pushing on and spamming you with more error messages.
You can ask for loads of specific warnings with options that start with -W, like -Wunused-variable to get warnings about declarations of variables that never get used 👀 Every one of these also has a negative form starting with -Wno- that turns the warning off, so -Wno-unused-variable is the opposite. This manual only lists one of the two forms, whichever one isn't the default 🌸 For more language-specific stuff, check out C++ Dialect Options and Objective-C and Objective-C++ Dialect Options. Extra warnings can also come from turning on the static analyzer;
Some options, like -Wall and -Wextra, switch on other options, like -Wunused, which might switch on even more, like -Wunused-variable. Positive and negative forms combine so that more specific options beat less specific ones, no matter where they sit on the command line. For options that are equally specific, the last one wins ✨ Options turned on or off with pragmas act as if they were at the very end of the command line 🧚
When you request an unrecognized warning (e.g., -Wunknown-warning), GCC throws an error saying the option isn't recognized. The -Wno- form is chiller, though: no diagnostic gets produced for -Wno-unknown-warning unless other diagnostics are being produced anyway. That lets you use new -Wno- options with old compilers, but if something goes sideways, 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. Some other warnings won't be issued at all unless optimization is on. Optimization in general makes warnings about control and data-flow problems better, but in some cases it can also cause false positives 🫶
-Wpedantic,-pedantic,--pedantic— issue all the warnings strict ISO C and ISO C++ demand, diagnose every program that uses forbidden extensions, and some other programs that don't follow ISO C and ISO C++ either. This follows whichever version of the ISO C or C++ standard you pick with any-stdoption 📚
Valid ISO C and ISO C++ programs should compile properly with or without this option (though a rare few need -ansi or a -std option naming the version of the standard). Without this option, certain GNU extensions and traditional C and C++ features are supported too. With this option, they get diagnosed (or rejected with -pedantic-errors).
-Wpedantic doesn't cause warnings for use of the alternate keywords whose names begin and end with __. That alternate format can also 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; 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 given with -std is a GNU extended dialect of C, such as gnu90 or gnu99, there's 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 wouldn't make sense for these warnings to only cover features outside the specified GNU C dialect, since by definition the GNU dialects include every feature the compiler supports with the given option, so there'd be nothing to warn about 🤷)
-pedantic-errors,--pedantic-errors— give an error whenever the base standard (see-Wpedantic) requires a diagnostic, in some cases where there's undefined behavior at compile time, and in some other cases that don't prevent compilation of programs that are valid according to the standard. 🚨
This is not equivalent to -Werror=pedantic: the latter is unlikely to be useful, because it only turns errors of the diagnostics controlled by -Wpedantic into errors. This option also affects required diagnostics that are always enabled or controlled by options other than -Wpedantic.
If you want the required diagnostics that are warnings by default to be errors instead, but don't also want to enable the -Wpedantic diagnostics, you can specify -pedantic-errors -Wno-pedantic (or -pedantic-errors -Wno-error=pedantic to enable them but only as warnings).
Some required diagnostics are errors by default, but can be reduced to warnings using -fpermissive or their specific warning option, e.g. -Wno-error=narrowing.
Some diagnostics for non-ISO practices are controlled by specific warning options other than -Wpedantic, but are also made errors by -pedantic-errors. 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— downgrades some required diagnostics about nonconformant code from errors to warnings, so it lets some nonconforming code compile. 😌 Some C++ diagnostics are controlled only by this flag, but it also downgrades some C and C++ diagnostics that have their own flag:-Wabbreviated-auto-in-template-arg(C++ and Objective-C++ only),-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),-Wtemplate-body(C++ and Objective-C++ only)
The -fpermissive option is the default for the historic C language modes (-std=c89, -std=gnu89, -std=c90, -std=gnu90) 🦋
-Wall,--all-warnings— this enables all the warnings about constructions that some users consider questionable and that are easy to avoid (or modify to prevent the warning), even in conjunction with macros. It also enables some language-specific warnings described in C++ Dialect Options and Objective-C and Objective-C++ Dialect Options 🎀
-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
Note that some warning flags are not implied by -Wall. Some of them warn about constructions that users generally don't consider questionable, but which you might occasionally want to check for. Others warn about constructions that are necessary or hard to avoid in some cases, and there's no simple way to modify the code to suppress the warning. Some of them are enabled by -Wextra, but many must be enabled individually 🧐
-Wextra,--extra-warnings— enables some extra warning flags that aren't enabled by-Wall. (This option used to be called-W. The older name is still supported, but the newer name is more descriptive 💜)
okay so the warning squad is still coming in hot 🔥 here's the rest of the -W lineup, and yes, I'm obsessed 💅
-Wabsolute-value(only for C/ObjC) ✨-Walloc-size🌸-Wcalloc-transposed-args🦋-Wcast-function-type💖-Wclobbered🧚-Wdangling-reference(C++ only) 👑-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-name(C/ObjC only) 💅-Wmissing-parameter-type(C/ObjC only) ✨-Wold-style-declaration(C/ObjC only) 💀-Wmultiple-parameter-fwd-decl-lists(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⭐-Wunterminated-string-initialization(C/ObjC only) 😭-Wunused-parameter(only with-Wunusedor-Wall) 🍓-Wunused-but-set-parameter(only with-Wunusedor-Wall) 🌈
ngl -Wextra gets a bonus round 👑 it also flags these cases:
- 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 so -Wabi is the one that yells when your code gets hit by ABI changes 😭 That includes code that might not be compatible with the vendor-neutral C++ ABI, plus the psABI for your particular target. The psABI warnings have their own switch, -Wpsabi, and -Wabi implies it 🫶
Since G++ now defaults to updating the ABI with each major release, -Wabi usually only warns about C++ ABI compatibility problems when a check got added later in a release series for an ABI issue found after the initial release 💅 But if you pick an older ABI version with -fabi-version=n, -Wabi gets way more chatty 🙈
You can also give -Wabi an explicit version number, like -Wabi=2, to check C++ ABI compatibility against a particular -fabi-version level. So -Wabi=2 warns about changes relative to -fabi-version=2 🦋
If you give an explicit version number and don't set -fabi-compat-version, that number is used for compatibility aliases. If you skip the number on this option but DO set -fabi-compat-version, that version is used for C++ ABI warnings instead 🌸
Real talk: they tried to catch every case 🥺 but there are probably some sneaky ones that slip through even when G++ is generating incompatible code. And sometimes you'll get warnings even though the generated code is totally compatible. Not ideal, but that's life 💀
If you're worried that G++ output might not be binary compatible with code from other compilers, bestie, you should rewrite your code to dodge these warnings 💖
Known incompatibilities in -fabi-version=2 (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 does not 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 was folded away 💀
These mangling issues were fixed in -fabi-version=5 ✅
- Scoped enumerators passed as arguments to a variadic function are promoted like unscoped enumerators, causing
va_argto complain. On most targets this does not actually affect the parameter passing ABI, as there is no way to pass an argument smaller thanint🤓
Also, the ABI 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 with function-cv-qualifiers, the un-qualified function type was incorrectly treated as a substitution candidate 🤯
This was fixed in -fabi-version=8, the default for GCC 5.1 ✅
decltype(nullptr)incorrectly had an alignment of 1, leading to unaligned accesses. Note that this did not affect the ABI of a function with anullptr_tparameter, as parameters have a minimum alignment 🫠
This was fixed in -fabi-version=9, the default for GCC 5.2 ✅
- Target-specific attributes that affect the identity of a type, such as ia32 calling conventions on a function type (stdcall, regparm, etc.), did not affect the mangled name, leading to name collisions when function pointers were used as template arguments 💥
This was fixed in -fabi-version=10, the default for GCC 6.1 ✅
🦋 -Wpsabi (C, Objective-C, C++ and Objective-C++ only)
-Wpsabi enables warnings about processor-specific ABI changes, like changes in alignment requirements or how function arguments get passed 🧚 On several targets, including AArch64, ARM, x86, MIPS, RS6000/PowerPC, and S/390, these details have changed between different GCC versions and/or different versions of the C or C++ language standards, in ways that affect binary compatibility of compiled code 😵💫 With -Wpsabi, GCC can detect potentially incompatible usages and warn you about them 💖
-Wpsabi is enabled by default, and is also implied by -Wabi ✨
💜 -Wno-changes-meaning (C++ and Objective-C++ only)
C++ requires that unqualified uses of a name within a class have the same meaning in the complete scope of the class, so declaring the name after using it 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 the two declarations have the same type, while the B2 case is an error. Both diagnostics can be disabled with -Wno-changes-meaning. Alternately, the error case can be reduced to a warning with -Wno-error=changes-meaning or -fpermissive 🔧
Both diagnostics are also suppressed by -fms-extensions 🌸
🍓 -Wchar-subscripts
This warns if an array subscript has type char 😭 It's a super common mistake because people forget that char is signed on some machines. This warning is enabled by -Wall ✅
🌈 -Wno-coverage-mismatch
This warns if feedback profiles don't match when you use the -fprofile-use option. If a source file gets changed between compiling with -fprofile-generate and with -fprofile-use, the files with the profile feedback can fail to match the source file, and then GCC can't use the profile feedback information 🥺 By default, this warning is enabled and is treated as an error. -Wno-coverage-mismatch can disable the warning, or -Wno-error=coverage-mismatch can disable the error 🙃
Disabling the error for this warning can result in poorly optimized code. It's only useful for very minor changes, like bug fixes to an existing code-base. Completely disabling the warning is not recommended 🚫
🎀 -Wno-coverage-too-many-conditions
This warns if -fcondition-coverage is used and an expression has too many terms, so GCC gives up on coverage. Coverage gets given up when there are more terms in the conditional than there are bits in a gcov_type_unsigned 🤯 This warning is enabled by default ✅
🧚 -Wno-coverage-too-many-paths
This warns if -fpath-coverage is used and a function has too many paths, so GCC gives up on coverage. Giving up is controlled by -fpath-coverage-limit. This warning is enabled by default ✅
💖 -Wno-coverage-invalid-line-number
This warns in case a function ends earlier than it begins because of invalid linenum macros 🫠 The warning is only emitted with --coverage enabled.
By default, this warning is enabled and is treated as an error. -Wno-coverage-invalid-line-number can disable the warning, or -Wno-error=coverage-invalid-line-number can disable the error 💅
🌸 -Wno-cpp (C, Objective-C, C++, Objective-C++ and Fortran only)
This suppresses warning messages emitted by #warning directives 🤫
👑 -Wdouble-promotion (C, C++, Objective-C and Objective-C++ only)
Okay this one is so sneaky 😭 It gives a warning when a value of type float is implicitly promoted to double. CPUs with a 32-bit single-precision floating-point unit implement float in hardware, but emulate double in software. On a machine like that, doing computations with double values is much more expensive because of the overhead required for software emulation 🐢
It's super easy to accidentally do computations with double, because floating-point literals are implicitly of type double. For example, in:
float area(float radius)
{
return 3.14159 * radius * radius;
}the compiler performs the entire computation with double because the floating-point literal is a double 🙈
🫶 -Wduplicate-decl-specifier (C and Objective-C only)
This warns if a declaration has a duplicate const, volatile, restrict or _Atomic specifier 🍓 This warning is enabled by -Wall ✨
-Wformat,-Wformat=n— okay so this one is the format police 👮♀️✨ It checks your calls toprintfandscanf(and their crew) to make sure the arguments you pass actually match the types the format string asks for, and that the conversions in the format string make sense. That includes the standard functions plus anything tagged with format attributes, across theprintf,scanf,strftimeandstrfmon(an X/Open extension, not in the C standard) families, or other target-specific families. Which functions get checked without a format attribute depends on the standard version you picked, and those checks get turned off by-ffreestandingor-fno-builtin. 🫶
The formats get checked against the format features supported by GNU libc version 2.2. That covers all ISO C90 and C99 features, 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 you 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 selected standard version (just not for strfmon formats, since those aren't in any version of the C standard).
-Wformat=1,-Wformat—-Wformatis the same thing 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 bits of this level can be switched off with-Wno-format-contains-nul,-Wno-format-diag,-Wno-format-extra-args, and-Wno-format-zero-length. And yes,-Wformatis enabled by-Wall🌸-Wformat=2— level up! ⭐ This turns on-Wformatplus additional format checks. Right now it's the same as-Wformat -Wformat-nonliteral -Wformat-security -Wformat-y2k. Iconic behaviour, no notes.
-Wno-format-contains-nul— if you've got-Wformaton, this tells GCC to chill and not warn about format strings that contain NUL bytes. 🙈-Wno-format-diag— if-Wformatis on, this stops GCC from warning about format strings that aren't suitable for GCC's own diagnostics. 🦋-Wno-format-extra-args— if-Wformatis on, GCC won't yell about excess arguments to aprintforscanfformat function. The C standard says those extra arguments just get ignored, so it's not really a crime 🙃
Where the unused arguments sit between used arguments that use $ operand number specifications, GCC will normally still warn you anyway. The reason is that the implementation can't know what type to hand to va_arg to skip the unused ones. HOWEVER, for scanf formats, this option does suppress the warning if the unused arguments are all pointers, because the Single Unix Specification says those unused pointer arguments are allowed. ✨
-Wformat-overflow,-Wformat-overflow=level— okay this one is giving buffer-safety vibes 🧚 It warns about calls to formatted I/O functions likesprintfandvsprintfthat might overflow the destination buffer. When GCC can't work out exactly how many bytes a format directive writes at compile time, it guesses using heuristics that depend on the level and on optimization. Turning on optimization usually makes the warning more accurate, but it can also cause false positives. 😭-Wformat-overflow=1,-Wformat-overflow— level 1 is enabled by-Wformatand is the cautious one. It only warns about calls that will most likely overflow the buffer. At this level, numeric arguments to format directives 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 that range produces the most output bytes. For example, thesprintfcall below gets diagnosed because 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 dodge the actual 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 given an argument of sufficient length or 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 that can't be assumed to be bounded by the directive's precision, by a finite set of string literals they might evaluate to, or by the character array they might point to, are assumed to be 1 character long. At this level, the example above gets diagnosed again, but this time because withaequal to a 32-bitINT_MIN, the first%idirective will write some of its digits past the end of the destination buffer. To make the call safe no matter what the two variables are, the destination buffer needs to be at least 34 bytes. GCC even includes the minimum buffer size in an informational note after the warning. Helpful, bestie 💖
An alternative to making the buffer bigger is to constrain the formatted values. You can bound the maximum length of string arguments by specifying the precision in the format directive. And when numeric arguments can be assumed to be bounded by less than the precision of their type, picking an appropriate length modifier for the specifier will shrink the required buffer size. For example, if a and b in the example above can be assumed to be within the precision of the short int type, then using either the %hi format directive or casting the argument to short brings the maximum required buffer size down 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— if-Wformatis specified, GCC won't warn about zero-length formats. The C standard says zero-length formats are allowed, so this one is valid, no cap 🧸-Wformat-nonliteral— if-Wformatis specified, GCC will also warn if the format string isn't a string literal, since that means it can't be checked. The exception is when the format function takes its format arguments as ava_list. 🌈-Wformat-security— if-Wformatis specified, this also warns about uses of format functions that could be security problems. Right now it warns about calls toprintfandscanffunctions where the format string isn't a string literal and there are no format arguments, likeprintf (foo);. That can be a 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 might be added to-Wformat-securitythat aren't included in-Wformat-nonliteral.)-Wformat-signedness— if-Wformatis specified, this also warns if the format string needs an unsigned argument and you pass a signed one, and vice versa. 🦢-Wformat-truncation,-Wformat-truncation=level— this one is the truncation watcher 👑 It warns about calls to formatted I/O functions likesnprintfandvsnprintfthat might cut off the output. Same deal as-Wformat-overflow: if the exact byte count can't be known at compile time, GCC estimates it with heuristics that depend on the level and on optimization. Optimization usually helps accuracy, but might also cause false positives. Unless noted otherwise, it uses the same logic as-Wformat-overflow.-Wformat-truncation=1,-Wformat-truncation— level 1 is enabled by-Wformatand is the careful version. It only warns about calls to bounded functions whose return value is unused and that will most likely result in truncated output. 💅-Wformat-truncation=2— level 2 also warns about calls to bounded functions whose return value is used and that might truncate the output, given an argument of sufficient length or magnitude. 🌸
-Wformat-y2k— if-Wformatis specified, this also warns aboutstrftimeformats that may only yield a two-digit year. Y2K energy, and not the good kind 💀-Wnonnull— warns about passing a null pointer for arguments 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. 🤨-Wnonnull-compareis included in-Wall, and it can be disabled with-Wno-nonnull-compare.-Wnull-dereference— warns if the compiler detects paths that trigger erroneous or undefined behavior because a null pointer gets dereferenced. ⚠️ This option only works when-fdelete-null-pointer-checksis active, which optimizations turn on for most targets. How precise the warnings are depends on the optimization options you use.-Wno-musttail-local-addr— don't warn about passing a pointer (or, in C++, a reference) to a local variable or label as an argument to amusttailcall. Those variables go out of scope before the tail call instruction, so this is the "I know what I'm doing" switch 🦋-Wmaybe-musttail-local-addr— warns when the address of a local variable can escape to amusttailcall, unless the variable already goes out of scope before themusttailcall. Main-character warning for your pointers 🎀
int foo (int *); int
bar (int *x)
{
if (x[0] == 1)
{
int a = 42;
foo (&a);
/* Without the C<musttail> attribute this call would not
be tail called, because address of the C<a> variable escapes
and the second foo call could dereference it. With the attribute
the local variables are assumed to go out of scope immediately
before the tail call instruction and the compiler warns about
this. */
[[gnu::musttail]] return foo (nullptr);
}
else
{
{
int a = 42;
foo (&a);
}
/* The C<a> variable isn't already in scope, so even when it
escaped, even without C<musttail> attribute it would be
undefined behavior to dereference it and the compiler could
turn this into a tail call. No warning is diagnosed here. */
[[gnu::musttail]] return foo (nullptr);
}
}This warning is enabled by -Wextra. ✨
🎀 -Wnrvo (C++ and Objective-C++ only)
okay so this one is all about the Named Return Value Optimization (aka NRVO) 💅 It warns when the compiler doesn't skip copying a local variable into the return value, even though [class.copy.elision] says it's allowed to. The compiler could do it, it just didn't, and this flag lets you know. 🫶
Here's the example. The compiler can't skip the copy from both v1 and v2, so it skips neither. 🙃
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, and it's giving main character energy because it works at all optimization levels 🔥 Heads up though, catching infinite recursion between two or more functions needs optimization turned on. -Winfinite-recursion is included in -Wall. 👑
Compare this with -Wanalyzer-infinite-recursion, which gives a similar diagnostic but is implemented in a different way (as part of -fanalyzer). 🧚
🦋 -Winit-self (C, C++, Objective-C and Objective-C++ only)
This one warns about uninitialized variables that get initialized with themselves 🙈 Note that this option can only be used with the -Wuninitialized option.
GCC warns about "i" being uninitialized in the following snippet only when -Winit-self has been 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 option controls warnings when a declaration doesn't specify a type. It's enabled by default, as an error, in C99 and later dialects of C, 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 option controls warnings when a function is used before it's declared. It's enabled by default, as an error, in C99 and later dialects of C, and also by -Wall. You can downgrade it to a warning with -fpermissive (along with certain other errors), or for this error alone, with -Wno-error=implicit-function-declaration. 🍓
Yep, -pedantic-errors upgrades this one to an error too. 💀
🍓 -Wimplicit (C and Objective-C only)
Same as -Wimplicit-int and -Wimplicit-function-declaration. It's enabled by -Wall. ✨
🔥 -Whardened
This one warns when -fhardened didn't enable an option from its set (see -fhardened for the full lineup). For example, if you use -fhardened and -fstack-protector at the same time on the command line, -Whardened will warn, because -fstack-protector-strong won't be enabled by -fhardened. 🛡️
It's enabled by default, and it only has an effect when -fhardened is enabled. 🌸
🧚 -Wimplicit-fallthrough
-Wimplicit-fallthrough is the same as -Wimplicit-fallthrough=3, and -Wno-implicit-fallthrough is the same as -Wimplicit-fallthrough=0. 🦋
🫧 -Wimplicit-fallthrough=n
okay so this 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;
}It does not warn 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. 🙌
This also takes control flow statements into account, such as ifs, and it only warns when it's appropriate. E.g.
switch (cond)
{
case 1:
if (i > 3) {
bar (5);
break;
} else if (i < 1) {
bar (0);
} else
return;
default:
...
}Sometimes a case fall through is totally intentional, so GCC gives you an attribute, __attribute__ ((fallthrough)), to be used along with a null statement to suppress the warning that would normally happen:
switch (cond)
{
case 1:
bar (0);
__attribute__ ((fallthrough));
default:
...
}In C++17 and C23 there's a standard way to do this 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 which kind of comments are accepted:
-Wimplicit-fallthrough=0disables the warning altogether. 🚫-Wimplicit-fallthrough=1matches".*"regular expression, so any comment counts as a fallthrough comment. 💬-Wimplicit-fallthrough=2case insensitively matches".*falls?[ \t-]*thr(ough|u).*"regular expression. 🔍-Wimplicit-fallthrough=3case sensitively matches one of the following regular expressions:"-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=4case sensitively matches one of the following regular expressions:"-fallthrough""@fallthrough@""lint -fallthrough[ \t]*""[ \t]*FALLTHR(OUGH|U)[ \t]*"
-Wimplicit-fallthrough=5doesn't recognize any comments as fallthrough comments, so only attributes disable the warning. 🙅
The comment has to be followed, after optional whitespace and other comments, by a case or default keyword, or by a user label that comes right before some case or default label. 🎀
switch (cond)
{
case 1:
bar (0);
/* FALLTHRU */
default:
...
}The -Wimplicit-fallthrough=3 warning is enabled by -Wextra. 💅
🌙 -Wno-if-not-aligned (C, C++, Objective-C and Objective-C++ only)
This controls whether warnings triggered by the warn_if_not_aligned attribute get issued. These warnings are enabled by default. 🫧
🍑 -Wignored-qualifiers (C and C++ only)
Warns if a function's return type has a type qualifier such as const. In ISO C, that qualifier has no effect, since the value returned by a function isn't an lvalue. In C++, the warning is only emitted for scalar types or void. ISO C prohibits qualified void return types on function definitions, so those always get a warning, even without this option. 😭
This warning is also enabled by -Wextra. ✨
🙈 -Wno-ignored-attributes (C and C++ only)
This option controls warnings when an attribute is ignored. It's different from the -Wattributes option, because it warns whenever the compiler decides to drop an attribute, not when the attribute is unknown, used in the wrong place, and so on. This warning is enabled by default. 🌸
👑 -Wmain
Warns if the type of main is suspicious. main should be a function with external linkage, returning int, taking either zero arguments, two, or three arguments of appropriate types. This warning is enabled by default in C++, and it's also enabled by either -Wall or -Wpedantic. 💖
Upgraded to an error by -pedantic-errors. 💀
🧁 -Wmisleading-indentation (C and C++ only)
Warns when the indentation of the code doesn't match the block structure. Specifically, a warning is issued for if, else, while, and for clauses with a guarded statement that doesn't use braces, followed by an unguarded statement with the same indentation. 🫣
In the following example, the call to bar is misleadingly indented as if it were guarded by the if conditional:
if (some_condition ())
foo ();
bar (); /* Gotcha: this is not guarded by the "if". */With mixed tabs and spaces, the warning uses the -ftabstop= option to figure out whether the statements line up (it defaults to 8). 📏
The warning is not issued for code involving multiline preprocessor logic, such as the following example:
if (flagA)
foo (0);
#if SOME_CONDITION_THAT_DOES_NOT_HOLD
if (flagB)
#endif
foo (1);Okay so the warning is not issued after a #line directive 🙈 That usually means the code was autogenerated, and nobody can assume anything about the layout of the file the directive points to. Respect the vibe.
This warning is enabled by -Wall in C and C++ ✨
-Wmissing-attributes— bestie, this one flags a function declaration that's missing an attribute a related function was declared with, when that absence could hurt the correctness or efficiency of the generated code 💅 The classic example is an alias that uses attributes to ask for less strict stuff than its target. That's basically a potential optimization opportunity. The flip side is-Wattribute-alias=2, which warns when the alias is more restrictive than the target, and that one can lead to incorrect code generation 😭 The attributes it keeps an eye on are "alloc_align", "alloc_size", "cold", "const", "hot", "leaf", "malloc", "nonnull", "noreturn", "nothrow", "pure", "returns_nonnull", and "returns_twice".
In C++, it warns when an explicit specialization of a primary template is declared without one of these attributes: "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 slap the same set of attributes onto a declaration as another declaration has, without listing them all out. It works on declarations of functions, variables, or types. Peep Common Attributes too 🎀
-Wmissing-attributes is enabled by -Wall.
Like, since the primary function template below uses both "malloc" and "alloc_size", 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 when an aggregate or union initializer isn't fully bracketed 🧚 In this example,ais not fully bracketed, butbis, and that's the whole difference 💖
int a[2][2] = { 0, 1, 2, 3 }; int b[2][2] = { { 0, 1 }, { 2, 3 } };
This warning is enabled by -Wall.
-Wmissing-include-dirs(C, C++, Objective-C, Objective-C++ and Fortran only) — warns if a user-supplied include directory doesn't exist 📂 It's off by default for C, C++, Objective-C and Objective-C++. For Fortran, it's partially on by default, but only for-Iand-J🌸-Wno-missing-profile— this one is about feedback profiles going missing when you use-fprofile-use✨ It calls out cases where a new function or a new file got added between-fprofile-generateand-fprofile-usewithout regenerating the profiles. The profile feedback data files then have no info for that new function or file. Also, if profile count data (.gcda) files get deleted, GCC can't use any profile feedback info at all. In all these cases you get a warning telling you a profile generation step is due 🥺 Ignoring it can leave you with poorly optimized code.
-Wno-missing-profile can turn the warning off, but that's not recommended 🚫 Only do it when having non-existent profile data is actually justified.
-Wmismatched-dealloc— warns on calls to deallocation functions that get pointer arguments returned from allocation functions the former isn't a suitable deallocator for 🔥 You can pair up matching allocators and deallocators with themallocattribute. Unless-fno-builtinis in play, the standard "calloc", "malloc", "realloc", and "free" are implicitly paired up, same goes for C++ "operator new" and "operator delete" 🫶 In the example, "mydealloc" is the deallocator for pointers from "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 sketchy multiple statement macros that look guarded by something like "if", "else", "for", "switch", or "while", where only the first statement actually ends up guarded once the macro expands 💀
#define DOIT x++; y++ if (c) DOIT;
This will increment "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 enabled by -Wall in C and C++.
-Wparentheses— warns when parentheses get left out in certain spots 🍓 Like when there's an assignment where a truth value is expected, or when operators are nested in a way people often get mixed up about.
It also warns if you write something like x<=y<=z. That's equivalent to (x<=y ? 1 : 0) <= z, which is a totally different reading from normal math notation 🤯
It warns for dangerous uses of the GNU extension to ?: with the middle operand omitted. When the condition in the ?: operator is a boolean expression, the omitted value is always 1. Programmers often expect it to be a value computed inside the conditional expression instead, so this is a major vibe check 🚩
For C++, this also warns about some unnecessary parentheses in declarations, which can mean someone was trying to make 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 enabled by -Wall.
-Wno-self-move(C++ and Objective-C++ only) — this warns when a value is moved to itself with "std::move" 🦋 That kind of "std::move" typically does nothing at all.
struct T { ... }; void fn() { T t; ... t = std::move (t); }
This warning is enabled by -Wall.
-Wsequence-point— warns about code that might have undefined semantics because it breaks the sequence point rules in the C and C++ standards 🌈 Okay this one is a lot, so bear with me 🫠
The standards define the order expressions get evaluated in using sequence points, which are a partial ordering between parts of the program: stuff executed before the sequence point, and stuff executed after it. They happen after a full expression is evaluated (one that isn't part of a larger expression), after the first operand of a "&&", "||", "? :" or "," (comma) operator is evaluated, before a function is called (but after its arguments and the expression naming the called function are evaluated), and in some other places too. Apart from what the sequence point rules say, the order subexpressions get evaluated in isn't specified. These 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 of those calls isn't specified. However, the standards committee has ruled that function calls do not overlap 🙌
It isn't specified when, between sequence points, changes to object values take effect. Programs that depend on that have undefined behavior. The C and C++ standards say that "Between the previous and next sequence point an object shall have its stored value modified at most once by the evaluation of an expression. Furthermore, the prior value shall be read only to determine the value to be stored.". If a program breaks these rules, results on any given implementation are completely unpredictable 😵
Examples of undefined behavior are "a = a++;", "a[n] = b[n++]" and "a[i++] = i;". Some trickier cases don't get diagnosed by this option, and it might occasionally give a false positive. Still, it's been found pretty effective at catching this kind of problem in programs ✨
The C++17 standard defines 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, so 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— don't warn about returning a pointer (or, in C++, a reference) to a variable that goes out of scope after the function returns 🌷 Okay, you do you 🫶-Wreturn-mismatch— okay bestie, this one is all about return statements 💅. It warns when a function that isn'tvoidhits areturnwith no expression 😭. It also warns when avoidfunction tries toreturnan expression, unless that expression is alsovoid🙈. As a GNU extension, that last case gets a free pass with no warning unless you've got-Wpedanticturned on 🧚.
💀 Heads up: using the return value of a non-voidfunction (other thanmain) that runs off the end by reaching its closing curly brace is undefined behavior. Don't do it, babe 🫶.
This warning is C-only and enabled by default ✨. In C99 and later dialects, it gets promoted to an error 🚫. You can soften it back into a regular warning with -fpermissive (which also softens other warnings) 🦋, or just for this one with -Wno-error=return-mismatch 🌸.
-Wreturn-type— this one checks a few things 🔍. It warns about a function defined with a return type that defaults toint(unless-Wimplicit-intis active, which takes priority 👑). It also warns if execution might reach the end of the function body, or if the function doesn't contain anyreturnstatement at all 💀.
💀 Same UB energy: using the return value of a non-voidfunction (other thanmain) that runs off the end by reaching its closing curly brace is undefined behavior.
Unlike in C, in C++, flowing off the end of a non-void function other than main is undefined behavior even when the function's value isn't used 😬. This warning is enabled by default in C++ and by -Wall otherwise 🌈.
-Wno-shift-count-negative— controls the warnings for a negative shift count 🙈. Heads up, this one is enabled by default.-Wno-shift-count-overflow— controls the warnings for when a shift count is greater than or equal to the bit width of the type 🧮. Enabled by default too.-Wshift-negative-value— warns if you left shift a negative value 🌀. It's 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 level you get from plain-Wshift-overflow, and it's enabled by default in C99 and C++11 modes (and newer) 💖. It doesn't warn about left-shifting1into the sign bit 🙃. (In C, though, that overflow still gets rejected in contexts where an integer constant expression is required.) No warning shows up in C++20 mode (and newer), since signed left shifts always wrap there 🦋.-Wshift-overflow=2— this level also warns about left-shifting1into the sign bit 😤, unless C++14 mode (or newer) is active.
-Wswitch— warns whenever aswitchhas an index of enumerated type and is missing acasefor one or more of that enum's named codes 🍓. Adefaultlabel stops this warning from firing 🛑.caselabels that don't match any enumerator also trigger warnings with this option, unless the enum is marked with theflag_enumattribute 🧚. This is enabled by-Wall✨.-Wswitch-default— warns whenever aswitchdoesn't have adefaultcase 🫠.-Wswitch-enum— warns about the same missing-casesituation as-Wswitch💅. The only difference is that this one still warns about an omitted enumeration code even if there's adefaultlabel 😤. Like-Wswitch,caselabels that don't correspond to enumerators also get warnings, unless the enum is marked with theflag_enumattribute 💜.-Wno-switch-bool— don't warn when aswitchhas an index of boolean type and the case values are outside the range of a boolean 🙅. 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 the range of its type 📏. Enabled by default for C and C++ programs ✨.-Wno-switch-unreachable— don't warn when aswitchhas statements between the controlling expression and the firstcaselabel, since those statements will never be executed 🏃♀️. For example:
switch (cond)
{
i = 15;
...
case 5:
...
}-Wswitch-unreachable doesn't warn if the statement between the controlling expression and the first case label is just a declaration 🙌. For example:
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 get used 🚨. Heads up, these functions changed semantics in GCC 4.4 😬.-Wtrivial-auto-var-init— warns when-ftrivial-auto-var-initcan't initialize an automatic variable 🫥. A super common case is an automatic variable declared between the controlling expression and the firstcaselabel of aswitch🌀.-Wunused-but-set-parameter— this is the same as-Wunused-but-set-parameter=3, and-Wno-unused-but-set-parameteris the same as-Wunused-but-set-parameter=0🎀.-Wunused-but-set-parameter=n— warns whenever a function parameter gets assigned to but is otherwise unused (aside from its declaration) 👀. To shush it, use theunusedattribute 🤫.-Wunused-but-set-parameter=0disables the warning 🙅.-Wunused-but-set-parameter=1means all uses except initialization and a left hand side of assignment that isn't used further will disable the warning 💅.-Wunused-but-set-parameter=2means that, additionally, uses of the parameter in++and--operators don't count as uses 🙃.-Wunused-but-set-parameter=3means that, additionally, uses in parm@=rhs outside of rhs don't count as uses 🧾. See-Wunused-but-set-variable=nfor examples 📚.
This -Wunused-but-set-parameter=3 warning is also enabled by -Wunused together with -Wextra ✨.
-Wunused-but-set-variable— this is the same as-Wunused-but-set-variable=3, and-Wno-unused-but-set-variableis the same as-Wunused-but-set-variable=0🧠.-Wunused-but-set-variable=n— warns whenever a local variable gets assigned to but is otherwise unused (aside from its declaration) 🫣. This-Wunused-but-set-variable=3warning is enabled by-Wall✨. To suppress it, use theunusedattribute 🤫.-Wunused-but-set-variable=0disables the warning 🙅.-Wunused-but-set-variable=1means all uses except initialization and a left hand side of assignment that isn't used further will disable the warning 💅.-Wunused-but-set-variable=2means that, additionally, uses of the variable in++and--operators don't count as uses 🙃.-Wunused-but-set-variable=3means that, additionally, uses in parm@=rhs outside of rhs don't count as uses 🧾.
This -Wunused-but-set-variable=3 warning is also enabled by -Wunused, which is enabled by -Wall 💖. Check out this example:
void foo (void)
{
int a = 1; // B<-Wunused-variable> warning
int b = 0; // Warning for <n> >= 1
b = 1; b = 2;
int c = 0; // Warning for <n> >= 2
++c; c--; --c; c++;
int d = 0; // Warning for <n> >= 3
d += 4;
int e = 0; // No warning, cast to void
(void) e;
int f = 0; // No warning, f used
int g = f = 5;
(void) g;
int h = 0; // No warning, preincrement used
int i = ++h;
(void) i;
int j = 0; // No warning, postdecrement used
int k = j--;
(void) k;
int l = 0; // No warning, l used
int m = l |= 2;
(void) m;
}-Wunused-function— warns whenever astaticfunction is declared but not defined, or when a non-inlinestaticfunction is unused 🕵️. Enabled by-Wall✨.-Wunused-label— warns whenever a label is declared but not used 🏷️. Enabled by-Wall. To suppress it, use theunusedattribute 🤫.-Wunused-local-typedefs(C, Objective-C, C++ and Objective-C++ only) — warns when atypedefdefined locally inside a function isn't used 🧁. Enabled by-Wall.-Wunused-parameter— warns whenever a function parameter is unused (aside from its declaration) 👻. This option isn't enabled by-Wunusedunless-Wextrais also specified 🧃. To suppress it, use theunusedattribute 🤫.-Wno-unused-result— don't warn if a caller of a function marked with thewarn_unused_resultattribute doesn't use its return value 🙅. The default is-Wunused-result💅.-Wunused-variable— warns whenever a local orstaticvariable is unused (aside from its declaration) 🫧. This option implies-Wunused-const-variable=1for C, but not for C++ 🌸. Enabled by-Wall✨. To suppress it, use theunusedattribute 🤫.-Wunused-const-variable,-Wunused-const-variable=n— warns whenever a constantstaticvariable is unused (aside from its declaration) 💜. To suppress it, use theunusedattribute 🤫.-Wunused-const-variable=1warns about unusedstatic constvariables defined in the main compilation unit 🎯, but not aboutstatic constvariables declared in any included header 🙈. 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, sinceconstvariables take the place of#defines 💅.
-Wunused-const-variable=2: okay so this level also warns about unused constant static variables in headers 📚, just not system headers 🙅♀️. It's the same as the short form-Wunused-const-variable. You have to ask for it explicitly in both C and C++ 💅 because cleaning up every header you've included can be genuinely hard 😭.-Wunused-value: ngl, this one is iconic 🔥. It warns whenever a statement computes a result that's explicitly not used 💀. To shut it up, cast the unused expression to"void". That covers an expression-statement or the left-hand side of a comma expression that has no side effects. Sox[i,j]gets flagged, butx[(void)i,j]is totally fine 🙈.- This warning is enabled by
-Wall✨.
- This warning is enabled by
-Wunused: all the above-Wunusedoptions combined, except the ones that have to be specified explicitly 🎀.- To get 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🧚. -Wunusedonly enables-Wunused-const-variable=1instead of-Wunused-const-variable, and only for C, not C++ 🙅♀️.
- To get a warning about an unused function parameter, you must either specify
-Wuse-after-free(C, Objective-C, C++ and Objective-C++ only) and-Wuse-after-free=n: this one warns about uses of pointers to dynamically allocated objects that were made indeterminate by a call to a deallocation function 🦋. It's enabled at all optimization levels, but the results can be different with optimization than without ⚠️.-Wuse-after-free=1: at level 1, the warning only tries to catch unconditional uses of pointers made indeterminate by a deallocation call or a successful call to"realloc", no matter whether that call actually reallocated memory 🌸. This includes double-"free"calls, plus uses in arithmetic and relational expressions. Uses of indeterminate pointers in equality (or inequality) expressions are undefined, but they aren't diagnosed at this level 🫶.-Wuse-after-free=2: at level 2, on top of unconditional uses, it also diagnoses conditional uses of pointers made indeterminate by a deallocation call 👑. As at level 2, uses in equality (or inequality) expressions aren't diagnosed. Here's a sneaky example where the second"free"gets flagged 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 💅. Every use of an indeterminate pointer is undefined, but equality tests sometimes pop up after"realloc"calls as an attempt to figure out whether the object got moved to a new address 🧐. They get their own level so legacy code can gradually move to safer alternatives 🌈. Here's the equality test that gets flagged 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 way you don't need to adjust the stored pointers after reallocation 🍓.
-Wuse-after-free=2is included in-Wall💜.
-Wuseless-cast(C, Objective-C, C++ and Objective-C++ only): 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 legit way to make 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 gets used without having been initialized 😱. In C++, it also warns if a non-static reference or non-static"const"member shows up in a class without constructors 🎀.- 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 also gets diagnosed here 🔍. (-Wmaybe-uninitializedhandles ordinary functions.) - If you want to warn about code that uses the uninitialized value of a variable in its own initializer, use the
-Winit-selfoption 🧠. - These warnings cover individual uninitialized elements of structure, union or array variables, as well as variables that are uninitialized as a whole 🧸. They do not occur for variables or elements declared
"volatile". Since these warnings depend on optimization, exactly which variables or elements get warned about depends on the precise optimization options and the version of GCC you're using 🌀. - There may be no warning about a variable that's only used to compute a value that itself is never used, because data flow analysis might delete those computations before the warnings get printed 🗑️.
- In C++, this warning also catches using uninitialized objects in member-initializer-lists. GCC warns about
"b"being uninitialized in this snippet 👇:
- Passing a pointer (or, in C++, a reference) to an uninitialized object into a
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 in thememory_orderenumeration 🧵. For example,__atomic_storeand__atomic_store_nare only defined for the relaxed, release, and sequentially consistent memory orders, so this code gets diagnosed 💀:
void store (int *i)
{
__atomic_store_n (i, 0, memory_order_consume);
}-Winvalid-memory-modelis 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 where it's initialized, but some other paths where it isn't, the compiler warns if it can't prove those uninitialized paths never run at runtime 🌙.- 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 attributeaccess (none)says the argument isn't used to access the object, and that avoids the warning 🙌. - These warnings are only possible in optimizing compilation, because otherwise GCC doesn't track the state of variables 🛠️. On the flip side,
-Wmaybe-uninitializedis known to miss plenty of situations (false negatives) because optimizations like constant propagation take advantage of the undefinedness of uninitialized uses 🤷♀️. - These warnings are optional because GCC may not be able to tell when code is correct even though it looks like an error 🥺. Here's one example of how that happens:
- Passing a pointer (or, in C++, a reference) to an uninitialized object into a
{
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 that 🥹. To suppress the warning, provide a default case withassert(0)or similar code 💅. - This option also warns when a non-volatile automatic variable might be changed by a call to
"longjmp". The compiler only sees the calls to"setjmp". It can't know where"longjmp"will be called, since a signal handler could call it at any point in the code 😵. So you might get a warning even when there's actually no problem, because"longjmp"can't really be called at the place that would cause one. - Some spurious warnings can be avoided if you declare all the functions you use that never return as
"noreturn"🌷. - This warning is enabled by
-Wallor-Wextra💜.
-Wunknown-pragmas: warns when a#pragmadirective shows up that GCC doesn't understand 🧩. If this command-line option is used, warnings are even issued for unknown pragmas in system header files. That's not the case if the warnings are only enabled by the-Wallcommand-line option 🚫.-Wno-pragmas: don't warn about misuses of pragmas, like incorrect parameters, invalid syntax, or conflicts between pragmas 🙈. See also-Wunknown-pragmas🔗.-Wno-pragma-once-outside-header: don't warn when#pragma onceis used in a file that isn't a header file, such as a main file 🌸.-Wno-prio-ctor-dtor: don't warn if a priority from 0 to 100 is used for a constructor or destructor 🎀. The constructor and destructor attributes let you assign a priority to control the order of execution beforemainis called or after it returns 🗝️. The priority values must be greater than 100, because the compiler reserves priority values between 0--100 for the implementation 🔒.-Wstrict-aliasing: this one is only active when-fstrict-aliasingis active 🌈. It warns about code that might break the strict aliasing rules the compiler uses for optimization ✨. It doesn't catch every case, but it does try to catch the more common pitfalls 🫶. It's included in-Wall, and it's equivalent to-Wstrict-aliasing=3💖.-Wstrict-aliasing=n— 💖 okay bestie, this one only works when-fstrict-aliasingis turned on. It checks for code that might break the strict aliasing rules the compiler uses for optimization ✨. Higher levels are more accurate (fewer false positives), but they also take more effort, kinda like how-Oworks 🧚.-Wstrict-aliasingis the same thing as-Wstrict-aliasing=3🎀.- Level 1 is the most aggressive, quick, and least accurate option 💅. It's useful when the higher levels don't warn but
-fstrict-aliasingstill breaks your code, since it has very few false negatives 😭. The catch is it has many false positives. It warns for every pointer conversion between possibly incompatible types, even if the pointer is never dereferenced. It only runs in the front end 🙈. - Level 2 is aggressive and quick but not super precise 🌸. It can still have a lot of false positives (just not as many as level 1), and few false negatives, though maybe more than level 1. Unlike level 1, it only warns when an address is taken. It also warns about incomplete types. It runs in the front end only 🫶.
- Level 3 is the default for
-Wstrict-aliasing👑. It should have very few false positives and very few false negatives 🔥. It's slightly slower than levels 1 or 2 when optimization is enabled. It handles 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 deals with 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 ✨.
-Wstrict-overflow,-Wstrict-overflow=n— 🌈 this one is only active when signed overflow is undefined. It warns when the compiler optimizes based on the assumption that signed overflow never happens. Heads up, it doesn't catch every spot where your code might overflow 🙈. It only warns where the compiler actually does some optimization, so this warning depends on your optimization level 💅.- An optimization that assumes signed overflow doesn't happen is totally safe if the values never actually overflow 💀. That's why this warning can easily give a false positive, meaning a warning about code that isn't actually a problem 😭. To help you focus on the important stuff, there are several warning levels 🎀. No warnings are 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=1warns about cases that are both questionable and easy to avoid 🌸. For example, the compiler simplifies"x + 1 > x"to 1. This level is enabled by-Wall. Higher levels aren't, so you have to ask for them explicitly 💖.-Wstrict-overflow=2also warns about other cases where a comparison gets simplified to a constant ✨. For example:"abs (x) >= 0". This can only be simplified when signed integer overflow is undefined, because"abs (INT_MIN)"overflows toINT_MIN, which is less than zero 🧚. Plain-Wstrict-overflowwith no level is the same as-Wstrict-overflow=2🎀.-Wstrict-overflow=3also warns about other comparisons that get simplified 🦋. For example:"x + 1 > 1"gets simplified to"x > 0"💅.-Wstrict-overflow=4also warns about other simplifications that aren't covered above 🔥. For example:"(x * 10) / 5"gets simplified to"x * 2"👑.-Wstrict-overflow=5also warns about cases where the compiler reduces the magnitude of a constant in a comparison 😭. For example:"x + 2 > y"gets simplified to"x + 1 >= y". This is only reported at the highest warning level 💀.
⚠️ This simplification applies to so many comparisons that this level gives a very large number of false positives 🙈.
-Wstring-compare— 🍓 this one warns for calls to"strcmp"and"strncmp"whose result is determined to be zero or non-zero in equality tests, because one argument's length is bigger than the size of the array the other argument is stored in (or the bound, for"strncmp") 🌈. Those calls could be mistakes 🙈. In the example below, the"strcmp"call gets flagged, since its result is necessarily non-zero no matter what's in the array"a"💅.
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");
}-Wstring-compare is enabled by -Wextra ✨.
-Wno-stringop-overflow,-Wstringop-overflow,-Wstringop-overflow=type— 🚨 this one warns about code that can be figured out at compile time to cause buffer overflows or memory overruns, like"memcpy"and"strcpy"calls that 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 string functions that work on character arrays. Raw memory functions like"memcpy"always use type-zero Object Size Checking 🫶.- It also warns for calls that specify a size bigger than the largest possible object, or at most
"SIZE_MAX / 2"bytes 💜. - This option gives the best results with optimization turned on 🔥. Even without optimization, it can catch a small subset of simple buffer overflows in calls to GCC built-in functions like
"__builtin_memcpy"that match the standard functions 🌸. Either way, it only warns about a subset of the overflows caught by the matching overflow checking built-ins, like"__builtin___memcpy_chk". Those can do run-time checking when the access can't be proven safe at compile time 🦋. - In the example below, this option warns about the
"strcpy"call because it copies at least 5 characters (the string"blue"plus the terminating NUL) into a buffer of size 4 🎀.
- It also warns for calls that specify a size bigger than the largest possible object, or at most
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
}This option isn't only for string or memory functions, either 👑. In the example below, a warning is issued because a 1-element array gets passed to a function that needs at least a 4-element array argument 💅.
void f (int[static 4]);
void g (void)
{
int *p = (int *) malloc (1 * sizeof(int));
f (p); // warning here
}-Wstringop-overflow=2 is enabled by default 💖.
-Wstringop-overflow,-Wstringop-overflow=1— this one uses type-zero Object Size Checking to figure out the sizes of destination objects 🌈. At this setting, it doesn't warn about 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 could 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 about the same code that gets flagged when the_FORTIFY_SOURCEmacro is defined to a non-zero value 🦋.-Wstringop-overflow=2— this one 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 doesn't warn about excessive writes to the same members of unknown objects referenced by pointers, since those pointers might point to arrays with unknown numbers of elements 🙈. This is the default setting for this option 👑.-Wstringop-overflow=3— this one 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 😭. This is the most restrictive setting that might warn about safe code too 💀.-Wstringop-overflow=4— this one 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 one to decide whether to warn 🧚. Like-Wstringop-overflow=3, this setting may result in warnings for benign code 🎀.
-Wno-stringop-overread— 🌊 this one warns for calls to string manipulation functions like"memchr"or"strcpy"that are determined to read past the end of the source sequence 🫶.-Wstringop-overreadis enabled by default ✨.-Wno-stringop-truncation— 🙅♀️ this one stops the warning for calls to bounded string manipulation functions like"strncat","strncpy", and"stpncpy"that might truncate the copied string or leave the destination unchanged 💖. In the example below, the"strncat"call 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, use"bufsize - strlen (buf) - 1)"as the bound 💅.
void append (char *buf, size_t bufsize)
{
strncat (buf, ".txt", 3);
}In another example, the "strncpy" call copies only the characters before the terminating NUL into "d", without adding the NUL to the end 🦋. Assuming the result of "strncpy" is always a NUL-terminated string is a super common mistake, so this call gets flagged 🙈. If the result isn't expected to be NUL-terminated, call "memcpy" instead to avoid the warning 🌸.
void copy (char *d, const char *s)
{
strncpy (d, s, strlen (s));
}Okay so this is the sketchy one 👀 Next up is the safe version. Here the strncpy call uses the size of the destination buffer as its bound, and if the source string is equal to or longer than that size, the copy won't be NUL-terminated. So GCC diagnoses it too 🚩 To dodge the warning, use sizeof buf - 1 as the bound and set the last element of the buffer to NUL. Literally one tiny fix, no cap 💅
void copy (const char *s)
{
char buf[80];
strncpy (buf, s, sizeof buf);
...
}Now, sometimes a character array is supposed to hold a run of bytes with no terminating NUL, and that's valid! For those, you can slap the nonstring attribute on the array so this warning chills out 🧊 BUT bestie, these arrays are not it for functions that expect NUL-terminated strings. To catch accidental misuse, GCC warns on them unless it can prove the use is safe 🫶
-Wstrict-flex-arrays(C and C++ only) — this one checks for sus usage of flexible array members. It goes by the level in thestrict_flex_array (level)attribute on the trailing array field of a struct, if that's available. If not, it goes by-fstrict-flex-arrays=levelinstead. It's only effective when level is greater than0✨- At level 1, you get warnings for a trailing array reference in a struct that has 2 or more elements, if that trailing array is referenced as a flexible array member 🌸
- At level 2, you get everything from level 1, plus warnings for a trailing one-element array reference in a struct if it's used as a flexible array member 🦋
- At level 3, you get everything from level 2, plus warnings for a trailing zero-length array reference in a struct if it's used as a flexible array member 👑
- This option hits harder with
-ftree-vrpon (the default for-O2and above), but some warnings can still show up even without optimization 💖
-Wsuggest-attribute=attribute-name— warns when adding an attribute might be a glow-up 💅 The attribute names supported right now are:-Wsuggest-attribute=pure-Wsuggest-attribute=const-Wsuggest-attribute=noreturn-Wmissing-noreturn-Wsuggest-attribute=malloc-Wsuggest-attribute=returns_nonnull
These all warn about functions that might 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 have an infinite loop and doesn't 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=formatand-Wmissing-format-attribute— these warn about function pointers that might be candidates forformatattributes. Heads up, these are only possible candidates, not guaranteed ones 🙈 GCC assumes that function pointers withformatattributes, used in an assignment, initialization, parameter passing, or a return statement, should have a matchingformatattribute in the resulting type. So 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 format candidates, and again, that's just a maybe. GCC guesses format attributes might fit any function that calls something like vprintf or vscanf, but that's not always true, and some functions that do deserve format attributes might not get detected 🌈
-Wsuggest-attribute=cold— warns about functions that might be candidates for thecoldattribute 🧊 This is based on static detection, and it usually only warns about functions that always lead to a call to anothercoldfunction, like wrappers around C++throwor fatal error reporting functions that lead toabort.-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 is assigned to. This includes the built-in forms ofaligned_alloc,alloca,calloc,malloc, andrealloc💅-Walloc-zero— warns about calls to allocation functions decorated with thealloc_sizeattribute that specify zero bytes. This includes the built-in forms ofaligned_alloc,alloca,calloc,malloc, andrealloc. Behavior with a zero size differs between implementations (andreallocwith zero has been deprecated), so relying on it can cause subtle portability bugs. Bestie, just avoid it 🚫-Wcalloc-transposed-args— warns about calls to allocation functions decorated with thealloc_sizeattribute that have two arguments, where the earlier size argument uses thesizeofoperator and the later one doesn't. This is a coding style warning 🎀 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). If usingsizeofin the earlier argument but not the latter is on purpose, 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 with thealloc_sizeattribute that try to allocate objects larger than the specified number of bytes. It also warns when the result of 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 enabled by default. You can disable these warnings by specifying a byte-size ofSIZE_MAXor more, or by using-Wno-alloc-size-larger-than.-Wno-alloc-size-larger-than— disables the-Walloc-size-larger-than=warnings. It's equivalent to-Walloc-size-larger-than=SIZE_MAXor larger 🌸-Walloca— warns on all uses ofallocain the source 🙈-Wauto-profile— outputs warnings about auto-profile inconsistencies 🔍-Wcannot-profile— warns when profiling instrumentation was requested but couldn't be applied to a certain function 🥀-Walloca-larger-than=byte-size— warns on calls toallocawith an integer argument whose value is either zero, or isn't bounded by a controlling predicate that limits it to at most byte-size. It also warns forallocacalls where the bound value is unknown. Arguments of non-integer types count as unbounded, even if they look like they're in the expected range 🧐
Here's a bounded case of alloca:
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, since the alloca call is known to be at most 1000 bytes. But if you passed -Walloca-larger-than=500, the compiler would warn ⚠️
Unbounded uses are alloca calls with no controlling predicate constraining the integer argument. For example:
void func ()
{
void *p = alloca (n);
f (p);
}With -Walloca-larger-than=500, the above would trigger a warning, because there's no bounds checking 💀
Heads up, even seemingly correct code with signed integers can cause a warning:
void func (signed int n)
{
if (n < 500)
{
p = alloca (n);
f (p);
}
}In the example above, 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— warns 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🔢 Check the vibes:
void f (char c, int i)
{
c = c + i; // warns with -Wconversion
c = c + 1; // only warns with -Warith-conversion
}-Warray-boundsand-Warray-bounds=n— warn 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 💜
Okay so by default, the trailing array at the end of a struct gets treated as a flexible array member by -Warray-bounds or -Warray-bounds=n 💅. That's true whether it's written as a C99 flexible array member ([]), 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. Lowkey wild, but it's the vibe ✨
You can add -fstrict-flex-arrays or -fstrict-flex-arrays=level to control how this option treats a trailing struct array as a flexible array member 🎀
level<=1— no change to the default behavior 🌸level=2— extra warnings get issued for out-of-bounds subscripts or offsets into one-element arrays 🔥level=3— in addition to level=2, extra warnings get issued 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 turned on by-Wall, so you have to ask for them explicitly 🫶-Warray-bounds=2— this level also warns about the intermediate results of pointer arithmetic that might come out as out-of-bounds values 🙈. It can give you a bigger pile of false positives, so it's deactivated by default 💀
-Wunterminated-string-initialization (C and Objective-C only)
Okay, this one is about character arrays that get initialized as unterminated character sequences using a string literal 😭. It warns about that unless the declaration being initialized has the nonstring attribute. Here's the tea:
char arr[3] = "foo"; /* Warning. */
char arr2[3] __attribute__((nonstring)) = "bar"; /* No warning. */This warning is enabled by -Wextra 🌈. If -Wc++-compat is enabled, the warning has slightly different wording, and it warns even if the declaration has the nonstring attribute. Why? Because in C++, those initializations are an error 💅
-Warray-compare
This one warns about equality and relational comparisons between two operands of array type 👀. Fun fact (not fun): that comparison got deprecated in C++20 🥀. Example:
int arr1[5];
int arr2[5];
bool same = arr1 == arr2;-Warray-compare is enabled by -Wall ✨
-Warray-parameter and -Warray-parameter=n
Warn about redeclarations of functions that involve parameters of array or pointer types with inconsistent kinds or forms 🧚. It also turns on detecting out-of-bounds accesses to those parameters through warnings like -Warray-bounds 🔍.
If the first function declaration uses the array form for a parameter, 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 📏. Giving it arguments that are too small, or accessing more than that maximum, may get diagnosed by warnings like -Warray-bounds or -Wstringop-overflow 🚨. At level 1, the warning diagnoses inconsistencies involving array parameters declared with the "T[static N]" form.
For example, the warning triggers on the second declaration of f, because the first one, with the keyword static, says the array argument must have at least four elements, while the second one allows an array of any size to be passed in 😤
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 that denote array sizes 🌸. Pointers and arrays of unspecified bound are considered equivalent, so they don't trigger a warning 🫶
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,
-Warray-parameter, is equivalent to-Warray-parameter=2✨ - The negative form,
-Wno-array-parameter, is equivalent to-Warray-parameter=0🙅
-Wattribute-alias=n and -Wno-attribute-alias
This warns about declarations that use the "alias" and similar attributes whose target is incompatible with the type of the alias 🎀
-Wattribute-alias=1— this is the default level 💅. It diagnoses incompatibilities between the type of the alias declaration and the type of its target. These are usually signs 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 on its target 🧐. These mismatches can potentially lead to incorrect code generation 💀. Other times they're totally benign, and you can fix them just by adding the missing attribute to the target 🩹. For comparison, check out-Wmissing-attributes, which controls diagnostics when the alias declaration is less restrictive than the target, rather than more restrictive 👀
Attributes considered at this level 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, which is the default 💖. You can turn these warnings off with either -Wno-attribute-alias or -Wattribute-alias=0 🙅♀️
-Wbidi-chars=[none|unpaired|any|ucn]
Okay, this one is super important 😭. It warns about possibly misleading UTF-8 bidirectional control characters in comments, string literals, character constants, and identifiers 🌈. These characters can flip 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 can be genuinely dangerous 💀. For instance, a piece of code might look like it isn't commented out, when it actually is. Or the other way around!
GCC supports three levels of this warning 🔥
-Wbidi-chars=unpaired— this is the default, and it 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 (universal character names). You can totally turn on that checking, though, with -Wbidi-chars=unpaired,ucn or -Wbidi-chars=any,ucn 🧚. Using -Wbidi-chars=ucn is valid too, and it's equivalent to -Wbidi-chars=unpaired,ucn, as long as no previous -Wbidi-chars=any was specified 🫶
NOTE: In Ubuntu 25.10 and later versions,-Wbidi-charsis enabled by default for C, C++, ObjC, and ObjC++, unless-Wno-bidi-charsor-Wbidi-chars=noneis found 🐧
-Wbool-compare
This warns about a boolean expression being compared with an integer value that's different from "true"/"false" 🤔. For instance, this comparison is always false:
int n = 5;
...
if ((n > 1) == 2) { ... }This warning is enabled by -Wall 💅
-Wbool-operation
This warns about suspicious operations on expressions of a boolean type 👀. For example, bitwise negation of a boolean is very likely a bug in your 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
This warns when an if-else has identical branches 👯. It detects cases like this one:
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, like this one:
int i = x ? *p : *p;-Wduplicated-cond
This warns about duplicated conditions in an if-else-if chain 🔁. For instance, it'll warn for code like this:
if (p->q != NULL) { ... }
else if (p->q != NULL) { ... }-Wframe-address
This warns when __builtin_frame_address or __builtin_return_address is called with an argument greater than 0 🚨. Those calls may return indeterminate values or crash the program 💀. This warning is included in -Wall 💖
-Wno-discarded-qualifiers (C and Objective-C only)
Okay so this one turns off a warning 🙅. By default, the compiler warns if the type qualifiers on pointers are being discarded 👀. Typically, that's when a "const char *" variable gets passed to a function that takes a "char *" parameter. Use this option if you want to suppress that warning 🫶
-Wno-discarded-array-qualifiers (C and Objective-C only)
Same energy, but for arrays that are pointer targets 💅. Do not warn if the type qualifiers on those arrays are being discarded. Typically, the compiler warns if a "const int (*)[]" variable is passed to a function that takes an "int (*)[]" parameter. This option suppresses that warning 🌸
-Wno-incompatible-pointer-types (C and Objective-C only)
This tells GCC not to warn when there's a conversion between pointers that have incompatible types 🙈. It covers cases not handled by -Wno-pointer-sign, which is the one 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 😭. You can downgrade it to a warning with -fpermissive (along with certain other errors), or for this error alone, with -Wno-error=incompatible-pointer-types 🩹. This warning gets upgraded to an error by -pedantic-errors 🔥
-Wno-int-conversion (C and Objective-C only)
This tells GCC not to warn about incompatible integer-to-pointer and pointer-to-integer conversions 🧚. This one is about implicit conversions. For explicit conversions, you can use -Wno-int-to-pointer-cast and -Wno-pointer-to-int-cast instead 💅
By default, in C99 and later dialects of C, GCC treats this issue as an error 💀. You can downgrade it to a warning with -fpermissive (along with certain other errors), or for this error alone, with -Wno-error=int-conversion 🌈
Heads up, bestie: this next one gets bumped up to an error if you use -pedantic-errors 🚨
-Wzero-as-null-pointer-constant— okay so this one yells whenever you use a literal0as a null pointer constant 🙈-Wzero-length-bounds— ngl this one is giving "watch your array bounds" energy ✨ It warns 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 accessing them is undefined.
⚠️ Undefined behaviour alert: touching those interior zero-length arrays is undefined, so please don't go poking at them 😭
Check out this example. The first two stores in function bad get flagged because those array elements overlap the next members b and c. The third store gets caught by -Warray-bounds instead, since it's past the end 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
}Also, -Wzero-length-bounds is enabled by -Warray-bounds, so it tags along for the ride 🎀
-Wno-div-by-zero— bestie, this turns off the warning for compile-time integer division by zero 🙅♀️ Floating-point division by zero doesn't get warned about either, because it can be a legit way to get infinities and NaNs 🌈-Wsystem-headers— this one tells GCC to print warnings for constructs found in system header files 📚 Normally those warnings are suppressed, on the assumption that they usually aren't real problems and would just make the compiler output harder to read. With this flag, GCC emits them as if they happened in user code 💅 Heads up though: using-Wallalongside this option does not warn about unknown pragmas in system headers. For that, you also need-Wunknown-pragmas🫶-Wtautological-compare— this one catches self-comparisons that always evaluate to true or false 💀 It detects mistakes like this:
int i = 1;
...
if (i > i) { ... }It also warns about bitwise comparisons that always come out true or false. For example:
if ((a & 16) == 10) { ... }That one will always be false, sis 😭 This warning is enabled by -Wall ✨
-Wtrailing-whitespace,-Wtrailing-whitespace=kind— this one warns about trailing whitespace at the end of lines, including inside comments, but skips trailing whitespace in raw string literals 🧹-Wtrailing-whitespaceis the same as-Wtrailing-whitespace=blanks, and it only warns about trailing spaces and horizontal tabs.-Wtrailing-whitespace=anyalso catches trailing form feed or vertical tab characters.-Wno-trailing-whitespaceor-Wtrailing-whitespace=noneturns it off, which is the default. This is a coding style warning, so it's more of a vibe thing than a bug thing 💖-Wleading-whitespace=kind— this one checks for style issues in leading whitespace, but it doesn't care about how much you indent 🌸 Some projects only use spaces, some only use tabs, and some use zero or more tabs (in multiples of-ftabstop=n) followed by zero or fewer than n spaces. No warning shows up on lines that are only whitespace (although a-Wtrailing-whitespace=warning might still pop up), and nothing gets flagged inside raw string literals. It does check leading whitespace inside multi-line comments, though 👀-Wleading-whitespace=spaceswarns about leading whitespace that isn't spaces, for projects that want to indent with just spaces 🎀-Wleading-whitespace=tabswarns about leading whitespace that isn't horizontal tabs, for projects that want to indent with just horizontal tabs 🧚-Wleading-whitespace=blankswarns about leading whitespace that isn't spaces or horizontal tabs. It also flags a horizontal tab after a space in the leading whitespace, or n or more consecutive spaces in leading whitespace, where n is the argument of-ftabstop=n(8 by default) 🔥-Wleading-whitespace=noneturns the warning off, which is the default 💜
-Wtrampolines— this one warns about trampolines generated for pointers to nested functions 🦋 A trampoline is a little piece of data or code that gets 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. On most targets, though, it's made of code, which means the stack has to be executable for the program to work properly.
⚠️ Security vibes: making the stack executable is a big deal, so be careful with trampolines on those targets 🙈
-Wfloat-equal— this one warns if floating-point values are used in equality comparisons 🌈 The idea is that sometimes it's convenient to treat floating-point values as approximations to infinitely precise real numbers. If you're doing that, you need to figure out the maximum (or likely maximum) error the computation introduces, and allow for it when you compare values (and when you produce output, but that's a different problem 💅). Instead of testing for equality, you should check whether the two values have overlapping ranges. You do that with the relational operators, so equality comparisons are probably a mistake 🫶-Wtraditional(C and Objective-C only) — this one warns about constructs that behave differently in traditional C and ISO C 🕰️ It also warns about ISO C constructs that have no traditional C equivalent, and about problematic constructs you should probably avoid. Here's what it catches:- Macro parameters that show up inside string literals in the macro body. Traditional C does macro replacement inside string literals, but ISO C doesn't 🧵
- Preprocessor directives that traditional C didn't really have. Traditional preprocessors only treated a line as a directive if the
#was 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#pragmathat 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, like the_MIN/_MAXmacros in<limits.h>. Using those macros in user code would 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 usually represent bit patterns) don't get warned about 🔢
- ISO string concatenation usage 🧶
- Initialization of automatic aggregates 📦
- Identifier conflicts with labels. Traditional C doesn't have a separate namespace for labels 🏷️
- Initialization of unions. If the initializer is zero, the warning is skipped. This assumes 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-point and floating-point values, and vice versa. Missing 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 intentionally isn't issued for prototype declarations or variadic functions, because those ISO C features show up in your code when you use libiberty's traditional C compatibility macros,
PARAMSandVPARAMS. The warning is also skipped for nested functions, since that's already a GCC extension and isn't relevant to traditional C compatibility 🧁
-Wtraditional-conversion(C and Objective-C only) — this one warns if a prototype causes a type conversion that's different from what would happen to the same argument without a prototype 🔁 That includes fixed-point to floating-point conversions and vice versa, and 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) — this one warns when a declaration shows up after a statement in a block 📝 This construct comes from C++, was introduced with ISO C99, and is allowed by default in GCC. It isn't supported by ISO C90. This warning gets upgraded to an error by-pedantic-errors🙈-Wshadow— this one 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 gets 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. It's the same as-Wshadow=global💅-Wno-shadow-ivar(Objective-C only) — this one stops the warning for when a local variable shadows an instance variable in an Objective-C method 🙅♀️-Wshadow=global— this warns for any shadowing at all, and it's the same as-Wshadow🌍-Wshadow=local— this warns when a local variable shadows another local variable or a parameter 🏠-Wshadow=compatible-local— okay so this one warns when a local variable shadows another local or a parameter whose type is compatible with its own. In C++, "compatible" means the shadowing variable can be converted to the shadowed variable's type. It exists alongside-Wshadow=localbecause when a local shadows one of incompatible type, it's usually on purpose and not a bug or typo. Check out this iterator situation 👀:
for (SomeIterator i = SomeObj.begin(); i != SomeObj.end(); ++i)
{
for (int i = 0; i < N; ++i)
{
...
}
...
}Since the two i variables have incompatible types, turning on only -Wshadow=compatible-local gives no warning here. And if someone accidentally swaps one i for the other, type checking should catch it and throw an error or warning. Using this instead of -Wshadow=local can cut down on the noise from intentional shadowing. Heads up, though: shadowing const char *i with char *i also won't trigger a warning with this flag. This warning is also turned on by -Wshadow=local. 💅
-Wlarger-than=byte-size— warns whenever you define an object bigger than byte-size. It's on by default with-Wlarger-than=PTRDIFF_MAX. You can silence these warnings by setting byte-size toSIZE_MAXor more, or by using-Wno-larger-than. It also warns about calls to bounded functions likememchrorstrnlenwhen the bound is bigger than the largest possible object, which isPTRDIFF_MAXbytes by default. Those particular warnings can only be turned off with-Wno-larger-than. 🧚-Wno-larger-than— disables the-Wlarger-than=warnings. It's the same as-Wlarger-than=SIZE_MAXor larger. 🫶-Wframe-larger-than=byte-size— warns if a function's stack frame is bigger than byte-size. Fair warning: the math for the frame size is approximate and not conservative, so the real requirements might be a bit bigger than byte-size even when you get no warning at all. Also, the compiler doesn't count any space fromalloca, variable-length arrays, or similar stuff when it decides whether to warn. It's on by default with-Wframe-larger-than=PTRDIFF_MAX. You can disable these by setting byte-size toSIZE_MAXor more, or by using-Wno-frame-larger-than. 🌸-Wno-frame-larger-than— disables the-Wframe-larger-than=warnings. Same deal as-Wframe-larger-than=SIZE_MAXor larger. 🦋-Wfree-nonheap-object— warns when you try to deallocate something that wasn't allocated on the heap, or when you use a pointer that didn't come back from the matching allocation call. The example below gets flagged becausestpcpyhands back a pointer to the terminating nul character instead of the start of the object, so thefreecall gets caught. It's included in-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 one is conservative, so the compiler does count any space fromalloca, variable-length arrays, or related constructs. The message matches what-fstack-usageoutputs. Here's what you'll see depending on the situation:- If the stack usage is fully static but goes over the limit, you get:
warning: stack usage is 1120 bytes- If the stack usage is (partly) dynamic but bounded, you get:
warning: stack usage might be 1648 bytes- If the stack usage is (partly) dynamic and unbounded, you get:
warning: stack usage might be unboundedIt's on by default with -Wstack-usage=PTRDIFF_MAX. You can disable these by setting byte-size to SIZE_MAX or more, or by using -Wno-stack-usage. 💖
-Wno-stack-usage— disables the-Wstack-usage=warnings. It's the same as-Wstack-usage=SIZE_MAXor larger. ✨-Wunsafe-loop-optimizations— warns if a loop can't be optimized because the compiler can't assume anything about the bounds of the loop indices. If you add-funsafe-loop-optimizations, it warns whenever the compiler does make those assumptions instead. 👑-Wno-pedantic-ms-format(MinGW targets only) — when you combine it with-Wformatand-pedanticwithout GNU extensions, this turns off the warnings about the non-ISOprintf/scanfformat width specifiersI32,I64, andIthat get used on Windows targets. Those depend on the MS runtime, so they're not standard. 🎀-Wpointer-arith— warns about anything that depends on the "size of" a function type or ofvoid. GNU C gives these 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 turned on by-Wpedantic, and-pedantic-errorsupgrades it to an error. 🧠-Wno-pointer-compare— stops the warning for when a pointer gets compared with a zero character constant. That usually means you meant to dereference the pointer, so it's a useful catch. Like this:
const char *p = foo ();
if (p == '\0')
return 42;Heads up that the code above is invalid in C++11. This warning is enabled by default. 🙈
-Wno-tsan— disables warnings about features that ThreadSanitizer doesn't support. Just so you know, ThreadSanitizer doesn't supportstd::atomic_thread_fenceand can report false positives with it. 🧵-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 flagged, though. For example, it'll warn if an unsigned variable gets compared against zero with<or>=. This warning is also turned on by-Wextra. 💜-Wabsolute-value(C and Objective-C only) — warns when you call a standard function that computes an absolute value, but there's a more appropriate standard function you should be using. For instance, callingabs(3.14)triggers it, because the right function for a double isfabs. It also warns when the argument in one of those calls has an unsigned type. You can get rid of the warning with an explicit type cast, and it's also turned on 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 turned on by-Wall. 💅-Wtrigraphs— warns if any trigraphs get encountered that might change what the program means. Trigraphs inside comments don't get warned about, except for the ones that would form escaped newlines. This option is implied by-Wall. If you don't pass-Wall, it's still turned on, unless trigraphs are enabled. If you want trigraph conversion without the warnings but still want 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. 🌙-Wexpansion-to-defined— warns wheneverdefinedshows up in the expansion of a macro, including when the macro gets expanded by an#ifdirective. That kind of usage isn't portable. This warning is also turned on 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 a 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.
Note: if a macro is only used inside skipped conditional blocks, the preprocessor still reports it as unused. To avoid that, you could improve the scope of the macro's definition by moving it into the first skipped block, for example. Or you can give it a dummy use with something like this:
#if defined the_macro_causing_the_warning
#endif-Wno-endif-labels— stops the warning for when an#elseor an#endifgets followed by text. This pops up sometimes in older programs with code like this:
#if FOO
...
#else FOO
...
#endif FOOThe second and third FOO should 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 type that doesn't match. For example, it warns if a call to a function that returns 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. Think variable length arrays, thelong longtype, thebooltype, compound literals, designated initializers, and so on. This option doesn't depend on the standards mode. Warnings get 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. That includes anonymous structures and unions, the_Atomictype qualifier, the_Thread_localstorage-class specifier, the_Alignasspecifier, theAlignofoperator, the_Generickeyword, and so on. This option is also independent of the standards mode, and warnings are disabled in the expression that follows__extension__. 🌷
-Wc11-c23-compat, -Wc11-c2x-compat (C and Objective-C only) — okay so this one's about stuff that's in ISO C23 but NOT in ISO C11 🌸 It'll warn you about things like leaving the string out of _Static_assert, using [[]] attribute syntax, or using decimal floating-point types. It works no matter which standards mode you're in 💅 Warnings get switched off inside the expression after __extension__. Also, heads up: the name -Wc11-c2x-compat is deprecated, so use the c23 one 🥺 And when you're not compiling in C23 mode, -pedantic-errors turns these warnings into full-on errors 💀
-Wc23-c2y-compat (C and Objective-C only) — same energy, but for stuff in ISO C2Y that isn't in ISO C23 🦋 Example: a _Generic that picks by type name instead of by expression. Also independent of the standards mode, and disabled in the expression after __extension__. When you're not in C2Y mode, -pedantic-errors upgrades these to errors ✨
-Wc++-compat (C and Objective-C only) — this one checks for ISO C code that steps outside the shared zone of ISO C and ISO C++ 🧚 Like asking for an implicit conversion from void * to a pointer to something that isn't void.
-Wc++11-compat (C++ and Objective-C++ only) — flags C++ stuff whose meaning changed between ISO C++ 1998 and ISO C++ 2011 🎀 For example, identifiers that were fine in C++98 but are keywords in C++11. This one turns on -Wnarrowing and is enabled by -Wall 👑
-Wc++14-compat (C++ and Objective-C++ only) — same vibe, but for the change from ISO C++ 2011 to ISO C++ 2014 🌈 Enabled by -Wall.
-Wc++17-compat (C++ and Objective-C++ only) — checks for things whose meaning shifted from ISO C++ 2014 to ISO C++ 2017 ⭐ Enabled by -Wall.
-Wc++20-compat (C++ and Objective-C++ only) — checks the glow-up from ISO C++ 2017 to ISO C++ 2020 🍓 Enabled by -Wall.
-Wc++26-compat (C++ and Objective-C++ only) — checks for C++ constructs whose meaning differs between ISO C++ 2023 and the upcoming ISO C++ 2026 🔥 Enabled by -Wall.
-Wno-c++11-extensions (C++ and Objective-C++ only) — if you're compiling with an older C++ standard, this stops the warnings about C++11 constructs 🙈 Heads up though: some C++11 constructs only get flagged when you use -Wpedantic, even without this option.
-Wno-c++14-extensions (C++ and Objective-C++ only) — same deal, but for C++14 constructs in older-standard code 💜 Some of them only get diagnosed with -Wpedantic.
-Wno-c++17-extensions (C++ and Objective-C++ only) — silences the C++17 construct warnings in older-standard code 🦋 Some C++17 constructs still only get flagged with -Wpedantic.
-Wno-c++20-extensions (C++ and Objective-C++ only) — silences the C++20 construct warnings in older-standard code 🌸 Some C++20 constructs still only get flagged with -Wpedantic.
-Wno-c++23-extensions (C++ and Objective-C++ only) — silences the C++23 construct warnings in older-standard code ✨ Some C++23 constructs still only get flagged with -Wpedantic.
-Wno-c++26-extensions (C++ and Objective-C++ only) — silences the C++26 construct warnings in older-standard code 💅 Some C++26 constructs still only get flagged with -Wpedantic.
-Wcast-qual — this one catches pointer casts that drop a type qualifier from the target type 🫶 Like casting a const char * to a plain char *. It also warns when a cast adds a qualifier in an unsafe way. Casting char ** to const char ** is the classic example, and it's not safe:
/* 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 makes the required alignment of the target bigger 😭 For example, casting a char * to an int * on machines where integers can only be accessed at two- or four-byte boundaries. There's also a version that warns about the same char * to int * cast no matter what target machine you're on 🔥
-Wcast-function-type — warns when a function pointer gets cast to an incompatible function pointer 🧚 For casts involving variadic function types, only the types of the initial arguments that are actually provided get checked. Any pointer-type parameter matches any other pointer-type. Harmless integral differences get ignored, like int vs. long on ILP32 targets, and type qualifiers get ignored too. The function type void (*) (void) is special and matches everything, so it can be used to suppress this warning. For pointer-to-member types, it warns whenever the cast changes the pointer-to-member type. This one's enabled by -Wextra 🌈
-Wcast-user-defined — warns when a cast to a reference type doesn't involve a user-defined conversion you'd probably expect to get called 🎀 Like this:
struct A { operator const int&(); } a;
auto r = (int&)a; // warningThis warning is enabled by default 💖
-Wwrite-strings — when you're compiling C, this gives string constants the type const char[length], so copying one's address into a non-const char * pointer gives you a warning 🍓 It can catch code that tries to write into a string constant at compile time, but only if you've been super careful with const in your declarations and prototypes. Otherwise it's just a nuisance 🙄 That's why -Wall doesn't ask for it.
When you're compiling C++, it warns about the deprecated conversion from string literals to char *. This is enabled by default for C++ programs, and -pedantic-errors upgrades it to an error in C++11 mode or later 👑
-Wclobbered — warns about variables that might get changed by longjmp or vfork 😭 This one's also enabled by -Wextra.
-Wno-complain-wrong-lang — normally, language front ends complain when a command-line option is valid but doesn't apply to that front end 💀 You can turn that off with -Wno-complain-wrong-lang. It's mostly handy when you invoke one compiler driver for multiple source files in different languages, like this:
$ g++ -fno-rtti a.cc b.f90Here the g++ driver hands a.cc to the C++ front end and b.f90 to the Fortran front end. The Fortran one complains with 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. This option can also be used to disable warnings like cc1plus: note: CTF debug info requested, but not supported for 'GNU C++20' frontend produced by -gctf or -gsctf for unsupported languages. 🧚
-Wcompare-distinct-pointer-types (C and Objective-C only) — warns if pointers of distinct types get compared without a cast 🦋 This one's enabled by default.
-Wconversion — warns about implicit conversions that might change a value 👀 That includes conversions between real and integer types, like abs (x) when x is a double. It also covers conversions between signed and unsigned, like unsigned ui = -1, and conversions to smaller types, like sqrtf (M_PI). It won'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 the signed/unsigned warnings are too much, you can turn those off with -Wno-sign-conversion 🌸
In C++, it also warns about confusing overload resolution for user-defined conversions, plus conversions that never use a type conversion operator: conversions to void, to the same type, to a base class, or to a reference to any of those. The signed/unsigned conversion warnings are disabled by default in C++ unless you explicitly enable -Wsign-conversion 💅 And warnings about conversion from arithmetic on a small type back to that same type only show up with -Warith-conversion ✨
-Wdangling-else — warns about code where it might be unclear which if an else branch belongs to 🙈 Here's an example that's confusing:
{
if (a)
if (b)
foo ();
else
bar ();
}In C/C++, every else branch belongs to the innermost possible if statement, which in this example is if (b). That's often not what the programmer expected, even though the indentation suggests otherwise 💀 When there's potential for this confusion, GCC warns if you specify this flag. 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 — warns about using 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 those 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, it only diagnoses unconditional uses of dangling pointers 🧚
-Wdangling-pointer=2— bestie, level 2 is the full drama 🎭 It catches everything level 1 does, plus the conditional uses of dangling pointers too ✨
The short form -Wdangling-pointer is the same as -Wdangling-pointer=2. Meanwhile -Wno-dangling-pointer and -Wdangling-pointer=0 both switch the warnings off 🙅♀️ And -Wdangling-pointer=2 is already included in -Wall 💅
Okay, this example triggers the warning at level 1 🔥 The address of the unnamed temporary gets referenced unconditionally outside of its scope, and that's a whole mess 😭
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 this 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;
}Here the array a is out of scope by the time the pointer s gets used 🙈 Since the code that sets "s" is conditional, this one only 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 🕰️ They can make it impossible to get bitwise-identical reproducible compilations, so this one's a vibe check for your build 🧐-Wempty-body— flags an empty body in anif,elseordo whilestatement 🫥 This warning is also turned on by-Wextra✨-Wno-endif-labels— chill out and don't warn about stray tokens after#elseand#endif🌸-Wenum-compare— warns about a comparison between values of different enumerated types 👀 In C++, enum mismatches in conditional expressions get diagnosed too, and this one's enabled by default there 💜 In C, it's turned on by-Wall🔥-Wenum-conversion— warns when a value of enumerated type gets implicitly converted into a different enumerated type 🦋 In C, this 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 🧚 Like, this is the kind of messy situation I mean:
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 the underlying type of an enumerated type is implementation-defined, so these mismatches can cause portability issues 😭 In C++, though, they're an error ❌ In C, this warning is enabled by -Wall and -Wc++-compat 💖
-Wjump-misses-init(C, Objective-C only) — warns if agotoor aswitchstatement jumps forward across the initialization of a variable, or jumps backward to a label after the variable has already been initialized 🙃 It only cares about variables that are initialized when they're declared 🎀 This one is only supported for C and Objective-C, because in C++ this kind of branch is an error anyway 💅
-Wjump-misses-init is included in -Wc++-compat ✨ And it can be disabled with the -Wno-jump-misses-init option 🫧
-Wsign-compare— warns when a comparison between signed and unsigned values could give an incorrect result, because the signed value gets converted to unsigned 🧐 In C++, it's also enabled by-Wall💜 In C, it's enabled by-Wextra🌸-Wsign-conversion— warns about implicit conversions that might change the sign of an integer value 🍓 Think assigning a signed integer expression to an unsigned integer variable 👀 An explicit cast silences it 🫶 In C, this option is also turned on by-Wconversion✨-Wflex-array-member-not-at-end(C and C++ only) — warns when a structure with a C99 flexible array member as its last field ends up not at the end of another structure 🦋 For example:
struct flex { int length; char data[]; };
struct mid_flex { int m; struct flex flex_data; int n; };-Wfloat-conversion— warns about implicit conversions that reduce the precision of a real value 📉 That includes real-to-integer conversions, and going from higher precision real values down to lower precision ones 🔥 This is also enabled by-Wconversion🫶-Wno-scalar-storage-order— doesn't warn about suspicious constructs involving reverse scalar storage order 🙈-Wsizeof-array-div— warns about dividing twosizeofoperators when the first one is applied to an array and the divisor doesn't match the size of the array element 🧮 The computation won't give you the number of elements in the array, which is probably not what you meant 😭 For example, this function would get flagged:
int fn ()
{
int arr[10];
return sizeof (arr) / sizeof (short);
}This warning is enabled by -Wall 💖
-Wsizeof-pointer-div— warns about suspicious divisions of twosizeofexpressions that divide the pointer size by the element size 🫠 That's usually how you'd compute an array size, but it won't work right with pointers 💀 It warns e.g. aboutsizeof (ptr) / sizeof (ptr[0])whenptris a pointer and not an array 🌈 This warning is enabled by-Wall✨-Wsizeof-pointer-memaccess— warns about suspicious length parameters passed to certain string and memory built-in functions when the argument usessizeof🧠 It triggers for things likememset (ptr, 0, sizeof (ptr));whenptris a pointer and not an array, and it'll even suggest a possible fix 🛠️ It also catches stuff likememcpy (&foo, ptr, sizeof (&foo));🙃
It also warns about calls to bounded string copy functions like strncat or strncpy that use a sizeof expression of the source array as the bound 🚨 In the following function, the strncat call uses the size of the source string as its bound, which is almost certainly a mistake, so the call gets diagnosed 👑
void make_file (const char *name)
{
char path[PATH_MAX];
strncpy (path, name, sizeof path - 1);
strncat (path, ".text", sizeof ".text");
...
}The -Wsizeof-pointer-memaccess option is enabled by -Wall 💅
-Wno-sizeof-array-argument— don't warn when thesizeofoperator gets applied to a parameter that's declared as an array in a function definition 🫶 This warning is enabled by default for C and C++ programs 🌟-Wmemset-elt-size— warns about suspicious calls to thememsetbuilt-in function where the first argument references an array, and the third argument is a number equal to the number of elements but not equal to the size of the array in memory 😤 That means you probably forgot to multiply by the element size 🙈 This warning is enabled by-Wall🦋-Wmemset-transposed-args— warns about suspicious calls tomemsetwhere the second argument isn't zero and the third argument is zero 🔄 For example,memset (buf, sizeof buf, 0)gets diagnosed, becausememset (buf, 0, sizeof buf)was what was meant 💀 The diagnostic is only emitted if the third argument is a literal zero 🎯 If it's an expression that folds to zero, or a cast of zero to some type, the args are way less likely to be mixed up, so no warning shows up 🙅♀️ This warning is enabled by-Wall💖-Waddress— warns about suspicious uses of address expressions 👀 These are the sus ones you'll want to know about:
Comparing the address of a function or a declared object to the null pointer constant, like this, is one of them 🧐
void f (void);
void g (void)
{
if (!f) // warning: expression evaluates to false
abort ();
}Comparing a pointer to a string literal is another, like this 🎀
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 is also on the list 🙃
void f (const int *p, int i)
{
return p + i == NULL;
}These uses usually mean the programmer made a mistake 🚩 The address of most functions and objects always evaluates to true (the exception is weak symbols), so putting them in a conditional might mean you're missing parentheses in a function call, or a dereference in an array expression 😭
The object pointer part of this warning can be suppressed by casting the pointer operand to an integer type, such as intptr_t or uintptr_t 🧚 Comparisons against string literals result in unspecified behavior and aren't portable, and they usually suggest you meant to call strcmp 🌸 The warning is suppressed if the suspicious expression comes out of a macro expansion 🫧 -Waddress is enabled by -Wall 💅
-Wno-address-of-packed-member— don't warn when the address of a packed member of a struct or union is taken 🧊 That usually gives you an unaligned pointer value, but this is enabled by default, so you're already covered ✨-Wlogical-op— warns about suspicious uses of logical operators in expressions 🧠 That includes using logical operators where a bitwise operator is probably what was expected 🍓 It also warns when the operands of a logical operator are the same, like this:
extern int a;
if (a < 0 && a < 0) { ... }-Wlogical-not-parentheses— warns about a logical not used on the left hand side operand of a comparison 🙈 It doesn't warn if the right operand is considered to be a boolean expression 🫶 Its whole purpose is to catch sus code like this:
int a;
...
if (!a > 1) { ... }It is possible to suppress the warning by wrapping the LHS into parentheses, bestie 🫶 ✨
if ((!a) > 1) { ... }This warning is enabled by -Wall 💅
-Waggregate-return— okay so this one 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 turns off the warning when the compiler spots undefined behavior inside a loop that has a constant number of iterations 💀 Heads up,-Waggressive-loop-optimizationsis already on by default ✨-Wno-attributes— no warning if an unexpected__attribute__shows up, like unrecognized attributes or function attributes slapped onto variables, etc. 🦋 It won't stop errors for wrong use of attributes that are supported though 😭 Also, warnings about ill-formed uses of standard attributes get upgraded to errors by-pedantic-errors❗
Next level: using -Wno-attributes= lets you silence 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 if you want the whole namespace gone, -Wno-attributes=vendor:: stops the warnings for both of these:
[[vendor::safe]] void f();
[[vendor::unsafe]] void f2();Lowkey important: -Wno-attributes= does not imply -Wno-attributes 👑
-Wno-builtin-declaration-mismatch— this one warns if a built-in function gets declared with an incompatible signature or as a non-function 🔥 It also fires when a built-in function declared with a type that has no prototype gets called with arguments whose promoted types don't match what the function expects 💜 With-Wextra, it also warns when a built-in function that takes arguments is declared without a prototype 🌈 The-Wbuiltin-declaration-mismatchwarning is on by default, but to dodge it, just include the right header so the built-in function prototypes are in scope 🫶
Here's the drama: the memset call below gets caught because the function wants a size_t argument, but 32 is an int 😭 With -Wextra, the declaration itself gets flagged too 💅
extern void* memset ();
void f (void *d)
{
memset (d, '\0', 32);
}-Wno-builtin-macro-redefined— don't warn if certain built-in macros get redefined 🙈 This quiets warnings for redefining__TIMESTAMP__,__TIME__,__DATE__,__FILE__, and__BASE_FILE__🍓-Wkeyword-macro— warns if a keyword gets defined as a macro or undefined 🎀 For C++, identifiers with special meaning or standard attribute identifiers get called out too ✨ This one is enabled by default for C++26 if-Wpedanticis on, and it emits a pedwarn in that case 🔥-Wfree-labels(C and Objective-C only) — warns if a label is applied to a non-statement, or sits at the end of a compound statement 🦋 C23 and later allow these labels, and GCC offers them as an extension in every other dialect 🌸 This warning is also turned on by-Wc11-c23-compat, and-pedantic-errorsturns it into an error if you're building for a C version before C23 💀-Wheader-guard— this warns if a valid multiple inclusion guard in a preprocessor header has a#defineright after the#ifndefor#if !defineddirective, and that#definedefines a different macro with a similar name 👀 The real guard macro also isn't defined at the matching#ifndefat the end of the header, and the#definemakes an object-like macro with an empty definition 🫠 Usually that means it's just a misspelled guard name, either in the#ifndefor#if !definedline or in the#defineafter it 😭 This warning is enabled by-Wall💖-Wstrict-prototypes(C and Objective-C only) — warns if a function is declared or defined without specifying the argument types 🌸 An old-style function definition is allowed without a warning if it's preceded by a declaration that does specify the argument types 🧚-Wold-style-declaration(C and Objective-C only) — warns about obsolescent usages in a declaration, according to the C Standard 🍓 For example, it warns if storage-class specifiers likestaticaren't the first things in a declaration 👑 This warning is also enabled by-Wextra✨-Wold-style-definition(C and Objective-C only) — warns if an old-style function definition is used 🦋 It warns even if there's already a previous prototype 💅 A definition using()isn't treated as old-style in C23 mode, since it's equivalent to(void)there, but it is treated as old-style for older standards 🌈-Wmultiple-parameter-fwd-decl-lists(C and Objective-C only) — warns if more than one list of forward declarations of parameters shows up in a function prototype 🎀 This warning is also enabled by-Wextra🫶-Wdeprecated-non-prototype(C and Objective-C only) — warns if a function declared with an empty parameter list()gets called with one or more arguments, or if a function definition with one or more parameters shows up after such a declaration 😭 Both cases are errors in C23 and later dialects of C 💀 This warning is also enabled by-Wc11-c23-compat✨-Wmissing-parameter-name(C and Objective-C only) — warns if a function definition leaves out a parameter name and only gives its type 🧚 This can be handy for documenting that a parameter goes unused in the definition 🍓 It's part of C23 and later dialects of C, and GCC offers it as an extension in all other dialects 🌈 This warning is also enabled by-Wc11-c23-compat, and-pedantic-errorsmakes it an error if you're building for a C version before C23 💅-Wmissing-parameter-type(C and Objective-C only) — warns when a function parameter has no type specifier in K&R-style functions, like this 👇
void foo(bar) { }This warning is also enabled by -Wextra 🔥
-Wno-declaration-missing-parameter-type(C and Objective-C only) — no warning if a function declaration has a parameter name without a type 🙈 These declarations don't give you a function prototype, so they block most type checking in function calls 💀 This warning is on 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 for this error alone with-Wno-error=declaration-missing-parameter-type🫶-pedantic-errorsupgrades this warning to an error 👑-Wmissing-prototypes(C and Objective-C only) — warns if a global function gets defined without a previous prototype declaration 🦋 It warns even if the definition itself has a prototype 💅 Use this one to catch global functions that don't have a matching prototype declaration in a header file 🌸 It isn't valid for C++, since all function declarations there provide prototypes, and a non-matching declaration declares an overload instead of conflicting with an earlier one 🧚 For missing declarations in C++, use-Wmissing-declarationsinstead 💖-Wmissing-variable-declarations(C and Objective-C only) — warns if a global variable gets defined without a previous declaration 🌈 Use it to find global variables that don't have a matchingexterndeclaration in a header file 🍓-Wmissing-declarations— warns if a global function gets defined without a previous declaration, even if the definition itself has a prototype 🎀 Use this to catch global functions that aren't declared in header files ✨ In C, no warnings are issued for functions with previous non-prototype declarations, so use-Wmissing-prototypesfor those 🦋 In C++, no warnings are issued for function templates, inline functions, or functions in anonymous namespaces 👑-Wmissing-field-initializers— warns if a struct's initializer is missing some fields 🫠 In this example, the code triggers the warning becausex.his implicitly zero:
struct s { int f, g, h; };
struct s x = { 3, 4 };In C, this option doesn't warn about designated initializers, so this one is fine:
struct s { int f, g, h; };
struct s x = { .f = 3, .g = 4 };In C, it 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, for example:
struct s { int f, g, h; };
s x = { };This warning is included in -Wextra 💅 If you want 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 here:
bool satisfied = requires { C<T> };satisfied will be true if C<T> is a valid expression, which it is for all T 🫠 Presumably the user meant to write this instead:
bool satisfied = requires { requires C<T> };so satisfied is only true if concept C is satisfied for type T 💖 You can turn off this warning with -Wno-missing-requires 🧚
-Wno-missing-template-keyword— the member access tokens.,->and::need to be followed by thetemplatekeyword if the parent object is dependent and the member being named is a template 🦋 Here's the vibe check:
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 them, 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.
}Psst, you can totally switch that one off with -Wno-missing-template-keyword if it's being extra. 💅
-Wno-multichar— bestie, don't warn if a multicharacter constant like'FOOF'shows up. ngl these are usually a typo in your code 🙈, since their values are implementation-defined and they shouldn't be in portable code anyway.-Wnormalized=[none|id|nfc|nfkc]— okay so, in ISO C and ISO C++, two identifiers are different if they're different sequences of characters. BUT when you use characters outside basic ASCII, you can end up with two totally different sequences that look the same 😭. The ISO 10646 standard has normalization rules that turn lookalikes into the same sequence, and GCC can warn you if your identifiers aren't normalized. This option controls that warning. There are four levels.- 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 C++ allow in identifiers stop being allowed once they're turned into NFC. So there's no way to use these symbols in portable ISO C or C++ and keep all your identifiers in NFC.
-Wnormalized=idsuppresses the warning for these characters. It's hoped that future versions of the standards will fix this, which is why it isn't the default. 🥺 - You can switch the warning off for all characters with
-Wnormalized=noneor-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 ISO 10646 characters have distinct meanings but look identical in some fonts or display methods, especially once formatting is 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. It can still be a useful local coding convention if the programming environment can't be fixed to display these characters distinctly. 🔍
- The default is
-Wno-attribute-warning— no warnings about using functions declared with the "warning" attribute. This warning is enabled by default, but-Wno-attribute-warningcan turn it off, or-Wno-error=attribute-warningcan turn off the error when you compile with the-Werrorflag. 🎀-Wno-deprecated— no warnings about using deprecated features.- In C++, explicitly specifying
-Wdeprecatedalso enables warnings about some features that are deprecated in later language standards, specifically-Wcomma-subscript,-Wvolatile,-Wdeprecated-enum-float-conversion,-Wdeprecated-enum-enum-conversion,-Wdeprecated-literal-operator, and-Wdeprecated-variadic-comma-omission.
- In C++, explicitly specifying
-Wno-deprecated-declarations— no warnings when you use functions, variables, or types marked as deprecated with the "deprecated" attribute. 🙄-Wno-deprecated-openmp— no warnings about deprecated OpenMP code.-Wno-overflow— no warnings about compile-time overflow in constant expressions.-Wno-odr— warns about One Definition Rule violations during link-time optimization. Enabled by default.
Heads up, bestie: the-Wno-in the name of-Wno-odrand-Wno-openmpdoesn't match what their descriptions say. Read the description, not just the name, or you'll be confused 👀.
-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 that the user 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 is overridden when using designated initializers.- This warning is included in
-Wextra. To get the other-Wextrawarnings without this one, use-Wextra -Wno-override-init.
- This warning is included in
-Wno-override-init-side-effects(C and Objective-C only) — no warning if an initialized field with side effects is overridden when using designated initializers. This warning is enabled by default.-Wpacked— warns if a structure is given the packed attribute, but the packed attribute has no effect on the layout or size of the structure. Those structures can end up misaligned for little benefit. For instance, in this code, the variable "f.x" in "struct bar" is misaligned even though "struct bar" doesn't itself have the packed attribute:
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 ignored the "packed" attribute on bit-fields of type "char". This 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, there's no longer a 4-bit padding between field "a" and "b" in this structure:
struct foo
{
char a:4;
char b:8;
} __attribute__ ((packed));This warning is enabled by default. Use -Wno-packed-bitfield-compat to disable this warning. 🦋
-Wpacked-not-aligned(C, C++, Objective-C and Objective-C++ only) — warns if a structure field with explicitly specified alignment in a packed struct or union is misaligned. For example, a warning will be issued on "struct S", like "warning: alignment 1 of 'struct S' is less than 8", in this code:
struct __attribute__ ((aligned (8))) S8 { char a[8]; };
struct __attribute__ ((packed)) S {
struct S8 s8;
};This warning is enabled by -Wall.
-Wpadded— warns if padding is included in a structure, either to align an element of the structure or to align the whole structure. Sometimes it's possible to rearrange the fields of the structure to reduce the padding and make it smaller. 🌸-Wredundant-decls— warns if anything is declared more than once in the same scope, even in cases where multiple declarations are valid and change nothing.-Wrestrict— warns when an object referenced by a "restrict"-qualified parameter (or, in C++, a "__restrict"-qualified parameter) is aliased by another argument, or when copies between such objects overlap. In the example below, thestrcpycall tries to truncate the string by replacing its initial characters with the last four. But because the call writes the terminating NUL into "a[4]", the copies overlap and the call gets diagnosed:
void foo (void)
{
char a[] = "abcd1234";
strcpy (a, a + 4);
...
}The -Wrestrict option detects some instances of simple overlap 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 an "extern" declaration is encountered within a function.-Winline— warns if a function that is declared as inline cannot be inlined. Even with this option, the compiler does not warn about failures to inline functions declared in system headers.- The compiler uses a variety of heuristics to decide whether or not to inline a function. For example, it takes into account the size of the function being inlined and the amount of inlining that has already been done in the current function. So seemingly insignificant changes in the source program can make the
-Winlinewarnings appear or disappear. 🙈
- The compiler uses a variety of heuristics to decide whether or not to inline a function. For example, it takes into account the size of the function being inlined and the amount of inlining that has already been done in the current function. So seemingly insignificant changes in the source program can make the
-Winterference-size,-Wno-interference-size— warns about questionable uses of the C++17 "constexpr" variables "std::hardware_destructive_interference_size" and "std::hardware_constructive_interference_size". These variables are meant for controlling class layout, to avoid false sharing in concurrent code, like this:
struct independent_fields {
alignas(std::hardware_destructive_interference_size)
std::atomic<int> one;
alignas(std::hardware_destructive_interference_size)
std::atomic<int> two;
};Here, "one" and "two" are intended to be far enough apart that stores to "one" won't require accesses to the other to reload the cache line. 🧚
By default, these variables are given values based on the current -mtune option, typically the L1 cache line size for the particular target CPU, and sometimes a range if tuning for a generic target. So all translation units that depend on ABI compatibility for the use of these variables must be compiled with the same -mtune (or -mcpu).
If ABI stability is important, such as if the use is in a header for a library, you should probably not use the hardware interference size variables at all.
These warnings are enabled by default. If you're confident that your use of these variables does not 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 suspicious use of integer values where boolean values are expected. Examples include conditional expressions (?:) using non-boolean integer constants in a boolean context, likeif (a <= b ? 2 : 3), or left shifting of signed integers in a boolean context, likefor (a = 0; 1 << a; a++);. It's likewise for all kinds of multiplications, regardless of the data type. This warning is enabled by-Wall. 👑-Wno-int-to-pointer-cast— suppresses warnings from casts to pointer type of an integer of a different size. In C++, casting to a pointer type of smaller size is an error.Wint-to-pointer-castis enabled by default. 🫶-Wno-pointer-to-int-cast(C and Objective-C only) — bestie, this one silences the warning for casting a pointer to an integer type of a different size 🙈-Winvalid-pch— ooh, this warns you if a precompiled header is sitting in the search path but GCC can't actually use it 🦋-Winvalid-utf8— flags any invalid UTF-8 character. It's on by default for C++23 when-finput-charset=UTF-8is used, and it becomes a full-on error with-pedantic-errors💅-Wno-unicode— skips complaining about invalid forms of delimited or named escape sequences that get treated as separate tokens. Heads up:-Wunicodeis already on by default ✨-Wlong-long— warns when thelong longtype shows up. It's switched on by either-Wpedanticor-Wtraditionalin ISO C90 and C++98 modes. If you want it quiet, use-Wno-long-long🌸
This one gets promoted to an error by -pedantic-errors, so be careful, bestie 😭
-Wvariadic-macros— warns if variadic macros are used in ISO C90 mode, or if the GNU alternate syntax is used in ISO C99 mode. It's enabled by either-Wpedanticor-Wtraditional, and you can shush it with-Wno-variadic-macros🎀-Wno-varargs— stops the warnings about questionable usage of the macros that handle variable arguments, likeva_start. These are on by default, so this is how you turn them off 🧚-Wvector-operation-performance— warns if a vector operation isn't implemented through the architecture's SIMD capabilities. It's mainly for performance tuning, and the vibes are: a vector op can be done "piecewise", which means the scalar op runs on every vector element; "in parallel", which means the vector op uses scalars of a wider type (usually way more performance efficient); or "as a single scalar", which means the vector fits into a scalar type 🔥-Wvla— warns if a variable-length array is used anywhere in the code.-Wno-vlastops the-Wpedanticwarning about variable-length arrays. This one gets upgraded to an error by-pedantic-errors💀-Wvla-larger-than=byte-size— when you use this, the compiler warns about declarations of variable-length arrays whose size is either unbounded, or bounded by an argument that lets the array size go over byte-size bytes. It's kind of like how-Walloca-larger-than=byte-sizeworks, but for VLAs 👑
Real talk though: GCC may optimize small variable-length arrays with a known value into plain arrays, so this warning might not fire for those ones 🙈
-Wvla-larger-than=PTRDIFF_MAX is on 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— turns off the-Wvla-larger-than=warnings. It's the same as-Wvla-larger-than=SIZE_MAXor larger 💜-Wvla-parameter— warns about redeclarations of functions that have variable-length array arguments of inconsistent kinds or forms, and it also turns on detection of out-of-bounds accesses to those parameters through 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 also the maximum number of elements it accesses. Not providing arguments of sufficient size, or accessing more than that max, may get diagnosed 😭
Here's the example, exactly as written, so you can see the chaos in action:
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);
...
}The warning triggers for these redeclarations because the first one lets an array of any size get passed to f, while the second one says the array argument has to have at least n elements. On top of that, calling f with the associated VLA bound parameter larger than the actual VLA bound also triggers a warning 💅
-Wvla-parameter is included in -Wall. For similar problems with ordinary array arguments, -Warray-parameter is the one that warns 🌈
-Wvolatile-register-var— warns if a register variable is declaredvolatile. Real tea: thevolatilemodifier doesn't stop every optimization that might 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 the warnings about uses of^, the exclusive or operator, when it looks like the code meant exponentiation. Specifically, it fires 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, but in some other languages (like TeX and some versions of BASIC) it means exponentiation. Iykyk 🫶
You can silence this warning by converting one of the operands to hexadecimal, and also by compiling with -Wno-xor-used-as-pow.
-Wdisabled-optimization— warns if a requested optimization pass is disabled. Don't panic, this doesn't usually mean your code is wrong 🌸 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, and GCC refuses to optimize programs when the optimization would likely take inordinate amounts of time 🐢-Wpointer-sign(C and Objective-C only) — warns for pointer argument passing or assignment with different signedness. It's only supported for C and Objective-C. It's implied by-Walland by-Wpedantic, and you can disable it with-Wno-pointer-sign💖
This warning is upgraded to an error by -pedantic-errors.
-Wstack-protector— only active when-fstack-protectoris active. It warns about functions that aren't protected against stack smashing 🛡️-Woverlength-strings— warns about string constants longer than the "minimum maximum" length the C standard specifies. Modern compilers usually allow way longer strings than the standard's minimum, but very portable programs should avoid them 🧵
The limit applies after string constant concatenation, and it doesn't count the trailing NUL. In C90, the limit was 509 characters. In C99, it got raised to 4095. C++98 doesn't specify a normative minimum maximum, so GCC doesn't diagnose overlength strings in C++ 💅
This option is implied by -Wpedantic, and you can disable it with -Wno-overlength-strings.
-Wunsuffixed-float-constants(C and Objective-C only) — warns about any floating constant that doesn't have a suffix. If you pair it with-Wsystem-headers, it also warns about those constants in system header files 🌈 This is super useful when you're prepping code to use with theFLOAT_CONST_DECIMAL64pragma from the decimal floating-point extension to C99.-Wno-lto-type-mismatch— during link-time optimization, this stops GCC from warning about type mismatches in global declarations from different compilation units. It requires-fltoto be enabled, and it's enabled by default ✨-Wno-designated-init(C and Objective-C only) — suppresses warnings when a positional initializer is used to initialize a structure that's been marked with thedesignated_initattribute 🎀
✨ Options That Control Static Analysis ✨
-fanalyzer— okay, this one turns on a static analysis of program flow. It hunts for "interesting" interprocedural paths through the code and drops warnings for problems it finds on them 🔍
Heads up, it's way more expensive than other GCC warnings 💸
Technically speaking, it does coverage-guided symbolic execution of the code being compiled. It's neither sound nor complete, which means it can have false positives and false negatives. It's a bug-finding tool, not a tool for proving program correctness 🫠
The analyzer is only suitable for C code in this release.
Enabling this option effectively enables the following 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-throw-of-unexpected-type
-Wanalyzer-undefined-behavior-ptrdiff
-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-literalThis option is only available if GCC was configured with analyzer support enabled.
-Wanalyzer-symbol-too-complex— if-fanalyzeris enabled, the analyzer uses various heuristics to try to track the state of memory. But sufficiently complicated code can defeat those heuristics 🌀
By default, the analysis quietly gives up on tracking expression values once they blow past an internal limit 🙈, and it falls back to an imprecise representation for them. The -Wanalyzer-symbol-too-complex option is the one that actually warns you when this happens 🫶
-Wanalyzer-too-complex— the analyzer's explorer brain getting overwhelmed 🧚
If -fanalyzer is on, the analyzer uses a bunch of heuristics to poke around the control flow and data flow of your program ✨. But sufficiently complicated code can totally defeat them 💀.
By default, if the code is too complicated for the analyzer to fully explore and it hits an internal limit, the analysis just stops, no fuss. -Wanalyzer-too-complex makes it warn you instead 📢.
-Wno-analyzer-allocation-size— flags buffer sizes that don't line up with the pointer type 📏
This warning requires -fanalyzer, which enables it; to disable it, use -Wno-analyzer-allocation-size.
This diagnostic 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).
-Wno-analyzer-deref-before-check— catchesNULLchecks that show up after the pointer was already dereferenced 🙃
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-deref-before-check to disable it.
This diagnostic warns for paths through the code where a pointer is checked for NULL after it has already been dereferenced, which suggests the pointer could have been NULL. Cases like this mean the NULL check is either redundant, or it needs to be moved to before the pointer is dereferenced.
This diagnostic also considers values passed to a function argument marked with __attribute__((nonnull)) as requiring a non-NULL value, so it'll complain if such values get checked for NULL after returning from that function call.
⚠️ This diagnostic is unlikely to be reported when any level of optimization is enabled, because GCC's optimization logic typically considers those NULL checks redundant and optimizes them away before the analyzer "sees" them. So you should disable optimization when you're trying to trigger this one 💅
-Wno-analyzer-double-fclose— yells when aFILE *getsfclosed more than once 📁
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-double-fclose to disable it.
This diagnostic warns for paths through the code where a FILE * can have fclose called on it more than once.
📚 See CWE-1341: Multiple Releases of Same Resource or Handle (https://cwe.mitre.org/data/definitions/1341.html).
-Wno-analyzer-double-free— spots pointers that get freed twice 💀
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-double-free to disable it.
This diagnostic warns for paths through the code where a pointer can have a deallocator called on it more than once, either free, or a deallocator referenced by attribute malloc.
📚 See CWE-415: Double Free (https://cwe.mitre.org/data/definitions/415.html).
-Wno-analyzer-exposure-through-output-file— stops secrets from leaking into output files 🤫
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-exposure-through-output-file to disable it.
This diagnostic warns for paths through the code where a security-sensitive value is 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— warns about uninitialized data crossing a trust boundary 🚨
This warning requires both -fanalyzer and the use of a plugin to specify a function that copies across a "trust boundary". Use -Wno-analyzer-exposure-through-uninit-copy to disable it.
This diagnostic warns for "infoleaks", which are paths through the code where uninitialized values get copied across a security boundary. A classic example is code inside an OS kernel that copies a partially-initialized struct on the stack out 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— yells when you read from a write-only fd, or write to a read-only one 🙅
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-fd-access-mode-mismatch to disable it.
This diagnostic warns for paths through the code where a "read" is attempted on a write-only file descriptor, or vice versa.
This diagnostic also warns for code paths where a function with attribute fd_arg_read (N) is called with a file descriptor opened with O_WRONLY at referenced argument N, or where a function with attribute fd_arg_write (N) is called with a file descriptor opened with O_RDONLY at referenced argument N.
-Wno-analyzer-fd-double-close— catches fds that get closed more than once 🦋
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-fd-double-close to disable it.
This diagnostic warns for paths through the code 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— flags open fds that never get released 🌸
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-fd-leak to disable it.
This diagnostic warns for paths through the code where an open file descriptor is 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— operations done at the wrong point in an fd's life 🧩
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-fd-phase-mismatch to disable it.
This diagnostic warns for paths through the code where an operation is attempted in the wrong phase of a file descriptor's lifetime. For example, it'll warn on attempts to call accept on a stream socket that has not yet had listen successfully called on it.
📚 See CWE-666: Operation on Resource in Wrong Phase of Lifetime (https://cwe.mitre.org/data/definitions/666.html).
-Wno-analyzer-fd-type-mismatch— wrong kind of fd for the operation you're doing 🙈
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-fd-type-mismatch to disable it.
This diagnostic warns for paths through the code where an operation is attempted on the wrong type of file descriptor. For example, it'll warn on attempts to use socket operations on a file descriptor obtained via open, or when attempting to use a stream socket operation on a datagram socket.
-Wno-analyzer-fd-use-after-close— using an fd after it's already been closed ⏰
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-fd-use-after-close to disable it.
This diagnostic warns for paths through the code where a read or write is called on a closed file descriptor.
This diagnostic also warns for paths through the code where a function with attribute fd_arg (N) or fd_arg_read (N) or fd_arg_write (N) is called with a closed file descriptor at referenced argument N.
-Wno-analyzer-fd-use-without-check— using an fd without checking it's valid first 🫣
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-fd-use-without-check to disable it.
This diagnostic warns for paths through the code where a file descriptor is used without being checked for validity.
This diagnostic also warns for paths through the code where a function with attribute fd_arg (N) or fd_arg_read (N) or fd_arg_write (N) is called with a file descriptor, at referenced argument N, without being checked for validity.
-Wno-analyzer-file-leak—FILE *streams that never get cleaned up 📄
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-file-leak to disable it.
This diagnostic warns for paths through the code where a <stdio.h> FILE * stream object is leaked.
📚 See CWE-775: Missing Release of File Descriptor or Handle after Effective Lifetime (https://cwe.mitre.org/data/definitions/775.html).
-Wno-analyzer-free-of-non-heap— callingfreeon something that was never on the heap 🪦
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-free-of-non-heap to disable it.
This diagnostic warns for paths through the code where free is called on a non-heap pointer, like an on-stack buffer or a global.
📚 See CWE-590: Free of Memory not on the Heap (https://cwe.mitre.org/data/definitions/590.html).
-Wno-analyzer-imprecise-fp-arithmetic— floating-point math where precision matters 🧮
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-imprecise-fp-arithmetic to disable it.
This diagnostic warns for paths through the code where floating-point arithmetic is used in locations where precise computation is needed. At the moment, it only warns on the use of floating-point operands inside the calculation of an allocation size.
-Wno-analyzer-infinite-loop— loops that look like they'll never end 🔁
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-infinite-loop to disable it.
This diagnostic warns for paths through the code which appear to lead to an infinite loop.
Specifically, the analyzer will issue this warning when it "sees" a loop in which:
- no externally-visible work could be being done within the loop
- there is no way to escape from the loop
- the analyzer is sufficiently confident about the program state throughout the loop to know that the above are true
One way for this warning to be emitted is when there is an execution path through a loop for which taking the path on one iteration implies that the same path will be taken on all subsequent iterations.
For example, consider:
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 complain for the above case because if opcode ever matches none of the cases, the switch will follow the implicit default case, making the body of the loop be a no-op with cpu_state.pc unchanged, and thus using the same value of opcode on all subsequent iterations, leading to an infinite loop 🌀.
📚 See CWE-835: Loop with Unreachable Exit Condition ('Infinite Loop') (https://cwe.mitre.org/data/definitions/835.html).
-Wno-analyzer-infinite-recursion— recursion that never bottoms out 🪞
This warning requires -fanalyzer, which enables it; use -Wno-analyzer-infinite-recursion to disable it.
Okay so this one is about infinite recursion 🌀 It warns about paths in the code that look like they never stop calling themselves, which is giving "this function will never end" 💀
Here's how the analyzer sees it: whenever it spots 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 of that same function on the stack 🧚 The warning only shows up if nothing in memory seems to be changing. If any parameters or globals look like they're changing, the analyzer assumes the recursion will end and quietly skips the warning 🫶
Heads up though 🙈 this diagnostic can miss infinite recursion that the optimizer already turned into iteration before the analyzer gets to look. So if you're trying to trigger it, disable optimization ✨
Compare with -Winfinite-recursion, which gives a similar diagnostic but is implemented a different way 💜
See CWE-674: Uncontrolled Recursion ("https://cwe.mitre.org/data/definitions/674.html").
-Wno-analyzer-jump-through-null— 🦋 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-jump-through-null. It warns about paths where a "NULL" function pointer gets called 💀-Wno-analyzer-malloc-leak— 🌸 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-malloc-leak. It warns about paths where a pointer from an allocator gets leaked. The allocator can be eithermalloc, or a function marked with attributemalloc🫠- See CWE-401: Missing Release of Memory after Effective Lifetime (
"https://cwe.mitre.org/data/definitions/401.html").
- See CWE-401: Missing Release of Memory after Effective Lifetime (
-Wno-analyzer-mismatching-deallocation— 💅 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-mismatching-deallocation. It warns about paths where the wrong deallocation function gets called on a pointer, based on which function allocated it. It catches mismatches betweenfree, scalardelete, and vectordelete[], plus anything marked as an allocator/deallocator pair using attributemalloc🔥- See CWE-762: Mismatched Memory Management Routines (
"https://cwe.mitre.org/data/definitions/762.html").
- See CWE-762: Mismatched Memory Management Routines (
-Wno-analyzer-out-of-bounds— 👑 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-out-of-bounds. It warns about paths where a buffer is definitely read or written out of bounds. It works when the analyzer can figure out a constant offset, and for accesses past the end of a buffer with a constant capacity. It also does 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 (
"https://cwe.mitre.org/data/definitions/119.html"). - When the analyzer can manage it, it draws a text art diagram 🎨 of the memory region it predicts will be accessed, next to the range that's actually valid. The diagram shows whether they overlap, touch, or sit close or far apart, which one comes first in memory, the relative sizes, whether the access is a read or a write, and sometimes the values of the data involved. You can hide this diagram with
-fdiagnostics-text-art-charset=none.
- See CWE-119: Improper Restriction of Operations within the Bounds of a Memory Buffer (
-Wno-analyzer-overlapping-buffers— 🫶 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-overlapping-buffers. It warns about paths where overlapping buffers get passed to an API where the behavior is undefined for that kind of input. Specifically, it looks at calls to these functions, but only when the buffers are known to overlap:*<"memcpy">*<"strcat">*<"strcpy">
-Wno-analyzer-possible-null-argument— 🌈 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-possible-null-argument. It warns about paths where a possibly-NULL value gets passed to a function argument marked with__attribute__((nonnull))as needing a non-NULL value 💖- See CWE-690: Unchecked Return Value to NULL Pointer Dereference (
"https://cwe.mitre.org/data/definitions/690.html").
- See CWE-690: Unchecked Return Value to NULL Pointer Dereference (
-Wno-analyzer-possible-null-dereference— ✨ This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-possible-null-dereference. It warns about paths where a possibly-NULL value gets dereferenced 🙈- See CWE-690: Unchecked Return Value to NULL Pointer Dereference (
"https://cwe.mitre.org/data/definitions/690.html").
- See CWE-690: Unchecked Return Value to NULL Pointer Dereference (
-Wno-analyzer-null-argument— 🍓 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-null-argument. It warns about paths where a value known to be NULL gets passed to a function argument marked with__attribute__((nonnull))as needing a non-NULL value 💀- See CWE-476: NULL Pointer Dereference (
"https://cwe.mitre.org/data/definitions/476.html").
- See CWE-476: NULL Pointer Dereference (
-Wno-analyzer-null-dereference— 🧚 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-null-dereference. It warns about paths where a value known to be NULL gets dereferenced 😭- See CWE-476: NULL Pointer Dereference (
"https://cwe.mitre.org/data/definitions/476.html").
- See CWE-476: NULL Pointer Dereference (
-Wno-analyzer-putenv-of-auto-var— 🎀 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-putenv-of-auto-var. It warns about paths where a call to "putenv" gets passed a pointer to an automatic variable or an on-stack buffer 👀- See POS34-C. Do not call putenv() with a pointer to an automatic variable as the argument (
"https://wiki.sei.cmu.edu/confluence/x/6NYxBQ").
- See POS34-C. Do not call putenv() with a pointer to an automatic variable as the argument (
-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 warns about paths where a shift is attempted with a negative count. It's the analyzer's version of-Wshift-count-negative, which the C/C++ front ends do, but this one looks at interprocedural paths instead of just parsing the syntax tree. The analyzer doesn't prioritize finding these, so false negatives are more likely compared to other warnings 🫠-Wno-analyzer-shift-count-overflow— 💜 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-shift-count-overflow. It warns about paths where a shift is attempted with a count greater than or equal to the precision of the operand's type. It's analogous to-Wshift-count-overflowin the C/C++ front ends, but it's based on analyzing interprocedural paths rather than just the syntax tree. Same catch as before: the analyzer doesn't prioritize these, so false negatives are more likely compared to other warnings 🫶-Wno-analyzer-stale-setjmp-buffer— 😭 This one needs-fanalyzerto turn it on, and you can switch it off with-Wno-analyzer-stale-setjmp-buffer. It warns about paths where "longjmp" gets called to rewind to a "jmp_buf" tied to a "setjmp" call, in a function that has already returned ⚠️- When "setjmp" is called on a "jmp_buf" to record a rewind location, it records the stack frame. That stack frame becomes invalid once the function containing the "setjmp" call returns. Trying to rewind to it with "longjmp" would reference a stack frame that no longer exists, and that's likely to crash (or worse) 💀
-Wno-analyzer-tainted-allocation-size— 🔥 This one needs-fanalyzerwhich turns it on, and you can switch it off with-Wno-analyzer-tainted-allocation-size. It warns about paths where a value an attacker could control gets used as the size of an allocation without being sanitized first. That means an attacker could inject a huge allocation and maybe cause a denial of service attack 🙅♀️- See CWE-789: Memory Allocation with Excessive Size Value (
"https://cwe.mitre.org/data/definitions/789.html").
- See CWE-789: Memory Allocation with Excessive Size Value (
-Wno-analyzer-tainted-assertion— 👑 This one needs-fanalyzerwhich turns it on, and you can switch it off with-Wno-analyzer-tainted-assertion. It warns about paths where a value an attacker could control gets used as part of a condition without being sanitized first, and that condition guards a call to a function marked with attributenoreturn(like the function__builtin_unreachable). Those functions usually mean the program is terminating abnormally, like assertion failure handlers. For example:
assert (some_tainted_value < SOME_LIMIT);In those 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 the code is assuming
Heads up 💅 when assertion-checking is disabled, the preprocessor usually removes the assertions before the analyzer gets a chance to "see" them. So this diagnostic can only generate warnings on builds where assertion-checking is enabled.
For this warning, any function marked with attribute noreturn counts as a possible assertion failure handler, including __builtin_unreachable. These functions are sometimes removed by the optimizer before the analyzer "sees" them, so disable optimization 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 */
}Okay so that default: branch is giving 💀 because the comment literally says an attacker can trigger it 😭 Despite the example above, it's not an assertion failure, strictly speaking 🙄 but it's still a whole vibe check 🔥
-Wno-analyzer-tainted-array-index— ✨ This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-tainted-array-indexto turn it off. It flags paths where a value an attacker could control gets used as an array index without being sanitized, so an attacker could sneak in an out-of-bounds access 👀- See CWE-129: Improper Validation of Array Index (
https://cwe.mitre.org/data/definitions/129.html).
- See CWE-129: Improper Validation of Array Index (
-Wno-analyzer-tainted-divisor— 🦋 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-tainted-divisorto turn it off. It flags paths where an attacker-controllable value is used as the divisor in a division or modulus operation without being sanitized, so an attacker could inject a division-by-zero 💅- See CWE-369: Divide By Zero (
https://cwe.mitre.org/data/definitions/369.html).
- See CWE-369: Divide By Zero (
-Wno-analyzer-tainted-offset— 🌸 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-tainted-offsetto turn it off. It flags paths where an attacker-controllable value is used as a pointer offset without being sanitized, 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).
- See CWE-823: Use of Out-of-range Pointer Offset (
-Wno-analyzer-tainted-size— 🍓 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-tainted-sizeto turn it off. It flags paths where an attacker-controllable value is used as the size of an operation such asmemsetwithout being sanitized, 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).
- See CWE-129: Improper Validation of Array Index (
-Wno-analyzer-throw-of-unexpected-type— 🧚 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-throw-of-unexpected-typeto turn it off. Heads up, dynamic exception specifications are only available in C++14 and earlier. It flags paths where an exception is thrown from a function with a dynamic exception specification and the exception doesn't comply with that specification 💜-Wno-analyzer-undefined-behavior-ptrdiff— 🫶 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-undefined-behavior-ptrdiffto turn it off. It flags paths where a pointer subtraction happens between pointers that refer to different chunks of memory. That code relies on undefined behavior, because pointer subtraction is only defined when both pointers point within (or just after) the same array ⚠️- See CWE-469: Use of Pointer Subtraction to Determine Size (
https://cwe.mitre.org/data/definitions/469.html).
- See CWE-469: Use of Pointer Subtraction to Determine Size (
-Wno-analyzer-undefined-behavior-strtok— 🎀 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-undefined-behavior-strtokto turn it off. It flags paths where a call tostrtokhas undefined behavior. Specifically, passingNULLas the first parameter for the initial call tostrtokwithin a process is undefined behavior 💀-Wno-analyzer-unsafe-call-within-signal-handler— 🔥 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-unsafe-call-within-signal-handlerto turn it off. It flags paths where a function known to be async-signal-unsafe (such asfprintf) 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).
- See CWE-479: Signal Handler Use of a Non-reentrant Function (
-Wno-analyzer-use-after-free— 👑 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-use-after-freeto turn it off. It flags paths where a pointer gets used after a deallocator has been called on it. That means eitherfree, or a deallocator referenced by attributemalloc🥀- See CWE-416: Use After Free (
https://cwe.mitre.org/data/definitions/416.html).
- See CWE-416: Use After Free (
-Wno-analyzer-use-of-pointer-in-stale-stack-frame— 🌈 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-use-of-pointer-in-stale-stack-frameto turn it off. It flags paths where a pointer gets dereferenced while pointing to a variable in a stale stack frame ⭐-Wno-analyzer-va-arg-type-mismatch— 💖 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-va-arg-type-mismatchto turn it off. It flags 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 expression passed to the call 🧐- See CWE-686: Function Call With Incorrect Argument Type (
https://cwe.mitre.org/data/definitions/686.html).
- See CWE-686: Function Call With Incorrect Argument Type (
-Wno-analyzer-va-list-exhausted— ✨ This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-va-list-exhaustedto turn it off. It flags 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).
- See CWE-685: Function Call With Incorrect Number of Arguments (
-Wno-analyzer-va-list-leak— 🍃 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-va-list-leakto turn it off. It flags interprocedural paths where the analyzer detects thatva_startorva_copyhas been called on ava_listwithout a matching call tova_end📝-Wno-analyzer-va-list-use-after-va-end— 🎠 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-va-list-use-after-va-endto turn it off. It flags interprocedural paths where the analyzer detects an attempt to use ava_listafterva_endhas been called on it 🛑-Wno-analyzer-write-to-const— 🦄 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-write-to-constto turn it off. It flags paths where the analyzer detects an attempt to write through a pointer to aconstobject. Fair warning though, the analyzer doesn't prioritize catching these, so false negatives are more likely compared to other warnings 🙃-Wno-analyzer-write-to-string-literal— 🌷 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-write-to-string-literalto turn it off. It flags paths where the analyzer detects an attempt to write through a pointer to a string literal. Same deal though, the analyzer doesn't prioritize these, so false negatives are more likely compared to other warnings 🫣-Wno-analyzer-use-of-uninitialized-value— 🍭 This warning requires-fanalyzer, which enables it. Use-Wno-analyzer-use-of-uninitialized-valueto turn it off. It flags paths where an uninitialized value gets used 🥺- See CWE-457: Use of Uninitialized Variable (
https://cwe.mitre.org/data/definitions/457.html).
- See CWE-457: Use of Uninitialized Variable (
Okay, so the analyzer 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 the behavior of these functions for working with file descriptors 📂
openclosecreatdup,dup2anddup3isattypipe, andpipe2readwritesocket,bind,listen,accept, andconnect
And these functions for working with <stdio.h> streams 🌊
- 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, these ones too 💅
- 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
In addition, various functions with an __analyzer_ prefix have special meaning to the analyzer. These are described in the GCC Internals manual 📖 Various internal parameters, settable via --param, are used to control the exploration, and those are documented in the GCC Internals manual too 🔍
The following options control the analyzer 🎀
-fanalyzer-assume-nothrow— okay so by default, if-fexceptionsis on, the analyzer assumes that calling any function without the "nothrow" attribute could throw an exception 😭. This is amazing for catching paths that leak because exceptions skip the clean-up code, but it can lead to false positives when you're using headers where the author didn't add the "nothrow" attribute 🙈.- If
-fanalyzer-assume-nothrowis enabled, the analyzer assumes external functions never throw exceptions ✨. This can reduce the "noise" when you turn on-fexceptionsfor C code, but it could hide real issues if something the C code calls can raise an exception 💀.
- If
-fanalyzer-call-summaries— this one simplifies interprocedural analysis by computing the effect of certain calls instead of exploring every path through the function from the callsite to each possible return 🧠. Only functions with more than one call site, and that are sufficiently complicated, get call summaries 💅.-fanalyzer-checker=name— restricts the analyzer to run just the named checker, and enables it 🎯.-fanalyzer-debug-text-art-headings— this is for analyzer developers only 🛠️. If enabled, the analyzer adds extra annotations to any diagrams it generates 🎨.-fno-analyzer-feasibility— this one's for analyzer developers too 🧑💻. 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 with no feasible path get rejected 🚫. This filtering can be suppressed with-fno-analyzer-feasibility, which is handy for debugging issues in this code 🔍.-fanalyzer-fine-grained— does nothing 🤷♀️. It's only kept around for backward compatibility 🕰️.-fanalyzer-show-duplicate-count— another developer-only option 🙋♀️. If several diagnostics are detected as duplicates of each other, this emits a note when reporting the best diagnostic, giving the number of additional diagnostics the deduplication logic suppressed 🔢.-fanalyzer-show-events-in-system-headers— by default, the analyzer keeps simplified diagnostic paths tidy by hiding events fully located within a system header 🧹. With-fanalyzer-show-events-in-system-headers, those events stop getting suppressed 👀.-fno-analyzer-simplify-supergraph— developer-only vibes 🧪. By default, the analyzer simplifies the program supergraph before analyzing it. With-fno-analyzer-simplify-supergraph, that simplification gets skipped, which is useful for debugging issues with it 🐛.-fno-analyzer-state-merge— developer-only again 💻. By default, the analyzer merges sufficiently similar states at each program point while it builds its "exploded graph" 🧩. With-fno-analyzer-state-merge, that merging is suppressed, handy for debugging state-handling issues 🔧.-fno-analyzer-state-purge— for analyzer developers 🫶. By default, the analyzer purges aspects of state at a program point that don't seem relevant anymore, like 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 is 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 you with 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 be helpful for debugging the analyzer, or for microbenchmarks that detect undefined behavior 🧫.
-fanalyzer-transitivity— this one enables transitivity of constraints within the analyzer 🔗.-fno-analyzer-undo-inlining— developer-only 🧑🔬.-fanalyzerruns relatively late compared to other code analysis tools, so some optimizations have already been applied. In particular, function inlining may have happened, which means the interprocedural execution paths the analyzer emits can contain function frames that don't match the original source code 😵💫. By default, the analyzer tries to reconstruct the original function frames and emit events showing the inlined calls ✨. With-fno-analyzer-undo-inlining, that reconstruction is disabled, which may help when debugging issues in the analyzer 🛠️.-fanalyzer-verbose-edges— for analyzer developers 📚. It turns on more verbose, lower-level detail in the descriptions of control flow within diagnostic paths 🌀.-fanalyzer-verbose-state-changes— also for analyzer developers 🧑💻. It turns on more verbose, lower-level detail in the descriptions of events relating to state machines within diagnostic paths 🎢.-fanalyzer-verbosity=level— this one controls how complex the control flow paths are that get emitted for analyzer diagnostics 📜. Thelevelcan be one of:0— 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 to "free" will show up 👯.1— same as the previous level, but also shows events for the entry to each function 🚪.2— same as the previous level, but also shows control flow events that matter for triggering the issue, like "true path taken" at a conditional 🔀. This is the default, so it's the main character level 👑.3— same as the previous level, but shows all control flow events, not just the significant ones 🌊.4— for analyzer developers only 🤓. It adds various other events meant 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" that's suitable for viewing with GraphViz, tofile.eg.dot🎨. The nodes are color-coded based on state-machine states, so state changes really pop 💖.-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— dumps a textual representation of the "exploded graph" to one dump file per node, namedfile.eg-id.txt📂. Heads up, this is typically a large number of dump files 😭.-fdump-analyzer-exploded-paths— dumps a textual representation of the "exploded path" for each diagnostic tofile.idx.kind.epath.txt🧾.-fdump-analyzer-feasibility— dumps internal details about the analyzer's search for feasible paths 🔎. The details are written in a form suitable for GraphViz, to filenames likefile.*.fg.dot,file.*.tg.dot, andfile.*.fpath.txt🖼️.-fdump-analyzer-infinite-loop— dumps internal details about the analyzer's search for infinite loops ♾️. The details are written in a form suitable for GraphViz, to filenames likefile.*.infinite-loop.dot🌀.-fdump-analyzer-json— dumps a compressed JSON representation of analyzer internals tofile.analyzer.json.gz🗜️. Heads up, the precise format is subject to change ⚠️.-fdump-analyzer-state-purge— same idea as-fdump-analyzer-supergraph, so it dumps a "supergraph" representation suitable for GraphViz 🗺️. But this one annotates the graph with info on what state will be purged at each node 🧹. The graph is written tofile.state-purge.dot💜.-fdump-analyzer-supergraph— dumps representations of the "supergraph" suitable for GraphViz tofile.supergraph.index.kind.dot🌈. These show all of the control flow graphs in the program at various stages of the analysis 📈. The precise set of dumps and what they show is subject to change 🙈.-fdump-analyzer-untracked— emits custom warnings with internal details meant for analyzer developers 🚨.
✨ Options for Debugging Your Program ✨
To get GCC to emit extra info for a debugger, you almost always just need to add -g to your other options 🐞. Some debug formats can co-exist (like DWARF with CTF) when each one is explicitly enabled by adding its own command line option to your other options 🫶.
GCC lets you use -g with -O 💅. The shortcuts taken by optimized code can be a little surprising 😳: some variables you declared may not exist at all, flow of control may briefly move somewhere you didn't expect, some statements may not execute because they compute constant results or their values are already at hand, and some statements may execute in different places because they've been moved out of loops 🌀. Still, it's totally possible to debug optimized output, which makes it reasonable to use the optimizer for programs that might have bugs 💖.
If you're not using some other optimization option, consider using -Og with -g 🧚. With no -O option at all, some compiler passes that collect info useful for debugging don't run, so -Og may give you a better debugging experience ✨.
-g,--debug— produces debugging information in the operating system's native format (stabs, COFF, XCOFF, or DWARF) 🎀. GDB can work with this debugging information 🦋.
On most systems that use stabs format, -g unlocks extra debugging info that only GDB can actually use 🔍. It makes debugging in GDB way smoother, but it can make other debuggers crash or refuse to read the program 💀. If you want to be certain whether that extra info gets generated, use -gvms instead (more on that below) ✨.
-ggdb— Asks for the most expressive debug format available, which is DWARF, then stabs, then the native format if neither of those is supported 🦋. GDB extensions get included too, if at all possible 💖.-gdwarf,-gdwarf-version— Makes DWARF debug info, as long as the target supports it 🌈. The version can be2,3,4or5. Most targets default to version 5, 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 need GDB 7.0 and
-fvar-tracking-assignmentsto get the full benefit. Version 5 needs GDB 8.0 or higher. - GCC no longer supports DWARF Version 1, which is very different from Version 2 and later. For historical reasons, some other DWARF-related options, such as
-fno-dwarf2-cfi-asm, still have Version 2 in their names, but they apply to every DWARF version that's currently supported 📜.
-gbtf— Requests BTF debug info. BTF is the default debugging format for the eBPF target 🧚. On other targets, like x86, BTF can be generated alongside DWARF if you turn on both formats explicitly with their own command-line options.-gprune-btf,-gno-prune-btf— Prunes BTF info before it gets emitted ✂️. When pruning, only type info for types used by global variables and file-scope functions gets emitted. If you're compiling for the BPF target with BPF CO-RE enabled, type info also gets emitted for types used in BPF CO-RE relocations. Struct and union types that are only referred to through pointers from members of other struct or union types get pruned and replaced withBTF_KIND_FWD, as though they were only forward declarations in the input.- This option shrinks the BTF output a ton, but you lose a lot of detailed type info 😭. It's mainly useful for the BPF target, where it keeps the object small and drops BTF info that doesn't matter for loading the BPF program.
- It's turned on by default for the BPF target when BTF info is being generated.
-gctf,-gctflevel— Requests CTF debug info, and the level decides how much gets made 🎀. If you use-gctfwithout a level, the default is 2. CTF can be generated alongside DWARF if you turn on both formats explicitly with their own command-line options.- Level 0 produces no CTF debug info at all, so
-gctf0cancels out-gctf🙅. - Level 1 produces CTF info for tracebacks only. That includes callsite info but not type info.
- Level 2 produces type info only for entities (functions, data objects etc.) at file scope or global scope.
- Level 0 produces no CTF debug info at all, so
-gvms— Makes debug info in the Alpha/VMS debug format, if that's supported. It's the format DEBUG uses on Alpha/VMS systems 💜.-gcodeview— Makes debug info in the CodeView format, if that's supported. Microsoft Visual C++ uses this one on Windows 🪟.-glevel,-ggdblevel,-gvmslevel— Requests debug info and uses the level to set how much you get 📊. The default level is 2.- Level 0 produces no debug info at all, so
-g0cancels out-g. - Level 1 produces minimal info, enough for 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 adds extra info, like all the macro definitions in the program. Some debuggers can do macro expansion when you use
-g3🔎. - If you use several
-goptions, with or without level numbers, the last one wins 👑. -gdwarfdoesn't accept a concatenated debug level, so it won't get confused with-gdwarf-level. Use an extra-gleveloption to change the debug level for DWARF instead 🫶.
- Level 0 produces no debug info at all, so
-fno-eliminate-unused-debug-symbols— By default, no debug info gets 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 debug info for a C++ class in just one object file, this emits it in every object file that uses the class. Only use it with debuggers that can't handle the way GCC normally emits class debug info, because it can make the debug info up to twice as big 😬.-fno-merge-debug-strings— Tells the linker not to merge strings in the debug info that are identical across different object files. Not every assembler or linker supports merging. Merging makes the debug info in the output file smaller, but it costs more link time. Merging is enabled by default 🧵.-fdebug-prefix-map=old=new— When compiling files in directoryold, the debug info describes them as if they lived in directorynewinstead 🗺️. You can use it to swap 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. That can give more reproducible builds, which don't depend on location, 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 🕵️♀️. It works out where variables are stored at each position in the code, so better debug info gets generated (if the debug format supports that). It's enabled by default when you compile with optimization (-Os,-O,-O2, ...), with debug info (-g), and the debug info format supports it.-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-4alongside it is recommended.- It can be turned on even when var-tracking is off. In that case the annotations get created and maintained, then thrown away at the end.
- By default, this flag is enabled together with
-fvar-tracking, except when selective scheduling is enabled.
-fvar-tracking-uninit,-fno-var-tracking-uninit— Does variable tracking and also marks uninitialized variables in the debug info 🏷️. This flag is enabled by default by-fvar-tracking, and it also implies-fvar-tracking. To do variable tracking without marking uninitialized variables, use-fvar-tracking -fno-var-tracking-uninit.-gsplit-dwarf— If DWARF debug info is enabled, it pulls out as much of that info as possible into a separate output file with the.dwoextension 📦. This lets your build system avoid linking files that have debug info. To be useful, you need 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 depends on the target, but on most targets it's-gdwarf32. The 32-bit format is smaller, but none of the DWARF debug info sections can go past 2GiB. The 64-bit format allows bigger debug info, though not every consumer supports it well yet.-gdescribe-dies— Adds description attributes to some DWARF DIEs that have no name attribute, like artificial variables, external references and call site parameter DIEs 🏷️.-gpubnames— Generates the DWARF.debug_pubnamesand.debug_pubtypessections 📚.-ggnu-pubnames— Generates.debug_pubnamesand.debug_pubtypesin a format that's suitable for converting into a GDB index. This is only useful with a linker that can produce GDB index version 7 🧩.-gno-pubnames— Doesn't generate the DWARF.debug_pubnamesand.debug_pubtypessections 🚫.-fdebug-types-section— With DWARF Version 4 or higher, type DIEs can go into their own.debug_typessection instead of living in.debug_info🗂️. It's more efficient to put them in a separate comdat section, since the linker can then remove duplicates. But not every DWARF consumer supports.debug_typesyet, and for some objects it makes the debug info bigger instead of smaller 😵.-grecord-gcc-switches,-gno-record-gcc-switches— Appends the command-line options that might affect code generation to theDW_AT_producerattribute in DWARF debug info 📝. The options are joined with spaces, separating them from each other and from the compiler version. It's enabled by default. See also-frecord-gcc-switchesfor another way to store compiler options in the object file.-gstrict-dwarf— Disallows using extensions from a later DWARF standard version than the one you picked with-gdwarf-version🚧. On most targets, using non-conflicting DWARF extensions from later standard versions is allowed.-gno-strict-dwarf— Allows using extensions from a later DWARF standard version than the one you picked with-gdwarf-version🌸.-gas-loc-support: okay so this one tells the compiler the assembler speaks.locdirectives 🧚, which means the compiler can let the assembler build the DWARF2+ line number tables. Ngl that's super desirable, because assembler-made line-number tables are a lot more compact than the ones the compiler can cook up on its own 💅. It's on by default if GCC's configure step found the assembler supports those directives ✨.-gno-as-loc-support: the opposite energy 🙅♀️. It forces GCC to generate DWARF2+ line number tables internally, but only if DWARF2+ line number tables are being generated in the first place.-gas-locview-support: tells the compiler the assembler can handle "view" assignment and reset assertion checking inside.locdirectives 🦋. It's on by default if, at GCC configure time, the assembler was found to support them.-gno-as-locview-support: forces GCC to assign view numbers internally 🫶, but only when-gvariable-location-viewshas been explicitly requested.-gcolumn-info,-gno-column-info: puts location column info into the DWARF debugging information, not just file and line 🎀. It's on by default, bestie.-gstatement-frontiers,-gno-statement-frontiers: GCC drops markers into its internal representation at the start of each statement and keeps them roughly in place through the whole compile 📍. Then it uses them to steer whereis_stmtmarkers show up in the line number table. This is on 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: adds progressive view numbers, implied from the line number table, onto the variable location lists 👑. This lets debug info consumers inspect state at certain points in the program, even when no instructions tied to those source locations are present there 🔍. If the assembler can't handle view numbers in line number tables, the compiler emits the line number table itself, which makes things somewhat less compact 🙈. The augmented line number tables and location lists are fully backward-compatible, so consumers that don't know about these augmentations can still read them. They just won't get any benefit from them either 🤷♀️.
This is on by default when outputting DWARF 2 debug info at the normal level, as long as there is assembler support, -fvar-tracking-assignments is enabled, and -gstrict-dwarf is not. When assembler support is missing, it can still be enabled, but it forces GCC to output internal line number tables. And if -ginternal-reset-location-views is not enabled, that most certainly leads to silently mismatching location views 😭.
⚠️ Heads up, bestie: there's a proposed view-number representation that is NOT 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 provided as 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 using it 💀.
-ginternal-reset-location-views,-gno-internal-reset-location-views: tries to figure out which location views can be left out of location view lists 🧮. This requires the compiler to have very accurate instruction length estimates, which isn't always the case. It may also silently generate incorrect view lists when using an assembler that doesn't support location view lists. The GNU assembler flags 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 are inserted at inlined entry points, so address and view numbers can be computed and output in debug info. This can be enabled 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 🗜️. Iftypeisn't given, the default depends on the capabilities of the assembler and linker used.typemay be one ofnone(don't compress debug sections),zlib(use zlib compression in ELF gABI format), orzstd(use zstd compression in ELF gABI format). If the linker doesn't support writing compressed debug sections, the option is 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 substantially reduces the size of debug info, but at significant potential loss in type information for the debugger. See-femit-struct-debug-reducedfor a less aggressive option, and-femit-struct-debug-detailedfor more detailed control. This option works only 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, unless the struct is a template or defined in a system header 🧹. This significantly reduces the size of debug info, with some potential loss in type information for the debugger. See-femit-struct-debug-baseonlyfor a more aggressive option, and-femit-struct-debug-detailedfor more detailed control. This option works only with DWARF debug output.-femit-struct-debug-detailed[=spec-list]: lets you specify the struct-like types GCC generates debug info for 🔍. The intent is to reduce duplicate struct debug info between different object files within the same program. It's the detailed version of-femit-struct-debug-reducedand-femit-struct-debug-baseonly, and it serves most needs. A specification has the syntax[dir:|ind:][ord:|gen:](any|sys|base|none).- The optional first word limits the specification 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 member. Indirect uses arise through pointers to structs. That is, when use of an incomplete struct is valid, the use is indirect. An example isstruct one direct;andstruct two * indirect;. - The optional second word limits the specification to ordinary structs (
ord:) or generic structs (gen:). Generic structs are a bit complicated to explain. For C++, these are non-explicit specializations of template classes, or non-template classes within the above. Other programming languages have generics, but-femit-struct-debug-detaileddoes not yet implement them. - The third word specifies the source files for those structs for which the compiler should emit debug info. The values
noneandanyhave the normal meaning. The valuebasemeans that the base of the name of the file in which the type declaration appears must match the base of the name of the main compilation file. In practice, this means that when compilingfoo.c, debug info is generated for types declared in that file andfoo.h, but not other header files. The valuesysmeans those types satisfyingbaseor declared in system or compiler headers.
- The optional first word limits the specification to structs that are used directly (
You may need to experiment to determine the best settings for your application 🧪. The default is -femit-struct-debug-detailed=all. This option works only with DWARF debug output.
-fno-dwarf2-cfi-asm: emits DWARF unwind info as a compiler-generated.eh_framesection, instead of using GAS.cfi_*directives 🧾.-fno-eliminate-unused-debug-types: normally, when producing DWARF output, GCC skips debug symbol output for types that are nowhere used in the source file being compiled. Sometimes it's useful to have GCC emit debug info for all types declared in a compilation unit, used or not. For example, if in the debugger you want to cast a value to a type that isn't actually used in your program (but is declared). More often, though, this just results in a significant amount of wasted space 🙃.
✨ Options That Control Optimization ✨
These options control various sorts of optimizations 🪄.
Without any optimization option, the compiler's goal is to reduce the cost of compilation and to make debugging produce the expected results. Statements are independent: if you stop the program with a breakpoint between statements, you can then assign a new value to any variable or change the program counter to any other statement in the function and get exactly the results you expect from the source code 🎯.
Turning on optimization flags makes the compiler attempt to improve the performance and/or code size at the expense of compilation time and possibly the ability to debug the program 🏋️♀️.
The compiler performs optimization based on the knowledge it has of the program. Compiling multiple files at once to a single output file mode allows the compiler to use information gained from all of the files when compiling each of them 🧠.
Not all optimizations are controlled directly by a flag. Only optimizations that have a flag are listed in this section.
Most optimizations are completely disabled at -O0 or if an -O level is not set on the command line, even if individual optimization flags are specified. Similarly, -Og suppresses many optimization passes 🙈.
Depending on the target and how GCC was configured, a slightly different set of optimizations may be enabled at each -O level than those listed here. You can invoke GCC with -Q --help=optimizers to find out the exact set of optimizations that are enabled at each level 🔎.
-O,-O1,--optimize: optimize, bestie 🔥. Optimizing compilation takes somewhat more time, and a lot more memory for a large function.
Okay so with -O, the compiler tries to shrink your code and make it run faster 🏃♀️💨, but it won't do anything that takes forever to compile. Lowkey the perfect balance, bestie ✨
If you're dealing with huge machine-generated code, -O is the vibe 💅. It's the recommended level because it balances compile time and memory use. The higher levels run optimizations with way more algorithmic complexity than plain -O does, so they cost more.
-O turns on this squad of 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 -fivopts -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 🌸
Optimize even more! 🔥 GCC performs nearly all supported optimizations that don't involve a space-speed tradeoff. Compared to -O, this option increases both the compilation time and the performance of the generated code, so it's a glow-up with a cost.
-O2 turns on all optimization flags specified by -O1. It also turns on these extras:
-falign-functions -falign-jumps -falign-labels -falign-loops
-fcaller-saves -fcode-hoisting -fcrossjumping -fcse-follow-jumps
-fcse-skip-blocks -fdelete-null-pointer-checks -fdep-fusion
-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-crc -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
-fspeculatively-call-stored-functions -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 check the warning under-fgcseabout invoking-O2on programs that use computed gotos. It's important, no cap.
NOTE 🎀: In Ubuntu 8.10 and later versions,-D_FORTIFY_SOURCE=2, and in Ubuntu 24.04 and later versions,-D_FORTIFY_SOURCE=3, is set by default. It's activated when-Ois set to 2 or higher. This enables additional compile-time and run-time checks for several libc functions. To turn it off, specify either-U_FORTIFY_SOURCEor-D_FORTIFY_SOURCE=0.
NOTE 🦋: In Debian 13 and Ubuntu 24.04 and later versions,-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 👑
Optimize yet more! 💖 -O3 turns on every optimization specified by -O2, and it also brings along these 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 🧚
Reduce compilation time and make debugging produce the expected results. This is the default, so you get it without asking 💅.
At -O0, GCC completely disables most optimization passes. They don't run even if you explicitly enable them on the command line, or if -Q --help=optimizers lists them as enabled by default. Many optimizations depend on code analysis or canonicalization passes that -O turns on, so running individual optimization passes in isolation wouldn't be useful anyway. Not worth the chaos, bestie.
🍓 -Os 🍓
Optimize for size! 🧸 -Os enables all the -O2 optimizations except the ones that often make your 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 further optimizations designed to shrink your code.
⚡ -Ofast ⚡
Disregard strict standards compliance. 😈 -Ofast enables all -O3 optimizations. It also enables optimizations that aren't valid for every standard-compliant program. It turns on -ffast-math, -fallow-store-data-races and the Fortran-specific -fstack-arrays, unless -fmax-stack-var-size is specified, and -fno-protect-parens. It turns off -fsemantic-interposition.
⚠️ Danger zone, bestie: because -Ofast enables optimizations that aren't valid for all standard-compliant programs, it can change how your code behaves. Only reach for it if you've checked that your code can handle it. 💀
🔍 -Og 🔍
Optimize while keeping debugging in mind! 🕵️♀️ -Og should be the level of choice for the standard edit-compile-debug cycle. It gives you a reasonable blend of optimization, fast compilation and a good debugging experience, especially for code with a high abstraction penalty. Unlike -O0, this enables -fvar-tracking-assignments and -fvar-tracking, which handle debug information in the prologue and epilogue of functions better than -O0 does.
Like -O0, -Og completely skips a number of optimization passes, so the individual options that control them have no effect. Otherwise, -Og enables all -O1 optimization flags except the ones known to greatly interfere with 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 🦋
Optimize aggressively for size rather than speed. 🗜️ This may increase the number of instructions executed if those instructions need fewer bytes to encode. -Oz behaves similarly to -Os, including enabling most -O2 optimizations.
If you use multiple -O options, with or without level numbers, the last one is the one that takes effect. Main character energy, the last one wins 👑.
Options of the form -fflag specify machine-independent flags. Most flags have both positive and negative forms, and the negative form of -ffoo is -fno-foo. In the list below, only one of the forms is listed, the one you typically use. You can figure out the other form by either removing no- or adding it. Easy peasy 🌈.
The following options control specific optimizations. They're either activated by -O options or related to ones that are. You can use these flags in the rare cases when "fine-tuning" of the optimizations to be performed is desired. Only touch these if you know what you're doing, bestie 🫶.
-fno-defer-pop— For machines that must pop arguments after a function call, this always pops the arguments as soon as each function returns. At levels-O1and higher,-fdefer-popis the default, which lets the compiler let arguments pile up on the stack for several function calls and then pop them all at once.-fforward-propagate— Runs 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 are performed and the second one is scheduled after loop unrolling.
This option is enabled by default at optimization levels -O1, -O2, -O3 and -Os.
-favoid-store-forwarding/-fno-avoid-store-forwarding— Lots of CPUs stall for many cycles when a load partially depends on previous smaller stores. This pass tries to spot those cases and dodge the penalty by changing the order of the load and store, then fixing up the loaded value. 🧠
Disabled by default.
-ffp-contract=style—-ffp-contract=offturns off 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 enables 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.
-ffp-int-builtin-inexact— Allows the built-in functions "ceil", "floor", "round" and "trunc", plus their "float" and "long double" variants, to generate code that raises the "inexact" floating-point exception for noninteger arguments. ISO C99 and C11 let these functions raise the "inexact" exception, but ISO/IEC TS 18661-1:2014, the C bindings to IEEE 754-2008 as integrated into ISO C23, does not. 🤓
The default is -fno-fp-int-builtin-inexact, which disallows the exception from being raised, unless C17 or an earlier C standard is selected. This option does nothing unless -ftrapping-math is in effect.
NOTE 🌷: Even if -fno-fp-int-builtin-inexact is used, if these functions generate a call to a library function, the "inexact" exception may still be raised if the library implementation doesn't follow TS 18661.
-fomit-frame-pointer— Omits the frame pointer in functions that don't need one. This 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 has no effect, because the standard calling sequence always uses a frame pointer, so it can't be omitted.
Note that -fno-omit-frame-pointer doesn't guarantee the frame pointer is used in all functions. Several targets always omit the frame pointer in leaf functions.
Enabled by default at -O1 and higher.
-foptimize-crc— okay bestie, this one is a CRC detective 🕵️♀️✨ It spots loops doing CRC math (that's polynomial long division, so fancy 🧮) and swaps them for a faster version 🚀 It recognizes 8, 16, 32, and 64 bit CRCs using a constant polynomial without the leading 1 bit, in both bit-forward and bit-reversed flavors 🦋 If the target has a CRC instruction and your polynomial matches it, it generates that instruction 💖 Otherwise, if the target has a carry-less-multiplication instruction, it uses that to make the CRC 🌸 and if neither is available, it falls back to a table-based CRC 🍓- Enabled by default at
-O2and higher. 👑
- Enabled by default at
-foptimize-sibling-calls— this one optimizes sibling and tail recursive calls, so your recursion stops wasting stack space 🧚- Enabled at levels
-O2,-O3,-Os.
- Enabled at levels
-foptimize-strlen— it glows up standard C string functions like"strlen","strchr", or"strcpy", plus their"_FORTIFY_SOURCE"counterparts, into faster alternatives 🏎️💨- Enabled at levels
-O2,-O3.
- Enabled at levels
-finline-atomics,-fno-inline-atomics— inlines__atomicoperations whenever a lock-free instruction sequence is available 🔒 This optimization is enabled by default. 💅-finline-stringops[=fn]— expands memory and string operations (for now, only"memset") inline, even when the length is variable or big enough to need looping 🧵 This is most useful alongside-ffreestandingand-fno-builtin.- In some circumstances it can take advantage of known alignment and length multipliers, but even then it might be less efficient than optimized runtime implementations 🙈 It can also bloat code size so much that a less performant but shared implementation ends up running faster, thanks to better use of code caches.
- This option is disabled by default. 🫶
-fno-inline— don't expand any functions inline unless they're marked with the"always_inline"attribute 🚫 This is the default when not optimizing.- You can exempt single functions from inlining by marking them with the
"noinline"attribute. 🦋
- You can exempt single functions from inlining by marking them with the
-finline-small-functions— integrates functions into their callers when their body is smaller than the function call code, so the whole program gets smaller 📉 The compiler heuristically decides which functions are simple enough for this, and it applies to all functions, even ones not declared inline ✨- Enabled at levels
-O2,-O3,-Os.
- Enabled at levels
-findirect-inlining— inlines indirect calls that are known at compile time thanks to previous inlining 🧠 This only does anything when inlining is turned on by-finline-functionsor-finline-small-functions.- Enabled at levels
-O2,-O3,-Os.
- Enabled at levels
-finline-functions— considers all functions for inlining, even ones not declared inline 💖 The compiler heuristically decides which are worth integrating.- If all calls to a given function get integrated, and the function is declared
"static", then it's normally not output as assembler code in its own right. 🎀 - Enabled at levels
-O2,-O3,-Os. Also enabled by-fprofile-useand-fauto-profile. 🔥
- If all calls to a given function get integrated, and the function is declared
-finline-functions-called-once— considers all"static"functions called once for inlining into their caller, even if they aren't marked"inline"🌈 If a call to a function gets integrated, the function isn't output as assembler code on its own either.- Enabled at levels
-O1,-O2,-O3and-Os, but not-Og.
- Enabled at levels
-fearly-inlining— inlines functions marked"always_inline", plus functions whose body seems smaller than the call overhead, early 🏃♀️ This happens before the-fprofile-generateinstrumentation and the real inlining pass. It makes profiling significantly cheaper and usually makes inlining faster on programs with large chains of nested wrapper functions 🧚- Enabled by default. ✨
-fipa-sra— performs interprocedural scalar replacement of aggregates, removes unused parameters, and swaps parameters passed by reference for parameters passed by value 🧩- Enabled at levels
-O2,-O3and-Os.
- Enabled at levels
-finline-limit=n— by default, GCC caps the size of functions it'll inline 📏 This flag gives you coarse control over that cap.nis the size of functions that can be inlined, measured in pseudo instructions.- Inlining is actually controlled by a bunch of internal parameters, which are documented in the GCC Internals manual and shouldn't normally be set directly 🙅♀️
- Note: there may be no value of
-finline-limitthat results in default behavior. 🤷♀️
Note: a pseudo instruction, in this particular context, is an abstract measurement of a function's size 💀 It in no way represents a count of assembly instructions, so its exact meaning might change from one release to another.
-fno-keep-inline-dllexport— this is a more fine-grained version of-fkeep-inline-functions, and it only applies to functions declared with the"dllexport"attribute or declspec 🎯-fkeep-inline-functions— in C, emits"static"functions declared"inline"into the object file, even if the function got inlined into all of its callers 🌸 This switch doesn't affect functions using the"extern inline"extension in GNU C90. In C++, it emits any and all inline functions into the object file 💜-fkeep-static-functions— emits"static"functions into the object file, even if they're never used 📦-fkeep-static-consts— emits variables declared"static const"when optimization isn't turned on, even if the variables aren't referenced 🍓- GCC enables this option by default. If you want the compiler to check whether a variable is referenced regardless of optimization, use
-fno-keep-static-consts. 🔍
- GCC enables this option by default. If you want the compiler to check whether a variable is referenced regardless of optimization, use
-fmerge-constants— tries to merge identical constants (string constants and floating-point constants) across compilation units 🧲- This option is the default for optimized compilation if the assembler and linker support it. Use
-fno-merge-constantsto inhibit this behavior. - Enabled at levels
-O1,-O2,-O3,-Os.
- This option is the default for optimized compilation if the assembler and linker support it. Use
-fmerge-all-constants— tries to merge identical constants and identical variables 👀 This option implies-fmerge-constants. On top of that, it considers things like even constant initialized arrays, or initialized constant variables with integral or floating-point types 🧁
⚠️ Bestie, listen: languages like C or C++ require each variable, including multiple instances of the same variable in recursive calls, to have distinct locations. Using this option results in non-conforming behavior 😭
-fmodulo-sched— performs swing modulo scheduling immediately before the first scheduling pass 🌀 It looks at innermost loops and reorders their instructions by overlapping different iterations.-fmodulo-sched-allow-regmoves— more aggressive SMS-based modulo scheduling, with register moves allowed 🚀 Setting this flag deletes certain anti-dependence edges, which triggers the generation of reg-moves based on life-range analysis. This option is only effective with-fmodulo-schedenabled.-fno-branch-count-reg— disables the optimization pass that scans for chances to use "decrement and branch" instructions on a count register, instead of instruction sequences that decrement a register, compare it against zero, and then branch based on the result 🔢 This is only meaningful on architectures that support such instructions, which include x86, PowerPC, IA-64 and S/390.- Note that
-fno-branch-count-regdoesn't remove the decrement and branch instructions introduced into the generated instruction stream by other optimization passes. - The default is
-fbranch-count-regat-O1and higher, except for-Og. 💅
- Note that
-fno-function-cse— doesn't put function addresses in registers 🙅♀️ Instead, each instruction that calls a constant function contains the function's address explicitly.- This results in less efficient code, but some strange hacks that alter the assembler output may get confused by the optimizations performed when this option isn't used 💀
- The default is
-ffunction-cse
-ffuse-ops-with-volatile-access— allows limited optimization of operations with volatile memory access when doing so does not change the semantics outlined in- The default is
-ffuse-ops-with-volatile-access🌈
- The default is
-fno-zero-initialized-in-bss— if the target supports a BSS section, GCC by default puts variables initialized to zero into BSS, which can save space in the resulting code 💾 This option turns that behavior off, because some programs explicitly rely on variables going to the data section---e.g., so the resulting executable can find the beginning of that section and/or make assumptions based on that 🧸- The default is
-fzero-initialized-in-bssexcept in Ada. 🎀
- The default is
-fthread-jumps— performs optimizations that check whether a jump branches to a location where another comparison subsumed by the first one is found 🦘 If so, the first branch is redirected to either the destination of the second branch or a point immediately following it, depending on whether the condition is known to be true or false.- Enabled at levels
-O1,-O2,-O3,-Os.
- Enabled at levels
-fsplit-wide-types— when using a type that occupies multiple registers, such as"long long"on a 32-bit system, the registers get split apart and allocated independently 🧠 This normally generates better code for those types, but may make debugging more difficult 🙈- Enabled at levels
-O1,-O2,-O3,-Os.
- Enabled at levels
-fsplit-wide-types-early— fully splits wide types early, instead of very late ⏰ This option has no effect unless-fsplit-wide-typesis turned on.- This is the default on some targets. ✨
-fcse-follow-jumps— in common subexpression elimination (CSE), it scans through jump instructions when the target of the jump isn't reached by any other path 👀 For example, when CSE encounters an"if"statement with an"else"clause, CSE follows the jump when the condition tested is false.- Enabled at levels
-O2,-O3,-Os. 🫶
- Enabled at levels
-fcse-skip-blocks— okay bestie, this is basically-fcse-follow-jumpsbut with more ✨ReACH✨ 🦋 It makes CSE follow jumps that conditionally skip over blocks. When CSE hits a simpleifwith noelseclause,-fcse-skip-blockstells it to follow the jump right around the body of theif. 💅
Enabled at levels -O2, -O3, -Os.
Wait, let me redo that properly, because I'm getting ahead of myself. Here it is in order:
✨ OPTIONS (continued) ✨
-fcse-skip-blocks— this is giving "follow the jump" energy 🦋 It's similar to-fcse-follow-jumps, but CSE also follows jumps that conditionally skip over blocks. When CSE runs into a simpleifwith noelseclause,-fcse-skip-blocksmakes it follow the jump around the body of theif. 💅
Enabled at levels -O2, -O3, -Os.
-frerun-cse-after-loop— okay so this one re-runs common subexpression elimination after the loop optimizations finish 🔁✨ main character re-run energy 💖
Enabled at levels -O2, -O3, -Os.
-fgcse— slay 💅 this performs a global common subexpression elimination pass, and it also does global constant and copy propagation. iconic behavior 👑
⚠️ Heads up, bestie: when you're compiling a program that uses computed gotos (a GCC extension 🙈), you might get better run-time performance if you disable the global CSE pass by adding -fno-gcse to the command line. no cap.
Enabled at levels -O2, -O3, -Os.
-fgcse-lm— lowkey my favourite of the GCSE crew 🌸 When it's enabled, global CSE tries to move loads that are only killed by stores into themselves. So a loop with a load/store sequence can become a load outside the loop and a copy/store inside the loop. 🧚
Enabled by default when -fgcse is enabled.
-fgcse-sm— store motion, babe 🦋 When it's enabled, a store motion pass runs after global CSE and tries to move stores out of loops. Used together with-fgcse-lm, a loop with a load/store sequence can turn into a load before the loop and a store after it. 🫶
Not enabled at any optimization level.
-fgcse-las— this one is so precious 🥹 It makes the global CSE pass eliminate redundant loads that come after stores to the same memory location (both partial and full redundancies). no notes 💜
Not enabled at any optimization level.
-fgcse-after-reload— clean-up crew vibes 🧹✨ When it's enabled, a redundant load elimination pass runs after reload. Its whole purpose is to tidy up redundant spilling.
Enabled by -O3, -fprofile-use and -fauto-profile.
-faggressive-loop-optimizations— the loop optimizer gets to use language constraints to work out bounds on how many iterations a loop does 🔥 It assumes loop code doesn't invoke undefined behavior, like causing signed integer overflows or out-of-bounds array accesses 😭 Those bounds then guide loop unrolling, peeling, and loop exit test optimizations. This option is enabled by default.-funconstrained-commons— this tells the compiler that variables declared in common blocks (for example, in Fortran) may later be overridden with longer trailing arrays. It prevents certain optimizations that depend on knowing the array bounds. 🎀-fcrossjumping— performs the cross-jumping transformation, which unifies equivalent code and saves code size 🍓 The resulting code may or may not perform better than without cross-jumping, so it's a mixed bag ngl.
Enabled at levels -O2, -O3, -Os.
-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.-fdce— performs dead code elimination (DCE) on RTL 🗑️💅 Enabled by default at-O1and higher.-fdse— performs dead store elimination (DSE) on RTL 🌈 Enabled by default at-O1and higher.-fif-conversion— attempts to transform conditional jumps into branch-less equivalents 🦋 This includes conditional moves, min, max, set flags and abs instructions, and some tricks doable 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.
-fif-conversion2— uses conditional execution (where available) to transform conditional jumps into branch-less equivalents 💖
Enabled at levels -O1, -O2, -O3, -Os, but not with -Og.
-fdeclone-ctor-dtor— okay so 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 two variants become thunks that call a common implementation. 🧚
Enabled by -Os.
-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 enables simple constant folding optimizations at all optimization levels. Other GCC passes use this flag to control global dataflow analyses that eliminate useless null pointer checks. These assume that a memory access to address zero always results in a trap, so if a pointer is checked after it has already been dereferenced, it can't be null.
⚠️ Careful, bestie: in some environments this assumption isn't true. Use -fno-delete-null-pointer-checks to disable this optimization for programs that depend on that behavior.
This option is enabled by default on most targets. On AVR and MSP430, this option is completely disabled.
Passes that use the dataflow information are enabled independently at different optimization levels.
-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.-fdevirtualize-speculatively— attempts to convert calls to virtual functions into speculative direct calls 🔮 Based on analysis of the type inheritance graph, it figures out the set of likely targets for a given call. If the set is small (preferably size 1), the call becomes a conditional that picks between a direct and an indirect call. The speculative calls enable 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 running the link-time optimizer in local transformation mode 📦 This enables more devirtualization but significantly increases the size of streamed data. For this reason it's disabled by default.-fexpensive-optimizations— performs a number of minor optimizations that are relatively expensive 💸
Enabled at levels -O2, -O3, -Os.
-fext-dce,-fno-ext-dce— performs dead code elimination on zero and sign extensions, using special dataflow analysis 🧼-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.
-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 during its lifetime are dead once it's destroyed. Normally dead store elimination takes advantage of this. If your code relies on the object storage's value persisting past the object's lifetime, use this flag to turn that optimization off. To keep stores made before the constructor starts (for example, because youroperator 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.-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 🎨 The algorithm argument can bepriority, which specifies Chow's priority coloring, orCB, which specifies Chaitin-Briggs coloring. Chaitin-Briggs coloring isn't implemented for all architectures, but on the targets that do support it, it's the default because it generates better code. ✨ - *
-fira-region=region* — picks the regions the integrated register allocator uses 🗺️ The region argument 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 set.mixed— 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 -Os for all targets.
-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 -O3 for some targets.
-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: bestie, this one is a hard pass 🙅♀️ It disables sharing of stack slots allocated for pseudo-registers 🧱 Every pseudo-register that doesn't get a hard register gets its very own stack slot, so function stack frames end up larger 📦💀-flra-remat: okay this one is giving main character energy ✨ It turns on CFG-sensitive rematerialization in LRA 🦋 Instead of loading values of spilled pseudos, LRA tries to rematerialize (recalculate) them whenever that's profitable 🧮 Enabled at levels-O2,-O3,-Os💅-fdelayed-branch: if the target machine supports it, GCC tries reordering instructions so they can use the instruction slots after delayed branch instructions 🧠 Enabled at levels-O1,-O2,-O3,-Os, but not at-Og🙅♀️-fschedule-insns: if the target supports it, GCC reorders instructions to get rid of execution stalls caused by required data being unavailable ⏳ This helps machines with slow floating point or memory load instructions, since other instructions can get issued while you wait for the load or float result to show up 🫶 It's conventionally enabled at-O2and-O3, but lowkey plenty of targets override that 😭 On x86 it's disabled at all levels, while on AArch64 it's only enabled at-O3🌸-fschedule-insns2: same main vibe as-fschedule-insns, but this one adds an extra pass of instruction scheduling after register allocation 🔁 It's 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✨-fno-sched-interblock: disables instruction scheduling across basic blocks 🚫 This is normally on 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 before register allocation, i.e. with-fschedule-insnsor at-O2or higher 🫧-fsched-pressure: turns on register pressure sensitive insn scheduling before register allocation 🧠 It only makes sense when scheduling before register allocation is enabled, i.e. with-fschedule-insnsor at-O2or higher 🎀 Using it can improve the generated code and shrink its size by stopping register pressure from climbing above the number of available hard registers, which would otherwise mean spills later in register allocation 🫠-fsched-spec-load: allows speculative motion of some load instructions 🔮 It only makes sense when scheduling before register allocation, i.e. with-fschedule-insnsor at-O2or higher 🌷-fsched-spec-load-dangerous: allows speculative motion of more load instructions ⚠️ The name is literally a warning label 💀 It only makes sense when scheduling before register allocation, i.e. with-fschedule-insnsor at-O2or higher 🙈-fsched-stalled-insns,-fsched-stalled-insns=n: this decides how many insns (if any!) can be moved prematurely from the queue of stalled insns into the ready list during the second scheduling pass 🚚-fno-sched-stalled-insnsmeans none get moved early,-fsched-stalled-insns=0means there's no limit on how many queued insns can be moved prematurely, and-fsched-stalled-insnswith no value is the same as-fsched-stalled-insns=1🧁-fsched-stalled-insns-dep,-fsched-stalled-insns-dep=n: defines how many insn groups (cycles) get checked for a dependency on a stalled insn that's a candidate for premature removal from the queue of stalled insns 🔍 This only has an effect during the second scheduling pass, and only if-fsched-stalled-insnsis used 🫶-fno-sched-stalled-insns-depis equivalent to-fsched-stalled-insns-dep=0, and-fsched-stalled-insns-depwithout a value is equivalent to-fsched-stalled-insns-dep=1💖-fsched2-use-superblocks: when scheduling after register allocation, this uses superblock scheduling 🧩 That allows motion across basic block boundaries, which gives faster schedules ⚡ Heads up, though: this one is experimental, because not all machine descriptions model the CPU closely enough to avoid unreliable results from the algorithm 🥺 It only makes sense after register allocation, i.e. with-fschedule-insns2or at-O2or higher 💅-fsched-group-heuristic: enables the group heuristic in the scheduler 🧑🤝🧑 It favors the instruction that belongs to a schedule group 🎀 This is enabled by default when scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher 🌈-fsched-critical-path-heuristic: enables the critical-path heuristic in the scheduler 🛤️ It favors instructions on the critical path 👑 This is enabled by default when scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher ⭐-fsched-spec-insn-heuristic: enables the speculative instruction heuristic 🔮 It favors speculative instructions with greater dependency weakness 🦋 This is enabled by default when scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher 🫶-fsched-rank-heuristic: enables the rank heuristic 🏆 It favors the instruction belonging to a basic block with greater size or frequency 📈 This is enabled by default when 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 🧃 This is enabled 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 🧮 It favors the instruction that has more instructions depending on it 🫂 This is enabled by default when scheduling is enabled, i.e. with-fschedule-insnsor-fschedule-insns2or at-O2or higher ✨-fspeculatively-call-stored-functions: GCC attempts to convert indirect calls of function pointers into calls through pointers loaded from a structure field, but only if all visible stores to that field store just a single candidate 🎲 When it works, the call becomes a conditional that picks between the direct call and the original indirect one 🧠 These speculative calls often enable more optimizations, such as inlining 🚀 And if they seem useless after further optimization, they get converted back into their original form 🔄-freschedule-modulo-scheduled-loops: modulo scheduling is performed before traditional scheduling 🔁 If a loop is modulo scheduled, later scheduling passes may change its schedule, and this option is how you control that behavior 🎛️-fselective-scheduling: schedules instructions using the selective scheduling algorithm 🎯 Selective scheduling runs instead of the first scheduler pass 🫶-fselective-scheduling2: same energy, schedules instructions with the selective scheduling algorithm, but this one runs instead of the second scheduler pass 🥰-fsel-sched-pipelining: enables software pipelining of innermost loops during selective scheduling 🌀 This option has no effect unless-fselective-schedulingor-fselective-scheduling2is turned on 🙈-fsel-sched-pipelining-outer-loops: when pipelining loops during selective scheduling, this also pipelines outer loops 🪆 It has no effect unless-fsel-sched-pipeliningis turned on 🫠-fsemantic-interposition: okay this one is a lot 🫠 Some object formats, like ELF, allow the dynamic linker to interpose symbols 🔀 That means for symbols exported from the DSO, the compiler can't do interprocedural propagation, inlining, or other optimizations, because it has to assume the function or variable in question might get swapped out 😵 This is useful for things like rewriting memory allocation functions with a debugging implementation, but it's expensive in terms of 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) 🧸 Similarly, if interposition happens for variables, the constructor of the variable will be the same 🎀 The flag has no effect for functions explicitly declaredinline(where interposition is never allowed to change semantics), and 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 🎁 This flag is enabled by default at-Oand higher ✨-fshrink-wrap-separate: shrink-wraps separate parts of the prologue and epilogue separately, so those parts only run when they're needed 🌙 This option is on by default, but has no effect unless-fshrink-wrapis also turned on and the target supports this 🦋-fcaller-saves: enables allocating values to registers that get clobbered by function calls, by emitting extra instructions to save and restore those registers around such calls 🧺 This allocation only happens when it seems to result in better code 💅 This option is always enabled by default on certain machines, usually the ones with no 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 🧑🍳 In that case, there's no need to save and restore them 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 📚 Enabled at levels-O2,-O3,-Os, however the option is disabled if the generated code will be instrumented for profiling (-p, or-pg) or if the callee's register usage can't be known exactly (this happens on targets that don't expose prologues and epilogues in RTL) 🙃-fconserve-stack: minimizes stack usage 🥹 The compiler tries to use less stack space, even if that makes the program slower 🐢 This option implies setting thelarge-stack-frameparameter to100and thelarge-stack-frame-growthparameter to400💜-ftree-reassoc— okay so this one does reassociation on trees 🦋 It's switched on by default at-O1and higher ✨-fcode-hoisting— code hoisting, bestie 🫶 It tries to move the evaluation of expressions that run 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 💅 On by default at-O2and higher.-ftree-pre— partial redundancy elimination (PRE) on trees 🌸 Enabled by default at-O2and-O3.-ftree-partial-pre— makes PRE more aggressive 🔥 Enabled by default at-O3.-ftree-forwprop— forward propagation on trees 🧚 On by default at-O1and higher.-ftree-fre— full redundancy elimination (FRE) on trees 💖 The tea is that FRE only considers expressions computed on all paths leading to the redundant computation, while PRE is the bigger, messier sibling. FRE's analysis is faster than PRE, though it exposes fewer redundancies. On by default at-O1and higher.-ftree-phiprop— hoists 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 come from adjacent locations in the same structure and the target architecture has a conditional move instruction 🎀 On by default at-O2and higher.-ftree-copy-prop— copy propagation on trees 🦋 This pass gets rid of unnecessary copy operations. On by default at-O1and higher.-fipa-pure-const— figures out which functions are pure or constant 🔮 Enabled by default at-O1and higher.-fipa-reference— finds which static variables do not escape the compilation unit 👀 Enabled by default at-O1and higher.-fipa-reference-addressable— finds read-only, write-only and non-addressable static variables 💅 Enabled by default at-O1and higher.-fipa-reorder-for-locality— groups call chains close together in the binary layout 🧚 The goal is better code locality and shorter jump distances between frequently called functions. Unlike-freorder-functions, this pass looks at the call chains between functions and groups them together, instead of putting all hot/normal/cold/never-executed functions into separate sections. Unlike-fprofile-reorder-functions, it aims to improve code locality throughout the runtime of the program rather than focusing on program startup.
This option is incompatible with an explicit -flto-partition= option, since it enforces a custom partitioning scheme.
If you use this option, it's recommended to also use profile feedback, but this option is not enabled by default otherwise 🙈
-fipa-stack-alignment— reduces stack alignment on call sites if possible 🌈 Enabled by default.-fipa-pta— interprocedural pointer analysis and interprocedural modification and reference analysis 🧠
This one can cause excessive memory and compile-time usage on large compilation units, so be careful, bestie 💀 It is not enabled by default at any optimization level.
-fipa-profile— interprocedural profile propagation 📈 Functions called only from cold functions are marked as cold. Functions executed once (such as "cold", "noreturn", static constructors or destructors) are identified too. Cold functions and loop less parts of functions executed once are then optimized for size. Enabled by default at-O1and higher.-fipa-modref— interprocedural mod/ref analysis 🦋 This optimization analyzes the side effects of functions (memory locations that are modified or referenced), which lets the compiler optimize better across the function call boundary. On by default at-O1and higher.-fipa-cp— interprocedural constant propagation 👑 This optimization analyzes the program to figure out when values passed to functions are constants, then optimizes accordingly. It can substantially increase performance if your app passes constants to functions. Enabled by default at-O2,-Osand-O3. It's also enabled by-fprofile-useand-fauto-profile.-fipa-cp-clone— function cloning to make interprocedural constant propagation stronger 🍓 When enabled, interprocedural constant propagation clones a function when an externally visible function can be called with constant arguments.
Because this optimization can create multiple copies of functions, it may significantly increase code size 😭 Enabled by default at-O3. It's also enabled by-fprofile-useand-fauto-profile.
-fipa-bit-cp— interprocedural bitwise constant propagation 💜 When enabled, it does the bitwise version of the constant propagation. Enabled by default at-O2, and by-fprofile-useand-fauto-profile. It requires that-fipa-cpis enabled.-fipa-vrp— interprocedural propagation of value ranges 🌸 When enabled, it propagates value ranges across functions. Enabled by default at-O2. It requires that-fipa-cpis enabled.-fipa-icf-functions,-fipa-icf-variables,-fipa-icf— Identical Code Folding 🧚-fipa-icf-functionsdoes it for functions,-fipa-icf-variablesdoes it for read-only variables, and-fipa-icfdoes both. This reduces code size, but it may disturb unwind stacks by swapping a function out for an equivalent one with a different name. It works even better with link-time optimization enabled ✨
Although the behavior is similar to the Gold Linker's ICF optimization, GCC ICF works on different levels, so the optimizations are not the same. There are equivalences that only GCC finds and equivalences that only Gold finds 🦋
-fipa-icf is enabled by default at -O2 and -Os.
-flate-combine-instructions— turns on two instruction combination passes that run pretty late in the compilation process 🔥 One runs before register allocation and the other runs after it. The main goal is to substitute definitions into all their uses. Most targets enable this flag by default at-O2and-Os.-flive-patching=level— controls GCC's optimizations so the output is suitable for live-patching 🩹 Here's the deal: if an optimization uses a function's body (or info pulled from it) to change another function, that other function is called an impacted function. If a function gets patched, its impacted functions should be patched too. The impacted functions are determined by the compiler's interprocedural optimizations. For example, a caller is impacted when a function gets inlined into it, when a function is cloned and its caller is changed to call the clone, or when a function's pureness/constness info is extracted to optimize its direct or indirect callers. Usually, the more IPA optimizations are on, the more impacted functions each function has. So IPA optimizations can be partially enabled at two different levels, which keeps the list manageable 🧮
The level argument should be one of the following:
inline-clone— only inlining and cloning optimizations are enabled, which includes inlining, cloning, interprocedural scalar replacement of aggregates and partial inlining. So when patching a function, all its callers and its clones' callers are impacted, and they need to be patched too.
-flive-patching=inline-clone disables the following 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 patching a static function, all its callers are impacted and need to be patched too.
On top of everything -flive-patching=inline-clone disables, -flive-patching=inline-only-static also disables these: -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.
Note that-flive-patchingis not supported with link-time optimization (-flto) ⚠️
-fisolate-erroneous-paths-dereference— detects paths that trigger erroneous or undefined behavior from dereferencing a null pointer (with-fdelete-null-pointer-checksenabled) or from a division by zero 🚧 It isolates those paths from the main control flow and turns the statement with erroneous or undefined behavior into a trap. On by default at-O2and higher.-fisolate-erroneous-paths-attribute— detects paths that trigger erroneous or undefined behavior because a null value is used in a way forbidden by a "returns_nonnull" or "nonnull" attribute 🙅 It isolates those paths from the main control flow and turns the statement into a trap.
This is not currently enabled, but it may be enabled by -O2 in the future 👀
-ftree-sink— forward store motion on trees 🦋 On by default at-O1and higher.-ftree-bit-ccp— sparse conditional bit constant propagation on trees, plus pointer alignment info propagation 🎀 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 💖 This pass only operates on local scalar variables. Enabled by default at-O1and higher.-fssa-backprop— propagates info about uses of a value up the definition chain to simplify the definitions 🧹 For example, this pass strips sign operations if the sign of a value never matters. Enabled by default at-O1and higher.
Okay bestie, let's keep going 💅✨ These are the tree-level passes doing the behind-the-scenes cleanup, and they are giving main character energy 🦋
-fssa-phiopt— pattern matching on SSA PHI nodes to tidy up conditional code 🧚 It's on by default at-O1and higher, except for-Og💖-ftree-switch-conversion— turns simple initializations inside a switch into initializations from a scalar array 🎀 On by default at-O2and higher.-ftree-tail-merge— hunts down identical chunks of code and, when it finds them, swaps one for a jump to the other 🦋 This is known as tail merging or cross jumping. On by default at-O2and higher. You can cap how long this pass takes with themax-tail-merge-comparisonsparameter and themax-tail-merge-iterationsparameter 🙈-ftree-cselim— conditional store elimination on trees 💜 On by default at-O1and higher, but only on targets that have conditional move instructions.-ftree-dce— dead code elimination (DCE) on trees 💀 On by default at-O1and higher.-ftree-builtin-call-dce— conditional DCE for calls to built-in functions that may set"errno"but are otherwise free of side effects 🌸 On by default at-O2and higher, as long as-Osisn't also specified.-ffinite-loops— assumes a loop with an exit will eventually take that exit instead of spinning forever 🌈 This lets the compiler remove loops that have no side effects, since it isn't worrying about endless looping. It's on by default at-O2for C++ with-std=c++11or 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, which reduces jumps to jumps. On 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. In that case the earlier store can be deleted. On by default at-O1and higher.-ftree-ch— loop header copying on trees 👑 This helps code motion optimizations work better and saves one jump. On by default at-O1and higher, but not for-Os, since it usually bumps up code size.-ftree-loop-optimize— loop optimizations on trees 🔁 On by default at-O1and higher.-ftree-loop-linear,-floop-strip-mine,-floop-block— loop nest optimizations, same as-floop-nest-optimize🧚 To use this transformation, GCC has to be configured with--with-islso the Graphite loop transformation infrastructure is enabled.-fgraphite-identity— enables the identity transformation for graphite 🪞 For every SCoP, GCC builds the polyhedral representation and transforms it back to gimple. With-fgraphite-identityyou can check the costs or benefits of the GIMPLE -> GRAPHITE -> GIMPLE round trip. The isl code generator also does some minimal optimizations, like index splitting and dead code elimination in loops.-floop-nest-optimize— turns on the isl based loop nest optimizer 💅 It's a generic one built on the Pluto optimization algorithms, and it works out a loop structure tuned for data-locality and parallelism.
⚠️ This option is experimental, so handle it with care bestie 🙈
-floop-parallelize-all— uses Graphite data dependence analysis to find loops that can be parallelized 🧵 It parallelizes every loop that can be analyzed as having no loop carried dependences, without checking whether parallelizing is actually profitable.-ftree-coalesce-vars— when the program is transformed out of SSA representation, this tries to reduce copying by coalescing versions of different user-defined variables, not just compiler temporaries 🫶 In the negated form, this flag prevents SSA coalescing of user variables. It's on by default if optimization is enabled, and it does very little otherwise.
⚠️ This may severely limit your ability to debug an optimized program compiled with -fno-var-tracking-assignments 😭
-ftree-loop-if-convert— transforms conditional jumps in the innermost loops into branch-less equivalents 🌙 The goal is to strip control flow out of those loops so the vectorization pass can handle them better. It's on by default if vectorization is enabled.-ftree-loop-distribution— loop distribution 🍓 This can improve cache performance on big loop bodies and lets further loop optimizations, like parallelization or vectorization, take place. For example, this loop:
DO I = 1, N
A(I) = B(I) + C
D(I) = E(I) * F
ENDDOgets split into this:
DO I = 1, N
A(I) = B(I) + C
ENDDO
DO I = 1, N
D(I) = E(I) * F
ENDDOOn by default at -O3. It's also enabled by -fprofile-use and -fauto-profile 💖
-ftree-loop-distribute-patterns— distributes loops that can be code generated as calls to a library 🧸 On by default at-O2and higher, and also enabled by-fprofile-useand-fauto-profile.
This pass distributes the initialization loops and generates a call to memset zero. For example, this loop:
DO I = 1, N
A(I) = 0
B(I) = A(I) + I
ENDDObecomes this:
DO I = 1, N
A(I) = 0
ENDDO
DO I = 1, N
B(I) = A(I) + I
ENDDOand the initialization loop turns into a call to memset zero 🌈
-floop-interchange— loop interchange, done outside of graphite 🔄 This can improve cache performance on loop nests and lets further loop optimizations, like vectorization, happen. For example, this C loop:
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];gets transformed into this:
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];On by default at -O3. It's also enabled by -fprofile-use and -fauto-profile 🫧
-floop-unroll-and-jam— applies unroll and jam transformations to feasible loops 🫧 In a loop nest, this unrolls the outer loop by some factor and fuses the resulting multiple inner loops. On by default at-O3, and also enabled by-fprofile-useand-fauto-profile.-ftree-loop-im— loop invariant motion on trees 🧲 This only moves the invariants that are hard to handle at RTL level, like function calls or operations that expand into nontrivial sequences of insns. With-funswitch-loops, it also moves operands of invariant conditions out of the loop, so loop unswitching can rely on 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 that count out needs complicated analysis 🔢 Later optimizations can then find the number easily. It's especially useful together with unrolling.-ftree-scev-cprop— final value replacement ✨ If a variable changes in a loop in a way that its value on exit can be worked out from just its initial value and the number of loop iterations, uses of the final value get replaced with that computation, as long as it's cheap enough. This reduces data dependencies and may allow more simplifications. On by default at-O1and higher.-fivopts— induction variable optimizations on trees 💜 That's strength reduction, induction variable merging and induction variable elimination. On by default at-O1and higher.-ftree-parallelize-loops,-ftree-parallelize-loops=n— parallelizes loops by splitting their iteration space to run in multiple threads 🧵 This only works for loops whose iterations are independent and can be arbitrarily reordered. It's only worth it on multiprocessor machines, for CPU-intensive loops rather than ones held back by something like memory bandwidth. This option implies-pthread, so it's only supported on targets that support-pthread.- With a positive value
n, the number of threads is fixed at compile time and can't be changed after compilation. The compiler generates#pragma omp parallel num_threads(n). - Without
=n(just-ftree-parallelize-loops), the number of threads is decided at program execution time through theOMP_NUM_THREADSenvironment variable. IfOMP_NUM_THREADSisn't set, the OpenMP runtime auto-detects the number of available processors and uses that value. This lets you make binaries that adapt to different hardware without recompiling 🌸
- With a positive value
-ftree-pta— function-local points-to analysis on trees 🎯 On by default at-O1and higher, except for-Og.-ftree-sra— scalar replacement of aggregates 🍬 This swaps structure references for scalars so structs don't get committed to memory too early. On by default at-O1and higher, except for-Og.-fstore-merging— merges narrow stores to consecutive memory addresses 📦 It takes contiguous stores of immediate values that are narrower than a word and merges them into fewer, wider stores to cut down on instructions. On by default at-O2and higher, as well as-Os🫶-ftree-ter— okay bestie, this one does temporary expression replacement during theSSA->normalphase 💅 Single use/single def temporaries get swapped out at their use location for their defining expression ✨ It leaves you with non-GIMPLE code, but the expanders get way more complex trees to work with, which means better RTL generation 🧚 It's on by default at-O1and higher 🌸-ftree-slsr— this is giving straight-line strength reduction on trees 🔥 It spots related expressions involving multiplications and swaps them for cheaper calculations when it can 💖 Enabled by default at-O1and higher ✨-ftree-vectorize— vectorization on trees 🦋 This flag also turns on-ftree-loop-vectorizeand-ftree-slp-vectorize, as long as you haven't explicitly specified them 💜-ftree-loop-vectorize— loop vectorization on trees 🌈 It's on by default at-O2, and it also gets switched on by-ftree-vectorize,-fprofile-use, and-fauto-profile🫶-ftree-slp-vectorize— basic block vectorization on trees 🎀 On by default at-O2, and also enabled by-ftree-vectorize,-fprofile-use, and-fauto-profile💅-ftrivial-auto-var-init=choice— main character energy alert 🚨 This one initializes automatic variables and temporary objects with either a pattern or zeroes, which boosts security and predictability by stopping uninitialized memory from being leaked or used 🛡️ GCC still treats an automatic variable with no explicit initializer as uninitialized, so-Wuninitializedand-Wanalyzer-use-of-uninitialized-valuewill still warn about those, and the compiler will still optimize as if the variable were uninitialized 👀 With this flag on, GCC also zeroes any padding in automatic variables or temporaries that have structure or union types 🧸 Heads up: the current implementation can't initialize automatic variables whose initialization gets bypassed through aswitchorgotostatement 😭 Use-Wtrivial-auto-var-initto report all such cases 🔍- The three values of choice are:
uninitialized— doesn't initialize any automatic variables 🙅pattern— initializes automatic variables with values that will likely turn logic bugs into crashes down the line 💥 They're easy to recognize in a crash dump 🔎 and they aren't values programmers can rely on for useful program semantics 🚫 The current value is a byte-repeatable pattern with byte0xFE, and the values used for pattern initialization might be changed in the future 🔮zero— initializes automatic variables with zeroes 🍓
- The default is
uninitializedexcept for C++26. In C++26, if-ftrivial-auto-var-init=isn't specified at all, automatic variables and temporary objects are zero initialized, but zero initialization of padding bits does not happen 🧸 - Quick note: the initializer values, whether zero or pattern, refer to the data representation (in memory or machine registers), not to their interpretation as numerical values 🤓 This distinction can matter in languages that support types with biases or implicit multipliers, and with extensions like 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
0x00or0xFE, depending on the choice, whether or not those representations stand for values in that range. Even if they do, the interpretation of the value held by the variable depends on the bias 🎯 - A hardbool variable that uses, say,
0x5Aand0xA5for "false" and "true", respectively, will trap with either choice of trivial initializer. That means zero initialization won't convert to the representation for "false", even if it would for astaticvariable of the same type 💀 So 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 for a specific variable with the
uninitializedvariable attribute (the standard attribute) or C++26's[[indeterminate]]🎯
- The three values of choice are:
-fvect-cost-model=model— tweaks the cost model used for vectorization 💜 Themodelargument should be one ofunlimited,dynamic,cheap, orvery-cheap:unlimited— the vectorized code path is assumed to be profitable 💪dynamic— a runtime check guards the vectorized code path, so it only gets enabled for iteration counts that will likely run faster than the original scalar loop 🏃♀️cheap— disables vectorization of loops where doing so would be cost prohibitive, for example because of required runtime checks for data dependence or alignment. Otherwise it's equal todynamic🪙very-cheap— disables vectorization of loops whenever any runtime check for data dependence or alignment is required. It also disables vectorization of epilogue loops, but otherwise it's equal tocheap🧃- The default cost model depends on other optimization flags and is either
dynamicorcheap🌸
-fsimd-cost-model=model— same vibe, but for loops marked with the OpenMPsimddirective 🎀 Themodelargument should be one ofunlimited,dynamic, orcheap. All values ofmodelhave the same meaning as described in-fvect-cost-model, and by default the cost model defined with-fvect-cost-modelis used 🫶-ftree-vrp— Value Range Propagation on trees 📈 It's similar to the constant propagation pass, but instead of values, ranges of values get propagated 💅 That lets the optimizers remove unnecessary range checks, like array bound checks and null pointer checks 🗑️ Enabled by default at-O2and higher 🔥 Null pointer check elimination only happens if-fdelete-null-pointer-checksis enabled 🙈-fsplit-paths— splits paths leading to loop backedges ✂️ This can improve dead code elimination and common subexpression elimination 🧹 Enabled by default at-O3and above 💖-fsplit-ivs-in-unroller— lets values of induction variables in later iterations of an unrolled loop be expressed using the value from the first iteration 🧠 That breaks long dependency chains, which improves the efficiency of the scheduling passes ⚡- A combination of
-fweband CSE is often enough to get the same effect 🤏 But that's not reliable when the loop body is more complicated than a single basic block 😬 It also doesn't work at all on some architectures, due to restrictions in the CSE pass 🚫 - This optimization is enabled by default ✨
- A combination of
-fvariable-expansion-in-unroller— when unrolling a loop, the compiler creates multiple copies of some local variables, which can result in superior code 💎 Enabled by default for PowerPC targets, but disabled by default otherwise 🦚-fpartial-inlining— inlines parts of functions 🧩 This option only has an effect when inlining itself is turned on by-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) performed in previous loop iterations 🔁 Enabled at level-O3, and also by-fprofile-useand-fauto-profile💜-fprefetch-loop-arrays— if the target machine supports it, generates instructions to prefetch memory, which can improve the performance of loops that access large arrays 🏎️ This may generate better or worse code, since results are highly dependent on the structure of loops in the source code 🤷 Disabled at level-Os😴-fno-printf-return-value— don't substitute constants for the known return values of formatted output functions like"sprintf","snprintf","vsprintf", and"vsnprintf"(but not"printf"or"fprintf") 🙅♀️ This lets GCC optimize or even eliminate branches based on the known return value of these functions, when they're called with arguments that are constant, or whose values are known to be in a range that makes the exact return value possible to determine 🧮 For example, when-fprintf-return-valueis in effect, both the branch and the body of theifstatement (but not the call tosnprint) can be optimized away wheniis 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 yields the best results with -O2 and above 🏆 It works in tandem with -Wformat-overflow and -Wformat-truncation 🤝 The -fprintf-return-value option is enabled by default ✨
-fno-peephole,-fno-peephole2— disables any machine-specific peephole optimizations 🧼 The difference between-fno-peepholeand-fno-peephole2is in how they're implemented in the compiler. Some targets use one, some use the other, and a few use both 🤓-fpeepholeis enabled by default 💅-fpeephole2is enabled at levels-O2,-O3,-Os🌸
-fno-guess-branch-probability— don't 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, the heuristics are used to guess the rest of the control flow graph, taking the__builtin_expectinfo into account 🧠 The interactions between the heuristics and__builtin_expectcan get complex, so in some cases it's useful to disable the heuristics, making the effects of__builtin_expecteasier to understand 🫠- It's also possible to specify the expected probability of an expression with the
__builtin_expect_with_probabilitybuilt-in function 🎯 - The default is
-fguess-branch-probabilityat levels-O,-O2,-O3,-Os💖
- It's also possible to specify the expected probability of an expression with the
-freorder-blocks— reorders basic blocks in the compiled function to reduce the number of taken branches and improve code locality 🦋
Okay so this one is enabled at -O1, -O2, -O3, and -Os 💅✨
-freorder-blocks-algorithm=algorithm 🦋
Tells the compiler which algorithm to use when it shuffles basic blocks around. You can pick simple, which doesn't bloat your code size (though sometimes alignment side effects can nudge it a bit 🙈), or stc, the "software trace cache" algorithm. stc groups all the frequently run code together so fewer branches get executed, but it does it by making extra copies of code, so it's giving bigger binary energy 🍓
The default is simple at -O1 and -Os, and stc at -O2 and -O3.
-freorder-blocks-and-partition 🌸
On top of reordering basic blocks inside each compiled function (to cut down on taken branches), this one splits hot and cold blocks into separate sections in the assembly and .o files. The result is better paging and cache locality, which is a whole vibe 🧚
This optimization gets turned off automatically in a few situations: when exception handling or unwind tables are present (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. If you're using -fsplit-stack, it's not enabled by default (to avoid linker errors), but you can turn it on explicitly if your linker actually works 💀
Enabled for x86 at -O2, -O3, and -Os.
-freorder-functions 👑
Reorders functions in the object file to improve code locality. Unlike -fipa-reorder-for-locality, this one prioritizes grouping every function in a category (hot, normal, cold, or never-executed) together. It does this with special subsections: .text.hot for the most frequently executed functions and .text.unlikely for the ones that are unlikely to run. The linker does the actual reordering, so your object file format needs to support named sections, and the linker has to place them sensibly ✨
This option doesn't do anything unless you either provide profile feedback (see -fprofile-arcs for details) or manually annotate functions with hot or cold attributes. No profile, no annotations, no glow-up 🥀
Enabled at levels -O2, -O3, and -Os.
-fstrict-aliasing 💖
This lets the compiler assume the strictest aliasing rules that apply to the language being compiled. For C (and C++), that turns on optimizations based on the type of expressions. Specifically, accessing an object of one type through an expression of a different type is not allowed, unless the types are compatible, differ only in signedness or qualifiers, or the expression has a character type. Accessing scalar objects through a corresponding vector type is also allowed.
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 you most recently wrote to (called "type-punning") is super common. Even with -fstrict-aliasing, type-punning is allowed in C, as long as the memory is accessed through the union type. In ISO C++, type-punning through a union type is undefined behavior, but GCC supports it as an extension, 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;
}Same energy goes for accessing something by taking its address, casting the resulting pointer, and dereferencing it. That 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;
}⚠️ Heads up bestie: all of the above is undefined behavior territory in some cases, so be careful with your pointers 😭
The -fstrict-aliasing option is enabled at levels -O2, -O3, and -Os.
-fipa-strict-aliasing 🔥
Controls whether the rules of -fstrict-aliasing get applied across function boundaries. Fun fact: 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, but it only does anything in combination with -fstrict-aliasing.
-falign-functions 🎀
Aligns the start of functions to the next power-of-two greater than or equal to n, skipping up to m-1 bytes. This makes sure 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 is ignored for functions considered cold. If you need alignment for every single function, use -fmin-function-alignment instead 🫶
The forms you can use are:
-falign-functions
-falign-functions=n
-falign-functions=n:m
-falign-functions=n:m:n2
-falign-functions=n:m:n2:m2If m isn't specified, it defaults to n.
Examples: -falign-functions=32 aligns functions to the next 32-byte boundary. -falign-functions=24 aligns to the next 32-byte boundary only if that can be done by skipping 23 bytes or less. -falign-functions=32:7 aligns to the next 32-byte boundary only if that can be done by skipping 6 bytes or less.
The second pair, n2:m2, lets you set a secondary alignment. -falign-functions=64:7:32:3 aligns to the next 64-byte boundary if that can be done by skipping 6 bytes or less, and otherwise 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-functions and -falign-functions=1 are equivalent, and both mean that functions are not aligned.
If n isn't specified or is zero, the compiler uses a machine-dependent default. The maximum allowed n value is 65536.
Enabled at levels -O2 and -O3.
-flimit-function-alignment 🦋
When this is enabled, the compiler tries not to overalign functions for no reason. It asks the assembler to align by the amount specified by -falign-functions, but it won't skip more bytes than the size of the function itself 🙅♀️
-falign-labels 🌈
Aligns all branch targets to a power-of-two boundary.
The parameters for this option work the same way as they do for -falign-functions. -fno-align-labels and -falign-labels=1 are equivalent and both mean labels are not aligned.
The forms you can use are:
-falign-labels
-falign-labels=n
-falign-labels=n:m
-falign-labels=n:m:n2
-falign-labels=n:m:n2:m2If -falign-loops or -falign-jumps apply and are greater than this value, their values are used instead.
If n isn't specified or is zero, the compiler uses a machine-dependent default, which is very likely to be 1, meaning no alignment. The maximum allowed n value is 65536.
Enabled at levels -O2 and -O3.
-falign-loops 🍓
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-labels is greater than this value, its value is used instead.
The parameters work like -falign-functions. -fno-align-loops and -falign-loops=1 are equivalent and both mean loops are not aligned. The maximum allowed n value is 65536.
The forms you can use are:
-falign-loops
-falign-loops=n
-falign-loops=n:m
-falign-loops=n:m:n2
-falign-loops=n:m:n2:m2If n isn't specified or is zero, the compiler uses a machine-dependent default.
Enabled at levels -O2 and -O3.
-falign-jumps 🧚
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 run. It's a code performance optimization, and alignment is ignored for jumps considered cold.
If -falign-labels is greater than this value, its value is used instead.
The parameters work like -falign-functions. -fno-align-jumps and -falign-jumps=1 are equivalent and both mean loops are not aligned (yes, the original says loops, it's a lil mix-up 🙈). The maximum allowed n value is 65536.
The forms you can use are:
-falign-jumps
-falign-jumps=n
-falign-jumps=n:m
-falign-jumps=n:m:n2
-falign-jumps=n:m:n2:m2If n isn't specified or is zero, the compiler uses a machine-dependent default.
Enabled at levels -O2 and -O3.
-fmin-function-alignment 💜
Specifies the minimal alignment of functions to the next power-of-two greater than or equal to n. Unlike -falign-functions, this alignment gets applied to all functions, even the ones considered cold. It's also not affected by -flimit-function-alignment 👑
-fno-allocation-dce ✨
Stops the compiler from removing unused C++ allocations (the ones using operator "new" and operator "delete") during dead code elimination. So those allocations stay put 🫶
See also -fmalloc-dce.
-fallow-store-data-races ⭐
Lets the compiler do optimizations that might introduce new data races on stores, without proving that the variable can't be accessed by other threads at the same time. It doesn't affect optimization of local data. It's safe to use this if you know global data won't be accessed by multiple threads 🧵
Examples of optimizations this enables include hoisting, or if-conversions that might cause a value already in memory to be rewritten with that same value. That rewrite is safe in a single-threaded context but can be unsafe in a multi-threaded one. Also, on some processors, if-conversions may be required before vectorization can happen.
⚠️ Only use this if global data is single-threaded, otherwise you're playing with fire 🔥
Enabled at level -Ofast.
-funit-at-a-time 🌸
This one is only here for compatibility reasons. -funit-at-a-time has no effect, but -fno-unit-at-a-time implies -fno-toplevel-reorder and -fno-section-anchors 🙃
Enabled by default.
-fno-toplevel-reorder 💅
Stops the compiler from reordering top-level functions, variables, and asm statements. It outputs them in the same order they appear in the input file. When this is used, unreferenced static variables are not removed. This option exists to support existing code that relies on a specific ordering. For new code, it's better to use attributes whenever you can 🎀
-ftoplevel-reorder is the default at -O1 and higher 💅, and at -O0 too if you explicitly ask for -fsection-anchors 🦋. Also, -fno-toplevel-reorder implies -fno-section-anchors 🙈.
-funreachable-traps— okay so this one is a whole vibe 💀. With it on, the compiler turns calls to__builtin_unreachableinto traps instead of using them for optimization. It also hits any of those calls the compiler generates on its own 🧚.
This is the same as -fsanitize=unreachable -fsanitize-trap=unreachable, but it doesn't change the values of those options 🫶. If -fsanitize=unreachable is enabled, that one takes priority over this one 👑. It's enabled by default at -O0 and -Og ✨.
-fweb— this builds webs for register allocation and gives each web its own pseudo register 🧠. That lets the register allocation pass work on pseudos directly and also boosts 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" 😭. It's enabled by default with-funroll-loops.-fwhole-program— you're basically telling the compiler "this compilation unit is the whole program" 👑. All public functions and variables become static, exceptmainand anything merged by attributeexternally_visible, so the interprocedural optimizers can go hard 💜.
With -flto, this one has limited use 🥺. Usually the linker plugin already knows the precise list of symbols used or exported from the binary, from the resolution info the linker passes to the link-time optimizer. It's still useful if no linker plugin is used, or during the incremental link step when final code is produced (with -flto -flinker-output=nolto-rel).
-flto[=n]
Okay, the link-time optimizer is literally so iconic 🦋. This option runs the standard link-time optimizer. When you invoke it with source code, it generates GIMPLE (one of GCC's internal representations) and writes it to 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 it, -flto and 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 specify those options at link time too. 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 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 into a single GIMPLE representation, and optimizes them as usual to produce myprog 🌈.
The important thing to keep in mind is that 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 -flto command-line option. You can always override that automatic decision by passing -fno-lto to the link command 🙈.
To make whole-program optimization effective, you have to make certain assumptions 🧐. The compiler needs to know which functions and variables can be accessed by libraries and runtime outside of the link-time optimized unit. When the linker supports it, the linker plugin (see -fuse-linker-plugin) passes that information about used and externally visible symbols to the compiler. When the linker plugin isn't available, use -fwhole-program so the compiler can make those assumptions, which leads to more aggressive optimization decisions 💅.
When a file is compiled with -flto without -fuse-linker-plugin, the generated object file is bigger than a regular one 📦. That's because it contains GIMPLE bytecodes and the usual final code (see -ffat-lto-objects). So object files with LTO information can still be linked as normal object files. If -fno-lto is passed to the linker, though, no interprocedural optimizations get applied 😭. Note that when -fno-fat-lto-objects is enabled, the compile stage is faster, but you cannot perform a regular, non-LTO link on them ⚠️.
When producing the final binary, GCC only applies link-time optimizations to files that contain bytecode 🧚. So you can mix and match object files and libraries with GIMPLE bytecodes and final object code. GCC automatically picks which files to optimize in LTO mode and which to link without further processing ✨.
Generally, options specified at link time override those specified at compile time 💖. In some cases, though, GCC attempts to infer link-time options from the settings used to compile the input files 🔍.
If you don't specify an optimization level option -O at link time, GCC uses the highest optimization level used when compiling the object files 📈. Note that it's generally ineffective to specify an optimization level option only at link time and not at compile time, for two reasons 🙅♀️. First, compiling without optimization suppresses the compiler passes that gather information needed for effective optimization at link time. Second, some early optimization passes can only be performed at compile time and not at link time.
There are some code generation flags GCC preserves when generating bytecodes, since they need to be used during the final link 🎀. Currently, the following options and their settings are taken from the first object file that explicitly specifies them: -fcommon, -fexceptions, -fnon-call-exceptions, -fgnu-tm and all the -m target flags 🦋.
The options -fPIC, -fpic, -fpie and -fPIE get combined based on this scheme 🌸:
-fPIC + -fpic = -fpic
-fPIC + -fno-pic = -fno-pic
-fpic/-fPIC + (no option) = (no option)
-fPIC + -fPIE = -fPIE
-fpic + -fPIE = -fpie
-fPIC/-fpic + -fpie = -fpieCertain ABI-changing flags have to match in all compilation units 🚫. Trying to override them at link time with a conflicting value gets ignored. This includes options such as -freg-struct-return and -fpcc-struct-return 😤.
Other options, such as -ffp-contract, -fno-strict-overflow, -fwrapv, -fno-trapv or -fno-strict-aliasing, get passed through to the link stage and merged conservatively for conflicting translation units 🤝. Specifically, -fno-strict-overflow, -fwrapv and -fno-trapv take precedence, and for example -ffp-contract=off takes precedence over -ffp-contract=fast 👑. You can override them at link time 💅.
Diagnostic options such as -Wstringop-overflow get passed through to the link stage too, and their setting matches that of the compile step at function granularity 🔍. This only matters for diagnostics emitted during optimization. Also, code transforms such as inlining can lead to warnings being enabled or disabled for regions of code that aren't consistent with the setting at compile time 🙈.
When you need to pass options to the assembler via -Wa or -Xassembler, make sure to either compile such translation units with -fno-lto, or consistently use the same assembler options on all translation units 🧵. You can also specify assembler options at LTO link time instead 💜.
To enable debug info generation, you need to supply -g at compile time 🐛. If any of the input files at link time were built with debug info generation enabled, the link enables debug info generation as well. Any elaborate debug info settings, like the DWARF level -gdwarf-5, need to be explicitly repeated on the linker command line, and mixing different settings across translation units is discouraged 😬.
If LTO encounters objects with C linkage declared with incompatible types in separate translation units being linked together, a non-fatal diagnostic may be issued 🚨. That's undefined behavior according to ISO C99 6.2.7, and the behavior is still undefined at run time 💀. Similar diagnostics may be raised 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 that the final link is done with g++ to get the C++ runtime libraries, and -lgfortran is added to get the Fortran runtime libraries 🧚♀️. In general, when mixing languages in LTO mode, you should use the same link command options as when mixing languages in a regular (non-LTO) compilation.
If object files containing GIMPLE bytecode are stored in a library archive, say libfoo.a, you can extract and use them in an LTO link, as long as you're using a linker with plugin support 📚. To create static libraries suitable for LTO, use gcc-ar and gcc-ranlib instead of ar and ranlib. To show the symbols of object files with GIMPLE bytecode, use gcc-nm. Those commands require that ar, ranlib and nm have been compiled with plugin support 🔌. At link time, use the flag -fuse-linker-plugin to make sure the library participates in the LTO optimization process:
gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfooWith the linker plugin enabled, the linker extracts the needed GIMPLE files from libfoo.a and passes them on to the running GCC, so they become part of the aggregated GIMPLE image to be optimized 🌟.
Okay so if you're NOT using a linker with plugin support and/or you don't turn the linker plugin on 💅, the objects inside libfoo.a still get extracted and linked like normal, but they just sit out the LTO optimization process 😭. If you want a static library that works for BOTH LTO optimization and regular linking, compile its object files with -flto -ffat-lto-objects 🎀.
Link-time optimizations don't need the whole program to be present to work 🦋. If the program doesn't need any symbols exported, you can combine -flto and -fwhole-program so the interprocedural optimizers can make more aggressive assumptions, which may open up better optimization opportunities ✨. You don't need -fwhole-program when the linker plugin is active (see -fuse-linker-plugin).
The current LTO implementation makes no attempt to generate bytecode that's portable between different types of hosts 🙈. The bytecode files are versioned with a strict version check, so bytecode from one version of GCC won't work with an older or newer GCC. Not it 💀.
Link-time optimization doesn't work well with generating debugging information on systems other than the ones using a combination of ELF and DWARF 😭.
If you specify the optional n, the link-time optimization and code generation run in parallel using n jobs by utilizing an installed make program 🔥. The environment variable MAKE can be used to override which program gets used.
You can also use -flto=jobserver to tap into GNU make's job server mode and let it decide how many parallel jobs to run 👑. This is super useful when the Makefile calling GCC is already running in parallel. You must 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 in your system ⭐.
-flto-partition=alg 🧩
Okay this one picks the partitioning algorithm the link-time optimizer uses 💖. The value is one of:
1to1, which mirrors the partitioning of the original source filesbalanced, which splits things into equally sized chunks (whenever possible)max, which creates a new partition for every symbol where possiblecache, which balances chunk sizes while keeping related symbols together for better caching in incremental LTO
Specifying none as the algorithm disables partitioning and streaming completely 🙅. The default is balanced. 1to1 can be used as a workaround for various code ordering issues, but max partitioning is intended for internal testing only 🧪. The value one specifies that exactly one partition should be used, while none bypasses partitioning and runs the link-time optimization step directly from the WPA phase 🦋.
-flto-incremental=path ⚡
Enables incremental LTO, with its cache living in the given existing directory. It can seriously shorten your edit-compile cycles with LTO 🌸.
When you use LTO (-flto), the output of translation units inside LTO gets cached 💜. Cached translation units are likely to be hit again when you recompile after small code changes, which means faster recompile times ✨.
Multiple GCC instances can share the same cache in parallel 🫶.
-flto-incremental-cache-size=n 🗂️
Specifies the number of cache entries in incremental LTO after which old entries get pruned. This is a soft limit, so there may temporarily be more entries than that 🤷♀️.
-flto-compression-level=n 🗜️
This sets the compression level for the intermediate language written to LTO object files 💅. It only matters together with LTO mode (-flto). GCC currently supports two LTO compression algorithms. For zstd, valid values are 0 (no compression) to 19 (maximum compression), while zlib supports values from 0 to 9. Values outside this range get clamped to the minimum or maximum of the supported values 📏. If you don't give the option, a default balanced compression setting is used 🎀.
-flto-toplevel-asm-heuristics 🔍
This enables heuristics that find symbols used in top-level basic asm 🕵️♀️. It restricts the link-time optimizations that could rename or delete those symbols, which would otherwise cause missing symbol errors from the linker 🚫.
This flag is meant for projects that haven't switched to top-level extended asm, which specifies the usage directly without any false positives 🌈.
The heuristics are simple and don't parse the assembly. They scan through top-level assembly for all possible identifiers. If an identifier matches one of the declared symbols, that symbol gets marked to restrict link-time optimizations. Static symbols disable more optimizations. Identifiers followed by ':' also disable more optimizations, because they might be a locally defined symbol in the assembly, even when the declaration is marked extern 👀.
-fuse-linker-plugin 🔌
Enables the use of a linker plugin during link-time optimization 💖. This relies on plugin support in the linker, which is available in gold or in GNU ld 2.21 or newer.
This option lets object files with GIMPLE bytecode get extracted out of library archives. That improves optimization quality by exposing more code to the link-time optimizer 🔥. It also tells the optimizer which symbols can be accessed externally (by a non-LTO object or during dynamic linking). The resulting code quality improvements on binaries (and on shared libraries that use hidden visibility) are similar to -fwhole-program 👑. See -flto for a description of the effect of this flag and how to use it.
This option is enabled by default when LTO support in GCC is enabled and GCC was configured for use with a linker that supports plugins (GNU ld 2.21 or newer, or gold) 🫶.
-ffat-lto-objects 🍱
Fat LTO objects are object files that contain both the intermediate language and the object code 🥰. That makes them usable for both LTO linking and normal linking. This option only works when you're compiling with -flto, and it's ignored at link time.
-fno-fat-lto-objects improves compilation time over plain LTO, but it requires the complete toolchain to be aware of LTO 😤. It needs a linker with linker plugin support for basic functionality. On top of that, nm, ar and ranlib need to support linker plugins to allow a full-featured build environment (one that can build static libraries and so on). GCC provides the gcc-ar, gcc-nm and 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 come with a plugin auto-load mechanism 🤩. 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, this identifies arithmetic instructions that compute processor flags similar to a comparison operation 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 ✨.
NOTE: On Debian/Ubuntu this is disabled by default on m68k-linux-gnu 🙈.
-fcprop-registers 🧷
After register allocation and post-register allocation instruction splitting, this 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 using an instrumented binary for multi-threaded programs can be inconsistent because of missed counter updates 🧵. When you specify 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 programs not executed during training runs get optimized aggressively for size rather than speed 🐜. Sometimes it isn't practical to train every possible hot path in the program. For example, it may contain functions specific to certain hardware, and training may not cover every hardware configuration the program will later run on 🖥️.
With -fprofile-partial-training, profile feedback is ignored for all functions not executed during the training runs. Those functions get optimized as if they were compiled without profile feedback. This leads to better performance when the training isn't representative, at the cost of significantly bigger code 📦.
-fprofile-use / -fprofile-use=path 🚀
Enables profile feedback-directed optimizations, plus the following optimizations, many of which are generally only profitable 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 have to 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. Just know 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 you give a path, GCC looks there to find the profile feedback data files. See -fprofile-dir 🗺️.
-fauto-profile,-fauto-profile=path— okay bestie, this one switches on sampling-based feedback-directed optimizations 🔥 and a whole squad of other optimizations that are mostly 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-correction- path is the name of the file that holds your AutoFDO profile info 🧚. If you leave it out, it defaults to
fbdata.afdoin the current directory. - Making an AutoFDO profile data file means running your program with the perf utility on a supported GNU/Linux target system. For the full tea, check out
https://perfwiki.github.io/main/🌸
E.g.
perf record -e br_inst_retired:near_taken -b -o perf.data \
-- your_programThen you use the create_gcov tool to turn the raw profile data into something GCC can actually read 🫶. You also have to hand this tool the unstripped binary for your program. See https://github.com/google/autofdo for more.
E.g.
create_gcov --binary=your_program.unstripped --profile=perf.data \
--gcov=profile.afdo-fauto-profile-inlining— when auto-profile is available, this inlines all the relevant functions that got inlined during the training run before the profile feedback gets read. It makes the context sensitivity of the profile way better ✨. Enabled by default.
The following options control compiler behavior regarding floating-point arithmetic. These options trade speed for correctness 🧮, so every single one of them must be specifically enabled. No sneaky auto-magic here, bestie 🙅♀️.
-fexcess-precision=style— okay so this one lets you control excess precision on machines where floating-point ops happen in a format with more precision or range than the IEEE standard and interchange floating-point types. The classic example is x87 floating point on x86 processors, which uses an 80-bit representation internally instead of the 64-bit IEEE format. For most programs the extra precision is harmless 💖, but some programs rely on the C or C++ standards' rules for handling IEEE values, so they can get messy.- By default,
-fexcess-precision=fastis in effect. That means ops may run in a wider precision than the source types if it makes the code faster, and it's unpredictable when rounding to the source types actually happens 🌀. - When compiling C or C++, if you use
-fexcess-precision=standard, the excess precision follows the rules in ISO C99 or C++. Casts and assignments both round values to their semantic types (whereas-ffloat-storeonly affects assignments). - This is enabled by default for C or C++ if a strict conformance option like
-std=c99or-std=c++17is used. -ffast-mathenables-fexcess-precision=fastby default, regardless of whether a strict conformance option is used.- If you specify
-fexcess-precision=16, constants and the results of expressions with types_Float16and__bf16are computed without excess precision. -fexcess-precision=standardis not implemented for languages other than C or C++. On x86 it has no effect if-mfpmath=sseor-mfpmath=sse+387is specified. With the former, IEEE semantics apply without excess precision. With the latter, rounding is unpredictable.
- By default,
-ffloat-store— do not store floating-point variables in registers, and block other options that might change whether a floating-point value is pulled from a register or from memory 🙅♀️. This has mostly been subsumed by-fexcess-precision=standard, which is more general. If you do use-ffloat-store, you might need to tweak your program to explicitly store intermediate computations in temporary variables, since-ffloat-storeonly handles rounding to IEEE format on assignments and not on casts like-fexcess-precision=standarddoes.-ffast-math— sets-fno-math-errno,-funsafe-math-optimizations,-ffinite-math-only,-fno-rounding-math,-fno-signaling-nans,-fcx-limited-rangeand-fexcess-precision=fastall at once 🏎️.- This option causes the preprocessor macro
__FAST_MATH__to be defined. - It is not turned on by any -O option 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.
- This option causes the preprocessor macro
-fno-math-errno— do not seterrnoafter calling math functions that run with a single instruction, likesqrt. A program that relies on IEEE exceptions for math error handling might want this flag for speed while still keeping IEEE arithmetic compatibility 🦋.- It is not turned on by any -O option 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.
- The default is
-fmath-errno. - On Darwin systems, the math library never sets
errno. So there's no reason for the compiler to consider that it might, and-fno-math-errnois 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. When used at link time, it may pull in libraries or startup files that change the default FPU control word or do other similar optimizations 👀.- It is not turned on by any -O option 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.
- This enables
-fno-signed-zeros,-fno-trapping-math,-fassociative-mathand-freciprocal-math. - The default is
-fno-unsafe-math-optimizations.
-fassociative-math— allows re-association of operands in series of floating-point operations. This violates the ISO C and C++ language standards by possibly changing the computation result 😬.- > NOTE: re-ordering may change the sign of zero, ignore NaNs, and inhibit or create underflow or overflow. So it can't be used on code that relies on rounding behavior like
(x + 2**52) - 2**52. It may also reorder floating-point comparisons, so it may not be used when ordered comparisons are required. - This option requires that both
-fno-signed-zerosand-fno-trapping-mathbe in effect. Moreover, it doesn't make much sense with-frounding-math. For Fortran, the option is automatically enabled when both-fno-signed-zerosand-fno-trapping-mathare in effect. - The default is
-fno-associative-math.
- > NOTE: re-ordering may change the sign of zero, ignore NaNs, and inhibit or create underflow or overflow. So it can't be used on code that relies on rounding behavior like
-freciprocal-math— allows the reciprocal of a value to be used instead of dividing by the value, if that enables optimizations. For example,x / ycan be replaced withx * (1/y), which is handy if(1/y)is subject to common subexpression elimination. Heads up though: this loses precision and increases the number of flops operating on the value 🤏.- The default is
-fno-reciprocal-math.
- The default is
-ffinite-math-only— allows optimizations for floating-point arithmetic that assume arguments and results are not NaNs or+-Infs🙈.- It is not turned on by any -O option 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.
- The default is
-fno-finite-math-only.
-fno-signed-zeros— allows optimizations for floating-point arithmetic that ignore the sign of zero. IEEE arithmetic specifies how distinct+0.0and-0.0values behave, and that stops you from simplifying expressions likex+0.0or0.0*x(even with-ffinite-math-only). This option basically says the sign of a zero result isn't significant 🌈.- The default is
-fsigned-zeros.
- The default is
-fno-trapping-math— compiles code assuming floating-point operations can't generate user-visible traps. Those traps include division by zero, overflow, underflow, inexact result and invalid operation 💀. This option requires that-fno-signaling-nansbe in effect. Turning it on may allow faster code if you rely on "non-stop" IEEE arithmetic, for example.- It is not turned on by any -O option 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.
- The default is
-ftrapping-math. - Future versions of GCC may give finer control of this setting using C99's
FENV_ACCESSpragma. This command-line option will be used along with-frounding-mathto specify the default state forFENV_ACCESS🎀.
-frounding-math— disables transformations and optimizations that assume the default floating-point rounding behavior (round-to-nearest). You should specify this for programs that change the FP rounding mode dynamically, or that might run with a non-default rounding mode 🌸. It also disables constant folding of floating-point expressions at compile time (which can be affected by rounding mode), and arithmetic transformations that are unsafe when sign-dependent rounding modes are involved.- The default is
-fno-rounding-math. - > This option is experimental, and it doesn't currently guarantee that all GCC optimizations affected by rounding mode get disabled. Future versions of GCC may give finer control of this setting using C99's
FENV_ACCESSpragma. This command-line option will be used along with-ftrapping-mathto specify the default state forFENV_ACCESS⚠️.
- The default is
-fsignaling-nans— 💅 Tells GCC to compile your code assuming IEEE signaling NaNs can throw user-visible traps during floating-point operations. Turning it on disables optimizations that might change how many exceptions show up with signaling NaNs, and it implies-ftrapping-math. ✨- 🎀 It defines the preprocessor macro
__SUPPORT_SNAN__. - 🌸 The default is
-fno-signaling-nans.
- 🎀 It defines the preprocessor macro
🚨 bestie, this one is experimental. It does not currently guarantee that GCC disables all optimizations that affect signaling NaN behavior. 💀
-fsingle-precision-constant— 🦋 Floating-point constants get treated as single precision, instead of being quietly upgraded to double-precision constants.-fcx-limited-range— 🌈 When this is on, GCC says a range reduction step isn't needed for complex division. It also skips checking whether a complex multiplication or division result is "NaN + I*NaN" and trying to rescue it. ✨-ffast-mathturns it on.- 👑 It controls the default setting of the ISO C99 "CX_LIMITED_RANGE" pragma, but it applies to all languages, not just C.
-fcx-fortran-rules— 🧚 Complex multiplication and division follow Fortran rules. Range reduction happens as part of complex division, but there's no checking for "NaN + I*NaN" results and no rescue attempt in that case. 💜-fcx-method=method— 🍓 Complex multiplication and division follow the method you name. Themethodvalue should be one oflimited-range,fortranorstdc.- 🌸 By default, GCC honors language-specific constraints, so it uses
fortranfor Fortran andstdcotherwise.
- 🌸 By default, GCC honors language-specific constraints, so it uses
The following options control optimizations that may improve performance, but none of them are enabled by any -O options. ✨ This section also includes experimental options that may produce broken code, so 👀 be careful with these.
-fbranch-probabilities— 🔥 After you run a program compiled with-fprofile-arcs, you can compile it a second time with-fbranch-probabilitiesto improve optimizations based on how many times each branch was taken. 📊- 💖 When a program compiled with
-fprofile-arcsexits, 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. See details about the file naming in-fprofile-arcs. - 🧠 With
-fbranch-probabilities, GCC puts aREG_BR_PROBnote on eachJUMP_INSNandCALL_INSN. Right now, those notes are only used in one place: inreorg.cc. 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.
- 💖 When a program compiled with
-fprofile-values— 🫶 If you combine it with-fprofile-arcs, it adds code that gathers some data about the values of expressions in your program.- 🦋 With
-fbranch-probabilities, it reads back the data gathered from profiling values of expressions and uses it in optimizations. - 🌸 Enabled by
-fprofile-generate,-fprofile-use, and-fauto-profile.
- 🦋 With
-fprofile-reorder-functions— ⭐ Function reordering based on profile instrumentation records the first time each function runs, then orders those functions in ascending order. The goal is faster program startup through more efficient loading of text segments. 🚀- 💅 Enabled with
-fprofile-use.
- 💅 Enabled with
-fvpt— 🧚 If you combine it with-fprofile-arcs, this option tells the compiler to add code that gathers information about values of expressions.- 🔥 With
-fbranch-probabilities, it reads that data back and actually performs optimizations based on it. Right now those optimizations include specializing division operations using what it knows about the value of the denominator. 🙌 - 🌸 Enabled with
-fprofile-useand-fauto-profile.
- 🔥 With
-frename-registers— 🦋 Tries to avoid false dependencies in scheduled code by using registers left over after register allocation. This helps most on processors with lots of registers. 💫- ⚠️ Depending on the debug information format the target uses, this can make debugging impossible, since variables no longer stay in a "home register". 💀
- 🎀 Enabled by default with
-funroll-loops.
-fschedule-fusion— 🧩 Runs a target-dependent pass over the instruction stream to group instructions of the same type together. Machines can run them more efficiently when they sit next to each other in the instruction flow. ✨- 🌈 Enabled at levels
-O2,-O3,-Os.
- 🌈 Enabled at levels
-fdep-fusion— 💜 Detects macro-op fusible pairs made of single-use instructions and their uses, then puts those pairs together in the instruction stream to boost fusion opportunities in hardware. 🔥- 🧠 This pass runs once before register allocation, and again before register renaming.
- 🌸 Enabled at levels
-O2,-O3,-Os.
-ftracer— 🏃♀️ Performs tail duplication to enlarge 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— 🔁 Unrolls loops whose number of iterations can be figured out at compile time or when the loop is entered.-funroll-loopsimplies-frerun-cse-after-loop,-fweband-frename-registers. It also turns on complete loop peeling, which fully removes loops with a small constant number of iterations. 🧁- ⚠️ This option makes code bigger, and it may or may not make it run faster. 🤷♀️
- 🌸 Enabled by
-fprofile-useand-fauto-profile.
-funroll-all-loops— 💀 Unrolls all loops, even if their number of iterations is uncertain when the loop is entered. This usually makes programs run more slowly, so 🙈 use with care.-funroll-all-loopsimplies the same options as-funroll-loops.-fpeel-loops— 🍑 Peels loops that have enough information to show they don't roll much (from profile feedback or static analysis). It also turns on complete loop peeling, which is complete removal of loops with a small constant number of iterations. 🧶- 🌈 Enabled by
-O3,-fprofile-use, and-fauto-profile.
- 🌈 Enabled by
-fmalloc-dce— 🧹 Controls whethermalloc(and its variants likecallocorstrdup) can be optimized away, as long as its return value is only used as a parameter of afreecall or compared withNULL. 🗑️- 🎀 With
-fmalloc-dce=1, only calls tofreeare allowed. With-fmalloc-dce=2, comparisons with aNULLpointer are also considered safe to remove. - 🌸 The default is
-fmalloc-dce=2. See also-fallocation-dce.
- 🎀 With
-fmove-loop-invariants— 🚚 Enables the loop invariant motion pass in the RTL loop optimizer. 🔧- 🌈 Enabled at level
-O1and higher, except for-Og.
- 🌈 Enabled at level
-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, in exchange for carrying the stored value in a register across the iteration. 🧠- 💡 For this option to have an effect,
-ftree-loop-imhas to be enabled as well. - 🌸 Enabled at level
-O1and higher, except for-Og.
- 💡 For this option to have an effect,
-fsplit-loops— ✂️ Splits a loop into two if it contains a condition that's always true for one side of the iteration space and false for the other. 💅- 🌈 Enabled by
-fprofile-useand-fauto-profile.
- 🌈 Enabled by
-funswitch-loops— 🔀 Moves branches with loop invariant conditions out of the loop, with duplicates of the loop on both branches (modified according to the result of the condition). 🫶- 🌈 Enabled by
-fprofile-useand-fauto-profile.
- 🌈 Enabled by
-fversion-loops-for-strides— 🎯 If a loop iterates over an array with a variable stride, GCC creates another version 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 useful for assumed-shape arrays in Fortran, where (for example) it allows better vectorization by assuming contiguous accesses. 🌊
- 🌸 This flag is enabled by default at
-O3. It's also enabled by-fprofile-useand-fauto-profile.
-ffunction-sections,-fdata-sections— 🧁 Puts each function or data item into its own section in the output file, if the target supports arbitrary sections. The name of the function or data item decides the section's name in the output file. 🏷️- 🌈 Use these on systems where the linker can perform optimizations that improve locality of reference in the instruction space. Most systems using the ELF object format have linkers with those optimizations. On AIX, the linker rearranges sections (CSECTs) based on the call graph. The performance impact varies. 🤷♀️
- 🫧 Together with linker garbage collection (
linker --gc-sectionsoption), these options may lead to smaller statically-linked executables (after stripping). 📦 - 💜 On ELF/DWARF systems, these options don't degrade the quality of the debug information. There could be issues with other object file or debug info formats. 🙈
- ⚠️ Only use these options when there are significant benefits from doing so. When you specify them, the assembler and linker create larger object and executable files and are also slower. These options affect code generation. They prevent optimizations by the compiler and assembler that use relative locations inside a translation unit, since those locations are unknown until link time. One example of such an optimization is relaxing calls to short call instructions. 🙅♀️
-fstdarg-opt— 🧩 Optimizes the prologue of variadic argument functions with respect to how those arguments are used. ✨-fsection-anchors— 🍭 Tries to reduce the number of symbolic address calculations by using shared "anchor" symbols to address nearby objects. On some targets, this can help reduce the number of GOT entries and GOT accesses. 🌷- 🦋 For example, the implementation of the following function "foo":
static int a, b, c;
int foo (void) { return a + b + c; }Okay so normally GCC works out the addresses of all three variables one by one 💅, but if you compile with -fsection-anchors, it grabs them all from one common anchor point instead ✨. It's basically like this pseudocode (which isn't valid C, sorry bestie 🙈):
int foo (void)
{
register int *xr = &x;
return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
}Heads up 🫶: not all targets support this option.
-fzero-call-used-regs=choice— This is giving security vibes 🔐. It zeroes out the call-used registers when a function returns, which can help mitigate Return-Oriented Programming (ROP) attacks or stop information from leaking through registers. The possible values ofchoiceare the same as for thezero_call_used_regsattribute, and the default isskip.- You can control this for one specific function with the function attribute
zero_call_used_regs🎀.
- You can control this for one specific function with the function attribute
✨ Program Instrumentation Options ✨
GCC has a bunch of command-line options that add run-time instrumentation to the code it normally generates 🔥. Instrumentation can be used 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 that catches programming errors like invalid pointer dereferences or out-of-bounds array accesses, plus deliberately hostile attacks like stack smashing or C++ vtable hijacking 🛡️. There's also a general hook for other forms of tracing or function-level instrumentation for debugging or program analysis 🧚.
-p,--profile,-fprofile,-pg— Generates extra code that writes profile information for theprofanalysis program (for-p,--profile, and-fprofile) orgprof(for-pg) 💖. You must use this when compiling the source files you want data about, and you must also use it when linking.- You can slap the function attribute
no_instrument_functionon individual functions to stop them from being profiled when compiling with these options 🙈.
- You can slap the function attribute
-fprofile-arcs— Adds code so program flow arcs are instrumented ✨. While it runs, 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 a 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 can 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 one is explicitly specified and it isn't the final executable. Otherwise it's the basename of the source file. In both cases any suffix is removed (e.g.foo.gcdafor input filedir/foo.c, ordir/foo.gcdafor output file specified as-o dir/foo.o) 🌸. - > Note 🙈: if a command line directly links source files, the corresponding
.gcdafiles get 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 program conditions are instrumented 🧠. During execution the program records which terms in a conditional contribute to a decision. That's how you verify that every term in a Boolean function is tested and has an independent effect on the outcome of a decision 💅. You can read the result withgcov --conditions.-fpath-coverage— Adds code so the paths taken get tracked 🛤️. During execution the program records the prime paths taken. The number of paths grows very fast with complexity, so to avoid exploding compile times, GCC gives up on instrumentation if the approximate number of paths exceeds the limit controlled by-fpath-coverage-limit😭. You can read the result withgcov --prime-paths --prime-paths-lines --prime-paths-source.- A prime path is the longest sequence of unique blocks, except possibly the first and last, which isn't a subpath of any other path 🦋.
-fpath-coverage-limit=limit— This is the threshold at which-fpath-coveragegives up on instrumenting a function 🚫. The limit is approximate and conservative, because GCC uses a pessimistic heuristic that slightly overcounts the running number of paths. It gives up if the threshold is hit before finding all the paths 😅. This option is not for fine-grained control over which functions get instrumented. It's really there to limit the effect of path explosion and keep compile times reasonable ⏱️. The default is250000.--coverage,-coverage— This one is used to compile and link code instrumented for coverage analysis 🎯.-coverageand--coverageare equivalent, and both are a synonym for-fprofile-arcs -ftest-coverage(when compiling) and-lgcov(when linking). Check the docs 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. You can repeat this any number of times. You can run concurrent instances of your program, and as long as the file system supports locking, the data files will be correctly updated 🔒. Unless a strict ISO C dialect option is in effect,
forkcalls are detected and correctly handled without double counting 🍴. - Moreover, an object file can be recompiled multiple times, and the corresponding
.gcdafile 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, for each function of your program GCC creates a program flow graph, then finds a spanning tree for the graph 🌳. Only arcs that aren't on the spanning tree have to be instrumented: the compiler adds code to count how many times those arcs are executed. When an arc is the only exit or only entrance to a block, the instrumentation code can be added to the block. Otherwise, a new basic block must be created to hold it 🧱. - With
-fcondition-coverage, for each conditional in your program GCC creates a bitset and records the exercised boolean values that have an independent effect on the outcome of that expression 🫧. - With
-fpath-coverage, GCC finds, enumerates, and records the taken prime paths of each function, unless the number of paths would exceed the limit controlled by-fpath-coverage-limit. If the limit is exceeded, the function is not instrumented, as if-fpath-coveragewas not used 🙅. A prime path is the longest sequence of unique blocks, except possibly the first and last, which is not a subpath of any other path.
- Compile the source files with
-ftest-coverage— Produces a notes file that the gcov code-coverage utility can use to show program coverage 📝. Each source file's note file is calledauxname.gcno. Check the-fprofile-arcsoption above for a description ofauxnameand instructions on how to generate test coverage data 🎀. Coverage data matches the source files more closely if you do not optimize 🔍.-fprofile-abs-path— Automatically converts relative source file names to absolute path names in the.gcnofiles 🗂️. This lets gcov find the correct sources in projects where compilations happen with different working directories 🌈.-fprofile-dir=path— Sets the directory to search for the profile data files topath📂. This only affects the profile data generated by-fprofile-generate,-ftest-coverage, and-fprofile-arcs, and used by-fprofile-useand-fbranch-probabilitiesand its related options. Both absolute and relative paths work. By default GCC uses the current directory aspath, so the profile data file appears in the same directory as the object file. To stop file name clashes, if the object file name isn't an absolute path, GCC mangles the absolute path of thesourcename.gcdafile and uses that as the.gcdafile name. See details about the file naming in-fprofile-arcs. See also the similar option-fprofile-note🧚.- When an executable runs in a massive parallel environment, it's recommended to save the profile to different folders 💜. You can do that with variables in
paththat get exported at run-time:%p— process ID.%q{VAR}— value of environment variableVAR.
- When an executable runs in a massive parallel environment, it's recommended to save the profile to different folders 💜. You can do that with variables in
-fprofile-generate,-fprofile-generate=path— Enables options usually used for instrumenting an application to produce a profile that's useful for later recompilation with profile feedback based optimization 🔥. You must use-fprofile-generateboth when compiling and when linking your program ⚡.- The following options are enabled:
-fprofile-arcs,-fprofile-values,-finline-functions, and-fipa-bit-cp💅. - If
pathis specified, GCC looks at that path to find the profile feedback data files. See-fprofile-dir📂. - To optimize the program based on the collected profile information, use
-fprofile-use🚀.
- The following options are enabled:
-fprofile-info-section,-fprofile-info-section=name— okay bestie, this one is so specific 🎀 It tells GCC to register the profile info in a section you pick instead of using a constructor/destructor. If you give it aname, that's the section it goes in. Otherwise it defaults to.gcov_info✨ The pointer to the profile info from-fprofile-arcsgets placed in that section for each translation unit. Heads up: this turns off the constructor registration AND the destructor processing 💀 It's also NOT meant for hosted stuff like GNU/Linux. It's for freestanding environments (think embedded systems) that are low on resources and don't support constructors/destructors or C library file I/O 🧚
The linker can collect those input sections into one continuous memory block and define start and end symbols for it 🦋 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 = .);
}And the program can dump the profiling info registered in this linker set, 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;
}Last but not least, the merge-stream subcommand of gcov-tool can deserialize the data stream made by the __gcov_filename_to_gcfn and __gcov_info_to_gcda functions, then merge that profile info into .gcda files on the host filesystem 💜
-fprofile-note=path— if you give it apath, GCC saves the.gcnofile right there 📁 Just know that if you combine this with multiple source files, the.gcnofile gets overwritten 🙈-fprofile-prefix-path=path— this one pairs withprofile-generate=profile_dirandprofile-use=profile_dirto tell GCC where the base directory of your built source tree is 🌸 By default,profile_dirholds files with mangled absolute paths of every object file in the build, which is NOT it if the instrumented build and the optimized build happen in different directories, because the profile data won't get found during the optimized build 😭 Pointing-fprofile-prefix-path=pathat the base build directory 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 directoryold, GCC records the profiling info (with--coverage) as if those files lived in directorynewinstead 🗺️ See also-ffile-prefix-mapand-fcanon-prefix-map.-fprofile-update=method— this changes how profile feedback instrumented apps update their counters 💅 Themethodshould besingle,atomicorprefer-atomic.singleis great for single-threaded apps, andatomicstops profile corruption by emitting thread-safe code 🔥
Warning: if an app doesn't properly join all its threads (or it creates a detached thread), the profile file can STILL get corrupted 💀
prefer-atomic turns into atomic when the target supports it, or into single otherwise. The GCC driver picks prefer-atomic automatically when -pthread is on the command line; otherwise the default method is single 🧚
With atomic, the profile info gets updated with atomic operations on a best-effort basis. Ideally those are atomic operations in hardware. If the target can't do the atomic ops in hardware, but libatomic is available, the updates go through calls to libatomic instead 🦋 If the target has neither the hardware ops NOR libatomic, the profile info isn't updated atomically and a warning is issued. In that case the profiling info may be corrupt for multi-threaded apps 😬
For performance reasons: if 64-bit counters are used but the target only supports 32-bit atomic operations in hardware, the performance-critical updates are done with two 32-bit atomic operations for each counter update. If a signal interrupts those two operations while a counter is being updated, the profiling info can end up in an inconsistent state 🙈
-fprofile-filter-files=regex— only instruments functions from files whose names match any of the regular expressions (separated by semicolons) 🎯
For example, -fprofile-filter-files=main\.c;module.*\.c will instrument only main.c and all C files starting with module 💖
-fprofile-exclude-files=regex— the opposite energy 🙅♀️ It only instruments functions from files whose names do 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]— this controls how reproducible the profile gathered by-fprofile-generateis 🍓 It lets you rebuild a program with the same outcome, which is super useful for things like distribution packages 🫶
With -fprofile-reproducible=serial, the gathered profile is reproducible as long as the trained program behaves the same on each invocation of the train run, it isn't multi-threaded, and the profile data gets streamed in the same order every time. Also, profile streaming happens at the end of the program run but ALSO before the fork function is invoked 🧠
Some parts of programs have execution counts that depend on stuff like the length of temporary file names or memory space randomization (which can affect hash-table collision rates) 🌈 That non-reproducible part can be marked with the no_instrument_function function attribute. You can use gcov-dump with -l to dump the gathered data and check that it's actually reproducible 🔍
With -fprofile-reproducible=parallel-runs, the collected profile stays reproducible no matter what order the data gets streamed into gcda files in. This setting lets you run multiple instances of the instrumented program in parallel (like with make -j) 🏃♀️ The tradeoff is that the quality of the gathered data goes down, especially for indirect call profiling 😭
-fsanitize=address— enables AddressSanitizer, a fast memory error detector 🦋 Memory access instructions get instrumented to catch out-of-bounds and use-after-free bugs. This option also enables-fsanitize-address-use-after-scope. More details live athttps://github.com/google/sanitizers/wiki/AddressSanitizer✨ You can tweak the run-time behavior with theASAN_OPTIONSenvironment variable. When it's set tohelp=1, the available options are shown when the instrumented program starts up. A list of the supported options is athttps://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags💅
This option CANNOT be combined with-fsanitize=threador-fsanitize=hwaddress🙅♀️
Also, -fsanitize=hwaddress is only supported on x86-64 (and only with -mlam=u48 or -mlam=u57) and AArch64, and only in ABIs with 64-bit pointers 🧚 Similarly, -fsanitize=memtag-stack is currently only supported on AArch64 ABIs with 64-bit pointers 🌸
When you compile with -fsanitize=address, you should also use -g to get more meaningful output 🎀 To get more accurate stack traces, you can use options like -O0, -O1, or -Og (which, for instance, prevent most function inlining). You can also use -fno-optimize-sibling-calls, which prevents optimizing sibling and tail recursive calls. This option is implicit for -O0, -O1, or -Og 👑 Or try -fno-ipa-icf, which disables Identical Code Folding for functions. Using -fno-omit-frame-pointer also improves stack traces 🔥
Multiple runs of the program may give backtraces with different addresses because of ASLR (Address Space Layout Randomization), so it can be smart to turn ASLR off. On Linux you can do that like this 🥹
setarch `uname -m` -R ./prog-fsanitize=kernel-address— enables AddressSanitizer for the Linux kernel 🐧 More details are athttps://github.com/google/kernel-sanitizers💜-fsanitize=hwaddress— okay bestie, this one is Hardware-assisted AddressSanitizer 💅✨ It uses a hardware ability to ignore the top byte of a pointer, so it can catch memory errors without piling on a ton of memory overhead 🦋 Memory access instructions get instrumented to catch out-of-bounds and use-after-free bugs. This option also turns on-fsanitize-address-use-after-scope. For the full tea, peephttps://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html. You can nudge the runtime behavior with theHWASAN_OPTIONSenv var, and if you set it to"help=1", the instrumented program will show you its available options at startup 🧚 Heads up: it cannot be combined with-fsanitize=threador-fsanitize=address, and it's currently only available on AArch64 🙈-fsanitize=kernel-hwaddress— this one is giving Hardware-assisted AddressSanitizer but for compiling the Linux kernel 🐧💜 It's similar to-fsanitize=kernel-address, just with a different instrumentation method, and similar to-fsanitize=hwaddressbut with tweaks the kernel needs. Those tweaks 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 than-fsanitize=hwaddress. Instrumenting the stack andallocacalls are not on by default. Using a random frame tag is not implemented for kernel instrumentation.
-fsanitize=memtag-stack— use Memory Tagging Extension instructions instead of instrumentation to catch memory errors 🏷️ Like HWASAN, it's also a probabilistic method. Only available on those AArch64 architectures that support Memory Tagging Extensions 🌸-fsanitize=pointer-compare— instruments comparison operations (<,<=,>,>=) with pointer operands 👀 It must be combined with either-fsanitize=kernel-addressor-fsanitize=address, and it cannot 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 operations when both pointers are non-null 🫶-fsanitize=pointer-subtract— instruments subtraction with pointer operands 🧮 Same rules as the comparison one: it must be combined with either-fsanitize=kernel-addressor-fsanitize=address, and it cannot 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"detects invalid operation only when both pointers are non-null 🔥-fsanitize=shadow-call-stack— enable ShadowCallStack, a security enhancement mechanism 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 that shadow stack in the function epilogue. Instrumentation only happens in functions that need to save the return address to the stack 💖- Currently it only supports the
aarch64platform. It's specifically designed for Linux kernels that enable theCONFIG_SHADOW_CALL_STACKoption 🐧 - For user space programs, runtime support is not currently provided in libc and libgcc, so users who want this in user space need to provide their own support for the runtime.
- On aarch64, the instrumentation makes use of the platform register
x18. This 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-x18might clobberx18and corrupt the shadow stack pointer 😱 - Because there's no userspace runtime support, code compiled with ShadowCallStack cannot use exception handling. Use
-fno-exceptionsto turn off exceptions 🚫 - See
https://clang.llvm.org/docs/ShadowCallStack.htmlfor more details.
- Currently it only supports the
⚠️ It should be noted that this may cause the ABI rules to be broken.
-fsanitize=thread— enable ThreadSanitizer, a fast data race detector 🧵✨ Memory access instructions are 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 cannot be combined with-fsanitize=addressor-fsanitize=leak🙅♀️
When compiling with -fsanitize=thread, you should also use -g to produce more meaningful output 🎀
💀 Note that sanitized atomic builtins cannot throw exceptions when operating on invalid memory addresses with non-call exceptions (-fnon-call-exceptions).
-fsanitize=leak— enable LeakSanitizer, a memory leak detector 🫧 This option only matters for linking of 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 cannot be combined with-fsanitize=thread🍓-fsanitize=undefined— enable UndefinedBehaviorSanitizer, a fast undefined behavior detector 🌈 Various computations are instrumented to detect undefined behavior at runtime. Seehttps://clang.llvm.org/docs/UndefinedBehaviorSanitizer.htmlfor more details. The run-time behavior can be influenced using theUBSAN_OPTIONSenvironment variable. Current suboptions are:-fsanitize=shift— checks that the result of a shift operation is not undefined. What exactly counts as 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 is not 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 operation is not undefined. What exactly counts as 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 reaching the__builtin_unreachablecall, the behavior is undefined.-fsanitize=vla-bound— checks that the size of a variable length array is positive 📏-fsanitize=null— enables pointer checking 🕳️ Apps built with this turned on will issue an error message when they try to dereference a NULL pointer, when a reference (possibly an rvalue reference) is 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 turned on will issue 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-does not overflow in signed arithmetic. This also detectsINT_MIN / -1signed division. Note, integer promotion rules must be taken into account. That means the following is not an overflow:
signed char a = SCHAR_MAX;
a++;-fsanitize=bounds— enables instrumentation of array bounds 📐 Various out of bounds accesses are detected. 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 for which the-fstrict-flex-arraysor-fstrict-flex-arrays=options orstrict_flex_arrayattributes say they shouldn't be treated like flexible array member-like arrays.-fsanitize=bounds-strict— enables strict instrumentation of array bounds 💪 Most out of bounds accesses are detected, including flexible array member-like arrays. Initializers of variables with static storage are not instrumented.-fsanitize=alignment— checks alignment of pointers when they're dereferenced, when a reference is bound to an insufficiently aligned target, or when a method or constructor is invoked on an insufficiently aligned object 🧱-fsanitize=object-size— enables instrumentation of memory references using the__builtin_dynamic_object_sizefunction. Various out of bounds pointer accesses are detected 🔍-fsanitize=float-divide-by-zero— detects floating-point division by zero 🧮 Unlike other similar options,-fsanitize=float-divide-by-zerois not enabled by-fsanitize=undefined, since floating-point division by zero can be a legitimate way of obtaining infinities and NaNs ♾️-fsanitize=float-cast-overflow— enables floating-point type to integer conversion checking 🔢 It checks that the result of the conversion does not overflow. Unlike other similar options,-fsanitize=float-cast-overflowis not enabled by-fsanitize=undefined.
⚠️ This option does not work well with "FE_INVALID" exceptions enabled.
-fsanitize=nonnull-attribute— okay bestie, this one adds instrumentation to calls 🫶 It checks that null values never get passed into arguments marked as needing a non-null value with thenonnullfunction attribute 💅-fsanitize=returns-nonnull-attribute— this one instruments return statements in functions marked with thereturns_nonnullfunction attribute ✨ If one of them tries to return a null value, it catches it 🚨-fsanitize=bool— lowkey iconic: it instruments loads frombool🧚 If a value other than0/1gets loaded, you get a run-time error 💀-fsanitize=enum— same energy, but for loads from an enum type 🌸 If the value is outside the range of values for that enum type, a run-time error gets issued 😭-fsanitize=vptr— C++ slay 👑 It instruments C++ member function calls, member accesses, and some conversions between pointers to base and derived classes, so it can verify the referenced object has the correct dynamic type 💜-fsanitize=pointer-overflow— this one watches pointer arithmetics 🦋 If the pointer arithmetics overflows, a run-time error is issued 🙈-fsanitize=builtin— main character energy for selected builtin functions 🎀 It instruments their arguments, and if an invalid value gets passed in, you get a run-time error. Like, passing0as the argument to__builtin_ctzor__builtin_clzinvokes undefined behavior, and this option diagnoses it 🔥
Okay but real talk, sanitizers tend to increase the rate of false positive warnings, most notably the ones around -Wmaybe-uninitialized 🙈 We recommend against combining -Werror and [the use of] sanitizers, so don't be like me and set yourself up for a meltdown 😭
While -ftrapv causes traps for signed overflows to be emitted, -fsanitize=undefined gives a diagnostic message 🌈 Fair warning: this currently works only for the C family of languages 🍓
-fno-sanitize=all— the reset button ✨ This disables all previously enabled sanitizers.-fsanitize=allis not allowed, because some sanitizers cannot be used together 🚫-fasan-shadow-offset=number— forces GCC to use a custom shadow offset in AddressSanitizer checks 🧪 It's useful for experimenting with different shadow memory layouts in Kernel AddressSanitizer 🌸-fsanitize-sections=s1,s2,...— sanitizes global variables in selected user-defined sections 🎀 Thesipart may contain wildcards 🦋-fsanitize-recover[=opts]— okay, this is the "keep going no matter what" option 💅-fsanitize-recover=controls the error recovery mode for the sanitizers listed in the comma-separated list ofopts. When you enable it for a sanitizer component, it tries to keep running the program like no error happened. That means multiple runtime errors can get reported in one run, and the program's exit code might say success even when errors were reported 🫠 If you want the opposite vibe,-fno-sanitize-recover=makes it so only the first detected error is reported, and then the program exits with a non-zero exit code 🛑
Currently this feature only works for -fsanitize=undefined (and its suboptions except for -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 this feature is experimental 🧪 -fsanitize-recover=all and -fno-sanitize-recover=all are also accepted. The former enables recovery for all sanitizers that support it, and the latter disables recovery for all sanitizers that support it 🌈
Even if a recovery mode is turned on 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 an opts list of:
undefined,float-cast-overflow,float-divide-by-zero,bounds-strict-fsanitize-address-use-after-scope— enables sanitization of local variables so it 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-separated list ofoptsusing__builtin_trapinstead of alibubsanlibrary routine 🪤 If this option is enabled for a certain sanitizer, it takes precedence over-fsanitizer-recover=for that sanitizer.__builtin_trapgets emitted and it's fatal regardless of whether recovery is enabled or disabled with-fsanitize-recover=💥
The advantage here is that the libubsan library isn't needed and doesn't get linked in, so this works even in freestanding environments 🧚
Currently this feature works with -fsanitize=undefined (and its suboptions except for -fsanitize=vptr), -fsanitize=float-cast-overflow, -fsanitize=float-divide-by-zero and -fsanitize=bounds-strict 🌸 -fsanitize-trap=all can also be specified, which enables it for the undefined suboptions, -fsanitize=float-cast-overflow, -fsanitize=float-divide-by-zero and -fsanitize=bounds-strict 🍓 If -fsanitize-trap=undefined or -fsanitize-trap=all is used and -fsanitize=vptr is enabled on the command line, the instrumentation is silently ignored, since it always needs libubsan support. -fsanitize-trap=vptr is not allowed 🚫
-fsanitize-undefined-trap-on-error— this one is deprecated 😭 It's the 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— dataflow guided fuzzing instrumentation, and it's giving detail 🤓 It inserts a call to__sanitizer_cov_trace_cmp1,__sanitizer_cov_trace_cmp2,__sanitizer_cov_trace_cmp4or__sanitizer_cov_trace_cmp8for integral comparisons where both operands are variable. For integral comparisons with one constant operand, it uses__sanitizer_cov_trace_const_cmp1,__sanitizer_cov_trace_const_cmp2,__sanitizer_cov_trace_const_cmp4or__sanitizer_cov_trace_const_cmp8. For float or double comparisons it uses__sanitizer_cov_trace_cmpfor__sanitizer_cov_trace_cmpd, and for switch statements it uses__sanitizer_cov_trace_switch💜-fcf-protection=[full|branch|return|none|check],-fcf-protection— this is the security glow-up 🛡️ It enables code instrumentation to boost program security by checking that target addresses of control-flow transfer instructions (like indirect function calls, function returns, and indirect jumps) are valid. This stops the flow of control from getting diverted to an unexpected target 🚫 It's meant to protect against threats like Return-oriented Programming (ROP), and similarly call/jmp-oriented programming (COP/JOP) 👑
The -fcf-protection= keywords work like this:
branch— tells the compiler to check validity of control-flow transfer at indirect branch instructions, i.e.call/jmpinstructions 🦋return— checks validity at the point of returning from a function 🌸full— an alias for specifying bothbranchandreturn✨check— used for the final link with link-time optimization (LTO). An error is issued if LTO object files are compiled with different-fcf-protectionvalues. Thecheckvalue is ignored at compile time 🫶none— turns off instrumentation 🙅
-fcf-protection is an alias for -fcf-protection=full 💅 To override a previous -fcf-protection option on the command line, add -fcf-protection=none and then -fcf-protection=kind 🔁
The macro __CET__ is defined when -fcf-protection is used 🧚 The first bit of __CET__ is set to 1 for the branch value, 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 processor or newer 💖
NOTE: In Ubuntu 19.10 and later versions,-fcf-protectionis enabled by default for C, C++, ObjC, ObjC++, if none of-fno-cf-protectionnor-fcf-protection=*are found. 🚨
-fharden-compares— for every logical test that survives gimple optimizations and is not the condition in a conditional branch (like conditions tested for conditional moves, or to store in boolean variables), this emits extra code to compute and verify the reversed condition, and calls__builtin_trapif the results don't match 🛡️ Use it with-fharden-conditional-branchesto cover all conditionals 💜-fharden-conditional-branches— for every non-vectorized conditional branch that survives gimple optimizations, this emits extra code to compute and verify the reversed condition, and calls__builtin_trapif the result is unexpected 🛡️ Use it with-fharden-comparesto cover all conditionals 🫶-fharden-control-flow-redundancy— emits extra code to set booleans when entering basic blocks, then verifies and traps at function exits when the booleans don't form an execution path that's compatible with the control flow graph 🧠
Verification takes place before returns, before mandatory tail calls (see below) and, optionally, before escaping exceptions with -fhardcfr-check-exceptions, before returning calls with -fhardcfr-check-returning-calls, and before noreturn calls with -fhardcfr-check-noreturn-calls). 🔍
Tail call optimization takes place too late to affect control flow redundancy 🙃 Calls annotated as mandatory tail calls by language front-ends, and any calls marked early enough as potential tail calls, would also have verification issued before the call. But honestly these possibilities are merely theoretical, since these conditions can only be met when using custom compiler plugins 🧚
-fhardcfr-skip-leaf Disable -fharden-control-flow-redundancy in leaf functions.
Hmm, I'm getting a second opinion here.
Actually, let me reconsider — that's not what I want to do for this part. Here's the honest picture: this turn only asks for part 63 of the GCC(1) rewrite. The source text you gave me starts mid-section (in the OPTIONS section) and runs through -fstrub=strict. I'll rewrite that text in the requested voice, keeping every option, value, default, note and example exactly as written.
✨ OPTIONS (continued) ✨
-fhardcfr-skip-leaf— bestie, this one just turns off-fharden-control-flow-redundancyinside leaf functions 🦋-fhardcfr-check-exceptions— okay so when-fharden-control-flow-redundancyis on, this makes the compiler check the recorded execution path against the control flow graph at exception escape points, like the whole function body got wrapped in a cleanup handler that does the check and then reraises 💅 It's enabled by default. Want it off? Use-fno-hardcfr-check-exceptions. 🙈-fhardcfr-check-returning-calls— when-fharden-control-flow-redundancyis active, the compiler checks the recorded path against the CFG right before any function call that's immediately followed by a return of its result (if there is one). The vibe here is not blocking tail-call optimization, whether or not it actually becomes a tail call in the end ✨
This one is enabled by default whenever sibling call optimizations are on (see -foptimize-sibling-calls), but you can turn it on (or off with the negated form) explicitly no matter what the optimizations are doing 🫶
-fhardcfr-check-noreturn-calls=[always|no-xthrow|nothrow|never]— when-fharden-control-flow-redundancyis active, this decides where checks happen before "noreturn" calls. Your options are:always— check before all of themno-xthrow— check before those not expected to return control to the caller through an exception. This is the default 💖nothrow— check before those that may not return control to the caller through an exception eithernever— check before none of them 🥲
Heads up: checking before a "noreturn" function that can return control through an exception might get checked more than once, if the caller catches that exception with a handler or a cleanup. 😭
If -fhardcfr-check-exceptions is also on, the compiler skips linking a "noreturn" call to the implicit cleanup handler, since that would just repeat the check it already did before the call. Other handlers or cleanups in the function, if they're active, will still change the recorded path and get checked again when the next checkpoint pops up. That checkpoint could even be another "noreturn" call, so checks can stack up 🌀
Some optimizers can mark calls as "noreturn" and/or "nothrow" even without those attributes, which can shift where checks land and whether implicit cleanup handlers get added. That unpredictability, plus the fact that raising and reraising exceptions basically amounts to calling "noreturn" functions, is why no-xthrow is the default. It only excludes internal functions used to (re)raise exceptions, which those optimizations don't touch ✨
-fhardened— the glow-up flag 🎀 It turns on a bundle of flags for C and C++ that boost security of the generated code without changing its ABI. The exact list can shift between major GCC releases, but right now it's:
-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 full list with --help=hardened 👑
If the system glibc is older than 2.35, -D_FORTIFY_SOURCE=2 gets used instead. 🧚
This one is meant for production builds, not just debug builds, so don't be shy about using it for the real stuff 🔥
Right now -fhardened is only supported on GNU/Linux targets. 🌈
Also: -fhardened only enables a particular option if it wasn't already set anywhere on the command line. For example, -fhardened -fstack-protector will only enable -fstack-protector, not -fstack-protector-strong 💅
-fstack-protector— adds extra code to catch buffer overflows, like stack smashing attacks 🛡️ It works by adding a guard variable to functions with vulnerable objects. That includes functions that callalloca, plus functions with buffers of 8 bytes or more. The guards get initialized on function entry and checked on exit. If a guard check fails, an error message gets printed and the program exits. Only variables actually allocated on the stack count, so optimized-away variables or ones living in registers are ignored 🦋-fstack-protector-all— same as-fstack-protector, except every function gets 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. Again, only variables actually allocated on the stack count; optimized-away or register variables don't 🔥
NOTE: In Ubuntu 14.10 and later,-fstack-protector-strongis enabled by default for C, C++, ObjC, and ObjC++, as long as none of-fno-stack-protector,-nostdlib, or-ffreestandingare found. 💀
-fstack-protector-explicit— like-fstack-protector, but it only protects functions that have the "stack_protect" attribute 🎀-fstack-check— generates code to verify you don't go past the boundary of the stack. You should specify this if you're running with multiple threads, but you rarely need it single-threaded, since stack overflow gets detected automatically on nearly all systems when there's only one stack 🧚
Heads up: this switch doesn't actually do the checking itself. The operating system or language runtime has to do that. The switch just generates code that makes sure they see the stack being extended 🌸
You can add a string parameter:
no— no checking at allgeneric— forces the old-style checkingspecific— uses the best checking method, and is equivalent to bare-fstack-check
Old-style checking is a generic mechanism that needs no special target support in the compiler, but it comes with some drawbacks:
- Modified allocation strategy for large objects: they're always allocated dynamically once their size exceeds a fixed threshold. This may change the semantics of some code.
- Fixed limit on the size of the static frame of functions: when a particular function tops it, stack checking isn't reliable, and the compiler issues a warning.
- Inefficiency: because of both the modified allocation strategy and the generic implementation, performance takes a hit.
Old-style stack checking is also the fallback for specific if the compiler has no target support 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 isn't 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 🛡️ With this on, the compiler only allocates one page of stack space at a time, and each page gets accessed right after allocation. So allocations can't jump over any stack guard page the operating system provides ✨
Most targets don't fully support this. On those targets, -fstack-clash-protection still 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, -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 so the stack doesn't grow past a certain value, either the value of a register or the address of a symbol. If a bigger stack is needed, a signal gets raised at run time. On most targets the signal goes off before the stack overruns the boundary, so you can catch it without any special precautions 🦋
For example, if the stack starts at absolute address 0x80000000 and grows downwards, you can use -fstack-limit-symbol=__stack_limit and -Wl,--defsym,__stack_limit=0x7ffe0000 to enforce a stack limit of 128KB. Note this may only work with the GNU linker. 🧚
You can locally override stack limit checking with the "no_stack_limit" function attribute. 💅
-fsplit-stack— generates code that automatically splits the stack before it overflows. The result is a discontiguous stack that can only overflow if the program can't allocate any more memory. This is super useful for threaded programs, since you no longer need to calculate a good stack size for each thread 🧵 It's currently only implemented for x86 targets running GNU/Linux.
When code compiled with -fsplit-stack calls code compiled without it, there may not be much stack space left for the latter code to run. If compiling everything (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 implemented in the gold linker in GNU Binutils release 2.21 and later. 🌸
-fstrub=disable— disables stack scrubbing entirely, ignoring any "strub" attributes 🙅♀️-fstrub=strict— functions default to "strub" mode "disabled", and strictly apply the restriction that only functions associated with "strub"-"callable" modes ("at-calls", "callable" and "always_inline" "internal") can be "callable" by functions with "strub"-enabled modes ("at-calls" and "internal") 🔒-fstrub=relaxed— okay so this one resets stack scrub ("strub") back to its default, which means "strub" only kicks in when function and data types have "strub" attributes attached 🧹 "Relaxed" just means strub contexts can't call functions that are explicitly tagged with "strub" mode "disabled". It's 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 🦋 This is mostly for testing, to put the "strub" machinery through its paces in scenarios that stay inside a single translation unit. Since this mode changes function interfaces, any function that's visible to other translation units, or that has its address taken, won't be affected. Optimization options can also change viability. Check the "strub" attribute documentation for the full viability and eligibility rules 📖-fstrub=internal— enables "internal" "strub" mode where viable 🧪 Also mainly for testing. It's built to thoroughly exercise the parts of the "strub" machinery that do the less efficient but interface-preserving "strub" mode. Functions this option wouldn't affect are pretty rare 🙈-fstrub=all— enables some "strub" mode where viable 🔥 If both modes are viable, "at-calls" wins.-fdump-ipa-strubmadds function attributes that show which mode got picked for each function. This one is primarily for testing, so you can really stress-test the "strub" machinery 💪-fvtable-verify=[std|preinit|none]— C++ only, bestie! 💜 This turns on the security feature that checks at run time, for every virtual call, that the vtable pointer being used is valid for the object's type and hasn't been corrupted or overwritten. Pass-fvtable-verify=noneto turn it off. If a bad vtable pointer gets caught, an error is reported and the program halts immediately 🚨
This option builds run-time data structures at program startup, and those are what check the vtable pointers. The std and preinit values control when those structures get built. Either way, they're built before execution reaches main. -fvtable-verify=std builds them after shared libraries have been loaded and initialized, while -fvtable-verify=preinit builds them before the shared libraries are loaded and initialized ⏰
If this option shows up more than once on the command line with different values, none takes the highest priority over both std and preinit, and preinit beats std 👑
-fvtv-debug— this one only works alongside-fvtable-verify=stdor-fvtable-verify=preinit🔍 It makes the compiler call the debug versions of the vtable verification runtime functions, and it also logs which vtable pointers it finds for each class. That info goes into a file calledvtv_set_ptr_data.log, saved in the directory named by the environment variableVTV_LOGS_DIRif it's defined, or the current working directory if it isn't 🗂️
Heads up, this feature appends to the log file! If you want a fresh one, delete any existing log first 🙈
-fvtv-counts— a debugging flag, and a very nerdy-iconic one 🤓 Used with-fvtable-verify=stdor-fvtable-verify=preinit, it makes the compiler keep track of the total number of virtual calls it runs into and how many verifications it inserts. It also counts the calls to certain run-time library functions it adds, and logs all of that for each compilation unit 📊 Results go tovtv_count_data.login the directory named byVTV_LOGS_DIRif that's defined, otherwise the current working directory. It also counts the size of the vtable pointer sets for each class and writes that tovtv_class_set_sizes.login the same directory 🌈
Same deal here: this appends to the log files, so delete any existing ones if you want fresh logs 💀
-finstrument-functions— generates instrumentation calls for entry and exit of functions ✨ Right after a function is entered and right before it exits, these profiling functions get called with the address of the current function and its call site:
void __cyg_profile_func_enter (void *this_fn,
void *call_site);
void __cyg_profile_func_exit (void *this_fn,
void *call_site);(On some platforms, __builtin_return_address doesn't work beyond the current function, so the call site info might not be available to the profiling functions otherwise 🙃)
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 have to be available. If all your uses of a function get expanded inline, this might add extra code size. If you use extern inline in your C code, an addressable version of those functions must be provided. (This is usually the case anyway, but if you got lucky and the optimizer always expanded them inline, you might have gotten away without static copies 😭)
A function can be given the attribute no_instrument_function, and then this instrumentation won't happen for it 🛑 That's handy for 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 basically-finstrument-functions, but the profiling functions only get called once per instrumented function 🎀 The first profiling function gets called after the first entry into the instrumented function, and the second one gets 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 it only guarantees that the profiling functions are 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-functions) 🚫 If the file containing a function definition matches one of the files in the list, that function won't be instrumented. The match is done on substrings: if the file parameter is a substring of the file name, it counts as a match.
For example:
-finstrument-functions-exclude-file-list=/bits/stl,include/sysThis 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 sym, 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 the file list one, but this option sets the list of function names to exclude from instrumentation 🧁 The name that gets matched is its user-visible name, likevector<int> blah(const vector<int> &), not the internal mangled name (like_Z4blahRSt6vectorIiSaIiEE). The match is done on substrings too: if the sym parameter is a substring of the function name, it's 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]— generates N NOPs right at the beginning of each function, with the function entry point before the Mth NOP 🦋 If M is left out, it defaults to 0, so the function entry points to the address right at the first NOP. Those NOP instructions reserve extra space that can be used to patch in any instrumentation you want at run time, as long as the code segment is writable. You control the amount of space indirectly through the number of NOPs. The NOP instruction used matches what the internal GCC back-end interfacegen_nopemits. This behavior is target-specific and may also depend on the architecture variant and/or other compilation options 🖥️
For run-time identification, the starting addresses of these areas (which match their respective function entries minus M) also get collected in the __patchable_function_entries section of the resulting binary 🗺️
Note that the value of __attribute__ ((patchable_function_entry (N,M))) takes precedence over the command-line option -fpatchable-function-entry=N,M 👑 This can be used to increase the area size, or to remove it completely on a single function. If N=0, no pad location is recorded.
The NOP instructions go at the function entry address (and maybe before it, depending on M), even before the prologue 🌙 On PowerPC with the ELFv2 ABI, for a function with dual entry points, the local entry point is this function entry address by default. See the -msplit-patch-nops option to change that 🔧
The maximum value of N and M is 65535. On PowerPC with the ELFv2 ABI, for a function with dual entry points, the supported values for M are 0, 2, 6 and 14 when not using -msplit-patch-nops 💖
✨ Options Controlling the Preprocessor ✨
These options control the C preprocessor, which is run on each C source file before actual compilation 🌸
If you use the -E option, nothing is done except preprocessing 💅 Some of these options only make sense with -E, because they make the preprocessor output unsuitable for actual compilation 🙈
Okay so there are also a bunch of options for controlling search paths for include files 🗺️, which you'll find in Directory Options. The ones that control preprocessor diagnostics live in Warning Options ⚠️
-D name,--define-macro=name,--define-macro name— predefine name as a macro, with the definition1💖-D name=definition,--define-macro=name=definition,--define-macro name=definition— ✨ the definition gets tokenized and processed as if it showed up during translation phase three in a#definedirective. Important bit, bestie: embedded newline characters truncate the definition 🪓- If you're invoking the preprocessor from a shell (or something shell-like), you might need the shell's quoting syntax to protect characters like spaces, since they mean something to the shell 🐚
- Want a function-like macro on the command line? Write its argument list in parentheses before the equals sign (if there is one). Parentheses mean stuff to most shells, so you should quote the option 🙈 With
shandcsh,-D'name(args...)=definition'works 💅 -Dand-Uoptions get processed in the order you give them on the command line. All-imacros fileand-include fileoptions get processed after all the-Dand-Uones 🫶
-U name,--undefine-macro=name,--undefine-macro name— cancel any previous definition of name, whether it was built in or came from a-Doption 🗑️-include file,--include=file,--include file— processes file as if#include "file"appeared as the first line of the primary source file 📄 The twist: the first directory searched for file is the preprocessor's working directory, not the directory containing the main source file 🧭 If it isn't found there, it gets searched for in the rest of the#include "..."search chain as normal.- If you give multiple
-includeoptions, the files get included in the order they appear on the command line 🔢
- If you give multiple
-imacros file,--imacros=file,--imacros file— exactly like-include, except any output produced by scanning file is thrown away 🧼 Macros it defines stay defined. This lets you grab all the macros from a header without also processing its declarations 🪄- All files specified by
-imacrosget processed before all files specified by-include👑
- All files specified by
-undef— don't predefine any system-specific or GCC-specific macros 🙅♀️ The standard predefined macros stay defined 💜-pthread— defines additional macros required for using the POSIX threads library 🧵 You should use this option consistently for both compilation and linking ‼️ It's supported on GNU/Linux targets, most other Unix derivatives, and also on x86 Cygwin and MinGW targets 🌈-M,--dependencies— instead of outputting the preprocessed result, output a rule suitable formakedescribing the dependencies of the main source file 🧩 The preprocessor outputs one make rule containing the object file name for that source file, a colon, and the names of all the included files, including those coming from-includeor-imacroscommand-line options 📜- Unless you specify it explicitly (with
-MTor-MQ), the object file name is the name of the source file with any suffix replaced by the object file suffix, and with any leading directory parts removed 🪄 - If there are many included files, the rule gets split into several lines using
\-newline📏 - The rule has no commands 🚫
- This option does not suppress the preprocessor's debug output, such as
-dM🙈 To avoid mixing that debug output with the dependency rules, explicitly specify the dependency output file with-MF, or use an environment variable likeDEPENDENCIES_OUTPUT🫶 Debug output still goes to the regular output stream as normal. - Passing
-Mto the driver implies-E, and suppresses warnings with an implicit-w🤫
- Unless you specify it explicitly (with
-MM,--user-dependencies— like-M, but doesn't mention header files found in system header directories, nor header files that are included, directly or indirectly, from such a header 🙅♀️- This implies that the choice of angle brackets or double quotes in an
#includedirective does not, by itself, determine whether that header appears in-MMdependency output 🎀
- This implies that the choice of angle brackets or double quotes in an
-MF file— when used with-Mor-MM, specifies a file to write the dependencies to 📝 If no-MFswitch is given, the preprocessor sends the rules to the same place it would send preprocessed output.- When used with the driver options
-MDor-MMD,-MFoverrides the default dependency output file 🔁 - If file is
-, the dependencies are written to stdout 🖥️
- When used with the driver options
-MG,--print-missing-file-dependencies— in conjunction with an option like-Mrequesting 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 directly from the#includedirective, without prepending any path 📍-MGalso suppresses preprocessed output, since a missing header file renders that useless 🗑️- This feature is used in automatic updating of makefiles 🤖
-Mno-modules— disables dependency generation for compiled module interfaces 🚫📦-MP— this instructs CPP to add a phony target for each dependency other than the main file, causing each one to depend on nothing 🪄 These dummy rules work around errorsmakegives if you remove 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 emitted by dependency generation 🎯 By default, CPP takes the name of the main input file, deletes any directory components and any file suffix such as.c, and appends the platform's usual object suffix. That result is the target.- An
-MToption sets the target to be exactly the string you specify 💯 If you want multiple targets, you can specify them as a single argument to-MT, or use multiple-MToptions 🧁
- An
For example, -MT '$(objpfx)foo.o' might give:
$(objpfx)foo.o: foo.c-MQ target— same as-MT, but it quotes any characters which are special to Make 🧷-MQ '$(objpfx)foo.o'gives:
$$(objpfx)foo.o: foo.cThe default target is automatically quoted, as if it were given with -MQ 🫧
-MD,--write-dependencies— equivalent to-M -MF file, except that-Eis not implied 💾 The driver determines file based on whether an-ooption is given. If it is, the driver uses its argument but with a suffix of.d. Otherwise, it takes the name of the input file, removes any directory components and suffix, and applies a.dsuffix.- If
-MDis used in conjunction 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
-Eis not implied,-MDcan be used to generate a dependency output file as a side effect of the compilation process 🌈
- If
-MMD,--write-user-dependencies— like-MD, but only mentions user header files, not system header files 🧑💻-fpreprocessed— indicates to the preprocessor that 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 problems 💅 In this mode the integrated preprocessor is little more than 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🗂️
-fdirectives-only— when preprocessing, handle directives, but do not expand macros 🪄 How it behaves depends on-Eand-fpreprocessed:- With
-E, preprocessing is limited to handling directives such as#define,#ifdef, and#error📐 Other preprocessor operations, such as macro expansion and trigraph conversion, are not performed 🙅♀️ On top of that, the-dDoption is implicitly enabled 💡 - With
-fpreprocessed, predefinition of command line and most builtin macros is disabled 🧹 Macros such as__LINE__, which are contextually dependent, are handled normally ✅ This enables compilation of files previously preprocessed with-E -fdirectives-only🎁 - With both
-Eand-fpreprocessed, the rules for-fpreprocessedtake precedence 👑 This enables full preprocessing of files previously preprocessed with-E -fdirectives-only💖
- With
-fdollars-in-identifiers— accept$in identifiers 💲-fextended-identifiers— accept universal character names and extended characters in identifiers 🌍 This option is enabled by default for C99 (and later C standard versions) and C++ 🎀-fno-canonical-system-headers— when preprocessing, do not shorten system header paths with canonicalization 🛣️-fmax-include-depth=depth— set the maximum depth of the nested#include🪆 The default is200.-fsearch-include-path[=kind]— look for input files on the#includepath, not just the current directory 🗺️ This is particularly useful with C++20 modules, for which both header units and module interface units need to be compiled directly 🧚 Like this:
g++ -c -std=c++20 -fmodules -fsearch-include-path bits/stdc++.h bits/std.cckind defaults to user, which looks on the #include "..." search path 🧭 You can also explicitly specify system for the #include <...> search path 🫶
-ftabstop=width— set the distance between tab stops 📏 This helps the preprocessor report correct column numbers in warnings or errors, even if tabs appear on the line 🔢 If the value is less than1or greater than100, the option is ignored. The default is8.-ftrack-macro-expansion[=level]: okay bestie, this one tracks where tokens come from across macro expansions 🔍✨ So when something breaks inside a macro, the compiler can show you the whole macro expansion stack in its diagnostics 💅 Heads up, though: the preprocessor and compiler eat more memory with it on 🫠 The level lets you dial back the precision to save memory if you need to 🦋0deactivates this option 🙅1runs in a degraded mode for minimal memory overhead 🧃 All tokens from the expansion of an argument of a function-like macro end up with the same location.2tracks token locations completely 🔥 It's the most memory hungry one, periodt.- If you give no argument, the default is
2.
Note that -ftrack-macro-expansion=2 is activated by default 💜
-fmacro-prefix-map=old=new: when preprocessing files living in directoryold, the__FILE__and__BASE_FILE__macros expand as if those files were in directorynewinstead 🗺️ Using.fornewis a glow-up for turning absolute paths into relative ones, which can make your builds more reproducible and location independent 🌸 This also affects__builtin_FILE()during compilation. See also-ffile-prefix-mapand-fcanon-prefix-map🎀-fexec-charset=charset: sets the execution character set, which is used for string and character constants 💬 The default isUTF-8💖charsetcan be any encoding the 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 being used for code generation 🦋 Like-fexec-charset,charsetcan be any encodingiconvsupports, but you'll have problems with encodings that don't fit exactly inwchar_t😭-finput-charset=charset: sets the input character set, used to translate from the character set of the input file to the source character set GCC uses 📥 If the locale doesn't specify it, or GCC can't get it from the locale, the default isUTF-8. The locale or this command-line option can override it, but right now the command-line option takes precedence if there's a conflict 👑charsetcan be any encoding the system'siconvlibrary routine supports.-fpch-deps: when you're using precompiled headers, this flag 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 aren't consulted when a precompiled header is used 🙈-fpch-preprocess: lets you use a precompiled header together with-E🧩 It inserts a special#pragma,#pragma GCC pch_preprocess "filename", into the output to mark the place where the precompiled header was found, along with its filename 📍 When-fpreprocessedis in use, GCC recognizes that#pragmaand loads the PCH 🫶- It's 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
#pragmain your own code, bestie 🚫 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 linemarkers in the preprocessor output that tell the compiler the current working directory at the time of preprocessing 🗂️ When this is on, the preprocessor emits, after the initial linemarker, a second linemarker with the current working directory followed by two slashes 🎀 GCC uses that directory, when it's present in the preprocessed input, as the directory emitted as the current working directory in some debugging information formats ✨ This is implicitly enabled if debugging information is enabled, but you can block it with the negated form-fno-working-directory🙅 If the-Pflag is in the command line, this option does nothing, since no#linedirectives get emitted whatsoever 💀-C,--comments: don't toss the comments 💬 All comments get passed through to the output file, except comments in processed directives, which are deleted along with the directive 🗑️- Be prepared for side effects when you use
-C😵 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#💀
- Be prepared for side effects when you use
-CC,--comments-in-macros: keeps 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 🌷- On top of the side effects of
-C,-CCconverts all C++-style comments inside a macro into C-style comments 🛡️ That stops a later use of that macro from accidentally commenting out the rest of the source line 😤 -CCis generally used to support lint comments 🧹
- On top of the side effects of
-P,--no-line-commands: inhibits linemarkers in the output from the preprocessor 🚫📍 This might be handy when you run the preprocessor on something that isn't C code and send it to a program that might get confused by the linemarkers 🫠-traditional,--traditional,-traditional-cpp,--traditional-cpp: tries to imitate pre-standard C preprocessors, as opposed to the ISO C ones 🕰️ Check the GNU CPP manual for all the details 📖- GCC doesn't otherwise try to emulate a pre-standard C compiler 🙅, and these options are only supported with the
-Eswitch, or when you invoke CPP explicitly 💅
- GCC doesn't otherwise try to emulate a pre-standard C compiler 🙅, and these options are only supported with the
-trigraphs,--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:
Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
Replacement: [ ] { } # \ ^ | ~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,--trace-includes: prints the name of each header file used, in addition to other normal activities 🔎 Each name is indented to show how deep it is in the#includestack 🪜 Precompiled header files get printed too, even if they're found to be invalid 🙈 An invalid precompiled header file is printed with...x, and a valid one with...!.-dletters,--dump=letters,--dump letters: makes debugging dumps during compilation as specified by letters 🧪 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,--dump=M: 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 is 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,--dump=D: like-dM, except it outputs both the#definedirectives and the result of preprocessing 🎁 Both kinds of output go to the standard output file 📤-dN,--dump=N: like-dD, but emits only the macro names, not their expansions 🫧-dI,--dump=I: outputs#includedirectives in addition to the result of preprocessing 📑-dU,--dump=U: 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 ⏳#undefdirectives are also output for macros that were tested but undefined at the time 🧹
-fdebug-cpp: this option is only useful for debugging GCC itself 🛠️ When used from CPP or 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: lets you bypass the compiler driver and passoptiondirectly through to the preprocessor 🚀 Ifoptioncontains commas, it is split into multiple options at the commas ✂️ Many options are modified, translated, or interpreted by the compiler driver before being passed to the preprocessor, and-Wpforcibly bypasses this phase ⚠️
The preprocessor's direct interface is undocumented and subject to change, so whenever possible you should avoid using -Wp and let the driver handle the options instead 🫶
-Xpreprocessor option: passesoptionalong as an option to the preprocessor 🎀 You can use this to supply system-specific preprocessor options that GCC doesn't recognize 💻- If you want to pass an option that takes an argument, you must use
-Xpreprocessortwice: once for the option and once for the argument 👯
- If you want to pass an option that takes an argument, you must use
-no-integrated-cpp,--no-integrated-cpp— okay so normally GCC does preprocessing right inside tokenizing and parsing, all smooth and integrated ✨ But if you pass this one, GCC does preprocessing as its own separate pass before compiling. The language front end (cc1,cc1plus, orcc1objfor C, C++, and Objective-C, respectively) gets called twice instead: once for preprocessing only, and once to actually compile the preprocessed input 🧚. It's lowkey super useful when you pair it with-Bor-wrapperto swap in a different preprocessor or do extra processing on your source between preprocessing and compiling 💅
🎀 Passing Options to the Assembler 🎀
You can pass options to the assembler, bestie 🫶
-Wa,option— sendsoptionalong to the assembler 📨 Ifoptionhas commas in it, it gets chopped into multiple options at every comma.-Xassembler option,--for-assembler=option,--for-assembler option— same vibe, sendsoptionto the assembler 💖 This is your escape hatch for system-specific assembler options that GCC doesn't recognize yet.
If you want to pass an option that takes an argument, you must use -Xassembler twice, once for the option and once for the argument 😭 Don't skip it or it won't slay.
🔗 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, so don't expect them to do anything otherwise 🙈
object-file-name— a file name that doesn't end in a special recognized suffix is treated as an object file or library 🍓 (The linker tells objects apart from libraries by looking at the file contents.) If linking happens, these object files get fed into the linker as input.-c,-S,-E— if any of these is used, the linker doesn't run at all 🚫 So object file names shouldn't be used as arguments.-flink-libatomic— enables linking of libatomic if the target supports it, and it's on by default ✨ The negative form-fno-link-libatomicexplicitly turns linking of libatomic off.-flinker-output=type— this one controls code generation for the link-time optimizer 🌈 By default the linker plugin figures out the linker output automatically. But 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. Here's the tea on each type:exec— code generation produces a static binary. In this case-fpicand-fpieare both disabled.dyn— code generation produces a shared library. In this case-fpicor-fPICis 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 🦋pie— code generation produces an-fpieexecutable. You get similar optimizations asexec, except-fpieisn't disabled if you specified it at compilation time.rel— the compiler assumes incremental linking is happening. The sections holding intermediate code for link-time optimization get merged, pre-optimized, and output to the resulting object file. Also, if-ffat-lto-objectsis 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, and at link time it loads faster than a static library, assuming most of the objects in the library get used.nolto-rel— the compiler is set up 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 (cross-module inlining happens, for example), but most of the perks of whole-program optimizations are lost.
During an incremental link (by -r), the linker plugin defaults to rel. You need GNU Binutils 2.44 or later 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 uses nolto-rel. To keep whole-program optimization, link those objects into a static library instead.
-fuse-ld=bfd— uses the bfd linker instead of the default linker.-fuse-ld=gold— uses the gold linker instead of the default linker.-fuse-ld=lld— uses the LLVM lld linker instead of the default linker.-fuse-ld=mold— uses the Modern Linker (mold) instead of the default linker 🚀-fuse-ld=wild— uses the Wild linker (wild) instead of the default linker 🦖-llibrary,-l library— searches the library named library when linking 🌸 (The second version, with the library as a separate argument, is only there for POSIX compliance and isn't recommended, bestie.)
The -l option gets passed straight through to the linker by GCC, so check your linker docs for the exact details. The general description below applies to the GNU linker 🧚
The linker searches a standard list of directories for the library. Those include several standard system directories, plus any you add with -L 📂
Static libraries are archives of object files and have file names like liblibrary.a. Some targets also support shared libraries, which usually have names like liblibrary.so. If both static and shared libraries are found, the linker prefers the shared one unless the -static option is used 🫧
Where you write this option in the command actually 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— you need this special case of the-loption to link an Objective-C or Objective-C++ program 🌈-nostartfiles— don't use the standard system startup files when linking ✨ The standard system libraries are still used normally, unless-nostdlib,-nolibc, or-nodefaultlibsis used.-nodefaultlibs— don't use the standard system libraries when linking 🙅♀️ Only the libraries you specify get passed to the linker, and options that set the linkage of 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". Those entries are usually resolved by entries in libc. When this option is specified, these entry points need to be supplied some other way 🫶
-nolibc— don't use the C library or the system libraries tightly coupled with it when linking 💅 You still link with the startup files, libgcc, or toolchain-provided language support libraries such as libgnat, libgfortran, or libstdc++, unless options preventing their inclusion are used too. This usually 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. It's meant for bare-board targets where there's genuinely no C library available 🤖-nostdlib,--no-standard-libraries— don't use the standard system startup files or libraries when linking 🙈 No startup files get passed, only the libraries you specify, and options that set the linkage of system libraries, like-static-libgccor-shared-libgcc, are ignored.
The compiler may generate calls to "memcmp", "memset", "memcpy" and "memmove". Those entries are usually resolved by entries in libc. When this option is specified, these entry points need to be supplied some other way 🫶
One of the standard libraries skipped by -nostdlib and -nodefaultlibs is libgcc.a, a library of internal subroutines that GCC uses to work around shortcomings of particular machines, or to meet 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. That way you won't have any unresolved references to internal GCC library subroutines 💖 (An example of one of those internal subroutines is "__main", which makes sure C++ constructors get called.)
-nostdlib++— don't implicitly link with standard C++ libraries.-e entry,--entry=entry,--entry entry— sets the program entry point to entry 🚪 The linker interprets the argument: the GNU linker accepts either a symbol name or an address.-pie,--pie— produces a dynamically linked position independent executable on targets that support it 🦋 For predictable results, you also need to specify the same set of options used for compilation (-fpie,-fPIE, or model suboptions) when you use this linker option.-no-pie— don't produce a dynamically linked position independent executable.-static-pie,--static-pie— produces a static position independent executable on targets that support it 🌟 It's similar to a static executable, but it can be loaded at any address without a dynamic linker. For predictable results, you also need to specify the same set of options used for compilation (-fpie,-fPIE, or model suboptions) when you use this linker option.-pthread— links with the POSIX threads library 🧵 This option is supported on GNU/Linux targets, most other Unix derivatives, and also on x86 Cygwin and MinGW targets. On some targets it also sets flags for the preprocessor, so use it consistently for both compilation and linking, periodt 💅-r— produces a relocatable object as output. This is also known as partial linking 🧩-rdynamic— okay so this one tells the ELF linker to pass-export-dynamic, but only on targets that actually support it 💅. It basically shoves every symbol into the dynamic symbol table, not just the ones being used 🦋. You'll want it for somedlopensetups, or if you need backtraces from inside your program 🔍.-s— literally strips all the symbol table and relocation info out of the executable 🧹 clean girl energy.-static,--static— on systems that support dynamic linking, this overrides-pieand stops linking with shared libraries 🚫. On other systems it does nothing at all 💀.-shared,--shared— makes a shared object that you can link with other objects to build an executable ✨. Not every system supports this one 😭. For predictable results, you also have to use the same set of options you compiled with (-fpic,-fPIC, or model suboptions) when you use this linker option.[1]-shared-libgcc,-static-libgcc— on systems that ship libgcc as a shared library, these force the shared or the static version, respectively 🌈. If no shared version of libgcc was built when the compiler was configured, these do nothing 🙈.
There are a few situations where an app should use the shared libgcc instead of the static one 🫶. The biggest one is when the app wants to throw and catch exceptions across different shared libraries. In that case, every one of those libraries and the app itself should be using the shared libgcc.
So the G++ driver automatically adds -shared-libgcc whenever you build a shared library or a main executable 👑. C++ programs usually use exceptions, so this is the correct move, bestie.
If you use the GCC driver to make shared libraries instead, they might not always end up linked with the shared libgcc 🤔. If GCC finds out at 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 uses the linker's smarts and skips linking with the shared libgcc, so it links the static version by default instead 🧠. This lets exceptions propagate through those shared libraries without taking on relocation costs at library load time ⚡.
However, if a library or main executable is supposed to throw or catch exceptions, you must link it with the G++ driver, or use the option -shared-libgcc, so it gets linked with the shared libgcc. Don't skip this one, it's the main character of the whole section 🎀
-static-libasan— when-fsanitize=addressis used to link a program, the GCC driver automatically links against libasan 🔍. If libasan is available as a shared library and-staticisn't used, it links the shared version. This option tells the GCC driver to link libasan statically, without necessarily linking other libraries statically 🦋.-static-libtsan— when-fsanitize=threadis used to link a program, the GCC driver automatically links against libtsan 🧵. If libtsan is available as a shared library and-staticisn't used, it links the shared version. This option tells the GCC driver to link libtsan statically, without necessarily linking other libraries statically 🌸.-static-liblsan— when-fsanitize=leakis used to link a program, the GCC driver automatically links against liblsan 🫧. If liblsan is available as a shared library and-staticisn't used, it links the shared version. This option tells the GCC driver to link liblsan statically, without necessarily linking other libraries statically 💜.-static-libubsan— when-fsanitize=undefinedis used to link a program, the GCC driver automatically links against libubsan 🍓. If libubsan is available as a shared library and-staticisn't used, it links the shared version. This option tells 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-staticisn't used, it links the shared version, and that's normally totally 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 tells theg++driver to link libstdc++ statically, without necessarily linking other libraries statically 💅.-symbolic,--symbolic— binds references to global symbols when building a shared object 🔗. It also warns about any unresolved references (unless you override that with the link editor option-Xlinker -z -Xlinker defs) ⚠️. Only a few systems support this one, so don't be shocked if it's not there 🙈.-T script— usesscriptas the linker script 📜. This is supported by most systems using the GNU linker. On some targets, like bare-board targets with no operating system, you might need-Twhen linking so you don't end up with references to undefined symbols 😭.-Xlinker option— passesoptionstraight through to the linker 🎀. Perfect for 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 write -Xlinker -assert -Xlinker definitions. Writing -Xlinker "-assert definitions" does not work, because that passes the whole string as a single argument, and the linker is not having it 💀.
When you're using the GNU linker, it's usually way more convenient to pass arguments 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. Other linkers might not support this syntax for command-line options 🤷♀️.
-Wl,option,--for-linker=option,--for-linker option— passesoptionto the linker too 🧚. Ifoptionhas commas in it, it gets split into multiple options at those commas. This is how you give an argument to the option:-Wl,-Map,output.mappasses-Map output.mapto the linker 🗺️. With the GNU linker you can also 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🙈 heads up bestie.
-u symbol,--force-link=symbol,--force-link symbol— pretends the symbolsymbolis undefined, which forces linking of library modules that define it 🧲. You can use-umultiple times with different symbols to force loading of additional library modules 🌈.-Tbss=addr— passed straight through to the linker without GCC touching it 🔁.-Tdata=addr— passed straight through to the linker without GCC touching it 🔁.-Ttext=addr— passed straight through to the linker without GCC touching it 🔁.-N— passed straight through to the linker without GCC touching it 🔁.-n— passed straight through to the linker without GCC touching it 🔁.-t— passed straight through to the linker without GCC touching it 🔁.-Z— passed straight through to the linker without GCC touching it 🔁.-z keyword— passed straight through to the linker without GCC touching it 🔁.
These are all passed through to the linker without GCC interpreting them 🫶. Check your linker documentation for what they actually mean, because GCC isn't going to explain them for you 📖.
✨ Options for Directory Search ✨
These options tell GCC which directories to search for header files, libraries and parts of the compiler 🗂️:
-I dir— addsdirto the list of directories searched for header files during preprocessing 📂.--include-directoryis an alias for-I, while--include-directory-afteris an alias for-idirafter. Ifdirbegins with=or$SYSROOT, then the=or$SYSROOTgets replaced by the sysroot prefix; see--sysrootand-isysroot🌸.-iquote dir— directories specified this way only apply to the quote form of the directive,#include "file"💬.-isystem dir— applies to lookup for both#include "file"and#include <file>directives 🔍.-idirafter dir— applies to lookup for both#include "file"and#include <file>directives 🔍.--include-directory-after=dir— alias for-idirafter🪞.--include-directory-after dir— alias for-idirafter🪞.--include-directory=dir— alias for-I🪞.--include-directory dir— alias for-I🪞.
You can use any number or combination of these on the command line to search for headers in several directories at once 🧩. 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 swap in your own version, since these directories get searched before the standard system header directories 🔄. But don't use this option to add directories that hold vendor-supplied system headers. Use -isystem for those 🙅♀️.
The -isystem and -idirafter options also mark the directory as a system directory, so it gets the same special treatment as the standard system directories 🎀.
If a standard system include directory, or a directory specified with -isystem, is also specified with -I, the -I option gets ignored 🙃. The directory is still searched, but as a system directory at its normal position in the system include chain. This keeps GCC's procedure for fixing buggy system headers and the ordering for the #include_next directive from getting changed by accident 🛡️. If you really need to change the search order for system directories, use the -nostdinc and/or -isystem options 🫣.
-I-,--include-barrier— splits the include path 🚧. This option has been deprecated 😭. Please use-iquoteinstead for the-Idirectories that come before-I-, and remove the-I-option ✨.
Okay so the -I- thing is kinda sneaky 🙈 Any directories you pass with -I before -I- only get checked for "#include "file"" lookups. They are NOT searched for #include <file>. But if you add -I dirs after the -I-, those get searched for all #include directives 💖
And on top of that, -I- stops the directory of the current file from being the first place searched for #include "file" 🦋 There is no way to undo that effect of -I-, so use it wisely, bestie.
-iprefix prefix,--include-prefix=prefix,--include-prefix prefix— Setsprefixas the prefix for any later-iwithprefixoptions 🌸 If the prefix is a directory, make sure you include the final/.-iwithprefix dir,-iwithprefixbefore dir,--include-with-prefix=prefix,--include-with-prefix prefix,--include-with-prefix-after=prefix,--include-with-prefix-after prefix,--include-with-prefix-before=prefix,--include-with-prefix-before prefix— Tacksdironto the prefix you set earlier with-iprefix, then adds the result to the include search path ✨-iwithprefixbeforeputs it in the same spot-Iwould, and-iwithprefixputs it where-idirafterwould.
--include-with-prefix and --include-with-prefix-after are both aliases for -iwithprefix, and --include-with-prefix-before is an alias for -iwithprefixbefore 🧚
-isysroot dir— This one is like--sysroot, but it only applies to header files 🎀 The exception is Darwin targets, where it applies to both header files and libraries. Check the--sysrootoption for more info.-imultilib dir— Usesdiras a subdirectory of the directory holding target-specific C++ headers 💜-imultiarch dir— Usesdiras a subdirectory of the directory holding architecture-specific C++ headers 💜-nostdinc,--no-standard-includes— Skips the standard system directories when looking for headers 🙅 Only the dirs you explicitly pass with-I,-iquote,-isystem, and/or-idirafterget searched, plus the directory of the current file if it applies.-nostdinc++— Skips the C++-specific standard directories, but still searches the other standard ones 🌈 (This one is used when building the C++ library.)--embed-dir=dir,--embed-directory=dir,--embed-directory dir— Addsdirto the list of directories searched for the#embedpreprocessing directive or the__has_embedmacro 💅 There are no default directories for#embed.
If dir begins with = or $SYSROOT, that = or $SYSROOT gets swapped out for the sysroot prefix. See --sysroot and -isysroot for the deets.
-iplugindir=dir— Sets the directory to search for plugins that get passed with-fplugin=nameinstead of-fplugin=path/name.so🔥
🙈 This option is not meant to be used by you, the user. It's only passed by the driver.
-Ldir,--library-directory=dir,--library-directory dir— Adds directorydirto the list of directories searched for-l🦋-Bprefix,--prefix=prefix,--prefix prefix— This one tells the compiler where to find its own executables, libraries, include files, and data files 🌸
The compiler driver runs one or more of the subprograms cpp, cc1, as and ld. It tries prefix as a prefix for each program it runs, both with and without machine/version/ for the matching target machine and compiler version.
For each subprogram, the driver tries the -B prefix first, if you gave one. If that name isn't found, or if -B isn't specified, it 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 in the directories listed in your PATH environment variable.
The compiler checks whether the path given by -B is a directory, and if needed it adds a directory separator character to the end of the path 🫶
-B prefixes that effectively name directories also apply to libraries in the linker, since the compiler translates these options into -L options for the linker 👑 They also apply to include files in the preprocessor, since the compiler translates them into -isystem options for the preprocessor. In that 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 get tried, and that's it. If it still isn't found by those means, the file gets left out of the link.
Another way to specify a prefix, kinda like the -B prefix, is the environment variable GCC_EXEC_PREFIX ✨
As a special kludge, if the path given by -B is [dir/]stageN/, where N is a number from 0 to 9, it gets replaced by [dir/]include. This is there to help with boot-strapping the compiler 🤓
-no-canonical-prefixes,--no-canonical-prefixes— Stops the compiler from expanding symbolic links, resolving/../or/./, or making the path absolute when it generates a relative prefix 🧚--sysroot=dir,--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 searchesdir/usr/includeanddir/usr/libinstead.
If you use both this option and -isysroot, then --sysroot applies to libraries, and -isysroot applies to header files.
The GNU linker (beginning with version 2.16) has the support this option needs. If your linker doesn't support it, the header file side of --sysroot still works, but the library side doesn't 💔
--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 that suffix 🙅
🎀 Options for use with Picolibc 🎀
These options control compilation and linking when you're using picolibc 💖
--oslib=library— Searches the library namedlibraryafter the C library, so symbols the C library leaves undefined can be defined by this library ✨ The C library, libgcc, and this library get placed between--start-groupand--end-groupflags, so each one can refer to symbols in the others. For many targets, picolibc provides a semihost variant (specified with--oslib=semihost) that gives you enough basic OS functionality for console and file I/O when running in an emulator or using an in-circuit debugger.--crt0=[none|minimal|hosted|semihost]— Replaces the defaultcrt0.oname withcrt0-variant.o🦋 Thenonevariant gives you no startup code at all, so you can supply your own.minimaldoes basic memory setup but doesn't invoke any constructors. When no-crt0option is given, the default initialization code adds calls to all constructors.hostedadds a call toexitwhenmainreturns.semihostreads a command line parameter supplied through the semihosting interface, splits it into arguments at whitespace boundaries, and passes the resulting array of strings tomaininargcandargv. On some targets, including aarch64, arc, arm, loongarch, m68k, riscv, super-h and x86,semihostalso traps hardware exceptions and prints information to the console. Note that--crt0=semihostdepends on APIs provided by--oslib=semihost⚠️--printf=[d|f|l|i|m]— Picks the printf variant 🖨️ Picolibc has five printf variants, and each one offers less functionality but also smaller code size.dis the default and offers full C17 and POSIX.1-2024 conformance.fhas the same feature set, but supportsfloatvalues instead ofdouble, passed using theprintf_floatmacro.ldrops all floating point and POSIX positional parameter support.ilimits integers to those no larger thanlong.mremoves support for most formatting options, including width and precision. The formats and arguments still get parsed correctly, but the output doesn't respect those parameters 💀--scanf=[d|f|l|i|m]— Picks the scanf variant 🔍 Picolibc has five scanf variants with the same deal: less functionality and smaller code as you go down.dis the default and offers full C17 and POSIX.1-2024 conformance.fremoves support fordoublevalues.ldrops all floating point support.ilimits integers to those no larger thanlong.mremoves support for%[conversion specifiers.
💅 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. The negative form of -ffoo is -fno-foo. In the list 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.allenables stack reuse for all local variables and temporaries.named_varsenables reuse only for user-defined local variables that have names.nonedisables stack reuse completely. The default value isall.
This option is needed when the program extends the lifetime of a scoped local variable or a compiler-generated temporary beyond the end point the language defines. When a variable's lifetime ends, and the variable lives in memory, the optimizing compiler is free to reuse its stack space for 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, because one spooky pointer is never enough 👻🎀
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?
}Okay so the lifetime of a compiler generated temporary is well defined by the C++ standard 📜✨ When that lifetime ends and the temporary lives in memory, the optimizing compiler is allowed to reuse its stack space for other temporaries or scoped local variables whose live range does not overlap with it. 🦋 But ngl, some legacy code relies on older compilers where temporaries' stack space was never reused, so this aggressive stack reuse can lead to runtime errors 💀 This option is used to control that temporary stack reuse optimization.
-ftrapv— 🚨 This one makes the compiler generate traps for signed overflow on addition, subtraction and multiplication.-ftrapvand-fwrapvoverride each other, so-ftrapv -fwrapvon the command line means-fwrapvends up being the one that's effective. Only the options that are actually active get to override, so-ftrapv -fwrapv -fno-wrapvmakes-ftrapvthe effective one. 💅-fwrapv— 🌸 This tells the compiler to assume that signed arithmetic overflow of addition, subtraction and multiplication wraps around using twos-complement representation. It enables some optimizations and disables others, so it's giving trade-off energy. The same override drama applies here too:-ftrapvand-fwrapvoverride each other, so-ftrapv -fwrapvon the command line results in-fwrapvbeing effective, and-ftrapv -fwrapv -fno-wrapvresults in-ftrapvbeing effective, since only active options override.-fwrapv-pointer— 🧚 Same vibe, but for pointers. This tells the compiler to assume that pointer arithmetic overflow on addition and subtraction wraps around using twos-complement representation. It disables some optimizations that assume pointer overflow is invalid.-fstrict-overflow— 👑 This one implies-fno-wrapv -fno-wrapv-pointer, and when negated it implies-fwrapv -fwrapv-pointer.-fexceptions— 🔥 Enables exception handling and generates the extra code needed to propagate exceptions. On some targets this implies GCC generates frame unwind information for all functions, which can produce significant data size overhead, although it does not affect execution. If you don't specify this option, GCC enables it by default for languages like C++ that normally require exception handling, and disables it for languages like C that do not. You may still need to enable it when compiling C code that has to interoperate properly with exception handlers written in C++. You may also wish to disable it if you're compiling older C++ programs that don't use exception handling.-fnon-call-exceptions— 🌈 Generates code that allows trapping instructions to throw exceptions. ngl this needs platform-specific runtime support that doesn't exist everywhere. It only lets trapping instructions (memory references or floating-point instructions) throw exceptions. Exceptions cannot be thrown from arbitrary signal handlers such as "SIGALRM". This enables-fexceptions.-fdelete-dead-exceptions— 🧹 Instructions that may throw exceptions but don't otherwise contribute to the execution of the program can be optimized away. This does not affect calls to functions, except those with the "pure" or "const" attributes. This option is enabled by default for the Ada and C++ compilers, as permitted by the language specifications. Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels.-funwind-tables— 🦋 This is similar to-fexceptions, except it just generates any needed static data and doesn't affect the generated code in any other way. You normally don't need to enable it yourself, because a language processor that needs this handling enables it on your behalf.-fasynchronous-unwind-tables— ⭐ Generates an unwind table in DWARF format, if the target machine supports it. The table is exact at each instruction boundary, so it can be used for stack unwinding from asynchronous events (such as a debugger or garbage collector).-fno-gnu-unique— 🫶 On systems with a recent GNU assembler and C library, the C++ compiler uses the "STB_GNU_UNIQUE" binding to make sure that definitions of template static data members and static local variables in inline functions are unique, even in the presence of "RTLD_LOCAL". This is necessary to avoid problems with a library used by two different "RTLD_LOCAL" plugins that depend on a definition in one of them and therefore disagree with the other about the binding of the symbol. But this causes "dlclose" to be ignored for affected DSOs. If your program relies on reinitializing a DSO via "dlclose" and "dlopen", you can use-fno-gnu-unique.-fpcc-struct-return— 🎀 Returns "short" "struct" and "union" values in memory, like longer ones, rather than in registers. This convention is less efficient, but it has the advantage of allowing intercallability between GCC-compiled files and files compiled with other compilers, particularly 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 the-fpcc-struct-returnswitch is not binary compatible with code compiled with the-freg-struct-returnswitch. Use it to conform to a non-default application binary interface. 🙈
-freg-struct-return— 💜 Returns "struct" and "union" values in registers when possible. This is more efficient for small structures than-fpcc-struct-return.
If you specify neither -fpcc-struct-return nor -freg-struct-return, GCC defaults to whichever convention is standard for the target. If there is no standard convention, GCC defaults to -fpcc-struct-return, except on targets where GCC is the principal compiler. In those cases, we can choose the standard, and we chose the more efficient register return alternative.
Warning: code compiled with the-freg-struct-returnswitch is not binary compatible with code compiled with the-fpcc-struct-returnswitch. Use it to conform to a non-default application binary interface. 😭
-fshort-enums— 🍓 Allocates to an "enum" type only as many bytes as it needs for the declared range of possible values. Specifically, the "enum" type is equivalent to the smallest integer type that has enough room. This option has no effect for an enumeration type with a fixed underlying type.
Warning: the -fshort-enums switch causes GCC to 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 default for the target. This option is useful for building programs to run under WINE.
Warning: the -fshort-wchar switch causes GCC to 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 option controls the placement of global variables defined without an initializer, known as tentative definitions in the C standard. Tentative definitions are distinct from declarations of a variable with the "extern" keyword, which do not allocate storage.
The default is -fno-common, which means the compiler places uninitialized global variables in the BSS section of the object file. This inhibits the merging of tentative definitions by the linker, so you get a multiple-definition error if the same variable is accidentally defined in more than one compilation unit. 🚫
The -fcommon option places uninitialized global variables in a common block. This allows the linker to resolve all tentative definitions of the same variable in different compilation units to the same object, or to a non-tentative definition. This behavior is inconsistent with C++, and on many targets it implies a speed and code size penalty on global variable references. It is mainly useful for enabling legacy code to link without errors. 🧱
-fno-ident,-Qy,-Qn— 🤫-fno-identsuppresses the emission of.identassembler directives and causes the "#ident" preprocessor directive to be ignored.-Qyand-Qnare obsolete synonyms for-fidentand-fno-ident, respectively.-finhibit-size-directive— ✂️ Don't output a.sizeassembler directive, or anything else that would cause trouble if the function is split in the middle and the two halves are placed at locations far apart in memory. This option is used when compiling crtstuff.c; you should not need to use it for anything else.-fverbose-asm— 📝 Puts extra commentary information in the generated assembly code to make it more readable. This option is generally only of use to people who actually need to read the generated assembly code (perhaps while debugging the compiler itself).
-fno-verbose-asm, the default, causes the extra information to be omitted, and it's useful when 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,
...which high-level expressions line up with the various assembly instruction operands 💅
Okay so say we've got this C file 🌸
int test (int n)
{
int i;
int total = 0;
for (i = 0; i < n; i++)
total += i * i;
return total;
}Now we compile it to (x86_64) assembly with -S and shove the result straight to stdout with -o - 🧚
gcc -S test.c -fverbose-asm -Os -o -and you get something like 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 for humans, not machines 🙈 so the exact format of the comments is subject to change, bestie.
-frecord-gcc-switches 🎀
This switch causes the command line used to invoke the compiler to be recorded into the object file that is being created. It's only implemented on some targets, and the exact format of the recording is target and binary file format dependent, but it usually takes the form of a section containing ASCII text. This one is related to -fverbose-asm, but that switch only records info in the assembler output file as comments, so it never reaches the object file 😭 See also -grecord-gcc-switches for another way of storing compiler options into the object file.
-fpic 🦋
Generate position-independent code (PIC) suitable for use in a shared library, if supported for the target machine. Such code accesses all constant addresses through a global offset table (GOT). The dynamic loader resolves the GOT entries when the program starts (the dynamic loader is not part of GCC; it is part of the operating system). If the GOT size for the linked executable exceeds a machine-specific maximum size, you get an error message from the linker indicating that -fpic does not work. In that case, recompile with -fPIC instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k on the m68k and RS/6000. The x86 has no such limit.)
Position-independent code requires special support, and therefore works only 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 to 1.
-fPIC 🌈
If supported for the target machine, emit position-independent code, suitable for dynamic linking and avoiding any limit on the size of the global offset table. This option makes a difference on AArch64, m68k, PowerPC and SPARC.
Position-independent code requires special support, and therefore works only on certain machines.
When this flag is set, the macros "__pic__" and "__PIC__" are defined to 2.
-fpie, -fPIE 💜
These options are similar to -fpic and -fPIC, but the generated position-independent code can only be linked into executables. Usually these options are used to compile code that will be linked using the -pie GCC option.
-fpie and -fPIE both define the macros "__pie__" and "__PIE__". The macros have the value 1 for -fpie and 2 for -fPIE.
-fno-plt 👑
Do not use the PLT for external function calls in position-independent code. Instead, load the callee address at call sites from the GOT and branch to it. This leads to more efficient code by eliminating PLT stubs and exposing GOT loads to optimizations. On architectures such as 32-bit x86 where PLT stubs expect the GOT pointer in a specific register, this gives more register allocation freedom to the compiler. Lazy binding requires use of the PLT; with -fno-plt all external symbols are resolved at load time.
Alternatively, the function attribute "noplt" can be used to avoid calls through the PLT for specific external functions.
In position-dependent code, a few targets also convert calls to functions that are marked to not use the PLT to use the GOT instead.
-fno-jump-tables 🍓
Do not use jump tables for switch statements even where it would be more efficient than other code generation strategies. This option is of use in conjunction with -fpic or -fPIC for building code that forms part of a dynamic linker and cannot reference the address of a jump table. On some targets, jump tables do not require a GOT and this option is not needed.
-fno-bit-tests 💅
Do not use bit tests for switch statements even where it would be more efficient than other code generation strategies.
-ffixed-reg 🧚
Treat the register named reg as a fixed register; generated code should never refer to it (except perhaps as a stack pointer, frame pointer or in some other fixed role).
reg must be the name of a register. The register names accepted are machine-specific and are defined in the "REGISTER_NAMES" macro in the machine description macro file.
This flag does not have a negative form, because it specifies a three-way choice.
-fcall-used-reg ✨
Treat the register named reg as an allocable register that is clobbered by function calls. It may be allocated for temporaries or variables that do not live across a call. Functions compiled this way do not save and restore the register reg.
It is an error to use this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model produces disastrous results.
This flag does not have a negative form, because it specifies a three-way choice.
-fcall-saved-reg 🫶
Treat the register named reg as an allocable register saved by functions. It may be allocated even for temporaries or variables that live across a call. Functions compiled this way save and restore the register reg if they use it.
It is an error to use this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model produces disastrous results.
A different sort of disaster results from the use of this flag for a register in which function values may be returned.
This flag does not have a negative form, because it specifies a three-way choice.
-fpack-struct[=n] 🌸
Without a value specified, pack all structure members together without holes. When a value is specified (which must be a small power of two), pack structure members according to this value, representing the maximum alignment (that is, objects with default alignment requirements larger than this are output potentially unaligned at the next fitting location).
Warning: the -fpack-struct switch causes GCC to generate code that is not binary compatible with code generated without that switch. Additionally, it makes the code suboptimal. Use it to conform to a non-default application binary interface.
-fleading-underscore 🔥
This option and its counterpart, -fno-leading-underscore, forcibly change the way C symbols are represented in the object file. One use is to help link with legacy assembly code.
Warning: the -fleading-underscore switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface. Not all targets provide complete support for this switch.
-ftls-model=model 🧚♀️
Alter the thread-local storage model to be used. The model argument should be one of global-dynamic, local-dynamic, initial-exec or local-exec. Note that the choice is subject to optimization: the compiler may use a more efficient model for symbols not visible outside of the translation unit, or if -fpic is not given on the command line.
The default without -fpic is initial-exec; with -fpic the default is global-dynamic.
-ftrampolines 🦋
For targets that normally need trampolines for nested functions, always generate them instead of using descriptors. Otherwise, for targets that do not need them, like for example HP-PA or IA-64, do nothing.
A trampoline is a small piece of code that is created at run time on the stack when the address of a nested function is taken, and is used to call the nested function indirectly. Therefore, it requires the stack to be made executable in order for the program to work properly.
-fno-trampolinesis enabled by default on a language by language basis to let the compiler avoid generating them, if it computes that this is safe, and replace them with descriptors. Descriptors are made up of data only, but the generated code must be prepared to deal with them. As of this writing,-fno-trampolinesis enabled by default only for Ada. 💀
Okay so, bestie, this is the big catch 🚨: code compiled with -ftrampolines and code compiled with -fno-trampolines are not binary compatible if nested functions are present 💀. So this option has to be used on a program-wide basis and handled with extreme care 🫶. No mixing and matching, periodt.
For languages other than Ada, the -ftrampolines and -fno-trampolines options currently have no effect 🙈. Trampolines are always generated on platforms that need them for nested functions, no notes.
🦋 -ftrampoline-impl=[stack|heap]
By default, trampolines live on the stack 🥞. BUT some platforms, like the Apple M1, don't allow an executable stack 😤. So -ftrampoline-impl=heap makes GCC generate calls to __gcc_nested_func_ptr_created and __gcc_nested_func_ptr_deleted to allocate and deallocate trampoline space on the executable heap ✨. Those functions live in libgcc, and they only show up on specific targets: x86_64 Darwin, 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. ⚠️
🌈 -fvisibility=[default|internal|hidden|protected]
This sets the default ELF image symbol visibility to whatever you pick. Every symbol gets marked with it unless the code overrides it 💅. It can seriously speed up linking and load times for shared object libraries 🚀, makes the code more optimized ✨, gives you near-perfect API export, and stops symbol clashes 🙅♀️. Strongly recommend using it in any shared objects you distribute.
Despite the name, default always means public, i.e., available to be linked against from outside the shared object 🌍. protected and internal are pretty useless in real-world usage, so the only other commonly used option is hidden 🫠. If you don't specify -fvisibility, the default is default, i.e., every symbol is public 📢.
Want the deets? Check out "How To Write Shared Libraries" by Ulrich Drepper, found at https://www.akkadia.org/drepper/ 📚. BUT, and this is the big brain move 🧠, a better trick than marking stuff hidden when the default is public is to flip it: make the default hidden and mark the public things as public. That's the norm with DLLs on Windows. With -fvisibility=hidden plus __attribute__ ((visibility("default"))) instead of __declspec(dllexport), you get almost identical semantics with identical syntax 🤯. Huge win for cross-platform projects 🌸.
Adding visibility to old code? #pragma GCC visibility is your friend 🧚. You wrap the declarations you care about with, for example, #pragma GCC visibility push(hidden) and #pragma GCC visibility pop. Real talk: visibility is part of the API interface contract, so all new code should specify visibility whenever it isn't the default 💅. Anything only meant for use within the local DSO should be marked hidden explicitly, so as to avoid PLT indirection overheads ⚡. It also makes the code way more readable and self-documenting 📖. And thanks to ISO C++ specification requirements, operator new and operator delete must always be default visibility 🙃.
Heads up 👀: headers from outside your project, especially system headers and headers from any other library you use, might not be expecting to be compiled with visibility other than the default. You might need to explicitly say #pragma GCC visibility push(default) before including any such headers 🫶.
extern declarations aren't affected by -fvisibility, so tons of code can be recompiled with -fvisibility=hidden with zero modifications ✨. BUT calls to extern functions with no explicit visibility go through the PLT. So it's 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 🧐. For example, an exception class that is going to be thrown between DSOs must be explicitly marked with default visibility, so the type_info nodes get unified between the DSOs 🤝.
If you want the whole tea on these techniques, their benefits, and how to use them, peep https://gcc.gnu.org/wiki/Visibility 🍵.
🎀 -fstrict-volatile-bitfields
Use this when accesses to volatile bit-fields (or other structure fields, although the compiler usually honors those types anyway) should be a single access at the width of the field's type, aligned to a natural alignment if possible 💖. Example: targets with memory-mapped peripheral registers might need every access to be 16 bits wide. With this flag, you declare all the peripheral bit-fields as unsigned short (assuming short is 16 bits on those targets) to force GCC into 16-bit accesses instead of a maybe-more-efficient 32-bit one 🔧.
If this option is disabled, the compiler just grabs the most efficient instruction 🏃♀️. In the example above, that could be a 32-bit load instruction, even though it touches bytes that don't contain any portion of the bit-field, or memory-mapped registers unrelated to the one being updated 😬.
Sometimes it just isn't possible, like when the packed attribute is applied to a structure field. Then there's no single read or write that is correctly aligned for the target machine 🙃. In that case GCC falls back to generating multiple accesses, instead of code that will fault or truncate the result at run time 🛟.
Note: Due to restrictions of the C/C++11 memory model, write accesses are not allowed to touch non bit-field members. So it's 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 one 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 🧵.
It's enabled by default, so the only useful form of the option is -fno-sync-libcalls 🙅. This option is used in the implementation of the libatomic runtime library 🧪.
🛏️ -fzero-init-padding-bits=value
This guarantees zero initialization of padding bits in automatic variable initializers 💜. Some languages already promise it in certain cases, like C23 when using empty initializers ({}), or C++ when using zero-initialization, or C guaranteeing that fields not specified in an initializer have their padding bits zero initialized 🧸. This option lets you change when padding bits in initializers are guaranteed to be zero initialized. The default is -fzero-init-padding-bits=standard, which makes no further guarantees than the corresponding standard. Like:
struct A { char a; unsigned long long b; char c; };
union B { char a; unsigned long long b; };
struct A a = {}; // C23 guarantees padding bits are zero.
struct A b = { 1, 2, 3 }; // No guarantees.
union B c = {}; // C23 guarantees padding bits are zero.
union B d = { 1 }; // No guarantees.-fzero-init-padding-bits=unions goes a step further and guarantees zero initialization of padding bits in unions, on top of what the standards promise 🌈. That applies if the initializer of a union is empty, which zeroes ALL the bits of the union. It also applies if the initialized member of the union is smaller than the size of the union, which zeroes the padding bits outside the initialized member. This was the GCC behavior before GCC 15. In the example above, it guarantees zero initialization of the last sizeof (unsigned long long) - 1 bytes in the union 🍰.
-fzero-init-padding-bits=all goes even further 🚀 and also guarantees zero initialization of padding bits of other aggregates. So that covers the padding in between b.a and b.b (if any), and the tail padding in the structure (if any) 🌸.
NOTE: In Ubuntu 25.10 and later versions,-fzero-init-padding-bits=allis enabled by default for C, C++, ObjC, ObjC++, unless-fzero-init-padding-bits=standardis found 👀.
✨ GCC Developer Options ✨
This part is for the GCC developers out there 🧑💻. These are command-line options mainly for compiler testing and digging into compiler bugs and compile-time performance problems 🔍. That includes options that spit out debug dumps at various points in the compilation, print stats like memory use and execution time, and print info about GCC's configuration, like where it searches for libraries 📚. Honestly, you should rarely need these for ordinary compiling and linking, so don't go wild 💀.
A lot of developer options that make GCC dump output to a file take an optional =filename suffix 📄. You can say stdout or - to dump to standard output, and stderr for standard error 🖥️.
If you leave out =filename, GCC builds a default dump file name by sticking together: the base dump file name, a pass number, a phase letter, and the pass name 🧩. The base dump file name is the output file name the compiler produced, if you explicitly specified one and it's not an executable. Otherwise it's the source file name. The pass number comes from the order passes get registered with the compiler's pass manager. That's usually the same as the order of execution, BUT passes registered by plugins, target-specific passes, or passes that get registered late are numbered higher than the pass named final, even if they run earlier 🤪. The phase letter is one of i (inter-procedural analysis), l (language-specific), r (RTL), or t (tree). And the files get created in the directory of the output file 📁✨.
-fcallgraph-info,-fcallgraph-info=MARKERS— okay bestie, this one makes the compiler spit out callgraph info for your program 🦋, one file per object file. It comes out in the common VCG format 💅. You can add extra decorations to the per-node and/or per-edge info by passing a comma-separated list of markers ✨. Thesumarker adds stack usage info, and it's the same as-fstack-usage🔥. Thedamarker adds info about dynamically allocated objects.- When you compile with
-flto, no callgraph info comes out alongside the object file 🙈. At LTO link time,-fcallgraph-infomay generate multiple callgraph info files right next to the intermediate LTO output files.
- When you compile with
-dletters,--dump=letters,--dump letters,-fdump-rtl-pass,-fdump-rtl-pass-options,-fdump-rtl-pass-options=filename— this is the debugging-dump family 🔍. It makes dumps during compilation at the times you pick with-dletters, or by pass when you go with-fdump-rtl. It's how you debug the RTL-based passes of the compiler, and it's giving main character energy 👑.- Some
-dlettersswitches mean something different when you use-Efor preprocessing, so watch out 👀. - The
-optionsform gives you way more control over the details of the dump. See-fdump-treefor the deets 🧚.
- Some
Here are the actual command-line options that follow these patterns, and what each one does:
-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 only runs 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— these 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— these 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— these 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— these 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— these enable dumping after the two forward propagation passes.-fdump-rtl-gcse1,-fdump-rtl-gcse2— these 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— these enable dumping after the basic block scheduling passes.-fdump-rtl-ree— dumps after sign/zero extension elimination.-fdump-rtl-seqabstr— dumps after common sequence discovery.-fdump-rtl-shorten— dumps after shortening branches.-fdump-rtl-split1,-fdump-rtl-split2,-fdump-rtl-split3,-fdump-rtl-split4,-fdump-rtl-split5— these enable dumping after five rounds of instruction splitting 🪓.-fdump-rtl-sms— dumps after modulo scheduling. This pass only runs on some architectures.-fdump-rtl-stack— dumps after converting GCC's "flat register file" registers to the x87's stack-like registers. This pass only runs on x86 variants.-fdump-rtl-subreg1,-fdump-rtl-subreg2— these enable dumping after the two subreg expansion passes.-fdump-rtl-vartrack— dumps after variable tracking.-fdump-rtl-vregs— dumps after converting virtual registers to hard registers.-fdump-rtl-web— dumps after live range splitting.-fdump-rtl-regclass,-fdump-rtl-subregs_of_mode_init,-fdump-rtl-subregs_of_mode_finish,-fdump-rtl-dfinit,-fdump-rtl-dfinish— these are defined but always produce empty files 🫠.-da,--dump=a,-fdump-rtl-all— produce all the dumps listed above 💖.-dA,--dump=A— annotate the assembler output with miscellaneous debugging information.-dD,--dump=D— dump all macro definitions at the end of preprocessing, in addition to the normal output.-dH,--dump=H— produce a core dump whenever an error occurs 💀.-dp,--dump=p— annotate the assembler output with a comment indicating which pattern and alternative is used. The length and cost of each instruction get printed too.-dP,--dump=P— dump the RTL in the assembler output as a comment before each instruction. This also turns on-dpannotation.-dx,--dump=x— just generate RTL for a function instead of compiling it. This is usually used with-fdump-rtl-expand🧚.
-fdump-debug— dumps the debugging information generated during the debug generation phase 🐛.-fdump-earlydebug— dumps the debugging information generated during the early debug generation phase.-fdump-noaddr— when you're doing debugging dumps, this suppresses address output. That makes it way more feasible todiffyour dumps across compiler invocations with different compiler binaries and/or different text / bss / data / heap / stack / dso start locations 🧠.-freport-bug— if an internal compiler error (ICE) happens, this collects and dumps debug info into a temporary file 🚨.-fdump-unnumbered— when you're doing debugging dumps, this suppresses instruction numbers and address output. That makes it more feasible todiffyour dumps for compiler invocations with different options, especially with and without-g🫶.-fdump-unnumbered-links— when you're doing debugging dumps (see the-doption above), this suppresses instruction numbers for the links to the previous and next instructions in a sequence.-fdump-internal-locations— dumps detailed info about GCC's internal representation of source code locations 📍.-fdump-ipa-switch,-fdump-ipa-switch-options— these control the dumping, at various stages of the inter-procedural analysis, of the language tree to a file 🌈. The file name is made by appending a switch-specific suffix to the source file name, and the file gets created in the same directory as the output file. These dumps are possible:all— enables all inter-procedural analysis dumps.cgraph— dumps info about call-graph optimization, unused function removal, and inlining decisions.inline— dumps after function inlining.strubm— dumps after selecting "strub" modes, and records the selections as function attributes.strub— dumps "strub" transformations: interface changes, function wrapping, and insertion of builtin calls for stack scrubbing and watermarking.
On top of that, you can add -optimized, -missed, -note, or -all. They mean the same thing as they do for -fopt-info, and the default is -optimized 💅.
For example, -fdump-ipa-inline-optimized-missed will emit info on the callsites that got inlined, along with the callsites that did not get inlined 👀.
By default, the dump contains messages about successful optimizations (the same as -optimized), together with low-level details about the analysis 🎀.
-fdump-ipa-clones— okay this one is for the live-patching crew 🩹✨ It makes a dump file listing when call graph node clones get created and when call graph nodes get removed during inter-procedural optimizations and transformations. The main point is that tools building live-patches can work out the full set of functions they need to live-patch to completely replace one particular function (see-flive-patching) 💅 The file name is your source file name with the suffixipa-clonestacked on, and it gets saved in the same directory as the output file. Every entry sits on its own line with semicolon-separated fields 🌸
Clone creation: for call graph clone creation, the fields go like this:
"Callgraph clone", the literal string 🎀- Name of the function being cloned, as the assembler sees it.
- A number that uniquely represents the function being cloned in the call graph. Heads up: it's only unique within a compilation unit or within whole-program analysis, and it's likely to be different between the two phases 🙈
- The file name of the source file where the function is defined.
- The line where the function definition lives.
- The column where the function definition lives.
- Name of the new function clone, as the assembler sees it.
- A number that uniquely represents the new function clone in the call graph. Same deal: only unique within a compilation unit or whole-program analysis, and likely different in the two phases.
- The file name of the source file that the new clone's source code location points to.
- The line that the new clone's source code location points to.
- The column that the new clone's source code location points to.
- A string that tells you the reason for cloning 🧚
Clone removal: for call graph clone removal, the fields go like this:
"Callgraph removal", the literal string 💜- Name of the function being removed, as it would be presented to the assembler.
- A number that uniquely represents the function being cloned in the call graph. Only unique within a compilation unit or whole-program analysis, and likely to differ between the two phases.
- The file name of the source file where the function is defined.
- The line where the function definition is located.
- The column where the function definition is located.
-fdump-lang— dump the language-specific info 🦋 The file name is made by slapping.langonto the end of the source file name.-fdump-lang-all,-fdump-lang-switch,-fdump-lang-switch-options,-fdump-lang-switch-options=filename— these are the controls for dumping language-specific info 🌈 Theoptionsandfilenamebits work exactly like they do in-fdump-tree.-fdump-tree-allturns on all the language-specific dumps, and everything else depends on the language, so main character energy from each one 👑 For instance, see-fdump-passes— prints the list of optimization passes that the current command-line options switch on and off, straight to stderr 🔥-fdump-statistics-option— turns on and controls pass statistics dumping into a separate file 📊 The file name is your source file name with a suffix that ends in.statistics, and it gets created in the same directory as the output file. If you use the-optionform,-statssums the counters over the whole compilation unit, while-detailsdumps every event as the passes generate them. With no option at all, the counters get summed for each function that's compiled 💅-fdump-tree-all,-fdump-tree-switch,-fdump-tree-switch-options,-fdump-tree-switch-options=filename— this crew controls dumping at the different stages of processing the intermediate language tree into a file 🌳 If you use the-optionsform,optionsis a list of--separated options that control how detailed the dump is. Not every option applies to every dump, and the ones that don't make sense just get ignored 🫶 These are the ones you can use:address— prints the address of each node. Usually not that meaningful, since it changes depending on the environment and source file. Its real job is tying a dump file to a debug environment 🙈asmname— if"DECL_ASSEMBLER_NAME"has been set for a decl, it gets used in the dump instead of"DECL_NAME". It's mostly handy for working backward from mangled names in the assembly file ✨slim— when dumping front-end intermediate representations, it stops members of a scope or a function body from getting dumped just because that scope was reached. Those items only show up when some other path directly reaches them. When dumping pretty-printed trees, it stops the bodies of control structures from being dumped. When dumping RTL, it prints the RTL in slim (condensed) form instead of the default LISP-like representation 🍓raw— prints a raw representation of the tree. By default, trees get pretty-printed into a C-like representation 🧸details— enables more detailed dumps (not every dump option honors this one). It also includes info from the optimization passes 🔍stats— enables dumping various statistics about the pass (again, not honored by every dump option) 📈blocks— enables showing basic block boundaries (disabled in raw dumps) 🧱graph— for each of the other indicated dump files (-fdump-rtl-pass), dumps a control flow graph representation tofile.passid.pass.dot, which is suitable for viewing with GraphViz. Each function in the file gets pretty-printed as a subgraph, so GraphViz can render them all in one single plot 🗺️ RTL is always dumped in slim form.vops— enables showing virtual operands for every statement 🎀lineno— enables showing line numbers for statements 📍uid— enables showing the unique ID ("DECL_UID") for each variable 🆔verbose— enables showing the tree dump for each statement 📜eh— enables showing the EH region number that's holding each statement 🛟scev— enables showing scalar evolution analysis details 🧮optimized— enables showing optimization info (only available in certain passes) ✅missed— enables showing missed optimization info (only available in certain passes) 😭note— enables other detailed optimization info (only available in certain passes) 📝folding— enables dumping info about match-and-simplify (match.pd) patterns when they get applied 🪄all— turns on all the options, exceptraw,slim,verboseandlineno💖optall— turns on all the optimization options, which meansoptimized,missed, andnote🌟
Finding the dump you want: if you wanna figure out what tree dumps exist or find the dump for a pass you care about, follow these steps 🕵️♀️
- Invoke GCC with
-fdump-passes, then look in the stderr output for a code that matches the pass you're into. For example, the codes"tree-evrp","tree-vrp1", and"tree-vrp2"all correspond to the three Value Range Propagation passes. The number at the end tells you apart the different invocations of the same pass 🔢 - To make the dump file get created, 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-evrpoption. You can optionally name the dump file yourself. If you don't, GCC makes one as described below 💅 - Find the pass dump in a file whose name has three parts separated by periods: the name of the source file GCC was invoked to compile, a numeric suffix for the pass number followed by the letter
tfor tree passes (or the letterrfor 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. Heads up that the numeric codes aren't stable and can change from one version of GCC to another 🙈
-fopt-info,-fopt-info-options,-fopt-info-options=filename— controls optimization dumps coming from the various optimization passes ✨ If you use the-optionsform,optionsis a list of--separated option keywords that pick the dump details and optimizations. The options split into three groups: 1. options describing what kinds of messages get emitted, 2. options describing how verbose the dump is, and 3. options describing which optimizations get included 🧩 You can mix the options from each group freely since they don't overlap. But if there's a conflict, the later option on the command line wins 👑
Message kinds: these control which kinds of messages get emitted:
optimized— prints info when an optimization gets applied successfully. It's up to each pass to decide what info is relevant. For example, the vectorizer passes print the source location of loops that get vectorized 🚀missed— prints info about missed optimizations. Each pass controls what info goes into 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🌈
Verbosity: this one controls how verbose the dump is:
internals— by default only "high-level" messages get emitted. This turns on extra, more detailed messages that are probably only interesting to GCC developers 🤓
Groups: these keywords describe a whole group of optimizations, so you don't have to list them one by one:
ipa— enables dumps from all interprocedural optimizations 🦋loop— enables dumps from all loop optimizations 🔁inline— enables dumps from all inlining optimizations 🫧
omp— okay so this one turns on dumps from all the OMP (Offloading and Multi Processing) optimizations 🧚vec— dumps from all the vectorization optimizations 💜optall— dumps from every single optimization 👑 It's a superset of the groups above, so it's basically the whole buffet 💅
If options is left out, it defaults to optimized-optall. That means you get messages about the successful optimizations from all the passes, minus anything tagged as "internals" 🫶
If you give it a filename, all the applicable dumps get concatenated into that file. If you don't, the dump goes to stderr instead 🦋 You can use more than one -fopt-info option, but only one of them can carry a filename. If you slip in extra filenames, every one after the first gets ignored 🙈
⚠️ Heads up, bestie: the output filename gets overwritten when you have multiple translation units. If you want one combined output from several translation units, use stderr instead 😭
Here's the vibe in action. This one dumps the optimization info straight to stderr:
gcc -O3 -fopt-infoThis one writes the missed optimization report from all the passes into missed.all:
gcc -O3 -fopt-info-missed=missed.allAnd this one prints info about missed opportunities from the vectorization passes to stderr. Fun fact: -fopt-info-vec-missed is the same thing as -fopt-info-missed-vec 🌈 The order of the group names and message types after -fopt-info doesn't matter, so do whatever feels right ✨
gcc -O2 -ftree-vectorize -fopt-info-vec-missedNext up, this one outputs info about missed optimizations and optimized locations from all the inlining passes into inline.txt 💖
gcc -O3 -fopt-info-inline-optimized-missed=inline.txtFinally, we've got a little conflict situation 💀
gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.optTwo output filenames, vec.miss and loop.opt, are fighting, since only one output file is allowed. So only the first option takes effect and the rest get ignored. You'll only end up with vec.miss, which holds the vectorizer's dumps about missed opportunities 🎀
-fsave-optimization-record— okay, this one writes aSRCFILE.opt-record.json.gzfile that details what optimizations were performed, for every optimization that supports-fopt-info🍓
🧪 This option is experimental, and the format of the data inside the compressed JSON file is subject to change. Use it with caution, bestie.
It's roughly a machine-readable version of -fopt-info-all. You get a collection of messages with the source file, line number and column number, plus some extra goodies for each message:
- the execution count of the code being optimized, plus metadata on whether it came from actual profile data or just an estimate, so consumers can sort messages by how hot the code is 🔥
- the function name of the code being optimized, where that applies 💅
- the "inlining chain" for the code being optimized, so when a function gets inlined into a bunch of different places (which might themselves be inlined), you can tell the copies apart 🦋
- objects identifying the parts of the message that refer to expressions, statements or symbol-table nodes, which category each one belongs to, and, when it's available, its source code location 🧚
- the GCC pass that emitted the message, and
- the location in GCC's own code where the message was emitted 🤓
Also, some messages are logically nested inside other messages, which reflects the implementation details of the optimization passes 🌸
-fsched-verbose=n— on targets that use instruction scheduling, this controls how much debugging output the scheduler dumps into the dump files 🎀- For
ngreater than zero, it outputs the same info 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 the RTL at the abort point, plus control-flow and regions info. - And for
nover four,-fsched-verbosealso includes dependence info 💀
- For
-fenable-kind-pass,-fdisable-kind-pass=range-list— this is a whole family of options for explicitly disabling or enabling optimization passes 🧪 They're meant for debugging GCC itself, so regular compiler users should stick to the normal 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 gets statically invoked in the compiler more than once, append a sequential number to the pass name, starting from 1 🌈-fdisable-rtl-pass,-fdisable-rtl-pass=range-list— disables the RTL pass pass, where pass is the pass name. Same numbering deal as above: if it's invoked multiple times, append 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 uid falls inside one of the specified ranges, the pass gets disabled for that function. You can find the uid in the function header of a dump file, and you can dump the pass names by using
-fdump-passes🔍
-fdisable-tree-pass,-fdisable-tree-pass=range-list— disables the tree pass pass. Check out-fdisable-rtlfor how the option arguments work 💜-fenable-ipa-pass— enables the IPA pass pass, where pass is the pass name. Same numbering rule applies: if it's invoked multiple times, append a sequential number starting from 1 🦋-fenable-rtl-pass,-fenable-rtl-pass=range-list— enables the RTL pass pass. See-fdisable-rtlfor the option argument description and examples 🌸-fenable-tree-pass,-fenable-tree-pass=range-list— enables the tree pass pass. See-fdisable-rtlfor the description of the option arguments 👑
Here are some examples of these options in action, lowkey iconic 💅
# 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— turns on internal consistency checking ✅ The default depends on how the compiler was configured.-fchecking=2goes further and enables extra internal consistency checking that might affect code generation 👀-frandom-seed=string— this gives GCC a seed to use instead of random numbers when it generates certain symbol names that have to be different in every compiled file 🎲 It's also used to stamp coverage data files and the object files that produce them. Use-frandom-seedif you want reproducibly identical object files 💖
The string can be a number (decimal, octal or hex), or an arbitrary string, which gets converted to a number by computing CRC32 🧮 The string should be different for every file you compile 🫶
-save-temps,--save-temps— stores the usual "temporary" intermediate files permanently 📁 They get named as auxiliary output files, as specified under-dumpbaseand-dumpdir🧚
When you use it with the -x command-line option, -save-temps is smart enough to avoid overwriting an input source file that has the same extension as an intermediate file. If you want the corresponding intermediate file, rename the source file before using -save-temps 🙈
-save-temps=cwd— equivalent to-save-temps -dumpdir ./.📂-save-temps=obj— equivalent to-save-temps -dumpdir outdir/, whereoutdir/is the directory of the output file given after the-ooption, including any directory separators 🦋 If-oisn't used,-save-temps=objacts like-save-temps=cwd💜-specs=file,--specs=file,--specs file— processes file after the compiler reads in the standard specs file, so you can override the defaults thegccdriver uses when picking which switches to pass tocc1,cc1plus,as,ld, etc. 🎀 You can specify more than one-specs=file, and they're processed in order, from left to right 🌈-time[=file]— reports the CPU time taken by each subprocess in the compilation sequence ⏱️ 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 running the program itself. The second number is the "system time", 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 it 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 displayed too, so you can later tell which file was being compiled and with which options 🧾
-fdump-final-insns[=file]— dumps the final internal representation (RTL) to file 🧚 If the optional argument is left out (or if file is.), the dump file name is determined by appending.gkdto the dump base name, see-dumpbase💅-fcompare-debug[=opts]— okay so if compiling goes through with no errors, GCC runs the compiler a second time, addingoptsand-fcompare-debug-secondto the arguments for that second run 💅 It dumps the final internal representation from both compilations and prints an error if they don't match. Verification ate, no crumbs 🔍
Leave off the equal sign and the default -gtoggle kicks in 🎀
The GCC_COMPARE_DEBUG environment variable can turn this on for you. If it's defined, non-empty and nonzero, it implicitly enables -fcompare-debug. If GCC_COMPARE_DEBUG is defined to a string that starts with a dash, that string is used for opts. Otherwise you get the default -gtoggle 🧚
-fcompare-debug= (with the equal sign but no opts) is the same as -fno-compare-debug. That turns off the dumping of the final representation and the second compilation, and it means even GCC_COMPARE_DEBUG can't take effect ✋
Want full coverage while you test with -fcompare-debug? 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) 🙈 Only want a warning instead? Setting GCC_COMPARE_DEBUG to -w%n-fcompare-debug not overridden will do 🦋
-fcompare-debug-second— this one gets passed to the compiler automatically for the second compilation that-fcompare-debugasks for. It comes along with options that silence warnings, and it leaves out any other options that would make the compiler write output to files or to standard output as a side effect 🌸 During the second compilation, dump files and preserved temporary files get the extra ".gk" extension 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. Honestly that makes it pretty much only useful for debugging the compiler itself 💀
-gtoggle— this flips debug info generation. If leaving out this option generates debug info, it turns generation off. Otherwise it turns debug info on at level 2 💜 Where you put it on the command line doesn't matter. It takes effect after all other options are processed, and it only does its thing once, no matter how many times you write it. It's mainly meant to be used with-fcompare-debug.-fvar-tracking-assignments-toggle— toggles-fvar-tracking-assignments, the same way-gtoggletoggles-g✨-Q— main character energy for help output 👑 When it's used on the command line before--help=,-Qacts as a modifier to the help output.
Otherwise, this option makes the compiler print the name of each function as it gets compiled, and print some statistics about each pass when that pass finishes 📊
-ftime-report— makes the compiler print some stats to stderr about the time each pass consumed when it finishes ⏱️
If you asked for SARIF diagnostics output with -fdiagnostics-format=sarif-file or -fdiagnostics-format=sarif-stderr, then the -ftime-report info gets emitted as JSON inside the SARIF output instead. The precise format of that JSON is subject to change. The values might not exactly match the ones sent to stderr, since they get written out at a slightly different place 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 is5. Ifnis greater than or equal to10, the dump output goes to stderr in the same format asnminus10🧠-flto-report— prints a report with internal details on how the link-time optimizer is working. What's in this report changes from version to version 🤷♀️ It's meant for GCC developers who are processing object files in LTO mode (via-flto). It's disabled by default.-flto-report-wpa— like-flto-report, but it 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 either before or after interprocedural optimization. Pick your vibe 💅-fmultiflags— this one's giving build-system drama in the best way 🎀 It enables multilib-aware"TFLAGS"to be used for building target libraries with options that differ 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 stay more demanding. 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, so this is the easier route 🫶
Unlike "TFLAGS", using specs lets different flags get selected for different multilibs. To pull that off, build with make TFLAGS=-fmultiflags, after configuring with --with-specs=%{fmultiflags:...}.
This option gets discarded by the driver once it's done processing the driver self spec 🗑️
It's also handy for checking that "TFLAGS" are being used to build all target libraries. You do that by configuring a non-bootstrap compiler with --with-specs='%{!fmultiflags:%emissing TFLAGS}' and then building 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 info for your program, per function. The dump filename is made by appending.suto the auxname. The auxname comes from the name of the output file if you explicitly specified one and it's not 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 manipulates 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 get made in the function. The second field is that fixed number of bytes 🧱
The qualifier "dynamic" means the function manipulates the stack dynamically. On top of the static allocation above, stack adjustments get made in the body of the function, for example to push and pop arguments around function calls. If the qualifier "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 those 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 compilation. This is only supported by the C++ front end, 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-listis a comma-separated list ofname:lower_bound1-upper_bound1 [:lower_bound2-upper_bound2...]tuples. Each one sets the name of the counter and a list of closed intervals. Thelower_boundis optional and gets 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-autofdo-gcov-version,--print-autofdo-gcov-version— prints the current version of GCOV being used by the AutoFDO infrastructure 🖨️-print-file-name=library,--print-file-name=library,--print-file-name library— prints the full absolute name of the library filelibrarythat would be used when linking, and then stops there. With this option, GCC doesn't compile or link anything. It just prints the file name 📂-print-multi-directory,--print-multi-directory— prints the directory name that matches the multilib selected by any other switches on the command line. That directory is supposed to exist inGCC_EXEC_PREFIX🗂️-print-multi-lib,--print-multi-lib— prints the mapping from multilib directory names to the compiler switches that enable them. The directory name is separated from the switches by;. Each switch starts with@instead of-, with no spaces between multiple switches. This is supposed to make shell processing easier 🐚-print-multi-os-directory,--print-multi-os-directory— prints the path to OS libraries for the selected multilib, relative to somelibsubdirectory. If OS libraries live in thelibsubdirectory and no multilibs are used, this is usually just.. If OS libraries live inlibsuffixsibling directories, it prints something like../lib64,../libor../lib32. If OS libraries live inlib/subdirsubdirectories, it prints something likeamd64,sparcv9orev6🌍-print-multiarch,--print-multiarch— prints the path to OS libraries for the selected multiarch, relative to somelibsubdirectory 🧩-print-prog-name=program,--print-prog-name=program,--print-prog-name program— like-print-file-name, but it searches for a program such ascppinstead of a library 🔧-print-libgcc-file-name,--print-libgcc-file-name— same as-print-file-name=libgcc.a💖
This is useful when you use -nostdlib or -nodefaultlibs but you still want to link with libgcc.a. You can do:
gcc -nostdlib <files>... `gcc -print-libgcc-file-name`-print-search-dirs,--print-search-dirs— prints the name of the configured installation directory and a list of the program and library directories gcc searches, and then stops. It doesn't do anything else 🗺️
Okay so this bit is SO useful when gcc starts throwing the classic installation problem, cannot exec cpp0: No such file or directory. 😭🫶 To fix it, you either need to put cpp0 and the other compiler components exactly where gcc expects to find them, or you can set the environment variable GCC_EXEC_PREFIX to the directory where you installed them. And don't forget the trailing /! 💅
-print-sysroot,--print-sysroot— prints the target sysroot directory the compiler is using while it compiles 🌸. That's whatever was set at configure time or with--sysroot, maybe with an extra suffix that depends on your compilation options. If there's no target sysroot, it prints nothing at all, bestie.-print-sysroot-headers-suffix,--print-sysroot-headers-suffix— prints the suffix tacked onto the target sysroot when searching for headers 🧚. If the compiler wasn't configured with a suffix, it errors out instead. Either way it stops there and doesn't do anything else.-dumpmachine— prints the compiler's target machine, likei686-pc-linux-gnu, and then it's done 🦋.-dumpversion— prints the compiler version, like3.0,6.3.0or7, and then stops ✨. This is the version used in filesystem paths and specs. Depending on how the compiler was configured, it could be one number (major), 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 and nothing else 💜. 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 only used when GCC itself is being built, so it's kinda niche.)--param name=value,--param=name=value— okay so GCC, by convention, uses parameters you can pass on the command line instead of hard-wired constants for compiler limits and heuristics 🔥. Lots of them are optimization stuff, like GCC not inlining functions that have more than a certain number of instructions. The static analyzer uses them to limit complexity, link-time optimization uses them to control partitioning, and so on. Others control internal stuff like memory allocation and garbage collection strategy, and some control target-specific behavior. The--paramoption gives you one uniform way to set all of them, but the names and meanings are tied to the compiler's internals and can change without notice in future releases.
Don't depend on parameter settings for your program to compile correctly! 💀 They're exposed for developers debugging compilation problems or, in some cases, as workarounds for compiler bugs.
✨ Machine-Dependent Options ✨
Each target machine GCC supports can have its own options 🌸. For example, you can compile for a particular processor variant or ABI, or control optimizations specific to that machine. By convention, machine-specific option names start with -m.
Some configurations of the compiler also support extra target-specific options, usually so they can play nice with other compilers on the same platform 🫶.
🦋 AArch64 Options 🦋
These options are defined for AArch64 implementations:
-mabi=name— picks the data model you want code generated for 👑.ilp32is the SysV-like one whereint,long intand pointers are all 32 bits, andlp64is the SysV-like one whereintis 32 bits butlong intand pointers are 64 bits. The default depends on your specific target configuration. The LP64 and ILP32 ABIs are NOT link-compatible, so you have to compile your entire program with the same ABI and link it against a compatible set of libraries. Also, theilp32model is deprecated, so be careful with it 😭.-mbig-endian— generates big-endian code 🍓. This is the default when GCC is configured for anaarch64_be-*-*target.-mlittle-endian— generates little-endian code 💖. This is the default when GCC is configured for anaarch64-*-*target but not anaarch64_be-*-*one.-menable-sysreg-checking— gives you an error message if you try to access a system register that isn't available on the target architecture 🙈.-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.-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, so you get it for free 💅.-mcmodel=large— generates code for the large code model 🔥. It makes NO assumptions about addresses and section sizes. Programs can only be statically linked. Also,-mcmodel=largeis incompatible with-mabi=ilp32,-fpicand-fPIC, so don't mix them up 🙅♀️.-mtp=name— specifies the system register to use as the 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 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 end up accessing a different thread pointer from the wrong exception level 😬.-mstrict-align,-mno-strict-align— avoids or allows generating memory accesses that might 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 (omitting it) 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 thesysregchoice,-mstack-protector-guard-reg=regand-mstack-protector-guard-offset=offsetfurther specify which system register to use as the base register for reading the canary, and what offset from that base register to use. There's 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 ⭐. 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 works by inserting a NOP instruction between memory instructions and 64-bit integer multiply-accumulate instructions. This flag gets ignored if an architecture or cpu is specified on the command line that doesn't need the workaround.-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 flag only passes the corresponding flag to the linker. It's also ignored if an architecture or cpu is specified on the command line that doesn't need the workaround.-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 precision of reciprocal square root results to about 16 bits for single precision and to 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 precision of square root results to about 16 bits for single precision and to 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 precision of division results to about 16 bits for single precision and to 32 bits for double precision.-mtrack-speculation,-mno-track-speculation— enables or disables generation of extra code that tracks speculative execution through conditional branches 🕵️♀️. The tracking state can then be used by the compiler when expanding calls to"__builtin_speculation_safe_value", 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 👑. These helpers figure out at runtime 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 ✨.
💖 -mmax-vectorization / -mno-max-vectorization
okay so these two flip a switch that makes the vectorizer's cost model override itself, so vectorization always looks profitable 😭✨ -mmax-vectorization turns that on and -mno-max-vectorization turns it back off. You can pair it with -mautovec-preference for super precise control over which ISA gets used for auto-vectorization 🎀. And heads up, bestie: unlike -fno-vect-cost-model or -fvect-cost-model=unlimited, this one does not turn off the cost comparison between different vector modes 🧚.
✨ -mautovec-preference=name
this one forces an ISA selection strategy for auto-vectorization 💅 The possible values of name are:
default— just use the default heuristics, nothing fancy 🌸asimd-only— Advanced SIMD only, no SVE allowed 🦋sve-only— SVE only, no Advanced SIMD allowed 🔥prefer-asimd— use both Advanced SIMD and SVE, but go with Advanced SIMD when the costs are deemed equal 🍓prefer-sve— use both Advanced SIMD and SVE, but go with SVE when the costs are deemed equal 💜
For the best performance, it is highly recommended to use-mcpuor-mtuneinstead ⚠️ This parameter should only be used for code exploration, so don't go rewriting your whole build around it 🙈
🌈 -march=name
okay this is the big one 👑 -march specifies the name of the target architecture and, optionally, one or more feature modifiers. It has the form -march=arch{+[no]feature}* ✨
Here's the lineup of permissible arch values and the features each one enables by default:
armv8-a(Armv8-A) — includes by default:+fp,+simdarmv8.1-a(Armv8.1-A) — includes by default:armv8-a,+crc,+lse,+rdmaarmv8.2-a(Armv8.2-A) — includes by default:armv8.1-aarmv8.3-a(Armv8.3-A) — includes by default:armv8.2-a,+pauth,+fcma,+jscvtarmv8.4-a(Armv8.4-A) — includes by default:armv8.3-a,+flagm,+fp16fml,+dotprod,+rcpc2armv8.5-a(Armv8.5-A) — includes by default:armv8.4-a,+sb,+ssbs,+predres,+frintts,+flagm2armv8.6-a(Armv8.6-A) — includes by default:armv8.5-a,+bf16,+i8mmarmv8.7-a(Armv8.7-A) — includes by default:armv8.6-a,+wfxt,+xsarmv8.8-a(Armv8.8-a) — includes by default:armv8.7-a,+mopsarmv8.9-a(Armv8.9-a) — includes by default:armv8.8-aarmv9-a(Armv9-A) — includes by default:armv8.5-a,+sve,+sve2armv9.1-a(Armv9.1-A) — includes by default:armv9-a,+bf16,+i8mmarmv9.2-a(Armv9.2-A) — includes by default:armv9.1-a,+wfxt,+xsarmv9.3-a(Armv9.3-A) — includes by default:armv9.2-a,+mopsarmv9.4-a(Armv9.4-A) — includes by default:armv9.3-a,+sve2p1armv9.5-a(Armv9.5-A) — includes by default:armv9.4-a,cpa,+faminmax,+lutarmv8-r(Armv8-R) — includes by default:armv8-r
the value native is available on native AArch64 GNU/Linux and tells the compiler to pick the architecture of the host system 🧚 If the compiler can't recognize the host architecture, this option just has no effect. When -march=native is given and no other -mcpu or -mtune is given, GCC picks the host CPU to tune for and selects the architecture features from it. Basically, -march=native gets treated as -mcpu=native 💖
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 uses name to decide what kind of instructions it can emit when generating assembly code. If -march is specified without -mtune or -mcpu also being specified, the code is tuned to perform well across a range of target processors implementing the target architecture 🌸
🌸 -mtune=name
-mtune is where you tell GCC which target processor to tune the performance of your code for 💅 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, oryon-1,
neoverse-512tvb, neoverse-e1, neoverse-n1, neoverse-n2, neoverse-v1,
neoverse-v2, grace, neoverse-v3, neoverse-v3ae, neoverse-n3,
olympus, cortex-a725, cortex-x925, qdf24xx, saphira, phecda, xgene1,
vulcan, octeontx, octeontx81, octeontx83, octeontx2, octeontx2t98,
octeontx2t96 octeontx2t93, octeontx2f95, octeontx2f95n,
octeontx2f95mm, a64fx, fujitsu-monaka, thunderx, thunderxt88,
thunderxt88p1, thunderxt81, tsv110, hip12, 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-r82ae, cortex-x1, cortex-x1c, cortex-x2, cortex-x3,
cortex-x4, cortex-a510, cortex-a520, cortex-a520ae, cortex-a710,
cortex-a715, cortex-a720, cortex-a720ae, ampere1, ampere1a,
ampere1b, ampere1c, cobalt-100, apple-m1, apple-m2, apple-m3,
apple-m4, c1-nano, c1-pro, c1-premium c1-ultra and native.some of these are big.LITTLE combos, and those values tell GCC to tune for a big.LITTLE system 🧸 They are cortex-a57.cortex-a53, cortex-a72.cortex-a53, cortex-a73.cortex-a35, cortex-a73.cortex-a53, cortex-a75.cortex-a55, cortex-a76.cortex-a55, apple-m1, apple-m2, apple-m3, and gb10 ✨
neoverse-512tvb is giving "all Neoverse cores with SVE and a total vector bandwidth of 512 bits per cycle" 🦋 In other words, it tunes for Neoverse cores that can execute 4 128-bit Advanced SIMD arithmetic instructions a cycle, and 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 🌈
On native AArch64 GNU/Linux systems, native tunes performance to the host system. If the compiler can't recognize the host processor, that 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
-mcpu is the name of the target processor, optionally suffixed by one or more feature modifiers 💖 It has the form -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. Same rule as before, bestie: if feature modifiers conflict, the right-most one is used 🎀
GCC uses name to figure out what kind of instructions it can emit when generating assembly code (as if by -march), and to figure out which target processor to tune for performance (as if by -mtune) 🧚 If you use this option together with -march or -mtune, those options take precedence over the matching part of -mcpu ✨
-mcpu=neoverse-512tvb is special, lowkey 🌸 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 🦋 And unless you override it with -mtune, -mcpu=neoverse-512tvb tunes code in the same way as -mtune=neoverse-512tvb 💅
🦋 -moverride=string
this one overrides the tuning decisions the back-end makes in response to a -mtune= switch 🧪 The syntax, semantics, and accepted values for string are not guaranteed to be consistent across releases, so please don't build anything important on it 😭
This option is only intended to be useful when developing GCC 🛠️
🧚 -mpc-relative-literal-loads / -mno-pc-relative-literal-loads
these enable or disable PC-relative literal loads 💜 With this option, literal pools are accessed using a single instruction and 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 selects the function scope where return address signing gets applied 🔐 The permissible values are:
none— disables return address signingnon-leaf— enables pointer signing for functions which are not leaf functionsall— enables pointer signing for all functions
The default value is none. Heads up, this option has been deprecated by -mbranch-protection, so use that one instead 🙅♀️
🔥 -mbranch-protection=features
this picks the branch protection features to use 🛡️ features can have one of the following forms:
none— the default, turns off all types of branch protection 🫥standard— turns on all types of branch protection features. If a feature has additional tuning options, thenstandardsets it to its standard level 💖pac-ret— turns on return address signing to its standard level: signing functions that save the return address to memory (non-leaf functions practically always do this) using the A-key 🦋pac-ret+leaf— extends thepac-retsigning to include leaf functions 🌈pac-ret+b-keyorpac-ret+leaf+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 🎯gcs— turns on guarded control stack compatible code generation 👑
💅 -mharden-sls=opts
this enables compiler hardening against straight line speculation (SLS) 🫶 opts is a comma-separated list of the following options:
retbrblr
In addition, -mharden-sls=all enables all SLS hardening, while -mharden-sls=none disables all SLS hardening ✨
🫶 -mearly-ra=scope
this decides 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 / -mno-early-ldp-fusion
these enable or disable 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 / -mno-late-ldp-fusion
same vibe as the early one, but these enable or disable 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— okay so this one sets how many bits live in an SVE vector register 🦋 It only does anything when SVE is turned on 💅
GCC makes two flavors of SVE code, bestie. There's "vector-length agnostic" output that's happy with any size of vector register ✨, and "vector-length specific" output that lets GCC assume a vector length when that helps with optimization 🔥. The possible values of bits are scalable, 128, 256, 512, 1024, and 2048. scalable gets you vector-length agnostic output. At present, -msve-vector-bits=128 also gives you vector-length agnostic output on big-endian targets 🌈. Every other value makes vector-length specific code. These values might change in future releases, so ngl the only one you should rely on for code that's portable across different hardware SVE vector lengths is scalable 🫶
The default is -msve-vector-bits=scalable, which makes vector-length agnostic code 🌸
🌈 -march and -mcpu Feature Modifiers 🌈
Okay, feature modifiers used with -march and -mcpu can be any of the ones below, and each one also has an inverse you write as nofeature 💖
crc— Enable the CRC extension. It's on by default for-march=armv8.1-a🧚crypto— Enable the Crypto extension. This also turns on Advanced SIMD and floating-point instructions 🔐fp— Enable floating-point instructions. It's on by default for literally every possible value of-marchand-mcpu💅simd— Enable Advanced SIMD instructions. This also turns on floating-point instructions. It's on by default for every possible value of-marchand-mcpu✨sve— Enable Scalable Vector Extension instructions. This also turns on Advanced SIMD and floating-point instructions 🦋lse— Enable Large System Extension instructions. It's on by default for-march=armv8.1-a🔥rdma— Enable Round Double Multiply Accumulate instructions. It's on by default for-march=armv8.1-a🌸fp16— Enable the FP16 extension. This also turns on floating-point instructions 🍓fp16fml— Enable the FP16 fmla extension. This also turns on the FP16 extensions and floating-point instructions. It's enabled by default for-march=armv8.4-a. Using this with architectures before Armv8.2-A isn't supported 🙈rcpc— Enable the RCpc extension. This lets you use theLDAPRinstructions for load-acquire atomic semantics, and it passes the setting on to the assembler so inline asm statements can use RCpc instructions 💜dotprod— Enable the Dot Product extension. This also turns on Advanced SIMD instructions 🌈aes— Enable the Armv8-aaesandpmullcrypto extension. This also turns on Advanced SIMD instructions 🔐sha2— Enable the Armv8-asha2crypto extension. This also turns on Advanced SIMD instructions ⭐sha3— Enable thesha512andsha3crypto extension. This also turns on Advanced SIMD instructions. Using this with architectures before Armv8.2-A isn't supported 🫶sm4— Enable thesm3andsm4crypto extension. This also turns on Advanced SIMD instructions. Using this with architectures before Armv8.2-A isn't supported 🧚profile— Enable the Statistical Profiling extension. This only turns it on at the assembler level and doesn't change code generation 📊rng— Enable the Armv8.5-a Random Number instructions. This only turns the extension on at the assembler level and doesn't affect code generation 🎲memtag— Enable the Armv8.5-a Memory Tagging Extensions. Using this with architectures before Armv8.5-A isn't supported 🏷️sb— Enable the Armv8-a Speculation Barrier instruction. This only turns it on at the assembler level and doesn't affect code generation. It's enabled by default for-march=armv8.5-a🛡️ssbs— Enable the Armv8-a Speculative Store Bypass Safe instruction. This only turns it on at the assembler level and doesn't affect code generation. It's enabled by default for-march=armv8.5-a🙌predres— Enable the Armv8-a Execution and Data Prediction Restriction instructions. This only turns them on at the assembler level and doesn't affect code generation. It's enabled by default for-march=armv8.5-a💀sve2— Enable the Armv8-a Scalable Vector Extension 2. This also turns on SVE instructions 🦋sve2-bitperm— Enable SVE2 bitperm instructions. This also turns on SVE2 instructions 🌸sve2-sm4— Enable SVE2 sm4 instructions. This also turns on SVE2 instructions 🍓sve2-aes— Enable SVE2 aes instructions. This also turns on SVE2 instructions 🔥sve2-sha3— Enable SVE2 sha3 instructions. This also turns on SVE2 instructions 👑sve2p1— Enable SVE2.1 instructions. This also turns on SVE2 instructions 🌈tme— Enable the Transactional Memory Extension 🧠i8mm— Enable 8-bit Integer Matrix Multiply instructions. This also turns on Advanced SIMD and floating-point instructions. It's enabled by default for-march=armv8.6-a. Using this with architectures before Armv8.2-A isn't supported 🔢f32mm— Enable 32-bit Floating point Matrix Multiply instructions. This also turns on SVE instructions. Using this with architectures before Armv8.2-A isn't supported 🧮f64mm— Enable 64-bit Floating point Matrix Multiply instructions. This also turns on SVE instructions. Using this with architectures before Armv8.2-A isn't supported 🧮bf16— Enable brain half-precision floating-point instructions. This also turns on Advanced SIMD and floating-point instructions. It's enabled by default for-march=armv8.6-a. Using this with architectures before Armv8.2-A isn't supported 🧠ls64— Enable the 64-byte atomic load and store instructions for accelerators 🚀mops— Enable the instructions that speed up memory operations like "memcpy", "memmove", "memset". It's enabled by default for-march=armv8.8-a💨flagm— Enable the Flag Manipulation instructions Extension 🚩flagm2— Enable the FlagM2 flag conversion instructions 🔁pauth— Enable the Pointer Authentication Extension 🔑cssc— Enable the Common Short Sequence Compression instructions 🗜️cmpbr— Enable the shorter compare and branch instructions, "cbb", "cbh" and "cb" ⚡sme— Enable the Scalable Matrix Extension 🧊sme-i16i64— Enable the FEAT_SME_I16I64 extension to SME. This also turns on SME instructions 🧊sme-f64f64— Enable the FEAT_SME_F64F64 extension to SME. This also turns on SME instructions 🧊sme2— Enable the Scalable Matrix Extension 2. This also turns on SME instructions 🧊sme-f8f16— Enable the FEAT_SME_F8F16 extension to SME. This also turns on SME2 and FP8 instructions 🧊sme-f8f32— Enable the FEAT_SME_F8F32 extension to SME. This also turns on SME2 and FP8 instructions 🧊sme-b16b16— Enable the FEAT_SME_B16B16 extension to SME. This also turns on SME2 and SVE_B16B16 instructions 🧊sme-f16f16— Enable the FEAT_SME_F16F16 extension to SME. This also turns on SME2 instructions 🧊sme2p1— Enable the Scalable Matrix Extension version 2.1. This also turns on SME2 instructions 🧊fcma— Enable the complex number SIMD extensions 🔢jscvt— Enable the "fjcvtzs" JavaScript conversion instruction 📜frintts— Enable floating-point round to integral value instructions 🎯wfxt— Enable the "wfet" and "wfit" instructions ⏳xs— Enable the XS memory attribute extension 🧱lse128— Enable the LSE128 128-bit atomic instructions extension. This also turns on LSE instructions 🔐d128— Enable support for 128-bit system register read/write instructions. This also turns on the LSE128 extension 🗝️gcs— Enable support for the Armv9.4-a Guarded Control Stack extension 🏰the— Enable support for the Armv8.9-a/9.4-a translation hardening extension 🛠️rcpc2— Enable the RCpc2 extension 💜rcpc3— Enable the RCpc3 (Release Consistency) extension 💜fp8— Enable the fp8 (8-bit floating point) extension 🌟fp8fma— Enable the fp8 (8-bit floating point) multiply accumulate extension ✖️ssve-fp8fma— Enable the fp8 (8-bit floating point) multiply accumulate extension in streaming mode 🌊fp8dot4— Enable the fp8 (8-bit floating point) to single-precision 4-way dot product extension 🎀ssve-fp8dot4— Enable the fp8 (8-bit floating point) to single-precision 4-way dot product extension in streaming mode 🌊fp8dot2— Enable the fp8 (8-bit floating point) to half-precision 2-way dot product extension 🎀ssve-fp8dot2— Enable the fp8 (8-bit floating point) to half-precision 2-way dot product extension in streaming mode 🌊faminmax— Enable the Floating Point Absolute Maximum/Minimum extension 📏lut— Enable the Lookup Table extension 🗺️sme-lutv2— Enable the SME Lookup Table v2 (LUTv2) extension 🗺️cpa— Enable the Checked Pointer Arithmetic instructions 🧷sve-b16b16— Enable the SVE non-widening brain floating-point ("bf16") extension. This only has an effect when "sve2" or "sme2" are also enabled 🧠sve-bfscale— Enable the SVE_BFSCALE extension ⚖️
Feature crypto implies aes, sha2, and simd, which implies fp. Conversely, nofp implies nosimd, which implies nocrypto, noaes and nosha2. So they all come as a little package deal 🎀
🌸 Adapteva Epiphany Options 🌸
These -m options are defined for Adapteva Epiphany 🦋
-mhalf-reg-file,-mno-half-reg-file— Don't allocate any register in the range "r32"..."r63". That lets code run on hardware variants that don't have these registers 💅-mprefer-short-insn-regs,-mno-prefer-short-insn-regs— Preferentially allocate registers that allow short instruction generation. This can bump up the instruction count, so it might shrink or grow overall code size 🤷♀️-mbranch-cost=num— Set the cost of branches to roughlynum"simple" instructions. This cost is only a heuristic and isn't guaranteed to give consistent results across releases 🧮-mcmove,-mno-cmove— Enable the generation of conditional moves ✨-mnops=num— EmitnumNOPs before every other generated instruction 🫧-mno-soft-cmpsf,-msoft-cmpsf— okay so this pair is about single-precision floating-point comparisons 🦋 With-mno-soft-cmpsf, the compiler emits anfsubinstruction and checks the flags instead. It's faster than a software comparison, BUT it can get wrong answers when NaNs are involved, or when two different small numbers subtract to zero, which is so not it 💀 The default is-msoft-cmpsf, which uses slower software comparisons that are IEEE-compliant. Safe and sound, just not the speed demon 🫶-mstack-offset=num— this sets the gap between the top of the stack and the stack pointer 🧚 A value of 8 means the eight bytes fromsp+0throughsp+7can be used by leaf functions without stack allocation 🍓 Heads up though: values other than 8 or 16 are untested and unlikely to work 🙈 This option also changes the ABI, so compiling a program with a different stack offset than the one your libraries were built with generally doesn't work 😭 It's useful if you're testing whether a different offset gives you better code. But if you actually want working programs with a different offset, the move is to configure the toolchain with the appropriate--with-stack-offset=numoption 🎀-mno-round-nearest,-mround-nearest—-mno-round-nearestmakes the scheduler assume the rounding mode has been set to truncating 🌸 The default is-mround-nearest.-mlong-calls— if an attribute doesn't say otherwise, this assumes every call might be beyond the offset range of theb/blinstructions 🧸 So the function address gets loaded into a register before the (otherwise direct) call. This is the default, bestie.-mshort-calls— if an attribute doesn't say otherwise, this assumes all direct calls are in range of theb/blinstructions, so those instructions get used for direct calls ⚡ The default is-mlong-calls. Also note that-mlong-callsis equivalent to-mno-short-calls, and-mno-long-callsis equivalent to-mshort-calls. It's giving mirror energy 🪞-msmall16,-mno-small16— this assumes addresses can be loaded as 16-bit unsigned values 💅 It doesn't apply to function addresses where-mlong-callssemantics are in effect.-mfp-mode=mode— this sets the prevailing mode of the floating-point unit, which decides the floating-point mode that's provided and expected at function call and return ✨ If you match it to the mode you mostly need at function start, your programs can get smaller and faster by skipping unnecessary mode switches 🔥 Themodecan be one of these: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 one's perfect for libraries or compilation units you might drop into different programs with different FPU modes. The convenience of a single object file outweighs the extra size and speed overhead of mode switching, compared with a more specific pick 👑truncate— the mode used for floating-point calculations with truncating (round towards zero) rounding. That includes conversion from floating point to integer.round-nearest— the mode used for floating-point calculations with round-to-nearest-or-even rounding.int— the mode used to do integer calculations in the FPU, like integer multiply or integer multiply-and-accumulate.
The default is -mfp-mode=caller.
-mmay-round-for-trunc,-mno-may-round-for-trunc— this lets floating point to integer truncation get swapped out for rounding, so you can save on mode switching 🌈 It's disabled by default.-mfp-iarith,-mno-fp-iarith— this turns on using the floating-point unit for integer add and subtract 🧮 It's disabled by default.-msplit-lohi,-mno-split-lohi,-mpost-inc,-mno-post-inc,-mpost-modify,-mno-post-modify— these are code generation tweaks 🍓 They control, 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.-mno-vect-double— this changes the preferred SIMD mode to SImode 🎀 The default is-mvect-double, which uses DImode as the preferred SIMD mode.-max-vect-align=num— this is the maximum alignment for SIMD vector mode types.numcan be 4 or 8, and the default is 8 🫶 Note that this is an ABI change, even though lots of library function interfaces are unaffected if they don't use SIMD vector modes in places that affect the size and/or alignment of relevant types.-msplit-vecmove-early,-mno-split-vecmove-early— this splits vector moves into single word moves before reload 🧠 In theory it can give better register allocation, but so far the reverse seems to be generally the case 😭-m1reg-reg— this specifies a register to hold the constant-1, which makes loading small negative constants and certain bitmasks faster ⚡ Allowable values for reg arer43andr63, which use that register as a fixed register, andnone, which means no register is used for this purpose. The default is-m1reg-none.
🌈 AMD GCN Options 🌈
These options are defined specifically for the AMD GCN port, so they're for the GPU girlies 🎮
-march=gpu,-mtune=gpu— this sets the architecture type or tuning forgpu💖 The supported values forgpuare:gfx900— compile for GCN5 Vega 10 devices (gfx900).gfx902— compile for GCN5 Vega gfx902 devices. (Experimental)gfx904— compile for GCN5 Vega gfx904 devices. (Experimental)gfx906— compile for GCN5 Vega 20 devices (gfx906).gfx908— compile for CDNA1 Instinct MI100 series devices (gfx908).gfx909— compile for GCN5 Vega gfx909 devices. (Experimental)gfx90a— compile for CDNA2 Instinct MI200 series devices (gfx90a).gfx90c— compile for GCN5 Vega 7 devices (gfx90c).gfx942— compile for CDNA3 Instinct MI300 series devices (gfx942). (Experimental)gfx950— compile for CDNA3 gfx950 devices. (Experimental)gfx9-generic— compile generic code for Vega devices, executable on the following subset of GFX9 devices: gfx900, gfx902, gfx904, gfx906, gfx909 and gfx90c.gfx9-4-generic— compile generic code for CDNA3 devices, executable on the following subset of GFX9 devices: gfx942 and gfx950. (Experimental)gfx1030— compile for RDNA2 gfx1030 devices (GFX10 series).gfx1031— compile for RDNA2 gfx1031 devices (GFX10 series). (Experimental)gfx1032— compile for RDNA2 gfx1032 devices (GFX10 series). (Experimental)gfx1033— compile for RDNA2 gfx1033 devices (GFX10 series). (Experimental)gfx1034— compile for RDNA2 gfx1034 devices (GFX10 series). (Experimental)gfx1035— compile for RDNA2 gfx1035 devices (GFX10 series). (Experimental)gfx1036— compile for RDNA2 gfx1036 devices (GFX10 series).gfx10-3-generic— compile generic code for GFX10-3 devices, executable on gfx1030, gfx1031, gfx1032, gfx1033, gfx1034, gfx1035, and gfx1036.gfx1100— compile for RDNA3 gfx1100 devices (GFX11 series).gfx1101— compile for RDNA3 gfx1101 devices (GFX11 series). (Experimental)gfx1102— compile for RDNA3 gfx1102 devices (GFX11 series). (Experimental)gfx1103— compile for RDNA3 gfx1103 devices (GFX11 series).gfx1150— compile for RDNA3 gfx1150 devices (GFX11 series). (Experimental)gfx1151— compile for RDNA3 gfx1151 devices (GFX11 series). (Experimental)gfx1152— compile for RDNA3 gfx1152 devices (GFX11 series). (Experimental)gfx1153— compile for RDNA3 gfx1153 devices (GFX11 series). (Experimental)gfx11-generic— compile generic code for GFX11 devices, executable on gfx1100, gfx1101, gfx1102, gfx1103, gfx1150, gfx1151, gfx1152, and gfx1153.
-mgang-private-size=bytes— this sets how much local data-share (LDS) memory gets reserved for gang-private variables 💜 The default is 512.-msram-ecc=on,-msram-ecc=off,-msram-ecc=any— these compile binaries for devices with the SRAM-ECC feature enabled, disabled, or either mode 🔐 Some devices let you turn this on per-process, and your compiled code has to match the device's mode. The default isany, for devices that support it.-mxnack=on,-mxnack=off,-mxnack=any— these compile binaries for devices with the XNACK feature enabled, disabled, or either mode 🌸 Some devices always require 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.-Wopenacc-dims,-Wno-openacc-dims— these control warnings about invalid OpenACC dimensions ⚠️
🧚 ARC Options ✨
The following options control the architecture variant that code is being compiled for 🦖
-mbarrel-shifter— this generates instructions supported by the barrel shifter. It's the default unless-mcpu=ARC601or-mcpu=ARCEMis in effect.-mjli-always— this forces a function call using thejli_sinstruction 💅 It's only valid for the ARCv2 architecture.-mcpu=cpu— this sets the architecture type, register usage, and instruction scheduling parameters forcpu👑 There are shortcut alias options too, for backward compatibility and convenience. The 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 the ARC EM4 DMIPS CPU with the single-precision floating-point extension.em4_fpuda— 💅 Compile for the ARC EM4 DMIPS CPU with single-precision floating-point and double assist instructions.hs— ✨ Compile for the ARC HS CPU with no hardware extensions except the atomic instructions. Minimal, but still atomic 💜.hs34— 🦋 Compile for the ARC HS34 CPU.hs38— 🎀 Compile for the ARC HS38 CPU.hs38_linux— 👑 Compile for the ARC HS38 CPU with all hardware extensions on. Full glam mode.hs4x— 🌈 Compile for the ARC HS4x CPU.hs4xd— 🔥 Compile for the ARC HS4xD CPU.hs4x_rel31— ⭐ Compile for the ARC HS4x CPU release 3.10a.arc600_norm— 🍓 Compile for the ARC 600 CPU with "norm" instructions enabled.arc600_mul32x16— 🧚 Compile for the ARC 600 CPU with "norm" and 32x16-bit multiply instructions enabled.arc600_mul64— 💖 Compile for the ARC 600 CPU with "norm" and "mul64"-family instructions enabled.arc601_norm— 🌸 Compile for the ARC 601 CPU with "norm" instructions enabled.arc601_mul32x16— 🦋 Compile for the ARC 601 CPU with "norm" and 32x16-bit multiply instructions enabled.arc601_mul64— 💜 Compile for the ARC 601 CPU with "norm" and "mul64"-family instructions enabled.nps400— 🫶 Compile for ARC 700 on the NPS400 chip.em_mini— 🌙 Compile for the ARC EM minimalist configuration, which features a reduced register set. Less is more, bestie 🤍.
-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,-mdpfp-lrsr— 🎀 Control whether "lr" and "sr" instructions use FPX extension aux registers. This is enabled by default, so you're already set ✨.-mea— 👑 Generate extended arithmetic instructions. Currently only "divaw", "adds", "subs", and "sat16" are supported. This is only valid for-mcpu=ARC700, so don't try it elsewhere 🙈.-mmul32x16— 💖 Generate 32x16-bit multiply and multiply-accumulate instructions.-mmul64— 🧚 Generate "mul64" and "mulu64" instructions. Only valid for-mcpu=ARC600, so keep it in its lane 💅.-mnorm— 🌈 Generate "norm" instructions. This is the default if-mcpu=ARC700is in effect, so it's basically automatic.-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. Only valid for-mcpu=ARC700. Main character SIMD energy 💅.-msoft-float— 🙈 This option is ignored. It's only here for compatibility, bestie. 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. Not the one you're looking for 💀.-mswap— 🍓 Generate "swap" instructions.-matomic— ✨ This enables use of the locked load/store conditional extension to implement atomic memory built-in functions. It's not available for ARC 6xx or ARC EM cores, so skip it there 🫶.-mdiv-rem— 💜 Enable "div" and "rem" instructions for ARCv2 cores.-mcode-density,-mno-code-density— 🌸 Enable code density instructions for ARC EM. This option is on by default for ARC HS, so you only need the flag if you're on EM 🧚.-mll64— 🦋 Enable double load/store operations for ARC HS cores.-mtp-regno=regno— 👑 Specify the thread pointer register number.-mbitops— 🔥 Enable use of NPS400 bit operations.-mcmem— 🌈 Enable use of the NPS400 xld/xst extension.-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 value. 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. The 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— Enables support for double-precision floating-point, square-root and divide hardware extensions. This option includes optionfpus_div. Not available for ARC EM.fpus_fma— Enables support for single-precision floating-point and fused multiply and add hardware extensions.fpud_fma— Enables support for double-precision floating-point and fused multiply and add hardware extensions. This option includes optionfpus_fma. Not available for ARC EM.fpus_all— Enables support for all single-precision floating-point hardware extensions.fpud_all— Enables support for all single- and double-precision floating-point hardware extensions. Not available for ARC EM.
-mirq-ctrl-saved=register-range, blink, lp_count— 🛡️ Specifies the general-purpose registers that the processor automatically saves and restores on interrupt entry and exit. The register-range is written as two registers separated by a dash. The range always starts with "r0", and the upper limit is the "fp" register.blinkandlp_countare optional. This option is only valid for ARC EM and ARC HS cores. 💜-mrgf-banked-regs=number— 🌸 Specifies the number of registers replicated in the second register bank on entry to a fast interrupt. Fast interrupts are interrupts with the highest priority level, P0. These interrupts save only the PC and STATUS32 registers, so they avoid memory transactions during interrupt entry and exit sequences. Use this option when you're using fast interrupts on an ARC V2 family processor. Permitted values are 4, 8, 16, and 32. ⚡-mlpc-width=width— 🧮 Specify the width of the "lp_count" register. Valid values for width are 8, 16, 20, 24, 28, and 32 bits. The default width is fixed to 32 bits. If the width is less than 32, the compiler does not attempt to transform loops in your program to use the zero-delay loop mechanism unless it is known that the "lp_count" register can hold the required loop-counter value. Depending on the width specified, the compiler and run-time library might continue to use the loop mechanism for various needs. This option defines the macro__ARC_LPC_WIDTH__with the value of width. 🦋-mrf16— 🍓 This option instructs the compiler to generate code for a 16-entry register file. This option defines the__ARC_RF16__preprocessor macro. ✨-mbranch-index— 🧚 Enable use of "bi" or "bih" instructions to implement jump tables. 🌈
These next ones get passed down to the assembler and also define preprocessor macro symbols, so they're doing double duty 💅.
-mlock— 🔒 Passed down to the assembler to enable the locked load/store conditional extension. It also sets the preprocessor symbol__Xlock.-mswape— 🍓 Passed down to the assembler to enable the swap byte ordering extension instruction. It also sets the preprocessor symbol__Xswape.-mxy— 💖 Passed down to the assembler to enable the XY memory extension. It also sets the preprocessor symbol__Xxy.
And this one's all about how the assembly code gets annotated 📝.
-misize— 🫧 Annotate assembler instructions with estimated addresses.
Next up, the options that get passed through to the linker 🔗:
-marclinux,-mno-arclinux— okay so this one passes stuff through to the linker and tells it to use the "arclinux" emulation 💅 It's on by default in toolchains built forarc-linux-uclibcandarceb-linux-uclibctargets, but only when profiling is not requested 🌸-marclinux_prof,-mno-arclinux_prof— same vibe, but for the "arclinux_prof" emulation 🔮 This one is on by default for those samearc-linux-uclibcandarceb-linux-uclibctargets, except this time it's when profiling is requested ✨
Next up, these options control the semantics of generated code 🧠
-mlong-calls— calls get generated as register indirect calls, which gives you access to the full 32-bit address range 🚀 main character energy, no limits 👑-mmedium-calls,-mno-medium-calls— ngl this one is a whole mood 🦋 It stops calls from using less than the 25-bit addressing range, which is the offset an unconditional branch-and-link instruction gets. 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 num— externally-visible data goes into a small data section, as long as it's no bigger thannumbytes 🍓 The default fornumis4for any ARC configuration, or8when you've got double load/store operations 💜-mno-sdata— don't generate sdata references 🙅♀️ This is the default for toolchains built forarc-linux-uclibcandarceb-linux-uclibctargets 🫶-mvolatile-cache,-mno-volatile-cache— this controls how volatile references get accessed 🧚 The default is-mvolatile-cache, which uses ordinary cached memory accesses for volatile references. If you want cache bypass for volatile references instead, go with-mno-volatile-cache🌸
Next, these options fine tune code generation 💅
-mauto-modify-reg— turns on the use of pre/post modify with register displacement ✨-mno-brcc,-mbrcc— this one controls a target-specific pass inarc_reorgthat generates compare-and-branch (brcc) instructions 🔥 It's enabled by default. Heads up, it has no effect on generation of these instructions when they're driven by the combiner pass 🙈-mcase-vector-pcrel— uses PC-relative switch case tables so case table shortening can happen 🦋 This is the default for-Os💖-mno-cond-exec— disables the ARCompact-specific pass that generates conditional execution instructions 💀 Okay real talk, the target-independent pass for conditional execution is often lacking, because of delay slot scheduling and interactions between operand numbers, literal sizes, instruction lengths, and conditional execution support. So the ARC port keeps a special pass around that hunts for more conditional execution opportunities after register allocation, branch shortening, and delay slot scheduling are done 🧠 This pass generally, but not always, improves performance and code size, but it costs extra compilation time, which is why there's an option to switch it off 🍓 If call instructions are exceeding their allowable offset range because they got conditionalized, you should consider using-mmedium-callsinstead 🫶-mearly-cbranchsi— enables pre-reload use of the "cbranchsi" pattern 🌈-mindexed-loads— enables the use of indexed loads 🎀 This can be problematic though, because some optimizers then assume indexed stores exist, and that's not the case 😭-mlra-priority-none— doesn't indicate any priority for target registers 🫠-mlra-priority-compact— indicates target register priority forr0..r3/r12..r15💜-mlra-priority-noncompact— reduces target register priority forr0..r3/r12..r15🌸-mmillicode— when you're optimizing for size with-Os, prologues and epilogues that have to save or restore a big pile of registers often get shortened by calling a special function in libgcc, which is called a millicode call 🧚 But these calls can cause performance issues, and/or linking issues when you link in a nonstandard way, so this option lets you turn millicode call generation on or off 🔁-mcode-density-frame— lets the compiler emit "enter" and "leave" instructions 🦋 These are only valid for CPUs with the code-density feature, so don't try it elsewhere 🙅♀️-msize-level=level— fine-tunes size optimization with regards to instruction lengths and alignment 📏 The recognized values forlevelare:0— no size optimization. This level is deprecated and treated like1😬1— short instructions get used opportunistically 🌷2— on top of that, alignment of loops and of code after barriers gets dropped 🍃3— on top of that, optional data alignment gets dropped, and the optionOsis enabled 👑
This defaults to 3 when -Os is in effect. Otherwise, when this isn't set, the behavior is equivalent to level 1 💅
-mtune=cpu— sets instruction scheduling parameters forcpu, overriding anything implied by-mcpu=🎯 Supported values forcpuare:ARC600— tunes for ARC600 CPU 🧸ARC601— tunes for ARC601 CPU 🧸ARC700— tunes for ARC700 CPU with standard multiplier block ✨ARC700-xmac— tunes for ARC700 CPU with XMAC block 🔥ARC725D— tunes for ARC725D CPU 🌈ARC750D— tunes for ARC750D CPU 💖core3— tunes for ARCv2 core3 type CPU. This option enables usage of the "dbnz" instruction 🧚release31a— tunes for ARC4x release 3.10a 🦋
-mmultcost=num— sets the cost to assume for a multiply instruction, with4being equal to a normal instruction 💜
🦋 ARM Options 🦋
These -m options are defined for the ARM port 🌸
-mabi=name— generates code for the specified ABI 🎀 Permissible values are:apcs-gnu,atpcs,aapcsandaapcs-linux✨-mapcs-frame— generates a stack frame that's compliant with the ARM Procedure Call Standard for all functions, even if it's not strictly necessary for the code to run correctly 🧱 If you specify-fomit-frame-pointerwith this option, stack frames don't get generated for leaf functions 🍃 The default is-mno-apcs-frame. Heads up, this option is deprecated 😭-mapcs— a synonym for-mapcs-frame, and it's deprecated too 🙈-mthumb-interwork— generates code that supports calling between the ARM and Thumb instruction sets 🤝 Without this option, on pre-v5 architectures, the two instruction sets can't be reliably used inside one program 💀 The default is-mno-thumb-interwork, since slightly larger code gets generated when-mthumb-interworkis specified 📏 In AAPCS configurations this option is meaningless 🫠-msched-prolog,-mno-sched-prolog— allows or prevents reordering of instructions in the function prologue, or merging those instructions with the instructions in the function's body 🧠 With-mno-sched-prolog, all functions start with a recognizable set of instructions (or one of a choice from a small set of different function prologues), and that info can be used to locate the start of functions inside an executable piece of code 🔍 The default is-msched-prolog💖-mfloat-abi=name— specifies which floating-point ABI to use 🧮 Permissible values are:soft,softfpandhard🌈softmakes GCC generate output containing library calls for floating-point operations 📚softfpallows code generation using hardware floating-point instructions, but still uses the soft-float calling conventions 🛠️hardallows generation of floating-point instructions and uses FPU-specific calling conventions ⚡
The default depends on the specific target configuration 🎯 > Note that the hard-float and soft-float ABIs are not link-compatible. You have to compile your entire program with the same ABI, and link with a compatible set of libraries, or it's gonna be a whole disaster 💀
-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 code for a little-endian processor, so you have to ask for this one explicitly 🌊-mbe8,-mbe32— when linking a big-endian image, these let you select between BE8 and BE32 formats 🧩 The option has no effect for little-endian images and is ignored 🙅♀️ The default depends on the selected target architecture. For ARMv6 and later architectures the default is BE8, and for older architectures the default is BE32 🕰️ Heads up, BE32 format has been deprecated by ARM 😭-march=name[+extension...]— specifies the name of the target ARM architecture 🏹 GCC uses this name to figure out what kind of instructions it can emit when generating assembly code 🧑💻 You can use this option together with-mcpu=, or instead of it 🫶
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, iwmmxt and iwmmxt2 🧾
Additionally, the following architectures, which lack support for the Thumb execution state, are recognized but support is deprecated: armv4 🥀
Lots of the architectures support extensions 🧩 You can add these by appending +extension to the architecture name. Extension options get processed in order, and capabilities accumulate. An extension will also enable any necessary base extensions it depends on. For example, the +crypto extension will always enable the +simd extension 🔐 The exception to the additive construction is for extensions prefixed with +no...: these disable the specified option and any other extensions that may depend on the presence of that extension 🚫
For example, -march=armv7-a+simd+nofp+vfpv4 is equivalent to writing -march=armv7-a+vfpv4, since the +simd option is entirely disabled by the +nofp option that follows it 🫠✨
Okay bestie, most of these extension names are super generic 🥹 but what they actually do depends on which architecture you put them on ✨ Like, +simd works on both armv7-a and armv8-a, but on armv7-a it turns on the original ARMv7-A Advanced SIMD (Neon) extensions, and on armv8-a you get the ARMv8-A version 💅
Here's the tea 🫖 The list below shows which extensions each architecture supports. If an architecture isn't mentioned, it straight up supports zero extensions 💀
armv5te,armv6,armv6j,armv6k,armv6kz,armv6t2,armv6z,armv6zk🧚 these all share the same two extensions:+fp— The VFPv2 floating-point instructions.+vfpv2works as an alias for this one, so you can use either.+nofp— Turns the floating-point instructions off.
armv7🌈 the common subset of the ARMv7-A, ARMv7-R and ARMv7-M architectures.+fp— The VFPv3 floating-point instructions, with 16 double-precision registers.+vfpv3-d16is an alias for this one. Heads up, bestie: the base ARMv7-M architecture doesn't support floating-point, but it's compatible with both ARMv7-A and ARMv7-R.+nofp— Turns the floating-point instructions off.
armv7-a👑 the main character of the ARMv7 family, with the most extensions 🔥+mp— The multiprocessing extension.+sec— The security extension.+fp— The VFPv3 floating-point instructions, with 16 double-precision registers.+vfpv3-d16is an alias for this one.+simd— The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions.+neonand+neon-vfpv3can both be used as aliases for this one.+vfpv3— The VFPv3 floating-point instructions, but with 32 double-precision registers.+vfpv3-d16-fp16— The VFPv3 floating-point instructions with 16 double-precision registers, plus the half-precision floating-point conversion operations.+vfpv3-fp16— 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, 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, plus 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. Floating-point stays on, though 🙌+nofp— Disables the floating-point and Advanced SIMD instructions.
armv7ve🦋 the extended version of ARMv7-A, with support for virtualization.+fp— The VFPv4 floating-point instructions, with 16 double-precision registers.+vfpv4-d16is an alias for this one.+simd— The Advanced SIMD (Neon) v2 and the VFPv4 floating-point instructions.+neon-vfpv4is 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, plus the half-precision floating-point conversion operations.+vfpv3-fp16— 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, with 16 double-precision registers.+vfpv4— The VFPv4 floating-point instructions, with 32 double-precision registers.+neon— The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions.+neon-vfpv3is an alias for this one.+neon-fp16— The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions, plus the half-precision floating-point conversion operations.+nosimd— Disables the Advanced SIMD instructions. Floating-point stays on 🫶+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.+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 also turns on the Advanced SIMD and floating-point instructions.+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,armv8.3-a💜 these two share the same list:+fp16— The half-precision floating-point data processing instructions. This also turns on the Advanced SIMD and floating-point instructions.+fp16fml— The half-precision floating-point fmla extension. This also turns on the half-precision floating-point extension, plus the Advanced SIMD and floating-point instructions.+simd— The ARMv8.1-A Advanced SIMD and floating-point instructions.+crypto— The cryptographic instructions. This also turns on the Advanced SIMD and floating-point instructions.+dotprod— Enables the Dot Product extension. This also turns on the 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 turns on the Advanced SIMD and floating-point instructions.+bf16— The Brain half-precision floating-point instructions. This also turns on the Advanced SIMD and floating-point instructions.
armv8.4-a🔥+fp16— The half-precision floating-point data processing instructions. This also turns on the Advanced SIMD and floating-point instructions, plus the Dot Product extension and the half-precision floating-point fmla extension.+simd— The ARMv8.3-A Advanced SIMD and floating-point instructions, plus the Dot Product extension.+crypto— The cryptographic instructions. This also turns on 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 turns on the Advanced SIMD and floating-point instructions.+bf16— The Brain half-precision floating-point instructions. This also turns on the Advanced SIMD and floating-point instructions.
armv8.5-a🌸+fp16— The half-precision floating-point data processing instructions. This also turns on the Advanced SIMD and floating-point instructions, plus the Dot Product extension and the half-precision floating-point fmla extension.+simd— The ARMv8.3-A Advanced SIMD and floating-point instructions, plus the Dot Product extension.+crypto— The cryptographic instructions. This also turns on 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 turns on the Advanced SIMD and floating-point instructions.+bf16— The Brain half-precision floating-point instructions. This also turns on the Advanced SIMD and floating-point instructions.
armv8.6-a🧚+fp16— The half-precision floating-point data processing instructions. This also turns on the Advanced SIMD and floating-point instructions, plus the Dot Product extension and the half-precision floating-point fmla extension.+simd— The ARMv8.3-A Advanced SIMD and floating-point instructions, plus the Dot Product extension.
+crypto— 🔐 The cryptographic instructions, and this one also flips on the Advanced SIMD and floating-point instructions plus the Dot Product extension ✨+nocrypto— 🙅 Disable the cryptographic extension+nofp— 💀 Disable the floating-point, Advanced SIMD and cryptographic instructions. Everything spicy, gone+i8mm— 🧮 The 8-bit Integer Matrix Multiply instructions. This one also enables Advanced SIMD and floating-point instructions+bf16— 🧠 The Brain half-precision floating-point instructions. This one also enables Advanced SIMD and floating-point instructions
🦋 armv7-r
+fp.sp— 🎀 The single-precision VFPv3 floating-point instructions.+vfpv3xdworks as an alias for this extension too+fp— 💜 The VFPv3 floating-point instructions with 16 double-precision registers.+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, plus the half-precision floating-point conversion operations+vfpv3-d16-fp16— ✨ The VFPv3 floating-point instructions with 16 double-precision registers, plus the half-precision floating-point conversion operations+nofp— 🙅 Disable the floating-point extension+idiv— ➗ The ARM-state integer division instructions+noidiv— 🫠 Disable 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— 🙅 Disable 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— 🙅 Disable the floating-point extension+cdecp0,+cdecp1, ... ,+cdecp7— 🔧 Enable the Custom Datapath Extension (CDE) on selected coprocessors, according to the numbers given in the options in the range 0 to 7+pacbti— 🛡️ Enable the Pointer Authentication and Branch Target Identification Extension
👑 armv8-m.main
+dsp— 🎶 The DSP instructions+nodsp— 🙅 Disable the DSP extension+fp— ⭐ The single-precision floating-point instructions+fp.dp— ⭐ The single- and double-precision floating-point instructions+nofp— 🙅 Disable the floating-point extension+cdecp0,+cdecp1, ... ,+cdecp7— 🔧 Enable 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— 🙅 Disable the cryptographic instructions+nofp— 💀 Disable the floating-point, Advanced SIMD and cryptographic instructions
-march=native causes the compiler to auto-detect the architecture of the build computer. ✨ At present, this feature is only supported on GNU/Linux, and not all architectures are recognized. If the auto-detect is unsuccessful, the option has no effect 🙈
-march=unset causes the compiler to ignore any -march=... options that appear earlier on the command line and behave as if the option was never passed. 🧹 This is useful to avoid warnings about conflicting CPU and architecture options when the two produce different architecture specifications.
💖 -mtune=name
This option specifies the name of the target ARM processor that GCC should tune the performance of the code for. 🎯 For some ARM implementations, you can get better performance by using this option. 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 it gets even better 🍭 This option can also tell GCC to tune the performance of the code for a big.LITTLE system. Permissible names 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 tells GCC to tune the performance for a blend of processors within architecture arch. 🌈 The goal is code that runs well on the most popular processors right now, balancing optimizations that benefit some CPUs in the range while avoiding performance pitfalls of the other CPUs. The effects of this option may change in future GCC versions as CPU models come and go 🕰️
-mtune permits the same extension options as -mcpu, but the extension options do not affect the tuning of the generated code 🤷
-mtune=native causes the compiler to auto-detect the CPU of the build computer. ✨ At present, this feature is only supported on GNU/Linux, and not all architectures are recognized. If the auto-detect is unsuccessful, the option has no effect 🙈
🎀 -mcpu=name[+extension...]
This specifies the name of the target ARM processor. 👑 GCC uses this name to work out the target ARM architecture (as if you'd specified -march) and the ARM processor type to tune for performance (as if you'd specified -mtune). If you use this option together with -march or -mtune, those options take precedence over the matching part of this option 💅
Lots of the supported CPUs have optional architectural extensions. 🧩 When that's the case, the extensions are normally enabled by default. If implementations that lack the extension exist, you can use the extension syntax to disable the ones that have been left out. For floating-point and Advanced SIMD (Neon) instructions, you also have to think about the settings of -mfloat-abi and -mfpu: floating-point and Advanced SIMD instructions will only be used if -mfloat-abi is not set to soft, and any setting of -mfpu other than auto will override the available floating-point and SIMD extension instructions. 🫶
For example, cortex-a9 comes in three major configurations: integer only, with just a floating-point unit, or with floating-point and Advanced SIMD. The default is to enable all the instructions, but the extensions +nosimd and +nofp can be used to disable just the SIMD or both the SIMD and floating-point instructions, respectively 🦋
Permissible names for this option are the same as those for -mtune.
The following extension options are common to the listed CPUs 📝
+nodsp— 🙅 Disable 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— 🙅 Disable the Pointer Authentication and Branch Target Identification Extension oncortex-m52andcortex-m85+nomve— 🙅 Disable the M-Profile Vector Extension (MVE) integer and single precision floating-point instructions oncortex-m52,cortex-m55andcortex-m85+nomve.fp— 🙅 Disable the M-Profile Vector Extension (MVE) single precision floating-point instructions oncortex-m52,cortex-m55andcortex-m85+cdecp0,+cdecp1, ... ,+cdecp7— 🔧 Enable the Custom Datapath Extension (CDE) on selected coprocessors, according to the numbers given in the options in the range 0 to 7 oncortex-m52,cortex-m55andstar-mc1+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. It also disables the floating-point and SIMD instructions 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😭+nofp.dp— okay so this one switches OFF the double-precision bit of the floating-point instructions on cortex-r5, cortex-r7, cortex-r8, cortex-r52, cortex-r52plus and cortex-m7 💅+nosimd— this one turns off the SIMD instructions (but keeps the floating-point ones) on generic-armv7-a, cortex-a5, cortex-a7 and cortex-a9 🌸+crypto— bestie, this one ENABLES the cryptographic instructions on cortex-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-a53 and cortex-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. They mean the same thing as the extensions to -march=armv7-a ✨.
-mcpu=generic-arch is also allowed, and it's the same as -march=arch -mtune=generic-arch. Check out -mtune for more deets 🧚.
-mcpu=native tells the compiler to auto-detect the CPU of the build computer 👑. Right now this only works on GNU/Linux, and not every architecture gets recognized. If the auto-detect doesn't work out, the option does nothing 🙈.
-mcpu=unset makes the compiler ignore any -mcpu=... options that show up earlier on the command line, so it acts like that option was never passed at all 🫶. This is super useful for avoiding warnings about conflicting CPU and architecture options when the two give different architecture specs 💜.
-mfpu=name 🎀
This picks 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. Also, neon is an alias for neon-vfpv3, and vfp is an alias for vfpv2 🌈.
The setting auto is the default and it's kind of special ✨. It makes the compiler pick the floating-point and Advanced SIMD instructions based on the settings of -mcpu and -march 💅.
Heads up, bestie: if the selected floating-point hardware includes the NEON extension (e.g.-mfpu=neon), floating-point operations are NOT generated by GCC's auto-vectorization pass unless-funsafe-math-optimizationsis also specified 😭. This is because NEON hardware doesn't fully implement the IEEE 754 standard for floating-point arithmetic (in particular, denormal values are treated as zero), so using NEON instructions may lead to a loss of precision 💀.
You can also set the fpu name at function level by 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 value varies for different toolchains. For the COFF targeted toolchain, the default is 8. A value of 64 is only allowed if the underlying ABI supports it 👑.
Bigger numbers can produce faster, more efficient code, but they can also make your program bigger 🧚. Different values are potentially incompatible 💅. Code compiled with one value can't necessarily be expected to work with code or libraries compiled with another value, if they swap info using structures or unions 😭.
This option is deprecated, so maybe don't build your life around it 💀.
-mabort-on-noreturn 🌈
This generates a call to the function abort at the end of a noreturn function 🔥. It runs if the function tries to return ⭐.
-mlong-calls, -mno-long-calls 💜
These tell the compiler to make function calls by first loading the address of the function into a register, and then doing a subroutine call on that register 🦋. You need this switch if the target function lives outside the 64-megabyte addressing range of the offset-based version of the subroutine call instruction 🌸.
Even with this switch on, not every function call gets turned into a long call 🙈. The heuristic is 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 that 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 🫶. Heads up that these switches have no effect on how the compiler generates code for handling function calls via function pointers 💀.
-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 🎀.
-mpic-register=reg 🍓
This specifies the register to be used for PIC addressing 💖. For the standard PIC base case, the default is any suitable register the compiler picks. For the single PIC base case, the default is R9 if the target is EABI based or stack-checking is enabled, and otherwise the default is R10 🌈.
-mpic-data-is-text-relative ⭐
This assumes the displacement between the text and data segments is fixed at static link time 🔥. That lets you use PC-relative addressing operations to access data known to be in the data segment 🦋. For non-VxWorks RTP targets, this option is enabled by default. When it's disabled on those targets, it enables -msingle-pic-base by default 💜.
-mpoke-function-name 🌸
This writes the name of each function into the text section, directly before the function prologue 🙈. The generated code looks kinda 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 doing a stack backtrace, code can inspect 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, then we know there's a function name embedded right before this location, with length ((pc[-3]) & 0xff000000) 🔥.
-mthumb, -marm 🦋
These let you pick between generating code that runs in ARM state and code that runs in Thumb state 💅. The default for most configurations is ARM state, but you can change that by configuring GCC with the --with-mode=state configure option 👑.
You can also override ARM and Thumb mode for each function by using the target("thumb") and target("arm") function attributes or pragmas ✨.
-mtpcs-frame 🎀
This generates a stack frame that's compliant with the Thumb Procedure Call Standard for all non-leaf functions 🌈. (A leaf function is one that doesn't call any other functions.) The default is -mno-tpcs-frame 💖.
-mtpcs-leaf-frame ⭐
This generates a stack frame that's compliant with the Thumb Procedure Call Standard for all leaf functions 🧚. (A leaf function is one that doesn't call any other functions.) The default is -mno-apcs-leaf-frame 🙈.
-mcallee-super-interworking 💜
This gives all externally visible functions in the file being compiled an ARM instruction set header, which switches to Thumb mode before executing the rest of the function 🌸. That way these functions can be called from non-interworking code 🫶. This option is not valid in AAPCS configurations, because interworking is already enabled by default 💀.
-mcaller-super-interworking 🔥
This lets calls via function pointers (including virtual functions) execute correctly, whether or not the target code was compiled for interworking 🦋. There's a small overhead in the cost of executing a function pointer when this option is enabled 😭. This option is not valid in AAPCS configurations, because interworking is already enabled by default 👑.
-mtp=name 🌈
This specifies the access model for the thread local storage pointer ✨. The model soft generates calls to __aeabi_read_tp. The other accepted models are tpidrurw, tpidruro and tpidrprw, which fetch the thread pointer directly from the corresponding system register (supported from the arm6k architecture and later) 💅. These system registers are accessed through the CP15 co-processor interface, and the argument cp15 is also accepted as a convenience alias of tpidruro 🎀.
soft— calls__aeabi_read_tptpidrurw,tpidruro,tpidrprw— read the thread pointer straight from the system register (arm6k and later) 🦋cp15— a convenience alias oftpidruro💖auto— uses the best available method for the selected processor 🧚
The default setting is auto 🫶.
-mtls-dialect=dialect 💜
This specifies the dialect to use for accessing thread local storage 🌸. Two dialects are supported: gnu and gnu2 🙈. The gnu dialect selects the original GNU scheme for supporting local and global dynamic TLS models 💅. The gnu2 dialect 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 require new assembler, linker and library support 😭. Initial and local exec TLS models are unaffected by this option and always use the original scheme ✨.
-mword-relocations 🔥
This only generates absolute relocations on word-sized values (i.e. R_ARM_ABS32) 🦋. It's enabled by default on targets (uClinux, SymbianOS) where the runtime loader imposes this restriction, and when -fpic or -fPIC is specified 🌈.
Watch out: this option conflicts with -mslow-flash-data 💀.
-mfix-cortex-m3-ldrd Some Cortex-M3 cores can corrupt data when ldrd instructions have overlapping destination and base registers. This option stops GCC from generating those instructions, and it's switched on by default when -mcpu=cortex-m3 is specified. 🛡️✨
-mfix-cortex-a57-aes-1742098 -mno-fix-cortex-a57-aes-1742098 -mfix-cortex-a72-aes-1655431 -mno-fix-cortex-a72-aes-1655431 Turns the mitigation for an erratum on Cortex-A57 and Cortex-A72 that messes with the AES crypto instructions on or off. It's on by default when either -mcpu=cortex-a57 or -mcpu=cortex-a72 is specified. 🔐💅
-munaligned-access -mno-unaligned-access Lets you turn reading and writing of 16- and 32-bit values from addresses that aren't 16- or 32-bit aligned on (or off). By default it's off for all pre-ARMv6, all ARMv6-M, and ARMv8-M Baseline architectures, and on 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 this option. If unaligned access is enabled, the preprocessor symbol __ARM_FEATURE_UNALIGNED is also defined. 🏷️
-mslow-flash-data Assumes loading data from flash is slower than fetching instructions, so literal loads get minimized for better performance. This 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 is using unified asm syntax. Right now it's off by default, which means divided syntax. This option has no impact on Thumb2, but that might change in future GCC releases. Divided syntax should be considered deprecated, so bye bye 👋💀
-mrestrict-it Restricts IT block generation so it follows the ARMv8-A rules. IT blocks can only contain a single 16-bit instruction from a select set of instructions. This is on by default for ARMv8-A Thumb mode. 🎀
-mpure-code Stops constant data from being placed in code sections. Also, when compiling for ELF object format, it gives all text sections the ELF processor-specific section attribute SHF_ARM_PURECODE. This is only available when generating non-PIC code for M-profile targets. 🌸
-mcmse Generates secure code according to the "ARMv8-M Security Extensions: Requirements on Development Tools Engineering Specification", which you can find at <https://developer.arm.com/documentation/ecm0359818/latest/>. Very official, very important 📜🔒
-mfix-cmse-cve-2021-35465 Mitigates a potential security issue with the VLLDM instruction on some M-profile devices when using CMSE (CVE-2021-365465). This is enabled by default when -mcpu= is used with cortex-m33, cortex-m35p, cortex-m52, cortex-m55, cortex-m85, or star-mc1. You can use -mno-fix-cmse-cve-2021-35465 to disable the mitigation. 🛡️🫶
-mstack-protector-guard=guard -mstack-protector-guard-offset=offset Generates stack protection code using a canary at guard. The supported locations are global for a global canary, or tls for a canary accessible through the TLS register. The option -mstack-protector-guard-offset= is for use with -fstack-protector-guard=tls, and it is not for use in user-land code. 🧠
-mfdpic -mno-fdpic Selects the FDPIC ABI, which uses 64-bit function descriptors to represent pointers to functions. When the compiler is configured for arm-*-uclinuxfdpiceabi targets, this is on by default and implies -fPIE if none of the PIC/PIE-related options are provided. On other targets, it only enables the FDPIC-specific code generation features, so you'll need to explicitly provide the PIC/PIE-related options as needed. 🦋
Static linking isn't supported, because it would still involve the dynamic linker when the program self-relocates. If that behavior is acceptable to you, use -static and -Wl,-dynamic-linker options. 🙈
The opposite option, -mno-fdpic, is useful (and required) for building the Linux kernel with the same (arm-*-uclinuxfdpiceabi) toolchain you used to build userland programs. 🐧
-mbranch-protection=features Enables branch protection features (armv8.1-m.main only). ✨
features can be one of the following forms:
none generates code without branch protection or return address signing. 🚫
standard generates code with all branch protection features enabled at their standard level. 💯
pac-ret generates code with return address signing set to its standard level, which means signing all functions that save the return address to memory. 🔏
pac-ret+leaf extends pac-ret signing to include leaf functions, even if they don't write the return address to memory. 🍃
bti adds landing-pad instructions at the permitted targets of indirect branch instructions. 🛬
If support for the +pacbti architecture extension isn't enabled (for example, via -march=), 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 runtime 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. 🌈
-mvectorize-with-neon-quad -mvectorize-with-neon-double Controls whether vectorization uses NEON quad-word or double-word registers. The default is -mvectorize-with-neon-quad. 🍓
AVR Options
These options are defined for AVR implementations: 🦖
-mmcu=mcu Specifies the AVR instruction set architecture (ISA) or device type. The default for this option is avr2. 🎯
Here's the lineup of AVR devices and ISAs that are supported. Heads up, bestie: a complete device support setup needs startup code crtmcu.o, a device header avr/io*.h, a device library libmcu.a, and a device-specs file specs-mcu (see <https://gcc.gnu.org/wiki/avr-gcc#spec-files>). Only the specs file is provided by the compiler, according to the supported mcus below. The rest comes from AVR-LibC (<https://github.com/avrdudes/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 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 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, the glow-up crew ✨. mcu values:atmega128,atmega128a,atmega128rfa1,atmega128rfr2,atmega1280,atmega1281,atmega1284,atmega1284p,atmega1284rfr2,at90can128,at90usb1286,at90usb1287.avr6— 🦋 "Enhanced" devices with a 3-byte PC, so anything with more than 128 KiB of program memory. mcu values:atmega256rfr2,atmega2560,atmega2561,atmega2564rfr2.avrxmega2— 🌸 "XMEGA" devices with more than 8 KiB and up to 64 KiB of program memory. mcu values:atxmega8e5,atxmega16a4,atxmega16a4u,atxmega16c4,atxmega16d4,atxmega16e5,atxmega32a4,atxmega32a4u,atxmega32c3,atxmega32c4,atxmega32d3,atxmega32d4,atxmega32e5,avr64da28,avr64da28s,avr64da32,avr64da32s,avr64da48,avr64da48s,avr64da64,avr64da64s,avr64db28,avr64db32,avr64db48,avr64db64,avr64dd14,avr64dd20,avr64dd28,avr64dd32,avr64du28,avr64du32,avr64ea28,avr64ea32,avr64ea48,avr64sd28,avr64sd32,avr64sd48.avrxmega3— 🧚 "XMEGA" devices with up to 64 KiB of combined program memory and RAM, where the program memory is visible in the RAM address space. Major main-character energy 👑. mcu values: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,avr16du14,avr16du20,avr16du28,avr16du32,avr16ea28,avr16ea32,avr16ea48,avr16eb14,avr16eb20,avr16eb28,avr16eb32,avr16la14,avr16la20,avr16la28,avr16la32,avr32da28,avr32da28s,avr32da32,avr32da32s,avr32da48,avr32da48s,avr32db28,avr32db32,avr32db48,avr32dd14,avr32dd20,avr32dd28,avr32dd32,avr32du14,avr32du20,avr32du28,avr32du32,avr32ea28,avr32ea32,avr32ea48,avr32eb14,avr32eb20,avr32eb28,avr32eb32,avr32la14,avr32la20,avr32la28,avr32la32,avr32sd20,avr32sd28,avr32sd32.avrxmega4— 🍓 "XMEGA" devices with more than 64 KiB and up to 128 KiB of program memory. mcu values:atxmega64a3,atxmega64a3u,atxmega64a4u,atxmega64b1,atxmega64b3,atxmega64c3,atxmega64d3,atxmega64d4,avr128da28,avr128da28s,avr128da32,avr128da32s,avr128da48,avr128da48s,avr128da64,avr128da64s,avr128db28,avr128db32,avr128db48,avr128db64.avrxmega5— 🔥 "XMEGA" devices with more than 64 KiB and up to 128 KiB of program memory, plus more than 64 KiB of RAM. mcu values:atxmega64a1,atxmega64a1u.avrxmega6— 💅 "XMEGA" devices with more than 128 KiB of program memory. mcu values: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 values: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 values:attiny4,attiny5,attiny9,attiny10,attiny102,attiny104,attiny20,attiny40.avr1— 🙈 This ISA is implemented by the minimal AVR core and is only supported for the assembler, so no compiling for it. mcu values:attiny11,attiny12,attiny15,attiny28,at90s1200.-mabsdata— 🫶 Assume that all data in static storage can be reached with LDS / STS instructions. This only does anything on reduced Tiny devices like ATtiny40.- See also the "absdata" AVR Attributes,variable attribute.
-mcvt— 🌈 Use a compact vector table. Some devices support a CVT with only four entries:0=Reset,1=NMI,2=Prio1 IRQ,3=Prio0 IRQs. This option links the startup code fromcrtmcu-cvt.oinstead of the usualcrtmcu.o. Besides giving you the compact table, the startup code sets the bitCPUINT_CTRLA.CPUINT_CVT, which turns on the CVT on the device.- When you don't want the startup code to set
CPUINT_CTRLA.CPUINT_CVT, you can satisfy the symbol__init_cvtso that the code isn't pulled in fromlibmcu.aanymore. For example, you can link with-Wl,--defsym,__init_cvt=0. - The CVT startup code is available since AVR-LibC v2.3 (
https://github.com/avrdudes/avr-libc/issues/1010).
- When you don't want the startup code to set
-mdouble=bits,-mlong-double=bits— 🧁 Set the size (in bits) of thedoubleorlong doubletype, respectively. The only possible values for bits are 32 and 64. Whether a given 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) may use the__gcc_isrpseudo instruction, which is supported by GNU Binutils. If this option is on, you can still turn the feature off for individual ISRs with the AVR Attributes,,"no_gccisr" function attribute. This feature is turned on by default if optimization is on (but not with-Og, @pxref{Optimize Options}), and if GNU Binutils supports PR21683 (https://sourceware.org/PR21683).-mint8— 🍭 Assumeintis an 8-bit integer. This changes the sizes of all the 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 give you smaller code size, though.
-mmain-is-OS_task— 🦋 Don't save registers inmain. The effect is the same as attaching the AVR Attributes,,"OS_task" attribute tomain. It's turned on by default if optimization is on.-mno-call-main— 🌸 Don't runmainby means of:
XCALL main
XJMP exit- Instead, put
mainin the section.init9(https://avrdudes.github.io/avr-libc/avr-libc-user-manual/mem_sections.html#sec_dot_init) so no call is needed. By setting this option, you're promising thatmainwill never return. - This option is for devices with very limited resources, where it saves a few bytes of code and stack space. It works as expected since AVR-LibC v2.3 (
https://github.com/avrdudes/avr-libc/issues/1012). With older versions, there's no performance gain.
-mno-interrupts— 🫧 The generated code is not compatible with hardware interrupts. The upside is that the code size is smaller.-mrelax— ✨ Try to swap aCALLorJMPinstruction for the shorterRCALLorRJMPinstruction when that's possible. Setting-mrelaxjust adds the--mlink-relaxoption to the assembler's command line and the--relaxoption to 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.
-mpmem-wrap-around— 🔁 Enable program counter wrap-around in linker relaxation.-mrodata-in-ram,-mno-rodata-in-ram— 🧠 Put the.rodatasections for read-only data in RAM or in program memory, respectively. For most devices there's no real choice, so this option acts more like an assertion.- Since v14, and for the AVR64* and AVR128* devices,
.rodatalives 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-ramcan bring back the old layout with.rodatain RAM.
- Since v14, and for the AVR64* and AVR128* devices,
-mtiny-stack— 🌷 Only change the lower 8 bits of the stack pointer.-mfract-convert-truncate— 💜 Allow truncation instead of rounding towards zero for fractional fixed-point types.-nodevicelib— 🙅♀️ Don't link against AVR-LibC's device specific librarylibmcu.a.- Heads up: since AVR-LibC v2.3, that library contains code that's essential for a program to work correctly. In particular, it has parts of the startup code, like
__init_sp(https://github.com/avrdudes/avr-libc/issues/1011) which sets the stack pointer to the symbol__stack,__init_cvt(https://github.com/avrdudes/avr-libc/issues/1010) which sets up the hardware for a compact vector table with-mcvt,__call_main(https://github.com/avrdudes/avr-libc/issues/1012) which callsmainandexit, and__do_flmap_init(https://github.com/avrdudes/avr-libc/issues/931) which sets up FLMAP according to the symbol__flmap.
- Heads up: since AVR-LibC v2.3, that library contains code that's essential for a program to work correctly. In particular, it has parts of the startup code, like
-nodevicespecs— 🎀 Don't add-specs=device-specs/specs-mcuto the compiler driver's command line. You're on the hook for giving the subprocesses (the compiler proper, the assembler, and the 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 the option-mmcu=mcu.- This option can also replace the older way of specifying custom device-specs files. That way needed
-B some-pathto 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.
- This option can also replace the older way of specifying custom device-specs files. That way needed
-Waddr-space-convert— Heads up, this one warns you whenever you convert between address spaces and the result doesn't fit inside the incoming address space. Those conversions can quietly go sideways 👀-Wmisspelled-isr— Warns if your ISR name is misspelled, meaning it's missing the__vectorprefix. It's on by default, so you get this one for free 💅
🌸 AVR Optimization Options 🌸
okay so these are the pure optimization options 💖 The ones from above, -mgas-isr-prologues, -mmain-is-OS_task, -mno-call-main, and -mrelax, are only almost optimization options. There are rare moments where their different code generation actually matters, so they're not 100% just speed boosts 🫶
-maccumulate-args— Collects outgoing function arguments and grabs or releases the stack space for them once, in the function prologue and epilogue. Without this, outgoing arguments get pushed before each call and popped afterwards. Also check out-fdefer-popover in the Optimize Options section ✨
Popping arguments after a call can be expensive on AVR, so accumulating the stack space can actually give you smaller executables. Arguments don't need to be removed from the stack after every call anymore 🧚
This one can shrink your code for functions that make several calls to functions that take their arguments on the stack, like printf-style functions 🖨️
-mbranch-cost=cost— Sets the branch costs for conditional branch instructions tocost. Reasonable values are small, non-negative integers. The default branch cost is0🌈-mcall-prologues— Function prologues and epilogues get expanded as calls to the right subroutines. The result is smaller code size 🦋-mfuse-add,-mno-fuse-add,-mfuse-add=level— Optimizes indirect memory accesses on reduced Tiny devices. By default it useslevel=1for-Ogand-O1, andlevel=2for higher optimization levels. Valid values forlevelare0,1, and2🍓-mfuse-move,-mno-fuse-move,-mfuse-move=level— Runs a post-reload optimization pass that tries to fuse move instructions and split multi-byte instructions into 8-bit operations. The default islevel=3for-O1, andlevel=23for higher optimizations. Valid values forlevelare in the range0 ... 23, which is a 3:2:2:2 mixed radix value. Each digit controls a different aspect of the optimization, so it's giving math nerd energy 🤓💜-mfuse-move2— Runs a post-combine optimization pass that tries to fuse move instructions 🔥-mstrict-X— Uses the address registerXthe way the hardware intends. That meansXis only used in indirect, post-increment, or pre-decrement addressing 👑
Without this option, X can be used just like Y or Z, but that gets emulated with extra instructions. For example, loading a value with X+const addressing (where const is a small non-negative value, 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-msplit-bit-shift— Splits multi-byte shifts with a constant offset into a byte-offset shift plus a residual shift with a non-byte offset. This is turned on by default for-O2and higher, including-Os, but not-Oz🙈 Splitting shifts whose constant offset is a multiple of 8 is controlled by-mfuse-move.-msplit-ldst— Splits multi-byte loads and stores into several byte loads and stores. Turned on by default for-O2and higher 🫧-muse-nonzero-bits— Enables optimizations that are only possible when some bits in a register are always zero. Turned on by default for-O2and higher 🧠
🧚 "EIND" and Devices With More Than 128 Ki Bytes of Flash 🧚
okay this section is a lot, but it's important bestie 😭
Pointers in the implementation are 16 bits wide. The address of a function or label is stored 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 program memory, there's a special function register called EIND. It serves as the most significant part of the target address when EICALL or EIJMP instructions are used ✨
Indirect jumps and calls on these devices are handled like this by the compiler, and they come with some limitations:
- The compiler never sets
EIND. - The compiler uses
EINDimplicitly inEICALL/EIJMPinstructions, or might readEINDdirectly to emulate an indirect call/jump using aRETinstruction. - The compiler assumes that
EINDnever changes during the startup code or during the application. In particular,EINDis not saved or restored in function or interrupt service routine prologues/epilogues. 🚫 - For indirect calls to functions and computed gotos, the linker generates stubs. Stubs are jump pads, sometimes also called trampolines. So the indirect call or jump actually jumps to a stub, and the stub contains a direct jump to the desired address 🦋
- Linker relaxation must be turned on so the linker generates the stubs correctly in all situations. See the compiler option
-mrelaxand the linker option--relax. 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 your code is supposed to work withEIND != 0, you need a custom linker script to place the sections whose names start with.trampolinesinto the segment thatEINDpoints to 🗺️ - The startup code from libgcc never sets
EIND. Heads up that startup code is a blend of code from libgcc and AVR-LibC. For how AVR-LibC affectsEIND, check the AVR-LibC user manual athttps://avrdudes.github.io/avr-libc/avr-libc-user-manual/📖 - It's legit for user-specific startup code to set up
EINDearly, for example through initialization code placed in section.init3. That code runs before 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 lives 🫶
Here's an example:
#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 get generated automatically by the linker when both of these conditions are met:
- The address of a label is taken by means of the
gsmodifier (short for generate stubs), like so:
- The address of a label is taken by means of the
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
gsmodifiers for code labels in these situations:- Taking the address of a function or code label.
- Computed goto.
- If a prologue-save function is used. See the
-mcall-prologuescommand-line option. - Switch/case dispatch tables. If you don't want these 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 this is not supported 🚨
int main (void)
{
/* Call function at word address 0x2 */
return ((int(*)(void)) 0x2)();
}Instead, you need to set up a stub, meaning 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();
}Then link the application 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 🎀
Some AVR devices support memories bigger than the 64 KiB range that 16-bit pointers can reach. To access memory locations outside that 64 KiB range, the content of a RAMP register gets used as the high part of the address. The X, Y, and Z address registers get concatenated with RAMPX, RAMPY, and RAMPZ special function registers, respectively, to form a wide address. Similarly, RAMPD is used together with direct addressing 🌈
- The startup code initializes the
RAMPspecial function registers with zero. - If a named address space other than generic or
__flashis used (see AVR Named Address Spaces), thenRAMPZis set as needed before the operation. - If the device supports RAM larger than 64 KiB and the compiler needs to change
RAMPZto accomplish an operation,RAMPZis reset to zero after the operation. - If the device comes with a specific
RAMPregister, the ISR prologue/epilogue saves and restores that SFR, and initializes 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. If you use inline assembler to read from locations outside the 16-bit address range and change one of the
RAMPregisters, you must reset it to zero after the access ⚠️
💖 AVR Built-in Macros 💖
GCC defines several built-in macros so user code can test for the presence or absence of features. Almost any of the following built-in macros are deduced from device capabilities and are therefore triggered by the -mmcu= command-line option 🧠
For even more AVR-specific built-in macros, see AVR Named Address Spaces and AVR Built-in Functions 🔍
__AVR_ARCH__— A built-in macro that resolves to a decimal number identifying the architecture. It depends on the-mmcu=mcuoption. Possible values are:
2, 25, 3, 31, 35, 4, 5, 51, 6
for mcu="avr2", "avr25", "avr3", "avr31", "avr35", "avr4", "avr5", "avr51", "avr6", respectively, and:
100, 102, 103, 104, 105, 106, 107
Those mcu values each get their own number, respectively 💅: "avrtiny", "avrxmega2", "avrxmega3", "avrxmega4", "avrxmega5", "avrxmega6", and "avrxmega7" 🌸. If mcu names an actual device, this built-in macro gets set to match. For example, with -mmcu=atmega8 the macro is defined to 4 ✨.
"__AVR_Device__"💖 Setting-mmcu=devicedefines this macro, and it reflects the device's name. So-mmcu=atmega8defines"__AVR_ATmega8__",-mmcu=attiny261adefines"__AVR_ATtiny261A__", and so on 🦋.- The names follow the scheme
"__AVR_Device__", where Device is the device name as it's written 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 is only a core architecture like
avr51and not a real device, this macro isn't defined 💀.
- The names follow the scheme
"__AVR_DEVICE_NAME__"🍓 Setting-mmcu=devicemakes this one hold the device's name. With-mmcu=atmega8it's defined to"atmega8".- Same deal here: if device is just a core architecture like
avr51, this macro isn't defined.
- Same deal here: if device is just a core architecture like
"__AVR_CVT__"🎀 You're compiling with-mcvtto use a compact vector table."__AVR_XMEGA__"👑 The device or architecture belongs to the XMEGA family."__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 for 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. The definition of 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 has an 8-bit stack pointer, respectively. The definition of these macros is affected by-mmcu=, and for-mmcu=avr2and-mmcu=avr25also 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."__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, etc., may use a different address than an instruction accessing RAM, likeLDorSTS. This offset depends on the device architecture and has to be subtracted from the RAM address to get the respective I/O address."__AVR_SHORT_CALLS__"🌈 The-mshort-callscommand-line option is set."__AVR_PM_BASE_ADDRESS__=addr"👑 Some devices support reading 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 and there's no need to put.rodatainto RAM. This is handled by the default linker description file, and it's currently available foravrtinyandavrxmega3. Even more convenient, there's no need for address spaces like__flashor features like theprogmemattribute andpgm_read_*."__AVR_HAVE_FLMAP__"💜 This macro is defined when the following conditions are met:- The device has the
NVMCTRL_CTRLB.FLMAPbitfield. This applies to theAVR64*andAVR128*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 to1when 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_SIGNAL_N__"⭐ The compiler supports thesignal(num)andinterrupt(num)AVR Attributes,,function attributes, with an argumentnumthat specifies the number of the interrupt service routine."__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-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 ✨
Okay bestie, these ones are used internally by the compiler, and they're how device specs files talk to the compiler proper 🧚. You don't need to set them by hand, and they are not optimization options 🙅. They're documented for completeness, and so you can get a better understanding of device specs (https://gcc.gnu.org/wiki/avr-gcc#spec-files) files.
Using these the wrong way may lead to sub-optimal or wrong code. Don't freestyle these 😭.
-mn-flash=num👑 Assume the flash memory has a size ofnumtimes 64 KiB. This determines which"__flashN"address spaces are available.-mflmap💜 The device has theFLMAPbit field, located in the special function registerNVMCTRL_CTRLB.-mrmw🔥 Assume the device supports the Read-Modify-Write instructionsXCH,LAC,LAS, andLAT.-mshort-calls🌸 AssumeRJMPandRCALLcan target the whole program memory. This option is used for multilib generation and selection for the devices from architectureavrxmega3.-mskip-bug🙈 Generate code without skips (CPSE,SBRS,SBRC,SBIS,SBIC) over 32-bit instructions.-msp8🫶 Treat the stack pointer register as an 8-bit register, i.e. assume the high byte of the stack pointer is zero. The compiler uses this option to select and build multilibs for architecturesavr2andavr25. 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 of these:bf512,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
The optional sirevision specifies the silicon revision of the target Blackfin processor. Any workarounds available for the targeted silicon revision are enabled. If sirevision is none, no workarounds are enabled. If sirevision is any, all workarounds for the targeted processor are enabled. The "__SILICON_REVISION__" macro is defined to two hexadecimal digits representing the major and minor numbers in the silicon revision. If sirevision is none, "__SILICON_REVISION__" is not defined. If sirevision is any, "__SILICON_REVISION__" is defined to be 0xffff. If this optional sirevision isn't used, GCC 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 provided by libgloss to be linked in if -msim is not given.
Without this option, bf532 is used as the processor by default.
Heads up: support forbf561is incomplete. Forbf561, only the preprocessor macro is defined.
-msim🌈 Specifies that the program will be run on the simulator. This causes the simulator BSP provided by libgloss to be linked in. This option has effect only for thebfin-elftoolchain. Certain other options, such as-mid-shared-libraryand-mfdpic, imply-msim.-momit-leaf-frame-pointer✨ Don't keep the frame pointer in a register for leaf functions. This avoids the instructions to save, set up, and restore frame pointers, and makes an extra register available in leaf functions.-mspecld-anomalyand-mno-specld-anomaly💖 When enabled, the compiler ensures the generated code does not contain speculative loads after jump instructions. If this option is used,"__WORKAROUND_SPECULATIVE_LOADS"is defined.-mcsync-anomaly,-mno-csync-anomaly— okay so when this is on, the compiler makes sure it never slipsCSYNCorSSYNCinstructions in too soon after conditional branches 🫶 Using it also defines__WORKAROUND_SPECULATIVE_SYNCS✨-mlow64k,-mno-low64k— when enabled, the compiler gets to assume your whole program fits in the low 64k of memory, so it can take shortcuts 🌸 The default is-mno-low64k, which treats the program as arbitrarily large, so no shortcuts for you, bestie 🙈-mstack-check-l1— does stack checking using info the uClinux kernel stashes in L1 scratchpad memory 🧚-mid-shared-library,-mno-id-shared-library— generates code that supports shared libraries through the library ID method. This is the vibe for execute in place and shared libraries in an environment with no virtual memory management 🦋 It implies-fPIC, and on abfin-elftarget it also implies-msim. The default is-mno-id-shared-library, which doesn't assume ID-based shared libraries are in use.-mleaf-id-shared-library,-mno-leaf-id-shared-library— same ID-based shared library energy, but this one assumes your library or executable won't link against any other ID shared libraries 💅 That lets the compiler use faster code for jumps and calls. The default is-mno-leaf-id-shared-library, where nobody makes that assumption, so the jump and call instructions come out slower 🐢-mshared-library-id=n— sets 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 they're no more space- or time-efficient than just leaving the option out.-msep-data,-mno-sep-data— lets the data segment live in a different area of memory from the text segment 💜 This helps with execute in place when there's no virtual memory management, since it gets rid of relocations against the text section. The default is-mno-sep-data, which assumes the data segment follows the text segment.-mlong-calls,-mno-long-calls— tells the compiler to do function calls the long way: load the function's address into a register first, then make a subroutine call on that register 🌈 You need this if the target function lives outside the 24-bit addressing range of the offset-based subroutine call instruction. It's not on by default, and-mno-long-callsputs you back to the default. Heads up, these switches don't change how calls through function pointers get generated 👀-mfast-fp— links 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— enables inlining of PLT entries in function calls to functions that aren't known to bind locally 🎀 It does nothing unless you also use-mfdpic.-mmulticore— builds a standalone application for multicore Blackfin processors 👑 It makes sure the right start files and link scripts for multicore get used, and defines the macro__BFIN_MULTICORE. This one only works with-mcpu=bf561[-sirevision]. You can pair it with-mcoreaor-mcorebfor the one-application-per-core setup. Without either of those, you get the single-application, dual-core model, where the main function of Core B has to be namedcoreb_main. If you skip this option entirely, you get the single-core application model.-mcorea— builds a standalone application for Core A of BF561 in the one-application-per-core setup 🫶 The proper start files and link scripts for Core A get used, and the macro__BFIN_COREAis defined. This only works together with-mmulticore.-mcoreb— builds a standalone application for Core B of BF561 in the one-application-per-core setup 💖 The right start files and link scripts for Core B get used, and__BFIN_COREBis defined. When you use this one,coreb_mainreplacesmain. It also only works together with-mmulticore.-msdram— builds a standalone application for SDRAM 🧠 Start files and link scripts get used to put your app into SDRAM, and the macro__BFIN_SDRAMis defined. Your loader has to initialize SDRAM before it loads the application.-micplb— assumes ICPLBs are enabled at run time 🔥 This changes how certain anomaly workarounds behave. For Linux targets, the default is to assume ICPLBs are enabled. For standalone applications, the default is off.
🦋 C6X Options 🦋
-march=name— sets the name of the target architecture 💅 GCC uses this to figure out which kinds of instructions it's allowed to emit when generating assembly code. The valid names arec62x,c64x,c64x+,c67x,c67x+, andc674x.-mbig-endian— generates code for a big-endian target 🌸-mlittle-endian— generates code for a little-endian target. This is the default ✨-msim— picks startup files and a linker script that work with the simulator 🧚-msdata=default— puts small global and static data into the.neardatasection, which gets pointed to by registerB14💜 Small uninitialized global and static data goes into.bss, which sits right next to.neardata. Small read-only data goes into.rodata. The sections for the big pieces of data are.fardata,.far, and.const.-msdata=all— puts all data into the small-data sections, not just the small stuff, and uses addressing relative to theB14register to get at it 🍓-msdata=none— no small-data sections at all. Everything gets accessed with absolute addresses 🙈 All initialized global and static data goes into.fardata, all uninitialized data goes into.far, and all constant data goes into.const.-mdsbt— compiles for the DSBT shared library ABI 🦋 You need this to compile with-fpicor-fPIC, and it implies-fpic.-mlong-calls— avoids PC-relative calls and uses indirection instead 🌈
🎀 CRIS Options 🎀
These options are defined specifically for the CRIS ports 💅
-march=architecture-type,-mcpu=architecture-type— generates code for the architecture you pick ⭐ The choices arev3,v8, andv10, which line up with ETRAX 4, ETRAX 100, and ETRAX 100 LX. The default isv0.-mtune=architecture-type— tunes everything that applies to the generated code for the architecture you name, except the ABI and the set of available instructions 🫶 The choices are the same as for-march=architecture-type.-mmax-stackframe=n— warns when a function's stack frame goes overnbytes ⚠️-metrax4,-metrax100— these are just synonyms for-march=v3and-march=v8, respectively 🧚-mmul-bug-workaround,-mno-mul-bug-workaround— works around a bug in themulsandmuluinstructions, on the CPU models where that bug shows up 🔥 It's disabled by default.-mpdebug— turns on CRIS-specific verbose debug info in the assembly code 🔍 This also turns off the#NO_APPformatted-code indicator that gets sent to the assembler at the top of the assembly file.-mcc-init— don't reuse condition-code results from the previous instruction 🙅♀️ Instead, always emit compare and test instructions before any condition codes get used.-mno-side-effects— doesn't emit instructions with side effects in addressing modes, except for post-increment 🌸-mstack-align,-mno-stack-align,-mdata-align,-mno-data-align,-mconst-align,-mno-const-align— these decide whether the stack frame, individual data, and constants get aligned to the biggest single data access size for your chosen CPU model 💖 The no- versions turn that alignment off. The default is 32-bit alignment. ABI details like structure layout stay the same no matter what you pick here.-m32-bit,-m16-bit,-m8-bit— kind of like the stack, data, and const alignment options above, but these make the stack frame, writable data, and constants 32-bit, 16-bit, or 8-bit aligned 🎀 The default is 32-bit alignment.-mno-prologue-epilogue,-mprologue-epilogue— with-mno-prologue-epilogue, the normal function prologue and epilogue that set up the stack frame get skipped, and no return instructions or return sequences get generated 💀
Use -mno-prologue-epilogue only alongside careful visual inspection of the compiled code, bestie. No warnings or errors show up when call-saved registers need to be saved, or when storage for local variables needs to be allocated. You're on your own for that one 😭
-mbest-lib-options,-moverride-best-lib-options—-mbest-lib-optionspicks the most feature-enabling options that the other options allow 🌈 It has no no- form, but-moverride-best-lib-optionsturns it off no matter where the two options sit on the command line.-mtrap-using-break8— emits traps asbreak 8🦋 This is the default for CRIS v3 and up. If you disable it, calls toabortget used instead.-mtrap-unaligned-atomic— emits checks that makebreak 8instructions run when atomic builtins get applied to misaligned memory 👀-munaligned-atomic-may-use-library— handles atomic builtins that might get applied to unaligned data by calling library functions instead 📚 This one overrides-mtrap-unaligned-atomic.-sim— links with the input-output functions from a simulator library 🧪 Code, initialized data, and zero-initialized data all get allocated one after another.-sim2— works like-sim, but the linker options place initialized data at0x40000000and zero-initialized data at0x80000000💫
🌈 C-SKY Options 🌈
GCC has a whole set of options just for C-SKY V2 chips 🧚 Let's go through them 💖
-march=arch— pick the C-SKY target architecture 🎀 Valid values for arch areck801,ck802,ck803,ck807, andck810. The default isck810.-mcpu=cpu— pick the exact C-SKY target processor 💅 Valid values for cpu are the whole squad:
ck801, 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, and
ck810ftv.-mbig-endian,-mlittle-endian— choose big-endian or little-endian code 🌸 The default is little-endian.-mfloat-abi=name— choose which floating-point ABI to use 🔥 Permissible values aresoft,softfp, andhard.soft: GCC generates output with library calls for floating-point operations.softfp: you get hardware floating-point instructions, but it still uses the soft-float calling conventions.hard: you get floating-point instructions and FPU-specific calling conventions.
The default depends on the specific target configuration.
⚠️ The hard-float and soft-float ABIs are NOT link-compatible. Compile your entire program with the same ABI and link with a compatible set of libraries, or it's giving chaos 💀
-mdouble-float,-mno-double-float— when-mhard-floatis in effect, turn on generation of double-precision float instructions 🦋 This is the default except when compiling forCK803.-mfdivdu,-mno-fdivdu— when-mhard-floatis in effect, turn on generation of"frecipd","fsqrtd", and"fdivd"instructions ✨ This is the default except when compiling forCK803.-mfpu=fpu— select the floating-point processor 💜 This option can only be used with-mhard-float. Values for fpu arefpv2_sf(equivalent to-mno-double-float -mno-fdivdu),fpv2(-mdouble-float -mno-divdu), andfpv2_divd(-mdouble-float -mdivdu).-melrw,-mno-elrw— enable the extended"lrw"instruction 🧚 This option defaults to on forCK801and off otherwise.-mistack,-mno-istack— enable interrupt stack instructions. The default is off. 🌈 The-mistackoption is required to handle the"interrupt"and"isr"function attributes.-mmp,-mno-mp— enable multiprocessor instructions. The default is off 🍓-mcp,-mno-cp— enable coprocessor instructions. The default is off 🫶-mcache,-mno-cache— enable coprocessor instructions. The default is off 🌸-msecurity,-mno-security— enable C-SKY security instructions. The default is off 🔒-mtrust,-mno-trust— enable C-SKY trust instructions. The default is off 🦋-mdsp,-mno-dsp,-medsp,-mno-edsp,-mvdsp,-mno-vdsp— enable C-SKY DSP, Enhanced DSP, or Vector DSP instructions, respectively 💅 All of these options default to off.-mdiv,-mno-div— generate divide instructions. Default is off ✨-msmart,-mno-smart— generate code for Smart Mode, using only registers numbered0-7so you can use 16-bit instructions 🎀 This option is ignored forCK801, where this is already the required behavior, and it defaults to on forCK802. For other targets, the default is off.-mhigh-registers,-mno-high-registers— generate code using the high registers numbered16-31👑 This option is not supported onCK801,CK802, orCK803, and it's enabled by default for other processors.-manchor,-mno-anchor— generate code using global anchor symbol addresses 🌈-mpushpop,-mno-pushpop— generate code using"push"and"pop"instructions 💖 This option defaults to on.-mmultiple-stld,-mno-multiple-stld— generate code using"stm"and"ldm"instructions 🧚 This option isn't supported onCK801, but it's enabled by default on other processors.-mconstpool,-mno-constpool— create 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 onCK801andCK802. On other processors it's optional.-mstack-size,-mno-stack-size— emit".stack_size"directives for each function in the assembly output 🦋 This option defaults to off.-mccrt,-mno-ccrt— generate code for the C-SKY compiler runtime instead oflibgcc💜 This option defaults to off.-mbranch-cost=n— set the branch costs to roughly"n"instructions 🍓 The default is1.-msched-prolog,-mno-sched-prolog— permit scheduling of function prologue and epilogue sequences 💀 Using this option can result in code that is not compliant with the C-SKY V2 ABI prologue requirements, and that cannot be debugged or backtraced. It is disabled by default.
🚨 Heads up, bestie: -msched-prolog can make code that isn't compliant with the C-SKY V2 ABI prologue requirements. That code also can't be debugged or backtraced. It's disabled by default for a reason.
-msim,-mno-sim— links the librarylibsemi.a, which is compatible with the simulator 🖥️ Applicable to ELF compiler only.
✨ Cygwin and MinGW Options ✨
These additional options are available for Microsoft Windows targets 🌸
-mconsole— generate a console application by telling the linker to set the PE header subsystem type needed for console apps 🎀 This option is available for Cygwin and MinGW targets and is enabled by default on those targets.-mcrtdll=library— preprocess, compile, or link with the specified C RunTime DLL library 🧚 This option adjusts the predefined macros"__CRTDLL__","__MSVCRT__","_UCRT", and"__MSVCRT_VERSION__"for the specified CRT library. It also picks the start file for the CRT library and links with the CRT library. Recognized CRT library names for the preprocessor are"crtdll*","msvcrt10*","msvcrt20*","msvcrt40*","msvcr40*","msvcrtd*","msvcrt-os*","msvcr70*","msvcr71*","msvcr80*","msvcr90*","msvcr100*","msvcr110*","msvcr120*"and"ucrt*". If this option isn't specified, the default MinGW import library"msvcrt"is used for linking, and no other preprocessor adjustment is done. The MinGW import library"msvcrt"is just a symlink to (or a copy of) another MinGW CRT import library, chosen during MinGW compilation. The MinGW import library"msvcrt-os"is for the Windows system CRT DLL"msvcrt.dll", and in most cases it's the default MinGW import library. Generally speaking, changing the CRT DLL requires recompiling the entire MinGW CRT. This option is for experimental and testing purposes only 🧪 It's available for MinGW targets.-mdll— available for Cygwin and MinGW targets 🌈 It generates a DLL (a dynamic link library), letting you select the required runtime startup object and entry point.-mnop-fun-dllimport— available for Cygwin and MinGW targets 💅 It makes GCC ignore the"dllimport"attribute.-mthreads— supports thread-safe exception handling on MinGW 🔥 Programs that rely on thread-safe exception handling must compile and link all code with the-mthreadsoption. When compiling,-mthreadsdefines-D_MT. When linking, it links in a special thread helper library,-lmingwthrd, which cleans up per-thread exception-handling data.-municode— available for MinGW-w64 targets 🌸 It predefines the"UNICODE"preprocessor macro and chooses Unicode-capable runtime startup code.-mwin32— available for Cygwin and MinGW targets 🦋 It sets the typical Microsoft Windows predefined macros in the preprocessor, but it doesn't influence the choice of runtime library or startup code.-mwindows— available for Cygwin and MinGW targets 🎀 It generates a GUI application by telling the linker to set the PE header subsystem type appropriately.-fno-set-stack-executable— available for MinGW targets 🫶 It means the executable flag for the stack used by nested functions isn't set. This is necessary for binaries running in kernel mode of Microsoft Windows, since the User32 API (the one used to set executable privileges) isn't available there.-fwritable-relocated-rdata— available for MinGW and Cygwin targets 🧚 It puts relocated data in a read-only section into the".data"section. This is necessary for older runtimes that don't support modifying".rdata"sections for pseudo-relocation.-mpe-aligned-commons— available for Cygwin and MinGW targets 💜 It means the GNU extension to the PE file format, which permits correct alignment of COMMON variables, should be used when generating code. It's enabled by default if GCC detects that the target assembler found during configuration supports the feature.-muse-libstdc-wrappers— uses Cygwin DLL wrappers to support the C++ operators"new"and"delete"🌈
See also under x86 Options for standard options.
🌈 Darwin Options 🌈
These options are defined for all architectures running the Darwin operating system 🍎
FSF GCC on Darwin does not create "fat" object files. It creates an object file for the single architecture that GCC was built to target. Apple's GCC on Darwin does create "fat" files if multiple -arch options are used. It does this by running the compiler or linker multiple times and joining the results together with lipo 💖
The subtype of the file created (like ppc7400 or ppc970 or i686) is determined by the flags that specify the ISA that GCC is targeting, like -mcpu or -march. You can use -force_cpusubtype_ALL to override this ✨
okay so the Darwin tools are not chill about ISA mismatches 💀 the assembler, as, only lets you use instructions that are valid for the subtype of the file it's generating, so you literally cannot put 64-bit instructions in a ppc750 object file 🙅♀️ the shared library linker, /usr/bin/libtool, will fail and print an error if you ask it to make a shared library with a less restrictive subtype than its input files (like shoving a ppc970 object file into a ppc7400 library, no thank you 😭). the executable linker, ld, is the chill one 🫶 it quietly gives the executable the most restrictive subtype of any of its inputs.
✨ OPTIONS ✨
-Fdir— okay this one's a whole vibe 🌸 it adds the framework directorydirto the front of the list of places searched for header files. these directories get mixed in with the ones from-Ioptions and they're scanned left-to-right, in order 🧚
A framework directory is just a folder full of frameworks 📁 and a framework is a directory that ends in .framework and has a Headers and/or PrivateHeaders directory sitting right inside it. the framework's name is the folder name without the .framework part. its headers live in one of those two folders, and Headers gets searched first 💖
A subframework is a framework directory that lives inside a framework's Frameworks directory 🦋 you can only #include subframework headers from inside a header of the framework that contains it, or from a sibling subframework header. two subframeworks are siblings if they're in the same framework. a subframework should not share a name with a framework, and if it does, GCC will warn you 🚨 right now a subframework can't have subframeworks of its own, but that might get added later 👀
the standard frameworks live in /System/Library/Frameworks and /Library/Frameworks. an example include looks like #include <Framework/header.h>, where Framework is the framework's name and header.h is found in its PrivateHeaders or Headers directory 🎀
-iframeworkdir— like-F, except the directory gets treated as a system directory 🫧 the big difference is that with-iframework, the compiler won't warn you about stuff inside header files it finds throughdir. this option only works for the C family of languages 💅-arch name— generates output for architecturename🌈 as we talked about earlier, GCC makes output for the architecture it was configured for, and you use its usual options to pick subarchitecture variants.-archis only here for compatibility, but ifnamedoesn't match GCC's own idea of the target architecture, you'll get an error 🙅♀️-dependency-file filename— this is just an alias for the preprocessor option-MF filename🧚-fapple-kext— generates code for Darwin loadable kernel extensions 🔥-gused— emits debugging info for symbols that are used ✨ for the stabs debugging format, this also turns on-feliminate-unused-debug-symbols. it's ON by default, so you're already getting it 🍓-gfull— emits debugging info for all symbols and types 💜 the whole buffet 🍽️-matt-stubs,-mno-att-stubs— turns on (or off) AT&T-style PIC stubs 🦋 this is the default when the target architecture supports it, which right now means x86 only 💀-mconstant-cfstrings,-fconstant-cfstrings— when the NeXT runtime is in use (which is the default on these systems), this overrides any-fconstant-string-classsetting and makes@"..."literals get laid out as constant CoreFoundation strings 🌸-fconstant-cfstringsis just an alias for-mconstant-cfstrings, so they're twins 👯♀️-mdynamic-no-pic— generates code for executables, not shared libraries 🎀 heads up, this one is incompatible with-fpic,-fPIC,-fpie, and-fPIE, so don't mix them 🙅♀️-mfix-and-continue,-ffix-and-continue,-findirect-data— generates code built for fast turnaround development ⚡ the example given is letting GDB dynamically load.ofiles into programs that are already running, which is giving main character debugging energy 😭-findirect-dataand-ffix-and-continueare only around for backwards compatibility 🫶-mkernel— turns on kernel development mode 🧠 this one sets-static,-fno-common,-fno-use-cxa-atexit,-fno-exceptions,-fno-non-call-exceptions,-fapple-kext,-fno-weak, and-fno-rtti, where applicable 💅 for PowerPC targets it also sets-mno-altivec,-msoft-float,-fno-builtin, and-mlong-branch👑-mmacosx-version-min=version,-asm_macosx_version_min=version—-mmacosx-version-minsets the earliest MacOS X version this executable will run on, which isversion✨ typical values include12,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 work with as many systems and codebases as possible 🫧
-asm_macosx_version_min=version is similar, but the GCC driver only passes its version info to the assembler 🧚
-mone-byte-bool— overrides the defaults forboolso thatsizeof(bool)==1🍓 by default,sizeof(bool)is 4 on Darwin/PowerPC and 1 on Darwin/x86, so this option does nothing on x86 🙈
Warning: -mone-byte-bool makes GCC generate code that is NOT binary compatible with code made without that switch 😭 using it might mean recompiling every other module in your program, including system libraries. only use it to conform to a non-default data model.
-msymbol-stubs,-mno-symbol-stubs— forces generation of external symbol indirection stubs for PIC references 🦋 by default this gets turned on automatically if the target linker version (-mtarget-linker) is old enough to need them 💜-mtarget-linker=version,-mtarget-linker version— specifies the target ld64 version and overrides whatever version is in the GCC configuration 🔥 newer linker versions support improved code generation in some cases, like for PIC code 🌈-ObjC— equivalent to-x objective-c, which says the input is Objective-C source code 🎀-ObjC++— equivalent to-x objective-c++, which says the input is Objective-C++ source code 💖-Wnonportable-cfstrings,-Wno-nonportable-cfstrings— warns if constant CoreFoundation string objects contain non-portable characters ⚠️ this warning is enabled by default 🫶-all_load— loads all members of static archive libraries 📦 seeman ld(1)for more 🧚-arch_errors_fatal— makes errors about files with the wrong architecture fatal 💀-bind_at_load— marks the output file so the dynamic linker binds all undefined references when the file is loaded or launched 🌸-bundle— produces a Mach-o bundle format file 🫧 seeman ld(1)for more information 🙌-bundle_loader executable— specifies the executable that will load the build output file being linked 🎀 seeman ld(1)for more information 📖-dynamiclib— when you pass this, GCC produces a dynamic library instead of an executable when linking, using the Darwinlibtoolcommand 🦋-force_cpusubtype_ALL— makes GCC's output file have theALLsubtype, instead of one controlled by the-mcpuor-marchoption 👑-nodefaultrpaths— doesn't add default run paths for the compiler library directories to executables, modules, or dynamic libraries 🧠 on macOS 10.5 and later, the embedded runpath gets added by default unless you put-nodefaultrpathson the link line. run paths are needed (and therefore enforced) to build on macOS 10.11 or later 💅-nodefaultexport— doesn't add default symbol exports to modules or dynamic libraries 🌈
These next ones are the linker options that get passed straight through to the Darwin linker, which explains them in full in its own man page 📖 no cap, it's a lot to cover here 😭
-allowable_client client_name— passed to the Darwin linker 🧚-client_name— passed to the Darwin linker 🧚-compatibility_version— passed to the Darwin linker 🧚-current_version— passed to the Darwin linker 🧚-dead_strip— passed to the Darwin linker 🧚-dylib_file— passed to the Darwin linker 🧚-dylinker— passed to the Darwin linker 🧚-dylinker_install_name— passed to the Darwin linker 🧚-dynamic— passed to the Darwin linker 🧚-exported_symbols_list— passed to the Darwin linker 🧚-filelist— passed to the Darwin linker 🧚-flat_namespace— passed to the Darwin linker 🧚-force_flat_namespace— passed to the Darwin linker 🧚-framework— passed to the Darwin linker 🧚-headerpad_max_install_names— passed to the Darwin linker 🧚-image_base— passed to the Darwin linker 🧚-init symbol-name— passed to the Darwin linker 🧚-install_name— passed to the Darwin linker 🧚-keep_private_externs— passed to the Darwin linker 🧚-pagezero_size— passed to the Darwin linker 🧚-preload— passed to the Darwin linker 🧚-read_only_relocs— passed to the Darwin linker 🧚-sectalign— passed to the Darwin linker 🧚-sectcreate— passed to the Darwin linker 🧚-seg_addr_table— passed to the Darwin linker 🧚-seg1addr— passed to the Darwin linker 🧚-segaddr— passed to the Darwin linker 🧚-segprot— passed to the Darwin linker 🧚-segs_read_only_addr— passed to the Darwin linker 🧚-segs_read_write_addr— passed to the Darwin linker 🧚-sub_library— passed to the Darwin linker 🧚-sub_umbrella— passed to the Darwin linker 🧚-twolevel_namespace— passed to the Darwin linker 🧚-twolevel_namespace_hints— passed to the Darwin linker 🧚-umbrella— passed to the Darwin linker 🧚-undefined— passed to the Darwin linker 🧚-unexported_symbols_list— passed to the Darwin linker 🧚-weak_framework— passed to the Darwin linker 🧚-weak_reference_mismatches— passed to the Darwin linker 🧚-whatsloaded— passed to the Darwin linker 🧚-whyload— passed to the Darwin linker 🧚
🦋 DEC Alpha Options 🦋
okay these are the -m options defined for the DEC Alpha implementations 💜
-mno-soft-float,-msoft-float— tells GCC to use (or not use) the hardware floating-point instructions for floating-point operations 🔥 with-msoft-float, functions inlibgcc.aget used to do the floating-point ops instead. unless those get replaced by routines that emulate the FP operations, or get compiled to call such emulation routines, those routines will issue floating-point operations 😭 if you're compiling for an Alpha without floating-point operations, you have to 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-regs,-mno-fp-regs— generates code that uses (or does not use) the floating-point register set 💅-mno-fp-regsimplies-msoft-float🫶 if the FP 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 that gets 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 👑
Okay bestie, the Alpha chip's floating-point hardware is built for maximum speed 🏎️💨 It's mostly IEEE compliant, but full compliance needs a little software help 🫶
-mieee— This is the fully IEEE-compliant mode, except the inexact-flag isn't kept track of (more on that below) 💖 When it's on, the macro_IEEE_FPgets defined during compilation ✨ The code runs slower, but it can handle denormalized numbers and the special IEEE values like not-a-number and plus/minus infinity 🦋 Other Alpha compilers call this-ieee_with_no_inexact💅
DEBIAN SPECIFIC: this one 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 can produce denormalized numbers, NaNs, and infs, and without -mieee those will make a program SIGFPE the second it tries to use the results 💀
-mieee-with-inexact— This is like-mieee, but the generated code also keeps the IEEE inexact-flag 🫧 Turn it on and you get fully-compliant IEEE math. Along with_IEEE_FP, the macro_IEEE_FP_EXACTgets defined too ✨ On some Alpha chips the code can run significantly slower than the default, and since hardly any code depends on the inexact-flag, you should normally skip this one 🙅♀️ Other Alpha compilers call it-ieee_with_inexact💜-mfp-trap-mode=trap-mode— This controls which floating-point-related traps are enabled 🪤 Other Alpha compilers call it-fptm trap-mode💅 The trap mode can be one of four values:n— The default (normal) setting. The only traps enabled are the ones that can't be turned off in software, like the division by zero trap 🍓u— Everythingngives you, plus underflow traps 🌸su— Likeu, but the instructions are marked as safe for software completion (check the Alpha architecture manual for the deets) 🧚sui— Likesu, plus inexact traps 👑
-mfp-rounding-mode=rounding-mode— Picks the IEEE rounding mode 🎀 Other Alpha compilers call it-fprm rounding-mode💖 The rounding-mode can be one of these:n— Normal IEEE rounding. Numbers get rounded towards the nearest machine number, or towards the even machine number if it's a tie ⚖️m— Round towards minus infinity ⬇️c— Chopped rounding. Numbers get rounded towards zero 🫧d— Dynamic rounding. A field in the floating-point control register (fpcr, see the Alpha architecture reference manual) decides which rounding mode is in effect 🎛️ The C library sets this register to round towards plus infinity, so unless your program changes the fpcr,dmeans round towards plus infinity ✨
-mtrap-precision=trap-precision— Okay so, Alpha floating-point traps are imprecise 😭 Without software help you can't recover from a floating trap, and the program usually has to be terminated. GCC can generate code that helps OS trap handlers figure out the exact spot that caused a floating-point trap 🔍 You can pick how precise you want it:p— Program precision. This is the default, and it means a trap handler can only tell which program caused a floating-point exception 📦f— Function precision. The trap handler can find the function that caused the exception 🧩i— Instruction precision. The trap handler can find the exact instruction that caused the exception 🎯
Other Alpha compilers have equivalent options called -scope_safe and -resumption_safe 💅
-mieee-conformant— Marks the generated code as IEEE conformant 📜 > Don't use this unless you also specify-mtrap-precision=iand either-mfp-trap-mode=suor-mfp-trap-mode=sui, or it's not gonna be it 🙅♀️ Its only effect is to emit the line.eflag 48in the function prologue of the generated assembly file 🧾-mbuild-constants— Normally, GCC looks at a 32- or 64-bit integer constant to see if it can put it together 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 with code, even if that takes more instructions (the max is six) 🔨 You typically use this when building 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— These decide whether GCC should generate code that uses the optional BWX, CIX, FIX and MAX instruction sets 🎛️ By default it uses whichever instruction sets the CPU type from-mcpu=supports, or the ones supported by the CPU GCC was built on if you didn't specify one 🫶-msafe-bwa,-mno-safe-bwa— These decide whether, without the optional BWX instruction set, GCC should generate multi-thread and async-signal safe code for byte and aligned word memory accesses 🧵-msafe-partial,-mno-safe-partial— These decide whether GCC should generate multi-thread and async-signal safe code for partial memory accesses 🧩 That includes piecemeal accesses to unaligned data, plus block accesses to the leading and trailing parts of aggregate types or other objects in memory that don't start and end on an aligned 64-bit data boundary 📐-mfloat-vax,-mfloat-ieee—-mfloat-vaxgenerates code that uses VAX F and G floating-point arithmetic, and-mfloat-ieeegenerates code that does not use it, so you get IEEE single and double precision instead 🦕-mexplicit-relocs,-mno-explicit-relocs— Older Alpha assemblers had no way to generate symbol relocations except through assembler macros, and those macros don't allow optimal instruction scheduling 😩 GNU Binutils as of version 2.12 supports a new syntax that lets the compiler explicitly mark which relocations apply to which instructions 🙌 This option is mostly useful for debugging, since GCC detects the assembler's capabilities when it's built and sets the default accordingly 🔧-msmall-data,-mlarge-data— When-mexplicit-relocsis in effect, static data is accessed through gp-relative relocations 🗂️ With-msmall-data, objects 8 bytes long or smaller get placed in a small data area (the.sdataand.sbsssections) and get accessed through 16-bit relocations off of the$gpregister ✨ This caps the small data area at 64KB, but the variables can be accessed with a single instruction, which is iconic 💅
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 must use malloc or mmap to allocate the data in the heap instead of in the program's data segment 🧠
When generating code for shared libraries, -fpic implies -msmall-data, and -fPIC implies -mlarge-data 🫧
-msmall-text,-mlarge-text— With-msmall-text, the compiler assumes the code of the entire program (or shared library) fits in 4MB, so it's reachable with a branch instruction 🦋 When-msmall-datais also used, the compiler can assume all local symbols share the same$gpvalue, which cuts the instructions for a function call from 4 down to 1 🏃♀️ The default is-mlarge-text🌸-mcpu=cpu_type— Sets the instruction set and instruction scheduling parameters for the machine type cpu_type 💻 You can use either the EV style name or the matching chip number. GCC supports scheduling parameters for the EV4, EV5 and EV6 families, and it picks the default instruction set values from the processor you specify 🎯 If you don't specify a processor type, GCC defaults to the processor the compiler was built on 🏗️
Supported values for cpu_type are:
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 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 🤷♀️
-mtune=cpu_type— Sets only the instruction scheduling parameters for the machine type cpu_type 🎶 The instruction set stays the same. Native toolchains also supportnative, which picks the best architecture option for the host processor 🖥️-mtune=nativehas no effect if GCC doesn't recognize the processor 🫠-mmemory-latency=time— Sets the latency the scheduler should assume for typical memory references as the application sees them ⏱️ This number depends a lot on the application's memory access patterns and the size of the external cache on the machine 🧃 Valid options for time are:number— A decimal number representing 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), as well as main memory 🧠 Heads up,L3is only valid for EV5 ⚠️
-mtls-kernel— Emitsrdvalinstead ofrduniqfor the thread pointer 🧵✨
🦋 eBPF Options 🦋
-mtls-size=bitsize— okay so this one sets the bit size of immediate TLS offsets 🎀 The valid values are16,32, and64, and it defaults to32✨-mlong-double-128,-mlong-double-64— these decide how big the "long double" type is 📏 ngl-mlong-double-128is incompatible with VAX floating point, so don't mix them 💀
🧚 eBPF Options 🧚
-mframe-limit=bytes— this is the hard limit for frame sizes, in bytes 📦 The value has to be less than or equal to32767. If you don't pick one, it defaults to whatever limit the version of the Linux kernel you're targeting imposes 🌸-mbig-endian— generates code for a big-endian target 🍓-mlittle-endian— generates code for a little-endian target. This is the default, so you're already slaying 👑-mjmpext,-mno-jmpext— turn the extra conditional-branch instructions on or off 🦋 They're enabled for CPU v2 and above.-mjmp32,-mno-jmp32— turn 32-bit jump instructions on or off 💜 Enabled for CPU v3 and above.-malu32,-mno-alu32— turn 32-bit ALU instructions on or off ✨ Enabled for CPU v3 and above.-mv3-atomics,-mno-v3-atomics— turn on or off the instructions for general atomic operations that came in with CPU v3 ⚡ Enabled for CPU v3 and above.-mbswap,-mno-bswap— turn byte swap instructions on or off 🔄 Enabled for CPU v4 and above.-msdiv,-mno-sdiv— turn signed division and modulus instructions on or off ➗ Enabled for CPU v4 and above.-msmov,-mno-smov— turn 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, so check first 🙈 The default isv4.
Here are the supported values for version:
v1— the first stable eBPF ISA, with no special features or extensions 🍼v2— supports the jump extensions, as in-mjmpext🦋v3— all the v2 features, plus:- 32-bit jump operations, as in
-mjmp32 - 32-bit ALU operations, as in
-malu32 - general atomic operations, as in
-mv3-atomics
- 32-bit jump operations, as in
v4— all the v3 features, 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
- byte swap instructions, as in
-mco-re,-mno-co-re— enable or disable BPF Compile Once - Run Everywhere (CO-RE) support 🌈 CO-RE support is enabled by default when you generate BTF debug information for the BPF target (-gbtf).-mxbpf— generates code for an expanded version of BPF that relaxes some of the usual BPF restrictions 🚀 One of the things it does is save and restore callee-saved registers at function entry and exit, respectively.-masm=dialect— outputs assembly using the eBPF dialect you pick 💅 The default ispseudoc.
Here are the supported values for dialect:
normal— outputs the normal assembly dialectpseudoc— outputs the pseudo-C assembly dialect
-minline-memops-threshold=bytes— sets a size threshold in bytes. At or below it,memmove,memcpy, andmemsetare always expanded inline 🧠 Anything bigger would need a library call instead, but BPF doesn't allow libcalls, so going over the threshold is a compile-time error 💀 The default is1024bytes.-Wco-re— turns on warnings for situations where-mco-reis enabled but it might not be possible to generate CO-RE compatible code 👀
🌸 FR30 Options 🌸
These options are defined specifically for the FR30 port 🎀
-msmall-model— uses the small address space model 🐣 This can make 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 🧃
💜 FRV Options 💜
-mgpr-32— only uses the first 32 general-purpose registers 🔢-mgpr-64— uses all 64 general-purpose registers 🚀-mfpr-32— uses only the first 32 floating-point registers 🔢-mfpr-64— uses all 64 floating-point registers 💪-mhard-float— uses hardware instructions for floating-point operations ⚡-msoft-float— uses library routines for floating-point operations instead 📚-malloc-cc— dynamically allocates condition code registers 🪄-mfixed-cc— doesn't try to dynamically allocate condition code registers, and only usesicc0andfcc0🔒-mdword,-mno-dword— control whether the ABI uses double-word instructions 🎀-mdouble,-mno-double— enable or disable use of floating-point double instructions 🦋-mmedia,-mno-media— enable or disable use of media instructions 🎶-mmuladd,-mno-muladd— enable or disable use of multiply and add/subtract instructions ✖️-mfdpic— selects the FDPIC ABI, which uses function descriptors to represent pointers to functions 🧭 Without any PIC/PIE-related options, it implies-fPIE. With-fpicor-fpie, it assumes GOT entries and small data are within a 12-bit range from the GOT base address. With-fPICor-fPIE, GOT offsets are computed with 32 bits 🔢 With abfin-elftarget, this option implies-msim.-minline-plt— enables inlining of PLT entries in function calls to functions that aren't known to bind locally 🧩 It has no effect without-mfdpic. It's enabled by default if you're optimizing for speed and compiling for shared libraries (i.e.,-fPICor-fpic), or when an optimization option such as-O3or above is in the command line ⚡-mTLS— assumes a large TLS segment when generating thread-local code 🧵-mtls— does not assume a large TLS segment when generating thread-local code 🧶-mgprel-ro— enables the use of"GPREL"relocations in the FDPIC ABI for data that's known to be in read-only sections 📖 It's enabled by default, except for-fpicor-fpie. Even though it may help make the global offset table smaller, it trades 1 instruction for 4 there 🤔 With-fPICor-fPIE, it trades 3 instructions for 4, one of which may be shared by multiple symbols, and it avoids the need for a GOT entry for the referenced symbol, so it's more likely to be a win ✨ If it isn't, you can use-mno-gprel-roto disable it.-multilib-library-pic— links with the (library, not FD) pic libraries 📦 It's implied by-mlibrary-pic, as well as by-fPICand-fpicwithout-mfdpic. You should never have to use it explicitly 🙅♀️-mlinked-fp— follows the EABI requirement of always creating a frame pointer whenever a stack frame is allocated 🖼️ This option is enabled by default and can be disabled with-mno-linked-fp.-mlong-calls— uses indirect addressing to call functions outside the current compilation unit 📞 This lets the functions be placed anywhere within the 32-bit address space 🌍-malign-labels— tries to align labels to an 8-byte boundary by inserting NOPs into the previous packet 🧱 This only does anything when VLIW packing is enabled. It doesn't create new packets; it just adds NOPs to existing ones 🫶-mlibrary-pic— generates position-independent EABI code 🧭-macc-4— uses only the first four media accumulator registers 4️⃣-macc-8— uses all eight media accumulator registers 8️⃣-mpack,-mno-pack— enable or disable packing VLIW instructions 📦-mno-eflags— does not mark ABI switches ine_flags🚫-mcond-move,-mno-cond-move— enable or disable the use of conditional-move instructions. It's enabled by default ↪️
This switch is mainly for debugging the compiler and will likely be removed in a future version. 🙈
-mscc,-mno-scc— enable or disable the use of conditional set instructions. It's enabled by default 🎯
This switch is mainly for debugging the compiler and will likely be removed in a future version. 🙈
-mcond-exec,-mno-cond-exec— enable or disable the use of conditional execution. It's enabled by default 🏃♀️
This switch is mainly for debugging the compiler and will likely be removed in a future version. 🙈
-mvliw-branch,-mno-vliw-branch— enable or disable an optimization pass that packs branches into VLIW instructions. It's enabled by default 📦
This switch is mainly for debugging the compiler and will likely be removed in a future version. 🙈
-mmulti-cond-exec,-mno-multi-cond-exec— enable or disable optimization of"&&"and"||"in conditional execution. It's enabled by default 🔀
This switch is mainly for debugging the compiler and will likely be removed in a future version. 🙈
-mnested-cond-exec,-mno-nested-cond-exec— enable or disable nested conditional execution optimizations. It's enabled by default 🪆
This switch is mainly for debugging the compiler and will likely be removed in a future version. 🙈
-moptimize-membar,-mno-optimize-membar— this switch removes redundantmembarinstructions from the compiler-generated code 🧹 It's enabled by default.-mtomcat-stats— makes gas print out tomcat statistics 📊-mcpu=cpu— selects the processor type to generate code for 🖥️ The possible values arefrv,fr550,tomcat,fr500,fr450,fr405,fr400,fr300, andsimple✨
🎀 FT32 Options 🎀
These options are defined specifically for the FT32 port 💖
-msim— specifies that the program will run on the simulator 🖥️ This causes an alternate runtime startup and library to be linked.
You must not use this option when generating programs that will run on real hardware 🚨 You must provide your own runtime library for whatever I/O functions are needed.
-mnodiv— does not usedivandmodinstructions ➗-mft32b— enables use of the extended instructions of the FT32B processor 🚀-mcompress— compresses all code using the FT32B code compression scheme 🗜️-mnopm— does not generate code that reads program memory 📵
🐧 GNU/Linux Options 🐧
These -m options are defined 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🎀 Okay bestie, this one switches GCC over to the uClibc C library. It's the default on*-*-linux-*uclibc*targets.-mmusl🌸 This one uses the musl C library instead. It's the default on*-*-linux-*musl*targets.-mbionic🤖 This one uses the Bionic C library. It's the default on*-*-linux-*android*targets.-mandroid,-mno-android📱 This makes your code Android-compatible 💅 It's the default on*-*-linux-*android*targets.- When compiling, it 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 defines the preprocessor macro"__ANDROID__". - You can turn all of this off with
-mno-android.
- When compiling, it turns on
-tno-android-cc🙅♀️ This turns off the compilation side of-mandroid. So-mbionic,-fPIC,-fno-exceptionsand-fno-rttiwon't get turned on by default.-tno-android-ld🐧 This turns off the linking side of-mandroid. The linker gets the standard Linux linking options instead.
✨ H8/300 Options ✨
Okay so these -m options are only for the H8/300 implementations 🧚
-mrelax🦋 Shortens some address references at link time, whenever that's possible. It does this by using 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. You have to use this with either-mhor-ms.-msx🔥 Generates H8SX code.-ms2600👑 Generates code for the H8S/2600. You must use this with-ms.-mquickcall🫶 Uses registers for passing arguments.-mslowbyte🐢 Treats access to byte-sized memory as slow.-mexr,-mno-exr💅 Stores extended registers on the stack before running functions with the"monitor"attribute. The default is-mexr. This one 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 those chips align longs and floats on 4-byte boundaries.-malign-300moves them to 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 architecture you specify. The choices are1.0for PA 1.0,1.1for PA 1.1 and2.0for PA 2.0 processors. To find 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.1and-march=2.0, respectively.-matomic-libcalls,-mno-atomic-libcalls⚛️ Generates libcalls for atomic loads and stores when sync libcalls are disabled. This one is enabled by default. It only affects how the HPPA backend generates atomic libcalls.- 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
DImodeare 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 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 atomicDImodeaccesses on 32-bit targets.
- 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
-mcaller-copies📦 The caller copies function arguments that get passed by hidden reference. Use this one 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. This lets GCC emit faster indirect calls.- Heads up: this doesn't work in the presence of shared libraries or nested functions ⚠️
-mfixed-range=register-range📌 Generates code that treats the given register range as fixed registers. A fixed register is one the register allocator can't use, which is handy when compiling kernel code. Write a register range as two registers separated by a dash. You can list multiple ranges separated by a comma.-mgas🧵 Enables assembler directives that only GAS understands.-mgnu-ld🐂 Uses options specific to GNU ld. This passes-sharedto ld when building a shared library. It's the default when GCC is configured, explicitly or implicitly, with the GNU linker.- This option doesn't change which ld gets called. It only changes the parameters passed to that ld. The ld that's called is decided by the
--with-ldconfigure option, then GCC's program search path, and finally the user'sPATH. - 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*.
- This option doesn't change which ld gets called. It only changes the parameters passed to that ld. The ld that's called is decided by the
-mhp-ld🏢 Uses options specific to HP ld. This 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.- Like
-mgnu-ld, this doesn't change which ld gets called. It only changes the parameters passed to it. The ld that's called is decided by the--with-ldconfigure option, GCC's program search path, and finally the user'sPATH. - 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*.
- Like
-mlinker-opt🔧 Enables the optimization pass in the HP-UX linker.- Heads up: this makes symbolic debugging impossible 💀
-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 (depending on the case) goes past a predefined limit. That limit is set by the branch type being used. The limits for normal calls are 7,600,000 and 240,000 bytes, for PA 2.0 and PA 1.X architectures respectively. Sibling calls are always limited to 240,000 bytes.
- Distances are measured from the beginning of functions when using the
-ffunction-sectionsoption. They're also measured that way when using the-mgasand-mno-portable-runtimeoptions together under HP-UX with the SOM linker. - It's usually not something you want, since it degrades performance 😬 But it may be useful in large applications, especially 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. Systems that support long absolute calls, and long PIC symbol-difference or PC-relative calls, should see a relatively small impact. An indirect call is used on 32-bit ELF systems in PIC code, though, and it's quite long 🫠
-mlong-load-store📦 Generates 3-instruction load and store sequences, which the HP-UX 10 linker sometimes requires. This is equivalent to the+koption to the HP compilers.-mno-space-regs🚀 Generates code that assumes the target has no space registers. This allows GCC to 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 aren't 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 typecpu-type. The choices are700 7100,7100LC,7200,7300and8000. To find the right scheduling option for your machine, check/usr/lib/sched.modelson an HP-UX system. The default scheduling is8000.-msio,-mwsio🖨️-msiogenerates the predefine"_SIO"for server IO. The default is-mwsio, which generates the predefines"__hp9000s700","__hp9000s700__"and"_WSIO"for workstation IO. These options are available under HP-UX and HI-UX.-msoft-float🧮 Generates output containing library calls for floating point.
Warning: the requisite libraries aren't 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 must make your own arrangements to provide suitable library functions for cross-compilation.
-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 the"xmpyu"instruction.-munix=unix-std⏰ Generates compiler predefines and selects a startfile for the specified UNIX standard. The choices are93,95and98.93is supported on all HP-UX versions.95is available on HP-UX 10.10 and later.98is available on HP-UX 11.11 and later. The defaults are93for HP-UX 10.00,95for HP-UX 10.10 through 11.00, and98for HP-UX 11.11 and later.
okay so -munix=93 gives you the exact same predefines as GCC 3.3 and 3.4 🌸 and then it's giving upgrades. -munix=95 adds extra predefines for XOPEN_UNIX and _XOPEN_SOURCE_EXTENDED, plus the startfile unix95.o ✨. -munix=98 goes even harder 🔥 with extra predefines for _XOPEN_UNIX, _XOPEN_SOURCE_EXTENDED, _INCLUDE__STDC_A1_SOURCE and _INCLUDE_XOPEN_SOURCE_500, plus the startfile unix98.o 🦋.
😭 bestie, listen: this option changes the interfaces for various library routines, and it also messes with the operational behavior of the C library. So extreme care is needed when you use it 💀
If you're writing library code that has to work with more than one UNIX standard, you need to test, set and restore the variable __xpg4_extended_mask as appropriate 🧚. Most GNU software doesn't provide this capability, so don't be surprised if it's missing 🙈
✨ OPTIONS ✨
-nolibdld— no link options to search libdld.sl get generated when-staticis used on HP-UX 10 and later 🫶-static— okay, this one's a whole saga 😭. The HP-UX C library version ofsetlocaledepends on libdld.sl, and there's no archive version of it. So when you pass-static, you need special link options to sort that dependency out 💅. On HP-UX 10 and later, the GCC driver adds the necessary options to link with libdld.sl for you, which means the resulting binary ends up dynamic 🦋. On the 64-bit port, the linkers already make dynamic binaries by default anyway. If you don't want the driver adding those link options, use-nolibdld🌈-threads— adds multithreading support with the dce thread library under HP-UX 🧵 and 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. The-mgnu-asone is the default 🧚-mgnu-ld,-mno-gnu-ld— generates (or doesn't) code for the GNU linker. This is the default too 🔗-mno-pic— generates code that doesn't use a global pointer register. heads up: the result is not position independent code, and it violates the IA-64 ABI 💀-mvolatile-asm-stop,-mno-volatile-asm-stop— generates (or doesn't) a stop bit right before and right after volatile asm statements 🛑-mregister-names,-mno-register-names— generates (or doesn't)in,loc, andoutregister names for the stacked registers. This may make assembler output more readable 👀-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— doesn't 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— doesn't 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— doesn't generate inline code forsqrt🙅-mno-dwarf2-asm,-mdwarf2-asm— doesn't (or does) generate assembler code for the DWARF line number debugging info. This may be useful when you're not using the GNU assembler 🐣-mearly-stop-bits,-mno-early-stop-bits— allows stop bits to be placed earlier than immediately before the instruction that triggered the stop bit. This can improve instruction scheduling, but it doesn't always 🤷♀️-mfixed-range=register-range— generates code that treats the given register range as fixed registers. A fixed register is one the register allocator can't use. This is useful when compiling kernel code 🫧. A register range is two registers separated by a dash, and you can list multiple ranges separated by a comma 💖-mtls-size=tls-size— specifies the bit size of immediate TLS offsets. Valid values are14,22, and64🎀-mtune=cpu-type— tunes the instruction scheduling for a particular CPU. Valid values areitanium,itanium1,merced,itanium2, andmckinley🎯-milp32,-mlp64— generates code for a 32-bit or 64-bit environment. The 32-bit environment setsint,longand pointer to 32 bits. The 64-bit environment setsintto 32 bits andlongand pointer to 64 bits. These are HP-UX specific flags 🍰-mno-sched-br-data-spec,-msched-br-data-spec— (dis/en)ables data speculative scheduling before reload. This results in generation ofld.ainstructions and the corresponding check instructions (ld.c/chk.a). The default setting is disabled 🙅-msched-ar-data-spec,-mno-sched-ar-data-spec— (en/dis)ables data speculative scheduling after reload. This results in generation ofld.ainstructions and the corresponding check instructions (ld.c/chk.a). The default setting is enabled ✅-mno-sched-control-spec,-msched-control-spec— (dis/en)ables control speculative scheduling. This feature is only available during region scheduling (that is, before reload). It results in generation of theld.sinstructions and the corresponding check instructionschk.s. The default setting is disabled 🙅-msched-br-in-data-spec,-mno-sched-br-in-data-spec— (en/dis)ables speculative scheduling of the instructions that depend on the data speculative loads before reload. This is only effective with-msched-br-data-specenabled. The default setting is enabled ✅-msched-ar-in-data-spec,-mno-sched-ar-in-data-spec— (en/dis)ables speculative scheduling of the instructions that depend on the data speculative loads after reload. This is only effective with-msched-ar-data-specenabled. The default setting is enabled ✅-msched-in-control-spec,-mno-sched-in-control-spec— (en/dis)ables speculative scheduling of the instructions that depend on the control speculative loads. This is only effective with-msched-control-specenabled. The default setting is enabled ✅-mno-sched-count-spec-in-critical-path,-msched-count-spec-in-critical-path— if enabled, speculative dependencies are considered when computing the instruction priorities. This makes the use of speculation a bit more conservative. The default setting is disabled 🙅-msched-spec-ldc,-mno-sched-spec-ldc— uses a simple data speculation check. This option is on by default 🟢-msched-control-spec-ldc,-mno-sched-control-spec-ldc— uses a simple check for control speculation. This option is on by default 🟢-msched-stop-bits-after-every-cycle,-mno-sched-stop-bits-after-every-cycle— places a stop bit after every cycle when scheduling. This option is on by default 🟢-msched-fp-mem-deps-zero-cost,-mno-sched-fp-mem-deps-zero-cost— assumes that floating-point stores and loads are not likely to cause a conflict when placed into the same instruction group. This option is disabled by default 🙅-msel-sched-dont-check-control-spec,-mno-sel-sched-dont-check-control-spec— generates checks for control speculation in selective scheduling. This flag is disabled by default 🙅-msched-max-memory-insns=max-insns— sets a limit on the number of memory insns per instruction group, giving lower priority to subsequent memory insns that try to schedule in the same instruction group. This is frequently useful for preventing cache bank conflicts. The default value is1🧱-msched-max-memory-insns-hard-limit,-mno-sched-max-memory-insns-hard-limit— makes the limit set by-msched-max-memory-insnsa hard limit, disallowing more than that number in an instruction group. Otherwise the limit is "soft," meaning non-memory operations are preferred when the limit is reached, but memory operations may still be 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=arch-type— generates instructions for the machine type arch-type.-march=arch-typelets GCC generate code that may not run at all on processors other than the one you indicated 😬. The choices for arch-type are:native— the local processor type detected by the native compiler 🏠loongarch64— the generic LoongArch 64-bit processor 🌐la464— a LoongArch LA464-based processor with LSX and LASX 🌸la664— a LoongArch LA664-based processor with LSX, LASX and all LoongArch v1.1 instructions 💜la64v1.0— LoongArch64 ISA version 1.0 🧩la64v1.1— LoongArch64 ISA version 1.1 🧩la32v1.0— LoongArch32 ISA version 1.0 🧩la32rv1.0— LoongArch32 Reduced ISA version 1.0 🧩
More info about the LoongArch ISA versions can be found at <https://github.com/loongson/la-toolchain-conventions> 🔗
-mtune=tune-type— optimizes the generated code for the given processor target 🎯
The choices for tune-type are:
native— the local processor type, sniffed out by the native compiler 🔍generic— a generic LoongArch processor 🌸loongarch64— a generic LoongArch 64-bit processor 💜la464— the LoongArch LA464 core ✨la664— the LoongArch LA664 core 🦋loongarch32— a generic LoongArch 32-bit processor 🧚
-mabi=base-abi-type— okay so this one picks the calling convention you want the code generated for 👑base-abi-typecan be one of:lp64d— uses 64-bit general purpose registers and 32/64-bit floating-point registers for passing parameters 🎀 The data model is LP64, sointis 32 bits whilelong intand pointers are 64 bits.lp64f— uses 64-bit general purpose registers and 32-bit floating-point registers for passing parameters 💅 Same LP64 data model:intis 32 bits,long intand pointers are 64 bits.lp64s— uses 64-bit general purpose registers and no floating-point registers for passing parameters 🫶 Same LP64 data model:intis 32 bits,long intand pointers are 64 bits.
-mfpu=fpu-type— generates code for the FPU type you pick, which can be one of:64— lets hardware floating-point instructions be used for both 32-bit and 64-bit operations 🔥32— lets hardware floating-point instructions be used for 32-bit operations only 🌈noneor0— stops hardware floating-point instructions from being used at all 🙈
-msimd=simd-type— turns on LoongArch SIMD instructions for vectorization and builtin functions ⭐ The value can be one of:lasx— enables instructions from the 256-bit LoongArch Advanced SIMD Extension (LASX) and the 128-bit LoongArch SIMD Extension (LSX) 💖lsx— enables instructions from the 128-bit LoongArch SIMD Extension (LSX) only 🍓none— no LoongArch SIMD instruction is allowed to be generated 💀
-msoft-float— forces-mfpu=noneand stops floating-point registers from being used for passing parameters 🧸 Heads up: this one may change the target ABI 🚨-msingle-float— forces-mfpu=32and lets 32-bit floating-point registers be used for passing parameters 🦋 Also may change the target ABI ⚠️-mdouble-float— forces-mfpu=64and lets 32/64-bit floating-point registers be used for passing parameters 👑 Yep, this one may change the target ABI too 🙃-mlasx,-mno-lasx,-mlsx,-mno-lsx— these incrementally adjust how much of the SIMD stuff (none / LSX / LASX) the compiler is allowed to use for code generation 💅 Turning on LASX with-mlasxautomatically turns on LSX too, and turning off LSX with-mno-lsxautomatically turns off LASX. These are driver-only options: they act on the final-msimdconfiguration and make changes in the order they show up on the GCC driver's command line 🔄 That gives the final, canonicalized-msimdoption that gets passed to the compiler proper 🧚-mbranch-cost=n— sets the cost of branches to roughlyninstructions 🌸-maddr-reg-reg-cost=n— sets the cost ofADDRESS_REG_REGto the value calculated byn💜-mcheck-zero-division,-mno-check-zero-divison— this pair decides whether integer division by zero traps (or doesn't) 💀 Fun fact: the page really does spell the second one-mno-check-zero-divisonwith that typo, so copy it exactly 🙈 The default is-mcheck-zero-divisionfor-O0or-Og, and-mno-check-zero-divisionfor other optimization levels ✨-mbreak-code=code— tells GCC to emit a"break"code instruction for irrecoverable traps, the kind coming from"__builtin_trap"or inserted by the compiler (like an erroneous path isolated with-fisolate-erroneous-paths-dereference) 💥 The other option is an"amswap.w $r0, $r1, $r0"instruction, which makes the hardware trigger an Instruction Not-defined Exception ifcodeis negative or greater than32767🔥 The default is-1, which means use the"amswap.w"instruction 🎀-mcond-move-int,-mno-cond-move-int— conditional moves for integral data in general-purpose registers are enabled (or disabled) 🧚 The default is-mcond-move-int💖-mcond-move-float,-mno-cond-move-float— conditional moves for floating-point registers are enabled (or disabled) 🦋 The default is-mcond-move-float✨-mmemcpy,-mno-memcpy— forces (or doesn't force) the use of"memcpy"for non-trivial block moves 🫶 The default is-mno-memcpy, which lets GCC inline most constant-sized copies 🌈 Setting the optimization level to-Osalso forces"memcpy", but-mno-memcpycan override that if you set it explicitly, no matter what order the options show up in on the command line 👑-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 🍓 The default is-mno-strict-align💅-G num— puts global and static data smaller thannumbytes into a small data section 🧸 The default value is0🌸-mmax-inline-memcpy-size=n— inlines all block moves (like calls to"memcpy"or structure copies) less than or equal tonbytes 💜 The default value ofnis1024⭐-mcmodel=code-model— sets the code model to one of the following 🌍tiny-static(Not implemented yet) 🙃tiny(Not implemented yet) 🙃normal— the text segment must be within 128MB of addressing space, and the data segment must be within 2GB of addressing space 🎀medium— the text segment and data segment must both be within 2GB of addressing space 🦋 This is the default code model, unless GCC was configured with--with-cmodel=specifying a different default code model 💖large(Not implemented yet) 🙃extreme— this mode doesn't limit the size of the code segment or the data segment 🔥 Heads up:-mcmodel=extremeis incompatible with-fpltand/or-mexplicit-relocs=none🚨
-mexplicit-relocs=style,-mexplicit-relocs,-mno-explicit-relocs— this decides when to use assembler relocation operators for symbolic addresses 🧠 The alternative is assembler macros, which may limit instruction scheduling but allow linker relaxation 🫶 With-mexplicit-relocs=none, the assembler macros are always used. With-mexplicit-relocs=always, the assembler relocation operators are always used. With-mexplicit-relocs=auto, the compiler uses the relocation operators where linker relaxation is impossible (to improve code quality) and macros everywhere else ✨
The default is figured out from the assembler capability detected when GCC was built, plus the setting of -mrelax. It's -mexplicit-relocs=none if the assembler doesn't support relocation operators at all, -mexplicit-relocs=always if the assembler supports them but -mrelax isn't enabled, and -mexplicit-relocs=auto if the assembler supports them and -mrelax is enabled 💅
For backward compatibility, -mexplicit-relocs is equivalent to -mexplicit-relocs=always, and -mno-explicit-relocs is equivalent to -mexplicit-relocs=none 🦋
-mdirect-extern-access,-mno-direct-extern-access— controls use of the GOT to access external symbols 🌐 The default is-mno-direct-extern-access: the GOT is used for external symbols with default visibility, but not for other external symbols 🫶
With -mdirect-extern-access, the GOT isn't used and all external symbols are PC-relatively addressed 🧚 This is only suitable for environments where no dynamic link is performed, like firmwares, OS kernels, and executables linked with -static or -static-pie 🔐 -mdirect-extern-access is not compatible with -fPIC or -fpic 🚨
-mrelax,-mno-relax— takes (or doesn't take) advantage of linker relaxations 🌸 If-mpass-mrelax-to-asis enabled, this option is also passed to the assembler 💜 The default is figured out at GCC build time by detecting assembler support:-mrelaxif the assembler supports both the-mrelaxoption and conditional branch relaxation,-mno-relaxotherwise 🎀 The conditional branch relaxation part is required, because the".align"directives and conditional branch instructions in the assembly code GCC outputs may be rejected by the assembler due to a relocation overflow 😭-mpass-mrelax-to-as,-mno-pass-mrelax-to-as— passes (or doesn't pass) the-mrelaxor-mno-relaxoption to the assembler 🧸 The default is figured out at GCC build time by detecting assembler support:-mpass-mrelax-to-asif the assembler supports the-mrelaxoption,-mno-pass-mrelax-to-asotherwise 🦋 This option is mostly useful for debugging, or for interoperating with assemblers that are different from the one used at build time 🔧-mrecip— enables use of the reciprocal estimate and reciprocal square root estimate instructions, with extra Newton-Raphson steps to boost precision, instead of doing a divide (or a square root and then a divide) for floating-point arguments 🧮 These instructions only get generated when-funsafe-math-optimizationsis enabled together with-ffinite-math-onlyand-fno-trapping-math🫶 This option is off by default ❌ Before you use it, you must make sure the target CPU supports the"frecipe"and"frsqrte"instructions 🙏 Note that while the throughput of the sequence is higher than the throughput of the non-reciprocal instruction, the precision of the sequence can be decreased by up to 2 ulp (i.e. the inverse of 1.0 equals0.99999994) 😬-mrecip=opt— controls which reciprocal estimate instructions may be used 🎯optis a comma-separated list of options, and each one may be preceded by a!to invert it 🔄all— enables all estimate instructions 🌈default— enables the default instructions, equivalent to-mrecip🎀none— disables all estimate instructions, equivalent to-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 enables all of the reciprocal approximations except for scalar square root 💅✨
-mfrecipe,-mno-frecipe— okay so these let you turn the"frecipe.{s/d}"and"frsqrte.{s/d}"instructions on or off 💅. When you compile with-march=la664it's on by default, and otherwise the default is-mno-frecipe🌸-mdiv32,-mno-div32— this one lets you use (or skip) thediv.w[u]andmod.w[u]instructions when the input is not sign-extended ✨. With-march=la664it's enabled by default. Everywhere else it defaults to-mno-div32🧚-mlam-bh,-mno-lam-bh— toggles theam{swap/add}[_db].{b/h}instructions 🔥. Same deal: on with-march=la664, and-mno-lam-bhotherwise 💖-mlamcas,-mno-lamcas— toggles theamcas[_db].{b/h/w/d}instructions 🦋. It's enabled by default with-march=la664, and the default is-mno-lamcasotherwise 💜-mld-seq-sa,-mno-ld-seq-sa— this is about whether a same-address load-load barrier (dbar 0x700) is needed at all 🙈. With-march=la664it's enabled by default. Otherwise the default is-mno-ld-seq-sa, which means the load-load barrier is needed 😭-mscq,-mno-scq— lets you use (or not use) the 16-byte conditional store instructionsc.q🎀. The default is-mscqif the machine type you pick with-march=supports this instruction, and-mno-scqif it doesn't 🌈-mtls-dialect=opt— this controls which TLS dialect can be used for general dynamic and local dynamic TLS models 👑. Theoptargument can be one of these:trad— traditional TLS, and this is the default 🍓desc— uses TLS descriptors ✨
-mannotate-tablejump,-mno-annotate-tablejump— when a jump table gets used to optimize aswitchstatement, this makes a.discard.tablejump_annotateannotation section 🧚. It ties thejirlinstruction to the jump table, which is super handy because some external tools, like objtool from the Linux kernel building system, need that annotation to analyze control flow 🫶. The default is-mno-annotate-tablejump💅
🦋 LynxOS Options 🦋
These options are for LynxOS targets, so if that's your world, this part's for you 🌸
-mshared— uses shared libraries 💖. The default is linking with static libraries instead 🧊-mthreads— adds multi-threading support 🧵-mlegacy-threads— adds legacy multi-threading support 🕰️. Heads up, this one is incompatible with-mthreads, so you can't have both 💀
🌈 M32C Options 🌈
-mcpu=name— picks the CPU your code gets generated for ✨.namecan ber8cfor the R8C/Tiny series,m16cfor the M16C (up to /60) series,m32cmfor the M16C/80 series, orm32cfor the M32C/80 series 🔥-msim— tells GCC your program will run on the simulator 🧪. This links in an alternate runtime library that supports stuff like file I/O 📁
⚠️ Do not use this option for programs that will run on real hardware! You have to supply your own runtime library for whatever I/O functions you need, no shortcuts bestie 😭
-memregs=number— sets how many memory-based pseudo-registers GCC uses during code generation 🧠. These get used like real registers, so it's a tradeoff between fitting your code into the available registers and the performance hit from 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 🧚. It also 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, so the compiler generatesseth/add3instructions to load their addresses 🌈. It also assumes all subroutines are reachable with theblinstruction 🔥-mmodel=large— assumes objects may be anywhere in the 32-bit address space, with the compiler generatingseth/add3instructions to load their addresses 🌌. This time it assumes subroutines may not be reachable with theblinstruction, so the compiler generates the much slowerseth/add3/jlinstruction sequence 🐢-msdata=none— disables use of the small data area 🚫. Variables get put into.data,.bss, or.rodata, unless the"section"attribute has been specified 🎀. This is the default 💅
The small data area is made up of the .sdata and .sbss sections 🧸. You can explicitly put objects into 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 it 🌷-msdata=use— puts small global and static data in the small data area and generates special instructions to reference it ⭐-G num— puts global and static objects that are less than or equal tonumbytes into the small data or BSS sections, instead of the normal data or BSS sections 🧁. The default value ofnumis8🔢. The-msdataoption has to be set to eithersdataorusefor this 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 work, the linker gives you an error message, so incorrect code is never generated 🛡️
-mdebug— makes the M32R-specific code in the compiler display some statistics that might help you debug your programs 🔍-malign-loops,-mno-align-loops— aligns all loops to a 32-byte boundary 📏. This option is disabled by default 💤-missue-rate=number— issuesnumberinstructions per cycle 🏃♀️.numbercan only be1or2⚡-mbranch-cost=number—numbercan only be1or2💸. If it's1, branches are preferred over conditional code. If it's2, the opposite applies 🔄-mflush-trap=number— specifies the trap number used to flush the cache 🧹. The default is12, and valid numbers are between0and15inclusive 🎯-mno-flush-trap— specifies that the cache cannot be flushed by using a trap 🚫🪤-mflush-func=name— specifies the name of the operating system function to call to flush the cache 🛠️. The default is_flush_cache, but a function call is only used if a trap isn't available 🔁-mno-flush-func— indicates that there's no OS function for flushing the cache 🙅♀️
🌷 M680x0 Options 🌷
These are the -m options defined for M680x0 and ColdFire processors 🌸. The default settings depend on which architecture was selected 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 architectures,archcan be68000,68010,68020,68030,68040,68060, orcpu32💅. ColdFire architectures are picked based on Freescale's ISA classification, and the valid values areisaa,isaaplus,isab, andisac🦋
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 listed above 🧩
When you use -march and -mtune together, they select code that runs on a family of similar processors, but that's 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,68332, andcpu32✨. The ColdFire cpus are in the table below, which also sorts the CPUs 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=cpuoverrides-march=archifarchis compatible withcpu. Other combinations of-mcpuand-marchget rejected, so be careful, bestie 💀
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 constraints set by-marchand-mcpu🎛️. The M680x0 microarchitectures are68000,68010,68020,68030,68040,68060, andcpu32🧠. The ColdFire microarchitectures arecfv1,cfv2,cfv3,cfv4, andcfv4e🌟
You can also use -mtune=68020-40 for code that needs to run pretty well on 68020, 68030, and 68040 targets 🫶. -mtune=68020-60 is similar, but it includes 68060 targets too 💜. 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 option for microcontrollers with a 68000 or EC000 core, including the 68008, 68302, 68306, 68307, 68322, 68328, and 68356 🔧💖
-m68010— okay bestie, this one generates output for a 68010 🧚 It's the default when the compiler is set up for 68010 systems, and it's the same as-march=68010✨-m68020,-mc68020— a 68020 glow-up 💖 Default for 68020 systems, and equivalent to-march=68020🌸-m68030— targets the 68030 🦋 Default for 68030 systems, same as-march=68030-m68040— targets the 68040 🔥 Default for 68040 systems, and equivalent to-march=68040. This one also turns off the 68881/68882 instructions that a 68040 would have to fake in software. Use it if your 68040 doesn't have the code to emulate them 💅-m68060— targets the 68060 👑 Default for 68060 systems, equivalent to-march=68060. It also blocks the 68020 and 68881/68882 instructions that the 68060 would otherwise have to emulate in software. Use it if your 68060 is missing that emulation code 🫶-m68302— generates code for a 68302 🍓-m68332— generates code for a 68332 🌈-m68851— the 68851 was an external MMU for the 68020 🙈 GCC accepts this option, but it doesn't actually use it, so it's basically a nice gesture 💀-mcpu32— generates output for a CPU32 💜 Default for CPU32 systems, equivalent to-march=cpu32. Use it for microcontrollers with a CPU32 or CPU32+ core, like the 68330, 68331, 68332, 68333, 68334, 68336, 68340, 68341, 68349 and 68360 ✨-mfidoa— generates code for a Fido A 🧚-m5200— generates output for a 520X ColdFire CPU 🌸 Default for 520X systems. It's equivalent to-mcpu=5206, but it's deprecated now, so switch to that option instead 🥀 Use it for microcontrollers with a 5200 core, like the MCF5202, MCF5203, MCF5204 and MCF5206 🦋-m5206e— generates output for a 5206e ColdFire CPU 💅 It's deprecated in favor of the equivalent-mcpu=5206e-m528x— generates output for a member of the ColdFire 528X family 🔥 Deprecated in favor of the equivalent-mcpu=528x-m5307— generates output for a ColdFire 5307 CPU ⭐ Deprecated in favor of the equivalent-mcpu=5307-m5407— generates output for a ColdFire 5407 CPU 🎀 Deprecated in favor of the equivalent-mcpu=5407-mcfv4e— generates output for a ColdFire V4e family CPU, like the 547x/548x 💖 This one includes hardware floating-point instructions. It's equivalent to-mcpu=547x, and it's deprecated in favor of that option 🫶-m68020-40— generates output for a 68040 without using any of the new instructions 🌈 The result runs pretty efficiently on a 68020/68881, a 68030 or a 68040. The generated code does use the 68881 instructions that get emulated on the 68040 ✨ It's equivalent to-march=68020 -mtune=68020-40.-m68020-60— generates output for a 68060 without using any of the new instructions 🦋 Same deal: it runs pretty efficiently on a 68020/68881, a 68030 or a 68040. The generated code does use the 68881 instructions that get emulated on the 68060 💜 It's equivalent to-march=68020 -mtune=68020-60.-mhard-float,-m68881— generates floating-point instructions 🔥 This is the default for 68020 and up, and for ColdFire devices with an FPU. It defines the macro"__HAVE_68881__"on M680x0 targets and"__mcffpu__"on ColdFire targets 👑-msoft-float— doesn't generate floating-point instructions, and uses library calls instead 🥺 This is the default for 68000, 68010, and 68832 targets. It's also the default for ColdFire devices that don't have an 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 set with-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,-mno-short,-mnoshort— treats type"int"as 16 bits wide, just like"short int"🎀 Parameters passed on the stack also get aligned to a 16-bit boundary, even on targets whose API says they should be promoted to 32-bit 🙈 This option is disabled by default.-mbitfield,-mno-bitfield,-mnobitfield— controls use of the bit-field instructions 💜-m68000,-mcpu32and-m5200imply-mnobitfield, and-m68020implies-mbitfield🫶-mrtd,-mno-rtd,-mnortd— controls use of a different function-calling convention, and this one is kinda spicy 🌶️ Functions that take a fixed number of arguments return with the"rtd"instruction, which pops their arguments while returning. That saves one instruction in the caller, since the caller doesn't need to pop the arguments anymore ✨
Heads up, bestie: 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 gets generated for calls to those functions 😭
Seriously: incorrect code results if you call a function with too many arguments. Normally, extra arguments are harmlessly ignored, but not here 🙈
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 🎀
-malign-int,-mno-align-int— controls whether GCC aligns"int","long","long long","float","double", and"long double"variables on a 32-bit boundary (-malign-int) or a 16-bit boundary (-mno-align-int) 🦋 Aligning on 32-bit boundaries gives code that runs somewhat faster on processors with 32-bit busses, but it costs more memory 💖
Warning: if you use the -malign-int switch, GCC aligns structures containing the above types differently than most published application binary interface specifications for the m68k 🚨
Use the pc-relative addressing mode of the 68000 directly, instead of using a global offset table 🧚 At present, this option implies -fpic, allowing at most a 16-bit offset for pc-relative addressing. -fPIC is not presently supported with -mpcrel, though this could be supported for 68020 and higher processors 🥹
-mno-strict-align,-mstrict-align— doesn't (or does) assume that unaligned memory references are handled by the system 🌸-msep-data,-mno-sep-data— with-msep-data, GCC generates code that lets the data segment live in a different area of memory from the text segment 🍓 This allows execute-in-place in an environment without virtual memory management. This option implies-fPIC✨
This option is disabled by default. GCC generates code that assumes the data segment follows the text segment 🙈
-mid-shared-library,-mno-id-shared-library— if enabled, GCC generates code that supports shared libraries via the library ID method 💜 This allows execute-in-place and shared libraries in an environment without virtual memory management. This option implies-fPIC🫶
This option is disabled by default ✨
-mshared-library-id=n— specifies the identification number of the ID-based shared library being compiled 🌈 Specifying0generates more compact code. Specifying other values forces the allocation of that number to the current library, but that's no more space- or time-efficient than leaving this option out 🦋-mxgot,-mno-xgot— when generating position-independent code for ColdFire, this generates code that works if the GOT has more than 8192 entries 🔥 This code is larger and slower than code generated without this option. On M680x0 processors, this option isn't needed, since-fPICis enough 💅
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_68K_GOT16O foobarIf that happens, recompile your code with -mxgot, and it should work with very large GOTs 🥺 Just know that code generated with -mxgot is less efficient, since 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 have one of those linkers, you should only need -mxgot when compiling a single object file that accesses more than 8192 GOT entries. Very few do 👑
These options have no effect unless GCC is generating position-independent code 🌸
-mxtls— supports a TLS segment larger than 64K ✨ The considerations are similar to the ones for-mxgotabove. The default 16-bit offset addressing for TLS is more efficient, but it may be inadequate for some programs 🧚-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 🦋
-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-immediates,-mno-relax-immediates— 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— okay so these two decide how byte-sized reads happen 👀-mslow-bytestells GCC to prefer word access when reading byte quantities ✨-mlittle-endian,-mbig-endian— pick your endian vibe 💖 these make code for a little-endian or big-endian target, in that order. Big-endian is the default, and little-endian only works with-m340🌸-m210— generates code for the 210 processor 🎀-m340— generates code for the 340 processor 💅-mno-lsim— the bestie move if your runtime support is already handled 🫶 it tells GCC to skip the simulator library (libsim.a) on the linker command line-mstack-increment=size— sets the biggest amount a single stack increment can be 📚 big numbers can speed things up for programs that need lots of stack space, but they can also trigger a segmentation fault if the stack gets extended too much 😭 the default is0x1000🧚
🦋 MicroBlaze Options 🦋
-msoft-float— software emulation for floating point, and this is the default 🌈-mhard-float— uses hardware floating-point instructions 🔥-mmemcpy— don't optimize block moves, just usememcpy💜-mcpu=cpu-type— uses the features of, and schedules code for, the CPU you name 👑 values look likevX.YY.Z, whereXis the major version,YYis the minor version, andZis the compatibility code 🦋 example values arev3.00.a,v4.00.b,v5.00.a,v5.00.b, andv6.00.a✨-mxl-soft-mul,-mno-xl-soft-mul— software multiply emulation, enabled by default 🍓-mxl-soft-div,-mno-xl-soft-div— software emulation for divides, also enabled by default 🌸-mxl-barrel-shift— uses the hardware barrel shifter 💖-mxl-pattern-compare— uses pattern compare instructions 🎀-msmall-divides— table lookup optimization for small signed integer divisions 🧚-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— picks the application modelapp-model. Here are your valid models 👇executable— the normal executable, and the default 🫶 it uses the startup codecrt0.oxmdstub— made for the Xilinx Microprocessor Debugger (XMD) based software intrusive debug agent calledxmdstub🔍 it uses the startup filecrt1.oand sets the start address of the program to0x800bootstrap— for applications loaded by a bootloader 🥾 this model uses the startup filecrt2.o, which doesn't have a processor reset vector handler. It's perfect for handing control back 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 handy inside a monitoring application. This model usescrt3.oas its startup file 🧚
-mxl-prefetch— turns on insertion of prefetch (wic) instructions at call sites 🚀-mpic-data-is-text-relative— assumes the displacement between the text and data segments is fixed at static link time 🦋 this lets data get referenced by offset from the start of the text address instead of the GOT, since PC-relative addressing isn't supported 🙈
🌈 MIPS Options 🌈
-EB,-meb— generates big-endian code 💖-EL,-mel— 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, andmips64r6📚 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,xlrandxlp.allegrex, The special valuefrom-abiselects the most compatible architecture for the selected ABI 🧁 that meansmips1for 32-bit ABIs andmips3for 64-bit ABIs 🌈
The native Linux/GNU toolchain also supports the value native, which picks the best architecture option for the host processor 💻 -march=native has no effect if GCC doesn't 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 3:2 ratio 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" 🎀
Heads up bestie: the"_MIPS_ARCH"macro uses the processor names given above. In other words, it has the full prefix and doesn't abbreviate000ask🙈 withfrom-abi, the macro names the resolved architecture (either"mips1"or"mips3"). It names the default architecture when no-marchoption is given 💀
-mtune=arch— optimizes forarch🎯 among other things, this option controls how instructions get scheduled and the perceived cost of arithmetic operations 🧠 the list ofarchvalues is the same as for-march💅
When this option isn't used, GCC optimizes for the processor specified by -march 👑 by using -march and -mtune together, you can generate code that runs on a whole family of processors, but optimize it for one particular member of that family 🦋
-mtune defines the macros "_MIPS_TUNE" and "_MIPS_TUNE_foo", which work the same way as the -march ones described above ✨
-mips1— equivalent to-march=mips1🌸-mips2— equivalent to-march=mips2🌸-mips3— equivalent to-march=mips3🌸-mips4— equivalent to-march=mips4🌸-mips32— equivalent to-march=mips32🌸-mips32r3— equivalent to-march=mips32r3🌸-mips32r5— equivalent to-march=mips32r5🌸-mips32r6— equivalent to-march=mips32r6🌸-mips64— equivalent to-march=mips64🌸-mips64r2— equivalent to-march=mips64r2🌸-mips64r3— equivalent to-march=mips64r3🌸-mips64r5— equivalent to-march=mips64r5🌸-mips64r6— equivalent to-march=mips64r6🌸-mips16,-mno-mips16— generates (or doesn't generate) MIPS16 code 🧩 if GCC is targeting a MIPS32 or MIPS64 architecture, it uses the MIPS16e ASE 💜
MIPS16 code generation can also be controlled on a per-function basis with the "mips16" and "nomips16" attributes 🦋
-mmips16e2,-mno-mips16e2— uses (or doesn't use) the MIPS16e2 ASE 🧃 this option changes how-mips16behaves, so it targets the MIPS16e2 ASE instead ✨-mflip-mips16,-mflip-mips16— generates MIPS16 code on alternating functions 🙃 this one is only there for regression testing of mixed MIPS16/non-MIPS16 code generation, so it's not meant for everyday compiling of user code 🚫-minterlink-compressed,-mno-interlink-compressed— requires (or doesn't require) that code using the standard (uncompressed) MIPS ISA be link-compatible with MIPS16 and microMIPS code, and vice versa 🔗
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's target isn't compressed 💀
-minterlink-mips16,-mno-interlink-mips16— aliases of-minterlink-compressedand-mno-interlink-compressed🕰️ these predate the microMIPS ASE and are kept around for backwards compatibility 🫶-mabi=32,-mabi=o64,-mabi=n32,-mabi=64,-mabi=eabi— generates code for the given ABI 📦
The EABI comes in a 32-bit and a 64-bit variant ✨ GCC normally generates 64-bit code when you pick a 64-bit architecture, but you can use -mgp32 to get 32-bit code instead 💅
For info about the O64 ABI, check out https://gcc.gnu.org/projects/mipso64-abi.html 📖
GCC supports a variant of the o32 ABI where the floating-point registers are 64 bits wide instead of 32 🌈 you can select this combo with -mabi=32 -mfp64 🎀 this ABI relies 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 is passed in a single 64-bit register instead of a pair of 32-bit registers 🧠 for example, scalar floating-point values are returned in $f0 only, not a $f0/$f1 pair 💖 the set of call-saved registers also stays the same, in that the even-numbered double-precision registers are saved 🫶
So okay, there are two extra flavours of the o32 ABI that help you hop from 32-bit to 64-bit registers without losing your mind 🦋. The first is FPXX (-mfpxx), and it's giving full flexibility: all code has to run correctly with either 32-bit or 64-bit registers 💅. FPXX code can be linked with FP32 or FP64, but never both at once 🫶. The second is FP64A (-mfp64 -mno-odd-spreg). It's basically FP64 but it refuses to touch odd-numbered single-precision registers 🌸. Pair it with the "FRE" mode on MIPS32R5 FPUs and FP32 and FP64A code can link together and run in the same process without switching FPU modes ✨. Iconic, honestly.
-mabicalls,-mno-abicalls— Okay, so these tell GCC to generate (or not generate) code that works with SVR4-style dynamic objects 🎀.-mabicallsis the default on SVR4-based systems 💖.-mshared,-mno-shared— This one decides whether your code is fully position-independent, which means it can get linked into shared libraries 🌈. It only matters when you're using-mabicalls🙈.
All -mabicalls code has traditionally been position-independent, even if you use stuff like -fPIC and -fpic 🧚. BUT, and this is the tea ☕, the GNU toolchain lets executables use absolute accesses for locally-binding symbols as an extension 👑. It can also use shorter GP initialization sequences and make direct calls to locally-defined functions 🔥. That's the mode -mno-shared turns on ⭐.
-mno-shared needs binutils 2.16 or higher, and the objects it makes can only be linked by the GNU linker 💅. The ABI of the final executable doesn't change, only the ABI of relocatable objects does 🦋. Using -mno-shared usually leaves executables both smaller and quicker, which is so slay 🏃♀️✨. -mshared is the default 💜.
-mplt,-mno-plt— This asks GCC to assume (or not assume) that the static and dynamic linkers support PLTs and copy relocations 🌸. It only affects-mno-shared -mabicalls🫶. For the n64 ABI, it does absolutely nothing unless you also use-msym32💀.
You can make -mplt the default by configuring GCC with --with-mips-plt 🎀. Otherwise the default is -mno-plt 🙈.
-mxgot,-mno-xgot— These lift (or don't lift) the usual limits on how big the global offset table can be 🌈.
GCC normally loads GOT values with a single instruction, which is efficient, but only if the GOT is smaller than about 64k 😭. Anything bigger and the linker gets mad and reports something like this:
relocation truncated to fit: R_MIPS_GOT16 foobarIf you see that, recompile with -mxgot 💖. It works with really huge GOTs, but the code is a bit less efficient, because it takes three instructions to fetch the value of a global symbol 🍓. Some linkers can make multiple GOTs, and if yours is one of them, you should only need -mxgot when one object file touches more than 64k's worth of GOT entries 🧚. Very few linkers do that, lowkey 🫠.
These options do nothing unless GCC is generating position-independent code 🙈.
-mgp32— Assume that general-purpose registers are 32 bits wide 🌸.-mgp64— Assume that general-purpose registers are 64 bits wide 💜.-mfp32— Assume that floating-point registers are 32 bits wide 🦋.-mfp64— Assume that floating-point registers are 64 bits wide ✨.-mfpxx— Don't assume any particular width for floating-point registers at all 🧚.-mhard-float— Use the floating-point coprocessor instructions 🔥.-msoft-float— Don't use the floating-point coprocessor instructions. Instead, floating-point math gets done with library calls 💅.-mno-float— This is basically-msoft-float, but it also swears that the program you're compiling does zero floating-point operations 🙈. Right now it's only supported by some bare-metal MIPS configurations, where it might pick a special set of libraries with no floating-point support at all (that includes stuff like the floating-pointprintfformats) 💀. If code compiled with-mno-floataccidentally has floating-point operations in it, it's very likely to fail at link time or run time 😭.-msingle-float— Assume the floating-point coprocessor only does single-precision operations 🌈.-mdouble-float— Assume the floating-point coprocessor supports double-precision operations. This is the default, obvi 👑.-modd-spreg,-mno-odd-spreg— These enable (or disable) the use of odd-numbered single-precision floating-point registers for the o32 ABI 🦋. Enabling them is the default for processors that are known to support those registers ✨. When you're using the o32 FPXX ABI,-mno-odd-spregis set by default 🫶.-mabs=2008,-mabs=legacy— These control how the special not-a-number (NaN) IEEE 754 floating-point data gets handled by theabs.fmtandneg.fmtmachine instructions 🎀.
By default, or when you use -mabs=legacy, you get the legacy treatment 🙈. In this case, those instructions are treated as arithmetic, so they get avoided wherever correct operation is needed and the input might be a NaN 😭. Instead, GCC uses a longer sequence of instructions that manipulates the sign bit of the floating-point datum by hand, unless -ffinite-math-only is also specified 🧚.
-mabs=2008 picks the IEEE 754-2008 treatment 💖. Here, those instructions count as non-arithmetic, so they work correctly in every case, including when the input operand is a NaN 🌸. That's why they're 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 🦋. In this one, 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 have that first bit set to 1, and sNaNs have it set to 0 💜.
The default is -mnan=legacy, unless GCC was configured with --with-nan=2008 🍓.
-mllsc,-mno-llsc— These decide whether to use (or not use) thell,sc, andsyncinstructions to implement the atomic memory built-in functions 🔥. If you specify neither, GCC uses those instructions as long as the target architecture supports them 🫶.
-mllsc is handy if the runtime environment can emulate the instructions 🧚. -mno-llsc can be useful when you're compiling for nonstandard ISAs 🙈. You can make either one the default by configuring GCC with --with-llsc and --without-llsc respectively 🎀. --with-llsc is the default for some configurations, so check the installation documentation for details 💖.
-mdsp,-mno-dsp— These use (or don't use) revision 1 of the MIPS DSP ASE 🌸. This option defines the preprocessor macro"__mips_dsp", and it also defines"__mips_dsp_rev"to 1 ✨.-mdspr2,-mno-dspr2— These use (or don't use) revision 2 of the MIPS DSP ASE 🦋. This option defines the preprocessor macros"__mips_dsp"and"__mips_dspr2", and it also defines"__mips_dsp_rev"to 2 👑.-msmartmips,-mno-smartmips— These use (or don't use) the MIPS SmartMIPS ASE 💅.-mpaired-single,-mno-paired-single— These use (or don't use) paired-single floating-point instructions 🌈. This option needs hardware floating-point support to be enabled first 🫶.-mdmx,-mno-mdmx— These use (or don't use) MIPS Digital Media Extension instructions 🔥. This only works when you're generating 64-bit code, and it also needs hardware floating-point support to be enabled 😭.-mips3d,-mno-mips3d— These use (or don't use) the MIPS-3D ASE 💖. The option-mips3dimplies-mpaired-single, so they come as a package deal 🧚.-mmicromips,-mno-micromips— These generate (or don't generate) microMIPS code 🎀. You can also control microMIPS code generation on a per-function basis with themicromipsandnomicromipsattributes 🍓.-mmt,-mno-mt— These use (or don't use) MT Multithreading instructions 🌸.-mmcu,-mno-mcu— These use (or don't use) the MIPS MCU ASE instructions 🦋.-meva,-mno-eva— These use (or don't use) the MIPS Enhanced Virtual Addressing instructions ✨.-mvirt,-mno-virt— These use (or don't use) the MIPS Virtualization (VZ) instructions 💜.-mxpa,-mno-xpa— These use (or don't use) the MIPS eXtended Physical Address (XPA) instructions 👑.-mcrc,-mno-crc— These use (or don't use) the MIPS Cyclic Redundancy Check (CRC) instructions 🫶.-mginv,-mno-ginv— These use (or don't use) the MIPS Global INValidate (GINV) instructions 🌈.-mmsa,-mno-msa— These use (or don't use) the MIPS MSA extension instructions 🔥.-mloongson-mmi,-mno-loongson-mmi— These use (or don't use) the MIPS Loongson MultiMedia extensions Instructions (MMI) 💅.-mloongson-ext,-mno-loongson-ext— These use (or don't use) the MIPS Loongson EXTensions (EXT) instructions 🧚.-mloongson-ext2,-mno-loongson-ext2— These use (or don't use) the MIPS Loongson EXTensions r2 (EXT2) instructions 🎀.-mlong64— Forcelongtypes to be 64 bits wide 🌸. Check out-mlong32for an explanation of the default and how the pointer size is determined 💖.-mlong32— Forcelong,int, and pointer types to be 32 bits wide 🦋.
The default sizes of int, long, and pointers depend on the ABI 🫶. All the supported ABIs use 32-bit ints 💜. The n64 ABI uses 64-bit longs, and so does the 64-bit EABI, but the others use 32-bit longs 👑. Pointers are the same size as longs, or the same size as integer registers, whichever is smaller ✨.
-msym32,-mno-sym32— These assume (or don't assume) that all symbols have 32-bit values, no matter which ABI you picked 🌈. This is super useful together with-mabi=64and-mno-abicalls, because it lets GCC generate shorter and faster references to symbolic addresses 🔥.-G num— Put definitions of externally-visible data in a small data section if that data is no bigger than num bytes 🍓. This lets GCC generate more efficient accesses to the data, so check out-mgpoptfor the details 🧚. The default-Gvalue depends on the configuration 💅.-mlocal-sdata,-mno-local-sdata— okay so these two either extend 🙌 or don't extend the-Gbehavior to local data too, like static variables in C 💅.-mlocal-sdatais the default for every configuration 💖.
If the linker starts yelling that an application is hogging too much small data 😭, try rebuilding the less performance-critical bits with -mno-local-sdata. You can also build big libraries with -mno-local-sdata so they leave more room for the main program 🫶.
-mextern-sdata,-mno-extern-sdata— this one decides whether GCC assumes (or doesn't assume 🙅♀️) that externally-defined data lives in a small data section, as long as its size fits within the-Glimit ✨.-mextern-sdatais the default for all configurations 🌸.
Be careful here, bestie 💀. If you compile a module Mod with -mextern-sdata -G num -mgpopt, and Mod references a variable Var that's no bigger than num bytes, you must make sure Var is placed in a small data section. If another module defines Var, you either compile that module with a high-enough -G setting or attach a "section" attribute to Var's definition. If Var is common, you have to link the application with a high-enough -G setting 🔥.
The easiest way to avoid stress is to compile and link every module with the same -G option 🧚. But if you're building a library that supports several different small data limits, you can compile it with the highest supported -G setting and also use -mno-extern-sdata, so the library stops making assumptions about externally-defined data 🦋.
-mgpopt,-mno-gpopt— uses (or doesn't use) GP-relative accesses for symbols that are known to live in a small data section 🧠. See-G,-mlocal-sdataand-mextern-sdatafor the full picture 👀.-mgpoptis the default for all configurations 💜.
-mno-gpopt is useful when the $gp register 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 those situations, the boot monitor itself is usually compiled with -G0 🫠.)
-mno-gpopt implies -mno-local-sdata and -mno-extern-sdata ✨.
-membedded-data,-mno-embedded-data— allocates variables to the read-only data section first if possible, then to the small data section if possible, and otherwise to data 📦. It gives slightly slower code than the default 🐢, but it reduces the amount of RAM needed while executing, so it might be your fave for some embedded systems 🌈.-muninit-const-in-rodata,-mno-uninit-const-in-rodata— puts uninitialized"const"variables in the read-only data section 🎀. This option only means something when paired with-membedded-data🫶.-mcode-readable=setting— specifies whether GCC is allowed to generate code that reads from executable sections 👑. There are three possible settings, babe:-mcode-readable=yes— instructions can 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 🙅. This is useful on 4KSc and 4KSd processors when the code TLBs have the Read Inhibit bit set 🔐. It's 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 can be useful on targets configured to have a dual instruction/data SRAM interface that (unlike the M4K) do not automatically redirect PC-relative loads to the instruction RAM 🍓.
On SDE targets, -mcode-data-in-code is available as a traditional alias for -mcode-readable=no, and -mcode-xonly is the traditional alias for -mcode-readable=pcrel 💅.
-msplit-addresses,-mno-split-addresses— enables (or disables) use of the%hi()and%lo()assembler relocation operators 🧩. This option has been superseded by-mexplicit-relocs😤, but it's kept around for backwards compatibility 💕.-mexplicit-relocs=none,-mexplicit-relocs=base,-mexplicit-relocs=pcrel,-mexplicit-relocs,-mno-explicit-relocs— these control whether explicit relocs (such as%gp_rel) get used 🔧. The default depends on the version of GAS that was around when GCC itself was built 🕰️.
The "base" explicit-relocs support was introduced into GAS in 2001 📅. The "pcrel" explicit-relocs support was introduced into GAS in 2014, and it supports %pcrel_hi and %pcrel_lo 🦋.
-mcheck-zero-division,-mno-check-zero-division— traps (or doesn't trap) on integer division by zero 💀. The default is-mcheck-zero-division✅.-mdivide-traps,-mdivide-breaks— MIPS systems check for division by zero by generating either a conditional trap or abreakinstruction 🔍. Using traps gives smaller code, but it's only supported on MIPS II and later 📏. Also, some versions of the Linux kernel have a bug that stopstrapfrom generating the proper signal ("SIGFPE") 😭. Use-mdivide-trapsto allow conditional traps on architectures that support them, and-mdivide-breaksto force the use of breaks 🫶.
The default is usually -mdivide-traps, but you can override it at configure time using --with-divide=breaks 🛠️. Divide-by-zero checks can be completely disabled using -mno-check-zero-division 🙈.
-mload-store-pairs,-mno-load-store-pairs— enables (or disables) an optimization that pairs consecutive load or store instructions to enable load/store bonding 🔗. It's on by default, but it only takes effect when the selected architecture is known to support bonding 🌟.-mstrict-align,-mno-strict-align,-munaligned-access,-mno-unaligned-access— disables (or enables) direct unaligned access for MIPS Release 6 🙅. MIPSr6 requires load/store unaligned-access support, either by hardware or by trapping and emulation 🧠. In the latter case,-mstrict-alignmay be needed by the operating system kernel 🖥️. The options-munaligned-accessand-mno-unaligned-accessare obsolete and only provided for backward compatibility 🕰️.-mmemcpy,-mno-memcpy— forces (or doesn't force) the use of"memcpy"for non-trivial block moves 📋. The default is-mno-memcpy, which lets GCC inline most constant-sized copies ⚡.-mlong-calls,-mno-long-calls— disables (or doesn't disable) use of the"jal"instruction 📞. Calling functions using"jal"is more efficient, but it requires the caller and callee to be in the same 256 megabyte segment 🗺️.
This option has no effect on abicalls code 🙅. The default is -mno-long-calls ✅.
-mmad,-mno-mad— enables (or disables) use of the"mad","madu"and"mul"instructions, as provided by the R4650 ISA 🧮.-mimadd,-mno-imadd— enables (or disables) use of the"madd"and"msub"integer instructions 🔢. The default is-mimaddon architectures that support"madd"and"msub", except for the 74k architecture, where it was found to generate slower code 🐌.-mfused-madd,-mno-fused-madd— enables (or disables) use of the floating-point multiply-accumulate instructions when they're available 🧮. The default is-mfused-madd✨.
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 not run its preprocessor over user assembler files (with a.ssuffix) when assembling them 🙅♀️.-mfix-24k,-mno-fix-24k— works around the 24K E48 (lost data on stores during refill) errata 🩹. The workarounds are implemented by the assembler rather than by GCC 🧩.-mfix-r4000,-mno-fix-r4000— works around certain R4000 CPU errata 🛠️. There are three of them, so buckle up:- 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-r10000 is the default when -march=r10000 is used; -mno-fix-r10000 is the default otherwise 🎯.
-mfix-r5900,-mno-fix-r5900— do not attempt to schedule the preceding instruction into the delay slot of a branch instruction placed at the end of a short loop of six instructions or fewer. Instead, always schedule a"nop"instruction there 🧘. The short loop bug under certain conditions causes loops to execute only once or twice, due to a hardware bug in the R5900 chip 😵. The workaround is implemented by the assembler rather than by GCC 🧩.-mfix-rm7000,-mno-fix-rm7000— works around the RM7000"dmult"/"dmultu"errata 🔧. The workarounds are implemented by the assembler rather than by GCC 🧩.-mfix-vr4120,-mno-fix-vr4120— works around certain VR4120 errata 🛠️:"dmultu"does not always produce the correct result."div"and"ddiv"do 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 the "mips64vr*-elf" configurations 🎯.
Other VR4120 errata require a NOP to be inserted between certain pairs of instructions 🫠. These errata are handled by the assembler, not by GCC itself 🧩.
Okay so the VR4130 has this sneaky mflo/mfhi errata 🙈
-mfix-vr4130,-mno-fix-vr4130— these work around the VR4130 "mflo"/"mfhi" errata 🩹. The fix is handled by the assembler, not GCC, but GCC steers clear ofmfloandmfhiwhen the VR4130macc,macchi,dmaccanddmacchiinstructions are available instead ✨.-mfix-sb1,-mno-fix-sb1— bestie, this one patches certain SB-1 CPU core errata 💅. Right now it only handles the SB-1 revision 2 "F1" and "F2" floating-point errata 🔥.-mfix4300,-mno-fix4300— this works around a bug in early VR4300 silicon 🐛. Multiplies with certain operands can corrupt the multiply that comes right after them 💀.
🦋 -mr10k-cache-barrier=setting 🦋
This one controls whether GCC inserts cache barriers to dodge the side effects of speculation on R10K processors 👑.
Okay, the vibe: lots of processors guess which way a conditional branch will go and speculatively run instructions from the "taken" branch 🔮. If the guess was wrong, they abort those instructions later. The R10K is extra though, because even aborted instructions can leave side effects behind 😭.
This only really messes with kernel stores and, depending on the system, kernel loads 🙈. For example, a speculatively-executed store might pull the target memory into cache and mark the line as dirty, even if the store gets aborted later. If a DMA operation writes to that same memory before the "dirty" line is flushed, the cached data overwrites the DMA-ed data 💀. The R10K processor manual has the full scoop, 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=setting controls how GCC does this. It assumes that aborted accesses to any byte in the following regions have no 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's the kernel's job to make sure speculative accesses to these regions are actually safe 🫶.
If your input program has a function declaration like this:
void foo (void);then the implementation of foo must allow j foo and jal foo to run speculatively 🧚. GCC honors this for functions it compiles itself. It expects non-GCC functions (like hand-written assembly) to do the same 💜.
The option comes in 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 GCC calls to flush the I and D caches, or tells it to skip calling any such function 🌊. If you do call one, it has to take the same arguments as the common_flush_func: the address of the memory range being flushed, the size of that range, and the number3(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 roughlynum"simple" instructions 🧮. Heads up, this is only a heuristic, so it isn't guaranteed to give 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 selected architecture defaults to 🦄. By default they may be generated if the selected architecture supports them. The exception is the MIPS32 and MIPS64 architectures, plus processors that implement those. For those, Branch Likely instructions aren't generated by default, because MIPS32 and MIPS64 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=never— makes sure compact branch instructions are never generated 🚫.-mcompact-branches=always— makes sure a compact branch instruction is generated if one is available, for MIPS Release 6 onwards 🏃♀️. If a compact branch instruction isn't available (or it's pre-R6), a delay slot form of the branch is used instead 🐢. If it's used for MIPS16/microMIPS targets, it's just ignored right now. The MIPS16/microMIPS behavior may change in the future, since those do have some compact branch instructions 👀.-mcompact-branches=optimal— uses a delay slot branch 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 when one is available ✨.
-mfp-exceptions,-mno-fp-exceptions— specifies whether FP exceptions are enabled 🧯. This affects how FP instructions get scheduled on some processors. By default, 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 on, GCC aligns pairs of instructions that it thinks should execute in parallel 💫. It only does anything when you're optimizing for the VR4130 🎯. It usually makes code faster, but at the cost of making it bigger 🐘. It's enabled by default at optimization level-O3🔥.-msynci,-mno-synci— enables or disables generation ofsynciinstructions on architectures that support them 🔄. If enabled, thesynciinstructions get generated when__builtin___clear_cacheis compiled 🛠️. This option defaults to-mno-synci, but you can override the default by configuring GCC with--with-synci⚙️. Compiling for single processor systems? It's generally safe to usesynci😌. But on many multi-core (SMP) systems, it doesn't invalidate the instruction caches on all cores, and it may lead to undefined behavior 🚨.-mrelax-pic-calls,-mno-relax-pic-calls— tries to turn PIC calls that are normally dispatched via register$25into direct calls 🎯. This only works if the linker can resolve the destination at link time, and if the destination is within range for a direct call 📏.-mrelax-pic-callsis the default if GCC was configured to use an assembler and linker that support the.relocassembly directive and-mexplicit-relocsis in effect 🧩. With-mno-explicit-relocs, this optimization can be done by the assembler and the linker alone, without help from the compiler 🤝.-mmcount-ra-address,-mno-mcount-ra-address— emits (or doesn't emit) code that lets_mcountmodify the calling function's return address 🪄. When enabled, this extends the usual_mcountinterface with a new ra-address parameter. It has typeintptr_t *and gets passed in register$12🧵._mcountcan then modify the return address by doing both of the following:- Returning the new address in register
$31. - Storing the new address in
*ra-address, if ra-address is nonnull. The default is-mno-mcount-ra-address💅.
- Returning the new address in register
-mframe-header-opt,-mno-frame-header-opt— enables (or disables) frame header optimization in the o32 ABI 🧺. With the o32 ABI, calling a function allocates 16 bytes on the stack for the called function to write out register arguments. When enabled, this optimization skips allocating the frame header if it can be determined that it's unused 🧹. Heads up, it's off by default at all optimization levels 🙅♀️.-mlxc1-sxc1,-mno-lxc1-sxc1— when applicable, enables (or disables) generation oflwxc1,swxc1,ldxc1,sdxc1instructions 🌟. Enabled by default 💖.-mmadd4,-mno-madd4— when applicable, enables (or disables) generation of 4-operandmadd.s,madd.dand related instructions 🧮. Enabled by default ✨.
🌌 MMIX Options 🌌
These options are defined for the MMIX 🧑💻:
-mlibfuncs,-mno-libfuncs— specifies that intrinsic library functions are being compiled, passing all values in registers, no matter the size 📦.-mepsilon,-mno-epsilon— generates floating-point comparison instructions that compare with respect to therEepsilon register 🎯.-mabi=mmixware,-mabi=gnu—-mabi=mmixwaregenerates code that passes function parameters and return values that (in the called function) are seen as registers$0and up 🧺.-mabi=gnuuses the GNU ABI instead, which uses global registers$231and up 🌍.-mzero-extend,-mno-zero-extend— when reading data from memory in sizes shorter than 64 bits, uses (or doesn't use) zero-extending load instructions by default, instead of sign-extending ones 🔢.-mknuthdiv,-mno-knuthdiv— makes the result of a division that yields a remainder have the same sign as the divisor 🧠. With the default,-mno-knuthdiv, the sign of the remainder follows the sign of the dividend. Both methods are arithmetically valid, though the latter is almost exclusively used 🤓.-mtoplevel-symbols,-mno-toplevel-symbols— prepends (or doesn't prepend) a:to all global symbols, so the assembly code can be used with thePREFIXassembly directive 🏷️.-melf— generates an executable in the ELF format, instead of the default mmo format used by the mmix simulator 🎁.-mbranch-predict,-mno-branch-predict— uses (or doesn't use) the probable-branch instructions when static branch prediction indicates a probable branch 🔮.-mbase-addresses,-mno-base-addresses— okay so this one decides if your code uses base addresses 💖 When it does, the assembler and linker set up a constant in a global register, and then a bunch of base address requests within 0 to 255 get measured from whatever's sitting in that register ✨ Generally that means short, fast code 🔥 BUT only a limited number of different data items can be addressed this way, so if your program uses lots of static data, you might need-mno-base-addresses🙈-msingle-exit,-mno-single-exit— this either forces or doesn't force the generated code to have one single exit point in each function 🦋-mset-data-start=address— when linking, this sets the start of the data section toaddress🎀-mset-program-start=address,-mno-set-program-start— when linking, this sets the program start address toaddress🌸 It defaults to0x100, unless you use-mno-set-program-start, which shuts this option off completely 💅
🦋 MN10300 Options 🦋
These -m options are defined for Matsushita MN10300 architectures 🌈
-mmult-bug,-mno-mult-bug— when enabled, it generates code that dodges bugs in the multiply instructions for MN10300 processors 🛡️ This one's the default, periodt ✨-mam33,-mno-am33— generates code using features specific to the AM33 processor 💜 The default is-mno-am33.-mam33-2,-mno-am33-2— generates code using features specific to the AM33/2.0 processor 🫶 The default is-mno-am33-2.-mam34,-mno-am34— generates code using features specific to the AM34 processor 🍓 The default is-mno-am34.-mtune=cpu-type— uses the timing characteristics of the CPU type you pick when scheduling instructions ⏱️ This does not change the targeted processor type, so don't panic 😭 The CPU type has to be one ofmn10300,am33,am33-2oram34.-mreturn-pointer-on-d0,-mno-return-pointer-on-d0— when generating a function that returns a pointer, this returns the pointer in both"a0"and"d0"👑 Otherwise, the pointer only comes back in"a0", and trying to call those functions without a prototype throws errors 💀 This option is on by default. To turn it off, use-mno-return-pointer-on-d0🙅♀️-mno-crt0— do 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 only has an effect when you use it on the command line for the final link step.
Heads up bestie: this option makes symbolic debugging impossible 💀
-mliw,-mno-liw— lets the compiler generate Long Instruction Word instructions if the target is AM33 or later 🌟 This is enabled by default.-mliwdefines the preprocessor macro"__LIW__", and-mno-liwdefines the preprocessor macro"__NO_LIW__"💖-msetlb,-mno-setlb— lets the compiler generate the SETLB and Lcc instructions if the target is AM33 or later 🦄 This is enabled by default.-msetlbdefines the preprocessor macro"__SETLB__", and-mno-setlbdefines 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,-mno-mul.x— generatesmul.xandumul.xinstructions 🧁 This option is enabled by default formoxiebox-*-*configurations.-mno-crt0— do 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 one's around for testsuite and/or aesthetic purposes 🎨-mmcu=name— selects the MCU you're targeting 🎯 This creates a C preprocessor symbol based on the MCU name, converted to upper case and wrapped in__on both ends. Themsp430.hheader file then uses that symbol to pick an MCU-specific supplementary header file 🫧
The 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 gets selected. The generic MCU name msp430 can also 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 tacked on the end. So -mmcu=xxx defines the C preprocessor symbol "__XXX__" and makes the linker search for a script called xxx.ld 🥰
The ISA and hardware multiply support for each MCU is hard-coded into GCC 🏗️ However, an external devices.csv file can extend device support beyond those hard-coded ones, which is lowkey amazing 🙌
GCC searches for the devices.csv file using the methods below, in 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 the include paths and linker library search paths 📂 - Path specified by the environment variable
MSP430_GCC_INCLUDE_DIR— define the global environment variableMSP430_GCC_INCLUDE_DIRas the full path to the directory containingdevices.csv, and GCC will search that directory for it 🗂️ Ifdevices.csvis found there, this directory also gets registered as an include path and linker library path. That means header files and linker scripts in this directory can be used without manually specifying-Iand-Lon the command line 🫶 - The
msp430-elf{,bare}/include/devicesdirectory — finally, GCC checksmsp430-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.csvin there, the MCU data gets read. Like before, this directory is also registered as an include path and linker library path 💖
If none of the above search methods find devices.csv, then the hard-coded MCU data gets used 🥹
-mwarn-mcu,-mno-warn-mcu— this turns warnings on or off about conflicts between the MCU name from-mmcuand the ISA set by-mcpu, and/or the hardware multiply support set by-mhwmult🚨 It also toggles warnings about unrecognized MCU names. This option is on by default ✅-msim— links to the simulator runtime libraries and linker script 🧪 This overrides any scripts that would've been picked by-mmcu=💅-mlarge— uses large-model addressing, with 20-bit pointers and a 20-bit"size_t"🐘-msmall— uses small-model addressing, with 16-bit pointers and a 16-bit"size_t"🐁-mrelax— this gets passed to the assembler and linker, and lets the linker do certain optimizations that can't happen until the final link 🧘♀️mhwmult=type— describes the type of hardware multiply the target supports 🧮 The accepted values fortypeare:nonefor no hardware multiply 🙅16bitfor the original 16-bit-only multiply supported by early MCUs 🦖32bitfor the 16/32-bit multiply supported by later MCUs 🦕f5seriesfor the 16/32-bit multiply supported by F5-series MCUs 🌟auto, which tells GCC to figure out the hardware multiply support from the MCU name you gave with-mmcu🕵️♀️
If there's no -mmcu option, or the MCU name isn't recognized, then no hardware multiply support is assumed. "auto" is the default setting 💜
Hardware multiplies are normally performed by calling a library routine, which saves space in the generated code 📦 When compiling at -O3 or higher, though, the hardware multiplier gets invoked inline. That makes the code bigger but faster 🚀
The hardware multiply routines disable interrupts while they're running and restore the previous interrupt state when they finish 🛑 This makes them safe to use inside interrupt handlers as well as in normal code 🫶
-minrt— enables a minimum runtime environment with no support for static initializers or constructors 🪶 This is meant for memory-constrained devices. The compiler puts special symbols in some objects that tell the linker and runtime which code fragments are required 🧩-mtiny-printf— enables reduced code size"printf"and"puts"library functions 🐣
These tiny implementations are not reentrant, so be careful using them in multi-threaded applications 😬
Support for streams has been removed, and the string to be printed is always sent to stdout via the "write" syscall 📨 The string isn't buffered before it's sent to write.
This option requires Newlib Nano IO, so GCC must be configured with --enable-newlib-nano-formatted-io ⚙️
-mmax-inline-shift=n— this takes an integernbetween 0 and 64 inclusive, and sets the maximum number of inline shift instructions that can be emitted to perform a shift by a constant amount 🌀 When that limit needs to be exceeded, anmspabihelper function is used instead. The default value is 4 🍰
This only affects cases where a shift by multiple positions can't be finished with a single 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 for this option gets divided by 2, and that resulting value is used instead 🧮
-mcode-region=where,-mdata-region=where— these tell the compiler where to place functions and data that don't have one of the"lower","upper","either"or"section"attributes 🗺️ The possible values forwherearelower,upper,eitherorany. The first three behave like the corresponding attribute. The fourth value,any, is the default, and it leaves placement entirely up to the linker script and how it assigns the standard sections (".text",".data", etc.) to the memory regions 🌈-muse-lower-region-prefix— adds the.lowerprefix to section names when compiling with-mcode-region=loweror-mdata-region=lower🎀 This is disabled by default.-msilicon-errata=name[,name...]: okay bestie, this one passes your request along to the assembler so it turns on the fixes for the silicon errata you name 🔧✨ For the full scoop, check the assembler docs.-msilicon-errata-warn=name[,name...]: same vibe, but instead of fixing things, the assembler just warns you when a named silicon errata might need a fix 👀 Again, the assembler docs have the details.-mwarn-devices-csv,-mno-warn-devices-csv: this one warns you ifdevices.csvis missing or if there are problems parsing it. It's on by default 💅
✨ NDS32 Options ✨
These options are defined for NDS32 implementations 🌸
-mbig-endian,-EB: generates code in big-endian mode 🦋-mlittle-endian,-EL: generates code in little-endian mode 🫶-mabi=2,-mfloat-abi=soft: uses the soft floating-point ABI 🍓-mabi=2fp+,-mfloat-abi=hard: uses the hard floating-point ABI 🔥-mreduced-regs: uses the reduced-set registers for register allocation 🎀-mfull-regs: uses the full-set registers for register allocation 👑-malways-align: always aligns function entry, jump targets, and return address. Main character alignment energy 🧚-malign-functions: aligns function entry to 4 bytes 📏-mfp-as-gp,-mno-fp-as-gp: enables or disables the fp-as-gp optimization 💜-mcmov,-mno-cmov: enables or disables generation of conditional move instructions ✨-mhw-abs,-mno-hw-abs: enables or disables generation of hardware abs instructions 🌈-mext-perf,-mno-ext-perf: enables or disables generation of performance extension instructions ⭐-mext-perf2,-mno-ext-perf2: enables or disables generation of performance extension 2 instructions 💖-mext-string,-mno-ext-string: enables or disables generation of string extension instructions 🫶-mext-dsp,-mno-ext-dsp: enables or disables generation of DSP extension instructions 🦋-mext-fpu-fma,-mno-ext-fpu-fma: enables or disables generation of floating-point multiply-accumulation instructions 🔥-mext-fpu-sp,-mno-ext-fpu-sp: enables or disables generation of single-precision floating-point instructions 🌸-mext-fpu-dp,-mno-ext-fpu-dp: enables or disables generation of double-precision floating-point instructions 👑-mv3push,-mno-v3push: enables or disables generation of v3push25/pop25instructions 🍓-m16-bit,-mno-16-bit: enables or disables generation of 16-bit instructions 💅-mvh,-mno-vh: enables or disables Virtual Hosting support 🎀-misr-vector-size=num: specifies the size of each interrupt vector, which must be4or16🧚-misr-secure=num: specifies the security level of c-isr for the whole file 🔐-mcache-block-size=num: specifies the size of each cache block, which must be a power of 2 between 4 and 512 💜-march=arch: specifies the target architecture.archmay be one ofv2,v3,v3j,v3m,v3f, orv3s✨-mcpu=cpu: specifies the CPU to compile for.cpumay be one ofn6,n650,n7,n705,n8,n801,sn8,sn801,s8,s801,e8,e801,n820,s830,e830,n9,n903,n903a,n968,n968a,n10,n1033,n1033a,n1033-fpu,n1033-spu,n1068,n1068a,n1068-fpu,n1068a-fpu,d10,d1088,d1088-fpu,d1088-spu,n15,d15,n15s,d15s,n15f,d15f,n12,n1213,n1233,n1233-fpu,n1233-spu,n13,n1337,n1337-fpu,n1337-spu, orsimple🌈-mconfig-fpu=num: specifies an FPU configuration value from0to7.0--3is as the FPU spec says, and4--7correspond to0--3🫶-mconfig-mul=type: specifies the configuration for the multiply instruction.typecan be one offast,fast1(equivalent tofast),fast2, orslow. The default isfast1🦋-mconfig-register-ports=kind: specifies the numbers of read/write ports for n9/n10 cores. The value should be3r2wor2r1w🍓-mcmodel=code-model: sets the code model to one of the following 🌸small: all the data and read-only data segments must be within 512KB addressing space. The text segment must be within 16MB addressing space.medium: the data segment must be within 512KB while the read-only data segment can be within 4GB addressing space. The text segment should be still within 16MB addressing space.large: all the text and data segments can be within 4GB addressing space.
The default is large on GNU/Linux targets and medium on other ELF targets 💖
-mctor-dtor,-mno-ctor-dtor: enables or disables the constructor/destructor feature 🧚-mrelax,-mno-relax: enables or disables the linker option to relax instructions 💅-mrelax-hint,-mno-relax-hint: enables or disables insertion of hints for the linker to do relaxation 🎀-msched-prolog-epilog,-mno-sched-prolog-epilog: enables or disables scheduling of a function's prologue and epilogue sequence 👑-mret-in-naked-func,-mno-ret-in-naked-func: enables or disables generation of return instructions in naked functions. This option is enabled by default 🌈-malways-save-lp,-mno-always-save-lp: enables or disables always saving$lpon the stack 💜-munaligned-access,-mno-unaligned-access: enables or disables unaligned word and halfword accesses to packed data 🍓-minline-asm-r15,-mno-inline-asm-r15: allows or disallows use ofr15for inline asm 🫶
✨ Nvidia PTX Options ✨
These options are defined for Nvidia PTX 💅
-m64: ignored, but preserved for backward compatibility. Only the 64-bit ABI is supported 🔥-march=architecture-string: generates code for the specified PTX ISA target architecture. Valid architecture strings aresm_30,sm_35,sm_37,sm_52,sm_53,sm_61,sm_70,sm_75,sm_80, andsm_89. The default depends on how the compiler has been configured, see--with-arch✨
This option sets the value of the preprocessor macro "__PTX_SM__". For instance, for sm_35, it has the value 350 🧚
-misa=architecture-string: an alias of-march=🌸-march-map=architecture-string: selects the closest available-march=value that is not more capable. For instance, for-march-map=sm_50it selects-march=sm_37, and for-march-map=sm_53it selects-march=sm_53🗺️-mptx=version-string: generates code for the specified PTX ISA version. Valid version strings are3.1,4.1,4.2,5.0,6.0,6.3,7.0,7.3, and7.8. The default PTX ISA version is the one that added support for the selected PTX ISA target architecture, see-march=, but at least6.3, or7.3for-march=sm_52and higher 💖
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 instead of offloading execution 🫶-moptimize,-mno-optimize: enables or disables partitioned execution optimizations. This option is enabled by default when any level of optimization is selected 🌈-msoft-stack,-mno-soft-stack: 🍓
For -mno-soft-stack (the default, unless -mgomp has been specified), use PTX "native" stacks, that is, generate code that uses ".local" memory or PTX "alloca" directly for stack storage. Unless -mptx=7.3 or higher and -march=sm_52 or higher are active, variable-length arrays and dynamically allocating memory on the stack with "alloca" are not supported.
For -msoft-stack (implied by -mgomp), generate code that does not use ".local" memory or PTX "alloca" directly for stack storage. Instead, a per-warp stack pointer is maintained explicitly. This enables variable-length stack allocation (with variable-length arrays or "alloca"), and when global memory is used for underlying storage, makes it possible to access automatic variables from other threads, or with atomic instructions. This code generation variant is used for OpenMP offloading, but the option is exposed on its own for the purpose of testing the compiler. To generate code suitable for linking into programs using OpenMP offloading, use option -mgomp 🧚
-msoft-stack-reserve-local=size: specifies the size of".local"memory used for the stack when the exact amount is not known. It defaults to128💜-muniform-simt,-mno-uniform-simt: enables or disables a code generation variant that allows execution of all threads in each warp, while maintaining memory state and side effects as if only one thread in each warp was active outside of OpenMP SIMD regions. All atomic operations and calls to runtime ("malloc","free","vprintf") are conditionally executed (iff 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. Shared memory array"int __nvptx_uni[]"stores all-zeros or all-ones bitmasks for each warp, indicating current mode (0 outside of SIMD regions). Each thread can bitwise-and the bitmask at position"tid.y"with current lane index to compute the master lane index 👑-mgomp,-mno-gomp: enables or disables generation of code for use in OpenMP offloading.-mgompenables-msoft-stackand-muniform-simtoptions, and selects a corresponding multilib variant 🌸
✨ OpenRISC Options ✨
These options are defined for OpenRISC 🌈
-mboard=name: configures a board specific runtime. This is passed to the linker for newlib board library linking. The default is"or1ksim"🦋-msoft-div,-mhard-div: selects software or hardware divide ("l.div","l.divu") instructions. The default is hardware divide 🍓-msoft-mul,-mhard-mul: selects software or hardware multiply ("l.mul","l.muli") instructions. The default is hardware multiply 💖-msoft-float,-mhard-float: selects software or hardware for floating point operations. The default is software 🫶-mdouble-float: when-mhard-floatis selected, enables generation of double-precision floating point instructions. By default, functions from libgcc are used to perform double-precision floating point operations 🔥-munordered-float: when-mhard-floatis selected, enables generation of unordered floating point compare and set flag ("lf.sfun*") instructions. By default, functions from libgcc are used to perform unordered floating point compare and set flag operations 💅-mcmov— okay so this turns on conditional move (l.cmov) instructions 💅. Without it, GCC builds the same effect with set and branch instead.-mror— enablesl.rorrotate-right instructions ✨. By default, rotate-right operations go through functions from libgcc.-mrori— enablesl.rorirotate-right-with-immediate instructions 🦋. By default, these also go through libgcc functions.-msext— enablesl.ext*sign extension instructions 🌈. By default, sign extension is handled with memory loads.-msfimm— enablesl.sf*icompare-and-set-flag-with-immediate instructions 🔥. By default, GCC adds extra instructions to store the immediate in a register first.-mshftimm— enablesl.srai,l.srli, andl.sllishift-with-immediate instructions 💜. By default, extra instructions store the immediate in a register first.-mcmodel=small— generates OpenRISC code for the small model 🌸. The GOT is limited to 64k, and function call jumps are limited to 64M offsets. This is the default model.-mcmodel=large— generates OpenRISC code for the large model 👑. The GOT can grow up to 4G in size, and function call jumps can target the full 4G address space.
🌸 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— skips hardware floating point 🙈.-mac0,-mno-ac0— with-mac0, floating-point results come back inac0(fr0in Unix assembler syntax) 💅. The default,-mno-ac0, returns floating-point results in memory.-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 a 16-bitint💖. This is the default.-mint32,-mno-int16— uses a 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 the PRU target 💅:
-minrt— links with a minimum runtime environment 🦋. This can seriously shrink the final ELF binary, but some standard C runtime features get removed.
This option disables support for static initializers and constructors. Beware, because the compiler could still generate code with static initializers and constructors. It's up to the programmer to make sure the source program doesn't use those features.
The minimal startup code does not pass argc and argv arguments to main, so main has to be declared as int main (void). This is already the norm for most firmware projects ✨.
-mmcu=mcu— picks the PRU hardware variant to use 🔥. A correspondingly named spec file gets loaded, which passes the memory region sizes to the linker and defines hardware-specific C macros.
Newlib only provides the sim spec, which is meant for running regression tests with a simulator 🙈. Specs for real hardware can be obtained by installing the GnuPruMcu package at https://github.com/dinuxbg/gnuprumcu/ 🫶.
-mno-relax— makes GCC pass--no-relaxto the linker instead of--relax💀.-mloop,-mno-loop— allows (or doesn't allow) GCC to use theLOOPinstruction 🍓.-mmul,-mno-mul— allows (or doesn't allow) GCC to use the PRU multiplier unit 💖.-mfillzero,-mno-fillzero— allows (or doesn't allow) GCC to use theFILLandZEROinstructions 🌸.-mabi=variant— picks 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. Here's how they differ:- Function Pointer Size — TI ABI says function (code) pointers are 16-bit, whereas GNU only supports 32-bit data and code pointers 🎀.
- Optional Return Value Pointer — return values larger than 64 bits get passed through a hidden pointer as the first argument of the function 🦋. TI ABI mandates that this pointer can be
NULLif the caller isn't using the returned value. GNU always passes and expects a valid return value pointer 💅. - Size Of Struct Containing Bit-fields — TI ABI says the struct size is determined by the bit-field type, if it has any 🧚. GNU allocates the smallest number of bytes that would fit the bit-field ✨.
For example, TI ABI reserves 4 bytes for this struct, whereas GNU reserves a single byte 🙈:
struct S { int i:1; };- Access Size For Volatile Bit-fields — TI ABI mandates that volatile bit-fields are accessed using their type 🔥. GNU ABI instead uses the smallest integer type that fits the bit-field 💜.
For example, TI ABI requires a single load of 4 bytes for the following bit-field. GNU generates a load of 1 byte 💀:
struct S { volatile int i:1; };The current -mabi=ti implementation just raises a compile error whenever any of the above code constructs shows up 😭. As a result, the standard C library can't be built, so it's omitted when linking with -mabi=ti.
Relaxation is a GNU feature, and for safety reasons it's disabled when using -mabi=ti. The TI toolchain doesn't emit relocations for QBBx instructions, so the GNU linker can't adjust them when it shortens 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 💅.-mabi=ABI-string— picks the integer and floating-point calling convention ✨. An ABI string has two parts: the size of integer types, and the registers used for floating-point types 🧚. For example,-march=rv64ifd -mabi=lp64dmeanslongand pointers are 64-bit (which implicitly makesint32-bit), and floating-point values up to 64 bits wide are passed in F registers 🔥. Compare that 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 if you want a specific calling convention, you should specify one explicitly 🫶. The valid calling conventions are ilp32, ilp32f, ilp32d, lp64, lp64f, and lp64d 💖. Some calling conventions are impossible 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 🎀.
Theilp32eandlp64eABIs aren't well-specified at present, and they're subject to change.
-mfdiv,-mno-fdiv— does (or doesn'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 🔥.-mfence-tso,-mno-fence-tso— does (or doesn't) use thefence.tsoinstruction 💅. It's unimplemented on some processors, including those from T-Head 🙈. If thefence.tsoinstruction isn't available, a stronger fence is used instead 🫶.-mdiv,-mno-div— does (or doesn'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— picks the version of the RISC-V Unprivileged (formerly User-Level) ISA specification that generated code should conform to 🧚. The possible values forISA-spec-stringare:2.2— produces code conforming to version 2.2 💖.20190608— produces code conforming to version 20190608 💜.20191213— produces 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|Profile|Profile_ISA|processor-string]— generates code for a given RISC-V ISA, profile, or a combination of them (for example,rv64im,rvi20u64, orrvi20u64_zbb) 👑. ISA and profile names must be lower case. Examples includerv64i,rv32g,rv32e,rv32imaf,rva22u64, andrva23u64💅. To combine a named profile with optional RISC-V ISA extensions, put the profile first and then append the extension name(s) with an underscore as the delimiter (for example,rvi20u64_zca_zcborrva23u64_zacas) ✨. There's also a special value,help(-march=help), which lists all supported extensions 🔥.
-march=unset makes the compiler ignore any -march=... options that appear earlier on the command line, behaving as if that option was never passed 🦋. This is handy for making sure the architecture comes from the -mcpu option. An error results if no -mcpu option is given when -march=unset is used 💀.
The syntax of the ISA string is defined as follows:
- The string must start with
rv32orrv64, followed byi,e, org. These are called the base ISA 🧚. - The rest of the string is a list of extension names. Extension names can be multi-letter (for example,
zba) or single-letter (for example,v). Single-letter extensions can appear back to back, but multi-letter extensions must be separated by underscores 🌈. - An underscore can appear anywhere after the base ISA. It has no specific effect, but it's used to improve readability and can act as a separator 🫶.
okay so extension names can carry a version too 💅 the syntax is <major>p<minor> or just <major>, so m2p1 or m2 both work 🦋 here's the full lineup, with the version(s) each one supports and what it's about. quick heads up: a version of - just means there isn't one listed 🫶
g(version-) — the general-purpose computing base extension ✨gis shorthand that expands toi,m,a,f,d,zicsrandzifencei, so you get all of them in one go 👑e(version 2.0) — the reduced base integer extension 🌸i(versions 2.0 and 2.1) — the base integer extension 💖m(version 2.0) — integer multiplication and division, obsessed 🔥a(versions 2.0 and 2.1) — the atomic extension 💜f(versions 2.0 and 2.2) — single-precision floating-point 🦋d(versions 2.0 and 2.2) — double-precision floating-point, iconic 🌈c(version 2.0) — the compressed extension 🧚b(version 1.0) — the standard extension for bit manipulation functions 🍓v(version 1.0) — the vector extension ✨h(version 1.0) — the hypervisor extension 👑zic64b(version 1.0) — cache block size is 64 bytes 🎀zicbom(version 1.0) — cache-block management, main character energy 💅zicbop(version 1.0) — cache-block prefetch 🌸zicboz(version 1.0) — cache-block zero 🦋ziccamoa(version 1.0) — main memory supports all atomics inA💜ziccif(version 1.0) — main memory supports instruction fetch with an atomicity requirement 🫶zicclsm(version 1.0) — main memory supports misaligned loads and stores 🌈ziccrse(version 1.0) — main memory supports forward progress onLR/SCsequences ✨zicfilp(version 1.0) — control-flow integrity landing pad extension 🔥zicfiss(version 1.0) — control-flow integrity shadow stack extension 👑zicntr(version 2.0) — the standard extension for base counters and timers ⭐zicond(version 1.0) — integer conditional operations 🧚zicsr(version 2.0) — control and status register access, slay 💅zifencei(version 2.0) — instruction-fetch fence 🍓zihintntl(version 1.0) — non-temporal locality hints 🌸zihintpause(version 2.0) — pause hint 🦋zihpm(version 2.0) — the standard extension for hardware performance counters 💖zimop(version 1.0) — may-be-operations 🌈zilsd(version 1.0) — load/store pair instructions ✨zmmul(version 1.0) — integer multiplication 💜za128rs(version 1.0) — reservation set size of 128 bytes 🎀za64rs(version 1.0) — reservation set size of 64 bytes 🎀zaamo(version 1.0) — atomic memory operations 🔥zabha(version 1.0) — byte and halfword atomic memory operations 💅zacas(version 1.0) — atomic compare-and-swap instructions 👑zalrsc(version 1.0) — the load-reserved/store-conditional subset of theAextension 🫶zawrs(version 1.0) — wait-on-reservation-set 🧚zama16b(version 1.0) — misaligned loads, stores, and AMOs that are fully contained within a naturally-aligned 16-byte boundary are atomic 🌸zfa(version 1.0) — additional floating-point 🦋zfbfmin(version 1.0) — minimal BF16 support 💖zfh(version 1.0) — half-precision floating-point 🌈zfhmin(version 1.0) — minimal half-precision floating-point ✨zfinx(version 1.0) — single-precision floating-point in integer registers 💜zdinx(version 1.0) — double-precision floating-point in integer registers 🔥zca(version 1.0) — integer compressed instructions 🧚zcb(version 1.0) — simple compressed instructions 🍓zcd(version 1.0) — compressed double-precision floating-point loads and stores 🌸zce(version 1.0) — compressed instruction extensions for embedded processors 🎀zcf(version 1.0) — compressed single-precision floating-point loads and stores 🦋zcmop(version 1.0) — compressed may-be-operations 🌈zcmp(version 1.0) — compressed push and pop 💅zcmt(version 1.0) — table jump instructions 👑zclsd(version 1.0) — compressed load/store pair instructions 🫶zba(version 1.0) — address calculation 💖zbb(version 1.0) — basic bit manipulation 🔥zbc(version 1.0) — carry-less multiplication ✨zbkb(version 1.0) — cryptography bit-manipulation 💜zbkc(version 1.0) — cryptography carry-less multiply 🌈zbkx(version 1.0) — cryptography crossbar permutation 🧚zbs(version 1.0) — single-bit operations 🍓zk(version 1.0) — the standard scalar cryptography extension 🔐✨zkn(version 1.0) — the NIST algorithm suite extension 🌸zknd(version 1.0) — AES decryption 🦋zkne(version 1.0) — AES encryption 💖zknh(version 1.0) — hash functions 🌈zkr(version 1.0) — entropy source ✨zks(version 1.0) — the ShangMi algorithm suite extension 💜zksed(version 1.0) — SM4 block cipher 🔥zksh(version 1.0) — SM3 hash function 🧚zkt(version 1.0) — data independent execution latency 🍓ztso(version 1.0) — total store ordering 👑zvbb(version 1.0) — vector basic bit-manipulation 🫶zvbc(version 1.0) — vector carry-less multiplication 🌸zve32f(version 1.0) — vector extensions for embedded processors 🎀zve32x(version 1.0) — vector extensions for embedded processors 🎀zve64d(version 1.0) — vector extensions for embedded processors 🦋zve64f(version 1.0) — vector extensions for embedded processors 🦋zve64x(version 1.0) — vector extensions for embedded processors 🌈zvfbfmin(version 1.0) — vector BF16 converts 💅zvfbfwma(version 1.0) — vector BF16 widening multiply/add 👑zvfh(version 1.0) — vector half-precision floating-point 💖zvfhmin(version 1.0) — vector minimal half-precision floating-point 🔥zvkb(version 1.0) — vector cryptography bit-manipulation ✨zvkg(version 1.0) — vector GCM/GMAC 💜zvkn(version 1.0) — vector NIST Algorithm Suite, wherezvknwill expand to (the page just trails off right there 💀)zvknc(version 1.0) — vector NIST Algorithm Suite with carry-less multiply,zvknc🧚zvkned(version 1.0) — vector AES block cipher 🍓zvkng(version 1.0) — vector NIST Algorithm Suite with GCM, wherezvkngwill expand (again, cut off here 🙈)zvknha(version 1.0) — vector SHA-2 secure hash 🌸zvknhb(version 1.0) — vector SHA-2 secure hash 🦋zvks(version 1.0) — vector ShangMi algorithm suite, wherezvkswill expand (cut off 🙈)zvksc(version 1.0) — vector ShangMi algorithm suite with carry-less multiplication, and the page stops right after the comma 🙈zvksed(version 1.0) — vector SM4 block cipher 💖zvksg(version 1.0) — vector ShangMi algorithm suite with GCM 🌈zvksh(version 1.0) — vector SM3 secure hash ✨zvkt(version 1.0) — vector data independent execution latency 💜zvl1024b(version 1.0) — minimum vector length standard extensions 🔥zvl128b(version 1.0) — minimum vector length standard extensions 🧚zvl16384b(version 1.0) — minimum vector length standard extension 🍓zvl2048b(version 1.0) — minimum vector length standard extensions 👑zvl256b(version 1.0) — minimum vector length standard extensions 🫶zvl32768b(version 1.0) — minimum vector length standard extension 🌸zvl32b(version 1.0) — minimum vector length standard extensions 🎀zvl4096b(version 1.0) — minimum vector length standard extensions 🦋zvl512b(version 1.0) — minimum vector length standard extensions 🌈zvl64b(version 1.0) — minimum vector length standard extensions 💅zvl65536b(version 1.0) — minimum vector length standard extension 👑zvl8192b(version 1.0) — minimum vector length standard extension 💖zhinx(version 1.0) — half-precision floating-point in integer registers 🔥zhinxmin(version 1.0) — minimal half-precision floating-point in integer registers ✨sdtrig(version 1.0) — debug triggers 💜sha(version 1.0) — the augmented hypervisor extension 🌈shcounterenw(version 1.0) — writeable enables for any supported counter 🧚shgatpa(version 1.0) —SvNNx4mode supported for all modes thatsatpsupports 🍓shlcofideleg(version 1.0) — delegating LCOFI interrupts to VS-mode 👑shtvala(version 1.0) — thehtvalregister provides all the values needed 🫶shvstvala(version 1.0) — thevstvalregister provides all the values needed 🌸shvstvecd(version 1.0) — thevstvecregister supports direct mode 🎀shvsatpa(version 1.0) — thevsatpregister supports all modes thatsatpsupports 🦋smaia(version 1.0) — advanced interrupt architecture 🌈smcntrpmf(version 1.0) — cycle and instret privilege mode filtering 💅smcsrind(version 1.0) — machine-level indirect CSR access 👑smepmp(version 1.0) — PMP enhancements for memory access and execution prevention in machine mode 💖smmpm(version 1.0) — supervisor-mode pointer masking 🔥smnpm(version 1.0) — supervisor-mode pointer masking, same vibe assmmpm✨smrnmi(version 1.0) — resumable non-maskable interrupts 💜smstateen(version 1.0) — state enable 🌈smdbltrp(version 1.0) — double trap extensions 🧚ssaia(version 1.0) — advanced interrupt architecture for supervisor mode 🍓
Okay so the extension list keeps going, bestie 🫶 and every single one of these is giving main character energy ✨
ssccptr(v1.0) — main memory supports page table reads 💖sscofpmf(v1.0) — count overflow and filtering extension 🦋sscounterenw(v1.0) — writeable enables for any supported counter, iconic 🌸sscsrind(v1.0) — supervisor-mode indirect CSR accessssnpm(v1.0) — supervisor-mode pointer masking extensionsspm(v1.0) — same vibe asssnpm, supervisor-mode pointer masking extension 🙈ssstateen(v1.0) — supervisor-mode state-enable extensionsstc(v1.0) — supervisor-mode timer interrupts extension ⏰sstvala(v1.0) — stval provides all the values you need ✨sstvecd(v1.0) — stvec supports direct mode 💅ssstrict(v1.0) — unimplemented reserved encodings raise illegal instruction exceptions, and no non-conforming extensions are present 💀ssdbltrp(v1.0) — double trap extensionsssu64xl(v1.0) —UXLEN=64must be supportedsupm(v1.0) — user-mode pointer masking extensionsvinval(v1.0) — fine-grained address-translation cache invalidation extensionsvnapot(v1.0) — NAPOT translation contiguity extension 🌈svpbmt(v1.0) — page-based memory types extensionsvvptc(v1.0) — extension that makes memory-management instructions unnecessary after you mark PTEs valid 🧚svadu(v1.0) — hardware updating of A/D bits extensionsvade(v1.0) — cause exception when hardware updating of A/D bits is disabledsvbare(v1.0) — satp mode bare is supportedxcvalu(v1.0) — Core-V miscellaneous ALU extensionxcvbi(v1.0) — Core-V immediate branch extensionxcvelw(v1.0) — Core-V event load word extensionxcvmac(v1.0) — Core-V multiply-accumulate extensionxcvsimd(v1.0) — Core-V SIMD extensionxsfcease(v1.0) — SiFive CEASE instruction extensionxsfvcp(v1.0) — SiFive VCIX vector coprocessor extensionxsfvfnrclipxfqf(v1.0) — SiFive FP32-to-int8 ranged clip instructionsxsfvqmaccdod(v1.0) — SiFive int8 matrix multiplication extensionxsfvqmaccqoq(v1.0) — SiFive int8 matrix multiplication extension 🔥xtheadba(v1.0) — T-head address calculation extensionxtheadbb(v1.0) — T-head basic bit-manipulation extensionxtheadbs(v1.0) — T-head single-bit instructions extensionxtheadcmo(v1.0) — T-head cache management operations extensionxtheadcondmov(v1.0) — T-head conditional move extensionxtheadfmemidx(v1.0) — T-head indexed memory operations for floating-point registers extensionxtheadfmv(v1.0) — T-head double floating-point high-bit data transmission extensionxtheadint(v1.0) — T-head acceleration interruption extensionxtheadmac(v1.0) — T-head multiply-accumulate extensionxtheadmemidx(v1.0) — T-head indexed memory operation extensionxtheadmempair(v1.0) — T-head two-GPR memory operation extensionxtheadsync(v1.0) — T-head multi-core synchronization extensionxtheadvector(v1.0) — T-head vector extensionxventanacondops(v1.0) — Ventana integer conditional operations extensionxmipscmov(v1.0) — Mips conditional move extensionxmipscbop(v1.0) — Mips prefetch extensionxandesperf(v5.0) — Andes performance extension 🚀xandesbfhcvt(v5.0) — Andes bfloat16 conversion extensionxandesvbfhcvt(v5.0) — Andes vector bfloat16 conversion extensionxandesvsintload(v5.0) — Andes vector INT4 load extensionxandesvpackfph(v5.0) — Andes vector packed FP16 extensionxandesvdot(v5.0) — Andes vector dot product extensionxsmtvdot(v1.0) — SpacemiT vector dot product extension 🎀
When -march= is not specified, GCC uses the setting from -mcpu.
If both -march and -mcpu= are not specified, the default for this argument is system dependent. So if you want a specific architecture extension, you should specify one explicitly, no excuses 💅
When the RISC-V specifications define an extension as depending on other extensions, GCC implicitly adds the dependent extensions to the enabled extension set if they weren't added explicitly. It's like the extensions come as a package deal 🫶
🎀 Core Name
-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-p450, sifive-p670, thead-c906, xt-c908, xt-c908v, xt-c910, xt-c910v2, xt-c920, xt-c920v2, tt-ascalon-d8, xiangshan-nanhu, xiangshan-kunminghu, mips-p8700, andes-n22, andes-n25, andes-a25, andes-nx25, andes-ax25, andes-a27, andes-ax27, andes-n225, andes-d23, andes-n45, andes-nx45, andes-a45, andes-ax45, spacemit-x60.
Note that -mcpu does not override -march or -mtune. Don't expect it to 🙅♀️
🎀 Tune Name
-mtune=processor-string— optimize the output for the given processor, specified by microarchitecture or a particular CPU name. Permissible values for this option are:
generic, rocket, sifive-3-series, sifive-5-series, sifive-7-series, sifive-p400-series, sifive-p600-series, tt-ascalon-d8, thead-c906, xt-c908, xt-c908v, xt-c910, xt-c910v2, xt-c920, xt-c920v2, xiangshan-nanhu, xiangshan-kunminghu, spacemit-x60, generic-ooo, size, mips-p8700, andes-25-series, andes-23-series, andes-45-series, and all valid options for -mcpu=.
When -mtune= is not specified, GCC uses the setting from -mcpu. The default is generic if neither is specified.
The size choice is not intended for use by end-users, bestie. It's used when -Os is 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— attempt to keep the stack boundary aligned to a 2 raised to num byte boundary. If-mpreferred-stack-boundaryis not specified, the default is4(16 bytes or 128-bits).
⚠️ Warning: if you use this switch, you must build all modules with the same value, including any libraries. That means the system libraries and startup modules too. Don't skip this one, it's serious 💀
-msmall-data-limit=n— put global and static data smaller than n bytes into a special section (on some targets) 📦-msave-restore,-mno-save-restore— do or don't use smaller but slower prologue and epilogue code that uses library function calls. The default is to use fast inline prologues and epilogues ⚡-mmovcc,-mno-movcc— do or don't produce branchless conditional-move code sequences, even on targets that don't have specific instructions for conditional operations. If enabled, sequences of ALU operations are produced using base integer ISA instructions where profitable 🧠-minline-atomics,-mno-inline-atomics— do or don't use smaller but slower subword atomic emulation code that useslibatomicfunction calls. The default is to use fast inline subword atomics that don't requirelibatomic🔥-minline-strlen,-mno-inline-strlen— do or do not attempt to inlinestrlencalls if possible. Inlining can only be done if the string is properly aligned and instructions for accelerated processing are available. The default is to inlinestrlencalls ✨-minline-strcmp,-mno-inline-strcmp— do or do not attempt to inlinestrcmpcalls if possible. Inlining can only be done if the strings are properly aligned and instructions for accelerated processing are available. The default is to inlinestrcmpcalls 💅-minline-strncmp,-mno-inline-strncmp— do or do not attempt to inlinestrncmpcalls if possible. Inlining can only be done if the strings are properly aligned and instructions for accelerated processing are available. The default is to inlinestrncmpcalls 🦋-mstringop-strategy=strategy— pick a specific strategy for inlining string and memory operations. strategy may be one ofauto,libcall,scalar, orvector🌸-mshorten-memrefs,-mno-shorten-memrefs— do or do not try to make more use of compressed load/store instructions, by replacing a load/store of 'base register + large offset' with a new load/store of 'new base + small offset'. If the new base gets stored in a compressed register, then the new load/store can be compressed. Currently this only targets 32-bit integer load/stores 🧚-mstrict-align,-mno-strict-align— this one is a lot: it controls whether unaligned memory accesses get generated or not. The default depends on whether the processor you're optimizing for supports fast unaligned access or not 💀-mscalar-strict-align,-mno-scalar-strict-align— same deal as the one above, it controls unaligned memory accesses, with the default depending on fast unaligned access support. This is an alias for-mstrict-align🫶
-mvector-strict-align, -mno-vector-strict-align 🎀 — bestie, these decide whether GCC is allowed to generate unaligned vector memory accesses 🫶 Default is off, unless the processor you're optimizing for explicitly supports element-misaligned vector memory access ✨
-menable-vectorization-override— no wait, scratch that. Here's the real one:-mmax-vectorization,-mno-max-vectorization💅 — this turns an override on or off for the vectorizer's cost model, so vectorization always looks profitable 🔥 Unlike-fno-vect-cost-modelor-fvect-cost-model=unlimited, this one does not turn off the cost comparison between different vector modes 🧠-mcmodel=medlow🌸 — generates code for the medium-low code model. The program and its statically defined symbols have to live inside one 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, unless GCC was configured with--with-cmodel=pointing at a different default 🧚-mcmodel=medany🦋 — generates code for the medium-any code model. The program and its statically defined symbols just need to fit in any single 2 GiB address range. Programs can be statically or dynamically linked ✨
The medium-any code model produces position-independent code, but it is not guaranteed to function correctly when linked into position-independent executables or libraries 💀
-mcmodel=large👑 — generates code for a large code model with no restrictions on the size or placement of symbols 🌈-mexplicit-relocs,-mno-explicit-relocs🧚 — use or skip assembler relocation operators when dealing with symbolic addresses. The other route is assembler macros, which may limit optimization 🥺-mrelax,-mno-relax⭐ — takes advantage of linker relaxations to cut down the number of instructions needed to materialize symbol addresses. The default is to take advantage of them 💖-mriscv-attribute,-mno-riscv-attribute🍓 — emits (or doesn't emit) a RISC-V attribute that records extra info into ELF objects. This feature needs at leastbinutils 2.32🫶-mcsr-check,-mno-csr-check🔥 — enables or disables CSR checking. Simple as that 💅-momit-leaf-frame-pointer🦋 — don't keep 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 🌸-malign-data=type🎀 — controls how GCC aligns variables and constants of array, structure, or union types. The supported values fortypearexlen, 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. Heads up, though: support for RISC-V big-endian is experimental 🙈
The ABI isn't stable yet, so it could change in incompatible ways in future releases ⚠️
-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 atguard. The supported locations areglobal(a global canary) ortls(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 the base register for reading the canary, and what offset from that base register it lives at 🎯 There is 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 👑-mrvv-vector-bits=value🦋 — specifies how the number of bits for an RVV vector register (taken from the-march=option) gets interpreted.valueis a string keyword that can bescalableorzvl. The default isscalable, which tells GCC to treat the number as a minimum, whilezvltells GCC to use exactly the number of bits you specified 🔥-mrvv-max-lmul=value💅 — gives you explicit control over the maximum length multiplier (LMUL) used when generating code for the RISC-V Vector Extensions (RVV).valueis a string keyword that can bem1,m2,m4,m8, ordynamic. The default ism1, for compatibility with existing hardware that doesn't support the other options 🫶-madjust-lmul-cost,-mno-adjust-lmul-cost🧠 — adjusts the cost model used to schedule vector instructions so the latency of instructions gets multiplied by the RVV length multiplier, LMUL. It's disabled by default 🙈-mautovec-segment,-mno-autovec-segment🌈 — enables or disables generation of vector segment load/store instructions. This option is enabled by 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🔥 — specifies the type of hardware multiplication and division support to use. The simplest one is"none", which uses software for both multiplication and division, and it's the default 💖"g13"is for the hardware multiply/divide peripheral found on the RL78/G13 (S2 core) targets 🌸"g14"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"🦋
In addition, a C preprocessor macro gets defined based on this option's setting. The possible values are "__RL78_MUL_NONE__", "__RL78_MUL_G13__", or "__RL78_MUL_G14__" 🧠
-mcpu=g10,-mcpu=g13,-mcpu=g14,-mcpu=rl78👑 — specifies the RL78 core to target. The default is the G14 core, also known as an S3 core or just RL78 ✨ The G13 (or S2) core doesn't have multiply or divide instructions, and 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 this option is set, 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 off hardware multiplications altogether 💅
Note, though: even though the RL78/G14 core is the default target, specifying -mcpu=g14 or -mcpu=rl78 on the command line does change the toolchain's behavior, because it also enables G14 hardware multiply support 👀 If these options aren't specified on the command line, software multiplication routines get used even though the code targets the RL78 core 🐢 That's for backward compatibility with older toolchains that didn't have hardware multiply and divide support 🫶
In addition, a C preprocessor macro gets defined based on this option's setting. The possible values are "__RL78_G10__", "__RL78_G13__", or "__RL78_G14__" 🧚
-mg10,-mg13,-mg14,-mrl78🕰️ — these are aliases for the corresponding-mcpu=option. They're only here for backwards compatibility 💜-mallregs🌸 — lets the compiler use all of the available registers. By default, registersr24..r31are reserved for use in interrupt handlers, but with this option enabled, they can be used in ordinary functions too 🔥-mrelax,-mno-relax⭐ — enables or disables assembler and linker relaxation. This is enabled by default at-Os💖-mes0🦋 — assumes"ES"is zero throughout program execution, and uses it to address read-only data 🎀-msave-mduc-in-interrupts,-mno-save-mduc-in-interrupts🛡️ — specifies that interrupt handler functions should preserve the MDUC registers. This is only necessary if normal code might use the MDUC registers, for example because 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 calls another function 🫶
✨ IBM RS/6000 and PowerPC Options ✨
These -m options are defined for the IBM RS/6000 and PowerPC 🍓
-mcpu=cpu_type👑 — sets the architecture type, register usage, and instruction scheduling parameters for the machine typecpu_type. The supported values forcpu_typeare401,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,power11,powerpc,powerpc64,powerpc64le,rs64, andnative🌈
-mcpu=powerpc, -mcpu=powerpc64, and -mcpu=powerpc64le specify pure 32-bit PowerPC (either endian), 64-bit big endian PowerPC, and 64-bit little endian PowerPC architecture machine types 🧚 Each one gets an appropriate, generic processor model assumed for scheduling purposes ✨
Specifying native as the cpu type detects and selects the architecture option that matches the host processor of the system doing the compilation 🖥️ -mcpu=native has no effect if GCC doesn't recognize the processor 🙈
The other options specify a specific processor 🎯 Code generated under those options runs best on that processor, and may not run at all on others 💀
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-protectSo the exact settings for each CPU can shift between compiler versions 💅 It's whatever looks fastest for that chip, so it doesn't always match what the hardware can actually do 🤷♀️ If you want one specific option set to a certain value, just put it after -mcpu, like -mcpu=970 -mno-altivec 🎀
On AIX, -mcpu doesn't turn -maltivec or -mpowerpc64 on or off right now, because AIX doesn't fully support those options yet 🙈 You can still toggle them yourself if you're sure it'll work in your setup 💜
Honestly? For most cases we'd recommend -mcpu=cpu_type over the switches that control specific instructions. It's the cleaner move 🫶
-mtune=cpu_type— Sets the instruction scheduling parameters for the machine typecpu_type, but it leaves the architecture and register usage alone, unlike-mcpu=cpu_type✨ You use the samecpu_typevalues for-mtuneas you would for-mcpu. If you specify both, the code uses the architecture and registers from-mcpu, but the scheduling comes from-mtune🧚-mpowerpc64,-mno-powerpc64—-mpowerpc64lets GCC generate the extra 64-bit instructions from the full PowerPC64 architecture, and treats GPRs as 64-bit doubleword quantities 💖 GCC defaults to-mno-powerpc64🌸-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 🍓 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. Other data and code are only limited by the 64-bit address space 🌈-mprofile-kernel— Only on PowerPC64 GNU/Linux targets. When you use it with-pg, calls to"mcount"get inserted before the function prologue instead of after it 🔥-maltivec,-mno-altivec— Generates code that does (or doesn't) use AltiVec instructions, and also turns on built-in functions that give you more direct access to the AltiVec instruction set 💅 You might also need-mabi=altivecto adjust the current ABI with the AltiVec ABI enhancements 🦋
When you use-maltivec, the element order for AltiVec intrinsics likevec_splat,vec_extract, andvec_insertmatches the array element order for the target's endianness 😭 Element zero is the leftmost element in a vector register on a big-endian target, and the rightmost element in a vector register on a little-endian target.
-mpowerpc-gpopt,-mno-powerpc-gpopt— Specifying-mpowerpc-gpoptlets GCC use the optional PowerPC instructions in the General Purpose group, including floating-point square root ✨ Specifying-mpowerpc-gfxopt,-mno-powerpc-gfxopt—-mpowerpc-gfxoptlets GCC use the optional PowerPC instructions in the Graphics group, including floating-point select 🎀-mmfcrf,-mno-mfcrf—-mmfcrflets GCC generate the move-from-condition-register-field instruction, which is on the POWER4 and other processors that support PowerPC V2.01 🧚-mpopcntb,-mno-popcntb—-mpopcntblets GCC generate the popcount and double-precision FP reciprocal estimate instruction, which is on the POWER5 and other processors that support PowerPC V2.02 💜-mpopcntd,-mno-popcntd—-mpopcntdlets GCC generate the popcount instruction, which is on the POWER7 and other processors that support PowerPC V2.06 👑-mfprnd,-mno-fprnd—-mfprndlets GCC generate the FP round-to-integer instructions, which are on the POWER5+ and other processors that support PowerPC V2.03 🌸-mcmpb,-mno-cmpb—-mcmpblets GCC generate the compare bytes instruction, which is on the POWER6 and other processors that support PowerPC V2.05 🦋-mhard-dfp,-mno-hard-dfp—-mhard-dfplets GCC generate the decimal floating-point instructions found on some POWER processors 🍓-mvrsave,-mno-vrsave— Generates VRSAVE instructions when generating AltiVec code 🌈-msecure-plt— Generates code so thatldandld.socan build executables and shared libraries with non-executable".plt"and".got"sections 🔥 This is a PowerPC 32-bit SYSV ABI option 💅-mbss-plt— Generates code that uses a BSS".plt"section thatld.sofills in. It requires".plt"and".got"sections that are both writable and executable 😭 This is a PowerPC 32-bit SYSV ABI option 🙈-msplit-patch-nops— When you add NOPs for a patchable area with the-fpatchable-function-entryoption, this emits the "before" NOPs in front of the global entry point and the "after" NOPs after the local entry point 🧚 That makes the NOP sequence non-consecutive when a global entry point is generated. Without this option, the NOPs go directly before and after the local entry point, so they're consecutive, but the global and local entry points end up further apart 🫶 If only a single entry point is generated, this option does nothing ✨-misel,-mno-isel— This switch enables or disables the generation of ISEL instructions 💖-mvsx,-mno-vsx— Generates code that does (or doesn't) use vector/scalar (VSX) instructions, and also turns on 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 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 direct access to the Hardware Transactional Memory (HTM) instructions added in version 2.07 of the PowerPC ISA 🌸-mpower8-fusion,-mno-power8-fusion— Generates code that keeps some integer operations next to each other, so the instructions can be fused together on power8 and later processors 🍓-mquad-memory,-mno-quad-memory— Generates code that does (or doesn't) use the non-atomic quad word memory instructions 💅-mquad-memoryrequires 64-bit mode 🌈-mquad-memory-atomic,-mno-quad-memory-atomic— Generates code that does (or doesn't) use 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 to use IEEE 128-bit floating point support 💜 IEEE 128-bit floating point is only supported on Linux 🐧
-mfloat128 is enabled by default on PowerPC Linux systems using 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 generation of ISA 3.0 IEEE 128-bit floating point instructions 🧚 Otherwise, if you don't specify ISA 3.0 instruction generation, or you're targeting a 32-bit big-endian system, IEEE 128-bit floating point is handled with software emulation 🙈
-mfloat128-hardware,-mno-float128-hardware— Enables or disables using ISA 3.0 hardware instructions to support the__float128data type 🦋
-mfloat128-hardware is enabled by default on PowerPC Linux systems using the ISA 3.0 instruction set, and disabled on other systems 🌈
-m32,-m64— Generates code for 32-bit or 64-bit environments of 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, andlongand pointer to 64 bits, and generates code for PowerPC64, as for-mpowerpc64👑-mfull-toc,-mno-fp-in-toc,-mno-sum-in-toc,-mminimal-toc— These modify how the TOC (Table Of Contents) gets generated, which happens for every executable file 📜-mfull-tocis selected by default 💅 In that case, GCC allocates at least one TOC entry for each unique non-automatic variable reference in your program. GCC also puts floating-point constants in the TOC 🫶 Heads up: only 16,384 entries are available in the TOC 😭
If the linker throws an error saying 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, and -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 of these. Each one makes GCC produce very slightly slower and larger code, but it saves TOC space 🌸
If you're still out of TOC space even with both of those options, try -mminimal-toc instead 🙈 It makes GCC create only one TOC entry for every file. The code comes out slower and larger, but it uses extremely little TOC space 💜 You might want to use this only on files with less frequently executed code 🦋
-maix64,-maix32— Enables the 64-bit AIX ABI and calling convention: 64-bit pointers, a 64-bit"long"type, and the infrastructure needed to support them 👑-maix64implies-mpowerpc64, while-maix32disables the 64-bit ABI and implies-mno-powerpc64✨ GCC defaults to-maix32🌈-mxl-compat,-mno-xl-compat— okay so these make your code act more like IBM XL compiler output when you're using the AIX-compatible ABI 💅. With-mxl-compat, floating-point args to prototyped functions also go on the stack past the register save area (RSA), on top of the argument FPRs. It also stops assuming the most significant double in a 128-bitlong doubleis properly rounded when comparing and converting todouble, and it uses XL symbol names for thelong doublesupport routines.- The AIX calling convention got extended without any initial docs to cover an obscure K&R C case: calling a function that takes the address of its arguments with fewer arguments than it declares 🙈. IBM XL compilers read floating-point args that don't fit in the RSA from the stack, but only when a subroutine is compiled without optimization.
- Always storing FP args on the stack is inefficient and rarely needed, so this is not on by default. You only need it when calling subroutines built by IBM XL compilers without optimization.
-mpe— this one's giving IBM RS/6000 SP Parallel Environment (PE) support 🧚. 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 override the specs file with-specs=to point at the right directory.
The Parallel Environment doesn't support threads, so-mpeand-pthreadare incompatible. Don't pair them, bestie 😭.
-malign-natural,-malign-power— on AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux,-malign-naturaloverrides the ABI's alignment for bigger types (like floating-point doubles) and puts them on their natural size-based boundary ✨.-malign-powertells GCC to follow the ABI's alignment rules instead. GCC defaults to the standard ABI alignment.- On 64-bit Darwin, natural alignment is the default, and
-malign-poweris not supported 💀.
- On 64-bit Darwin, natural alignment is the default, and
-msoft-float,-mhard-float—-msoft-floatgenerates code that skips the floating-point register set, and-mhard-floatgenerates code that uses it 🦋. With-msoft-float, software floating-point emulation gets provided, but you have to pass the option to GCC when linking too.-mmultiple,-mno-multiple—-mmultipleuses the load multiple word and store multiple word instructions, and-mno-multipledoesn't. These are generated by default on POWER systems but not on PowerPC systems 🌸.
Don't use -mmultiple on little-endian PowerPC systems, because those instructions don't work when the processor is in little-endian mode. The exceptions are PPC740 and PPC750, which allow them in little-endian mode.
-mupdate,-mno-update—-mupdateuses the load or store instructions that update the base register to the calculated memory address, and-mno-updateskips them. These are generated by default 🍓.
If you use -mno-update, there's a small window between when the stack pointer gets updated and when the address of the previous frame gets stored. That means code that walks the stack frame across interrupts or signals might 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-addressestries not to avoid them 🧠. Indexed instructions can cost you performance on Power6 processors in certain situations, like stepping through large arrays that cross a 16M boundary. This is enabled by default when targeting Power6 and disabled otherwise.-mfused-madd,-mno-fused-madd—-mfused-madduses the floating-point multiply and accumulate instructions, and-mno-fused-madddoesn't 💜. These are generated by default when hardware floating point is used.- The machine-dependent
-mfused-maddoption is now mapped to the machine-independent-ffp-contract=fastoption. -mno-fused-maddis mapped to-ffp-contract=off.
- The machine-dependent
-mmulhw,-mno-mulhw—-mmulhwuses the half-word multiply and multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors, and-mno-mulhwdoesn't ⭐. These are generated by default when targeting those processors.-mdlmzb,-mno-dlmzb—-mdlmzbuses the string-searchdlmzbinstruction on the IBM 405, 440, 464 and 476 processors, and-mno-dlmzbdoesn'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 with bit-fields to align to the base type of the bit-field, and-mbit-aligndoes 👑.- For example, by default a struct with nothing but 8
"unsigned"bit-fields of length 1 gets aligned to a 4-byte boundary and ends up 4 bytes in size. With-mno-bit-align, that same struct is aligned to a 1-byte boundary and is just 1 byte. Iconic 🙌.
- For example, by default a struct with nothing but 8
-mbit-word,-mno-bit-word— allows bit-fields to cross word boundaries 🌈.-mno-strict-align,-mstrict-align— on System V.4 and embedded PowerPC systems,-mno-strict-aligndoes not assume unaligned memory references are handled by the system, and-mstrict-aligndoes assume that 🫶.-mrelocatable,-mno-relocatable—-mrelocatablegenerates code that lets a static executable be relocated to a different address at run time, and-mno-relocatabledoesn't allow that 🦋. A simple embedded PowerPC system loader should relocate the entire contents of".got2"and the 4-byte locations listed in the".fixup"section. That's a table of 32-bit addresses this option generates.- For this to work, every object linked together must be compiled with
-mrelocatableor-mrelocatable-lib. -mrelocatablecode aligns the stack to an 8-byte boundary.
- For this to work, every object linked together must be compiled with
-mrelocatable-lib,-mno-relocatable-lib— same vibe as-mrelocatable: it generates a".fixup"section so static executables can be relocated at run time 🧚. The difference is that-mrelocatable-libdoesn't use the smaller stack alignment that-mrelocatabledoes.- Objects compiled with
-mrelocatable-libcan be linked with objects compiled with any combination of the-mrelocatableoptions 💖.
- Objects compiled with
-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 it's not relocatable, but its external references are 🌈. The result is suitable for applications, but not 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— controls the priority given to dispatch-slot restricted instructions during the second scheduling pass 👑. Thepriorityargument takes0,1, or2, which assigns no, highest, or second-highest (respectively) priority to those instructions.-msched-costly-dep=dependence_type— controls which dependences the target considers costly during instruction scheduling 🧠. Thedependence_typeargument 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 tonumberis costly.
-minsert-sched-nops=scheme— controls which NOP insertion scheme gets used during the second scheduling pass 💅. Theschemeargument 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. It inserts exactly as many NOPs as needed to push an insn into a new group, according to the estimated processor grouping.number— insert NOPs to force costly dependent insns into separate groups. It insertsnumberNOPs to force an insn into 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— same as specifying both-mcall-sysvand-meabi🫶.-mcall-sysv-noeabi— same as specifying both-mcall-sysvand-mno-eabi🌸.-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— picks the type of traceback table ✨. Valid values fortraceback_typearefull,part, andno.-maix-struct-return— returns all structures in memory, as the AIX ABI specifies 👑.-msvr4-struct-return— returns structures smaller than 8 bytes in registers, as the SVR4 ABI specifies 🔥.-mabi=abi-type— extends the current ABI with a particular extension, or removes one 🧚. Valid values arealtivec,no-altivec,ibmlongdouble,ieeelongdouble,elfv1,elfv2, and, for AIX,vec-extabiandvec-default.-mabi=ibmlongdouble— okay bestie, this one flips the ABI over to IBM extended-precisionlong double💖. Heads up, it's not likely to work if your system already defaults to IEEE extended-precisionlong double🙈. If you switchlong doubleaway from IEEE extended-precision, the compiler warns you unless you add-Wno-psabi. You also need-mlong-double-128turned on for it to work 🎀-mabi=ieeelongdouble— the mirror image of the one above ✨. It's switching the ABI to IEEE extended-precisionlong double, and it's probably not going to work if your system defaults to IBM extended-precisionlong double💀. If you changelong doubleaway from IBM extended-precision, you'll get a warning unless you use-Wno-psabi. And yep, you still need-mlong-double-128enabled 🦋-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 honestly it's likely to fail in spectacular ways 😭-mabi=elfv2— the ELFv2 ABI, which is the default for little-endian PowerPC 64-bit Linux 🧚. Same warning applies: overriding it needs special system support and will probably fail in spectacular ways 💅-mgnu-attribute,-mno-gnu-attribute— this tells GCC to emit.gnu_attributeassembly directives 🫶. Those set tag/value pairs in a.gnu.attributessection, which describe ABI variations in function parameters or return values ✨-mprototype,-mno-prototype— on System V.4 and embedded PowerPC systems, this lets you assume every call to a variable argument function is properly prototyped 👑. Without it, GCC has to slip an instruction in before every non-prototyped call to set or clear bit 6 of the condition code register (CR). That bit says whether floating-point values are being passed in the floating-point registers, just in case the function takes variable arguments 🤓. 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.o, and that the standard C libraries arelibsim.aandlibc.a🍓. It's the default forpowerpc-*-eabisimconfigurations 💜-mmvme— on embedded PowerPC systems, the startup module iscrt0.oand the standard C libraries arelibmvme.aandlibc.a⭐-mads— on embedded PowerPC systems, the startup module iscrt0.oand the standard C libraries arelibads.aandlibc.a🔥-myellowknife— on embedded PowerPC systems, the startup module iscrt0.oand the standard C libraries arelibyk.aandlibc.a🌸-mvxworks— on System V.4 and embedded PowerPC systems, this tells GCC you're compiling for a VxWorks system 🦋-memb— on embedded PowerPC systems, this sets thePPC_EMBbit in the ELF flags header 🎀. That's how you indicate that eabi extended relocations are being used 💖-meabi,-mno-eabi— on System V.4 and embedded PowerPC systems, this either adheres to (-meabi) or doesn't adhere to (-mno-eabi) the Embedded Applications Binary Interface (EABI) 🫶. EABI is basically a set of modifications to the System V.4 specifications, so it's a whole vibe ✨- With
-meabi, the stack is aligned to an 8-byte boundary, a function__eabiis called frommainto set up the EABI environment, and the-msdataoption can use bothr2andr13to point to two separate small data areas 👑 - With
-mno-eabi, the stack is aligned to a 16-byte boundary, no EABI initialization function is called frommain, and the-msdataoption only usesr13to point to a single small data area 🌈 - The
-meabioption is on by default if you configured GCC using one of thepowerpc*-*-eabi*options ⭐
- With
-msdata=eabi— on System V.4 and embedded PowerPC systems, small initializedconstglobal and static data goes in the.sdata2section, which is pointed to by registerr2🍓. Small initialized non-constglobal and static data goes in the.sdatasection, pointed to by registerr13💜. Small uninitialized global and static data goes in the.sbsssection, which sits right next to.sdata🔥. Heads up,-msdata=eabiis incompatible with-mrelocatable, and it also sets-memb🙈-msdata=sysv— on System V.4 and embedded PowerPC systems, small global and static data goes in the.sdatasection, pointed to by registerr13🧚. Small uninitialized global and static data goes in.sbss, which is adjacent to.sdata🦋. This one's incompatible with-mrelocatabletoo 💀-msdata=default,-msdata— on System V.4 and embedded PowerPC systems, if-meabiis used, the code gets compiled the same as-msdata=eabi🌸. Otherwise it's compiled the same as-msdata=sysv✨-msdata=data— on System V.4 and embedded PowerPC systems, small global data goes in the.sdatasection 💅. Small uninitialized global data goes in.sbss🫶. The catch is that registerr13is not 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 the.datasection, and all uninitialized data goes in the.bsssection 🍓-mreadonly-in-sdata— read-only objects get put in the.sdatasection as well 👑. This is the default 💖-mblock-move-inline-limit=num— this inlines all block moves (like calls tomemcpyor structure copies) that are less than or equal tonumbytes ⭐. The minimum value fornumis 32 bytes on 32-bit targets and 64 bytes on 64-bit targets 🔥. The default value depends on the target 🌸-mblock-compare-inline-limit=num— this generates non-looping inline code for all block compares (like calls tomemcmpor structure compares) that are less than or equal tonumbytes 🦋. Ifnumis0, all inline expansion of block compares is disabled, both the non-loop and loop kinds 💀. The default value depends on the target 🎀-mblock-compare-inline-loop-limit=num— this generates an inline expansion using loop code for all block compares that are less than or equal tonumbytes, but greater than the limit for non-loop inline block compare expansion 🧚. If the block length isn't constant, at mostnumbytes get compared beforememcmpis called to handle the rest of the block 💅. The default value depends on the target 💜-mstring-compare-inline-limit=num— this compares at mostnumstring bytes with inline code 🫶. If the difference or the end of the string isn't found at the end of the inline compare, a call tostrcmporstrncmptakes care of the rest of the comparison 🙈. The default is 64 bytes 🌈-G num— on embedded PowerPC systems, global and static items less than or equal tonumbytes go into the small data or BSS sections instead of the normal data or BSS section 🍓. By default,numis 8 ✨. The-G numswitch is also passed to the linker 👑. All modules should be compiled with the same-G numvalue, no exceptions 🔥-mregnames,-mno-regnames— on System V.4 and embedded PowerPC systems, this does (-mregnames) or doesn't (-mno-regnames) emit register names in the assembly output using symbolic forms 💖-mlongcall,-mno-longcall— by default, GCC assumes all calls are far away, so it uses a longer and more expensive calling sequence 🐢. That's 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 detect 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 🧚. It's planned to add this feature to the GNU linker for 32-bit PowerPC systems as well 🌸
- 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) 🫶. Heads up, PowerPC with-mbss-pltand PowerPC64 ELFv1 (big-endian) do not support inline PLT calls 🙈 - On Darwin/PPC systems,
#pragma longcallgeneratesjbsr 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 abl calleeif the PPCblinstruction reaches the callee directly 🌈. Otherwise, the linker generatesbl L42to call the branch island 🍓. The branch island is 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 directs the compiler to emit the glue for every direct call, and the Darwin linker decides whether to use it or discard it 💜
- In the future, GCC may ignore all
longcallspecifications when the linker is known to generate glue 🔮
-mpltseq,-mno-pltseq— this implements (-mpltseq) or doesn't implement (-mno-pltseq)-fno-pltand long calls using an inline PLT call sequence 🦋. That sequence supports lazy linking and long calls to functions indlopen'd shared libraries 💖. 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 the support is detected when configuring GCC 🎀. For 32-bit PowerPC, they're also enabled if GCC is configured with--enable-secureplt🌈. Watch out:-mpltseqcode and-mbss-plt32-bit PowerPC relocatable objects may not be linked together 🙈-mtls-markers,-mno-tls-markers— this marks (-mtls-markers) or doesn't mark (-mno-tls-markers) calls to__tls_get_addrwith a relocation that specifies the function argument 🧚. That relocation lets the linker reliably associate the function call with the argument setup instructions for TLS optimization 💅. In turn, that lets GCC schedule the sequence better 🫶-mrecip,-mno-recip— okay so this one flips on the reciprocal estimate and reciprocal square root estimate instructions 💅, plus extra Newton-Raphson steps to win back precision, instead of doing a straight divide (or a square root and then a divide) on floating-point arguments 🦋. Bestie, you should pair-mrecipwith-ffast-math(or at least-funsafe-math-optimizations,-ffinite-math-only,-freciprocal-mathand-fno-trapping-math) 🫶. ngl the throughput is usually higher than the non-reciprocal instruction, BUT the precision can drop by up to 2 ulp for reciprocal square roots (like, the inverse of1.0comes out as0.99999994) 😭-mrecip=opt — this is the picky version 🎀 where you choose which reciprocal estimate instructions get to show up. opt is a comma-separated list, and you can put a "!" in front of any option to invert it 💜all— enable all estimate instructions ✨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 for FRSQRTE, XSRSQRTEDP, and XVRSQRTEDP, which are the ones handling double-precision reciprocal square root math 🔥
-mrecip-precision,-mno-recip-precision— this one lets GCC assume (or not assume 🙃) that the reciprocal estimate instructions are more precise than the PowerPC ABI actually requires. Picking-mcpu=power6,-mcpu=power7or-mcpu=power8automatically selects-mrecip-precisionfor you ✨. Also, the double-precision square root estimate instructions are NOT generated by default on low-precision machines, because they don't converge after three steps 💀-mveclibabi=type — this sets the ABI type used when vectorizing intrinsics with an external library 🧚. The only type supported right now ismass, which tells GCC to use IBM's Mathematical Acceleration Subsystem (MASS) libraries for that job 💅. GCC currently emits calls to the following when generating code for power7 🫶:
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 must ALSO be enabled 🔥, and the MASS libraries must be specified at link time 🎀
-mfriz,-mno-friz— okay so this decides whether GCC generates thefrizinstruction when-funsafe-math-optimizationsis used to speed up rounding floating-point values to 64-bit integers and back to floating point 🌸
Warning, bestie 😭 the friz instruction does NOT return the same value if the floating-point number is too large to fit in an integer.
-mpointers-to-nested-functions,-mno-pointers-to-nested-functions— this controls whether GCC generates code that loads up the static chain register (r11) when calling through a pointer on AIX and 64-bit Linux systems 🧚. On those systems a function pointer points to a 3-word descriptor that gives the function address, the TOC value to load into registerr2, and the static chain value to load into registerr11💜.-mpointers-to-nested-functionsis on by default 🌈
Heads up, bestie 💀 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 generates (or doesn't generate 🙈) code that saves the TOC value in the reserved stack location in the function prologue, if the function calls through a pointer on AIX and 64-bit Linux systems ✨. If the TOC value isn't saved in the prologue, it gets saved just before the call through the pointer 🦋. The-mno-save-toc-indirectoption is the default 🍓-mcompat-align-parm,-mno-compat-align-parm— this generates (or doesn't generate) code that passes structure parameters with a maximum alignment of 64 bits, so it matches older versions of GCC 🎀
Older versions of GCC (prior to 4.9.0) incorrectly did not align a structure parameter on a 128-bit boundary when that structure had a member needing 128-bit alignment 😭. This got fixed in more recent versions of GCC, but this option can help you make code that plays nicely with functions compiled by those older versions 🫶
The -mno-compat-align-parm option is the default 🌸
-mstack-protector-guard=guard,-mstack-protector-guard-reg=reg,-mstack-protector-guard-offset=offset — these generate stack protection code using a canary at guard 🔥. The supported locations areglobal(a global canary) ortls(a per-thread canary in the TLS block, which is the default with GNU libc version 2.4 or later) 👑
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 to use 💅. The defaults for those are whatever the relevant ABI specifies ✨
-mpcrel,-mno-pcrel— this generates (or doesn't generate 🙈) pc-relative addressing 🦋. The-mpcreloption requires that the medium code model (-mcmodel=medium) AND prefixed addressing (-mprefixed) options are enabled 🫶-mprefixed,-mno-prefixed— this generates (or doesn't generate) addressing modes that use prefixed load and store instructions 🧚. The-mprefixedoption requires that-mcpu=power10(or later) is enabled 💖-mmma,-mno-mma— this generates (or doesn't generate) the MMA instructions 🌈. The-mmaoption requires that-mcpu=power10(or later) is enabled 🔥-mrop-protect,-mno-rop-protect— this generates (or doesn't generate) ROP protection instructions when the target processor supports them 🛡️ Currently, this option disables the shrink-wrap optimization (-fshrink-wrap) 💀-mprivileged,-mno-privileged— this generates (or doesn't generate) code that runs in privileged state 👑-mblock-ops-unaligned-vsx,-mno-block-ops-unaligned-vsx— this generates (or doesn't generate) unaligned VSX loads and stores for inline expansion ofmemcpyandmemmove✨-msplat-word-constant,-mno-splat-word-constant— this generates (or doesn't generate) code that uses theXXSPLTIWinstruction 🌸. This option is enabled by default 🍓-msplat-float-constant,-mno-splat-float-constant— this generates (or doesn't generate) code that uses theXXSPLTIDPinstruction 🦋. This option is enabled by default 💜-mieee128-constant,-mno-ieee128-constant— this generates (or doesn't generate) code that uses theLXVKQinstruction 🧚. This option is enabled by default 🫶-mwarn-altivec-long,-mno-warn-altivec-long— this turns warnings on or off about deprecated vector long ... Altivec type usage ⚠️ This option is enabled by default 💅
🦋 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) in size 🎀 The default is-m32bit-doubles. Note that RX floating-point hardware only works on 32-bit values, which is exactly why the default is-m32bit-doubles🙈-fpu,-nofpu— this enables (-fpu) or disables (-nofpu) the use of RX floating-point hardware 🔥 The default is enabled for the RX600 series and disabled for the RX200 series 👑
Floating-point instructions are only generated for 32-bit floating-point values, though, so the FPU hardware is not used for doubles if the -m64bit-doubles option is used 💀
Note: if the-fpuoption is enabled, then-funsafe-math-optimizationsis also enabled automatically 😭 This is because the RX FPU instructions are themselves unsafe.
-mcpu=name — this selects the type of RX CPU to target 🧚 Right now three types are supported: 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 does not support the MVTIPL instruction 🌸
The RX200 series does not have a hardware floating-point unit, so -nofpu is enabled by default when this type is selected 🫶
-mbig-endian-data,-mlittle-endian-data— this stores data (but NOT code) in the big-endian format 🌈 The default is-mlittle-endian-data, which means data is stored in the little-endian format 💜-msmall-data-limit=N — this specifies the maximum 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 size of the area is limited and it's up to the programmer to make sure the area doesn't overflow 😭
Also, when the small data area is used, one of the RX's registers (usually r13) is reserved for pointing to this area, so the compiler can't use it anymore 💅 This could result in slower and/or larger code if variables get pushed onto the stack instead of being held in that register 💀
Note, bestie: common variables (variables that have not been initialized) and constants are NOT placed into the small data area, because they get assigned to other sections in the output executable 🫶
okay so the default value is zero, which disables this feature 🙅♀️ and bestie, it is not switched on by default at higher optimization levels (-O2 etc) because reserving a register can be kinda detrimental 😬. It's up to you to experiment and see whether it actually helps your program ✨. Peep the -mpid description for how the register holding the small data area pointer gets picked 🧚
-msim,-mno-sim— Use the simulator runtime 🎮. The default is the libgloss board-specific runtime.-mas100-syntax,-mno-as100-syntax— When GCC spits out assembler output, this makes it use a syntax that plays nice with Renesas's AS100 assembler 🧸. GAS can read it too, but it has some restrictions, so it is not generated by default 🙈-mmax-constant-size=N— Sets the biggest a constant can be (in bytes) and still be used as an operand in an RX instruction 📏. RX instructions can take constants up to 4 bytes, but a longer value means a longer instruction, so sometimes it's lowkey beneficial to restrict this 💅. Constants that are too big get tossed into a constant pool and referenced through register indirection 🫶
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 🦋. The linker tries to shrink your program by finding shorter versions of various instructions. It's disabled by default.-mint-register=N— Reserves registers for fast interrupt handler functions 👑.Ncan be between0and4:1reserves"r13"for the exclusive use of fast interrupt handlers2reserves"r13"and"r12"3reserves"r13","r12"and"r11"4reserves"r13"through"r10"0, the default, reserves nothing 🌸
-msave-acc-in-interrupts— Tells interrupt handlers to preserve the accumulator register 🔥. This is only needed if normal code might use the accumulator, like when it does 64-bit multiplications. The default is to ignore the accumulator, because that keeps the interrupt handlers faster ⚡-mpid,-mno-pid— Enables position-independent data 🧚♀️. When it's on, any access to constant data happens 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 💜
Heads up, this reserves a register (usually "r13") for the constant data base address 😭. That can make code slower and/or bigger, especially in complicated functions.
Which register ends up holding that base address depends on whether -msmall-data-limit and/or -mint-register are on. Starting at "r13" and working downwards, registers get allocated first for -mint-register, then -mpid, and finally -msmall-data-limit. So the small data area register can be "r8" if both -mint-register=4 and -mpid are specified on the command line 💅
By default this feature is not enabled. You can restore the default with -mno-pid 🙃
-mno-warn-multiple-fast-interrupts,-mwarn-multiple-fast-interrupts— Stops GCC from yelling with 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, since the RX only supports one of them 🙄-mallow-string-insns,-mno-allow-string-insns— Turns the string manipulation instructions"SMOVF","SCMPU","SMOVB","SMOVU","SUNTIL""SWHILE"and also the"RMPA"instruction on or off 🧵. These can prefetch data, which is not safe if you're touching an I/O register 😱 (see section 12.2.7 of the RX62N Group User's Manual for more info).
The default is to allow them. GCC can't reliably detect every situation where a string instruction might touch an I/O register, so it can't turn them off automatically. It's on you to use -mno-allow-string-insns if your program accesses I/O space 🫶
When these instructions are enabled, GCC defines the C preprocessor symbol"__RX_ALLOW_STRING_INSNS__". Otherwise it defines"__RX_DISALLOW_STRING_INSNS__"🚨
-mjsr,-mno-jsr— Use only (or not only)"JSR"instructions to access functions 🧭. This can help when your code size goes beyond the range of"BSR"instructions. Note that-mno-jsrdoesn't mean "don't useJSR" 🙅♀️. It just means any type of branch may be used.-mlra— Uses the new LRA register allocator 🆕. By default the old"reload"allocator is used.
Note: the generic GCC command-line option -ffixed-reg has special significance for the RX port when 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 when the normal use of those registers has been restricted with -ffixed-reg or -mint-register 🌈
🌸 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.ahandle decimal-floating-point operations. 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 switches 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 in the callee's stack frame 🔗. A backchain may be needed to debug with tools that don't understand DWARF call frame information 🐛. When-mno-packed-stackis in effect, the backchain pointer is stored at the bottom of the stack frame. When-mpacked-stackis in effect, the backchain goes into the topmost word of the 96/160 byte register save area 🍓
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-stackand-mhard-floatis 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 much more efficient with the stack space 👑
When -mbackchain is 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 though: 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. To build 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 that uses the"bras"instruction for subroutine calls 📞. This only works reliably if the total executable size doesn't go over 64k 🚫. The default is to use the"basr"instruction instead, which doesn't have that limitation 💅-m64,-m31— With-m31, GCC generates code compliant with the GNU/Linux for S/390 ABI 🖥️. With-m64, it generates code compliant with the GNU/Linux for zSeries ABI. This lets GCC generate 64-bit instructions 🚀. For the s390 targets the default is-m31, while the s390x targets default to-m64✨
-m31 is deprecated and support will be removed 😭-mzarch,-mesa— With-mzarch, GCC generates code using the instructions available on z/Architecture 🌌. With-mesa, it generates code using the instructions available on ESA/390. Note that-mesais not possible with-m64🙅♀️. When generating code compliant with the GNU/Linux for S/390 ABI, the default is-mesa. When generating code compliant with the GNU/Linux for zSeries ABI, the default is-mzarch💖-mhtm,-mno-htm— ✨ okay so-mhtmunlocks a set of S/390 System z Built-in Functions that use instructions from the transactional execution facility, introduced with the IBM zEnterprise EC12 machine generation 🧚. It's on by default when you use-march=zEC12💖.-mvx,-mno-vx— bestie,-mvxmakes GCC generate code with the vector extension facility from the IBM z13 machine generation 🦋. It also changes the ABI for some vector type values when it comes to alignment and calling conventions 👀. If vector types show up somewhere ABI-relevant, GCC adds a GAS.gnu_attributecommand so the binary is marked with the ABI it used 📝.-mvxis on by default with-march=z13✨.-mzvector,-mno-zvector— this one is giving vector language extensions 💅.-mzvectorturns on vector language extensions and builtins using the z13 vector extension facility, and it lets you usevectoras a keyword for vector type variables and arguments 🎀. Heads up:vectoronly works when GNU extensions are on, and it's not expanded when you ask for strict standard compliance, like with-std=c99🙈. On top of the GCC low-level builtins,-mzvectoralso adds builtins for compatibility with AltiVec-style implementations like Power and Cell 🌈. To actually use them, you have to include the header filevecintrin.h📚.-mzvectoris disabled by default 🫶.-mmvcle,-mno-mvcle—-mmvcletells GCC to generate code that uses themvcleinstruction for block moves 🚚. With-mno-mvcle, it uses anmvcloop instead 🔁. This is the default unless you're optimizing for size 🌸.-mdebug,-mno-debug—-mdebugmakes the compiler print extra debug info while it compiles 🔍.-mno-debugkeeps it quiet, and quiet is the default 🤫.-march=cpu-type— the big one 👑. This generates code that runs on cpu-type, which is the name of a system representing a certain processor type ⭐. The possible values arez900/arch5,z990/arch6,z9-109,z9-ec/arch7,z10/arch8,z196/arch9,zEC12,z13/arch11,z14/arch12,z15/arch13,z16/arch14,z17/arch15, andnative🧚.
The default is -march=z900 🍓.
Using native as the cpu type picks the best architecture option for your host processor 💜. Just know that -march=native does nothing if GCC doesn't recognize the processor 💀.
-mtune=cpu-type—-mtunetells GCC to tune everything applicable in the generated code to cpu-type 🎯. The one exception is the ABI and the set of available instructions, which it leaves alone 🙅♀️. The list of values is the same as for-march✨. The default is whatever value was used for-march💅.-mtpf-trace,-mno-tpf-trace—-mtpf-tracemakes GCC add TPF OS specific branches to trace routines in the operating system 🛰️.-mno-tpf-traceskips adding them. This option is off by default, even when you're compiling for TPF OS 🙃.-mtpf-trace-skip,-mno-tpf-trace-skip—-mtpf-trace-skipchanges the default branch targets enabled by-mtpf-traceso they point at specialized trace routines 🎯. These let you selectively skip function trace entries for TPF OS 🦋.-mno-tpf-trace-skipleaves those targets alone. This is also off by default, even when you're compiling for TPF OS and passing-mtpf-trace😭.-mmain— for the TPF OS target, use this one when linking 🔗. It adds the startup code and other linker options so you get a main object 🎀.-mfused-madd,-mno-fused-madd—-mfused-maddmakes GCC use the floating-point multiply and accumulate instructions ➕✖️.-mno-fused-maddtells it not to 🙅♀️. These instructions get generated by default when hardware floating point is in use 💖.-mwarn-framesize=framesize— this one's a little warning guard 🚨. It makes GCC emit a warning if the current function goes over the frame size you give it 📏. It's a compile-time check, so it doesn't have to be a real problem when the program runs 🫶. It's meant to flag functions that will most likely cause a stack overflow 💀. It's super useful in environments with a limited stack size, like the Linux kernel 🐧. A value of zero turns this warning off, and zero is the default 🌸.-mwarn-dynamicstack,-mno-warn-dynamicstack—-mwarn-dynamicstackmakes GCC warn if a function callsallocaor uses dynamically-sized arrays ⚠️. This is generally a bad idea when the stack size is limited 🙈.-mno-warn-dynamicstackturns the warning off.-mstack-guard=stack-guard,-mstack-size=stack-size,-mno-stack-guard,-mno-stack-size— these are the stack overflow detectives 🕵️♀️. When they're enabled, the S/390 back end adds extra instructions to the function prologue that trigger a trap if the stack goes stack-guard bytes above stack-size 🪤. (Remember, the stack on S/390 grows downward ⬇️.) If you leave outstack-guard, GCC picks the smallest power of 2 that's larger than the frame size of the compiled function 🧮.
These are meant for debugging stack overflow problems 🔧. The extra code only adds a little overhead, so it can run on production-like systems without a big performance hit 🚀.
Some rules, bestie: the given values have to be exact powers of 2, and stack-size has to be greater than stack-guard without going over 64k 🚫. To be efficient, the extra code assumes the stack starts at an address aligned to the value given by stack-size 📐. The -mstack-guard= option only works together with -mstack-size= 🫂. You can override these on the command line with -mno-stack-guard and -mno-stack-size, respectively 🦋.
-mhotpatch=pre-halfwords,post-halfwords— if hotpatch is enabled, GCC generates a "hot-patching" function prologue for every function in the compilation unit 🔥. The function label gets prepended with the given number of two-byte NOP instructions (pre-halfwords, max1000000) 🫧. After the label,2 * post-halfwordsbytes get appended, using the largest NOP-like instructions the architecture allows (max1000000) 🧩.
If both arguments are zero, hotpatching is disabled 🙅♀️. You can override this for individual functions with the hotpatch attribute ✨.
-mpic-data-is-text-relative,-mno-pic-data-is-text-relative— when you compile for S/390 with-fpicor-fPIC, GCC normally uses relative addressing between code and data 🗺️. But for hotpatching, you might need to add new.textparts while still using the existing.dataand.bsssections 🧠. In that case, use-mno-pic-data-is-text-relativeto force addressing through the GOT instead 🎀.-mstack-protector-guard=guard— this 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 (the default) 🧵.-mstack-protector-guard-record— this one results in a section called__stack_protector_locthat holds pointers to every instruction that loads the address of the global guard 📍. So it only does something alongside-mstack-protector-guard=global🫶. It's intended for the Linux kernel 🐧.-mindirect-branch=choice,-mindirect-branch-jump=choice,-mindirect-branch-call=choice,-mfunction-return=choice,-mfunction-return-mem=choice,-mfunction-return-reg=choice— this whole group is about security 🛡️. It deals with vulnerabilities around speculative execution and indirect branch prediction by swapping indirect branches and function returns for direct branches to a thunk 🧵✨.
Here's how the choice values work, bestie 💅:
keepgives you the default code.thunkgenerates out-of-line thunks and replaces the old indirect branch with a direct branch to the thunk.thunk-externdoes the same branch replacement asthunk, but doesn't emit the thunks 🫥.thunk-inlineis only available with-mindirect-branch-jump. You should prefer it overthunkin user-space applications, since it keeps stack unwinding and exception handling correct 🧠.
-mindirect-branch sets both -mindirect-branch-jump and -mindirect-branch-call 🔗. -mfunction-return sets both -mfunction-return-reg and -mfunction-return-mem 🔗. And you can set all of these per function using function attributes 🎯.
-mindirect-branch-table,-mno-indirect-branch-table— this is a team player 🤝. It works with-mindirect-branchand-mfunction-return. When enabled, it generates tables pointing to the branch locations those options patched 🗂️. The tables live in sections named.s390_indirect_jump,.s390_indirect_call,.s390_return_reg, and.s390_return_mem📦. Each section is an array of 32-bit elements, and each entry holds the offset from the entry to the patched location 🔢.-mfentry,-mno-fentry— used together with-pg,-mfentryemits profiling code using the__fentry__hook that GLIBC 2.29 or later provides 📈. This is only available for 64-bit code 💻. If you don't enable it, profiling falls back to the less efficient_mcounthook 🐢.-mrecord-mcount,-mno-record-mcount— when enabled, GCC generates a__mcount_locsection that holds the locations of all the generated profiling calls to_mcountor__fentry__📋.mnop-mcount,mno-nop-mcount— instead of generating calls to_mcountor__fentry__with-pg, this inserts a sequence of no-op instructions of the same length right where those calls would have gone 😴. Pair it with-mrecord-mcountand you can patch the call sequences into the object file without recompiling it 🧩✨.-mpreserve-args,-mno-preserve-args— when enabled, GCC saves all the argument registers to the stack and generates the matching CFI information 🗃️. This is handy for apps that want to build their own stack unwinding and need access to function arguments 🫶.-munaligned-symbols,-mno-unaligned-symbols— this tells GCC to assume that external symbols with a natural alignment of 1 might be unaligned 🙈. By default, every symbol without explicit alignment is assumed to be aligned on a 2-byte boundary, as the IBM Z ABI requires 📐.
🦋 SH Options
These -m options are defined for the SH implementations 🌈.
-m1— generates code for the SH1 💜.-m2— generates code for the SH2 🌸.-m2e— generates code for the SH2e ✨.-m2a-nofpu— okay bestie, this one is for the SH2a, or an SH2a-FPU that you want to act like it has no FPU 🦋. The floating-point unit never gets used.-m2a-single-only— SH2a-FPU code that never does double-precision floating-point math. Very single-precision core 💜.-m2a-single— SH2a-FPU code that assumes the FPU starts out in single-precision mode ✨.-m2a— SH2a-FPU code that assumes the FPU starts out in double-precision mode 👑.-m3— SH3 code, plain and simple 🌸.-m3e— SH3e code 🧚.-m4-nofpu— SH4 code with no floating-point unit at all 🫶.-m4-single-only— SH4 code for a floating-point unit that can only do single-precision arithmetic 💅.-m4-single— SH4 code that assumes the FPU is in single-precision mode by default 🎀.-m4— SH4 code, the classic 💖.-m4-100— SH4-100 code 🍓.-m4-100-nofpu— SH4-100 code that keeps the floating-point unit out of it completely 🌈.-m4-100-single— SH4-100 code that assumes the FPU is in single-precision mode by default ⭐.-m4-100-single-only— SH4-100 code where no double-precision floating-point operations sneak in 🔥.-m4-200— SH4-200 code 💜.-m4-200-nofpu— SH4-200 code, written so the floating-point unit is not used. The wording in the original is a bit garbled here, but the vibe is "no FPU, please" 🙈.-m4-200-single— SH4-200 code that assumes the FPU is in single-precision mode by default 🦋.-m4-200-single-only— SH4-200 code where no double-precision floating-point operations are used 🌸.-m4-300— SH4-300 code 🧚.-m4-300-nofpu— SH4-300 code, again written so the floating-point unit is not used. Same little wording glitch as the SH4-200 one 💀.-m4-300-single— SH4-300 code where no double-precision floating-point operations are used. Yes, the original says exactly that, so we're keeping it 🫶.-m4-300-single-only— SH4-300 code where no double-precision floating-point operations are used. Same as the one right above it, periodt 💅.-m4-340— SH4-340 code. No MMU, no FPU, very minimal, very iconic ✨.-m4-400— SH4-400 code. Also no MMU and no FPU 🌈.-m4-500— SH4-500 code with no FPU 🔥. It also passes-isa=sh4-nofputo the assembler, so the assembler knows the deal too 🧚.-m4a-nofpu— code for the SH4al-dsp, or for an SH4a that doesn't touch the floating-point unit 💖.-m4a-single-only— SH4a code where no double-precision floating-point operations are used 🎀.-m4a-single— SH4a code that assumes the FPU is in single-precision mode by default 🍓.-m4a— SH4a code 👑.-m4al— basically the same as-m4a-nofpu, except it also quietly passes-dspto the assembler. Also, GCC doesn't generate any DSP instructions right now, so that part is more of a heads-up than a feature 🙈.-mb— compiles for big-endian mode 🌊.-ml— compiles for little-endian mode 🌊.-mdalign— aligns doubles on 64-bit boundaries 📐. Heads up though: this changes the calling conventions, so some standard C library functions won't work unless you recompile them with-mdalignfirst. Not a vibe, that's a warning ⚠️.
Heads up:-mdalignchanges the calling conventions, so standard C library functions that weren't recompiled with-mdalignmay break. Recompile first, bestie 💀.
-mrelax— shortens some address references at link time when it's possible, and it does this by using the linker option-relax🦋.-mbigtable— uses 32-bit offsets in"switch"tables. The default is 16-bit offsets, so this one is the upgrade 🧚.-mbitops— turns on bit manipulation instructions on SH2A 💅.-mfmovd— turns on thefmovdinstruction 🌸. Check-mdalignfor the alignment rules that come with it 🫶.-mrenesas,-mno-renesas—-mrenesasmakes the compiler follow the calling conventions defined by Renesas 👑. The default for every SH toolchain target is-mno-renesas, which uses the calling conventions GCC had before the Renesas ones existed ✨.-mnomacsave— marks the"MAC"register as call-clobbered, even when-mrenesasis also given 💜.-mieee,-mno-ieee— these control how IEEE compliant floating-point comparisons are, which affects what happens when a comparison result is unordered 🔥.-mieeeis implicitly on by default. If-ffinite-math-onlyis on,-mno-ieeegets implicitly set, and that makes floating-point greater-equal and less-equal comparisons faster ⭐. You can override the implicit setting by explicitly passing either-mieeeor-mno-ieee💅.-minline-ic_invalidate,-mno-inline-ic_invalidate— inlines code that invalidates instruction cache entries after setting up nested function trampolines 🧚. This option does nothing if-musermodeis in effect and your code generation option (like-m4) doesn't allow theicbiinstruction 🙈. If the code generation option doesn't allowicbiand-musermodeisn't in effect, the inlined code pokes the instruction cache address array directly with an associative write. That needs privileged mode at run time, and it also breaks if the cache line was mapped through the TLB and has since become unmapped 💀.-misize— dumps instruction size and location into the assembly code 📐.-matomic-model=model— sets the model for atomic operations, plus any extra parameters, as a comma-separated list 🌈. For the full scoop on atomic built-in functions, check__atomic Builtins. These are the models and parameters you can pick from:none— turns off compiler-generated atomic sequences and emits library calls for atomic operations instead 🫶. This is the default when the target isn'tsh*-*-linux*.soft-gusa— generates GNU/Linux-compatible gUSA software atomic sequences for the atomic built-ins 🦋. These need extra help from the system's interrupt and exception handling code, and they're only good for single-core SH3* and SH4* systems 💜. This option is on by default when the target issh*-*-linux*and the chip is SH3* or SH4*. When the target is SH4A, it also partly uses the hardware atomic instructionsmovli.landmovco.lto make the code faster, unless you specifystrict🔥.soft-tcb— generates software atomic sequences that use a variable in the thread control block ⭐. It's basically a variation of gUSA sequences that also works on SH1* and SH2* targets 🌸. These sequences also need extra help from the interrupt and exception handling code, and they're only suitable for single-core systems 🎀. When you use this model, you have to specify thegbr-offset=parameter too 🧚.soft-imask— generates software atomic sequences that temporarily turn interrupts off by settingSR.IMASK = 1111🙈. This model only works when the program runs in privileged mode, and it's only for single-core systems 💅. It doesn't need extra help from the system's interrupt and exception handling code 🫶. It's on by default when the target issh*-*-linux*and the chip is SH1* or SH2* 👑.hard-llcs— generates hardware atomic sequences using only themovli.landmovco.linstructions 💖. It's only available on SH4A and is good for multi-core systems 🌈. Those hardware instructions only support 32-bit atomic variables, so 8-bit and 16-bit access gets emulated with 32-bit accesses 🔥. Code built with this option is still compatible with other software atomic model interrupt and exception handling systems, as long as it runs on an SH4A system ✨. It doesn't need any extra help from the system's interrupt and exception handling code 🦋.gbr-offset=— this parameter sets the offset in bytes of the variable in the thread control block structure that the generated atomic sequences use whensoft-tcbis picked 🧚. For other models it gets ignored 💀. The value has to be an integer multiple of four and in the range 0-1020 📐.strict— stops you from mixing multiple atomic models, even if they'd be compatible, and makes the compiler generate atomic sequences for only the model you specified 🔒.
-mtas— generates thetas.bopcode for__atomic_test_and_set🔥. Heads up, this can hurt overall performance depending on your hardware and software setup, becausetas.bforces operand cache line flushes ⚠️. On multi-core SH4A processors,tas.bhas to be used with real caution, since it can corrupt data with certain cache configurations 💀.-mprefergot— when generating position-independent code, makes function calls go through the Global Offset Table instead of the Procedure Linkage Table 🌸.-musermode,-mno-usermode—-musermodestops the compiler from generating privileged mode code, and-mno-usermodelets it do so 👑.-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*,-musermodedoes nothing, because those chips have no user mode 💅.-multcost=number— sets the cost the compiler assumes for a multiply instruction 🧮.-mdiv=strategy— picks the division strategy for integer division operations 🌈. Thestrategycan be one of these:call-div1— calls a library function that does the operation with the single-step division instructiondiv1🎀. Dividing by zero gives an unspecified result and doesn't 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 💜. Dividing by zero causes a floating-point exception ⭐. This is the default for SHcompact with an FPU 👑. If you specify this on a target that doesn't have a double-precision FPU, it falls back tocall-div1🦋.
call-table— okay so this one calls a library function that uses a lookup table for small divisors 📚, and for bigger divisors it switches to thediv1instruction with case distinction 💅. Dividing by zero gives an unspecified result and does not trap. This is the default for SH4 🌸. Picking it for targets without dynamic shift instructions makescall-div1the default instead ✨.
When you don't pick a division strategy, GCC chooses one based on the current target 🎀. For SH2A, the default is to use the divs and divu instructions instead of library function calls 🦋.
-maccumulate-outgoing-args,-mno-accumulate-outgoing-args— reserve space once for outgoing arguments in the function prologue, instead of around each call 🧚. This is generally great for performance and size, and it's also needed for unwinding so the stack frame doesn't change around conditional code 💖.-maccumulate-outgoing-argsis enabled by default.-mdivsi3_libfunc=name— sets the name of the library function used for 32-bit signed division to name 🔥. This only changes the name used in the call division strategies. The compiler still expects the same sets of input, output, and clobbered registers as if this option weren't there 🫶.-mfixed-range=register-range— tells GCC to treat the given register range as fixed registers 🔒. A fixed register is one the register allocator can't use, which is super useful when compiling kernel code 👑. A register range is written as two registers separated by a dash, and you can list multiple ranges separated by a comma ✨.-mbranch-cost=num— assumes num is the cost of a branch instruction 💜. Higher numbers make the compiler try to generate more branch-free code when it can 🌈. If you don't specify it, the value depends on the processor type you're compiling for 🎀.-mzdcbranch,-mno-zdcbranch— these assume (or don't assume) that zero displacement conditional branch instructionsbtandbfare fast ⚡. With-mzdcbranch, the compiler prefers zero displacement branch code sequences 🦋. It's enabled by default when generating code for SH4 and SH4A, and you can explicitly turn it off with-mno-zdcbranch🙈.-mcbranch-force-delay-slot— forces the use of delay slots for conditional branches, filling the delay slot with anopif a suitable instruction can't be found 🧸. It's disabled by default. You can turn it on to work around hardware bugs like the ones found in the original SH7055 🛠️.-mfsca,-mno-fsca— allows or disallows the compiler from emitting thefscainstruction for sine and cosine approximations 📐.-mfscahas to be used together 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 or disallows the compiler from emitting thefsrrainstruction for reciprocal square root approximations 🌟.-mfsrrahas to 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,-mno-pretend-cmove— prefer or don't prefer zero-displacement conditional branches for conditional move instruction patterns 🍓. This can make code faster on the SH4 processor 🚀.-mfdpic,-mno-fdpic— generates code using the FDPIC ABI 🌸.-mlra,-mno-lra— uses the new LRA register allocator 🆕. By default, the oldreloadallocator is used 🕰️.
🌸 Solaris 2 Options 🌸
These options are supported on Solaris 2 💜:
-mclear-hwcap,-mno-clear-hwcap—-mclear-hwcaptells the compiler to remove the hardware capabilities generated by the Solaris assembler 🧹. You only need this when object files use ISA extensions the current machine doesn't support, but the code checks at runtime whether or not to use them 🔍.-mimpure-text,-mno-impure-text— used together with-shared,-mimpure-texttells the compiler not to pass-z textto the linker when linking a shared object 🌈. With this option, you can link position-dependent code into a shared object 🧩.
Yikes, read this part 😭:-mimpure-textsuppresses the "relocations remain against allocatable but non-writable sections" linker error message. However, the necessary relocations trigger copy-on-write, so the shared object is not actually shared across processes 💔. Instead of using-mimpure-text, you should compile all source code with-fpicor-fPIC✨.
-gsctf— generates Solaris CTF 📦. It needs to be used for both compilation and linking 🔗. Seectf(7)for more information 📖. This is only supported since Solaris 11.4 SRU 84, where the necessary toolchain support was added 🎉.
🌈 SPARC Options 🌈
These -m options are supported on the SPARC 🦋:
-mno-app-regs,-mapp-regs—-mapp-regsgenerates output using the global registers 2 through 4, which the SPARC SVR4 ABI reserves for applications 🎀. Like global register 1, each of global registers 2 through 4 is then treated as an allocable register that gets clobbered by function calls 💅. This is the default.
To be fully SVR4 ABI-compliant (with some performance loss) use -mno-app-regs 🫶. You should compile libraries and system software with this option 📚.
-mflat,-mno-flat— with-mflat, the compiler doesn't generate 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 are 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 containing floating-point instructions 🔥. This is the default 👑.-mno-fpu,-msoft-float— generates output containing library calls for floating point 📞.
Warning ⚠️: the requisite libraries are not available for all SPARC targets 😬. Normally the facilities of the machine's usual C compiler are used, but this can't be done directly in cross-compilation 🙃. You must 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 containing quad-word (long double) floating-point instructions 💫.-msoft-quad-float— generates output containing library calls for quad-word (long double) floating-point instructions 📚. The functions called are the ones specified in the SPARC ABI, and 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 of the instruction 🫠. Because of that trap handler overhead, this is much slower than calling the ABI library routines 🐢. That's why -msoft-quad-float is the default 💜.
-mno-unaligned-doubles,-munaligned-doubles—-mno-unaligned-doublesassumes that doubles have 8-byte alignment. This is the default 📏.
With -munaligned-doubles, GCC assumes doubles have 8-byte alignment only if they're contained in another type or have an absolute address 🧐. Otherwise, it assumes they have 4-byte alignment 🤏. Using this option avoids some rare compatibility problems with code generated by other compilers 🫶. It isn't the default because it causes a performance loss, especially for floating-point code 📉.
-muser-mode,-mno-user-mode—-mno-user-modedoesn't generate code that can only run in supervisor mode 🙅. This only matters for thecasainstruction emitted for the LEON3 processor 🧠. This is the default ✨.-mfaster-structs,-mno-faster-structs— with-mfaster-structs, the compiler assumes structures should have 8-byte alignment 📐. This enables pairs oflddandstdinstructions for copies in structure assignment, in place of twice as manyldandstpairs 🏎️. However, this changed alignment directly violates the SPARC ABI 🚫. So it's only meant for targets where the developer acknowledges their resulting 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 returning structures or unions to detect 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 🚫.-mcpu=cpu_type— sets the instruction set, register set, and instruction scheduling parameters for the machine type cpu_type 🖥️. Supported values forcpu_typearev7,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 are 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,leon3v7🌷v8—supersparc,hypersparc,leon,leon3,leon5🍓sparclite—f930,f934,sparclite86x🦋sparclet—tsc701🧚v9—ultrasparc,ultrasparc3,niagara,niagara2,niagara3,niagara4,niagara7,m8👑
By default (unless it's been configured otherwise), GCC cooks up code for the V7 flavour of SPARC 🌸 Add -mcpu=cypress and it also gets tuned for the Cypress CY7C602 chip, the one living in the SPARCStation/SPARCServer 3xx series 💅 It's also a great fit for the older SPARCStation 1, 2, IPX etc. 🫶
With -mcpu=v8, GCC generates code for the V8 variant of SPARC ✨ The only real 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 🔥 Add -mcpu=supersparc and it's additionally optimized for the SuperSPARC chip, the one 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. Then -mcpu=f930 further optimizes it for the Fujitsu MB86930 chip, which is the original SPARClite and has no FPU 🙈 And -mcpu=f934 optimizes it for the Fujitsu MB86934 chip, the more recent SPARClite that does have an FPU 🦋
With -mcpu=sparclet, GCC generates code for the SPARClet variant of SPARC 💜 This adds the integer multiply, multiply/accumulate, integer divide step and scan ("ffs") instructions that exist in SPARClet but not in SPARC-V7. Add -mcpu=tsc701 and it's optimized for the TEMIC SPARClet chip 🎀
With -mcpu=v9, GCC generates code for the V9 variant of SPARC, and it's giving upgrade 🌈 This adds 64-bit integer and floating-point move instructions, 3 additional floating-point condition code registers and conditional move instructions. Then:
-mcpu=ultrasparcoptimizes for the Sun UltraSPARC I/II/IIi chips 💖-mcpu=ultrasparc3optimizes for the Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips ✨-mcpu=niagaraoptimizes for Sun UltraSPARC T1 chips 🍓-mcpu=niagara2optimizes for Sun UltraSPARC T2 chips 🌸-mcpu=niagara3optimizes for Sun UltraSPARC T3 chips 🦋-mcpu=niagara4optimizes for Sun UltraSPARC T4 chips 💅-mcpu=niagara7optimizes for Oracle SPARC M7 chips 👑-mcpu=m8optimizes for Oracle M8 chips 🔥-mtune=cpu_type— sets the instruction scheduling parameters for machine typecpu_type, but it does not touch the instruction set or register set the way-mcpu=cpu_typedoes 🧁
The same values you can use for -mcpu=cpu_type work for -mtune=cpu_type, but only the ones that pick out a particular CPU implementation are actually useful: 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 also be used 🫶
Hmm, the bullet list for -mcpu was list items with chips; fine—they're not option lists exactly. Good.
Continue with the rest. Ensure "-mcpu=v9..." list, "-mtune" bullets, etc. Write final.With -mcpu=v8, GCC generates code for the V8 variant of SPARC ✨ The only real 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 🔥 Add -mcpu=supersparc and it's also optimized for the SuperSPARC chip, the one 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. Then -mcpu=f930 further optimizes it for the Fujitsu MB86930 chip, the original SPARClite, which has no FPU 🙈 And -mcpu=f934 optimizes it for the Fujitsu MB86934 chip, the more recent SPARClite with an FPU 🦋
With -mcpu=sparclet, GCC generates code for the SPARClet variant of SPARC 💜 This adds the integer multiply, multiply/accumulate, integer divide step and scan ("ffs") instructions that exist in SPARClet but not in SPARC-V7. Add -mcpu=tsc701 and it's optimized for the TEMIC SPARClet chip 🎀
With -mcpu=v9, GCC generates code for the V9 variant of SPARC, and it's giving upgrade 🌈 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 flavours go like this:
-mcpu=ultrasparcoptimizes for the Sun UltraSPARC I/II/IIi chips 💖-mcpu=ultrasparc3optimizes for the Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips ✨-mcpu=niagaraoptimizes for Sun UltraSPARC T1 chips 🍓-mcpu=niagara2optimizes for Sun UltraSPARC T2 chips 🌸-mcpu=niagara3optimizes for Sun UltraSPARC T3 chips 🦋-mcpu=niagara4optimizes for Sun UltraSPARC T4 chips 💅-mcpu=niagara7optimizes for Oracle SPARC M7 chips 👑-mcpu=m8optimizes for Oracle M8 chips 🔥-mtune=cpu_type— sets the instruction scheduling parameters for machine typecpu_type, but it does not set the instruction set or register set the way-mcpu=cpu_typedoes 🧁
The same values you can use for -mcpu=cpu_type work for -mtune=cpu_type, but only the ones that pick out a particular CPU implementation are actually useful: 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 also be used 🫶
-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 treated as 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 takes advantage of the UltraSPARC Visual Instruction Set extensions 🌈 The default is-mno-vis.-mvis2,-mno-vis2— with-mvis2, GCC takes advantage of version 2.0 of the UltraSPARC Visual Instruction Set extensions 💜 The default is-mvis2when targeting a cpu that supports such instructions, such as UltraSPARC-III and later. Setting-mvis2also sets-mvis.-mvis3,-mno-vis3— with-mvis3, GCC takes advantage of version 3.0 of the UltraSPARC Visual Instruction Set extensions 🦋 The default is-mvis3when targeting a cpu that supports such instructions, such as niagara-3 and later. Setting-mvis3also sets-mvis2and-mvis.-mvis3b,-mno-vis3b— with-mvis3b, GCC takes advantage of version 3.0 of the UltraSPARC Visual Instruction Set extensions, plus the additional VIS instructions introduced in the Oracle SPARC Architecture 2011 🔥 The default is-mvis3bwhen targeting a cpu that supports such instructions, such as niagara-7 and later. Setting-mvis3balso sets-mvis3,-mvis2and-mvis.-mvis4,-mno-vis4— with-mvis4, GCC takes advantage of version 4.0 of the UltraSPARC Visual Instruction Set extensions 👑 The default is-mvis4when targeting a cpu that supports such instructions, such as niagara-7 and later. Setting-mvis4also sets-mvis3b,-mvis3,-mvis2and-mvis.-mvis4b,-mno-vis4b— with-mvis4b, GCC takes advantage of version 4.0 of the UltraSPARC Visual Instruction Set extensions, plus the additional VIS instructions introduced in the Oracle SPARC Architecture 2017 🌸 The default is-mvis4bwhen targeting a cpu that supports such instructions, such as m8 and later. Setting-mvis4balso sets-mvis4,-mvis3b,-mvis3,-mvis2and-mvis.-mcbcond,-mno-cbcond— with-mcbcond, GCC takes advantage of the UltraSPARC Compare-and-Branch-on-Condition instructions 🍓 The default is-mcbcondwhen targeting a CPU that supports such instructions, such as Niagara-4 and later.-mfmaf,-mno-fmaf— with-mfmaf, GCC takes advantage of the UltraSPARC Fused Multiply-Add Floating-point instructions ✨ The default is-mfmafwhen targeting a CPU that supports such instructions, such as Niagara-3 and later.-mfsmuld,-mno-fsmuld— with-mfsmuld, GCC takes advantage of the Floating-point Multiply Single to Double (FsMULd) instruction 💖 The default is-mfsmuldwhen targeting a CPU supporting the architecture versions V8 or V9 with FPU, except-mcpu=leon.-mpopc,-mno-popc— with-mpopc, GCC takes advantage of the UltraSPARC Population Count instruction 🧁 The default is-mpopcwhen targeting a CPU that supports such an instruction, such as Niagara-2 and later.-msubxc,-mno-subxc— with-msubxc, GCC takes advantage of the UltraSPARC Subtract-Extended-with-Carry instruction 💅 The default is-msubxcwhen targeting a CPU that supports such an instruction, such as Niagara-7 and later.-mfix-at697f— enables the documented workaround for the single erratum of the Atmel AT697F processor (which corresponds to erratum #13 of the AT697E processor) 🛠️-mfix-ut699— enables the documented workarounds for the floating-point errata and the data cache nullify errata of the UT699 processor 🛠️-mfix-ut700— enables the documented workaround for the back-to-back store errata of the UT699E/UT700 processor 🛠️-mfix-gr712rc— enables 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— generates code for a 32-bit or 64-bit environment 🎀 The 32-bit environment setsint,longand pointer to 32 bits. The 64-bit environment setsintto 32 bits andlongand pointer to 64 bits.-mptr32,-mptr64— uses 32- or 64-bit pointers, respectively 💜 Unlike the-m32and-m64options, this only affects the pointer size and not the ABI.-mcmodel=which— sets the code model to one of the following 🦋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 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 may 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 starting anywhere in memory (determined 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— sets the memory model in force on the processor to one of the following 🧠default— the default memory model for the processor and operating system.rmo— Relaxed Memory Orderpso— Partial Store Ordertso— Total Store Ordersc— 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 that the stack pointer, and frame pointer if present, are offset by-2047, which must be added back when making stack frame references. This is the default in 64-bit mode. Otherwise, it 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 is recommended that-symbolicor-sharedbe used instead. 💅-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— Skips (or turns on) the optimization that copies a pointer into theepregister when a basic block uses the same index pointer 4 or more times, which also lets the compiler use the shortersldandsstinstructions.-mepis on by default when you optimize. 🌸-mno-prolog-function,-mprolog-function— Stops (or starts) using external functions to save and restore registers in a function's prologue and epilogue. Those helper functions are slower, but they take up less code space when more than one function saves the same number of registers.-mprolog-functionis on by default when you optimize. 💅-mspace— Tries to make the code as tiny as possible. Right now it only switches on-mepand-mprolog-function. 🧚-mtda=n— Puts static or global variables that arenbytes or smaller into the tiny data area that theepregister points to. That area holds up to 256 bytes total, or 128 bytes for byte references. 🦋-msda=n— Puts static or global variables that arenbytes or smaller into the small data area that thegpregister points to. That area can hold up to 64 kilobytes. ✨-mzda=n— Puts static or global variables that arenbytes or smaller into the first 32 kilobytes of memory. 🎀-mv850— Tells GCC the target processor is the V850. 🌈-mv850e3v5— Tells GCC the target processor is the V850E3V5. The preprocessor constant__v850e3v5__gets defined when you use this. 👑-mv850e2v4— Tells GCC the target processor is the V850E3V5. It's an alias for-mv850e3v5. 🫶-mv850e2v3— Tells GCC the target processor is the V850E2V3. The preprocessor constant__v850e2v3__gets defined when you use this. 🔥-mv850e2— Tells GCC the target processor is the V850E2. The preprocessor constant__v850e2__gets defined when you use this. 💜-mv850e1— Tells GCC the target processor is the V850E1. The preprocessor constants__v850e1__and__v850e__get defined when you use this. 🍓-mv850es— Tells GCC the target processor is the V850ES. It's an alias for-mv850e1. 🌸-mv850e— Tells GCC the target processor is the V850E. The preprocessor constant__v850e__gets defined when you use this. ⭐
If none of -mv850, -mv850e, -mv850e1, -mv850e2, -mv850e2v3 or -mv850e3v5 is set, GCC picks a default target processor and defines the matching __v850*__ preprocessor constant. 🧚
The preprocessor constants __v850 and __v851__ are always defined, no matter which processor variant you're targeting. 💖
-mdisable-callt,-mno-disable-callt— Suppresses generation of theCALLTinstruction for the v850e, v850e1, v850e2, v850e2v3 and v850e3v5 flavors of the v850 architecture. This is on by default when the RH850 ABI is in use (see-mrh850-abi) and off by default when the GCC ABI is in use. IfCALLTinstructions are being generated, the C preprocessor symbol__V850_CALLT__gets defined. 🙈-mrelax,-mno-relax— Passes (or doesn't pass) the-mrelaxcommand-line option along to the assembler. 🦋-mlong-jumps,-mno-long-jumps— Turns off (or back on) generating PC-relative jump instructions. ✨-msoft-float,-mhard-float— Turns off (or back on) generating hardware floating point instructions. This only matters when the target architecture is V850E2V3 or higher. If hardware floating point instructions are being generated, the C preprocessor symbol__FPU_OK__gets defined. Otherwise,__NO_FPU__gets defined. 🌈-mloop— Turns on the e3v5LOOPinstruction. It isn't enabled by default when the e3v5 architecture is selected, because it's still experimental. 🧪-mrh850-abi,-mghs— Turns on support for the RH850 version of the V850 ABI. This is the default. With this ABI version, these rules apply:- Integer sized structures and unions get returned through a memory pointer instead of a register.
- Large structures and unions (more than 8 bytes in size) get passed by value.
- Functions get 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 ABI version is on, the C preprocessor symbol __V850_RH850_ABI__ gets defined. 👑
-mgcc-abi— Turns on support for the old GCC version of the V850 ABI. With this ABI version, these rules apply:- 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 not enabled by default.
When this ABI version is on, the C preprocessor symbol __V850_GCC_ABI__ gets defined. 🫶
-m8byte-align,-mno-8byte-align— Letsdoubleandlong longtypes align on 8-byte boundaries. By default, every object is restricted to at most 4-byte alignment. When-m8byte-alignis in effect, the C preprocessor symbol__V850_8BYTE_ALIGN__gets defined. 💅-mbig-switch,-mno-big-switch— Generates code that works with big switch tables. Only use this if the assembler or linker complains about out of range branches inside a switch table. 😭-mapp-regs,-mno-app-regs—-mapp-regsmakes the compiler user2andr5in the code it generates. This is the default.-mno-app-regsmakesr2andr5fixed registers that the compiler won't touch. 🔥-msmall-sld,-mno-small-sld— Turns on (or off) the use of the short load instructions. 🌸-mno-strict-align— Doesn't enforce strict data alignment. 🍓-mjump-tables-in-data-section,-mno-jump-tables-in-data-section— Puts jump tables forswitchstatements in the.datasection instead of the.codesection (or keeps them in.code). The default is-mno-jump-tables-in-data-section. 🧚
✨ VAX Options ✨
These -m options are defined for the VAX: 🦋
-munix— Doesn't output certain jump instructions (aobleqand so on) that the Unix assembler for the VAX can't handle across long ranges. 🌈-mgnu— Does output those jump instructions, on the assumption that you're using the GNU assembler. ✨-md,-md-float— Uses the D_floating data format for double-precision floating-point numbers instead of G_floating. 💜-mg,-mg-float— Uses the G_floating data format for double-precision floating-point numbers instead of D_floating. 💖-mlra,-mno-lra— Enables Local Register Allocation. It's still experimental for the VAX, so by default the compiler uses standard reload. 🧪-mvaxc-alignment— Uses VAXC conventions for aligning structure members. 🎀-mqmath,-mno-qmath— Turns new instruction patterns for 64-bit integer addition and subtraction on or off. ⭐
✨ Visium Options ✨
-mdebug— Use this when linking programs that do file I/O and are meant to run on an MCM target. It links the librarieslibc.aandlibdebug.a. You should run the program on the target under the control of the GDB remote debugging stub. 🔥-msim— Use this when linking programs that do file I/O and are meant to run on the simulator. It links the librarieslibc.aandlibsim.a. 🍓-mfpu,-mhard-float— Generates code with floating-point instructions. This is the default. 💅-mno-fpu,-msoft-float— Generates code with library calls for floating-point instead. 🙈
-msoft-floatchanges the calling convention in the output file, so it's only useful if you compile your whole program with this option. You also need to compilelibgcc.a(the library that comes with GCC) with-msoft-floatfor this to work. 💀
-mcpu=cpu_type— Sets the instruction set, register set, and instruction scheduling parameters for the machine typecpu_type. Supported values forcpu_typearemcm,gr5andgr6. 👑
mcm is a synonym for gr5, 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 the 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. Possible values forsizeare32orshortfor 32-bit pointers,64orlongfor 64-bit pointers, andnofor supporting only 32-bit pointers. Thenooption 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: Okay so GCC can make code for VxWorks kernels and real time processes (RTPs) 🌸. This flag switches it over to RTPs, and it also defines the preprocessor macro__RTP__✨.-msmp: This picks the SMP runtimes for linking 💜. It's only a thing on PowerPC 🙈 and isn't available on VxWorks version 7 or later. On 7+, the choice is part of the VxWorks build configuration, and the library paths are the same either way 🧚.-mvthreads: Links against the VxWorks AE vThread runtime environment 🦋.-non-static: Links an RTP executable against shared libraries instead of static ones 🔗.-staticand-sharedwork for RTPs too, and-staticis the default 💅.-Bstatic,-Bdynamic: These get passed down to the linker 🫶. They're here for Diab compatibility, so Diab folks feel right at home 🏡.-Xbind-lazy: Turns on lazy binding of function calls 💤. It's equivalent to-Wl,-z,now, and it's defined for Diab compatibility too.-Xbind-now: Turns lazy binding off 🙅. This is the default, and it's also there for Diab compatibility.
✨ x86 Options ✨
This section is all about the -m options for the x86 family of computers 💻.
The next group lets you target a specific processor 🎯.
-march=cpu-type: Generates instructions for the machine type cpu-type 🚀. Quick difference check:-mtune=cpu-typeonly tunes the generated code for that CPU, but-march=cpu-typelets GCC generate code that may not run at all on other processors ⚠️. Specifying-march=cpu-typeimplies-mtune=cpu-type, except where noted otherwise.
The choices for cpu-type are:
native: Picks the CPU to generate code for at compile time by checking the processor type of the machine doing the compiling 🖥️.-march=nativeenables all instruction subsets supported by the local machine, so the result might not run on different machines 💀.-mtune=nativemakes code optimized for the local machine under the constraints of the selected instruction set.x86-64: A generic CPU with 64-bit extensions, MMX, SSE, SSE2, and FXSR instruction set support 🌈.x86-64-v2,x86-64-v3,x86-64-v4: These 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 the x86-64 psABI documents for that micro-architecture level. These values don't have a matching-mtunesetting, so using-marchwith them enables generic tuning. Want specific tuning? Use-mtune=other-cpu-typewith an appropriate other-cpu-type value.i386: Original Intel i386 CPU 🦕.i486: Intel i486 CPU. No scheduling is implemented for this chip.i586,pentium: Intel Pentium CPU with no MMX support.lakemont: Intel Lakemont MCU, based on the Intel Pentium CPU.pentium-mmx: Intel Pentium MMX CPU, based on the Pentium core with MMX instruction set support.pentiumpro: Intel Pentium Pro CPU with no MMX support.i686: With-march, the Pentium Pro instruction set is used, so the code runs on all i686 family chips 🍓. With-mtune, it has the same meaning asgeneric.pentium2: Intel Pentium II CPU, based on the Pentium Pro core with MMX and FXSR instruction set support.pentium3,pentium3m: Intel Pentium III CPU, based on the Pentium Pro core with MMX, FXSR and SSE instruction set support.pentium-m: 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: Intel Pentium 4 CPU with MMX, SSE, SSE2 and FXSR instruction set support.prescott: An improved Intel Pentium 4 CPU with MMX, SSE, SSE2, SSE3 and FXSR instruction set support ⭐.nocona: An improved Intel Pentium 4 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and FXSR instruction set support ⭐.core2: Intel Core 2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, CX16, SAHF and FXSR instruction set support 💜.nehalem,corei7: 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: 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,corei7-avx: 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,core-avx-i: 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,core-avx2: Intel Haswell CPU with 64-bit extensions, 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 with 64-bit extensions, 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 and PREFETCHW instruction set support 💅.skylake: Intel Skylake CPU with 64-bit extensions, 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 and SGX instruction set support 👑.skylake-avx512: Intel Skylake Server CPU with 64-bit extensions, 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 and AVX512CD instruction set support 🔥.cascadelake: Intel Cascade Lake CPU with 64-bit extensions, 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 and AVX512VNNI instruction set support 🌈.cannonlake: Intel Cannon Lake Server CPU with 64-bit extensions, 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 and SHA instruction set support 🧊.cooperlake: Intel Cooper Lake CPU with 64-bit extensions, 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, AVX512VNNI and AVX512BF16 instruction set support 🫶.icelake-client: Intel Ice Lake Client CPU with 64-bit extensions, 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 and AVX512VPOPCNTDQ instruction set support 🧊.icelake-server: Intel Ice Lake Server CPU with 64-bit extensions, 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 and CLWB instruction set support 🧊.tigerlake: Intel Tiger Lake CPU with 64-bit extensions, 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, AVX512VP2INTERSECT and KEYLOCKER instruction set support 🦋.rocketlake: Intel Rocket Lake CPU with 64-bit extensions, 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, RDPID and AVX512VPOPCNTDQ instruction set support 🌸.
alderlake,raptorlake,meteorlake,gracemont: Intel Alder Lake/Raptor Lake/Meteor Lake/Gracemont CPUs, which come with 64-bit extensions, MOVBE, 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, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL and AVX-VNNI instruction set support. 💖✨arrowlake: Intel Arrow Lake CPU 🦋, with 64-bit extensions, MOVBE, 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, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, KL, WIDEKL, AVX-VNNI, UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT and CMPCCXADD instruction set support. 👑arrowlake-s,lunarlake: Intel Arrow Lake S/Lunar Lake CPUs, which come with 64-bit extensions, MOVBE, 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, 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 and SM4 instruction set support. 🌈pantherlake,wildcatlake: Intel Panther Lake/Wildcat Lake CPUs with 64-bit extensions, MOVBE, 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, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, AVX-VNNI, UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, SM3 and SM4 instruction set support. 🧚novalake: Intel Nova Lake CPU with 64-bit extensions, MOVBE, 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, WAITPKG, ADCX, AVX, AVX2, BMI, BMI2, F16C, FMA, LZCNT, PCONFIG, PKU, VAES, VPCLMULQDQ, SERIALIZE, HRESET, AVX-VNNI, UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, SM3, SM4, PREFETCHI, APX_F, AVX10.1, AVX10.2 and MOVRS instruction set support. 🌸sapphirerapids,emeraldrapids: Intel Sapphire Rapids/Emerald Rapids CPUs with 64-bit extensions, 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 and AVX512BF16 instruction set support. 💅graniterapids: Intel Granite Rapids CPU with 64-bit extensions, 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-FP16 and PREFETCHI instruction set support. 🔥graniterapids-d: Intel Granite Rapids D CPU with 64-bit extensions, 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, PREFETCHI and AMX-COMPLEX instruction set support. 🦋diamondrapids: Intel Diamond Rapids 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, 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, PREFETCHI, AMX-COMPLEX, AVX10.1-512, AVX-IFMA, AVX-NE-CONVERT, AVX-VNNI-INT16, AVX-VNNI-INT8, CMPccXADD, SHA512, SM3, SM4, AVX10.2-512, APX_F, AMX-AVX512, AMX-FP8, AMX-TF32, MOVRS and AMX-MOVRS instruction set support. 👑✨bonnell,atom: Intel Bonnell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3 and SSSE3 instruction set support. 🍓silvermont,slm: Intel Silvermont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, PCLMUL, PREFETCHW and RDRND instruction set support. 🎀goldmont: Intel Goldmont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, CX16, SAHF, FXSR, PCLMUL, PREFETCHW, RDRND, AES, SHA, RDSEED, XSAVE, XSAVEC, XSAVES, XSAVEOPT, CLFLUSHOPT and FSGSBASE instruction set support. 🌈goldmont-plus: Intel Goldmont Plus CPU with 64-bit extensions, MOVBE, 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 and SGX instruction set support. ⭐tremont: Intel Tremont CPU with 64-bit extensions, MOVBE, 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, CLDEMOTE and WAITPKG instruction set support. 💜sierraforest: Intel Sierra Forest CPU with 64-bit extensions, MOVBE, 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, ENQCMD and UINTR instruction set support. 🦋grandridge: Intel Grand Ridge CPU with 64-bit extensions, MOVBE, 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, ENQCMD and UINTR instruction set support. 🧚clearwaterforest: Intel Clearwater Forest CPU with 64-bit extensions, MOVBE, 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, AVX-VNNI, ENQCMD, UINTR, AVXIFMA, AVXVNNIINT8, AVXNECONVERT, CMPCCXADD, AVXVNNIINT16, SHA512, SM3, SM4, USER_MSR and PREFETCHI instruction set support. 💅k6: AMD K6 CPU with MMX instruction set support. 🌸k6-2,k6-3: Improved versions of AMD K6 CPU with MMX and 3DNow! instruction set support. ✨athlon,athlon-tbird: AMD Athlon CPU with MMX, 3dNOW!, enhanced 3DNow! and SSE prefetch instructions support. 🔥athlon-4,athlon-xp,athlon-mp: Improved AMD Athlon CPU with MMX, 3DNow!, enhanced 3DNow! and full SSE instruction set support. 👑k8,opteron,athlon64,athlon-fx: Processors based on the AMD K8 core with x86-64 instruction set support, including the AMD Opteron, Athlon 64, and Athlon 64 FX processors. (This supersets MMX, SSE, SSE2, 3DNow!, enhanced 3DNow! and 64-bit instruction set extensions.) 🧚k8-sse3,opteron-sse3,athlon64-sse3: Improved versions of AMD K8 cores with SSE3 instruction set support. 🫶amdfam10,barcelona: CPUs based on AMD Family 10h cores with x86-64 instruction set support. (This supersets MMX, SSE, SSE2, SSE3, SSE4A, 3DNow!, enhanced 3DNow!, ABM and 64-bit instruction set extensions.) 🌈bdver1— CPUs built on AMD Family 15h cores with x86-64 support 💖 (This supersets FMA4, AVX, XOP, LWP, AES, PCLMUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set extensions.)bdver2— AMD Family 15h core CPUs with x86-64 support 🦋 (This supersets BMI, TBM, F16C, FMA, FMA4, AVX, XOP, LWP, AES, PCLMUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set extensions.)bdver3— AMD Family 15h core CPUs with x86-64 support ✨ (This supersets BMI, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, XOP, LWP, AES, PCLMUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set extensions.)bdver4— AMD Family 15h core CPUs with x86-64 support 🌸 (This supersets BMI, BMI2, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, AVX2, XOP, LWP, AES, PCLMUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set extensions.)znver1— AMD Family 17h core CPUs with x86-64 support 👑 (This supersets BMI, 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 CPUs with x86-64 support 🧚 (This supersets BMI, 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 CPUs with x86-64 support 💜 (This supersets BMI, 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 CPUs with x86-64 support 🔥 (This supersets BMI, 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 and 64-bit instruction set extensions.)znver5— AMD Family 1ah core CPUs with x86-64 support 🌈 (This supersets BMI, 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, PREFETCHI and 64-bit instruction set extensions.)znver6— AMD Family 1ah core CPUs with x86-64 support 🦋 (This supersets BMI, 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, PREFETCHI, AVXVNNIINT8, AVXIFMA, AVX512FP16, AVXNECONVERT, AVX512BMM and 64-bit instruction set extensions.)btver1— CPUs built on AMD Family 14h cores with x86-64 support 🍓 (This supersets MMX, SSE, SSE2, SSE3, SSSE3, SSE4A, CX16, ABM and 64-bit instruction set extensions.)btver2— CPUs built on AMD Family 16h cores with x86-64 support 🫶 This includes MOVBE, F16C, BMI, AVX, PCLMUL, AES, SSE4.2, SSE4.1, CX16, ABM, SSE4A, SSSE3, SSE3, SSE2, SSE, MMX and 64-bit instruction set extensions.winchip-c6— IDT WinChip C6 CPU 💅 It's handled exactly like i486, plus extra MMX instruction set support.winchip2— IDT WinChip 2 CPU 🎀 It's handled exactly like i486, plus extra MMX and 3DNow! instruction set support.c3— VIA C3 CPU with MMX and 3DNow! instruction set support 🌸 (No scheduling is implemented for this chip.)c3-2— VIA C3-2 (Nehemiah/C5XL) CPU with MMX and SSE instruction set support 💖 (No scheduling is implemented for this chip.)c7— VIA C7 (Esther) CPU with MMX, SSE, SSE2 and SSE3 instruction set support ✨ (No scheduling is implemented for this chip.)samuel-2— VIA Eden Samuel 2 CPU with MMX and 3DNow! instruction set support 🦋 (No scheduling is implemented for this chip.)nehemiah— VIA Eden Nehemiah CPU with MMX and SSE instruction set support 🧚 (No scheduling is implemented for this chip.)esther— VIA Eden Esther CPU with MMX, SSE, SSE2 and SSE3 instruction set support 💜 (No scheduling is implemented for this chip.)eden-x2— VIA Eden X2 CPU with x86-64, MMX, SSE, SSE2 and SSE3 instruction set support 🔥 (No scheduling is implemented for this chip.)eden-x4— VIA Eden X4 CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX and AVX2 instruction set support 🌈 (No scheduling is implemented for this chip.)nano— Generic VIA Nano CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3 instruction set support 👑 (No scheduling is implemented for this chip.)nano-1000— VIA Nano 1xxx CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3 instruction set support 🍓 (No scheduling is implemented for this chip.)nano-2000— VIA Nano 2xxx CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3 instruction set support 🫶 (No scheduling is implemented for this chip.)nano-3000— VIA Nano 3xxx CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1 instruction set support 💅 (No scheduling is implemented for this chip.)nano-x2— VIA Nano Dual Core CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1 instruction set support 🎀 (No scheduling is implemented for this chip.)nano-x4— VIA Nano Quad Core CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1 instruction set support 🌸 (No scheduling is implemented for this chip.)lujiazui— ZHAOXIN lujiazui CPU with x86-64, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PCLMUL, RDRND, XSAVE, XSAVEOPT, FSGSBASE, CX16, ABM, BMI, BMI2, FXSR, RDSEED instruction set support 💖 The CPUs do support AVX and F16C, but-march=lujiazuidoesn't turn these on, "for performance reasons."yongfeng— ZHAOXIN yongfeng CPU with x86-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, LZCNT instruction set support ✨shijidadao— ZHAOXIN shijidadao CPU with x86-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, LZCNT instruction set support 🧚geode— AMD Geode embedded processor with MMX and 3DNow! instruction set support 🌈
✨ -mtune=cpu-type ✨
Tune cpu-type for everything that applies to the generated code, except the ABI and the set of available instructions 🎀 Picking a specific cpu-type schedules things nicely for that exact chip, but the compiler won't spit out code that can't run on the default machine type unless you also use a -march=cpu-type option. For example, if GCC is configured for i686-pc-linux-gnu, then -mtune=pentium4 makes code tuned for Pentium 4 that still runs on i686 machines 💅
The choices for cpu-type are the same as for -march. On top of those, -mtune supports 2 extra choices for cpu-type:
generic— Optimizes for the most common IA32/AMD64/EM64T processors 💜 If you know exactly which CPU your code will run on, use the matching-mtuneor-marchoption instead of-mtune=generic. But if you have no clue what CPUs your users will have, this is the one to use 🫶
As new processors hit the market, the behavior of this option changes. So if you upgrade to a newer GCC, code generation under this option will shift to match the processors that are most popular when that GCC version gets released 🌸
There's no -march=generic option, because -march describes the instruction set the compiler can use, and there's no generic instruction set that fits every processor. -mtune, on the other hand, describes the processor (or, in this case, the whole collection of processors) that the code is optimized for ✨
intel— Optimizes for the most current Intel processors, which are Haswell and Silvermont for this version of GCC 🔥 If you know which CPU your code will run on, use the matching-mtuneor-marchoption instead of-mtune=intel. But if you want your application to perform better on both Diamond Rapids and Clearwater Forest, this is the option you want 👑
As new Intel processors hit the market, this option's behavior is going to change 🔄. So if you upgrade to a newer GCC, the code generated by this option will shift to match the newest Intel chips available when that GCC version comes out ✨.
There's no -march=intel option, bestie 🙅♀️. -march controls the instruction set the compiler is allowed to use, and there's no single instruction set that every Intel processor shares. -mtune is different: it tells GCC which processor (or, in this case, group of processors) the code is optimized for 💅.
The following options give you more detailed control over which instruction set extensions GCC targets 🎀. Each one has a matching -mno- option that turns those instructions off 💖.
These extensions are also available as built-in functions. Check out x86 Built-in Functions for the details on which functions get enabled and disabled by these switches 🧚.
These options let GCC use the extended instructions in generated code. Apps that do run-time CPU detection have to compile separate files for each supported architecture, using the right flags 🫶.
Heads up 🙈: the file containing the CPU detection code should be compiled without these options.
To control whether 387 or SSE/AVX instructions get generated automatically for floating-point arithmetic, see -mfpmath=, below 📐.
-mmmx— Turns on MMX built-in functions 🌸.-msse— Turns on MMX and SSE built-in functions and code generation 🦋.-msse2— Turns on MMX, SSE and SSE2 built-in functions and code generation ✨.-msse3— Turns on MMX, SSE, SSE2 and SSE3 built-in functions and code generation ✨.-mssse3— Turns on MMX, SSE, SSE2, SSE3 and SSSE3 built-in functions and code generation ✨.-msse4.1— Turns on MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1 built-in functions and code generation ✨.-msse4.2— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1 and SSE4.2 built-in functions and code generation ✨.-msse4— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1 and SSE4.2 built-in functions and code generation 👑.
Quick note 📝:-msse4turns on both SSE4.1 and SSE4.2 support, while-mno-sse4turns those features off. Neither form of the option touches SSE4A support, which is controlled separately by-msse4a.
-msse4a— Turns on MMX, SSE, SSE2, SSE3 and SSE4A built-in functions and code generation 🌈.-mavx— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2 and AVX built-in functions and code generation 🔥.-mavx2— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX and AVX2 built-in functions and code generation 🔥.-mavx512f— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2 and AVX512F built-in functions and code generation 💜.-mavx512cd— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512CD built-in functions and code generation 💜.-mavx512vl— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512VL built-in functions and code generation 💜.-mavx512bw— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512BW built-in functions and code generation 💜.-mavx512dq— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512DQ built-in functions and code generation 💜.-mavx512ifma— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512IFMA built-in functions and code generation 💜.-mavx512vbmi— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512VBMI built-in functions and code generation 💜.-mavx512vpopcntdq— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512VPOPCNTDQ built-in functions and code generation 💜.-mavx512vp2intersect— Turns on AVX512VP2INTERSECT built-in functions and code generation 🦋.-mavx512vnni— Turns on AVX512VNNI built-in functions and code generation 🦋.-mavx512vbmi2— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512VBMI2 built-in functions and code generation 💜.-mavx512bf16— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512BF16 built-in functions and code generation 💜.-mavx512fp16— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512-FP16 built-in functions and code generation 💜.-mavx512bitalg— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX512F and AVX512BITALG built-in functions and code generation 💜.-mavx512bmm— Turns on AVX512BMM built-in functions and code generation 🦋.-mavxvnni— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, and AVXVNNI built-in functions and code generation 🌸.-mavxifma— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, and AVXIFMA built-in functions and code generation 🌸.-mavxvnniint8— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2 and AVXVNNIINT8 built-in functions and code generation 🌸.-mavxneconvert— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, and AVXNECONVERT built-in functions and code generation 🌸.-mavxvnniint16— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2 and AVXVNNIINT16 built-in functions and code generation 🌸.-mavx10.1— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, and AVX10.1 built-in functions and code generation 👑.-mavx10.2— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX10.1 and AVX10.2 built-in functions and code generation 👑.-msha— Turns on SHA1 and SHA256 built-in functions and code generation 🔐.-maes— Turns on AES built-in functions and code generation 🔐.-mpclmul— Turns on PCLMUL built-in functions and code generation 🔐.-mclflushopt— Turns on CLFLUSHOPT instructions 🧹.-mclwb— Turns on the CLWB instruction 🧹.-mfsgsbase— Turns on FSGSBASE built-in functions and code generation 🧠.-mptwrite— Turns on PTWRITE built-in functions and code generation 🧠.-mrdrnd— Turns on RDRND built-in functions and code generation 🎲.-mf16c— Turns on F16C built-in functions and code generation 🧠.-mfma— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX and FMA built-in functions and code generation 🔥.-mfma4— Turns on FMA4 built-in functions and code generation 🔥.-mpconfig— Turns on PCONFIG built-in functions and code generation ⚙️.-mwbnoinvd— Turns on WBNOINVD built-in functions and code generation ⚙️.-mprfchw— Turns on the PREFETCHW instruction 🏎️.-mrdpid— Turns on RDPID built-in functions and code generation 🆔.-mrdseed— Turns on the RDSEED instruction 🎲.-msgx— Turns on SGX built-in functions and code generation 🔒.-mxop— Turns on XOP built-in functions and code generation 🧚.-mlwp— Turns on LWP built-in functions and code generation 🧚.-m3dnow— Turns on 3DNow! built-in functions 🕹️.-m3dnowa— Turns on Athlon 3Dnow! built-in functions 🕹️.-mpopcnt— Turns on code generation for the popcnt instruction 🔢.-mabm— Turns on code generation for Advanced Bit Manipulation (ABM) instructions 🔢.-madx— Turns on flag-preserving add-carry instructions ➕.-mbmi— Turns on BMI built-in functions and code generation 🔢.-mbmi2— Turns on BMI2 built-in functions and code generation 🔢.-mlzcnt— Turns on the LZCNT built-in function and code generation 🔢.-mfxsr— Turns on FXSAVE and FXRSTOR instructions 💾.-mxsave— Turns on XSAVE and XRSTOR instructions 💾.-mxsaveopt— Turns on the XSAVEOPT instruction 💾.-mxsavec— Turns on XSAVEC instructions 💾.-mxsaves— Turns on XSAVES and XRSTORS instructions 💾.-mrtm— Turns on RTM built-in functions and code generation 🧵.-mhle— Turns on Hardware Lock Elision prefixes 🧵.-mtbm— Turns on TBM built-in functions and code generation 🔢.-mmwaitx— Turns on MWAITX and MONITORX built-in functions and code generation ⏳.-mclzero— Turns on CLZERO built-in functions and code generation 🧹.-mpku— Turns on PKU built-in functions and code generation 🔑.-mgfni— Turns on GFNI built-in functions and code generation 🔐.-mvaes— Turns on VAES built-in functions and code generation 🔐.-mwaitpkg— Turns on WAITPKG built-in functions and code generation ⏳.-mvpclmulqdq— Turns on VPCLMULQDQ built-in functions and code generation 🔐.-mmovdiri— Turns on MOVDIRI built-in functions and code generation 🚚.-mmovdir64b— Turns on MOVDIR64B built-in functions and code generation 🚚.-menqcmd— Turns on ENQCMD built-in functions and code generation 📨.-muintr— Turns on UINTR built-in functions and code generation 📨.-mtsxldtrk— Turns on TSXLDTRK built-in functions and code generation 🧵.-mcldemote— Turns on CLDEMOTE built-in functions and code generation 🧹.-mserialize— Turns on SERIALIZE built-in functions and code generation 🧵.-mamx-tile— Turns on AMX-TILE built-in functions and code generation 🧱.-mamx-int8— Turns on AMX-INT8 built-in functions and code generation 🧱.-mamx-bf16— Turns on AMX-BF16 built-in functions and code generation 🧱.-mhreset— Turns on HRESET built-in functions and code generation 🔄.-mkl— Turns on KL built-in functions and code generation 🔑.-mwidekl— Turns on WIDEKL built-in functions and code generation 🔑.-mcmpccxadd— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, and CMPCCXADD built-in functions and code generation 🌈.-mamx-fp16— Turns on AMX-FP16 built-in functions and code generation 🧱.-mprefetchi— Turns on PREFETCHI built-in functions and code generation 🏎️.-mraoint— Turns on RAOINT built-in functions and code generation 🧠.-mamx-complex— Turns on AMX-COMPLEX built-in functions and code generation 🧱.-msm3— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX and SM3 built-in functions and code generation 🌸.-msm4— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX and SM4 built-in functions and code generation 🌸.-msha512— Turns on MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX and SHA512 built-in functions and code generation 🌸.-mapxf— Turns on code generation for APX features, including EGPR, PUSH2POP2, NDD, PPX, NF, CCMP and ZU 👑.
Okay bestie, let's get into the x86 extras 🦋✨
-musermsr— slay 💅 this one turns onUSER_MSRbuilt-in functions and code generation 💖-mamx-avx512— the full glow-up 👑 it supports MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2, AVX10.1, AVX10.2 and AMX-AVX512 built-in functions and code generation 🔥-mamx-tf32— adds AMX-TF32 built-in functions and code generation 🌸-mamx-fp8— adds AMX-FP8 built-in functions and code generation 🧚-mmovrs— adds MOVRS built-in functions and code generation 🎀-mamx-movrs— adds AMX-MOVRS built-in functions and code generation 🫶
These extra options are all for the x86 processor family 🌈
🌈 -mfpmath=unit
This one picks which unit does your floating-point math, unit. The choices are:
387— uses the standard 387 floating-point coprocessor that's in most chips, and emulates it on the ones that don't have it 🫧 Code built this way runs almost everywhere 🌍 Temporary results get computed in 80-bit precision instead of the precision the type asks for, so you can get slightly different answers than most other chips. Check out-ffloat-storefor the more detailed deets. This is the default choice for non-Darwin x86-32 targets.sse— uses the scalar floating-point instructions from the SSE instruction set 💫 Pentium III and newer chips have it, and on the AMD side it's Athlon-4, Athlon XP and Athlon MP chips. The earlier SSE version only handles single-precision arithmetic, so double and extended-precision still go through 387. A later version, found only in Pentium 4 and AMD x86-64 chips, handles double-precision too. For the x86-32 compiler you need-march=cpu-type,-msseor-msse2to turn on the SSE extensions and make this option work. For the x86-64 compiler those extensions are on by default. The result should be considerably faster in most cases and dodge the numerical instability problems of 387 code 🏃♀️ but it might break existing code that expects temporaries to be 80 bits 💀 This is the default choice for the x86-64 compiler, Darwin x86-32 targets, and x86-32 targets with the SSE2 instruction set when-ffast-mathis enabled. Also, GCC switches SSE instructions off when-mavx(or another option enabling AVX extensions) is used. Instead it generates new AVX instructions, or AVX equivalents for all SSE instructions, when needed.sse,387,sse+387,both— tries to use both instruction sets at once 🧠 This effectively doubles the number of available registers, and on chips with separate execution units for 387 and SSE, it doubles the execution resources too. Use this with care! It's still experimental, because the GCC register allocator doesn't model separate functional units well, which leads to unstable performance 😭
-mieee-fp,-mno-ieee-fp— controls 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— generates output containing 80387 instructions for floating point 🔥-mno-80387,-msoft-float— generates output containing library calls for floating point 📚
Warning: the requisite libraries are not part of GCC! 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 be emitted even if -msoft-float is used 🙈
-mno-fp-ret-in-387— stops using the FPU registers for function return values 🫠 The usual calling convention has functions returnfloatanddoublevalues in an FPU register, even when there's no FPU, since the operating system is supposed to emulate one.-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 one stops GCC from generating them 🧚 It gets overridden when-marchsays the target CPU always has an FPU, since then the instruction doesn't need emulating. These instructions aren't generated unless you also use the-funsafe-math-optimizationsswitch.-malign-double,-mno-align-double— controls whether GCC alignsdouble,long double, andlong longvariables on a two-word boundary or a one-word boundary 📏 Aligningdoublevariables on a two-word boundary makes code run somewhat faster on a Pentium, but at the expense of more memory. On x86-64,-malign-doubleis on by default.
Warning: if you use -malign-double, structures containing the above types get aligned differently than the published application binary interface specifications for x86-32, so they aren't 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 says the size is 96 bits, so-m96bit-long-doubleis the default in 32-bit mode. Modern architectures (Pentium and newer) preferlong doublealigned to an 8- or 16-byte boundary, but 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 specifies thatlong doubleis aligned on a 16-byte boundary. Heads up: neither of these options enables any extra precision over the x87 standard of 80 bits for along double.
Warning: if you override the default value for your target ABI, this changes the size of structures and arrays containinglong doublevariables, and also modifies the function calling convention for functions takinglong double. Hence they aren't binary-compatible with code compiled without that switch 🫣
-mlong-double-64— controls the size of thelong doubletype 🎀 A size of 64 bits makeslong doubleequivalent todouble. This is the default for the 32-bit Bionic C library.-mlong-double-80— part of the same family of switches that set the size oflong double, alongside the two around it 🍓-mlong-double-128— a size of 128 bits makeslong doubleequivalent to__float128. This 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, and also modifies the function calling convention for functions takinglong double. Hence 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 bigger than threshold get placed in large data sections 📦 The default is65535.-mrtd— switches to a different function-calling convention 🔄 In it, functions that take a fixed number of arguments return with theret numinstruction, which pops their arguments as they return. That saves one instruction in the caller, since there's no need to pop the arguments there. You can make an individual function use this calling sequence with the function attributestdcall, and you can override the-mrtdoption for a function with the function attributecdecl.
Warning: 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 🙅♀️ You must provide function prototypes for all functions that take variable numbers of arguments (including printf), otherwise incorrect code gets 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.) 💀
-mregparm=num— controls how many registers get used to pass integer arguments 🎯 By default, no registers are used to pass arguments, 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, you must build all modules with the same value, including any libraries. That includes the system libraries and startup modules 🧱
-msseregparm— uses SSE register passing conventions forfloatanddoublearguments and return values ✨ You can control this for a specific function with the function attributesseregparm.
Warning: if you use this switch, you must build all modules with the same value, including any libraries. That includes 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, to match the ABI of the Sun Studio compilers until version 12. Only use this option if you need to stay compatible with existing code produced by those earlier compiler versions or older versions of GCC 🕰️-mpc32,-mpc64,-mpc80— okay so these bestie options 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) 🎀.-mpc80rounds them to 64 bits (extended double precision) and it's the default, so it's giving classic 👑. Heads up: once you use one of these, higher precisions aren't available to you as 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 🔥. Ngl though, some math libraries assume extended-precision (80-bit) operations are on by default. Routines in those libraries can lose a lot of accuracy, usually through so-called "catastrophic cancellation" 💀, if you set the precision to less than extended.
-mdaz-ftz,-mno-daz-ftz— the FTZ (flush-to-zero) and DAZ (denormals-are-zero) flags in the MXCSR register are what control floating-point calculations here 🦋. Normally,-Ofast,-ffast-math, or-funsafe-math-optimizationslink in startup code that sets these flags, except when you're building a shared library (-shared) 🌈. Use-mdaz-ftzor-mno-daz-ftzto explicitly turn that setting on or off, no matter what other options GCC gets 💖.-mstackrealign— realigns the stack at entry 🧚. On x86, this generates an alternate prologue and epilogue that realigns the run-time stack when needed. It's how you mix legacy code that keeps 4-byte stack alignment with modern code that keeps 16-byte alignment for SSE compatibility 🫶. See also the attribute"force_align_arg_pointer", which works on individual functions.-mstack-arg-probe— emits stack probing code in the function prologue 🌸.-mpreferred-stack-boundary=num— tries to keep the stack boundary aligned to a 2 raised to num byte boundary 📏. If you don't specify this, the default is4(16 bytes, or 128 bits) 💜.
⚠️ Bestie, this one is dangerous. 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. The x86-64 ABI requires 16-byte stack alignment, so this is ABI incompatible 😭. It's only meant for a controlled environment where stack space is a seriously limited resource. It produces wrong code when functions compiled with 16-byte stack alignment (like functions from a standard library) get called with a misaligned stack, and then SSE instructions can cause misaligned memory access traps 💀. Variable arguments are also handled incorrectly for 16-byte aligned objects (including x87long doubleand__int128), which gives wrong results. You have to build all modules with-mpreferred-stack-boundary=3, including any libraries, and that covers the system libraries and startup modules too 🙅♀️.
-mincoming-stack-boundary=num— assumes the incoming stack is aligned to a 2 raised to num byte boundary 🧸. If you don't specify it, the one set by-mpreferred-stack-boundarygets 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 big run-time performance hits 🐢. 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 at least as aligned as whatever any value on the stack requires. 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 one compiled with a lower one will most likely misalign the stack 😬. Libraries that use callbacks should always stick with the default setting, as recommended.
This extra alignment eats up stack space and usually bumps up code size 📦. If your code is picky about stack space, like embedded systems and operating system kernels, you might want to drop the preferred alignment to -mpreferred-stack-boundary=2 🍓.
-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— fine-grain control of x86 code generation features 🎛️.feature-listis a comma-separated list of feature names. When you specify one, it gets turned on unless it's preceded by^, in which case it gets turned off. See also-mdump-tune-features.
🚨 This one is intended for GCC developers. Using it may lead to code paths that aren't covered by testing, and it can potentially cause compiler ICEs or runtime errors.
-mno-default— turns off all tunable features 🧹. See also-mtune-ctrl=feature-listand-mdump-tune-features.-mcld— makes GCC emit a"cld"instruction in the prologue of functions that use string instructions 🌀. String instructions depend on the DF flag to pick between autoincrement and autodecrement mode. The ABI says DF should be cleared on function entry, but some operating systems don't clear it in their exception dispatchers, so the handler can run with DF set and string instructions go the wrong direction 😵💫. This option can be turned on by default on 32-bit x86 targets if you configure GCC with the--enable-cldconfigure option. In that case, you can suppress generation of"cld"instructions with the-mno-cldcompiler option.-mvzeroupper— makes GCC emit a"vzeroupper"instruction before control flow leaves the function 🧼. This cuts down the AVX-to-SSE transition penalty and removes unnecessary"zeroupper"intrinsics.-mstv,-mno-stv— enable or disable the Scalar to Vectorization pass, which turns 64-bit integer computation into vector ones 💫. This optimization is restricted to-O2and higher.-mprefer-avx128— tells GCC to use 128-bit AVX instructions instead of 256-bit AVX instructions in the auto-vectorizer 🎀.-mprefer-vector-width=opt— tells GCC to use an opt-bit vector width in instructions instead of the default for the selected platform 📐.-mpartial-vector-fp-math,-mno-partial-vector-fp-math— lets GCC generate floating-point operations that might affect the floating-point status flags on partial vectors, where the vector elements live in the low part of the 128-bit SSE register 🧠. Unless you specify-fno-trapping-math, the compiler guarantees correct behavior by sanitizing all input operands so the unused upper part of the vector register is full of zeroes 🧽. 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 🐌. You can fix that 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 to bits 🚚. The valid values are128,256and512.-mstore-max=bits— sets the maximum number of bits that can be stored to memory efficiently to bits 💾. The valid values are128,256and512.none— no extra limitations on GCC beyond whatever the selected platform defines 🤷♀️.128— prefers a 128-bit vector width for instructions 💜.256— prefers a 256-bit vector width for instructions 💙.512— prefers a 512-bit vector width for instructions 🩵.
-mnoreturn-no-callee-saved-registers— optimizes functions with the"noreturn"attribute or the_Noreturnspecifier by not saving the callee-saved registers they use in the function prologue (except for the"BP"register) 🪄. This can mess with debugging the caller of the"noreturn"function, or any function further up the call stack, so it's not enabled by default ⚠️.-mcx16— lets GCC generate"CMPXCHG16B"instructions in 64-bit code to do compare-and-exchange operations on 16-byte aligned 128-bit objects 🔐. This is handy for atomic updates of data structures bigger than one machine word. The compiler uses this instruction to implement__syncbuiltins. For__atomicbuiltins operating on 128-bit integers, though, a library call is always used 📞.-msahf— enables generation of"SAHF"instructions in 64-bit code 🧃. Early Intel Pentium 4 CPUs with Intel 64 support, from before the Pentium 4 G1 step in December 2005, lacked the"LAHF"and"SAHF"instructions that AMD64 supports. These are load and store instructions, respectively, for certain status flags. In 64-bit mode, the"SAHF"instruction is used to optimize thefmod,drem, andremainderbuilt-in functions; see Other Builtins for details 🔍.-mmovbe— enables use of the"movbe"instruction to optimize byte swapping of four- and eight-byte entities 🔄.-mshstk— enables the shadow stack built-in functions from x86 Control-flow Enforcement Technology (CET) 🛡️.-mcrc32— enables the built-in functions"__builtin_ia32_crc32qi","__builtin_ia32_crc32hi","__builtin_ia32_crc32si"and"__builtin_ia32_crc32di"to generate the"crc32"machine instruction 🧮.-mmwait— enables the built-in functions"__builtin_ia32_monitor"and"__builtin_ia32_mwait"to generate the"monitor"and"mwait"machine instructions 😴.-mrecip— okay so this one turns on theRCPSSandRSQRTSSinstructions (plus their vectorized buddiesRCPPSandRSQRTPS) and adds an extra Newton-Raphson step for better precision. It swaps them in forDIVSSandSQRTSS(and their vectorized versions) when you're working with single-precision floating-point arguments. These only get generated when-funsafe-math-optimizationsis on together with-ffinite-math-onlyand-fno-trapping-math. Heads up: the sequence has higher throughput than the non-reciprocal instruction, but its precision can drop by up to 2 ulp. For example, the inverse of 1.0 comes out as 0.99999994 💅
GCC already turns 1.0f/sqrtf(x) into RSQRTSS (or RSQRTPS) with -ffast-math (or that same option combo), so you don't need -mrecip for that ✨
Also, GCC emits the sequence with the extra Newton-Raphson step for vectorized single-float division and vectorized sqrtf(x) already with -ffast-math (or that same option combo). Again, no -mrecip needed 🫶
-mrecip=opt— this one lets you pick exactly which reciprocal estimate instructions are allowed 🎀 Theoptpart is a comma-separated list, and you can put a!in front of any option to invert it.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 divisionvec-div— enables the approximation for vectorized divisionsqrt— enables the approximation for scalar square rootvec-sqrt— enables the approximation for vectorized square root
So, for example, -mrecip=all,!sqrt turns on all the reciprocal approximations except square root. It's giving main character energy for picking and choosing 👑
-mveclibabi=type— this sets the ABI type for vectorizing intrinsics with an external library.typecan besvml(the Intel short vector math library),aocl(the LibM math library from AMD Optimizing CPU Libraries, AOCL), oracml(the end-of-life AMD core math library, which AOCL-LibM succeeded) 🧚 To use it, you need both-ftree-vectorizeand-funsafe-math-optimizationsenabled, and you have to specify an SVML or ACML ABI-compatible library at link time. Otherwise it's a no-go 😭
GCC currently emits calls to these functions for svml:
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, vmlsAcos4For aocl, it's these corresponding function types:
amd_vrs4_acosf, amd_vrs16_acosf, amd_vrd8_asin, amd_vrs4_asinf,
amd_vrs8_asinf, amd_vrs16_asinf, amd_vrd2_atan, amd_vrd8_atan,
amd_vrs4_atanf, amd_vrs8_atanf, amd_vrs16_atanf, amd_vrd2_cos, amd_vrd4_cos,
amd_vrd8_cos, amd_vrs4_cosf, amd_vrs8_cosf, amd_vrs16_cosf, amd_vrs4_coshf,
amd_vrs8_coshf, amd_vrd2_erf, amd_vrd4_erf, amd_vrd8_erf, amd_vrs4_erff,
amd_vrs8_erff, amd_vrs16_erff, amd_vrd2_exp, amd_vrd4_exp, amd_vrd8_exp,
amd_vrs4_expf, amd_vrs8_expf, amd_vrs16_expf, amd_vrd2_exp10,
amd_vrs4_exp10f, amd_vrd2_exp2, amd_vrd4_exp2, amd_vrd8_exp2, amd_vrs4_exp2f,
amd_vrs8_exp2f, amd_vrs16_exp2f, amd_vrs4_expm1f, amd_vrd2_log, amd_vrd4_log,
amd_vrd8_log, amd_vrs4_logf, amd_vrs8_logf, amd_vrs16_logf, amd_vrd2_log10,
amd_vrs4_log10f, amd_vrs8_log10f, amd_vrs16_log10f, amd_vrd2_log1p,
amd_vrs4_log1pf, amd_vrd2_log2, amd_vrd4_log2, amd_vrd8_log2, amd_vrs4_log2f,
amd_vrs8_log2f, amd_vrs16_log2f, amd_vrd2_pow, amd_vrd4_pow, amd_vrd8_pow,
amd_vrs4_powf, amd_vrs8_powf, amd_vrs16_powf, amd_vrd2_sin, amd_vrd4_sin,
amd_vrd8_sin, amd_vrs4_sinf, amd_vrs8_sinf, amd_vrs16_sinf, amd_vrd2_tan,
amd_vrd4_tan, amd_vrd8_tan, amd_vrs16_tanf, amd_vrs4_tanhf, amd_vrs8_tanhf,
amd_vrs16_tanhfAnd for acml, it's these:
__vrd2_sin, __vrd2_cos, __vrd2_exp, __vrd2_log, __vrd2_log2, __vrd2_log10,
__vrs4_sinf, __vrs4_cosf, __vrs4_expf, __vrs4_logf, __vrs4_log2f,
__vrs4_log10f, __vrs4_powf-mabi=name— picks the calling convention to generate code for 🎀 The valid values aresysv(the ABI used on GNU/Linux and other systems) andms(the Microsoft ABI). By default you get the Microsoft ABI when targeting Microsoft Windows and the SysV ABI everywhere else. You can override this per function with thems_abiandsysv_abifunction attributes 💖-masm=dialect— chooses the assembly dialect for output 🍓 It also decides which dialect is used for basicasmand extendedasm. The choices areattorintel, and the default isatt. Fun fact (well, a limitation): Darwin doesn't supportintel💀-mforce-indirect-call— forces all function calls to be indirect ✨ This is handy with Intel Processor Trace, since it gives you more precise timing info for function calls 🦋-mmanual-endbr— only inserts theENDBRinstruction at function entry when you use thecf_checkfunction attribute 🫶 It's useful together with-fcf-protection=branchif you want to controlENDBRinsertion at the function entry yourself.-mcet-switch— by default, CET instrumentation is off for switch statements that use a jump table, and indirect branch track is disabled 🙈 Since jump tables live in read-only memory, that's not a direct loss of hardening. BUT if the jump table index is attacker-controlled, the indirect jump might 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— because of differences in 64-bit ABIs, any Microsoft ABI function that calls a System V ABI function has to treat RSI, RDI and XMM6-15 as clobbered 💅 By default, the code for saving and restoring those registers is emitted inline, which makes the prologues and epilogues pretty lengthy. With-mcall-ms2sysv-xlogues, the prologues and epilogues use stubs in the static portion oflibgccfor those saves and restores instead. That shrinks function size, at the cost of a few extra instructions 🧚-mtls-dialect=type— generates code to access thread-local storage using thegnuorgnu2conventions 🌈gnuis the conservative default.gnu2is more efficient, but it may add compile- and run-time requirements that can't be satisfied on all systems, so be careful 😭-mpush-args,-mno-push-args— uses PUSH operations to store outgoing parameters 🌸 This method is shorter and usually just as fast as the SUB/MOV approach, and it's enabled by default. In some cases, disabling it can improve performance thanks to better scheduling and fewer dependencies.-maccumulate-outgoing-args— if enabled, the maximum amount of 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 is not equal to 2. The tradeoff is a notable increase in code size. This switch implies-mno-push-args🍓
-mms-bitfields,-mno-ms-bitfields— enables or disables bit-field layout that's compatible with the native Microsoft Windows compiler 💜
Okay, here's the tea: if packed is used on a structure, or if bit-fields are used, the Microsoft ABI might lay out the structure differently than GCC normally does. Especially 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), you might need to access either format 👀
This option is enabled by default for Microsoft Windows targets. You can also control this behavior locally with variable or type attributes. For more info, check out x86 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 all data except structures, unions, and arrays, the alignment requirement is either the size of the object or the current packing size (set with either the
alignedattribute or thepackpragma), whichever is less. For structures, unions, and arrays, the alignment requirement is the largest alignment requirement of its members. Every object is allocated an offset so that:
offset % alignment_requirement == 0- Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation unit if the integral types are the same size, and if the next bit-field fits into the current allocation unit without crossing the boundary imposed by the common alignment requirements of the bit-fields 🧩
MSVC interprets zero-length bit-fields in the following ways:
- If a zero-length bit-field is inserted between two bit-fields that are normally 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 🌈
- okay so bestie, if a zero-length bit-field gets slotted in right after a bit-field called
foo, and its alignment is bigger than the member right after it (bar), thenbargets aligned as the type of that 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 lands at offset 2 instead of offset 1, so the size of t2 is 4 ✨. For t3, the zero-length bit-field doesn't mess with the alignment of bar, so the size of the struct doesn't change 💖
Taking this into account, here's what you need to know 👑
- If a zero-length bit-field follows a normal bit-field, its type can affect the alignment of the whole structure. Like,
t2is 4 bytes big because the zero-length bit-field comes after a normal bit-field and is type short 💅 - Even if a zero-length bit-field isn't followed by a normal bit-field, it can still change the alignment of the structure 😭
struct
{
char foo : 6;
long : 0;
} t4;Here, t4 takes up 4 bytes 🌸
- Zero-length bit-fields that come after non-bit-field members get ignored, no cap 🙈
struct
{
char foo;
long : 0;
char bar;
} t5;Here, t5 takes up 2 bytes 🦋
-mno-align-stringops— Skips aligning the destination of inlined string operations 🫶. This makes your code smaller and can speed things up when the destination is already aligned, but GCC doesn't know that, so it's kind of on you 💀-minline-all-stringops— By default GCC only inlines string operations when it knows the destination is aligned to at least a 4-byte boundary. This option makes it inline way more, which bumps up code size but can make shortmemcpyandmemsetcalls faster 🔥. It also turns on inline expansion ofstrlenfor all pointer alignments ✨-minline-stringops-dynamically— For string operations where the size isn't known, it adds run-time checks: inline code for small blocks, and a library call for big ones 🧚-mstringop-strategy=alg— Overrides GCC's internal heuristic for picking which algorithm gets used to inline string operations. The allowed values for alg are:rep_byte,rep_4byte,rep_8byte— Expands using the i386repprefix at the specified size 🌈byte_loop,loop,unrolled_loop— Expands into an inline loop 🔁libcall— Always uses a library call 📞
-mmemcpy-strategy=strategy— Overrides the internal heuristic that decides whether__builtin_memcpygets inlined, and which inline algorithm to use when the expected size of the copy is known 👀. The strategy is a comma-separated list of alg:max_size:dest_align triplets. alg is one of the values from-mstringop-strategy, and max_size is the biggest byte size that inline algorithm is allowed to handle. The last triplet must have a max_size of-1, and the max_size values in the list must go in increasing order. The minimum byte size for alg is 0 for the first triplet, andmax_size + 1of the range before it for every other triplet 💜-mmemset-strategy=strategy— Basically the same vibe as-mmemcpy-strategy=, except this one controls the__builtin_memsetexpansion 🍓-momit-leaf-frame-pointer— Doesn't keep the frame pointer in a register for leaf functions. That skips the instructions that save, set up, and restore frame pointers, and frees up an extra register in leaf functions 🙌. Heads up though: it removes the frame pointer for leaf functions, which 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 your 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-mavxoption turns this on by default ✨-mfentry,-mno-fentry— If profiling is active (-pg), this puts the profiling counter call before the prologue. Note: 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), this generates a section containing pointers to each profiling call, which is super handy for patching those calls automatically 🩹. You can use themfentry-section=option to set the name of that section. It defaults to__mcount_loc🎀-mnop-mcount,-mno-nop-mcount— If profiling is active (-pg), this generates the calls to the profiling functions as NOPs. That's useful when they should get patched in later on, dynamically. This is likely only useful together with-mrecord-mcount🦋-minstrument-return=type— With-pg -mfentry, this instruments function exits according to type, which can be one of:none(don't instrument),call(generate a call to"__return__"), ornop5(generate a 5-byte nop sequence) 🌸. This only instruments true returns that end with a"ret", not sibling calls made via a jump 🙅♀️-mrecord-return,-mno-record-return— Generates a"__return_loc"section that points to all the return instrumentation code 🗺️-mfentry-name=name— Sets the name of the"__fentry__"symbol that gets called at function entry for-pg -mfentryfunctions 📛-mfentry-section=name— Sets the name of the section where-mrecord-mcountcalls get recorded. The default is__mcount_loc🧾-mskip-rax-setup,-mno-skip-rax-setup— When generating code for the x86-64 architecture with SSE extensions disabled,-mskip-rax-setupcan skip setting up the RAX register, but only when no variable arguments are passed in vector registers 🧠-m8bit-idiv,-mno-8bit-idiv— On some processors, like Intel Atom, 8-bit unsigned integer divide is way faster than 32-bit/64-bit integer divide 🏎️. This option generates a run-time check: if both the dividend and divisor are in the range 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,-mstack-protector-guard-reg=reg,-mstack-protector-guard-offset=offset,-mstack-protector-guard-symbol=symbol— Generates stack protection code using a canary at guard. The supported locations areglobal(for a global canary) ortls(for a per-thread canary in the TLS block, which is the default) 🛡️. These only do something if-fstack-protectoror-fstack-protector-allis specified 🙈
With the latter choice (tls), -mstack-protector-guard-reg=reg and -mstack-protector-guard-offset=offset get to specify which segment register (%fs or %gs) to use as the base register for reading the canary, and what offset from that base register to use. The defaults for those are whatever the relevant ABI says 📖
-mstack-protector-guard-symbol=symbol overrides the offset with a symbol reference to a canary in the TLS block 🔑
-mgeneral-regs-only— Generates code that only uses the general-purpose registers. This stops the compiler from using floating-point, vector, mask, and bound registers 🚫🌈-mrelax-cmpxchg-loop— When emitting 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 theCMPXCHGinstruction, and uses thePAUSEinstruction to save CPU power when restarting the loop ⚡-mindirect-branch=choice— Converts indirect calls and jumps according to choice. The default iskeep, which leaves indirect calls and jumps unmodified 🙂.thunkconverts them to a call and return thunk.thunk-inlineconverts them to an inlined call and return thunk.thunk-externconverts them to an external call and return thunk, provided in a separate object file 📦. You can control this behavior for a specific function using the function attribute"indirect_branch"🎯
Heads up:-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-extern is compatible with -fcf-protection=branch, since the external thunk can be made to enable control-flow check 🫶
-mfunction-return=choice— Converts function returns according to choice. The default iskeep, which leaves function returns unmodified 🙂.thunkconverts function returns to a call and return thunk.thunk-inlineconverts them to an inlined call and return thunk.thunk-externconverts them to an external call and return thunk, provided in a separate object file 📦. You can control this behavior for a specific function using the function attribute"function_return"🎯
Note: -mindirect-return=thunk-extern is compatible with -fcf-protection=branch, since the external thunk can be made to enable control-flow check 🫶
Heads up:-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 via a register 🧚-mharden-sls=choice— okay bestie, this one's a whole security glow-up 🛡️ It makes GCC generate code that guards against straight line speculation (SLS), with the level set by choice. The default isnone, which turns off all SLS hardening.returncovers function returns,indirect-jmpcovers indirect jumps, andallturns on every SLS hardening option 🔥-mindirect-branch-cs-prefix— this one is giving very specific main character energy ✨ It adds a CS prefix tocallandjmpinstructions that go to an indirect thunk, where the branch target is in ther8-r15registers. That makes each call or jmp instruction 6 bytes long, so at run time they can potentially be swapped out forlfence; call *%r8-r15orlfence; jmp *%r8-r15🦋-mapx-inline-asm-use-gpr32— so by default, EGPR usage is turned off in inline asm constraints 🙈 The reason is that GCC has no way of knowing whether the asm instructions can handle GP32 or not. If your inline asm can handle EGPR, you add-mapx-inline-asm-use-gpr32and you're good to go 💅-mgather,-mscatter— these two are a matching set 🌈 They enable vectorization for gather and scatter instructions, respectively.
These -m switches are supported on top of everything above for x86-64 processors in 64-bit environments 🌸
-m32,-m64,-mx32,-m16— okay this is the environment squad 💖 They generate code for a 16-bit, 32-bit or 64-bit environment.-m32setsint,long, and pointer types to 32 bits, and generates code that runs in 32-bit mode.-m64setsintto 32 bits, setslongand 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 🍓-mx32setsint,long, and pointer types to 32 bits, and generates code for the x86-64 architecture ✨-m16is basically-m32, except it also outputs the.code16gccassembly directive at the very start of the assembly output, so the binary can run in 16-bit mode 🧚
-miamcu— this one generates code that conforms to the Intel MCU psABI. It requires-m32to be turned on 🎀-mno-red-zone— okay so the x86-64 ABI says there's a so-called "red zone" 🧚 It's a 128-byte area beyond the stack pointer that signal or interrupt handlers don't touch, so you can stash temporary data there without adjusting the stack pointer.-mno-red-zoneturns that red zone off 🙅♀️-mcmodel=small— the default, and it's the chill one 🌸 It 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, and programs can be statically or dynamically linked.-mcmodel=kernel— this one lives in the negative 2 GB of the address space, and it has to be used for Linux kernel code 👑-mcmodel=medium— the program gets linked in the lower 2 GB, and small symbols go there too. Symbols bigger than-mlarge-data-thresholdget put into large data or BSS sections, and those can sit above 2GB. Programs can be statically or dynamically linked 🦋-mcmodel=large— this model makes no assumptions at all about addresses and sizes of sections 🌈-maddress-mode=long— generates code for long address mode. It's 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. It's only supported for 32-bit and x32 environments, and it's the default address mode for 32-bit and x32 environments 🫶-mneeded,-mno-needed— these emit theGNU_PROPERTY_X86_ISA_1_NEEDEDGNU property for the Linux target, which tells you the micro-architecture ISA level needed to run the binary ⭐-mno-direct-extern-access— okay so without-fpicor-fPIC, this one always uses the GOT pointer to reach external symbols. With-fpicor-fPIC, it treats access to protected symbols 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 both the shared libraries and the executable. Be careful, bestie 😭
-munroll-only-small-loops,-mno-unroll-only-small-loops— this is conservative small loop unrolling 🌸 It's enabled by default with-O2, and it unrolls loops with fewer than 4 instructions by 1 time. That gives better utilization of the instruction decoding pipeline on modern processors. You can turn it off with-mno-unroll-only-small-loops, and it's also disabled if the more general options-funroll-loopsor-funroll-all-loopsare either enabled or explicitly disabled 🍓-mdispatch-scheduler— enables instruction scheduling ✨ It's only supported onbdver1,bdver2,bdver3,bdver4, andznver1processors, and it additionally requires-fschedule-insns -fsched-pressure🔥-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 🌸
🌵 Xstormy16 Options 🌵
These options are defined for Xstormy16 🦋
-msim— chooses startup files and a linker script that are suitable for the simulator 🧚
🌈 Xtensa Options 🌈
These options are supported for Xtensa targets 💜
-mconst16,-mno-const16— enables or disables the use of"CONST16"instructions for loading constant values 💅 When enabled,"CONST16"instructions are always used in place of the standard"L32R"instructions. The use of"CONST16"is enabled by default only if the"L32R"instruction is not available 🙈-mserialize-volatile,-mno-serialize-volatile— when this one is enabled, GCC inserts"MEMW"instructions before"volatile"memory references to guarantee sequential consistency 🫶 The default is-mserialize-volatile. Use-mno-serialize-volatileto leave out the"MEMW"instructions 💀-mforce-no-pic,-mno-force-no-pic— for targets like GNU/Linux, where all user-mode Xtensa code has to be position-independent code (PIC), this option turns PIC off when compiling kernel code 👑-mtext-section-literals,-mno-text-section-literals— these control the treatment of literal pools 🎀 The default is-mno-text-section-literals, which puts literals in a separate section in the output file. That lets the literal pool sit in data RAM/ROM, and it also lets the linker combine literal pools from separate object files to remove redundant literals and improve code size. With-mtext-section-literals, the literals are interspersed in the text section so they stay as close as possible to their references. This may be necessary for large assembly files. Literals for each function are placed right before that function 🌸-mauto-litpools,-mno-auto-litpools— these also control the treatment of literal pools 🦋 The default is-mno-auto-litpools, which puts literals in a separate section in the output file unless-mtext-section-literalsis used. With-mauto-litpools, the assembler interspersses the literals in the text section. The compiler doesn't produce explicit".literal"directives, and it loads literals into registers with"MOVI"instructions instead of"L32R", so the assembler can do relaxation and place literals as necessary. This option lets the assembler create several literal pools per function and assemble very big functions, which may not be possible with-mtext-section-literals🧚-mtarget-align,-mno-target-align— when enabled, GCC tells the assembler to automatically align instructions to reduce branch penalties, at the cost of some code density 🌈 The assembler tries to widen density instructions to align branch targets and the instructions following call instructions. If there aren't enough preceding safe density instructions to align a target, no widening happens. The default is-mtarget-align. These options don't affect auto-aligned instructions like"LOOP", which the assembler always aligns, either by widening density instructions or by inserting NOP instructions 💖-mlongcalls,-mno-longcalls— when enabled, GCC tells the assembler to translate direct calls into indirect calls, unless it can tell that the target of a direct call is in the range the call instruction allows 😭 This usually happens for calls to functions in other source files. Specifically, the assembler turns a direct"CALL"instruction into an"L32R"followed by a"CALLX"instruction. The default is-mno-longcalls. Use this option in programs where the call target might be out of range 🫶 It's implemented in the assembler, not the compiler, so the assembly code GCC generates still shows direct call instructions. Look at the disassembled object code to see the actual instructions 👀 The assembler uses an indirect call for every cross-file call, not just the ones that really are out of range 🙃-mabi=name— generates code for the specified ABI 💅 Permissible values arecall0andwindowed. The default ABI is chosen by the Xtensa core configuration.-mabi=call0— function parameters are passed in registers"a2"through"a7", registers"a12"through"a15"are caller-saved, and register"a15"may be used as a frame pointer 🌸 When this ABI version is enabled, the C preprocessor symbol"__XTENSA_CALL0_ABI__"is defined ✨-mabi=windowed— function parameters are passed in registers"a10"through"a15", and the called function rotates the register window by 8 registers on entry, so its arguments are found in registers"a2"through"a7"🧚 Register"a7"may be used as a frame pointer. The register window is rotated 8 registers back upon return. When this ABI version is enabled, the C preprocessor symbol"__XTENSA_WINDOWED_ABI__"is defined 👑
-mextra-l32r-costs=n— okay so this one lets you dial in an extra cost for instruction RAM/ROM access on"L32R"instructions, measured in clock cycles ⏱️ 🌸 When you're optimizing for speed, it decides whether a constant gets loaded from the literal pool with"L32R"or built from a small one using a couple of arithmetic instructions 🧮 The default is0.-mstrict-align,-mno-strict-align— these control whether GCC avoids (-mstrict-align) or allows (-mno-strict-align) memory accesses that might not line up on a natural object boundary, as the architecture spec describes 🙈 The default is-mno-strict-alignfor cores that handle both unaligned loads and stores in hardware, and-mstrict-alignfor every other core 💖
✨ 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 GCC at directories or prefixes to search when it's hunting for files, and others set up other aspects of the compilation environment 🌈
Also, you can name search spots directly with options like -B, -I and -L 🗺️ Those take precedence over environment variables, and environment variables take precedence over whatever the GCC configuration says. Main character rules 👑
✨ LANG ✨
✨ LC_CTYPE ✨
✨ LC_MESSAGES ✨
✨ LC_ALL ✨
These variables control how GCC uses localization info so it can work with different national conventions 🌍 GCC looks at the LC_CTYPE and LC_MESSAGES locale categories if it's been configured to do so. You can set these categories to any value your installation supports. A typical value is en_GB.UTF-8, which is English for the United Kingdom encoded in UTF-8 🇬🇧
LC_CTYPE— this one handles character classification 🔤 GCC uses it to figure out where character boundaries fall in a string. That 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— this one picks the language used in diagnostic messages 💬LC_ALL— if this is set, it overridesLC_CTYPEandLC_MESSAGES. If it isn't, thenLC_CTYPEandLC_MESSAGESdefault to the value ofLANG✨ If none of these variables are set, GCC defaults to traditional C English behavior 🎀
✨ TMPDIR ✨
If TMPDIR is set, it names the directory GCC uses for temporary files 📁 GCC makes temp files to hold the output of one stage of compilation that gets fed into the next stage. For example, the preprocessor's output is the input to the compiler proper 🧚
✨ GCC_DIAGNOSTICS_LOG ✨
If GCC_DIAGNOSTICS_LOG is set, extra info about the diagnostics subsystem gets emitted 🔍 If it's set to an empty value, that info goes to stderr. Otherwise, GCC tries to open the file you named and writes the info there 📝
The exact content and format of this info can change at any time. It's meant for GCC developers rather than end-users, so don't be surprised if it looks like it's for the insiders 🙈
✨ GCC_COMPARE_DEBUG ✨
Setting GCC_COMPARE_DEBUG is nearly the same as passing -fcompare-debug to the compiler driver 🪞 Check that option's documentation for more details 📖
✨ GCC_EXEC_PREFIX ✨
If GCC_EXEC_PREFIX is set, it names a prefix to use in the names of the subprograms GCC runs 🧩 No slash gets added when the prefix is combined with a subprogram name, but you can end your prefix with a slash if you want one 🦋
If GCC_EXEC_PREFIX isn't set, GCC tries to figure out a good prefix based on the pathname it was invoked with 🕵️♀️
If GCC can't find the subprogram using your prefix, it checks the usual places for it 🏠
The default value of GCC_EXEC_PREFIX is prefix/lib/gcc/, where prefix is the prefix of the installed compiler. In lots of cases, prefix is the value of "prefix" you used when you ran the configure script ⚙️
Prefixes you give with -B take precedence over this one 👑
This prefix is also used for finding files like crt0.o that get used for linking 🔗
It also gets used in a kind of unusual way when GCC hunts for header 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 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 the value of 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 uses these directories when searching for ordinary libraries for the -l option. Just remember that directories given with -L come first 🥇
✨ LANG ✨
This variable passes locale info to the compiler 🌏 One thing it's used for is deciding which character set to use when character literals, string literals and comments get parsed in C and C++. When the compiler is configured to allow multibyte characters, these values for LANG are recognized:
C-JIS— recognizes JIS characters 🇯🇵C-SJIS— recognizes SJIS characters 🍣C-EUCJP— recognizes EUCJP characters 🎌
If LANG isn't defined, or it has some other value, then 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 the following values, extra text gets emitted to stderr whenever fix-it hints are emitted 🩹 -fdiagnostics-parseable-fixits and -fno-diagnostics-parseable-fixits take precedence over this environment variable 👑
fixits-v1— emits parseable fix-it hints, equivalent to-fdiagnostics-parseable-fixits🧾 In particular, columns are expressed as a count of bytes, starting at byte 1 for the initial column 🔢fixits-v2— same asfixits-v1, except columns are expressed as display columns, per-fdiagnostics-column-unit=display📐
✨ EXPERIMENTAL_SARIF_SOCKET ✨
If EXPERIMENTAL_SARIF_SOCKET is set in the environment, the compiler will try to connect to a UNIX domain stream socket with that name 🔌 It then sends an "OnSarifResult" JSON-RPC 2.0 notification to it for each diagnostic that occurs, where the value of the notification is a SARIF "result" object 📨
The compiler will fail immediately if EXPERIMENTAL_SARIF_SOCKET is set and it can't connect to it 💀
This feature is experimental and subject to change or removal without notice. Don't build your whole life on it yet 🙃
Some additional environment variables affect the behavior of the preprocessor 🧼
✨ 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, to look in for header files 📂 The special character, "PATH_SEPARATOR", depends on the target and is determined when GCC is built. For Microsoft Windows-based targets it's a semicolon, and for almost all other targets it's a colon ⚡
CPATH specifies a list of directories to be searched as if you'd given them with -I, but after any paths given with -I options on the command line 🗂️ This environment variable is used no matter which language is being preprocessed 🌟
The remaining environment variables only apply when preprocessing the particular language they're named for. Each one specifies a list of directories to be searched as if you'd used -isystem, but after any paths given with -isystem options 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 the end of a path. For instance, if the value of CPATH is ":/special/include", that has the same effect as -I. -I/special/include 🫧
✨ DEPENDENCIES_OUTPUT ✨
If this variable is set, its value specifies how to output dependencies for Make, 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 be just a file name. In that case, the Make rules are written to that file, and the target name is guessed from the source file name 🎯 Or the value can take the form file target, in which case the rules are written to file using target as the target name 💜
In other words, this environment variable is equivalent to combining the options -MM and -MF, with an optional -MT switch too 🧠
✨ SUNPRO_DEPENDENCIES ✨
This variable is the same as DEPENDENCIES_OUTPUT (see above), except system header files are not ignored, so it implies -M rather than -MM 🙌 However, the dependence on the main input file is omitted 🫥
✨ SOURCE_DATE_EPOCH ✨
If this variable is set, its value specifies a UNIX timestamp to use in place of the current date and time in the "__DATE__" and "__TIME__" macros 🕰️ That way the embedded timestamps become reproducible ♻️
The value of SOURCE_DATE_EPOCH must be a UNIX timestamp, defined as the number of seconds (excluding leap seconds) since 01 Jan 1970 00:00:00, represented in ASCII. It's identical to the output of date +%s on GNU/Linux and other systems that support the %s extension in the "date" command 🐧
The value should be a known timestamp, such as the last modification time of the source or package, and it should be set by the build process 🏗️
✨ BUGS ✨
For instructions on reporting bugs, see <file:///usr/share/doc/gcc-16/README.Bugs> 🐛🫶
✨ FOOTNOTES ✨
- okay bestie, this one's a lil spicy 🌶️ 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. Skip the correct flags and you can get subtle defects 💀 but supplying them when they aren't needed is totally innocuous 🫶 Also,-sharedsuppresses the addition of startup code that alters the floating-point environment, which happens with-ffast-math,-Ofastor-funsafe-math-optimizationson some targets ✨
✨ SEE ALSO ✨
Go check these out, they're giving everything 📚
gpl(7),gfdl(7),fsf-funding(7),cpp(1),gcov(1),as(1),ld(1),gdb(1)- the Info entries for
gcc,cpp,as,ld,binutilsandgdb🦋
✨ AUTHOR ✨
the contributors are the real MVPs 👑 Check the Info entry for gcc, or peep <https://gcc.gnu.org/onlinedocs/gcc/Contributors.html> to see everyone who helped build GCC 🌈
✨ COPYRIGHT ✨
Copyright (c) 1988-2026 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 a wrap, bestie 🫶 This page is from gcc-16, dated 2026-03-22. Now go be a compiler girlie 💅✨
📦 where this page comes from
- ubuntu resolute: g++-16-arc-linux-gnu 16-20260322-1ubuntu1cross1
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms