446 lines
6.9 KiB
Markdown
446 lines
6.9 KiB
Markdown
# 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/`
|