c3c(1)

NAME
c3c - Compiler for the C3 programming language

SYNOPSIS
c3c [options ...] command [args ...]

DESCRIPTION
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.

COMMANDS

c3c compile file1 [file2 ...]
    Compile files without a project into an executable.

c3c init project name
    Initialize a new project structure.

c3c init-lib library name
    Initialize a new library structure.

c3c build [target]
    Build the target in the current project.

c3c benchmark [target]
    Run the benchmarks for the target in the current project.

c3c test [target]
    Run the unit tests for the target in the current project.

c3c clean
    Clean all build files.

c3c run [target] [-- [arg1 ...]]
    Run (and build if needed) the target in the current project.

c3c dist [target]
    Clean and build a target for distribution.

c3c clean-run [target] [-- [arg1 ...]]
    Clean, then run the target.

c3c compile-run file1 [file2 ...] [-- [arg1 ...]]
    Compile files then immediately run the result.

c3c compile-only file1 [file2 ...]
    Compile files but do not perform linking.

c3c compile-benchmark file1 [file2 ...]
    Compile files into a test-executable and run benchmarks.

c3c compile-test file1 [file2 ...]
    Compile files into a benchmark-executable and run unit tests.

c3c static-lib file1 [file2 ...]
    Compile files without a project into a static library.

c3c dynamic-lib file1 [file2 ...]
    Compile files without a project into a dynamic library.

c3c vendor-fetch library ...
    Fetches one or more libraries from the vendor collection.

c3c project subcommand ...
    Manipulate or view project files.

c3c fetch-sdk windows|macos|android ...
    Fetches the SDK required for cross-compiling.

c3c docgen [path1 path2 ...]
    Generate documentation for the project, or specific files and directories.

OPTIONS

-h, -hh, --help
    Print the help. -h for the normal options, -hh for the full help.

-V, --version
    Print version information.

-q, --quiet
    Silence unnecessary output.

-v, -vv, -vvv
    Verbose output. -v for default, -vv and -vvv gives more information.

-E
    Lex only.

-P
    Only parse and output the AST as JSON.

-C
    Only lex, parse and check.

- code...
    Read code from standard in.

-o file
    Write output to file.

-O0
    Safe, no optimizations, emit debug info.

-O1
    Safe, high optimization, emit debug info.

-O2
    Unsafe, high optimization, emit debug info.

-O3
    Unsafe, high optimization, single module, emit debug info.

-O4
    Unsafe, highest optimization, relaxed maths, single module, emit debug info, no panic messages.

-O5
    Unsafe, highest optimization, fast maths, single module, emit debug info, no panic messages, no backtrace.

-Os
    Unsafe, high optimization, small code, single module, no debug info, no panic messages.

-Oz
    Unsafe, high optimization, tiny code, single module, no debug info, no panic messages, no backtrace.

-D name
    Add feature flag name.

-U name
    Remove feature flag name.

--about
    Prints a short description of C3.

--build-env
    Prints build environment information (only valid in combination with a command such as 'compile').

--run-dir dir
    Set the directory from where to run the binary (only for run and compile-run).

--libdir dir
    Add this directory to the c3l library search paths.

--lib name
    Add this c3l library to the compilation.

--sources file1 [file2 ...]
    Add these additional sources to the compilation.

--validation= option
    Strictness of code validation: lenient (default), strict, obnoxious (very strict).

--stdlib dir
    Use this directory as the C3 standard library path.

--no-entry
    Do not generate (or require) a main function.

--path dir
    Use this as the base directory for the current command.

--template template
    Select template for 'init': "exe", "static-lib", "dynamic-lib" or a path.

--symtab value
    Sets the preferred symtab size.

--max-mem value
    Set the maximum memory size (in MB).

--run-once
    After running the output file, delete it immediately.

--suppress-run
    Build but do not run on test/benchmark options.

--trust= option
    Trust level: none (default), include ($include allowed), full ($exec / exec allowed).

--output-dir dir
    Override general output directory.

--build-dir dir
    Override build output directory.

--obj-out dir
    Override object file output directory.

--script-dir dir
    Override the base directory where scripts are searched.

--exec-dir dir
    Override the base directory for $exec and exec.

--llvm-out dir
    Override llvm output directory for '--emit-llvm'.

--asm-out dir
    Override asm output directory for '--emit-asm'.

--header-output dir
    Override header file output directory when building libraries.

--emit-llvm
    Emit LLVM IR as a .ll file per module.

--emit-asm
    Emit asm as a .s file per module.

--obj
    Emit object files (enabled by default).

--no-obj
    Do not output object files; this is only valid for `compile-only`.

--no-headers
    Do not generate C headers when building a library.

--target target
    Compile for a particular architecture + OS target.

--threads number
    Set the number of threads to use for compilation.

--safe= yes|no
    Turn safety (contracts, runtime bounds checking, null pointer checks etc) on or off.

--panic-msg= yes|no
    Turn panic message output on or off.

--optlevel= option
    Code optimization level: none, less, more, max.

--optsize= option
    Code size optimization: none, small, tiny.

--unroll-loops= yes|no
    Enable loop unrolling.

--loop-vectorize= yes|no
    Enable loop auto-vectorization.

--slp-vectorize= yes|no
    Enable SLP (superword-level parallelism) auto-vectorization.

--merge-functions= yes|no
    Enable function merging.

--single-module= yes|no
    Compile all modules together, enables more inlining.

--show-backtrace= yes|no
    Show detailed backtrace on segfaults.

--lsp
    Emit data about errors suitable for a LSP.

--print-large-functions
    Print functions with large compile size.

--warn-deadcode= yes|no|error
    Print warning on dead-code: yes, no, error.

--warn-recursivecontracts= yes|no|error
    Print warning on recursive contracts: yes, no, error.

