README.CMake.txt

README.CMake.txt - Building and using FLTK with CMake
-----------------------------------------------------


 CONTENTS
==========

  1     Introduction to CMake

  2     Using CMake to Build FLTK

    2.1    Prerequisites
    2.2    Options
    2.2.1  General CMake Options
    2.2.2  FLTK Specific Build Options
    2.2.3  Documentation Options
    2.2.4  Special Options
    2.3    Building under Linux with Unix Makefiles
    2.4    Building under Windows with Visual Studio and/or NMake
    2.4.1  Building under Windows with Visual Studio
    2.4.2  Building under Windows with NMake
    2.5    Building under Windows with MinGW using Makefiles
    2.6    Building under MacOS with Xcode
    2.7    Crosscompiling

  3     Using CMake with FLTK

    3.1    Library Names
    3.2    Library Aliases
    3.3    Exported and Imported Targets
    3.4    Building a Simple "Hello World" Program with FLTK
    3.5    Building a Program Using Fluid Files
    3.6    Building a Program Using CMake's FetchContent Module


  4     FindFLTK.cmake and find_package(FLTK)

 1.  Introduction to CMake
===========================

CMake was designed to let you create build files for a project once and
then compile the project on multiple platforms.

Using it on any platform consists of the same steps. Create the
CMakeLists.txt build file(s). Run one of the CMake executables, picking
your source directory, build directory, and build target. The "cmake"
executable is a one-step process with everything specified on the command
line. The others let you select options interactively, then configure
and generate your platform-specific target. You then run the resulting
Makefile / project file / solution file as you normally would.

CMake can be run in up to three ways, depending on your platform. "cmake"
is the basic command line tool. "ccmake" is the curses based interactive
tool. "cmake-gui" is the gui-based interactive tool. Each of these will
take command line options in the form of -DOPTION=VALUE. ccmake and
cmake-gui will also let you change options interactively.

CMake not only supports, but works best with out-of-tree builds. This means
that your build directory is not the same as your source directory or with a
complex project, not the same as your source root directory. Note that the
build directory is where, in this case, FLTK will be built, not its final
installation point. If you want to build for multiple targets, such as
VC++ and MinGW on Windows, or do some cross-compiling you must use out-of-tree
builds exclusively. In-tree builds will gum up the works by putting a
CMakeCache.txt file in the source root.

More information on CMake can be found on its web site https://www.cmake.org.



 2.  Using CMake to Build FLTK
===============================


 2.1  Prerequisites
--------------------

The prerequisites for building FLTK with CMake are staightforward:
CMake 3.15 or later and a recent FLTK release, snapshot, or Git download
(working copy). Installation of CMake is covered on its web site.

This howto will cover building FLTK with the default options using CMake
under Linux and MinGW with Unix Makefiles. Chapter 2.5 shows how to use
a MinGW cross compiling toolchain to build a FLTK library for Windows
under Linux. Other platforms are just as easy to use.


 2.2  Options
--------------

Options can be specified to CMake with the -D flag:

    cmake -D <OPTION_NAME>=<OPTION_VALUE>

Example:

    cmake -D CMAKE_BUILD_TYPE=Debug

Notes: the space between '-D' and the option name can be omitted.
Option values must be quoted if they contain spaces.

Other CMake tools are `ccmake` and `cmake-gui` but these are not
described here.

All options have sensible defaults so you won't usually need to specify
them explicitly.


 2.2.1  General CMake Options
------------------------------

There are only three CMake options that you may want to specify:

CMAKE_BUILD_TYPE
    This specifies what kind of build this is i.e. Release, Debug...
    Platform specific compile/link flags/options are automatically selected
    by CMake depending on this value.

CMAKE_INSTALL_PREFIX
    Where everything will go on install. Defaults are /usr/local for Unix
    and C:\Program Files\FLTK for Windows.

