SVAROG DEVELOPERS' GUIDE ======================== This guide is targeted for users of Ubuntu Linux 16.04 and it is meant to facilitate installation of developers' environment for Svarog, allowing for preparation and testing of application's JAR files. I. Preparation ---------------- 1. Download Svarog's repository from: git@gitlab.com:braintech/svarog2.git 2. Run (as root) script “install-dev-env.sh” from scripts catalogue (you should at least look at it before you run it). The script will install NetBeans IDE, as well as all dependencies required to develop Svarog, including Java JDK (e.g. OpenJDK 8 and OpenJFX). II. Generating JAR files -------------------------- ATTENTION: during the first compilation, maven will download a large number of Svarog's dependencies (libraries). Depending of your network connection, this process may take some time. In project's main directory, run mvn clean package whereas in case of minor changes "clean" may be omitted. The command will generate Svarog's runnable JAR file into directory svarog-standalone/target, as well as plugins' JAR files in separate directories PLUGIN-NAME/target. To run generated JAR, execute java -jar svarog-standalone/target/svarog-standalone-*.jar III. IDE configuration ---------------------- 1. Build Svarog from command line according to the instructions in section II. If you omit this point, NetBeans IDE will not be able to find all automatically required files and will display an error. 2. Run already installed application NetBeans, got into Tools → Plugins menu, open tab Settings and mark as checked all three available plugin sources. Go to Available Plugins, and after having refreshed the plugin list (Check for Newest) choose Maven from list and install it. NetBeans will ask to be restarted after this step. 3. You can now choose File → Open Projects… and navigate to the path of Svarog repository and/or subdirectory "svarog" inside it. Svarog consists of several connected Maven packages: * Svarog-top, which is the top-most project, which, when built, builds the entire Svarog with all dependencies * Svarog, which is the main part of Svarog Most of the source code of Svarog's main part is in directory svarog/src/main/java which is included in the project's CLASSPATH. It means that the hierarchy of subdirectories inside this directory directly corresponds to the structure of Java packages. Each source file contains directly one class, with the same name as the file. For example, svarog/src/main/java/org/signalml/app/SvarogApplication.java file contains the SvarogApplication class. The first line of this file defines the package, to which this class belongs: package org.signalml.app; IV. Working with translations ----------------------------- The first step is to generate *.pot files from Svarog's source code. It is done by executing mvn gettext:gettext in the "svarog" directory. The resulting *.pot file can be used to initialize a new translation by the use of "msginit" command. This will create an empty *.po (translation) file suited to the given language. These files should be edited either by hand or with the help of some GUI. Finished translation files (e.g. "pl.po") should be added to the directory svarog/src/main/resources/org/signalml/app/resource/i18n/ and will be automatically included in the JAR file. Also, every available language should be added to list LANGUAGES in file SvarogI18n.java. Translating help files, however, is mostly manual. Help files are stored in a versioned directory svarog/src/main/resources/org/signalml/help/ where the subdirectories (e.g. "en") mark the different language versions. To create the help files for another language, simply create a directory for a given language, and put the translations with the same names as original versions. V. Modifying Svarog version --------------------------- Svarog's version number is automatically created by Maven based on the most recent tags in git repository, as returned by git describe --tags with mvn versions:set -DgenerateBackupPoms=false -DnewVersion=$(git describe --tags) command (Which CI runs by itself). therefore, to create JAR with a new version number, it is necessary to: 1. Commit the changes and create a git tag with the new version number: git tag VERSION 2. You can now build the JAR file; it will have the new version number. VI. Creating ZIP file for github Releases ----------------------------------------- ZIP package consists of: a) Svarog's JAR file c) executable script run_svarog.sh d) an example signal wakeEEG.bin with corresponding XML file e) binary executables of MP5 and empi The most recent ZIP file can be used to provide all the files except a) and b). Afterwards, it is necessary to: * replace Svarog's JAR file, if it has changed * replace version number in run_svarog.sh * make a ZIP file with the new name (check if the name of the package corresponds to the package's main directory) VII. Known problems ------------------- It is known that sometimes, especially when working in virtual machine environment, any change of the display resolution or energy-saving transition (e.g. computer sleep/wakeup) triggers the following error: message: sun.awt.image.BufImgSurfaceData cannot be cast to sun.java2d.xr.XRSurfaceData class java.lang.ClassCastException This is a known bug in the current version of Java, and can be avoided by starting Svarog from JAR file with the command-line option -Dsun.java2d.xrender=false