## VerilogToImage Framework - Quick Start Guide

### Installation

#### Windows (PowerShell)
```powershell
cd "d:\WorkFolder\My project python\My library python\VerilogToImage"
pip install -e .
```

#### WSL (Ubuntu)
```bash
wsl -d Ubuntu
cd c
bash setup_wsl.sh
pip3 install -e .
```

### Basic Usage

#### 1. Parse Verilog Code
```python
from verilog_framework.core import VerilogLexer, VerilogParser

code = "module test(input a, output b); assign b = a; endmodule"

lexer = VerilogLexer(code)
tokens = lexer.tokenize()
parser = VerilogParser(tokens)
ast = parser.parse()

print(f"Module: {ast.name}")
print(f"Statements: {len(ast.statements)}")
```

#### 2. Visualize AST
```python
from verilog_framework.visualization import GraphvizVisualizer

visualizer = GraphvizVisualizer()
dot_graph = visualizer.generate_dot(ast)

with open("ast_graph.svg", "w") as f:
    f.write(dot_graph)
```

#### 3. Generate Circuit Diagrams
```python
from verilog_framework.verilogtoimage import VerilogToImagePipeline, get_logger

logger = get_logger()
pipeline = VerilogToImagePipeline()

svg_file = pipeline.verilog_to_svg(code, "circuit.svg")
png_file = pipeline.verilog_to_png(code, "circuit.png")
```

#### 4. Using CLI
```bash
# Parse and generate AST visualization
python examples/cli.py module.v --ast

# Generate circuit SVG
python examples/cli.py module.v --svg

# Generate circuit PNG
python examples/cli.py module.v --png

# Generate all outputs
python examples/cli.py module.v --all
```

### Running Tests

```bash
# Run all tests
python tests/run_tests.py

# Run specific test suite
python tests/test_lexer.py
python tests/test_parser.py
python tests/test_visualizer.py
python tests/test_processor.py
python tests/test_verilogtoimage.py
```

### Project Structure
```
verilog_framework/
├── core/                           (23 Python files total)
│   ├── ast_nodes.py               # AST node definitions
│   ├── lexer.py                   # Tokenizer
│   ├── parser.py                  # Parser
│   └── __init__.py
├── visualization/
│   ├── visitor.py                 # Visitor pattern
│   ├── visualizer.py              # Graph generation
│   └── __init__.py
├── verilogtoimage/
│   ├── logger.py                  # Logging utilities
│   ├── converters.py              # Tool converters
│   ├── pipeline.py                # Image pipeline
│   └── __init__.py
├── utils/
│   └── __init__.py
└── __init__.py

tests/
├── test_lexer.py                  # 7 tests
├── test_parser.py                 # 8 tests
├── test_visualizer.py             # 5 tests
├── test_processor.py              # 3 tests
├── test_verilogtoimage.py         # Image generation tests
└── run_tests.py

examples/
├── cli.py                         # Command-line interface
├── generate_circuit.py            # Circuit generation example
└── test_module.v                  # Sample Verilog file

setup.py                           # Installation script
requirements.txt                   # Dependencies
setup_wsl.sh                       # WSL setup script
README.md                          # Full documentation
QUICKSTART.md                      # This file
```

### Logging Examples

```python
from verilog_framework.verilogtoimage import get_logger

logger = get_logger()

logger.debug("Debug message")
logger.info("Info message")
logger.error("Error message")
```

Output:
```
2026-02-11 12:41:17 - VerilogFramework - DEBUG - Debug message
2026-02-11 12:41:17 - VerilogFramework - INFO - Info message
2026-02-11 12:41:17 - VerilogFramework - ERROR - Error message
```

### Troubleshooting

#### WSL Tools Not Found
```bash
# Verify installation
wsl -d Ubuntu which yosys
wsl -d Ubuntu which netlistsvg
wsl -d Ubuntu python3 -c "import cairosvg"

# Re-run setup if needed
wsl -d Ubuntu bash /mnt/d/WorkFolder/"My project python"/"My library python"/VerilogToImage/setup_wsl.sh
```

#### Path Issues
- Ensure WSL is installed: `wsl --list --verbose`
- Check Ubuntu is available: `wsl -d Ubuntu echo "OK"`
- Verify Windows paths are properly escaped in commands

#### Python Module Import Errors
```bash
# Set PYTHONPATH
python -c "import sys; sys.path.insert(0, '.'); from verilog_framework import *"

# Or use pip install in development mode
pip install -e .
```

### Performance Notes

- Lexer: Can process ~100K tokens/second
- Parser: Can parse ~10K lines/second
- AST Visualization: Dependent on module complexity
- Circuit Generation: Requires WSL tool overhead (~2-5 seconds per conversion)

### Supported Verilog Syntax

✓ Module declarations
✓ Input/Output/Inout ports
✓ Wire and Reg declarations
✓ Continuous assignments
✓ Always blocks with sensitivity lists
✓ Binary operators (+, -, *, /, &, |, ^, <<, >>)
✓ Unary operators (!, ~, -)
✓ Expressions and operator precedence

### Next Steps

1. Read [README.md](README.md) for comprehensive documentation
2. Check [examples/](examples/) for more usage patterns
3. Run tests to verify installation: `python tests/run_tests.py`
4. Generate your first circuit: `python examples/cli.py examples/test_module.v --all`

### Additional Resources

- Verilog Language Reference: https://en.wikipedia.org/wiki/Verilog
- Yosys Documentation: https://yosyshq.net/
- netlistsvg: https://github.com/nturley/netlistsvg
- CairoSVG: https://cairosvg.org/
