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

Required software and dependencies:

Ruby (version 2.7.0 or higher)
RubyGems
Bundler gem
ImageMagick or Vips (for image processing)

# 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

Installing ImageMagick on Windows:

Download the appropriate installer:
- Visit the ImageMagick Windows Download Page
- Choose the appropriate version (recommended: Q16-HDRI-x64)
- Example filename: ImageMagick-7.1.1-21-Q16-HDRI-x64-dll.exe
During installation:
- Check "Add to system PATH"
- Check "Install development headers and libraries for C and C++"
- Check "Install legacy utilities (e.g. convert)"
Verify installation:
- Open Command Prompt
- Run magick -version

View troubleshooting steps

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

The serve task provides a development environment with:

Live reload capability
Automatic Sass compilation
Vendor file processing
Asset watching

View implementation

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

The build task creates production-ready assets:

Minified CSS and JavaScript
Optimized images
Compiled Jekyll site
Environment-specific configurations

View implementation

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

Automated image optimization features:

Batch conversion to WebP format
Original file preservation options
Size optimization reporting
Configurable quality settings

View usage

# 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:

Start development server: bundle exec rake serve
Make changes to source files
Test in development environment
Optimize images if needed
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

Create custom Rake tasks in Rakefile:

View example

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`

Project Pages

Single Projects

Usage

Styleguide

Elements