Home Contact

Event Series Intelligence

Building Esper

You can start using Esper with the binary jar that is included in all distributions. There is no need to build your own kit 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.

In Esper, all module builds are managed by Apache Maven 3 or above. The Esper engine itself can be build and unit tested via the below commands. The instructions below have last been tried using Maven 3. Maven can be downloaded from http://maven.apache.org/.

You will need to perform a checkout from the Subversion source code control system (see Source Repository page).

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

As a prerequisite, you should have a version of Java JDK 6 installed and set up.

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

cd esper
mvn install

Running all tests may take about 10 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 created from 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 1GB and Dual Core 2x1.8 GHz
  • Access to the full Subversion trunk file system is required as tests will read external files that may not be part of the source distribution.
  • If you are running the test suite from within an IDE, please use the following parameters: -Dlog4j.configuration=etc/infoonly_log4j.xml -Xms512M -Xmx512M

Similarly, the Esper IO library for input output adapters also build by the same commands:

cd esper/esperio
mvn install

Esper examples are a separate Maven project. The example codebase are contains JUnit tests. All examples can be build and run via these commands:

cd esper/examples
mvn test

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, the MVEL specific tests are deactive by default.

In regression\scripts\TestScriptExpression.java enable TEST_MVEL and rerun the tests.

Add merge&release tag

Add tag to tags/release_x.x.0_prerelease from trunk.

Run code quality tools

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

Findbugs

Findbugs 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, code style, 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 of checkboxes).

Change version in

  • esper/pom.xml
  • esper/build.xml
  • esper/doc/reference/en/master.xml (releaseinfo element)
  • esper/src/site/site.xml
  • examples/pom.xml (2 places)
  • examples/etc/setenv.bat and setenv.sh

search for further reference to old version number via text file searcher

Make sure all code is in Github and all JavaDocs generate.

Review changelog.txt in root dir

Clean Maven cache - this helps make sure all references to older jar file cause an error if used

Remove jar files from C:\Documents and Settings\<NAME>\.m2\repository\com\espertech

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"

JavaDoc

cd esper; ant javadoc
cd esperio; ant javadoc
cd esper-avro; ant javadoc

//copy to site

Manual

Generate docs:

cd esper\doc
mvn clean install
cd esperio\doc
mvn clean install
// copy to site

Distribution release

  • Create distribution zip: "ant dist_zip" and "ant dist_tar"
  • copy to distribution dir
  • "ant source_zip", copy src zips to distribution dir

Maven repository deployment

  • This is simply "mvn clean deploy";

Test Release

  • web site updated?
  • doc links on web site
  • distribution available, download, unpack

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 download.php and news.php and index.php on site
  • Update support system adding X.Y as a new version number of choose from the dropdown