.. _section-building-source: Building |me_h| for Common Platforms ==================================== This section describes how to compile |me|, either the Platform Support Libraries (PSL) or the full source if available, for an architecture supported by RTI (see :ref:`section-platforms` for more information). .. Please refer to :ref:`porting` for documentation on how to port |me| to an *unsupported* architecture. For information about how to compile and link |me| applications, please refer to :ref:`section-prepare-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. .. _section-set-up-build-environment: Setting up the build environment -------------------------------- The following terminology is used to refer to the environment in which |me| is built and run: - The *host* is the machine that runs the software to compile and link |me|. - The *target* is the machine that will run |me|. - In many cases |me| 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 |me|. 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 |me| is built, used, or run. The word *may* is used to describe an optional feature. The host environment .................... |me| 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). |me| 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 |me|, and in some cases it may also not be recommended. As a rule of thumb, if |me| can be built from the command-line, `CMake `_ is recommended. - be able to run bash shell scripts (Linux and macOS systems) or BAT scripts (Windows systems). 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. 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 .. _`psl_compiling`: Building the PSL ---------------- As described in :ref:`section-libraries`, |me| 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 |me| because it simplifies configuring the |me| 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 |me|. This system makes it easier to support building |me| 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 |me|. Building the PSL with rtime-make ................................ The |me| source bundle includes a bash (on Linux and macOS systems) and BAT (on Windows systems) 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: .. tabs:: .. group-tab:: Linux .. code-block:: console RTIMEHOME/resource/scripts/rtime-make --config Debug --target x86_64leElfgcc7.3.0-Linux4 \ -G "Unix Makefiles" --build .. group-tab:: Windows .. code-block:: console RTIMEHOME\resource\scripts\rtime-make --config Debug --target x86_64lePEvs2017-Win10 \ -G "Visual Studio 15 2017" --build .. note:: When building for Windows systems on any architecture other than x86, you must add the ``-A`` option for your architecture. For example: .. code-block:: none -A x64 When the compilation has finished, the PSL is copied to the directory ``RTIMEHOME/lib/`` where ```` is the argument passed to the ``--target ``. .. warning:: The above command will overwrite the PSL installed by RTI. To use a different output directory refer to :ref:`target_name`. 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 ``: The target for the sources to be built. Refer to :ref:`rl_supported` for the architecture abbreviations of supported platforms. - ``--build Build``: Build the generated project files. To get a list of all the options, run: .. code-block:: console rtime-make -h To get help for a specific target, run: .. code-block:: console rtime-make --target --help .. _`target_name`: Specifying a different output directory ''''''''''''''''''''''''''''''''''''''' By default, rtime-make copies the compiled PSL into a directory named ``RTIMEHOME/lib/`` where ```` is the argument that was passed to the ``--target `` option. To copy the compiled PSL to a different output directory, the ``--name `` option can be used together with ``--target ``. In this case, the PSL will be compiled using the same options as specified for ``--target ``, but instead the PSLs will be copied to the directory ``RTIMEHOME/lib/``. .. note:: You should use the same naming convention for ``--name`` as for ``--target``. |me| 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`` .. code-block:: console RTIMEHOME/resource/scripts/rtime-make --config Debug \ --target x86_64leElfgcc7.3.0-Linux4 \ --name x86_64leElfgcc7.3.0-mypsl \ -G "Unix Makefiles" --build Building the PSL with CMake ........................... .. _`prepare-psl`: 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 |me| 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 :ref:`xbuild` use the ```` parameter passed to ``--target `` to determine various compiler options and selections. RTI uses the following format for the target architecture PSL: .. code-block:: none {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 |me| for an x64 CPU compiled using GCC 7.3.0 and running a Linux4 kernel. - ``x86_64lePEvs2017-Win10``: PSL for |me| 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]/``. 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. 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. .. code-block:: console cmake -G -DCMAKE_BUILD_TYPE= \ -DCMAKE_TOOLCHAIN_FILE= \ -DCMAKE_MODULE_PATH=RTIMEHOME/resource/cmake/architectures \ -DRTIME_TARGET_NAME= \ -DRTIME_TARGET= \ 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/``. 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_``: 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 `` help`` for a list of available targets to build. For example, if makefiles were generated:: make help .. _`source_compiling`: Building the source ------------------- .. warning:: This section only applies to |me| source bundles (``rti_connext_dds_micro--source.zip``). For other bundles, refer to :ref:`psl_compiling`. When you build |me| 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 :ref:`section-libraries` 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. Building with rtime-make ........................ The |me| source bundle includes a bash (on Linux and macOS systems) and BAT (on Windows systems) 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: .. tabs:: .. group-tab:: Linux To build the PIL: .. code-block:: console RTIMEHOME/resource/scripts/rtime-make --config Debug --target x86_64leElfgcc7.3.0 \ -G "Unix Makefiles" --build To build the PSL using the above PIL: .. code-block:: console RTIMEHOME/resource/scripts/rtime-make --config Debug --target x86_64leElfgcc7.3.0-Linux4 \ -G "Unix Makefiles" --build To build the integrated library: .. code-block:: console RTIMEHOME/resource/scripts/rtime-make --config Debug --target x64Linux4gcc7.3.0 \ -G "Unix Makefiles" --build .. group-tab:: Windows To build the PIL: .. code-block:: console RTIMEHOME\resource\scripts\rtime-make --config Debug --target x86_64lePEvs2017 \ -G "Visual Studio 15 2017" --build To build the PSL using the above PIL: .. code-block:: console RTIMEHOME\resource\scripts\rtime-make --config Debug --target x86_64lePEvs2017-Win10 \ -G "Visual Studio 15 2017" --build To build the integrated library: .. code-block:: console 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 ``: The target for the sources to be built. Refer to :ref:`rl_supported` for the architecture abbreviations of supported platforms. - ``--build Build``: The generated project files. To get a list of all the options, run: .. code-block:: console rtime-make -h To get help for a specific target, run: .. code-block:: console rtime-make --target --help Building with CMake ................... .. _`prepare`: 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 |me| 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 :ref:`xbuild` use the **RTIME_TARGET_NAME** variable to determine various compiler options and selections. RTI uses the following formats for the target architecture libraries: .. tabs:: .. group-tab:: PIL .. code-block:: none {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. .. group-tab:: PSL .. code-block:: none {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. .. group-tab:: Integrated .. code-block:: none {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 an x64 CPU, compiled with gcc 7.3.0. - ``x86_64leElfgcc7.3.0-Linux4``: PSL for an x64 CPU, running Ubuntu 18.04 LTS, compiled with gcc 7.3.0. - ``x64Linux4gcc7.3.0``: Integrated library for an x64 CPU, running Ubuntu 18.04 LTS, compiled with gcc 7.3.0. - ``x86_64lePEvs2017``: PIL for an x64 CPU, compiled with Visual Studio 2017. - ``x86_64lePEvs2017-Win10``: PSL for an x64 CPU, running Windows 10, compiled with Visual Studio 2017. - ``x64Win64VS2017``: Integrated library 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]/``. 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. 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 :ref:`out_of_source_cmake`. 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: .. code-block:: console cmake -G -DCMAKE_BUILD_TYPE= \ -DCMAKE_TOOLCHAIN_FILE= \ -DCMAKE_MODULE_PATH=RTIMEHOME/resource/cmake/architectures \ -DRTIME_TARGET_NAME= \ -DRTIME_TARGET= \ 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/``. 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_``: 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 `` help`` for a list of available targets to build. For example, if makefiles were generated:: make help .. _`out_of_source_cmake`: Building with CMake outside of source ''''''''''''''''''''''''''''''''''''' .. note:: This option is only available with the |me| source bundle. You may need to build |me| in a directory that is located outside ``RTIMEHOME`` and to install |me| 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: .. code-block:: console cmake -DCMAKE_TOOLCHAIN_FILE= \ -DRTIME_TARGET= \ -DRTIME_TARGET_NAME= \ -DCMAKE_BUILD_TYPE=[debug | Release] \ 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: .. code-block:: console cmake -DCMAKE_TOOLCHAIN_FILE= \ -DRTIME_TARGET= \ -DRTIME_TARGET_NAME= \ -DCMAKE_BUILD_TYPE=[debug | Release] \ To build the PSL: .. code-block:: console cmake -DCMAKE_TOOLCHAIN_FILE= \ -DRTIME_TARGET= \ -DRTIME_TARGET_NAME= \ -DCMAKE_BUILD_TYPE=[debug | Release] \ -DRTIME_PIL_PATH= \ 3. Invoke the build tool on the generated build-files: .. code-block:: console make 4. Install the compiled libraries using ``cmake --install``: .. code-block:: console cmake --install . --prefix The last command will copy the header files and libraries to: - ``/include`` (header files) - ``/lib`` (libraries) .. _`xbuild`: Cross-compiling |me_h| ---------------------- Cross-compiling the |me| source-code uses the exact same process described in :ref:`source_compiling`, 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``: .. code-block:: console rtime-make --list