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>
2024-05-15 17:50:06 +02:00 · 2024-05-15 17:50:06 +02:00 · 9f4c8422a8
parent bca3b5abef
commit 9f4c8422a8
11 changed files with 203 additions and 64 deletions
--- a/.gitignore
+++ b/.gitignore
@ -9,3 +9,5 @@ Dist/
 out/

 CMakeSettings.json
+
+Help.md
--- 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."
  )
--- 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."
+)
--- 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}
+)
--- 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
 )

--- 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
-)
--- 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
--- 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
-)
+)
--- 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)
+install (TARGETS carla-ros2-native DESTINATION lib)
--- 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"
-  )
+)

--- 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
 )