.. 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
.............

#. |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.2/``, then set *RTITSSHOME* (in bash) with
   this command:

  .. code-block:: bash

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

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.4``, 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-a53FACE_GP.cmake
  * armv8Vx7SR0660llvm10.0.1.cortex-a53_rtpFACE_GP.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 :ref:`section-porting` guide
to add a new architecture.

Once an architecture is chosen, set environment variables
*RTITSSARCH* and *NDDSARCH* to the architecture name:

  .. code-block:: bash

    export RTITSSARCH=x64Linux4gcc7.3.0
    export NDDSARCH=x64Linux4gcc7.3.0

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

  .. code-block:: bash

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

.. _build-cmakeCommand-label:



Build libraries
...............

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

1. Create a build directory:

   .. code-block:: bash

     cd ${RTITSSHOME}
     mkdir build

2. Run CMake, with the necessary definitions as described below 

   .. code-block:: bash

     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| 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 the SafetyBase profile with |CONNEXT_MICRO|
    2.4.13.4, and GeneralPurpose profile with |CONNEXT| *Professional* 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| *Professional* or
    |CONNEXT_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*"

  ``RTI_LOG_VERBOSITY`` sets the level of logging verbosity:

    - "*Silent*"
    - "*Error*"
    - "*Warning*" (**default**)
    - "*Info*"
    - "*Debug*"

  ``RTI_TSS_LOG_FILE_TYPE`` sets the logging output type:

    - "*none*"
    - "*stdout*" (**default**)
    - "*file*"
    - "*timestamp*"

  .. note::

    Logging is enabled by default for None and GeneralPurpose compliance level.
    It will be silented when built for SafetyBase. When RTI_LOG_VERBOSITY is set,
    LOG_VERBOSITY will be defined accordingly.
    ``RTI_TSS_LOG_FILE_TYPE`` can be used to configure how to display logging
    messages. When ``RTI_TSS_LOG_FILE_TYPE`` is set to 'file', ``RTI_TSS_LOG_FILE_NAME``
    can be used to define the name of the log file. It is "rtifacetss.log" by
    default.

    To enable logging at verbosity level of 'Info' and display the message on
    stdout, add these flag to the |RTI_TSS| build command mention previously.
    ``-DRTI_TSS_LOG_FILE_TYPE=stdout`` is optional since it is stdout by default.

    .. code-block:: bash

      -DRTI_LOG_VERBOSITY=Info -DRTI_TSS_LOG_FILE_TYPE=stdout

    To enable logging at verbosity level of 'Debug' and store the log messages
    in a file called "logMessages.log",

    .. code-block:: bash

      -DRTI_LOG_VERBOSITY=Debug -DRTI_TSS_LOG_FILE_TYPE=file -DRTI_TSS_LOG_FILE_NAME=logMessages.log

    The log file can be found in the application's build directory.

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



3. Build the |RTI_TSS| libraries:

   .. code-block:: bash

     cmake --build .



Verify build
............

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

The library for RTI |CONNEXT| *Professional* will be built as
``${RTITSSHOME}/lib/${RTITSSARCH}/pro/librti_tsscppz.a``.

The library for RTI |CONNEXT_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``).