Development Setup
Comprehensive guide to setting up a development environment for contributing to the Azu web framework.
Overview
This guide covers everything you need to set up a development environment for contributing to Azu, including prerequisites, installation, configuration, and development tools.
Prerequisites
System Requirements
# Check your system requirements
echo "Operating System: $(uname -s)"
echo "Architecture: $(uname -m)"
echo "Available Memory: $(free -h | grep Mem | awk '{print $2}')"
echo "Available Disk Space: $(df -h . | tail -1 | awk '{print $4}')"
Minimum Requirements:
OS: Linux, macOS, or Windows (WSL)
Memory: 4GB RAM
Disk Space: 2GB free space
Crystal: 1.16.0 or higher
Crystal Installation
# Install Crystal on macOS
brew install crystal
# Install Crystal on Ubuntu/Debian
curl -fsSL https://crystal-lang.org/install.sh | sudo bash
# Install Crystal on CentOS/RHEL
curl -fsSL https://crystal-lang.org/install.sh | sudo bash
# Verify installation
crystal --version
Git Setup
# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# Set up SSH key (optional but recommended)
ssh-keygen -t ed25519 -C "your.email@example.com"
cat ~/.ssh/id_ed25519.pub
# Add to GitHub/GitLab
Repository Setup
Fork and Clone
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/your-username/azu.git
cd azu
# Add upstream remote
git remote add upstream https://github.com/azu-framework/azu.git
# Verify remotes
git remote -v
Branch Strategy
# Create a feature branch
git checkout -b feature/your-feature-name
# Or create a bugfix branch
git checkout -b fix/your-bug-description
# Or create a documentation branch
git checkout -b docs/your-doc-update
Development Environment
IDE Setup
VS Code Configuration
// .vscode/settings.json
{
"crystal.formatOnSave": true,
"crystal.languageServer": true,
"crystal.compiler": "crystal",
"editor.formatOnSave": true,
"editor.rulers": [120],
"files.trimTrailingWhitespace": true,
"files.insertFinalNewline": true
}
VS Code Extensions
// .vscode/extensions.json
{
"recommendations": [
"crystal-lang-tools.crystal-lang",
"ms-vscode.vscode-json",
"bradlc.vscode-tailwindcss",
"esbenp.prettier-vscode"
]
}
Crystal Language Server
# Install Crystal language server
crystal tool install
# Verify language server
crystal tool --help
Project Dependencies
Install Dependencies
# Install project dependencies
shards install
# Verify installation
crystal spec
Development Dependencies
# shard.yml development dependencies
development_dependencies:
ameba:
github: crystal-ameba/ameba
version: ~> 1.5.0
db:
github: crystal-lang/crystal-db
version: ~> 0.12.0
sqlite3:
github: crystal-lang/crystal-sqlite3
version: ~> 0.20.0
Development Tools
Code Quality Tools
# Install Ameba for code analysis
crystal tool install ameba
# Run Ameba
crystal tool run ameba
# Run Ameba on specific files
crystal tool run ameba src/azu/
Testing Setup
# Run all tests
crystal spec
# Run specific test file
crystal spec spec/azu/endpoint_spec.cr
# Run tests with coverage
crystal spec --coverage
# Run tests in parallel
crystal spec --parallel
Documentation Generation
# Generate documentation
crystal docs
# Serve documentation locally
crystal docs --serve
# Generate API documentation
crystal docs src/azu.cr
Database Setup
Development Database
# Install PostgreSQL (macOS)
brew install postgresql
brew services start postgresql
# Install PostgreSQL (Ubuntu)
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql
# Create development database
createdb azu_development
createdb azu_test
Database Configuration
# config/database.cr
CONFIG.database = {
development: {
url: "postgresql://localhost/azu_development",
pool_size: 5
},
test: {
url: "postgresql://localhost/azu_test",
pool_size: 2
}
}
Development Workflow
Code Style Guidelines
# .editorconfig
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2
[*.cr]
indent_size = 2
[*.yml]
indent_size = 2
[*.md]
trim_trailing_whitespace = false
Git Hooks
# .git/hooks/pre-commit
#!/bin/bash
# Run tests
crystal spec
# Run code analysis
crystal tool run ameba
# Check formatting
crystal tool format --check
Continuous Integration
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:13
env:
POSTGRES_PASSWORD: postgres
POSTGRES_DB: azu_test
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- uses: actions/checkout@v3
- name: Setup Crystal
uses: crystal-lang/install-crystal@v1
- name: Install dependencies
run: shards install
- name: Run tests
run: crystal spec
env:
DATABASE_URL: postgresql://postgres:postgres@localhost:5432/azu_test
- name: Run code analysis
run: crystal tool run ameba
Debugging Setup
Debug Configuration
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Azu",
"type": "crystal",
"request": "launch",
"program": "${workspaceFolder}/src/azu.cr",
"args": [],
"cwd": "${workspaceFolder}"
},
{
"name": "Debug Tests",
"type": "crystal",
"request": "launch",
"program": "crystal",
"args": ["spec"],
"cwd": "${workspaceFolder}"
}
]
}
Logging Configuration
# config/logging.cr
require "log"
# Development logging
Log.setup do |c|
backend = Log::IOBackend.new
c.bind("*", :info, backend)
c.bind("azu.*", :debug, backend)
end
Performance Profiling
Profiling Tools
# Install profiling tools
crystal tool install profile
# Run with profiling
crystal run --profile src/azu.cr
# Memory profiling
crystal run --stats src/azu.cr
Benchmarking
# spec/benchmark/performance_spec.cr
require "benchmark"
describe "Performance Benchmarks" do
it "benchmarks endpoint performance" do
time = Benchmark.measure do
1000.times do
# Test endpoint
end
end
puts "Average time: #{time.real / 1000}ms"
end
end
Documentation Development
Documentation Tools
# Install MkDocs
pip install mkdocs mkdocs-material
# Serve documentation
mkdocs serve
# Build documentation
mkdocs build
Documentation Structure
# mkdocs.yml
site_name: Azu Framework
theme:
name: material
features:
- navigation.tabs
- navigation.sections
- navigation.expand
- search.highlight
nav:
- Overview: index.md
- Getting Started:
- Installation: getting-started/installation.md
- First App: getting-started/first-app.md
- Core Concepts:
- Endpoints: core-concepts/endpoints.md
- Requests: core-concepts/requests.md
- Responses: core-concepts/responses.md
Testing Environment
Test Configuration
# spec/spec_helper.cr
require "spec"
require "../src/azu"
# Test configuration
CONFIG.test = {
database_url: "sqlite3://./test.db",
log_level: "error",
environment: "test"
}
# Test utilities
module TestHelpers
def self.create_test_request(path : String, method : String = "GET")
Azu::HttpRequest.new(
method: method,
path: path,
params: {} of String => String,
headers: HTTP::Headers.new
)
end
end
Test Database Setup
# spec/database_helper.cr
module DatabaseHelper
def self.setup_test_database
# Create test database schema
DB.connect(CONFIG.test.database_url) do |db|
db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)")
end
end
def self.cleanup_test_database
# Clean test data
DB.connect(CONFIG.test.database_url) do |db|
db.exec("DELETE FROM users")
end
end
end
Development Scripts
Build Scripts
#!/bin/bash
# scripts/build.sh
echo "Building Azu framework..."
# Clean previous build
rm -rf bin/
mkdir -p bin/
# Build release version
crystal build --release src/azu.cr -o bin/azu
# Build debug version
crystal build --debug src/azu.cr -o bin/azu-debug
echo "Build completed!"
Development Server
#!/bin/bash
# scripts/dev-server.sh
echo "Starting development server..."
# Run with hot reload
crystal run --watch src/azu.cr
echo "Development server stopped."
Code Quality Script
#!/bin/bash
# scripts/quality.sh
echo "Running code quality checks..."
# Format code
crystal tool format
# Run Ameba
crystal tool run ameba
# Run tests
crystal spec
echo "Code quality checks completed!"
Troubleshooting
Common Issues
# Issue: Crystal not found
export PATH="/usr/local/bin:$PATH"
# Issue: Permission denied
sudo chown -R $(whoami) /usr/local/bin
# Issue: Database connection failed
sudo systemctl start postgresql
# Issue: Dependencies not found
shards install --frozen
Debug Commands
# Check Crystal installation
crystal --version
which crystal
# Check dependencies
shards list
# Check database connection
psql -h localhost -U postgres -d azu_development
# Check system resources
top
df -h
free -h
Next Steps
First Contribution
# 1. Fork the repository
# 2. Clone your fork
git clone https://github.com/your-username/azu.git
# 3. Create a feature branch
git checkout -b feature/your-feature
# 4. Make your changes
# 5. Run tests
crystal spec
# 6. Commit your changes
git add .
git commit -m "Add feature: description"
# 7. Push to your fork
git push origin feature/your-feature
# 8. Create a pull request
Getting Help
GitHub Issues: Report bugs and request features
GitHub Discussions: Ask questions and discuss ideas
Discord: Join the community chat
Documentation: Read the comprehensive guides
Best Practices
1. Code Organization
# Follow the established structure
src/
├── azu/
│ ├── handler/
│ ├── templates/
│ └── *.cr
├── azu.cr
└── main.cr
2. Testing Strategy
# Write tests for new features
describe "New Feature" do
it "works as expected" do
# Test implementation
end
it "handles edge cases" do
# Edge case testing
end
end
3. Documentation
# Document public APIs
# Represents a user in the system
class User
# Creates a new user with the given attributes
def initialize(@name : String, @email : String)
end
end
Next Steps
Code Standards - Coding standards and guidelines
Roadmap - Development roadmap and priorities
Contributing Guidelines - General contributing guidelines
Happy coding! Your contributions help make Azu better for everyone.
Last updated
Was this helpful?