Running Ballerina Code

The sections below include information on running Ballerina programs.

Understanding the Structure

A Ballerina application can have:

  1. A main() function that runs as a terminating process.

  2. A service, which is a hosted non-terminating process.

Both of these are considered as entry points for program execution.

These applications can be structured into a single program file or a Ballerina module. A collection of modules can be managed together with versioning and dependency management as part of a Ballerina package.

Source files and modules can contain zero or more entry points, and the runtime engine has precedence and sequence rules for choosing which entry point to execute.

If the source file contains at least one entry point, it can be executed using the run command.

$ bal run foo.bal

You can compile a source file with an entry point into an executable jar.

$ bal build [-o outputfilename.jar] foo.bal

You can run .jar files directly:

$ bal run filename.jar

Running a Package

A package is a folder that manages modules as part of common versioning, dependency management, build, and execution. You can build and run items collectively or individually as modules. See How To Structure Ballerina Code for in-depth structuring of packages.

Running a ballerina package:

$ bal run myFirstPackage 
$ bal run <ballerina-package-path>

Build a ballerina package:

$ bal build myFirstPackage
$ bal build <ballerina-package-path>

Alternatively you can cd into ballerina package and run:

$ bal build

Building a ballerina package will generate .jar inside target/bin/ of the package directory.

You can run the .jar file directly:

$ bal run target/bin/testPackage.jar

Options for running programs with entry points in a package:

$ bal run main.bal
$ bal run main.jar

Configuring Your Ballerina Runtimes

Ballerina Runtime Configurable Variables

A Ballerina runtime can be configured using configurable variables. The values for configurable variables can be provided through command-line parameters and configuration files. When loading the values to the configurable variables, command-line arguments get the higher precedence than the configuration TOML files.

See Configurable BBE for more details.

Consider the following example, which uses configurable variables.

import ballerina/io;

configurable int id = ?;
configurable string name = "Ann";
configurable boolean married = true;

public function main() {
  io:println("User ID : ", id);
  io:println("User Name : ", name);
  io:println("Married : ", married);
}

? denotes that id is a required configuration. Hence, the configuration must specify a value for the id key. If a default value is assigned, the configuration is optional. Hence, the configuration may or may not contain values for the name and married configurable variables.

Consider the below Config.toml file.

id = 1001
name = "Jhone"

Since the Config.toml file contains a value for the name key, the program default value will be overridden by the value in the Config.toml file.

$ bal run main.bal
User ID : 1001
User Name : Jhone
Married : true

When running a program with configurable values, Ballerina locates the TOML files in the following ways:

  • From an environment variable with the name BAL_CONFIG_FILES that provides a list of paths to the TOML files separated by the OS-specific separator. The file precedence order will be as specified in the environment variable.

  • From an environment variable with the name BAL_CONFIG_DATA that contains the content of the configuration TOML file.

  • If the above environment variables are not specified, the configuration file is located in the current directory with the file name Config.toml by default.

Currently, TOML-based configuration is supported for configurable variables of types int, float, boolean, string, decimal, the arrays of the respective types, and table.

In the example, you can set the path to the Config.toml file using the following command.

$ export BAL_CONFIG_FILES = <path>
$ bal run main.bal
User ID : 1001
User Name : Jhone
Married : true

It is possible to provide the values for configurable variables through command-line arguments in the format of -Ckey=value. The key of a command-line argument can be specified as,

key:= [[org-name .] module-name .] variable

The org-name and module-name is optional for the variable defined in the root module or in a single Ballerina file. Currently, command-line-based configuration is supported for configurable variables of types int, float, boolean, string, decimal, and xml.

In the example, you can use the following command to pass values from the command-line.

$ bal run main.bal -- -Cid=1001 -Cname=Jhone -Cmarried=true
User ID : 1001
User Name : Jhone
Married : true

Configuring Sensitive Data as Configurable Variables

You can provide sensitive data to configurable variables through a separate TOML file and specify it using BAL_CONFIG_FILES environment variable with higher priority.

For in-depth details, see Securing Sensitive Data using configurable variables.