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.
1 | ballerina new [PROJECT-NAME] |
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.
1 2 3 | C:\USERS\KARLDEV\DESKTOP\BALLERINA └───myproject └───src |
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.
1 | ballerina add [MODULE-NAME] |
Consider the following sample usage.
1 2 | C:\Users\karldev\Desktop\ballerina\myproject>ballerina add mymodule Added new ballerina module at 'src\mymodule' |
The command creates a mymodule subdirectory within the src directory.
1 2 3 4 5 6 7 8 9 10 | C:\Users\karldev\Desktop\ballerina\myproject\src>tree Folder PATH listing for volume Windows Volume serial number is 14A2-F668 C:. └───mymodule ├───resources └───tests └───resources C:\Users\karldev\Desktop\ballerina\myproject\src> |
The module will also have the following files.
1 2 3 4 5 6 7 8 9 | C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\main.bal C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\Module.md C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\resources C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\tests C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\resources\.keep C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\tests\main_test.bal C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\tests\resources C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\tests\resources\.keep |
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.
1 | ballerina build [<ballerina-file> | <module-name> | -a | --all] |
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | C:\Users\karldev\Desktop\ballerina\myproject>ballerina build mymodule Compiling source karldev/mymodule:0.1.0 Creating balos target\balo\mymodule-2020r1-any-0.1.0.balo Running Tests karldev/mymodule:0.1.0 I'm the before suite function! I'm the before function! I'm in test function! I'm the after function! I'm the after suite function! [pass] testFunction 1 passing 0 failing 0 skipped Generating executables target\bin\mymodule.jar C:\Users\karldev\Desktop\ballerina\myproject> |
Running a Ballerina Project
There a few options for running a Ballerina project using the CLI tools, consider the following command.
1 | ballerina run [<bal-file> | <module-name> | <executable-jar>] |
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.
1 2 3 4 5 6 7 8 9 10 11 | C:\Users\karldev\Desktop\ballerina\myproject>ballerina run mymodule Compiling source karldev/mymodule:0.1.0 Creating balos target\balo\mymodule-2020r1-any-0.1.0.balo target\bin\mymodule.jar Running executables Hello World! |
For running a jar file, we need to build first the file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | C:\Users\karldev\Desktop\ballerina\myproject>ballerina build --all Compiling source karldev/mymodule:0.1.0 Creating balos target\balo\mymodule-2020r1-any-0.1.0.balo Running Tests karldev/mymodule:0.1.0 I'm the before suite function! I'm the before function! I'm in test function! I'm the after function! I'm the after suite function! [pass] testFunction 1 passing 0 failing 0 skipped Generating executables target\bin\mymodule.jar C:\Users\karldev\Desktop\ballerina\myproject>ballerina run target/bin/mymodule.jar Hello World! C:\Users\karldev\Desktop\ballerina\myproject> |
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.
1 | ballerina test <module-name> | -a | --all |
Consider the following sample usage.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | C:\Users\karldev\Desktop\ballerina\myproject>ballerina test mymodule Compiling source karldev/mymodule:0.1.0 Creating balos target\balo\mymodule-2020r1-any-0.1.0.balo Running Tests karldev/mymodule:0.1.0 I'm the before suite function! I'm the before function! I'm in test function! I'm the after function! I'm the after suite function! [pass] testFunction 1 passing 0 failing 0 skipped |
Generate Ballerina API Documentation
Consider the following usage sample in generating Ballerina API documentation.
1 2 3 4 5 6 7 8 9 10 11 12 | C:\Users\karldev\Desktop\ballerina\myproject>ballerina doc ballerina: 'doc' command requires a module name. use '-a' or '--all' flag to generate api documentation for all the modules of the project. USAGE: ballerina doc {<module-name> | -a | --all} C:\Users\karldev\Desktop\ballerina\myproject>ballerina doc mymodule Compiling source karldev/mymodule:0.1.0 Generating API Documentation target\apidocs |
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.
1 | ballerina clean |
Format Ballerina Codes
The Ballerina CLI tools allow us to format all the codes within a project. Consider the following usage.
1 2 3 4 5 | C:\Users\karldev\Desktop\ballerina\myproject\src\mymodule\main.bal format successful. C:\Users\karldev\Desktop\ballerina\myproject> |
The command formats the following codes
1 2 3 4 5 6 7 8 | import ballerina/io; # Prints `Hello World`. public function main() { io:println("Hello World!"); } |
to
1 2 3 4 5 6 7 8 | import ballerina/io; # Prints `Hello World`. public function main() { io:println("Hello World!"); } |
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.
1 | ballerina pull wso2/jms |
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.
1 | ballerina pull wso2/jms:0.7.0 |
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.
1 | ballerina push mymodule |
The module will be available in our Ballerina Central account.
From here on, other developers can pull our module using the following command.
1 | ballerina pull karldev/mymodule |
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.
1 | ballerina search [keyword] |
This is part of the Ballerina Programming Language Tutorial.
