docs: Update CLI documentation and improve LLVM backend

- Update README and CLI book chapter with LLVM backend usage
- Improve ast_builder with better node handling
- Refactor CLI backend module for cleaner code
- Update LLVM AOT backend with improved error handling

Author: darmie

README.md

@@ -40,36 +40,39 @@ The Zyntax command-line interface provides a unified compilation toolchain with
 # Build the CLI
 cargo build --release
 
-# Compile and run a program
-zyntax compile input.json -o myprogram --run
+# Compile and run a program with JIT
+zyntax compile input.json --jit
 
 # Multiple input formats supported
-zyntax compile program.zbc --format zbc -o output
-zyntax compile source.zyn --format zyn -o output --jit
+zyntax compile program.zbc --format hir-bytecode -o output
+zyntax compile --source code.calc --grammar calc.zyn --format zyn --jit
 ```
 
 ### CLI Features
 
 - **Dual-Format Support**: Compile from JSON TypedAST or ZBC bytecode
-- **JIT Execution**: Run programs directly with `--run` flag
+- **JIT Execution**: Run programs directly with `--jit` flag
 - **Multiple Backends**: Choose Cranelift (fast) or LLVM (optimized)
 - **Format Auto-Detection**: Automatically detects input format from file extension
 - **Rich Diagnostics**: Clear error messages with source location tracking
 
 ### Usage Examples
 
 ```bash
-# Compile JSON TypedAST to executable
+# Compile JSON TypedAST to executable (AOT)
 zyntax compile program.json -o myapp
 
-# Compile and run immediately
-zyntax compile program.json --run
+# JIT compile and run immediately
+zyntax compile program.json --jit
 
 # Compile ZBC bytecode format
 zyntax compile program.zbc -o myapp
 
-# Use specific backend
+# Use LLVM backend for maximum optimization
 zyntax compile program.json --backend llvm -o myapp
+
+# JIT with LLVM backend
+zyntax compile program.json --backend llvm --jit
 ```
 
 ---
@@ -192,11 +195,14 @@ WHITESPACE = _{ " " | "\t" | "\n" | "\r" }
 ### CLI Usage
 
 ```bash
-# Compile and run with grammar
-zyntax compile --source input.calc --grammar calc.zyn --format zyn --run
+# JIT compile and run with grammar
+zyntax compile --source input.calc --grammar calc.zyn --format zyn --jit
+
+# AOT compile to executable
+zyntax compile --source code.mylang --grammar mylang.zyn --format zyn -o output
 
-# Verbose mode shows compilation steps
-zyntax compile -v --source code.mylang --grammar mylang.zyn --format zyn -o output
+# Use LLVM backend for maximum optimization
+zyntax compile --source code.mylang --grammar mylang.zyn --backend llvm -o output
 
 # Interactive REPL mode
 zyntax repl --grammar calc.zyn

book/03-using-the-cli.md

@@ -42,12 +42,12 @@ zyntax compile --grammar <grammar.zyn> --source <file> [OPTIONS]
 
 ### Compile and Run (JIT)
 
-The most common workflow - compile and execute immediately:
+The most common workflow - JIT compile and execute immediately:
 
 ```bash
 zyntax compile --grammar crates/zyn_peg/grammars/zig.zyn \
                --source examples/hello.zig \
-               --run
+               --jit
 ```
 
 Output:
@@ -62,12 +62,21 @@ result: main() returned: 42
 | `--grammar` | `-g` | ZynPEG grammar file (.zyn) | Required |
 | `--source` | `-s` | Source file to compile | Required |
 | `--output` | `-o` | Output file path | None |
-| `--backend` | `-b` | Backend: `jit` or `llvm` | `jit` |
+| `--backend` | `-b` | Backend: `cranelift` or `llvm` | `cranelift` |
 | `--opt-level` | `-O` | Optimization: 0-3 | `2` |
-| `--run` | | Execute after compilation (JIT only) | Off |
+| `--jit` | | JIT compile and execute immediately | Off |
 | `--verbose` | `-v` | Show detailed output | Off |
 | `--format` | `-f` | Input format (see below) | `auto` |
 
+### Backends
+
+Zyntax supports two compilation backends:
+
+| Backend | Description | Use Case |
+|---------|-------------|----------|
+| `cranelift` | Fast compilation, good code quality | Development, JIT |
+| `llvm` | Maximum optimization, slower compilation | Production, AOT |
+
 ### Input Formats
 
 The `--format` option controls how input is interpreted:
@@ -81,38 +90,45 @@ The `--format` option controls how input is interpreted:
 
 ### Examples
 
-#### Compile and Run
+#### JIT Compile and Run
 
 ```bash
-# Simple execution
-zyntax compile -g zig.zyn -s test.zig --run
+# Simple execution with Cranelift (fast)
+zyntax compile -g zig.zyn -s test.zig --jit
 
 # With verbose output
-zyntax compile -g zig.zyn -s test.zig --run -v
+zyntax compile -g zig.zyn -s test.zig --jit -v
+
+# JIT with LLVM backend (maximum optimization)
+zyntax compile -g zig.zyn -s test.zig --backend llvm --jit
 ```
 
