7.2. Building Connext Micro for Common Platforms

This section describes how to compile Connext Micro, either the Platform Support Libraries (PSL) or the full source if available, for an architecture supported by RTI (see Connext Micro Platforms for more information).

For information about how to compile and link Connext Micro applications, please refer to Prepare Your Development Environment.

This section is written for developers and engineers with a background in software development. RTI recommends reading this section in order, as one subsection may refer to or assume knowledge about concepts described in a preceding subsection.

7.2.1. Setting up the build environment

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

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

  • The target is the machine that will run Connext Micro.

  • In many cases Connext Micro 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 word must describes a requirement that must be met. Failure to meet a must requirement may result in failure to compile, use, or run Connext Micro.

The word should describes a requirement that is strongly recommended to be met. A failure to meet a should recommendation may require modification to how Connext Micro is built, used, or run.

The word may is used to describe an optional feature.

7.2.1.1. The host environment

Connext Micro has been designed to be easy to build and to require few tools on the host.

The host machine must:

  • support long filenames (8.3 will not work). Connext Micro does not require a case-sensitive file-system.

  • have the necessary compiler, linkers, and build-tools installed.

The host machine should:

  • have CMake (www.cmake.org) installed. Note that it is not required to use CMake to build Connext Micro, and in some cases it may also not be recommended. As a rule of thumb, if Connext Micro can be built from the command-line, CMake is recommended.

  • be able to run bash shell scripts (Unix type systems) or BAT scripts (Windows machines).

Supported host environments are Windows (cygwin and mingw are not tested), Linux, and macOS systems.

Typical examples of host machines are:

  • a Linux PC with the GNU tools installed (make, gcc, g++, etc.).

  • a Mac computer with Xcode and the command-line tools installed.

  • a Windows computer with Microsoft Visual Studio Express edition.

  • a Linux, Mac or Windows computer with an embedded development tool-suite.

7.2.1.2. The target environment

The target compiler should:

  • be C99 compliant. Note that many non-standard compilers work, but may require additional configuration.

  • be C++98 compliant.

The remainder of this manual assumes that the target environment is one supported by RTI:

  • POSIX (Linux, macOS, QNX®)

  • Windows

7.2.2. Building the PSL

As described in Library types, Connext Micro comes with Platform Support Libraries (PSL) that are compatible with specific Platform Independent Libraries (PIL). The source code for the PSL is also available in the host package. This section describes how to build the PSL from the provided source code.

RTI provides the PSL source code because it allows the PSL to be recompiled for a specific platform configuration. This may be important in some use cases if the header files include platform-specific information that is different from the binaries provided by RTI.

There are two recommended methods to compile the PSL: by running the rtime-make script (which invokes CMake), or by invoking CMake manually. Both are described in more detail below.

CMake is the preferred tool to build Connext Micro because it simplifies configuring the Connext Micro build options and generates build files for a variety of environments. Note that CMake itself does not compile anything. CMake is used to generate build files for a number of environments, such as make, Eclipse® CDT, Xcode® and Visual Studio. Once the build-files have been generated, any of the tools mentioned can be used to build Connext Micro. This system makes it easier to support building Connext Micro in different build environments. CMake is easy to install with pre-built binaries for common environments and does not depend on external tools to build Connext Micro.

7.2.2.1. Building the PSL with rtime-make

The Connext Micro source bundle includes a bash (UNIX) and BAT (Windows) script to simplify the invocation of CMake. These scripts are a convenient way to invoke CMake with the correct options.

Note

rtime-make must be invoked from the RTIMEHOME directory.

Run the rtime-make script with the following command:

Linux

Windows

RTIMEHOME/resource/scripts/rtime-make --config Debug --target x86_64leElfgcc7.3.0-Linux4 \
                      -G "Unix Makefiles" --build

RTIMEHOME\resource\scripts\rtime-make --config Debug --target x86_64lePEvs2017-Win10 \
                  -G "Visual Studio 15 2017" --build

When the compilation has finished, the PSL is copied to the directory RTIMEHOME/lib/<target> where <target> is the argument passed to the --target <target>.

Warning

The above command will overwrite the PSL installed by RTI. To use a different output directory refer to Specifying a different output directory.

