Commit d79c3483 authored by balaskoa's avatar balaskoa
Browse files

C++ changed to {cpp} in each adoc file.


Signed-off-by: default avatarbalaskoa <Jeno.Balasko@ericsson.com>
parent 1f5d8121
......@@ -2,7 +2,7 @@
== Overview
This document describes the TITAN API on C\++ level. It is intended for users who write test port implementation, external function implementation in language C++ and want to use the available resources of TITAN.
This document describes the TITAN API on C\++ level. It is intended for users who write test port implementation, external function implementation in language {cpp} and want to use the available resources of TITAN.
Detailed information can be found on the following topics:
......@@ -10,13 +10,13 @@ Detailed information can be found on the following topics:
* built-in encoding and decoding functions;
* TTCN-3 data mapping to C++ constructs;
* TTCN-3 data mapping to {cpp} constructs;
* troubleshooting for common TTCN-3 related issues and problems.
== Target Groups
This document is intended for advanced users of the TITAN API on C++ level.
This document is intended for advanced users of the TITAN API on {cpp} level.
== Typographical Conventions
......
......@@ -2,21 +2,21 @@
:table-number: 0
:toc:
The C++ source code generated by the Compiler is protocol independent, that is, it does not contain any device specific operations. To provide the connection between the executable test suite and SUT, that is, the physical interface of the test equipmentfootnote:[The test equipment not necessarily requires a special hardware; it can even be a simple PC with an Ethernet interface.], a so-called Test Port is needed.
The {cpp} source code generated by the Compiler is protocol independent, that is, it does not contain any device specific operations. To provide the connection between the executable test suite and SUT, that is, the physical interface of the test equipmentfootnote:[The test equipment not necessarily requires a special hardware; it can even be a simple PC with an Ethernet interface.], a so-called Test Port is needed.
The Test Port is a software library written in C++ language, which is linked to the executable test program. It maps the device specific operations to function calls specified in an API. This chapter describes the Test Port API in details.
The Test Port is a software library written in {cpp} language, which is linked to the executable test program. It maps the device specific operations to function calls specified in an API. This chapter describes the Test Port API in details.
== Generating the Skeleton
The functions of Test Ports must be written by the user who knows the interface between the executable test suite and the test equipment. In order to make this development easier, the Compiler can generate Test Port skeletons. A Test Port belongs to one certain TTCN–3 port type, so the skeleton is generated based on port type definitions.
A Test Port consists of two parts. One part is generated automatically by the Compiler, and it is put into the generated C++ code. The user has nothing to do with this part.
A Test Port consists of two parts. One part is generated automatically by the Compiler, and it is put into the generated {cpp} code. The user has nothing to do with this part.
The other part is a C\++ class, which is written mainly by the user. This class can be found in a separate C++ header and source file (their suffixes are `.hh` and `.cc`, respectively). The names of the source files and the C++ class are identical to the name of the port type. Please note that the name mapping rules described in <<5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc#mapping-of-names-and-identifiers, Mapping of Names and Identifiers>> also apply to these class and file names.
The other part is a C\++ class, which is written mainly by the user. This class can be found in a separate {cpp} header and source file (their suffixes are `.hh` and `.cc`, respectively). The names of the source files and the {cpp} class are identical to the name of the port type. Please note that the name mapping rules described in <<5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc#mapping-of-names-and-identifiers, Mapping of Names and Identifiers>> also apply to these class and file names.
During the translation, when the Compiler encounters a port type definition and the `*–t*` command line switch is used, it checks whether the header and source files of Test Port exist in its working directory. If none of them can be found there, the compiler generates the skeleton header and source files for the corresponding test port automatically. This means, once you have generated (and possibly modified) a skeleton, it will never be overwritten. If you want to re-generate the skeleton, you must rename or remove the existing one.
If the list of message types/signatures of a TTCN-3 port type changes, the list of the Test Port class member functions also needs to change. If the Test Port skeleton has been generated, it will not be modified, resulting in build errors (C++ compile errors like "cannot declare variable of abstract type"/"virtual functions are pure", or linker errors). In this case, the Test Port skeleton files should be renamed/moved, the skeleton generated, and any user-written code should be copied back into the newly generated source files.
If the list of message types/signatures of a TTCN-3 port type changes, the list of the Test Port class member functions also needs to change. If the Test Port skeleton has been generated, it will not be modified, resulting in build errors ({cpp} compile errors like "cannot declare variable of abstract type"/"virtual functions are pure", or linker errors). In this case, the Test Port skeleton files should be renamed/moved, the skeleton generated, and any user-written code should be copied back into the newly generated source files.
If you have defined a TTCN–3 port type that you intend to use for internal communication only (that is, for sending and receiving messages between TTCN–3 test components), you do not need to generate and compile an empty Test Port skeleton for that port type. Adding the attribute with `{extension "internal"}` to the port type definition in the TTCN–3 module disables the generation and use of a Test Port for the port type.
......@@ -558,7 +558,7 @@ incoming_message(const CHARSTRING& incoming_par);
Receiving operations on procedure based ports is similar to receiving messages on message based ports. The difference is that there are different overloaded incoming functions for call, reply and raise operations called `incoming_call`, `incoming_reply` and `incoming_exception`, respectively. The event handler (when called) must recognize the type of operation on receiving and call one of these functions accordingly with one of the internal representations of the signature (see <<5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc #additional-non-standard-functions, Additional Non-Standard Functions>>).
In the examplefootnote:[In the example the signatures were defined in a different TTCN–3 module named MyModule2, as a consequence all types defined in that module must be prefixed with the C++ namespace name of that module.] the class `MyProcedurePort_BASE` has the following member functions for incoming operations:
In the examplefootnote:[In the example the signatures were defined in a different TTCN–3 module named MyModule2, as a consequence all types defined in that module must be prefixed with the {cpp} namespace name of that module.] the class `MyProcedurePort_BASE` has the following member functions for incoming operations:
[source]
----
incoming_call(const MyModule2::inProc_call& incoming_par);
......@@ -689,7 +689,7 @@ This section summarizes only the differences from the normal Test Port API:
* The Test Port header file must not include the generated header file of the corresponding TTCN–3 module. The common header file of the Base Library called TTCN3.hh shall be included instead. The source file of the Test Port may include any header file without restriction.
* The member functions of the Test Port may refer to C++ classes that are generated from user-defined message types and signatures. To avoid compilation failures the declarations of the referenced classes must be added to the beginning of the header file. At the moment the Test Port skeleton generator has a limitation that it cannot collect the class declarations from the port type, so they must be added manually. Please note that if a message type or signature is imported from another module the corresponding class declaration must be put into the appropriate namespace.
* The member functions of the Test Port may refer to {cpp} classes that are generated from user-defined message types and signatures. To avoid compilation failures the declarations of the referenced classes must be added to the beginning of the header file. At the moment the Test Port skeleton generator has a limitation that it cannot collect the class declarations from the port type, so they must be added manually. Please note that if a message type or signature is imported from another module the corresponding class declaration must be put into the appropriate namespace.
The following example shows the generated Test Port skeleton of a provider port type.
......@@ -880,7 +880,7 @@ void MyPortType::log(const char *fmt, ...)
=== Error Handling
None of the Test Port member functions have return value like a status code. If a function returns normally, the run-time environment assumes that it has performed its task successfully. The handling of run-time errors is done in a special way, using C++ exceptions. This simplifies the program code because the return values do not have to be checked everywhere and dynamically created complex error messages can be used if necessary.
None of the Test Port member functions have return value like a status code. If a function returns normally, the run-time environment assumes that it has performed its task successfully. The handling of run-time errors is done in a special way, using {cpp} exceptions. This simplifies the program code because the return values do not have to be checked everywhere and dynamically created complex error messages can be used if necessary.
If any kind of fatal error is encountered anywhere in the Test Port, the following function should be called:
[source, subs="+quotes"]
......
......@@ -30,7 +30,7 @@ The generated, runtime specific (load-test or function-test) header file `TitanL
#endif
----
Unfortunately, the `dlopen()` API is a C API, not a C\++ API, but each logger plug-in is a class, which needs to be instantiated. To resolve this, the logger plug-ins are always instantiated and destroyed through C factory functions. These functions are mandatory for all logger plug-ins and they must follow C-style linkage rules. Otherwise, the function names would be mangled by the C++ compiler, using its own, implementation dependent mangling mechanism, and `dlsym()` and such functions would not be able to locate the correct symbol in the SOs of the logger plug-ins. These functions look pretty simple:
Unfortunately, the `dlopen()` API is a C API, not a C\++ API, but each logger plug-in is a class, which needs to be instantiated. To resolve this, the logger plug-ins are always instantiated and destroyed through C factory functions. These functions are mandatory for all logger plug-ins and they must follow C-style linkage rules. Otherwise, the function names would be mangled by the {cpp} compiler, using its own, implementation dependent mangling mechanism, and `dlsym()` and such functions would not be able to locate the correct symbol in the SOs of the logger plug-ins. These functions look pretty simple:
[source]
----
#ifdef __cplusplus
......@@ -79,7 +79,7 @@ void log(const TitanLoggerApi::TitanLogEvent& event, bool
The first parameter event is the event itself, the second parameter `log_buffered` indicates, whether the event is coming from an internal buffer or not, `separate_file` and `use_emergency_mask` are configuration options for emergency logging. The `use_emergency_mask` flag indicates that the given event is an emergency event and should be handled in a special way by the plug-ins, the `separate_file` flag indicates that all the emergency events should be handled separately (for example written into a separate file). For more details on emergency logging please check link:https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide[Programmer's Technical Reference]. In this function, the plug-in can handle the log events individually depending on the event’s type (that is, the alternative selected in the union `event.logEvent().choice()).`
`TitanLoggerApi::TitanLogEvent` is a generated type defined in TitanLoggerApi.xsd, which can be found in `${TTCN3_DIR}/include`. This file contains all the necessary type definitions a logger plug-in should be aware of. The corresponding header files generated from this XSD file can be found in `${TTCN3_DIR}/include/{RT1/RT2}`. The mapping between TTCN-3 types and C\++ types is defined in link:5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc[Mapping TTCN–3 Data Types to C++ Constructs].
`TitanLoggerApi::TitanLogEvent` is a generated type defined in TitanLoggerApi.xsd, which can be found in `${TTCN3_DIR}/include`. This file contains all the necessary type definitions a logger plug-in should be aware of. The corresponding header files generated from this XSD file can be found in `${TTCN3_DIR}/include/{RT1/RT2}`. The mapping between TTCN-3 types and C\++ types is defined in link:5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc[Mapping TTCN–3 Data Types to {cpp} Constructs].
//The mapping between XSD and TTCN-3 types is defined in *Error! Reference source not found.*
== Execution
......
......@@ -351,7 +351,7 @@ When a compound type is only used internally or it is never RAW encoded/decoded
[[api-0]]
=== API
The C++ Application Programming Interface for RAW encoding and decoding is described in the following. It can be used for example in test port implementation, in external function implementation.
The {cpp} Application Programming Interface for RAW encoding and decoding is described in the following. It can be used for example in test port implementation, in external function implementation.
[[encoding-0]]
==== Encoding
......
......@@ -5,34 +5,34 @@
Information not fitting in any of the previous chapters is given in this chapter.
[[migrating-existing-c-code-to-the-naming-rules-of-version-1-7]]
== Migrating Existing C++ Code to the Naming Rules of Version 1.7
== Migrating Existing {cpp} Code to the Naming Rules of Version 1.7
When using the new naming rulesfootnote:[The new naming rules are used by default; the naming rules can be changed using the compiler command line switch -N.] the compiler generates a C\++ namespace for each TTCN–3 and ASN.1 module. The name of the namespace corresponds to the module. The generated C++ entities of a module are all placed in its namespace; therefore all the test port or protocol module code must use these namespaces.
When using the new naming rulesfootnote:[The new naming rules are used by default; the naming rules can be changed using the compiler command line switch -N.] the compiler generates a C\++ namespace for each TTCN–3 and ASN.1 module. The name of the namespace corresponds to the module. The generated {cpp} entities of a module are all placed in its namespace; therefore all the test port or protocol module code must use these namespaces.
Rules to follow when writing C++ code:
Rules to follow when writing {cpp} code:
* When referencing an entity located in a different module its C++ name has to be prefixed with the namespace name of that module.
* When referencing an entity located in a different module its {cpp} name has to be prefixed with the namespace name of that module.
* A test port class must be placed into the namespace of its module.
* Encoding and decoding functions must be placed into the namespace of the TTCN–3 module in which the external function was defined.
* All C\++ entities have to be placed into namespace. An exception to this may be C++ entities used only locally; these are defined with the keyword `static`.
* All C\++ entities have to be placed into namespace. An exception to this may be {cpp} entities used only locally; these are defined with the keyword `static`.
* For convenience the `using namespace` directive can be used in C++ source files. It is forbidden to use this directive in header files!
* For convenience the `using namespace` directive can be used in {cpp} source files. It is forbidden to use this directive in header files!
* C++ enum types are placed in the scope of their value class; enum types have to be prefixed by the C++ name of the value class.footnote:[The enum hack option has become obsolete with the new naming rules.]
* {cpp} enum types are placed in the scope of their value class; enum types have to be prefixed by the {cpp} name of the value class.footnote:[The enum hack option has become obsolete with the new naming rules.]
[[using-external-c-functions-in-ttcn-3-test-suites]]
== Using External C++ Functions in TTCN–3 Test Suites
== Using External {cpp} Functions in TTCN–3 Test Suites
Sometimes standard library functionsfootnote:[C language functions cannot be called directly from TTCN–3; you need at least a wrapper function for them.] are called in the test suite or there is a need for efficiently implemented "bit-crunching" functions in the TTCN–3 ATS. In these cases functions to be called from the test suite can be developed in C++.
Sometimes standard library functionsfootnote:[C language functions cannot be called directly from TTCN–3; you need at least a wrapper function for them.] are called in the test suite or there is a need for efficiently implemented "bit-crunching" functions in the TTCN–3 ATS. In these cases functions to be called from the test suite can be developed in {cpp}.
There are the standard library functions as well as other libraries in the C++ functions. The logging and error handling facilities of the run-time environment are also available as in case of Test Ports.
There are the standard library functions as well as other libraries in the {cpp} functions. The logging and error handling facilities of the run-time environment are also available as in case of Test Ports.
Since version 1.4.pl1 the semantic analyzer of the compiler checks the import statements thoroughly. Therefore one cannot use the virtual C++ modules as before: C++ functions must be defined as external functions to be accessible from TTCN–3 modules.
Since version 1.4.pl1 the semantic analyzer of the compiler checks the import statements thoroughly. Therefore one cannot use the virtual {cpp} modules as before: {cpp} functions must be defined as external functions to be accessible from TTCN–3 modules.
For example, the following definitions make two C++ functions accessible from TTCN–3 module `MyModule` and from any other module that imports `MyModule`.
For example, the following definitions make two {cpp} functions accessible from TTCN–3 module `MyModule` and from any other module that imports `MyModule`.
[[example-ttcn-3-module-mymodule-ttcn]]
=== Example TTCN–3 Module (MyModule.ttcn)
......@@ -49,7 +49,7 @@ module MyModule {
}
----
The compiler will translate those external function definitions to C++ function prototypes in the generated header file `MyModule.hh`:
The compiler will translate those external function definitions to {cpp} function prototypes in the generated header file `MyModule.hh`:
[source]
----
......@@ -59,17 +59,17 @@ The compiler will translate those external function definitions to C++ function
[...]
----
Both pre-defined and user-defined TTCN–3 data types can be used as parameters and/or return types of the C\++ functions. The detailed description of the equivalent C++ classes as well as the name mapping rules are described in chapter <<4-encoding_and_decoding.adoc#xml-encoding-xer,XML Encoding (XER)>>.
Both pre-defined and user-defined TTCN–3 data types can be used as parameters and/or return types of the C\++ functions. The detailed description of the equivalent {cpp} classes as well as the name mapping rules are described in chapter <<4-encoding_and_decoding.adoc#xml-encoding-xer,XML Encoding (XER)>>.
Using templates as formal parameters in external functions is possible, but not recommended because the API of the classes realizing templates is not documented and subject to change without notice.
The formal parameters of external TTCN–3 functions are mapped to C++ function parameters according to the following table:
The formal parameters of external TTCN–3 functions are mapped to {cpp} function parameters according to the following table:
.TTCN–3 formal parameters and their C++ equivalents
.TTCN–3 formal parameters and their {cpp} equivalents
[cols=",",options="header",]
|==============================================
|TTCN–3 formal parameter |Its C++ equivalent
|TTCN–3 formal parameter |Its {cpp} equivalent
|`[in] MyType myPar` |`const MyType& myPar`
|`out MyType myPar` |`MyType& myPar`
|`inout MyType myPar` |`MyType& myPar`
......@@ -78,11 +78,11 @@ The formal parameters of external TTCN–3 functions are mapped to C++ function
NOTE: In versions 1.6.pl3 and earlier the in keyword had an extra meaning in formal parameter lists. According to the TTCN–3 standard the parameter definitions `MyType myPar` and in `MyType myPar` are totally equivalent, but the earlier versions of the compiler distinguished them. Unless the keyword `in` was present the compiler passed the parameter by value (involving a copy constructor call) instead of using a const reference. That is why it was recommended to use an explicit in keyword in parameter lists of external functions.
Due to the strictness of the TTCN–3 semantic analyzer one cannot use C/C++ data types with external functions as formal parameters or return types, only TTCN–3 and ASN.1 data types are allowed. Similarly, one cannot use pointers as parameters or return values because they have no equivalents in TTCN–3 .
Due to the strictness of the TTCN–3 semantic analyzer one cannot use C/{cpp} data types with external functions as formal parameters or return types, only TTCN–3 and ASN.1 data types are allowed. Similarly, one cannot use pointers as parameters or return values because they have no equivalents in TTCN–3 .
The external functions can be implemented in one or more C\++ source files. The generated header file that contains the prototypes of the external functions shall be included into each C++ source file. This file makes accessible all built-in data types, the user-defined types of the corresponding TTCN–3 module and all available services of the run-time environment (logging, error handling, etc.).
The external functions can be implemented in one or more C\++ source files. The generated header file that contains the prototypes of the external functions shall be included into each {cpp} source file. This file makes accessible all built-in data types, the user-defined types of the corresponding TTCN–3 module and all available services of the run-time environment (logging, error handling, etc.).
The name, return type and the parameters of the implemented C++ functions must match exactly the generated function prototypes or the compilation will fail. The generated function prototype is in the namespace of the module, therefore the implementation of the function has to be placed in that namespace, too.
The name, return type and the parameters of the implemented {cpp} functions must match exactly the generated function prototypes or the compilation will fail. The generated function prototype is in the namespace of the module, therefore the implementation of the function has to be placed in that namespace, too.
[[logging-in-test-ports-or-external-functions]]
== Logging in Test Ports or External Functions
......@@ -168,7 +168,7 @@ static void TTCN_Logger::OS_error();
==== log
The C++ classes of predefined and compound data types are equipped with a member function called `log`. This function puts the actual value of the variable at the end of current buffer. Unbound variables and fields are denoted by the symbol `<unbound>`. The contents of TTCN–3 value objects can be logged only in buffered mode.
The {cpp} classes of predefined and compound data types are equipped with a member function called `log`. This function puts the actual value of the variable at the end of current buffer. Unbound variables and fields are denoted by the symbol `<unbound>`. The contents of TTCN–3 value objects can be logged only in buffered mode.
[source, subs="+quotes"]
void <any TTCN-3 type>::log() const;
......@@ -201,7 +201,7 @@ Differences between the formats:
The "-" symbol is the NotUsedSymbol which can be used inside compound values, but when logging an unbound value which is not inside a record or record of the TTCN-3 output format of the logger is actually not a legal TTCN-3 value/template because a value or template cannot be set to be unbound. Thus this output format can be copy-pasted from a log file into a ttcn-3 file or to a module parameter value in a configuration file only if it semantically makes sense.
The C++ API extensions to change the logging format: +
The {cpp} API extensions to change the logging format: +
A new enum type for the format in TTCN_Logger class:+
`enum data_log_format_t { LF_LEGACY, LF_TTCN }`; +
Static functions to get/set the format globally: +
......@@ -238,7 +238,7 @@ The above code fragment will produce three lines in the log in the following ord
`second message`
`first message`
If the code calls a C++ function that might throw an exception while the logger has an active event buffer care must be taken that event is properly finished during stack unwinding. Otherwise the stack of the logger and the call stack of the program will get out of sync. The following example illustrates the proper usage of buffered mode with exceptions:
If the code calls a {cpp} function that might throw an exception while the logger has an active event buffer care must be taken that event is properly finished during stack unwinding. Otherwise the stack of the logger and the call stack of the program will get out of sync. The following example illustrates the proper usage of buffered mode with exceptions:
[source]
----
TTCN_Logger::begin_event(TTCN_DEBUG);
......@@ -261,7 +261,7 @@ If a fatal error is encountered in the Test Port, you should call the function `
[source, subs="+quotes"]
void TTCN_error(const char *fmt, …);
The parameter `fmt` contains the reason of the error in a NUL terminated character string in the format of a `printf` format string. If necessary, additional values should be passed to `TTCN_error` as specified in the format string. The error handling in the executable test program is implemented using C++ exceptions so the function `TTCN_error` never returns; instead, it throws an exception. The exception value contains an instance of the empty class called `TC_Error`. This exception is normally caught at the end of each test case and module control part. After logging the reason `TTCN_Logger::OS error()` is called. Finally, the verdict is set to error and the test executor performs an error recovery, so it continues the execution with the next test case.
The parameter `fmt` contains the reason of the error in a NUL terminated character string in the format of a `printf` format string. If necessary, additional values should be passed to `TTCN_error` as specified in the format string. The error handling in the executable test program is implemented using {cpp} exceptions so the function `TTCN_error` never returns; instead, it throws an exception. The exception value contains an instance of the empty class called `TC_Error`. This exception is normally caught at the end of each test case and module control part. After logging the reason `TTCN_Logger::OS error()` is called. Finally, the verdict is set to error and the test executor performs an error recovery, so it continues the execution with the next test case.
It is not recommended to use own error recovery combined with the default method (that is, catching this exception).
......@@ -271,11 +271,11 @@ The UNIX signals may interrupt the normal execution of programs. This may happen
In the executable test program there are system calls not only in the Base Library, but in Test Ports as well. Since the other Test Ports that you are using may have been written by many developers, one cannot be sure that they are prepared to the effects of signals. So it is recommended to avoid using signals in Test Ports.
== Mixing C and C++ Modules
== Mixing C and {cpp} Modules
Modules written in C language may be used in the Test Ports. In this case the C header files must be included into the Test Port source code and the object files of the C module must be linked to the executable. Using a C compiler to compile the C modules may lead to errors when linking the modules together. This is because the C and C\++ compilers use different rules for mapping function names to symbol names of the object file to avoid name clashes caused by the C++ polymorphism. There are two possible solutions to solve this problem:
Modules written in C language may be used in the Test Ports. In this case the C header files must be included into the Test Port source code and the object files of the C module must be linked to the executable. Using a C compiler to compile the C modules may lead to errors when linking the modules together. This is because the C and C\++ compilers use different rules for mapping function names to symbol names of the object file to avoid name clashes caused by the {cpp} polymorphism. There are two possible solutions to solve this problem:
1. Use the same C++ compiler to compile all of your source code (including C modules).
1. Use the same {cpp} compiler to compile all of your source code (including C modules).
2. If the first one is impossible (when using a third party software that is available in binary format only), the definitions of the C header file must be put into an `extern "C"` block like this.
[source]
----
......@@ -290,4 +290,4 @@ extern "C" {
#endif
----
The latter solution does not work with all C\++ compilers; it was tested on GNU C++ compiler only.
The latter solution does not work with all C\++ compilers; it was tested on GNU {cpp} compiler only.
......@@ -20,7 +20,7 @@ endif::[]
*Abstract*
This document describes detailed information on the TITAN Application Programming Interface (API) on C++ level, advanced TTCN–3 programming, and background information on the TITAN TTCN–3 Test Executor project.
This document describes detailed information on the TITAN Application Programming Interface (API) on {cpp} level, advanced TTCN–3 programming, and background information on the TITAN TTCN–3 Test Executor project.
*Copyright*
......@@ -39,7 +39,7 @@ ifdef::env-github,backend-html5[]
* link:2-test_ports.adoc[Test Ports]
* link:3-logger_plug-ins.adoc[Logger Plug-ins]
* link:4-encoding_and_decoding.adoc[Encoding and Decoding]
* link:5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc[Mapping TTCN–3 Data Types to C++ Constructs]
* link:5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc[Mapping TTCN–3 Data Types to {cpp} Constructs]
* link:6-tips_&_troubleshooting.adoc[Tips & Troubleshooting]
* link:7-references.adoc[References]
* link:8-abbreviations.adoc[Abbreviations]
......
......@@ -149,11 +149,11 @@ Download the Titan package for your platform, OS and GCC version from the provid
* For users outside Ericsson: https://projects.eclipse.org/projects/tools.titan/downloads. This version is licensed under the Eclipse Public License.
A binary distribution, suitable for the used operating system (Solaris, Linux, FreeBSD), and for a C++ compiler, in a tar-gzip archive will be received. For Windowsfootnote:[For using TITAN on Windows platforms, installing the Cygwin programming environment is required see chapter 1.5 Installing Prerequisites on Cygwin (on Windows)] users there is no pre-built version, but compiling the open-source version is possible.
A binary distribution, suitable for the used operating system (Solaris, Linux, FreeBSD), and for a {cpp} compiler, in a tar-gzip archive will be received. For Windowsfootnote:[For using TITAN on Windows platforms, installing the Cygwin programming environment is required see chapter 1.5 Installing Prerequisites on Cygwin (on Windows)] users there is no pre-built version, but compiling the open-source version is possible.
WARNING: the version of C++ compiler used is important. If the version difference between the system’s compiler and the compiler that the basic TTCN–3 library was built with is large enough, the linking of executable test suites will fail with strange error messages. The reason is the different mapping of C++ class and (polymorphic) member function names into linker symbols. For example, this problem persists between versions 2.8.x and 2.95.x of GCC. Different C++ compilers (e.g. Sun Workshop and GCC) are, of course, totally incompatible. The solution for this problem is to use nearly the same version of the C++ compiler as the binary package was built with.
WARNING: the version of {cpp} compiler used is important. If the version difference between the system’s compiler and the compiler that the basic TTCN–3 library was built with is large enough, the linking of executable test suites will fail with strange error messages. The reason is the different mapping of {cpp} class and (polymorphic) member function names into linker symbols. For example, this problem persists between versions 2.8.x and 2.95.x of GCC. Different {cpp} compilers (e.g. Sun Workshop and GCC) are, of course, totally incompatible. The solution for this problem is to use nearly the same version of the {cpp} compiler as the binary package was built with.
Binaries for other operating systems or C++ compilers are available only on request.
Binaries for other operating systems or {cpp} compilers are available only on request.
== Installing the Package
......@@ -169,16 +169,16 @@ or +
The following sub-directories are created:
* `bin` contains the executable programs: The Compiler, the Makefile Generator, the Main Controller for parallel test execution and two log formatter utilities.
* `etc` contains a demo license key, which enables to use the parser parts of the Compiler by any user on any host, that is, without C++ code generation. The installation can be tested with this demo key until the personalized license key is received.
* `include` contains the C+/+ header files needed to compile the generated C++ code.
* `lib` contains the pre-compiled Base Library for use with the generated C++ code both for single and parallel mode in static and dynamic linkingfootnote:[Note that not all platforms support dynamic linking.] formats.
* `etc` contains a demo license key, which enables to use the parser parts of the Compiler by any user on any host, that is, without {cpp} code generation. The installation can be tested with this demo key until the personalized license key is received.
* `include` contains the C+/+ header files needed to compile the generated {cpp} code.
* `lib` contains the pre-compiled Base Library for use with the generated {cpp} code both for single and parallel mode in static and dynamic linkingfootnote:[Note that not all platforms support dynamic linking.] formats.
* `man` contains UNIX manual pages (for the Compiler and the Makefile Generator).
* `demo` contains a simple TTCN–3 test suite ("Hello, world!") together with a sample test port and a compiled executable.
* `doc` contains this documentation in PostScript and PDF formats.
To complete the TITAN TTCN–3 Test Executor installation, some environmental variables should be set and the login script should be modified.
NOTE: The C++ source code generated by this version (patch level) of Compiler is not compatible with older versions of TTCN–3 Base Library and vice versa.footnote:[Sometimes even the linking fails; but a successful linking does not mean that everything is correct at all.]If upgrading TITAN from an older version, all modules of existing test suites must be re-translated with the new compiler in order to make them running with the new libraries.
NOTE: The {cpp} source code generated by this version (patch level) of Compiler is not compatible with older versions of TTCN–3 Base Library and vice versa.footnote:[Sometimes even the linking fails; but a successful linking does not mean that everything is correct at all.]If upgrading TITAN from an older version, all modules of existing test suites must be re-translated with the new compiler in order to make them running with the new libraries.
It is recommended to make a backup copy of the older version of the distribution. There are some minor incompatibilities in the compiler’s grammar that may cause many syntax errors in TTCN–3 modules that were translated correctly with earlier versions.
......@@ -195,8 +195,8 @@ Currently it is experimental to use TITAN with clang on Ubuntu operating system.
There are some important notes about using clang with TITAN:
* The C++ source code generated and TITAN must be compiled with the same version of clang. See section 2.2 note.
* Makefiles of TTCN-3 projects must be modified by hand(replace *CXX = g++* with *CXX = clang++3.8*). Or regenerated using *makefilegen*, to use clang compiler. TITAN’s *makefilegen* can detect if it was compiled with clang and will generate makefiles with clang as default C++ compiler.
* The {cpp} source code generated and TITAN must be compiled with the same version of clang. See section 2.2 note.
* Makefiles of TTCN-3 projects must be modified by hand(replace *CXX = g++* with *CXX = clang++3.8*). Or regenerated using *makefilegen*, to use clang compiler. TITAN’s *makefilegen* can detect if it was compiled with clang and will generate makefiles with clang as default {cpp} compiler.
* Required clang version is *3.8*.
= Building Titan from source code
......
......@@ -2,7 +2,7 @@
Note: the feature described here is deprecated; please use instead the coverage tool described in <<4-ttcn3_language_extensions.adoc#profiling-and-code-coverage, Profiling and code coverage>>.
The TTCN-3 compiler is able to instrument the generated C/C++ code for a set of TTCN-3 modules (= or files) to generate code coverage information during runtime. To enable this feature the `-K file` option needs to be used. For convenience this option is available for `ttcn3_makefilegen` as well. It’s possible to generate code coverage information only for a given set of TTCN-3 modules listed on the command line. In that case the set of files in `file` needs to be a subset of the files listed on the command line. If `file` contains a file which is not listed on the command line an error will be issued.
The TTCN-3 compiler is able to instrument the generated C/{cpp} code for a set of TTCN-3 modules (= or files) to generate code coverage information during runtime. To enable this feature the `-K file` option needs to be used. For convenience this option is available for `ttcn3_makefilegen` as well. It’s possible to generate code coverage information only for a given set of TTCN-3 modules listed on the command line. In that case the set of files in `file` needs to be a subset of the files listed on the command line. If `file` contains a file which is not listed on the command line an error will be issued.
== Generating Code Coverage
......
......@@ -4,7 +4,7 @@
The TTCN-3 debugger is a feature in TITAN, which allows the user to pause (halt) the execution of a TTCN-3 program and print (or in some cases overwrite) information about the current state of the program.
The compiler option `–n` activates the debugger and augments the generated C++ code to store debug information and to allow the addition of breakpoints at runtime. For convenience this option is available for `ttcn3_makefilegen` as well.
The compiler option `–n` activates the debugger and augments the generated {cpp} code to store debug information and to allow the addition of breakpoints at runtime. For convenience this option is available for `ttcn3_makefilegen` as well.
== Gathered information
......
......@@ -13,7 +13,7 @@ The type aliasing is implemented in the test executor, but it translates this TT
`typedef MyType MyAlternativeName;`
The limitation of the C typedef is that the C\++ compiler cannot distinguish between the original and alias name in polymorphism (i.e. the identically named functions with parameter type `MyType` and `MyAlternativeName` are treated as same). That is, if you define a port type that allows the sending or receiving both of the original and aliased type, the generated C++ code cannot be compiled because the Test Port class contains two identical send/receive function.
The limitation of the C typedef is that the C\++ compiler cannot distinguish between the original and alias name in polymorphism (i.e. the identically named functions with parameter type `MyType` and `MyAlternativeName` are treated as same). That is, if you define a port type that allows the sending or receiving both of the original and aliased type, the generated {cpp} code cannot be compiled because the Test Port class contains two identical send/receive function.
As a work-around to this problem you can repeat the definition of the original type using the alternative name instead of type aliasing. In this case two differently named, but identical classes will be generated and the polymorphism problem will not occur.
......@@ -42,7 +42,7 @@ NOTE: This feature, as preprocessors in general, should be avoided if not absolu
Tips for the `Makefile` generated using the option `-p:`
* All the options for the C precompiler can be specified using the variable `CPPFLAGS_TTCN3`. Do not confuse it with the variable `CPPFLAGS`, which is used on the generated C++ code. If standard TTCN-3 output is needed the flag `-P` has to be added manually to the variable `CPPFLAGS_TTCN3`. The resulting `ttcn` files can be compiled with any TTCN-3 compiler (if other special language extensions are not used). Globally used preprocessor symbols can be defined here with the option `-D`. For example to compile the debug version of a project a `DEBUG` symbol can be specified with `-DDEBUG`.
* All the options for the C precompiler can be specified using the variable `CPPFLAGS_TTCN3`. Do not confuse it with the variable `CPPFLAGS`, which is used on the generated {cpp} code. If standard TTCN-3 output is needed the flag `-P` has to be added manually to the variable `CPPFLAGS_TTCN3`. The resulting `ttcn` files can be compiled with any TTCN-3 compiler (if other special language extensions are not used). Globally used preprocessor symbols can be defined here with the option `-D`. For example to compile the debug version of a project a `DEBUG` symbol can be specified with `-DDEBUG`.
* Files which are included in the `.ttcnpp` source files (with `#include`) and do not need to be translated can be specified in the `TTCN3_INCLUDES` variable. These files will be checked for modification when the `.ttcnpp` files are processed by `make`; any modification will trigger preprocessing of all the `.ttcnpp` files and the recompilation of the affected modules. If the suffix of a file is `.ttcnin` the Makefile Generator will add it to `TTCN3_INCLUDES`; in all other cases the file has to be added manually.
......@@ -251,9 +251,9 @@ with { extension "prototype (convert) decode(XER:XER_EXTENDED)" }
}
----
The "prototype (convert)" attribute instructs the compiler to generate a C++ implementation for each of the external functions (see section 4.22.4 above). This permits the use of the encoding/decoding functions directly from TTCN-3 code.
The "prototype (convert)" attribute instructs the compiler to generate a {cpp} implementation for each of the external functions (see section 4.22.4 above). This permits the use of the encoding/decoding functions directly from TTCN-3 code.
In case more sophisticated processing is required (or some form of pre/postprocessing), the encoder/decoder functions can be reimplemented in C++. The basic functionality provided by the compiler can be used as a starting point.
In case more sophisticated processing is required (or some form of pre/postprocessing), the encoder/decoder functions can be reimplemented in {cpp}. The basic functionality provided by the compiler can be used as a starting point.
NOTE: In this case all the ``with'' attributes in the example above must be removed from the external function declaration (otherwise the compiler will generate the functions again with the same signature and duplicate symbol errors will appear at link time).
......
......@@ -3,7 +3,7 @@
The present Test Executor is an implementation of TTCN–3 Core Language standard (<<13-references.adoc#_1, [1]>>) with support of ASN.1 (<<13-references.adoc#_3, [3]>>). However, the following TTCN–3 language constructs are not supported in the current version of the Test Executor. When applicable, the relevant clause of the standard text (<<13-references.adoc#_1, [1]>>) is given within parentheses after each limitation. The list of ASN.1 related limitations can be found in chapter *4.25*.
* C++ code generation for parameterized local templates is not supported.footnote:[The semantic analyzer is able to verify modules with such definitions, but the generated C++ code will be incomplete or erroneous.] (5.0, relevant cells of Table 1)
* {cpp} code generation for parameterized local templates is not supported.footnote:[The semantic analyzer is able to verify modules with such definitions, but the generated {cpp} code will be incomplete or erroneous.] (5.0, relevant cells of Table 1)
* Parameterized TTCN–3 `record`, `set` and `union types`. (5.4 in <<13-references.adoc#_1, [1]>>))
* TTCN–3 sub-typing constraints are checked only at compilation time. In the run-time environment the restricted types are substituted with the corresponding base type and no run-time error is produced if the assigned value violates the subtype constraint.
* The special TTCN–3 type `anytype` is supported with restrictions. (6.2.6 in <<13-references.adoc#_1, [1]>>)
......
......@@ -11,7 +11,7 @@ The compiler does not report an error or warning if the semi-colon is missing at
The statement block is optional after the guard operations of `altsteps`, `alt` and `interleave` constructs and in the response and exception handling part of `call` statements. A missing statement block has the same meaning as an empty statement block. If the statement block is omitted, a terminating semi-colon must be present after the guard statement.
The standard escape sequences of C/C++ programming languages are recognized and accepted in TTCN–3 character string values, that is, in literal values of `charstring` and `universal` `charstring` types, as well as in the arguments of built-in operations `log()` and `action()`.
The standard escape sequences of C/{cpp} programming languages are recognized and accepted in TTCN–3 character string values, that is, in literal values of `charstring` and `universal` `charstring` types, as well as in the arguments of built-in operations `log()` and `action()`.
NOTE: As a consequence of the extended escape sequences and in contrast with the TTCN–3 standard, the backslash character itself has to be always duplicated within character string values.
......@@ -205,9 +205,9 @@ Types imported from another module (elsewhere) can be added to the anytype of th
== Ports and Test Configurations
If all instances of a TTCN–3 port type are intended to be used for internal communication only (i.e. between two TTCN–3 test components) the generation and linking of an empty Test Port skeleton can be avoided. If the attribute `with { extension "internal" }` is appended to the port type definition, all C++ code that is needed for this port will be included in the output modules.<<13-references.adoc#_9, [9]>>
If all instances of a TTCN–3 port type are intended to be used for internal communication only (i.e. between two TTCN–3 test components) the generation and linking of an empty Test Port skeleton can be avoided. If the attribute `with { extension "internal" }` is appended to the port type definition, all {cpp} code that is needed for this port will be included in the output modules.<<13-references.adoc#_9, [9]>>
If the user wants to use `address` values in `to` and `from` clause and sender redirect of TTCN–3 port operations the `with { extension "address" }` attribute shall be used in the corresponding port type definition(s) to generate proper C++ code.
If the user wants to use `address` values in `to` and `from` clause and sender redirect of TTCN–3 port operations the `with { extension "address" }` attribute shall be used in the corresponding port type definition(s) to generate proper {cpp} code.
NOTE: When address is used in port operations the corresponding port must have an active mapping to a port of the test system interface, otherwise the operation will fail at runtime. Using of address values in to and from clauses implicitly means system as component reference. (See section "Support of address type" in <<13-references.adoc#_16, [16]>> for more details).<<13-references.adoc#_10, [10]>>
......@@ -268,7 +268,7 @@ The compiler realizes TTCN–3 `interleave` statements using a different approac
* Loop constructs `for`, `while` and `do-while` loops are accepted and supported without any restriction in `interleave` statements. The transformation of statements is done in a lower level than the TTCN–3 language, which does not restrict the embedded loops.
* Statements `activate`, `deactivate` and `stop` can also be used within `interleave`. The execution of these statements is atomic so we did not see the reason why the standard forbids them.
* The size of our generated code is linear in contrast to the exponential code growth of the canonical algorithm. In other words, the C++ equivalent of every embedded statement appears exactly once in the output.
* The size of our generated code is linear in contrast to the exponential code growth of the canonical algorithm. In other words, the {cpp} equivalent of every embedded statement appears exactly once in the output.
* The run-time realization does not require any extra operating system resources, such as multi-threading.
== Logging Disambiguation
......@@ -1129,7 +1129,7 @@ All component types are compatible with each empty component type. Empty compone
== Implicit Message Encoding
The TTCN–3 standard <<13-references.adoc#_1, [1]>> does not specify a standard way of data encoding/decoding. TITAN has a common C\++ API for encoding/decoding; to use this API external functions are usually needed. The common solution is to define a TTCN–3 external function and write the C++ code containing the API calls. In most cases the C++ code explicitly written to an auxiliary C++ file contains only simple code patterns which call the encoding/decoding API functions on the specified data. In TITAN there is a TTCN–3 language extension which automatically generates such external functions.
The TTCN–3 standard <<13-references.adoc#_1, [1]>> does not specify a standard way of data encoding/decoding. TITAN has a common C\++ API for encoding/decoding; to use this API external functions are usually needed. The common solution is to define a TTCN–3 external function and write the {cpp} code containing the API calls. In most cases the {cpp} code explicitly written to an auxiliary {cpp} file contains only simple code patterns which call the encoding/decoding API functions on the specified data. In TITAN there is a TTCN–3 language extension which automatically generates such external functions.
Based on this automatic encoding/decoding mechanism, dual-faced ports are introduced. Dual-faced ports have an external and an internal interface and can automatically transform messages passed through them based on mapping rules defined in TTCN–3 source files. These dual-faced ports eliminate the need for simple port mapping components and thus simplify the test configuration.
......@@ -1175,7 +1175,7 @@ The following transformation rules may apply to the automatic conversion between
* No conversion. Applicable to any message type, this is a type preserving mapping, no value conversion is performed. Source and target types must be identical. This mapping does not have any options. For example, control or status indication massages may transparently be conveyed between the external and the internal interfaces. Keyword used in attribute `user` of port type definition: `simple`.
* Message discarding. This rule means that messages of the given source type will not be forwarded to the opposite interface. Thus, there is no destination type, which must be indicated by the not used symbol (-). This mapping does not have any options. For example, incoming status indication massages of the external interface may be omitted on the internal interface. Keyword used in attribute `user` of port type definition: `discard`.
* Conversion using the built-in codecs. Here, a corresponding encoding or decoding subroutine of the built-in codecs (for example RAW, TEXT or BER) is invoked. The conversion and error handling options are specified with the same syntax as used for the encoding/decoding functions, see section <<attribute-syntax, Attribute Syntax>>. Here, source type corresponds to input type and target type corresponds to output type of the encoding. Keyword used in attribute `user` of port type definition: `encode` or `decode`; either followed by an optional `errorbehavior`.
* Function or external function. The transformation rule may be described by an (external) function referenced by the mapping. The function must have the attribute `extension` specifying one of the prototypes given in section <<encoder-decoder-function-prototypes, Encoder/decoder Function Prototypes>>. The incoming and the outgoing type of the function must be equal to the source and target type of the mapping, respectively. The function may be written in TTCN-3, C++ or generated automatically by the compiler. This mapping does not have any options. Keyword used in attribute `user` of port type definition: `function`.
* Function or external function. The transformation rule may be described by an (external) function referenced by the mapping. The function must have the attribute `extension` specifying one of the prototypes given in section <<encoder-decoder-function-prototypes, Encoder/decoder Function Prototypes>>. The incoming and the outgoing type of the function must be equal to the source and target type of the mapping, respectively. The function may be written in TTCN-3, {cpp} or generated automatically by the compiler. This mapping does not have any options. Keyword used in attribute `user` of port type definition: `function`.
==== Mapping with One Target
......@@ -1284,7 +1284,7 @@ The first portion of the input data received in the parameter `param_1` of type
[[automatic-generation-of-encoder-decoder-functions]]
=== Automatic Generation of Encoder/decoder Functions
Encoding and decoding is performed by C++ external functions using the built-in codecs. These functions can be generated automatically by the complier. The present section deals with attributes governing the function generation.
Encoding and decoding is performed by {cpp} external functions using the built-in codecs. These functions can be generated automatically by the complier. The present section deals with attributes governing the function generation.
==== Input and Output Types
......@@ -1302,7 +1302,7 @@ The syntax of the `encode` and `decode` attributes is the following:
BER encoding can be applied only for ASN.1 types.
The <`codec_options`> part specifies extra options for the particular codec. Currently it is applicable only in case of BER and XML encoding/decoding. The `codec_options` are copied transparently to the parameter list of the C++ encoder/decoder function call in the generated function body without checking the existence or correctness of the referenced symbols.
The <`codec_options`> part specifies extra options for the particular codec. Currently it is applicable only in case of BER and XML encoding/decoding. The `codec_options` are copied transparently to the parameter list of the {cpp} encoder/decoder function call in the generated function body without checking the existence or correctness of the referenced symbols.
Example of prototype `convert`, BER encoding and decoding (the PDU is an ASN.1 type):
[source]
......@@ -1335,7 +1335,7 @@ The TITAN codec API has some well defined function calls that control the behavi
Possible error types and error handlings are defined in <<13-references.adoc#\_16, [16]>>, section "The common API". The value of `<error_type>` shall be a value of type `error_type_t` without the prefix `ET_`. The value of `<error_handling>` shall be a value of type `error_behavior_t` without the prefix `EB_`.
The TTCN–3 attribute `errorbehavior(INCOMPL_ANY:ERROR)`, for example, will be mapped to the following C++ statement:
The TTCN–3 attribute `errorbehavior(INCOMPL_ANY:ERROR)`, for example, will be mapped to the following {cpp} statement:
[source]
----
TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_INCOMPL_ANY,
......@@ -1453,7 +1453,7 @@ Restrictions:
* the stream type of custom encoding and decoding functions is `bitstring`
NOTE: Although theoretically variant attributes can be added for custom encoding types, their coding functions would not receive any information about them, so they would essentially be regarded as comments. If custom variant attributes are used, the variant attribute parser’s error level must be lowered to warnings with the compiler option `-E`. +
The compiler searches all modules when attempting to find the coder functions needed for a type (including those that are not imported to the module where the `encvalue`, `decvalue`, `decmatch` or `@decoded` is located; if this is the case, then an extra include statement is added in the generated C++ code to the header generated for the coder function’s module).
The compiler searches all modules when attempting to find the coder functions needed for a type (including those that are not imported to the module where the `encvalue`, `decvalue`, `decmatch` or `@decoded` is located; if this is the case, then an extra include statement is added in the generated {cpp} code to the header generated for the coder function’s module).
Example:
[source]
......@@ -1490,7 +1490,7 @@ This can be achieved the same way as the custom encoder and decoder functions de
This can only be done for ASN.1 types, and has the same restrictions as the custom encoder and decoder functions. There is one extra restriction when using legacy codec handling (see section <<setting-the-default-codec-for-asn-1-types, Setting the default codec for ASN.1 types>>): an ASN.1 type cannot have both a PER encoder/decoder function and an encoder/decoder function of a built-in type set (this is checked separately for encoding and decoding).
NOTE: The compiler searches all modules when attempting to find the coder functions needed for a type (including those that are not imported to the module where the `encvalue`, `decvalue`, `decmatch` or `@decoded` is located; if this is the case, then an extra include statement is added in the generated C++ code to the header generated for the coder function’s module).
NOTE: The compiler searches all modules when attempting to find the coder functions needed for a type (including those that are not imported to the module where the `encvalue`, `decvalue`, `decmatch` or `@decoded` is located; if this is the case, then an extra include statement is added in the generated {cpp} code to the header generated for the coder function’s module).
Example:
[source]
......@@ -1537,7 +1537,7 @@ Example: the attribute +
=== API describing External Interfaces
Since the default class hierarchy of test ports does not allow sharing of C++ code with other port types, an alternate internal API is introduced for port types describing external interfaces. This alternate internal API is selected by giving the appropriate TTCN–3 extension attribute to the port. The following extension attributes or attribute combinations can be used:
Since the default class hierarchy of test ports does not allow sharing of {cpp} code with other port types, an alternate internal API is introduced for port types describing external interfaces. This alternate internal API is selected by giving the appropriate TTCN–3 extension attribute to the port. The following extension attributes or attribute combinations can be used:
.Port extension attributes
[cols=",,,,,",options="header",]
......@@ -1619,7 +1619,7 @@ type record ControlRequest { }
type record ControlResponse { }
type record PDUType1 { }
type record PDUType2 { }
// the encoder/decoder functions are written in C++
// the encoder/decoder functions are written in {cpp}
external function enc_PDUType1(in PDUType1 par) return octetstring
with { extension "prototype(convert)" }
external function dec_PDUType1(in octetstring stream,
......@@ -7224,13 +7224,13 @@ In general, a module should require the full version of another module or TITAN
=== Consistency Check in the Generated Code
A number of checks are performed during the build to ensure consistency of the TITAN compiler, TITAN runtime, C++ compiler used during the build. The compiler generates checking code that verifies:
A number of checks are performed during the build to ensure consistency of the TITAN compiler, TITAN runtime, {cpp} compiler used during the build. The compiler generates checking code that verifies:
* The version of the TITAN compiler matches the version of the TITAN runtime
* The platform on which the build is being performed matches the platform of the TITAN compiler
* The compiler used to build the TITAN compiler matches the compiler used to build the TITAN runtime
* Some of this information (in form of C\++ preprocessor macros definitions and instructions) is available to test port writers to express dependency on a particular TITAN version. When a C++ file includes a header generated by the TITAN compiler, that header includes the definitions for the TITAN runtime, including version information. These macro dependencies can be used in user-written C++ code.
* TTCN3_VERSION is a C/C\++ macro defined by the TITAN runtime headers. It contains an aggregated value of the TITAN major version, minor version and patch level. So, to express that a certain C++ file must be compiled together with TITAN R8C, the following code can be used:
* Some of this information (in form of C\++ preprocessor macros definitions and instructions) is available to test port writers to express dependency on a particular TITAN version. When a {cpp} file includes a header generated by the TITAN compiler, that header includes the definitions for the TITAN runtime, including version information. These macro dependencies can be used in user-written {cpp} code.
* TTCN3_VERSION is a C/C\++ macro defined by the TITAN runtime headers. It contains an aggregated value of the TITAN major version, minor version and patch level. So, to express that a certain {cpp} file must be compiled together with TITAN R8C, the following code can be used:
+
[source]
----
......@@ -7239,7 +7239,7 @@ A number of checks are performed during the build to ensure consistency of the T
#endif
----
* There is a preprocessor macro defined in the makefile which identifies the platform (operating system). It can be one of SOLARIS (for Solaris 6), SOLARIS8 (for Solaris 8 and above), LINUX, WIN32. Platform-dependent code can be isolated using conditional compilation based on these macro definitions.
* If the TITAN runtime was compiled with the GNU Compiler Collection (GCC), the macro GCC_VERSION is defined by the TITAN runtime headers. Its value is 10000 * (GCC major version) + 100 * (GCC minor version). For example, for GCC 3.4.6, GCC_VERSION will be defined to the value 30400; for GCC 4.1.2 it will be 40100. The value of this macro is compared during C++ compilation to the version of the compiler that was used to build TITAN itself to ensure consistency of the build. The GCC patch level is ignored for this comparison; code generated by a compiler with the same major and minor version is considered compatible. User-written code can use this value if it requires a certain version of the compiler. Alternatively, the predefined macros of the GNU compiler (*GNUC* and *GNUC_MINOR*) can be used for this purpose.
* If the TITAN runtime was compiled with the GNU Compiler Collection (GCC), the macro GCC_VERSION is defined by the TITAN runtime headers. Its value is 10000 * (GCC major version) + 100 * (GCC minor version). For example, for GCC 3.4.6, GCC_VERSION will be defined to the value 30400; for GCC 4.1.2 it will be 40100. The value of this macro is compared during {cpp} compilation to the version of the compiler that was used to build TITAN itself to ensure consistency of the build. The GCC patch level is ignored for this comparison; code generated by a compiler with the same major and minor version is considered compatible. User-written code can use this value if it requires a certain version of the compiler. Alternatively, the predefined macros of the GNU compiler (*GNUC* and *GNUC_MINOR*) can be used for this purpose.
* If the TITAN runtime was built with the SunPro compiler, the compiler itself defines the __SUNPRO_CC macro. Please consult the compiler documentation for the possible values.
== Negative Testing
......@@ -8089,7 +8089,7 @@ testcase TC(in integer i) runs on MyComp {
}
// external function can be used to re-throw the error in the catch block with a
// modified or original (as in the example above) error message, the C++
// modified or original (as in the example above) error message, the {cpp}
// implementation:
void throw_(const CHARSTRING& msg) {
TTCN_error("%s", (const char*)msg);
......
......@@ -3,7 +3,7 @@
:toc:
:table-number: 11
You can translate your TTCN–3 and ASN.1 modules to C++ source code using the program compiler.
You can translate your TTCN–3 and ASN.1 modules to {cpp} source code using the program compiler.
[[command-line-syntax]]
== Command Line Syntax
......@@ -102,7 +102,7 @@ Instructs the variant attribute parser to display warnings instead of errors for
* `-f`
+
Forces the compiler to overwrite (update) the output files even if they exist or the contents of them will be identical. Without this flag the output C++ header and source files will be overwritten only if their contents change compared to the previous version.
Forces the compiler to overwrite (update) the output files even if they exist or the contents of them will be identical. Without this flag the output {cpp} header and source files will be overwritten only if their contents change compared to the previous version.
* `-g`
+
......@@ -144,7 +144,7 @@ Because of the `-T` flag the `Third.ttcn` will be treated as a TTCN-3 file, and
* `-l`
+
Instructs the compiler to generate source file and line information (that is, #line directives) into the output code so that the error messages of the C\++ compiler refer back to the lines of the original TTCN–3 input module. This makes finding the reason of C++ error messages easier. This option has effect only in the equivalent C++ code of TTCN–3 functions, test cases and control parts and this feature is not provided in other TTCN–3 definitions such as types, constants or templates.WARNING! This is an experimental feature and the C++ compiler may report misleading error messages that refer to totally wrong (e.g. non-existent) TTCN–3 line numbers. In these cases please turn off this flag, repeat the compilation and analyze the generated code manually. Without this flag, the compiler also inserts the source code information for the better understanding of C++ error messages, but only as C++ comments. This option has no impact on the run-time performance of the generated code. The compiler performs full semantic analysis on its entire input; it normally does not generate erroneous C++ code. So this option became obsolete and will be removed in future versions.
Instructs the compiler to generate source file and line information (that is, #line directives) into the output code so that the error messages of the C\++ compiler refer back to the lines of the original TTCN–3 input module. This makes finding the reason of {cpp} error messages easier. This option has effect only in the equivalent {cpp} code of TTCN–3 functions, test cases and control parts and this feature is not provided in other TTCN–3 definitions such as types, constants or templates.WARNING! This is an experimental feature and the {cpp} compiler may report misleading error messages that refer to totally wrong (e.g. non-existent) TTCN–3 line numbers. In these cases please turn off this flag, repeat the compilation and analyze the generated code manually. Without this flag, the compiler also inserts the source code information for the better understanding of {cpp} error messages, but only as {cpp} comments. This option has no impact on the run-time performance of the generated code. The compiler performs full semantic analysis on its entire input; it normally does not generate erroneous {cpp} code. So this option became obsolete and will be removed in future versions.
* `-L`
+
......@@ -196,11 +196,11 @@ Disables the generation of RAW encoder/decoder routines for all TTCN–3 types.
* `-R`
+
Instructs the compiler to generate code for use with the function test runtime. The size of the generated code is significantly reduced, much of the functionality was migrated to the runtime. The generated C++ code has to be compiled using the TITAN_RUNTIME_2 symbol and has to be linked with the function test version of the runtime library. For example instead of the library file libttcn3.a the alternative libttcn3-rt2.a file must be used. The included c++ header files are the same.
Instructs the compiler to generate code for use with the function test runtime. The size of the generated code is significantly reduced, much of the functionality was migrated to the runtime. The generated {cpp} code has to be compiled using the TITAN_RUNTIME_2 symbol and has to be linked with the function test version of the runtime library. For example instead of the library file libttcn3.a the alternative libttcn3-rt2.a file must be used. The included c++ header files are the same.
* `-s`
+
Instructs the compiler to parse the given TTCN–3 and ASN.1 modules and perform semantic analysis on them, but not to generate C++ output. The list of given modules shall be complete so it is not allowed to import from a module that is not in the list. All options that influence the code generation are silently ignored when used together with `-s`.
Instructs the compiler to parse the given TTCN–3 and ASN.1 modules and perform semantic analysis on them, but not to generate {cpp} output. The list of given modules shall be complete so it is not allowed to import from a module that is not in the list. All options that influence the code generation are silently ignored when used together with `-s`.
+
NOTE: The TTCN–3 semantic analyzer of the compiler is still under development, thus, it is not capable of detecting every kind of semantic error.
......@@ -286,7 +286,7 @@ The single dash character as command line argument has a special meaning: it con
* `–ttcn2json`
+
Changes the purpose of the compiler to generate a JSON schema from the types defined in the specified TTCN-3 and ASN.1 modules. The parsing and semantic check of the input modules is still executed, but a JSON schema is generated instead of the C++ files. This must always be the first compiler option, and the previously listed options don’t apply (apart from options `–A` and `–T`), instead the following options are available:
Changes the purpose of the compiler to generate a JSON schema from the types defined in the specified TTCN-3 and ASN.1 modules. The parsing and semantic check of the input modules is still executed, but a JSON schema is generated instead of the {cpp} files. This must always be the first compiler option, and the previously listed options don’t apply (apart from options `–A` and `–T`), instead the following options are available:
* `-j`
+
......@@ -329,7 +329,7 @@ The switches denoted by square brackets are optional. More than one option may b
* `-a`
+
The flag refers to files using absolute path names in the generated Makefile. Makefile uses by default relative path names to access files located outside the current working directory of the compiler. Files from the current working directory are always referenced using only the file name without any directory. The flag generates a Makefile that is capable of using pre-compiled C++ and object files from central directories in order to save disk space and compilation time. WARNING! This feature works only if the generated files of the central directory is kept up-to-date and all directories use exactly the same environment (platform, TTCN–3 Executor and C++ compiler version, etc.).
The flag refers to files using absolute path names in the generated Makefile. Makefile uses by default relative path names to access files located outside the current working directory of the compiler. Files from the current working directory are always referenced using only the file name without any directory. The flag generates a Makefile that is capable of using pre-compiled {cpp} and object files from central directories in order to save disk space and compilation time. WARNING! This feature works only if the generated files of the central directory is kept up-to-date and all directories use exactly the same environment (platform, TTCN–3 Executor and {cpp} compiler version, etc.).
* `-c`
+
......@@ -401,7 +401,7 @@ Writes the Makefile to the given directory or file. If the given argument is an
* `-O <file>`
+
Add file to the list of other files in the generated `Makefile` without analyzing the file contents and suffix. This option can be used to temporarily exclude some TTCN-3, ASN.1 modules ASN.1 or C++ files from the build process, but add them to the archive created by the command make archive.
Add file to the list of other files in the generated `Makefile` without analyzing the file contents and suffix. This option can be used to temporarily exclude some TTCN-3, ASN.1 modules ASN.1 or {cpp} files from the build process, but add them to the archive created by the command make archive.
* `-p`
+
......@@ -439,7 +439,7 @@ Enforces legacy behaviour of the "out" function parameters (the "out" parameter
+
Enables code coverage and profiling in the TTCN-3 files listed in the `file` argument. The TTCN-3 files in the list must be separated by new lines and must also appear among the makefile generator’s arguments (this switch is ignored if the –t option is present).
+
If any of the source (TTCN-3, ASN.1, user-written C++) files does not exist or cannot be accessed, `ttcn3_makefilegen` exits with an error.
If any of the source (TTCN-3, ASN.1, user-written {cpp}) files does not exist or cannot be accessed, `ttcn3_makefilegen` exits with an error.
+
Other options are discussed in the next chapters.
......@@ -762,7 +762,7 @@ The `makefilegen` tool allows the usage of code splitting mechanisms when genera
Let "number" be equal to 4 for this example. We want to split the files into four pieces.
Firstly, TITAN finds the TTCN3 module whose C\++ generated code will be the largest. In this example, it will be 10000 characters (let’s call it MAX). So the largest generated C++ module contains 10000 characters.
Firstly, TITAN finds the TTCN3 module whose C\++ generated code will be the largest. In this example, it will be 10000 characters (let’s call it MAX). So the largest generated {cpp} module contains 10000 characters.
Secondly TITAN calculates the splitting threshold by dividing MAX with "number", so it will be 10000 / 4 = 2500 in this case. TITAN will only split the generated c++ files which are larger than 2500 characters.
......@@ -816,11 +816,11 @@ NOTE: Error recovery is not always successful and it might result in additional