The following steps explain how to setup a development environment for LimeDS. We assume you already have the latest Java JDK installed (we recommend JDK 8u92 or newer).

Step 1: Install Eclipse

The recommended development environment for LimeDS (which relies heavily on OSGi and Bndtools) is Eclipse Neon or newer. Each LimeDS workspace is also a valid Gradle project, which can be used by developers that don't work in Eclipse.

We refer to the Eclipse website for downloading the appropriate binaries: http://www.eclipse.org/.

Step 2: Install Bndtools

LimeDS integrates with Bndtools in order to provide a streamlined experience for developing LimeDS modules, which are OSGi bundles with additional meta-data. To add Bndtools to Eclipse, perform the following actions:

1. In Eclipse, go to "Help -> Install New Software..."
2. Enter the following URL in the "Work with" search box: https://dl.bintray.com/bndtools/bndtools/latest/
3. The pane below should show an install entry for Bndtools, select it and click next.
4. Click next and follow the instructions on-screen to finish the installation.

After this, Eclipse will restart and Bndtools will be ready for use. Visit http://bndtools.org/ for more information.

Step 3: Setting up the workspace

LimeDS provides a simple Setup Manager that allows you to manage your development workspace. Download this Java executable and copy it to the folder where you want to create your workspace, then open a terminal in the folder and type:

java -jar setup.jar

We can then initialize the development workspace by entering the init-workspace command. This will download the latest templates and build files in the appropriate directories. If the operation was successful, you should see the following message in the console:

Follow these instructions to finish the initialization.

Step 4: Starting a project

LimeDS-based software is designed in a very modular way. For each new feature, a separate module should be created that can dynamically be installed on any LimeDS instance. To implement such a module, you need to create a designated project for it in your LimeDS workspace. E.g. we can create a project for a module called 'examples.hello' by entering the following command in the Setup Manager:

add-project examples.hello

If the operation was successful, you should see the following message in the console:

Follow the displayed instructions so that Eclipse and the LimeDS runtime know about the project.

We can now add our first LimeDS function, but first we need to create a Java package for it. The Setup Manager automates a number of actions for us (creating a package info file, registering the package with bnd, etc...) so we create the package using the following Setup Manager command:

add-package examples.hello.impl examples.hello

Refresh the project in Eclipse and then add the following class:

package example.hello.impl;

import org.ibcn.limeds.FunctionalSegment;
import org.ibcn.limeds.annotations.ApplySchedule;
import org.ibcn.limeds.annotations.Configurable;
import org.ibcn.limeds.annotations.Segment;
import org.ibcn.limeds.json.JsonValue;

/**
 * This example LimeDS segment is scheduled to say hello when starting the
 * framework!
 * 
 * @author wkerckho
 *
 */
@ApplySchedule("delay 0 seconds")
@Segment
public class Hello implements FunctionalSegment {

    @Configurable(description = "The message to print", defaultValue = "Hello from LimeDS instance!")
    private String message;

    @Override
    public JsonValue apply(JsonValue... input) throws Exception {
        System.out.println(message);
        return null;
    }

}

Step 5: Test the setup

We can now test if the workspace is setup correctly. Go to the run folder, and open the run.bndrun file. It should open using the Bndtools Run editor, which shows the execution environment details. Click the "Run OSGi" button to start the LimeDS instance. Normally, you should see a message "Hello from the LimeDS Hello Segment!" in the console output.

Note that by default, LimeDS will bind to port 8080. You can change this by adding a runtime property org.osgi.service.http.port with the desired port value to the run.bndrun file.

The run project represents the folder where the LimeDS binary is executed, configuration files and Slices created using the LimeDS editor can be found here.

Step 6: Develop your first Slice using the Visual Editor

A basic tutorial on how to use the Visual Editor to create a basic Slice can be found here.

Step 7: Updating your workspace

Once your workspace has been setup, your projects and runtime depend on a specific release of LimeDS. However, LimeDS is still continuously evolving, so at some point you will probably want to make your workspace compatible with a newer version. To do this manually would be a tedious process, as it requires:

• downloading our latest annotation processor
• updating the build configuration
• updating the version number of the dependencies on the core modules in each of your projects
• updating the runtime configuration to make sure it runs on the latest LimeDS core binaries

Fortunately, we've added a command to the Setup Manager tool that can automate this process:

update-workspace

It will prompt you to close Eclipse first (so all file handles are released). If the process is successful, you should see the following message in the console:

Follow the displayed instruction to complete the update process.