README

###############################################################################
# Copyright (c) 2000-2021 Ericsson Telecom AB
# All rights reserved. This program and the accompanying materials
# are made available under the terms of the Eclipse Public License v2.0
# which accompanies this distribution, and is available at
# https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html
###############################################################################

The intended audience of this README file are the Titan Eclipse plugins project developers.
This file describes the main steps to create the development environment for the Titan Eclipse plugins project.

----------------------------------------------------------------------
1. VERSION REQUIREMENTS
----------------------------------------------------------------------
Java 1.6 or higher, recommended: 1.7. To compile Titanium, Java 1.8 is required.
XText 2.7.3 (Prerequisite for antlr), available at http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/

ANTLR 4 SDK 0.3.5, available on Eclipse Marketplace
ANTLR Runtime 4.3, recommended: 4.3, available at Eclipse Orbit
Ant 1.9.2 or higher 
NOTE: Build will not work below 1.8 for sure!
Eclipse IDE for Eclipse Committers 4.7.0 or higher, recommended: 4.18.0
ANTLR 4.3
----------------------------------------------------------------------
2. SETTING UP ECLIPSE FOR TITAN PLUGIN DEVELOPMENT
----------------------------------------------------------------------
2.0 Download ANTLR 4.3.0 (and not higher!!!) from http://www.antlr.org/download/antlr-4.3-complete.jar for example to $HOME/antlr/.

2.1. Installing Eclipse plug-ins:
-Eclipse -> Help -> Install New Software...
  Contact all update sites during install to find required software -> ALWAYS SWITCH OFF (it can cause problems), except of installing XText!!!
-Install XText 2.7.3, ANTLR 4 SDK, ANTLR Runtime 4.3.0 and Ant according to 1. by filtering the product name.
/* ANTLR UI : http://antlreclipse.sourceforge.net/updates/ (not necessary???) */

2.1.1 After installing ANTLRs, go to Windows->Preferences-> ANTLR 4->Tools and 
-Under ANTLR Tool 
  set yes for "Tool is activated".
  select ANTLR 4.3 from the distribution list (or add $HOME/antlr/antlr-4.3-complete if is not in the list, see 2.0)
-Under Options
  type  into the "Directory" field:./src
  set the other fields no,no,yes,yes,"UTF-8"
2.1.2 Set the new JDK in Window -> Preferences -> Java -> Installed JREs

2.1.3 Set java compliance level 

Open Window -> Preferences -> Java -> Compiler
In the JDK Compliance box, set 'Compiler compliance level' to at least 1.6, otherwise there can be compile errors for some ternary operators.

2.1.4 Install additional dependencies
-Download and unzip the "Eclipse plug-ins x.x.x" from  https://projects.eclipse.org/projects/tools.titan/downloads
-Help->Install New Software->Add..-> Local : Set the folder of the uzipped project folder, e.g. TITAN_Designer_and_Executor_plugin-6.3.pl0/
-Select only the "Titan_external_dependencies" and "Titanium_external_dependencies" and install them


2.2. Importing Titan plug-in projects to Eclipse
Add "Git Repository Exploring" perspective
Add an existing local Git repository
  Choose titan.core and titan.EclipsePlug-ins, finish, e.g:
titan.EclipsePlug-ins: right click -> import projects... -> next -> finish
---------------------------------------------------------------------
3. Other recommended settings for TTCN3 developers in Eclipse
----------------------------------------------------------------------
3.1 Install Titan Eclipse Core from the Titan update site
https://projects.eclipse.org/projects/tools.titan/downloads

3.2 Set Perspective
Set TITAN Editing perspective or
Set TITAN Executing perspective


3.3 Window->Preferences->TITAN Preferences:
  TITAN installation path: <git repository>/titan/Install
  License file (optional, only if license checking is switched on): /home/<user id>/license_<license id>.dat
3.4 windows/customize perspective/commands groups availability -> "Launch" switch on

3.5 In Eclipse, on existing Titan Project: Project property (right click, properties) -> TITAN Project Property -> Internal makefile creation attributes (middle tab) ->
  Include source line info in C++ code (-l) -> switch on
  Add source line info for logging (-L) -> switch on
---------------------------------------------------------------------
4. SWITCHING ON TITAN LICENSE CHECKING AND USAGE STATISTICS SENDING
----------------------------------------------------------------------
By default Titan license checking and usage statistics sending are switched off. You can switch them on by running the following script:

