Developer Guide

This guide covers the development workflow, project structure, and contribution guidelines for Axion-HDL.

Project Structure

axion-hdl/
├── axion_hdl/              # Main Python package
│   ├── __init__.py         # Package initialization, version
│   ├── axion.py            # Core AxionHDL class
│   ├── cli.py              # Command-line interface
│   ├── parser.py           # VHDL parser (@axion annotations)
│   ├── systemverilog_parser.py  # SystemVerilog parser (@axion annotations)
│   ├── systemverilog_utils.py   # SystemVerilog type/range utilities
│   ├── annotation_parser.py # Annotation parsing utilities
│   ├── yaml_input_parser.py # YAML register definition parser
│   ├── json_input_parser.py # JSON register definition parser
│   ├── xml_input_parser.py  # XML register definition parser
│   ├── toml_input_parser.py # TOML register definition parser
│   ├── address_manager.py  # Address conflict detection
│   ├── bit_field_manager.py # Bit field/subregister management
│   ├── code_formatter.py   # Code formatting utilities
│   ├── source_modifier.py  # Source file modification (GUI)
│   ├── vhdl_utils.py       # VHDL utility functions
│   ├── rule_checker.py     # Design rule validation
│   ├── generator.py        # VHDL generator (VHDLGenerator)
│   ├── doc_generators.py   # Output generators (Doc, CHeader, XML, YAML, JSON, TOML)
│   ├── gui.py              # Flask-based web GUI
│   ├── templates/          # HTML templates for GUI
│   ├── systemverilog_generator.py # SystemVerilog code generator
│   └── static/             # CSS, JS for GUI
├── tests/                  # Test suite
│   ├── python/             # Python unit tests
│   ├── vhdl/               # VHDL simulation tests
│   └── run_tests.py        # Test runner
├── docs/                   # Documentation (Sphinx)
│   ├── source/             # Markdown source files
│   ├── requirements/       # Requirements specifications
│   └── examples/           # Example input files
├── pyproject.toml          # Package configuration
├── Makefile                # Build and test automation
└── .version                # Version file

Development Setup

Prerequisites

Python 3.7+
pip
(Optional) GHDL for VHDL simulation tests
(Optional) Node.js for Playwright GUI tests

Installation

Clone the repository and install in development mode:

git clone https://github.com/bugratufan/axion-hdl.git
cd axion-hdl
pip install -e ".[dev]"

For GUI development:

pip install -e ".[dev,gui]"

For documentation:

pip install -e ".[docs]"

Running Tests

All Tests

make test

Python Unit Tests

make test-python

Runs pytest on tests/python/. Tests are organized by requirement category:

test_parser.py - PARSER-xxx requirements
test_generator.py - GEN-xxx requirements
test_cli.py - CLI-xxx requirements
test_addressing.py - ADDR-xxx requirements
etc.

VHDL Simulation Tests

make test-vhdl

Requires GHDL. Runs simulation tests in tests/vhdl/ to verify:

AXI4-Lite protocol compliance (AXION-xxx, AXI-LITE-xxx)
Register read/write behavior
CDC synchronization

GUI Tests (Playwright)

make test-gui

Requires Playwright. Install browsers first:

playwright install chromium

Tests GUI requirements (GUI-xxx) including:

Dashboard functionality
Editor interactions
Save/diff workflows

Branching Workflow

This project uses a develop → main branching strategy.

Feature Development

Start from develop:

git checkout develop
git pull origin develop

Create feature branch:

git checkout -b feature/your-feature-name

Make changes and commit:

git add .
git commit -m "feat: your commit message"

Push and create PR to develop:

git push -u origin feature/your-feature-name

Releases

PyPI publishes happen when develop is merged into main:

Ensure version is updated in:
- .version
- pyproject.toml
- setup.py
- axion_hdl/__init__.py
Create PR from develop to main
After merge, CI automatically:
- Runs tests
- Builds package
- Creates GitHub release
- Publishes to PyPI

Code Style

Python

Use Black for formatting
Line length: 100 characters
Run before committing:
```
black axion_hdl tests
```

Linting

flake8 axion_hdl tests

Adding New Features

1. Check Requirements

Review existing requirements in:

docs/source/requirements-core.md
docs/source/requirements-gui.md

Your feature may already be covered or need a new requirement.

2. Add Requirement

If new, add to appropriate requirements document:

| ID | Definition | Acceptance Criteria | Test Method |
|----|------------|---------------------|-------------|
| CAT-XXX | Feature description | How to verify | Test reference |

3. Write Tests First

Add tests in tests/python/ referencing the requirement:

def test_cat_xxx():
    """CAT-XXX: Feature description"""
    # Test implementation
    assert expected_behavior

4. Implement Feature

Write the implementation in the appropriate module.

5. Run Tests

make test

6. Update Documentation

If user-facing, update docs in docs/source/.

Building Documentation

Local Build

cd docs
make html

View at docs/build/html/index.html.

ReadTheDocs

Documentation is automatically built on ReadTheDocs when changes are pushed.

Useful Make Targets

Target	Description
`make test`	Run all tests
`make test-python`	Python unit tests only
`make test-vhdl`	VHDL simulation tests only
`make test-gui`	Playwright GUI tests only
`make lint`	Run flake8 linting
`make format`	Format code with black
`make build`	Build distribution package
`make clean`	Clean build artifacts
`make generate-docs`	Generate HTML documentation