From 9f4c8422a804aa571acd472c02a812b2fa4a6388 Mon Sep 17 00:00:00 2001
From: MarcelPiNacy-CVC <169088301+MarcelPiNacy-CVC@users.noreply.github.com>
Date: Wed, 15 May 2024 17:50:06 +0200
Subject: [PATCH] Add functions and macros to aid in documentation and general
 usability. (#7639)

* Introduce the macros carla_add_executable, carla_add_library, carla_add_custom_target and introduce help dialog and help file generation.

* Remove semicolon on output.

* Switch from using configure time logic to a target "carla-help".

* Remove GCC_COMPILER option.

* Check PACKAGE_CONFIGURATION for empty.

* Revert to add_library for carla-ros2-native ExternalProject.

* Add function carla_add_target_docs and document "clean".

* Minor fix (missing names).

---------

Co-authored-by: Marcel Pi <25649656+MarcelPiNacy@users.noreply.github.com>
Co-authored-by: Marcel Pi <marcelpi97@gmail.com>
---
 .gitignore                                   |   2 +
 CMake/Options.cmake                          |  10 +-
 CMake/Util.cmake                             | 112 ++++++++++++++++++-
 CMakeLists.txt                               |  27 ++++-
 Examples/CppClient/CMakeLists.txt            |   3 +-
 LibCarla/CMakeLists.txt                      |  15 +--
 PythonAPI/CMakeLists.txt                     |   6 +-
 Ros2Native/CMakeLists.txt                    |  26 +++--
 Ros2Native/LibCarlaRos2Native/CMakeLists.txt |   6 +-
 Unreal/CMakeLists.txt                        |  54 +++++----
 osm-world-renderer/CMakeLists.txt            |   6 +-
 11 files changed, 203 insertions(+), 64 deletions(-)

diff --git a/.gitignore b/.gitignore
index 51b46a87a..bff4d8432 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,5 @@ Dist/
 out/
 
 CMakeSettings.json
+
+Help.md
diff --git a/CMake/Options.cmake b/CMake/Options.cmake
index d5ac73375..22abe12ff 100644
--- a/CMake/Options.cmake
+++ b/CMake/Options.cmake
@@ -125,13 +125,7 @@ carla_option (
 carla_string_option (
   LIBCARLA_IMAGE_SUPPORTED_FORMATS
   "Semicolon-separated list of supported image formats by LibCarla. Available formats: png, jpeg, tiff."
-  png
-)
-
-carla_string_option (  
-  GCC_COMPILER
-  "gcc compiler used by some CARLA extensions."
-  /usr/bin/gcc-7
+  "png"
 )
 
 
@@ -192,7 +186,7 @@ if (${BUILD_CARLA_UNREAL} AND ${CARLA_HAS_UNREAL_ENGINE_PATH})
   )
 else ()
   carla_error (
-    "Could not add UE project to build since the carla_option CARLA_UNREAL_ENGINE_PATH"
+    "Could not add UE project to build since the carla_option CARLA_UNREAL_ENGINE_PATH "
     "is not set to a valid path (\"${CARLA_UNREAL_ENGINE_PATH}\")."
     "Please set it to point to the root path of your CARLA Unreal Engine installation."
   )
diff --git a/CMake/Util.cmake b/CMake/Util.cmake
index 5a2c0e629..dff2b780b 100644
--- a/CMake/Util.cmake
+++ b/CMake/Util.cmake
@@ -17,26 +17,130 @@ endfunction ()
 
 
 
-# message wrapper for warnings.
-macro (carla_warning)
+# message() wrapper for warnings.
+function (carla_warning)
   message (WARNING ${ARGN})
-endmacro ()
+endfunction ()
 
 
 
-# message wrapper for errors.
+# message() wrapper for errors.
 function (carla_error)
   message (FATAL_ERROR ${ARGN})
 endfunction ()
 
 
 
+function (carla_get_option_docs OUT_VAR)
+  get_property (DOCS GLOBAL PROPERTY CARLA_OPTION_DOCS)
+  set (${OUT_VAR} ${DOCS})
+  return (PROPAGATE ${OUT_VAR})
+endfunction ()
+
 macro (carla_option NAME DESCRIPTION VALUE)
   option (${NAME} ${DESCRIPTION} ${VALUE})
   carla_message ("(option) ${NAME} : ${VALUE}")
+  get_property (DOCS GLOBAL PROPERTY CARLA_OPTION_DOCS)
+  string (
+    APPEND
+    DOCS
+    "- ${NAME}\n"
+    "\t- Description: ${DESCRIPTION}\n"
+    "\t- Default: ${VALUE}\n"
+  )
+  set_property (GLOBAL PROPERTY CARLA_OPTION_DOCS ${DOCS})
 endmacro ()
 
+
+
 macro (carla_string_option NAME DESCRIPTION VALUE)
   set (${NAME} "${VALUE}")
   carla_message ("(option) ${NAME} : \"${VALUE}\"")
+  get_property (DOCS GLOBAL PROPERTY CARLA_OPTION_DOCS)
+  string (
+    APPEND
+    DOCS
+    "- ${NAME}\n"
+    "\t- Description: ${DESCRIPTION}\n"
+    "\t- Default: \"${VALUE}\"\n"
+  )
+  set_property (GLOBAL PROPERTY CARLA_OPTION_DOCS ${DOCS})
 endmacro ()
+
+
+
+# If, for some reason, CARLA is configured with CMake<3.5, this is necessary:
+if (${CMAKE_VERSION} VERSION_LESS 3.5)
+  include (CMakeParseArguments)
+endif ()
+
+function (carla_add_target_docs)
+  set (OPTIONS)
+  set (ONE_VAL_ARGS NAME TYPE DOCS_BRIEF)
+  set (MULTI_VAL_ARGS)
+  cmake_parse_arguments (
+    ARG
+    "${OPTIONS}"
+    "${ONE_VAL_ARGS}"
+    "${MULTI_VAL_ARGS}"
+    ${ARGN}
+  )
+  get_property (DOCS GLOBAL PROPERTY CARLA_TARGET_DOCS)
+  string (APPEND DOCS "- ${ARG_NAME}\n")
+  if (NOT ${ARG_TYPE} STREQUAL "")
+    string (APPEND DOCS "\t- Type: ${ARG_TYPE}\n")
+  endif ()
+  if (NOT ${ARG_DOCS_BRIEF} STREQUAL "")
+    string (APPEND DOCS "\t- Description: ${ARG_DOCS_BRIEF}\n")
+  endif ()
+  set_property (GLOBAL PROPERTY CARLA_TARGET_DOCS ${DOCS})
+endfunction ()
+
+
+
+function (carla_get_target_docs OUT_VAR)
+  get_property (DOCS GLOBAL PROPERTY CARLA_TARGET_DOCS)
+  set (${OUT_VAR} ${DOCS})
+  return (PROPAGATE ${OUT_VAR})
+endfunction ()
+
+
+
+function (carla_add_library NAME DESCRIPTION)
+  carla_add_target_docs (
+    NAME ${NAME}
+    TYPE Library
+    DOCS_BRIEF ${DESCRIPTION}
+  )
+  add_library (${NAME} ${ARGN})
+endfunction ()
+
+
+
+function (carla_add_executable NAME DESCRIPTION)
+  carla_add_target_docs (
+    NAME ${NAME}
+    TYPE Executable
+    DOCS_BRIEF ${DESCRIPTION}
+  )
+  add_executable (${NAME} ${ARGN})
+endfunction ()
+
+
+
+function (carla_add_custom_target NAME DESCRIPTION)
+  carla_add_target_docs (
+    NAME ${NAME}
+    TYPE CustomTarget
+    DOCS_BRIEF ${DESCRIPTION}
+  )
+  add_custom_target (${NAME} ${ARGN})
+endfunction ()
+
+
+
+carla_add_target_docs (
+  NAME clean
+  TYPE Builtin
+  DOCS_BRIEF "Removes all build directories and files."
+)
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 9170d32c5..3a8232dc6 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -73,8 +73,6 @@ include (${CARLA_WORKSPACE_PATH}/CMake/Options.cmake)
 include (${CARLA_WORKSPACE_PATH}/CMake/Common.cmake)
 include (${CARLA_WORKSPACE_PATH}/CMake/Dependencies.cmake)
 
-
-
 if (BUILD_CARLA_CLIENT OR BUILD_CARLA_SERVER)
   add_subdirectory (LibCarla)
 endif ()
@@ -99,3 +97,28 @@ endif ()
 if (BUILD_EXAMPLES)
   add_subdirectory (Examples)
 endif ()
+
+carla_add_custom_target (
+  carla-help
+  "Display this message."
+  COMMAND ${CMAKE_COMMAND} -E cat "${CMAKE_CURRENT_BINARY_DIR}/Help.md"
+)
+
+carla_get_option_docs (CARLA_OPTION_DOCS)
+carla_get_target_docs (CARLA_TARGET_DOCS)
+set (CARLA_CMAKE_HELP_MESSAGE)
+string (
+  APPEND 
+  CARLA_CMAKE_HELP_MESSAGE
+  "# CARLA - CMake Help\n"
+  "## CMake Targets\n"
+  "${CARLA_TARGET_DOCS}\n"
+  "## CMake Options\n"
+  "${CARLA_OPTION_DOCS}\n"
+)
+
+file (
+  WRITE
+  ${CMAKE_CURRENT_BINARY_DIR}/Help.md
+  ${CARLA_CMAKE_HELP_MESSAGE}
+)
diff --git a/Examples/CppClient/CMakeLists.txt b/Examples/CppClient/CMakeLists.txt
index 343ed24b2..4ce087545 100644
--- a/Examples/CppClient/CMakeLists.txt
+++ b/Examples/CppClient/CMakeLists.txt
@@ -1,7 +1,8 @@
 project (carla-example-cpp-client)
 
-add_executable (
+carla_add_executable (
   carla-example-cpp-client
+  "Build the CARLA C++ client example."
   main.cpp
 )
 
diff --git a/LibCarla/CMakeLists.txt b/LibCarla/CMakeLists.txt
index 7325ae497..e6ccfce9f 100644
--- a/LibCarla/CMakeLists.txt
+++ b/LibCarla/CMakeLists.txt
@@ -108,8 +108,9 @@ if (BUILD_CARLA_SERVER)
     ${LIBCARLA_THIRD_PARTY_SOURCE_PATH}/pugixml/*.hpp
   )
 
-  add_library (
+  carla_add_library (
     carla-server
+    "Build the CARLA server."
     ${LIBCARLA_SERVER_HEADERS}
     ${LIBCARLA_SERVER_SOURCES}
     ${LIBCARLA_SERVER_HEADERS_THIRD_PARTY}
@@ -264,8 +265,9 @@ if (BUILD_CARLA_CLIENT)
     ${LIBCARLA_THIRD_PARTY_SOURCE_PATH}/pugixml/*.cpp
   )
 
-  add_library (
+  carla_add_library (
     carla-client
+    "Build the CARLA client."
     ${LIBCARLA_CLIENT_HEADERS}
     ${LIBCARLA_CLIENT_SOURCES}
     ${LIBCARLA_CLIENT_HEADERS_THIRD_PARTY}
@@ -300,12 +302,3 @@ if (BUILD_CARLA_CLIENT)
   )
 
 endif ()
-
-add_custom_target (
-  carla-server-package
-)
-
-add_dependencies (
-  carla-server-package
-  carla-server
-)
diff --git a/PythonAPI/CMakeLists.txt b/PythonAPI/CMakeLists.txt
index 7f95a2dfb..4cec22528 100644
--- a/PythonAPI/CMakeLists.txt
+++ b/PythonAPI/CMakeLists.txt
@@ -81,8 +81,9 @@ else ()
   )
 endif ()
 
-add_custom_target (
+carla_add_custom_target (
   carla-python-api
+  "Build the CARLA Python API."
   COMMAND
     ${CMAKE_COMMAND}
       -E copy
@@ -96,8 +97,9 @@ add_custom_target (
   USES_TERMINAL
 )
 
-add_custom_target (
+carla_add_custom_target (
   carla-python-api-install
+  "Build & install the CARLA Python API"
   COMMAND
     ${Python3_EXECUTABLE}
       -m pip install
diff --git a/Ros2Native/CMakeLists.txt b/Ros2Native/CMakeLists.txt
index 4920935f0..bf03f7759 100644
--- a/Ros2Native/CMakeLists.txt
+++ b/Ros2Native/CMakeLists.txt
@@ -1,6 +1,6 @@
 cmake_minimum_required (VERSION 3.28.0)
 
-project(carla-ros2-native-project)
+project (carla-ros2-native-project)
 
 include (ExternalProject)
 
@@ -29,7 +29,7 @@ ExternalProject_add (
   DEPENDS foonathan_memory fastcdr
 )
 
-ExternalProject_Add(
+ExternalProject_Add (
   carla-ros2-native-lib
   DEPENDS fastdds
   SOURCE_DIR ${PROJECT_SOURCE_DIR}/LibCarlaRos2Native
@@ -37,16 +37,20 @@ ExternalProject_Add(
 )
 
 set (CARLA_PLUGIN_BINARY_PATH ${CMAKE_SOURCE_DIR}/Unreal/CarlaUnreal/Plugins/Carla/Binaries/Linux)
-make_directory(${CARLA_PLUGIN_BINARY_PATH})
-add_custom_command(
-    TARGET carla-ros2-native-lib
-    POST_BUILD
-    COMMAND ${CMAKE_COMMAND} -E copy
-      ${PROJECT_INSTALL_PATH}/lib/*.so*
-      ${CARLA_PLUGIN_BINARY_PATH}
+
+make_directory (${CARLA_PLUGIN_BINARY_PATH})
+
+add_custom_command (
+  TARGET carla-ros2-native-lib
+  POST_BUILD
+  COMMAND
+    ${CMAKE_COMMAND} -E copy
+    ${PROJECT_INSTALL_PATH}/lib/*.so*
+    ${CARLA_PLUGIN_BINARY_PATH}
 )
 
-add_custom_target (
+carla_add_custom_target (
   carla-ros2-native
+  "Build the ROS2-Native CARLA subproject."
   DEPENDS carla-ros2-native-lib
-)
\ No newline at end of file
+)
diff --git a/Ros2Native/LibCarlaRos2Native/CMakeLists.txt b/Ros2Native/LibCarlaRos2Native/CMakeLists.txt
index 3f9ce83c9..a9d211ecc 100644
--- a/Ros2Native/LibCarlaRos2Native/CMakeLists.txt
+++ b/Ros2Native/LibCarlaRos2Native/CMakeLists.txt
@@ -22,7 +22,9 @@ file (
     ${LIBCARLA_SOURCE_PATH}/carla/ros2/types/*.h
 )
 
-add_library (carla-ros2-native SHARED
+add_library (
+    carla-ros2-native
+    SHARED
     ${LIBCARLA_ROS2_HEADERS}
     ${LIBCARLA_ROS2_SOURCES}
 )
@@ -43,4 +45,4 @@ target_compile_definitions (carla-ros2-native PUBLIC
 target_link_libraries(carla-ros2-native
   ${CMAKE_INSTALL_PREFIX}/lib/libfastrtps.so)
 
-install (TARGETS carla-ros2-native DESTINATION lib)
\ No newline at end of file
+install (TARGETS carla-ros2-native DESTINATION lib)
diff --git a/Unreal/CMakeLists.txt b/Unreal/CMakeLists.txt
index 5904536d4..da3511a41 100644
--- a/Unreal/CMakeLists.txt
+++ b/Unreal/CMakeLists.txt
@@ -8,7 +8,8 @@ project (
     "Open-source simulator for autonomous driving research."
 )
 
-option(ENABLE_DIRECTORY_CLEAN
+carla_option (
+  ENABLE_DIRECTORY_CLEAN
   "Enable ADDITIONAL_CLEAN_FILES on directory level"
   ON
 )
@@ -295,8 +296,9 @@ file (
 
 
 
-add_custom_target (
+carla_add_custom_target (
   carla-unreal
+  "Build the CarlaUnreal subproject."
   COMMAND
     ${CARLA_UE_BUILD_COMMAND_PREFIX} 
     CarlaUnreal
@@ -316,8 +318,9 @@ add_dependencies (
   ${UE_DEPENDENCIES_ORDER_ONLY}
 )
 
-add_custom_target (
+carla_add_custom_target (
   carla-unreal-editor
+  "Build the CarlaUnrealEditor subproject."
   COMMAND
     ${CARLA_UE_BUILD_COMMAND_PREFIX} 
     CarlaUnrealEditor
@@ -337,9 +340,13 @@ add_dependencies (
   ${UE_DEPENDENCIES_ORDER_ONLY}
 )
 
-function(add_carla_ue_package_target TARGET_NAME_SUFFIX UE_BUILD_CONFIGURATION)
-  add_custom_target (
+function (add_carla_ue_package_target PACKAGE_CONFIGURATION UE_BUILD_CONFIGURATION)
+  if (NOT "${PACKAGE_CONFIGURATION}" STREQUAL "")
+    set (TARGET_NAME_SUFFIX -${PACKAGE_CONFIGURATION})
+  endif ()
+  carla_add_custom_target (
     carla-unreal-package${TARGET_NAME_SUFFIX}
+    "Create a CARLA package in ${PACKAGE_CONFIGURATION} mode."
     COMMAND
       ${CARLA_UE_BUILD_COMMAND_PREFIX}
       CarlaUnreal
@@ -371,8 +378,8 @@ function(add_carla_ue_package_target TARGET_NAME_SUFFIX UE_BUILD_CONFIGURATION)
       VERBATIM
     )
 
-  set(CARLA_TARGET_PACKAGE_PATH ${CARLA_PACKAGE_PATH}/${UE_SYSTEM_NAME})
-  add_custom_command(
+  set (CARLA_TARGET_PACKAGE_PATH ${CARLA_PACKAGE_PATH}/${UE_SYSTEM_NAME})
+  add_custom_command (
     TARGET carla-unreal-package${TARGET_NAME_SUFFIX}
     POST_BUILD
     COMMAND ${CMAKE_COMMAND} -E echo "********** PACKAGE CREATING VERSION FILE UNREAL PACKAGE EXTRA FILES STARTED **********"
@@ -411,8 +418,9 @@ function(add_carla_ue_package_target TARGET_NAME_SUFFIX UE_BUILD_CONFIGURATION)
     ${UE_DEPENDENCIES_ORDER_ONLY}
   )
 
-  add_custom_target (
+  carla_add_custom_target (
     package${TARGET_NAME_SUFFIX}
+    "Create a CARLA package in ${PACKAGE_CONFIGURATION} mode."
   )
 
   add_dependencies (
@@ -424,11 +432,11 @@ endfunction()
 # Docs for UE5 build configurations:
 # https://docs.unrealengine.com/4.27/en-US/ProductionPipelines/DevelopmentSetup/BuildConfigurations/
 add_carla_ue_package_target("" Shipping)
-add_carla_ue_package_target(-Shipping Shipping)
-add_carla_ue_package_target(-Debug Debug)
-add_carla_ue_package_target(-DebugGame DebugGame)
-add_carla_ue_package_target(-Development Development)
-add_carla_ue_package_target(-Test Test)
+add_carla_ue_package_target(Shipping Shipping)
+add_carla_ue_package_target(Debug Debug)
+add_carla_ue_package_target(DebugGame DebugGame)
+add_carla_ue_package_target(Development Development)
+add_carla_ue_package_target(Test Test)
 
 
 
@@ -445,8 +453,9 @@ set (
   VERBATIM
 )
 
-add_custom_target (
+carla_add_custom_target (
   launch
+  "Build and open CARLA in the Unreal Editor."
   ${CARLA_LAUNCH_TARGET_OPTIONS}
 )
 
@@ -462,8 +471,9 @@ else ()
   )
 endif ()
 
-add_custom_target (
-  prelaunch-content-check
+carla_add_custom_target (
+  check-unreal-content
+  "Perform some basic checks to ensure that the CARLA Unreal Editor will not open without its assets."
   COMMAND
     ${PRELAUNCH_CONTENT_CHECK_COMMAND}
   COMMENT
@@ -475,20 +485,22 @@ add_custom_target (
 add_dependencies (
   launch
   carla-unreal-editor
-  prelaunch-content-check
+  check-unreal-content
 )
 
-add_custom_target (
+carla_add_custom_target (
   launch-only
+  "Open CARLA in the Unreal Editor. This will not rebuild outdated targets."
   ${CARLA_LAUNCH_TARGET_OPTIONS}
 )
 
 add_dependencies (
   launch-only
-  prelaunch-content-check
+  check-unreal-content
 )
 
-set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES  
+set_property (
+  DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES  
   "${CARLA_UE_PATH}/Binaries" 
   "${CARLA_UE_PATH}/Intermediate"
   "${CARLA_UE_PATH}/Saved"
@@ -500,5 +512,5 @@ set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES
   "${CARLA_UE_CARLA_PATH}/Saved"
   "${CARLA_BUILD_PATH}/Package"
   "${CARLA_BUILD_PATH}/PythonAPI/dist"
-  )
+)
 
diff --git a/osm-world-renderer/CMakeLists.txt b/osm-world-renderer/CMakeLists.txt
index d62938bd4..df5777faf 100644
--- a/osm-world-renderer/CMakeLists.txt
+++ b/osm-world-renderer/CMakeLists.txt
@@ -11,8 +11,9 @@ set (
   ${CARLA_WORKSPACE_PATH}/osm-world-renderer/OsmRenderer
 )
 
-add_library (
+carla_add_library (
   lib-osm-map-renderer
+  "Build OSM-Map-Renderer."
   ${OSM_RENDERER_SOURCE_PATH}/src/OsmRenderer.cpp
   ${OSM_RENDERER_SOURCE_PATH}/src/MapDrawer.cpp
   ${OSM_RENDERER_SOURCE_PATH}/src/MapRasterizer.cpp
@@ -32,8 +33,9 @@ target_include_directories (
   ${OSM_RENDERER_SOURCE_PATH}/include
 )
 
-add_executable (
+carla_add_executable (
   osm-world-renderer
+  "Build OSM-World-Renderer."
   ${OSM_RENDERER_SOURCE_PATH}/main.cpp
 )