Contributing to the Styx Compiler

The Styx compiler is the core technology that transforms Boutiques descriptors into type-safe language bindings. This guide provides a basic overview of the compiler architecture and how to contribute to its development.

Repository Structure

The Styx compiler is organized into several key components:

styx/
├── src/
│   └── styx/
│       ├── frontend/       # Parses input formats into IR
│       │   └── boutiques/  # Boutiques-specific frontend
│       ├── ir/             # Intermediate Representation
│       └── backend/        # Code generation for target languages
│           ├── generic/    # Language-agnostic utilities
│           ├── python/     # Python-specific code generation
│           ├── typescript/ # TypeScript-specific code generation
│           └── r/          # R-specific code generation
├── tests/                  # Unit and integration tests
└── docs/                   # Documentation

Compiler Architecture

The Styx compiler follows a traditional compiler design with three main phases:

Frontend: Parses input formats (e.g., Boutiques descriptors) into an Intermediate Representation (IR)
IR: A language-agnostic representation of the tool interface
Backend: Generates code for target languages (Python, TypeScript, R) from the IR

Setting Up Your Development Environment

# Clone the repository
git clone https://github.com/styx-api/styx.git
cd styx

# Install development dependencies using uv
uv pip install -e .

# Run tests
python -m pytest tests/

Common Contribution Areas

Adding Features to Existing Language Backends

If you want to improve code generation for a specific language:

Locate the language provider in src/styx/backend/<language>/languageprovider.py
Make your changes to the code generation logic
Add tests in the tests/ directory
Run the test suite to ensure everything works as expected

Adding Support for a New Language

To add support for a new target language:

Create a new directory in src/styx/backend/ for your language
Implement a language provider that conforms to the interface in backend/generic/languageprovider.py
Add language-specific code generation logic
Add tests for your new language backend

Improving the IR

If you want to enhance the Intermediate Representation:

Make changes to the IR structure in src/styx/ir/core.py
Update the normalization and optimization passes if necessary
Ensure all language backends can handle your IR changes
Add tests for your IR modifications

Testing Your Changes

The Styx compiler has a comprehensive test suite:

# Run all tests
python -m pytest

# Run specific test files
python -m pytest tests/test_output_files.py

# Run with verbose output
python -m pytest -v

Documentation

Styx uses pdoc for API documentation:

# Install pdoc if needed
pip install pdoc

# Generate documentation
pdoc --html --output-dir docs/api src/styx

Getting Help

The Styx compiler is a complex piece of software. If you're having trouble:

Check existing issues on GitHub
Look at the test cases to understand how different components work
Reach out to the maintainers through GitHub issues

Next Steps

While contributing to the Styx compiler requires more technical expertise than contributing to NiWrap descriptors, it's a rewarding way to improve the entire ecosystem. Start with small changes and work your way up to more complex features.

For most users interested in neuroimaging tools, contributing to NiWrap might be a more accessible starting point.

Styx Book