CMAKE_OSX_ARCHITECTURES (macOS only, ignored on other platforms)
    Set this to either "arm64", "x86_64", or a list of both "arm64;x86_64".
    The latter will build "universal apps" on macOS, whereas the former
    will either build Intel (x86_64) or Apple Silicon aka M1 (arm64) apps.
    The default is to build for the host processor architecture.

Note: the CMake variable BUILD_SHARED_LIBS is ignored by FLTK. FLTK builds
    static libs by default and can optionally build shared libs as well.
    Please see FLTK_BUILD_SHARED_LIBS instead.


 2.2.2  FLTK Specific Build Options
------------------------------------

Following are the FLTK specific options. Platform specific options are
ignored on other platforms. For convenience the list of options is ordered
alphabetically except "Documentation Options" and "Special Options" that
follow in their own sections below.


FLTK_ABI_VERSION - default EMPTY
    Use a numeric value corresponding to the FLTK ABI version you want to
    build in the form 1xxyy for FLTK 1.x.y (xx and yy with leading zeroes).
    The default ABI version is 1xx00 (the stable ABI throughout all patch
    releases of one minor FLTK version). The highest ABI version you may
    choose is 1xxyy for FLTK 1.x.y (again with leading zeroes).
    Please see README.abi-version.txt for more information about which
    ABI version to select.

FLTK_ARCHFLAGS - default EMPTY
    Extra "architecture" flags used as C and C++ compiler flags.
    These flags are also "exported" to fltk-config.

FLTK_BACKEND_WAYLAND - default ON (only Unix/Linux)
    Enable the Wayland backend for all window operations, Cairo for all
    graphics and Pango for text drawing (Linux+FreeBSD only). Resulting FLTK
    apps use Wayland when a Wayland compositor is available at runtime,
    and use X11 for their window operations otherwise (unless FLTK_BACKEND_X11
    is OFF), but keep using Cairo and Pango - see README.Wayland.txt.
    If FLTK_BACKEND_X11 has been turned OFF and there is no Wayland compositor
    at runtime, then FLTK programs fail to start.

FLTK_BACKEND_X11 - default ON on Unix/Linux, OFF elsewhere (Windows, macOS).
    Enable or disable the X11 backend on platforms that support it.
    - Unix/Linux: enable or disable the X11 backend when building with
      Wayland (FLTK_BACKEND_WAYLAND), otherwise this option must be ON.
    - macOS: enable the X11 backend instead of standard system graphics.
      This requires XQuartz or a similar X11 installation. This option is
      tested only with XQuartz by the FLTK team.
      Use this only if you know what you do and if you have installed X11.
    - Windows/Cygwin: enable X11 backend for Cygwin platforms. This option
      is currently (as of FLTK 1.4.0) not supported on Windows.

Note: On platforms that support Wayland you may set FLTK_BACKEND_WAYLAND=ON
    (this is the default) and FLTK_BACKEND_X11=OFF to build a Wayland-only
    library or vice versa for an X11-only library.

FLTK_BUILD_EXAMPLES - default OFF
    Build the example programs in the 'examples' directory.

FLTK_BUILD_FLTK_OPTIONS - default ON
    Build the FLTK options editor ("fltk-options").

FLTK_BUILD_FLUID - default ON
    Build the Fast Light User-Interface Designer ("fluid").

FLTK_BUILD_FORMS - default ON
    Build the (X)Forms compatibility library. This option is ON by default
    for backwards compatibility but can safely be turned OFF if you don't
    need (X)Forms compatibility.

FLTK_BUILD_GL - default ON
    Build the OpenGL support library fltk_gl (fltk::gl) and enable OpenGL
    support in user programs using fltk_gl.

FLTK_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.
    You can use shared FLTK libs in your own CMake projects by appending
    "-shared" to FLTK target names as described in section 3.1 and 3.2.

