Current File : //opt/plesk/ruby/3.2.2/lib64/ruby/gems/3.2.0/gems/rbs-2.8.2/docs/collection.md
# 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`.
```console
$ 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:
# Skip loading rbs gem's RBS.
# It's unnecessary if you don't use rbs as a library.
- name: rbs
ignore: true
```
I also recommend updating `.gitignore`.
```console
$ echo /.gem_rbs_collection/ >> .gitignore
```
### Install dependencies
Then, install gems' RBS with `rbs collection install`! It copies RBS from [the gem RBS repository](https://github.com/ruby/gem_rbs_collection) to `.gem_rbs_collection/` directory by default.
I recommend to ignore `.gem_rbs_collection/` from version control system, such as Git.
```console
$ 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` updates `rbs_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`.
```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
# 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
```
### `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:
```yaml
# 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](https://github.com/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 of `rbs_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.
Mini Shell