3. Building Connext TSS

The Connext TSS libraries are shipped as source and must be built before use by a FACE application. This chapter describes how to build Connext TSS libraries for an architecture supported by RTI (refer to Supported Platforms for a list of platforms supported in this release). Note that the instructions in the following sections must be performed in order.

3.1. Prerequisites

• Connext Micro or Connext Professional must be installed (and built, if using Connext Micro) for the appropriate target architecture and FACE profile; check the Release Notes for compatibility information. For building instructions, refer to the doc folder in your Connext Micro or Connext Professional installation directory.

• Install a Java Runtime Environment (JRE). RTI Code Generator (rtiddsgen) requires a JRE to execute; RTI recommends AdoptOpenJDK version 17.0.12 (LTS) or later.

  Note

  If you installed Connext TSS with Connext Professional, a JRE is already included in your Connext Professional installation. Before you build Connext TSS, make sure that the included JRE is version 17.0.12 (LTS) or later.

• Set the JREHOME environment variable to the location of your JRE (if your JRE is not installed in your application’s path).

• Download and install CMake version 3.20 or above. Connext TSS provides and uses CMake scripts to generate the environment to build its libraries and example applications.

3.2. The Host and Target Environment

The following terminology is used to refer to the environment in which Connext TSS is built and run:

• The host is the machine that runs the software to compile and link Connext TSS.

• The target is the machine that runs Connext TSS.

• In many cases Connext TSS is built and run on the same machine. This is referred to as a self-hosted environment.

The environment is the collection of tools, OS, compiler, linker, hardware, etc., needed to build and run applications.

The following sections describe how to set up both types of environments for compiling and running Connext TSS.

3.2.1. The host environment

Before building the Connext TSS source code, you must set some environment variables to the installation paths for Connext TSS and Connext Micro or Connext Professional.

1. Make sure CMake is in the PATH environment variable.
   
   

2. Set the RTITSSHOME environment variable to point to your Connext TSS installation directory.

   For example, if Connext TSS is installed in /home/user/rti/rti_connext_tss-<version>/, set the RTITSSHOME environment variable with this command (in bash):

   export RTITSSHOME=/home/user/rti/rti_connext_tss-<version>
   

3. Set the RTIMEHOME or NDDSHOME environment variable to point to your Connext Micro or Connext Professional installation, respectively.

   For example, if Connext Micro is installed in /opt/local/rti/rti_connext_dds_micro-<version>, then set RTIMEHOME with this command (in bash):

   export RTIMEHOME=/opt/local/rti/rti_connext_dds_micro-<version>
   

   Note

   For Pro TPM builds, NDDSHOME must point to a non-FACE_GP Connext Professional library.

Note

The Connext Micro libraries must be conformant to the FACE profile of the Connext TSS libraries being built. For help configuring and building Connext Micro for FACE, refer to the user’s manual in the doc folder of your Connext Micro installation directory.

3.2.2. The target environment

Connext TSS requires a CMake architecture file configured for the target environment where it will run.

Note

For a list of demonstrated architectures for Connext TSS, refer to Supported Platforms.

The RTITSSHOME/resource folder includes CMake architecture files for the following platforms:

• x64Linux6gcc13.3.0FACE_GP

• x64Linux6gcc13.3.0FACE_SB

• x64Win64VS2022FACE_GP

• x86Lynx1782024.09.0.APEXgcc11.3.0FACE_SB

• x64Vx23.09llvm16.0_rtpFACE_GP

Set the environment variable RTITSSARCH to the selected architecture. For example:

export RTITSSARCH=x64Linux6gcc13.3.0FACE_GP

If compiling Connext TSS for the SafetyBase FACE Profile for Connext Micro, you may need to set the RTIMEARCH environment variable and append the CERT suffix to the architecture name. For example:

export RTITSSARCH=x64Linux6gcc13.3.0FACE_SB
export RTIMEARCH=x64Linux4gcc7.3.0CERT

If compiling Connext TSS for the General Purpose FACE Profile for Connext Professional, you may need to set the NDDSARCH environment variable and append the FACE_GP suffix to the architecture name. For example:

export RTITSSARCH=x64Linux6gcc13.3.0FACE_GP
export NDDSARCH=x64Linux4gcc7.3.0FACE_GP

Note

To use a different architecture from those listed above, refer to Porting Connext TSS.

3.3. Building the Libraries

After setting up your host and target environments, use CMake to create an out-of-source build of Connext TSS.

1. Create a build directory:

   cd ${RTITSSHOME}
   mkdir build
   

