Installation & Setup

Ferrite provides standalone precompiled binaries with no external runtime dependencies. Select your platform below for installation guidelines.

Windows

Download and run the custom setup wizard: ferrite-v2.3.1-setup.exe. The wizard will install the compiler and automatically configure your environment variables.

macOS

Install Ferrite using our official Homebrew tap:

# Add the tap and install
brew tap vishwanathdvgmm/tap
brew install ferrite
                            

Alternatively, download the `.tar.gz` archive for Apple Silicon (M1/M2/M3) or Intel architectures from our Releases page, extract it, and copy `ferrite` to `/usr/local/bin`.

Linux

Run the automated shell install script in your terminal:

curl -fsSL https://ferrite-lang.org/install.sh | sh
                            

Or download the precompiled binary from the Releases page, extract it, and add it to your path:

tar -xzf ferrite-v2.3.1-linux-x86_64.tar.gz
sudo mv ferrite /usr/local/bin/
                            

Build from Source

Ferrite can be compiled from source on any system running a modern Rust compiler toolchain:

# Clone the repository
git clone https://github.com/vishwanathdvgmm/ferrite.git
cd ferrite

# Build the release binary
cargo build --release

# Run a quick sanity check
./target/release/ferrite run tests/hello.fe
                            

Command Line Interface

The ferrite compiler binary includes utility subcommands for testing, executing, and type-checking scripts.

Command Syntax

# Syntax-check and type-check a program without running it
ferrite check my_code.fe

# Interpret a file instantly using the Tree-Walk engine
ferrite run my_code.fe

# Print help manuals and release versions
ferrite --help
ferrite --version
                            

Variables & Mutability

By default, variables declared in Ferrite are **immutable (read-only constants)** using the keep keyword. Mutable variables can be updated using normal reassignment syntax.

Declaration Examples

// Keep defines immutable constants
keep pi: float = 3.14159;
keep welcome: string = "Hello, System!";

// Mutable variables (assigned directly)
keep count: int = 10;
count = count + 1; // Works!

// Error: Cannot reassign an immutable keep once initialized
pi = 3.20; 
                            

Strict Type System

Ferrite implements absolute type safety. There is no concept of "truthiness" (e.g. if 1 is a compile error) and no silent numeric upgrades (e.g., passing an int into a function parameter expecting a float fails immediately).

Primitive Types

• int: 64-bit signed integer.
• float: 64-bit floating-point number.
• bool: Boolean values (true or false).
• string: UTF-8 character arrays.
• fun: First-class function handle signatures.
• Tensor: Multi-dimensional numeric arrays.

Casting Rules

keep x: int = 5;
keep y: float = 2.5;

// Fails: Types do not align (int + float)
keep z = x + y; 

// Success: Cast x explicitly to a float first
keep correct = float(x) + y;
                            

Loops & Control Flow

Ferrite supports conditional blocks and iteration loops with advanced jump controls like skip (continue) and stop (break).

Conditional branching

keep temperature: float = 38.5;

if temperature > 37.5 {
    println("Fever warning");
} else {
    println("Normal temperature");
}
                            

While Loops

keep i: int = 0;
while i < 10 {
    i = i + 1;
    if i == 3 { 
        skip; // Skip remaining block and continue loop
    }
    if i == 7 { 
        stop; // Break out of loop
    }
    println(str(i));
}
                            

Pattern Matching & Guards

Ferrite supports deep algebraic matching on Enum datatypes, featuring conditional guard clauses via the if keyword inside cases.

Match syntax

enum Result<T> {
    Ok(T);
    Err(string);
}

keep response = Ok(200);

match response {
    case Ok(status) if status == 200 => {
        println("Success code: " + str(status));
    }
    case Ok(status) => {
        println("Other OK status");
    }
    case Err(msg) => {
        println("Failure: " + msg);
    }
}
                            

Groups & Traits

Data containers are defined using group. Interfaces or shared protocols are declared using trait, which can be implemented explicitly on groups using the impl block.

Defining Structure and Interfaces

group Vector2 {
    x: float;
    y: float;
}

trait Display {
    fun format(self) -> string;
}

impl Display for Vector2 {
    fun format(self) -> string {
        return "Vector2(" + str(self.x) + ", " + str(self.y) + ")";
    }
}
                            

ML & Tensor Operations

Tensors are native primitives in Ferrite. Shapes are specified within the generic parameters and are enforced during type checking to prevent out-of-bounds layer math.

Compile-Time Shape Constraints

// Declare shapes (batch_size, inputs) and (inputs, outputs)
param batch: Tensor<float, (32, 128)> = rand();
param weights: Tensor<float, (128, 64)> = zeros();

// The @ symbol indicates matrix multiplication
keep activations = batch @ weights; // Compiles (result shape: 32, 64)

// Error: Shape mismatch at check-time! (128x64 cannot multiply 32x128)
keep invalid = weights @ batch;
                            

Execution Blocks (train / infer)

Isolate your operations inside context blocks which optimize execution parameters (e.g. tracking gradients, disabling backpropagation overheads):

train {
    // Gradients are calculated automatically
    keep loss = compute_gradients(batch);
}

infer {
    // Pure feed-forward path optimized for speed
    keep output = forward_pass(batch);
}
                            

Standard Library

Ferrite includes a curated set of native core libraries accessible via the `import` command.

Available modules

• "math": Trigonometric calculations, matrix algebra tools, distributions.
• "system": Direct environment querying, file reading/writing buffers.
• "tensors": High-level utility routines (reshaping, slicing, normalizations).