.TH "c3c" "1" "2026-07-03" "C3 Compiler" "User Commands"
.SH NAME
c3c \- Compiler for the C3 programming language

.SH SYNOPSIS
.B c3c
[\fIoptions\fR ...] \fIcommand\fR [\fIargs\fR ...]

.SH DESCRIPTION
.B c3c
is the compiler for the C3 language, providing commands for compilation, project
management, testing, and distribution. The available commands allow users to
compile files, initialize projects, build targets, run benchmarks, clean build
files, and more.

.SH COMMANDS
.PP
.B c3c compile
\fIfile1\fR [\fIfile2\fR ...]
.RS
Compile files without a project into an executable.
.RE
.PP
.B c3c init
\fIproject name\fR
.RS
Initialize a new project structure.
.RE
.PP
.B c3c init-lib
\fIlibrary name\fR
.RS
Initialize a new library structure.
.RE
.PP
.B c3c build
[\fItarget\fR]
.RS
Build the target in the current project.
.RE
.PP
.B c3c benchmark
[\fItarget\fR]
.RS
Run the benchmarks for the target in the current project.
.RE
.PP
.B c3c test
[\fItarget\fR]
.RS
Run the unit tests for the target in the current project.
.RE
.PP
.B c3c clean
.RS
Clean all build files.
.RE
.PP
.B c3c run
[\fItarget\fR] [-- [\fIarg1\fR ...]]
.RS
Run (and build if needed) the target in the current project.
.RE
.PP
.B c3c dist
[\fItarget\fR]
.RS
Clean and build a target for distribution.
.RE
.PP
.B c3c clean-run
[\fItarget\fR] [-- [\fIarg1\fR ...]]
.RS
Clean, then run the target.
.RE
.PP
.B c3c compile-run
\fIfile1\fR [\fIfile2\fR ...] [-- [\fIarg1\fR ...]]
.RS
Compile files then immediately run the result.
.RE
.PP
.B c3c compile-only
\fIfile1\fR [\fIfile2\fR ...]
.RS
Compile files but do not perform linking.
.RE
.PP
.B c3c compile-benchmark
\fIfile1\fR [\fIfile2\fR ...]
.RS
Compile files into a test-executable and run benchmarks.
.RE
.PP
.B c3c compile-test
\fIfile1\fR [\fIfile2\fR ...]
.RS
Compile files into a benchmark-executable and run unit tests.
.RE
.PP
.B c3c static-lib
\fIfile1\fR [\fIfile2\fR ...]
.RS
Compile files without a project into a static library.
.RE
.PP
.B c3c dynamic-lib
\fIfile1\fR [\fIfile2\fR ...]
.RS
Compile files without a project into a dynamic library.
.RE
.PP
.B c3c vendor-fetch
\fIlibrary\fR ...
.RS
Fetches one or more libraries from the vendor collection.
.RE
.PP
.B c3c project
\fIsubcommand\fR ...
.RS
Manipulate or view project files.
.RE
.PP
.B c3c fetch-sdk
\fIwindows|macos|android\fR ...
.RS
Fetches the SDK required for cross-compiling.
.RE
.PP
.B c3c docgen
[\fIpath1\fR \fIpath2\fR ...]
.RS
Generate documentation for the project, or specific files and directories.
.RE

