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.

examples/CMakeLists.txt

@@ -1,7 +1,7 @@
 #
 # CMakeLists.txt used to build example apps by the CMake build system
 #
-# Copyright 2020-2023 by Bill Spitzak and others.
+# Copyright 2020-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,11 +15,11 @@
 #
 ################################################################################
 
-include (../CMake/fl_create_example.cmake)
-include (../CMake/FLTK-Functions.cmake)
+include(../CMake/fl_create_example.cmake)
+include(../CMake/FLTK-Functions.cmake)
 
-set (EXECUTABLE_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/../bin/examples)
-file (MAKE_DIRECTORY ${EXECUTABLE_OUTPUT_PATH})
+set(EXECUTABLE_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/../bin/examples)
+file(MAKE_DIRECTORY ${EXECUTABLE_OUTPUT_PATH})
 
 ################################################################################
 
@@ -30,7 +30,7 @@ file (MAKE_DIRECTORY ${EXECUTABLE_OUTPUT_PATH})
 # simple examples w/o extra libs
 ############################################################
 
-set (SIMPLE_SOURCES
+set(SIMPLE_SOURCES
   browser-simple
   callbacks
   chart-simple
@@ -75,7 +75,7 @@ set (SIMPLE_SOURCES
 # simple FLUID examples w/o extra libs
 ############################################################
 
-set (FLUID_SOURCES
+set(FLUID_SOURCES
   fluid-callback
 )
 
@@ -83,7 +83,7 @@ set (FLUID_SOURCES
 # examples requiring fltk_images
 ############################################################
 
-set (IMAGE_SOURCES
+set(IMAGE_SOURCES
   animgifimage
   animgifimage-play
   animgifimage-resize
@@ -95,7 +95,7 @@ set (IMAGE_SOURCES
 # examples requiring cairo
 ############################################################
 
-set (CAIRO_SOURCES
+set(CAIRO_SOURCES
   cairo-draw-x
 )
 
@@ -103,7 +103,7 @@ set (CAIRO_SOURCES
 # examples requiring OpenGL + libGLEW
 ############################################################
 
-set (OPENGL_SOURCES
+set(OPENGL_SOURCES
   OpenGL3-glut-test
   OpenGL3test
 )
@@ -112,42 +112,42 @@ set (OPENGL_SOURCES
 # create simple example programs
 ############################################################
 
-foreach (src ${SIMPLE_SOURCES})
-  CREATE_EXAMPLE (${src} ${src}.cxx fltk)
-endforeach (src)
+foreach(src ${SIMPLE_SOURCES})
+  fl_create_example(${src} ${src}.cxx fltk)
+endforeach(src)
 
 ############################################################
 # create FLUID example programs
 ############################################################
 
-foreach (src ${FLUID_SOURCES})
-  CREATE_EXAMPLE (${src} ${src}.fl fltk)
-endforeach (src)
+foreach(src ${FLUID_SOURCES})
+  fl_create_example(${src} ${src}.fl fltk)
+endforeach(src)
 
 ############################################################
 # create example programs with fltk_images library
 ############################################################
 
-foreach (src ${IMAGE_SOURCES})
-  CREATE_EXAMPLE (${src} ${src}.cxx "fltk_images;fltk")
-endforeach (src)
+foreach(src ${IMAGE_SOURCES})
+  fl_create_example(${src} ${src}.cxx "fltk_images;fltk")
+endforeach(src)
 
 ############################################################
 # create example programs requiring cairo
 ############################################################
 
-if (FLTK_HAVE_CAIRO)
-  set (cairo_libs "fltk;cairo")
-  if (TARGET fltk_cairo)
-    set (cairo_libs fltk_cairo ${cairo_libs})
-  endif ()
-else ()
+if(FLTK_HAVE_CAIRO)
+  set(cairo_libs "fltk;cairo")
+  if(TARGET fltk_cairo)
+    set(cairo_libs fltk_cairo ${cairo_libs})
+  endif()
+else()
   set(cairo_libs "fltk")
-endif ()
+endif()
 
-foreach (src ${CAIRO_SOURCES})
-  CREATE_EXAMPLE (${src} ${src}.cxx "${cairo_libs}")
-endforeach (src)
+foreach(src ${CAIRO_SOURCES})
+  fl_create_example(${src} ${src}.cxx "${cairo_libs}")
+endforeach(src)
 
 ############################################################
 # create example programs with OpenGL + libGLEW
@@ -155,25 +155,25 @@ endforeach (src)
 
 # Note: macOS does not need libGLEW
 
-if (APPLE AND (NOT OPTION_APPLE_X11))
-  if (NOT LIB_GLEW)
-    set (LIB_GLEW TRUE)
-  endif ()
-  set (REQUIRED_LIBS fltk_gl fltk ${OPENGL_LIBRARIES})
-else ()
-  set (REQUIRED_LIBS fltk_gl fltk ${LIB_GLEW} ${OPENGL_LIBRARIES})
-endif ()
+if(APPLE AND NOT FLTK_BACKEND_X11)
+  if(NOT LIB_GLEW)
+    set(LIB_GLEW TRUE)
+  endif()
+  set(REQUIRED_LIBS fltk_gl fltk ${OPENGL_LIBRARIES})
+else()
+  set(REQUIRED_LIBS fltk_gl fltk ${LIB_GLEW} ${OPENGL_LIBRARIES})
+endif()
 
-if (OPENGL_FOUND AND LIB_GLEW)
-  foreach (src ${OPENGL_SOURCES})
-    CREATE_EXAMPLE (${src} ${src}.cxx "${REQUIRED_LIBS}")
-  endforeach (src)
-else ()
-  message (STATUS
+if(OPENGL_FOUND AND LIB_GLEW)
+  foreach(src ${OPENGL_SOURCES})
+    fl_create_example(${src} ${src}.cxx "${REQUIRED_LIBS}")
+  endforeach(src)
+else()
+  message(STATUS
     "OpenGL or libGLEW not present: OpenGL example programs will not be built.")
-  fl_debug_var (OPENGL_FOUND)
-  fl_debug_var (LIB_GLEW)
-  message ("")
-endif (OPENGL_FOUND AND LIB_GLEW)
+  fl_debug_var(OPENGL_FOUND)
+  fl_debug_var(LIB_GLEW)
+  message("")
+endif(OPENGL_FOUND AND LIB_GLEW)
 
-unset (REQUIRED_LIBS)
+unset(REQUIRED_LIBS)

examples/cairo-draw-x.cxx

@@ -59,7 +59,7 @@ int main(int argc, char **argv) {
 int main(int argc, char **argv) {
     fl_message_title("This program needs a Cairo enabled FLTK library");
     fl_message("Please configure FLTK with Cairo enabled (--enable-cairo or --enable-cairoext)\n"
-               "or one of the CMake options OPTION_CAIRO or OPTION_CAIROEXT, respectively.");
+               "or one of the CMake options FLTK_OPTION_CAIRO_WINDOW or FLTK_OPTION_CAIRO_EXT, respectively.");
     return 0;
 }
 #endif // (FLTK_HAVE_CAIRO)

examples/howto-simple-svg.cxx

@@ -55,7 +55,7 @@ const char *svg_logo =
 int main(int argc, char **argv) {
 #ifndef FLTK_USE_SVG
     fl_message("You need to build FLTK with 'configure --enable-svg'\n"
-               "or CMake option 'OPTION_USE_SVG'\n"
+               "or CMake option 'FLTK_OPTION_SVG'\n"
                "to use this example.");
     return(1);
 #else