<git repository>/titan_eclipse/license.sh

It modifies the source, you need to rebuild org.eclipse.titan.common plug-in project.

----------------------------------------------------------------------
5. BUILDING AND INSTALLING TITAN PLUG-INS FROM COMMAND LINE WITH ANT
----------------------------------------------------------------------
5.1. EXTERNAL JAR DEPENDENCIES
  ANTLR 4.3 SDK 0.3.5
    available at Eclipse Orbit
    http://download.eclipse.org/tools/orbit/downloads/drops/S20150519210750/
    NOTE: The drop version changes very often.
  antlr-4.3-complete.jar 
    available at: http://www.antlr.org/download/antlr-4.3-complete.jar
  junit.jar (JUnit4)

  These jars are needed by help.plugin to create pdf documentation
    PDF documentation can be created only inside Ericcson network
    doc2pdf.jar (optional, pdf will not be created if file not found at this location)
      For Ericsson users only: Download the plugin from http://ttcn.ericsson.se/download/third_party/ OR write to any contact person at Project Titan

  These jars are needed by titanium.plugin
    Google Guava 21.0 (com.google.guava)
      available at Eclipse Orbit
      http://download.eclipse.org/tools/orbit/downloads/drops/R20170307180635/repository
      
      NOTE: The drop version changes very often.
    edu.uci.ics.jung/jung-graph-impl-2.1.jar
    edu.uci.ics.jung/jung-visualization-2.1.jar
    edu.uci.ics.jung/jung-algorithms-2.1.jar
    edu.uci.ics.jung/jung-io-2.1.jar
      For Ericsson users only: Download the all-in-one package of Titan that contains it
        https://www.eclipse.org/downloads/download.php?file=/titan/TITAN_Designer_and_Executor_plugin-6.2.pl0.zip
      OR for users outside Ericsson: Write to any contact person on site https://projects.eclipse.org/projects/tools.titan and ask the jung.zip  
    org.apache.poi_3.9.0.v201405241750.jar
      available at Eclipse Orbit
      http://download.eclipse.org/tools/orbit/downloads/drops/S20150519210750/
      NOTE: The drop version changes very often.

5.2. BUILDING TITAN PLUG-INS FROM COMMAND LINE WITH ANT

Building must be run from <git repository>/titan_eclipse/automatic_build

In general building from command line is done with this command:
ant \
-f build_main.xml \
-D<environment value definition 1> \
...
-D<environment value definition n> \
-lib <JAR dependency 1> \
...
-lib <JAR dependency n> \
<target>

target can be one of the following:
  common.plugin
  designer.plugin
  executor.plugin
  help.plugin
  logviewer.plugin
  debug.plugin
  regressiontests.plugin
  titanium.plugin
  titanium.regressiontests.plugin
  updatesite.release
  updatesite.FOA
  updatesite.experimental
  updatesite.testing
  zip

Make sure, that the following environment variables are set to a valid directory/file:

JAVA_HOME
ECLIPSE_HOME
compiler.location: this is the titan project directory: <git repository>/titan
java6: a java6 executable
updatesite.experimental.location: output directory for experimental update site (optional)
updatesites.tmp.location: temporary output directory for experimental update site (optional)
zip.dir: output directory for zip package that contains all the plug-ins (optional)

These variables can be set by editing <git repository>/titan_eclipse/automatic_build/build_config.xml
and also in the command.

5.2.1 A working example with all of the dependencies (if all the values are set correctly, it will work with any target):

