This section describes how to set up Eclipse and Odysseus for developments.
You will need the following tools:
- Java 8 JDK
- Eclipse for RCP and RAP Developers (Important! Do not use a standard eclipse version!) e.g.: https://www.eclipse.org/downloads/packages/release/oxygen/3a/eclipse-rcp-and-rap-developers
Important: Photon currently doesn't work! Please use Eclipse Oxygen RCP RAP until we fixed the error.
- GIT Client (see next step for details)
2. Checkout Source Code
There are different ways to create new functionality with Odysseus. The first way should be used if you want to add something new to Odysseus (e.g. a new wrapper) but do not want to change the common code base. This should be the preferred way of development for Odysseus:
2.1 Option 1 (preferred): Extending Odysseus with new plugins
Odysseus has a very large code base. To allow a much easier start, we provide a template project in our Bitbucket server. You should clone or fork this project and use it to add new plugins to this template. The template can be found here:
When using git you should use the following command to clone Odysseus (Odysseus is based on submodules, so the flag recurse-submodules is necessary):
Remark: Because, you are not allowed to push updates here, you should change your repository URL to your git location and rename your folder to your new repository name.
2.2 Option 2: Working directly with the Odysseus source code
With this method, you check out all the source code from Odysseus. The source code is publicly available via git (from a Bitbucket server):
Odysseus uses git submodules, so the flag recurse-submodules is necessary.
3. Setup Eclipse
After Eclipse started, you have to import all bundles (these are the parts of Odysseus and are equal to an Eclipse project). Use "File -> Import -> Existing Projects into Workspace" to import them into Eclipse as follows:
After clicking "Next", select all needed projects.The source code folder has the following subfolders:
- application: this folder contains all applications that use Odysseus or provide any data like generators.
- client: contains all bundles that run on the client and don't have any dependencies to the server directly. It mainly offers the GUI.
- common: this holds common stuff und utilities that are needed on both server and client. Common does not have any dependencies to other folders like server, client...
- monolithic: this folder contains bundles that will only work in a monolithic system where server and client are the same product
- server: this is the server part of Odysseus and contains Odysseus main functionalities. Except of common, it does not have any dependencies to other folders. It does not have any GUI or client functionalities.
- test: contains stuff for testing and benchmarking
- tooling: contains primarily tools for the build controlling (Jenkins)
Furthermore, each main folder has different subfolders. Each subfolder normally contains a certain functionality or a dedicated extension (aka plugin for Odysseus).
In the follwing screenshot some bundles are selected.
We recommend to create working sets like here to group certain bundles:
For Odysseus core development: We recommend to use a dedicated Eclipse workspace for Odysseus, because a full import of Odysseus may have more than 300 projects. The most simple way is as follows. If you are starting Eclipse for the first time, choose the folder where you checked out the source code as the workspace location. If you already have a workspace, you can switch it via "File -> Switch Workspace -> Other...".
4. Target Platform
Since Odysseus has some dependencies to other external features like Eclipse GEF or the Equinox framework, it is necessary to use the target-platform definition. This definition is provided via the "target-platform.target" file.
If you are using the project template, the target platform can be found in the project targetplatform. If you are making core odysseus development, it can be found in the bundle/project called "de.uniol.inf.is.odysseus.common.feature". Open this file and click "Set as target platform" to use this as your target platform.
You can also use CRTL-SHIFT-R to search for the target platform
Notice, the target platform is valid for your whole workspace (therefore we recommend to use a dedicated workspace for Odysseus development).
Remark: Sometimes eclipse behaves strange when setting a new target platform. See Odysseus FAQ for further hints, if there are problems with the target platform.
5. First Run - Available Products
Now you should be able to run Odysseus. There are some predefined product-definitions to run Odysseus (depending on the bundles/folders you checked out before):
- Odysseus Server.product - (located in de.uniol.inf.is.odysseus.server.starter) - This is just a server-based instance of Odysseus (without any GUI) which can be used e.g. via a webservice.
- Odysseus Studio 2 (Client).product - (located in de.uniol.inf.is.odysseus.client.starter) - This is only the client part (GUI), which tries to connect to an Odysseus Server instance via webservice.
- Odysseus Studio 2 (Monolithic).product - (located in de.uniol.inf.is.odysseus.client.starter or de.uniol.inf.is.odysseus.monolithic.feature ) - This combines server and client into a single product and adds some additional bundles that only work in such a monolithic combination.
For the first time, the easiest way is to start the "Odysseus Studio 2 (Monolithic).product". Open this file and go to the tab "Overview". Click "Synchronize" under "Testing" and afterwards click "Launch an Eclipse application" to run Odysseus (you can alternatively run it in debug mode if you want).
When Odysseus Studio (the GUI) comes up, you have to insert some credentials. A default user is "System" and the password is "manager", the tenant can be left empty. Now Odysseus should be up and running.
6. Additional Information
Since Odysseus is an OSGi based application, it is divided into several bundles (the bunch of projects you checked out and imported before). To keep the overview of all bundles, they are combined to features. Each feature reflects a special functionality of Odysseus. Thus, we have a core.feature that encapsulates all minimal needed bundles or the studio.feature that contains all bundles for the RCP (i.e., GUI) of Odysseus (what we call Odysseus Studio).
The combination of several features is called a "product" - which should be runnable. The section above, for example, lists three products that combine different sets of features.
The core feature is necessary because it contains all fundamental functions for Odysseus.
See Adding features to products how to add a new Feature to an existing product.
Odysseus comes with the Simple Logging Facade for Java (SLF4J). To use logging, add the
de.uniol.inf.is.odysseus.slf4j bundle. In this bundle you can find the log4j.properties to configure the logging behavior.
Currently, only the server is working on MacOS. You can start the Odysseus Server product from Eclipse, but you cannot start any GUI product (e.g. Monolithic) that involves RCP. To run the server product, you have to install Java JDK 1.8, e.g. with homebrew: https://www.lonecpluspluscoder.com/2017/10/08/installing-other-versions-of-the-java-jdk-via-homebrew/