Skip to end of metadata
Go to start of metadata

Servoy Developer is a plugin for the Eclipse platform, so to develop the Servoy codebase an Eclipse SDK environment with Eclipse Plugin development facilities is required.

In order to get started with development on the open source Servoy projects, the following is required:

  1. A Servoy Developer installation
  2. The Servoy Server libraries
  3. A separate Eclipse environment with the Eclipse plugin development tools installed
  4. Configuration of the Eclipse installation

In This Chapter

Quick Start for the Impatient

  • Download and install JDK 1.8 from Oracle (some things like javaws.jar are needed that are not available in openJDK)
  • Install Servoy Developer
  • Install Eclipse and then the Plug-in Development Environment plugin then
  • In eclipse preferences add the JDK 1.8 that you installed previously to the list of available JREs - if it's not already there; check it to be the default
  • Setup a String Substitution variable named 'servoy_install' which points to the installation directory of the previously installed Servoy Developer
  • Create a ClassPath variable named 'WEBSTART' that points to javaws.jar of the used JDK (under jre/lib subfolder)
  • Create a ClassPath variable named 'TOOLS' that points to the tools.jar of the used JDK (under lib)
  • Use the GIT Repositories view to clone the open source Servoy projects (the branch for LTS build is (year)03; the branch for latest release is "release" but development for next release is done on "master" branch; take the branch you want for all the repositories below - the ones that have that branch; for those that don't have the branch you need take the master branch) from the repositories at https://github.com/Servoy/
  • Download the Servoy Server libraries from https://build.servoy.com/latest: open the right branch folder, and place them in the 'libs_extra' directory of the launch_targets project. Download only the files who's name postfix matches the value of the release number in the ClientVersion.java class in the checked-out source code
  • Setup a Target Platform by:
    • Opening the  'eclipse.target' file, located in the 'launch_targets' project
    • Make sure the entry for '${project_loc}/launch_targets/libs_extra' display '(x of x included)', where x is equal to the number of eclipse plugin libraries (.jar files) in the libs_extra directory. If not, force a refresh by selecting the entry, clicking Edit > Finish and then Control-S to save the editor
    • Clicking the link 'Set as Target Platform' of the Target editor
  • In order to add the documentation files, download the servoy_update.zip from https://build.servoy.com/latest, unzip it and also unzip the com.servoy.eclipse.core plugin jar. Copy the xml files from the com/servoy/eclipse/core/doc folder to the same location of the com.servoy.eclipse.core project.
  • Create a Launch Configuration (and directly start a debug session) by right-clicking the 'Servoy Launch.launch' file in the 'launch_files' directory of the 'com.servoy.eclipse.core' project and selecting Debug as > Servoy Launch (or Servoy Launch_mac when on OSX).
  • Add a maven toolchains.xml file to .m2 repository and build sablo using maven. Restart eclipse.

Installing Servoy Developer

An installation of Servoy Developer is required in order to be able to launch Servoy Developer from source code, because the source depends on the directory structure that is present in a Servoy Developer installation.

The installer for Servoy Developer can be downloaded at http://www.servoy.com/download. Running the installer will install Servoy Developer. For a more indepth description of installing Servoy Developer, see Download & Install Servoy Developer.

Installing Eclipse With The Eclipse Plugin Development Tools

The open source Servoy projects are all plugins for the Eclipse environment, so in order to develop on the projects a Eclipse version with Eclipse plugin development tools (PDE) installed is required.

The Eclipse.org download page (http://www.eclipse.org/downloads/) lists a wide range of prepackaged Eclipse distributions. See http://www.eclipse.org/downloads/packages/compare-packages for the overview of what each Eclipse distribution contains.

One of the offered distributions that includes PDE is the Eclipse Classic distribution. Although the plugin development tools can be installed in any Eclipse environment, the easiest is to download the 'Eclipse Classic' distribution and install it.

NOTE: if you want to run the Servoy mobile client, then you also need to install the Google plugin for Eclipse from https://developers.google.com/eclipse/docs/download

Configuration

Start the downloaded and installed Eclipse installation and choose or create a workspace in which the development on the open source projects of Servoy will take place.

After startup, the following configuration needs to be done:

Setup a variable: Go to Window > Preferences > Run/Debug > String Substitution and create a new variable named 'servoy_install' with the value of the directory where Servoy Developer is installed.

Create a classpath variable: Go to Window > Preferences > Java > Build Path > Classpath Variables and create a new variable named 'WEBSTART' with the value of of javaws.jar in the Java installation.

Setup a connection to the Servoy source:

  • Install the "egit" eclipse plugin

  • Open the GIT Perspective: Window > Open Perspective > Other > GIT

  • Use the GIT Repositories view to clone the open source Servoy projects (the branch for LTS build is (year)03; the branch for latest release is "release" but development for next release is done on "master" branch; take the branch you want for all the repositories below - the ones that have that branch; for those that don't have the branch you need take the master branch) from the repositories at https://github.com/Servoy/


    Make sure to enable the checkbox "check out projects when clone is complete" in the GIT clone wizard - when you want to import all projects from a repo. Otherwise you can right click on the repository in eGit repositories view and import projects (only the ones that are needed). Usually you do not need to import the root of a repository into the workspace, just the projects in it.

Download Servoy Server libraries and docs

In order to also be able to start debug clients from Servoy Developer launched from the source code, it is required to use the correct version of several libraries of the Servoy Application Server. The latest version of these libraries can be downloaded from the Servoy build server, located at http://build.servoy.com/latest. Download all the libraries from the subdirectory for a specific branch master who's name postfix matched the value of the releaseNumber variable in the ClientVersion.java class of the checked-out source code and place them in the 'libs_extra' directory of the 'launch_targets' project.

In order to add the generated documentation files (which are used in different parts of developer), download the servoy_update.zip from https://build.servoy.com/latest, unzip it and also unzip the com.servoy.eclipse.core plugin jar. Copy the xml files from the com/servoy/eclipse/core/doc folder to the same location of the com.servoy.eclipse.core project.


Download Servoy Server plugin for running mobile

Please download the latest version of the mobile and mobileservice plugins; these can also be downloaded from the Servoy build server, located at http://build.servoy.com/latest. Download the plugins from the subdirectory for trunk (currently) who's name postfix matches the value of the releaseNumber variable in the ClientVersion class. Copy these over to the the {servoyInstall}/application_server/plugins directory without the postfix (overwrite existing mobile and mobileservice plugins if needed).


Setup the Target Platform:

  • Switch to the Java Perspective: Window > Open Perspective > Java
  • Expand the 'launch_targets' project in the Package Explorer (read first the opensource_readme.txt)
  • make your own copy of the com.servoy.eclipse.target.target file so you can change this one and set that one as the main eclipse target
  • Add an entry '${project_loc}/launch_targets/libs_extra' display '(x of x included)', where x is equal to the number of eclipse plugin .jar files in the libs_extra directory. If not, force a refresh by selecting the entry, clicking Edit > Finish and then Control-S to save the editor.
  • Click the 'Set as Target Platform'.

Creating a Launch Configuration: Last step in the setup of the environment is the creation of a Launch Configuration. 

  • Expand to com.servoy.eclipse.core > launch_files in the Package Explorer
  • Right-click the 'Servoy Launch.launch' file and select Debug As > Servoy Launch
    The steps above will install the configuration contained in the 'Servoy Launch.launch' file as a launch configuration and launch a Servoy Developer as a debug session (when on OSX, add the -XstartOnFirstThread argument, to the VM Arguments tab in the launch configuration)


Upgrade notification on startup

When starting Servoy Developer from source code, it is most likely that a notification is shown indicating that the Servoy Application Server version should be upgraded. This message can be canceled and ignored.

When starting a debug session, Servoy Developer will launch with settings of the Launch Configuration. By default the workspace for example that is opened is set to '/workspace', relative to the Servoy Developer installation.

To edit the launch settings, open Run > Debug Configurations > Eclipse Application > Servoy Launch and edit the settings.

Ready: After completing the steps described above, the Eclipse installation is setup correctly to launch Servoy Developer in a debug session:

  • Run > Debug (or F11)

Add a toolchains.xml file to your .m2 folder in order to build with maven. Build the sablo project. Restart

If you want to build sablo for example via maven you have to add in the local maven repository (by default [user_home]/.m2) a file named toolchains.xml with this content:

<?xml version="1.0" encoding="UTF-8"?>
<toolchains>
  <!-- JDK toolchains -->
  <toolchain>
    <type>jdk</type>
    <provides>
    	<id>JavaSE-1.8</id>
    </provides>
    <configuration>
      <jdkHome>...</jdkHome>
    </configuration>
  </toolchain>
</toolchains>

where you replace those ... with the path to jdk8 on your system.

Then run a mvn clean install on the sablo project. You can do that from eclipse (right click on sablo/pom.xml and run as maven build then set the goals: clean install).

After this step and a restart of eclipse (currently needed because it needs to see some new jars downloaded by maven - that are used in the classpath of sablo project) it should compile without errors.

Optional Additional Configuration

*Adding other features to the target: *If additional features are required in the Servoy Developer that is launched from source code, for example an SVN Team Provider plugin, an easy way to achieve this is by adding the feature(s) to the target Definition. 

New way:

  • Open the 'eclipse.target' file in the root of the 'launch_targets' project (or make a copy of that and open the copy)
  • In "Locations" click Add and then give the software site (eclipse feature url) of the feature(s) that you want to include.
  • Click the 'Set/Reload as Target Platform' link (top-right).

Old way:

  • Make sure the feature is installed in a Eclipse installation, doesn't have to be a Servoy Developer installation, can also be the Eclipse SDK from which the development on the Servoy open source projects is being done.
  • Open the 'eclipse.target' file in the root of the 'launch_targets' project (or make a copy of that and open the copy)
  • Click Add > Features > Next
  • Point the location to an installation directory of Eclipse. Note that when using a Servoy Developer instance in this case, the {servoyInstall}/developer is the directory to point to.
  • Check the feature(s) to be included and press Finish.
  • Click the 'Set/Reload as Target Platform' link.

Running Mobile Client From Sources

  • Install GWT plugin for Eclipse
  • Run 'build_mobile_in_developer' ant task from 'build.xml' of 'servoy_mobile' project (this will create the template war file)
  • Refresh Workspace for Eclipse file system to see the war file
  • Copy(Overwrite) mobile_xyz*.jar and mobileservice_xyz.jar from http://build.servoy.com/latest to plugins folder of your Servoy install (where variable servoy_install points to). Download only the files who's name postfix matches the value of the release number in the ClientVersion class in the checked-out source code.
  • Run Servoy Developer
  • From Servoy Developer, export mobile solution to folder: {myEclipseWorkspace}/servoy_mobile/war
  • Refresh 'servoy_mobile' project from Eclipse workspace
  • From context menu of 'servoy_mobile' project run: Debug as > Web Application (choose index.html as html file)
  • Activate service solution in Servoy Developer
  • In Eclipse, from Development Mode view, open the provided url in Chrome browser
  • If GWT plugin for Chrome is not installed you will be prompted to install it; afterwards the mobile solution will run, breakpoints can be put in java classes of 'servoy_mobile' project
  • No labels