kefir - Man Page

C17 language compiler

Synopsis

kefir

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

kefir command-line options follow c99(1) compiler interface, extending it with some of supported gcc(1) flags and flags for special kefir features. Unknown command-line flags are ignored with a warning printed for each such flag passed to the compiler. kefir compiler driver features multiple operation modes. Command-line flags are parsed in left-to-right order with later flags overriding earlier. Some of operation modes, once selected, prevent further parsing and immediately invoke selected mode (refer to 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
--envinronment-info: Print compiler environment information (see Environment section below)
--environment-header: Print compiler environment header file (based on Environment section and current target)
-verbose: Report commands executed by the driver verbosely

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

The rest of command-line options are parsed normally:

-c: Skip the link-edit phase of the compilation, save object files
-S: Skip 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, save results
-o file: Save results to the output file
--target specification: Generate code for specified target system (see Target section below)
-O level: Code optimization level (default is 0). All non-zero levels are equivalent to 1
-fpreprocessed: Skip preprocessing stage
-D name[=value]: Define preprocessor macro
-U name: Undefine predefined preprocessor macro
-I directory: Add directory to preprocessor include 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)
-MT target: Override the default target name of make rule produced by dependency generation (used with -M and -MM options)
-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
-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 envinronment variable shall be 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
-nortlib: Do not link runtime routine library
-nostdinc: Do not add standard library to include path
-nortinc: Do not add runtime includes to include path
--soft-atomics: Enables atomic support via software library. Implies --Wdeclare-atomic-support option and links appropriate atomic primitives library (libatomic/libcompiler_rt). Unavailable for musl target.
--no-soft-atomics: Disables atomic support via software library. 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
-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
--print-runtime-code: Print runtime code for selected target
-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 -W switch:

--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 Target subsection)
--source-id identifier: Force use provided source file identifier
--sys-include-path dir: Add directory to include search path and mark it as a system include path (used for dependency output)
--debug-info: Include debug information into produced output
--feature-[name]: Enable compiler feature (see Features subsection)
--no-feature-[name]: Disable compiler feature (see Features subsection)
--internal-[flag]: Enable compiler internal flag (see INTERNALS subsection)
--no-internal-[flag]: Disable compiler internal flag (see INTERNALS subsection)
--codegen-[option]: Enable option for code generator (see Codegen subsection)
--no-codegen-[option]: Disable option for code generator (see Codegen subsection)
--optimizer-pipeline spec: Optimizer pipeline specification (see Optimizer subsection)
--precise-bitfield-load-store: Load and store bitfields at byte boundaries [default: on]. Provides extra correctness for structures allocated close to a boundary with unmapped memory pages at the expense of less efficient bitfield handling. Does not change bitfield layout.
--no-precise-bitfield-load-store: Load and store bitfields at machine word boundaries [default: off]. May cause failures for structures allocated close to boundaries with unmapped memory pages. Does not change bitfield layout.
--declare-atomic-support: Declare support of atomics (requires explicit linking of software atomic library such as libatomic or libcompiler_rt). Default for Glibc and BSD targets.
--no-declare-atomic-support: Declare the absence of atomic support via defining __STDC_NO_ATOMICS__ macro. Default for musl target.

Features

Supported features (to be used with --Wfeature-[feature-name] and --Wno-feature-[feature-name] flags):

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

Codegen

Supported code geneator options (to be used with --Wcodegen-[option] and --Wno-codegen-[option] flags):

emulated-tls

Use emulated TLS [disabled by default, enabled on openbsd platforms]

pic

Generate position-independent code

omit-frame-pointer

Omit frame pointer in leaf function that do not need it

no-omit-frame-pointer

Always use frame pointer in all functions

syntax=SYNTAX

Produce assembly output with specified syntax [x86_64-intel_noprefix, x86_64-intel_prefix, x86_64-att (default), x86_64-yasm].

details=DETAILS-SPEC

Augment assembly output with internal code generator details in comments. DETAILS-SPEC can be: vasm (virtual assembly), vasm+regs (virtual assembly and register allocations), devasm (devirtualized assembly).

pipeline=PIPELINE-SPEC

Code generator transformation pipeline specification consists of comma separated names of pipeline passes:

noop: No-operation pass
amd64-drop-virtual: Non-functional virtual instruction elimination for amd64 targets
amd64-peephole: Peephole optimizations for amd64 targets

Optimizer

Optimizer pipeline specification consists of comma separated names of pipeline passes:

noop: No-operation pass
phi-pull: Substitue phi nodes of SSA representation that unambiguously point to constant values
mem2reg: Pull function local variables into registers
op-simplify: General code simplification
constant-fold: Folding constant expressions
branch-removal: Eliminating branches with constant conditions

Target

Target platforms are specified in 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 optional parts of the target specification. Variant "none" avoids any implicit library linkages and include path. On linux, "default" is equivalent to "gnu", on other platforms -- to "system".

Environment

Environment variables that affect kefir operation:

KEFIR_AS | AS: Override the default "as" assembler
KEFIR_LD | LD: Override the default "ld" linker
KEFIR_RTLIB: Specify kefir runtime library location. Optional: it not specified, built-in runtime library will be used.
KEFIR_RTINC: Specify kefir runtime include location. Mandatory for all platform variants except "*-none"
KEFIR_MUSL_INCLUDE: Specify musl include paths (separated by ';'). Mandatory for "linux-musl" platform variant
KEFIR_MUSL_LIB: Specify musl library paths (separated by ';'). Mandatory for "linux-musl" platform variant
KEFIR_MUSL_DYNAMIC_LINKER: Specify dynamic linker path. Optional for "linux-musl" platform variant
KEFIR_GNU_INCLUDE: Specify GNU include paths (separated by ';'). Mandatory for "linux-gnu" platform variant
KEFIR_GNU_LIB: Specify GNU library paths (separated by ';'). Mandatory for "linux-gnu" platform variant
KEFIR_GNU_DYNAMIC_LINKER: Specify dynamic linker path. Optional for "linux-gnu" platform variant
KEFIR_FREEBSD_INCLUDE: Specify FreeBSD include paths (separated by ';'). Mandatory for "freebsd-system" platform variant
KEFIR_FREEBSD_LIB: Specify FreeBSD library paths (separated by ';'). Mandatory for "freebsd-system" platform variant
KEFIR_FREEBSD_DYNAMIC_LINKER: Specify dynamic linker path. Optional for "freebsd-system" platform variant
KEFIR_OPENBSD_INCLUDE: Specify OpenBSD include paths (separated by ';'). Mandatory for "openbsd-system" platform variant
KEFIR_OPENBSD_LIB: Specify OpenBSD library paths (separated by ';'). Mandatory for "openbsd-system" platform variant
KEFIR_OPENBSD_DYNAMIC_LINKER: Specify dynamic linker path. Optional for "openbsd-system" platform variant
KEFIR_TMPDIR: Override kefir temporary directory

Please report bugs found in kefir to jevgenij@protopopov.lv

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

Info

September 2024