mathic 0.2.0

A compiler with builtin support of symbolic operations, built with LLVM/MLIR
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

## Glossary

| Section | Description |
|---------|-------------|
| [Project Structure](#project-structure) | Tree view of the source code organization |
| [Pipeline](#pipeline) | Visual diagram of the compilation stages |
| [Symbolic Dialect](dialects/Symbolic.md) | The `symbolic` MLIR dialect: types, operations, and project structure |
| [Symbolic Passes](dialects/SymbolicPasses.md) | Lowering passes: `symbolic-extract-eval` and `symbolic-to-arith` |

## Project Structure

```
src/
├── bin/
│   └── euler.rs                   # Binary entry point
├── codegen/                       # MLIR code generation
│   ├── compiler_helper/
│   │   └── debugging.rs
│   ├── compiler_helper.rs
│   ├── dialect_integration.rs     # MLIR op builders for symbolic dialect
│   ├── function_ctx.rs            # Function context (locals, blocks)
│   ├── lvalue.rs                  # Statement compilation
│   └── rvalue.rs                  # Expression / symbolic compilation
├── codegen.rs                     # Module re-export
├── compiler.rs                    # Compiler driver
├── diagnostics/                   # Error types
│   ├── codegen.rs
│   ├── lowering.rs
│   └── parse.rs
├── diagnostics.rs                 # Module re-export
├── executor.rs                    # JIT execution
├── ffi/                           # C FFI to shared libraries
│   └── dialect_integration.rs
├── ffi.rs                         # LLVM FFI bindings
├── lib.rs                         # Crate root
├── lowering/                      # AST → MATHIR lowering
│   ├── ast_lowering/              # AST → MATHIR transformation
│   │   ├── control_flow.rs
│   │   ├── declaration.rs
│   │   ├── expression.rs
│   │   └── statement.rs
│   ├── ir/                        # MATHIR definitions
│   │   ├── adts.rs
│   │   ├── basic_block.rs
│   │   ├── function.rs
│   │   ├── instruction.rs
│   │   ├── ir_walk.rs
│   │   ├── symbols.rs
│   │   ├── types.rs
│   │   └── value.rs
│   ├── ast_lowering.rs
│   └── ir.rs
├── lowering.rs                    # Module re-export
├── parser/                        # Frontend: lexing and parsing
│   ├── ast/                       # AST nodes
│   │   ├── control_flow.rs
│   │   ├── declaration.rs
│   │   ├── expression.rs
│   │   └── statement.rs
│   ├── parsing/                   # Recursive descent parser
│   │   ├── control_flow.rs
│   │   ├── declaration.rs
│   │   ├── expression.rs
│   │   └── statement.rs
│   ├── ast.rs
│   ├── lexer.rs
│   ├── parsing.rs
│   └── token.rs
└── parser.rs                      # Module re-export
Dialects/                          # Custom MLIR dialect (C++)
└── Symbolic/                      # The `symbolic` dialect (see dialects/Symbolic.md)
tests/                             # Integration tests
```

## Pipeline

```mermaid
flowchart TD
    subgraph Frontend["📝 Frontend"]
        direction LR
        Source[Source Code .mth] --> Lexer --> Parser --> AST
    end

    subgraph Lowering["🔧 Lowering"]
        direction LR
        Lowerer --> MATHIR
    end

    subgraph Codegen["⚙️ Codegen"]
        direction LR
        MLIR[MLIR Codegen + Symbolic Dialect]
        MLIR --> MLIROut[MLIR]
    end

    subgraph Passes["⚡ Passes"]
        direction LR
        Canonicalizer --> ExtractEval[symbolic-extract-eval] --> ToArith[symbolic-to-arith] --> LLVM[Convert to LLVM IR] --> LLVMIR
    end

    subgraph Execution["🚀 Execution"]
        direction LR
        JIT[JIT Execution] --> Output
    end

    Frontend --> Lowering --> Codegen
    Codegen --> Passes
    Passes --> Execution
```

- **📝 Frontend**: Lexes and parses `.mth` source files into an AST.
- **🔧 Lowering**: Transforms the AST into MATHIR (Mathic IR).
- **⚙️ Codegen**: Lowers MATHIR to MLIR with the custom `symbolic` dialect.
- **⚡ Passes**: Canonicalization, symbolic lowering, and conversion to LLVM IR. See [Symbolic Passes](dialects/SymbolicPasses.md).
- **🚀 Execution**: JIT-compiles LLVM IR and runs the program.