Merge pull request #1291 from jphickey/fix-1289-cmake-cleanup

Fix #1289, cmake script modernization
nasa · Oct 11, 2022 · f34f23a · f34f23a
2 parents 310b9f6 + 66f2d4a
commit f34f23a
Show file tree

Hide file tree

Showing 27 changed files with 383 additions and 201 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -4,10 +4,16 @@
 #
 ######################################################################
 #
-# This defines the following static library target(s):
+# This defines the following target(s):
 #
-#         osal   : The main library containing the OSAL binary code
-#                  This is based off the OSAL_SYSTEM_OSTYPE selection
+# osal_public_api : Interface library that refers to the OSAL public API only.
+#                   This may be used for applications that need to use the
+#                   OSAL-provided types (such as common-types.h) but do not
+#                   make any OSAL API calls.
+#
+#         osal   : The main library containing the OSAL binary code.  This is
+#                  the normal library that applications should link to.
+#                  This is built based off the OSAL_SYSTEM_OSTYPE selection
 #
 #     osal_bsp   : The board support library containing the system-
 #                  specific entry point function (e.g. main) and the
@@ -21,14 +27,47 @@
 #                  Linking with this library also links with osal_bsp,
 #                  but not necessarily the osal library itself.
 #
+# ut_coverage_compile : an interface target that contains the
+#                       compiler options/definitions to enable coverage
+#                       instrumentation in the generated objects.  It should
+#                       be specified on files compiled for coverage analysis.
+#
+# ut_coverage_link    : an interface target that contains options/definitions
+#                       and any link libraries to enable coverage instrumentation in
+#                       the final executable.   It should be specified on coverage
+#                       test executable targets.
+#
+#
+# The following options and variables will customize the build:
+#
+# OSAL_SYSTEM_BSPTYPE: Should be set by the caller to indicate the type of
+#                  BSP to build.  This is a minimal platform-specific shim
+#                  layer to aid with startup and shutdown.  This implies a
+#                  value for OSTYPE (see below).
+#
+# OSAL_SYSTEM_OSTYPE: The selected OS abstraction type (posix, vxworks, rtems).
+#                  Normally this setting is not needed to be configured as it is
+#                  inferred from the BSP type.
+#
+# ENABLE_UNIT_TESTS : Boolean, enables build of the unit tests (coverage and functional)
+#
+# OSAL_OMIT_DEPRECATED : Boolean, Compile without deprecated or obsolete features for
+#                  forward compatibility testing.  Any features marked as deprecated
+#                  will be disabled, allowing developers to test software based
+#                  only on currently-supported software features and patterns.
+#
+# OSAL_EXT_SOURCE_DIR : External source directory to check for BSP/OS implementation
+#
 # Additionally the following target is defined if ENABLE_UNIT_TESTS
 # is set TRUE:
 #
 # ut_osapi_stubs : Stub library correlating to the OSAL public API
 #                  This is for unit testing OSAL-based applications
 #                  It operates in conjunction with the ut_assert library.
 #
-# This also exports the following variables:
+# For backward compatibility with previous versions, this also exports the following
+# variables.  Code which is depending on these values should migrate to using the
+# interfaces of the provide ut_coverage_compile/link targets instead.
 #
 #  UT_COVERAGE_COMPILE_FLAGS : Compiler flags that must be used to
 #                  instrument code for coverage testing
@@ -41,8 +80,27 @@
 #
 ######################################################################
 cmake_minimum_required(VERSION 3.5)
+
+# Set the policy dictating use of target_link_libraries across directories
+# Either OLD or NEW should work here but setting it to something avoids a
+# warning when using newer versions of the tool.
+if (CMAKE_VERSION VERSION_GREATER 3.13)
+    cmake_policy(SET CMP0079 NEW)
+endif()
+
 project(OSAL C)
 
+# define a custom property to track relationship between BSP and OS
+# this should be set on BSP "impl" targets to indicate the correct OS impl to go with it
+define_property(TARGET PROPERTY OSAL_EXPECTED_OSTYPE
+    BRIEF_DOCS
+        "The expected OS type for an OSAL BSP implementation"
+    FULL_DOCS
+        "This property is used to indicate the OS implementation layer that is intended to be paired with the BSP implementation"
+)
+
+option(OSAL_OMIT_DEPRECATED   "Compile without deprecated or obsolete features for backward compatibility testing" OFF)
+
 # The "OSAL_EXT_SOURCE_DIR" cache variable may be set to a path
 # on the host containing extra OS/BSP implementations which are not
 # part of the open source release.
