Fix #1289, cmake script modernization

Use target properties to define interfaces and compiler definitions
rather than referencing global variables or using "known" paths in
other modules.  This better aligns with current practices and creates
a more robust build environment that is less dependent on specific path
names existing in a given module.

This adds an "osal_public_api" interface target that contains the paths
to the public API headers as its INTERFACE_INCLUDE_DIRECTORIES and any
required compiler definitions as its INTERFACE_COMPILE_DEFINITIONS
property.  Applications should use this rather than referring to the
"${OSAL_SOURCE_DIR}/src/os/inc" include path directly.

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.

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