.SH OPTIONS
.PP
.B -h, -hh, --help
.RS
Print the help. -h for the normal options, -hh for the full help.
.RE
.PP
.B -V, --version
.RS
Print version information.
.RE
.PP
.B -q, --quiet
.RS
Silence unnecessary output.
.RE
.PP
.B -v, -vv, -vvv
.RS
Verbose output. -v for default, -vv and -vvv gives more information.
.RE
.PP
.B -E
.RS
Lex only.
.RE
.PP
.B -P
.RS
Only parse and output the AST as JSON.
.RE
.PP
.B -C
.RS
Only lex, parse and check.
.RE
.PP
.B -
\fIcode\fR...
.RS
Read code from standard in.
.RE
.PP
.B -o
\fIfile\fR
.RS
Write output to \fIfile\fR.
.RE
.PP
.B -O0
.RS
Safe, no optimizations, emit debug info.
.RE
.PP
.B -O1
.RS
Safe, high optimization, emit debug info.
.RE
.PP
.B -O2
.RS
Unsafe, high optimization, emit debug info.
.RE
.PP
.B -O3
.RS
Unsafe, high optimization, single module, emit debug info.
.RE
.PP
.B -O4
.RS
Unsafe, highest optimization, relaxed maths, single module, emit debug info, no panic messages.
.RE
.PP
.B -O5
.RS
Unsafe, highest optimization, fast maths, single module, emit debug info, no panic messages, no backtrace.
.RE
.PP
.B -Os
.RS
Unsafe, high optimization, small code, single module, no debug info, no panic messages.
.RE
.PP
.B -Oz
.RS
Unsafe, high optimization, tiny code, single module, no debug info, no panic messages, no backtrace.
.RE
.PP
.B -D
\fIname\fR
.RS
Add feature flag \fIname\fR.
.RE
.PP
.B -U
\fIname\fR
.RS
Remove feature flag \fIname\fR.
.RE
.PP
.B --about
.RS
Prints a short description of C3.
.RE
.PP
.B --build-env
.RS
Prints build environment information (only valid in combination with a command such as 'compile').
.RE
.PP
.B --run-dir
\fIdir\fR
.RS
Set the directory from where to run the binary (only for run and compile-run).
.RE
.PP
.B --libdir
\fIdir\fR
.RS
Add this directory to the c3l library search paths.
.RE
.PP
.B --lib
\fIname\fR
.RS
Add this c3l library to the compilation.
.RE
.PP
.B --sources
\fIfile1\fR [\fIfile2\fR ...]
.RS
Add these additional sources to the compilation.
.RE
.PP
.B --validation=
\fIoption\fR
.RS
Strictness of code validation: lenient (default), strict, obnoxious (very strict).
.RE
.PP
.B --stdlib
\fIdir\fR
.RS
Use this directory as the C3 standard library path.
.RE
.PP
.B --no-entry
.RS
Do not generate (or require) a main function.
.RE
.PP
.B --path
\fIdir\fR
.RS
Use this as the base directory for the current command.
.RE
.PP
.B --template
\fItemplate\fR
.RS
Select template for 'init': "exe", "static-lib", "dynamic-lib" or a path.
.RE
.PP
.B --symtab
\fIvalue\fR
.RS
Sets the preferred symtab size.
.RE
.PP
.B --max-mem
\fIvalue\fR
.RS
Set the maximum memory size (in MB).
.RE
.PP
.B --run-once
.RS
After running the output file, delete it immediately.
.RE
.PP
.B --suppress-run
.RS
Build but do not run on test/benchmark options.
.RE
.PP
.B --trust=
\fIoption\fR
.RS
Trust level: none (default), include ($include allowed), full ($exec / exec allowed).
.RE
.PP
.B --output-dir
\fIdir\fR
.RS
Override general output directory.
.RE
.PP
.B --build-dir
\fIdir\fR
.RS
Override build output directory.
.RE
.PP
.B --obj-out
\fIdir\fR
.RS
Override object file output directory.
.RE
.PP
.B --script-dir
\fIdir\fR
.RS
Override the base directory where scripts are searched.
.RE
.PP
.B --exec-dir
\fIdir\fR
.RS
Override the base directory for $exec and exec.
.RE
.PP
.B --llvm-out
\fIdir\fR
.RS
Override llvm output directory for '--emit-llvm'.
.RE
.PP
.B --asm-out
\fIdir\fR
.RS
Override asm output directory for '--emit-asm'.
.RE
.PP
.B --header-output
\fIdir\fR
.RS
Override header file output directory when building libraries.
.RE
.PP
.B --emit-llvm
.RS
Emit LLVM IR as a .ll file per module.
.RE
.PP
.B --emit-asm
.RS
Emit asm as a .s file per module.
.RE
.PP
.B --obj
.RS
Emit object files (enabled by default).
.RE
.PP
.B --no-obj
.RS
Do not output object files; this is only valid for `compile-only`.
.RE
.PP
.B --no-headers
.RS
Do not generate C headers when building a library.
.RE
.PP
.B --target
\fItarget\fR
.RS
Compile for a particular architecture + OS target.
.RE
.PP
.B --threads
\fInumber\fR
.RS
Set the number of threads to use for compilation.
.RE
.PP
.B --safe=
\fIyes|no\fR
.RS
Turn safety (contracts, runtime bounds checking, null pointer checks etc) on or off.
.RE
.PP
.B --panic-msg=
\fIyes|no\fR
.RS
Turn panic message output on or off.
.RE
.PP
.B --optlevel=
\fIoption\fR
.RS
Code optimization level: none, less, more, max.
.RE
.PP
.B --optsize=
\fIoption\fR
.RS
Code size optimization: none, small, tiny.
.RE
.PP
.B --unroll-loops=
\fIyes|no\fR
.RS
Enable loop unrolling.
.RE
.PP
.B --loop-vectorize=
\fIyes|no\fR
.RS
Enable loop auto-vectorization.
.RE
.PP
.B --slp-vectorize=
\fIyes|no\fR
.RS
Enable SLP (superword-level parallelism) auto-vectorization.
.RE
.PP
.B --merge-functions=
\fIyes|no\fR
.RS
Enable function merging.
.RE
.PP
.B --single-module=
\fIyes|no\fR
.RS
Compile all modules together, enables more inlining.
.RE
.PP
.B --show-backtrace=
\fIyes|no\fR
.RS
Show detailed backtrace on segfaults.
.RE
.PP
.B --lsp
.RS
Emit data about errors suitable for a LSP.
.RE
.PP
.B --print-large-functions
.RS
Print functions with large compile size.
.RE
.PP
.B --warn-deadcode=
\fIyes|no|error\fR
.RS
Print warning on dead-code: yes, no, error.
.RE
.PP
.B --warn-recursivecontracts=
\fIyes|no|error\fR
.RS
Print warning on recursive contracts: yes, no, error.
.RE
.PP
.B --warn-methodvisibility=
\fIyes|no|error\fR
.RS
Print warning when methods have ignored visibility attributes.
.RE
.PP
.B --warn-methodsnotresolved=
\fIyes|no|error\fR
.RS
Print warning on methods not resolved when accessed: yes, no, error.
.RE
.PP
.B --warn-deprecation=
\fIyes|no|error\fR
.RS
Print warning when using deprecated code and constructs: yes, no, error.
.RE
.PP
.B --warn-builtin=
\fIyes|no|error\fR
.RS
Print warning when using builtin functions outside of the stdlib: yes, no, error.
.RE
.PP
.B -g
.RS
Emit debug info.
.RE
.PP
.B -g0
.RS
Emit no debug info.
.RE
.PP
.B --ansi=
\fIyes|no\fR
.RS
Set colour output using ansi on/off, default is to try to detect it.
.RE
.PP
.B --echo-prefix
\fIarg\fR
.RS
Sets the prefix for any output using '$echo', defaults to 'c3c:'.
.RE
.PP
.B --test-filter
\fIarg\fR
.RS
Set a filter when running tests, running only matching tests.
.RE
.PP
.B --test-breakpoint
.RS
When running tests, trigger a breakpoint on failure.
.RE
.PP
.B --test-nosort
.RS
Do not sort tests.
.RE
.PP
.B --test-noleak
.RS
Disable tracking allocator and memory leak detection for tests.
.RE
.PP
.B --test-show-output
.RS
Disable test stdout capturing, all tests can print as they run.
.RE
.PP
.B --test-nocapture
.RS
Disable test stdout capturing, all tests can print as they run, same as --test-show-output.
.RE
.PP
.B --test-quiet
.RS
Run tests without printing full names, printing output only on failure.
.RE
.PP
.B --test-log-level=
\fIverbose|debug|info|warn|error|critical\fR
.RS
Set log priority when running tests.
.RE
.PP
.B --benchmark-csv-report
.RS
Print a CSV report after benchmarks have completed.
.RE
.PP
.B -l
\fIlibrary\fR
.RS
Link with the static or dynamic library provided.
.RE
.PP
.B -L
\fIlibrary dir\fR
.RS
Append the directory to the linker search paths.
.RE
.PP
.B -z
\fIargument\fR
.RS
Send the \fIargument\fR as a parameter to the linker.
.RE
.PP
.B --cc
\fIpath\fR
.RS
Set C compiler (for C files in projects and use as system linker).
.RE
.PP
.B --linker=
\fIoption\fR [\fIpath\fR]
.RS
Linker: builtin, cc, custom (default is 'cc'), 'custom' requires a path.
.RE
.PP
.B --use-stdlib=
\fIyes|no\fR
.RS
Include the standard library (default: yes).
.RE
.PP
.B --link-libc=
\fIyes|no\fR
.RS
Link libc and other default libraries (default: yes).
.RE
.PP
.B --custom-libc=
\fIyes|no\fR
.RS
Set to true if a custom libc implementation is provided (default: no).
.RE
.PP
.B --emit-stdlib=
\fIyes|no\fR
.RS
Output files for the standard library (default: yes).
.RE
.PP
.B --emit-only
\fIfile\fR
.RS
Output only the file matching \fIfile\fR.
.RE
.PP
.B --panicfn
\fIname\fR
.RS
Override the panic function name.
.RE
.PP
.B --testfn
\fIname\fR
.RS
Override the test runner function name.
.RE
.PP
.B --benchfn
\fIname\fR
.RS
Override the benchmark runner function name.
.RE
.PP
.B --reloc=
\fIoption\fR
.RS
Relocation model: none, pic, PIC, pie, PIE.
.RE
.PP
.B --cpu-flags
\fIstring\fR
.RS
Add/remove cpu flags from the default, e.g. '+a,-b'.
.RE
.PP
.B --x86cpu=
\fIoption\fR
.RS
Set general level of x64 cpu: baseline, ssse3, sse4, avx1, avx2-v1, avx2-v2 (Skylake/Zen1+), avx512 (Icelake/Zen4+), native.
.RE
.PP
.B --x86vec=
\fIoption\fR
.RS
Set max type of vector use: none, mmx, sse, avx, avx512, default.
.RE
.PP
.B --riscv-abi=
\fIoption\fR
.RS
Set type of RISC-V ABI: int-only, float, double.
.RE
.PP
.B --riscv-cpu=
\fIoption\fR
.RS
Set the general level of RISC-V cpu: rvi (default 32-bit), rvimac, rvimafc, rvgc (default 64-bit), rvgcv.
.RE
.PP
.B --memory-env=
\fIoption\fR
.RS
Set the memory environment: normal, small, tiny, none.
.RE
.PP
.B --strip-unused=
\fIyes|no\fR
.RS
Strip unused code and globals from the output (default: yes).
.RE
.PP
.B --fp-math=
\fIoption\fR
.RS
FP math behaviour: strict, relaxed, fast.
.RE
.PP
.B --win64-simd=
\fIoption\fR
.RS
Win64 SIMD ABI: array, full.
.RE
.PP
.B --win-debug=
\fIoption\fR
.RS
Select debug output on Windows: codeview or dwarf (default: codeview).
.RE
.PP
.B --max-vector-size
\fInumber\fR
.RS
Set the maximum vector bit size to allow (default: 4096).
.RE
.PP
.B --max-stack-object-size
\fInumber\fR
.RS
Set the maximum size of a stack object in KB (default: 128).
.RE
.PP
.B --max-macro-iterations
\fInumber\fR
.RS
Set the maximum number of iterations in a macro loop (default: 1048575).
.RE
.PP
.B --print-linking
.RS
Print linker arguments.
.RE
.PP
.B --benchmarking
.RS
Run built-in benchmarks.
.RE
.PP
.B --testing
.RS
Run built-in tests.
.RE
.PP
.B --list-attributes
.RS
List all attributes.
.RE
.PP
.B --list-builtins
.RS
List all builtins.
.RE
.PP
.B --list-keywords
.RS
List all keywords.
.RE
.PP
.B --list-operators
.RS
List all operators.
.RE
.PP
.B --list-precedence
.RS
List operator precedence order.
.RE
.PP
.B --list-project-properties
.RS
List all available keys used in project.json files.
.RE
.PP
.B --list-manifest-properties
.RS
List all available keys used in manifest.json files.
.RE
.PP
.B --list-targets
.RS
List all architectures the compiler supports.
.RE
.PP
.B --list-type-properties
.RS
List all type properties.
.RE
.PP
.B --list-asm
.RS
List all asm instructions for the current target (must be used in combination with a compilation command such as 'compile' or 'build').
.RE
.PP
.B --print-output
.RS
Print the object files created to stdout.
.RE
.PP
.B --print-input
.RS
Print inputted C3 files to stdout.
.RE
.PP
.B --win-sdk
\fIdir\fR
.RS
Set the directory for Windows system library files for cross compilation.
.RE
.PP
.B --wincrt=
\fIoption\fR
.RS
Windows CRT linking: none, static-debug, static, dynamic-debug (default if debug info enabled), dynamic (default).
.RE
.PP
.B --windef
\fIfile\fR
.RS
Use Windows 'def' file for function exports instead of 'dllexport'.
.RE
.PP
.B --win-vs-dirs
\fIdir;dir\fR
.RS
Override Windows VS detection.
.RE
.PP
.B --win-subsystem=
\fIsubsystem\fR
.RS
Windows subsystem: console (default), windows (default if @winmain present), native, posix, boot, efi-app, efi-boot, efi-rom or efi-runtime.
.RE
.PP
.B --macos-sdk
\fIdir\fR
.RS
Set the directory for the MacOS SDK for cross compilation.
.RE
.PP
.B --macos-min-version
\fIver\fR
.RS
Set the minimum MacOS version to compile for.
.RE
.PP
.B --macos-sdk-version
\fIver\fR
.RS
Set the MacOS SDK compiled for.
.RE
.PP
.B --linux-libc=
\fIhost|gnu|musl\fR
.RS
Set the libc to use on Linux, defaults to host.
.RE
.PP
.B --linux-crt
\fIdir\fR
.RS
Set the directory to use for finding crt1.o and related files.
.RE
.PP
.B --linux-crtbegin
\fIdir\fR
.RS
Set the directory to use for finding crtbegin.o and related files.
.RE
.PP
.B --android-ndk
\fIdir\fR
.RS
Set the NDK directory location.
.RE
.PP
.B --android-api
\fIver\fR
.RS
Set Android API version.
.RE
.PP
.B --bsd-sysroot
\fIdir\fR
.RS
Set the BSD sysroot directory.
.RE
.PP
.B --sanitize=
\fIoption\fR
.RS
Enable sanitizer: address, memory, thread.
.RE

.SH EXAMPLES
.PP
Create a project:
.RS
.B c3c init new_project
.RE
.PP
Create a library project:
.RS
.B c3c init-lib new_library
.RE
.PP
Compile a file:
.RS
.B c3c compile main.c3
.RE
.PP
Build the current project:
.RS
.B c3c build
.RE
.PP
Run tests for the current project:
.RS
.B c3c test
.RE