rad~$
GitHub

Gemfile Syntax Comparison

Compare Bundler's Gemfile syntax with Rad's enhanced format and understand the compatibility between them.

Basic Compatibility

Rad is fully compatible with Bundler's Gemfile format. Any valid Bundler Gemfile will work with Rad without modifications. This guarantees a smooth transition between the two tools.

Rad's parser is designed to be 100% compatible with Bundler's Gemfile format while providing additional performance optimizations.

Standard Gemfile Features

Below are the standard Gemfile features supported by both Bundler and Rad:

terminal
# Basic gem declaration
source "https://rubygems.org"
# Ruby version specification
ruby "3.2.2"
# Basic gem with exact version
gem "rails", "7.1.0"
# Gem with version constraint
gem "pg", "~> 1.5.0"
# Group declaration
group :development, :test do
gem "rspec-rails"
gem "debug"
end
# Platform-specific gems
platforms :ruby do
gem "sqlite3"
end
# Gem from git source
gem "rails", git: "https://github.com/rails/rails.git", branch: "main"
# Gem from path
gem "my_gem", path: "../my_gem"
# Gemspec for gem development
gemspec

Rad's Enhanced Features

Rad offers several enhancements to the standard Gemfile format that provide better performance and more precise dependency management:

terminal
# Source with priority
source "https://rubygems.org", priority: :highest
# More precise version constraints
gem "rails", "~{'>'} 7.1.0", exact_minor: true # Ensures minor version is exactly 7.1.x
# Advanced platform specifications
gem "pg", platforms: [:ruby, :native] # Only install on native Ruby platforms
# Dependency resolution hints
gem "nokogiri", resolution: :prefer_newer # Prefers newer versions during resolution
# Performance optimizations
install_options parallel: true, jobs: 4 # Parallel installation with 4 jobs
# Enhanced git source options
gem "rails",
git: "https://github.com/rails/rails.git",
ref: "a1b2c3d",
sparse: true # Uses git sparse checkout for faster cloning
While Bundler will ignore Rad's enhanced features, they won't cause errors—making your Gemfile compatible with both tools.

Advanced Feature Comparison

FeatureBundler SyntaxRad Enhanced SyntaxBenefits
Source Prioritysource "https://example.com"source "https://example.com", priority: :highestBetter control over gem source resolution
Version Constraintsgem "rails", "~> 7.1.0"gem "rails", "~> 7.1.0", exact_minor: trueMore precise version pinning
Platform Handlingplatforms :ruby dogem "pg", platforms: [:ruby, :native]Finer-grained platform control
Git Integrationgem "rails", git: "..."gem "rails", git: "...", sparse: trueFaster git operations with sparse checkout
Parallel InstallationNot available in Gemfileinstall_options parallel: true, jobs: 4Faster installation with parallelism

Gemfile.rad Lockfile

Rad generates a Gemfile.rad lockfile alongside Bundler's Gemfile.lock. Both files can coexist in the same project:

terminal
→ls -la | grep -E 'Gemfile|\.rad'
-rw-r--r-- 1 user staff 354 Oct 8 12:34 Gemfile
-rw-r--r-- 1 user staff 4532 Oct 8 12:35 Gemfile.lock
-rw-r--r-- 1 user staff 5642 Oct 8 12:35 Gemfile.rad
drwxr-xr-x 4 user staff 128 Oct 8 12:35 .rad/

Key Differences in Lockfiles

While the format is compatible, Rad's lockfile includes additional metadata for faster resolution:

  • Enhanced checksum algorithms for better integrity verification
  • Optimized dependency graph representation for faster loading
  • Platform-specific metadata for improved cross-platform compatibility
  • Performance statistics and benchmarks (optional)
Projects can maintain both lockfiles to support developers using either Bundler or Rad. This is particularly useful during transition periods.

Migrating Between Formats

Converting Bundler's Lockfile to Rad

Rad can automatically convert a Bundler lockfile to its own format:

terminal
→rad lock --convert
Converting Gemfile.lock to Rad format...
Reading Bundler lockfile...
Creating optimized Rad lockfile...
✓ Successfully created Gemfile.rad
Lockfile size: 5642 bytes (25% more efficient than Bundler)

Using Rad's Enhanced Features

To take advantage of Rad's enhanced features while maintaining Bundler compatibility:

  1. Start with your existing Bundler Gemfile
  2. Add Rad-specific enhancements as needed
  3. Run rad install to generate both lockfiles
  4. Commit both lockfiles to your repository

Best Practices

  • Maintain compatibility with both Bundler and Rad during team transitions
  • Use Rad's enhanced features for performance-critical projects
  • Document your Gemfile's special features for team awareness
  • Leverage Rad's advanced platform support for cross-platform development
  • Consider using CI matrix builds with both Bundler and Rad for thorough testing

Further Reading

GitHub