Chapter 2
Getting Started

 2.1 Requirements
 2.2 Installation
 2.3 Usage
  2.3.1 The build script: wscript
  2.3.2 Running waf
  2.3.3 Speeding up the compilation

2.1 Requirements

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)
gcc gcc gcc msvc





Rational Systems Tester X X X





Picottcn X X X





Testcast T3 X






Table 2.1: Matrix of supported platforms and toolchains

2.2 Installation

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:

 
./waf configure 
./waf 
./waf install

Note: Windows users may need to prefix the command with the path of the python interpreter. Example:

 
c:\python26\python waf configure 
c:\python26\python waf 
c:\python26\python waf install

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:

 
./waf configure --check-ttcn3-dir=/path/to/my/ttcn3/tool

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

 
./waf configure --check-ttcn3-tool=picottcn 
 
./waf configure --check-ttcn3-tool=ibmrst 
 
./waf configure --check-ttcn3-tool=testcast

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:

 
./waf configure --boost-dir=c:\boost --boost-suffix=-vc90-mt-s

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.

 
./waf configure --prefix=/opt/t3devkit

Once the installation is completed, the following files are installed on the system:



File Description




/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/include/t3devlib/*.h T3DevKit’s headers


/usr/local/lib/libt3dev.a the library


/usr/local/lib/t3devkit/*.o the TRI/TCI integration modules provided by T3DevKit


/usr/local/share/t3devkit/waf-lighta local copy of waf to be used to compile the executable test suites
/usr/local/share/t3devkit/wafadmin


/usr/local/share/t3devkit/waftools additional waf modules providing support for TTCN-3 and T3DevKit


2.3 Usage

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.

2.3.1 The build script: wscript

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.

HelloWorld example

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.

 
#! /usr/bin/env python 
# encoding: utf-8 
 
# these variables are mandatory for waf (’/’ are converted automatically) 
srcdir = . 
blddir = __build__ 
 
 
# customisation of wafs command line options 
def set_options(opt): 
        opt.tool_options(compiler_ttcn3 t3devkit) 
 
# configuration phase 
def configure(conf): 
        conf.check_tool (compiler_ttcn3 t3devkit) 
 
# build phase 
def build(bld): 
        obj = bld.ttcn3_ets ( 
 
                target =      HelloWorld_ETS,            # target file name for the executable test suite 
                                                                # -> will generate Helloworld_ETS on POSIX systems 
                                                                #    and Helloworld_ETS.exe on windows 
 
                root_module =  HelloWorld,              # TTCN-3 root module of the test suite 
 
 
                features = t3devkit,                  # additional features used in this executable test suite 
 
 
                te_source = ’’’ttcn/HelloWorld.ttcn  ’’’,  # sources of the Test Executable 
                                                                # (basically all .ttcn and .asn files) 
 
                sa_source = ’’’c++/ConsolePort.cpp 
                                c++/sa-init.cpp      ’’’,  # sources of the System Adapter 
 
                # ets_* options apply to all the modules 
                ets_includes ="c++"                    # add the c++’ directory in the search directories 
                                                                # of the C/C++ preprocessor 
        )

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.

Base options

ttcn3_ets() may take the following parameters:



target name of target file (Executable Test Suite to be generated)


root_modulename 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)



PIC

Figure 2.1: TTCN-3 standard execution environment


Module-specific options (forwarded to waf’s task generators)

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


*_linkflagsadditional 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).

Options specific to T3DevKit

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_sourcelist 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_defaultuse the TRI-SA implementation from T3DevKit


no_sa do not include any TRI-SA implementation






Platform Adapter pa_defaultuse the TRI-PA implementation from T3DevKit


no_pa do not include any TRI-PA implementation






CoDec cd_defaultuse the TCI-CD implementation from T3DevKit (will also run the CoDec generator)


no_cd do not include any TCI-CD implementation






Component Handlerch_defaultuse the TCI-CH implementation from T3DevKit (dummy implementation with local execution only)


no_ch do not include any TCI-CH implementation






Test Manager tm_defaultuse 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_defaultuse 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)

2.3.2 Running waf

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:

 
twaf configure

then run twaf to build the test suite:

 
twaf

If the --run option is present, then the test suite will be executed once the build is finished.

 
twaf --run

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):

 
DEBUG_TRI=1 DEBUG_TCI=1 DEBUG_CODEC=1  twaf --run

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:

 
twaf configure build --run

T3DevKit provides the configuration option --t3dk-options for overriding the default integration modules used in the test suites (see Section 2.3.1). Example:

 
twaf configure --t3dk-options=tl_dummy       # use the dummy TL module (to disable the logging output)

If you need to clean the generated files, you can use the clean and distclean targets:

 
twaf clean         # will clean the build tree 
 
twaf distclean    # will completely remove the built tree

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.

 
twaf dist

2.3.3 Speeding up the compilation

Compilation may take a long time, especially on big projects. This section introduces two methods that can be used to speed up the compilation.

Using precompiled headers

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.

 
$ twaf configure --precomp 
$ twaf

Enabling WAF’s cache

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.

 
export WAFCACHE=/tmp/waf.cache.$UID 
$ twaf