Elexis 3 Core Repository

IMPORTANT Please employ the 3lexisFormatterProfile.xml as Eclipse default formatter prior to development and pull requests.
This accounts for all Elexis 3 related development.

Install latest build

Go to Jenkins-CI Builds.

Download and unzip the zip file for your machine.

Install Oracle java 1.8 from http://www.java.com/de/download/manual.jsp

Start the Elexis3 application.

Use Help..Install New Software to add the desired features from the elexis-3-base P2 repository.

Building

Maven based build

You need Java 1.8+. Maven >= 3.3. Then you should be able to generate the application and p2 update site using the following calls:

On Debian 10 (buster) there is no OpenJDK 8 available anymore. You can install it with the following steps

wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | sudo apt-key add
sudo add-apt-repository --yes https://adoptopenjdk.jfrog.io/adoptopenjdk/deb
sudo apt-get update && sudo apt-get install adoptopenjdk-8-hotspot
sudo update-alternatives --config java # select adoptopenjdk8
java --version # should now show a Java 8 version

git clone https://github.com/elexis/elexis-3-core
mvn -V clean verify -Dtycho.localArtifacts=ignore -DskipTests

Explanation of the used options

• -V: emits version of Java, Maven, GUI-Toolkit, Architecture. Handy when you ask a problem
• clean: Build everything from scratch
• verify: Compile, test and build a P2-site including products. But does NOT install maven artefacts
• -Dtycho.localArtifacts=ignore: Do not use any locally built maven artefacts
• -DskipTests: Skip unit tests (Use it only if you want to speed up the build)
• —quiet: Used for travis builds to generate Quiet output – only show errors. Without it the log would bee too long and make the travis-build fail.

It will be built for your OS/Window-System/Architecture combination. You will find the executables under ch.elexis.core.p2site/target/products/ch.elexis.core.application.ElexisApp/*/*/*

Note: This will fail in MacOSX. Build instructions for Mac:

Install Homebrew
brew install homebrew/versions/maven30
git clone https://github.com/elexis/elexis-3-core
mvn clean install -DskipTests

Continuos Intergration builds

We use Travis-CI to ensure that our build system works using a well documented environment. The status for the different branches can be founde under Travis-CI elexis-3-core

The downloads found under http://download.elexis.info/elexis/ are produced by jobs running via the Medelexis GitLab

Building via Eclipse IDE

If you want a complete development environment, try Oomph

Eclipse IDE-Preferences

We recommend (and if you want to submit patches, you have to respect) the following settings in the Eclipse IDE, reachabel via Window..Preferences:

• General..Workspace
  • Select UTF-8 as “Textfile encoding”
  • Select UNIX as “New text file line delimiter”
• Java..Code Style..Formatter
  • Click on “Import..” and select the 3lexisFormatterProfile.xml from the root directory of the elexis-3-core checkout
  • Select “3lexis Formatter” as “Active Formater”
• Java..Editor..Save Action
  • Select: Perform the selected actions on save
  • Do NOT select: Format source code
  • Select: Organize imports
  • Do NOT select: Additional actions
• Maven..Errors/Warning
  • Set “Plugin execution not covered by lifecycle configuration” to “Ignore”

Submitting patches

To submit patches you have to

• Fork our github repository to your personal account
• Clone this repository on your devevelopment machine
• Create a new branch (eg. git checkout -b my_branch)
• Commit your change (eg. @git commmit -m “My cool changes”)
• Push it to your account (eg. git push --set-upstream origin my_branch)
• Go to your github repository and create a pull requests by clicking on the greeen button “Compare & pull request”
• Review your changes. There should be only the lines that contribute to the problem. If you have too many changes look at the remarks about Eclipse IDE-Preferences

Developer Overview

This repository hosts the core Elexis 3. It consists of the following plug-ins and features:

• ch.rgw.utility Utilities required to drive Elexis.
• ch.elexis.core Core concepts and interface definitions.
• ch.elexis.core.data Core persistence and functionality packages and classes.
• ch.elexis.core.console.application Headless Elexis application.
• ch.elexis.core.ui User Interface dependent portions. Dependent on Eclipse RCP 3.×.
• ch.elexis.core.application Core UI Elexis Application.

• ch.elexis.core.releng Release Engineering specific parts (Build Target, 3rd party …)

• ch.elexis.core.logging Plug-In for starting ch.qos.logback logging (via slf4j interface)
• ch.elexis.core.logging.feature Feature for logging and Felix-gogo console
• ch.elexis.core.logging.default_configuration Default logging configuration (logback.xml)

• ch.elexis.core.ui.icons Plug-In for central icon management.
• ch.elexis.core.ui.contacts Plug-In for contact management.
• ch.elexis.core.ui.laboratory Plug-In for laboratory related tasks.
• ch.elexis.core.ui.p2 Plug-In to realize client side p2 update tasks
• ch.elexis.core.common.feature Headless Core Feature.
• ch.elexis.core.ui.feature Core UI Feature.
• ch.elexis.core.application.feature Core Application Feature.

For details about the resp. plug-ins/features switch to the respective directory. The plug-ins and features
are contained and inter-dependent as follows:

Guidelines for developing a new plugin/feature

New plugins and features should follow the E4 (eclipse 4) guideline. A good tutorial is from Lars Vogel

The ch.elexis.core.ui.tasks follows new e4 implementation rules. Analyse its working and adapt it to your problem.

Generate Javadoc

Elexis uses Javadoc go documents its API interface. The Eclipse IDE offers built-in support for reading the javadoc for a given method or class and provides also helper to generate it.

This is accomplished by calling mvn -DforceContextQualifier=javadoc javadoc:javadoc. It generates a complete javadoc. The generated output can be search at target/site/apidocs/index.html.

Even when theses javadoc are not used often, they provide a convenient way to get an overview over methods, packages, etc.

Check whether Javadocs are correctly generated

We use checkstyle to generate Javadoc. Use the following command line:

mvn checkstyle:checkstyle-aggregate site:site

This generates an browsable HTML file target/site/index.html. The links to the modules do not work, unless you call afterwards ch.elexis.core.releng/cleanup_after_checkstyle.rb, a small ruby script which generates a few missing links (not supported on Windows).

It uses the rules defined in ch.elexis.core.releng/checkstyle.xml to generate warnings for missing Javadoc. For each project, there exists an error report. E.g target/site/ch.rgw.utility/checkstyle.html. An aggregated, overall statistics can be found under target/site/checkstyle-aggregate.html

If you want to add even more checks, look at ch.elexis.core.releng/checkstyle_full.xml. Adding new checks should be discussed on the developers mailing list.

Updating all versions for a newer ID

We do this for all new major version, eg. 3.3 → 3.4. See also http://www.mojohaus.org/versions-maven-plugin/usage.html

Steps to follow are:

• Update the version in master pom.xml
• Run mvn org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion=3.9.0-SNAPSHOT
• Test and check whether the old version number is still present in other files.

Localisation / translation

We are in a transition phase to use trema and support french and italien versions of elexis. For details see l10n.md