Update Tool

This guide explains how to maintain your Ballerina installation up to date with the latest patch and minor releases.

Understand Ballerina distributions

The Ballerina compiler is a software program, which validates the Ballerina source code and translates it to an executable program. Ballerina has a stable and production-ready official compiler called jBallerina, which targets the JVM.

Also, there is a plan to develop a native compiler called nBallerina in the future, which will target platforms such as Linux, Windows, and macOS.

Ballerina distribution is a term, which refers to these jBallerina and nBallerina compilers.

Get to know the release channels

Ballerina distributions are released via two different release channels at the moment. Swan Lake release channel is the primary release channel and the other one is the 1.x release channel. It is recommended to use Swan Lake release channel, if you are new to Ballerina.

Ballerina does not have a release channel yet for nightly builds that give you access to the latest perhaps unstable features.

Patch releases

Patch releases of Ballerina distributions contain bug fixes and fixes for critical stability and security related issues. Occasionally, you would see on-demand patch releases for 2201.0.x.

Example patch releases: 2201.0.1, 2201.1.1

Use the update tool

If you haven’t installed Ballerina yet, see Install Ballerina for the instructions.

Once the installation is complete, you would see the following directory structure inside the installation directory.

The distributions is the directory, in which all your installed distributions are maintained. Only one distribution from the above list can be active at a given time.

Note: The Ballerina Tool delegates most of the user requests to the active distribution. The commands such as build, test, run, pull, and push are delegated to the active distribution, while the commands such as dist and version are handled by the tool itself.

E.g., when you invoke bal build, the Ballerina Tool dispatches this request to the active distribution.

You can change this active distribution at any time or manage it using the Ballerina Tool. However, first, you need to update the Ballerina Tool to its latest version.

Update the Ballerina tool

The bal update command updates the Ballerina Tool itself to the latest version. Ballerina Tool versions are independent of the Ballerina distribution versions. These tool updates are expected to be rare compared to distribution releases.

Manage your Ballerina distributions

After updating the Ballerina Tool, you can use the bal dist command to manage Ballerina distributions. The bal help dist output below shows all the details about the bal dist command.

Most of these subcommands are self-explanatory. Therefore, the sections below introduce them briefly.

List all local and remote distributions

The bal dist list command lists the installed distributions in your local environment. It also lists the distributions available for you to download.

Note: The star (*) indicates the active distribution.

Remove a distribution

The bal dist remove <distribution> command allows you to delete a particular distribution from your local environment. If you have been updating Ballerina regularly, you may have accumulated many unused distribution versions. This command helps you to clean them up.

Update to the latest preview/patch version

The bal dist update command updates your active distribution to the latest patch version.

Note: If the active distribution in your environment is slp4, it bumps to the next Swan Lake Preview version, which is slp5, and updates to it.

Pull a specific distribution

The bal dist pull <distribution> command downloads a particular distribution and stores it in your local environment. It also sets the fetched distribution as the active distribution.

Change the active distribution

The bal dist use <distribution> command sets a particular distribution version as the active one.