Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "BaSyx / Download / Java Setup"

(Adds trouble shooting for JUnit error)
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= How to build the BaSyx Java SDK =
 
= How to build the BaSyx Java SDK =
  
−
The BaSyx Java SDK is using maven to generate and control its building process.
+
The BaSyx Java SDK is using Maven to generate and control its building process.
−
This article will detail on how to build the Java SDK from a fresh checkout.
+
 
 +
This article will detail on how to set up the Java SDK from a new checkout.
  
 
== Requirements ==
 
== Requirements ==
Line 12: Line 13:
  
 
== Getting started ==
 
== Getting started ==
−
Check out BaSyx from the command line with
+
# Check out BaSyx from the command line with "git clone https://git.eclipse.org/r/basyx/basyx"
 +
# Start Eclipse and import the projects as maven projects (File -> Import -> Maven -> Existing Maven Projects -> Browse to the BaSyx directory)
 +
# Select (at least) the following Projects and click "Finish":
  
−
git clone https://git.eclipse.org/r/basyx/basyx
+
[[File:Project-selection.png|500px]]
  
−
into some directory of your choice. Now start Eclipse, open File -> Import, choose Maven -> Existing Maven Projects, and click "Next". Now click "Browse", and navigate to the directory where BaSyx was checked out to.
+
The Maven projects should be automatically set up in Eclipse. You can always update the project settings using the Maven plugin (Right Click -> Maven -> Update Project).  
  
−
Now select (at least) the following Projects:
+
=== Project dependencies ===
−
* basys.sdk
+
All dependencies for maven projects are specified in the project's pom.xml. When building the project using maven, these dependencies will be automatically taken from the local maven repository (default: ''C:/User/username/.m2/repository'') and downloaded from the remote repository if it is not available locally.
−
* basys.components
+
−
* basys.examples
+
  
 +
The imported projects (sdk, components and examples) depend on each other as shown below:
  
−
and click "Finish".
+
[[File:BaSyx_Java_Dependencies.PNG]]
  
−
Alternatively, if your Eclipse IDE has EGit and the Maven SCM Handler for EGit installed, you can check out BaSyx directly with Eclipse:
+
This means '''basyx.components''' depends on '''basyx.sdk''' and '''basyx.examples''' depends on the two other projects. So if you make changes in e.g. basyx.sdk, you need to "install" it to the local repository using Maven before building components that depend on it.
  
−
* open File -> Import, and choose "Check out Maven Projects from SCM"
+
=== Project installation ===
−
* In the Window that pops up, select "git" in the top left, enter the URL of the BaSyx repository (https://git.eclipse.org/r/basyx/basyx) to the right, and click "Finish".
+
# Make sure that each project has a JDK selected as JRE System Library
 +
## Window -> Preferences -> Java -> Installed JREs -> Enable the '''JDK'''
 +
## -> Execution Environments -> JavaSE-1.8 -> Enable the JDK in the list of compatible JREs
 +
# Install '''basyx.sdk'''
 +
## Right click -> Run As -> Maven install
 +
## Maven will download all required dependencies, run the tests and build and install the project into the local Maven repository
 +
## You can ignore errors in the output coming from testing exceptions in unit tests
 +
## If successful, you will see the message: ''[INFO] BUILD SUCCESS''
 +
# Prepare the components as described in [[BaSyx_/_Download_/_Components_Setup|Setting up the Components project]]
 +
# Install '''basyx.components''' and '''basyx.examples'''
 +
# Done
  
−
[[File:Check-out.png|500px]]
+
After installation build outputs are placed in the /target folder and installed in the local Maven repository.  
  
−
If you can't select "git" in the upper left, you don't have the Maven SCM Handler for EGit installed. In this case click on the link to the m2e Marketplace in the lower right and install it. If you have issues with installing, you might need to use another update site ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=544231 | see this bug report]).  
+
===Eclipse IDE configuration===
 +
Although the Eclipse IDE can handle the BaSyx projects, there are multiple settings that will make it easier to work with them. This is especially true, if you are working on hierarchical Maven projects as with basyx.components.
  
−
* In the next window, select the same projects as mentioned above and click "Finish".  
+
* Enable a '''hierarchical Maven projects''' representation
 +
** Window -> Show View -> Project Explorer
 +
** Project Explorer View Menu (three dots in the top right corner of the view) -> Projects Presentation -> Hierarchical
 +
* Enable a '''hierarchical packages''' representation
 +
** Project/Package Explorer View Menu -> Package Presentation -> Hierarchical
 +
* Make use of '''working sets''' to organize multiple groups of projects
 +
