Building VortexDDS applications

Building the Hello World! example

To test the installation, a small Hello World! application is used. This application will also be used as an introduction to DDS.

This chapter explains how to build this example, without details regarding the source code. The next chapter will explain what has to be done to code the Hello World! example.

The procedure used to build the Hello World! example can also be used for building your own applications.

Windows:It is advised to have the VortexDDS examples component installed (see Windows installation) when actively building the VortexDDS examples on Windows. This chapter refers to the VortexDDS examples installed in the User Profile directory on Windows.
Linux:It is advised to have copied the VortexDDS examples to a user-friendly location as described in this paragraph when actively building the VortexDDS examples on Linux. This chapter refers to the VortexDDS examples installed in the user-defined location.

Build Files

Three files are available Hello World! root directory to support building the example. Both Windows native (HelloWorld.sln) and Linux native (Makefile) build files will only be available for this Hello World! example. All the other examples make use of the CMake build system and thus only have the CMakeLists.txt build related file.

Linux Native Build

A Linux native Makefile is provided in the examples/helloworld directory within the destination location entered in the vdds_install_examples script. In a terminal, go to that directory and type

make

The build process should have access to the include files and the ddsc library. The Makefile expects them to be present at system default locations so that it can find them automatically. If this isn’t the case on your machine, then please update the commented out CFLAGS and LDFLAGS within the Makefile to point to the proper locations.

This will build the HelloworldSubscriber and HelloworldPublisher executables in the helloworld source directory (not the bin directory that contains the pre-build binaries).

The Hello World! example can now be executed, like described in Test your installation, using the binaries that were just build. Be sure to use the right directories.

Windows Native Build

For the Windows Native Build, a Visual Studio solution file is available in the examples/helloworld directory. Use a file explorer to navigate to that directory and double click on the HelloWorld.sln file. Visual Studio should now start with the HelloWorld solution that contains three projects.

Project Description
HelloWorldPublisher Information to build the example publisher.
HelloWorldSubscriber Information to build the example subcriber.
HelloWorldType Information to (re)generate HelloWorldData_Msg data type.

Creating the Hello World! example executables is as simple as selecting the required configuration and building the solution.

helloworld\vs\directories.props contains the location of where the VortexDDS header files and libraries are be placed. These locations are based on the default installation directory structure. When VortexDDS is installed in a different directory, the following paths in helloworld\vs\directories.props should be changed, like:

<VortexDDS_lib_dir>C:/Path/To/VortexDDS/Installation/lib</VortexDDS_lib_dir>
<VortexDDS_inc_dir>C:/Path/To/VortexDDS/Installation/include</VortexDDS_inc_dir>
<VortexDDS_idlc_dir>C:/Path/To/VortexDDS/Installation/share/VortexDDS/idlc</VortexDDS_idlc_dir>

To run the example, Visual Studio should run both the publisher and subscriber simultaneously. It is capable of doing so, but it’s not its default setting. To change it, open the HelloWorld solution property page by right clicking the solution and selecting Properties. Then go to Common Properties -> Startup Project, select Multiple startup project and set Action "Start" for HelloWorldPublisher and HelloWorldSubscriber. Finish the change by selecting OK.

Visual Studio is now ready to actually run the Hello World! example, which can be done by selecting Debug -> Start without debugging. Both the HelloworldSubscriber and the HelloworldPublisher will be started and the HelloworldPublisher will write a message that is received by the HelloworldSubscriber.

Building With CMake

In the earlier chapters, building the Hello World! example is done natively. However, the Hello World! example can also be build using the CMake tool. This is what is recommended. In fact, all the other examples don’t provide native makefiles, only CMake files.

CMake

CMake is an open-source, cross-platform family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice.

In other words, CMake’s main strength is build portability. CMake uses the native tools, and other than requiring itself, does not require any additional tools to be installed. The same CMake input files will build with GNU make, Visual studio 6,7,8 IDEs, borland make, nmake, and XCode.

An other advantage of CMake is building out-of-source. It simply works out-of-the-box. There are two important reasons to choose this:

  1. Easy cleanup (no cluttering the source tree). Simply remove the build directory if you want to start from scratch.
  2. Multiple build targets. It’s possible to have up-to-date Debug and Release targets, without having to recompile the entire tree. For systems that do cross-platform compilation, it is easy to have up-to-date builds for the host and target platform.

