Operating System The following operating systems are officially supported:
T3DevKit is mostly portable (thanks to the boost libraries and the waf build automation tool). It should be easy to port to other toolchains and operating systems.
Note: Some TTCN-3 compilers are not available on some platform. Table 2.1 display configurations that have been tested successfully with T3DevKit.
TTCN-3 Compiler You will need a TTCN-3 compiler that provides the C variant of ETSI standard interfaces: TRI and TCI. Currently two compilers are officially supported:
Some works have been done to integrate T3DevKit with other tools, but the support may not be complete or up-to-date:
Contributions for supporting other tools are welcome.
C++ Compiler The following compilers have been used successfully:
Flex and Bison
The Boost Libraries available at www.boost.org
Python 2.x is needed for running the waf scripts in order to build t3devkit and the TTCN-3 executable test suites (available at www.python.org) Windows users will also need to install the windows extensions package available on sourceforge.net
|Linux (32bit)||Linux (64bit)||Cygwin (32bit)||Windows (32bit)|
|Rational Systems Tester||X||X||X|
The installation procedure simplified thanks to the build automation tool waf. After decompressing the package just open a terminal and run the following commands in t3devkit’s source directory:
Note: Windows users may need to prefix the command with the path of the python interpreter. Example:
The waf script will try to detect which TTCN-3 tools are present on your system.
If your tool is not successfully detected, you may need to provide its installation path with --check-ttcn3-dir:
If you have several TTCN-3 tools installed on your system, waf will use the first one to be detected. You may want to force the detection of another tool with --check-ttcn3-compiler
The boost libraries may be difficult to detect (especially on windows) because their location and the suffix of the library files depend on the way the way boost was built and installed (by default the waf script will try with the -mt suffix). You can use --boost-dir to indicate where the libraries are installed and --boost-suffix to use another suffix, for example:
Note: Visual C++ users must ensure that the boost libraries are linked with the same variant of the C++ runtime library as the variant used by the TTCN-3 tool (i.e with the same compilation option among /MD /MDd /ML /MLd /MT /MTd /LD /LDd). You can get more detailed information on msdn.
By default the toolkit will be installed in /usr/local on posix systems and in C:\Documents and Settings\<user>\Local Settings\Temp on windows. You may want to choose another installation path with --prefix.
Once the installation is completed, the following files are installed on the system:
|/usr/local/bin/t3cdgen||the CoDec generator|
|/usr/local/bin/t3devkit-waf||a script to launch waf (with access to the TTCN-3 & T3DevKit modules)|
|/usr/local/bin/twaf||the same as t3devkit-waf but with a shorter name|
|/usr/local/lib/t3devkit/*.o||the TRI/TCI integration modules provided by T3DevKit|
|/usr/local/share/t3devkit/waf-light||a local copy of waf to be used to compile the executable test suites|
|/usr/local/share/t3devkit/waftools||additional waf modules providing support for TTCN-3 and T3DevKit|
The process of building an executable test suite can be quite complex. It is a subtle mix of C/C++ files and libraries, some of which are written manually while others are generated from TTCN-3 source files with two different tools (the TTCN-3 tool and T3DevKit’s CoDec Generator).
Hopefully T3DevKit provides a generic framework based on waf for doing the work transparently, whatever TTCN-3 tool is used. This is the recommended way to build executable test suites with T3DevKit.
TTCN-3 & T3DevKit support in waf is provided by additional python modules located by default in /usr/local/share/t3devkit/waftools. This directory must be present in the PYTHONPATH environment variable when running waf. T3DevKit provides a wrapper script twaf which does that automatically. From now on you should type twaf to launch waf.
This section describes how to write a waf build script to generate a TTCN-3 executable test suite using waf. More general information about the content of the file about waf’s usage can be found on waf’s official website.
Below is the build script of the HelloWorld example provided with T3DevKit. It is written in python and provides some functions and variables expected by waf.
configure() is called when waf is run with the configure command (“waf configure”). Its role is to prepare the build (detect the compilers & libraries installed on the system, ...). In our case the only needed action is to detect if a TTCN-3 compiler and T3DevKit are installed on the system (this will also load the corresponding waf extension modules).
Note: It is not necessary to detect the ’compiler_cxx’ tool because it is implicitly detected with t3devkit.
set_options() is used to declare additional command line options for waf. Here we just call opt.tool_options() to load the options provided by the compiler_ttcn3 and t3devkit modules.
The build() function implements the build phase. Its role is to create all the tasks (translation, compilation, linking, ...) to be executed to build the test suite. It is better not to create all these tasks manually because it is a tedious process and the result would very likely not be portable (the build procedure may be very different from one TTCN-3 tool to another). It is recommended to use the facade function ttcn3_ets() whose purpose is to generate all the tasks to build a TTCN-3 executable test suite.
ttcn3_ets() may take the following parameters:
|target||name of target file (Executable Test Suite to be generated)|
|root_module||name of the TTCN-3 root module of the test suite|
|root_module||name of the TTCN-3 root module of the test suite|
|features||additional features to include in the build|
|(these are implemented in waf extensions modules)|
The function takes accept additional options that are propagated to the actual task generators that will build the C/C++ executables.
Most of these options have a two-letter prefix corresponding to the runtime module to which they apply: te, sa, pa, cd, ch, tm or tl (see Figure 2.1). For example sa_source contains the list of source files for the System Adapter and the list of TTCN-3 source files shall be given in te_source.
Options prefixed with ets_ will apply to all the runtime modules. For example with ets_cxxflags = ’-Wall’, all C++ files in all the modules will be compiled with the -Wall option.
More details about the TTCN-3 runtime modules and the execution environment are given in Section 1.2.2.
The following table lists the options that are forwarded to waf’s task generators and that ca be used prefixed by ets_ by a module acronym. More detailed information about their usage can be found in waf’s documentation (in chapter “C and C++ projects”)
|*_source||list of source files|
|*_includes||additional search directories for the C/C++ preprossor|
|*_defines||additional C/C++ macro definitions|
|*_lib||additional libraries to be linked with this module|
|*_libpath||additional search directories for libraries|
|*_features||additional waf task generator features to be used|
|*_ccflags||additional flags for the compilation of C files|
|*_cxxflags||additional flags for the compilation of C++ files|
|*_linkflags||additional flags for linking the module|
Note: depending on the TTCN-3 tool used for building the Executable Test Suite, these runtime modules may or may not be linked in the same executable. For example a tool may require the System Adapter to be built as a separate dynamic library. Thus you have to be careful about the following points:
Note: if no source files are given for the SA, PA or CD (in other words if sa_source, pa_source or cd_source are empty) then the toolkit will automatically generate a C++ source file with the corresponding initialisation functions required by T3DevKit (SAInit(), SAReset(), PAInit(), PAReset() and CDInit()). This is a convenience feature when there is nothing to be implemented in these modules (for example if your test suite does not have external functions and if your are using the default timers, then you do not need to implement anything the PA).
The support of T3DevKit will be activated in "t3devkit" is present in the features parameter of ttcn3_ets().
T3DevKit provides a CoDec generator and a set of default implementation of each runtime modules (SA, PA, CD, CD, TM and TL). Thus when T3DevKit is activated, the following will take place:
This behaviour can be customised with the following options:
|t3cdgen_source||list of source files for the CoDec generation|
|(by default all files in te_source and cd_source)|
|t3cdgen_header||C++ header used for the CoDec generation (see Section 3.1)|
|t3dk_options||optional integration options|
By default the CoDec will be generated using all source files listed in te_source and cd_source, i.e. all TTCN-3 source files and all CoDec source files. In order to avoid unnecessary recompilations you may want to use the t3cdgen_source option to include only the files that actually contain TTCN-3 type definitions and C++ codets.
The t3dk_options parameter is used to configure which implementation will be used for each TRI/TCI interface. It may contain one or more words among the ones listed in the following table.
|System Adapter||sa_default||use the TRI-SA implementation from T3DevKit|
|no_sa||do not include any TRI-SA implementation|
|Platform Adapter||pa_default||use the TRI-PA implementation from T3DevKit|
|no_pa||do not include any TRI-PA implementation|
|CoDec||cd_default||use the TCI-CD implementation from T3DevKit (will also run the CoDec generator)|
|no_cd||do not include any TCI-CD implementation|
|Component Handler||ch_default||use the TCI-CH implementation from T3DevKit (dummy implementation with local execution only)|
|no_ch||do not include any TCI-CH implementation|
|Test Manager||tm_default||use the default TCI-TM implementation from T3DevKit|
|tm_native||use the native TM interface provided by the TTCN-3 tool|
|no_tm||do not include any TCI-TM implementation|
|Test Logger||tl_default||use the default TCI-TL implementation from T3DevKit|
|tl_dummy||use a dummy implementation of TCI-TL (useful when the TTCN-3 tool provides a native logging interface)|
|tl_logo||use a TCI-TL implementation that generates HTML reports (suitable for the IPv6 Ready Logo)|
|no_tl||do not include any TCI-TL implementation|
Note: Some options may not be supported by every TTCN-3 tool (for example if the relevant TRI/TCI interface is not supported)
Once the wscript file is written, the Executable Test Suite can be built and executed by running the command twaf or t3devkit-waf (both are equivalent).
twaf will run the copy of waf installed along with T3DevKit, with the t3devkit and compiler_ttcn3 modules ready to be loaded.
Note: If you choose to run your own copy of waf (either in the source directory or installed elsewhere in the system), then you must make sure that the extensions modules for TTCN-3 and T3DevKit are available. These modules are installed by default in /usr/local/share/t3devkit/waftools. You can either add this directory into the PYTHONPATH environment variable or copy its content into your wafadmin/Tools directory.
The procedure to build the test suite is pretty similar to the procedure for building T3DevKit. First you need to configure the build:
then run twaf to build the test suite:
If the --run option is present, then the test suite will be executed once the build is finished.
You may want to to make the execution more verbose (this is useful for debugging). T3Devkit provides several trace features that can be activated with environment variables (see chapter 5 for a complete reference):
Note: If you are using an IDE that does not support the “configure” phase, then you may want to run all the commands at once:
T3DevKit provides the configuration option --t3dk-options for overriding the default integration modules used in the test suites (see Section 2.3.1). Example:
If you need to clean the generated files, you can use the clean and distclean targets:
Also you need to distribute or archive your project, you can use the dist target. This will create a versioned archive or your project directory.
Compilation may take a long time, especially on big projects. This section introduces two methods that can be used to speed up the compilation.
By default the waf scripts used with T3DevKit will not compute precompiled headers for the C++ source files. If the project contains lot of files, you may experience a long build time because the headers require have to be recompiled for each single translation unit (especially the boost which tend to be a little heavy).
Precompiled headers are enabled by configuring the project with --precomp. With this option, a generic header will be generated and compiled on the fly. This header includes all the headers that are external to the project.
More details can be found on waf’s website.
Waf uses signatures to decide when files need to be rebuild (instead of comparing the modification dates as in most build automation tools). The signature is generated from the dependencies and the build options, thus there is no need to rebuild the file if the signature is unchanged.
When caching is enabled, waf will also make a copy of the generated file with its signature in its cache directory. Then if the same file is recompiled later with the same options (even after a clean) waf will restore the version in cache.