FLTK_BUILD_TEST - default ON in top-level build, OFF in sub-build
    Build the test and demo programs in the 'test' directory. The default
    is ON if the FLTK build is in a top-level project so all test and demo
    programs are built. If FLTK is built as a subproject only the Library
    and the tools (fluid and fltk-config) are built by default.

FLTK_GRAPHICS_CAIRO - default OFF (Unix/Linux: X11 + Wayland only).
    Make all drawing operations use the Cairo library (rather than Xlib),
    producing antialiased graphics (X11 platform: implies FLTK_USE_PANGO).
    When using Wayland this option is ignored (Wayland uses Cairo).

FLTK_GRAPHICS_GDIPLUS - default ON (Windows only).
    Make FLTK use GDI+ to draw oblique lines and curves resulting in
    antialiased graphics. If this option is OFF standard GDI is used.

FLTK_MSVC_RUNTIME_DLL - default ON (Windows only: Visual Studio and NMake).
    Select whether the build uses the MS runtime DLL (ON) or not (OFF).
    Default is ON: either /MD or /MDd for Release or Debug, respectively.
    Select OFF for either /MT or /MTd for Release or Debug, respectively.

FLTK_OPTION_CAIRO_EXT - default OFF
    Enable extended libcairo support - see README.Cairo.txt.

FLTK_OPTION_CAIRO_WINDOW - default OFF
    Enable support of class Fl_Cairo_Window (all platforms, requires the
    Cairo library) - see README.Cairo.txt.

FLTK_OPTION_FILESYSTEM_SUPPORT - default ON

FLTK_OPTION_LARGE_FILE - default ON
    Enables large file (>2G) support.

FLTK_OPTION_OPTIM - default EMPTY
    Extra optimization flags for the C and C++ compilers, for instance
    "-Wall -Wno-deprecated-declarations".

FLTK_OPTION_PRINT_SUPPORT - default ON
    When turned off, the Fl_Printer class does nothing and the
    Fl_PostScript_File_Device class cannot be used, but the FLTK library
    is somewhat smaller. This option makes sense only on the Unix/Linux
    platform or on macOS when FLTK_BACKEND_X11 is ON.

FLTK_OPTION_STD - default OFF
    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 be removed in the next minor (1.5.0) or major
    release which will use std::string and other modern C++ features.

FLTK_OPTION_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.

FLTK_USE_LIBDECOR_GTK - default ON (Wayland only).
    Allow to use libdecor's GTK plugin to draw window titlebars. Otherwise
    FLTK does not use GTK and apps will not need linking to GTK. This feature
    is always 'ON' if FLTK_USE_SYSTEM_LIBDECOR is 'ON'.

FLTK_USE_PANGO - default OFF (see note below)
    Enables use of the Pango library for drawing text. Pango supports all
    unicode-defined scripts and gives FLTK limited support of right-to-left
    scripts. This option makes sense only under X11 or Wayland, and also
    requires Xft.
    This option is ignored (always enabled) if Wayland or FLTK_GRAPHICS_CAIRO
    is ON.

FLTK_USE_POLL - default OFF
    Deprecated: don't turn this option ON.

FLTK_USE_PTHREADS - default ON except on Windows.
    Enables multithreaded support with pthreads if available.
    This option is ignored (switched OFF internally) on Windows except
    when using Cygwin.

FLTK_USE_SYSTEM_LIBDECOR - default ON (Wayland only)
    This option makes FLTK use package libdecor-0-dev to draw window titlebars
    under Wayland. When OFF or when this package has a version < 0.2.0, FLTK
    uses its bundled copy of libdecor to draw window titlebars.

FLTK_USE_SYSTEM_LIBJPEG - default ON (macOS and Windows: OFF)
FLTK_USE_SYSTEM_LIBPNG  - default ON (macOS and Windows: OFF)
FLTK_USE_SYSTEM_ZLIB    - default ON (macOS and Windows: OFF)
    FLTK has built in jpeg, zlib, and png libraries. These options let you
    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.
    The default is ON on Linux/Unix platforms but OFF on Windows and macOS
    because of potential incompatibilities on Windows and macOS whereas
    the system libraries can typically be used on Linux/Unix.
    Note: if any one of libpng or zlib is not found on the system, both
    libraries are built using the bundled ones and a warning is issued.

