Review Changes and Other Fixes and Tweaks

- Changed many cache variables to be typed with a documentation string.
- Fixed compatibility with CMake 3.3
- Added NO_PASSED and NO_GENERATED to opendds_install_interface_files
- Properly moved dds/DCPS/security/Uility.h to framework.
- Many fixes and tweaks to documentation.

CMakeLists.txt

@@ -25,7 +25,7 @@ get_filename_component(_OPENDDS_SOURCE_DIR_REAL "${OPENDDS_SOURCE_DIR}" REALPATH
 get_filename_component(_OPENDDS_BUILD_DIR_REAL "${OPENDDS_BUILD_DIR}" REALPATH)
 if("${_OPENDDS_SOURCE_DIR_REAL}" STREQUAL "${_OPENDDS_BUILD_DIR_REAL}")
   message(FATAL_ERROR "Please build OpenDDS in a different directory from the source tree "
-    "directory. Use something like \"cmake -B build\".")
+    "directory. Use something like \"cmake -S . -B build\".")
 endif()
 set(OPENDDS_BIN_DIR "${OPENDDS_BUILD_DIR}/bin" CACHE INTERNAL "")
 set(OPENDDS_LIB_DIR "${OPENDDS_BUILD_DIR}/lib" CACHE INTERNAL "")
@@ -88,6 +88,7 @@ if(OPENDDS_SECURITY)
 endif()
 add_subdirectory(tools/inspect)
 