Here is an explanation of each argument in the above command:

  • --config Debug: Create Debug build. Use --config Release to create a release build.

  • --target <target>: The target for the sources to be built. Refer to Supported Platforms and Programming Languages for the architecture abbreviations of supported platforms.

  • --build Build: Build the generated project files.

To get a list of all the options, run:

rtime-make -h

To get help for a specific target, run:

rtime-make --target <target> --help

7.2.2.1.1. Specifying a different output directory

By default, rtime-make copies the compiled PSL into a directory named RTIMEHOME/lib/<target> where <target> is the argument that was passed to the --target <target> option.

To copy the compiled PSL to a different output directory, the --name <name> option can be used together with --target <target>. In this case, the PSL will be compiled using the same options as specified for --target <target>, but instead the PSLs will be copied to the directory RTIMEHOME/lib/<name>.

Note

You should use the same naming convention for --name as for --target. Connext Micro may use the directory name to determine the appropriate Platform Independent Library (PIL) for the compiled PSL.

For example, the following command will compile the PSL using the same target configuration as for x86_64leElfgcc7.3.0-Linux4, but copy the compiled PSL to RTIMEHOME/lib/x86_64leElfgcc7.3.0-mypsl

RTIMEHOME/resource/scripts/rtime-make --config Debug \
    --target x86_64leElfgcc7.3.0-Linux4 \
    --name x86_64leElfgcc7.3.0-mypsl \
    -G "Unix Makefiles" --build

7.2.2.2. Building the PSL with CMake

7.2.2.2.1. Preparing to build

RTI recommends creating a unique directory for each build configuration. A build configuration can be created to address specific architectures, compiler settings, or different Connext Micro build options.

RTI recommends assigning a descriptive name to each build configuration, using a common format. While there are no requirements to the format for functional correctness, the toolchain files in Cross-compiling Connext Micro use the <name> parameter passed to --target <name> to determine various compiler options and selections.

RTI uses the following format for the target architecture PSL:

{cpu}{compiler}{profile}-{OS}

  • {cpu}: the CPU that the library was compiled for.

  • {compiler}: the compiler used to build the library.

  • {profile}: CERT if the library was built to be Cert-compatible; otherwise empty.

  • {OS}: The operating system that the PSL was compiled for.

Some examples of target names:

  • x86_64leElfgcc7.3.0-Linux4: PSL for Connext Micro for an x64 CPU compiled using GCC 7.3.0 and running a Linux4 kernel.

  • x86_64lePEvs2017-Win10: PSL for Connext Micro for an x64 CPU compiled using VS2017 and running in Windows 10.

Files built by each build configuration will be stored under RTIMEHOME/build/[Debug | Release]/<name>. These directories are referred to as build directories or RTIMEBUILD. The structure of the RTIMEBUILD depends on the generated build files and should be regarded as an intermediate directory.

7.2.2.2.2. Creating build files from the command line

Open a terminal window in the RTIMEHOME directory and create the RTIMEBUILD directory. Change to the RTIMEBUILD directory and invoke CMake with the following arguments:

Note

This section assumes that cmake is invoked from the RTIMEHOME directory.

cmake -G <generator> -DCMAKE_BUILD_TYPE=<Debug | Release> \
      -DCMAKE_TOOLCHAIN_FILE=<toolchain file>  \
      -DCMAKE_MODULE_PATH=RTIMEHOME/resource/cmake/architectures \
      -DRTIME_TARGET_NAME=<target-name> \
      -DRTIME_TARGET=<target-name> \
      RTIMEHOME

Depending on the generator, do one of the following:

  • For IDE generators (such as Eclipse, Visual Studio, Xcode), open the generated solution/project files and build the project/solution.

  • For command-line tools (such as make, nmake, ninja), run the build-tool.

After a successful build, the output is placed in RTIMEHOME/lib/<target-name>.

The generated build files may contain different sub-projects that are specific to the tool. For example, in Xcode and Visual Studio, the following targets are available:

  • ALL_BUILD: Builds all the projects.

  • \rti_me_<name>: Builds only the specific library. Note that that dependent libraries are built first.

  • ZERO_CHECK: Runs CMake to regenerate project files in case something changed in the build input. This target does not need to be built manually.

For command-line tools, try <tool> help for a list of available targets to build. For example, if UNIX makefiles were generated:

make help

7.2.3. Building the source

Warning

