Arden Overview

Why This Matters

This page is the fastest map of what Arden already ships today, how to approach learning it, and where to dive deeper without guessing.

Arden is a native systems language with three core priorities:

fast compile-time feedback
strong static guarantees
one integrated CLI workflow

What You Get Today

Arden is not just a parser demo. The repository already includes:

language core: types, functions, control flow, modules, classes, enums, interfaces, generics
generic support: functions/classes/interfaces + built-in generic types (Option, Result, ...) (user-defined generic enums are not supported yet)
object model extras: visibility (public/private/protected), inheritance (extends), destructors
safety model: ownership, borrowing, checked mutation, lifetime validation
effect model: @Pure, @Io, @Thread, @Any (+ @Net/@Alloc/@Unsafe support)
async model: Task<T>, async, await, task status/cancel/timeout APIs
FFI surfaces: extern, ABI options (c/system), bindgen workflow, Ptr<T> type support
stdlib namespace note: std.net import path exists, runtime Net.* API surface is currently placeholder-only
project mode: arden.toml, explicit file graph, cache-aware build/check/run/test
integrated tooling: formatter, linter/fixer, test runner, benchmark/profile, bindgen, LSP

Recommended Learning Path

Quick Start
Syntax, Variables, Types
Functions, Classes, Enums, Interfaces, Modules, Packages/Imports, Attributes, Language Edges
Ownership, Error Handling, Async, Effects
Extern and FFI, Projects, CLI, Architecture

Newcomer Cheat Sheet

If you are reading Arden for the first time, these symbols cover most confusion:

mut x -> binding can be reassigned
x (without mut) -> immutable binding
&x -> read-only borrow
&mut x -> exclusive mutable borrow
import std.<module>.*; -> required for Math.*, Str.*, Time.*, System.*, Args.*, File.*
Option<T> vs Result<T, E> -> missing value vs recoverable failure with reason
Task<T> -> async value you must await (or handle with timeout/status APIs)

60-Second Sanity Loop

arden check examples/single_file/basics/01_hello/01_hello.arden
arden run examples/single_file/basics/01_hello/01_hello.arden
arden test --path examples/single_file/tooling_and_ffi/24_test_attributes/24_test_attributes.arden

Learn With Runnable Examples

basics: 01_hello
ownership: 10_ownership
async boundary rules: 41_async_boundary_rules
async: 14_async
effects: 26_effect_system
extern/ffi: 27_extern_c_interop
borrow-mut behavior matrix: 43_borrow_mut_semantics
exact imports: 44_exact_import_values
visibility/contracts: 35_visibility_enforcement, 37_interfaces_contracts
interface inline-body rule: 45_interface_inline_body_rules
full example index: examples/README

Mental Model

Arden code is explicit by design:

explicit types at boundaries
explicit ownership, mutability, and effect rules
explicit project file graph

That makes behavior easier to reason about in large codebases and CI.

Performance and Tuning Notes

Day-to-day commands:

arden check --timings
arden build --timings

Advanced large-project tuning exists through environment variables (ARDEN_OBJECT_SHARD_THRESHOLD, ARDEN_OBJECT_SHARD_SIZE) for object-codegen sharding and ARDEN_CODEGEN_NATIVE_CPU=1 for host-native local codegen tuning. Keep these for profiling/CI experiments, not normal beginner workflow.

Where To Go Next

new user: Quick Start
language feature lookup: basics/ + features/
safety/runtime behavior: advanced/ + stdlib/
command usage: CLI Reference
compiler internals: Architecture

Generics, interfaces, enums, ownership, async, and project mode

Installation, quick start, projects, testing, and CLI reference