🪷 Lotus

Development Guide

This guide covers setting up your development environment, building the Lotus compiler, running tests, and contributing to the project.

Prerequisites

• Go 1.20+ - Programming language for the compiler
• LLVM 14+ - Required for the LLVM backend (default)
• GCC or Clang - For the legacy assembly backend (--gcc flag)
• Git - Version control
• Make - Build automation (optional)

Install Dependencies

Linux (Arch):

pacman -S go llvm gcc git make

Linux (Ubuntu/Debian):

sudo apt-get install golang-go llvm-dev gcc git make

macOS:

brew install go llvm gcc git make

Windows (WSL2):

# Inside WSL2
sudo apt-get install golang-go llvm-dev gcc git make

Setting Up Development Environment

1. Clone Repository

git clone https://github.com/j-alexander3375/Lotus.git
cd Lotus

2. Install Go Dependencies

go mod tidy

3. Build Compiler

go build -o lotus ./src

4. Verify Installation

./lotus -v

Should output version information if successful.

Project Structure

Directory Layout

Lotus/
├── src/
│   ├── main.go          # Entry point and CLI
│   ├── tokenizer.go     # Tokenization
│   ├── parser.go        # Syntax parsing
│   ├── llvm_codegen.go  # LLVM IR generation (default)
│   ├── codegen.go       # Legacy x86-64 assembly generation
│   ├── optimizer.go     # Peephole optimizations
│   ├── stdlib.go        # Standard library
│   └── ... (other modules)
├── tests/               # Test files (.lts)
├── examples/            # Example programs
├── ext/                 # VS Code extension
└── site/                # Documentation website

Module Responsibilities

• main.go - CLI interface and program entry point
• tokenizer.go - Tokenizes source code into tokens
• parser.go - Parses tokens into AST
• llvm_codegen.go - Generates LLVM IR (default backend)
• codegen.go - Generates x86-64 assembly (--gcc flag)
• optimizer.go - Peephole optimizations for assembly
• stdlib.go - Standard library implementation

Building and Testing

Development Build

go build -o lotus ./src

Optimized Build

go build -ldflags="-s -w" -o lotus ./src

Testing

# Run all tests
go test ./src

# Run specific test
go test -run TestName ./src

# Verbose output
go test -v ./src

Running a Lotus Program

./lotus -S -o output.s program.lts  # Generate assembly
gcc -c output.s -o output.o                    # Assemble
gcc output.o -o program                        # Link
./program                                       # Run

Common Development Tasks

Adding a New Built-in Function

1. Declare function in stdlib.go
2. Implement code generation in appropriate module
3. Add test cases in *_test.go
4. Update documentation
5. Test thoroughly

Fixing a Bug

1. Create a test case that reproduces the bug
2. Verify test fails
3. Fix the bug
4. Verify test passes
5. Check for regressions

Implementing a Language Feature

1. Update lexer for new tokens (if needed)
2. Update parser to handle new syntax
3. Add type checking logic
4. Implement code generation
5. Write comprehensive tests
6. Update documentation

Debugging

Generated Assembly

View generated assembly code:

./lotus -S -o output.s program.lts
cat output.s

Using GDB

# Build with debug symbols
go build -gcflags="-N -l" -o lotus ./src

# Run with debugger
gdb ./lotus

Printf Debugging

Add fmt.Printf statements in Go code to trace execution:

fmt.Printf("Debug: value=%d\n", value)

Test Failures

Run specific test with verbose output:

go test -v -run TestName ./src

Code Review Checklist

Before Submitting PR

• ✅ Code follows style guide
• ✅ All tests pass
• ✅ No regressions introduced
• ✅ Documentation updated
• ✅ Commit messages are clear
• ✅ Changes are focused and minimal
• ✅ Code is properly commented

Contributing to Lotus

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a feature branch: git checkout -b feature/your-feature
4. Make your changes
5. Write or update tests
6. Update documentation
7. Commit with clear messages
8. Push to your fork
9. Create a Pull Request

Pull Request Guidelines

• Title: Clear, concise description of changes
• Description: Explain what and why (not just what)
• Tests: Include test cases for new functionality
• Documentation: Update relevant docs
• Linked Issues: Reference any related issues
• One concern per PR: Keep scope focused

Reporting Issues

When reporting a bug, include:

• Clear description of the issue
• Steps to reproduce
• Expected vs actual behavior
• Environment (OS, Go version, Lotus version)
• Minimal reproducible example

Standard Library Development

Adding a New Module

1. Define module structure in stdlib.go
2. Implement module functions
3. Add to module registry
4. Create comprehensive tests
5. Document module API

Module Categories

• io - Input/output and formatting
• mem - Memory management
• math - Mathematical operations
• str - String operations
• future - Time, file I/O, collections, etc.

Performance Optimization

Profiling

Profile compiler performance:

go test -cpuprofile=cpu.prof -memprofile=mem.prof ./src
go tool pprof cpu.prof

Benchmarking

Write benchmarks in test files:

func BenchmarkCompile(b *testing.B) {
    for i := 0; i < b.N; i++ {
        // Code to benchmark
    }
}

Common Optimization Areas

• Parser efficiency
• Type checking algorithms
• Code generation speed
• Memory allocations

Release Process

Version Numbering

Follow semantic versioning: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Release Steps

1. Update version in appropriate files
2. Update CHANGELOG
3. Create release notes
4. Tag release in Git
5. Build release binaries
6. Upload to GitHub Releases
7. Update package managers (AUR, etc.)

Resources

• GitHub Repository
• Go Documentation
• Go Blog
• x86-64 Architecture
• Issue Tracker

← Back to Documentation Get Help