CMake: add examples folder to build (optional)

- replace misnamed option 'OPTION_BUILD_EXAMPLES' with 'FLTK_BUILD_TEST'
- add option 'FLTK_BUILD_EXAMPLES' to build apps in examples folder
- move examples/fltk-versions.cxx to test/fltk-versions.cxx
- [Travis-CI] enable option 'FLTK_BUILD_EXAMPLES' for automatic builds

8 files changed, 181 insertions, 32 deletions

diff --git a/.travis.yml b/.travis.yml
index b56d69436..f8b48fbd5 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -38,10 +38,11 @@ before_script:
   - |
     if [ $TRAVIS_OS_NAME == linux ]; then
        sudo apt-get update -q
-       sudo apt-get install -y libxinerama-dev libxcursor-dev libasound2-dev
+       sudo apt-get install -y libxinerama-dev libxcursor-dev libasound2-dev libglew-dev
        sudo apt-get install -y doxygen
     elif [ $TRAVIS_OS_NAME == osx ]; then
-      brew install ccache # need to install on OSX
+      brew install ccache # need to install on macOS
+      # brew install glew   # libGLEW not needed on macOS
       export PATH="/usr/local/opt/ccache/libexec:$PATH"
       brew install doxygen
     fi
@@ -54,12 +55,12 @@ script:
      make
      mkdir cmake-build
      cd cmake-build
-     cmake -G "Unix Makefiles" ..
+     cmake -G "Unix Makefiles" -D FLTK_BUILD_EXAMPLES=ON ..
      make
    else
      mkdir scan-build
      cd scan-build
-     scan-build cmake -G "Unix Makefiles" ..
+     scan-build cmake -G "Unix Makefiles" -D FLTK_BUILD_EXAMPLES=ON ..
      scan-build -v make
    fi
 
diff --git a/CMake/options.cmake b/CMake/options.cmake
index 0c13fa9a6..0bb2e8762 100644
--- a/CMake/options.cmake
+++ b/CMake/options.cmake
@@ -35,14 +35,14 @@ add_definitions (${OPTION_OPTIM})
 set (OPTION_ARCHFLAGS ""
   CACHE STRING
   "custom architecture flags"
-  )
+)
 add_definitions (${OPTION_ARCHFLAGS})
 
 #######################################################################
 set (OPTION_ABI_VERSION ""
   CACHE STRING
   "FLTK ABI Version FL_ABI_VERSION: 1xxyy for 1.x.y (xx,yy with leading zero)"
-  )
+)
 set (FL_ABI_VERSION ${OPTION_ABI_VERSION})
 
 #######################################################################
@@ -100,15 +100,24 @@ endif (OPTION_USE_POLL)
 
 #######################################################################
 option (OPTION_BUILD_SHARED_LIBS
-  "Build shared libraries(in addition to static libraries)"
+  "Build shared libraries (in addition to static libraries)"
   OFF
-  )
+)
 
 #######################################################################
-option (OPTION_BUILD_EXAMPLES "build example programs" ON)
 option (OPTION_PRINT_SUPPORT "allow print support" ON)
 option (OPTION_FILESYSTEM_SUPPORT "allow file system support" ON)
 
+option (FLTK_BUILD_TEST     "Build test/demo programs" ON)
+option (FLTK_BUILD_EXAMPLES "Build example programs"   OFF)
+
+if (DEFINED OPTION_BUILD_EXAMPLES)
+  message (WARNING
+    "'OPTION_BUILD_EXAMPLES' is obsolete, please use 'FLTK_BUILD_TEST' instead.")
+  message (STATUS
+    "To remove this warning, please delete 'OPTION_BUILD_EXAMPLES' from the CMake cache")
+endif (DEFINED OPTION_BUILD_EXAMPLES)
+
 #######################################################################
 if (DOXYGEN_FOUND)
   option (OPTION_BUILD_HTML_DOCUMENTATION "build html docs" ON)
