Native Ballerina Interpreter

Ballerina is an open-source, cloud-native programming language optimized for integration. It has built-in support for JSON and XML, first-class constructs for services and concurrency, and structural typing. It is developed and supported by WSO2.

Try Ballerina in your browser: Ballerina Playground — run and share snippets without installing anything.

Goals

This project implements a native Ballerina interpreter in Go: compile Ballerina source to Ballerina Intermediate Representation (BIR) and interpret the BIR, with a focus on speed, low memory use, and fast startup. Development is organized by subsets of the language; each milestone adds support for a defined subset.

• Progress: GitHub Milestones
• Subset docs: doc/ (language features and restrictions per subset)

Usage

Dependencies

The project is built using the Go programming language. The following dependencies are required:

• Go 1.24 or later

Build the CLI

Production Build (default)

go build -o bal ./cli/cmd

Debug Build

go build -tags debug -o bal-debug ./cli/cmd

Using Profiling

Profiling is only available in debug builds (compiled with -tags debug).

Enable Profiling

# Default profiling port (:6060)
./bal-debug run --prof corpus/bal/subset1/01-boolean/equal1-v.bal

# Custom port
./bal-debug run --prof --prof-addr=:8080 corpus/bal/subset1/01-boolean/equal1-v.bal

Access Profiling Data

• Web UI: http://localhost:6060/debug/pprof/
• CPU Profile: http://localhost:6060/debug/pprof/profile?seconds=30
• Heap Profile: http://localhost:6060/debug/pprof/heap
• Goroutines: http://localhost:6060/debug/pprof/goroutine

Analyze with pprof Tool

# CPU profiling (30 second sample)
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Heap profiling
go tool pprof http://localhost:6060/debug/pprof/heap

# Interactive web UI
go tool pprof -http=:8081 http://localhost:6060/debug/pprof/profile?seconds=30

Using the CLI

CLI Help

./bal --help

./bal run --help

Running a bal source

Currently, the following are supported:

• Single .bal file
• Ballerina package with only the default module

E.g.

./bal run --dump-bir corpus/bal/subset1/01-boolean/equal1-v.bal
./bal run project-api-test/testdata/myproject

Testing

To run the tests, use the following command:

go test ./...

Report issues

Tip: If you are unsure whether you have found a bug, search the existing issues in the GitHub repo and open an issue if needed.

Open an issue

• Open an issue for bug reports or feature requests related to the native interpreter.

Report security issues

• Send an email to security@ballerina.io. For details, see the security policy.

Contribute to Ballerina

As an open-source project, ballerina-lang-go welcomes contributions from the community. To start contributing, read the contribution guidelines.

License

Ballerina code is distributed under Apache License 2.0.

Join the community

• Get help on Stack Overflow
• Join the conversations in Discord community.
• For more details on how to engage with the community, see Community.