kefir(1)

📦
version 0.5.0 · 2 versions
, in alpine 3.24

🦋 NAME 🦋

kefir — C17/C23 language compiler. This is the kefir(1) page from the General Commands Manual, bestie, and we're getting through it together. 💖

🌈 SYNOPSIS 🌈

kefir [options] files... [-run [args...]]

💅 DESCRIPTION 💅

Okay so kefir command-line options follow the c99(1) compiler interface, and they extend it with some of the supported gcc(1) flags plus flags for special kefir features. Unknown command-line flags are ignored with a warning printed for each such flag passed to the compiler — yes, every single one, no cap. 👀

The kefir compiler driver has multiple operation modes. Command-line flags are parsed in left-to-right order, and later flags override earlier ones. Some operation modes, once selected, prevent further parsing and immediately invoke the selected mode — refer to the “OPTIONS” section for details. ✨

🎀 OPTIONS 🎀

The following options terminate command-line argument parsing:

  • -h | --help — Print help text.
  • -v | --version — Print compiler version.
  • --compiler-info — Print compiler information.
  • --environment-info — Print compiler environment information (see the “ENVIRONMENT” section below).
  • --environment-header — Print compiler environment header file (based on the “ENVIRONMENT” section and current target).
  • -verbose — Report commands executed by the driver verbosely.

If passed, the -cc1 argument invokes the kefir-cc1 compiler directly, skipping the driver. The argument shall always be passed first to take an effect. 🫶