LIB_DIR_LOCAL=$HOME/lib
LIB_DIR_GIT=$HOME/git/titan_playground/jar
ant \
-f build_main.xml \
-DJAVA_HOME=$HOME/jdk/ \
-DECLIPSE_HOME=$HOME/eclipse/ \
-Dcompiler.location=$HOME/git/titan/ \
-Dantlr4.jar.location=${LIB_DIR_LOCAL}/antlr-4.3-complete.jar \
-Ddoc2pdf.jar=${LIB_DIR_GIT}/doc2pdf.jar \
-Djava6=$HOME/jdk/bin/java \
-lib ${LIB_DIR_GIT}/edu.uci.ics.jung/jung-graph-impl-2.1.jar \
-lib ${LIB_DIR_GIT}/edu.uci.ics.jung/jung-visualization-2.1.jar \
-lib ${LIB_DIR_GIT}/edu.uci.ics.jung/jung-algorithms-2.1.jar \
-lib ${LIB_DIR_GIT}/edu.uci.ics.jung/jung-io-2.1.jar \
-lib ${LIB_DIR_GIT}/com.google.guava_21.0.0.v20170206-1425.jar \
-lib ${LIB_DIR_LOCAL}/org.apache.poi_3.9.0.v201405241750.jar \
-lib ${LIB_DIR_GIT}/org.junit_4.11.0.v201303080030/junit.jar \
-Dupdatesite.release.location=result/update_site \
-Dupdatesite.FOA.location=result/FOA_update_site \
-Dupdatesite.experimental.location=result/experimental_update_site \
-Dupdatesite.testing.location=result/testing_update_site \
-Dupdatesites.tmp.location=result/eclipse_automatic_build/tmp_update_sites \
-Dzip.dir=result/zips/6.1.0.CRL_113_200_6_R1A \
zip

5.2.2. A working example with minimal requirements, with a target with few dependencies

ant \
-f build_main.xml \
-DJAVA_HOME=$HOME/jdk/ \
-DECLIPSE_HOME=$HOME/eclipse/ \
-Dantlr4.jar.location=$HOME/lib/antlr-4.3-complete.jar \
-Dcompiler.location=$HOME/git/titan/ \
designer.plugin

5.3. INSTALLING PLUG-INS TO ECLIPSE
The plug-in jars are created in result/plugins/ directory.
Copy these *.jar files to $ECLIPSE_HOME/plugins/ directory.

----------------------------------------------------------------------
6. RUNNING REGRESSION TEST(from Jenkins or from command line)
----------------------------------------------------------------------
6.1. Prerequisites:
  6.1.1. org.eclipse.titan.titanium plug-in is built
  6.1.2. The following plug-ins are present in eclipse/plugins directory in this structure
           edu.uci.ics.jung_2.1.0.20170405-1030/
             jung-graph-impl-2.1.jar
             jung-visualization-2.1.jar
             jung-algorithms-2.1.jar
             jung-io-2.1.jar
           com.google.guava_21.0.0.v20170206-1425.jar
           org.antlr.runtime_4.3.0.v201502022030.jar
           org.apache.poi_3.9.0.v201405241750.jar
  6.1.3. Titan jars are also copied to eclipse/plugins
         cp -f result/plugins/* ${ECLIPSE_INSTALLED}/plugins
  6.1.4. The folowing environemnt variables are set
         JAVA_HOME
         WORKSPACE
         TTCN3_LICENSE_FILE
         TEST_PROJ
         TARGET_WS

6.2. Running regression tests:
  Tests must be run from titan_eclipse/automatic_build
  This is a content of a script, that runs the tests
  
#!/bin/bash

# USAGE: run from git/titan_eclipse/automatic_build/
# Prerequisites: build_titan_eclipse_regressiontests_plugin.sh

set -e
set -o pipefail

JAVA_HOME=$HOME/jdk/
WORKSPACE=$HOME/git
TTCN3_LICENSE_FILE=$HOME/license.dat
TEST_PROJ=file://${WORKSPACE}/titan_eclipse
TARGET_WS=${WORKSPACE}/ws_test
echo "eclipse_ws: ${TEST_PROJ}"
ECLIPSE_INSTALLED=eclipse

# extract a fresh eclipse
tar -zxvf $HOME/install/eclipse-rcp-luna-SR2-linux-gtk.tar.gz ${ECLIPSE_INSTALLED}/

# copy required jars (5.1.2.)
cp -f -r $HOME/install/eclipse_plugins/* ${ECLIPSE_INSTALLED}/plugins

# copy titan jars to eclipse/plugins (5.1.3.)
cp -f result/plugins/* ${ECLIPSE_INSTALLED}/plugins

${ECLIPSE_INSTALLED}/eclipse \
-debug \
-noSplash \
-data ${TARGET_WS} \
-clean \
-application org.eclipse.titan.regressiontests.HeadlessRunner \
-workspace ${TEST_PROJ} \
-license ${TTCN3_LICENSE_FILE} \
-xml_out result.xml