The majority of the code in Homebrew is written in Ruby which is a dynamic language. To avail the benefits of static type checking, we have set up Sorbet in our codebase which provides the benefits of static type checking to dynamic languages like Ruby.
The Sorbet Documentation is a good place to get started if you want to dive deeper into Sorbet and it’s abilities.
To add type annotations to a class or module, we need to first extend it with
the T::Sig
module (read this as Type::Signature
). This adds the sig
method which is used to annotate method signatures. Here’s a simple example:
class MyClass
extend T::Sig
sig { params(name: String).returns(String) }
def my_method(name)
"Hello, #{name}!"
end
end
With params
, we specify that we have a parameter name
which must be a
String
and with returns
, we specify that this method always returns
a String
.
For more information on how to express more complex types, refer to the official documentation:
.rbi
)RBI files help Sorbet learn about constants, ancestors and methods defined in ways it doesn’t understand natively. We can also create a RBI file to help Sorbet understand dynamic definitions.
Sometimes it is necessary to explicitly include the Kernel
module in
order for Sorbet to know that methods such as puts
are available in
a given context. This is mostly necessary for modules since they can
be used in both BasicObject
s (which don’t include Kernel
) and
Object
s (which include Kernel
by default). In this case, it is
necessary to create an .rbi
file (example) since re-including the
Kernel
module in actual code can break things.
Read more about RBI files here.
Library/Homebrew/sorbet
DirectoryThe rbi
directory contains all Ruby Interface (.rbi
) files
auto-generated by running brew typecheck --update
:
srb rbi hidden-definitions
.srb rbi todo
.The config
file is a newline-separated list of arguments to pass to
srb tc
, the same as if they’d been passed at the command-line. Arguments
in the config file are always passed first, followed by arguments provided
on the command-line. We use it to ignore Gem directories which we do not
wish to type check.
Every Ruby file in the codebase has a magic # typed: <level>
comment at the
top, where <level>
is one of Sorbet’s strictness levels, usually false
,
true
or strict
. The false
files only report errors related to the
syntax, constant resolution and correctness of the method signatures, but no
type errors. Our long-term goal is to move all false
files to true
and
start reporting type errors on those files as well. Therefore, when adding
new files, you should ideally mark it with # typed: true
and work out any
resulting type errors.
brew typecheck
When run without any arguments, brew typecheck
, will run considering the strictness levels
set in each of the individual Ruby files in the core Homebrew codebase. However, when
it is run on a specific file or directory, more errors may show up since Sorbet
cannot resolve constants defined outside the scope of the specified file. These
problems can be solved with RBI files. Currently brew typecheck
provides --quiet
, --file
,
--dir
and --ignore
options but you can explore more options with srb tc --help
and
passing them with srb tc
.
Sorbet reports type errors along with an error reference code, which can be used to look up more information on how to debug the error, or what causes the error in the Sorbet Documentation. Here is how to debug some common type errors:
Using T.reveal_type
. In files which are true
or higher, if we wrap a variable
or method call in T.reveal_type
, Sorbet will show us what type it thinks that
variable has in the output of srb tc
. This is particularly useful when writing
method signatures and debugging. Make sure to
remove this line from your code before committing your changes, since this is
just a debugging tool.
One of the most frequent errors that we’ve encountered is: 7003: Method does not exist.
Since Ruby is a very dynamic language, methods can be defined in ways Sorbet cannot
see statically. In such cases, check if the method exists at runtime, if not, then
Sorbet has caught a future bug! But, it is also possible that even though a method
exists at runtime, Sorbet cannot see it. In such cases, we use
.rbi
files.
Since Sorbet does not automatically assume that Kernel is to be included in Modules,
we may encounter many errors while trying to use methods like puts
, ohai
, odebug
et cetera.
A simple workaround for this would be to add an extra include Kernel
line in the
respective RBI file.
The tips above are very generic and apply to lots of cases. For some common gotchas when using Sorbet, refer to the Sorbet Error Reference and FAQ.