Building the |rti_me_h| Source
==============================
Introduction
------------
|rti_me| has been engineered for reasonable portability to common platforms and
environments, such as Darwin, iOS, Linux, and Windows. This user manual
explains how to build the |me| source-code. The focus of this document is
building |me| for an architecture supported by RTI. Please refer to
:ref:`porting` for documentation on how to
*port* |me| to an *unsupported* architecture.
This manual is written for developers and engineers with a background in
software development. It is recommended to read the document in order, as
one section may refer to or assume knowledge about concepts described in a
preceding section.
The Host and Target 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 runs |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
....................
|rti_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 |rti_me| 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).
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
......................
|me| has been designed to run on a wide variety of targets. For example,
|me| can be ported to run with no OS, an RTOS, GNU libc or a non-standard
C library etc. This section only lists the minimum requirements. Please refer to
:ref:`porting` for how to port |me|.
The target machine must:
- support 8, 16, and 32-bit signed and unsigned integer. Note that a
16bit CPU (or even 8 bit) is supported as long as the listed types are
supported.
- |me| supports 64 bit CPUs, and it does not use any native 64 bit
quantities internally.
The target compiler should:
- have a C compiler that is C99 compliant. Note that many non-standard
compilers work, but may require additional configuration.
- have a C++ compiler that is C++98 compliant.
The remainder of this manual assumes that the target environment is one
supported by RTI:
- POSIX (Linux, Darwin, QNX, VOS, iOS, Android).
- VxWorks 6.9 or later.
- Windows.
- QNX.
Overview of RTI Connext DDS Micro Source Bundle
-----------------------------------------------
The |me| source is available from the
`RTI support portal `_.
If you do not have access, please contact `RTI Support `_.
The source-code is exactly the same as developed and
tested by RTI. No filtering or modifications are performed, except for
line-ending conversion for the Windows source bundle.
The source-bundle is a a directory called src/ under |rti_me| installation.
::
RTIMEHOME--+-- CmakeLists.txt
|
+-- build -- cmake --+-- Debug --+-- --
| |
| |
| +-- Release --+-- --
+-- doc --
|
+-- example
|
+-- include
|
+-- lib +-- --
|
+-- resource --+-- cmake
| |
| +-- scripts
|
+-- rtiddsgen
|
+-- rtiddsmag
|
+-- src
In this manual, ``RTIMEHOME`` refers to the root directory where RTI archives are
extracted and installed. The only difference between the Unix and Windows
source bundles is the line endings.
For the remainder of this document ``RTIMEROOT`` refers to both source/unix and
source/windows. Only when necessary will it be pointed out whether
it is the windows or Unix source that it is being referred too.
Directory Structure
...................
The recommended directory structure is described below and *should*
be used (1) because:
- the source bundle includes a helper script to run `CMake `_ that
expects this directory structure.
- this directory structure supports multiple architectures.
- this directory structure mirrors the structure shipped by RTI. To link
against built libraries instead of those shipped by RTI, set ``RTIMEHOME`` to
``RTIMEROOT`` (2).
NOTE 1: This applies to builds using `CMake `_. To build in a
custom environment, please refer to `Custom Build Environments`_.
NOTE 2: The path to an installation of *rtiddsgen*, likely from a
bundle shipped by RTI, will also have to be specified separately.
CMakeLists.txt.txt is the main input file to `CMake `_ and is used to
generate build files.
The *RTIMEROOT/include* directory contains the public header files.
By default it is identical to *RTIMEHOME/include*. However, custom ports
will typically add files to this directory.
The *RTIMEROOT/src* directory contains the |me| source files.
RTI does not support modifications to these files unless explicitly stated
in the porting guide. A custom port will typically add specific files to
this directory.
The *RTIMEROOT/build* directory is empty by default. `CMake `_
generates one set of build-files for each configuration. A build configuration
can be an architecture, |me| options, language selection etc. This directory
will contain `CMake `_ generated build-files per architecture
per configuration. By convention the *Debug* directory is used to
generate build-files for debug libraries and the *Release*
directory is used for release libraries.
The *RTIMEROOT/lib* directory is empty by default. All libraries
successfully built with the `CMake `_ generated build-files,
independent of which generator was used, will be copied to the
*RTIMEROOT/lib* directory.
The following naming conventions are used regardless of the build-tool:
- Static libraries have a *z* suffix.
- Shared libraries do *not* have an additional suffix.
- Debug libraries have a *d* suffix.
- Release libraries do *not* have an additional suffix.
The following libraries are built:
- *rti_me* - the core library, including the DDS C API.
- *rti_me_discdpde* - the Dynamic Participant Dynamic Endpoint plugin.
- *rti_me_discdpse* - the Dynamic Participant Static Endpoint plugin.
- *rti_me_rhsm* - the Reader History plugin.
- *rti_me_whsm* - the Writer History plugin.
- *rti_me_netioshmem* - Shared Memory Transport
- *rti_me_netiosdm* - Zero copy over shared memory transport library
- *rti_me_cpp* - the C++ API.
Note: the names above are the RTI library names. Depending on the
target architecture the library name is prefixed with *lib* prefix
and the library suffix also varies between target architectures,
such as .so, .dylib etc.
For example:
- rti_mezd indicates a static debug library
- rti_me indicates a dynamically liked release library
.. _`source_compiling`:
Compiling |rti_me_h|
--------------------
This section describes in detail how to compile |me| using `CMake `_.
It starts with an example that uses the included scripts followed
by a section showing how to build manually.
`CMake `_, available from www.cmake.org, is the
preferred tool to build |rti_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 has no dependencies on external tools.
NOTE: It is not required to use `CMake `_. Please refer to
`Custom Build Environments`_ for other ways to build |me|.
Building |rti_me_h| with rtime-make
...................................
The |me| source bundle includes a bash (Unix) and BAT (Windows) script to
simplify the invocation of `CMake `_. These scripts is a convenient way to
invoke `CMake `_ with the correct options.
Unix:
::
RTIMEROOT/resource/script/rtime-make --type Debug --target self \
--name i86Linux2.6gcc4.4.5 -G "Unix Makefiles" --build
Windows:
::
C:RTIMEROOT\resource\scripts|rti_me|-make --config Debug --target self \
--name i86Win32VS2010 -G "Visual Studio 10 2013" --build
Explanation of arguments:
- ``-config Debug`` : Create Debug build.
- ``-target \`` : The target for the sources will be built.
self indicates that the host machine is the target and |rti_me| will be built
with the options that `CMake `_ automatically determines for the local compiler.
Please refer to \ref source_xbuild for information for more information
on specifying the target architecture to build for.
- ``-name \`` : This is the name of the build and shall be a descriptive
name following the recommendation on naming described in section
\ref source_prepare. If - -name is not specified, the value for - -target will
be used as name.
- ``-build Build`` the generated project files.
On Unix:
- If gcc is part of the name GCC is assumed.
- If clang is part of the name clang is assumed.
On Windows:
- If Win32 if part of the name, a 32 bit Windows build is assumed.
- If Win64 if part of the name, a 64 bit Windows build is assumed.
To get a list of all the options::
rtime-make -h
To get a help for a specific target, use::
rtime-make --target --help
Manually Building with CMake
............................
.. _source-prepare:
Preparation for a Build
'''''''''''''''''''''''
As mentioned, it is recommended to create 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 to assign a descriptive *name* to each build
configuration, using a common format. While there are no requirements to
the format for functional correctness, the tool-chain files in
:ref:`xbuild` uses the **RTIME_TARGET_NAME** variable to determine various
compiler options and selections.
RTI uses the following name format::
{cpu}{OS}{compiler}_{config}
In order to avoid a naming conflict with RTI, the following name format is
recommended::
{prefix}_{cpu}{OS}{compiler}_{config}
Some examples:
- acme_ppc604FreeRTOSgcc4.6.1 - |me| for a PPC 604 running FreeRTOS
compiled with gcc 4.6.1, compiled by acme.
- acme_i86Win32VS2015 - |me| for a i386 running Windows XP or higher
compiled with Visual Studio 2015, compiled by acme.
- acme_i86Linux4gcc4.4.5_test - a test configuration build of |me| for a
i386 running Linux 3 or higher compiled with gcc 4.4.5, compiled by
acme.
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 Buildfiles for RTI Connext DDS Micro Using The CMake GUI
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Start the `CMake `_ GUI, either from a terminal window or a menu.
Please note that the cmake-gui does *not* set the **CMAKE_BUILD_TYPE** variable.
This variable is used to determine the names of the |me| libraries. Thus,
it is necessary to add **CMAKE_BUILD_TYPE** manually and specify either Debug
or Release. To add this variable manually, click the 'Add Entry' button,
specify the name as a string type.
As an alternative rtime-make's ``--gui`` option can be used. This option starts
the `CMake `_ and also adds the **CMAKE_BUILD_TYPE** option when the
`CMake `_ GUI exits.
Please note that when using Visual Studio or Xcode it is important to build the
same configuration as was specified with rtime-make's ``--config`` option. While
it is possible to build a different configuration from the IDE, selecting
a different configuration does *not* update the build configuration
generated for |me|.
It is recommended that the GUI is started from the ``RTIMEROOT`` directory. If
this is not the case, check that:
- The source directory is the location of ``RTIMEROOT``.
- The binary directory is the location of ``RTIMEBUILD``.
With the `CMake `_-gui running:
- Press 'Configure'.
- Select a generator. You must have a compatible tool installed to process the
generated files.
- Select 'Use default native compilers'.
- Press 'Done'.
- Press 'Configure'.
- Check 'Grouped'.
- Expand RTIME and select your build options. All available build options for
|me| are listed here.
- Type a target name for **RTIME_TARGET_NAME**. This should be the same as the
*\* used to create the ``RTIMEBUILD`` directory, that is the ``RTIMEBUILD``
should be on the form *\/\*.
- Press 'Configure'. All red lines should disappear. Due to how `CMake `_
works, it is strongly recommended to always press 'Configure' whenever a value
is changed for a variable. Other variables may depend on the modified variable
and pressing 'Configure' will mark those with a red line. No red lines
means everything has been configured.
- Press 'Generate'. This creates the build-files in the ``RTIMEBUILD`` directory.
Whenever an option is changed and configure is re-run, press Generate again.
- Exit the GUI.
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) change to the
RTIMEBUILD directory and run the build-tool.
After a successful build, the output is placed in RTIMEROOT/lib/\
The generated build-files may contain different sub-projects that are
specific to the tool. For example, in Xcode and MS Visual Studio the following
targets are available:
- ALL_BUILD - Builds all the projects.
- \rti_me_\ - Build 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 Unix makefiles where generated::
make help
Creating Buildfiles for |rti_me_h| Using CMake from The Command-line
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Open a terminal window in the ``RTIMEROOT`` directory and create the ``RTIMEBUILD``
directory. Change to the ``RTIMEBUILD`` directory and invoke cmake
using the following arguments::
cmake -G -DCMAKE_BUILD_TYPE= \
-DCMAKE_TOOLCHAIN_FILE= \
-DRTIME_TARGET_NAME=
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 *RTIMEROOT/lib/\*.
The generated build-files may contain different sub-projects that are
specific to the tool. For example, in Xcode and MS Visual Studio the following
targets are available:
- ALL_BUILD - Builds all the projects.
- \rti_me_\ - Build 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 Unix makefiles where generated::
make help
CMake Flags used by |rti_me_h|
''''''''''''''''''''''''''''''
The following CMake flags (-D) is understood by |me| and may be useful
when building outside of the source bundle installed by RTI. An example would
be incorporating the |me| source in a project tree and invoke cmake directly
on the CMakeLists.txt provided by |me|.
- ``-DRTIME_TARGET_NAME=\`` - The name of the target (equivalant of ``--name`` to rtime-make).
The default value is the name of the source directory.
- ``-DRTIME_CMAKE_ROOT=\`` - Where to place the CMake build files.
The default value is *\