2. Run CMake with the required definitions, as shown in the following command:

   cd build
   cmake -DRTI_CONNEXT_TYPE=<micro|pro> -DRTI_TSS_ENABLE_FACE_COMPLIANCE=<your_face_profile> ../
   

   The CMake definitions in the above command are required to successfully build Connext TSS.

   • -DRTI_CONNEXT_TYPE sets Connext Micro (micro) or Connext Professional (pro) as the RTI product being used.

   • -DRTI_TSS_ENABLE_FACE_COMPLIANCE sets the FACE OSS (Operating System Segment) profile Connext TSS will conform to:

     • None (default)

     • GeneralPurpose

     • SafetyExtended

     • SafetyBase

     • Security

   Note

   While RTI_TSS_ENABLE_FACE_COMPLIANCE can be set to any FACE OSS profile, check the Supported Platforms for information on which profiles are supported per platform. For more information about FACE profiles, see the FACE Technical Standard.

3. Build the Connext TSS libraries:

   cmake --build .
   

Alternatively, you can use the CMake GUI (cmake-gui) instead of the command line to complete the build.

3.3.1. Optional CMake definitions

The following definitions can be used to customize your build.

Definition	Description	Options
-DCMAKE_BUILD_TYPE	Sets the type of library or executable built.	“Release” (default) “Debug”
-DBUILD_TSS	Enables or disables building the Transport Service/Type Abstraction library.	“ON” (default) “OFF”
-DBUILD_STRINGS_SEQUENCES	Enables or disables building the RTI strings and sequences library.	“ON” (default) “OFF”
-DBUILD_SERIALIZATION [1]	Enables or disables building the FACE-to-CDR (Common Data Representation) serialization library.	“ON” (default) “OFF”
-DBUILD_MICRO_TPM	Enables or disables building the Connext Micro TPM library.	“ON” (default) “OFF”
-DBUILD_PRO_TPM	Enables or disables building the Connext Professional TPM library.	“ON” “OFF” (default)
-DLANGUAGE [2] [3]	Sets the language to build the enabled libraries for C or C++.	“c” (default) “cpp”
BUILD_SHARED_LIBS [4]	Defines whether libraries are built as dynamic (on) or static (off).	“ON” “OFF” (default)
-DLIFECYCLE_CLASS_EXT	Enables or disables sequence element lifecycle operations for complex types. See Sequence Element Lifecycle Operations.	“ON” (default) “OFF”

[1]

Serialization libraries are only used with Connext Micro. CMake will not build these libraries if -DBUILD_PRO_TPM is enabled.

[2]

RTI’s C++ API is a wrapper around the C API. When C++ is selected, both C and C++ libraries are built.

[3]

Connext TSS does not support C++ libraries on Connext Professional.

[4]

This Connext TSS release does not support dynamic libraries on Windows systems or for SafetyBase profiles.

3.3.2. Compile-time configuration

Connext TSS provides a set of compile-time parameters that control resource limits and buffer sizes. These parameters are defined with default values in code/RTI_Connext_TSS_Config.h. Each parameter is wrapped in an #ifndef guard, so it can be overridden by passing -D<PARAMETER>=<value> to CMake.

For example, to set the maximum number of connections per Base instance to 100:

cmake -DMAX_CONNECTIONS_PER_BASE_INSTANCE=100 ...

The following parameters can be overridden through CMake:

Parameter	Description	Default
STRINGS_BOUND	Default bound for unbounded strings.	255
SEQUENCES_BOUND	Default bound for unbounded sequences.	4096
MAX_CONNECTIONS_PER_BASE_INSTANCE	Maximum number of connections that a Base instance can own.	10000
MAX_TPM_REFERENCES_PER_BASE_INSTANCE	Maximum number of TPM references that a Base instance can hold.	50
MAX_CHANNELS_PER_CONNECTION	Maximum number of channels that a connection can contain.	10000
MAX_CONFIGURATION_STRING_LENGTH	Maximum length of the TSS configuration string. Update based on the size of your configuration.	1024
LOG_FILE_NAME_MAX_LENGTH	Maximum length of the log file name when logging is enabled.	256

Note

When using Connext Micro, data larger than the transport MTU is only fragmented for BEST_EFFORT reliability. RELIABLE communication does not support fragmentation and over-MTU samples are discarded by Micro. For this reason, keep effective serialized sample sizes within MTU by using bounded types and appropriately sizing STRINGS_BOUND and SEQUENCES_BOUND.

The following additional parameters are defined in RTI_Connext_TSS_Config.h but are not passed through CMake. To override them, define them in your compiler flags or edit the header directly:

