Skip to content

Getting Started

This guide walks you through installing Arx and compiling your first program.

Prerequisites

Installation

  1. Clone the repository:
git clone https://github.com/arxlang/arx.git
cd arx
  1. Create the conda environment and install dependencies:
mamba env create --file conda/dev.yaml
conda activate arx
poetry install
  1. Verify the installation:
arx --version

Your First Program

Create a file called hello.x:

```
title: Hello example
summary: Minimal Arx program that adds two values.
```
fn sum(a, b):
  ```
  title: sum
  summary: Returns the sum of a and b.
  ```
  return a + b

View the tokens

arx --show-tokens hello.x

View the AST

arx --show-ast hello.x

View the LLVM IR

arx --show-llvm-ir hello.x

Compile to an object file

arx hello.x --output-file hello

Examples

The examples/ directory contains several sample programs:

Sum

```
title: Sum example
summary: Demonstrates a basic addition function.
```
fn sum(a, b):
  ```
  title: sum
  summary: Returns the sum of two values.
  ```
  return a + b;

Average

```
title: Average example
summary: Demonstrates a basic arithmetic average function.
```
fn average(x, y):
  ```
  title: average
  summary: Returns the arithmetic mean of x and y.
  ```
  return (x + y) * 0.5;

Fibonacci

```
title: Fibonacci example
summary: Computes Fibonacci numbers recursively.
```
fn fib(x):
  ```
  title: fib
  summary: Returns the Fibonacci number for the input index.
  ```
  if x < 3:
    return 1
  else:
    return fib(x-1)+fib(x-2)

Constant

```
title: Constant example
summary: Demonstrates a function that returns its argument unchanged.
```
fn get_constant(x):
  ```
  title: get_constant
  summary: Returns the provided value.
  ```
  return x;

```
title: Print star example
summary: Emits star characters using an external output function.
```
fn print_star(n):
  ```
  title: print_star
  summary: Prints stars in a loop by calling putchard.
  ```
  for i in (1:n:1):
    putchard(42);  # ascii 42 = '*'

You can compile any example with:

arx examples/sum.x --show-llvm-ir

CLI Reference

arx [input_files] [options]
Option Description
--version Show the installed version
--output-file Specify the output file path
--lib Build source code as a library
--show-ast Print the AST for the input source code
--show-tokens Print the tokens for the input source
--show-llvm-ir Print the LLVM IR for the input source
--shell Open Arx in a shell prompt (not yet implemented)

Language Basics

Arx's syntax is influenced by Python with significant whitespace (indentation).

Functions

Functions are defined with the fn keyword and use : plus indentation for the body:

```
title: Function definition example
summary: Shows a basic function declaration.
```
fn add(x, y):
  ```
  title: add
  summary: Returns x plus y.
  ```
  return x + y

Control Flow

If/else:

```
title: If/else example
summary: Shows conditional branching in a function.
```
fn abs(x):
  ```
  title: abs
  summary: Returns the absolute value of x.
  ```
  if x < 0:
    return 0 - x
  else:
    return x

For loop:

```
title: For loop example
summary: Shows loop syntax with a slice-like range clause.
```
fn count(n):
  ```
  title: count
  summary: Iterates and prints star characters.
  ```
  for i in (1:n:1):
    putchard(42)

The range header uses (start:end:step) and is intentionally slice-like.

Variables

Variables are declared with var:

```
title: Variable example
summary: Shows var binding inside a function.
```
fn example():
  ```
  title: example
  summary: Binds a variable and computes a result.
  ```
  var a = 10 in
    a + 1

Extern Functions

External functions (e.g., from C) are declared with extern:

```
title: Extern declaration example
summary: Declares an external function symbol.
```
extern putchard(x)

Next Steps