README.md

Dana Compiler | ECE NTUA

A full compiler for the Dana programming language, implemented in C++17, Flex, Bison, and LLVM 14. It translates Dana programs into LLVM IR, optimizes them, and produces native executables linked with the runtime library libdanart.a.

---

Table of Contents

• Contributors
• Features
• Installation & Usage
  • Basic Example
  • Script Options
• Dana Runtime Library
• Components
• Testing
  • Extra Hard Programs
• Continuous Integration
• Requirements
  • Quick LLVM Installation (Debian/Ubuntu)

---

Contributors

• Nikolas Spyropoulos (AM: 03121202)
• Giannis Polychronopoulos (AM: 03121089)

Features

• Lexical Analysis – implemented with Flex, precise error reporting (line/column + caret).

• Parsing – LALR(1) grammar in Bison, constructs an AST.

• Semantic Analysis – scope resolution, type checking, control-flow validation.

• LLVM IR Code Generation – LLVM backend with support for:

  • Functions, recursion, closures (nested functions with captures)
  • Variables, arrays (1D and multi-dimensional)
  • Control flow: if, loop, break, continue, return
  • Procedure calls & function returns
  • String operations & runtime calls

• LLVM IR Optimizations – configurable optimization levels (-O0 to -O3).

• Outputs:

  • Intermediate machine code (.imm)
  • Assembly (.asm)
  • Native executables (linked with libdanart.a)

---

Installation & Usage

To install and build the compiler, follow these steps:

1. Clone the repository

git clone https://github.com/nspyrop03/DanaCompiler.git

2. Navigate to compiler directory and build:

cd compiler
make

3. Make the wrapper script executable

chmod +x ./danac.sh

The main frontend is danac. For convenience, we provide danac.sh, which automates IR generation, optimization, and linking.

Basic Example

cd compiler
./danac.sh ../testing/programs/hello.dana
./a.out

This compiles hello.dana into a.out and runs it. Intermediate files hello.imm and hello.asm are also produced in ../testing/programs/.

Script Options

Usage:
  ./danac.sh <input-file.dana> [-o output-file] [-O0|-O1|-O2|-O3]
  ./danac.sh -i [-O0|-O1|-O2|-O3]    # interactive stdin, print IR to stdout
  ./danac.sh -f [-O0|-O1|-O2|-O3]    # interactive stdin, print ASM to stdout
  ./danac.sh -h | --help             # show this help message

Options

Option	Description
-o <file>	Set output executable name (default: a.out).
-O0..-O3	Select optimization level (default: -O0).
-i	Interactive mode, output LLVM IR.
-f	Interactive mode, output assembly.
-h, --help	Show help message.

---

Dana Runtime Library

Dana built-ins (writeString, readInteger, etc.) are implemented in C (/compiler/dana_runtime.c).

We built the runtime with:

gcc -c dana_runtime.c -o dana_runtime.o
ar rcs libdanart.a dana_runtime.o

• gcc -c compiles to object file .o.
• ar rcs archives into static library .a.
• libdanart.a is linked into all Dana executables by clang.

---

Components

Each compiler stage lives in its own subdirectory with a dedicated README:

• Lexer
• Parser
• Semantic Analyzer
• LLVM IR Codegen

Additional documentation:

• LLVM IR Optimization – explains our optimization pipeline, levels, and LLVM passes used in the final compiler.
• Projects – analysis of large/complex Dana programs in testing/extra-hard/.

---

Testing

The repository includes a full Python test framework in testing/.

• Lexer tests → python3 testing/test_lexer.py
• Parser tests → python3 testing/test_parser.py
• Semantic tests → python3 testing/test_semantic.py
• LLVM tests → python3 testing/test_llvm.py

The end-to-end compiler test (python3 testing/test_compiler.py) does the following:

1. Builds the compiler.
2. Compiles all .dana programs in testing/programs/ with all optimization flags.
3. Executes each program 3 times and averages runtime.
4. Runs programs with matching .input files.
5. Compares outputs against .result files.
6. Produces a benchmark table for all optimization levels.

Extra Hard Programs

Complex stress-test programs live in testing/extra-hard/. These are analyzed in detail in PROJECTS.md.

---

Continuous Integration

GitHub Actions run tests on every push/PR:

• lexer.yml → runs lexer tests
• parser.yml → runs parser tests
• semantic.yml → runs semantic tests
• llvm.yml → builds LLVM backend and runs tests (LLVM 14)
• compiler.yml → builds full compiler and runs all tests

---

Requirements

• LLVM 14 (headers + llvm-config)
• Clang 14
• Flex & Bison
• g++ (C++17 or newer)
• Python 3.10+ (for testing)

Quick LLVM Installation (Debian/Ubuntu)

sudo apt update
sudo apt install llvm-14 llvm-14-dev flex bison g++ python3

This downloads and configures LLVM 14.