FLTK_USE_XCURSOR  - default ON
FLTK_USE_XFIXES   - default ON
FLTK_USE_XFT      - default ON
FLTK_USE_XINERAMA - default ON
FLTK_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.


 2.2.3  Documentation Options
------------------------------

  These options are only available if `doxygen' is installed and found.
  PDF related options require also `latex'.

FLTK_BUILD_HTML_DOCS - default ON
FLTK_BUILD_PDF_DOCS  - default ON
    These options can be used to enable HTML documentation generation with
    doxygen. If these are ON the build targets 'html', 'pdf', and 'docs'
    are generated but must be built explicitly. Technically the build targets
    are generated but excluded from 'ALL'.
    You can safely leave these two options ON if you want to save build time
    because the docs are not built automatically.

FLTK_BUILD_FLUID_DOCS - default OFF
    If this option is ON, the FLUID user documentation will be built. If 
    FLTK_BUILD_PDF_DOCS is ON, the FLUID documentation will be generated
    in PDF forma. To generate the screen shots used in the handbook,
    the CMake build mode must be set to "Debug".

FLTK_INCLUDE_DRIVER_DOCS - default OFF
    This option adds driver documentation to HTML and PDF docs (if ON). This
    option is marked as "advanced" since it is only useful for FLTK developers
    and advanced users. It is only used if at least one of the documentation
    options above is ON as well.

