README.md in tapioca-0.12.0 vs README.md in tapioca-0.13.0
- old
+ new
@@ -38,10 +38,11 @@
* [Generating RBI files for gems](#generating-rbi-files-for-gems)
* [Manually requiring parts of a gem](#manually-requiring-parts-of-a-gem)
* [Excluding a gem from RBI generation](#excluding-a-gem-from-rbi-generation)
* [Changing the strictness level of the RBI for a gem](#changing-the-strictness-level-of-the-rbi-for-a-gem)
* [Keeping RBI files for gems up-to-date](#keeping-rbi-files-for-gems-up-to-date)
+ * [Importing hand written signatures from gem's `rbi/` folder](#importing-hand-written-signatures-from-gems-rbi-folder)
* [Pulling RBI annotations from remote sources](#pulling-rbi-annotations-from-remote-sources)
* [Basic authentication](#basic-authentication)
* [Using a .netrc file](#using-a-netrc-file)
* [Changing the typed strictness of annotations files](#changing-the-typed-strictness-of-annotations-files)
* [Generating RBI files for Rails and other DSLs](#generating-rbi-files-for-rails-and-other-dsls)
@@ -81,14 +82,14 @@
tapioca init # Get project ready for type checking
tapioca require # Generate the list of files to be required by tapioca
tapioca todo # Generate the list of unresolved constants
Options:
- -c, [--config=<config file path>] # Path to the Tapioca configuration file
- # Default: sorbet/tapioca/config.yml
- -V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
- # Default: false
+ -c, [--config=<config file path>] # Path to the Tapioca configuration file
+ # Default: sorbet/tapioca/config.yml
+ -V, [--verbose], [--no-verbose], [--skip-verbose] # Verbose output for debugging purposes
+ # Default: false
```
<!-- END_HELP -->
## Getting started
@@ -115,14 +116,14 @@
Usage:
tapioca init
Options:
- -c, [--config=<config file path>] # Path to the Tapioca configuration file
- # Default: sorbet/tapioca/config.yml
- -V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
- # Default: false
+ -c, [--config=<config file path>] # Path to the Tapioca configuration file
+ # Default: sorbet/tapioca/config.yml
+ -V, [--verbose], [--no-verbose], [--skip-verbose] # Verbose output for debugging purposes
+ # Default: false
Get project ready for type checking
```
<!-- END_HELP_COMMAND_INIT -->
@@ -162,47 +163,47 @@
Usage:
tapioca gem [gem...]
Options:
- --out, -o, [--outdir=directory] # The output directory for generated gem RBI files
- # Default: sorbet/rbi/gems
- [--file-header], [--no-file-header] # Add a "This file is generated" header on top of each generated RBI file
- # Default: true
- [--all], [--no-all] # Regenerate RBI files for all gems
- # Default: false
- --pre, -b, [--prerequire=file] # A file to be required before Bundler.require is called
- --post, -a, [--postrequire=file] # A file to be required after Bundler.require is called
- # Default: sorbet/tapioca/require.rb
- -x, [--exclude=gem [gem ...]] # Exclude the given gem(s) from RBI generation
- [--include-dependencies], [--no-include-dependencies] # Generate RBI files for dependencies of the given gem(s)
- # Default: false
- --typed, -t, [--typed-overrides=gem:level [gem:level ...]] # Override for typed sigils for generated gem RBIs
- # Default: {"activesupport"=>"false"}
- [--verify], [--no-verify] # Verify RBIs are up-to-date
- # Default: false
- [--doc], [--no-doc] # Include YARD documentation from sources when generating RBIs. Warning: this might be slow
- # Default: true
- [--loc], [--no-loc] # Include comments with source location when generating RBIs
- # Default: true
- [--exported-gem-rbis], [--no-exported-gem-rbis] # Include RBIs found in the `rbi/` directory of the gem
- # Default: true
- -w, [--workers=N] # Number of parallel workers to use when generating RBIs (default: auto)
- [--auto-strictness], [--no-auto-strictness] # Autocorrect strictness in gem RBIs in case of conflict with the DSL RBIs
- # Default: true
- --dsl-dir, [--dsl-dir=directory] # The DSL directory used to correct gems strictnesses
- # Default: sorbet/rbi/dsl
- [--rbi-max-line-length=N] # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
- # Default: 120
- -e, [--environment=ENVIRONMENT] # The Rack/Rails environment to use when generating RBIs
- # Default: development
- [--halt-upon-load-error], [--no-halt-upon-load-error] # Halt upon a load error while loading the Rails application
- # Default: true
- -c, [--config=<config file path>] # Path to the Tapioca configuration file
- # Default: sorbet/tapioca/config.yml
- -V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
- # Default: false
+ --out, -o, [--outdir=directory] # The output directory for generated gem RBI files
+ # Default: sorbet/rbi/gems
+ [--file-header], [--no-file-header], [--skip-file-header] # Add a "This file is generated" header on top of each generated RBI file
+ # Default: true
+ [--all], [--no-all], [--skip-all] # Regenerate RBI files for all gems
+ # Default: false
+ --pre, -b, [--prerequire=file] # A file to be required before Bundler.require is called
+ --post, -a, [--postrequire=file] # A file to be required after Bundler.require is called
+ # Default: sorbet/tapioca/require.rb
+ -x, [--exclude=gem [gem ...]] # Exclude the given gem(s) from RBI generation
+ [--include-dependencies], [--no-include-dependencies], [--skip-include-dependencies] # Generate RBI files for dependencies of the given gem(s)
+ # Default: false
+ --typed, -t, [--typed-overrides=gem:level [gem:level ...]] # Override for typed sigils for generated gem RBIs
+ # Default: {"activesupport"=>"false"}
+ [--verify], [--no-verify], [--skip-verify] # Verify RBIs are up-to-date
+ # Default: false
+ [--doc], [--no-doc], [--skip-doc] # Include YARD documentation from sources when generating RBIs. Warning: this might be slow
+ # Default: true
+ [--loc], [--no-loc], [--skip-loc] # Include comments with source location when generating RBIs
+ # Default: true
+ [--exported-gem-rbis], [--no-exported-gem-rbis], [--skip-exported-gem-rbis] # Include RBIs found in the `rbi/` directory of the gem
+ # Default: true
+ -w, [--workers=N] # Number of parallel workers to use when generating RBIs (default: auto)
+ [--auto-strictness], [--no-auto-strictness], [--skip-auto-strictness] # Autocorrect strictness in gem RBIs in case of conflict with the DSL RBIs
+ # Default: true
+ --dsl-dir, [--dsl-dir=directory] # The DSL directory used to correct gems strictnesses
+ # Default: sorbet/rbi/dsl
+ [--rbi-max-line-length=N] # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
+ # Default: 120
+ -e, [--environment=ENVIRONMENT] # The Rack/Rails environment to use when generating RBIs
+ # Default: development
+ [--halt-upon-load-error], [--no-halt-upon-load-error], [--skip-halt-upon-load-error] # Halt upon a load error while loading the Rails application
+ # Default: true
+ -c, [--config=<config file path>] # Path to the Tapioca configuration file
+ # Default: sorbet/tapioca/config.yml
+ -V, [--verbose], [--no-verbose], [--skip-verbose] # Verbose output for debugging purposes
+ # Default: false
Generate RBIs from gems
```
<!-- END_HELP_COMMAND_GEM -->
@@ -221,22 +222,22 @@
For gems that have a normal default `require` and that load all of their constants through that, everything should work seamlessly. However, for gems that are marked as `require: false` in the `Gemfile`, or for gems that export constants optionally via different requires, where a single require does not load the whole gem code into memory, Tapioca will not be able to load some of the types into memory and, thus, won't be able to generate complete RBIs for them. For this reason, we need to keep a small external file named `sorbet/tapioca/require.rb` that is executed after all the gems in the `Gemfile` have been required and before generation of gem RBIs have started. This file is responsible for adding the requires for additional files from gems, which are not covered by the default require.
For example, suppose you are using the class `BetterHtml::Parser` exported from the `better_html` gem. Just doing a `require "better_html"` (which is the default require) does not load that type:
```shell
-$ bundle exec pry
+$ bundle exec irb
-[1] pry(main)> require 'better_html'
+irb(main):001> require 'better_html'
=> true
-[2] pry(main)> BetterHtml
+irb(main):002> BetterHtml
=> BetterHtml
-[3] pry(main)> BetterHtml::Parser
-NameError: uninitialized constant BetterHtml::Parser
-from (pry):3:in `__pry__`
-[4] pry(main)> require 'better_html/parser'
+irb(main):003> BetterHtml::Parser
+(irb):3:in '<main>': uninitialized constant BetterHtml::Parser (NameError)
+Did you mean? BetterHtml::ParserError
+irb(main):004> require 'better_html/parser'
=> true
-[5] pry(main)> BetterHtml::Parser
+irb(main):005> BetterHtml::Parser
=> BetterHtml::Parser
```
In order to make sure that `tapioca` can reflect on that type, we need to add the line `require "better_html/parser"` to the `sorbet/tapioca/require.rb` file. This will make sure `BetterHtml::Parser` is loaded into memory and a type annotation is generated for it in the `better_html.rbi` file. If this extra `require` line is not added to `sorbet/tapioca/require.rb` file, then Tapioca will be able to generate definitions for `BetterHtml` and other constants, but not for `BetterHtml::Parser`, which will be missing from the RBI file.
@@ -313,22 +314,31 @@
gemB: "false"
```
#### Keeping RBI files for gems up-to-date
-To ensure all RBI files for gems are up-to-date with the latest changes in your `Gemfile.lock`, Tapioca provides a `--verify` option:
+To ensure all RBI files for gems are present and have the correct version based on your `Gemfile.lock`, Tapioca provides a `--verify` option:
```shell
$ bin/tapioca gems --verify
Checking for out-of-date RBIs...
Nothing to do, all RBIs are up-to-date.
```
-This option can be used on CI to make sure the RBI files are always up-to-date and ensure accurate type checking. **Warning**: doing so will break your normal Dependabot workflow as every pull-request opened to bump a gem version will fail CI since the RBI will be out-of-date and will require you to manually run `bin/tapioca gems` to update them.
+This option can be used in CI to make sure the RBI files are *up-to-date* and ensure accurate type checking.
+**Warning**: doing so will break your normal automated dependency update workflow as every pull request opened to bump a gem version will fail CI since the RBI will be out-of-date. You will need to either set up additional automation (eg [Dependabot](https://github.com/dependabot/dependabot-core/issues/5962#issuecomment-1303781931)), or manually run `bin/tapioca gems` and commit the results.
+
+**Warning**: Verification ONLY ensures the RBI files are present, used and have the correct version based on the gem version in your `Gemfile.lock`. It's possible for your RBIs to be out-of-date if RBIs were not regenerated following an update to tapioca itself or if a another gem that injects functionality (e.g. `turbo-rails`) was installed/updated/removed. To ensure RBIs are completely up-to-date, you must run `bin/tapioca gems --all` but it's not recommended to do this in CI as it's an expensive operation.
+
+
+#### Importing hand written signatures from gem's `rbi/` folder
+
+Tapioca will import any signatures found in the `rbi/` folder of a given gem and combine them with the RBIs it generates. This is useful when a gem doesn't want to depend on `sorbet-runtime` but still wants to provide type safety to users during static checks. Note that the `rbi/` folder needs to be included in the gem release using the `.gemspec` file. Applications can choose not to import these signatures using the `--no-exported-gem-rbis` flag.
+
### Pulling RBI annotations from remote sources
Since Tapioca does not perform any type inference, the RBI files generated for the gems do not contain any type signatures. Instead, Tapioca relies on the community to provide high-quality, manually written RBI annotations for public gems.
To pull the annotations relevant to your project from the central repository, run the `annotations` command:
@@ -355,18 +365,18 @@
tapioca annotations
Options:
[--sources=one two three] # URIs of the sources to pull gem RBI annotations from
# Default: "https://raw.githubusercontent.com/Shopify/rbi-central/main"
- [--netrc], [--no-netrc] # Use .netrc to authenticate to private sources
+ [--netrc], [--no-netrc], [--skip-netrc] # Use .netrc to authenticate to private sources
# Default: true
[--netrc-file=NETRC_FILE] # Path to .netrc file
[--auth=AUTH] # HTTP authorization header for private sources
--typed, -t, [--typed-overrides=gem:level [gem:level ...]] # Override for typed sigils for pulled annotations
-c, [--config=<config file path>] # Path to the Tapioca configuration file
# Default: sorbet/tapioca/config.yml
- -V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
+ -V, [--verbose], [--no-verbose], [--skip-verbose] # Verbose output for debugging purposes
# Default: false
Pull gem RBI annotations from remote sources
```
<!-- END_HELP_COMMAND_ANNOTATIONS -->
@@ -465,36 +475,36 @@
Usage:
tapioca dsl [constant...]
Options:
- --out, -o, [--outdir=directory] # The output directory for generated DSL RBI files
- # Default: sorbet/rbi/dsl
- [--file-header], [--no-file-header] # Add a "This file is generated" header on top of each generated RBI file
- # Default: true
- [--only=compiler [compiler ...]] # Only run supplied DSL compiler(s)
- [--exclude=compiler [compiler ...]] # Exclude supplied DSL compiler(s)
- [--verify], [--no-verify] # Verifies RBIs are up-to-date
- # Default: false
- -q, [--quiet], [--no-quiet] # Suppresses file creation output
- # Default: false
- -w, [--workers=N] # Number of parallel workers to use when generating RBIs (default: 2)
- # Default: 2
- [--rbi-max-line-length=N] # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
- # Default: 120
- -e, [--environment=ENVIRONMENT] # The Rack/Rails environment to use when generating RBIs
- # Default: development
- -l, [--list-compilers], [--no-list-compilers] # List all loaded compilers
- # Default: false
- [--app-root=APP_ROOT] # The path to the Rails application
- # Default: .
- [--halt-upon-load-error], [--no-halt-upon-load-error] # Halt upon a load error while loading the Rails application
- # Default: true
- -c, [--config=<config file path>] # Path to the Tapioca configuration file
- # Default: sorbet/tapioca/config.yml
- -V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
- # Default: false
+ --out, -o, [--outdir=directory] # The output directory for generated DSL RBI files
+ # Default: sorbet/rbi/dsl
+ [--file-header], [--no-file-header], [--skip-file-header] # Add a "This file is generated" header on top of each generated RBI file
+ # Default: true
+ [--only=compiler [compiler ...]] # Only run supplied DSL compiler(s)
+ [--exclude=compiler [compiler ...]] # Exclude supplied DSL compiler(s)
+ [--verify], [--no-verify], [--skip-verify] # Verifies RBIs are up-to-date
+ # Default: false
+ -q, [--quiet], [--no-quiet], [--skip-quiet] # Suppresses file creation output
+ # Default: false
+ -w, [--workers=N] # Number of parallel workers to use when generating RBIs (default: 2)
+ # Default: 2
+ [--rbi-max-line-length=N] # Set the max line length of generated RBIs. Signatures longer than the max line length will be wrapped
+ # Default: 120
+ -e, [--environment=ENVIRONMENT] # The Rack/Rails environment to use when generating RBIs
+ # Default: development
+ -l, [--list-compilers], [--no-list-compilers], [--skip-list-compilers] # List all loaded compilers
+ # Default: false
+ [--app-root=APP_ROOT] # The path to the Rails application
+ # Default: .
+ [--halt-upon-load-error], [--no-halt-upon-load-error], [--skip-halt-upon-load-error] # Halt upon a load error while loading the Rails application
+ # Default: true
+ -c, [--config=<config file path>] # Path to the Tapioca configuration file
+ # Default: sorbet/tapioca/config.yml
+ -V, [--verbose], [--no-verbose], [--skip-verbose] # Verbose output for debugging purposes
+ # Default: false
Generate RBIs for dynamic methods
```
<!-- END_HELP_COMMAND_DSL -->
@@ -519,10 +529,22 @@
- sorbet/rbi/dsl/my_model.rbi
```
This option can be used on CI to make sure the RBI files are always up-to-date and ensure accurate type checking.
+If you are using Rails, you can configure `tapioca dsl` to run after each migration:
+
+```ruby
+# Rakefile
+if Rails.env.development?
+ namespace :db do
+ task :migrate do # Appends to the existing `db:migrate` task
+ system("bundle exec tapioca dsl", exception: true)
+ end
+ end
+```
+
#### Writing custom DSL compilers
It is possible to create your own compilers for DSLs not supported by Tapioca out of the box.
Let's take for example this `Encryptable` module that uses the [`included` hook](https://ruby-doc.org/core-3.1.1/Module.html#method-i-included) to dynamically add a few methods to the classes that include it:
@@ -838,26 +860,26 @@
Usage:
tapioca check-shims
Options:
- [--gem-rbi-dir=GEM_RBI_DIR] # Path to gem RBIs
- # Default: sorbet/rbi/gems
- [--dsl-rbi-dir=DSL_RBI_DIR] # Path to DSL RBIs
- # Default: sorbet/rbi/dsl
- [--shim-rbi-dir=SHIM_RBI_DIR] # Path to shim RBIs
- # Default: sorbet/rbi/shims
- [--annotations-rbi-dir=ANNOTATIONS_RBI_DIR] # Path to annotations RBIs
- # Default: sorbet/rbi/annotations
- [--todo-rbi-file=TODO_RBI_FILE] # Path to the generated todo RBI file
- # Default: sorbet/rbi/todo.rbi
- [--payload], [--no-payload] # Check shims against Sorbet's payload
- # Default: true
- -w, [--workers=N] # Number of parallel workers (default: auto)
- -c, [--config=<config file path>] # Path to the Tapioca configuration file
- # Default: sorbet/tapioca/config.yml
- -V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
- # Default: false
+ [--gem-rbi-dir=GEM_RBI_DIR] # Path to gem RBIs
+ # Default: sorbet/rbi/gems
+ [--dsl-rbi-dir=DSL_RBI_DIR] # Path to DSL RBIs
+ # Default: sorbet/rbi/dsl
+ [--shim-rbi-dir=SHIM_RBI_DIR] # Path to shim RBIs
+ # Default: sorbet/rbi/shims
+ [--annotations-rbi-dir=ANNOTATIONS_RBI_DIR] # Path to annotations RBIs
+ # Default: sorbet/rbi/annotations
+ [--todo-rbi-file=TODO_RBI_FILE] # Path to the generated todo RBI file
+ # Default: sorbet/rbi/todo.rbi
+ [--payload], [--no-payload], [--skip-payload] # Check shims against Sorbet's payload
+ # Default: true
+ -w, [--workers=N] # Number of parallel workers (default: auto)
+ -c, [--config=<config file path>] # Path to the Tapioca configuration file
+ # Default: sorbet/tapioca/config.yml
+ -V, [--verbose], [--no-verbose], [--skip-verbose] # Verbose output for debugging purposes
+ # Default: false
Check duplicated definitions in shim RBIs
```
<!-- END_HELP_COMMAND_CHECK_SHIMS -->