** Project/Package Explorer View Menu -> Top Level Elements -> Working Sets
 +
** Project Explorer View Menu -> Select Working Set -> New...
 +
** Add a Java working set named e.g. "BaSyx" and add all basyx.* projects to it
 +
** Add another Java working set for e.g. your own projects
 +
* Prepare useful '''launch configurations'''
 +
** Right Click basyx.sdk project -> Run As -> Maven build..
 +
** Rename the launch configuration to e.g. "Install BaSyx SDK"
 +
** Enter "clean install" in "Goals:"
 +
** Click Apply and close the window
 +
** Repeat this for other run configurations (e.g. install components/examples...)
 +
** Click at the small, black down-arrow right next to the "Run As..."-icon (the white arrow in a green circle) in the toolbar
 +
** Organize Favorites... -> Add... -> Check "Install BaSyx SDK"
 +
** Click at the arrow next to the "Run As..."-icon again
 +
** Run your favorite launch configuration
 +
* Customize '''resource filters''' if necessary (if you would like to see e.g. .gitignore or .env files)
 +
** Project Explorer Filters & Customization (filter symbol in the top right corner of the view)
 +
** Uncheck ''.* resources'' in the list of Pre-set filters to be able to see .* files
 +
** Add own filters to hide specific files or folders again (e.g. .project, .classpath and .settings)
  
−
[[File:Project-selection.png|500px]]
 
  
−
Now the three projects will be checked out. However, none of them will compile (regardless of which check-out method you choose) as we have to do some fixes in the next step:
+
Final result:
  
−
=== Eclipse setup ===
+
[[File:BaSyxEclipseIDE.jpg]]
−
Eclipse currently does not correctly import the source folders. To fix this, go to the properties of each project, remove the existing source folder entry ''src'' and add ''src/main/java'' and ''src/test/java''.
+
  
−
[[File:BaSyx-Setup.PNG]]
+
=== Further steps ===
 +
The '''[[BaSyx_/_Introductory_Examples | introductory examples]]''' are a good starting point to see how the SDK itself can be utilized.
  
−
After doing this for each project, do a maven refresh (right-click on project, and choose Maven -> Update Project) for each project.
+
Furthermore, the '''basyx.components''' project is built on top of the '''basyx.sdk''' and provides additional components. Among others you will also find components with '''[[BaSyx_/_Documentation_/_OffTheShelf#Docker_components | predefined docker images]]''' inside.  
  
−
[[File:Maven-update.png|500px]]
+
There are extended '''[[BaSyx_/_Examples | basyx.examples]]''' that demonstrate various examples and use cases for both projects.
  
−
Additionally, JUnit has to be set up. To do so, add in the project properties JUnit to the build path by Java Build Path -> Libraries -> Add Library
+
Also read the article about '''[[BaSyx_/_Developer_/_Contributing | how to contribute]]''' to the open source code.
−
[[File:BaSyx-Setup_AddJUnit.PNG]]
+
  
−
Now basys.sdk compiles, but the other two projects won't before finishing the next steps:
+
== Troubleshooting ==
 +
=== No compiler is provided===
 +
'''Error:'''
 +
When doing maven install, maven complains that no compiler could be found.
  
−
=== Starting development ===
+
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.1:compile (default-compile) on project basyx.sdk: Compilation failure
−
In order to start developing on the project, the first thing you need to do is
+
[ERROR] No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?
 +
[ERROR] -> [Help 1]
  
−
# Make sure that each project has a JDK selected as JRE System Library
+
'''Solution:'''
−
# Right-click “basys.sdk” >> Select “Run As” >> Select “Maven Install”
+
This error is typically when maven is not able to find the installed JDK. To fix this for the Eclipse IDE, perform the following steps to add the installed JDK:
  
 +
* Navigate to Window -> Preferences -> Java -> Installed JREs
 +
* Add the JDK, if it is not already there. This can be done by the ''Add...'' button, selecting standard vm and selecting the JRE home to be the JDK folder
 +
* Select the JDK as default be ensuring that the box next to it is checked
 +
* Now, for each project the default JRE needs to be changed. This can be done by righ-clicking each project -> Preferences -> Java Build Path -> double click ''JRE System Library'' -> Select ''Workspace default JRE (jdk....)''
  
−
Maven will download all required sources, run the unit and integration tests and export a jar of the SDK to the .components and .examples project. After a successful installation, basys.components does compile now as well.
 
  
−
The mentioned projects are depending on each other as shown below:
+
If you are using maven from command line, this error can be fixed by ensuring that the JDK is added to the environment (e.g. PATH value on Windows).
−
 
