Skip to content

Building EclipseLink

Jump to bottom
Radek Felcman edited this page Feb 16, 2024 · 18 revisions

This is a guide for new users to build EclipseLink locally

Table of Contents

EclipseLink 3.0+

Prerequisite steps:

  • Set up EclipseLink
  • (optional) Set up local database to run tests on. In this case except DB installation, is required to prepare test properties file in user home directory. It's possible copy some file from project. See: etc project sub-directory.

Test property files from there are used if there is no any in user home directory (default DB connection and JEE server settings). File names are e.g. el-test.mysql.properties for MySQL, el-test.oracle.properties for Oracle DB. Test property file has properties like db.url, db.user, db.pwd..... to describe connection to the testing DB. Property file from user home directory has higher priority, that file in etc directory.

  • (optional) Server side testing. Currently there is support for WildFly 15.0.1.Final, GlassFish 5.1 and Oracle WebLogic 12.2.1 (must be installed manually). WildFly and GlassFish are installed automatically during Maven build (server tests). Default installation directory for JEE servers is ~/.eclipselinktests (must be created).
  • (optional) Set up local WebLogic (download)

Required tools:

Default developer build

mvn install

performs the build and runs SRG tests on inmemory Apache Derby DB

Default developer build (without tests)

mvn install -DskipTests

performs the build without tests and without Oracle modules

Default build with LRG tests (MySQL)

mvn verify -Pmysql,test-lrg

performs the build including source and javadoc bundles and runs LRG tests on local Mysql DB without server side tests.

Server side tests (MySQL, WildFly)

mvn verify -pl :org.eclipse.persistence.jpa.test -P server-test-jpa-lrg1,mysql

mvn verify -pl :org.eclipse.persistence.jpa.test -P server-test-jpa-lrg2,mysql

performs the JPA server side tests on local Mysql DB and WildFly.

Note: JPA Server side tests are divided into two parts due Travis timeout limit.

Test execution examples

Core LRG tests (unit + integration) against MySQL DB

mvn verify -pl :org.eclipse.persistence.core.test -P test-core-lrg,mysql

and Oracle DB

mvn verify -pl :org.eclipse.persistence.core.test -P test-core-lrg,oracle

JPA LRG tests (unit + integration) against MySQL DB

mvn verify -pl :org.eclipse.persistence.jpa.test -P test-jpa-lrg,mysql

JPA JSE LRG tests against MySQL DB

mvn verify -pl :org.eclipse.persistence.jpa.jse.test -Pmysql

All LRG tests against MySQL DB (!!takes 2-6 hours depends on machine!!)

mvn verify -Pmysql,test-lrg

Oracle DB build

mvn install -Poracle

performs the build including Oracle DB specific extensions and runs SRG tests on local Oracle DB

Customized build

mvn install -P<database>,<applicationServer>,<testGroup>

where .
<database> = derby, mongo, mysql, oracle .
<applicationServer> = glassfish, weblogic, wildfly .
<testGroup> = test-srg, test-lrg

notable system properties:
-Dtest.properties.file=/path/to/someDB.properties - custom database server related properties .
-Dtestjee.properties.file=/path/to/someAS.properties - custom application server related properties .
-Ddb.driver.groupId=..., -Ddb.driver.artifactId=..., -Ddb.driver.version=... - Maven coordinates of custom JDBC driver .

See default property files in the repository for more details about the content of property files.

EclipseLink 2.7.x

Introduction

EclipseLink 2.7.x build is based on following technologies:

Apache Ant is entry point which calls Maven with some Tycho extensions.

There are three dependency systems used:

Required initial software and environment

Environment

Internet connection is needed. It's used by Maven and Eclipse Tycho. Ensure that Maven is correctly configured (can download dependencies).

Software
  • JDK 11+ (we are using now JDK 21)
  • Ant 1.10+ (currently 1.10.14)
  • Maven 3.6+ (currently 3.9.5)

Another required software will be mentioned in the build steps bellow.

Environment variables

Following environment variables has to be specified

JAVA_HOME=<absolute path to the JDK>
ANT_HOME=<absolute path to the Ant location>
M2_HOME=<absolute path to the Maven location>
PATH ... add to the system path: JDK tools (java, javac, javadoc...), ant, mvn

Note: Build will check some environment

Build steps

Note: All example commands there are taken from Linux/Unix

  1. Create directory for manually downloaded dependencies. You can create or use any directory.
    For example mkdir -p $HOME/extension.lib.external
    Location will be specified in build.properties file.

  2. Download into directory from step 1. following jars.
    junit-4.13.2.jar ... test framework
    hamcrest-core-1.3.jar ... test framework
    jmockit-1.35.jar ... used in the tests
    jboss-logging-3.4.3.Final.jar
    javax.el-3.0.1-b12.jar
    classmate-1.6.0.jar
    apache-ant-1.10.9-bin.tar.gz
    mysql-connector-java.jar ... MySQL JDBC driver for a tests
    See e.g. https://github.com/eclipse-ee4j/eclipselink/blob/2.7/.github/workflows/ant.yml#L62-L70
    or https://github.com/eclipse-ee4j/eclipselink/blob/2.7/etc/jenkins/init.sh#L20-L32
    Note: JARs above are used in the EclipseLink test modules

  3. Download and unpack Eclipse SDK.
    eclipse-SDK-4.10-linux-gtk-x86_64.tar.gz
    E.g.
    wget -nc https://download.eclipse.org/eclipse/downloads/drops4/R-4.10-201812060815/eclipse-SDK-4.10-linux-gtk-x86_64.tar.gz -O $HOME/extension.lib.external/eclipse-SDK-4.10-linux-gtk-x86_64.tar.gz
    tar -x -z -C $HOME/extension.lib.external -f $HOME/extension.lib.external/eclipse-SDK-4.10-linux-gtk-x86_64.tar.gz
    Specified exact version 4.10 is needed. Eclipse SDK is used by Tycho compiler and for the access and creation to P2 repositories.

