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](https://github.com/astral-sh/uv) - Fast Python package installer

## Installing uv

If you don't have `uv` installed:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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:

```bash
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

```bash
cd host
uv venv
```

### Activate Environment

```bash
# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate
```

### Deactivate Environment

```bash
deactivate
```

### Delete Environment

```bash
# Linux/macOS
rm -rf .venv

# Windows
rmdir /s .venv
```

## Dependency Management

### Install New Package

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

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

### Update Dependencies

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

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

### List Installed Packages

```bash
uv pip list
```

### Generate requirements.txt (if needed)

```bash
uv pip freeze > requirements.txt
```

## Testing

### Run All Tests

```bash
pytest
```

### Run with Coverage

```bash
pytest --cov=miniprofiler --cov-report=html
```

### Run Specific Test

```bash
pytest tests/test_protocol.py
```

## Code Quality

### Format Code (Black)

```bash
# Format all code
black miniprofiler tests

# Check without modifying
black --check miniprofiler tests
```

### Lint Code (Ruff)

```bash
# Check for issues
ruff check miniprofiler tests

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

## Common Tasks

### Generate Sample Data

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
# 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:**
```cmd
cd host
.venv\Scripts\activate
```

### Import errors after installation

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

# Verify package is installed
uv pip list | grep miniprofiler
```

### Port already in use

```bash
# 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`:

```bash
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](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](PROJECT_STRUCTURE.md)
3. Check out the code in `host/miniprofiler/`