--warn-methodvisibility= yes|no|error
    Print warning when methods have ignored visibility attributes.

--warn-methodsnotresolved= yes|no|error
    Print warning on methods not resolved when accessed: yes, no, error.

--warn-deprecation= yes|no|error
    Print warning when using deprecated code and constructs: yes, no, error.

--warn-builtin= yes|no|error
    Print warning when using builtin functions outside of the stdlib: yes, no, error.

-g
    Emit debug info.

-g0
    Emit no debug info.

--ansi= yes|no
    Set colour output using ansi on/off, default is to try to detect it.

--echo-prefix arg
    Sets the prefix for any output using '$echo', defaults to 'c3c:'.

--test-filter arg
    Set a filter when running tests, running only matching tests.

--test-breakpoint
    When running tests, trigger a breakpoint on failure.

--test-nosort
    Do not sort tests.

--test-noleak
    Disable tracking allocator and memory leak detection for tests.

--test-show-output
    Disable test stdout capturing, all tests can print as they run.

--test-nocapture
    Disable test stdout capturing, all tests can print as they run, same as --test-show-output.

--test-quiet
    Run tests without printing full names, printing output only on failure.

--test-log-level= verbose|debug|info|warn|error|critical
    Set log priority when running tests.

--benchmark-csv-report
    Print a CSV report after benchmarks have completed.

-l library
    Link with the static or dynamic library provided.

-L library dir
    Append the directory to the linker search paths.

-z argument
    Send the argument as a parameter to the linker.

--cc path
    Set C compiler (for C files in projects and use as system linker).

--linker= option [path]
    Linker: builtin, cc, custom (default is 'cc'), 'custom' requires a path.

--use-stdlib= yes|no
    Include the standard library (default: yes).

--link-libc= yes|no
    Link libc and other default libraries (default: yes).

--custom-libc= yes|no
    Set to true if a custom libc implementation is provided (default: no).

--emit-stdlib= yes|no
    Output files for the standard library (default: yes).

--emit-only file
    Output only the file matching file.

--panicfn name
    Override the panic function name.

--testfn name
    Override the test runner function name.

--benchfn name
    Override the benchmark runner function name.

--reloc= option
    Relocation model: none, pic, PIC, pie, PIE.

--cpu-flags string
    Add/remove cpu flags from the default, e.g. '+a,-b'.

--x86cpu= option
    Set general level of x64 cpu: baseline, ssse3, sse4, avx1, avx2-v1, avx2-v2 (Skylake/Zen1+), avx512 (Icelake/Zen4+), native.

--x86vec= option
    Set max type of vector use: none, mmx, sse, avx, avx512, default.

--riscv-abi= option
    Set type of RISC-V ABI: int-only, float, double.

--riscv-cpu= option
    Set the general level of RISC-V cpu: rvi (default 32-bit), rvimac, rvimafc, rvgc (default 64-bit), rvgcv.

--memory-env= option
    Set the memory environment: normal, small, tiny, none.

--strip-unused= yes|no
    Strip unused code and globals from the output (default: yes).

--fp-math= option
    FP math behaviour: strict, relaxed, fast.

--win64-simd= option
    Win64 SIMD ABI: array, full.

--win-debug= option
    Select debug output on Windows: codeview or dwarf (default: codeview).

--max-vector-size number
    Set the maximum vector bit size to allow (default: 4096).

--max-stack-object-size number
    Set the maximum size of a stack object in KB (default: 128).

--max-macro-iterations number
    Set the maximum number of iterations in a macro loop (default: 1048575).

--print-linking
    Print linker arguments.

--benchmarking
    Run built-in benchmarks.

--testing
    Run built-in tests.

--list-attributes
    List all attributes.

--list-builtins
    List all builtins.

--list-keywords
    List all keywords.

--list-operators
    List all operators.

--list-precedence
    List operator precedence order.

--list-project-properties
    List all available keys used in project.json files.

--list-manifest-properties
    List all available keys used in manifest.json files.

--list-targets
    List all architectures the compiler supports.

--list-type-properties
    List all type properties.

--list-asm
    List all asm instructions for the current target (must be used in combination with a compilation command such as 'compile' or 'build').

--print-output
    Print the object files created to stdout.

--print-input
    Print inputted C3 files to stdout.

--win-sdk dir
    Set the directory for Windows system library files for cross compilation.

--wincrt= option
    Windows CRT linking: none, static-debug, static, dynamic-debug (default if debug info enabled), dynamic (default).

--windef file
    Use Windows 'def' file for function exports instead of 'dllexport'.

--win-vs-dirs dir;dir
    Override Windows VS detection.

--win-subsystem= subsystem
    Windows subsystem: console (default), windows (default if @winmain present), native, posix, boot, efi-app, efi-boot, efi-rom or efi-runtime.

--macos-sdk dir
    Set the directory for the MacOS SDK for cross compilation.

--macos-min-version ver
    Set the minimum MacOS version to compile for.

--macos-sdk-version ver
    Set the MacOS SDK compiled for.

--linux-libc= host|gnu|musl
    Set the libc to use on Linux, defaults to host.

--linux-crt dir
    Set the directory to use for finding crt1.o and related files.

--linux-crtbegin dir
    Set the directory to use for finding crtbegin.o and related files.

--android-ndk dir
    Set the NDK directory location.

--android-api ver
    Set Android API version.

--bsd-sysroot dir
    Set the BSD sysroot directory.

--sanitize= option
    Enable sanitizer: address, memory, thread.

EXAMPLES

Create a project:
    c3c init new_project

Create a library project:
    c3c init-lib new_library

Compile a file:
    c3c compile main.c3

Build the current project:
    c3c build

Run tests for the current project:
    c3c test