pyc99 0.1.1
Educational C99 compiler written in Python - compiles C to x86/ARM assembly
License: MIT
Requires Python: >=3.11
Keywords: compiler, c99, education, assembly, x86, arm, code-generation, parser, lexer

# C99 Compiler

[![PyPI version](https://badge.fury.io/py/pyc99.svg)](https://badge.fury.io/py/pyc99)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/scobi84/pyc99/workflows/Tests/badge.svg)](https://github.com/scobi84/pyc99/actions)

An educational C99 compiler written in Python, demonstrating compiler construction principles and C language implementation.

## Features

- **Full C99 Support**: Implements most C99 language features including:
  - All primitive types (int, char, float, double, void)
  - Pointers, arrays, and multi-dimensional arrays
  - Structs, unions, and enums
  - Function pointers and variadic functions
  - Type qualifiers (const, volatile, restrict)
  - Storage classes (static, extern, auto, register)
  - Preprocessor directives (#define, #include, #ifdef, etc.)

- **Multiple Target Architectures**:
  - x86-64 (Intel and AT&T syntax)
  - ARM (32-bit and 64-bit)

- **Comprehensive Testing**: 1100+ test cases covering:
  - C99 conformance tests
  - Real-world program compilation
  - Integration tests
  - Unit tests for all compiler phases

## Project Structure

```
.
├── src/
│   ├── lexer/          # Tokenization and lexical analysis
│   ├── parser/         # Syntax analysis and AST construction
│   ├── preprocessor/   # C preprocessor implementation
│   ├── semantic/       # Semantic analysis and type checking
│   ├── ir/             # Intermediate representation
│   ├── codegen/        # Code generation for target architectures
│   │   ├── x86/        # x86-64 code generator
│   │   └── arm/        # ARM code generator
│   └── utils/          # Utility functions and error reporting
├── tests/
│   ├── conformance/    # C99 conformance tests
│   ├── integration/    # End-to-end integration tests
│   └── unit/           # Unit tests for individual components
└── examples/           # Example C programs
```

## Installation

### From PyPI (Recommended)

```bash
pip install pyc99
```

### From Source

```bash
# Clone the repository
git clone https://github.com/scobi84/pyc99.git
cd pyc99

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"
```

### Requirements

- Python 3.11 or higher
- click library (installed automatically)

## Usage

### Compiling a C Program

```bash
# Compile to x86-64 assembly
pyc99 input.c -S -o output.s

# Compile for ARM
pyc99 input.c -S -t arm -o output.s

# Compile to object file
pyc99 input.c -c -o output.o

# Compile and link to executable (requires system assembler/linker)
pyc99 input.c -o program

# Compile multiple files
pyc99 main.c utils.c helpers.c -o program

# With optimization
pyc99 input.c -O1 -o program

# Verbose output
pyc99 input.c -v -o program
```

### Command Line Options

```
Usage: pyc99 [OPTIONS] SOURCE_FILES...

Options:
  -t, --target [x86|arm]          Target architecture (default: x86)
  -o, --output PATH               Output file name
  -O, --optimization [0|1]        Optimization level (default: 0)
  -S, --assembly-only             Generate assembly only
  -c, --compile-only              Generate object file only
  -I, --include PATH              Add include search path
  -v, --verbose                   Verbose output
  -d, --debug                     Debug output
  --stop-after [preprocess|lex|parse|semantic|ir|optimize|codegen]
                                  Stop after specified phase
  --help                          Show this message and exit
```

### Running Tests

```bash
# Run all tests
python3 -m pytest tests/

# Run specific test categories
python3 -m pytest tests/conformance/     # C99 conformance tests
python3 -m pytest tests/integration/     # Integration tests
python3 -m pytest tests/unit/            # Unit tests

# Run with verbose output
python3 -m pytest tests/ -v

# Run specific test file
python3 -m pytest tests/conformance/test_c99_expressions.py
```

## Examples

See the `examples/` directory for sample C programs:

- `hello_world.c` - Basic hello world
- `fibonacci.c` - Recursive Fibonacci
- `struct_example.c` - Struct usage
- `pointer_example.c` - Pointer manipulation
- And many more...

## C99 Compliance

The compiler implements approximately 95% of the C99 standard. See `C99_COMPLIANCE_ROADMAP.md` for detailed feature coverage.

### Implemented Features

✅ All basic types and type qualifiers
✅ Pointers, arrays, and pointer arithmetic
✅ Structs, unions, and enums
✅ Function declarations and definitions
✅ Control flow (if, while, for, switch, etc.)
✅ Operators and expressions
✅ Preprocessor directives
✅ Type casting and conversions
✅ Function pointers
✅ Variadic functions
✅ Inline functions
✅ Compound literals
✅ Designated initializers

### Known Limitations

- Variable-length arrays (VLA) - partial support
- Some complex declarator combinations
- _Complex and _Imaginary types not implemented
- Some edge cases in type compatibility

## Architecture

The compiler follows a traditional multi-pass architecture:

1. **Preprocessing**: Handles #include, #define, conditional compilation
2. **Lexical Analysis**: Tokenizes source code
3. **Parsing**: Builds Abstract Syntax Tree (AST)
4. **Semantic Analysis**: Type checking, symbol resolution
5. **IR Generation**: Converts AST to intermediate representation
6. **Code Generation**: Emits target assembly code

## Development

### Running Individual Compiler Phases

```python
from src.lexer.tokenizer import Tokenizer
from src.parser.parser import Parser
from src.semantic.analyzer import SemanticAnalyzer

# Tokenize
tokenizer = Tokenizer(source_code, "file.c")

# Parse
parser = Parser(tokenizer)
ast = parser.parse_translation_unit()

# Semantic analysis
from src.utils.error_reporter import ErrorReporter
error_reporter = ErrorReporter()
analyzer = SemanticAnalyzer(ast, error_reporter)
analyzer.analyze()
```

## Contributing

This is an educational project demonstrating compiler construction. Feel free to:
- Report bugs or issues
- Suggest improvements
- Add more test cases
- Improve documentation

## License

Educational/Academic use

## Acknowledgments

Built as an educational project to demonstrate:
- Compiler design and implementation
- C language semantics
- Code generation techniques
- Software testing practices