@@ -307,7 +316,7 @@ if (ZLIB_FOUND)
   set (FLTK_BUILTIN_ZLIB_FOUND FALSE)
 else()
   if (OPTION_USE_SYSTEM_ZLIB)
-    message (STATUS "\ncannot find system zlib library - using built-in\n")
+    message (STATUS "cannot find system zlib library - using built-in\n")
   endif (OPTION_USE_SYSTEM_ZLIB)
 
   add_subdirectory (zlib)
@@ -336,7 +345,7 @@ if (JPEG_FOUND)
   set (FLTK_BUILTIN_JPEG_FOUND FALSE)
 else ()
   if (OPTION_USE_SYSTEM_LIBJPEG)
-    message (STATUS "\ncannot find system jpeg library - using built-in\n")
+    message (STATUS "cannot find system jpeg library - using built-in\n")
   endif (OPTION_USE_SYSTEM_LIBJPEG)
 
   add_subdirectory (jpeg)
@@ -365,7 +374,7 @@ if (PNG_FOUND)
   set (FLTK_BUILTIN_PNG_FOUND FALSE)
 else()
   if (OPTION_USE_SYSTEM_LIBPNG)
-    message (STATUS "\ncannot find system png library - using built-in\n")
+    message (STATUS "cannot find system png library - using built-in\n")
   endif (OPTION_USE_SYSTEM_LIBPNG)
 
   add_subdirectory (png)
diff --git a/CMake/resources.cmake b/CMake/resources.cmake
index f5878e206..a5d4b5ae8 100644
--- a/CMake/resources.cmake
+++ b/CMake/resources.cmake
@@ -156,12 +156,13 @@ find_library (LIB_fontconfig fontconfig)
 find_library (LIB_freetype freetype)
 find_library (LIB_GL GL)
 find_library (LIB_MesaGL MesaGL)
+find_library (LIB_GLEW GLEW)
 find_library (LIB_jpeg jpeg)
 find_library (LIB_png png)
 find_library (LIB_zlib z)
 
 mark_as_advanced (LIB_CAIRO LIB_dl LIB_fontconfig LIB_freetype)
-mark_as_advanced (LIB_GL LIB_MesaGL)
+mark_as_advanced (LIB_GL LIB_MesaGL LIB_GLEW)
 mark_as_advanced (LIB_jpeg LIB_png LIB_zlib)
 
 #######################################################################
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 281d6b440..397ab5b3b 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -118,11 +118,16 @@ configure_file (
 )
 
 #######################################################################
-# build examples - these have to be built after fluid is built/imported
+# options to build test/demo and example programs
 #######################################################################
-if (OPTION_BUILD_EXAMPLES)
-   add_subdirectory (test)
-endif (OPTION_BUILD_EXAMPLES)
+
+if (FLTK_BUILD_TEST)
+  add_subdirectory (test)
+endif (FLTK_BUILD_TEST)
+
+if (FLTK_BUILD_EXAMPLES)
+  add_subdirectory (examples)
+endif (FLTK_BUILD_EXAMPLES)
 
 #######################################################################
 # Android Studio wrapup
diff --git a/README.CMake.txt b/README.CMake.txt
index f64a80a83..b2281c649 100644
--- a/README.CMake.txt
+++ b/README.CMake.txt
@@ -113,8 +113,11 @@ OPTION_BUILD_SHARED_LIBS - default OFF
    Normally FLTK is built as static libraries which makes more portable
    binaries.  If you want to use shared libraries, this will build them too.
 
-OPTION_BUILD_EXAMPLES - default ON
-   Builds the many fine example programs.
+FLTK_BUILD_TEST - default ON
+   Builds the test and demo programs in the 'test' directory.
+
+FLTK_BUILD_EXAMPLES - default OFF
+   Builds the example programs in the 'examples' directory.
 
 OPTION_CAIRO - default OFF
    Enables libcairo support - see README.Cairo.txt.
