README 11.5 KB
Newer Older
Elemer Lelik's avatar
Elemer Lelik committed
1
###############################################################################
Adam Knapp's avatar
Adam Knapp committed
2
# Copyright (c) 2000-2021 Ericsson Telecom AB
Elemer Lelik's avatar
Elemer Lelik committed
3
# All rights reserved. This program and the accompanying materials
4
# are made available under the terms of the Eclipse Public License v2.0
Elemer Lelik's avatar
Elemer Lelik committed
5
# which accompanies this distribution, and is available at
6
# https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html
Elemer Lelik's avatar
Elemer Lelik committed
7
###############################################################################
Adam Knapp's avatar
Adam Knapp committed
8
9
10
11

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.

12
----------------------------------------------------------------------
Elemer Lelik's avatar
Elemer Lelik committed
13
1. VERSION REQUIREMENTS
14
15
16
----------------------------------------------------------------------
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/
Elemer Lelik's avatar
Elemer Lelik committed
17

18
ANTLR 4 SDK 0.3.5, available on Eclipse Marketplace
19
ANTLR Runtime 4.3, recommended: 4.3, available at Eclipse Orbit
Elemer Lelik's avatar
Elemer Lelik committed
20
Ant 1.9.2 or higher 
21
NOTE: Build will not work below 1.8 for sure!
22
Eclipse IDE for Eclipse Committers 4.7.0 or higher, recommended: 4.18.0
23
24
25
26
27
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/.
Elemer Lelik's avatar
Elemer Lelik committed
28
29

2.1. Installing Eclipse plug-ins:
30
31
32
33
34
35
36
37
38
39
40
-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
41
  set the other fields no,no,yes,yes,"UTF-8"
42
43
2.1.2 Set the new JDK in Window -> Preferences -> Java -> Installed JREs

44
45
46
47
48
49
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
50
51
52
-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
Elemer Lelik's avatar
Elemer Lelik committed
53
54


55
56
57
58
59
60
61
62
63
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
Kristof Szabados's avatar
Kristof Szabados committed
64
https://projects.eclipse.org/projects/tools.titan/downloads
Elemer Lelik's avatar
Elemer Lelik committed
65

66
67
68
3.2 Set Perspective
Set TITAN Editing perspective or
Set TITAN Executing perspective
Elemer Lelik's avatar
Elemer Lelik committed
69

70
71

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

76
3.5 In Eclipse, on existing Titan Project: Project property (right click, properties) -> TITAN Project Property -> Internal makefile creation attributes (middle tab) ->
Elemer Lelik's avatar
Elemer Lelik committed
77
78
  Include source line info in C++ code (-l) -> switch on
  Add source line info for logging (-L) -> switch on
79
80
81
---------------------------------------------------------------------
4. SWITCHING ON TITAN LICENSE CHECKING AND USAGE STATISTICS SENDING
----------------------------------------------------------------------
Elemer Lelik's avatar
Elemer Lelik committed
82
83
84
85
86
87
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.

88
89
90
91
----------------------------------------------------------------------
5. BUILDING AND INSTALLING TITAN PLUG-INS FROM COMMAND LINE WITH ANT
----------------------------------------------------------------------
5.1. EXTERNAL JAR DEPENDENCIES
Kristof Szabados's avatar
Kristof Szabados committed
92
  ANTLR 4.3 SDK 0.3.5
Elemer Lelik's avatar
Elemer Lelik committed
93
    available at Eclipse Orbit
Elemer Lelik's avatar
Elemer Lelik committed
94
95
    http://download.eclipse.org/tools/orbit/downloads/drops/S20150519210750/
    NOTE: The drop version changes very often.
Kristof Szabados's avatar
Kristof Szabados committed
96
97
  antlr-4.3-complete.jar 
    available at: http://www.antlr.org/download/antlr-4.3-complete.jar
Elemer Lelik's avatar
Elemer Lelik committed
98
  junit.jar (JUnit4)
Elemer Lelik's avatar
Elemer Lelik committed
99

Elemer Lelik's avatar
Elemer Lelik committed
100
  These jars are needed by help.plugin to create pdf documentation
Elemer Lelik's avatar
Elemer Lelik committed
101
    PDF documentation can be created only inside Ericcson network
Elemer Lelik's avatar
Elemer Lelik committed
102
103
104
105
    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
Kristof Szabados's avatar
Kristof Szabados committed
106
107
    Google Guava 21.0 (com.google.guava)
      available at Eclipse Orbit
balaskoa's avatar
balaskoa committed
108
109
      http://download.eclipse.org/tools/orbit/downloads/drops/R20170307180635/repository
      
Kristof Szabados's avatar
Kristof Szabados committed
110
111
112
113
114
115
      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
balaskoa's avatar
balaskoa committed
116
        https://www.eclipse.org/downloads/download.php?file=/titan/TITAN_Designer_and_Executor_plugin-6.2.pl0.zip
