RBS
Collection manager
rbs collection
sub command manages third party gems' RBS
. In short, it is bundler
for RBS
.
Requirements
git(1)
Gemfile.lock
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.
rbs collection update
updatesrbs_collection.lock.yaml
.rbs collection clean
removes unnecessary rbs from.gem_rbs_collection
directory.
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
rbs_collection.yaml
- The configuration file.
- You need to edit it if:
- You don't want to ignore gem's RBS.
- You want to add gem's RBS explicitly.
- You can change the file path with
--collection
option. e.g.rbs --collection another_conf.yaml collection install
.
rbs_collection.lock.yaml
- RBS installs and loads RBS files with this file.
- It is auto-generated file. Do not edit this file.
- I recommend to manage it with VCS such as git.
.gem_rbs_collection/
- RBS installs third party RBS files to the directory.
- I recommend to ignore it from VCS.
- You can change the path with
path
option ofrbs_collection.yaml
file.
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.