Gemfile DSL Reference

A comprehensive guide to the Gemfile Domain Specific Language (DSL) supported by Rad.

Introduction

Rad uses the same Gemfile format as Bundler, ensuring compatibility with existing Ruby projects. The Gemfile is a Ruby file that defines the gems your application depends on and optionally where they should be sourced from.

Rad handles even your weirdest Gemfiles like a champ. Its Gemfile Magic Support means that you can keep using your existing Gemfile format with all its quirks and complexities.

Basic Structure

A basic Gemfile starts with a source definition and lists the required gems:

terminal

# A sample Gemfile

source "https://rubygems.org"

gem "rails", "7.1.0"

gem "pg", "~> 1.5.0"

gem "puma"

Source Declaration

The source declaration specifies where to fetch gems from:

terminal

# Default public gem source

source "https://rubygems.org"

# Private gem source

source "https://gems.example.com" do

gem "internal-gem"

gem "private-helpers"

end

# Multiple sources with credentials

source "https://user:[email protected]"

Gem Declarations

Basic Gem Declaration

terminal

# Without version constraint

gem "rake"

# With exact version

gem "rails", "7.1.0"

# With version requirements

gem "pg", ">= 1.4.0", "< 2.0.0"

Version Requirements

Rad supports all standard version requirement formats with an advanced dependency resolver that makes Bundler look like it's using an abacus:

Format	Description	Example
"= 1.0"	Exactly version 1.0	gem "rails", "= 7.1.0"
"!= 1.0"	Any version except 1.0	gem "rails", "!= 7.0.0"
> 1.0	Any version greater than 1.0	gem "rails", > 7.0.0
< 2.0	Any version less than 2.0	gem "rails", < 8.0.0
>= 1.0	Version 1.0 or greater	gem "rails", >= 7.0.0
<= 2.0	Version 2.0 or less	gem "rails", <= 7.1.0
~> 1.0	Pessimistic version constraint (>= 1.0, < 2.0)	gem "rails", ~> 7.0
~> 1.0.1	Pessimistic version constraint (>= 1.0.1, < 1.1.0)	gem "rails", ~> 7.0.6
>= 1.0, < 2.0	Multiple requirements (ranges)	gem "rails", >= 7.0.0, < 8.0.0

The pessimistic version constraint (~>) is especially useful for ensuring compatible updates while avoiding potentially breaking changes in major version updates.

Gem Options

Gems can have additional options that specify how they should be handled:

terminal

# Specify a gem as required

gem "rails", require: true

# Don't require the gem automatically

gem "nokogiri", require: false

# Require a specific file instead of the gem name

gem "sinatra", require: "sinatra/base"

# Require multiple files

gem "rails-helpers", require: ["rails/helpers", "rails/filters"]

Alternate Sources

Gems can be loaded from different sources, including Git repositories and local paths:

terminal

# From a Git repository

gem "rails", git: "https://github.com/rails/rails.git"

# From a specific branch

gem "rails", git: "https://github.com/rails/rails.git", branch: "main"

# From a specific tag

gem "rails", git: "https://github.com/rails/rails.git", tag: "v7.1.0"

# From a specific revision

gem "rails", git: "https://github.com/rails/rails.git", ref: "4aded"

# From a local path

gem "my_gem", path: "../my_gem"

Groups

Gems can be organized into groups, which can be selectively installed:

terminal

# Grouping gems

group :development, :test do

gem "rspec-rails"

gem "factory_bot_rails"

end

group :development do

gem "listen"

gem "spring"

end

group :test do

gem "capybara"

gem "webdrivers"

end

group :production do

gem "newrelic_rpm"

gem "sentry-ruby"

end

# Specifying groups inline

gem "debug", group: [:development, :test]

You can install gems without certain groups:

terminal

→rad install --without development test

Fetching gem metadata from https://rubygems.org/... Resolving dependencies... Using rake 13.0.6 Using concurrent-ruby 1.2.2 ... Gems in the development, test groups were not installed

Platform-specific Gems

Gems can be specified for particular platforms with Rad's platform detection that's so accurate it's almost creepy:

terminal

# Using the platform block syntax

platforms :ruby do

gem "sqlite3"

end

platforms :jruby do

gem "activerecord-jdbc-adapter"

end

# Using the platform option in gem declaration

gem "pg", platform: :ruby

gem "jdbc-postgres", platform: :jruby

# Multiple platforms

gem "nokogiri", platforms: [:ruby, :mswin]

terminal

→rad platform list

Available Platforms: - ruby - x86_64-linux - x86_64-darwin - arm64-darwin - ...

Gemfile.rad

Rad is fully compatible with existing Gemfiles and automatically generates a Gemfile.rad file when resolving dependencies. This file is used to store Rad-specific metadata and optimizations.

terminal

→rad resolve

Resolving dependencies... Successfully resolved dependencies! Generated Gemfile.rad with optimized dependency metadata

The Gemfile.rad file should be committed to version control along with your Gemfile and Gemfile.lock.

Rad generates lockfiles so deterministic they'd make a mathematician weep. They ensure that your dependencies are consistent across all environments and installations.

Examples

Real-world Example

terminal

source "https://rubygems.org"

# Core gems

gem "rails", "~> 7.1.0"

gem "pg", ">= 1.4.0", "< 2.0"

gem "puma", "~> 6.0"

gem "redis", "~> 5.0"

# Frontend

gem "sprockets-rails"

gem "importmap-rails"

gem "turbo-rails"

gem "stimulus-rails"

# Background jobs

gem "sidekiq", "~> 7.0"

# Development tools

group :development, :test do

gem "debug", platforms: [:mri, :mingw, :x64_mingw]

gem "rspec-rails"

gem "factory_bot_rails"

end

# Platform-specific gems

platforms :ruby do

gem "sqlite3", "~> 1.6", groups: [:development, :test]

gem "bcrypt", "~> 3.1.7"

end

platforms :jruby do

gem "activerecord-jdbcsqlite3-adapter", groups: [:development, :test]

gem "jruby-bcrypt"

end