Parameter	Description	Default
FACE_MAX_CHANNELS_PER_MANAGER	Default maximum number of channels per channel manager.	50
MAX_CALLBACKS_PER_CONNECTION	Maximum number of callbacks per connection.	32
FACE_DEFAULT_BUFFER_SIZE	Buffer size for general-purpose operations (log messages, temporary buffers, etc.).	256
FACE_DEFAULT_MESSAGE_SIZE	Default message size for DDS message buffers.	1024
FACE_LARGE_BUFFER_SIZE	Large buffer size for configuration strings and bulk data.	8192
FACE_DEFAULT_DOMAIN_ID	Default DDS domain ID when none is configured.	0
FACE_DEFAULT_TIMEOUT_MS	Default timeout in milliseconds.	1000
FACE_RECEIVE_WAIT_SLICE_NS	Length in nanoseconds of one bounded wait slice. A blocking Receive_Message composes its caller’s timeout from slices of this length rather than handing the whole timeout to the transport, so it can notice a closing connection between slices. The timeout a caller observes is unchanged; what this bounds is how long a teardown waits for a receive parked in the transport. Message latency is unaffected.	100000000
FACE_LOG_BUFFER_SIZE	Size of internal log message buffer.	4096
FACE_DEFAULT_HASH_TABLE_SIZE	Initial bucket count for hash tables.	128

The following hash table tuning parameters control the performance characteristics of internal hash tables used for connection, channel, and TPM lookups. Adjusting these values can trade memory usage for lookup speed:

Parameter	Description	Default
FACE_MIN_HASH_TABLE_SIZE	Minimum bucket count for hash tables. Tables will not shrink below this size.	64
HASH_TABLE_LOAD_FACTOR_PERCENT	Load factor threshold (as a percentage). When the ratio of entries to buckets exceeds this value, the table is resized. Lower values reduce collisions at the cost of more memory.	75
HASH_TABLE_GROWTH_FACTOR	Multiplier applied to the bucket count when the table is resized. A factor of 2 doubles the table on each resize.	2
HASH_MAX_ITERATIONS	Maximum probe iterations for a single hash operation. Prevents unbounded search times in degenerate cases.	100
DJB2_HASH_INIT	Initial seed value for the DJB2 hash algorithm.	5381
DJB2_HASH_MULT	Multiplier used in the DJB2 hash calculation (hash = hash * mult + c).	33
FNV_OFFSET_BASIS	Offset basis for the FNV-1a hash algorithm.	0x811c9dc5
FNV_PRIME	Prime multiplier for the FNV-1a hash algorithm.	0x01000193

Note

For SafetyBase (and stricter) profiles, dynamic memory allocation is disabled. In these profiles the resource limits set by these parameters determine the fixed, pre-allocated capacity of the system. Choosing values appropriate for your deployment is especially important.

3.4. Verifying Built Libraries

A successful build will create multiple libraries depending on which CMake flags were set. If you build C++ libraries, both C and C++ libraries will be present. All created libraries should be located in <RTITSSHOME>/lib/<tss_arch>/<library_name>:

• librti_tssc / librti_tsscpp: Type Abstraction library.

• librti_tpm_micro_c / librti_tpm_micro_cpp: Transport Protocol Module library based on Connext Micro.

• librti_tpm_pro_c: Transport Protocol Module library based on Connext Professional.

  Note

  Connext TSS on Connext Professional does not support RTI Connext TSS C++ API.

• librti_tss_serialization_c / librti_tss_serialization_cpp: FACE-to-CDR serialization support library.

  Note

  • Serialization support libraries are only used with Connext Micro.

  • The serialization libraries are built by default (-DBUILD_SERIALIZATION=ON), but they are not automatically linked by application build scripts (including the provided example CMakeLists.txt).

  • If your application uses FACE-to-CDR serialization, you must explicitly add librti_tss_serialization_c (C API) or librti_tss_serialization_cpp (C++ API) to the target_link_libraries call in your application’s CMakeLists.txt.

  • If serialization is not needed, you can disable building the libraries by passing -DBUILD_SERIALIZATION=OFF to CMake when building Connext TSS.

• librti_tss_strings_sequencesc: Strings and sequences library.

Note

Static versions of the libraries have the letter z postpended to the filename. Debug versions of the libraries have the letter d postpended to the filename. For example, librti_tsscz is the release version of the static C API Type Abstraction library, and librti_tsscdz is the debug version of the static C API Type Abstraction library. Therefore, you can build both release and debug versions of the libraries in the same build directory.