There are a few other benefits to CMake, but that is out of the scope of this document.

Hello World! CMake (VortexDDS Package)

After the CMake digression, we’re back with the Hello World! example. Apart from the native build files, CMake build files are provided as well. See examples/helloworld/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
cmake_minimum_required(VERSION 3.5)

if (NOT TARGET VortexDDS::ddsc)
    # Find the VortexDDS package. If it is not in a default location, try
    # finding it relative to the example where it most likely resides.
    find_package(VortexDDS REQUIRED PATHS "${CMAKE_SOURCE_DIR}/../../")
endif()

# This is a convenience function, provided by the VortexDDS package,
# that will supply a library target related the the given idl file.
# In short, it takes the idl file, generates the source files with
# the proper data types and compiles them into a library.
idlc_generate(HelloWorldData_lib "HelloWorldData.idl")

# Both executables have only one related source file.
add_executable(HelloworldPublisher publisher.c)
add_executable(HelloworldSubscriber subscriber.c)

# Both executables need to be linked to the idl data type library and
# the ddsc API library.
target_link_libraries(HelloworldPublisher HelloWorldData_lib VortexDDS::ddsc)
target_link_libraries(HelloworldSubscriber HelloWorldData_lib VortexDDS::ddsc)

It will try to find the VortexDDS CMake package. When it has found it, every path and dependencies are automatically set. After that, an application can use it without fuss. CMake will look in the default locations for the code:VortexDDS package.

The VortexDDS package provides the ddsc library that contains the DDS API that the application needs. But apart from that, it also contains helper functionality (idlc_generate) to generate library targets from IDL files. These library targets can be easily used when compiling an application that depends on a data type described in an IDL file.

Two applications will be created, HelloworldPublisher and HelloworldSubscriber. Both consist only out of one source file.

Both applications need to be linked to the ddsc library in the VortexDDS package and HelloWorldData_lib that was generated by the call to idlc_generate.

Hello World! Configuration

The Hello World! example is prepared to be built by CMake through the use of its CMakeLists.txt file. The first step is letting CMake configure the build environment.

It’s good practice to build examples or applications out-of-source. In order to do that, create a build directory in the examples/helloworld directory and go there, making our location examples/helloworld/build.

Here, we can let CMake configure the build environment for us by typing:

cmake ../

Note

CMake does a pretty good job at guessing which generator to use, but some environments require that you supply a specific generator. For example, only 64-bit libraries are shipped for Windows, but CMake will generate a 32-bit project by default, resulting in linker errors. When generating a Visual Studio project keep in mind to append Win64 to the generator. The example below shows how to generate a Visual Studio 2015 project.

cmake -G "Visual Studio 14 2015 Win64" ..

Note

CMake generators can also create IDE environments. For instance, the “Visual Studio 14 2015 Win64” will generate a Visual Studio solution file. Other IDE’s are also possible, like Eclipse.

CMake will use the CMakeLists.txt in the helloworld directory to create makefiles that fit the native platform.

Since everything is prepared, we can actually build the applications (HelloworldPublisher and HelloworldSubscriber in this case).

Hello World! Build

After the configuration step, building the example is as easy as typing:

cmake --build .

Note

On Windows, it is likely that you have to supply the config of Visual Studio:

cmake --build . --config "Release"

while being in the build directory created during the configuration step: examples/helloworld/build.

The resulting Publisher and Subscriber applications can be found in:

Windows:examples\helloworld\build\Release.
Linux:examples/helloworld/build.

The Hello World! example can now be executed, like described in Test your installation, using the binaries that were just build. Be sure to use the right directories.

Summary

We’ve seen that a VortexDDS application can be build by using a Makefile on Linux or a Visual Studio Solutions on Windows. Also CMake can be used to build a VortexDDS application. In fact, it is the preferred way of building.

In the end, a predefined way of generating and building the source code should be followed when building VortexDDS applications. The figure below shows how a typical VortexDDS application is build.

../_images/BuildSchema.png

Next chapter will provide an overview of all steps mentioned in the figure above.