Let’s set up a Ballerina development environment and write a simple Ballerina program.
Install Ballerina
Download and install Ballerina based on your operating system.
Tip: For more information, see Installation options.
Set up the editor
Set up a text editor to write Ballerina code.
Tip: Preferably, Visual Studio Code with the Ballerina VS Code extension installed. For more information about the features of this extension, check Ballerina VS Code extension documentation.
Meet bal
bal
is the Ballerina build tool and package manager. Among other things, it helps you create, build, test, and run your package. The latest version of the bal
tool is included with the latest Ballerina installation.
Open your terminal, and run the following commands to verify that everything is ready.
$ bal
$ bal version
Let's create a Ballerina program that prints Hello, World!
.
Create a new package
Use the bal new
command to create a new Ballerina package, which is the primary unit for organizing and managing Ballerina code.
Info: For more information about packages, see Organize Ballerina code.
$ bal new greeter
This command creates a new directory named greeter
with the following content:
greeter/ ├── Ballerina.toml └── main.bal
- The
Ballerina.toml
file contains metadata that describes your package. Thebal
tool also uses theBallerina.toml
file to identify the root of a package. - The
main.bal
file is a source file and it contains the Ballerina code that printsHello, World!
to the console. You can add any number of source files in thegreeter
directory.
Say Hello, World!
Open the package directory in your text editor. If you are using VS Code, you could navigate to the greeter
directory and run code .
to open the directory in VS Code.
Then, open the main.bal
file to see the generated source.
import ballerina/io; public function main() { io:println("Hello, World!"); }
In this code:
- The first line is an import statement, which makes the functionality in the
ballerina/io
module available to your program. This module contains functions to write to the console, read from the console, and perform read/write operations on files. - The
main
function is your program's entry point, and you can execute it by running the program. - The
main
function contains a statement that printsHello, World!
to the console. This statement calls theprintln
function in theio
module with"Hello, World!"
as an argument.
Info: To learn more about the basics of the language, see Language basics.
Run the package
Run bal run
in your terminal to run this package.
$ bal run Compiling source example/greeter:0.1.0 Running executable Hello, World!
Alternatively, you can generate an executable file with bal build
,
$ bal build Compiling source example/greeter:0.1.0 Generating executable target/bin/greeter.jar
and run it using bal run
.
$ bal run target/bin/greeter.jar Hello, World!
Write a simple REST API
Now, let's change the greeter
application into a REST API. Ballerina has first-class abstractions for services, resources, etc., and they make network service development easier and more fun.
Replace the contents of the main.bal
file with the following code:
import ballerina/http; listener http:Listener httpListener = new (8080); service / on httpListener { resource function get greeting() returns string { return "Hello, World!"; } resource function get greeting/[string name]() returns string { return "Hello " + name; } }
Let's take a moment to understand the new constructs in this code:
- The
http
module provides high-level abstractions to work with the HTTP protocol. - The listener declaration creates a new HTTP listener that will listen on port
8080
. Thelistener
is the entity that receives network input and routes it to the attached service(s). - The service declaration specifies the listener to which the service gets attached and a collection of remotely accessible methods. There are two kinds of methods:
resource
methods andremote
methods. Services useremote
methods to expose services in a procedural style and are named using verbs, whereasresource
methods are used for data-oriented protocols and are named using nouns. - In this example, there are two
resource
methods: the first one responds to HTTP GET requests with the/greeting
path, and the other one responds toGET
requests with the/greeting/{name}
path. - These
resource
methods return astring
value, which maps to thetext/plain
content-type in the HTTP response.
Info: To learn more about services, see Network interaction.
Run the simple REST API
Let's run this package in your terminal:
$ bal run Compiling source example/greeter:0.1.0 Running executable
Now, open another terminal window and run the following commands to invoke the REST API.
$ curl localhost:8080/greeting Hello, World! $ curl localhost:8080/greeting/Ballerina Hello Ballerina
Alternatively, you can use the built-in Try it
feature by clicking on the Try it
CodeLens above the service declaration on VS Code.
Learn more
In this guide, you set up your development environment and wrote two Ballerina programs. For more learning resources, see Learn.