hydra-language/hydra

Purpose and Workspace

Hydra is a Rust workspace implementing a statically typed, data-oriented systems language and its hydrac compiler. It compiles Hydra source through an LLVM-based backend and can build multi-file programs such as the raytracer example. Workspace structure is rooted at Cargo.toml; language syntax is defined in grammar.md.

Compiler Entry and Source Environment

The command-line compiler starts in cli/src/main.rs. It owns compilation invocation and source/sysroot discovery, with cli/src/sysroot.rs locating bundled language libraries. The compiler consumes user .hydra modules plus standard-library source under stdlib/core/primitives.hydra, stdlib/core/intrinsics.hydra, and allocation APIs in stdlib/alloc/boxed.hydra.

Front End: Lexing, Parsing, Modules

Lexical input becomes tokens in crates/lexer/src/lexer.rs and crates/lexer/src/token.rs. The parser converts tokens into the AST in crates/parser/src/parser.rs and crates/parser/src/ast.rs; module loading/import structure is handled by crates/parser/src/module.rs. This is the boundary from source text to compiler-owned syntax structures.

Semantic Analysis and Typed IR

crates/analyzer/src/analyzer.rs coordinates name resolution, scopes, typing, expression/statement analysis, and generic specialization. Core stages include crates/analyzer/src/resolve.rs, crates/analyzer/src/types.rs, and crates/analyzer/src/monomorphizer.rs. Analysis lowers or populates the shared IR model in crates/ir/src/hir.rs, with expressions, statements, types, and compiler context represented in crates/ir/src/expr.rs, crates/ir/src/stmt.rs, and crates/ir/src/context.rs.

Safety and Mid-Level Processing

Borrow validation is a dedicated phase in crates/borrowcheck/src/borrowcheck.rs, operating after semantic structure is available and before final emission. A separate MIR layer provides construction and optimization: crates/mir/src/builder.rs and crates/mir/src/optimizer.rs. These layers form the main correctness/optimization boundary between typed language semantics and backend-oriented code generation.

LLVM Code Generation

The backend is implemented by crates/codegen/src/lib.rs, translating IR/MIR concepts to LLVM. It has specialized lowering for functions, expressions, statements, types, and compiler intrinsics/builtins in crates/codegen/src/functions.rs, crates/codegen/src/expressions.rs, and crates/codegen/src/builtins.rs. LLVM and Clang are material external dependencies: LLVM 14 is explicitly required on Windows, while Clang is required on Linux for the native toolchain.

Runtime and Native Startup

Generated programs link against a Rust runtime in runtime/src/lib.rs, including allocator support in runtime/src/alloc.rs. Architecture-specific startup assembly establishes the process entry boundary at runtime/arch/x86_64/start.s and runtime/arch/aarch_64/start.s. This separates language-level code generation from platform ABI/process initialization.

Diagnostics and Representative Programs

Cross-cutting compiler diagnostics are centralized in crates/errors/src/error.rs. examples/hello/hello.hydra is a minimal compile target; examples/raytracing/main.hydra and its companion modules demonstrate supported structs, methods, pointers/references, casts, and complex control flow. Linux is the reliable target for the raytracer; the README notes a Windows stack bug.