This section only applies to Connext Micro source bundles (rti_connext_dds_micro-<version>-source.zip). For other bundles, refer to Building the PSL.

When you build Connext Micro from the source bundle, you have two options:

  • Build a Platform Independent Library (PIL) and a compatible Platform Support Library (PSL).

  • Build an integrated library.

The source code for the PIL, PSL, and integrated libraries are all included in the source bundle. Refer to Library types for more information on the differences between them. The following sections explain how to compile each library type.

There are two recommended methods to compile libraries: by running the rtime-make script (which invokes CMake), or by invoking CMake manually. Both are described in more detail below.

7.2.3.1. Building with rtime-make

The Connext Micro source bundle includes a bash (UNIX) and BAT (Windows) script to simplify the invocation of CMake. These scripts are a convenient way to invoke CMake with the correct options.

Run the rtime-make script with the following commands:

Linux

Windows

To build the PIL:

RTIMEHOME/resource/scripts/rtime-make --config Debug --target x86_64leElfgcc7.3.0 \
                      -G "Unix Makefiles" --build

To build the PSL using the above PIL:

RTIMEHOME/resource/scripts/rtime-make --config Debug --target x86_64leElfgcc7.3.0-Linux4 \
                      -G "Unix Makefiles" --build

To build the integrated library:

RTIMEHOME/resource/scripts/rtime-make --config Debug --target x64Linux4gcc7.3.0 \
                      -G "Unix Makefiles" --build

To build the PIL:

RTIMEHOME\resource\scripts\rtime-make --config Debug --target x86_64lePEvs2017 \
                  -G "Visual Studio 15 2017" --build

To build the PSL using the above PIL:

RTIMEHOME\resource\scripts\rtime-make --config Debug --target x86_64lePEvs2017-Win10 \
                  -G "Visual Studio 15 2017" --build

To build the integrated library:

RTIMEHOME\resource\scripts\rtime-make --config Debug --target x64Win64VS2017 \
                  -G "Visual Studio 15 2017" --build

Here is an explanation of each argument in the above commands:

  • --config Debug: Create Debug build.

  • --target <target>: The target for the sources to be built. Refer to Supported Platforms and Programming Languages for the architecture abbreviations of supported platforms.

  • --build Build: The generated project files.

To get a list of all the options, run:

rtime-make -h

To get help for a specific target, run:

rtime-make --target <target> --help

7.2.3.2. Building with CMake

7.2.3.2.1. Preparing to build

RTI recommendeds creating a unique directory for each build configuration. A build configuration can be created to address specific architectures, compiler settings, or different Connext Micro build options.

RTI recommends assigning a descriptive name to each build configuration, using a common format. While there are no requirements to the format for functional correctness, the toolchain files in Cross-compiling Connext Micro use the RTIME_TARGET_NAME variable to determine various compiler options and selections.

RTI uses the following formats for the target architecture libraries:

PIL

PSL

Integrated

{cpu}{compiler}{profile}

  • {cpu}: the CPU that the library was compiled for.

  • {compiler}: the compiler used to build the library.

  • {profile}: CERT if the library was built to be Cert-compatible; otherwise empty.

{cpu}{compiler}{profile}-{OS}

  • {cpu}: the CPU that the library was compiled for.

  • {compiler}: the compiler used to build the library.

  • {profile}: CERT if the library was built to be Cert-compatible; otherwise empty.

  • {OS}: The operating system that the PSL was compiled for.

{cpu}{OS}{compiler}{profile}

  • {cpu}: the CPU that the library was compiled for.

  • {OS}: The operating system that the integrated library was compiled for.

  • {compiler}: the compiler used to build the library.

  • {profile}: CERT if the library was built to be Cert-compatible; otherwise empty.

Some examples of target names:

  • x86_64leElfgcc7.3.0: PIL for Connext Micro for an x64 CPU, running Ubuntu 18.04 LTS compiled with gcc 7.3.0.

  • x86_64leElfgcc7.3.0-Linux4: PSL for Connext Micro for an x64 CPU, running Ubuntu 18.04 LTS compiled with gcc 7.3.0.

  • x64Linux4gcc7.3.0: Integrated library for Connext Micro for an x64 CPU, running Ubuntu 18.04 LTS compiled with gcc 7.3.0.

  • x86_64lePEvs2017: PIL for Connext Micro for an x64 CPU, running Windows 10 compiled with Visual Studio 2017.

  • x86_64lePEvs2017-Win10: PSL for Connext Micro for an x64 CPU, running Windows 10 compiled with Visual Studio 2017.

  • x64Win64VS2017: Integrated library for Connext Micro for an x64 CPU, running Windows 10 compiled with Visual Studio 2017.

