This guide will help you set up a development environment and build Pumpkin from source.
Prerequisites
Pumpkin requires Rust 1.89 or later:
# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Verify installation
rustc --version
cargo --version
Git
Required to clone the repository:
# Verify git installation
git --version
Clippy (Recommended)
Linter for catching common mistakes:
rustup component add clippy
cargo-watch (Recommended)
Auto-rebuild on file changes:
cargo install cargo-watch
typos (Recommended)
Detect and fix typos automatically:
Getting the Source
Clone the Repository
git clone https://github.com/Pumpkin-MC/Pumpkin.git
cd Pumpkin
Repository Structure
Pumpkin/
├── pumpkin/ # Main server crate
├── pumpkin-protocol/ # Protocol implementation
├── pumpkin-world/ # World/chunk management
├── pumpkin-config/ # Configuration handling
├── pumpkin-data/ # Generated data/registries
├── pumpkin-inventory/ # Inventory system
├── pumpkin-util/ # Shared utilities
├── pumpkin-macros/ # Procedural macros
├── pumpkin-api-macros/ # Plugin API macros
├── pumpkin-nbt/ # NBT parsing (git submodule)
├── Cargo.toml # Workspace configuration
└── CONTRIBUTING.md # Contribution guidelines
Building Pumpkin
Development Build
Fastest compilation, includes debug symbols:
The binary will be at target/debug/pumpkin.
Release Build
Optimized for performance:
The binary will be at target/release/pumpkin.
Release builds take significantly longer but produce much faster executables.
The release profile uses LTO (Link-Time Optimization) and single codegen unit for maximum performance.
Running the Server
After building:
# Development build
./target/debug/pumpkin
# Release build
./target/release/pumpkin
cargo run:
# Development
cargo run
# Release
cargo run --release
Development Workflow
Running Tests
Run all unit tests:
Run tests for specific crate:
cargo test -p pumpkin-protocol
cargo test -p pumpkin-world
Linting with Clippy
Pumpkin uses strict Clippy settings. Run before submitting PRs:
# Check all targets
cargo clippy --all-targets
# Auto-fix some issues
cargo clippy --all-targets --fix
All Clippy warnings must be resolved before PRs can be merged. The CI will fail if any warnings exist.
cargo fmt
# Check formatting without applying
cargo fmt -- --check
Auto-rebuild on Changes
Use cargo-watch for automatic rebuilds:
# Watch and run
cargo watch -x run
# Watch and test
cargo watch -x test
# Watch and check (faster than build)
cargo watch -x check
Advanced Build Options
Build Profiles
Pumpkin defines several build profiles:
Release Profile
[profile.release]
lto = true # Link-time optimization
strip = "debuginfo" # Remove debug info
codegen-units = 1 # Single codegen unit (slower build, faster runtime)
Profiling Profile
For performance profiling:
cargo build --profile profiling
Bench Profile
Runs benchmarks with debug info enabled.
Feature Flags
Pumpkin supports optional features:
Console Subscriber (Tokio Debugging)
Enables tokio-console for async runtime debugging:
cargo build --features console-subscriber
Tokio Task Dump
Enables task dumping for debugging:
cargo build --features tokio_taskdump
Building Specific Crates
Build individual workspace members:
# Build just the protocol crate
cargo build -p pumpkin-protocol
# Build world crate with all features
cargo build -p pumpkin-world --all-features
Running Benchmarks
Pumpkin includes benchmarks using Criterion:
# Run all benchmarks
cargo bench
# Run specific benchmark
cargo bench --bench chunk
cargo bench --bench chunk_gen
cargo bench --bench noise_router
target/criterion/.
Troubleshooting
Build Failures
Rust Version Too Old
# Update Rust to latest stable
rustup update stable
# Or install specific version
rustup install 1.89
rustup default 1.89
Clippy Warnings Blocking Build
If clippy warnings prevent compilation:
# Build without clippy checks
cargo build
# Then fix warnings
cargo clippy --all-targets --fix
Out of Memory
Release builds with LTO can use significant memory:
# Reduce parallel jobs
cargo build --release -j 2
# Or disable LTO temporarily
cargo build --release --config profile.release.lto=false
Cleaning Build Artifacts
Remove all build artifacts:
Clean and rebuild:
cargo clean && cargo build --release
VS Code Setup
Recommended extensions:
- rust-analyzer: Rust language server
- CodeLLDB: Debugging support
- Even Better TOML: TOML syntax highlighting
IntelliJ IDEA / CLion Setup
Install the Rust plugin from JetBrains marketplace.
Linux
No special requirements. All dependencies are in Cargo.toml.
macOS
No special requirements. Ensure Xcode Command Line Tools are installed:
Windows
Install Visual Studio Build Tools or Visual Studio with C++ development tools.
WASI targets are not supported and will fail at compile time.
-
Profile your changes:
cargo build --profile profiling
# Use your preferred profiler (perf, instruments, etc.)
-
Run benchmarks:
# Baseline before changes
git stash
cargo bench
# After changes
git stash pop
cargo bench
-
Compare results in
target/criterion/
Next Steps
