Improve build instructions in README.CMake.txt (#164)

- update CMakeLists.txt files for user projects,
- add one that uses CMake's FetchContent module.

1 files changed, 126 insertions, 70 deletions

diff --git a/README.CMake.txt b/README.CMake.txt
index 8a6ba0834..115c80220 100644
--- a/README.CMake.txt
+++ b/README.CMake.txt
@@ -16,11 +16,13 @@ README.CMake.txt - Building and using FLTK with CMake
     2.7   Crosscompiling
   3     Using CMake with FLTK
     3.1   Library Names
-    3.2   Using Fluid Files
+    3.2   Building a Simple "Hello World" Program with FLTK
+    3.3   Building a Program Using Fluid Files
+    3.4   Building a Program Using CMake's FetchContent Module
   4     Document History
 
 
- 1.  INTRODUCTION TO CMAKE
+ 1.  Introduction to CMake
 ===========================
 
 CMake was designed to let you create build files for a project once and
@@ -216,10 +218,13 @@ OPTION_USE_GDIPLUS - default ON
    antialiased graphics (Windows platform only).
 
 OPTION_USE_STD - default OFF
-   This option allow FLTK to use some specific features of modern C++
+   This option allows FLTK to use some specific features of modern C++
    like std::string in the public API of FLTK 1.4.x. Users turning this
    option ON can benefit from some new functions and methods that return
    std::string or use std::string as input parameters.
+   Note: this option will probably be removed in the next minor (1.5.0)
+   or major (maybe 4.0.0) release which will default to use std::string
+   and more modern C++ features.
 
 OPTION_USE_SYSTEM_LIBDECOR - default OFF
    This option makes FLTK use package libdecor-0 to draw window titlebars
@@ -517,53 +522,75 @@ fltk-config.  For example, if you link your program to the FLTK
 library, it will automatically link in all of its dependencies.  This
 includes any special flags, i.e. on Linux it includes the -lpthread flag.
 
-This howto assumes that you have FLTK libraries which were built using
-CMake, installed.  Building them with CMake generates some CMake helper
-files which are installed in standard locations, making FLTK easy to find
-and use.
+This howto assumes that you have FLTK libraries which were built using CMake,
+installed.  Building them with CMake generates some CMake helper files which
+are installed in standard locations, making FLTK easy to find and use.
 
-Here is a basic CMakeLists.txt file using FLTK.
+In the following examples we set the CMake cache variable 'FLTK_DIR' so
+CMake knows where to find the FLTK configuration file 'FLTKConfig.cmake'.
+It is important (recommended practice) to set this as a CMake cache variable
+which enables the user executing 'cmake' to override this path either on the
+commandline or interactively using the CMake GUI 'cmake-gui' or 'ccmake' on
+Unix/Linux, for instance like this:
 
-------
+  $ mkdir build
+  $ cd build
+  $ cmake -G "Unix Makefiles" -S.. -D "FLTK_DIR=/home/me/fltk"
 
-cmake_minimum_required(VERSION 3.2.3)
 
-project(hello)
+ 3.1  Library Names
+--------------------
+
+When you use the target_link_libraries() command, CMake uses its own internal
+"target names" for libraries.  The fltk library names are:
+
+    fltk    fltk_forms    fltk_images    fltk_gl
+
+and for the shared libraries (if built):
+
+    fltk_SHARED    fltk_forms_SHARED    fltk_images_SHARED    fltk_gl_SHARED
+
+The built-in libraries (if built):
 
-# The following line is required only if (a) you didn't install FLTK
-# or if (b) find_package can't find your installation directory because
-# you installed FLTK in a non-standard location.  It points to
-# (a) the base folder of the build directory, or
-# (b) <fltk-install-prefix>/share/fltk
-# resp., where <fltk-install-prefix> is the installation prefix you
-# used to install FLTK.
-# (The file FLTKConfig.cmake and others must be found in that path.)
+    fltk_jpeg    fltk_png    fltk_z
 
-set(FLTK_DIR /path/to/fltk)
 
-find_package(FLTK REQUIRED NO_MODULE)
+ 3.2  Building a Simple "Hello World" Program with FLTK
+--------------------------------------------------------
+
+Here is a basic CMakeLists.txt file using FLTK.
+
+---
+cmake_minimum_required(VERSION 3.15)
+
+project(hello)
+
+set(FLTK_DIR "/path/to/fltk"
+    CACHE FILEPATH "FLTK installation or build directory")
+
+find_package(FLTK REQUIRED CONFIG)
 
 add_executable(hello WIN32 MACOSX_BUNDLE hello.cxx)
 if (APPLE)
-  target_link_libraries(hello "-framework cocoa")
+  target_link_libraries(hello PRIVATE "-framework cocoa")
 endif (APPLE)
 
-target_include_directories(hello PUBLIC ${FLTK_INCLUDE_DIRS})
-
-target_link_libraries(hello fltk)
+target_include_directories(hello PRIVATE ${FLTK_INCLUDE_DIRS})
 
-------
+target_link_libraries(hello PRIVATE fltk)
+---
 
 The set(FLTK_DIR ...) command is a superhint to the find_package command.
 This is very useful if you don't install or have a non-standard install.
 The find_package command tells CMake to find the package FLTK, REQUIRED
-means that it is an error if it's not found.  NO_MODULE tells it to search
+means that it is an error if it's not found.  CONFIG tells it to search
 only for the FLTKConfig file, not using the FindFLTK.cmake supplied with
 CMake, which doesn't work with this version of FLTK.
 
-The "WIN32 MACOSX_BUNDLE" in the add_executable tells this is
-a GUI app.  It is ignored on other platforms and should always be
-present with FLTK GUI programs for better portability.
+The "WIN32 MACOSX_BUNDLE" in the add_executable tells this is a GUI app.
+It is ignored on other platforms and should always be present with FLTK
+GUI programs for better portability - unless you explicity need to build
+a "console program", e.g. on Windows.
 
 Once the package is found the CMake variable FLTK_INCLUDE_DIRS is defined
 which can be used to add the FLTK include directories to the definitions
@@ -574,61 +601,47 @@ libraries. Thus, you may have to add fltk_images, fltk_gl, etc…
 
 Note: the variable FLTK_USE_FILE used to include another file in
 previous FLTK versions was deprecated since FLTK 1.3.4 and will be
-removed in FLTK 1.4.0 (this version) or later (maybe 1.4.1).
-
-
- 3.1  Library Names
---------------------
-
-When you use the target_link_libraries command, CMake uses its own
-internal names for libraries.  The fltk library names are:
+removed in FLTK 1.4.0 (this version) or later (maybe 1.4.1 or 1.4.2).
 
-    fltk     fltk_forms     fltk_images    fltk_gl
 
-and for the shared libraries (if built):
-
-    fltk_SHARED     fltk_forms_SHARED     fltk_images_SHARED    fltk_gl_SHARED
-
-The built-in libraries (if built):
-
-    fltk_jpeg      fltk_png    fltk_z
-
-
- 3.2  Using Fluid Files
-------------------------
+ 3.3  Building a Program Using Fluid Files
+-------------------------------------------
 
 CMake has a command named fltk_wrap_ui which helps deal with fluid *.fl
 files. Unfortunately it is broken in CMake 3.4.x but it seems to work in
-3.5 and later CMake versions. You can however use add_custom_command()
-to achieve the same result. This is a more basic approach and should
-work for all CMake versions.
+3.5 and later CMake versions. We recommend to use add_custom_command()
+to achieve the same result in a more explicit and well-defined way.
+This is a more basic approach and should work for all CMake versions.
 
 Here is a sample CMakeLists.txt which compiles the CubeView example from
 a directory you've copied the test/Cube* files to.
 
 ---
-cmake_minimum_required(VERSION 2.6.3)
+cmake_minimum_required(VERSION 3.15)
 
 project(CubeView)
 
 # change this to your fltk build directory
-set(FLTK_DIR /home/msurette/build/fltk-release/)
+set(FLTK_DIR "/path/to/fltk"
+    CACHE FILEPATH "FLTK installation or build directory")
 
-find_package(FLTK REQUIRED NO_MODULE)
-include_directories(${FLTK_INCLUDE_DIRS})
+find_package(FLTK REQUIRED CONFIG)
 
-#run fluid -c to generate CubeViewUI.cxx and CubeViewUI.h files
+# run fluid -c to generate CubeViewUI.cxx and CubeViewUI.h files
 add_custom_command(
-        OUTPUT "CubeViewUI.cxx" "CubeViewUI.h"
-        COMMAND fluid -c ${CMAKE_CURRENT_SOURCE_DIR}/CubeViewUI.fl
+    OUTPUT "CubeViewUI.cxx" "CubeViewUI.h"
+    COMMAND fluid -c ${CMAKE_CURRENT_SOURCE_DIR}/CubeViewUI.fl
 )
 
-include_directories(${CMAKE_CURRENT_BINARY_DIR})
-include_directories(${CMAKE_CURRENT_SOURCE_DIR})
+add_executable(CubeView WIN32 MACOSX_BUNDLE
+    CubeMain.cxx CubeView.cxx CubeViewUI.cxx)
 
-add_executable(CubeView WIN32 CubeMain.cxx CubeView.cxx CubeViewUI.cxx)
+target_include_directories(CubeView PRIVATE ${FLTK_INCLUDE_DIRS})
 
-target_link_libraries(CubeView fltk fltk_gl)
+target_include_directories(CubeView PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
+target_include_directories(CubeView PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+
+target_link_libraries(CubeView PRIVATE fltk fltk_gl)
 ---
 
 You can repeat the add_custom_command for each fluid file or if you
@@ -637,8 +650,8 @@ FLTK_RUN_FLUID for an example of how to run it in a loop.
 
 The two lines
 
-  include_directories(${CMAKE_CURRENT_BINARY_DIR})
-  include_directories(${CMAKE_CURRENT_SOURCE_DIR})
+    target_include_directories(CubeView PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
+    target_include_directories(CubeView PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 
 add the current build ("binary") and source directories as include directories.
 This is necessary for the compiler to find the local header files since the
@@ -646,15 +659,58 @@ fluid-generated files (CubeViewUI.cxx and CubeViewUI.h) are created in the
 current build directory.
 
 
- DOCUMENT HISTORY
-==================
+ 3.4  Building a Program Using CMake's FetchContent Module
+-----------------------------------------------------------
+
+FLTK can be downloaded and built within a user project using CMake's
+FetchContent module. A sample CMakeLists.txt file follows.
+
+You may need to adjust it to your configuration.
+
+---
+cmake_minimum_required(VERSION 3.15)
+project(hello)
+
+include(FetchContent)
+
+set(FLTK_BUILD_TEST OFF CACHE BOOL "" FORCE)
+if(UNIX AND NOT APPLE)
+    set(OPTION_USE_PANGO ON CACHE BOOL "" FORCE)
+endif()
+
+FetchContent_Declare(FLTK
+    GIT_REPOSITORY https://github.com/fltk/fltk
+    GIT_SHALLOW TRUE
+)
+FetchContent_MakeAvailable(FLTK)
+
+add_executable(hello WIN32 MACOSX_BUNDLE hello.cxx)
+
+target_include_directories(hello PRIVATE ${fltk_BINARY_DIR} ${fltk_SOURCE_DIR})
+
+# link as required: fltk fltk_gl fltk_images fltk_png fltk_jpeg fltk_z
+target_link_libraries(hello PRIVATE fltk)
+
+if(APPLE)
+    target_link_libraries(hello PRIVATE "-framework Cocoa") # needed for Darwin
+endif()
+
+if(WIN32)
+  target_link_libraries(hello PRIVATE gdiplus)
+endif()
+---
+
+
+ 4  Document History
+---------------------
 
-Dec 20 2010 - matt: merged and restructures
+Dec 20 2010 - matt: merged and restructured
 May 15 2013 - erco: small formatting tweaks, added some examples
 Feb 23 2014 - msurette: updated to reflect changes to the CMake files
 Apr 07 2015 - AlbrechtS: update use example and more docs
 Jan 31 2016 - msurette: custom command instead of fltk_wrap_ui
 Nov 01 2016 - AlbrechtS: remove deprecated FLTK_USE_FILE, add MinGW build
-Jul 05 2017 - matt: added instructions for MacOS and Xcode
+Jul 05 2017 - matt: added instructions for macOS and Xcode
 Dec 29 2018 - AlbrechtS: add documentation option descriptions
 Apr 29 2021 - AlbrechtS: document macOS "universal apps" build setup
+Nov 01 2023 - AlbrechtS: improve build instructions for user programs