Files built by each build configuration will be stored under RTIMEHOME/build/[Debug | Release]/<name>. These directories are referred to as build directories or RTIMEBUILD. The structure of the RTIMEBUILD depends on the generated build files and should be regarded as an intermediate directory.

7.2.3.2.2. Creating build files from the command line

Note

This section assumes that CMake is invoked from the RTIMEHOME directory. For out-of-source builds using CMake, refer to Building with CMake outside of source.

Open a terminal window in the RTIMEHOME directory and create the RTIMEBUILD directory. Change to the RTIMEBUILD directory and invoke CMake with the following arguments:

cmake -G <generator> -DCMAKE_BUILD_TYPE=<Debug | Release> \
      -DCMAKE_TOOLCHAIN_FILE=<toolchain file>  \
      -DCMAKE_MODULE_PATH=RTIMEHOME/resource/cmake/architectures \
      -DRTIME_TARGET_NAME=<target-name> \
      -DRTIME_TARGET=<target-name> \
      RTIMEHOME

Depending on the generator, do one of the following:

  • For IDE generators (such as Eclipse, Visual Studio, Xcode), open the generated solution/project files and build the project/solution.

  • For command-line tools (such as make, nmake, ninja), run the build-tool.

After a successful build, the output is placed in RTIMEHOME/lib/<name>.

The generated build-files may contain different sub-projects that are specific to the tool. For example, in Xcode and Visual Studio the following targets are available:

  • ALL_BUILD: Builds all the projects.

  • \rti_me_<name>: Builds only the specific library. Note that that dependent libraries are built first.

  • ZERO_CHECK: Runs CMake to regenerate project files in case something changed in the build input. This target does not need to be built manually.

For command-line tools, try <tool> help for a list of available targets to build. For example, if UNIX makefiles were generated:

make help

7.2.3.2.3. Building with CMake outside of source

Note

This option is only available with the Connext Micro source bundle.

You may need to build Connext Micro in a directory that is located outside RTIMEHOME and to install Connext Micro in a separate installation directory. In this case, do the following:

  1. Create a build directory and change the current directory to it.

  2. Invoke CMake with the following command to create build files for an integrated library:

cmake -DCMAKE_TOOLCHAIN_FILE=<RTI toolchain> \
      -DRTIME_TARGET=<target-name> \
      -DRTIME_TARGET_NAME=<target-name> \
      -DCMAKE_BUILD_TYPE=[debug | Release]  \
      <path to RTIMEHOME/CMakeLists.txt>

Alternatively, you can create build files for split libraries. This requires two commands, one for the PIL and one for the PSL.

To build the PIL:

cmake -DCMAKE_TOOLCHAIN_FILE=<RTI toolchain> \
      -DRTIME_TARGET=<target-name> \
      -DRTIME_TARGET_NAME=<target-name> \
      -DCMAKE_BUILD_TYPE=[debug | Release]  \
      <path to RTIMEHOME/CMakeLists.txt>

To build the PSL:

cmake -DCMAKE_TOOLCHAIN_FILE=<RTI toolchain> \
      -DRTIME_TARGET=<target-name> \
      -DRTIME_TARGET_NAME=<target-name> \
      -DCMAKE_BUILD_TYPE=[debug | Release]  \
      -DRTIME_PIL_PATH=<path to  RTI's PIL if compiling a PSL> \
      <path to RTIMEHOME/CMakeLists.txt>

  1. Invoke the build tool on the generated build-files:

make

  1. Install the compiled libraries using cmake --install:

cmake --install . --prefix <install path>

The last command will copy the header files and libraries to:

  • <install path>/include (header files)

  • <install path>/lib (libraries)

7.2.4. Cross-compiling Connext Micro

Cross-compiling the Connext Micro source-code uses the exact same process described in Building the source, but requires an additonal toolchain file. A toolchain file is a CMake file that describes the compiler, linker, etc., needed to build the source for the target.

To see a list of available targets, use --list:

rtime-make --list