JezK
Edit File: 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.