Skip to content

Latest commit

 

History

History
192 lines (132 loc) · 6.27 KB

adopting.md

File metadata and controls

192 lines (132 loc) · 6.27 KB
id title sidebar_label
adopting
Adopting Sorbet in an Existing Codebase
Adopting Sorbet

Step 1: Install dependencies

There are two components to Sorbet: the command line interface and runtime systems. We'll declare them in our Gemfile and install them with Bundler:

# -- Gemfile --

gem 'sorbet', :group => :development
gem 'sorbet-runtime'
❯ bundle install

This should install cleanly in most Ruby development environments, but see "What platforms does Sorbet support?" in the FAQ for some important caveats.

Verify installation

To test that everything is working so far, we can run these commands:

❯ bundle exec srb
[help output]

❯ bundle exec srb typecheck -e 'puts "Hello, world!"'
No errors! Great job.

❯ bundle exec ruby -e 'puts(require "sorbet-runtime")'
true

Step 2: Initialize Sorbet in our project

For small projects, Sorbet can run on a single file with no additional information. But for projects that have multiple files and depend on other gems, Sorbet needs to know more information to work.

To initialize Sorbet in an existing project, run:

❯ srb init

It's normal for this command to spew a bunch of output to the terminal. When it's done, there should be a sorbet/ folder in the current directory. Be sure to check the entire folder into version control.

Verify initialization

The contents of the sorbet/ folder should now look like this:

sorbet/
├── config
└── rbi/
    └── ···

  • sorbet/config is the config file Sorbet will read (see Command Line Reference)

  • sorbet/rbi/ is a folder containing RBI files. RBI files (or "Ruby Interface" files) declare classes, modules, constants, and methods to Sorbet that it can't see on its own.

    srb init creates many kinds of RBI files. For more information, see RBI files.

If these two items exist, we're all set to typecheck our project for the first time.

Step 3: Run srb tc for the first time

Now that we've initialized Sorbet, type checking Sorbet should be as simple as:

❯ srb tc

By default, this will type check every Ruby file in the current folder. To configure this, see Command Line Reference.

Step 4: Fix constant resolution errors

At this point, it's likely that there are lots of errors in our project, but Sorbet silences them by default. Our next job is to unsilence them and then fix the root causes. Empirically, there are a handful of categories of errors people encounter at this step:

  1. Parse errors

    Sorbet requires that all files parse as valid Ruby syntax.

  2. Dynamic constant references

    Sorbet does not support resolving constants through expressions. For example, foo.bar::A is not supported---all constants must be resolvable without knowing what type an expression has. In most cases, it's possible to rewrite this code to use method calls (like, foo.bar.get_A).

  3. Dynamic includes

    Sorbet cannot statically analyze a codebase that dynamically includes code. For example, code like this is impossible to statically analyze.

    Dynamic includes must be rewritten so that all includes are constant literals.

  4. Missing constants

    For Sorbet to be effective, it has to know about every class, module, and constant that's defined in a codebase, including all gems. Constants are central to understanding the inheritance hierarchy and thus knowing which types can be used in place of which other types.

To solve points (3) and (4), Sorbet uses RBI files. We mentioned RBI files before when we introduced srb init. RBI files are purely annotations files, separate from Ruby source code. While srb init can automatically create these files, it's not a perfect process. To eliminate constant errors, sometimes Sorbet requires hand-written RBI files.

To learn more about RBI files and how they can help with adopting Sorbet, see the docs here.

Step 5: Enable type checking

At this step, running srb tc should show zero errors.

Congrats! Step 4 was the biggest hurdle to adopting Sorbet. To recap, Sorbet now enforces that...

  • all Ruby files parse.

  • every class, module, and constant in a codebase is known. These can be 100% accurately shown in auto-complete suggestions and used in type annotations.

  • all gems have explicit interfaces. More than YARD documentation, RBI files are machine-checked documentation about the libraries we're using.

Importantly, Sorbet does not yet report type errors (the errors we've seen so far have been syntax errors and constant resolution errors). The final step is to start enabling more type checks in our code.

The rest of this site is dedicated to learning about the extra checks we can enable. The tl;dr is that type checking happens when we add # typed: true to files and write method signatures in those files.

Step 6: Source Control

All files generated by srb init should be committed to source control, including the entire sorbet directory. For more information, see this note about vendoring RBIs.

What next?

  • Enable Static Checks

    At this point, Sorbet is currently silencing all type-related errors, and only knows about the types coming from the standard library. Adding type annotations lets Sorbet find more bugs in our code and provide better completion results.

  • Enable Runtime Checks

    Sorbet relies heavily on runtime type checks to back up the predictions made statically about a codebase. Learn why these checks are necessary, and how to enable them.

  • Signatures

    Sorbet requires some type annotations in order to work. The most common kind of annotations are method signatures, or sigs.