+
−
[[File:BaSyx_Java_Dependencies.PNG]]
+
  
−
That means the basys.sdk project is required as a .jar file in each of the local maven repositories of basys.examples and basys.components. If you want to make changes to the basys.sdk project, you need to make a maven install in order to see the changes reflect in the other projects.
+
=== HTTP tests failing ===
 +
'''Error:'''
 +
Tests related to HTTP are failing. The console contains an error similar to
 +
SEVERE: Failed to initialize connector [Connector[HTTP/1.1-4001]]
 +
...  
 +
Caused by: java.net.BindException: Address already in use: bind
 +
...
  
−
Before you get started, the second task you need to do is to update the .sdk project to align with the maven configuration. For this what you need to do is
+
'''Solution:'''
−
* Right-click “basys.sdk” >> Select “Maven” >> Select “Update Project…” (ignore errors)
+
The reason for this error is that the port used by the HTTP tomcat server is already blocked. A common reason for this an already running tomcat instance. If you are using for example XMPP, it may occupy this port.
  
−
Finally, the last step is to run a Maven clean compile to make sure that the changes you do during coding are directly reflected when you execute single unit tests manually.
+
To fix this error, please close the application occupying the port.
−
* Right-click “basys.sdk” >> Select “Run As” >> Select “Build…”, type “clean test-compile” in the "Goals" field and click "Run".
+
  
−
'''!! Note: Make sure to clean compile after each install! Otherwise, your changes in the code will not be reflected in manual unit testing. !!
+
=== Cannot find '[..]junit[..]' on project build path ===
−
'''
+
'''Error:'''
 +
Can't execute the JUnit tests in Eclipse IDE due to missing entries in the build path
 +
Cannot find 'org.junit.platform.commons.annotation.Testable' on project build path.
 +
JUnit 5 tests can only be run if JUnit 5 is on the build path.
 +
''
  
−
To make basyx.examples compile, you need to do a Maven install of basys.components first. This, in turn, requires to set up and run your postgreSQL installation as [[BaSyx:BaSyx.Documentation.Component.Build | described here]].
+
'''Solution''':
 +
As the error message says, JUnit is missing in the build path. To address this issue, add JUnit to the build path:
 +
* Right click project -> ''Build Path'' -> ''Configure Build Path''
 +
* Click ''Add Library...''
 +
* Select ''JUnit'' -> ''Next'' -> Make sure that JUnit5 is selected -> ''Finish''

Revision as of 02:48, 24 April 2020

How to build the BaSyx Java SDK

The BaSyx Java SDK is using Maven to generate and control its building process.

This article will detail on how to set up the Java SDK from a new checkout.

Requirements

The BaSyx Java SDK requires the following dependencies to successfully build:

  • Java™ SE Development Kit 8, Update 152 (JDK 8u152 or higher)
  • Maven

To check out BaSyx, you also need a GIT installation. No Eclipse GIT plugin is required as we can do the checkout by using GIT only from the command line. If you want to checkout using Eclipse, you need the EGit plugin and also the Maven SCM Handler for EGit (more on that below).

Getting started

  1. Check out BaSyx from the command line with "git clone https://git.eclipse.org/r/basyx/basyx"
  2. Start Eclipse and import the projects as maven projects (File -> Import -> Maven -> Existing Maven Projects -> Browse to the BaSyx directory)
  3. Select (at least) the following Projects and click "Finish":

Project-selection.png

The Maven projects should be automatically set up in Eclipse. You can always update the project settings using the Maven plugin (Right Click -> Maven -> Update Project).

Project dependencies

All dependencies for maven projects are specified in the project's pom.xml. When building the project using maven, these dependencies will be automatically taken from the local maven repository (default: C:/User/username/.m2/repository) and downloaded from the remote repository if it is not available locally.

The imported projects (sdk, components and examples) depend on each other as shown below:

BaSyx Java Dependencies.PNG

This means basyx.components depends on basyx.sdk and basyx.examples depends on the two other projects. So if you make changes in e.g. basyx.sdk, you need to "install" it to the local repository using Maven before building components that depend on it.

Project installation

  1. Make sure that each project has a JDK selected as JRE System Library
    1. Window -> Preferences -> Java -> Installed JREs -> Enable the JDK
    2. -> Execution Environments -> JavaSE-1.8 -> Enable the JDK in the list of compatible JREs
  2. Install basyx.sdk
    1. Right click -> Run As -> Maven install
    2. Maven will download all required dependencies, run the tests and build and install the project into the local Maven repository
    3. You can ignore errors in the output coming from testing exceptions in unit tests
    4. If successful, you will see the message: [INFO] BUILD SUCCESS
  3. Prepare the components as described in Setting up the Components project
  4. Install basyx.components and basyx.examples
  5. Done

