Introduce "Modern CMake" in FLTK

This is a big commit and there are too many changes to list them all.
The main changes are:

- rename all CMake build options to 'FLTK_*'
- export library targets with namespace (prefix) 'fltk::'
- standardize shared library target names with suffix '-shared'
- set public build properties on libraries for consumers
- document library names and aliases in README.CMake.txt
- document changes in "Migrating Code from FLTK 1.3 to 1.4"
- partial backwards compatibility for old user projects

Included but not directly related changes:

- fix Windows (Visual Studio) DLL build
- add CMake function fl_debug_target() to show target properties
- don't build test programs if FLTK is a subproject
- internal: reformat CMake code: remove space before '('

Thanks to Matthias and Manolo for their help, testing, and feeback.

1 files changed, 93 insertions, 90 deletions

diff --git a/CMake/resources.cmake b/CMake/resources.cmake
index aa17f73b3..7ee2c665d 100644
--- a/CMake/resources.cmake
+++ b/CMake/resources.cmake
@@ -1,8 +1,8 @@
 #
 # Resource definitions to build the FLTK project using CMake (www.cmake.org)
-# Written by Michael Surette
+# Originally written by Michael Surette
 #
-# Copyright 1998-2021 by Bill Spitzak and others.
+# Copyright 1998-2024 by Bill Spitzak and others.
 #
 # This library is free software. Distribution and use rights are outlined in
 # the file "COPYING" which should have been included with this file.  If this
@@ -24,34 +24,37 @@
 # and the result of the search is logged with fl_debug_var().
 # This is useful for debugging.
 
-set (CMAKE_REQUIRED_QUIET 1)
+set(CMAKE_REQUIRED_QUIET 1)
 
-include (CheckIncludeFiles)
+include(CheckIncludeFiles)
 
 macro (fl_find_header VAR HEADER)
-  check_include_files ("${HEADER}" ${VAR})
-  if (NOT CMAKE_REQUIRED_QUIET)
-    fl_debug_var (${VAR})
-  endif (NOT CMAKE_REQUIRED_QUIET)
+  check_include_files("${HEADER}" ${VAR})
+  if(NOT CMAKE_REQUIRED_QUIET)
+    fl_debug_var(${VAR})
+  endif(NOT CMAKE_REQUIRED_QUIET)
 endmacro (fl_find_header)
 
 #######################################################################
 # Include FindPkgConfig for later use of pkg-config
 #######################################################################
 
-include (FindPkgConfig)
+include(FindPkgConfig)
 
-# fl_debug_var (PKG_CONFIG_FOUND)
-# fl_debug_var (PKG_CONFIG_EXECUTABLE)
-# fl_debug_var (PKG_CONFIG_VERSION_STRING)
+# fl_debug_var(PKG_CONFIG_FOUND)
+# fl_debug_var(PKG_CONFIG_EXECUTABLE)
+# fl_debug_var(PKG_CONFIG_VERSION_STRING)
 
 #######################################################################
 # Find header files...
 #######################################################################
 
-if (${CMAKE_HOST_SYSTEM_NAME} STREQUAL "FreeBSD")
-  list (APPEND CMAKE_REQUIRED_INCLUDES /usr/local/include)
-endif (${CMAKE_HOST_SYSTEM_NAME} STREQUAL "FreeBSD")
+if(${CMAKE_HOST_SYSTEM_NAME} STREQUAL "FreeBSD")
+  list(APPEND CMAKE_REQUIRED_INCLUDES /usr/local/include)
+endif(${CMAKE_HOST_SYSTEM_NAME} STREQUAL "FreeBSD")
+
+# fl_debug_var(CMAKE_HOST_SYSTEM_NAME)
+# fl_debug_var(CMAKE_REQUIRED_INCLUDES)
 
 fl_find_header (HAVE_ALSA_ASOUNDLIB_H alsa/asoundlib.h)
 fl_find_header (HAVE_DLFCN_H dlfcn.h)
@@ -65,23 +68,23 @@ fl_find_header (HAVE_SYS_STDTYPES_H sys/stdtypes.h)
 
 fl_find_header (HAVE_X11_XREGION_H "X11/Xlib.h;X11/Xregion.h")
 