Elemer Lelik's avatar
Elemer Lelik committed
117
118
      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
Elemer Lelik's avatar
Elemer Lelik committed
119
      available at Eclipse Orbit
Elemer Lelik's avatar
Elemer Lelik committed
120
121
      http://download.eclipse.org/tools/orbit/downloads/drops/S20150519210750/
      NOTE: The drop version changes very often.
Elemer Lelik's avatar
Elemer Lelik committed
122

123
5.2. BUILDING TITAN PLUG-INS FROM COMMAND LINE WITH ANT
Elemer Lelik's avatar
Elemer Lelik committed
124

Elemer Lelik's avatar
Elemer Lelik committed
125
Building must be run from <git repository>/titan_eclipse/automatic_build
Elemer Lelik's avatar
Elemer Lelik committed
126

Elemer Lelik's avatar
Elemer Lelik committed
127
In general building from command line is done with this command:
Elemer Lelik's avatar
Elemer Lelik committed
128
129
130
131
132
133
134
135
136
ant \
-f build_main.xml \
-D<environment value definition 1> \
...
-D<environment value definition n> \
-lib <JAR dependency 1> \
...
-lib <JAR dependency n> \
<target>
Elemer Lelik's avatar
Elemer Lelik committed
137
138
139
140
141
142
143
144
145
146
147

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
Elemer Lelik's avatar
Elemer Lelik committed
148
149
150
151
152
  updatesite.release
  updatesite.FOA
  updatesite.experimental
  updatesite.testing
  zip
Elemer Lelik's avatar
Elemer Lelik committed
153
154
155
156
157
158
159
160
161
162
163
164

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
Elemer Lelik's avatar
Elemer Lelik committed
165
and also in the command.
Elemer Lelik's avatar
Elemer Lelik committed
166

167
5.2.1 A working example with all of the dependencies (if all the values are set correctly, it will work with any target):
Elemer Lelik's avatar
Elemer Lelik committed
168
169
170
171
172

LIB_DIR_LOCAL=$HOME/lib
LIB_DIR_GIT=$HOME/git/titan_playground/jar
ant \
-f build_main.xml \
Elemer Lelik's avatar
Elemer Lelik committed
173
174
175
-DJAVA_HOME=$HOME/jdk/ \
-DECLIPSE_HOME=$HOME/eclipse/ \
-Dcompiler.location=$HOME/git/titan/ \
Elemer Lelik's avatar
Elemer Lelik committed
176
177
-Dantlr4.jar.location=${LIB_DIR_LOCAL}/antlr-4.3-complete.jar \
-Ddoc2pdf.jar=${LIB_DIR_GIT}/doc2pdf.jar \
Elemer Lelik's avatar
Elemer Lelik committed
178
-Djava6=$HOME/jdk/bin/java \
Kristof Szabados's avatar
Kristof Szabados committed
179
180
181
182
183
-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 \
Elemer Lelik's avatar
Elemer Lelik committed
184
185
186
187
188
189
190
-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 \
Kristof Szabados's avatar
Kristof Szabados committed
191
-Dzip.dir=result/zips/6.1.0.CRL_113_200_6_R1A \
Elemer Lelik's avatar
Elemer Lelik committed
192
193
zip

194
5.2.2. A working example with minimal requirements, with a target with few dependencies
Elemer Lelik's avatar
Elemer Lelik committed
195
196
197
198
199
200
201

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/ \
Elemer Lelik's avatar
Elemer Lelik committed
202
203
designer.plugin

204
5.3. INSTALLING PLUG-INS TO ECLIPSE
Elemer Lelik's avatar
Elemer Lelik committed
205
206
207
The plug-in jars are created in result/plugins/ directory.
Copy these *.jar files to $ECLIPSE_HOME/plugins/ directory.

208
209
210
211
212
213
----------------------------------------------------------------------
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
Kristof Szabados's avatar
Kristof Szabados committed
214
215
216
217
218
219
           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
Elemer Lelik's avatar
Elemer Lelik committed
220
221
           org.antlr.runtime_4.3.0.v201502022030.jar
           org.apache.poi_3.9.0.v201405241750.jar
222
  6.1.3. Titan jars are also copied to eclipse/plugins
Elemer Lelik's avatar
Elemer Lelik committed
223
         cp -f result/plugins/* ${ECLIPSE_INSTALLED}/plugins
224
  6.1.4. The folowing environemnt variables are set
Elemer Lelik's avatar
Elemer Lelik committed
225
226
227
228
229
230
         JAVA_HOME
         WORKSPACE
         TTCN3_LICENSE_FILE
         TEST_PROJ
         TARGET_WS

231
6.2. Running regression tests:
Elemer Lelik's avatar
Elemer Lelik committed
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
  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