After installation build outputs are placed in the /target folder and installed in the local Maven repository.

Eclipse IDE configuration

Although the Eclipse IDE can handle the BaSyx projects, there are multiple settings that will make it easier to work with them. This is especially true, if you are working on hierarchical Maven projects as with basyx.components.

  • Enable a hierarchical Maven projects representation
    • Window -> Show View -> Project Explorer
    • Project Explorer View Menu (three dots in the top right corner of the view) -> Projects Presentation -> Hierarchical
  • Enable a hierarchical packages representation
    • Project/Package Explorer View Menu -> Package Presentation -> Hierarchical
  • Make use of working sets to organize multiple groups of projects
    • Project/Package Explorer View Menu -> Top Level Elements -> Working Sets
    • Project Explorer View Menu -> Select Working Set -> New...
    • Add a Java working set named e.g. "BaSyx" and add all basyx.* projects to it
    • Add another Java working set for e.g. your own projects
  • Prepare useful launch configurations
    • Right Click basyx.sdk project -> Run As -> Maven build..
    • Rename the launch configuration to e.g. "Install BaSyx SDK"
    • Enter "clean install" in "Goals:"
    • Click Apply and close the window
    • Repeat this for other run configurations (e.g. install components/examples...)
    • Click at the small, black down-arrow right next to the "Run As..."-icon (the white arrow in a green circle) in the toolbar
    • Organize Favorites... -> Add... -> Check "Install BaSyx SDK"
    • Click at the arrow next to the "Run As..."-icon again
    • Run your favorite launch configuration
  • Customize resource filters if necessary (if you would like to see e.g. .gitignore or .env files)
    • Project Explorer Filters & Customization (filter symbol in the top right corner of the view)
    • Uncheck .* resources in the list of Pre-set filters to be able to see .* files
    • Add own filters to hide specific files or folders again (e.g. .project, .classpath and .settings)


Final result:

BaSyxEclipseIDE.jpg

Further steps

The introductory examples are a good starting point to see how the SDK itself can be utilized.

Furthermore, the basyx.components project is built on top of the basyx.sdk and provides additional components. Among others you will also find components with predefined docker images inside.

There are extended basyx.examples that demonstrate various examples and use cases for both projects.

Also read the article about how to contribute to the open source code.

Troubleshooting

No compiler is provided

Error: When doing maven install, maven complains that no compiler could be found. 

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.1:compile (default-compile) on project basyx.sdk: Compilation failure
[ERROR] No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?
[ERROR] -> [Help 1]

Solution: This error is typically when maven is not able to find the installed JDK. To fix this for the Eclipse IDE, perform the following steps to add the installed JDK:

  • Navigate to Window -> Preferences -> Java -> Installed JREs
  • Add the JDK, if it is not already there. This can be done by the Add... button, selecting standard vm and selecting the JRE home to be the JDK folder
  • Select the JDK as default be ensuring that the box next to it is checked
  • Now, for each project the default JRE needs to be changed. This can be done by righ-clicking each project -> Preferences -> Java Build Path -> double click JRE System Library -> Select Workspace default JRE (jdk....)


If you are using maven from command line, this error can be fixed by ensuring that the JDK is added to the environment (e.g. PATH value on Windows).

HTTP tests failing

Error: Tests related to HTTP are failing. The console contains an error similar to 

SEVERE: Failed to initialize connector [Connector[HTTP/1.1-4001]]
... 
Caused by: java.net.BindException: Address already in use: bind
...

Solution: The reason for this error is that the port used by the HTTP tomcat server is already blocked. A common reason for this an already running tomcat instance. If you are using for example XMPP, it may occupy this port.

To fix this error, please close the application occupying the port.

Cannot find '[..]junit[..]' on project build path

Error: Can't execute the JUnit tests in Eclipse IDE due to missing entries in the build path 

Cannot find 'org.junit.platform.commons.annotation.Testable' on project build path.
JUnit 5 tests can only be run if JUnit 5 is on the build path.

Solution: As the error message says, JUnit is missing in the build path. To address this issue, add JUnit to the build path:

  • Right click project -> Build Path -> Configure Build Path
  • Click Add Library...
  • Select JUnit -> Next -> Make sure that JUnit5 is selected -> Finish
Retrieved from "https://wiki.eclipse.org/index.php?title=BaSyx_/_Download_/_Java_Setup&oldid=439100"

Back to the top