@@ -65,26 +123,52 @@ endforeach(CONFIG OSAL_CONFIGURATION_FILE)
 # Use the supplied configuration to generate the osconfig.h file
 # which can be referenced by the code.  This will be stored in the top level
 # "inc" directory of the binary output directory
-file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/inc")
+file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/inc")
 configure_file(
     "${OSAL_SOURCE_DIR}/osconfig.h.in"
-    "${OSAL_BINARY_DIR}/osconfig.gen"
+    "${CMAKE_CURRENT_BINARY_DIR}/osconfig.gen"
     @ONLY
 )
 
 # Only copy the osconfig.h into place if different from the existing file
 # This avoids unnecessarily rebuilding all code in case cmake was re-run
 # and but generated the same file.
 execute_process(COMMAND ${CMAKE_COMMAND} -E copy_if_different
-    "${OSAL_BINARY_DIR}/osconfig.gen"
-    "${CMAKE_BINARY_DIR}/inc/osconfig.h"
+    "${CMAKE_CURRENT_BINARY_DIR}/osconfig.gen"
+    "${CMAKE_CURRENT_BINARY_DIR}/inc/osconfig.h"
 )
 
+# The "osal_public_api" is an interface target that will always be defined by this script,
+# and refers to the complete set of public API header files for OSAL
+add_library(osal_public_api INTERFACE)
+
+# The initial set of directories that define the OSAL API
+# This is used to initialize the interface include directory property of external targets
+target_include_directories(osal_public_api INTERFACE
+    $<BUILD_INTERFACE:${OSAL_SOURCE_DIR}/src/os/inc>
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/inc>
+    $<INSTALL_INTERFACE:include/osal>
+)
+if (OSAL_OMIT_DEPRECATED)
+    target_compile_definitions(osal_public_api INTERFACE OSAL_OMIT_DEPRECATED)
+endif (OSAL_OMIT_DEPRECATED)
+
+
+# OSAL_SYSTEM_BSPTYPE indicate which of the BSP packages
+# to build.  If not defined then no OSAL implementation will be built, however
+# the api interface target (osal_public_api) is still usable.  Therefore
+# this is not considered a fatal error for that reason.  If called with no BSP type,
+# then only the osal_public_api interface target will be defined, and the script ends here.
+if (NOT DEFINED OSAL_SYSTEM_BSPTYPE)
+  message(STATUS "OSAL_SYSTEM_BSPTYPE not defined, no OSAL implementation will be compiled")
+  return()
+endif ()
+
 # The initial set of directories that define the OSAL API
 # This is used to initialize the interface include directory property of external targets
 set(OSAL_API_INCLUDE_DIRECTORIES
     "${OSAL_SOURCE_DIR}/src/os/inc"
-    "${CMAKE_BINARY_DIR}/inc"
+    "${CMAKE_CURRENT_BINARY_DIR}/inc"
 )
 include_directories(${OSAL_API_INCLUDE_DIRECTORIES})
 
@@ -97,20 +181,15 @@ add_definitions(${OSAL_USER_C_FLAGS})
 # but flagged using "EXCLUDE_FROM_ALL" so they won't be built unless actually used.  This
 # is because the library is usable with functional tests, not just unit (coverage) tests.
 # This is done early, so that other targets may reference UT_ASSERT_SOURCE_DIR if needed
+# Note that UT assert is only usable with an OSAL BSP implementation, thus this target
+# cannot be compiled unless a specific BSP is selected.
 add_subdirectory(ut_assert)
 
 #
 # Step 1:
 # Build the BSP layer
 #
 
-
-# OSAL_SYSTEM_BSPTYPE indicate which of the BSP packages
-# to build.  This is required and must be defined. Confirm that this exists
-# and error out now if it does not.
-if (NOT DEFINED OSAL_SYSTEM_BSPTYPE)
-  message(FATAL_ERROR "OSAL_SYSTEM_BSPTYPE must be set to the appropriate BSP")
-endif ()
 if (OSAL_EXT_SOURCE_DIR AND IS_DIRECTORY "${OSAL_EXT_SOURCE_DIR}/${OSAL_SYSTEM_BSPTYPE}")
     set(OSAL_BSP_SOURCE_DIR "${OSAL_EXT_SOURCE_DIR}/${OSAL_SYSTEM_BSPTYPE}")
 elseif(IS_DIRECTORY "${OSAL_SOURCE_DIR}/src/bsp/${OSAL_SYSTEM_BSPTYPE}")
