4-managing_projects.adoc 65.2 KB
Newer Older
1
= Managing Projects
Kristof Szabados's avatar
Kristof Szabados committed
2
:toc:
balaskoa's avatar
balaskoa committed
3
:toclevels: 4
Kristof Szabados's avatar
Kristof Szabados committed
4
5
6
7
:figure-number: 26

In the TITAN Designer plug-in, you work with projects. A project usually represents the complex procedure of developing a test suite and creating the executable from this test suite.

8
9
10
To manage these projects, it is advised to use the Project Explorer view provided by Eclipse.
Other views, like the Navigator view, can also be used; however, beginners shall take special care as those views might provide completely different data.
For example, by default the Project Explorer does not show the `.TITAN_properties` file, while the Navigator view does.
balaskoa's avatar
balaskoa committed
11
The role of the `.TITAN_properties` will be explained later in section <<Saving and Loading Project Properties>>
Kristof Szabados's avatar
Kristof Szabados committed
12
13
14
15
16

For advanced users it is advised to take also a look on the other navigators, as they might be better in solving some minor problems.

Projects that are handled by the TITAN Designer plug-in will be referred to as TITAN projects although in the Eclipse terminology they should be called TITAN natured projects. More information on natures can be found in the Eclipse documentation.

17
From the release of TITAN version 6.6.0 the Designer supports 2 types of TITAN Projects:
Adam Knapp's avatar
Adam Knapp committed
18
* TITAN {cpp} Project: is the original way of working, supporting a build system that translates TTCN-3 and ASN.1 modules using C as the intermediate language.
19
20
21
22
23
* TITAN Java Project: if a way of working that supports a build system, that translates TTCN-3 and ASN.1 modules using Java as the intermediate language.

When not specified explicitly the expression "TITAN Project" might refer to both modes.
As they only differ in a few settings and their way of building, most of the advanced editing features will work exactly the same way on both project types.

balaskoa's avatar
balaskoa committed
24
[[creating-a-new-titan-project]]
Adam Knapp's avatar
Adam Knapp committed
25
== Creating a New TITAN {cpp} Project
Kristof Szabados's avatar
Kristof Szabados committed
26
27
28

Using the TITAN Designer, new TITAN projects can be created following these three steps:

