Building from Source

The sections below will guide you to build either the complete Ballerina distribution or the basic Ballerina runtime build as preferred.

Overview

Building the complete Ballerina distribution provides you access to all the main features of Ballerina such as the runtime, corresponding tools, standard library modules etc.

Info: However, if you need just a plain Ballerina language build with only the basic language features and the JBallerina Java (Java Introp) API in it, you can build only the Ballerina Runtime with the tools

Setting up the Prerequisites

Follow the steps below to set up the prerequisites.

  1. Download and set up OpenJDK 11 (Adopt OpenJDK or any other OpenJDK distribution).

    Info: You can also use Oracle JDK.

  2. Set up a Personal Access Token for your GitHub account and configure the following environment variables (the access token should have the read package permission).

    For Unix/macOS:

     export packageUser="<YOUR_GITHUB_USERNAME>";
     export packagePAT="<YOUR_PERSONAL_ACCESS_TOKEN>";
    

    For Windows:

     set packageUser=<YOUR_GITHUB_USERNAME>
     set packagePAT=<YOUR_PERSONAL_ACCESS_TOKEN>
    

Building the Complete Ballerina Distribution

Follow the steps below to build the ballerina-distribution repository to get full access to the complete Ballerina distribution.

  1. Fork the ballerina-distribution repository to your GitHub account and execute following command to clone it.

     git clone --recursive https://github.com/<GITHUB_USERNAME>/ballerina-distribution.git
    
  2. Navigate to the <BALLERINA_DISTRIBUTION_PROJECT> directory, and execute the command below to start the build (here, the tests are excluded to speed up the build).

    For Unix/macOS:

     ./gradlew clean build -x test
    

    For Windows:

     gradlew clean build -x test
    
  3. Extract the built Ballerina Language distribution (i.e., the <BALLERINA_DISTRIBUTION_PROJECT>/ballerina/build/distributions/ballerina-<VERSION>.zip file) to a preferred location.

  4. Configure the environment variables below.

    For Unix/macOS:

     # Set up the `BALLERINA_HOME` environment variable.
     export BALLERINA_HOME="<YOUR_LOCATION>/ballerina-<VERSION>";
    
     # Include the binaries to the system `PATH`.
     PATH=$BALLERINA_HOME/bin:$PATH;
     export PATH;
    

    For Windows:

     # Set up the `BALLERINA_HOME` environment variable.
     set BALLERINA_HOME="<YOUR_LOCATION>\ballerina-<VERSION>";
    
     # Include the binaries to the system `PATH`.
     set PATH=%PATH%;%BALLERINA_HOME%\bin;
    

Testing the Distribution Build

Since this is a complete Ballerina distribution build, this will have all the Standard Library module dependencies included in it.

Therefore, follow the steps below to write a simple program using the Ballerina io module to test the distribution build.

  1. Create a hello_world_with_io.bal file with the code below.

     import ballerina/io;
    
     // ballerina hello world program
     public function main() {
           io:println("Hello, World with IO!");
     }
    
  2. Execute the command below to build and run this program.

     bal run hello_world_with_io.bal
    

    If your build is successful, you view the output below.

     Hello, World with IO!
    

Building Only the Ballerina Runtime with the Tools

Follow the steps below to build just the Ballerina runtime with the corresponding tools.

  1. Fork the ballerina-lang repository to your GitHub account and execute following command to clone it.

     git clone --recursive https://github.com/<GITHUB_USERNAME>/ballerina-lang.git
    
  2. Navigate to the <BALLERINA_LANG_PROJECT> directory, and execute the command below to update the Git submodules.

     git submodule update --init
    
  3. Execute one of the commands below to start the build process.

    For Unix/macOS:

     ./gradlew clean build
    

    For Windows:

     gradlew clean build
    
  4. Extract the built Ballerina Language distribution (i.e., the <BALLERINA_LANG_PROJECT>/distribution/zip/jballerina-tools/build/distributions/jballerina-tools-<VERSION>.zip file) to a preferred location.

  5. Configure the environment variables below.

    For Unix/macOS:

     # Set up the `BALLERINA_HOME` environment variable.
     export BALLERINA_HOME="<YOUR_LOCATION>/jballerina-tools-<VERSION>";
    
     # Include the binaries to the system `PATH`.
     PATH=$BALLERINA_HOME/bin:$PATH;
     export PATH;
    

    For Windows:

     # Set up the `BALLERINA_HOME` environment variable.
     set BALLERINA_HOME="<YOUR_LOCATION>\jballerina-tools-<VERSION>";
    
     # Include the binaries to the system `PATH`.
     set PATH=%PATH%;%BALLERINA_HOME%\bin;
    

Testing the Runtime Build

Since this runtime build is just a plain Ballerina language build, you only have the basic language features and JBallerina Java (Java Introp) API in it.

Therefore, follow the steps below to write a basic Ballerina program using only those functionalities to test the runtime build.

  1. Create a hello_world.bal file with the code below.

     import ballerina/jballerina.java;
    
     public function main(string... args) {
         var systemOut = out();
         println(systemOut, java:fromString("Hello, World!"));
     }
    
     // Retrieves the current System output stream
     public function out() returns handle = @java:FieldGet {
         name: "out",
         'class: "java.lang.System"
     } external;
    
     // Calls `println` method of the  `PrintStream`
     function println(handle receiver, handle message) = @java:Method {
         paramTypes: ["java.lang.String"],
         'class: "java.io.PrintStream"
     } external;
    
  2. Execute the command below to build and run this program.

     bal run hello_world.bal
    

    If your build is successful, you view the output below.

     Hello, World!