6-building_the_project.adoc 22.7 KB
Newer Older
1
= Building the Project
Kristof Szabados's avatar
Kristof Szabados committed
2
:toc:
3
:figure-number: 93
Kristof Szabados's avatar
Kristof Szabados committed
4

Adam Knapp's avatar
Adam Knapp committed
5
In this chapter a detailed, step-by-step procedure description is provided about how to build a project according to the workflow.
Kristof Szabados's avatar
Kristof Szabados committed
6

7
Building a project from the TTCN–3 or ASN.1 source modules and perhaps test port files is a procedure consisting of several steps. In the TITAN Designer plugin, the procedure is fully automated. The commands issued by the build related functionalities and their progress messages are displayed in the TITAN console, so the successful completion of the processes can easily be verified. Also, in case of an error, the analysis of the progress messages helps to find the cause of the problem (this is also automated to some extent; please refer <<7-editing_with_titan_designer_plugin.adoc#mark-occurrences-1, here>>). The build process also provides Eclipse with user friendly information about its progress.
Kristof Szabados's avatar
Kristof Szabados committed
8
9
10
11
12

The building process is automated; that is, the executable is updated in the background when project resources change (because they have been created, deleted or updated). There is no need for user interaction—provided that automatic building is enabled.

There is a way to build the project manually, by selecting *Project* / *Build project* or *Project* / *Build all.* This is useful when automatic building (*Project* / *Build Automatically*) is disabled**.**

Adam Knapp's avatar
Adam Knapp committed
13
NOTE: The problem markers of the compiler are parsed from the output of TITAN, for this reason they are updated when the compiler is run (the project is built, or the files are checked). If automatic building is not used, the projects should be built regularly, to have up-to-date problem markers (see <<7-editing_with_titan_designer_plugin.adoc#mark-occurrences-1, here>>).
Kristof Szabados's avatar
Kristof Szabados committed
14

Adam Knapp's avatar
Adam Knapp committed
15
== Building the TITAN {cpp} Project
16
17

=== Step by Step
Kristof Szabados's avatar
Kristof Szabados committed
18
19
20

The following sections describe the steps of the build process. These steps are carried out either automatically by the TITAN plugin or manually by the user; the sections indicate which way applies.

21
==== Creating Symbolic Links
Kristof Szabados's avatar
Kristof Szabados committed
22
23
24
25
26
27
28

By default, the first step of the build process is creating or updating symbolic links in the working directory of the project. The working directory contains symbolic links pointing to every file included in the project (this is not true for files contained in a central storage directory, because they are handled differently). For information please see the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>.

Symbolic link creation is done automatically by the build process; no user action is required.

NOTE: The creation of symbolic links can be turned off in the Designer plug-in, for more information please refer <<4-managing_projects.adoc#setting-the-local-build-properties-of-a-project, here>>.

29
==== Creating or Regenerating the Makefile
Kristof Szabados's avatar
Kristof Szabados committed
30
31
32
33
34
35
36
37
38

The second step of the build process, if needed, is creating or updating the project `Makefile`. Automatic `Makefile` management should be enabled on the *Properties / TITAN Project Property* page of the projects.

Every time it is required, the `Makefile` generator of TITAN will be called with the parameters provided on the *Makefile creation attributes* tab (see <<4-managing_projects.adoc#the-makefile-creation-attributes-tab, here>>). It is possible to indicate a `Makefile` updater script on the *Make attributes* tab (see <<4-managing_projects.adoc#the-internal-makefile-creation-attributes-tab, here>>) that will be run on the generated `Makefile`.

Information about the flags of the TITAN `Makefile` generator and the `Makefile` updater script can be found in the TITAN Programmer’s Technical Reference <<12-references.adoc#_4, [4]>>.

It is the user’s responsibility to create and update the `Makefile` when automatic `Makefile` management is disabled.

39
==== Editing the Makefile Skeleton
Kristof Szabados's avatar
Kristof Szabados committed
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

If the generated `Makefile` is not suitable then either the options that direct its generation should be changed or (after having disabled automatic building) the `Makefile` should be created by hand. Everyone is allowed to write his own `Makefile`; however, the `Makefile` skeleton generated by the compiler always serves as a good starting point. For an extensive description of what shall be checked in the generated `Makefile`, see the TITAN User Guide <<12-references.adoc#_3, [3]>>.

The TITAN plug-in has knowledge about the following `Makefile` commands:

* `make`
* `make all`
* `make dep`
* `make check`
* `make clean`

NOTE: the TITAN plug-in has some assumptions on what functionality the `Makefile` offers. The real `Makefile` should support these functions, and they should be conforming to what behavior TITAN would create.

This step, if needed, is carried out manually by the user.

55
==== Module Compilation
Kristof Szabados's avatar
Kristof Szabados committed
56

Adam Knapp's avatar
Adam Knapp committed
57
In this step {cpp} files are generated from TTCN-3 and ASN.1 files. When a {cpp} file already exists, then the timestamp of the Compile file is used to decide whether a {cpp} file in question is up-to-date or not. A {cpp} file is refreshed only if the corresponding TTCN–3 or ASN.1 module was modified later than the timestamp in the Compile file indicates, or the project was refreshed by *right clicking* the project and selecting *Refresh*; otherwise the generated {cpp} file is considered up-to-date.
Kristof Szabados's avatar
Kristof Szabados committed
58
59
60

The first compilation of the modules will result in addition of the following files in the working directory:

61
* C/{cpp} header files:
Kristof Szabados's avatar
Kristof Szabados committed
62
+
63
These are the header files of the generated {cpp} code. One `.hh` file is generated for every TTCN–3 and ASN.1 module in the project with the same name.
Kristof Szabados's avatar
Kristof Szabados committed
64

65
* C/{cpp} source files:
Kristof Szabados's avatar
Kristof Szabados committed
66
+
67
These are the body files of the generated {cpp} code. One `.cc` file is generated for every TTCN–3 and ASN.1 module in the project with the same name.
Kristof Szabados's avatar
Kristof Szabados committed
68
69
70
71
72
73
74
75
76
77
78
79

* Compile file:
+
This is an empty file. The attributes of the file indicate the date and the time of the last compilation process.

* `Makefile.bak`:
+
This is the backup of the `Makefile`, created when the `make dep` command has been issued.

Module compilation is done automatically by the build process; no user action is required.

[[creating-dependencies]]
80
==== Creating Dependencies
Kristof Szabados's avatar
Kristof Szabados committed
81

82
Once the symbolic links have been created and the `Makefile` of the project has been properly edited if necessary, the command make dep has to be issued to find the dependencies between the resulting {cpp} codes. It is extremely important that the dependencies are always uptodate. If, for example, a TTCN–3 module is removed from the project, the dependencies between the {cpp} files must be updated, otherwise the command `make` fails.
Kristof Szabados's avatar
Kristof Szabados committed
83
84
85
86
87
88
89
90
91
92
93
94

Dependencies appear at the end of the `Makefile` as dependency lines. They are determining the conditions of the binary object code recompilation launched by the command make.

It is discouraged to edit the appended dependency lines.

image::images/6_F83.png[title="Dependencies"]

The dependency update is done automatically if the build level mentioned <<building, here>> is set to three or five. Otherwise it must be carried out manually.

Alternatively, incremental generation of dependency information is available when using Makefiles written for GNU `make`. Instead of modifying the `Makefile`, dependency information is written into separate files with `.d` extension (one for each `.cc` file). These files are included into the main `Makefile`. This has the advantage that the `Makefile` is not modified every time a dependency changes. Another benefit is that the dependencies are always updated during `make`; there is no need to explicitly run `make dep`. For information on how to set this option please refer <<4-managing_projects.adoc#the-makefile-creation-attributes-tab, here>>.

[[building]]
95
==== Building
Kristof Szabados's avatar
Kristof Szabados committed
96

97
In the final step of the project building procedure a conventional {cpp} compiler is used to compile Test port codes and the generated {cpp} source code to a binary object code. The resulting code is linked with the Base Library. The Base Library contains important supplementary function libraries used for the execution of the generated code (for example verdict handling, Host Controller code, and so on).
Kristof Szabados's avatar
Kristof Szabados committed
98
99
100
101
102
103
104
105
106

If automatic building is enabled, Eclipse will invoke the build process whenever project resources change (are created, deleted or updated), or you refresh your project by *right clicking* the project and selecting *Refresh*.

If automatic building (*Project / Build Automatically*) is disabled, then the build process is started by a click on *Project / Build project,* *Project / Build all* or by *right clicking* the project name and selecting *Build*.

The build process will result in the generation of the following files in the working directory:

* Object files:
+
107
For every {cpp} file in the project (source code files, test ports, and so on), an object file (with the extension `.o`) will be created by the {cpp} compiler.
Kristof Szabados's avatar
Kristof Szabados committed
108
109
110

* Shared object files (if dynamic linking is enabled, see <<4-managing_projects.adoc#setting-the-local-build-properties-of-a-project, here>>):
+
111
For every (static) object file (with extension `.o`) in the project a shared object file (with the extension `.so`) will be created by the {cpp} compiler.
Kristof Szabados's avatar
Kristof Szabados committed
112
113
114
115
116
117
118
119
120

* Executable:
+
The executable file has the same name as the project has.

The build process can be configured to set the build level for the given project (see <<4-managing_projects.adoc#setting-the-local-build-properties-of-a-project, here>>). The following build levels are supported:

* Level 0 – Semantic Check
+
Kristof Szabados's avatar
Kristof Szabados committed
121
Only syntactic and semantic checks are carried out on the TTCN-3 and ASN.1 source files. Uses the Makefile target *check*.
Kristof Szabados's avatar
Kristof Szabados committed
122

123
* Level 1 – TTCN3 → {cpp} compilation
Kristof Szabados's avatar
Kristof Szabados committed
124
+
Kristof Szabados's avatar
Kristof Szabados committed
125
In addition to the syntactic and semantic checks, the {cpp} code is also generated from the TTCN-3 and ASN.1 source files if there were no errors found. Uses the `Makefile` target *compile*.
Kristof Szabados's avatar
Kristof Szabados committed
126
127
128

* Level 2 – Creating object files
+
Kristof Szabados's avatar
Kristof Szabados committed
129
Executes the syntactic and semantic checks, generates the {cpp} code and tries to compile it into object (`.o`) and if applicable, into shared object (`.so`) files. Uses the `Makefile` target *objects* or *shared_objects*.
Kristof Szabados's avatar
Kristof Szabados committed
130
131
132

* Level 2.5 – Creating object files with heuristic dependency update
+
133
Executes the syntactic and semantic checks and generates the {cpp} code, but before generating the object and if applicable, shared object files it also updates the dependencies of the source codes if this is needed. This means that the long lasting dependency refresh will not be executed if only such files that the on-the-fly analyzer is able to analyze were changed since the last build, and none of the changes made make a dependency refresh mandatory. Uses the `Makefile` targets *objects* or *shared_objects*; or *dep objects* or *dep shared_objects*.
Kristof Szabados's avatar
Kristof Szabados committed
134
135
136

* Level 3 – Creating object files with dependency update
+
137
Executes the syntactic and semantic checks and generates the {cpp} code, but before generating the object and if applicable, shared object files it also always updates the dependencies of the source codes. Uses the `Makefile` targets *dep objects* or *dep shared_objects*.
Kristof Szabados's avatar
Kristof Szabados committed
138
139
140
141
142
143
144

* Level 4 – Creating Executable Test Suite
+
Carries out a full build and creates the Executable Test Suite, but the dependencies are not updated. Uses the `Makefile` target *all*.

* Level 4.5 – Creating Executable Test Suite with heuristic dependency update
+
Kristof Szabados's avatar
Kristof Szabados committed
145
Carries out a full build, creates the Executable Test Suite and the dependencies are also updated if that is needed. This means that the long lasting dependency refresh will not be executed if only such files that the on-the-fly analyzer is able to analyze were changed since the last build, and none of the changes made make a dependency refresh mandatory. Uses the `Makefile` target *all* or *dep all*.
Kristof Szabados's avatar
Kristof Szabados committed
146
147
148
149
150
151
152

* Level 5 – Creating Executable Test Suite with dependency update
+
Carries out a full build, creates the Executable Test Suite and the dependencies are also always updated. Uses the `Makefile` target *dep all*.

Some hints for selecting the appropriate build level: on build levels 0-3 the executable will not be generated, only levels 4 and 5 produce an Executable Test Suite. Dependency update is only required when the import hierarchy of the source files is changed.

153
=== Remote Build
Kristof Szabados's avatar
Kristof Szabados committed
154
155
156

Projects might need to be built for several platforms, for several different GCC versions, or it might just happen that the user’s computer is not powerful enough to assure short build times.

balaskoa's avatar
balaskoa committed
157
158
159
Building remotely is chosen by *right clicking* the project and selecting *Titan / Build remotely*, as shown on Figure 80 above.

image::images/RemoteBuild1.png[title="Build remotely"]
Kristof Szabados's avatar
Kristof Szabados committed
160
161
162

The outputs of the remote build processes are displayed in the TITAN Console view. Every piece of such an output is prefixed by the host name that provided it.

163
==== Remarks and Tips
Kristof Szabados's avatar
Kristof Szabados committed
164
165
166
167
168
169
170
171
172

It is impossible to clearly identify which source files were some errors reported for, for this reason precise build problems reported by remote build hosts are not redirected to the graphical interface. Only those problems are reported and marked, which are the errors in the build process itself (for example: abnormal termination is reported, but as a build process is not terminated by build errors, such errors are not redirected).

As it is the user’s responsibility to keep the files on the remote host uptodate, no file transfer or file synchronization is provided by the TITAN plugin. Therefore, the remote build process cannot be run automatically.

Building remotely might start up the shell of the remote host in interactive mode. If the remote build host reports missing environmental variables, it is a good idea to check how the shell of the remote build host is configured in interactive mode (this is usually user specified).

The overall length of the name and build commands of the remote hosts should be less than about 2,000 characters. However, assuming that an automated login mechanism and a build script is used on the remote hosts (creating remote build commands like `rlogin rhea; buildscript.sh`), means that the build process might still be executed in parallel on about 60 remote hosts, which should be enough for now.

173
=== Building from the Command Line
Kristof Szabados's avatar
Kristof Szabados committed
174

175
==== Building Directly
Kristof Szabados's avatar
Kristof Szabados committed
176
177
178
179
180
181

It is possible to invoke the build process of Eclipse from the command line, without Eclipse showing even the splash screen.

An example invocation:
[source]
----
182
eclipse.exe -noSplash -consoleLog -data location_of_workspace -application org.eclipse.titan.designer.application.InvokeBuild project_name_to_build
Kristof Szabados's avatar
Kristof Szabados committed
183
184
185
186
187
188
----

This command instructs Eclipse to call our application with the name of the project to be built, while not displaying even the splash screen, redirecting all error log to the console too and using the workspace from the provided location.

The benefit of using this feature over generating the Makefile and building by hand is that this way one will build with the exact same settings he uses inside Eclipse. If for example 3rd party tools are also used as part of the build process, this method will invoke them too properly.

189
==== Building with an External Script
Kristof Szabados's avatar
Kristof Szabados committed
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
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

It is possible to create an XML file for each Eclipse project, which will store all the information needed to create the Makefile and build the project from the command line.

image::images/6_F84.png[title="Generate external builder information"]

In order to create this file, right click on a project and select the *TITAN* / *Generate external builder information* menu entry. This will create a new file in the root of the project called *external_builder_information.xml*

The XSD schema definition of this file looks like:

[source,xml]
----
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" id="TITAN_External_Builder_Information">
  <xs:element name="TITAN_External_Builder_Information">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Makefile_settings">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="useAbsolutePath" type="xs:boolean"/>
              <xs:element name="GNUMake" type="xs:boolean"/>
              <xs:element name="incrementalDependencyRefresh" type="xs:boolean"/>
              <xs:element name="dynamicLinking" type="xs:boolean"/>
              <xs:element name="singleMode" type="xs:boolean"/>
              <xs:element name="codeSplitting">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:pattern value="none|type"/>
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="projectName" type="xs:string"/>
              <xs:element name="projectRoot" type="xs:anyURI"/>
              <xs:element name="workingDirectory" type="xs:anyURI"/>
              <xs:element name="targetExecutable" type="xs:anyURI"/>
              <xs:element name="MakefileScript" type="xs:anyURI"/>
              <xs:element name="MakefileFlags" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="ReferencedProjects">
          <xs:complexType>
            <xs:sequence>
              <xs:element maxOccurs="unbounded" minOccurs="0" name="ReferencedProject">
                <xs:complexType>
                  <xs:attribute name="location" type="xs:anyURI" use="required"/>
                  <xs:attribute name="name" type="xs:string" use="required"/>
                  <xs:attribute name="cygwinPath" type="xs:anyURI"/>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Files">
          <xs:complexType>
            <xs:sequence>
              <xs:element maxOccurs="unbounded" minOccurs="0" name="File">
                <xs:complexType>
                  <xs:attribute name="path" type="xs:anyURI" use="required"/>
                  <xs:attribute name="relativePath" type="xs:anyURI" use="required"/>
                  <xs:attribute name="centralStorage" type="xs:boolean"/>
                  <xs:attribute name="fromProject" type="xs:string"/>
                  <xs:attribute name="cygwinPath" type="xs:anyURI"/>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute name="version" type="xs:decimal"/>
    </xs:complexType>
  </xs:element>
</xs:schema>
----

NOTE: After this information was generated it is the user’s responsibility to create and use the script files that actually do the building of the project.

NOTE: This file will only hold information relevant from the point of view of TITAN. If other tools are also integrated on the project (to help its build, execution) their data will not be included.

269
=== Cleaning the TITAN Project
Kristof Szabados's avatar
Kristof Szabados committed
270
271
272

After switching to a newer version of the test executor or simply to save disk space, the project might need to be cleaned by removing the generated files from the working directory.

Kristof Szabados's avatar
Kristof Szabados committed
273
To remove all generated files from the project, select *Clean* in the *Project* menu option in Eclipse.
Kristof Szabados's avatar
Kristof Szabados committed
274
275
276
277
278

The following files will be deleted from the working directory:

* All object files (files with suffix `.o`) and if applicable, all TITAN generated shared object files (files with suffix `.so`)

279
* All {cpp} sources files translated from the original TTCN–3 and or ASN.1 modules
Kristof Szabados's avatar
Kristof Szabados committed
280
281
282
283
284

* The Compile file

* The executable file

285
=== Pitfalls
Kristof Szabados's avatar
Kristof Szabados committed
286
287
288
289
290
291
292

Every build related action is executed as a command line command. If the command line is not responsive, the tool will not be able to extract messages from it.

In the `Makefile` generation process the size of the longest allowed command can become a serious limitation. For example, on Windows 2000 this number is around 2048 characters by default; this is not enough for larger projects. However, as every command that we try to execute, this is also displayed in the TITAN Console, making it is possible to copy and paste it into a proper command line window (in this case into a Cygwin console).

Manually editing of the `Makefile` can kick off a vicious build cycle if automatic `Makefile` generation is enabled. Explanation: saving a file is a resource change and can start the build process. On the other hand, the build process, with automatic `Makefile` generation enabled, might re-create the `Makefile`. Next, the editor detects that the `Makefile` has been changed and tries to open it which is also a resource changing operation and triggers the build process.

293
294
295
296
297
298
299
300
== Building the TITAN Java Project

=== Step by Step

The following sections describe the steps of the build process. These steps are carried out either automatically by the TITAN plugin or manually by the user; the sections indicate which way applies.

==== Module Compilation

Adam Knapp's avatar
Adam Knapp committed
301
In this step Java source files are generated from TTCN-3 and ASN.1 files. When a Java file already exists, its content is re-checked to decide whether the Java file in question is up-to-date or not. A Java file is refreshed in the current build only if the generated code from the corresponding TTCN–3 or ASN.1 module would be different; otherwise the generated Java file is considered up-to-date.
302
303
304
305
306

The first compilation of the modules will result in addition of the following files in the java_src directory:

* Java files:
+
Adam Knapp's avatar
Adam Knapp committed
307
These are the Java files of the generated Java code. One `.java` file is generated for every TTCN–3 and ASN.1 module in the project with the same name.
308
309
310

Module compilation is done automatically by the build process; no user action is required.

Adam Knapp's avatar
Adam Knapp committed
311
NOTE: The Java files will be located in a Java package that is created using the project's name. This process will also create some subdirectories inside the java_src folder. For more information please refer to section 5.1 of the TITAN Programmer’s Technical Reference guide <<12-references.adoc#_12, [12]>>.
312
313
314
315

[[building-java]]
==== Building

Adam Knapp's avatar
Adam Knapp committed
316
In the final step of the project's building procedure, Eclipse's built-in Java compilation feature is used to compile Test port codes, external functions and the generated Java source codes to executable Java format (`.class` files).
317
318
319
320
321

If automatic building is enabled, Eclipse will invoke the build process whenever project resources change (are created, deleted or updated), or you refresh your project by *right clicking* the project and selecting *Refresh*.

If automatic building (*Project / Build Automatically*) is disabled, then the build process is started by a click on *Project / Build project,* *Project / Build all* or by *right clicking* the project name and selecting *Build*.

Adam Knapp's avatar
Adam Knapp committed
322
The built in Java compiler infrastructure of Eclipse takes the generated code (from the java_src folder), the test ports and external functions (preferably from the user_provided folder) and compiles them into `.class` files generated into the java_bin folder.
323
324
325
326
327
328
329

=== Cleaning the TITAN Java Project

After switching to a newer version of the test executor or simply to save disk space, the project might need to be cleaned by removing the generated files.

To remove all generated files from the project, select *Clean* in the *Project* menu option in Eclipse.

Adam Knapp's avatar
Adam Knapp committed
330
This action will delete all files from the java_src and java_bin folders.