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.

7 files changed, 9 insertions, 9 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index 3757b65be..95d08c9db 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -1473,8 +1473,8 @@ public:
     \endcode
 
     If you configure FLTK with \c '--enable-cairo' or CMake option
-    \c 'OPTION_CAIRO' (i.e. without \c '--enable-cairoext' or CMake option
-    \c 'OPTION_CAIROEXT') or if you don't enable the \c 'autolink' Cairo
+    \c 'FLTK_OPTION_CAIRO_WINDOW' (i.e. without \c '--enable-cairoext' or CMake option
+    \c 'FLTK_OPTION_CAIRO_EXT') or if you don't enable the \c 'autolink' Cairo
     context you may do the equivalent to use Cairo drawings in an
     overridden draw() method of derived classes by using
     \code
diff --git a/FL/Fl_Cairo.H b/FL/Fl_Cairo.H
index 03c3c1cfe..cf43de421 100644
--- a/FL/Fl_Cairo.H
+++ b/FL/Fl_Cairo.H
@@ -51,7 +51,7 @@
   For internal use only.
   \note Only available when configure has the --enable-cairo or
        --enable-cairoext option or one or both of the CMake options
-       OPTION_CAIRO or OPTION_CAIROEXT is set (ON)
+       FLTK_OPTION_CAIRO_WINDOW or FLTK_OPTION_CAIRO_EXT is set (ON)
 */
 class FL_EXPORT Fl_Cairo_State {
 public:
diff --git a/FL/Fl_Cairo_Window.H b/FL/Fl_Cairo_Window.H
index 567fc228c..ebffb51ce 100644
--- a/FL/Fl_Cairo_Window.H
+++ b/FL/Fl_Cairo_Window.H
@@ -78,7 +78,7 @@
   \see test/cairo_test.cxx
 
   \note Class Fl_Cairo_Window requires the FLTK library to have been built with
-  CMake option OPTION_CAIRO or configure --enable-cairo.
+  CMake option FLTK_OPTION_CAIRO_WINDOW or configure --enable-cairo.
 
   \note You can alternatively define your custom Cairo FLTK window,
   and thus at least override the draw() method to provide custom Cairo
diff --git a/FL/Fl_Native_File_Chooser.H b/FL/Fl_Native_File_Chooser.H
index 721d0c1f4..92e21a98e 100644
--- a/FL/Fl_Native_File_Chooser.H
+++ b/FL/Fl_Native_File_Chooser.H
@@ -1,8 +1,8 @@
 //
 // FLTK native OS file chooser widget
 //
-// Copyright 1998-2016 by Bill Spitzak and others.
 // Copyright 2004 Greg Ercolano.
+// Copyright 2005-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
@@ -108,7 +108,7 @@ class Fl_Native_File_Chooser_Driver;
  not turned off, the \p zenity -based dialog opens. This is expected to be more appropriate
  than other dialog forms for sandboxed apps.
  -# Else if the app runs under the KDE desktop and if command \p kdialog is available at run-time
- and if the library was not built with <tt>cmake -DOPTION_USE_KDIALOG=Off</tt>, the
+ and if the library was not built with <tt>cmake -D FLTK_USE_KDIALOG=OFF</tt>, the
  \p kdialog -based dialog opens.
  -# Else if the GTK library is available at run-time on the computer and if \p Fl::option(OPTION_FNFC_USES_GTK) is
  not turned off, the GTK-styled dialog opens. Call fl_register_images() to add  a "Preview" button to this dialog.
diff --git a/FL/Fl_Printer.H b/FL/Fl_Printer.H
index 4a3f9177b..7da0f1da5 100644
--- a/FL/Fl_Printer.H
+++ b/FL/Fl_Printer.H
@@ -75,7 +75,7 @@
  <li>If the GTK library is available at run-time, class Fl_Printer runs GTK's printer dialog which allows to set
  printer, paper size and orientation.
  <li>Under the KDE desktop, Fl_Printer runs the <tt>kdialog</tt> command to create KDE-styled file dialogs if
- that command is available at run-time, unless FLTK was built with CMake and option OPTION_USE_KDIALOG turned off.
+ that command is available at run-time, unless FLTK was built with CMake and option FLTK_USE_KDIALOG turned off.
  In that case, Fl_Printer attempts to run the GTK dialog.
  <li>If the GTK library is not available, or if Fl::option(Fl::OPTION_PRINTER_USES_GTK) has been turned off,
  class Fl_Printer runs FLTK's print dialog.
diff --git a/FL/Fl_Table.H b/FL/Fl_Table.H
index 1adc29255..746b3a37d 100644
--- a/FL/Fl_Table.H
+++ b/FL/Fl_Table.H
@@ -24,7 +24,7 @@
 
 // EXPERIMENTAL
 // We use either std::vector or the private class Fl_Int_Vector
-// depending on the build option OPTION_USE_STD or --enable-use_std.
+// depending on the build option FLTK_OPTION_STD or --enable-use_std.
 // This option allows to use std::string and std::vector in FLTK 1.4.x
 
 #if (FLTK_USE_STD)
diff --git a/FL/x11.H b/FL/x11.H
index a79cf38f8..c3473020b 100644
--- a/FL/x11.H
+++ b/FL/x11.H
@@ -38,7 +38,7 @@ extern Window fl_x11_xid(const Fl_Window *win);
 extern Fl_Window *fl_x11_find(Window xid);
 /** Returns the X11-specific currently active graphics context.  */
 extern GC fl_x11_gc();
-/** Returns the Cairo-specific currently active graphics context (OPTION_USE_CAIRO=On) */
+/** Returns the Cairo-specific currently active graphics context (FLTK_GRAPHICS_CAIRO=On) */
 extern cairo_t* fl_cairo_gc();
 #else // ! FL_DOXYGEN