Development Setup

This guide helps you set up a development environment for contributing to Calor.

Prerequisites

Requirement	Version	Purpose
.NET SDK	8.0+	Build and run
Git	Any recent	Version control
Editor	VS Code, Rider, VS	Code editing

Clone and Build

Bash

# Clone your fork (or the main repo)
git clone https://github.com/YOUR_USERNAME/calor.git
cd calor

# Build everything
dotnet build

# Run tests
dotnet test

Project Structure

Plain Text

calor/
├── src/
│   └── Calor.Compiler/           # The compiler
│       ├── Lexer/               # Tokenization
│       ├── Parser/              # Parsing
│       ├── AST/                 # Abstract syntax tree
│       └── CodeGen/             # C# generation
│
├── samples/
│   └── HelloWorld/              # Sample program
│
├── tests/
│   ├── E2E/                     # End-to-end tests
│   │   ├── scenarios/           # Test programs
│   │   ├── run-tests.sh         # Mac/Linux runner
│   │   └── run-tests.ps1        # Windows runner
│   │
│   └── Calor.Evaluation/         # Evaluation framework
│       ├── Metrics/             # Metric calculators
│       ├── Core/                # Framework core
│       └── Benchmarks/          # Benchmark programs
│
└── docs/                        # This documentation

Running the Compiler

Bash

# Compile an Calor file
dotnet run --project src/Calor.Compiler -- \
  --input path/to/file.calr \
  --output path/to/output.g.cs

# With verbose output
dotnet run --project src/Calor.Compiler -- \
  --input file.calr \
  --output file.g.cs \
  --verbose

Running Tests

E2E Tests

Bash

# Mac/Linux
./tests/E2E/run-tests.sh

# Windows
.\tests\E2E\run-tests.ps1

# Clean generated files
./tests/E2E/run-tests.sh --clean

Unit Tests

Bash

# Run all unit tests
dotnet test

# Run specific test project
dotnet test tests/Calor.Compiler.Tests

Evaluation Framework

Bash

# Run evaluation
dotnet run --project tests/Calor.Evaluation -- --output report.json

# Generate markdown report
dotnet run --project tests/Calor.Evaluation -- --output report.md --format markdown

Making Changes

1. Create a Branch

Bash

git checkout -b feature/your-feature-name

2. Make Your Changes

Edit the relevant files in your editor.

3. Build and Test

Bash

# Build
dotnet build

# Run tests
dotnet test

# Run E2E tests
./tests/E2E/run-tests.sh

4. Commit

Bash

git add -A
git commit -m "Description of your changes"

5. Push and PR

Bash

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Common Development Tasks

Adding a New Syntax Element

Update Lexer/ to recognize new tokens
Update Parser/ to parse new syntax
Update AST/ with new node types
Update CodeGen/ to emit C#
Add E2E test in tests/E2E/scenarios/

Adding a New Metric

Create calculator in tests/Calor.Evaluation/Metrics/
Implement IMetricCalculator interface
Register in evaluation runner
Add documentation

Adding a Benchmark

See Adding Benchmarks.

Debugging

VS Code

Add to .vscode/launch.json:

JSON

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Compiler",
      "type": "coreclr",
      "request": "launch",
      "program": "${workspaceFolder}/src/Calor.Compiler/bin/Debug/net10.0/Calor.Compiler.dll",
      "args": ["--input", "test.calr", "--output", "test.g.cs"],
      "cwd": "${workspaceFolder}",
      "console": "internalConsole"
    }
  ]
}

Rider/Visual Studio

Set Calor.Compiler as startup project with command line arguments:

Plain Text

--input samples/HelloWorld/hello.calr --output output.g.cs

Code Style

C# Conventions

Use file-scoped namespaces
Use expression-bodied members where appropriate
Use var for obvious types
Use meaningful names

Calor Conventions

Use Lisp-style expressions for operations
Include IDs on all structures
Declare effects explicitly
Add contracts where meaningful

Getting Help

Check existing issues on GitHub
Open a new issue for questions
Review the documentation

Adding Benchmarks - Add evaluation programs