FLTK_INSTALL_HTML_DOCS - default OFF
FLTK_INSTALL_FLUID_DOCS - default OFF
FLTK_INSTALL_PDF_DOCS  - default OFF
    If these options are ON then the HTML, FLUID, and/or PDF docs are installed
    when the 'install' target is executed, e.g. with `make install'. You 
    need to select above options FLTK_BUILD_*_DOCS as well.


 2.2.4  Special Options
------------------------

FLTK_INSTALL_LINKS - default OFF
    Deprecated: install "compatibility" links to compensate for typos in
    include statements (for case sensitive file systems only).
    You should not use this option, please fix the sources instead for
    better cross-platform compatibility.


 2.3  Building under Linux with Unix Makefiles
-----------------------------------------------

After unpacking the FLTK source, go to the root of the FLTK tree and type
the following.

    mkdir build
    cd build
    cmake ..
    make
    sudo make install (optional)

IMPORTANT: The trailing ".." on the cmake command must be specified
(it is NOT an ellipsis).                          ^^^^^^^^^^^^^^^^^

This will build and install a default configuration FLTK.

Some flags can be changed during the 'make' command, such as:

    make VERBOSE=on

which builds in verbose mode, so you can see all the compile/link commands.

Hint: if you intend to build several different versions of FLTK, e.g. a Debug
and a Release version, or multiple libraries with different ABI versions or
options, then use subdirectories in the build directory, like this:

    mkdir build
    cd build
    mkdir debug
    cd debug
    cmake -D 'CMAKE_BUILD_TYPE=Debug' ../..
    make
    sudo make install (optional)


 2.4  Building under Windows with Visual Studio and/or NMake
-------------------------------------------------------------

Building with CMake under Visual Studio may require to specify the CMake
generator with the -G"Visual Studio ..." command line switch, or the
generator can be selected interactively in the GUI (cmake-gui). If you
are not sure which one to select use `cmake --help` which lists all
generators known to CMake on your system.


 2.4.1 Building under Windows with Visual Studio
-------------------------------------------------

CMake often finds an installed Visual Studio generator and uses it w/o
using the commandline switch, particularly if you are using a special
"Visual Studio Command Prompt":

  - Hit the "Windows" key

  - Type "developer command ..."
    ... until you see something like "Developer Command Prompt for VS xxxx"
    (replace 'xxxx' with your installed Visual Studio version)

  - Activate the "app" to execute the command prompt (like an old "DOS" shell)

  - Inside this command prompt window, run your installed `cmake` (command
    line) or `cmake-gui` (GUI) program. You may need to specify the full path
    to this program.

  If you use `cmake-gui` you can select the source and the build folders in
  the GUI, otherwise change directory to where you downloaded and installed
  the FLTK sources and execute:

      `cmake` -G "Visual Studio xxx..." -B build
      cd build

  This creates the Visual Studio project files (FLTK.sln and more) in the
  'build' directory.

  Open Visual Studio, choose File -> Open -> Project, and pick the "FLTK.sln"
  created in the previous step.

  (Or, if only one version of the Visual Studio compiler is installed,
  you can just run from DOS: .\FLTK.sln)

  Make sure the pulldown menu has either "Release" or "Debug" selected
  in the "Solution Configurations" pulldown menu.

  In the "Solution Explorer", right click on:

      Solution 'FLTK' (## projects)

      ... and in the popup menu, choose "Build Solution"

  or choose 'Build/Build Solution' or 'Build/Rebuild Solution' from the
  menu at the top of the window.

  That's it, that should build FLTK.

  The test programs (*.exe) can be found relative to the 'build' folder in

      build\bin\test\Release\*.exe
      build\bin\test\Debug\*.exe

  ... and the FLTK include files (*.H & *.h) your own apps can
  compile with can be found in:

      build\FL

  *and* [1] in the source folder where you downloade FLTK, e.g. in

      C:\fltk-1.4.x\FL

  ... and the FLTK library files (*.lib) which your own apps can
  link with can be found in:

      Release: build\lib\Release\*.lib
        Debug: build\lib\Debug\*.lib

  [1] If you want to build your own FLTK application directly using
      the build directories (i.e. without "installation") you need
      to include both the build tree (first) and then the FLTK source
      tree in the compiler's header search list.


 2.4.2 Building under Windows with NMake
-----------------------------------------

  This example uses cmake to generate + build FLTK in Release mode using nmake,
  using purely the command line (never need to open the Visual Studio IDE)
  using Multithreaded (/MT):

    mkdir build-nmake
    cd build-nmake
    cmake -G "NMake Makefiles" -D CMAKE_BUILD_TYPE=Release -D FLTK_MSVC_RUNTIME_DLL=off ..
    nmake

  which results in a colorful percentage output crawl similar to what we see
  with unix 'make'.

  Instead of running `nmake` directly you can also use cmake to build:

    cmake --build .


 2.5  Building under Windows with MinGW using Makefiles
--------------------------------------------------------

Building with CMake under MinGW requires you to specify the CMake Generator
with the -G command line switch. Using

  cmake -G "Unix Makefiles" /path/to/fltk

is recommended by the FLTK team if you have installed MinGW with the MSYS
environment. You can use the stock Windows CMake executables, but you must
run the CMake executables from within the MinGW environment so CMake can
use your MinGW PATH to find the compilers and build tools. Example:

  alias cmake='/c/CMake/bin/cmake'
  alias cmake-gui='/c/CMake/bin/cmake-gui'

  mkdir build
  cd build
  cmake -G "Unix Makefiles" -D 'CMAKE_BUILD_TYPE=Debug' ..

Note the path to FLTK ".." in the last command line. Depending on where you
installed CMake you may need to adjust the path's in the alias commands.


2.6  Building under MacOS with Xcode
------------------------------------

Building with CMake under Xcode requires the CMake generator
with the -G command line switch. This step need to be done only once. If any
of the cmake related files are updated, Xcode will rerun cmake for you.

1) Open the MacOS Terminal

2) Change to the directory containing the FLTK project. For example:
     > cd ~/dev/fltk-1.4.x

3) Create a build directory
     > mkdir build
     > cd build

4) If you plan different build versions, it is useful to create another
   subdirectory level
     > mkdir Xcode
     > cd Xcode

5) Let CMake create the required IDE files
     > cmake -G Xcode ../..
   This step should end in the message:
     -- Build files have been written to: .../dev/fltk-1.4.x/build/Xcode

5a) To build the Release version of FLTK, use
      > cmake -G Xcode -D CMAKE_BUILD_TYPE=Release ../..

6) Launch Xcode from the Finder or from the Terminal:
     > open ./FLTK.xcodeproj
   When Xcode starts, it asks if it should "Autocreate Schemes". Click on
   "Automatically Create Schemes" to confirm.

7) To build and test FLTK, select the scheme "ALL_BUILD" and hit Cmd-B to
   build. Then select the scheme "demo" and hit Cmd-R to run the FLTK Demo.

8) The interactive user interface tool "Fluid" will be located in
   build/Xcode/bin/Debug. The example apps are in .../bin/examples/Debug.
   Static libraries are in .../lib/Debug/

9) The "install" Scheme currently fails because it is run with user permission.


 2.7  Crosscompiling
---------------------

Once you have a crosscompiler going, to use CMake to build FLTK you need
two more things. You need a toolchain file which tells CMake where your
build tools are. The CMake website is a good source of information on
this file. Here's one for MinGW (64-bit) under Linux.

----
# CMake Toolchain File for MinGW-w64 (64-bit) Cross Compilation

# the name of the target operating system
set(CMAKE_SYSTEM_NAME Windows)

# which tools to use
set(CMAKE_C_COMPILER   /usr/bin/x86_64-w64-mingw32-gcc)
set(CMAKE_CXX_COMPILER /usr/bin/x86_64-w64-mingw32-g++)
set(CMAKE_RC_COMPILER  /usr/bin/x86_64-w64-mingw32-windres)

# here is where the target environment located
set(CMAKE_FIND_ROOT_PATH  /usr/x86_64-w64-mingw32)

# adjust the default behavior of the FIND_XXX() commands:

# search programs in the host environment
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)

# search headers and libraries in the target environment
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

set(CMAKE_INSTALL_PREFIX ${CMAKE_FIND_ROOT_PATH}/usr CACHE FILEPATH
   "install path prefix")

# initialize required linker flags
set(CMAKE_EXE_LINKER_FLAGS_INIT "-static-libgcc -static-libstdc++")

# end of toolchain file
----

Not too tough. The other thing you need is a native installation of FLTK
on your build platform. This is to supply the fluid executable which will
compile the *.fl into C++ source and header files.

So, again from the FLTK tree root.

    mkdir mingw
    cd mingw
    cmake -DCMAKE_TOOLCHAIN_FILE=~/projects/toolchain/Toolchain-mingw32.cmake ..
    make
    sudo make install

IMPORTANT: The trailing ".." on the cmake command must be specified
(it is NOT an ellipsis).                          ^^^^^^^^^^^^^^^^^

This will create a default configuration FLTK suitable for mingw/msys and
install it in the /usr/x86_64-w64-mingw32/usr tree.

Note: replace 'x86_64-w64-mingw32' with your cross toolchain location as
required.


 3.  Using CMake with FLTK
===========================

The CMake Export/Import facility can be thought of as an automated
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.

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"


 3.1  Library Names
--------------------

When you use the target_link_libraries() command, CMake uses its own internal
"target names" for libraries. The original fltk library names in the build
tree are:

    fltk    fltk_forms    fltk_images    fltk_gl

The bundled image and zlib libraries (if built):

    fltk_jpeg    fltk_png    fltk_z

Append suffix "-shared" for shared libraries (Windows: DLL's).

These library names are used to construct the filename on disk with system
specific prefixes and postfixes. For instance, on Linux/Unix 'fltk' is libfltk.a
and the shared library (fltk-shared) is libfltk.so.1.4.0 (in FLTK 1.4.0) with
additional system specific links.

Note: since FLTK 1.4.0 the library fltk_cairo is no longer necessary and
should be removed from CMake files of user projects. fltk_cairo is now an
empty library solely for backwards compatibility and will be removed in the
future.


 3.2  Library Aliases
----------------------

Since FLTK 1.4.0 "aliases" for all libraries in the FLTK build tree are
created in the namespace "fltk::". These aliases should always be used by
consumer projects (projects that use FLTK) for several reasons which are
beyond the scope of this README file. The following table shows the FLTK
libraries and their aliases in the FLTK build tree.

  Library Name      Alias          Shared Library Alias   Notes
  --------------------------------------------------------------
    fltk           fltk::fltk     fltk::fltk-shared       [1]
    fltk_forms     fltk::forms    fltk::forms-shared      [2]
    fltk_gl        fltk::gl       fltk::gl-shared         [2]
    fltk_images    fltk::images   fltk::images-shared     [2]
    fltk_jpeg      fltk::jpeg     fltk::jpeg-shared       [3]
    fltk_png       fltk::png      fltk::png-shared        [3]
    fltk_z         fltk::z        fltk::z-shared          [3]

  [1] The basic FLTK library. Use this if you don't need any of the other
      libraries for your application.
  [2] Use one or more of these libraries if you have specific needs,
      e.g. if you need to read images (fltk::images), OpenGL (fltk::gl),
      or (X)Forms compatibility (fltk::forms). If you use one of these
      libraries in your CMakeLists.txt then fltk::fltk will be included
      automatically.
  [3] The bundled libraries are only built if requested and are usually
      not needed in user projects. They are linked in with fltk::images
      automatically if they were built with FLTK.
      The only reason you may need them would be if you used libpng,
      libjpeg, or zlib functions directly in your application and need
      to use the bundled FLTK libs (e.g. on Windows).


 3.3  Exported and Imported Targets
------------------------------------

CMake terminology is to "export" and "import" library "targets". FLTK's
CMake files export targets and its CONFIG module FLTKConfig.cmake imports
targets so user projects can use them. Hence, if you use CMake's CONFIG
mode to find FLTK all library targets will be defined using the namespace
convention listed above in the "Alias" column. This is what user projects
are intended to use.

In addition to the library targets FLTK defines the "imported target"
'fltk::fluid' which can be used to generate source (.cxx) and header (.h)
files from fluid (.fl) files.

Another target fltk::fltk-config can be used to set (e.g.) system or user
specific FLTK options. This would usually be executed in the installation
process of a user project but should rarely be needed and is beyound the
scope of this documentation.


 3.4  Building a Simple "Hello World" Program with FLTK
--------------------------------------------------------

Here is a basic CMakeLists.txt file using FLTK. It is important that
this file can only be used as simple as it is if you use find_package()
in `CONFIG` mode as shown below. This requires that the FLTK library
itself has been built with CMake.

---
cmake_minimum_required(VERSION 3.15)

project(hello)

# optional (see below):
set(FLTK_DIR "/path/to/fltk"
    CACHE FILEPATH "FLTK installation or build directory")

find_package(FLTK CONFIG REQUIRED)

add_executable       (hello WIN32 MACOSX_BUNDLE hello.cxx)
target_link_libraries(hello PRIVATE fltk::fltk)
---

We recommend to use `cmake_minimum_required(VERSION 3.15)` or higher for
building projects that use FLTK. Lower CMake versions may work for user
projects but this is not tested by FLTK developers.

The optional `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 location. The path you give to it must be that of a directory that
contains the file FLTKConfig.cmake.

