Skip to content

usage.md

Latest commit

 

History

History
59 lines (41 loc) · 3.65 KB

usage.md

File metadata and controls

59 lines (41 loc) · 3.65 KB

Command-Line Interface (CLI) Guide

The Aburiscript compiler driver is designed to feel familiar if you have used GCC or Clang. The executable is aburi, and it processes command-line arguments to determine the compilation mode, ABI targets, and output formats.

Basic Usage

To compile a standard C or C++ file into an executable (invoking the system linker automatically):

aburi main.c -o my_program

Compilation Modes

You can instruct aburi to stop at specific stages of the pipeline:

  • -E (Preprocess Only): Stops after the preprocessor. Outputs raw C/C++ source code with all #includes resolved and macros expanded.
  • -fsyntax-only (Parse + Collect Only): Stops after preprocessing, parsing, and Collect. No LLVM IR, object file, or executable is produced.
  • --emit-llvm (Emit LLVM IR): Stops after ast2llvm lowering. Outputs human-readable LLVM Intermediate Representation (.ll). Highly recommended for debugging code generation.
  • -S (Emit Assembly): Stops after the LLVM backend optimization passes. Outputs target assembly (.s).
  • -c (Compile to Object): Stops before linking. Outputs a machine code object file (.o).

Language and Standard Options

  • -x <language>: Force the compiler to treat the input file as a specific language, regardless of its file extension.
    • -x c
    • -x c++
  • -std=<standard>: Set the language standard.
    • Examples: -std=c99, -std=c11, -std=c++20.
  • -stdlib=<family>: Select the C++ standard library family used for frontend header discovery.
    • Options: auto, libc++, libstdc++
    • On macOS, auto currently resolves to libc++.
    • Darwin libc++ discovery also probes SDKROOT plus Command Line Tools and Xcode SDKs/ directories when present.

Advanced and ABI Flags

The driver allows overriding specific ABI behaviors, which is crucial for cross-compilation or testing edge cases.

  • -fexceptions / -fno-exceptions: Enable or disable C++ exception handling (try/catch/throw).
  • -fexception-runtime=<profile>: Select the exception runtime profile to link against.
    • Options: llvm, gcc, custom.
  • -fc++-abi=<abi>: Force a specific C++ ABI model. aburi defaults to itanium.
  • -fabi-version=<version>: Specify the exact version of the ABI to target.
  • -mms-bitfields: Enable Microsoft-compatible struct bitfield layout rules.
  • --ast-memory-report: A debugging flag that prints a report of AST node allocations and side-table usage at the end of compilation.

Build System Compatibility (Meson)

When compiling large, real-world projects like mpv, libplacebo, or gstreamer that use the Meson build system, you may need aburi to identify itself and behave like Clang so the build scripts configure correctly.

You can activate the Clang compat persona using:

  • --driver-mode=clang (or --driver-mode=clang-compat)

Alternatively, you can create a symlink to the aburi executable named clang or aburi-clang, and the compiler will automatically detect the invocation name and switch to the Clang compatibility persona. This ensures version strings and specific driver behaviors mimic Clang to satisfy Meson's compiler checks.

More info here: meson-build/meson: Support generic POSIX C compiler.

Passthrough Behavior

If you pass a file that the aburi frontend does not recognize (like a .s assembly file, or a .m Objective-C file), aburi will act as a passthrough driver. It will automatically delegate the compilation of that specific file to your system's default compiler (usually /usr/bin/cc), passing along relevant linker flags.