Downloading and Building Egeria Tutorial¶

Create a new directory for Egeria's main libraries. In the example below it is called egeria-main-libraries:

mkdir egeria-main-libraries

Change to your new directory.

cd egeria-main-libraries

Egeria's source is extracted from GitHub using the following git command:

git clone -b egeria-release-{release-number} --single-branch https://github.com/odpi/egeria.git

git clone -b egeria-release-3.14 --single-branch https://github.com/odpi/egeria.git

git clone https://github.com/odpi/egeria.git

A new directory has been created with the core Egeria source code. Change to the egeria directory and you are ready to build the source.

cd egeria

Create a new directory for Egeria's main libraries. In the example below it is called egeria-samples-source:

mkdir egeria-samples-source

Change to your new directory.

cd egeria-samples-source

Egeria's samples source is extracted from GitHub using the following git command:

git clone https://github.com/odpi/egeria-samples.git

A new directory has been created with the samples' source code. Change to the egeria-samples directory and you are ready to build the source.

cd egeria-samples

Create a new directory for Egeria's developer projects. In the example below it is called egeria-dev-projects-source:

mkdir egeria-dev-projects-source

Change to your new directory.

cd egeria-dev-projects-source

Egeria's source is extracted from GitHub using the following git command:

git clone https://github.com/odpi/egeria-dev-projects.git

A new directory has been created with the developer projects source code. Change to the egeria-dev-projects directory and you are ready to build the source.

cd egeria-dev-projects

Egeria currently supports building on *nix, Linux & Linux-like operating systems such as MacOS.

Our official build pipelines are based on x86_64 architecture, but it is expected the build will run on other architectures, subject to the availability of the required tools and interpreters/jvms/runtimes on that platform (for example Java, Python, Docker/containerd/k8s etc).

Currently, the Egeria team does not regularly test or use Windows, so there may be areas that are not documented as well, or not work. We would welcome any interested developers who use Windows on a daily basis to join us and help improve this area!

On Windows, you should use Windows Subsystem for Linux Version 2 or above, and install a Linux distribution such as Ubuntu. This avoids issues we have seen with path separators, symbolic links, slow I/O performance, long path names. WSL version 2 should be used, not version 1, due to differences in file I/O (emulation). The docs above explain how to switch from v1 to v2.

From the command line everything should work just as for macOS & linux, including building and running Egeria since a full linux distribution is being used, with a linux kernel.

However, IDE use may be a little different. Some IDEs can run the GUI in Windows natively, and then use the WSL environment to perform build and execution.

With IntelliJ the following process is most likely to work:

• Ensure an Ubuntu environment is setup using WSL2
• Install a java sdk, and maven as for mac/linux
• ensure a build at the command line works ok
• Install IntelliJ community edition on Windows. Using the latest version (2022.1 at time of writing) is recommended as WSL support is a new area
• Create a new project 'from existing sources' and ensure you point to //wsl$/..... (path in linux environment)
• After a few warnings as IntelliJ detects the code, your SDK should be set automatically to the linux java version

Jetbrains have a WSL2 support article which elaborates these instructions in more detail

Another option would be to run the IDE itself directly within the linux environment, and share the display via X11, VNC, or another form of remote desktop. This is likely to work, but could perform sluggishly. Microsoft are improving this area with WSLg , but this requires very new software, and dedicated graphics to work well. It's also outside the scope of this summary.

Egeria provides both maven and gradle build scripts. On Windows we've seen issues with maven which can cause IntelliJ to be busy or unresponsive for hours. If this happens you could try to use the gradle build instead. To do this in IntelliJ:

• Navigate to your maven tool window,click the top level maven project 'Egeria' & 'Unlink Maven Projects' - and confirm.
• In the left project tree right-click on the top level build.gradle and 'Link gradle project'

Yet another option to use IntelliJ is to make use of Remote Development. With this configuration you would use a seperate linux system, and connect remotely. This is beyond the scope of these docs.

Feedback on Windows, offers to help, clarification on the steps can be directed to odpi/egeria-docs#335

This is a regular incremental build, but will also run all tests and generate javadoc.

./gradlew build

The quick build skips generation of javadoc, and tests

./gradlew build -x test -x javadoc

We avoid any use of cache, and ensure a full clean build. This may be needed when you want to recheck something that has no changed sources, but needs a rebuild -- for example to review compiler warning messages (not errors)

./gradlew clean build --no-build-cache

This build option creates an OMAG Server Platform where the registered services are optional. The OMAG Server Platform loads the registered services it finds on the loader path specified with the -Dloader.path={directoryName} option of its startup command. Use this option if you want to remove the registered services that you are not using, or you would like introduce your own registered services.

./gradlew -PadminChassisOnly build 

The egeria.git repository has a top-level pom file so all of the modules can be built using one mvn clean install command from the top-level egeria directory. There is also a quick build option for people just wishing to use Egeria rather than make changes - enter mvn clean install -P quick -D skipFVT

The egeria-samples.git repository does not have a top-level pom file. Each sample is built separately. When you want to build a sample, change to the sample's directory where the pom.xml file is located and issue mvn clean install.

The egeria-dev-projects.git repository has a top-level pom fileo all of the modules can be built using one mvn clean install command from the top-level egeria-dev-projects directory.