CLI Usage Guide

Complete reference for the neurc command-line compiler.

Installation

After building from source:

# Install compiler globally
cargo install --path compiler/neurc

# Or run directly from source
cargo run -p neurc -- <command> <args>

Commands

check

Validate syntax and types without generating code.

Syntax:

neurc check <file.nr>

Examples:

# Check a single file
neurc check examples/basics/hello.nr

# With debug logging
RUST_LOG=debug neurc check examples/basics/milestone.nr

Output:

• Success: Type checking passed for "examples/basics/hello.nr" (1 module(s), 11 HIR items)
• Failure: Type errors found in "<file>": followed by a numbered error list, then Error: N type error(s) found

Exit codes:

• 0: No errors found
• 1: Errors found

compile

Compile Neuro source to native executable.

Syntax:

neurc compile <file.nr> [options]

Options:

• -o, --output <FILE> - Specify output executable path (default: the input filename without its extension)
• -O, --optimization <0-3> - Optimization level (default: 0); see Optimization

Examples:

# Default output (hello.exe on Windows)
neurc compile examples/basics/hello.nr

# Custom output path
neurc compile examples/basics/hello.nr -o bin/my_program

# Custom output with .exe extension
neurc compile examples/basics/hello.nr -o bin/my_program.exe

# Compile from different directory
neurc compile ../path/to/program.nr

# With debug logging
RUST_LOG=debug neurc compile examples/basics/hello.nr

Output:

• Success: Successfully compiled <input.nr> -> <output_path>
• Failure: the failing stage's errors, then Compilation failed: <reason> plus a numbered Caused by (n): chain

Exit codes:

• 0: Compilation successful
• 1: Compilation failed

Environment Variables

RUST_LOG

Control logging verbosity:

# Windows (PowerShell)
$env:RUST_LOG="debug"
neurc compile program.nr

# Unix
RUST_LOG=debug neurc compile program.nr

Levels:

• error - Only errors
• warn - Warnings and errors
• info - Informational messages
• debug - Detailed compilation steps (recommended for troubleshooting)
• trace - Very verbose output

Examples:

RUST_LOG=error neurc compile program.nr   # Minimal output
RUST_LOG=info neurc compile program.nr    # Standard output
RUST_LOG=debug neurc compile program.nr   # Detailed diagnostics

LLVM_SYS_201_PREFIX

Path to the LLVM 20 installation (required to build the compiler):

# Arch / CachyOS
export LLVM_SYS_201_PREFIX=/usr/lib/llvm20

# Ubuntu / Debian
export LLVM_SYS_201_PREFIX=/usr/lib/llvm-20

# macOS (Homebrew)
export LLVM_SYS_201_PREFIX=$(brew --prefix llvm@20)

See the Installation Guide for full setup.

Workflow Examples

Basic Development

# 1. Write code in editor
vim program.nr

# 2. Check for errors (fast)
neurc check program.nr

# 3. Fix errors, re-check
neurc check program.nr

# 4. Compile when ready
neurc compile program.nr

# 5. Run executable
./program  # Unix
.\program.exe  # Windows

Rapid Iteration

# Check-compile-run loop (Unix)
neurc check program.nr && neurc compile program.nr && ./program

# Windows (PowerShell)
neurc check program.nr; if ($?) { neurc compile program.nr; if ($?) { .\program.exe } }

Debugging Compilation Issues

# Enable debug logging
RUST_LOG=debug neurc compile program.nr 2> debug.log

# Review debug.log for detailed diagnostics
cat debug.log

Output Files

Executable

Default executable naming:

• Windows: <input>.exe (e.g., program.nr → program.exe)
• Unix: <input> without extension (e.g., program.nr → program)

Custom output with -o:

neurc compile program.nr -o custom_name
neurc compile program.nr -o bin/release/app

Temporary Files

A temporary object file is written during compilation and deleted after linking:

• Location: system temp directory
• Format: .o on Unix, .obj on Windows
• Cleanup: removed once the linker finishes

Error Handling

Errors go to stderr with exit code 1. compile wraps the failing stage's message in a Compilation failed: line followed by a numbered Caused by (n): chain.

Parse Errors

Example:

Information provided:

• The module that failed to parse
• The offending token and what the parser expected

Type Errors

Example:

Information provided:

• A numbered list of every type error (the type checker keeps going after the first)
• Each error's kind, its byte range in the source (Span), and the expected/found types

Code Generation and Link Errors

Codegen failures print as Compilation failed: Code generation error: ...; link failures name the linker invocation, for example:

Common causes:

• Missing C toolchain (MSVC or clang on Windows, gcc/clang on Unix)
• Missing system libraries

Performance

Compilation Times

Rough figures for a release-build compiler on a modern desktop; a debug build of neurc itself is slower:

Optimization

neurc compile supports optimization levels -O0 through -O3.

• -O0: Fastest compile time, minimal optimization
• -O1: Basic optimization
• -O2: Balanced optimization (recommended default for release-like builds)
• -O3: Maximum optimization

Platform-Specific Notes

Windows

Requirements:

• MSVC Build Tools 2022 OR MinGW-w64
• LLVM 20 (full development package)
• vcpkg with libxml2

Executable extension: Always .exe

Path separators: Use backslashes or forward slashes

1# Both work2neurc compile examples\hello.nr3neurc compile examples/basics/hello.nr

Linux

Requirements:

• GCC or Clang
• LLVM 20
• Build essentials (make, cmake, etc.)

Executable extension: None (no extension)

Permissions: Make executable:

chmod +x ./program
./program

macOS

Requirements:

• Xcode Command Line Tools
• LLVM 20 (via Homebrew, llvm@20)

Apple Silicon: Fully supported

Executable extension: None

Advanced Usage

Custom Toolchain

Override default linker:

# Use specific linker (not yet configurable)
# Future feature

Cross-Compilation

Not yet supported. Compiles for the native target only.

Build Scripts

Integrate into build scripts:

#!/bin/bash
set -e

echo "Checking Neuro programs..."
neurc check src/main.nr
neurc check src/utils.nr

echo "Compiling..."
neurc compile src/main.nr -o bin/app

echo "Build complete!"

CI/CD Integration

1# Example GitHub Actions workflow2- name: Install LLVM3  run: |4    wget https://apt.llvm.org/llvm.sh5    chmod +x llvm.sh6    sudo ./llvm.sh 207 8- name: Build Neuro compiler9  run: cargo build --release -p neurc10 11- name: Compile program12  run: cargo run --release -p neurc -- compile program.nr13 14- name: Run tests15  run: ./program

Troubleshooting

See Troubleshooting Guide for common issues and solutions.

Future Features

Planned CLI Enhancements

• Debug information: -g flag
• Position-independent code: -fPIC
• Verbose output: -v flag
• Quiet mode: -q flag
• Color output control: --color option

Planned

• Incremental compilation
• Build caching
• Cross-compilation targets

References

• Quick Start Guide
• Troubleshooting Guide
• Language Reference