@@ -138,16 +141,17 @@ OPTION_USE_SYSTEM_LIBPNG - default ON
    use system libraries instead, unless CMake can't find them.  If you set
    any of these options to OFF, then the built in library will be used.
 
-OPTION_USE_NANOSVG - default ON
-   FLTK has a built in nano svg library. Turning this option off
-   disables nano SVG support.
+OPTION_USE_SVG - default ON
+   FLTK has a built in SVG library and can create (write) SVG image files.
+   Turning this option off disables SVG (read and write) support.
 
 OPTION_USE_XINERAMA - default ON
-OPTION_USE_XFT - default ON
-OPTION_USE_XDBE - default ON
-OPTION_USE_XCURSOR - default ON
-OPTION_USE_XRENDER - default ON
-   These are X11 extended libraries.
+OPTION_USE_XFT      - default ON
+OPTION_USE_XDBE     - default ON
+OPTION_USE_XCURSOR  - default ON
+OPTION_USE_XRENDER  - default ON
+   These are X11 extended libraries. These libs are used if found on the
+   build system unless the respective option is turned off.
 
 OPTION_USE_PANGO - default OFF
    Enables use of the Pango library for drawing text. Pango supports all
@@ -173,8 +177,8 @@ OPTION_PRINT_SUPPORT - default ON
 Documentation options: these options are only available if `doxygen' is
    installed and found by CMake. PDF related options require also `latex'.
 
-OPTION_BUILD_HTML_DOCUMENTATION - default OFF
-OPTION_BUILD_PDF_DOCUMENTATION - default OFF
+OPTION_BUILD_HTML_DOCUMENTATION - default ON
+OPTION_BUILD_PDF_DOCUMENTATION  - default ON
    These options can be used to switch HTML documentation generation with
    doxygen on. The build targets ('html', 'pdf', or 'docs') need still to
    be executed explicitly.
@@ -185,7 +189,7 @@ OPTION_INCLUDE_DRIVER_DOCUMENTATION - default OFF
    or advanced users.
 
 OPTION_INSTALL_HTML_DOCUMENTATION - default OFF