You can omit this statement if CMake finds the required FLTK version
without it. This variable is stored in the CMake Cache so users can change
it with the ususal CMake GUI interfaces (ccmake, cmake-gui) or on the
CMake commandline (-D FLTK_DIR=...).

The find_package command tells CMake to find the package FLTK, REQUIRED
means that it is an error if it's not found. CONFIG tells it to search
only for the FLTKConfig.cmake file, not using the FindFLTK.cmake "module"
supplied with CMake, which doesn't work with this version of FLTK.

"WIN32 MACOSX_BUNDLE" in the add_executable() command tells CMake that
this is a GUI app. It is ignored on other platforms than Windows or macOS,
respectively, and should always be present with FLTK GUI programs for
better portability - unless you explicitly need to build a "console program"
on Windows.

Once the package is found (in CONFIG mode, as described above) all built
FLTK libraries are "imported" as CMake "targets" or aliases and can be used
directly. These CMake library targets contain all necessary informations to
be used without having to know about additional include directories or
other library dependencies. This is what is called "Modern CMake".

Older FLTK versions required to use the variables FLTK_INCLUDE_DIRS and
FLTK_LIBRARIES (among others). These variables and related commands are
no longer necessary if your project (CMakeLists.txt) uses CMake's
CONFIG mode as described in this file.