The rest of the command-line options are parsed normally:

  • -c — Skip the link-edit phase of the compilation, save object files.
  • -S — Skip the assembling phase of the compilation, save assembly files.
  • -E — Preprocess C-language source files, print results to standard output.
  • -P — Preprocess C-language source files, print results to standard output.
  • -std= standard — Determine language standard. For C23, supported values are: c23, c2x, gnu23, gnu2x, iso9899:2024. For C17 [default], any other value not explicitly listed for C23.
  • -x -language — Specify processing for the next input files. Supported values: none [default], c, c-header, cpp-output, assembler, assembler-with-cpp.
  • -preprocess-save — Preprocess C-language source files, save results.
  • -o file — Save results to the output file.
  • --target specification — Generate code for the specified target system (see the “TARGET” section below).
  • -O level — Code optimization level (default is 0). All non-zero levels are equivalent to 1. All non-numerical levels (such as -Os) are also equivalent to 1.
  • -fpreprocessed — Skip preprocessor directive processing and macro expansion. Preprocessor skips over any directive except for line directive, and acts solely as tokenizer.
  • --preprocessor-linemarkers — Include linemarkers into preprocessor output [default: off]. Likemarker content slightly differs from gcc, which might break some builds. Enable with care.
  • -funsigned-char — Let the type char be unsigned. By default, it is target-specific.
  • -fsigned-char — Let the type char be signed. By default, it is target-specific.
  • -fcommon — Place tentative definitions into common section (equivalent to common attribute applied to all variables).
  • -fvisibility=default|internal|hidden|protected — Set visibility for symbols in the program, unless overridden by a particular symbol attribute.
  • -fno-common — Do not place tentative definitions into common section [default].
  • -D name[=value] — Define preprocessor macro.
  • -U name — Undefine predefined preprocessor macro.
  • -I directory — Add directory to preprocessor include path.
  • -isystem directory — Add directory to preprocessor system include path.
  • -iquote directory — Add directory to preprocessor include path for quoted includes exclusively (processed before -I).
  • -idirafter directory — Add directory to preprocessor system include path (after processing other system include directories).
  • --embed-dir= directory — Add directory to preprocessor embed search path.
  • -M — Output a make rule describing the dependencies of source file (including the dependencies from system path).
  • -MM — Output a make rule describing the dependencies of source file (excluding the dependencies from system path and their transitive includes).
  • -MD — Output a make rule describing the dependencies of source file (including the dependencies from system path), while also running normal compilation pipeline.
  • -MMD — Output a make rule describing the dependencies of source file (excluding the dependencies from system path and their transitive includes), while also running normal compilation pipeline.
  • -MP — Output a phony target for each dependency of source file.
  • -MT target — Override the default target name of make rule produced by dependency generation.
  • -MF filename — Override the default output file for make rule produced by dependency generation.
  • -include file — Include file during preprocessing phase.
  • -s — Strip linked executable.
  • -r — Retain relocations in linked executable.
  • -e entry — Override entry point of linked executable.
  • -u symbol — Add undefined symbol to linked executable.
  • -l library — Link library.
  • -L directory — Add directory to linker library search path.
  • -rpath directory — Add directory to runtime library search path.
  • -soname name — Pass -soname option to the linker.
  • -pthread — Define macros and link pthread library.
  • -rdynamic — Pass --export-dynamic option to the linker.
  • -static — Produce a statically linked executable.
  • -shared — Produce a shared object.
  • -fPIC | -fpic — Produce position-independent code [default].
  • -fno-pic — Do not produce position-independent code [default].
  • -pie — Produce position-independent executable (requires -fPIC flag).
  • -no-pie — Do not produce position-independent executable [default].
  • -masm=ASSEMBLER — Produce code for the following assembler: [x86_64-gas-intel, x86_64-gas-intel_prefix, x86_64-gas-att (default), x86_64-yasm, intel (alias for x86_64-gas-intel), att (alias for x86_64-gas-att)]. Also affects assembler flags. Note that KEFIR_AS or AS environment variable shall point to the respective assembler executable.
  • -fomit-frame-pointer — Omit frame pointer in leaf functions that do not need it [default on optimization levels > 0].
  • -fno-omit-frame-pointer — Always use frame pointer in all functions [default on optimization level 0].
  • -g | -ggdb — Produce debug information [default: off].
  • -g[level] | -ggdb[level] — Produce debug information if level is greater than 0 [default: off].
  • -nostartfiles — Do not link start files.
  • -nodefaultlibs — Do not link default libraries.
  • -nolibc — Do not link libc.
  • -nostdlib — Do not link start files and default libraries.
  • -nostdinc — Do not add standard library to include path.
  • -nortinc — Do not add runtime includes to include path.
  • --enable-atomics — Enables atomic support. Implies --Wdeclare-atomic-support option and links appropriate atomic primitives library (libatomic/libcompiler_rt) where necessary.
  • --disable-atomics — Disables atomic support. Implies --Wno-declare-atomic-support option.
  • -Wp,option — Pass "option" to preprocessing phase as command line option. If option contains commas, it is split into multiple options.
  • -Xpreprocessor option — Pass "option" to preprocessing phase as command line option.
  • -Wc,option — Pass "option" to compiling phase as command line option. If option contains commas, it is split into multiple options.
  • -Wa,option — Pass "option" to assembler phase as command line option. If option contains commas, it is split into multiple options.
  • -Xassembler option — Pass "option" to assembler phase as command line option.
  • -Wl,option — Pass "option" to linking phase as command line option. If option contains commas, it is split into multiple options.
  • -z -keyword — Pass "-z keyword" to linking phase as command line options.
  • -Xlinker option — Pass "option" to linking phase as command line option.
  • -Woption — Pass "--option" to compiling phase as command line option.
  • -W option — Pass "option" to compiling phase as command line option.
  • --restrictive-c — Enable restrictive compiling mode with C extensions disabled.
  • --permissive-c — Enable permissive compiling mode with C extensions enabled [default].
  • --print-tokens — Print tokenized source in JSON format.
  • --print-ast — Print AST in JSON format.
  • --print-ir — Print intermediate representation in JSON format.
  • --print-opt — Print optimization representation in JSON format.
  • -run [file args...] — Run the linked executable with the rest of command line arguments. If no input file was specified, the first argument is treated as input file.
  • -runarg arg — Pass an argument to the runned process (shall precede -run flag).
  • -run-stdin file — Redirect runned process stdin from file (shall precede -run flag).
  • -run-stdout file — Redirect runned process stdout to file (shall precede -run flag).
  • -run-stderr file — Redirect runned process stderr to file (shall precede -run flag).
  • -run-stderr2out — Redirect runned process stderr to stdout (shall precede -run flag).

🧚 COMPILER OPTIONS 🧚

