Introducing Rebar3 TypEr
Do you have an Erlang codebase that’s a little short on type specs? Maybe you know TypEr exists, but wouldn’t it be nice to:
- incorporate it into your build system?
- configure it only once?
- have it ✨ magically✨ figure out all the command line arguments for you?
We built that! It’s called
rebar3_typer, and it (as the name implies) plugs into rebar3. With that rebar3 integration comes understanding the rest of your configuration. It’s available on hex.pm.
One of the first things we had to do was refactor the original upstream TypEr a bit. TypEr was always intended to be run from the command line. It didn’t have (or need) an API available from within the BEAM. Well, until now. We needed that. So, we split out a “core” module and sent that upstream. That’ll be in OTP 25.
We have to thank Viacheslav Katsuba for his rebar3_plugin template. It was very helpful for getting us a framework to start from so we could dive in. And of course, thanks to Kostis Sagonas for all his work on Dialyzer and TypEr.
How to use rebar3_typer
For a quick up-and-running, just add this to your
rebar.config (either in your project or globally in
Without further configuration, it will:
- look for source files in the usual places
- look for source files wherever they’ve been configured in
rebar.configfor the project in general
- look for Dialyzer’s PLT file in the usual place
- look for Dialyzer’s PLT file wherever it’s been configured in
rebar.configfor the project in general
- emit a list of all the specs you can add to those modules, based on the types inferred by Dialyzer
Or if you want to take advantage of our enhancement that automatically annotates your source code directly for you, try:
(Yes, this new feature has been sent upstream.)
All options are available on the command line or in the
rebar.config file. The command-line options always override the options in the config file.
The basic config starts out:
Choose the files
If source file auto-detection doesn’t work for your situation, you’ll need to specify either a list of files (
-f) or a list of directories (
-r) (or both!) to be analyzed.
Provide the PLT
rebar3_typer can’t find your PLT file (and you’re sure it’s already been generated), you can give it some hints.
Show or annotate
Do you want it to only print the type specs to stdout, or do you want it to put its output in files?
If you want them printed to stdout, do you want it for all functions?
Or maybe only for exported (public) functions?
--show_exported is also accepted)
If you’d like the results to go to files, use an
annotate option instead of a
Do you want to annotate
include() files? (Warning, though: there is an open bug upstream for this feature.)
--annotate_inc_files is also accepted)
By default, annotations go into separate
.ann.erl files in a
typer_ann/ directory. Would you like it to instead put the annotations directly into your code for you? Check out
--annotate_in_place is also accepted)
By default, only functions with missing specs will be addressed, in any of these modes.
What format to use
rebar3_typer will use
-spec syntax. If you’d prefer Edoc syntax (
@spec), you can specify that:
How to handle pre-existing type specs
You have some options for what to do when it finds type specs already in place. If you have particular files with specs, and you want those specs to serve as the basis for additional type specs:
(This accepts file names or directory names. But another warning: this also has an open bug upstream.)
If you’d rather existing type specs be completely ignored:
Finally, TypEr has an option to show Dialyzer’s success typings, which is reachable through this plugin. This is undocumented upstream.
This project was part of Hack Week, the twice-yearly event where employees get to decide what we build. We learn things, try things out, and get to work with different folks than usual. You can read more about Hack Week.