The target_link_libraries() command is used to specify all necessary FLTK
libraries. Thus you may use fltk::fltk, fltk::images, fltk::gl, fltk::forms,
or any combination. fltk::fltk is linked automatically if any of the other
libs is included.


 3.5  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. 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.
It is described below.

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 3.15)

project(CubeView)

# change this to your fltk build directory
set(FLTK_DIR "/path/to/fltk"
    CACHE FILEPATH "FLTK installation or build directory")

find_package(FLTK CONFIG REQUIRED)

# run fluid -c to generate CubeViewUI.cxx and CubeViewUI.h files
add_custom_command(
    OUTPUT "CubeViewUI.cxx" "CubeViewUI.h"
    COMMAND fltk::fluid -c ${CMAKE_CURRENT_SOURCE_DIR}/CubeViewUI.fl
)

add_executable(CubeView WIN32 MACOSX_BUNDLE
               CubeMain.cxx CubeView.cxx CubeViewUI.cxx)

target_include_directories(CubeView PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
target_include_directories(CubeView PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

target_link_libraries     (CubeView PRIVATE fltk::gl)
---

You can repeat the add_custom_command for each fluid file or if you
have a large number of them see the fltk_run_fluid() function in
CMake/FLTK-Functions.cmake for an example of how to run it in a loop.

The two lines

  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
fluid-generated files (CubeViewUI.cxx and CubeViewUI.h) are created in the
current build directory and other header files may be in the source directory
(depending on your project).


 3.6  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)

FetchContent_Declare(FLTK
  GIT_REPOSITORY  https://github.com/fltk/fltk
  GIT_TAG         master
  GIT_SHALLOW     TRUE
)

message(STATUS "Download and build FLTK if necessary, please wait...")
FetchContent_MakeAvailable(FLTK)
message(STATUS "Download and build FLTK - done.")

add_executable       (hello WIN32 MACOSX_BUNDLE hello.cxx)
target_link_libraries(hello PRIVATE fltk::fltk)
---

This is as simple as it can be. The CMake FetchContent module is used to
download the FLTK sources from their Git repository and to build them.
Note that this will download and build the FLTK library during the CMake
configure phase which can take some time. Therefore the statement
`FetchContent_MakeAvailable()` is wrapped in `message(STATUS "...")`
commands to let the user know what's going on.


 4  FindFLTK.cmake and find_package(FLTK)
==========================================

The FindFLTK.cmake module provided by CMake which is also used in the
CMake command find_package(FLTK) does not yet support FLTK's new "Modern
CMake" features.

Unfortunately this module has to be used if the FLTK library wasn't built
with CMake and thus CONFIG mode can't be used. In this case CMake falls back
to MODULE mode and find_package() uses this old CMake module.

There are plans to provide a FindFLTK.cmake module with FLTK 1.4.0 but this
module is not yet written. Look here for further info if you need it...