Merge pull request OpenDDS#4314 from iguessthislldo/igtd/cmake-build

Fixes and Tweaks for CMake Documentation

cmake/get_ace_tao.cmake

@@ -7,7 +7,8 @@ endif()
 set(url_base "https://github.com/DOCGroup/ACE_TAO/releases/download/")
 set(ace_ver "7.1.1")
 set(zip_md5 "db6d014b6d5863090988204295a0f73e")
-set(tbz_zmd5 "2f60399b059dfd184c8248443920b6e5")
+set(tbz_md5 "2f60399b059dfd184c8248443920b6e5")
+
 set(_OPENDDS_CONFIGURE_ACE_TAO_ARGS)
 set(ACE_IS_BEING_BUILT MPC CACHE INTERNAL "")
 set(TAO_IS_BEING_BUILT MPC CACHE INTERNAL "")

cmake/opendds_group.cmake

@@ -2,7 +2,7 @@
 # file or http://www.opendds.org/license.html for details.
 #
 # Definitions for the OpenDDS libraries that are shared between the CMake
-# config package for a MPC-built OpenDDS and a CMake-built OpenDDS.
+# config package for an MPC-built OpenDDS and a CMake-built OpenDDS.
 
 if(_OPENDDS_GROUP_CMAKE)
   return()

docs/devguide/building/cmake.rst

@@ -2,6 +2,10 @@
 Using OpenDDS in a CMake Project
 ################################
 
+.. seealso::
+
+  :ref:`cmake-building`
+
 OpenDDS can be used with `CMake <https://cmake.org>`__\-based projects by using the :ghfile:`OpenDDS CMake config package <cmake>`.
 This package bridges the gap between the MPC build system used by OpenDDS and CMake-based projects by providing :ref:`imported library targets <cmake-libraries>` and the ability to add IDL to a target using :cmake:func:`opendds_target_sources`.
 
@@ -733,50 +737,51 @@ These variables can be used to override default behavior of the CMake package.
 Config Variables
 -----------------
 
-These variables are set by the configure script and normally shouldn't be changed.
+These variables are set by the ``configure`` script in an MPC-built OpenDDS and normally shouldn't be changed.
+They can be changed when configuring a :ref:`CMake-built OpenDDS <cmake-building>` using ``-D``, but should not be changed after that.
 
 Dependencies
 ^^^^^^^^^^^^
 
 .. cmake:var:: OPENDDS_ACE
   :nocontentsentry:
 
-  Path to ACE, usually :envvar:`ACE_ROOT`
+  Path to :ref:`deps-ace`, usually :envvar:`ACE_ROOT`
 
 .. cmake:var:: OPENDDS_TAO
   :nocontentsentry:
 
-  Path to TAO, usually :envvar:`TAO_ROOT`
+  Path to :ref:`deps-tao`, usually :envvar:`TAO_ROOT`
 
 .. cmake:var:: OPENDDS_OPENSSL
   :nocontentsentry:
 
-  Path to OpenSSL
+  Path to :ref:`deps-openssl`
 
 .. cmake:var:: OPENDDS_GTEST
   :nocontentsentry:
 
-  Path to Google Test
+  Path to :ref:`deps-gtest`
 
 .. cmake:var:: OPENDDS_JAVA
   :nocontentsentry:
 
-  Path to Java
+  Path to :ref:`deps-java`
 
 .. cmake:var:: OPENDDS_QT
   :nocontentsentry:
 
-  Path to QT
+  Path to :ref:`deps-qt`
 
 .. cmake:var:: OPENDDS_RAPIDJSON
   :nocontentsentry:
 
-  Path to RapidJSON
+  Path to :ref:`deps-rapidjson`
 
 .. cmake:var:: OPENDDS_XERCES3
   :nocontentsentry:
 
-  Path to Xerces
+  Path to :ref:`deps-xerces`
 
 .. cmake:var:: OPENDDS_HOST_TOOLS
 
@@ -801,6 +806,7 @@ Features
 
   ACE/TAO and OpenDDS were built with C++11 or later.
   Default depends on the compiler being used.
+  Has no effect when building OpenDDS using CMake.
 
 .. cmake:var:: OPENDDS_DEBUG
   :nocontentsentry:
@@ -819,6 +825,7 @@ Features
 
   ``.inl`` files are included in header files.
   Default is ``ON``
+  Has no effect when building OpenDDS using CMake.
 
 .. cmake:var:: OPENDDS_VERSIONED_NAMEPSACE
   :nocontentsentry:

docs/devguide/building/index.rst

@@ -576,7 +576,8 @@ These are the variables that are exclusive to building OpenDDS with CMake:
 
 .. cmake:var:: OPENDDS_JUST_BUILD_HOST_TOOLS
 
-  If true, just builds ``opendds_idl``.
+  If true, ``opendds_idl`` is the only thing built for OpenDDS.
+  If ACE/TAO is also being built, then ``ace_gperf``, ``tao_idl``, and their dependencies are also built.
   The build directory for this can be passed to :cmake:var:`OPENDDS_HOST_TOOLS`.
 
 .. cmake:var:: OPENDDS_ACE_TAO_SRC
@@ -648,6 +649,11 @@ Installation
 Once built, OpenDDS can be installed using `cmake --install <https://cmake.org/cmake/help/latest/manual/cmake.1.html#install-a-project>`__.
 Currently ACE/TAO has to be installed separately and this is only possible with GNU Make.
 
+Using a CMake-built OpenDDS
+===========================
+
+After building and optionally installing OpenDDS, it can be used through the same :doc:`CMake package <cmake>` as an MPC-built OpenDDS.
+
 .. _cmake-running-tests:
 
 Running Tests
@@ -665,7 +671,7 @@ Known Limitations
 
 - 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`
+  All other platforms will require configuring and building ACE/TAO separately and passing the path using :cmake:var:`OPENDDS_ACE`.
 
   - See https://www.dre.vanderbilt.edu/~schmidt/DOC_ROOT/ACE/ACE-INSTALL.html for how to manually build ACE/TAO.
 

docs/news.d/cmake-build.rst

@@ -1,14 +1,15 @@
-.. news-prs: 4203
+.. news-prs: 4203 4214
 .. news-start-section: Additions
 .. news-rank: 10
 - OpenDDS can now be built using CMake for most common scenarios.
 
-  - This is still considered somewhat experimental as it doesn't support :ref:`all the scenarios that a MPC-built OpenDDS currently can <cmake-known-limitations>`.
-  - See :ref:`cmake-building` for how to build OpenDDS using CMake and other details.
+  - This is still considered somewhat experimental as it doesn't support :ref:`everything that an MPC-built OpenDDS currently can <cmake-known-limitations>`.
+  - See :ref:`cmake-building` for details.
 
 .. news-rank: 0
 .. news-start-section: CMake Config Package
 - Added :cmake:func:`opendds_install_interface_files` to help install IDL files and the files generated from them.
+- Added :cmake:var:`OPENDDS_HOST_TOOLS` and :cmake:var:`OPENDDS_ACE_TAO_HOST_TOOLS` to allow cross compiling applications with both MPC and CMake-built OpenDDS.
 .. news-rank: 0
 .. news-start-section: :cmake:func:`opendds_target_sources`:
 .. news-rank: 10