-if (WIN32 AND NOT CYGWIN)
+if(WIN32 AND NOT CYGWIN)
   # we don't use pthreads on Windows (except for Cygwin, see options.cmake)
-  set (HAVE_PTHREAD_H 0)
-else ()
+  set(HAVE_PTHREAD_H 0)
+else()
   fl_find_header (HAVE_PTHREAD_H pthread.h)
-endif (WIN32 AND NOT CYGWIN)
+endif(WIN32 AND NOT CYGWIN)
 
 # Do we have PTHREAD_MUTEX_RECURSIVE ?
 
-if (HAVE_PTHREAD_H)
+if(HAVE_PTHREAD_H)
   try_compile(HAVE_PTHREAD_MUTEX_RECURSIVE
     ${CMAKE_CURRENT_BINARY_DIR}
     ${CMAKE_CURRENT_SOURCE_DIR}/CMake/pthread_mutex_recursive.c
   )
-else ()
-  set (HAVE_PTHREAD_MUTEX_RECURSIVE 0)
-endif ()
+else()
+  set(HAVE_PTHREAD_MUTEX_RECURSIVE 0)
+endif()
 
 # Special case for Microsoft Visual Studio generator (MSVC):
 #
@@ -94,19 +97,19 @@ endif ()
 #
 # Note: these cache variables can only be seen in "advanced" mode.
 
-if (MSVC)
+if(MSVC)
 
-  if (NOT HAVE_GL_GLU_H)
-    message (STATUS "Info: Header file GL/glu.h was not found. Continuing...")
-    set (HAVE_GL_GLU_H 1)
-  endif (NOT HAVE_GL_GLU_H)
+  if(NOT HAVE_GL_GLU_H)
+    message(STATUS "Info: Header file GL/glu.h was not found. Continuing...")
+    set(HAVE_GL_GLU_H 1)
+  endif(NOT HAVE_GL_GLU_H)
 
-  if (NOT HAVE_LOCALE_H)
-    message (STATUS "Info: Header file locale.h was not found. Continuing...")
-    set (HAVE_LOCALE_H 1)
-  endif (NOT HAVE_LOCALE_H)
+  if(NOT HAVE_LOCALE_H)
+    message(STATUS "Info: Header file locale.h was not found. Continuing...")
+    set(HAVE_LOCALE_H 1)
+  endif(NOT HAVE_LOCALE_H)
 
-endif (MSVC)
+endif(MSVC)
 
 # Simulate the behavior of autoconf macro AC_HEADER_DIRENT, see:
 # https://www.gnu.org/software/autoconf/manual/autoconf-2.69/html_node/Particular-Headers.html
@@ -118,15 +121,15 @@ endif (MSVC)
 
 fl_find_header (HAVE_DIRENT_H dirent.h)
 
-if (NOT HAVE_DIRENT_H)
+if(NOT HAVE_DIRENT_H)
   fl_find_header (HAVE_SYS_NDIR_H sys/ndir.h)
-  if (NOT HAVE_SYS_NDIR_H)
+  if(NOT HAVE_SYS_NDIR_H)
     fl_find_header (HAVE_SYS_DIR_H sys/dir.h)
-    if (NOT HAVE_SYS_DIR_H)
+    if(NOT HAVE_SYS_DIR_H)
       fl_find_header (HAVE_NDIR_H ndir.h)
-    endif (NOT HAVE_SYS_DIR_H)
-  endif (NOT HAVE_SYS_NDIR_H)
-endif (NOT HAVE_DIRENT_H)
+    endif(NOT HAVE_SYS_DIR_H)
+  endif(NOT HAVE_SYS_NDIR_H)
+endif(NOT HAVE_DIRENT_H)
 
 mark_as_advanced (HAVE_ALSA_ASOUNDLIB_H HAVE_DIRENT_H HAVE_DLFCN_H)
 mark_as_advanced (HAVE_GL_GLU_H)
@@ -147,18 +150,18 @@ mark_as_advanced (HAVE_X11_XREGION_H)
 find_path (FREETYPE_PATH freetype.h PATH_SUFFIXES freetype2)
 find_path (FREETYPE_PATH freetype/freetype.h PATH_SUFFIXES freetype2)
 
