# Makefile Usage Guide
This document explains how to use the comprehensive Makefile for Graph_D development.
## Quick Start
```bash
# Show all available commands
make help
# Set up development environment
make setup
# Quick development workflow
make dev # format + lint + check + test
# Build and test
make build
make test
```
## Command Categories
### 🏗️ **Build Commands**
```bash
make build # Debug build
make build-release # Optimized release build
make build-all # All targets (lib, bin, examples, tests, benches)
make check # Fast compilation check
```
### 🧪 **Testing Commands**
```bash
make test # All tests
make test-unit # Unit tests only
make test-integration # Integration tests only
make test-memory # Tests with memory management features
make test-coverage # Generate HTML coverage report
make test-watch # Continuous testing (requires cargo-watch)
```
### ⚡ **Benchmarking Commands**
```bash
make bench # All benchmarks
make bench-basic # Basic performance benchmarks
make bench-scalability # Scalability tests
make bench-memory # Memory management benchmarks
make bench-advanced # Advanced benchmarks (1M nodes test)
make bench-regression # Performance regression detection
make perf-report # Generate performance analysis report
```
### 🎨 **Code Quality Commands**
```bash
make format # Format code with rustfmt
make format-check # Check formatting without changes
make lint # Run clippy lints
make lint-fix # Auto-fix clippy warnings
make audit # Security audit
make outdated # Check for outdated dependencies
```
### 📚 **Documentation Commands**
```bash
make doc # Generate documentation
make doc-open # Generate and open docs in browser
make doc-test # Run documentation tests
```
### 🎯 **Examples and Demos**
```bash
make examples # Build all examples
make run-memory-example # Run memory management demo
```
### 🔄 **Development Workflows**
```bash
make dev # Full dev check: format + lint + check + test
make ci # Run CI pipeline locally
make pre-commit # Pre-commit checks
make quick-check # Fast check: format + check + unit tests
```
### 🚀 **Release Commands**
```bash
make release # Build optimized release binary
make release-check # Pre-release validation
make package # Create release package
```
### 🛠️ **Utility Commands**
```bash
make clean # Clean build artifacts
make info # Project information and status
make deps # Show dependency tree
make size # Binary size information
make git-status # Git status and recent commits
```
### 🔍 **Analysis Commands**
```bash
make memory-test # Memory usage analysis
make perf-profile # Performance profiling (requires perf)
make flamegraph # Generate flamegraph (requires cargo-flamegraph)
```
### 🎛️ **Feature-Specific Commands**
```bash
make build-unsafe # Build with unsafe allocators feature
make test-unsafe # Test with unsafe allocators
make bench-unsafe # Benchmark with unsafe allocators
```
### 🎯 **Module-Specific Testing**
```bash
make db-test # Database-specific tests
make gql-test # GQL parser/executor tests
```
## Common Workflows
### Daily Development
```bash
# Start working
make quick-check
# Before committing
make pre-commit
# Full validation
make dev
```
### Performance Analysis
```bash
# Basic performance check
make bench-basic
# Full performance analysis
make bench
make perf-report
# Memory efficiency testing
make bench-memory
make memory-test
```
### Release Preparation
```bash
# Comprehensive pre-release check
make release-check
# Create release
make release
make package
```
### CI/CD Simulation
```bash
# Run the same checks as CI
make ci
```
### Fresh Environment Setup
```bash
# Clean start
make fresh # clean + setup + build + test
```
## Tips and Best Practices
1. **Start with `make help`** to see all available commands
2. **Use `make dev`** for regular development workflow
3. **Run `make ci`** before pushing to simulate CI checks
4. **Use `make quick-check`** for fast feedback during development
5. **Run `make bench-basic`** regularly to catch performance regressions
6. **Use `make test-coverage`** to ensure good test coverage
7. **Run `make audit`** periodically for security updates
## Requirements
- **Rust toolchain** (stable)
- **Make** (available on most Unix systems)
- **Git** (for version control commands)
### Optional Tools
- `cargo-watch` for `make test-watch`
- `cargo-tarpaulin` for `make test-coverage`
- `cargo-audit` for `make audit`
- `cargo-outdated` for `make outdated`
- `cargo-flamegraph` for `make flamegraph`
- `perf` tools for `make perf-profile`
Install optional tools:
```bash
cargo install cargo-watch cargo-tarpaulin cargo-audit cargo-outdated flamegraph
```
## Color Output
The Makefile uses colored output to improve readability:
- 🔵 **Blue**: Section headers and command descriptions
- 🟢 **Green**: Success messages
- 🟡 **Yellow**: Warnings and notes
- 🔴 **Red**: Errors
## Custom Targets
You can extend the Makefile by adding your own targets. Follow the existing pattern:
```makefile
my-target: ## Description for help
@echo "$(BLUE)Running my custom target...$(RESET)"
@your-command-here
@echo "$(GREEN)My target completed!$(RESET)"
```
## Performance Monitoring
The Makefile includes several performance monitoring capabilities:
- **Regression Detection**: `make bench-regression`
- **Memory Analysis**: `make bench-memory` and `make memory-test`
- **Performance Reports**: `make perf-report` generates PERFORMANCE_REPORT.md
- **Advanced Benchmarks**: `make bench-advanced` runs the 1M nodes target test
## Troubleshooting
If you encounter issues:
1. Check your Rust installation: `make info`
2. Clean and rebuild: `make clean && make build`
3. Update dependencies: `cargo update`
4. Check for security issues: `make audit`
For more detailed information about specific commands, use `make help` or examine the Makefile directly.