diff --git a/usrguide/apiguide/1-introduction.adoc b/usrguide/apiguide/1-introduction.adoc index 3838e6a8b9c943093057a89ec2ad81aa5c599cd1..4615d9d209d7a940f7010d79a0d87ff96c32e6ce 100644 --- a/usrguide/apiguide/1-introduction.adoc +++ b/usrguide/apiguide/1-introduction.adoc @@ -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 {cpp} and want to use the available resources of TITAN. +This document describes the TITAN API on {cpp} 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: diff --git a/usrguide/apiguide/2-test_ports.adoc b/usrguide/apiguide/2-test_ports.adoc index 76cbd09754008945243d681d5446d3491828f269..cf2947b288659d68b1cfddbbe0b6563c207b7f98 100644 --- a/usrguide/apiguide/2-test_ports.adoc +++ b/usrguide/apiguide/2-test_ports.adoc @@ -12,7 +12,7 @@ The functions of Test Ports must be written by the user who knows the interface 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 {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. +The other part is a {cpp} 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. diff --git a/usrguide/apiguide/3-logger_plug-ins.adoc b/usrguide/apiguide/3-logger_plug-ins.adoc index 1f7aaf476a65fd404098953d9397679f98e70618..744390bc74489a4d03bd76bc5edcc4e7f6211fcf 100644 --- a/usrguide/apiguide/3-logger_plug-ins.adoc +++ b/usrguide/apiguide/3-logger_plug-ins.adoc @@ -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 {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: +Unfortunately, the `dlopen()` API is a C API, not a {cpp} 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 {cpp} 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 {cpp} 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 diff --git a/usrguide/apiguide/5-mapping_ttcn3_data_types_to_c++_constructs.adoc b/usrguide/apiguide/5-mapping_ttcn3_data_types_to_c++_constructs.adoc index 597086695437dff095ab1f5c91b0c5c48ed44449..e5c3f5073859224abff60dc037d0038ac7b89adb 100644 --- a/usrguide/apiguide/5-mapping_ttcn3_data_types_to_c++_constructs.adoc +++ b/usrguide/apiguide/5-mapping_ttcn3_data_types_to_c++_constructs.adoc @@ -3,20 +3,20 @@ :table-number: 7 :toc: -The TTCN–3 language elements of the test suite are individually mapped into more or less equivalent C\++ constructs. The data types are mapped to {cpp} classes, the test cases become {cpp} functions, and so on. In order to write a Test Port, it is inevitable to be familiar with the internal representation format of TTCN–3 data types and values. This section gives an overview about the data types and their equivalent {cpp} constructs. +The TTCN–3 language elements of the test suite are individually mapped into more or less equivalent {cpp} constructs. The data types are mapped to {cpp} classes, the test cases become {cpp} functions, and so on. In order to write a Test Port, it is inevitable to be familiar with the internal representation format of TTCN–3 data types and values. This section gives an overview about the data types and their equivalent {cpp} constructs. [[mapping-of-names-and-identifiers]] == Mapping of Names and Identifiers -In order to identify the TTCN–3 language elements in the generated C\++ program properly, the names of test suite are translated to {cpp} identifiers according to the following simple rules. +In order to identify the TTCN–3 language elements in the generated {cpp} program properly, the names of test suite are translated to {cpp} identifiers according to the following simple rules. -If the TTCN–3 identifier does not contain any underscore (_) character, its equivalent C\++ identifier will be the same. For example, the TTCN–3 variable `MyVar` will be translated to a {cpp} variable called `MyVar`. +If the TTCN–3 identifier does not contain any underscore (_) character, its equivalent {cpp} identifier will be the same. For example, the TTCN–3 variable `MyVar` will be translated to a {cpp} variable called `MyVar`. -If the TTCN–3 identifier contains one or more underscore characters, each underscore character will be duplicated in the C\++ identifier. So the TTCN–3 identifier `My_Long_Name` will be mapped to a {cpp} identifier called `My\__Long__Name`. +If the TTCN–3 identifier contains one or more underscore characters, each underscore character will be duplicated in the {cpp} identifier. So the TTCN–3 identifier `My_Long_Name` will be mapped to a {cpp} identifier called `My\__Long__Name`. -The idea behind this name mapping is that we may freely use the C\++ identifiers containing one underscore character in the generated code and in the Test Ports as well. Otherwise name clashes can always happen because the name space of TTCN–3 and {cpp} is identical. Furthermore, the generated C\++ language elements fulfill the condition that the scope of a translated {cpp} identifier is identical as the scope of the original TTCN–3 identifier. +The idea behind this name mapping is that we may freely use the {cpp} identifiers containing one underscore character in the generated code and in the Test Ports as well. Otherwise name clashes can always happen because the name space of TTCN–3 and {cpp} is identical. Furthermore, the generated {cpp} language elements fulfill the condition that the scope of a translated {cpp} identifier is identical as the scope of the original TTCN–3 identifier. -The identifiers that are keywords of C or C\++ but not keywords in TTCN–3 are mapped to themselves, but a single underscore character is appended at the end (for example `typedef` becomes `typedef_`). The same rule applies to the all-uppercase identifiers that are used in the Base Library: identifier `INTEGER` in TTCN–3 becomes `INTEGER_` in {cpp}, `TRUE` footnote:[The built-in `verdict` and `boolean` constants in TTCN–3 shall be written with all lowercase letters, such as true or pass. Although previous compiler versions have accepted `TRUE` or `PASS` as well, these words are treated by the compiler as regular identifiers as specified in the standard.] is mapped to `TRUE_`, etc. +The identifiers that are keywords of C or {cpp} but not keywords in TTCN–3 are mapped to themselves, but a single underscore character is appended at the end (for example `typedef` becomes `typedef_`). The same rule applies to the all-uppercase identifiers that are used in the Base Library: identifier `INTEGER` in TTCN–3 becomes `INTEGER_` in {cpp}, `TRUE` footnote:[The built-in `verdict` and `boolean` constants in TTCN–3 shall be written with all lowercase letters, such as true or pass. Although previous compiler versions have accepted `TRUE` or `PASS` as well, these words are treated by the compiler as regular identifiers as specified in the standard.] is mapped to `TRUE_`, etc. Here is the complete list (in alphabetical order) of the identifiers that are handled in such special way:asm, auto, bitand, bitor, bool, break, case, class, compl, continue, delete, double, enum, explicit, export, friend, inline, int, ischosen, long, main, mutable, namespace, new, operator, private, protected, public, register, short, signed, static, stderr, stdin, stdout, struct, switch, this, throw, try, typedef, typeid, typename, unsigned, using, virtual, void, volatile, ADDRESS, BITSTRING, BOOLEAN, CHAR, CHARSTRING, COMPONENT, DEFAULT, ERROR, FAIL, FALSE, FLOAT, HEXSTRING, INCONC, INTEGER, NONE, OBJID, OCTETSTRING, PASS, PORT, TIMER, TRUE, VERDICTTYPE. @@ -32,12 +32,12 @@ The compiler generates a {cpp} namespace for every TTCN–3 and ASN.1 module. Al The definitions of the TTCN–3 Base Library do not use any namespace. -When accessing a C\++ entity that belongs to a different module than the referring Test Port or external function is in the reference has to be prefixed with the namespace of the referenced module. For example, to access the {cpp} class that realizes type `MyType` defined in `MyModule1` from a Test Port that belongs to module `MyModule2` the reference shall be written as `MyModule1::MyType`. +When accessing a {cpp} entity that belongs to a different module than the referring Test Port or external function is in the reference has to be prefixed with the namespace of the referenced module. For example, to access the {cpp} class that realizes type `MyType` defined in `MyModule1` from a Test Port that belongs to module `MyModule2` the reference shall be written as `MyModule1::MyType`. [[predefined-ttcn-3-data-types]] == Predefined TTCN–3 Data Types -There are some basic data types in TTCN–3 that have no equivalent data types in language C/C\++ (for example bitstring, verdicttype). Other types have {cpp} equivalent, but the TTCN–3 executor must know whether a variable has a valid value or not because sending an unbound value must result in a dynamic test case error. Thus, in the TTCN–3 Base Library all basic data types of TTCN–3 were implemented as {cpp} classes. This section describes the member functions of these classes. +There are some basic data types in TTCN–3 that have no equivalent data types in language C/{cpp} (for example bitstring, verdicttype). Other types have {cpp} equivalent, but the TTCN–3 executor must know whether a variable has a valid value or not because sending an unbound value must result in a dynamic test case error. Thus, in the TTCN–3 Base Library all basic data types of TTCN–3 were implemented as {cpp} classes. This section describes the member functions of these classes. === `Integer` @@ -298,7 +298,7 @@ void TTCN_Runtime::setverdict(const VERDICTTYPE&); verdicttype TTCN_Runtime::getverdict(); ---- -These functions are the C\++ equivalents of TTCN–3 `setverdict` and `getverdict` operations. Use them only if your Test Port or {cpp} function encounters a low-level failure, but it can continue its normal operation (that is, error recovery is not necessary). +These functions are the {cpp} equivalents of TTCN–3 `setverdict` and `getverdict` operations. Use them only if your Test Port or {cpp} function encounters a low-level failure, but it can continue its normal operation (that is, error recovery is not necessary). Other operators (global functions): [source] @@ -1085,7 +1085,7 @@ boolean operator!=(component component_value, Empty `record` and `set` types are not real built-in types in TTCN–3, but the {cpp} realization of these types also differs from regular records or sets. The empty types are almost identical to each other, only their names are different. That is why we treat them as predefined types. -Each empty type is defined in a C\++ class, which is generated by the compiler. Using separate classes enables us to differentiate among them in {cpp} type polymorphism. For example, several empty types can be defined as incoming or outgoing types on the same TTCN–3 port type. +Each empty type is defined in a {cpp} class, which is generated by the compiler. Using separate classes enables us to differentiate among them in {cpp} type polymorphism. For example, several empty types can be defined as incoming or outgoing types on the same TTCN–3 port type. Let us consider the following TTCN–3 type definition as an example: [source, subs="+quotes"] @@ -1140,7 +1140,7 @@ The user-defined compound data types are implemented in {cpp} classes. These cla === Record and Set Type Constructs -The TTCN–3 type constructs `record` and `set` are mapped in an identical way to C\++. There will be a {cpp} class for each record type in the generated code. This class builds up the record from its fields.footnote:[This section deals with the record and set types that have at least one field. See <<empty-types, Empty Types>> for the {cpp} mapping of empty record and set types.] The fields can be either basic or compound types. +The TTCN–3 type constructs `record` and `set` are mapped in an identical way to {cpp}. There will be a {cpp} class for each record type in the generated code. This class builds up the record from its fields.footnote:[This section deals with the record and set types that have at least one field. See <<empty-types, Empty Types>> for the {cpp} mapping of empty record and set types.] The fields can be either basic or compound types. Let us consider the following example type definition. The types `t1` and `t2` can be arbitrary. [source] @@ -1296,7 +1296,7 @@ Using the value of an unbound `union` variable for anything will cause dynamic t ==== The anytype -The TTCN-3 anytype is implemented as a C\++ class named anytype. The class is generated only if an actual anytype access is present in the module. It has the same interface as any other {cpp} class generated for a union, with a few differences: +The TTCN-3 anytype is implemented as a {cpp} class named anytype. The class is generated only if an actual anytype access is present in the module. It has the same interface as any other {cpp} class generated for a union, with a few differences: If a field is a built-in type or the address type, the name used in `union_selection_type` is the name of the runtime class implementing the type (usually the name of the type in all uppercase). @@ -1399,7 +1399,7 @@ boolean operator!=(null_type null_value, const t2& other_value); // Not equal ==== Pre-generated `record of` and `set of` constructs -The C\++ classes for the `record of` and `set of` constructs of most predefined TTCN-3 types are pre-generated and part of the TITAN runtime. Only a type alias ({cpp} `typedef`) is generated for instances of these types declared in TTCN-3 and ASN.1 modules. There is a class with regular memory allocation and one with optimized memory allocation pre-generated for each type. These classes are located in the `PreGenRecordOf` namespace. +The {cpp} classes for the `record of` and `set of` constructs of most predefined TTCN-3 types are pre-generated and part of the TITAN runtime. Only a type alias ({cpp} `typedef`) is generated for instances of these types declared in TTCN-3 and ASN.1 modules. There is a class with regular memory allocation and one with optimized memory allocation pre-generated for each type. These classes are located in the `PreGenRecordOf` namespace. .Pre-generated classes for `record of`/`set of` predefined types @@ -1541,7 +1541,7 @@ Using the value of an unbound enumerated variable for anything will cause dynami === The `address` Type -The special TTCN–3 data type `address` is represented in C\++ as if it was a regular data type. The name of the equivalent {cpp} class is `ADDRESS`. If it is an alias to another (either built-in or user-defined) type then a {cpp} `typedef` is used. +The special TTCN–3 data type `address` is represented in {cpp} as if it was a regular data type. The name of the equivalent {cpp} class is `ADDRESS`. If it is an alias to another (either built-in or user-defined) type then a {cpp} `typedef` is used. == Predefined Functions @@ -1549,7 +1549,7 @@ Annex C of link:https://www.etsi.org/deliver/etsi_es/201800_201899/20187301/04.0 The prototypes for these functions can be found in `*$TTCN3_DIR/include/Addfunc.hh*`, but for easier navigation we list them also in the present document. -The majority of these functions have more than one polymorphic version: when appropriate, one of them takes literal (built-in) C\++ types as arguments instead of the objects of equivalent {cpp} classes. For instance, if the incoming argument is stored in an `int` variable in your {cpp} code, you should not construct a temporary object of class `INTEGER` because passing an `int` is faster and produces smaller binary code. Similarly, the returned type is also literal when it is possible. +The majority of these functions have more than one polymorphic version: when appropriate, one of them takes literal (built-in) {cpp} types as arguments instead of the objects of equivalent {cpp} classes. For instance, if the incoming argument is stored in an `int` variable in your {cpp} code, you should not construct a temporary object of class `INTEGER` because passing an `int` is faster and produces smaller binary code. Similarly, the returned type is also literal when it is possible. === `Integer` to character @@ -1935,6 +1935,6 @@ The class representing the exceptions of a signature (remote procedure) is simil |`void log() const` |Puts the contents of the exception into the log. |=================================================================================================================================================================================================================================== -If an exception type is a user-defined type the field name will be constructed from the C\++ namespace name of the module that the exception type resides in and the name of the {cpp} class that realizes the exception type. The two identifiers are glued together using a single underscore character. Please note that the namespace name is always present in the identifiers, even if the exception type is defined in the same module as the signature. +If an exception type is a user-defined type the field name will be constructed from the {cpp} namespace name of the module that the exception type resides in and the name of the {cpp} class that realizes the exception type. The two identifiers are glued together using a single underscore character. Please note that the namespace name is always present in the identifiers, even if the exception type is defined in the same module as the signature. For example, if exception type `My_Record` is defined in module `My_Module` the respective field access functions will be named as `My\__Module_My__Record_field` and the associated enum value will be `MyProc_exception::ALT_My__Module_My__Record`. diff --git a/usrguide/apiguide/6-tips_&_troubleshooting.adoc b/usrguide/apiguide/6-tips_&_troubleshooting.adoc index 47c4106ab608474957b618f81b8ca1d3a6d1eda4..a3df21b5957d881035fc7679aa6773c8a62ecbdb 100644 --- a/usrguide/apiguide/6-tips_&_troubleshooting.adoc +++ b/usrguide/apiguide/6-tips_&_troubleshooting.adoc @@ -7,7 +7,7 @@ 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 {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 {cpp} 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 {cpp} 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 {cpp} code: @@ -17,7 +17,7 @@ Rules to follow when writing {cpp} code: * 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 {cpp} entities used only locally; these are defined with the keyword `static`. +* All {cpp} 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 {cpp} source files. It is forbidden to use this directive in header files! @@ -59,7 +59,7 @@ The compiler will translate those external function definitions to {cpp} functio [...] ---- -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)>>. +Both pre-defined and user-defined TTCN–3 data types can be used as parameters and/or return types of the {cpp} 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. @@ -80,7 +80,7 @@ NOTE: In versions 1.6.pl3 and earlier the in keyword had an extra meaning in for 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 {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 external functions can be implemented in one or more {cpp} 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 {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]] @@ -273,7 +273,7 @@ In the executable test program there are system calls not only in the Base Libra == 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 {cpp} 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 {cpp} 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 {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. @@ -290,4 +290,4 @@ extern "C" { #endif ---- -The latter solution does not work with all C\++ compilers; it was tested on GNU {cpp} compiler only. +The latter solution does not work with all {cpp} compilers; it was tested on GNU {cpp} compiler only. diff --git a/usrguide/referenceguide/12-tips_&_troubleshooting.adoc b/usrguide/referenceguide/12-tips_&_troubleshooting.adoc index d17eada4f9b5d55d390862d6864b3e918ebc5fa0..96b843616a86ae68281aebd9177b2cb90bd993bb 100644 --- a/usrguide/referenceguide/12-tips_&_troubleshooting.adoc +++ b/usrguide/referenceguide/12-tips_&_troubleshooting.adoc @@ -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 {cpp} code cannot be compiled because the Test Port class contains two identical send/receive function. +The limitation of the C typedef is that the {cpp} 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. diff --git a/usrguide/referenceguide/4-ttcn3_language_extensions.adoc b/usrguide/referenceguide/4-ttcn3_language_extensions.adoc index cb70b5b02a5ac72c8376b73c65c0bdf2e56b06c0..0d835d7def581d959d1454970cb975a78f0370a5 100644 --- a/usrguide/referenceguide/4-ttcn3_language_extensions.adoc +++ b/usrguide/referenceguide/4-ttcn3_language_extensions.adoc @@ -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 {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. +The TTCN–3 standard <<13-references.adoc#_1, [1]>> does not specify a standard way of data encoding/decoding. TITAN has a common {cpp} 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. @@ -7229,8 +7229,8 @@ A number of checks are performed during the build to ensure consistency of the T * 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 {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: +* Some of this information (in form of {cpp} 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/{cpp} 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] ---- diff --git a/usrguide/referenceguide/6-compiling_ttcn3_and_asn1_modules.adoc b/usrguide/referenceguide/6-compiling_ttcn3_and_asn1_modules.adoc index d6e78315d306b6ff964283644a8d9041734be3aa..76961fd5437313e1af86ab97168347f0b241a913 100644 --- a/usrguide/referenceguide/6-compiling_ttcn3_and_asn1_modules.adoc +++ b/usrguide/referenceguide/6-compiling_ttcn3_and_asn1_modules.adoc @@ -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 {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. +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 {cpp} 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` + @@ -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 {cpp} module contains 10000 characters. +Firstly, TITAN finds the TTCN3 module whose {cpp} 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. diff --git a/usrguide/releasenotes/releasenotes.adoc b/usrguide/releasenotes/releasenotes.adoc index c2c41ad0bd3b67df08fe448269a03faf94d982ea..9ceb4834cf900f47e5ac1d0c801f48caa21c9ff9 100644 --- a/usrguide/releasenotes/releasenotes.adoc +++ b/usrguide/releasenotes/releasenotes.adoc @@ -423,7 +423,7 @@ Version 1.8 has the following new features: Version 1.7 has the following new features: -* The naming convention of the generated C\++ code has been revised to avoid potential name clashes between definitions. The definitions of each TTCN–3 and ASN.1 module is put into a separate {cpp} namespace that corresponds to the module name. This eliminates all problems caused by definitions with identical names in different modules. The scope of {cpp} enum values that represent the values of TTCN–3 and ASN.1 enumerated types became narrower to avoid conflicts if the same element name appears in two different enumerated types. +* The naming convention of the generated {cpp} code has been revised to avoid potential name clashes between definitions. The definitions of each TTCN–3 and ASN.1 module is put into a separate {cpp} namespace that corresponds to the module name. This eliminates all problems caused by definitions with identical names in different modules. The scope of {cpp} enum values that represent the values of TTCN–3 and ASN.1 enumerated types became narrower to avoid conflicts if the same element name appears in two different enumerated types. * Extension (inheritance) of TTCN–3 component types and compatibility between different component types is now supported by the compiler. @@ -502,7 +502,7 @@ Version 1.4 has the following new features: * The compiler supports the full semantic analysis of ASN.1 modules and semantic analysis of TTCN–3 type definitions. The output for other TTCN–3 definitions is still generated on the fly without checks. -* The compiler performs automatic reordering in the generated code for TTCN–3 types as well. This means, the generated C\++ code will be always valid even if the type definitions use forward referencing. + +* The compiler performs automatic reordering in the generated code for TTCN–3 types as well. This means, the generated {cpp} code will be always valid even if the type definitions use forward referencing. + NOTE: The forward referencing problem between TTCN–3 constants and templates is still unsolved. They must be declared in bottom-up order to get a working {cpp} code. @@ -544,7 +544,7 @@ Version 1.2 has the following new features: * The compiler supports the new, Edition 2 syntax of the TTCN–3 Core Language. The obsolete language elements that were supported in version 1.1 (e.g. named alternatives) are still accepted for backward compatibility, but a warning message is printed. -* The toolset contains a new ASN.1 compiler, which allows the importing of ASN.1 modules into TTCN–3 test suites. Like the TTCN–3 compiler, the ASN.1 compiler translates ASN.1 definitions to C\++ code, which shall be used together with {cpp} output of TTCN–3 modules. +* The toolset contains a new ASN.1 compiler, which allows the importing of ASN.1 modules into TTCN–3 test suites. Like the TTCN–3 compiler, the ASN.1 compiler translates ASN.1 definitions to {cpp} code, which shall be used together with {cpp} output of TTCN–3 modules. * The ASN.1 compiler performs a semantic analysis on its input and reports errors instead of generating invalid {cpp} code. @@ -1429,23 +1429,23 @@ New features added to the Eclipse plugins: *Fixed bugs* -* The generated C\++ equivalent of enumerated types could not be compiled with GCC 2.95.x if the new naming rules were in effect. The problem was caused by the {cpp} enum type that was declared within the scope of the {cpp} class representing the values of the enumerated type. The old version of GCC accepts the casting operator only if the name of the embedded enum type is prefixed with the name of the {cpp} class. +* The generated {cpp} equivalent of enumerated types could not be compiled with GCC 2.95.x if the new naming rules were in effect. The problem was caused by the {cpp} enum type that was declared within the scope of the {cpp} class representing the values of the enumerated type. The old version of GCC accepts the casting operator only if the name of the embedded enum type is prefixed with the name of the {cpp} class. * When logging the matching procedure of optional fields in record and set types the field of the value and the template was printed in the wrong order if the field of the value was set to omit. Always the value must be printed first during matching, which corresponds to the order of arguments in built-in operation `match()`. -* The compiler generated wrong C\++ code for repeat statements found within the response and exception handling parts of call statements. If the call statement was embedded into an altstep the generated code assumed that the repeat statement refers to the whole altstep. Otherwise the generated {cpp} code was erroneous, it could not be compiled. +* The compiler generated wrong {cpp} code for repeat statements found within the response and exception handling parts of call statements. If the call statement was embedded into an altstep the generated code assumed that the repeat statement refers to the whole altstep. Otherwise the generated {cpp} code was erroneous, it could not be compiled. * The copy constructor of class TTCN Buffer did not work properly in the Base Library. This class is used by the common API for encoding and decoding. The defective copy constructor did not copy the length indicator field of the buffer to the newly created object thus some manually written codec functions and Test Ports reported mysterious internal error messages. * The semantic analyzer of the compiler reported false error messages while checking procedure-based operations `catch(timeout)`. Although this operation is applicable after calling any blocking signature the compiler accepted `catch(timeout)` only if the regular catch operation was allowed (i.e. the corresponding signature had at least one exception type). Of course, the operation `catch(timeout)` is allowed within the response and exception handling parts of call operations and only if the respective operation has a call timer. -* The compiler generated erroneous C\++ code for the construct _value returning done_ if the new naming rules were in effect. The invoked {cpp} function was not prefixed with the appropriate namespace if the done statement and the return type of the PTC behavior function (having attribute with _{extension "done" }_) were defined in different modules. +* The compiler generated erroneous {cpp} code for the construct _value returning done_ if the new naming rules were in effect. The invoked {cpp} function was not prefixed with the appropriate namespace if the done statement and the return type of the PTC behavior function (having attribute with _{extension "done" }_) were defined in different modules. * Erroneous circular TTCN–3 type references pointing back to themselves with field or array sub-references (like type T[0].f1 T;) caused infinite recursion in the semantic analyzer and consequently the compiler crashed with segmentation fault. * The utility `*ttcn3 logbrowser*` mis-interpreted some log entries. If the text of the log entry contained only a small integer number (like 1 or 2) the log browser presented the number as an erroneous component reference and left the field for the event text empty. -* The generated C\++ code related to TTCN–3 expressions comparing optional fields of record and set types was erroneous in some cases. If two optional fields were tested for inequality the generated code could not be compiled with GCC 4.0.x or later. GCC complained about ambiguous overloading of operators. Furthermore, if an optional field containing a value of type charstring was compared with an optional field containing universal charstring the {cpp} code caused infinite recursion at runtime. All these errors were related to the instantiation of template member functions of {cpp} template classes. +* The generated {cpp} code related to TTCN–3 expressions comparing optional fields of record and set types was erroneous in some cases. If two optional fields were tested for inequality the generated code could not be compiled with GCC 4.0.x or later. GCC complained about ambiguous overloading of operators. Furthermore, if an optional field containing a value of type charstring was compared with an optional field containing universal charstring the {cpp} code caused infinite recursion at runtime. All these errors were related to the instantiation of template member functions of {cpp} template classes. * The semantic analyzer of the compiler did not check properly the value list and value range (i.e. character range) type restrictions of type universal charstring. Even some basic checks, such as the verification of range boundaries and overlapping, were skipped in previous versions. @@ -1467,7 +1467,7 @@ New features added to the Eclipse plugins: * The decode type mapping rules of dual-faced port types did not consider the associated `errorbehavior` attribute. The reason was that the {cpp} equivalents of the errorbehavior settings were left out from the generated code by mistake. -* The default argument of the constructor (NULL pointer) was missing from the generated C\++ classes implementing TTCN–3 ports if the respective TTCN–3 port type had attribute provider or user. Because of this the compilation of the generated {cpp} code failed when a TTCN–3 port array was created from the above port types. The {cpp} template class that realizes port arrays tried to instantiate its elements using the default constructor (i.e. without parameters). +* The default argument of the constructor (NULL pointer) was missing from the generated {cpp} classes implementing TTCN–3 ports if the respective TTCN–3 port type had attribute provider or user. Because of this the compilation of the generated {cpp} code failed when a TTCN–3 port array was created from the above port types. The {cpp} template class that realizes port arrays tried to instantiate its elements using the default constructor (i.e. without parameters). * The command line version of the Main Controller (i.e. `mctr cli`) crashed with a segmentation fault after encountering the expansion of an invalid macro to a host name (e.g. $_{NonExistentMacro, hostname}_) in the configuration file. The crash occurred after reporting the appropriate error message. The reason was an uninitialized variable. @@ -1475,7 +1475,7 @@ New features added to the Eclipse plugins: * The error message of the compiler pointed to the wrong location in the source file if a (named) TTCN–3 constant was assigned to a variable and the actual value of the constant violated the subtype restrictions in the type of the variable. In this case the error message pointed to the literal value of the constant (which was apparently correct) rather than the faulty variable assignment. -* The Base Library lacked the C\++ functions and operators that can implicitly convert a template (or template variable) of type charstring to a template of type universal charstring by translating the embedded matching mechanisms character-by-character. TTCN–3 modules using such constructs were accepted by the compiler, but the generated {cpp} code could not be compiled due to ambiguous overloads of operators. To resolve the problem a new constructor and assignment operator have been added to class UNIVERSAL CHARSTRING template, both taking CHARSTRING template as argument. +* The Base Library lacked the {cpp} functions and operators that can implicitly convert a template (or template variable) of type charstring to a template of type universal charstring by translating the embedded matching mechanisms character-by-character. TTCN–3 modules using such constructs were accepted by the compiler, but the generated {cpp} code could not be compiled due to ambiguous overloads of operators. To resolve the problem a new constructor and assignment operator have been added to class UNIVERSAL CHARSTRING template, both taking CHARSTRING template as argument. * Although the ASN.1 front-end of the compiler ignores all type constraints except the table and component relation constraints of open types, some valid type constraints were rejected by the parser. False syntax errors were generated, for instance, if a single value constraint contained values within brackets (such as `SEQUENCE` or `SET` values) or a permitted alphabet constraint (denoted by keyword FROM) contained single characters using the quadruple notation. @@ -1498,11 +1498,11 @@ Released on March 9, 2007. *New features* -* The naming convention of the generated C\++ code has been revised to avoid name clashes between different definitions. The use of a {cpp} namespace for each module eliminates all compilation problems caused by definitions with the same identifier in different modules. The proper scoping of enumerated values excludes the name conflict between two enumerated types and makes the enum-hack option unnecessary and obsolete. +* The naming convention of the generated {cpp} code has been revised to avoid name clashes between different definitions. The use of a {cpp} namespace for each module eliminates all compilation problems caused by definitions with the same identifier in different modules. The proper scoping of enumerated values excludes the name conflict between two enumerated types and makes the enum-hack option unnecessary and obsolete. * Extensibility (inheritance) of TTCN–3 component types and type compatibility between different component types is now supported by the compiler. -* The compiler can generate TTCN–3 external functions automatically in C\++ to perform encoding and decoding of message types using the built-in codecs of the runtime environments. {cpp} programming is no longer necessary to create a complete and working protocol module. All options of the encoding shall be given in TTCN–3 as attributes of the external functions. +* The compiler can generate TTCN–3 external functions automatically in {cpp} to perform encoding and decoding of message types using the built-in codecs of the runtime environments. {cpp} programming is no longer necessary to create a complete and working protocol module. All options of the encoding shall be given in TTCN–3 as attributes of the external functions. * Dual-faced TTCN–3 ports are now supported. Such ports have two different interfaces: internal (used when sending and receiving messages) and external (used when connecting the port to another test component or mapping to a system port). The handling of incoming and outgoing messages shall be specified using type mapping rules in the attributes of port types. @@ -1609,7 +1609,7 @@ Released on November 27, 2006. * In some cases the GUI did not load the user-defined test sets that were stored in the project. -* The compiler generated wrong (uncompilable) C\++ code for the location information when the name of the input file contained special characters (like the backslash) that require escaping in {cpp} string literals. +* The compiler generated wrong (uncompilable) {cpp} code for the location information when the name of the input file contained special characters (like the backslash) that require escaping in {cpp} string literals. * The compiler aborted with an internal fatal error during semantic analysis if a RAW attribute POINTERTO referred to a non-existent field. The abort occurred after printing the relevant error message. @@ -1621,7 +1621,7 @@ Released on November 27, 2006. * The semantic analyzer of the compiler verified the arguments of built-in TTCN–3 conversion functions int2hex and int2oct incorrectly. In some cases when the arguments were constants and the given value did not fit in the given length the semantic analyzer did not report any error, but the compiler aborted with an internal fatal error during constant folding while doing the conversion. -* The compiler generated incorrect C\++ code for TTCN–3 for loops if the boolean guard expression was constant false. In this case the entire loop was substituted with an empty {cpp} statement although the initial variable assignment had to be executed exactly once in all cases. The wrong code could cause problems if the initial assignment had side effects (e.g. it called a function or modified a variable defined outside the for loop). +* The compiler generated incorrect {cpp} code for TTCN–3 for loops if the boolean guard expression was constant false. In this case the entire loop was substituted with an empty {cpp} statement although the initial variable assignment had to be executed exactly once in all cases. The wrong code could cause problems if the initial assignment had side effects (e.g. it called a function or modified a variable defined outside the for loop). * The compiler and the run-time environment supports the short-circuit evaluation of logical `and` and `or` operations as it is required by the TTCN–3 standard. If the result of the operation can be determined based on the first (left) operand (i.e. the first operand is false in case of and or true in case of or) the second (right) operand will not be evaluated at all. The writer of the TTCN–3 code can exploit this behavior if the right operand may have side-effects or cause a dynamic test case error. @@ -1722,9 +1722,9 @@ NOTE: The only possible value of these types is _{}_. NOTE: The array indices in type references are handled in a special way in the compiler: it is verified that the value in square brackets should be of type integer, but the number itself is not used for anything. -* The compiler generated wrong (uncompilable) C\++ code for ASN.1 open types in some cases. The {cpp} equivalents of some types and values were missing if an unnamed information object set was used in the open type’s table constraint. This was the case, for instance, if the open type was embedded into a parameterized type assignment and the object set was defined in-line in the actual parameter list of the type reference. +* The compiler generated wrong (uncompilable) {cpp} code for ASN.1 open types in some cases. The {cpp} equivalents of some types and values were missing if an unnamed information object set was used in the open type’s table constraint. This was the case, for instance, if the open type was embedded into a parameterized type assignment and the object set was defined in-line in the actual parameter list of the type reference. -* Incremental compilation of ASN.1 modules did not work properly if the instantiation of some parameterized type assignments changed since the last full re-compilation of all modules. Changing the order of files in the compiler’s command line could cause similar problems. Module-based incremental compilation uses the concept that the C\++ equivalent of a module shall only depend on the module itself and the imported modules. Importing modules that use some definitions from the module must not influence the generated code. The {cpp} equivalents of parameterized assignments are generated when the assignment is instantiated by a parameterized reference (because only these instances can be visible from TTCN–3 ). The instances are created in the module where the parameterized reference is because the actual parameters might be visible only from that module. Different instantiations of the same parameterized assignment are identified by instance counters. Earlier versions of the compiler used one instance counter for each parameterized assignment. This can cause problems when there is a parameterized assignment in module A and it is instantiated from B and C. If the number of instantiations in B changes this would change the instance counters of C. Thus the generated files of C became outdated although C does not import from B. Starting from this version the instance counters are associated with target modules. In the above example the parameterized assignment in A has two counters: one for B and another for C. This change required a new naming convention for the C\++ classes of instantiated types: the identifier of the target module became part of the name, which resulted in longer {cpp} identifiers. +* Incremental compilation of ASN.1 modules did not work properly if the instantiation of some parameterized type assignments changed since the last full re-compilation of all modules. Changing the order of files in the compiler’s command line could cause similar problems. Module-based incremental compilation uses the concept that the {cpp} equivalent of a module shall only depend on the module itself and the imported modules. Importing modules that use some definitions from the module must not influence the generated code. The {cpp} equivalents of parameterized assignments are generated when the assignment is instantiated by a parameterized reference (because only these instances can be visible from TTCN–3 ). The instances are created in the module where the parameterized reference is because the actual parameters might be visible only from that module. Different instantiations of the same parameterized assignment are identified by instance counters. Earlier versions of the compiler used one instance counter for each parameterized assignment. This can cause problems when there is a parameterized assignment in module A and it is instantiated from B and C. If the number of instantiations in B changes this would change the instance counters of C. Thus the generated files of C became outdated although C does not import from B. Starting from this version the instance counters are associated with target modules. In the above example the parameterized assignment in A has two counters: one for B and another for C. This change required a new naming convention for the {cpp} classes of instantiated types: the identifier of the target module became part of the name, which resulted in longer {cpp} identifiers. * The compiler assigned wrong identifiers to some ASN.1 open type members. Open types are mapped to implicit CHOICE types and the alternatives are the distinct types from the table constraint’s object set. The alternative identifiers of the CHOICE are derived from each type’s name by changing the first letter (which must always be a capital letter) to lower case. This mapping of names did not work properly if the elements of the object set were the instances of a parameterized information object assignment. For instance, different types got the same identifier (and therefore the generated {cpp} code was invalid) if the respective object field was a dummy reference pointing to the object’s formal parameter. When constructing open types the compiler generates a warning message if a member type has a complicated constructed name and thus the alternative will get a strange identifier. These warnings were missing too from the instances of parameterized types. @@ -1829,7 +1829,7 @@ Released on December 16, 2005. * The run-time location information of else if statements pointed to the wrong line of the TTCN–3 code. For example, if an error occurred in the boolean expression of an else if statement the dynamic test case error message of the log file contained the line number of the first if statement. This made difficult to find the reason of the error since the first boolean expression, which the error message referred to, was correct. -* The compiler generated faulty C\++ code if the last statement of a TTCN–3 statement block was a select-case statement. The {cpp} compiler complained about that the last label of the block was not followed by a statement. The syntaxerror was corrected by adding an empty {cpp} statement (i.e. a semi-colon) after the corresponding label. +* The compiler generated faulty {cpp} code if the last statement of a TTCN–3 statement block was a select-case statement. The {cpp} compiler complained about that the last label of the block was not followed by a statement. The syntaxerror was corrected by adding an empty {cpp} statement (i.e. a semi-colon) after the corresponding label. * The compiler crashed with a segmentation fault during code generation if the boolean expression of a TTCN–3 if, for or while statement contained an in-line compound expression that could not be mapped directly to a {cpp} expression. @@ -1865,7 +1865,7 @@ Released on December 16, 2005. * Utility `*ttcn3 logmerge*` could cause segmentation fault if one of its arguments was a path name containing . or .., but its file name part did not contain dash (i.e. -) character. -* The compiler generated invalid C\++ code if the first operand of predefined function `substr` was a charstring element. The {cpp} compiler complained about an ambiguous function overload. +* The compiler generated invalid {cpp} code if the first operand of predefined function `substr` was a charstring element. The {cpp} compiler complained about an ambiguous function overload. * The following bug fixes have been made on the GUI: @@ -1979,7 +1979,7 @@ Released on June 30, 2005. * The compiler aborted with an internal fatal error when checking a TTCN–3 expression (or sub-expression) if all operands of an arithmetic or logical operation were available at compilation timefootnote:[The operands were literal values or references pointing to constants.] and one of the operands was a referenced value pointing to a TTCN–3 constant of type float or ASN.1 value of type REAL. -* The generated C\++ code was uncompilable if the name of an ASN.1 built-in string type (e.g. UTF8String) was used as identifier in a TTCN–3 module or the name of a TTCN–3 built-in conversion function (e.g. bit2int) was used as ASN.1 identifier. Now the compiler appends a single underscore character to the {cpp} equivalents of these identifiers to avoid name clashes with the definitions of the Base Library. +* The generated {cpp} code was uncompilable if the name of an ASN.1 built-in string type (e.g. UTF8String) was used as identifier in a TTCN–3 module or the name of a TTCN–3 built-in conversion function (e.g. bit2int) was used as ASN.1 identifier. Now the compiler appends a single underscore character to the {cpp} equivalents of these identifiers to avoid name clashes with the definitions of the Base Library. * The compiler caused segmentation fault during semantic analysis if the type of a constant or module parameter was erroneous (e.g. the referenced type was not imported) and the value of the constant or the default value of the module parameter contained an embedded record or set value (i.e. a value with TTCN–3 assignment notation). The problem occurred after reporting the relevant error message and only if when {cpp} code generation was requested (i.e. the command line switch `-s` was not used). @@ -2064,7 +2064,7 @@ Released on April 1, 2005. * In some cases the compiler aborted with an internal fatal error when checking modified templates for record of or set of types. This was the case, for instance, if the base template contained a generic wildcard like ? or *. -* The compiler generated invalid (uncompilable) C\++ code for `getcall` operations if the corresponding signature was imported from another module. This was because the default arguments of the {cpp} function that handles `param` redirects for the respective signature were generated into the source file instead of the header file and thus remained invisible for other modules. +* The compiler generated invalid (uncompilable) {cpp} code for `getcall` operations if the corresponding signature was imported from another module. This was because the default arguments of the {cpp} function that handles `param` redirects for the respective signature were generated into the source file instead of the header file and thus remained invisible for other modules. * The code generator of the compiler ignored the `NotUsedSymbol` characters in `param` redirect of `getcall` and `getreply` operations if the `VariableList` notation was used. Thus the run-time environment assigned the wrong parameters to the given variables. @@ -2114,7 +2114,7 @@ Released on April 1, 2005. * The run-time environment did not handle the variable assignments for record of and set of types properly. If the newly assigned value had fewer elements than the previous value of the variable the extra elements at the end were not erased from the variable. For example, if a variable contained three elements and the newly assigned value had only two, the new value of the variable had incorrectly three elements: the first two from the new value and the third one from the old value. This problem was present regardless whether the embedded type was a built-in or a user defined type or the extra values were bound or not. The effects of this bug were the most strange if a component variable of the MTC was initialized in the component type definition and several test cases were executed after each other. -* The run-time environment caused dynamic test case error if an optional component of an ASN.1 `SEQUENCE` or `SET` type, the type of which was the ANY type, was assigned to an optional octetstring field of a TTCN–3 `record` or `set` type and the source field contained omit value. The appropriate C\++ member function was missing and the {cpp} compiler performed an implicit conversion, which assumed that the value of the source field is present. +* The run-time environment caused dynamic test case error if an optional component of an ASN.1 `SEQUENCE` or `SET` type, the type of which was the ANY type, was assigned to an optional octetstring field of a TTCN–3 `record` or `set` type and the source field contained omit value. The appropriate {cpp} member function was missing and the {cpp} compiler performed an implicit conversion, which assumed that the value of the source field is present. * In case of some valid, but sophisticated TTCN–3 or ASN.1 type recursion loops the compiler did not produce the equivalent {cpp} classes in the right bottom-up order. Thus the generated code was uncompilable because of forward referencing of incomplete types. @@ -2124,9 +2124,9 @@ Released on April 1, 2005. * The compiler aborted with an internal fatal error during semantic analysis if the base template of a modified union template did not contain a specific value (e.g. it was a generic wildcard like "?"). -* The generated C\++ code was uncompilable if an indexed element of a string value was assigned to a template. The {cpp} compiler complained about ambiguous function overloads in case of all string types (i.e. bitstring, hexstring, octetstring, charstring and universal charstring). +* The generated {cpp} code was uncompilable if an indexed element of a string value was assigned to a template. The {cpp} compiler complained about ambiguous function overloads in case of all string types (i.e. bitstring, hexstring, octetstring, charstring and universal charstring). -* The generated C\++ code was uncompilable if an operand of a built-in TTCN–3 arithmetic, logical or string operation was a reference pointing to an optional field of a record or set value. The problem was present in case of all TTCN–3 operations that are mapped to infix {cpp} operators. +* The generated {cpp} code was uncompilable if an operand of a built-in TTCN–3 arithmetic, logical or string operation was a reference pointing to an optional field of a record or set value. The problem was present in case of all TTCN–3 operations that are mapped to infix {cpp} operators. * The HC logs contained incorrect information about the exit status of the test component if the corresponding UNIX process was terminated by a signal. In this case the log file showed a successful (zero) exit status although the process was aborted by a fatal error. Now the HC distinguishes between normal and abnormal process termination and reports the signal number instead of exit status in the latter case. @@ -2278,9 +2278,9 @@ Released on September 20, 2004. * The compiler reported memory leak at termination if it encountered a `self.stop` or `mtc.stop` statement in its input module(s). A small memory block was not deallocated during the parsing of these constructs. This mistake had no other harmful side-effects. -* The compiler generated invalid C\++ code if a TTCN–3 `activate` operation was used as a function statement. This construct was introduced in the most recent BNF and the newly written code generator forgot to put a semi-colon at the end of the equivalent {cpp} statement. +* The compiler generated invalid {cpp} code if a TTCN–3 `activate` operation was used as a function statement. This construct was introduced in the most recent BNF and the newly written code generator forgot to put a semi-colon at the end of the equivalent {cpp} statement. -* If a TTCN–3 or ASN.1 module contained an enumerated type and it was imported into another TTCN–3 module using the undocumented `"light" extension` attribute the C\++ equivalent of the importing module was uncompilable. This option disables the processing of some sections of the imported {cpp} header file from the importing module by using the C preprocessor to reduce the compilation time for large projects. The masked section contains mainly the C\++ equivalent classes of data types and in this case some in-line enumerated conversion functions in another (active) section referred to class members, which were invisible from the {cpp} translation unit of the importing module. +* If a TTCN–3 or ASN.1 module contained an enumerated type and it was imported into another TTCN–3 module using the undocumented `"light" extension` attribute the {cpp} equivalent of the importing module was uncompilable. This option disables the processing of some sections of the imported {cpp} header file from the importing module by using the C preprocessor to reduce the compilation time for large projects. The masked section contains mainly the {cpp} equivalent classes of data types and in this case some in-line enumerated conversion functions in another (active) section referred to class members, which were invisible from the {cpp} translation unit of the importing module. * The compiler did not accept the hexadecimal string notation in ASN.1 modules for the values of the ANY type. @@ -2300,7 +2300,7 @@ Released on September 20, 2004. * The compiler aborted with an internal fatal error during error recovery (i.e. after reporting the error) if an invalid `SEQUENCE` notation was used for an ASN.1 REAL value. -* The generated C\++ code could be uncompilable due to ambiguous function overloads in the class that implements TTCN–3 port types if the support of address type was turned on (i.e. the extension attribute `address` was used in the port type). The problem appeared only if the port type had outgoing messages or signatures and the address type was aliased to a built-in type the {cpp} equivalent class of which had a constructor with `int` parameter (e.g.` integer`, objid and all string types). The reason was a missing explicit cast in a generated function and the {cpp} compiler could not distinguish between component references and address values. +* The generated {cpp} code could be uncompilable due to ambiguous function overloads in the class that implements TTCN–3 port types if the support of address type was turned on (i.e. the extension attribute `address` was used in the port type). The problem appeared only if the port type had outgoing messages or signatures and the address type was aliased to a built-in type the {cpp} equivalent class of which had a constructor with `int` parameter (e.g.` integer`, objid and all string types). The reason was a missing explicit cast in a generated function and the {cpp} compiler could not distinguish between component references and address values. * The compiler produced invalid {cpp} code if the to clause was present in a TTCN–3 `raise` port operation. The generated code contained an unnecessary extra closing parenthesis. @@ -2355,7 +2355,7 @@ Released on September 20, 2004. * The type descriptor needed for the RAW encoding of the boolean type was missing from the run-time environment. This resulted in segmentation fault if a message containing a boolean field was encoded or decoded. -* The compiler accepted an invalid syntax for catching timeout on procedure based ports. The string `catch timeout` was interpreted as a `catch` operation in addition to the standard `PortReference.catch(timeout)` notation. Moreover, the standard syntax produced invalid C\++ output, only the irregular variant resulted in working code. Only the standard syntax is accepted from now, and it is translated to a valid {cpp} code. +* The compiler accepted an invalid syntax for catching timeout on procedure based ports. The string `catch timeout` was interpreted as a `catch` operation in addition to the standard `PortReference.catch(timeout)` notation. Moreover, the standard syntax produced invalid {cpp} output, only the irregular variant resulted in working code. Only the standard syntax is accepted from now, and it is translated to a valid {cpp} code. * The compiler returned a misleading successful (zero) exit status if it encountered a general problem with an input file (e.g. the file could not be opened or classified as a TTCN–3 or ASN.1 module). @@ -2485,7 +2485,7 @@ NOTE: Although it is trivial to show a possible successful matching, it is very *Fixed bugs* -* If the `-E` (enum-hack) switch was used the compiler generated invalid C\++ code for those ASN.1 enumerated values that are keywords in both TTCN–3 and {cpp} languages (e.g. true). +* If the `-E` (enum-hack) switch was used the compiler generated invalid {cpp} code for those ASN.1 enumerated values that are keywords in both TTCN–3 and {cpp} languages (e.g. true). * If an ASN.1 `SEQUENCE`, `SET` or `CHOICE` type definition contained a syntax error the error recovery routines of the compiler did not work properly. Thus the compiler could fail with internal error messages or produce memory leaks later during the semantic analysis. @@ -2532,11 +2532,11 @@ Released on January 23, 2004. * The compiler issued irrelevant error messages for modified templates if the base template had formal parameter list. The error message complained about missing actual parameter lists, but the actual parameters of the base template shall not be specified according to TTCN–3 syntax. -* The compiler aborted with an internal fatal error if the base template reference of a modified template pointed to a definition other than a template. _•_ The compiler generated invalid C\++ code for some ASN.1 constructs if the enumhack (`-E`) option was used. If an ASN.1 type contained an embedded (unnamed) ENUMERATED type the {cpp} `enum` values were incorrectly prefixed in value assignments for such types. +* The compiler aborted with an internal fatal error if the base template reference of a modified template pointed to a definition other than a template. _•_ The compiler generated invalid {cpp} code for some ASN.1 constructs if the enumhack (`-E`) option was used. If an ASN.1 type contained an embedded (unnamed) ENUMERATED type the {cpp} `enum` values were incorrectly prefixed in value assignments for such types. -* The compiler crashed with a segmentation fault if an actual parameter of an altstep invocation contained an in-line compound expression. The C\++ mapping of such constructs is still unsolved due to the lack of full semantic analysis. The compiler now continues the parsing and substitutes the unsupported parameter with the comment /* NOT SUPPORTED */ in the output code, which will cause a {cpp} compilation error. +* The compiler crashed with a segmentation fault if an actual parameter of an altstep invocation contained an in-line compound expression. The {cpp} mapping of such constructs is still unsolved due to the lack of full semantic analysis. The compiler now continues the parsing and substitutes the unsupported parameter with the comment /* NOT SUPPORTED */ in the output code, which will cause a {cpp} compilation error. -* The compiler generated erroneous C\++ code for certain legal TTCN–3 constructs. Let us assume that the name P was used to identify a component variable in component type A. If a function, altstep or testcase had a runs on clause other than A and a formal parameter named `P` the resulting {cpp} code did not compile if parameter `P` was used in the function body. The reason is that the TTCN–3 component type scoping is solved using tricky C preprocessor macros in the generated code. Due to the wrong placement of preprocessor statements different name substitution rules were applied on formal parameter list and function body. +* The compiler generated erroneous {cpp} code for certain legal TTCN–3 constructs. Let us assume that the name P was used to identify a component variable in component type A. If a function, altstep or testcase had a runs on clause other than A and a formal parameter named `P` the resulting {cpp} code did not compile if parameter `P` was used in the function body. The reason is that the TTCN–3 component type scoping is solved using tricky C preprocessor macros in the generated code. Due to the wrong placement of preprocessor statements different name substitution rules were applied on formal parameter list and function body. * If the user `unmap` function of a Test Port called Install Handler the event handler could remain active after the deactivation of the port. This could result in unexpected Event Handler calls and warnings when the test component terminated. @@ -2789,7 +2789,7 @@ Released on June 13, 2003. * The `Makefile` generated by the compiler behaved incorrectly in case of incremental compilation because of a missing empty rule. The build process stopped immediately after the translation of TTCN–3 and ASN.1 modules and the {cpp} compiler was not invoked. The `make` command had to be issued again for the complete build. Moreover, in case of the non-GNU version the build procedure did not stop if the TTCN–3 /ASN.1 compiler returned unsuccessful exit status. -* The `-E` (enum-hack) option generated invalid C\++ identifiers if the enumeration was a C/{cpp} keyword (e.g.`class`). +* The `-E` (enum-hack) option generated invalid {cpp} identifiers if the enumeration was a C/{cpp} keyword (e.g.`class`). * The default syntax (i.e. when `WITH SYNTAX` is not defined) of object classes was implemented incorrectly. @@ -3002,7 +3002,7 @@ Released on October 11, 2002. * The internal string handling routines were rewritten in both TTCN–3 and ASN.1 compilers. The old functions were inefficient, especially when generating large {cpp} output files. The improved TTCN–3 compiler runs significantly (about 4 times, the ASN.1 compiler 2 times) faster on a typical input module. -* The C\++ header and source files generated from TTCN–3 and ASN.1 type definitions were restructured so that the header files became smaller. This means faster compilation (with lower memory usage) from {cpp} to object module in case of the importing modules of those type definitions. +* The {cpp} header and source files generated from TTCN–3 and ASN.1 type definitions were restructured so that the header files became smaller. This means faster compilation (with lower memory usage) from {cpp} to object module in case of the importing modules of those type definitions. * The error messages related to templates became more talkative for record/set/SEQUENCE and union/CHOICE types. This helps locating the error when debugging faulty template definitions. The type and field names are incorporated into the error strings. @@ -3059,7 +3059,7 @@ Released on August 16, 2002. * Event severity TTCN DEBUG was introduced in logger. -* String literals (constants) are translated to static C\++ objects, that is, they are listed in the source file only. In previous version when a string constant was added to or removed from the source TTCN–3 module, the compiler re-generated the {cpp} header file as well and therefore it was necessary to re-compile several {cpp} files. +* String literals (constants) are translated to static {cpp} objects, that is, they are listed in the source file only. In previous version when a string constant was added to or removed from the source TTCN–3 module, the compiler re-generated the {cpp} header file as well and therefore it was necessary to re-compile several {cpp} files. *Fixed bugs* @@ -3161,7 +3161,7 @@ Released on February 11 2002. * The built-in TTCN–3 type verdicttype was not recognized by the compiler. The compiler supported the older syntax that called this type as verdict. -* The compiler generated invalid C\++ code if you used an enumerated type in a record of type construct (within the same module). The resulting {cpp} definitions were in the wrong order. +* The compiler generated invalid {cpp} code if you used an enumerated type in a record of type construct (within the same module). The resulting {cpp} definitions were in the wrong order. * The octetstring values that contained ASCII control characters (e.g. newlines or tabulators) were incorrectly logged in ASCII format. @@ -3182,7 +3182,7 @@ Released on December 21 2001. * The compiler inserts source code information (i.e. the name and line number of TTCN–3 source code) as comments into the equivalent {cpp} code of TTCN–3 functions, test cases and control parts. This feature hopefully can help when locating syntax errors in TTCN–3 code. It still does not work for other definitions (such as constants or templates), but it will be extended in future versions. -* The `-l` command line switch instructs the compiler to include this line information as #line directives instead of C\++ comments. Using this the error messages of the {cpp} compiler will point to the lines of the original TTCN–3 source code. However, be extremely careful with this option because sometimes the error messages can refer to invalid line numbers. In such cases turn this switch off and analyze the {cpp} code manually. +* The `-l` command line switch instructs the compiler to include this line information as #line directives instead of {cpp} comments. Using this the error messages of the {cpp} compiler will point to the lines of the original TTCN–3 source code. However, be extremely careful with this option because sometimes the error messages can refer to invalid line numbers. In such cases turn this switch off and analyze the {cpp} code manually. * The TTCN–3 `rem` operator is now supported. In the Test Port API it is mapped to global function `rem`, which takes two arguments, either `INTEGER` or `int` in any combinations. @@ -3288,7 +3288,7 @@ Released on September 17 2001. *New features* -* The compiler does not overwrite the target C\++ header or source file if its content does not change. This can speed up incremental compilation because the header files usually do not change if the user only modifies a TTCN–3 definition and therefore only one {cpp} module shall be re-compiled. This feature can be disabled by passing the `-f` switch to the compiler. +* The compiler does not overwrite the target {cpp} header or source file if its content does not change. This can speed up incremental compilation because the header files usually do not change if the user only modifies a TTCN–3 definition and therefore only one {cpp} module shall be re-compiled. This feature can be disabled by passing the `-f` switch to the compiler. * Non-standard conversion functions `oct2char` and `char2oct` were introduced. @@ -3352,11 +3352,11 @@ Released on August 1 2001. *Fixed bugs* -* Some C\++ templates of Base Library generated erroneous {cpp} code. +* Some {cpp} templates of Base Library generated erroneous {cpp} code. * The bug in Main Controller that caused some map operations to fail was fixed. -* C/C\++ keywords that are not keywords in TTCN–3 are now translated to valid {cpp} identifiers, i.e. the compiler appends a trailing underscore character to them. +* C/{cpp} keywords that are not keywords in TTCN–3 are now translated to valid {cpp} identifiers, i.e. the compiler appends a trailing underscore character to them. * C style comments longer than 16 kbytes in TTCN–3 modules caused the compiler to fail during translation. @@ -3537,9 +3537,9 @@ Log event subtypes were introduced and the generated codes were updated to use t [[version-1-7-pl0]] == Version 1.7.pl0 -* Test Port classes as well as C\++ classes of user defined data types are put into a {cpp} namespace that corresponds to the TTCN–3 module. (INCOMPATIBLE) +* Test Port classes as well as {cpp} classes of user defined data types are put into a {cpp} namespace that corresponds to the TTCN–3 module. (INCOMPATIBLE) -* The C\++ equivalents of TTCN–3 and ASN.1 enumerated values were moved into the scope of the {cpp} class that implements the enumerated type. The enum-hack option became obsolete. (INCOMPATIBLE) +* The {cpp} equivalents of TTCN–3 and ASN.1 enumerated values were moved into the scope of the {cpp} class that implements the enumerated type. The enum-hack option became obsolete. (INCOMPATIBLE) * The {cpp} enumerated type that describes the selected field of a TTCN–3 union or ASN.1 CHOICE type was moved into the scope of the value class. The naming rules of the possible enumerated values have changed too. (INCOMPATIBLE) @@ -3640,7 +3640,7 @@ No changes. * The procedure based ports are now supported with an enhanced Test Port API. (ADDITION) -* The C\++ code generated by the compiler has changed for record of, set of and enumerated types. These are not realized as {cpp} template classes any more, but as regular {cpp} classes. These changes should not cause any incompatibilities in properly written test ports. +* The {cpp} code generated by the compiler has changed for record of, set of and enumerated types. These are not realized as {cpp} template classes any more, but as regular {cpp} classes. These changes should not cause any incompatibilities in properly written test ports. * The parameter type and/or return type of some helper functions used for enumerated types has been changed from `int` to `enum`. This may require explicit casting in some Test Ports. (INCOMPATIBLE) diff --git a/usrguide/userguide/2-overview_of_titan.adoc b/usrguide/userguide/2-overview_of_titan.adoc index aef3ed5007ce9d29eeedebd63f35d324611ed932..7bb53e52fe05b95ba25d87486d5f144123a718d6 100644 --- a/usrguide/userguide/2-overview_of_titan.adoc +++ b/usrguide/userguide/2-overview_of_titan.adoc @@ -13,9 +13,9 @@ The main components are the following: * The *Test Port(s)*, which facilitate the communication between the TTCN–3 Test System and the System Under Test (SUT). -The generated C\++ modules as well as the Test Ports should be compiled to binary object code and linked together with the Base Library using a traditional {cpp} compiler. +The generated {cpp} modules as well as the Test Ports should be compiled to binary object code and linked together with the Base Library using a traditional {cpp} compiler. -All parts, except the protocol specific Test Ports, are included in the binary package of the Test Executor. The Test Executor is a protocol and platform independent tool that can be easily adapted to any kind of protocols by writing the appropriate Test Port. The generated C\++ code is exactly the same on all platforms, provided that the pre-compiled Base Library that matches the operating system and {cpp} compiler is used. The Test Port may use operating system calls or external library functions for sending or receiving messages towards System Under Test so it may become platform dependent. +All parts, except the protocol specific Test Ports, are included in the binary package of the Test Executor. The Test Executor is a protocol and platform independent tool that can be easily adapted to any kind of protocols by writing the appropriate Test Port. The generated {cpp} code is exactly the same on all platforms, provided that the pre-compiled Base Library that matches the operating system and {cpp} compiler is used. The Test Port may use operating system calls or external library functions for sending or receiving messages towards System Under Test so it may become platform dependent. Writing a Test Port is not an easy task for the first time, but the Compiler alleviates it by generating an empty skeleton for each function to be written. This skeleton is also useful for checking the correctness of an existing test suite because the Executable Test Program can be linked with this empty Test Port. In this case the resulting program actually does nothing, but the successful linking means that no modules or functions are missing from the test suite. diff --git a/usrguide/userguide/3-creating_executable_test_suites_from_the_command-l.adoc b/usrguide/userguide/3-creating_executable_test_suites_from_the_command-l.adoc index b2d4f1bbcbcd3f90cd988d726d127fefb8097940..0cf58370a8c1934f108ab7b8b5409591dc738b4c 100644 --- a/usrguide/userguide/3-creating_executable_test_suites_from_the_command-l.adoc +++ b/usrguide/userguide/3-creating_executable_test_suites_from_the_command-l.adoc @@ -39,7 +39,7 @@ In this case simply issue the command `*make MyModule.o*` and the two translatio === Rules for Modular Test Suites -The compiler supports modular TTCN–3 test suites as well. Each module is translated to a separate C\++ header and source file. These source files can be compiled by the {cpp} compiler one-by-one separately. +The compiler supports modular TTCN–3 test suites as well. Each module is translated to a separate {cpp} header and source file. These source files can be compiled by the {cpp} compiler one-by-one separately. The importing mechanisms work in the following way. For example, two TTCN-3 modules are present in files `A.ttcn` and `B.ttcn`, respectively. Definitions of module A may be used from module B, so the `import from A all`; statement must be added to module B. The modules A and B *must* be translated by the compiler in one step to `A.cc`, `A.hh`, `B.cc` and `B.hh`. During the compilation from TTCN–3 to {cpp} of module B, the import statement will be translated to `#include "A.hh"`. This statement will be put to the beginning of `B.hh`, so you can refer to any definitions of A in module B. But note that when compiling `B.cc`, `A.hh` must exist and it must be up to date. @@ -107,11 +107,11 @@ If the `Makefile` generator ensured that the file is neither a TTCN–3 nor an A The remaining files (configuration files and so on) will be added to the other files’ section of the `Makefile`. These files do not take part in the build process, but they are added to the archive files created using the `Makefile`. -After the classification, the `Makefile` generator filters out the redundant generated C\++ files. If a given C/{cpp} file was found to be generated from one of the given TTCN–3 or ASN.1 modules, a warning is printed and the file will be dropped from the list of C/{cpp} files. That is, the file will not be added to the list of user source files since it is already a member of the generated sources. This feature is useful if one wants to regenerate the `Makefile` using the shell wildcard `*.cc` while the generated files from the previous compilation are still present. +After the classification, the `Makefile` generator filters out the redundant generated {cpp} files. If a given C/{cpp} file was found to be generated from one of the given TTCN–3 or ASN.1 modules, a warning is printed and the file will be dropped from the list of C/{cpp} files. That is, the file will not be added to the list of user source files since it is already a member of the generated sources. This feature is useful if one wants to regenerate the `Makefile` using the shell wildcard `*.cc` while the generated files from the previous compilation are still present. -In the next step the algorithm tries to complete the list of C/C\++ files by checking the pairs of header and source files. If a C/{cpp} source file was identified and a header file with the same name exists (only the suffix differs) too, the `Makefile` generator will add the header file automatically. This step is performed in the reverse direction too: the `Makefile` generator can find an existing source file based on the header file given to it. Of course a {cpp} source file can exist without a header file or vice versa. +In the next step the algorithm tries to complete the list of C/{cpp} files by checking the pairs of header and source files. If a C/{cpp} source file was identified and a header file with the same name exists (only the suffix differs) too, the `Makefile` generator will add the header file automatically. This step is performed in the reverse direction too: the `Makefile` generator can find an existing source file based on the header file given to it. Of course a {cpp} source file can exist without a header file or vice versa. -The `Makefile` generator continuously checks the uniqueness of files and module names. If the same file was given more than once in the command line the repeated argument is simply ignored and a warning message is displayed. It is not allowed to use two or more different TTCN–3 or ASN.1 files containing modules with the same name because the generated C\++ files would clash. For similar reasons the user C/{cpp} files cannot have identical names even if they are located in different directories. +The `Makefile` generator continuously checks the uniqueness of files and module names. If the same file was given more than once in the command line the repeated argument is simply ignored and a warning message is displayed. It is not allowed to use two or more different TTCN–3 or ASN.1 files containing modules with the same name because the generated {cpp} files would clash. For similar reasons the user C/{cpp} files cannot have identical names even if they are located in different directories. Finally the `Makefile` is generated based on the resulting data. If the `Makefile` generator finds an existing `Makefile` in its working directory, it will not be overwritten unless the option `-f` is used. @@ -147,7 +147,7 @@ The central directories should contain those common modules that do not change f In addition to the above mentioned ones the following assumptions are used in these `Makefiles`: -* The compiler will generate C\++ files only for those TTCN–3 and ASN.1 modules that are located in the current working directory. The generated {cpp} files of the remaining TTCN–3 and ASN.1 modules should be located in the same directory as the respective module. If a module is located in a directory other than the current working directory and it does not have pre-compiled files a symbolic link must be created in the current working directory, which should point to the file containing the module. +* The compiler will generate {cpp} files only for those TTCN–3 and ASN.1 modules that are located in the current working directory. The generated {cpp} files of the remaining TTCN–3 and ASN.1 modules should be located in the same directory as the respective module. If a module is located in a directory other than the current working directory and it does not have pre-compiled files a symbolic link must be created in the current working directory, which should point to the file containing the module. * Object and if applicable, shared object files will be created only from those C/{cpp} source files that are located in the current working directory. Object and if applicable, shared object files of the remaining source files should be located in the same directory as the respective source file. @@ -163,7 +163,7 @@ Note that when a pre-compiled TTCN–3 or ASN.1 module is taken from a central d * The module itself when performing the semantic analysis on the local modules importing it. -* The generated C\++ header file when compiling the generated {cpp} files of the importing modules. +* The generated {cpp} header file when compiling the generated {cpp} files of the importing modules. * The object and if applicable, the shared object file when linking the executable. @@ -359,14 +359,14 @@ Removes all generated files (generated {cpp} files, object and TITAN generated s * `*make compile*` + -Translates the TTCN–3 and ASN.1 modules to C\++. It is useful when the user wants to carry out the compilation of the generated {cpp} code later. As a result, an empty file named `compile` is created in the working directory. The attributes of this file contain the date and time of the last compilation, which helps the compiler in selective code generation. It is not recommended to change this file manually. The compiler will be invoked only if one or more of the TTCN–3 or ASN.1 modules were modified after that timestamp, otherwise the generated {cpp} files are up to date. +Translates the TTCN–3 and ASN.1 modules to {cpp}. It is useful when the user wants to carry out the compilation of the generated {cpp} code later. As a result, an empty file named `compile` is created in the working directory. The attributes of this file contain the date and time of the last compilation, which helps the compiler in selective code generation. It is not recommended to change this file manually. The compiler will be invoked only if one or more of the TTCN–3 or ASN.1 modules were modified after that timestamp, otherwise the generated {cpp} files are up to date. * `*make diag*` + Lists general information about the environment and the build. This information can be useful to fix build problem by the developers or the support team. The output contains: + - the compiler related information (titan version, build date, C\\++ version, license information, see command `*"compiler –v"*`), + - main controller related information (titan version, {cpp} compiler version, build date, license information, see command `*"mctr_cli –v"*`), + -- C\++ compiler information (see command `*"g++ -v"*`), + +- {cpp} compiler information (see command `*"g++ -v"*`), + - library creator info ( see command `*"ar –v"*`), + - values of environment variables `$TTCN3_DIR`, ``$ OPENSSL_DIR`, `$XML_DIR`, `$PLATFORM`. @@ -463,13 +463,13 @@ This section contains information useful for the experienced users who are using === Compiling the Generated {cpp} Code -If the TTCN–3 test suite was successfully translated to C\++, it’s a good idea to check if the generated code contains any errors. The simplest way is to compile it using a {cpp} compiler. Since the generated code refers to the base library, run the following command: +If the TTCN–3 test suite was successfully translated to {cpp}, it’s a good idea to check if the generated code contains any errors. The simplest way is to compile it using a {cpp} compiler. Since the generated code refers to the base library, run the following command: [source, subs="+quotes"] *g++ -c -I$TTCN3_DIR/include -Wall MyModule.cc* -In the following, using of an GNU C\++ compiler is assumed. If the TTCN–3 /ASN.1 compiler did not report any errors in the input test suite, the generated {cpp} code must be correct (that is, compile without errors). After certain TTCN–3 warnings (such as unreachable statements) the generated code may trigger similar warnings in the {cpp} compiler. +In the following, using of an GNU {cpp} compiler is assumed. If the TTCN–3 /ASN.1 compiler did not report any errors in the input test suite, the generated {cpp} code must be correct (that is, compile without errors). After certain TTCN–3 warnings (such as unreachable statements) the generated code may trigger similar warnings in the {cpp} compiler. -The generated code has been tested on various versions of GNU C\++ and Sun Workshop {cpp} compilers. However, the code should work with any standard-compliant C\++ compiler since it does not depend on hardware or compiler specific features. If the generated code fails to compile on a supported platform and {cpp} compiler the situation is considered as a compiler bug and a Trouble Report can be issued footnote:[The Trouble Report must include the compiler error message(s), all input files and command line switches of the TTCN–3 /ASN.1 compiler, the platform and the exact version of TITAN TTCN–3 Test Executor and the {cpp} compiler. It is highly appreciated if the user could minimize the input by dropping out irrelevant modules and definitions.]. +The generated code has been tested on various versions of GNU {cpp} and Sun Workshop {cpp} compilers. However, the code should work with any standard-compliant {cpp} compiler since it does not depend on hardware or compiler specific features. If the generated code fails to compile on a supported platform and {cpp} compiler the situation is considered as a compiler bug and a Trouble Report can be issued footnote:[The Trouble Report must include the compiler error message(s), all input files and command line switches of the TTCN–3 /ASN.1 compiler, the platform and the exact version of TITAN TTCN–3 Test Executor and the {cpp} compiler. It is highly appreciated if the user could minimize the input by dropping out irrelevant modules and definitions.]. The switch `-c` tells the GNU {cpp} compiler to compile only and not to build an executable because, for example, the `main` function is missing from the generated code. The switch `-I` adds the `$TTCN3_DIR/include` directory to the compiler’s standard include path. The optional argument, `-Wall`, forces the compiler to report all warnings found in its input. This argument can be used in GCC only. diff --git a/usrguide/userguide/4-executing_test_suites.adoc b/usrguide/userguide/4-executing_test_suites.adoc index f1529136efb5a2a6635e2e9b9c5e9bf157b8de1d..5324ab4006872f8584052270c31d9fa5ebdce9ed 100644 --- a/usrguide/userguide/4-executing_test_suites.adoc +++ b/usrguide/userguide/4-executing_test_suites.adoc @@ -294,7 +294,7 @@ The script returns different exit codes which can be used by user written softwa == Strange Behavior of the Executable -If modular test suites are executed, sometimes the executable test program can do strange things, for example, the execution terminates without any reason or the send functions of the Test Port is not called, and so on. This is because out-of-date C\++ header files are used for translating the {cpp} modules, that is, there is a wrong `Makefile`. +If modular test suites are executed, sometimes the executable test program can do strange things, for example, the execution terminates without any reason or the send functions of the Test Port is not called, and so on. This is because out-of-date {cpp} header files are used for translating the {cpp} modules, that is, there is a wrong `Makefile`. This may happen when the Test Port files are renamed, so the compiler regenerates them. Thus the {cpp} source files generated by the compiler see an empty Test Port header file, but the fully functional Test Port object file is linked to the executable. In this case, the linking will be successful, but during the execution strange things can happen. The reason behind this phenomenon is that the modules consider the raw binary structure of the same {cpp} class different, for example they fetch the virtual function pointer from a wrong place.