-if (FREETYPE_PATH)
-  include_directories (${FREETYPE_PATH})
-endif (FREETYPE_PATH)
+if(FREETYPE_PATH)
+  list(APPEND FLTK_BUILD_INCLUDE_DIRECTORIES ${FREETYPE_PATH})
+endif(FREETYPE_PATH)
 
 mark_as_advanced (FREETYPE_PATH)
 
 #######################################################################
 # libraries
 find_library (LIB_dl dl)
-if ((NOT APPLE) OR OPTION_APPLE_X11)
+if((NOT APPLE) OR FLTK_BACKEND_X11)
   find_library (LIB_fontconfig fontconfig)
-endif ((NOT APPLE) OR OPTION_APPLE_X11)
+endif((NOT APPLE) OR FLTK_BACKEND_X11)
 find_library (LIB_freetype freetype)
 find_library (LIB_GL GL)
 find_library (LIB_MesaGL MesaGL)
@@ -173,40 +176,40 @@ mark_as_advanced (LIB_jpeg LIB_png LIB_zlib)
 
 #######################################################################
 # functions
-include (CheckFunctionExists)
+include(CheckFunctionExists)
 
 # save CMAKE_REQUIRED_LIBRARIES (is this really necessary ?)
-if (DEFINED CMAKE_REQUIRED_LIBRARIES)
-  set (SAVED_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
-else (DEFINED CMAKE_REQUIRED_LIBRARIES)
-  unset (SAVED_REQUIRED_LIBRARIES)
-endif (DEFINED CMAKE_REQUIRED_LIBRARIES)
-set (CMAKE_REQUIRED_LIBRARIES)
-
-if (HAVE_DLFCN_H)
-  set (HAVE_DLFCN_H 1)
-endif (HAVE_DLFCN_H)
-
-set (CMAKE_REQUIRED_LIBRARIES ${CMAKE_DL_LIBS})
+if(DEFINED CMAKE_REQUIRED_LIBRARIES)
+  set(SAVED_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
+else(DEFINED CMAKE_REQUIRED_LIBRARIES)
+  unset(SAVED_REQUIRED_LIBRARIES)
+endif(DEFINED CMAKE_REQUIRED_LIBRARIES)
+set(CMAKE_REQUIRED_LIBRARIES)
+
+if(HAVE_DLFCN_H)
+  set(HAVE_DLFCN_H 1)
+endif(HAVE_DLFCN_H)
+
+set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_DL_LIBS})
 CHECK_FUNCTION_EXISTS (dlsym                    HAVE_DLSYM)
-set (CMAKE_REQUIRED_LIBRARIES)
+set(CMAKE_REQUIRED_LIBRARIES)
 
 CHECK_FUNCTION_EXISTS (localeconv               HAVE_LOCALECONV)
 
-if (LIB_png)
-  set (CMAKE_REQUIRED_LIBRARIES ${LIB_png})
+if(LIB_png)
+  set(CMAKE_REQUIRED_LIBRARIES ${LIB_png})
   CHECK_FUNCTION_EXISTS (png_get_valid          HAVE_PNG_GET_VALID)
   CHECK_FUNCTION_EXISTS (png_set_tRNS_to_alpha  HAVE_PNG_SET_TRNS_TO_ALPHA)
-  set (CMAKE_REQUIRED_LIBRARIES)
-endif (LIB_png)
+  set(CMAKE_REQUIRED_LIBRARIES)
+endif(LIB_png)
 
 CHECK_FUNCTION_EXISTS (scandir                  HAVE_SCANDIR)
 CHECK_FUNCTION_EXISTS (snprintf                 HAVE_SNPRINTF)
 
 # not really true but we convert strcasecmp calls to _stricmp calls in flstring.h
-if (MSVC)
-   set (HAVE_STRCASECMP 1)
-endif (MSVC)
+if(MSVC)
+   set(HAVE_STRCASECMP 1)
+endif(MSVC)
 
 CHECK_FUNCTION_EXISTS (strcasecmp               HAVE_STRCASECMP)
 
