123456789_123456789_123456789_123456789_123456789_

RBS Collection manager

rbs collection sub command manages third party gems' RBS. In short, it is bundler for RBS.

Requirements

Usage

Setup

First, generate the configuration file, rbs_collection.yaml, with rbs collection init.

$ rbs collection init
created: rbs_collection.yaml

$ cat rbs_collection.yaml
# Download sources
sources:
  - name: ruby/gem_rbs_collection
    remote: https://github.com/ruby/gem_rbs_collection.git
    revision: main
    repo_dir: gems

# A directory to install the downloaded RBSs
path: .gem_rbs_collection

# gems:
#   # If you want to avoid installing rbs files for gems, you can specify them here.
#   - name: GEM_NAME
#     ignore: true

I also recommend updating .gitignore.

$ echo /.gem_rbs_collection/ >> .gitignore

Install dependencies

Then, install gems' RBS with rbs collection install! It copies RBS from the gem RBS repository to .gem_rbs_collection/ directory by default. I recommend to ignore .gem_rbs_collection/ from version control system, such as Git.

$ rbs collection install
Installing ast:2.4 (ruby/gem_rbs_collection@4b1a2a2f64c)
...
It's done! 42 gems's RBSs now installed.

Finally the third party RBSs are available! rbs commands, such as rbs validate, automatically load the third party RBSs.

Other commands

rbs collection has two more commands.

Configuration

rbs_collection.yaml

Configure rbs collection with editing rbs_collection.yaml.

# rbs_collection.yaml

# Download sources.
# You can add own collection git repository.
sources:
  - name: ruby/gem_rbs_collection
    remote: https://github.com/ruby/gem_rbs_collection.git
    revision: main
    repo_dir: gems

  # You can also add a local path as a collection source optionally.
  - type: local
    path: path/to/local/dir

# A directory to install the downloaded RBSs
path: .gem_rbs_collection

gems:
  # If the Gemfile.lock doesn't contain csv gem but you use csv gem,
  # you can write the gem name explicitly to install RBS of the gem.
  - name: csv

  # If the Gemfile.lock contains nokogiri gem but you don't want to use the RBS,
  # you can ignore the gem.
  # `rbs collection` avoids to install nokogiri gem's RBS by this change.
  # It is useful if the nokogiri RBS has a problem, such as compatibility issue with other RBS.
  - name: nokogiri
    ignore: true

Avoid installing RBS

There are two ways to avoid RBS installation.

require: false in Gemfile

First, you can specify require: false in Gemfile. It is the recommended way to avoid installing RBS. For example:

# Gemfile

gem 'GEM_NAME', require: false

In this case, rbs collection doesn't install the RBS of GEM_NAME. We recommend to specify require: false for rbs gem itself because rbs gem's RBS file is not necessary in most cases.

ignore: true in rbs_collection.yaml

Second, you can write ignore: true in rbs_collection.yaml. It is useful if you want to avoid installing RBS but you need to require the gem.

# rbs_collection.yaml

gems:
  - name: GEM_NAME
    ignore: true

Load RBS specified require: false

You can also use ignore: false if you want to install RBS for a gem which you specify require: false in Gemfile. For example:

# Gemfile

gem 'GEM_NAME', require: false
# rbs_collection.yaml

gems:
  - name: GEM_NAME
    ignore: false

In this case, rbs collection installs the RBS of GEM_NAME.

manifest.yaml

If you are a gem maintainer, you can write manifest.yaml. You need to put the file if the gem has implicit dependencies, which don't appear in Gemfile.lock. You have to write standard libraries' dependencies in most cases. For example:

# manifest.yaml

dependencies:
  # If your gem depends on pathname but the gemspec doesn't include pathname,
  # you need to write the following.
  - name: pathname

If the gem's RBS is managed with ruby/gem_rbs_collection, put it as gems/GEM_NAME/VERSION/manifest.yaml. For example, gems/activesupport/6.0/manifest.yaml. If the gem's RBS is included in the gem package, put it as sig/manifest.yaml.

Files / Directories

How it works

rbs collection is integrated with Bundler. rbs collection install command generates gem_rbs_collection.lock.yaml from gem_rbs_collection.yaml and Gemfile.lock. It uses Gemfile.lock to detects dependencies.