Metadata-Version: 2.4
Name: upeep80
Version: 0.1.1
Summary: Universal peephole and AST optimizer for 8080/Z80 compilers
Author: upeep80 project
License: GPLv2
Project-URL: Homepage, https://github.com/yourusername/upeep80
Project-URL: Repository, https://github.com/yourusername/upeep80
Project-URL: Documentation, https://github.com/yourusername/upeep80/tree/main/docs
Project-URL: Bug Tracker, https://github.com/yourusername/upeep80/issues
Keywords: compiler,optimization,z80,8080,peephole,ast,retro
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: ruff>=0.0.285; extra == "dev"

# upeep80 - Universal Peephole Optimizer for 8080/Z80

A language-agnostic optimization library for 8080 and Z80 compilers.

## Overview

upeep80 provides high-quality optimization passes for compilers targeting the Intel 8080 and Zilog Z80 processors. The library is designed to be reusable across different source languages.

## Features

### AST-Level Optimizations
- **Constant Folding**: Evaluate compile-time constant expressions
- **Constant Propagation**: Replace variables with their constant values
- **Algebraic Simplification**: x+0=x, x*1=x, x*0=0, etc.
- **Strength Reduction**: Replace expensive operations with cheaper equivalents
  - Multiply/divide by power-of-2 → shifts
  - Modulo by power-of-2 → bitwise AND
- **Dead Code Elimination**: Remove unreachable code
- **Common Subexpression Elimination (CSE)**: Eliminate redundant calculations
- **Copy Propagation**: Track variable aliases
- **Dead Store Elimination**: Remove unused assignments
- **Loop Optimizations**:
  - Loop-invariant code motion
  - Loop unrolling (configurable)
- **Boolean Simplification**: x=x→true, x<>x→false
- **Procedure Inlining**: Inline small procedures

### Peephole Optimizations
- **Pattern-based optimization** on Z80 assembly
- **Redundant load/store elimination**
- **Jump optimization** (including relative jumps for Z80)
- **Stack operation combining**
- **Register allocation cleanup**
- **8080 to Z80 mnemonic translation**

### Optimization Levels
- **Level 0**: No optimization
- **Level 1**: Basic (constant folding, algebraic simplification)
- **Level 2**: Standard (+ strength reduction, dead code elimination)
- **Level 3**: Aggressive (+ CSE, loop optimizations, inlining)

### Optimization Targets
- **Speed**: Optimize for execution speed
- **Size**: Optimize for code size
- **Balanced**: Balance between speed and size

## Installation

```bash
pip install upeep80
```

Or for development:

```bash
git clone https://github.com/yourusername/upeep80.git
cd upeep80
pip install -e ".[dev]"
```

## Usage

### AST Optimization

```python
from upeep80 import ASTOptimizer, OptimizeFor

# Create optimizer
optimizer = ASTOptimizer(
    opt_level=2,
    optimize_for=OptimizeFor.BALANCED
)

# Optimize your AST
optimized_ast = optimizer.optimize(ast_tree)

# Check statistics
print(f"Constants folded: {optimizer.stats.constants_folded}")
print(f"Dead code eliminated: {optimizer.stats.dead_code_eliminated}")
```

### Peephole Optimization

```python
from upeep80 import PeepholeOptimizer, Target

# Create optimizer
optimizer = PeepholeOptimizer(
    target=Target.Z80,
    opt_level=2
)

# Optimize assembly code
optimized_asm = optimizer.optimize(assembly_lines)

# Check statistics
print(f"Patterns applied: {optimizer.stats.patterns_applied}")
print(f"Instructions eliminated: {optimizer.stats.instructions_eliminated}")
```

## Architecture

upeep80 is designed to be language-agnostic:

### AST Optimizer
- Works on generic expression trees
- Requires minimal AST node interface:
  - Binary/unary expressions
  - Literals (integer, real)
  - Identifiers
  - Statements (assignment, if, loop, etc.)
- Can be adapted to any language's AST

### Peephole Optimizer
- Works directly on assembly text
- No knowledge of source language required
- Pattern-based transformation engine
- Configurable for 8080 or Z80 targets

## Used By

- **[uplm80](https://github.com/yourusername/uplm80)** - PL/M-80 compiler for Z80
- **[uada80](https://github.com/yourusername/uada80)** - Ada compiler for Z80

## Examples

See the [examples/](examples/) directory for complete examples:

- `optimize_ast.py` - AST optimization example
- `optimize_asm.py` - Assembly peephole optimization example
- `custom_patterns.py` - Custom peephole pattern definition

## Documentation

Full documentation is available at [docs/](docs/):

- [API Reference](docs/API.md)
- [Optimization Guide](docs/OPTIMIZATION_GUIDE.md)
- [Custom Patterns](docs/CUSTOM_PATTERNS.md)
- [Integration Guide](docs/INTEGRATION.md)

## Development

### Running Tests

```bash
pytest
```

### Type Checking

```bash
mypy upeep80
```

### Code Formatting

```bash
black upeep80
ruff check upeep80
```

## Performance

Benchmarks on typical compiler workloads:

- AST optimization: ~10,000 nodes/second
- Peephole optimization: ~50,000 instructions/second
- Memory usage: ~100MB for typical compilation unit

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the GNU General Public License v2.0 - see [LICENSE](LICENSE) for details.

## History

upeep80 was extracted from the [uplm80](https://github.com/yourusername/uplm80) project to provide a reusable optimization library for multiple retro compiler projects targeting the 8080/Z80 architecture.

## Acknowledgments

- Optimization techniques based on classic compiler optimization literature
- Pattern-based peephole optimization inspired by Davidson & Fraser's work
- Z80 instruction set reference from [z80.info](http://z80.info)

## See Also

- [uplm80](https://github.com/yourusername/uplm80) - PL/M-80 compiler
- [uada80](https://github.com/yourusername/uada80) - Ada compiler for Z80
- [Z80 CPU User Manual](http://www.z80.info/zip/z80cpu_um.pdf)