Extra compiler options available via the -W switch:

  • --c17-standard — Use C17 language standard.
  • --c23-standard — Use C23 language standard.
  • --pp-timestamp timestamp — Override preprocessor timestamp.
  • --json-errors — Print errors in JSON format to stderr.
  • --tabular-errors — Print errors in tabular format to stderr.
  • --target-profile profile — Generate code for specified target (see the “TARGET” subsection).
  • --source-id identifier — Force use provided source file identifier.
  • --extension-lib libpath — loads up an extension library from libpath, bestie 💖
  • --system-include-dir dir — drops dir onto the include search path and flags it as a system include path (which matters for dependency output, iykyk)
  • --embed-dir directory — adds directory to the preprocessor's embed search path 🎀
  • --debug-info — bakes debug information right into the produced output
  • --optimizer-max-inline-depth depth — the max depth for function inlining (5 by default, no cap on the vibes)
  • --optimizer-max-inlines-per-func inlines — the max number of inlined functions per function (10 by default)
  • --enable-lowering — does the target-specific SSA lowering. This one is mandatory for bit-precise integer support, so like… don't skip it [default] ✨
  • --disable-lowering — skips the target-specific SSA lowering entirely 🙈
  • --preprocessor-assembly-mode — turns on assembly preprocessing mode (that's the default for .S files, lowercase-capital-S girlies). In this mode, leading '$' characters are not treated as part of an identifier
  • --preprocessor-normal-mode — turns assembly preprocessing mode back off (the default) 🦋
  • --feature-[name] — enables a compiler feature (go peek at the “FEATURES” subsection 👀)
  • --no-feature-[name] — disables a compiler feature (again: “FEATURES” subsection)
  • --internal-[flag] — enables a compiler internal flag (see “INTERNALS”)
  • --no-internal-[flag] — disables a compiler internal flag (see “INTERNALS”)
  • --codegen-[option] — enables an option for the code generator (see “CODEGEN”)
  • --no-codegen-[option] — disables an option for the code generator (see “CODEGEN”)
  • --optimizer-pipeline spec — your optimizer pipeline specification (see “OPTIMIZER”)
  • --precise-bitfield-load-store — loads and stores bitfields at byte boundaries [default: on]. It gives you extra correctness for structures allocated close to a boundary with unmapped memory pages, at the cost of less efficient bitfield handling. Does not change bitfield layout, so breathe 🫶
  • --no-precise-bitfield-load-store — loads and stores bitfields at machine word boundaries [default: off]. Heads up: this may cause failures for structures allocated close to boundaries with unmapped memory pages. Still doesn't change bitfield layout though ⭐
  • --declare-atomic-support — declares that atomics are supported (might require you to explicitly link a software atomic library like libatomic or libcompiler_rt, fr fr)
  • --no-declare-atomic-support — declares the absence of atomic support by defining the __STDC_NO_ATOMICS__ macro 💀
  • --optimize-stack-frame — optimizes the stack frame layout by reusing space for variables with disjoint lifetimes. Might increase compilation time and memory use on very large functions [default: on]
  • --no-optimize-stack-frame — no stack frame layout optimization, every variable gets its own separate allocation, no sharing, no slay 🌸
  • --unsigned-char — makes the type char unsigned. By default it's target-specific, so don't @ me
  • --signed-char — makes the type char signed. By default it's target-specific 💅
  • --codegen-tentative-common — places tentative definitions into the common section (equivalent to the common attribute applied to all variables)
  • --codegen-tentative-no-common — does not place tentative definitions into the common section [default]
  • --codegen-visibility-default — keeps default visibility for all symbols [default] ✨
  • --codegen-visibility-hidden — makes all symbols hidden unless an attribute says otherwise
  • --codegen-visibility-protected — makes all symbols protected unless an attribute says otherwise
  • --codegen-visibility-internal — makes all symbols internal unless an attribute says otherwise

✨ FEATURES ✨

These are the supported features, and you use them with the --Wfeature-[feature-name] and --Wno-feature-[feature-name] flags. Okay so here's the whole menu 🍓

  • fail-on-attributes — fails if __attribute__((...)) shows up [default: off]
  • missing-function-return-type — permits function definitions that are missing their return type [default: on]
  • designated-init-colons — permits the "fieldname:" syntax in designated initializers [default: on]
  • labels-as-values — permits label-addressing with the && operator [default: on]
  • non-strict-qualifiers — disables strict qualifier checks for pointers [default: on]
  • signed-enums — forces all enums to have a signed integral type [default: off]
  • implicit-function-decl — permits implicit function declarations at the use-site [default: on]
  • empty-structs — permits empty structure/union definitions [default: on]
  • ext-pointer-arithmetics — permits pointer arithmetics with function and void pointers [default: on]
  • missing-braces-subobj — permits missing braces for subobject initialization with scalar [default: on]
  • statement-expressions — enables statement expressions [default: on]
  • omitted-conditional-operand — permits omission of the middle ternary expression operand [default: on]
  • int-to-pointer — permits any integral type conversion to pointer [default: on]
  • permissive-pointer-conv — permits conversions between any pointer types [default: on]
  • named-macro-vararg — permits named macro variable arguments [default: on]
  • include-next — permits the include_next preprocessor directive [default: on]
  • fail-on-assembly — disables support of inline assembly [default: off]
  • va-args-comma-concat — enables special processing for the ", ##__VA_ARGS" case in the preprocessor [default: on]
  • switch-case-ranges — enables support for ranges in switch cases [default: on]
  • designator-subscript-ranges — enables support for ranges in designator subscripts [default: on]

🌈 CODEGEN 🌈

Supported code generator options, and you use these with the --Wcodegen-[option] and --Wno-codegen-[option] flags 💜

  • emulated-tls — use emulated TLS [disabled by default, enabled on the openbsd platform]
  • tls-common — generate a common section for thread-local storage if the respective attribute is on [enabled for linux and netbsd]
  • pic — generate position-independent code ✨
  • omit-frame-pointer — omit the frame pointer in leaf functions that don't need it
  • valgrind-compatible-x87 — replaces x87 opcodes that Valgrind doesn't support with more expensive alternatives [default: on]
  • syntax=SYNTAX — produces assembly output with the specified syntax. Your options are x86_64-intel_noprefix, x86_64-intel_prefix, x86_64-att (that's the default), and x86_64-yasm.
  • details=DETAILS-SPEC — augments assembly output with internal code generator details in comments. DETAILS-SPEC can be: vasm (virtual assembly), vasm+regs (virtual assembly and register allocations), or devasm (devirtualized assembly).
  • pipeline=PIPELINE-SPEC — the code generator transformation pipeline spec, which is a comma separated list of pipeline pass names:
    • noop — no-operation pass 😌
    • amd64-drop-virtual — non-functional virtual instruction elimination for amd64 targets
    • amd64-peephole — peephole optimizations for amd64 targets

🔥 OPTIMIZER 🔥

The optimizer pipeline specification is a comma separated list of pipeline pass names. Here's the roster 👑

  • noop — no-operation pass. She does nothing and she does it flawlessly 💅
  • phi-propagate — wherever possible, substitutes phi nodes of the SSA representation with actual references
  • mem2reg — pulls function local variables into registers
  • op-simplify — general code simplification
  • constant-fold — folding constant expressions
  • gvn — global value numbering pass, there to eliminate redundant arithmetic and bitwise operations
  • local-alloc-sink — moves local variable allocations closer to their actual uses (and does not affect effective variable lifetimes, noted)
  • dead-code-elimination — eliminates dead code, blocks and phi links
  • block-merge — removes unnecessary jump instructions and merges the respective blocks
  • dead-alloc — removes dead local variable allocations
  • inline-func — performs function inlining
  • tail-call — performs tail call optimization
  • lowering — performs target-specific lowering of the SSA representation. Mandatory for bit-precise integer support, so this one's kind of a big deal 😤

🦋 TARGET 🦋

Target platforms get specified in the format [<backend>-]<platform>[-<variant>] where:

  • backend — opt [default]
  • platform — <arch>-<os> | host [default]
  • arch — x86_64 | hostcpu [default]
  • platform — linux | freebsd | openbsd | netbsd | hostos [default]
  • variant — none | musl | gnu | system | default

Backend and variant are the optional parts of the target specification, bestie — they can dip if they want 💫

Variant "none" avoids any implicit library linkages and include path. On linux, "default" is equivalent to "gnu", and on other platforms it's equivalent to "system". That's the whole tea ☕

✨ ENVIRONMENT ✨

okay bestie, these are the env vars that change how kefir behaves. read carefully, some of them are literally mandatory for certain platforms 💅

  • KEFIR_AS | AS — overrides the default "as" assembler 🛠️
  • KEFIR_LD | LD — overrides the default "ld" linker 🔗
  • KEFIR_RTINC — tells kefir where the runtime include location lives. this one is mandatory for every platform variant except "*-none" 🫶
  • KEFIR_MUSL_INCLUDE — musl include paths, separated by ';'. mandatory for the "linux-musl" platform variant 🌸
  • KEFIR_MUSL_LIB — musl library paths, separated by ';'. mandatory for the "linux-musl" platform variant 🌸
  • KEFIR_MUSL_DYNAMIC_LINKER — dynamic linker path. optional for the "linux-musl" platform variant ✨
  • KEFIR_GNU_INCLUDE — GNU include paths, separated by ';'. mandatory for the "linux-gnu" platform variant 💜
  • KEFIR_GNU_LIB — GNU library paths, separated by ';'. mandatory for the "linux-gnu" platform variant 💜
  • KEFIR_GNU_DYNAMIC_LINKER — dynamic linker path. optional for the "linux-gnu" platform variant ✨
  • KEFIR_FREEBSD_INCLUDE — FreeBSD include paths, separated by ';'. mandatory for the "freebsd-system" platform variant 🦋
  • KEFIR_FREEBSD_LIB — FreeBSD library paths, separated by ';'. mandatory for the "freebsd-system" platform variant 🦋
  • KEFIR_FREEBSD_DYNAMIC_LINKER — dynamic linker path. optional for the "freebsd-system" platform variant ✨
  • KEFIR_OPENBSD_INCLUDE — OpenBSD include paths, separated by ';'. mandatory for the "openbsd-system" platform variant 🐡
  • KEFIR_OPENBSD_LIB — OpenBSD library paths, separated by ';'. mandatory for the "openbsd-system" platform variant 🐡
  • KEFIR_OPENBSD_DYNAMIC_LINKER — dynamic linker path. optional for the "openbsd-system" platform variant ✨
  • KEFIR_TMPDIR — overrides kefir's temporary directory 📁
  • KEFIR_DRIVER_CLI_QUIET — set it to "yes" (no quotes, bestie) and it suppresses warnings about unknown command line options 🤫
  • SOURCE_DATE_EPOCH — overrides the preprocessor timestamp with whatever value you give it. it wants a Unix epoch timestamp ⏰
fyi the ; separators are literal, don't go putting spaces or commas in there, okay? iykyk 🎀

💀 EXIT STATUS 💀

normally kefir exits with a 0 exit code, slay. but if literally any error shows up in any of the compilation stages, all further compilation gets aborted and you get a non-zero exit code back. so if you see a non-zero, something went wrong, no cap 😭

👑 STANDARDS 👑

kefir implements the C17 language standard as specified in its final draft, plus the C23 language standard (except _Decimal support) as specified in the first draft of C2Y. the range, the icon behavior 🫶

🦋 NOTES 🦋

the kefir compiler is licensed under the terms of the GNU GPLv3 license. the runtime code provided along with kefir is licensed under the terms of the BSD-3-Clause license 📜

kefir is developed and maintained by Jevgenij Protopopov (legally: Jevgenijs Protopopovs) 👑

please report bugs found in kefir to jevgenij@protopopov.lv — like, actually do it, don't just complain in the group chat 🙈

kefir is available online at https://sr.ht/~jprotopopov/kefir with read-only mirrors at https://git.protopopov.lv/kefir and https://codeberg.org/jprotopopov/kefir 🌈

and that's the whole page bestie, you're officially caught up 💖 this one's the Debian build from September 2025, filed under kefir(1) — go compile something iconic, periodt ✨🎀

📦 where this page comes from