Sorbet
This repository contains Sorbet, a fast, powerful type checker designed for Ruby.
It aims to be easy to add to existing codebases with gradual types, and fast to
respond with errors and suggestions.
This README contains documentation specifically for contributing to Sorbet. You
might also want to:
If you are at Stripe, you might also want to see http://go/types/internals for
docs about Stripe-specific development workflows and historical Stripe context.
Table of Contents
Sorbet user-facing design principles
Early in our project, we've defined some guidelines for how working with Sorbet should feel like.
-
Explicit
We're willing to write annotations, and in fact see them as
beneficial; they make code more readable and predictable. We're here
to help readers as much as writers.
-
Feel useful, not burdensome
While it is explicit, we are putting effort into making it concise.
This shows in multiple ways:
- error messages should be clear
- verbosity should be compensated with more safety
-
As simple as possible, but powerful enough
Overall, we are not strong believers in super-complex type
systems. They have their place, and we need a fair amount of
expressive power to model (enough) real Ruby code, but all else
being equal we want to be simpler. We believe that such a system
scales better, and—most importantly—is easier for our users to
learn & understand.
-
Compatible with Ruby
In particular, we don't want a new syntax. Existing Ruby syntax means
we can leverage most of our existing tooling (editors, etc). Also,
the point of Sorbet is to gradually improve an existing Ruby codebase. No
new syntax makes it easier to be compatible with existing tools.
-
Scales
On all axes: execution speed, number of collaborators, lines of code,
codebase age. We work in large Ruby codebases, and they will only get
larger.
-
Can be adopted gradually
In order to make adoption possible at scale, we cannot require every team or
project to adopt Sorbet all at once. Sorbet needs to support teams adopting
it at different paces.
Quickstart
-
Install the dependencies
brew install bazel autoconf coreutils parallel
-
Clone this repository
git clone https://github.com/sorbet/sorbet.gitcd sorbet
-
Build Sorbet
./bazel build //main:sorbet --config=dbg
-
Run Sorbet!
bazel-bin/main/sorbet -e "42 + 'hello'"
Learning how Sorbet works
We've documented the internals of Sorbet in a separate doc.
Cross-reference between that doc and here to learn how Sorbet works and how to
change it!
→ internals.md
There is also a talk online that describes Sorbet's high-level architecture and
the reasons why it's fast:
→ Fast type checking for Ruby
Building Sorbet
There are multiple ways to build sorbet. This one is the most common:
./bazel build //main:sorbet --config=dbg
This will build an executable in bazel-bin/main/sorbet (see "Running Sorbet"
below). There are many options you can pass when building sorbet:
--config=dbg
- Most common build config for development.
- Good stack traces, runs all ENFORCEs.
--config=dev
- Like
--config=dbg, but with light optimizations (-O1).
- Several times faster, at the cost of some variables being optimized out
in a debugger.
--config=sanitize
- Link in extra sanitizers, in particular: UBSan and ASan.
- Catches most memory and undefined-behavior errors.
- Substantially larger and slower binary.
--config=debugsymbols
- (Included by
--config=dbg) debugging symbols, and nothing else.
--config=forcedebug
- Use more memory, but report even more sanity checks.
--config=static-libs
- Forcibly use static linking (Sorbet defaults to dynamic linking for faster
build times).
- Sorbet already uses this option in release builds (see below).
--config=release-mac and --config=release-linux
- Exact release configuration that we ship to our users.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
