Prosody Guide - how to build applications to use Prosody

Applications are built from source files that include TiNG library header files, and the resulting objects need to be linked against a suitable TiNG library. Normally either a dynamically or a statically linkable version may be used. However in some circumstances it may be necessary to link the application against just a selection of individual TiNG library object files. This flexibilty can be useful when dealing with unusual build environments or other special circumstances. For QNX this is the only option currently available.

Prosody comes with various programs and the necessary support files to build them, so you can also look at them to see how they are built. The appropriate Makefiles are provided and, for Microsoft Windows, Visual Studio Project files are also provided.

Use of TiNG header files

In your source code which calls Prosody APIs, you need to include the necessary declarations. For example, for the Speech processing API you would use: 

	#include "smbesp.h"

The file required for each API is specified in the introduction to that API's reference manual.

You also need to add the Prosody include directory to the list of include directories for the compiler to search. For a command-line compiler, this is normally done with a "-Idirectory" option, so if the Prosody package is in "D:/Aculab/TiNG", then the option might be -I D:/Aculab/TiNG/include.

Use of header files associated with the TiNG library require a pre-processor symbol to be defined indicating target system type:

SymbolValueMeaning
TiNGTYPE_LINUXanything Use only on Linux Indicates that the component should be built for Linux
TiNGTYPE_QNXanything Use only on QNX Indicates that the component should be built for QNX
TiNGTYPE_WINNTanything Use only on Microsoft Windows Indicates that the component should be built for Windows

If, in source files including TiNG headers, the headers for call control, resource management or switching are included prior to those TiNG headers, the above pre-processor symbols will normally be defined for you automatically (by virtue of definitions in acu_type.h header). For other source files using TiNG headers you must make the compiler define the above pre-processor symbols. For a command-line compiler, this is normally done with a "-Dsymbol=value" option.

Don't forget any other settings which may be required. These typically include a setting to indicate the the program is multithreaded (for example, to use POSIX threads you need to define _REENTRANT). All applications using the TiNG library are multithreaded. Remember when building applications which use the Aculab call or switch drivers that you also need to define any symbols they require. See their documentation for full details.

Linking an application with the TiNG library

Linking an application with dynamically linked TiNG library

The required library file may be found in a target dependant subdirectory of ACULAB_ROOT.

Note for Linux - applications are typically linked with an rpath option so the TiNG library shared object may be located.

Linux RDTSC - Normally the TiNG library will use the RDTSC as a source of clock ticks. In some environments this has been found not to be a reliable source of timing information. Defining the environment variable TiNG_CLOCK_MONOTONIC to be non-zero will make the library use the system call clock_gettime with parameter CLOCK_MONOTONIC instead.

Like other dynamically linked libraries for Windows, the corresponding TiNG library DLL must be present in the application's PATH environment. Note also that Windows applications dynamically linked against TiNG library must be compiled with pre-processor symbol TiNG_USE_DLL defined.

Linking an application with statically linked TiNG library

The required library file may be found in a target dependant subdirectory of ACULAB_ROOT.

Statically linked library files are not available for Windows.

Linking an application with individual TiNG library object files

Both Prosody X and Prosody S applications need to be linked with TiNGcore and prosody_x object files from the target dependant subdirectory of the TiNG directory apilib.

Further object files may be required if high level library calls are used such as those from rtcplib, v8lib or smhlib.

If the instructions previously described in Building software components have been followed you should find that these object files have been built during installation.

Note for Windows - the pre-processor symbol TiNG_USE_DLL must NOT be defined when compiling source files that will be liked against individual TiNG library object files. Some non-TiNG header files will implicitly define this symbol unless the pre-processor symbol ACU_DONT_USE_TING_DLL is defined during compilation.

Note that if an application is linked with individual TiNG library object files then the calls sm_open_prosody_x() or sm_open_prosody_s_v3() must be used when opening the card.

Visual Studio

Under Microsoft Windows if you want to use Visual Studio, please see the separate document Prosody guide: building applications with Visual Studio for detailed instructions on how to configure projects.

Building in trace

Finally, when debugging your application, you may find the application tracing facility of Prosody to be useful. Consequently, it is highly adviseable to build in an appropriate mechanism for enabling this trace.