Ballerina, Software Development

Work on Ballerina Projects Using CLI Tools

Ballerina is a new programming language that shows a lot of promise, especially for microservice and cloud-based development. It is a general-purpose programming language for distributed applications. Since it is relatively new, many IDEs are yet to fully support it with advanced features. Ballerina comes with a CLI tool that has enough features to help developers start working with Ballerina projects. This post shows how we can use Ballerina CLI tools for working on projects.

Java Development Kit 8 And Balerina

Before we proceed, we need a Java runtime and a Ballerina distribution on our machine. We will install them using zip distributions only. Please see Run Ballerina On Command-Line Without Installing Java.

Create a Ballerina Project

In most situations, we do not create new Ballerina projects. The projects already exist and we only need to enhance them. In case we are starting a new Ballerina project, we can create it in the command-line window using the following command.

Below is an example of usage.

When we run the sample command, it creates a subdirectory myproject (and its empty subfolder src), Ballerina.toml, and .gitignore files.

Create A Ballerina Module In An Existing Project

Breaking down an application into modules is one of the best practices in Software Development. As a result, we make the application easier to maintain. We can create Ballerina modules in the command-line using the following command. Note – we must be inside the project’s root directory.

Consider the following sample usage.

The command creates a mymodule subdirectory within the src directory.

The module will also have the following files.

Building A Ballerina Project

Once we have our project, module, and Ballerina codes, we can build them in the command line using the following command.

There are three options for the build command; we can build a single file, a specific module, or all. If we want to build a single source file, we refer to a .bal  file using the <ballerina-file> option. If we’re going to build a specific module, we specify the module name. On the other hand, we can build all the codes within the Ballerina project using the -a or --all option flag.

The following is a sample usage of building a specific module. Since we only have one module, using the -a  or --all option flag yields the same console output.

Running a Ballerina Project

There a few options for running a Ballerina project using the CLI tools, consider the following command.

The command allows us to run a single Ballerina file, a Ballerina module, or a jar file. Consider the following usage for running a module.

For running a jar file, we need to build first the file.

Note that Ballerina, by default, creates the jar file in the target/bin directory.

Run Ballerina Unit Tests

To run all the tests in the whole project or a module, use the following command.

Consider the following sample usage.

Generate Ballerina API Documentation

Consider the following usage sample in generating Ballerina API documentation.

The command creates an apidocs directory in the target directory.

When we open the index.html file, get the following sample view.

Clean Ballerina Artifacts

When we want to keep only the source code and configuration files, we can use the clean command. It will delete the target directory and all its content.

Format Ballerina Codes

The Ballerina CLI tools allow us to format all the codes within a project. Consider the following usage.

The command formats the following codes


Work With Ballerina Central Using CLI Tools

The Ballerina Central is an online repository of open-source Ballerina modules that we can use in our Ballerina projects. It is akin to Maven Repository for Java or npm Registry for NodeJS.

Pull A Ballerina Module From Ballerina Central

Suppose we want to pull the wso2/jms module, we can use the following command.

We get the following output.

The command pulls the module and places it in the .ballerina local directory, e.g., C:\Users\karldev\.ballerina\balo_cache.

We can also specify the module version.

Push Ballerina Module To Ballerina Central

Pushing our Ballerina module to Ballerina Central requires that we have an account from which we get access tokens. Go to Ballerina Central and sign up. Once in, copy our Ballerina access token from the dashboard.

Then, create a Settings.toml and paste the access token as follows.

Next, we need to ensure we have the organization name in our Ballerina Central account, as specified in our Ballerina.toml file.

Finally, we can now push our module using the following command.

The module will be available in our Ballerina Central account.

From here on, other developers can pull our module using the following command.

After running the command, our module becomes in the .ballerina folder.

Search For Modules In Ballerina Central

We can also search for modules in Ballerina Central using the following command.

This is part of the Ballerina Programming Language Tutorial.

Got comments, or suggestions? Please visit our Facebook page!

You Might Also Like