Doc: Explain variables required for building Routing Service examples (#617)

* Doc: Explain variables required for building Routing Service examples

* chore: Fixed linter errors

* doc: Applied corrections from PR

Closes #621

Author: trubio-rti

examples/routing_service/file_adapter/c++11/README.md

@@ -28,22 +28,25 @@ For more details, please refer to the *RTI Routing Service SDK* documentation.
 
 ## Building C++ example
 
-In order to build this example, you need to provide the following variables to
-`CMake`:
-
-- `CONNEXTDDS_DIR`
-- `CONNEXTDDS_ARCH`
+In order to build this example, you need to define the variables `CONNEXTDDS_DIR`
+and `CONNEXTDDS_ARCH`. You can do so by exporting them manually, by sourcing
+the `rtisetenv` script for your architecture, or by passing them to the `cmake`
+command as arguments:
 
 ```bash
-$mkdir build
-$cmake -DCONNEXTDDS_DIR=<Connext DDS Directory>
-    -DCONNEXTDDS_ARCH=<Connext DDS Architecture>
-    -DBUILD_SHARED_LIBS=ON|OFF
-    -DCMAKE_BUILD_TYPE=Debug|Release ..
+mkdir build
+cd build
+cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \     # If not exported
+      -DCONNEXTDDS_ARCH=<Connext DDS Architecture> \ # If not exported
+      -DBUILD_SHARED_LIBS=ON|OFF \
+      -DCMAKE_BUILD_TYPE=Debug|Release ..
 cmake --build .
 ```
 
-**Note**: when compiling on a Windows 64-bit machine you will need to add the
+**Note**: You do not need to define `CONNEXTDDS_ARCH` if you only have one
+architecture target installed in your system.
+
+**Note**: When compiling on a Windows 64-bit machine you will need to add the
 `-A x64` parameter to the call to CMake.
 
 **Note:** If you are using a multi-configuration generator, such as Visual Studio

examples/routing_service/file_adapter/c/README.md

@@ -15,21 +15,24 @@ configuration file.
 
 ## Building C example
 
-In order to build this example, you need to provide the following variables to
-`CMake`:
-
-- `CONNEXTDDS_DIR`
-- `CONNEXTDDS_ARCH` (needed only if you have multiple architectures installed)
+In order to build this example, you need to define the variables `CONNEXTDDS_DIR`
+and `CONNEXTDDS_ARCH`. You can do so by exporting it manually, by sourcing
+the `rtisetenv` script for your architecture, or by passing them to the `cmake`
+command as arguments:
 
 ```bash
-$mkdir build
-$cmake -DCONNEXTDDS_DIR=<Connext DDS Directory>
-    -DCONNEXTDDS_ARCH=<Connext DDS Architecture>
-    -DBUILD_SHARED_LIBS=ON|OFF
-    -DCMAKE_BUILD_TYPE=Debug|Release ..
+mkdir build
+cd build
+cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \     # If not exported
+      -DCONNEXTDDS_ARCH=<Connext DDS Architecture> \ # If not exported
+      -DBUILD_SHARED_LIBS=ON|OFF \
+      -DCMAKE_BUILD_TYPE=Debug|Release ..
 cmake --build .
 ```
 
+**Note**: You do not need to define `CONNEXTDDS_ARCH` if you only have one
+architecture target installed in your system.
+
 **Note:** Since this example uses the `pthread` library, it only works on
 UNIX-like systems. It has been successfully tested on Ubuntu and macOS.
 

examples/routing_service/mongo_db/c++11/README.rst

@@ -4,23 +4,29 @@ Example Code: MongoDB Adapter
 Building
 --------
 
-In order to build this example, you need to provide the following variables to
-``CMake``:
+In order to build this example, you need to define the variables ``CONNEXTDDS_DIR``
+and ``CONNEXTDDS_ARCH``. You can do so by exporting them manually, by sourcing 
+the ``rtisetenv`` script for your architecture, or by passing them to the ``cmake``
+command as arguments. 
 
-- ``CONNEXTDDS_DIR``: path to the ``Connext`` installation root folder
-- ``CONNEXTDDS_ARCH``: target architecture
-- ``MONGODB_DIR``: path to the ``mongodbcxx`` installation root folder
+You also need to define the variable ``MONGODB_DIR`` as the path to the
+``mongodbcxx`` installation directory, which can be either exported or passed as
+an argument to ``cmake``, but won't be set by ``rtisetenv``.
 
 .. code::
-
     mkdir build
-    cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \
-            -DCONNEXTDDS_ARCH=<Connext DDS Architecture> \
-            -DMONGODB_DIR=<mongodbcxx directory> \
-            -DBUILD_SHARED_LIBS=ON \
-            -DCMAKE_BUILD_TYPE=Release ..
+    cd build
+    cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \     # If not exported
+          -DCONNEXTDDS_ARCH=<Connext DDS Architecture> \ # If not exported
+          -DMONGODB_DIR=<mongodbcxx directory> \         # If not exported
+          -DBUILD_SHARED_LIBS=ON|OFF \
+          -DCMAKE_BUILD_TYPE=Debug|Release ..
     cmake --build .
 
+.. note::
+
+   You do not need to define ``CONNEXTDDS_ARCH`` if you only have one architecture
+   target installed in your system.
 
 .. note::
 

examples/routing_service/monitoring/c++11/README.md

@@ -2,36 +2,29 @@
 
 ## Building the Example :wrench:
 
-To build this example, first run CMake to generate the corresponding build
-files. We recommend you use a separate directory to store all the generated
-files (e.g., ./build).
+In order to build this example, you need to define the variables `CONNEXTDDS_DIR`
+and `CONNEXTDDS_ARCH`. You can do so by exporting them manually, by sourcing
+the `rtisetenv` script for your architecture, or by passing them to the `cmake`
+command as arguments:
 
-```sh
+```bash
 mkdir build
 cd build
-cmake ..
-```
-
-Once you have run CMake, you will find a number of new files in your build
-directory (the list of generated files will depend on the specific CMake
-Generator). To build the example, run CMake as follows:
-
-```sh
+cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \     # If not exported
+      -DCONNEXTDDS_ARCH=<Connext DDS Architecture> \ # If not exported
+      -DBUILD_SHARED_LIBS=ON|OFF \
+      -DCMAKE_BUILD_TYPE=Debug|Release ..
 cmake --build .
 ```
 
-**Note**: if you are using a multi-configuration generator, such as Visual
-Studio solutions, you can specify the configuration mode to build as follows:
-
-```sh
-cmake --build . --config Release|Debug
-```
+**Note**: You do not need to define `CONNEXTDDS_ARCH` if you only have one
+architecture target installed in your system.
 
-Alternatively, you can use directly the generated infrastructure (e.g.,
-Makefiles or Visual Studio Solutions) to build the example. If you generated
-Makefiles in the configuration process, run make to build the example. Likewise,
-if you generated a Visual Studio solution, open the solution and follow the
-regular build process.
+Instead of using `cmake --build`, you can directly use the generated
+infrastructure (e.g., Makefiles or Visual Studio Solutions) to build the example.
+If you generated Makefiles in the configuration process, run make to build the
+example. Likewise, if you generated a Visual Studio solution, open the solution
+and follow the regular build process.
 
 ## Running the Example
 
@@ -104,7 +97,7 @@ Also, if you installed libraries for multiple target architectures on your syste
 you want to link against. For example:
 
 ```sh
-cmake -DCONNEXTDDS_ARCH=x64Linux3gcc5.4.0 ..
+cmake -DCONNEXTDDS_ARCH=<Connext DDS Architecture>..
 ```
 
 ### CMake Build Infrastructure

examples/routing_service/remote_admin/c++11/README.md

@@ -28,15 +28,24 @@ The following files are part of the example:
 
 ## Building the Example
 
-Build the example code by running the following command:
+In order to build this example, you need to define the variable `CONNEXTDDS_DIR`
+You can do so by exporting it manually, by sourcing the `rtisetenv` script for
+your architecture, or by passing it to the `cmake` command as arguments:
 
-```sh
+```bash
 mkdir build
 cd build
-cmake ..
+cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \     # If not exported
+      -DBUILD_SHARED_LIBS=ON|OFF \
+      -DCMAKE_BUILD_TYPE=Debug|Release ..
 cmake --build .
 ```
 
+> **Note**:
+>
+> You do not need to define `CONNEXTDDS_ARCH` if you only have one architecture
+> target installed in your system.
+>
 > **Note**:
 >
 > When using a multi-configuration generator, make sure you specify

examples/routing_service/shapes_processor/c++11/README.md

@@ -6,16 +6,18 @@ different architecture, please adapt the commands accordingly.
 
 ## Building the Example :wrench:
 
-To build this example, first run CMake to generate the corresponding build
-files. We recommend you use a separate directory to store all the generated
-files (e.g., ./build).
-
-```sh
+```bash
 mkdir build
 cd build
-cmake -DBUILD_SHARED_LIBS=ON ..
+cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \     # If not exported
+      -DBUILD_SHARED_LIBS=ON|OFF \
+      -DCMAKE_BUILD_TYPE=Debug|Release ..
+cmake --build .
 ```
 
+**Note**: You do not need to define `CONNEXTDDS_ARCH` if you only have one
+architecture target installed in your system.
+
 **Note**: when compiling on a Windows 64-bit machine you will need to add the
 `-A x64` parameter to the call to CMake. See
 [Customizing the Build](#customizing-the-build) for more details.

examples/routing_service/struct_array_transf/c++11/README.md

@@ -6,16 +6,22 @@ different architecture, please adapt the commands accordingly.
 
 ## Building the Example :wrench:
 
-To build this example, first run CMake to generate the corresponding build
-files. We recommend you use a separate directory to store all the generated
-files (e.g., ./build).
+In order to build this example, you need to define the variable `CONNEXTDDS_DIR`
+You can do so by exporting it manually, by sourcing the `rtisetenv` script for
+your architecture, or by passing it to the `cmake` command as arguments:
 
-```sh
+```bash
 mkdir build
 cd build
-cmake -DBUILD_SHARED_LIBS=ON ..
+cmake -DCONNEXTDDS_DIR=<Connext DDS Directory> \     # If not exported
+      -DBUILD_SHARED_LIBS=ON \
+      -DCMAKE_BUILD_TYPE=Debug|Release ..
+cmake --build .
 ```
 
+**Note**: You do not need to define `CONNEXTDDS_ARCH` if you only have one
+architecture target installed in your system.
+
 **Note**: when compiling on a Windows 64-bit machine you will need to add the
 `-A x64` parameter to the call to CMake. See
 [Customizing the Build](#customizing-the-build) for more details.