Skip to content

Development Setup

This page covers how to set up a local development environment for Dapper. For contribution guidelines, see Contributing.

Prerequisites

  • Python 3.9+
  • uv package manager

Installation

  1. Clone the repository: bash git clone https://github.com/jnsquire/dapper.git cd dapper

  2. Install uv (if not already installed): ```bash # On macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows powershell -c "irm https://astral.sh/uv/install.sh | iex"

# Or using pip pip install uv ```

  1. Install dependencies using uv: bash uv sync

This will create a virtual environment and install all dependencies from pyproject.toml.

Development Workflow

Activate the Virtual Environment

uv automatically manages the virtual environment. You can verify the active Python:

uv run python --version

Running Tests

Using uv (recommended):

# Run all tests
uv run pytest

# Run a specific test file
uv run pytest tests/test_debugger_core.py

# Run with coverage
uv run pytest --cov=dapper

Linting, Formatting, and Type Checking

Run these checks before submitting changes:

# Lint
uv run ruff check .

# Format (and verify no further edits are needed)
uv run ruff format

# Type checking
uv run pyright dapper tests

Optional auto-fix for lint findings:

uv run ruff check . --fix

Building the Package

There are a couple of useful build-related commands:

# Build distribution packages (regular PEP 517 backend invocation)
uv build

# Build the Cython frame‑eval extension only
uv run build-dev

# Build and then install the project in editable mode
# with the ``dev`` and ``frame-eval`` extras:
uv run build-dev -- --install
# or equivalently
uv run install-dev

(If you just want a production build of the extension, uv run build-prod still works as before.)

When run with --install the helper will perform the same pip install -e .[dev,frame-eval] step that you used previously, saving you the extra manual command.

Project Structure

dapper/
├── dapper/          # Main package
│   ├── __init__.py
│   ├── debugger.py     # Core debugger implementation
│   ├── server.py       # DAP server
│   ├── protocol.py     # DAP protocol handling
│   └── ...
├── tests/              # Test suite
│   ├── test_debugger_*.py  # Split test files
│   └── ...
├── pyproject.toml      # Project configuration
├── uv.lock             # uv lock file
└── README.md

Project Policies

These are current, informal policies the team follows during development.

  • API stability: Don't worry about backward compatibility of internal interfaces when making changes — there are no outside users right now. This means it's acceptable to change function/method signatures, rename internal helpers, or move responsibilities between modules without maintaining deprecated shims. Still aim to keep changes well-documented in commit messages and update tests accordingly.

Troubleshooting

uv not found

If uv is not available, you can still work with the project using traditional Python tools:

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

# Install dependencies
pip install -e .
pip install pytest pytest-asyncio pytest-cov

Permission issues on Windows

If you encounter permission issues with uv on Windows, try running your terminal as Administrator or use:

uv run --python-preference system pytest

See Also