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, 53 insertions, 26 deletions

diff --git a/CMake/FLTK-Functions.cmake b/CMake/FLTK-Functions.cmake
index 009653721..a8d339fac 100644
--- a/CMake/FLTK-Functions.cmake
+++ b/CMake/FLTK-Functions.cmake
@@ -1,8 +1,8 @@
 #
 # FLTK-Functions.cmake
-# 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
@@ -15,22 +15,37 @@
 #     https://www.fltk.org/bugs.php
 #
 
-#######################################################################
+################################################################################
 # functions used by the build system and exported for the end-user
-#######################################################################
+################################################################################
 
-# USAGE: FLTK_RUN_FLUID TARGET_NAME "FLUID_SOURCE [.. FLUID_SOURCE]"
+################################################################################
+#
+# fltk_run_fluid: Run fluid to compile fluid (.fl) files
+#
+# Usage: fltk_run_fluid(SOURCES "FLUID_SOURCE [.. FLUID_SOURCE]")
+#
+# Input:  The CMake variable "FL_FILES" must contain a list of input
+#         file names. Only names ending in ".fl" are considered and
+#         compiled to their ".cxx" and ".h" files which are stored
+#         in the current build directory.
+#
+# Output: "SOURCES" is used as a CMake variable name that is assigned the
+#         names of the compiled ".cxx" files as a ";" separated list in the
+#         parent scope (the caller's scope).
+#
+################################################################################
 
-function (FLTK_RUN_FLUID TARGET SOURCES)
+function(fltk_run_fluid SOURCES FL_FILES)
 
-  if (NOT FLTK_FLUID_EXECUTABLE)
-    message (WARNING "Not building ${SOURCES}. FLUID executable not found.")
-    return ()
-  endif (NOT FLTK_FLUID_EXECUTABLE)
+  if(NOT FLTK_FLUID_EXECUTABLE)
+    message(WARNING "Not building ${FL_FILES}. FLUID executable not found.")
+    return()
+  endif()
 
-  set (CXX_FILES)
-  foreach (src ${SOURCES})
-    if ("${src}" MATCHES "\\.fl$")
+  set(CXX_FILES)
+  foreach(src ${FL_FILES})
+    if("${src}" MATCHES "\\.fl$")
       string(REGEX REPLACE "(.*).fl" \\1 basename ${src})
       add_custom_command(
         OUTPUT "${basename}.cxx" "${basename}.h"
@@ -38,21 +53,33 @@ function (FLTK_RUN_FLUID TARGET SOURCES)
         DEPENDS ${src}
         MAIN_DEPENDENCY ${src}
       )
-      list (APPEND CXX_FILES "${basename}.cxx")
-    endif ("${src}" MATCHES "\\.fl$")
-  endforeach ()
-  set (${TARGET} ${CXX_FILES} PARENT_SCOPE)
+      list(APPEND CXX_FILES "${basename}.cxx")
+    endif()
+  endforeach()
+  set(${SOURCES} ${CXX_FILES} PARENT_SCOPE)
 
-endfunction (FLTK_RUN_FLUID TARGET SOURCES)
+endfunction(fltk_run_fluid SOURCES FL_FILES)
 
-#######################################################################
 
-# sets the bundle icon for OSX bundles
+################################################################################
+#
+# fltk_set_bundle_icon: Set the bundle icon for macOS bundles
+#
+# This function sets macOS specific target properties. These properties are
+# ignored on other platforms.
+#
+# Usage: fltk_set_bundle_icon(TARGET ICON_PATH)
+#
+# TARGET must be a valid CMake target that has been created before this
+# function is called. It must not be an alias name.
+#
+################################################################################
 
-function (FLTK_SET_BUNDLE_ICON TARGET ICON_PATH)
-  get_filename_component (ICON_NAME "${ICON_PATH}" NAME)
-  set_target_properties ("${TARGET}" PROPERTIES
-    MACOSX_BUNDLE_ICON_FILE "${ICON_NAME}"
-    RESOURCE "${ICON_PATH}"
+function(fltk_set_bundle_icon TARGET ICON_PATH)
+  get_filename_component(ICON_NAME "${ICON_PATH}" NAME)
+  set_target_properties(${TARGET}
+    PROPERTIES
+      MACOSX_BUNDLE_ICON_FILE "${ICON_NAME}"
+      RESOURCE "${ICON_PATH}"
   )
-endfunction (FLTK_SET_BUNDLE_ICON TARGET ICON_PATH)
+endfunction(fltk_set_bundle_icon TARGET ICON_PATH)