-#### Compile to Object File (LLVM)
+#### AOT Compile to Executable
 
 ```bash
-zyntax compile -g zig.zyn -s main.zig -b llvm -o main.o
+# Compile to native executable with Cranelift
+zyntax compile -g zig.zyn -s main.zig -o main
+
+# Compile with LLVM for maximum optimization
+zyntax compile -g zig.zyn -s main.zig --backend llvm -o main
 ```
 
 #### Optimization Levels
 
 ```bash
 # No optimization (fastest compile)
-zyntax compile -g zig.zyn -s test.zig -O0 --run
+zyntax compile -g zig.zyn -s test.zig -O0 --jit
 
 # Maximum optimization
-zyntax compile -g zig.zyn -s test.zig -O3 --run
+zyntax compile -g zig.zyn -s test.zig -O3 --jit
 ```
 
 #### Compile TypedAST JSON
 
 If you have pre-built TypedAST:
 
 ```bash
-zyntax compile program.json --run
+zyntax compile program.json --jit
 ```
 
 ## The `repl` Command
@@ -130,7 +146,7 @@ zyntax repl --grammar crates/zyn_peg/grammars/zig.zyn
 | Option | Short | Description | Default |
 |--------|-------|-------------|---------|
 | `--grammar` | `-g` | ZynPEG grammar file | Required |
-| `--backend` | `-b` | Backend (JIT only) | `jit` |
+| `--backend` | `-b` | Backend: `cranelift` or `llvm` | `cranelift` |
 | `--opt-level` | `-O` | Optimization: 0-3 | `0` |
 | `--verbose` | `-v` | Show parse details | Off |
 
@@ -223,7 +239,7 @@ When developing a grammar:
 zyntax repl -g mygrammar.zyn
 
 # Test a complete program
-zyntax compile -g mygrammar.zyn -s test.mylang --run
+zyntax compile -g mygrammar.zyn -s test.mylang --jit
 ```
 
 ### Testing Workflow
@@ -239,7 +255,7 @@ fn main() i32 {
 EOF
 
 # Run and verify
-zyntax compile -g zig.zyn -s /tmp/test_arithmetic.zig --run
+zyntax compile -g zig.zyn -s /tmp/test_arithmetic.zig --jit
 # Expected: result: main() returned: 14
 ```
 
