Ballerina compiler plugin design

30,000 feet view

​

February 08, 2020

Sameera Jayasoma

What is a compiler plugin?

Ballerina compiler plugin is a collection of related tasks such as:

• Code analyzers
• Analyze code and report diagnostics
• Not allowed to generate new code or modify existing code
• Code generators
• Generate additional Ballerina source files, modules, and other files that are compiled together with the rest of user code
• Not allowed to modify existing
• We may need to certify plugins that modify user code in Central
• Code transformers
• transform user code
• macroy...
• instrumentation, wrapping code, desugaring

Distributing compiler plugins

• A compiler plugin can only be distributed with a Ballerina package.
• The ballerina/http package contains a compiler plugin that analyzes all http services in a program.
• Shared via package repositories
• e.g. Ballerina central

Applying plugins to the compilation

There are two ways to apply a plugin:

1. Make the Ballerina package that contains the plugin, a node in the dependency graph.

If ballerina/http is a dependency of the current package, then the http compiler plugin will be executed.

• Specify the plugin in the compiler plugin section in Ballerina.toml file.

[[plugin]]

name = “linter”

org = “samjs”

version = “1.1.0”

Developing a compiler plugin

• Ballerina compiler SDK offers only a Java API to a develop compiler plugin.
• We can offer a Ballerina API later.
• Package the plugin as a Java module(.jar)
• It may depend on other Java libraries
• Create the Compiler-plugin.toml file at the root of the package directory.
• Specify plugin id, description, plugin class name and the list of platform-specific libraries (.jar files).
• Run `ballerina build -c`
• This step creates a Ballerina package with the compiler plugin.