Adam Knapp's avatar
Adam Knapp committed
29
1. Select *File / New / TITAN Project ({cpp})* from the main menu (see <<new-resources-menu, the next figure>>).(The corresponding TITAN shortcut must be enabled, see section <<2-getting_started.adoc#_enabling_titan_shortcuts,Enabling TITAN Shortcuts>>)
Kristof Szabados's avatar
Kristof Szabados committed
30
+
balaskoa's avatar
balaskoa committed
31
[[new-resources-menu]]
Kristof Szabados's avatar
Kristof Szabados committed
32
33
image::images/4_F26.png[title="New resources menu"]

Adam Knapp's avatar
Adam Knapp committed
34
2. Enter project name and location (see <<first-page-of-the-new-titan-project-wizard, the next figure>>).
35
By default, the project will be created in the directory of the workbench.
balaskoa's avatar
balaskoa committed
36
It is not recommended to select a path that contains special characters (like the spaces in "Documents and Settings").
Kristof Szabados's avatar
Kristof Szabados committed
37
+
balaskoa's avatar
balaskoa committed
38
[[first-page-of-the-new-titan-project-wizard]]
Adam Knapp's avatar
Adam Knapp committed
39
image::images/4_F27.png[title="First page of the new TITAN Project ({cpp}) wizard"]
Kristof Szabados's avatar
Kristof Szabados committed
40

41
3. At this point you can either select either *Finish* or *Next*.
Kristof Szabados's avatar
Kristof Szabados committed
42
43
44
+
If you select *Finish,* the new TITAN project will be created immediately.
+
balaskoa's avatar
balaskoa committed
45
If you select *Next,* you can customize some project properties (see the next figure): the name of the folder containing the sources, and the name of the working directory (containing the generated binaries).In case the project to be created will need a long time to set up, before it can be used it is possible to set that the source folder should be generated as excluded from build.
Kristof Szabados's avatar
Kristof Szabados committed
46

Adam Knapp's avatar
Adam Knapp committed
47
image::images/4_F28.png[title="Second page of the new TITAN Project ({cpp}) wizard"]
Kristof Szabados's avatar
Kristof Szabados committed
48
49
50

The final project is only created when you select *Finish*.

balaskoa's avatar
balaskoa committed
51
Now the new TITAN project (called `project1` on the figures) and the two directories are created and are listed in the Project Explorer. The TITAN logo is displayed to the left of the project name (provided that the TITAN decorator is enabled, see <<2-getting_started.adoc#_enabling_titan_decorations, here>>). TITAN projects will generally be decorated like this.
Kristof Szabados's avatar
Kristof Szabados committed
52
53
54
55
56

image::images/4_F29.png[title="Example created project"]

The projects created with this wizard differ from other "General" projects in that the TITAN nature and the TITAN builder (responsible for building the executable) are automatically set on them.

57
58
Once the new project is created the property page of that project will be displayed, so that it can be configured immediately. For more information on project properties please refer to section <<_setting_project_properties,Setting Project Properties>>

balaskoa's avatar
balaskoa committed
59
[[creating-a-new-titan-java-project]]
60
61
62
63
== Creating a New TITAN Java Project

Using the TITAN Designer, new TITAN Java projects can be created following these three steps:

Adam Knapp's avatar
Adam Knapp committed
64
1. Select *File / New / TITAN Project (Java)* from the main menu (see <<new-resources-menu, the next figure>>).(The corresponding TITAN shortcut must be enabled, see section <<2-getting_started.adoc#_enabling_titan_shortcuts,Enabling TITAN Shortcuts>>)
65

Adam Knapp's avatar
Adam Knapp committed
66
2. Enter project name and location (see <<first-page-of-the-new-titan-project-wizard, the next figure>>).
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
By default, the project will be created in the directory of the workbench.
It is not recommended to select a path that contains special characters (like the spaces in "Documents and Settings").

3. At this point you can select either *Finish*.
+
If you select *Finish,* the new TITAN Java project will be created immediately.

The final project is only created when you select *Finish*.

Now the new TITAN Java project (called `project1` on the figures) and the 4 directories are created and are listed in the Project Explorer. The TITAN logo is displayed to the left of the project name (provided that the TITAN decorator is enabled, see <<2-getting_started.adoc#_enabling_titan_decorations, here>>). TITAN projects will generally be decorated like this.

image::images/4_F29.png[title="Example created project"]

The projects created with this wizard differ from other "General" projects in that the TITAN nature and the TITAN Java builder (responsible for building the executable) are automatically set on them.

Once the new project is created the property page of that project will be displayed, so that it can be configured immediately. For more information on project properties please refer to section <<_setting_project_properties,Setting Project Properties>>
Kristof Szabados's avatar
Kristof Szabados committed
83

84
== Adding Directories to the Project
Kristof Szabados's avatar
Kristof Szabados committed
85

86
Directories can be added to projects in the following way:
balaskoa's avatar
balaskoa committed
87
*right click* the project where the directory should be added to and select *New / Folder* (see the next figure).
Kristof Szabados's avatar
Kristof Szabados committed
88

balaskoa's avatar
balaskoa committed
89
90
[[new-menu]]
image::images/4_F30.png[title="New menu"]
Kristof Szabados's avatar
Kristof Szabados committed
91

balaskoa's avatar
balaskoa committed
92
In the <<new-folder-window,New Folder window>> there is a possibility to set:
Kristof Szabados's avatar
Kristof Szabados committed
93
94
95
96
97
98
99
100
101
102
103

* where the new folder will be placed;

* how the new folder will be called;

* whether the folder is a virtual folder ("Folder is not located in the file system (Virtual Folder)" see Eclipse general documentation)

* whether only a link to an existing folder will be established ("Link to alternate location (Linked Folder)") (This will appear in the Project Explorer just like a normal folder, but is actually a link to a folder).
+
NOTE: linked folders are handled entirely by Eclipse; no additional resource will be placed in the projects directory.

balaskoa's avatar
balaskoa committed
104
[[new-folder-window]]
Kristof Szabados's avatar
Kristof Szabados committed
105
106
image::images/4_F31.png[title="New folder window"]

balaskoa's avatar
balaskoa committed
107
Once the new folder created, you shall see something like shown on the <<new-file-created,Figure>>  (without the filename file1.ttcn).
Kristof Szabados's avatar
Kristof Szabados committed
108

balaskoa's avatar
balaskoa committed
109
[[new-file-created]]
Kristof Szabados's avatar
Kristof Szabados committed
110
111
image::images/4_F32.png[title="New file created"]

112
== Adding Files to the Project
Kristof Szabados's avatar
Kristof Szabados committed
113
114
115

There are two ways to add files to a project. The first one, using wizards, is the recommended way to do it.

116
=== Using Wizards to Add Files to the Project
Kristof Szabados's avatar
Kristof Szabados committed
117

118
119
Wizards are available to create some of the TITAN modules
footnote:[The terms "modules" and "files" are used interchangeably in this section.] (TTCN-3, ASN.1 and Configuration files).
balaskoa's avatar
balaskoa committed
120
This functionality is reached by selecting *File / New* (see figure <<new-resources-menu,New resources menu>>).
Kristof Szabados's avatar
Kristof Szabados committed
121

Adam Knapp's avatar
Adam Knapp committed
122
NOTE: In the Project Explorer view, the wizards "TTCN-3 Module", "ASN.1 Module" and "Configuration file" can be also reached by **right click**ing the content area and selecting *New / Other…*.
Kristof Szabados's avatar
Kristof Szabados committed
123
124
125

In the example below, the "TTCN-3 Module" wizard is shown. The wizard is launched by selecting *File / New / TTCN3 Module*.

balaskoa's avatar
balaskoa committed
126
[[first-page-of-the-new-ttcn3-module-wizard]]
Kristof Szabados's avatar
Kristof Szabados committed
127
128
image::images/4_F33.png[title="First page of the New TTCN3 Module wizard"]

balaskoa's avatar
balaskoa committed
129
On the <<first-page-of-the-new-ttcn3-module-wizard,First page of the New TTCN3 Module wizard>> the correctness of the new module name is verified. The file extension is checked against the type of module being created. If the extension is not set, it is automatically appended when the file is created (the defaults are: `ttcn`, `asn` and `cfg` for the respective wizards). The on-the-fly checker, if it has enough data collected, verifies that a module name is unique in the project (right now this only works for TTCN-3 modules).
Kristof Szabados's avatar
Kristof Szabados committed
130

Adam Knapp's avatar
Adam Knapp committed
131
On the second page of the wizard there are a checkbox and a combo box:
Kristof Szabados's avatar
Kristof Szabados committed
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

image::images/4_F34.png[title="Second page of the New TTCN3 Module wizard"]

* *Generate as excluded from build*.
+
If this checkbox is selected the file to be created is excluded from the build; that is, the build system will not try to build it instantly. It is advised to create new modules with this option turned on to avoid build errors until the code logic is complete.

* **Generate with module with this content**
+
This Combo box contains three options: Empty module name, Module name and empty body and Module skeleton. As the names suggest, the generated file will contain empty module or module containing only module name and empty body or a module skeleton.

NOTE: Configuration files may also be created with a skeleton.

NOTE: The filename will be used as the module name in the inserted module.

147
=== Manually Adding Files to the Project
Kristof Szabados's avatar
Kristof Szabados committed
148

149
150
151
Manual file addition has moderate means to set file properties compared to the wizard (see <<_using_wizards_to_add_files_to_the_project, here>>).
On the other hand, some files can only be inserted into projects manually;
namely the following way: *right click* on the project (or on a folder in the project) where the file should be included and select *New / File*
balaskoa's avatar
balaskoa committed
152
(see <<new-menu,Figure New menu>> above).
Kristof Szabados's avatar
Kristof Szabados committed
153

balaskoa's avatar
balaskoa committed
154
On the <<new-file,New File>> window there is a possibility to set:
Kristof Szabados's avatar
Kristof Szabados committed
155
156
157
158
159

* where the new file should be placed;

* how the new file will be called;

balaskoa's avatar
balaskoa committed
160
* whether only a link to an existing file will be established (under selection menu *Advanced>>*)
Kristof Szabados's avatar
Kristof Szabados committed
161
162
163
164
165
+
(This will appear in the Project Explorer just like a normal file, but is actually a link to a file).

NOTE: Linked files are fully handled by Eclipse; no additional resource will be placed in the projects directory.

balaskoa's avatar
balaskoa committed
166
[[new-file]]
Kristof Szabados's avatar
Kristof Szabados committed
167
168
image::images/4_F35.png[title="New file"]

169
Once the file created, you should see something like shown on <<new-file-created,New file created>>.
balaskoa's avatar
balaskoa committed
170
You have created a project, added a folder and a file to it.
Kristof Szabados's avatar
Kristof Szabados committed
171

Adam Knapp's avatar
Adam Knapp committed
172
NOTE: Files handled by the TITAN Designer plug-in also have the TITAN logo to the left of their names, just like projects do. Decorators used by TITAN Designer are described <<2-getting_started.adoc#_enabling_titan_decorations, here>>.
Kristof Szabados's avatar
Kristof Szabados committed
173

174
== Setting Project Properties
Kristof Szabados's avatar
Kristof Szabados committed
175
176
177

Project properties for local and remote build are set in two separate windows.

178
=== Build Configurations
Kristof Szabados's avatar
Kristof Szabados committed
179

180
Our projects support to have several "build configurations" or "sets of build settings".
balaskoa's avatar
balaskoa committed
181
This means that it is possible to create sets of build settings, which can be switched to in an easy and consistent way.
Kristof Szabados's avatar
Kristof Szabados committed
182

183
184
One excellent usage tip would be, to have "Development" and "Release" modes for projects.
Debug could have settings tuned for very fast compilation, at the expense of generating slowly executing code:
Adam Knapp's avatar
Adam Knapp committed
185
This way development could be speed up considerably while only loosing features not relevant at development time.
186
187
Release mode could be fine-tuned for runtime performance, at the cost of increase in build times.
This way once the development is over, and the product is ready to be tested/investigated/used,
balaskoa's avatar
balaskoa committed
188
the build system could be set to use the most aggressive optimization methods available.
Kristof Szabados's avatar
Kristof Szabados committed
189

190
[.underline]#Changing the active build configuration# is available on all project preference pages, in the upper part of the window,
balaskoa's avatar
balaskoa committed
191
as seen on Figure <<makefile-creation-attributes,Makefile creation attributes>>.
Kristof Szabados's avatar
Kristof Szabados committed
192
193
194
195
196
197
198
199
200
201

Using the drop-down control, one can select and switch to any already existing build configuration created for the actual project.

Pushing the *Manage Configurations* button a new window will pop-up.

image::images/4_F36.png[title="Manage configurations"]

On this window it is possible to create new configurations, delete existing ones, or simply rename one.

[NOTE]
202
====
Kristof Szabados's avatar
Kristof Szabados committed
203
204
205
206
207
Even though the settings of the Default configuration can be changed it cannot be deleted or renamed, the existence of this configuration is needed to be forward compatible with older versions of our tools.

[.underline]#The build configuration name cannot contain whitespace character.#

[.underline]#The visible build configuration settings always refer to the active build configuration.# To change a build configuration at first it shall be selected as active configuration, then some of the settings described below shall be modified then the settings shall be saved by pushing the button "Apply" or "OK".
208
====
Kristof Szabados's avatar
Kristof Szabados committed
209
210

[[setting-the-local-build-properties-of-a-project]]
211
=== Setting the Local Build Properties of a TITAN Project
Kristof Szabados's avatar
Kristof Szabados committed
212

balaskoa's avatar
balaskoa committed
213
To set the project properties for local build first *right click* the project and select *Properties* then select *<<makefile-creation-attributes,TITAN Project Property>>*.
Kristof Szabados's avatar
Kristof Szabados committed
214

balaskoa's avatar
balaskoa committed
215
On the main window three options can be set:
Kristof Szabados's avatar
Kristof Szabados committed
216

Adam Knapp's avatar
Adam Knapp committed
217
* **Automatic Makefile management**
Kristof Szabados's avatar
Kristof Szabados committed
218
+
Adam Knapp's avatar
Adam Knapp committed
219
configures the TITAN Designer to automatically manage the `Makefile`.
Kristof Szabados's avatar
Kristof Szabados committed
220
+
221
NOTE: disabling the automatic `Makefile` management makes it the users’ responsibility to update the file when it is needed.
Adam Knapp's avatar
Adam Knapp committed
222
In case it is unchecked, the buttons on the *Makefile creation attributes* tab and on the *Internal makefile creation attributes* tab will be disabled. +
Kristof Szabados's avatar
Kristof Szabados committed
223
224
Default: selected.

Adam Knapp's avatar
Adam Knapp committed
225
* **Generate the Makefile using Eclipse internal Makefile generator**
Kristof Szabados's avatar
Kristof Szabados committed
226
+
Adam Knapp's avatar
Adam Knapp committed
227
228
figures the TITAN Designer to use its own `Makefile` generator instead of the one provided by TITAN. +
Default: selected.
Kristof Szabados's avatar
Kristof Szabados committed
229

Adam Knapp's avatar
Adam Knapp committed
230
* **Don’t use symbolic links in the build process**
Kristof Szabados's avatar
Kristof Szabados committed
231
+
Adam Knapp's avatar
Adam Knapp committed
232
figures the internal Makefile generator and the builder to drive the build process in a way that does not requires the creation of symbolic links.
Kristof Szabados's avatar
Kristof Szabados committed
233
+
Adam Knapp's avatar
Adam Knapp committed
234
NOTE: This option requires the internal Makefile generation option to be set. +
Kristof Szabados's avatar
Kristof Szabados committed
235
Default: selected.
balaskoa's avatar
balaskoa committed
236
[[makefile-creation-attributes]]
Kristof Szabados's avatar
Kristof Szabados committed
237
238
239
image::images/4_F37.png[title="Makefile creation attributes"]

[[the-makefile-creation-attributes-tab]]
240
==== The Makefile Creation Attributes tab
Kristof Szabados's avatar
Kristof Szabados committed
241

balaskoa's avatar
balaskoa committed
242
Information from the *Makefile creation attributes* tab is transferred to the `Makefile` generator program. The options of the `Makefile` generator are described in the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>.
Kristof Szabados's avatar
Kristof Szabados committed
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265

The following Makefile creation attributes are set on this tab:

* **Use absolute pathnames in the Makefile**
+
Specifies whether the generated `Makefile` should contain absolute or relative pathnames. Default: not selected.

* **Generate Makefile for GNU make**
+
If checked, a GNU `Makefile` will be generated during the building process. The gnu make utility can handle complex `Makefile` that the Solaris make cannot. Default: selected.

* **Generate Makefile with incrementally refreshing dependency**
+
If checked and GNU make style `Makefile` generation is also set, the generated `Makefile` will use GCC’s dependency tracking instead of makedepend. For more information, please refer <<6-building_the_project.adoc#creating-dependencies, here>>. Default: selected.

* **Link dynamically**
+
If checked, all files of the project will be compiled with `–fPIC` and for each (static) object, a new shared object will be created. Then, these shared objects will be linked to the final executable instead of the (static) objects. For more information, pros and cons etc. consult the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>. Default: not selected.

* **Generate Makefile for use with the function test runtime**
+
Titan has two runtime environments: one for function testing and one for load testing. The function test runtime provides more runtime checks and supports some specific features, like the negative testing feature, that is not available in the load test runtime. Therefore, for projects aiming functional testing, it is also advised to check the "generate `Makefile` for use with the function test runtime" checkbox. Default: not selected
+
balaskoa's avatar
balaskoa committed
266
NOTE: all dependent projects ("Project References" in Eclipse's term) shall use the same Titan runtime.
Kristof Szabados's avatar
Kristof Szabados committed
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288

* **Generate Makefile for single mode**
+
If checked, the executable will be built for single mode execution. Only one test component is allowed in single test mode. In parallel mode, on the other hand, several components can be used. Default: not selected.

* **Code splitting**
+
Configures how the generated code should be organized: *none*, *type*, *number*. By default it is set to be: *none*.

* **Default target**
+
Configures the default target of the generated `Makefile`:
+
- *Executable:* Executable test suite
+
- *Library:* Library archive

* **Name of the target executable**
+
The path of the executable to be built including the name of the file. This setting will be written into the `Makefile` generated by the builder and will also be used for execution. If it is not set, the executable will be generated in the working directory having the name of the project.

[[the-internal-makefile-creation-attributes-tab]]
289
==== The Internal Makefile Creation Attributes Tab
Kristof Szabados's avatar
Kristof Szabados committed
290
291
292

image::images/4_F38.png[title="Internal makefile creation attributes"]

balaskoa's avatar
balaskoa committed
293
On the Internal makefile creation attributes tab the options to be generated into the `Makefile` can be set. To change the value of an element it must be selected. Depending on the element selected on the left side, the right hand side of the tab will contain different options.
Kristof Szabados's avatar
Kristof Szabados committed
294
295
296
297
298

. TTCN-3 Preprocessor
+
image::images/4_F39.png[title="TTCN-3 preprocessor"]
+
Adam Knapp's avatar
Adam Knapp committed
299
On the TTCN-3 Preprocessor page it is possible to specify the preprocessor tool used to pre-process the `.ttcnpp` and `.ttcnin`.
Kristof Szabados's avatar
Kristof Szabados committed
300
301
302
+
This will be applied to the *CPP* macro. By default it is set to be: *cpp*
+
Adam Knapp's avatar
Adam Knapp committed
303
The pre-processing of `.ttcnpp` and `.ttcnin` files is the very first step of the build process, as the compiler is not able to analyze these file formats.
Kristof Szabados's avatar
Kristof Szabados committed
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326

. TTCN-3 Preprocessor Symbols
+
image::images/4_F40.png[title="TTCN-3 Preprocessor symbols"]
+
On the symbols page it is possible to specify the list of symbols that should be defined and the list of symbols that should be undefined when the TTCN-3 pre-processor tool is executed.
+
These lists of options are applied to the *CPPFLAGS_TTCN3* macro (only present if pre-processable files are used in the project). By default both lists are empty.

. TTCN-3 Preprocessor Included Directories
+
image::images/4_F41.png[title="TTCN-3 Preprocessor include directories"]
+
On the included directories page, it is possible to specify the list of directories where the TTCN-3 pre-processor can look for included files.
+
The list of options is applied to the *CPPFLAGS_TTCN3* macro (only present if pre-processable files are used in the project). By default the list is empty.

. TITAN Flags
+
image::images/4_F42.png[title="TITAN Flags"]
+
On the TITAN flags page, it is possible to specify the flags TITAN should be called with when compiling the TTCN-3 and ASN.1 files.
+
327
The options will be applied to the *COMPILER_FLAGS* macro. By default only the *Include source line info in {cpp} code* and *add source line info for logging* options are set.
Kristof Szabados's avatar
Kristof Szabados committed
328
329
330
+
NOTE: The flag responsible for function or load test runtime generation is not set here, but on the Makefile creation attributes (as that flag is handled by the Eclipse external `makefile` generator too).
+
331
332
333
NOTE: The flag `Enable object oriented programming - OOP  (-k)` only controls the makefile generator and the compiler. 
Syntactic and semantic analyser do not support the OOP features yet.
+
balaskoa's avatar
balaskoa committed
334
For more information on the meanings of these options please refer to section 5.1 of the TITAN Programmer’s Technical Reference guide <<12-references.adoc#_4, [4]>>.
335
+
Kristof Szabados's avatar
Kristof Szabados committed
336
337
338
339
. Preprocessor
+
image::images/4_F43.png[title="Preprocessor"]
+
Adam Knapp's avatar
Adam Knapp committed
340
The Preprocessor page only functions as reminder to the fact, that the generated `Makefile` uses the same tool for pre-processing the `.ttcnpp`, `.ttcnin` and C/{cpp} files.
Kristof Szabados's avatar
Kristof Szabados committed
341
342
343
344
345

. Preprocessor Symbols
+
image::images/4_F44.png[title="Preprocessor symbols"]
+
346
On the preprocessor symbols page, it is possible to specify the list of symbols that should be defined and the list of symbols that should be undefined when the C/{cpp} pre-processor tool is executed.
Kristof Szabados's avatar
Kristof Szabados committed
347
348
349
350
351
352
353
354
355
+
These lists of options are applied to the *CPPFLAGS* macro.By default both lists are empty.
+
NOTE: There are a few symbols that are not displayed here, but are generated into the `Makefile`. These symbols are required for proper operation.

. Preprocessor Included Directories
+
image::images/4_F45.png[title="Preprocessor include directories"]
+
356
On the included directories page, it is possible to specify the list of directories where the C/{cpp} pre-processor can look for included files.
Kristof Szabados's avatar
Kristof Szabados committed
357
358
359
360
361
+
The list of options is applied to the *CPPFLAGS* macro. By default the list is empty.
+
NOTE: Some directories (like the include directory of TITAN) are not displayed here, but are generated into the `Makefile`. They are required for proper operation.

362
. C/{cpp} Compiler
Kristof Szabados's avatar
Kristof Szabados committed
363
+
364
image::images/4_F46.png[title="C/{cpp} compiler"]
Kristof Szabados's avatar
Kristof Szabados committed
365
+
366
A C/C\++ compiler tool used to process the generated and the user provided C/{cpp} files can be specified on the C/{cpp} compiler page.
Kristof Szabados's avatar
Kristof Szabados committed
367
368
369
+
This will be applied to the *CXX* macro. By default it is set to be: *g++*

370
. C/{cpp} Compiler Optimization
Kristof Szabados's avatar
Kristof Szabados committed
371
+
372
image::images/4_F47.png[title="C/{cpp} compiler optimization"]
Kristof Szabados's avatar
Kristof Szabados committed
373
+
374
The C/{cpp} compiler optimization page allows the specification of optimization options for C/{cpp} compiler.
Kristof Szabados's avatar
Kristof Szabados committed
375
376
377
+
The optimization level option can be: none, minor optimizations, common optimizations, optimize for speed, optimize for size. By default it is set to: common optimizations.
+
378
The other optimization flags option allows the specification of any user defined optimization flag that is supported by the C/{cpp} compiler.
Kristof Szabados's avatar
Kristof Szabados committed
379
380
381
382
383
+
Both options will be applied the *CXXFLAGS* macro.
+
NOTE: The *–Wall* option is not displayed here, but is generated into the `Makefile`. It is required for proper operation.
+
Adam Knapp's avatar
Adam Knapp committed
384
For more information on the optimization flags please refer to the documentation of your C/{cpp} compiler. In case of the default C/{cpp} compiler g\+\+ is the manual pages of g\+\+ (invoked with the *man g\+\+* command line command).
Kristof Szabados's avatar
Kristof Szabados committed
385
386
387
388
389
390
391
392
393
394
395
396
397

. Platform Specific Libraries
+
image::images/4_F48.png[title="Platform specific libraries"]
+
On the platform specific libraries pages it is possible to specify the list of platform specific libraries that are needed to build the final executable for each supported platform.
+
The list of platform specific libraries is applied to the *SOLARIS_LIB*, *SOLARIS8_LIBS*, *LINUX_LIBS*, *FREEBSD_LIBS* and *WIN32_LIBS* macros respectively. By default all lists are empty.
+
NOTE: Some libraries are not displayed here, but are generated into the `Makefile`. These are required for proper operation on the above platforms.

. Linker
+
Adam Knapp's avatar
Adam Knapp committed
398
image::images/4_F49.png[title="Linker"]
Kristof Szabados's avatar
Kristof Szabados committed
399
+
400
The Linker page only functions as reminder to the fact, that the generated `Makefile` uses the same tool for compiling C/{cpp} sources and linking the generated object files.
Kristof Szabados's avatar
Kristof Szabados committed
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441

. Linker Libraries
+
image::images/4_F50.png[title="Linker libraries"]
+
On the linker libraries page it is possible to specify

* additional object files,
* the list of platform independent libraries (-l switch) and
* library search path (-L switch)
+
that are needed by the linker to produce a valid executable.
+
These lists of options are generated directly into the command responsible for creating the final executable. By default the lists are empty.
+
NOTE: In list of the library search paths (-L), environment variables can be used. If the form `[MYVAR]` or `$\{MYVAR}` is used, the value of `[MYVAR]` or `$\{MYVAR}` will be resolved, if it is possible, while generating `Makefile`. Any other form will be regarded as a path relative to the project folder and will be prefixed with the project path.
+
In order for the generated `Makefile` to work and the project to compile properly there are some libraries and search locations not displayed here, but generated into the `Makefile`.
+
If the *Disable the entries of the predefined libraries* option is selected only the search paths related to *TTCN3_DIR* will be generated, all other libraries and search paths are left out of the generated `Makefile`. For example, in the generated Makefile, lines
+
[source]
----
OPENSSL_DIR = $(TTCN3_DIR)
XMLDIR = $(TTCN3_DIR)
----
+
will be commented out and their usage will be omitted.
+
By default, this option is not selected.

. Linker Options
+
image::images/4_F51.png[title="Linker Options"]
+
On the page "Linker Options" you can select different linker options. These will be added to the value of LDFLAGS in the Makefile.
+
The first option is to use the GNU "gold" linker instead of the regular one. If it is selected the text "`-fuse-ld=gold`" will be added to the value of LDFLAGS.
+
The second option is a free text. It also will be added to the value of LDFLAGS without any checking. Use it carefully!

442
==== The Make Attributes Tab
balaskoa's avatar
balaskoa committed
443
444
[[make-attributes]]
image::images/4_F52.png[title="Make attributes tab"]
Kristof Szabados's avatar
Kristof Szabados committed
445
446
Figure Make attributes

balaskoa's avatar
balaskoa committed
447
On the <<make-attributes,Make attributes tab>> the following attributes are set:
Kristof Szabados's avatar
Kristof Szabados committed
448
449
450
451
452
453
454

* **The path to the Makefile updater script**
+
Points out a shell script that will be run to modify to the generated Makefile. The field is checked for validity: if not empty, it must point to an existing file.

* **Build level**
+
balaskoa's avatar
balaskoa committed
455
Specifies the project build level. For more information, please refer chapter <<5-converting_existing_projects.adoc,Converting Existing Projects>>.
Kristof Szabados's avatar
Kristof Szabados committed
456
457
458
459
460
461
462
463
464

* **Make flags**
+
Specifies the make command suffixes.

* **Working directory**
+
specifies a directory used by the build operations: symbolic links and generated files will be placed in this directory. This field is checked for validity.

Adam Knapp's avatar
Adam Knapp committed
465
In the resource based project representation of TITAN projects it is impossible to tell which files are source files and which ones are generated files. For this reason, it is assumed that every file in the working directory is a generated file and every file outside the working directory is a source file (if it is not excluded from build). For this reason, the user is forced to set a working directory, or otherwise the Designer plugin does not know which files to build.
Kristof Szabados's avatar
Kristof Szabados committed
466
467
468

NOTE: if the provided directories are in the project, either as actual directories or linked folders, the generated files can be seen from the workbench.

469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
=== Setting the Local Build Properties of a TITAN Java Project

For TITAN Java projects there are different configuration options available.

To set the project properties for local build first *right click* the project and select *Properties* then select *<<makefile-creation-attributes,TITAN Java Project Property>>*.

[[the-internal-makefile-creation-attributes-tab-Java]]
==== The Internal Makefile Creation Attributes Tab for TITAN Java Projects

image::images/4_F38_Internal_makefile_creation_attributes_for_TITAN_Java_Projects.png[title="Internal makefile creation attributes for TITAN Java Projects"]

On the Internal makefile creation attributes tab the options that configure the build process can be set. To change the value of an element it must be selected. Depending on the element selected on the left side, the right hand side of the tab will contain different options.

NOTE: In TITAN Java Projects the build system is not using makefiles, the name was kept to be compatible with the TITAN Project look and feel.

. TTCN-3 Preprocessor

. TTCN-3 Preprocessor Symbols
+
image::images/4_F40_TTCN_3_Preprocessor_symbols_for_TITAN_Java_Projects.png[title="TTCN-3 Preprocessor symbols for TITAN Java Projects"]
+
On the symbols page it is possible to specify the list of symbols that should be defined and the list of symbols that should be undefined when the TTCN-3 pre-processor tool is executed.
+
These lists of options are applied during syntactic and semantic checking of the project. By default both lists are empty.

. TTCN-3 Preprocessor Included Directories
+
image::images/4_F41_TTCN_3_Preprocessor_include_directories_for_TITAN_Java_Projects.png[title="TTCN-3 Preprocessor include directories for TITAN Java Projects"]
+
On the included directories page, it is possible to specify the list of directories where the TTCN-3 pre-processor can look for included files.
+
The list of options is applied during syntactic and semantic checking of the project. By default the list is empty.

. TITAN Flags
+
image::images/4_F42_TITAN_Flags_for_TITAN_Java_Projects.png[title="TITAN Flags for TITAN Java Projects"]
+
On the TITAN flags page, it is possible to specify the flags the TITAN Java code generator should use when compiling the TTCN-3 and ASN.1 files.
+
The options will be applied during the execution of the Java code generator.
+
For more information on the meanings of these options please refer to section 5.1 of the TITAN Programmer’s Technical Reference guide <<12-references.adoc#_12, [12]>>.

512
=== Setting Project and Folder Level Naming Convention Settings
Kristof Szabados's avatar
Kristof Szabados committed
513
514
515
516
517
518
519
520
521

image::images/4_F53.png[title="Project level naming convention settings"]

On the project and folder level it is possible to override the general workspace level naming conventions. This option can be used to further constrain the naming conventions, for example to include some project specific constants.

image::images/4_F54.png[title="Folder level naming convention settings"]

These are same options that are available as on the workspace level.

Adam Knapp's avatar
Adam Knapp committed
522
The overriding rules are evaluated by the following algorithm:
Kristof Szabados's avatar
Kristof Szabados committed
523

Adam Knapp's avatar
Adam Knapp committed
524
525
526
527
528
. It starts from the folder immediately containing the module in question.
. It walk-searches the folder hierarchy upwards to the project either till it finds a folder that overrides the naming conventions or till it reaches the project.
. If the folder overrides the naming conventions, it uses the settings found there.
. If it reached the project and the project overrides the naming conventions, it uses the settings found there.
. If it reached the project, but even the project itself is not overriding the naming conventions it will use the workspace level settings.
Kristof Szabados's avatar
Kristof Szabados committed
529
530
531
532

NOTE: It is suggested to switch off checking the naming convention because it significantly decreases the speed of the analysis. It should be switched only on at code cleaning.

[[setting-requirements-on-the-configuration-of-referenced-projects]]
533
=== Setting Requirements on the Configuration of Referenced Projects
Kristof Szabados's avatar
Kristof Szabados committed
534
535
536

image::images/4_F55.png[title="Requirements on the actual configuration of referenced projects"]

Kristof Szabados's avatar
Kristof Szabados committed
537
On this page it is possible to set for each project, directly referenced by the actual one, a requirement on its actual configuration. If the actual configuration on the given project is not the same as the required one it will cause a build error. This way it is possible to have fairly large project hierarchies, while still being able to consistently support build configuration for each project.
Kristof Szabados's avatar
Kristof Szabados committed
538
539
540
541
542
543
544
545
546

To change the requirement for a project either *select it* in the list and click on the *Edit…* button, or *double click on it* in the list.

On the window that pops up (Figure 56) it will be possible to select a configuration, from all of the configurations configured for the selected project.

image::images/4_F56.png[title="Configuration requirement selection window for project1"]

NOTE: Both in the list and on the requirement selection window the "*<No requirement>*" option is displayed if there is no requirement set for that given project at this time. If you wish to disable a previously set requirement, you have to select this option.

547
=== Setting the Remote Build Properties of a Project
Kristof Szabados's avatar
Kristof Szabados committed
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564

Remote build enables building of source codes:

* on several different machines;

* on several platforms;

* in several different directories;

* with several different build settings;

* using all of the above possibilities at the same time.

image::images/4_F57.png[title="Remote build attributes"]

On this property page one or more hosts can be chosen to build the project remotely. The modalities of the remote build process on these hosts are also set.

Adam Knapp's avatar
Adam Knapp committed
565
To set the project properties for remote build, first *right click* the project and select *Properties*, then select *Remote build* on the left pane (Figure 57). (If *Remote build* is missing from the left pane, *left click* the triangle sign next to the *TITAN Project Property*; see Figure 52.)
Kristof Szabados's avatar
Kristof Szabados committed
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594

The checkbox *Execute the build commands in parallel* controls how the provided build commands should be executed.

* If this option is NOT CHECKED (this is the default), the build commands will be executed serially, that is, one by one.

* If this option is CHECKED, the build command will be executed in a parallel fashion, meaning that each execution will start at the same time.

NOTE: The majority of the build systems requires exclusive access to the intermediate files (this is the reason why NOT SET is the default), otherwise the build process might become corrupted (this can happen for example when an intermediate file built with GCC 3.4 and another built with GCC 4.0 is linked together).

Remote build hosts have three attributes:

* *Active*
+
This attribute indicates whether the host should be included in the next remote build session or not.

* *Name*
+
This attribute shows the name of the host. It is only used to provide feedback to the user about the progress of the build processes. It doesn’t need to be unique.

* *Command*
+
This attribute contains part of the command that will be executed in the remote build process. The string inserted will be prefixed with sh –c before executing it. The default attribute content is `rsh <[user@]hostname> -n 'cd <working directory>; make dep; make',` and the string inserted must follow this pattern.

The user can control the build hosts using the buttons to the right from the table.

The *New…* button is used to create a new remote build host. It brings up the remote build host configuration window (Figure 58), where the properties of the new build host can be set. The new build host will be added to the end of the list of build hosts. Host creation can be cancelled by pressing the *Cancel* button, while the new host data is validated by pressing the *OK* button.

image::images/4_F58.png[title="Remote build attributes of a host"]

Kristof Szabados's avatar
Kristof Szabados committed
595
The *Edit…* button is used to edit the attributes of an existing remote build host. Before pressing the button, the host to be edited must be selected from the table. By pressing the button, the remote build host configuration window (Figure 58) will appear, showing with the current properties of the selected host. Changes made to the host can be revoked by pressing the *Cancel* button, while modifying the host is done by pressing the *OK* button.
Kristof Szabados's avatar
Kristof Szabados committed
596

Kristof Szabados's avatar
Kristof Szabados committed
597
The *Copy…* button is used to create a copy of an already existing host. Pressing this button will create an exact copy of the currently selected host. This way of creating a new host can be beneficial for example when the build command of the new host only slightly differs from the build command of the source host. Copying is abandoned by pressing the *Cancel* button, while it is confirmed by pressing the *OK* button.
Kristof Szabados's avatar
Kristof Szabados committed
598
599
600
601
602

The *Remove…* button is used to remove an existing host from list of remote build hosts. The command is abandoned by pressing the *Cancel* button, while it is confirmed by pressing the *OK* button.

NOTE: The saving of every change done on this page is validated by pressing the *Apply* or *OK* buttons at the bottom on the property page (Figure 57).

603
604
NOTE: The TITAN Java Projects do not have a remote build preference page. As Java is platform independent, there is no need to create platform specific binaries for particular machines.

605
==== Pitfalls
Kristof Szabados's avatar
Kristof Szabados committed
606
607
608
609
610
611

In case the rsh command is not present one should use the ssh command instead. In this case the default command to start from should be: `ssh –n <[user@]hostname> 'cd <working directory>; make dep; make`

As there is no way to enter a password when logging in to a remote machine, it is of crucial importance to set the login mechanism of the remote machine, to not require a password on login.

[[excluding-files-and-folders-from-the-build-process]]
612
== Excluding Files and Folders from the Build Process
Kristof Szabados's avatar
Kristof Szabados committed
613
614
615
616
617

A file or a folder excluded from the build process won’t be placed into the generated `Makefile`. For this reason, once an exclusion or inclusion has taken place, the `Makefile` and the symbolic links are updated (provided that automatic `Makefile` management is enabled for the project).

Excluding a folder from the build process also means that every file and subfolder contained in that folder will be excluded, too.

balaskoa's avatar
balaskoa committed
618
If a file or folder is excluded from build, its name is decorated with the string `[excluded]`, provided that TITAN decoration is enabled (see <<2-getting_started.adoc#_enabling_titan_decorations, here>>).
Kristof Szabados's avatar
Kristof Szabados committed
619
620
621

image::images/4_F59.png[title="Excluded from build"]

622
=== Excluding a File from the Build Process
Kristof Szabados's avatar
Kristof Szabados committed
623
624
625
626
627
628
629
630
631

A file can be excluded from build or included in the build in two different ways described below.

NOTE: There are some special files that can never be included into the build. In Eclipse these are project related plug-in resources, which by convention never have a name, just an extension, for example `.TITAN_properties`. Such files (that don’t have a name), are always excluded from build, no matter how their property is set.

To access File properties (the first alternative): *right click* the file and select *Properties*. On the *Properties for …* window, select *TITAN File Property*. Here the exclusion state of the file can be set via ticking the *Excluded from build* box.

image::images/4_F60.png[title="TITAN file property"]

Adam Knapp's avatar
Adam Knapp committed
632
To access the Pop-up menu (the second alternative), *right click* the file and select *TITAN / Toggle exclude from build state*. This method has the advantage that the exclusion state of several selected files can be changed all at once.
Kristof Szabados's avatar
Kristof Szabados committed
633
634
635

image::images/4_F61.png[title="Toggle exclude from build menu"]

636
=== Excluding a Folder from the Build Process
Kristof Szabados's avatar
Kristof Szabados committed
637
638
639
640
641
642
643
644
645

A folder can be excluded from build or included in the build in two different ways described below.

NOTE: There are some special folders that can never be included into the build. In Eclipse by convention folders having a name which starts with a . (dot) are used for storing special files or folders, that one or more plug-ins might temporarily create. Such folders and for this reason their whole content is always excluded from build, no matter how their property is set.

To access Folder properties (the first alternative), *right click* the folder and select *Properties*. On the *Properties for …* window, select *TITAN Folder Property*. Here the exclusion state of the folder can be set via ticking the *Excluded from build* box. (The other checkbox, *Folder is in central storage*, is described <<converting-a-folder-into-a-central-storage, here>>.)

image::images/4_F62.png[title="TITAN folder property"]

Adam Knapp's avatar
Adam Knapp committed
646
To access the Pop-up menu (the second alternative), *right click* the folder and select *TITAN / Toggle exclude from build state*. This method has the advantage that the exclusion state of several selected folders can be changed all at once (see Figure 61 above).
Kristof Szabados's avatar
Kristof Szabados committed
647
648

[[converting-a-folder-into-a-central-storage]]
649
== Converting a Folder into a Central Storage
Kristof Szabados's avatar
Kristof Szabados committed
650

Adam Knapp's avatar
Adam Knapp committed
651
A folder marked as Central Storage is assumed to have its own `Makefile`. For this reason, when this property of a directory is toggled, the `Makefile` and the symbolic links are updated (provided that automatic `Makefile` management is enabled for the project). For description of the Central Storage concept, please refer to the TITAN User Guide (<<12-references.adoc#_3, [3]>>).
Kristof Szabados's avatar
Kristof Szabados committed
652
653
654
655
656

A directory’s Central storage property can be toggled the following way:

*Right click* on the folder, select *Properties* and in the *Properties for …* window click *TITAN Folder Property*. Here the central storage state of the folder can be toggled via ticking the *Folder is in central storage* button (Figure 62).

657
== Opening and Closing Projects
Kristof Szabados's avatar
Kristof Szabados committed
658
659
660

A closed project cannot be edited; even its contents are hidden. This is useful to decrease memory occupation and computational load: a closed project does not use any resources.

Adam Knapp's avatar
Adam Knapp committed
661
In Eclipse, projects can be opened and closed by *right clicking* the project and selecting *open project* respective *close project*.
Kristof Szabados's avatar
Kristof Szabados committed
662

663
== Saving and Loading Project Properties
Kristof Szabados's avatar
Kristof Szabados committed
664
665
666
667
668

There is no need to save or load the project properties file, as this is done automatically. When files or folders are added or removed, or their properties are changed, the TITAN Designer plug-in automatically saves the new properties into the `.TITAN_properties` file, which always resides in the root directory of the project. When the content of this file is edited and saved, or when the TITAN Designer plugin starts up noticing that files were changed while it was not active, then it automatically loads the file’s contents and modifies the resources properties accordingly.

Besides the obvious use this is useful if more people are working on the same project. Someone updates the properties of the resources and sends the file to the others; when the recipients save the file the properties of their resources will be updated automatically.

669
== Importing and Exporting Projects
Kristof Szabados's avatar
Kristof Szabados committed
670
671
672
673
674
675
676
677
678
679
680
681
682

Importing and exporting projects can be done in many ways in Eclipse. Out of those 3 will be shown in detail: a native way, one using the TITAN project descriptor format, and a way to import project from the old mctr_gui format.

It is important to turn off automatic building and to refresh the project before importing and exporting. Because of the changing nature of the projects, it can be expected that there will always be files which are out of synchrony with the file system. Importing and exporting can only be done if every file in the project is in synchrony with their file system counterparts.

NOTE: Exporting and importing without archiving is almost exactly the same.

The following steps should be done before exporting a project:

. Automatic building should be turned off, so that further operations will not invoke any build related functionality.
. Optionally the project should be cleaned to reduce the size of the exported data.
. The project should be refreshed (*right click* the projectand select *Refresh*), to synchronize the files and the file system.

683
=== Exporting Projects in Native Format
Kristof Szabados's avatar
Kristof Szabados committed
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702

To export a project using a native way, for example into an archive file, follow the steps described below:

. *Right click* the project to be exported and select *Export*.
+
image::images/4_F63.png[title="Export menu"]

. On the *Export* window select *General / Archive File* and press *Next*.
+
image::images/4_F64.png[title="Export common dialog"]

. Fill in the fields in the *Export Archive file* wizard.
+
NOTE: it is advised to export every file related to the project, and also to export only those files in the archive which belong to the project.
+
image::images/4_F65.png[title="Export Archive file wizard"]

NOTE: This will export the whole project: not just the information on settings, but also the files and folders themselves.

703
=== Importing Projects from Native Format
Kristof Szabados's avatar
Kristof Szabados committed
704
705
706
707
708
709
710
711
712
713
714
715
716

To import a project from a native format, for example an archive file, follow the steps described below:

. *Right click* somewhere in *Project Explorer* and select *Import*, as shown on Figure 63 above.
. On the *Import* window select *General / Existing Projects into Workspace* and press *next* (below).
+
image::images/4_F66.png[title="Import common dialog"]

. In the *Import Projects* wizard select the archive to import from. Eclipse will list the projects the archive contains. Select one or more of them and press *Finish*.
+
image::images/4_F67.png[title="Import Archive file wizard"]

[[importing-an-existing-mctr-gui-project]]
717
=== Importing an Existing mctr_gui Project
Kristof Szabados's avatar
Kristof Szabados committed
718
719
720
721

To import a project from an existing mctr_gui project file follow the steps described below:

. *Right click* somewhere in *Project Explorer* and select *Import*, as shown on Figure 63.
Kristof Szabados's avatar
Kristof Szabados committed
722
 On the *Import* window select *TITAN / Project from .prj file* and press *next* (below).
Kristof Szabados's avatar
Kristof Szabados committed
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
+
image::images/4_F68.png[title="Import from .prj file"]

. On the *Import new TITAN Project from .prj file* wizard select the original project file to import from and press *Next*.
+
image::images/4_F69.png[title="Import new TITAN Project from .prj file"]

. Select the name and location of the new project to be created.
+
image::images/4_F70.png[title="Name of the new project"]
+
image::images/4_F71.png[title="Create the included projects automatically"]

. On the last page of the wizard it is possible to select whether included projects (if any exists) should be imported automatically or not.

The wizard will now create the new project, populate it with the files referring to the ones provided by the mctr_gui project file and set all options for the project which can be transferred.

Adam Knapp's avatar
Adam Knapp committed
740
For more information on how the project is converted to this format please refer to <<5-converting_existing_projects.adoc#convert-an-existing-mctr-gui-project-using-an-import-wizard, Section 5>>.
Kristof Szabados's avatar
Kristof Szabados committed
741
742

[[importing-files-as-linked-resources]]
743
=== Importing Files as Linked Resources
Kristof Szabados's avatar
Kristof Szabados committed
744
745
746
747
748

Linked resources are files and folders which are not physically copied into the Eclipse workspace nor linked as soft or hard linked there (at least not into the source folder just later into the build folder under the building process). Linked resources are stored primarily internally in the Eclipse. When linked resources are modified, the original files will be modified. This is the most useful ttcn source file handling method.

To import folders and files as "linked resources" follow the steps described below.

Adam Knapp's avatar
Adam Knapp committed
749
. Create an empty project without `src` subfolder according to <<creating-a-new-titan-project, Creating a New TITAN {cpp} Project>>. The project name should be the same as the name of the project to be imported.
Kristof Szabados's avatar
Kristof Szabados committed
750
751
752
. Right click on the project name and select *Import*, as shown on Figure 63 above. On the *Import* window select *General / File System* and press *Next* as shown on below.
+
image::images/4_F72.png[title=""]
Adam Knapp's avatar
Adam Knapp committed
753
. In the Import / File system dialog select *Browse* (as seen below), then find and select the `src` folder of the project to be imported.
Kristof Szabados's avatar
Kristof Szabados committed
754
755
+
image::images/4_F73.png[title=""]
Adam Knapp's avatar
Adam Knapp committed
756
. Click on the button *Advanced>>* in the dialog, select the options *Create link in workspace* and unselect options *Create virtual folders* and *Create link locations relative to:* as shown on below.
Kristof Szabados's avatar
Kristof Szabados committed
757
758
+
image::images/4_F74.png[title=""]
Adam Knapp's avatar
Adam Knapp committed
759
. Push Finish. The `src` folder appears under the project name in the Project Explorer as linked resource (the icon before the `src` folder contains a little link arrow) as shown below.
Kristof Szabados's avatar
Kristof Szabados committed
760
+
balaskoa's avatar
balaskoa committed
761
image::images/4_F75.png[title="The result of the import"]
Kristof Szabados's avatar
Kristof Szabados committed
762
763

[[exporting-projects-into-the-titan-project-descriptor-tpd-format]]
764
=== Exporting Projects into the TITAN Project Descriptor (tpd) Format
Kristof Szabados's avatar
Kristof Szabados committed
765

Adam Knapp's avatar
Adam Knapp committed
766
Exporting only project information into TITAN Project Descriptor (tpd) format can be performed manually or automatically.
Kristof Szabados's avatar
Kristof Szabados committed
767
768

[[exporting-project-manually-into-the-titan-project-descriptor-tpd-format]]
769
==== Exporting Project manually into the TITAN Project Descriptor (tpd) Format
Kristof Szabados's avatar
Kristof Szabados committed
770

Adam Knapp's avatar
Adam Knapp committed
771
To export the project information into a `tpd` file, follow the steps described below:
Kristof Szabados's avatar
Kristof Szabados committed
772

balaskoa's avatar
balaskoa committed
773
774
. *Right click* on the project to be exported and select *Export*.
. On the *Export* window select *TITAN / TITAN project settings* and press *Next* (see the figure below):
Kristof Szabados's avatar
Kristof Szabados committed
775
776
777
+
image::images/4_F76.png[title="Export to TITAN project descriptor"]

balaskoa's avatar
balaskoa committed
778
. Select the file where the information should be exported to, and press *Next* (see the next figure).
Kristof Szabados's avatar
Kristof Szabados committed
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
+
image::images/4_F77.png[title="File selection page"]

. On the options page fine tune the amount of data to be exported and press *Finish*.
+
image::images/4_F78.png[title="Export options"]

The available options are:

* *Do not generate information on the contents of the working directory:*
+
If the working directory is visible inside Eclipse, inside the project, its contents are by default also mentioned in the project description. As the working directory usually contains only generated files, that can be reproduced later, this behavior is not always desired. Its default value is on.

* *Do not generate information about resources whose name starts with a ".":*
+
In Eclipse this naming convention is used to signal that a resource stores some tool specific options about the project. As such, from the point of view of TITAN, they are not needed. Its default value is on.

* *Do not generate information on resources contained within linked resources:*
+
In many cases such links are intentionally used to connect to an existing folder whose content might change externally. For example, version handling of files can also be done like that.
+
Adam Knapp's avatar
Adam Knapp committed
800
NOTE:  It is recommended to use this feature with care as there is not much connection between the Eclipse internal resource system, and the file system, the activation of this option can cause unexpected side effects. Its default value is on.
Kristof Szabados's avatar
Kristof Szabados committed
801
802
803

* *Save default values:*
+
Adam Knapp's avatar
Adam Knapp committed
804
By default it is not include any information on any option/setting in the descriptor file, which has its default value as the actual one. This makes for a very compact description, but in cases where all information needs to be saved, this might not be ideal. Its default value is off. If it is switched on, the size of the `tpd` file is unnecessarily big. This is not a problem but perhaps it is not so easy to analyze by the user.
Kristof Szabados's avatar
Kristof Szabados committed
805
806
807
808
809
810
811

* *Pack all data of related projects:*
+
Project references in Eclipse are a great way to structure one’s work into manageable pieces. However, if one of those projects is not available, building the whole set is not possible. For this reason, it is possible to save all information from all required projects into one project descriptor. Its default value is off.

* *Export tpdName attribute to referenced projects:*
+
Adam Knapp's avatar
Adam Knapp committed
812
If this option is on, then the referenced projects will have a `tpdName` attribute. The value of the `tpdName` attribute by default is the project’s name and the `.tpd` suffix. If the referenced project had a `tpdName` attribute during the import, then that value will be stored. By default this option is on, if the project was imported from a `tpd` file using `–I` switches.
Kristof Szabados's avatar
Kristof Szabados committed
813

Adam Knapp's avatar
Adam Knapp committed
814
The default settings can be changed under *Window / Preferences / TITAN Preferences / Export* (see <<3-setting_workbench_preferences.adoc#export, Setting Workbench Preferences>>).
Kristof Szabados's avatar
Kristof Szabados committed
815

Adam Knapp's avatar
Adam Knapp committed
816
For more information, related to this file format, please refer to Section 8 of the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>.
Kristof Szabados's avatar
Kristof Szabados committed
817

818
==== Exporting Projects automatically into the TITAN Project Descriptor (tpd) Format
Kristof Szabados's avatar
Kristof Szabados committed
819

Adam Knapp's avatar
Adam Knapp committed
820
The automatic export of projects can be set on workspace level. The fine tuning of the information can be set. It can be set to ask/request the location of the `tpd` file when the first automatic save happens.
Kristof Szabados's avatar
Kristof Szabados committed
821
822
823

To export your projects automatically, follow the steps below:

balaskoa's avatar
balaskoa committed
824
. Select *Window / Preferences / TITAN Preferences / Export*. An option dialog appears (see <<3-setting_workbench_preferences.adoc#export, Figure Export options>>).
Kristof Szabados's avatar
Kristof Szabados committed
825
826
827
828
829
. Switch on the option "Refresh tpd file automatically".
. Switch on the option "Request new location for the tpds at the first automatic save" if your projects to be automatically saved have not been saved yet or if you want to change the location of your tpds when importing them.
. Optionally change the options in the group "Fine tune the amount of data saved about the project" if it is necessary. (It is not suggested.)
. Press *Apply* or *OK* to save the settings.

830
=== Importing Projects from TITAN Project Descriptor Format
Kristof Szabados's avatar
Kristof Szabados committed
831
832
833
834
835
836
837
838

To import a project using an existing TITAN project descriptor file follow the steps described below:

. *Right click* somewhere in *Project Explorer* and select *Import*, as shown on Figure 63.
. On the *Import* window select *TITAN / Project from new project file* and press *Next* (below).
+
image::images/4_F79.png[title="Import from project descriptor"]

Adam Knapp's avatar
Adam Knapp committed
839
. On the *Import new TITAN Project from .tpd file* page select the original project file to import from. There is an optional field where search paths can be entered in the format of `–Ipath` where path must be an absolute path. The mechanism of the `–I` flag is described in the Referred project usage with `–I` switch in the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>.
Kristof Szabados's avatar
Kristof Szabados committed
840
841
842
843
844
845
846
847
848
849
850
851
852
853
. Press *Next*.
+
image::images/4_F80.png[title="Press Next"]

. On the options page select how the importer should behave in certain situations.
+
image::images/4_F81.png[title="Import options"]

Available options:

* *Open the preference page for all imported sub projects:* By default the page where the project preferences can be configured is only displayed for the top level project, referenced projects don’t trigger this mechanism. However, if several projects are imported it can be useful to open this page for each of them.

* *Skip existing projects on import:* This is important when a project with a name, which is about to be loaded as a referenced project, already exists in the workbench. By default, there will be no warning, and the importation of that project will not take place.

854
=== Useful Tips for Exporting and Importing
Kristof Szabados's avatar
Kristof Szabados committed
855

856
[[pitfalls-1]]
balaskoa's avatar
balaskoa committed
857
==== Pitfalls
Kristof Szabados's avatar
Kristof Szabados committed
858
859
860

During the importation there might be several behaviors which might look strange at first.

Adam Knapp's avatar
Adam Knapp committed
861
When importing a project description containing Eclipse path variables, it is asked for permission from the user to add new variables, or in case the variable exists with a different value, override variables in his system.
Kristof Szabados's avatar
Kristof Szabados committed
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876

However, if the project description does not store, or the user does not add the necessary Eclipse path variable to his own system, this will not be treated as an error by our tool. Instead either the platform, or any other tool trying to access a resource being unavailable, will report this error.

If a project with the same name to be loaded already exists:

* If it is the top level project the user will be asked to change the name.

* If it is not the top level project the default is to silently ignore the import request, as the project is already imported.

* If it is not the top level project and the user asked not to skip existing projects, the name changing dialog will be displayed. Upon name change all references to the new project will use the new name.

It is worth to mention, that in order to re-import a project from a project descriptor file, it is required to first delete the actual project. It is not supported to overwrite the current contents automatically.

As an example, in the `mctr_gui` the process of closing the user interface and re-opening it while loading the same project, will load the newest version of the project description (and if it is not saved it will also lose all intermediate changes). However, as the closing of Eclipse does not change any state of the imported projects, after re-opening it, the original project with the original settings will be present. In order to load the new settings, the old project has to be explicitly removed from the working environment.

Adam Knapp's avatar
Adam Knapp committed
877
For more information, related to this file format, please refer to Section 8 of the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>.
Kristof Szabados's avatar
Kristof Szabados committed
878

balaskoa's avatar
balaskoa committed
879
==== Native Export and Import
Kristof Szabados's avatar
Kristof Szabados committed
880
881
882

If your projects contain absolute pathnames, the project can be natively exported and then imported only if the places defined with their absolute paths are visible from the new workspace. This is a strong requirement/restriction but it can be satisfied within the same group or working environment. But in that case why should the project be compressed, relocated and uncompressed?

balaskoa's avatar
balaskoa committed
883
==== Exporting and Importing Project Information and Projects via TPD Files in Case of Complex Projects
Kristof Szabados's avatar
Kristof Szabados committed
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901

All project information can be stored in TPD files as it is described in the previous subchapters but not all way of working achieves portability. The next method is applicable for projects of any complexity.

Terminology:

*Source root folder or root folder* is the folder which contains all source files of all projects. For example, for ClearCase titan users it can be /vobs/ttcn/TCC_Releases.

*Workspace* is the Eclipse workspace. It is a folder containing Eclipse related project information (and generally it can contain even source files).

*Source project* is a project of our complex project. It is stored in a subfolder of the source root folder. The name of the source project is the name of its containing folder.

General requirements

. The projects should be handled from bottom to top, precisely string from the projects independent from any others.
. The Eclipse workspace and the folders containing the project and the source code shall be totally disjoint (they shall not have any common element).

Suppose that the source codes are created and hierarchically stored under the source root folder. Follow the steps for each project of our complex project.

Adam Knapp's avatar
Adam Knapp committed
902
903
904
905
. Create an empty project in the workspace with the same name as the source project (see <<creating-a-new-titan-project, Creating a New TITAN {cpp} Project>>).
. Import the `src` folder of the project as linked resources according to <<importing-files-as-linked-resources, Importing Files as Linked Resources>>.
. Fill in project properties according to <<setting-the-local-build-properties-of-a-project, Setting the Local Build Properties of a TITAN Project>>.
. Export project properties into tpd format according to <<exporting-projects-into-the-titan-project-descriptor-tpd-format, Exporting Projects into the TITAN Project Descriptor (tpd) Format>>.
Kristof Szabados's avatar
Kristof Szabados committed
906
907
+
NOTE: The target place should be the folder of the original project where the project was imported from.
Adam Knapp's avatar
Adam Knapp committed
908
909
. Import the `tpd` file from the source project into the Eclipse project.
. Export the project into tpd format as in step 4.
Kristof Szabados's avatar
Kristof Szabados committed
910
+
Adam Knapp's avatar
Adam Knapp committed
911
NOTE: This way the new `tpd` file will contain the information about itself. It is extremely important if the whole set of project should be exported as a compressed file for example to send to a test lab as a product or to the TITAN support to report a bug.
Kristof Szabados's avatar
Kristof Szabados committed
912

balaskoa's avatar
balaskoa committed
913
==== Exporting Project Content from Command Line Using TPDs
Kristof Szabados's avatar
Kristof Szabados committed
914

Adam Knapp's avatar
Adam Knapp committed
915
To export the content of whole project sets if each project has a `tpd` file, follow the steps described below.
balaskoa's avatar
balaskoa committed
916
Unix environment is required.
Kristof Szabados's avatar
Kristof Szabados committed
917
918
919
920
921
922

. Go to the folder of the top level source project.
+
NOTE: It is located in the source root folder not in the workspace!
. Use this command from command line:
+
Adam Knapp's avatar
Adam Knapp committed
923
924
[source]
----
Kristof Szabados's avatar
Kristof Szabados committed
925
ttcn3_makefilegen -V -P rootdir_to_split -t top_level_tpd.tpd | xargs tar cfz my_target_tar.tgz
Adam Knapp's avatar
Adam Knapp committed
926
----
Kristof Szabados's avatar
Kristof Szabados committed
927
928
929
+
for example:
+
Adam Knapp's avatar
Adam Knapp committed
930
931
[source]
----
Kristof Szabados's avatar
Kristof Szabados committed
932
ttcn3_makefilegen -V -P /home/ethbaat/DiameterApplib/Diameter_Applib_2013_03_01 -t Libraries/EPTF_Applib_Diameter_CNL113521/EPTF_Applib_Diameter_CNL113521.tpd | xargs tar cfz DiamAppLibTest.tar.gz
Adam Knapp's avatar
Adam Knapp committed
933
----
Kristof Szabados's avatar
Kristof Szabados committed
934
935

[NOTE]
936
====
Kristof Szabados's avatar
Kristof Szabados committed
937
938
The compressed file will contain the files in the same structure as they have been stored in the source root directory.

Adam Knapp's avatar
Adam Knapp committed
939
See more information about the command `ttcn3_makefilegen` in Sections 6.1.2 and 6.1.3 in the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>.
940
====
Kristof Szabados's avatar
Kristof Szabados committed
941

942
== Formatting Log Files
Kristof Szabados's avatar
Kristof Szabados committed
943

Adam Knapp's avatar
Adam Knapp committed
944
To format a log file (one having `.log` as extension) *right click* the file and select *TITAN / Format log*.
Kristof Szabados's avatar
Kristof Szabados committed
945
946
947

image::images/4_F82.png[title="Format log menu"]

Adam Knapp's avatar
Adam Knapp committed
948
This will produce a formatted log file in the very same directory, with the same name, but having the extension `.formatted_log`.
Kristof Szabados's avatar
Kristof Szabados committed
949
950
951

NOTE: For the duration while the formatted log is being created progress indication is provided in the *Progress view*.

952
== Merging Log Files
Kristof Szabados's avatar
Kristof Szabados committed
953

Adam Knapp's avatar
Adam Knapp committed
954
To merge several log files (ones having `.log` as extension) select them, and after *right clicking* on one select *TITAN / Merge log*.
Kristof Szabados's avatar
Kristof Szabados committed
955
956
957
958
959
960
961
962

image::images/4_F83.png[title="Merge log menu"]

This will first ask for the file where the results have to be saved, processing the log files will only start after a new or an existing files is selected.

NOTE: For the duration while the formatted log is being created progress indication is provided in the *Progress view*.

[[using-project-references]]
963
== Using Project References
Kristof Szabados's avatar
Kristof Szabados committed
964

Adam Knapp's avatar
Adam Knapp committed
965
In Eclipse for the creation of a hierarchy of projects building on other projects one can use project references (Figure 81).
Kristof Szabados's avatar
Kristof Szabados committed
966

Adam Knapp's avatar
Adam Knapp committed
967
When a project references another project, this means for Eclipse that all of the resources of the referenced project are available for use in the referring project. For example if _Project_2_ is referencing _Project_1_:
Kristof Szabados's avatar
Kristof Szabados committed
968

Adam Knapp's avatar
Adam Knapp committed
969
* All modules available in _Project_1 can be used in _Project_2_ too (for importation, code completion …). For the on-the-fly toolset is will seem as if those modules were also part of Project_2.
Kristof Szabados's avatar
Kristof Szabados committed
970

Adam Knapp's avatar
Adam Knapp committed
971
* The order in which _Project_1_ and _Project_2_ are built will always be handled automatically:
Kristof Szabados's avatar
Kristof Szabados committed
972

Adam Knapp's avatar
Adam Knapp committed
973
* If _Project_1_ changes, _Project_2_ will be refreshed too.
Kristof Szabados's avatar
Kristof Szabados committed
974

Adam Knapp's avatar
Adam Knapp committed
975
* If _Project_2_ is built _Project_1_ will also be built, but only if it has also changed since the last time it was built.
Kristof Szabados's avatar
Kristof Szabados committed
976

Adam Knapp's avatar
Adam Knapp committed
977
* When _Project_2_ is built, it will not attempt to build the modules from _Project_1_ again, but rather use their already built form from the working directory of _Project_1_.
Kristof Szabados's avatar
Kristof Szabados committed
978

Adam Knapp's avatar
Adam Knapp committed
979
NOTE: Project reference hierarchies are not limited to two projects they can contain any number of projects.
Kristof Szabados's avatar
Kristof Szabados committed
980
981
982
983
984

Project references for one project can be managed in the following way: *right click* the project whose references should be changed and select *Properties / Project References.* Adding or removing a reference to a project can be done by simply selecting or unselecting to projects the references should point to.

image::images/4_F84.png[title="Project references"]

Adam Knapp's avatar
Adam Knapp committed
985
NOTE: These references are operating system and file system independent. This means that it is possible to connect projects coming from different physical locations / version handling systems, as long as each is project is set up to work correctly within its own rules.
Kristof Szabados's avatar
Kristof Szabados committed
986

987
== Mapping Elements of the Old Format
Kristof Szabados's avatar
Kristof Szabados committed
988
989
990

The elements of the old GUI can usually be mapped to the new GUI as folders. So, for example, a testports folder should be created in the project, and the files of testports should be placed there. This provides the users with much more configurable project hierarchy, as they can organize their sources as they wish.

Adam Knapp's avatar
Adam Knapp committed
991
Included projects can be generally mapped to simple or linked folders, provided that the central storage property of the folder is set (see <<converting-a-folder-into-a-central-storage,Section 4.7>>). Included projects are fully functioning projects that can be built separately, but are included in the actual project because they provide some useful features. Generally speaking, they are folders (projects are practically stored separately), which might be linked (as they are expected to be on a different computer in the network, if they are just local folders then they can be mapped to local directories) and they have their own `makefile` (because they can be built separately).
balaskoa's avatar
balaskoa committed
992

Kristof Szabados's avatar
Kristof Szabados committed
993
994
995
996
NOTE: Linked folders with their central storage property set provide the same features.

Automatic conversion between the old and new format is not a part of the TITAN Designer plug-in for the time being.

997
== Common Threats
Kristof Szabados's avatar
Kristof Szabados committed
998
999
1000

There are some very dangerous operations related to project management in Eclipse.

For faster browsing, not all history is shown. View entire blame