Rake Build System

Understanding Rake

What is Rake?

Rake (Ruby Make) is a build automation tool written in Ruby. In the Sandbox theme, it handles:

• Development server management
• Production builds
• Asset optimization
• Image processing
• Task automation

Prerequisites

# Install Ruby dependencies
gem install bundler

# Install ImageMagick (MacOS)
brew install imagemagick

# Install ImageMagick (Ubuntu/Debian)
sudo apt-get install imagemagick

# Install project dependencies
bundle install

Windows Installation Guide

Common Windows Issues:

1. "Convert not found" error:
   - Rename "convert.exe" to "imagemagick-convert.exe" in ImageMagick installation directory
   - This prevents conflicts with Windows system convert.exe

2. PATH issues:
   - Open System Properties
   - Click "Environment Variables"
   - Add ImageMagick directory to Path (typically C:\Program Files\ImageMagick-7.x.x-Q16)

3. Ruby gem installation fails:
   - Install Visual Studio Build Tools
   - Run: `ridk install` (select options 1, 2, and 3)
   - Reinstall the gem

4. DLL load failed:
   - Install Visual C++ Redistributable
   - Download from Microsoft's website
   - Install both x86 and x64 versions if unsure

System Requirements

Windows-specific requirements:

• Windows 10 or later (recommended)
• Visual C++ Redistributable 2015-2022
• Visual Studio Build Tools (for gem installation)
• At least 2GB free disk space
• Administrator privileges for installation

Core Functionality

Development Server

desc "Serve the site"
task :serve => [:prepare] do
  begin
    $logger.info "Starting development server..."
    sh "bundle exec jekyll serve --livereload --livereload-min-delay 5 --trace"
  rescue => e
    $logger.error "Serve error: #{e.message}"
    raise
  end
end

Production Build

desc "Build the site"
task :build => [:prepare] do
  begin
    $logger.info "Building site for production..."
    sh "JEKYLL_ENV=production bundle exec jekyll build"
  rescue => e
    $logger.error "Build error: #{e.message}"
    raise
  end
end

Image Processing

WebP Conversion

# Convert images to WebP
bundle exec rake convert_to_webp

# Optimize and remove originals
bundle exec rake optimize_images[true]

# Remove original files
bundle exec rake remove_originals

Best Practices

Development Workflow

Recommended development workflow:

1. Start development server: bundle exec rake serve
2. Make changes to source files
3. Test in development environment
4. Optimize images if needed
5. Build for production: bundle exec rake build

Performance Tips

Optimize build performance:

• Use incremental builds during development
• Process images in batches
• Maintain clean asset directories
• Regular cache clearing

Troubleshooting

Common Issues

Solutions for frequent problems:

• Missing Dependencies: Run bundle install
• Port Conflicts: Change port in configuration
• Build Failures: Check error logs and Jekyll environment
• Image Processing Errors: Verify ImageMagick installation

Debugging

Debug Rake tasks:

• Enable verbose mode: rake -v task_name
• Check Jekyll logs in _site/build.log
• Use --trace flag for detailed stack traces
• Monitor system resources during builds

Advanced Usage

Custom Tasks

desc "Custom task description"
task :custom_task do
  puts "Executing custom task..."
  # Add your custom logic here
end

# Task with dependencies
task :custom_task_with_deps => [:prepare, :build] do
  # This task runs after prepare and build
end

Command Reference

Available Commands

Command	Description	Usage
serve	Start development server	bundle exec rake serve
build	Build for production	bundle exec rake build
convert_to_webp	Convert images to WebP	bundle exec rake convert_to_webp
optimize_images	Convert and optionally remove originals	bundle exec rake optimize_images[true]
prepare	Run preparation tasks	bundle exec rake prepare
remove_originals	Remove original images	bundle exec rake remove_originals