Overview

You can start using Esper with the binary jar files that are included in all distributions. There is no need to build your own jar files at all unless your goal is to contribute.

You also do not need to build Esper to run the examples. Please follow the instructions in the readme file in the"examples/etc" folder to run the examples.

All builds are managed by Apache Maven 3 or above. The compiler and runtime can be build and unit-tested via the below commands. Maven can be downloaded from http://maven.apache.org/.

You will need to perform a checkout from the Github source code control system (see Source Repositorypage).

If you have a firewall you may need to change the proxy entry in Maven's setting.xml under your Maven installation directory.

As a prerequisite, you should have the respective minimum version of Java JDK installed (see change history).

The commands to compile Esper, run all tests and install a jar file into Maven's repository is:

mvn install

Running all tests may take about 30 minutes. The Maven command to run on the root of the project to install but skip tests and skip GPG signing is:

mvn -DskipTests -Dgpg.skip=true install

Note, in order to run all tests successfully, the following preconditions must be met:

  • For tests performing database joins to work, MySQL must be installed and available at connection string"jdbc:mysql://localhost/test?user=root&password=password" and the test table must be createdfrom etc/regression/create_testdb.sql (use "create database test;" if the test database is not already present)
  • For performance tests that assert against execution times the recommended minimum configuration is 2GB of heap (8GB system memory) and quad-core 4x2 GHz
  • Build from a clone of Github as tests will read external files that may not be part of the source
  • If you are running the test suite from within an IDE, please use the following parameters:-Dlog4j.configuration=etc/log4j.xml -Xms512M -Xmx2g

The Maven command to run a specific set of tests is (from the root directory):

mvn -pl regression-run test -Dtest=TestSuiteInfraNamedWindow

The Maven command to use Nondex to find flaky tests is (from the root directory):

mvn -pl regression-run edu.illinois:nondex-maven-plugin:2.1.7:nondex -Dtest=TestSuiteInfraNamedWindow

Esper Release Steps

Perform MVEL Integration Tests Manually

Since MVEL is an optional jar file and scripting language supported not through JSR 223 support but directly, theMVEL specific tests are deactive by default.

In TestScriptExpression.java enable TEST_MVEL and rerun the tests.

Run code quality tools

The project standard requires the following tools to pass before a release:

Spotbugs

Spotbugs is a separate download that comes with it's own GUI. In the GUI import the Esper source code and dependencies, and run an analysis. Analyze the findings and prioritize the required fixes. Not all reported warnings are relevant, and many are origined in ANTLR generated source code. Use judgement.

IntelliJ IDEA

  • Run the IDE default analysis profile over the Esper module. Look at the following issues: bitwise ops, class structure, codestyle, error handling, performance, threading, probable bugs; Some too-fine grained categories are usually:control flow, data flow, declaration redundance (module doesn't see extension points).
  • Create/Run the "JavaDoc" profile for checking java docs only (see "general" section ofcheckboxes).

Change of version

Replacing the version number globally requires a text editor that can search all files. Search for references to old version number via text file searcher.

Review changelog.txt in root dir

The changelog.txt in the root folder contains important change notes.

Build, test and install

mvn clean install

If you want to skip unit testing and only do a binary build, use "-DskipTests -Dgpg.skip=true"

Copy Dependencies to Local Lib Directories

This copies dependencies from the local Maven repository to "lib" directories for JavaDoc and for packaging the downloadable distribution. This task can also be used to set up a development environment with libraries coming from "lib" directories.

ant copydependencies

JavaDoc

Generate the JavaDoc then copy to site.

ant generatejavadoc

Manuals

Generate the manuals then copy to site.

Downloadable Distribution

  • Create distribution zip: "ant dist_zip" and "ant dist_tar"
  • Copy to distribution dir

Maven repository deployment

  • This is simply "mvn -DskipTests clean deploy";
  • Release by logging into Sonatype Nexus

Test Release

  • web site updated?
  • doc links on web site work?
  • distribution available? download and unpack, run an example on Linux and Windows

Github

  • Check in changed build files, if any
  • Draft a new release

Github Issue Management

  • Close all resolved Github issues

Announce

  • Upload new esper-configuration.xsd to ET site
  • Update support system adding X.Y as a new version number of choose from the dropdown