MiniProfiler/docs/SETUP.md

MiniProfiler Setup Guide

This guide covers setting up the MiniProfiler host application using uv for fast package management and virtual environment handling.

Prerequisites

• Python 3.8 or higher
• uv - Fast Python package installer

Installing uv

If you don't have uv installed:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

# Or with pipx
pipx install uv

Quick Start with uv

1. Create and Activate Virtual Environment

# From the MiniProfiler root directory
cd host

# Create a virtual environment with uv
uv venv

# Activate the virtual environment
# On Linux/macOS:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

2. Install the Package

# Install in editable mode with all dependencies
uv pip install -e .

# Or install with development dependencies
uv pip install -e ".[dev]"

3. Run the Application

# Run directly
miniprofiler

# Or with Python
python run.py

# Or with custom options
miniprofiler --host 0.0.0.0 --port 8080 --verbose

Using the Makefile (Recommended)

The project includes a Makefile for common tasks:

# From the project root directory

# Show available commands
make help

# Install the package
make install

# Install with dev dependencies
make dev

# Run the web server
make run

# Generate sample data
make sample

# Run tests (after installing dev dependencies)
make test

# Format code
make format

# Lint code
make lint

# Clean build artifacts
make clean

Manual Setup (Without Makefile)

Step-by-Step

# 1. Navigate to host directory
cd host

# 2. Create virtual environment
uv venv

# 3. Activate virtual environment
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# 4. Install package
uv pip install -e .

# 5. Verify installation
miniprofiler --help

# 6. Run the server
miniprofiler

Development Setup

For development with testing and linting tools:

cd host

# Create venv and install with dev dependencies
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black miniprofiler tests

# Lint code
ruff check miniprofiler tests

Project Structure with uv

MiniProfiler/
├── host/
│   ├── .venv/              # Virtual environment (created by uv venv)
│   ├── miniprofiler/       # Source code
│   ├── tests/              # Tests
│   ├── web/                # Web assets
│   ├── pyproject.toml      # Project configuration (uv compatible)
│   ├── .python-version     # Python version for uv
│   └── run.py              # Quick start script
└── Makefile                # Build automation

Configuration Files

pyproject.toml

Modern Python project configuration file supporting:

• Project metadata
• Dependencies
• Build system configuration
• Tool configurations (black, ruff, pytest)
• Entry points for CLI commands

.python-version

Specifies the Python version for uv to use. Currently set to 3.11.

Virtual Environment Management

Create New Environment

cd host
uv venv

Activate Environment

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Deactivate Environment

deactivate

Delete Environment

# Linux/macOS
rm -rf .venv

# Windows
rmdir /s .venv

Dependency Management

Install New Package

# With uv (fast)
uv pip install package-name

# Add to pyproject.toml dependencies manually, then:
uv pip install -e .

Update Dependencies

# Upgrade all packages
uv pip install --upgrade -e .

# Upgrade specific package
uv pip install --upgrade package-name

List Installed Packages

uv pip list

Generate requirements.txt (if needed)

uv pip freeze > requirements.txt

Testing

Run All Tests

pytest

Run with Coverage

pytest --cov=miniprofiler --cov-report=html

Run Specific Test

pytest tests/test_protocol.py

Code Quality

Format Code (Black)

# Format all code
black miniprofiler tests

# Check without modifying
black --check miniprofiler tests

Lint Code (Ruff)

# Check for issues
ruff check miniprofiler tests

# Auto-fix issues
ruff check --fix miniprofiler tests

Common Tasks

Generate Sample Data

cd host/tests
python sample_data_generator.py

This creates:

• sample_profile_data.bin
• sample_flamegraph.json
• sample_statistics.json
• sample_timeline.json

Run with Different Settings

# Bind to all interfaces
miniprofiler --host 0.0.0.0

# Use different port
miniprofiler --port 8080

# Enable debug mode
miniprofiler --debug

# Verbose logging
miniprofiler --verbose

# Combine options
miniprofiler --host 0.0.0.0 --port 8080 --verbose

Clean Build Artifacts

# Using Makefile
make clean

# Or manually
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type f -name "*.pyc" -delete
rm -rf host/.venv host/build host/dist

Troubleshooting

uv command not found

# Install uv
pip install uv

# Or use the installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

Virtual environment activation issues

Linux/macOS:

# Make sure you're in the host directory
cd host

# Source the activate script
source .venv/bin/activate

# Verify activation (should show .venv path)
which python

Windows:

cd host
.venv\Scripts\activate

Import errors after installation

# Reinstall in editable mode
cd host
uv pip install -e .

# Verify package is installed
uv pip list | grep miniprofiler

Port already in use

# Use a different port
miniprofiler --port 8080

# Or find and kill the process using port 5000
# Linux/macOS:
lsof -ti:5000 | xargs kill

# Windows:
netstat -ano | findstr :5000
taskkill /PID <PID> /F

Why uv?

Benefits over traditional pip:

• 10-100x faster package installation
• Better dependency resolution
• Drop-in replacement for pip
• Virtual environment management built-in
• Maintained by Astral (creators of ruff)

Speed comparison:

pip install:     ~30 seconds
uv pip install:  ~3 seconds

Alternative: Traditional pip + venv

If you prefer not to use uv:

cd host

# Create virtual environment
python -m venv .venv

# Activate
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Install
pip install -e .

# Run
miniprofiler

Next Steps

After setup:

1. Read GETTING_STARTED.md for usage guide
2. Generate sample data: make sample
3. Run the server: make run
4. Open browser to http://localhost:5000

For development:

1. Install dev dependencies: make dev
2. Read PROJECT_STRUCTURE.md
3. Check out the code in host/miniprofiler/