@@ -131,12 +210,20 @@ message(STATUS "BSP Selection: ${OSAL_SYSTEM_BSPTYPE} at ${OSAL_BSP_SOURCE_DIR}"
 # The Implementation-Specific BSP subdirectory should define
 # an OBJECT target named "osal_${OSAL_SYSTEM_BSPTYPE}_impl"
 add_subdirectory(${OSAL_BSP_SOURCE_DIR} ${OSAL_SYSTEM_BSPTYPE}_impl)
+
+target_compile_definitions(osal_${OSAL_SYSTEM_BSPTYPE}_impl PRIVATE
+    $<TARGET_PROPERTY:osal_public_api,INTERFACE_COMPILE_DEFINITIONS>
+)
+target_compile_options(osal_${OSAL_SYSTEM_BSPTYPE}_impl PRIVATE
+    $<TARGET_PROPERTY:osal_public_api,INTERFACE_COMPILE_OPTIONS>
+)
 target_include_directories(osal_${OSAL_SYSTEM_BSPTYPE}_impl PRIVATE
     ${OSAL_SOURCE_DIR}/src/bsp/shared/inc
 )
 
 # Confirm that the selected OS is compatible with the selected BSP.
-if (DEFINED OSAL_EXPECTED_OSTYPE)
+get_target_property(OSAL_EXPECTED_OSTYPE osal_${OSAL_SYSTEM_BSPTYPE}_impl OSAL_EXPECTED_OSTYPE)
+if (OSAL_EXPECTED_OSTYPE)
     if (NOT DEFINED OSAL_SYSTEM_OSTYPE)
         # In the event that OSAL_SYSTEM_OSTYPE was not specified at all,
         # implicitly assume the expected OSTYPE.
@@ -146,29 +233,7 @@ if (DEFINED OSAL_EXPECTED_OSTYPE)
         # Not calling this a fatal error because it could possibly be intended during development
         message(WARNING "Mismatched BSP/OS: ${OSAL_SYSTEM_BSPTYPE} implies ${OSAL_EXPECTED_OSTYPE}, but ${OSAL_SYSTEM_OSTYPE} is configured")
     endif(NOT DEFINED OSAL_SYSTEM_OSTYPE)
-endif (DEFINED OSAL_EXPECTED_OSTYPE)
-
-# Propagate the BSP-specific compile definitions and include directories
-# Apply these to the directory-scope COMPILE_DEFINITIONS  and INCLUDE_DIRECTORIES
-# Note this needs to append to the directory property, not overwrite it.
-get_directory_property(OSAL_BASE_COMPILE_DEFINITIONS COMPILE_DEFINITIONS)
-get_target_property(OSAL_BSP_COMPILE_DEFINITIONS osal_${OSAL_SYSTEM_BSPTYPE}_impl INTERFACE_COMPILE_DEFINITIONS)
-set(OSAL_COMPILE_DEFINITIONS)
-if (OSAL_BASE_COMPILE_DEFINITIONS)
-    list(APPEND OSAL_COMPILE_DEFINITIONS ${OSAL_BASE_COMPILE_DEFINITIONS})
-endif (OSAL_BASE_COMPILE_DEFINITIONS)
-if (OSAL_BSP_COMPILE_DEFINITIONS)
-    list(APPEND OSAL_COMPILE_DEFINITIONS ${OSAL_BSP_COMPILE_DEFINITIONS})
-endif (OSAL_BSP_COMPILE_DEFINITIONS)
-set_directory_properties(PROPERTIES COMPILE_DEFINITIONS "${OSAL_COMPILE_DEFINITIONS}")
-message(STATUS "OSAL Compile Definitions: ${OSAL_COMPILE_DEFINITIONS}")
-
-# The include directories is simpler, as the include_directories() function
-# appends to the directory property
-get_target_property(OSAL_BSP_INCLUDE_DIRECTORIES osal_${OSAL_SYSTEM_BSPTYPE}_impl INTERFACE_INCLUDE_DIRECTORIES)
-if (OSAL_BSP_INCLUDE_DIRECTORIES)
-    include_directories(${OSAL_BSP_INCLUDE_DIRECTORIES})
-endif (OSAL_BSP_INCLUDE_DIRECTORIES)
+endif (OSAL_EXPECTED_OSTYPE)
 
 set(BSP_SRCLIST
     src/bsp/shared/src/osapi-bsp.c
@@ -184,8 +249,8 @@ add_library(osal_bsp STATIC
     $<TARGET_OBJECTS:osal_${OSAL_SYSTEM_BSPTYPE}_impl>
 )
 
-target_include_directories(osal_bsp INTERFACE
-    ${OSAL_API_INCLUDE_DIRECTORIES}
+target_link_libraries(osal_bsp PUBLIC
+    osal_public_api
 )
 
 target_include_directories(osal_bsp PRIVATE
@@ -220,6 +285,12 @@ message(STATUS "OSAL Selection: ${OSAL_SYSTEM_OSTYPE} at ${OSAL_OS_SOURCE_DIR}")
 # an OBJECT target named "osal_${OSAL_SYSTEM_OSTYPE}_impl"
 add_subdirectory(${OSAL_OS_SOURCE_DIR} ${OSAL_SYSTEM_OSTYPE}_impl)
 
+target_compile_definitions(osal_${OSAL_SYSTEM_OSTYPE}_impl PRIVATE
+    $<TARGET_PROPERTY:osal_public_api,INTERFACE_COMPILE_DEFINITIONS>
+)
+target_compile_options(osal_${OSAL_SYSTEM_OSTYPE}_impl PRIVATE
+    $<TARGET_PROPERTY:osal_public_api,INTERFACE_COMPILE_OPTIONS>
+)
 # The "shared" directory contains internal components which
 # are referenced in implementation OSAL modules, but should _NOT_
 # be referenced outside the OSAL code
@@ -269,33 +340,16 @@ add_library(osal STATIC
     $<TARGET_OBJECTS:osal_${OSAL_SYSTEM_OSTYPE}_impl>
 )
 
-target_include_directories(osal INTERFACE
-    ${OSAL_API_INCLUDE_DIRECTORIES}
-)
-
 target_include_directories(osal PRIVATE
     ${OSAL_SOURCE_DIR}/src/os/shared/inc
     ${OSAL_SOURCE_DIR}/src/bsp/shared/inc
 )
 
 # Link the OSAL with the BSP
-target_link_libraries(osal osal_bsp)
-
-# propagate the BSP-specific compile flags to OSAL external library target, if defined
-if (OSAL_BSP_COMPILE_DEFINITIONS)
-    target_compile_definitions(osal INTERFACE
-        ${OSAL_BSP_COMPILE_DEFINITIONS}
-    )
-endif(OSAL_BSP_COMPILE_DEFINITIONS)
-
-# propagate the BSP-specific include directories OSAL all external library target, if defined
-if (OSAL_BSP_INCLUDE_DIRECTORIES)
-    target_include_directories(osal INTERFACE
-        ${OSAL_BSP_INCLUDE_DIRECTORIES}
-    )
-endif(OSAL_BSP_INCLUDE_DIRECTORIES)
-
-
+target_link_libraries(osal PUBLIC
+    osal_public_api
+    osal_bsp
+)
 
 # The "build_options.cmake" file within each component may
 # fine-tune the library for this particular build.  This is included
@@ -304,6 +358,12 @@ endif(OSAL_BSP_INCLUDE_DIRECTORIES)
 include("${OSAL_BSP_SOURCE_DIR}/build_options.cmake" OPTIONAL)
 include("${OSAL_OS_SOURCE_DIR}/build_options.cmake" OPTIONAL)
 
+# Report the full set of compile definitions after processing all modules
+get_target_property(OSAL_PUBLIC_API_COMPILE_DEFINITIONS osal_public_api INTERFACE_COMPILE_DEFINITIONS)
+message(STATUS "OSAL Compile Definitions: ${OSAL_PUBLIC_API_COMPILE_DEFINITIONS}")
+
+
+
 #
 # UNIT TEST SUPPORT
 #
@@ -317,7 +377,7 @@ if (ENABLE_UNIT_TESTS)
     function(add_osal_ut_exe TGTNAME)
 
       add_executable(${TGTNAME} ${ARGN})
-      target_link_libraries(${TGTNAME} ut_assert osal)
+      target_link_libraries(${TGTNAME} PUBLIC ut_assert osal)
       add_test(${TGTNAME} ${TGTNAME})
       foreach(TGT ${INSTALL_TARGET_LIST})
         install(TARGETS ${TGTNAME} DESTINATION ${TGT}/${UT_INSTALL_SUBDIR})
@@ -351,8 +411,10 @@ if (HAS_PARENT)
     # Export the UT coverage compiler/linker flags to the parent build.
     # These flags are based on the target system type and should be used
     # when building code intended for coverage analysis.
-    set(UT_COVERAGE_COMPILE_FLAGS "${UT_COVERAGE_COMPILE_FLAGS}" PARENT_SCOPE)
-    set(UT_COVERAGE_LINK_FLAGS "${UT_COVERAGE_LINK_FLAGS}" PARENT_SCOPE)
+    if (NOT OSAL_OMIT_DEPRECATED)
+        set(UT_COVERAGE_COMPILE_FLAGS "${UT_COVERAGE_COMPILE_FLAGS}" PARENT_SCOPE)
+        set(UT_COVERAGE_LINK_FLAGS "${UT_COVERAGE_LINK_FLAGS}" PARENT_SCOPE)
+    endif()
 else(HAS_PARENT)
     # In a standalone build, also add the documentation target(s)
     # Note that in a CFE/integrated build, it is expected this will be built separately.

diff --git a/docs/src/CMakeLists.txt b/docs/src/CMakeLists.txt
@@ -49,16 +49,35 @@ foreach(SRC ${OSAL_DOCFILE_LIST})
     string(APPEND OSAL_NATIVE_APIGUIDE_SOURCEFILES " \\\n  ${SRC}")
 endforeach()
 
-foreach(DIR ${OSAL_API_INCLUDE_DIRECTORIES})
-    file(GLOB OSAL_HEADERFILE_LIST ${DIR}/*.h)
-    foreach(HDR ${OSAL_HEADERFILE_LIST})
-        list(APPEND OSAL_DOC_DEPENDENCY_LIST ${HDR})
-        file(TO_NATIVE_PATH "${HDR}" HDR)
-        string(APPEND OSAL_NATIVE_APIGUIDE_SOURCEFILES " \\\n  ${HDR}")
-    endforeach()
-    file(TO_NATIVE_PATH "${DIR}" DIR)
-    string(APPEND OSAL_NATIVE_INCLUDE_DIRS " \\\n  ${DIR}")
-endforeach()
+# The complete list of public API include directories may be determined by reading the property of
+# the "osal_public_api" interface target.  However, the CFE documentation build may want to influence
+# this and provide an alternate path, mainly to provide its own alternate version of "osconfig.h" for
+# docs.  It should be preferred to pull this info from the actual source such that it will track any
+# changes made within OSAL as far as header organization goes.
+if (TARGET osal_public_api AND NOT OSAL_API_INCLUDE_DIRECTORIES)
+    get_target_property(OSAL_API_INCLUDE_DIRECTORIES osal_public_api INTERFACE_INCLUDE_DIRECTORIES)
+    if (NOT OSAL_API_INCLUDE_DIRECTORIES)
+        set (OSAL_API_INCLUDE_DIRECTORIES)
+    endif()
+    get_target_property(OSAL_API_COMPILE_DEFINITIONS osal_public_api INTERFACE_COMPILE_DEFINITIONS)
+    if (NOT OSAL_API_COMPILE_DEFINITIONS)
+        set (OSAL_API_COMPILE_DEFINITIONS)
+    endif()
+endif ()
+
+# Generate the list of actual header files from the directories specified.  This is done
+# as a target that runs a separate script such that generator expressions can be evaluated.
+# This is done as a custom target such that it runs and gets updated every build
+add_custom_target(osal_public_api_headerlist 
+    COMMAND ${CMAKE_COMMAND}
+        -DINCLUDE_DIRECTORIES="${OSAL_API_INCLUDE_DIRECTORIES}"
+        -DCOMPILE_DEFINITIONS="${OSAL_API_COMPILE_DEFINITIONS}"
+        -DINPUT_TEMPLATE="${CMAKE_CURRENT_SOURCE_DIR}/osal-public-api.doxyfile.in"
+        -DOUTPUT_FILE="${CMAKE_BINARY_DIR}/docs/osal-public-api.doxyfile"
+        -P "${CMAKE_CURRENT_SOURCE_DIR}/generate-public-api-doxyfile.cmake"
+    BYPRODUCTS "${CMAKE_BINARY_DIR}/docs/osal-public-api.doxyfile"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+)
 
 file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide-warnings.log OSAL_NATIVE_LOGFILE)
 file(TO_NATIVE_PATH ${CMAKE_BINARY_DIR}/docs/osal-common.doxyfile OSAL_NATIVE_COMMON_CFGFILE)
@@ -85,7 +104,9 @@ configure_file(
 
 add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
     COMMAND doxygen ${OSAL_NATIVE_APIGUIDE_CFGFILE}
-    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile ${CMAKE_BINARY_DIR}/docs/osal-common.doxyfile
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile"
+            "${CMAKE_BINARY_DIR}/docs/osal-common.doxyfile"
+            "${CMAKE_BINARY_DIR}/docs/osal-public-api.doxyfile"
             ${OSAL_DOCFILE_LIST} ${OSAL_DOC_DEPENDENCY_LIST}
     WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
 )