+# Installation
 set(cmake_dest "${CMAKE_INSTALL_DATAROOTDIR}/cmake/OpenDDS")
 install(EXPORT opendds_targets
   FILE "opendds_targets.cmake"
@@ -123,9 +124,14 @@ if(OPENDDS_RAPIDJSON)
     DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 endif()
 
-if(NOT DEFINED OPENDDS_BUILD_TESTS AND BUILD_TESTING)
-  set(OPENDDS_BUILD_TESTS TRUE)
+# Examples and Tests
+if(BUILD_TESTING)
+  set(_OPENDDS_BUILD_TESTS_DEFAULT TRUE)
+else()
+  set(_OPENDDS_BUILD_TESTS_DEFAULT FALSE)
 endif()
+set(OPENDDS_BUILD_TESTS ${_OPENDDS_BUILD_TESTS_DEFAULT} CACHE BOOL "Build OpenDDS Tests")
+set(OPENDDS_BUILD_EXAMPLES TRUE CACHE BOOL "Build OpenDDS Examples")
 if(OPENDDS_BUILD_EXAMPLES OR OPENDDS_BUILD_TESTS)
   enable_testing()
   add_subdirectory(DevGuideExamples/DCPS/Messenger)

cmake/OpenDDSConfig.cmake

@@ -1,7 +1,7 @@
-# This is what's CMake evaluates when find_package(OpenDDS) is called. It
-# should find ACE/TAO and OpenDDS according to COMPONENTS passed, make those
-# libraries and executables available, and make opendds_targets_sources
-# available if possible.
+# This is what CMake evaluates when find_package(OpenDDS) is called. It should
+# find ACE/TAO and OpenDDS according to COMPONENTS passed and other information
+# like OpenDDS_ROOT, make those libraries and executables available, and make
+# opendds_targets_sources available if possible.
 #
 # Distributed under the OpenDDS License. See accompanying LICENSE
 # file or http://www.opendds.org/license.html for details.

cmake/init.cmake

@@ -9,6 +9,8 @@ if(_OPENDDS_INIT_CMAKE)
 endif()
 set(_OPENDDS_INIT_CMAKE TRUE)
 
+include(CMakeParseArguments)
+
 include("${CMAKE_CURRENT_LIST_DIR}/opendds_version.cmake")
 
 function(_opendds_detect_ace)
@@ -31,7 +33,7 @@ function(_opendds_detect_ace)
       if(OPENDDS_CMAKE_VERBOSE)
         message(STATUS "${name}=${value}")
       endif()
-      set("${name}" "${value}" CACHE INTERNAL "")
+      set("${name}" "${value}" CACHE BOOL "")
     endif()
   endforeach()
 endfunction()
@@ -74,17 +76,18 @@ set(_OPENDDS_FEATURE_VARS)
 set(_OPENDDS_MPC_FEATURES)
 function(_opendds_feature name default_value)
   set(no_value_options MPC MPC_INVERTED)
-  set(single_value_options MPC_NAME)
+  set(single_value_options MPC_NAME DOC TYPE)
   set(multi_value_options)
   cmake_parse_arguments(arg
     "${no_value_options}" "${single_value_options}" "${multi_value_options}" ${ARGN})
+  if(NOT DEFINED arg_TYPE)
+    set(arg_TYPE BOOL)
+  endif()
 
   string(TOLOWER "${name}" lowercase_name)
   list(APPEND _OPENDDS_ALL_FEATURES "${lowercase_name}")
   set(name "OPENDDS_${name}")
-  if(NOT DEFINED "${name}")
-    set("${name}" "${default_value}" CACHE INTERNAL "")
-  endif()
+  set("${name}" "${default_value}" CACHE "${arg_TYPE}" "${arg_DOC}")
   list(APPEND _OPENDDS_FEATURE_VARS "${name}")
   if(arg_MPC OR arg_MPC_INVERTED)
     if(NOT DEFINED arg_MPC_NAME)
@@ -111,35 +114,41 @@ function(_opendds_feature name default_value)
 endfunction()
 
 # OpenDDS Features
-_opendds_feature(BUILT_IN_TOPICS ON)
-_opendds_feature(OBJECT_MODEL_PROFILE ON)
-_opendds_feature(PERSISTENCE_PROFILE ON)
-_opendds_feature(OWNERSHIP_PROFILE ON)
-_opendds_feature(OWNERSHIP_KIND_EXCLUSIVE ${OPENDDS_OWNERSHIP_PROFILE})
-_opendds_feature(CONTENT_SUBSCRIPTION ON)
-_opendds_feature(CONTENT_FILTERED_TOPIC ${OPENDDS_CONTENT_SUBSCRIPTION})
-_opendds_feature(MULTI_TOPIC ${OPENDDS_CONTENT_SUBSCRIPTION})
-_opendds_feature(QUERY_CONDITION ${OPENDDS_CONTENT_SUBSCRIPTION})
-_opendds_feature(SUPPRESS_ANYS ON)
-_opendds_feature(SECURITY OFF)
-_opendds_feature(SAFETY_PROFILE OFF)
+_opendds_feature(BUILT_IN_TOPICS ON DOC "Enables built-in-topics (BITs)")
+_opendds_feature(OBJECT_MODEL_PROFILE ON DOC "Allows using presentation group QoS")
+_opendds_feature(PERSISTENCE_PROFILE ON
+  DOC "Allows using the durability and durability service QoS")
+_opendds_feature(OWNERSHIP_PROFILE ON
+  DOC "Allows history depth QoS adn implies OPENDDS_OWNERSHIP_KIND_EXCLUSIVE")
+_opendds_feature(OWNERSHIP_KIND_EXCLUSIVE ${OPENDDS_OWNERSHIP_PROFILE}
+  DOC "Allows the EXCLUSIVE ownership QoS")
+_opendds_feature(CONTENT_SUBSCRIPTION ON
+  DOC "Implies OPENDDS_CONTENT_FILTERED_TOPIC, OPENDDS_MULTI_TOPIC, and OPENDDS_QUERY_CONDITION")
+_opendds_feature(CONTENT_FILTERED_TOPIC ${OPENDDS_CONTENT_SUBSCRIPTION}
+  DOC "Allows using ContentFilteredTopic")
+_opendds_feature(MULTI_TOPIC ${OPENDDS_CONTENT_SUBSCRIPTION} DOC "Allows using MultiTopic")
+_opendds_feature(QUERY_CONDITION ${OPENDDS_CONTENT_SUBSCRIPTION} DOC "Allows using QueryCondition")
+_opendds_feature(SUPPRESS_ANYS ON DOC "Default for opendds_target_sources(SUPPRESS_ANYS)")
+_opendds_feature(SECURITY OFF DOC "Build with RTPS Security support")
+_opendds_feature(SAFETY_PROFILE OFF DOC "Build using Safety Profile (Not for CMake-built OpenDDS)")
 
 # ACE Features
 if(NOT CMAKE_BUILD_TYPE OR CMAKE_BUILD_TYPE STREQUAL "Debug")
-  _opendds_feature(DEBUG ON MPC)
-  _opendds_feature(OPTIMIZE OFF MPC)
+  _opendds_feature(DEBUG ON MPC DOC "(Not for CMake-built OpenDDS)")
+  _opendds_feature(OPTIMIZE OFF MPC DOC "(Not for CMake-built OpenDDS)")
 else()
-  _opendds_feature(DEBUG OFF MPC)
-  _opendds_feature(OPTIMIZE ON MPC)
+  _opendds_feature(DEBUG OFF MPC DOC "(Not for CMake-built OpenDDS)")
+  _opendds_feature(OPTIMIZE ON MPC DOC "(Not for CMake-built OpenDDS)")
 endif()
-_opendds_feature(INLINE ON MPC)
+_opendds_feature(INLINE ON MPC DOC "(Not for CMake-built OpenDDS)")
 if(BUILD_SHARED_LIBS)
-  _opendds_feature(STATIC OFF MPC)
+  _opendds_feature(STATIC OFF MPC DOC "(Not for CMake-built OpenDDS)")
 else()
-  _opendds_feature(STATIC ON MPC)
+  _opendds_feature(STATIC ON MPC DOC "(Not for CMake-built OpenDDS)")
 endif()
-_opendds_feature(XERCES3 ${OPENDDS_SECURITY} MPC)
-_opendds_feature(IPV6 OFF MPC)
+_opendds_feature(XERCES3 "${OPENDDS_SECURITY}" MPC TYPE PATH
+  DOC "Build with Xerces XML parser, needed for secuirty and QoS XML Handler")
+_opendds_feature(IPV6 OFF MPC DOC "Build with IPv6 support")
 
 # TAO Features
 _opendds_feature(TAO_IIOP ON MPC_INVERTED MPC_NAME tao_no_iiop)

cmake/opendds_target_sources.cmake

@@ -399,7 +399,7 @@ function(opendds_target_sources target)
 endfunction()
 
 function(opendds_install_interface_files target)
-  set(no_value_options)
+  set(no_value_options NO_PASSED NO_GENERATED)
   set(single_value_options DEST INCLUDE_BASE)
   set(multi_value_options EXTRA_GENERATED_FILES)
   cmake_parse_arguments(arg
@@ -412,13 +412,19 @@ function(opendds_install_interface_files target)
     set(arg_DEST "${CMAKE_INSTALL_INCLUDEDIR}")
   endif()
 
-  get_target_property(passed ${target} OPENDDS_ALL_PASSED_INTERFACE_FILES)
-  foreach(file ${passed})
-    file(RELATIVE_PATH dest ${arg_INCLUDE_BASE} ${file})
-    get_filename_component(dest ${dest} DIRECTORY)
-    install(FILES ${file} DESTINATION "${arg_DEST}/${dest}")
-  endforeach()
+  if(NOT arg_NO_PASSED)
+    get_target_property(passed ${target} OPENDDS_ALL_PASSED_INTERFACE_FILES)
+    foreach(file ${passed})
+      file(RELATIVE_PATH dest ${arg_INCLUDE_BASE} ${file})
+      get_filename_component(dest ${dest} DIRECTORY)
+      install(FILES ${file} DESTINATION "${arg_DEST}/${dest}")
+    endforeach()
+  endif()
+
   get_target_property(generated ${target} OPENDDS_ALL_GENERATED_INTERFACE_FILES)
+  if(arg_NO_GENERATED)
+    unset(generated)
+  endif()
   get_target_property(gendir ${target} OPENDDS_GENERATED_DIRECTORY)
   foreach(file ${generated} ${arg_EXTRA_GENERATED_FILES})
     file(RELATIVE_PATH dest ${gendir} ${file})

dds/CMakeLists.txt

@@ -426,6 +426,7 @@ target_sources(OpenDDS_Dcps
     DCPS/security/framework/SecurityPluginInst.h
     DCPS/security/framework/SecurityPluginInst_rch.h
     DCPS/security/framework/SecurityRegistry.h
+    DCPS/security/framework/Utility.h
     DCPS/transport/framework/BasicQueueVisitor_T.h
     DCPS/transport/framework/BasicQueue_T.h
     DCPS/transport/framework/BuildChainVisitor.h

dds/DCPS/security/CMakeLists.txt

@@ -55,7 +55,6 @@ target_sources(OpenDDS_Security
     SSL/Utils.h
     TokenReader.h
     TokenWriter.h
-    Utility.h
     UtilityImpl.h
     framework/HandleRegistry.h
     framework/Properties.h

dds/DCPS/security/UtilityImpl.h

@@ -7,13 +7,13 @@
 #define OPENDDS_DCPS_SECURITY_UTILITYIMPL_H
 
 #include "OpenDDS_Security_Export.h"
-#include "Utility.h"
+#include "framework/Utility.h"
 
 #include <dds/Versioned_Namespace.h>
 
-#if !defined (ACE_LACKS_PRAGMA_ONCE)
-#pragma once
-#endif /* ACE_LACKS_PRAGMA_ONCE */
+#ifndef ACE_LACKS_PRAGMA_ONCE
+#  pragma once
+#endif
 
 OPENDDS_BEGIN_VERSIONED_NAMESPACE_DECL
 

dds/DCPS/security/framework/SecurityConfig.h

@@ -1,6 +1,4 @@
 /*
- *
- *
  * Distributed under the OpenDDS License.
  * See: http://www.opendds.org/license.html
  */
@@ -9,18 +7,13 @@
 #define OPENDDS_DCPS_SECURITY_FRAMEWORK_SECURITYCONFIG_H
 
 #include "SecurityConfigPropertyList.h"
-#ifdef OPENDDS_SECURITY
-#  include "HandleRegistry.h"
-#endif
+#include "HandleRegistry.h"
+#include "Utility.h"
 
 #include <dds/DCPS/dcps_export.h>
-
 #include <dds/DCPS/debug.h>
 #include <dds/DCPS/RcObject.h>
 #include <dds/DCPS/GuidUtils.h>
-#ifdef OPENDDS_SECURITY
-#  include <dds/DCPS/security/Utility.h>
-#endif
 
 #ifdef OPENDDS_SECURITY
 #  include <dds/DdsSecurityCoreC.h>

dds/DCPS/security/framework/SecurityPluginInst.h

@@ -1,22 +1,19 @@
 /*
- *
- *
  * Distributed under the OpenDDS License.
  * See: http://www.opendds.org/license.html
  */
 
 #ifndef OPENDDS_DCPS_SECURITY_FRAMEWORK_SECURITYPLUGININST_H
 #define OPENDDS_DCPS_SECURITY_FRAMEWORK_SECURITYPLUGININST_H
 
-#ifdef OPENDDS_SECURITY
-#include "dds/DdsSecurityCoreC.h"
-#include "dds/DCPS/security/Utility.h"
-#endif
+#include "Utility.h"
+
+#include <dds/DCPS/dcps_export.h>
+#include <dds/DCPS/RcObject.h>
 
-#include "dds/DCPS/dcps_export.h"
-#include "dds/DCPS/RcObject.h"
+#include <dds/DdsSecurityCoreC.h>
 
-#include "ace/Synch_Traits.h"
+#include <ace/Synch_Traits.h>
 
 OPENDDS_BEGIN_VERSIONED_NAMESPACE_DECL
 

dds/DCPS/security/Utility.h → dds/DCPS/security/framework/Utility.h

@@ -3,15 +3,14 @@
  * See: http://www.OpenDDS.org/license.html
  */
 
-#ifndef OPENDDS_DCPS_SECURITY_UTILITY_H
-#define OPENDDS_DCPS_SECURITY_UTILITY_H
+#ifndef OPENDDS_DCPS_SECURITY_FRAMEWORK_UTILITY_H
+#define OPENDDS_DCPS_SECURITY_FRAMEWORK_UTILITY_H
 
 #include <dds/DCPS/dcps_export.h>
-#include <dds/DCPS/SequenceIterator.h>
 #include <dds/DCPS/RcObject.h>
 #include <dds/Versioned_Namespace.h>
 
-#include <dds/DdsSecurityCoreC.h>
+#include <string>
 
 #ifndef ACE_LACKS_PRAGMA_ONCE
 #  pragma once

dds/InfoRepo/DCPSInfo_i.cpp

@@ -2260,7 +2260,7 @@ int TAO_DDS_DCPSInfo_i::init_transport(int listen_address_given,
     OpenDDS::DCPS::TransportInst_rch inst =
       OpenDDS::DCPS::TransportRegistry::instance()->create_inst(inst_name,
                                                                "tcp");
-    if(!inst) {
+    if (!inst) {
       if (OpenDDS::DCPS::log_level >= OpenDDS::DCPS::LogLevel::Error) {
         ACE_DEBUG((LM_DEBUG, "(%P|%t) TAO_DDS_DCPSInfo_i::init_transport: "
           "couldn't create TCP transport instance for BITs\n"));

docs/devguide/building/cmake.rst

@@ -451,7 +451,9 @@ Functions
     This allows using IDL files from multiple directories.
     :cmake:func:`opendds_install_interface_files` is proved to help install generated files that result from this.
     Any IDL file passed that's outside the include base will cause an error.
+
     The default behavior is the legacy behavior that assumes a flat hierarchy.
+    Starting with OpenDDS 4.0 this will always be enabled and will default to ``CMAKE_CURRENT_SOURCE_DIR``.
 
     .. versionadded:: 3.26
 

docs/devguide/building/dependencies.rst

@@ -130,7 +130,8 @@ See :doc:`cmake` for how to build OpenDDS applications with CMake and without th
 CMake is required to build :ref:`deps-gtest` for OpenDDS tests if a prebuilt GoogleTest is not found or provided.
 See :ghfile:`tests/gtest_setup.txt` for details.
 
-CMake should be version 3.3 or later.
+CMake should be version 3.3 or later for :doc:`cmake`.
+It should be version 3.23 or later for :ref:`cmake-building`.
 
 .. _deps-gtest:
 

docs/devguide/building/index.rst

@@ -592,7 +592,7 @@ These are the variables that are exclusive to building OpenDDS with CMake:
 
   Build examples that are currently supported when building OpenDDS with CMake.
   See :ref:`cmake-running-tests` for how to run them.
-  The default for this is :cmake:var:`OPENDDS_BUILD_TESTS`.
+  The default for this is ``TRUE``.
 
 Speeding up the build
 ---------------------
@@ -614,25 +614,15 @@ Cross Compiling
 Once set up properly, OpenDDS can be cross-compiled with CMake using normal `CMake cross compiling <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Cross%20Compiling%20With%20CMake.html>`__.
 A few things to note:
 
-- Host tools:
-
-  - Native-built host tools, like :term:`opendds_idl`, have to be configured and built separately and provided to the target build using :cmake:var:`OPENDDS_HOST_TOOLS`.
-
-  - The host tools can build its own ACE/TAO for the host system, but this can be overridden using :cmake:var:`OPENDDS_ACE` on the host build and :cmake:var:`OPENDDS_ACE_TAO_HOST_TOOLS` on the target build.
-
-- Target build:
-
-  - If building ACE/TAO for a target isn't automatically supported, then ACE/TAO will have to be configured and built separately and provided using :cmake:var:`OPENDDS_ACE`.
-    Current only ACE/TAO for Android can built automatically, see below for an example for this.
-
-  - See https://www.dre.vanderbilt.edu/~schmidt/DOC_ROOT/ACE/ACE-INSTALL.html for how to manually build ACE/TAO.
+- Native-built host tools, like :term:`opendds_idl`, have to be configured and built separately and provided to the target build using :cmake:var:`OPENDDS_HOST_TOOLS`.
+- The host tools will build its own ACE/TAO for the host system, but this can be overridden using :cmake:var:`OPENDDS_ACE` on the host build and :cmake:var:`OPENDDS_ACE_TAO_HOST_TOOLS` on the target build.
+- If the target platform isn't automatically supported, then ACE/TAO will have to be :ref:`built serperatly <cmake-ace-tao-manual>`.
 
 Android
 ^^^^^^^
 
 The following is an example of cross-compiling OpenDDS for Android on Linux using CMake.
-
-It assumes the NDK has been downloaded and the location is in an environment variables called ``NDK`` and the downloaded ACE/TAO version matches the version being used by host tools.
+It assumes the NDK has been downloaded and the location is in an environment variable called ``NDK``.
 
 .. code-block:: shell
 
@@ -661,13 +651,24 @@ Currently ACE/TAO has to be installed separately and this is only possible with
 Running Tests
 =============
 
-Tests (:cmake:var:`OPENDDS_BUILD_TESTS`) and examples (:cmake:var:`OPENDDS_BUILD_EXAMPLES`) can be run using the ``test`` target (``cmake --build build -t test``) or directly using `ctest <https://cmake.org/cmake/help/latest/manual/ctest.1.html>`__.
+:cmake:var:`Tests <OPENDDS_BUILD_TESTS>` and :cmake:var:`examples <OPENDDS_BUILD_EXAMPLES>` can be run using using `ctest <https://cmake.org/cmake/help/latest/manual/ctest.1.html>`__.
+There is also a target for running tests in the build, but the name differs based on the CMake generator used.
 
-Other Known Limitations
-=======================
+.. _cmake-known-limitations:
+
+Known Limitations
+=================
+
+.. _cmake-ace-tao-manual:
+
+- ACE/TAO can't be automatically built unless there is explicit support for the platform.
+  Currently this only exists for Windows, Linux, macOS, and Android.
+  All other platforms will require configuring and building ACE/TAO separately :cmake:var:`OPENDDS_ACE`
+
+  - See https://www.dre.vanderbilt.edu/~schmidt/DOC_ROOT/ACE/ACE-INSTALL.html for how to manually build ACE/TAO.
 
 - The following features are planned, but not implemented yet:
 
-  - The ability to use MPC for building user applications.
-  - Safety Profile
-  - Java Mapping
+  - Support for :ref:`safety_profile`
+  - Support for :ref:`java`
+  - The ability to use MPC for building user applications with an installed CMake-built OpenDDS