See e.g. https://github.com/eclipse-ee4j/eclipselink/blob/2.7/.github/workflows/ant.yml#L72
or https://github.com/eclipse-ee4j/eclipselink/blob/2.7/etc/jenkins/init.sh#L36

  1. Create build.properties file in the user home $HOME directory
    Example content (content must reflect current environment)
extensions.depend.dir=$HOME/extension.lib.external
junit.lib=$HOME/extension.lib.external/junit-4.13.2.jar:$HOME/extension.lib.external/hamcrest-core-1.3.jar
eclipse.install.dir=$HOME/extension.lib.external/eclipse  
jdbc.driver.jar=$HOME/extension.lib.external/mysql-connector-java.jar
db.driver=com.mysql.cj.jdbc.Driver
db.url=jdbc:mysql://localhost:3306/ecltests?allowPublicKeyRetrieval=true
db.user=root
db.pwd=root
db.platform=org.eclipse.persistence.platform.database.MySQLPlatform

Comments per each line:
extensions.depend.dir=$HOME/extension.lib.external ... points to the directory with manually downloaded dependencies from steps 1. 2.
junit.lib=$HOME/extension.lib.external/junit-4.13.2.jar:$HOME/extension.lib.external/hamcrest-core-1.3.jar ... points to JUnit FW related JARs. It allows in special cases to use different location than extensions.depend.dir.
eclipse.install.dir=$HOME/extension.lib.external/eclipse ... location where Eclipse SDK from step 3. is downloaded and unpacked. Needed for a Tycho build plugins.
jdbc.driver.jar=$HOME/extension.lib.external/mysql-connector-java.jar ... JDBC driver used in the tests. Needed for a tests.
db.driver=com.mysql.cj.jdbc.Driver ... JDBC driver class name. Needed for a tests.
db.url=jdbc:mysql://localhost:3306/ecltests?allowPublicKeyRetrieval=true ... JDBC URL to the testing DB
db.user=root ... DB username to the testing DB
db.pwd=root ... DB password to the testing DB
db.platform=org.eclipse.persistence.platform.database.MySQLPlatform ... EclipseLink DB platform class. It's related with testing DB vendor.

Note: DB mentioned above in db.* properties doesn't have to be functional/installed for EclipseLink build. Of course, it's needed in case of tests. There are mentioned only required properties, but not all of them.

See e.g. https://github.com/eclipse-ee4j/eclipselink/blob/2.7/.github/workflows/ant.yml#L73-L81 or https://github.com/eclipse-ee4j/eclipselink/blob/2.7/etc/jenkins/init.sh#L40-L52

[optional] 5. Proxy settings for Eclipse SDK Create proxy.ini file in the user home $HOME directory with following content

org.eclipse.core.net/proxyData/HTTP/host=<PROXY HOSTNAME>
org.eclipse.core.net/proxyData/HTTPS/host=<PROXY HOSTNAME>
org.eclipse.core.net/proxyData/HTTPS/hasAuth=true|false
org.eclipse.core.net/proxyData/HTTP/port=<PROXY PORT>
org.eclipse.core.net/proxyData/HTTPS/port=<PROXY PORT>
org.eclipse.core.net/org.eclipse.core.net.hasMigrated=true|false
org.eclipse.core.net/nonProxiedHosts=<NON PROXY host>
org.eclipse.core.net/systemProxiesEnabled=true|false
org.eclipse.core.net/proxyData/HTTP/hasAuth=true|false

Note: Don't forget to modify right side to reflect current environment.

  1. Build EclipseLink From the EclipseLink project directory (sources root dir) call:
    ant -f antbuild.xml clean build
    or for distribution bundles like eclipselink.zip
    ant -f antbuild.xml clean build

For other targets see https://github.com/eclipse-ee4j/eclipselink/blob/2.7/antbuild.xml#L41-L75

Troubleshooting

  • ensure, that JDK tools, Ant, Maven are on the system path and check versions by: java -version
    ant -v
    mvn -v
  • local P2 repository bug like Caused by: java.lang.RuntimeException: Failed to load p2 repository with ID
    1. Ensure that Internet connection is functional
    2. Ensure that Eclipse SDK is available and eclipse.install.dir is correctly configured
    3. Delete corrupted local P2 repositories from:
      • <EL PROJECT DIR>/buildsystem/compdeps/org.eclipse.persistence.compdeps/target
      • <EL PROJECT DIR>/buildsystem/compdeps/org.eclipse.persistence.compdeps.internal/target
      • <EL PROJECT DIR>/buildsystem/compdeps/org.eclipse.persistence.compdeps.p2repo/target
      • <EL PROJECT DIR>/buildsystem/compdeps/sun.misc/target
      • <EL PROJECT DIR>/buildsystem/oraclelibs/p2repo
      • <EL PROJECT DIR>/buildsystem/oraclelibs/target

EclipseLink 2.6 and older

build instructions for older versions can be found @ https://wiki.eclipse.org/EclipseLink/Building#Build

To install built artifacts into local maven repository, run full build using ant -f antbuild.xml build-distribution and then install artifacts by running:

ant -f uploadToNexus.xml -DsnapshotId=local -DsnapshotURL=file:///path/to/m2-repo \
 -Drelease.version=3.0.0 -Dbuild.type=SNAPSHOT -Dgit.hash=local \
 -Dmavenant.dir=/folder/with/maven-ant-tasks-2.1.3.jar -Dversion.string=3.0.0.qualifier
Clone this wiki locally