@@ -214,30 +217,30 @@ CHECK_FUNCTION_EXISTS (strlcat                  HAVE_STRLCAT)
 CHECK_FUNCTION_EXISTS (strlcpy                  HAVE_STRLCPY)
 CHECK_FUNCTION_EXISTS (vsnprintf                HAVE_VSNPRINTF)
 
-if (HAVE_SCANDIR AND NOT HAVE_SCANDIR_POSIX)
-   set (MSG "POSIX compatible scandir")
-   message (STATUS "Looking for ${MSG}")
+if(HAVE_SCANDIR AND NOT HAVE_SCANDIR_POSIX)
+   set(MSG "POSIX compatible scandir")
+   message(STATUS "Looking for ${MSG}")
    try_compile(V
       ${CMAKE_CURRENT_BINARY_DIR}
       ${CMAKE_CURRENT_SOURCE_DIR}/CMake/posixScandir.cxx
       )
-   if (V)
-      message (STATUS "${MSG} - found")
-      set (HAVE_SCANDIR_POSIX 1 CACHE INTERNAL "")
+   if(V)
+      message(STATUS "${MSG} - found")
+      set(HAVE_SCANDIR_POSIX 1 CACHE INTERNAL "")
    else()
-      message (STATUS "${MSG} - not found")
-      set (HAVE_SCANDIR_POSIX HAVE_SCANDIR_POSIX-NOTFOUND)
-   endif (V)
-endif (HAVE_SCANDIR AND NOT HAVE_SCANDIR_POSIX)
+      message(STATUS "${MSG} - not found")
+      set(HAVE_SCANDIR_POSIX HAVE_SCANDIR_POSIX-NOTFOUND)
+   endif(V)
+endif(HAVE_SCANDIR AND NOT HAVE_SCANDIR_POSIX)
 mark_as_advanced (HAVE_SCANDIR_POSIX)
 
 # restore CMAKE_REQUIRED_LIBRARIES (is this really necessary ?)
-if (DEFINED SAVED_REQUIRED_LIBRARIES)
-  set (CMAKE_REQUIRED_LIBRARIES ${SAVED_REQUIRED_LIBRARIES})
-  unset (SAVED_REQUIRED_LIBRARIES)
+if(DEFINED SAVED_REQUIRED_LIBRARIES)
+  set(CMAKE_REQUIRED_LIBRARIES ${SAVED_REQUIRED_LIBRARIES})
+  unset(SAVED_REQUIRED_LIBRARIES)
 else(DEFINED SAVED_REQUIRED_LIBRARIES)
-  unset (CMAKE_REQUIRED_LIBRARIES)
-endif (DEFINED SAVED_REQUIRED_LIBRARIES)
+  unset(CMAKE_REQUIRED_LIBRARIES)
+endif(DEFINED SAVED_REQUIRED_LIBRARIES)
 
 #######################################################################
 # packages
@@ -250,18 +253,18 @@ find_package (Doxygen)
 # Note: we only check existence of `latex' (LATEX_COMPILER), hence
 # building the pdf docs may still fail because of other missing tools.
 
-set (LATEX_FOUND)
-if (DOXYGEN_FOUND)
+set(LATEX_FOUND)
+if(DOXYGEN_FOUND)
   find_package (LATEX)
-  if (LATEX_COMPILER AND NOT LATEX_FOUND)
-    set (LATEX_FOUND YES)
-  endif (LATEX_COMPILER AND NOT LATEX_FOUND)
-endif (DOXYGEN_FOUND)
+  if(LATEX_COMPILER AND NOT LATEX_FOUND)
+    set(LATEX_FOUND YES)
+  endif(LATEX_COMPILER AND NOT LATEX_FOUND)
+endif(DOXYGEN_FOUND)
 
-# message ("Doxygen  found : ${DOXYGEN_FOUND}")
-# message ("LaTex    found : ${LATEX_FOUND}")
-# message ("LaTex Compiler : ${LATEX_COMPILER}")
+# message("Doxygen  found : ${DOXYGEN_FOUND}")
+# message("LaTex    found : ${LATEX_FOUND}")
+# message("LaTex Compiler : ${LATEX_COMPILER}")
 
 # Cleanup: unset local variables
 
-unset (CMAKE_REQUIRED_QUIET)
+unset(CMAKE_REQUIRED_QUIET)