.. include:: vars.rst

.. _section-build:

********************************************************************************
Build
********************************************************************************

The |RTI_TSS| libraries are shipped as source and must be built before use
by a FACE application.


Prerequisites
^^^^^^^^^^^^^
#. Set a ``JREHOME`` environment variable to the location of the JRE
   included with |CONNEXT| *Professional* or *Micro*.
#. |CONNEXT| *Professional* and/or *Micro* must be installed and built 
   for the target architecture and FACE profile.

.. _configure_build_environment:

Configure build environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^

In preparation for a build:

1. Download and install `CMake <https://cmake.org>`_.

  |RTI_TSS| provides and uses CMake scripts to generate the environment to
  build its libraries and example applications.

2. Set an *RTITSSHOME* environment variable to point to your |TSS| installation directory.

   For example, if |TSS| is installed in
   ``/home/user/rti/rti_connext_tss-3.1.1/``, then set *RTITSSHOME* (in bash) with
   this command:

  .. code-block:: bash

    export RTITSSHOME=/home/user/rti/rti_connext_tss-3.1.1

3. If building for |CONNEXT| *Professional*, set an *NDDSHOME*
   environment variable to point to your |CONNEXT| installation.

   For example, if |CONNEXT| is installed in
   ``/opt/local/rti/rti_connext_dds-6.1.1``, then set *NDDSHOME*
   (in bash) with this command:

  .. code-block:: bash

    export NDDSHOME=/opt/local/rti/rti_connext_dds-6.1.1


4. If building for |CONNEXT_MICRO|, set an *RTIMEHOME* environment
   variable to point to your |CONNEXT_MICRO| installation.

   For example, if |CONNEXT_MICRO| is installed in
   ``/opt/local/rti/rti_connext_micro.2.4.13.1``, then set *RTIMEHOME*
   (in bash) with this command:

  .. code-block:: bash

    export RTIMEHOME=/opt/local/rti/rti_connext_micro.2.4.13.4

.. note::

  The |CONNEXT| *Professional* and |CONNEXT_MICRO| libraries must be 
  conformant to the FACE profile of the |TSS| libraries being built. 
  See :ref:`ref-connext-doc` for help with configuring and building Connext for FACE.



Set architecture
^^^^^^^^^^^^^^^^

The architecture identifies the platform on which to run |RTI_TSS|.

CMake architecture files are provided for the following:

  * armv8Vx7SR0660llvm10.0.1.cortex-a53.cmake      
  * armv8Vx7SR0660llvm10.0.1.cortex-a53_rtp.cmake  
  * i86Linux2.6gcc4.4.5.cmake                      
  * i86Linux3gcc4.8.2.cmake                                                  
  * pentium64Vx7.0gcc4.8.1_rtp.cmake               
  * ppce6500Deos653-10.3.1gcc7.3.0.cmake           
  * ppce6500Deos653-10.3.1gcc7.3.0FACE_SB.cmake    
  * ppce6500Vx653-3.0.1.1gcc4.3.3.cmake            
  * ppce6500Vx653-3.0.1.1gcc4.3.3FACE_SB.cmake     
  * x64Linux3gcc4.8.2.cmake
  * x64Linux3gcc5.4.0.cmake
  * x64Linux4gcc7.3.0.cmake
  * x64Linux4gcc7.3.0FACE_GP.cmake
  * x64Linux4gcc7.3.0FACE_SB.cmake
  * x64Linux4gcc8.5.0.cmake
  * x64Linux4gcc8.5.0FACE_GP.cmake

For other architectures, follow the Porting guide
(:numref:`section-porting`) to add a new architecture.

Once an architecture is chosen, set an environment variable
*RTITSSARCH* to the architecture name:

  .. code-block:: bash

    export RTITSSARCH=x64Linux3gcc4.8.2

If compiling for the SafetyBase FACE Profile, you will need to
append a *FACE_SB* suffix to the architecture name:

  .. code-block:: bash

    export RTITSSARCH=x64Linux3gcc4.8.2FACE_SB

.. _build-cmakeCommand-label:

Build libraries
^^^^^^^^^^^^^^^

This section describes how to do an out-of-source build of |RTI_TSS|
using CMake.

- Create a build directory ::

    cd ${RTITSSHOME}
    mkdir build

- Run CMake, with the necessary definitions as described below ::

    cd build
    cmake -DRTI_CONNEXT_TYPE=<your_connext_type> -DRTI_TSS_ENABLE_FACE_COMPLIANCE=<your_face_profile> -DCMAKE_BUILD_TYPE=<your_build_type> ../


  RTI_CONNEXT_TYPE sets the Connext DDS product being used:
    - "*micro*" (**default**)
    - "*pro*"

  RTI_TSS_ENABLE_FACE_COMPLIANCE sets the FACE profile with which
  |RTI_TSS| is being built to conform:

    - "*None*" (**default**)
    - "*GeneralPurpose*"
    - "*SafetyExtended*"
    - "*SafetyBase*"
    - "*Security*"

  .. note::

    While RTI_TSS_ENABLE_FACE_COMPLIANCE can be set to any FACE OSS profile, 
    this release of |RTI_TSS| supports up to the SafetyBase profile with 
    Connext DDS Micro 2.4.13.4, and no profile with Connext DDS Pro 6.1.1.

  .. note::

    To enable long double types, the ``RTI_TSS_ENABLE_LONG_DOUBLE`` CMake
    variable must be set to True. This will define RTI_CDR_SIZEOF_LONG_DOUBLE
    or OSAPI_ENABLE_LONG_DOUBLE, needed by Connext DDS Pro or Connext DDS Micro
    respectively.

    .. code-block:: bash

      -DRTI_TSS_ENABLE_LONG_DOUBLE=TRUE

  CMAKE_BUILD_TYPE sets the type of library or executable built:

    - "*Release*" (**default**)
    - "*Debug*"


  Alternatively, the CMake GUI (`cmake-gui`) can be used instead of the command line.



- Build the |RTI_TSS| libraries ::

    cmake --build .



Verify build
^^^^^^^^^^^^

A successful build will result in one (statically linked) library:
*rti_tsscpp*.

The library for RTI Connext DDS Pro will be built as
``${RTITSSHOME}/lib/${RTITSSARCH}/pro/librti_tsscppz.a``.

The library for RTI Connext DDS Micro will be built as
``${RTITSSHOME}/lib/${RTITSSARCH}/micro/librti_tsscppz.a``.

The debug library name will have a 'd' suffix
(e.g. ``librti_tsscppzd.a``).

.. _3rd_party_strings_sequences:

Using Third-Party Strings and Sequences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To use other implementations of FACE Sequence and String classes than RTI's implementation,
create two new folders: ``include/third_party`` and ``src/third_party``.

Then, place inside ``include/third_party`` your ``String.hpp`` and ``Sequence.hpp``
header files along with any header files needed by them. At ``src/third_party``,
place all the C and C++ source files needed.

.. note:: 

  ``include/third_party`` contains example ``String.hpp`` and ``Sequence.hpp`` files. These files are required to build the libraries. If you wish to use your own or third party versions of these files, replace these files with the appropriate ``.hpp`` files.

Finally, compile with the ``RTI_USE_EXTERNAL_STR_SEQ`` CMake variable set to True
(``-DRTI_USE_EXTERNAL_STR_SEQ=TRUE``).