@@ -253,7 +269,7 @@ GRAMMAR="crates/zyn_peg/grammars/zig.zyn"
 
 for file in tests/*.zig; do
     echo "Testing: $file"
-    zyntax compile -g "$GRAMMAR" -s "$file" --run
+    zyntax compile -g "$GRAMMAR" -s "$file" --jit
     echo "---"
 done
 ```
@@ -264,7 +280,7 @@ When something doesn't work:
 
 ```bash
 # Step 1: Check parsing with verbose
-zyntax compile -g mygrammar.zyn -s broken.mylang -v --run
+zyntax compile -g mygrammar.zyn -s broken.mylang -v --jit
 
 # Step 2: Simplify the input
 echo "1 + 2" | zyntax repl -g mygrammar.zyn -v
@@ -319,7 +335,7 @@ zyntax repl -g mygrammar.zyn
 When parsing fails unexpectedly:
 
 ```bash
-zyntax compile -g grammar.zyn -s file.src -v --run
+zyntax compile -g grammar.zyn -s file.src -v --jit
 ```
 
 ### 3. Create Minimal Test Cases
@@ -360,7 +376,7 @@ FAIL=0
 
 for test in tests/*.mylang; do
     expected="${test%.mylang}.expected"
-    result=$(zyntax compile -g "$GRAMMAR" -s "$test" --run 2>&1)
+    result=$(zyntax compile -g "$GRAMMAR" -s "$test" --jit 2>&1)
 
     if diff -q <(echo "$result") "$expected" > /dev/null; then
         echo "✓ $test"
@@ -383,10 +399,10 @@ echo "Passed: $PASS, Failed: $FAIL"
 
 ```bash
 # Debug logging
-RUST_LOG=debug zyntax compile -g zig.zyn -s test.zig --run
+RUST_LOG=debug zyntax compile -g zig.zyn -s test.zig --jit
 
 # Full backtrace on errors
-RUST_BACKTRACE=1 zyntax compile -g zig.zyn -s test.zig --run
+RUST_BACKTRACE=1 zyntax compile -g zig.zyn -s test.zig --jit
 ```
 
 ## Next Steps

crates/zyn_peg/generated/ast_builder.rs

@@ -1062,14 +1062,65 @@ impl AstBuilderContext {
             .iter()
             .find(|p| p.as_rule() == Rule::expr)
             .cloned();
+        // Build the actual assignment as a Binary expression with Assign operator
+        let target = child_assign_target
+            .as_ref()
+            .and_then(|p| self.build_assign_target(p.clone()).ok())
+            .unwrap_or_default();
+        let value = child_expr
+            .as_ref()
+            .and_then(|p| self.build_expr(p.clone()).ok())
+            .unwrap_or_default();
+        // Check for compound assignment operators (+=, -=, etc.)
+        let assign_op_str = child_assign_op.as_ref().map(|p| p.as_str()).unwrap_or("=");
+        let assign_expr = if assign_op_str == "=" {
+            // Simple assignment: target = value
+            typed_node(
+                TypedExpression::Binary(TypedBinary {
+                    op: BinaryOp::Assign,
+                    left: Box::new(target),
+                    right: Box::new(value),
+                }),
+                Type::Never,
+                span,
+            )
+        } else {
+            // Compound assignment: target op= value  =>  target = target op value
+            let op = match assign_op_str {
+                "+=" => BinaryOp::Add,
+                "-=" => BinaryOp::Sub,
+                "*=" => BinaryOp::Mul,
+                "/=" => BinaryOp::Div,
+                "%=" => BinaryOp::Mod,
+                "&=" => BinaryOp::BitAnd,
+                "|=" => BinaryOp::BitOr,
+                "^=" => BinaryOp::BitXor,
+                "<<=" => BinaryOp::Shl,
+                ">>=" => BinaryOp::Shr,
+                _ => BinaryOp::Assign, // Fallback
+            };
+            let compound_value = typed_node(
+                TypedExpression::Binary(TypedBinary {
+                    op,
+                    left: Box::new(target.clone()),
+                    right: Box::new(value),
+                }),
+                Type::Never,
+                span,
+            );
+            typed_node(
+                TypedExpression::Binary(TypedBinary {
+                    op: BinaryOp::Assign,
+                    left: Box::new(target),
+                    right: Box::new(compound_value),
+                }),
+                Type::Never,
+                span,
+            )
+        };
         Ok({
             typed_node(
-                TypedStatement::Expression(Box::new(
-                    child_expr
-                        .as_ref()
-                        .and_then(|p| self.build_expr(p.clone()).ok())
-                        .unwrap_or_default(),
-                )),
+                TypedStatement::Expression(Box::new(assign_expr)),
                 Type::Never,
                 span,
             )

crates/zyntax_cli/Cargo.toml

@@ -48,7 +48,7 @@ rustyline = "14.0"
 dirs = "5.0"
 
 # LLVM backend (optional)
-inkwell = { version = "0.4", features = ["llvm17-0"], optional = true }
+inkwell = { version = "0.7.1", features = ["llvm21-1"], optional = true }
 
 [features]
 default = []

crates/zyntax_cli/src/backends/llvm_aot.rs

@@ -48,6 +48,13 @@ pub fn compile_llvm(
 
     if verbose {
         info!("Generated {} bytes of LLVM IR", llvm_ir.len());
+        debug!("LLVM IR:\n{}", llvm_ir);
+        // Also write LLVM IR to file for debugging
+        let ir_path = output_path.with_extension("ll");
+        std::fs::write(&ir_path, &llvm_ir).unwrap_or_else(|e| {
+            error!("Failed to write LLVM IR: {}", e);
+        });
+        info!("Wrote LLVM IR to {:?}", ir_path);
     }
 
     // Get target triple for the host machine
@@ -197,36 +204,36 @@ pub fn compile_and_run_llvm(
         .get_function_pointer(main_id)
         .ok_or("Failed to get main function pointer")?;
 
-    if verbose {
-        debug!("Executing main() at {:?}...", fn_ptr);
-    }
+    debug!("Got main function pointer: {:p}", fn_ptr);
+    debug!("About to execute main()...");
 
     // Execute main function
+    // IMPORTANT: Use extern "C" calling convention to match LLVM's default
     let result = unsafe {
         if main_fn.signature.returns.is_empty() {
-            let f: fn() = std::mem::transmute(fn_ptr);
+            let f: extern "C" fn() = std::mem::transmute(fn_ptr);
             f();
             0
         } else {
             match &main_fn.signature.returns[0] {
                 zyntax_compiler::hir::HirType::I32 => {
-                    let f: fn() -> i32 = std::mem::transmute(fn_ptr);
+                    let f: extern "C" fn() -> i32 = std::mem::transmute(fn_ptr);
                     f() as i64
                 }
                 zyntax_compiler::hir::HirType::I64 => {
-                    let f: fn() -> i64 = std::mem::transmute(fn_ptr);
+                    let f: extern "C" fn() -> i64 = std::mem::transmute(fn_ptr);
                     f()
                 }
                 zyntax_compiler::hir::HirType::F32 => {
-                    let f: fn() -> f32 = std::mem::transmute(fn_ptr);
+                    let f: extern "C" fn() -> f32 = std::mem::transmute(fn_ptr);
                     f() as i64
                 }
                 zyntax_compiler::hir::HirType::F64 => {
-                    let f: fn() -> f64 = std::mem::transmute(fn_ptr);
+                    let f: extern "C" fn() -> f64 = std::mem::transmute(fn_ptr);
                     f() as i64
                 }
                 zyntax_compiler::hir::HirType::Void => {
-                    let f: fn() = std::mem::transmute(fn_ptr);
+                    let f: extern "C" fn() = std::mem::transmute(fn_ptr);
                     f();
                     0
                 }