-OPTION_INSTALL_PDF_DOCUMENTATION - default OFF
+OPTION_INSTALL_PDF_DOCUMENTATION  - default OFF
    If these options are ON then the HTML and/or PDF docs get installed
    when the 'install' target is executed, e.g. with `make install'. You
    need to select above options OPTION_BUILD_*_DOCUMENTATION as well.
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
new file mode 100644
index 000000000..6dadb17af
--- /dev/null
+++ b/examples/CMakeLists.txt
@@ -0,0 +1,129 @@
+#
+# CMakeLists.txt used to build example apps by the CMake build system
+#
+# Copyright 2020 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
+# file is missing or damaged, see the license at:
+#
+#     https://www.fltk.org/COPYING.php
+#
+# Please see the following page on how to report bugs and issues:
+#
+#     https://www.fltk.org/bugs.php
+#
+################################################################################
+
+include (../CMake/fl_create_example.cmake)
+
+set (EXECUTABLE_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/../bin/examples)
+file (MAKE_DIRECTORY ${EXECUTABLE_OUTPUT_PATH})
+
+################################################################################
+
+# create separate lists of all source (.cxx) files
+# depending on the required FLTK and system libraries
+
+############################################################
+# simple examples w/o extra libs
+############################################################
+
+set (SIMPLE_SOURCES
+  browser-simple
+  draggable-group
+  howto-add_fd-and-popen
+  howto-browser-with-icons
+  howto-drag-and-drop
+  howto-draw-an-x
+  howto-menu-with-images
+  howto-parse-args
+  howto-remap-numpad-keyboard-keys
+  howto-text-over-image-button
+  menubar-add
+  nativefilechooser-simple-app
+  nativefilechooser-simple
+  progress-simple
+  shapedwindow
+  simple-terminal
+  table-as-container
+  table-simple
+  table-sort
+  table-spreadsheet
+  table-spreadsheet-with-keyboard-nav
+  table-with-keynav
+  table-with-right-column-stretch-fit
+  tabs-simple
+  textdisplay-with-colors
+  texteditor-simple
+  texteditor-with-dynamic-colors
+  tree-as-container
+  tree-custom-draw-items
+  tree-custom-sort
+  tree-of-tables
+  tree-simple
+  wizard-simple
+)
+
+############################################################
+# examples requiring fltk_images
+############################################################
+
+set (IMAGE_SOURCES
+  clipboard
+  howto-simple-svg
+)
+
+############################################################
+# examples requiring OpenGL + libGLEW
+############################################################
+
+set (OPENGL_SOURCES
+  OpenGL3-glut-test
+  OpenGL3test
+)
+
+############################################################
+# create simple example programs
+############################################################
+
+foreach (src ${SIMPLE_SOURCES})
+  CREATE_EXAMPLE (${src} ${src}.cxx fltk)
+endforeach (src)
+
+############################################################
+# create example programs with fltk_images library
+############################################################
+
+foreach (src ${IMAGE_SOURCES})
+  CREATE_EXAMPLE (${src} ${src}.cxx "fltk_images;fltk")
+endforeach (src)
+
+############################################################
+# create example programs with OpenGL + libGLEW
+############################################################
+
+# Note: macOS does not need libGLEW
+
+if (APPLE AND (NOT OPTION_APPLE_X11) AND (NOT OPTION_APPLE_SDL))
+  if (NOT LIB_GLEW)
+    set (LIB_GLEW TRUE)
+  endif ()
+  set (REQUIRED_LIBS fltk_gl fltk ${OPENGL_LIBRARIES})
+else ()
+  set (REQUIRED_LIBS fltk_gl fltk ${OPENGL_LIBRARIES} GLEW)
+endif ()
+
+if (OPENGL_FOUND AND LIB_GLEW)
+  foreach (src ${OPENGL_SOURCES})
+    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)
+
+unset (REQUIRED_LIBS)
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index deb6a74cd..be95c25c3 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -37,6 +37,7 @@ elseif (HAVE_ALSA_ASOUNDLIB_H)
   if (LIB_asound)
     set (AUDIOLIBS ${LIB_asound})
   endif (LIB_asound)
+  mark_as_advanced (LIB_asound)
 endif (WIN32)
 
 #######################################################################
@@ -73,6 +74,7 @@ CREATE_EXAMPLE (doublebuffer doublebuffer.cxx fltk ANDROID_OK)
 CREATE_EXAMPLE (editor "editor.cxx;editor-Info.plist" fltk ANDROID_OK)
 CREATE_EXAMPLE (fast_slow fast_slow.fl fltk ANDROID_OK)
 CREATE_EXAMPLE (file_chooser file_chooser.cxx "fltk_images;fltk")
+CREATE_EXAMPLE (fltk-versions fltk-versions.cxx fltk)
 CREATE_EXAMPLE (fonts fonts.cxx fltk)
 CREATE_EXAMPLE (forms forms.cxx "fltk_forms;fltk")
 CREATE_EXAMPLE (hello hello.cxx fltk)
@@ -127,8 +129,6 @@ CREATE_EXAMPLE (valuators valuators.fl fltk)
 CREATE_EXAMPLE (unittests unittests.cxx fltk)
 CREATE_EXAMPLE (windowfocus windowfocus.cxx fltk)
 
-CREATE_EXAMPLE (fltk-versions ../examples/fltk-versions.cxx fltk)
-
 # OpenGL demos...
 if (OPENGL_FOUND)
   CREATE_EXAMPLE (CubeView "CubeMain.cxx;CubeView.cxx;CubeViewUI.fl" "fltk_gl;fltk")
diff --git a/examples/fltk-versions.cxx b/test/fltk-versions.cxx
index ed80c7b1f..ed80c7b1f 100644
--- a/examples/fltk-versions.cxx
+++ b/test/fltk-versions.cxx