# project-nirmala/nircc architecture

> Architecture diagram of the GitHub repository project-nirmala/nircc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/project-nirmala/nircc
- Repository: https://github.com/project-nirmala/nircc

## Overview

Nirmala is a C compiler with a `cc`-style driver. The main workflow accepts C source, preprocesses and lexes it, parses a translation unit, then emits target assembly; the driver can additionally assemble and link. The README also documents optimization and a bootstrap milestone. The excerpts establish the compiler’s main calls and the driver’s tool invocations, but do not show all internal wiring—especially the optimizer’s invocation—so that relationship is marked unverified.

Main entry points: [`src/main.c`](https://github.com/project-nirmala/nircc/blob/master/src/main.c) (nircc entry), [`driver/driver.c`](https://github.com/project-nirmala/nircc/blob/master/driver/driver.c) (cc driver), [`src/gen.c`](https://github.com/project-nirmala/nircc/blob/master/src/gen.c) (Code generator), [`src/pp.c`](https://github.com/project-nirmala/nircc/blob/master/src/pp.c) (Preprocessor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Compiler frontend"]
  node_preprocessor["Preprocessor<br/>[pp.c]"]
  node_lexer["Lexer<br/>[lex.c]"]
  node_parser["Parser<br/>[parse.c]"]
end

subgraph group_core["Compiler core"]
  node_nircc["nircc entry<br/>[main.c]"]
  node_generator["Code generator<br/>[gen.c]"]
  node_optimizer["Assembly optimizer<br/>[peep.c]"]
end

subgraph group_driver["Driver and tools"]
  node_cc_driver["cc driver<br/>[driver.c]"]
  node_assembler["Assembler"]
  node_linker["System linker"]
end

subgraph group_support["Compiler support"]
  node_types["Type system<br/>[type.c]"]
  node_target["Target config<br/>[target.c]"]
  node_runtime_support["Compiler utilities<br/>[util.c]"]
  node_headers["C headers"]
end

node_user(("C developer"))
node_source["C source"]
node_assembly["Assembly output"]
node_binary["Executable or object"]

node_user -->|"invokes"| node_cc_driver
node_user -->|"invokes"| node_nircc
node_cc_driver -->|"runs compiler"| node_nircc
node_nircc -->|"reads"| node_source
node_nircc -->|"sets target"| node_target
node_nircc -->|"initializes types"| node_types
node_nircc -->|"preprocesses"| node_preprocessor
node_nircc -->|"tokenizes"| node_lexer
node_nircc -->|"parses tokens"| node_parser
node_nircc -->|"generates assembly"| node_generator
node_generator -->|"emits"| node_assembly
node_generator -.->|"may optimize"| node_optimizer
node_cc_driver -->|"runs assembler"| node_assembler
node_cc_driver -->|"runs linker"| node_linker
node_cc_driver -->|"passes assembly"| node_assembly
node_assembler -->|"produces object"| node_binary
node_linker -->|"produces executable"| node_binary
node_preprocessor -->|"includes headers"| node_headers

click node_cc_driver "https://github.com/project-nirmala/nircc/blob/master/driver/driver.c"
click node_nircc "https://github.com/project-nirmala/nircc/blob/master/src/main.c"
click node_preprocessor "https://github.com/project-nirmala/nircc/blob/master/src/pp.c"
click node_lexer "https://github.com/project-nirmala/nircc/blob/master/src/lex.c"
click node_parser "https://github.com/project-nirmala/nircc/blob/master/src/parse.c"
click node_types "https://github.com/project-nirmala/nircc/blob/master/src/type.c"
click node_target "https://github.com/project-nirmala/nircc/blob/master/src/target.c"
click node_generator "https://github.com/project-nirmala/nircc/blob/master/src/gen.c"
click node_optimizer "https://github.com/project-nirmala/nircc/blob/master/src/peep.c"
click node_runtime_support "https://github.com/project-nirmala/nircc/blob/master/src/util.c"
click node_headers "https://github.com/project-nirmala/nircc/tree/master/include"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_preprocessor,node_lexer,node_parser toneBlue
class node_nircc,node_generator,node_optimizer toneAmber
class node_cc_driver,node_assembler,node_linker toneMint
class node_types,node_target,node_runtime_support,node_headers toneRose
class node_user,node_source,node_assembly,node_binary toneIndigo
```

## Components

### Compiler frontend

- [Preprocessor](https://github.com/project-nirmala/nircc/blob/master/src/pp.c): `src/pp.c`
- [Lexer](https://github.com/project-nirmala/nircc/blob/master/src/lex.c): `src/lex.c`
- [Parser](https://github.com/project-nirmala/nircc/blob/master/src/parse.c): `src/parse.c`

### Compiler core

- [nircc entry](https://github.com/project-nirmala/nircc/blob/master/src/main.c): `src/main.c`
- [Code generator](https://github.com/project-nirmala/nircc/blob/master/src/gen.c): `src/gen.c`
- [Assembly optimizer](https://github.com/project-nirmala/nircc/blob/master/src/peep.c): `src/peep.c`

### Driver and tools

- [cc driver](https://github.com/project-nirmala/nircc/blob/master/driver/driver.c): `driver/driver.c`
- **Assembler**
- **System linker**

### Compiler support

- [Type system](https://github.com/project-nirmala/nircc/blob/master/src/type.c): `src/type.c`
- [Target config](https://github.com/project-nirmala/nircc/blob/master/src/target.c): `src/target.c`
- [Compiler utilities](https://github.com/project-nirmala/nircc/blob/master/src/util.c): `src/util.c`
- [C headers](https://github.com/project-nirmala/nircc/tree/master/include): `include`

### Other components

- **C developer**
- **C source**
- **Assembly output**
- **Executable or object**

## Connections

- C developer → cc driver: invokes (evidence: `driver/driver.c`)
- C developer → nircc entry: invokes (evidence: `src/main.c`)
- cc driver → nircc entry: runs compiler (evidence: `driver/driver.c`)
- nircc entry → C source: reads (evidence: `src/main.c`)
- nircc entry → Target config: sets target (evidence: `src/main.c`)
- nircc entry → Type system: initializes types (evidence: `src/main.c`)
- nircc entry → Preprocessor: preprocesses (evidence: `src/main.c`)
- nircc entry → Lexer: tokenizes (evidence: `src/main.c`)
- nircc entry → Parser: parses tokens (evidence: `src/main.c`)
- nircc entry → Code generator: generates assembly (evidence: `src/main.c`)
- Code generator → Assembly output: emits (evidence: `src/gen.c`)
- Code generator → Assembly optimizer: may optimize
- cc driver → Assembler: runs assembler (evidence: `driver/driver.c`)
- cc driver → System linker: runs linker (evidence: `driver/driver.c`)
- cc driver → Assembly output: passes assembly (evidence: `driver/driver.c`)
- Assembler → Executable or object: produces object
- System linker → Executable or object: produces executable
- Preprocessor → C headers: includes headers (evidence: `src/pp.c`)
