README.developer.txt - FLTK developer related docs -------------------------------------------------- CONTENTS ======== 1 FLTK Build Macros 1.1 WIN32 1.2 __CYGWIN__ 1.3 __APPLE__ 1.4 __APPLE_QUARTZ__ 1.5 FLTK_USE_X11 1.6 FLTK_USE_WAYLAND 1.7 USE_XFT 1.8 FL_LIBRARY 1.9 FL_DLL 1.10 FL_EXPORT 1.11 FL_OVERRIDE 1.12 WIN_API 1.13 FL_INTERNALS 1.14 FL_DOXYGEN 1.15 FL_ABI_VERSION 2 Makefile Standards 2.1 General Organization 2.2 Makefile Documentation 2.3 Portable Makefile Construction 2.4 Standard Variables 2.5 Standard Targets 2.6 Object Files 2.7 Programs 2.8 Static Libraries 2.9 Shared Libraries 2.10 Dependencies 2.11 Install/Uninstall Support X FLTK Software Releases X.1 Version Numbering X.2 Generation X.3 Testing X.4 Releases X.4.1 Beta Releases X.4.2 Release Candidates X.4.3 Production Releases X.4.4 Major Releases X.4.5 Minor Releases X.4.6 Patch Releases 1. FLTK Build Macros ===================== Files FL/fl_config.h and config.h and the C++ compilers define a few preprocessor variables that help organize platform-specific code and control access to a few internal classes. Only code internal to the FLTK library can include the config.h header file, whereas FL/fl_config.h is accessible by user code (installed). Thus, FLTK header files that are part of the public API must not, directly or indirectly, #include config.h. 1.1 _WIN32 ----------- Defined on the MS-Windows platform, both for 32-bit and 64-bit, and for all architectures: i386, x86_64, arm, etc. Note: FLTK 1.3.x: used WIN32 which had to be defined by the FLTK build system. FLTK 1.4.x: uses _WIN32 (with leading underscore) which should be defined by build tools (preprocessor, compiler) on the Windows platform. 1.2 __CYGWIN__ --------------- Defined when FLTK runs on Windows but uses Cygwin's POSIX emulation features (cygwin1.dll). 1.3 __APPLE__ -------------- Defined on the macOS platform. 1.4 __APPLE_QUARTZ__ --------------------- >> Deprecated in FLTK 1.4 and will be removed in a future version. >> Use __APPLE__ instead. Defined by config.h for the macOS platform. At present, use of __APPLE_QUARTZ__ is equivalent to using __APPLE__. 1.5 FLTK_USE_X11 ----------------- Defined by config.h when Xlib is the graphics system used. FLTK_USE_X11 is defined on all Unix and Linux platforms, and on Windows if configure used --enable-cygwin and --enable-x11. FLTK_USE_X11 is also defined when building FLTK for macOS with: cmake -DOPTION_APPLE_X11=On ..or: configure –enable-x11 1.6 FLTK_USE_WAYLAND --------------------- Defined by config.h when building under Linux/Unix for the Wayland platform. -- -- CAUTION -- -- Unless the FLTK library was built with “cmake -DOPTION_WAYLAND_ONLY=On” or with “configure --disable-x11”, the Wayland-enabled libfltk is a hybrid library supporting both the Wayland and the X11 protocols. Therefore, both FLTK_USE_WAYLAND and FLTK_USE_X11 are defined in this situation. -- -- -- 1.7 USE_XFT ------------ Defined by config.h when FLTK_USE_X11 is defined. Set to 1 when the Xft library of scalable anti-aliased fonts is used, or 0 otherwise. 1.8 FL_LIBRARY --------------- Defined by all FLTK library build systems when the FLTK library itself is compiled. Application program developers should not define it when compiling their programs. 1.9 FL_DLL ----------- Defined when building shared libraries (DLL's) with Visual Studio. Application developers using Visual Studio and linking against the shared FLTK libraries (DLL's) built with Visual Studio must define this macro when compiling their source files. This macro *must* be defined by the build system (VS project setup/properties) or via the compiler command line so it is "seen" by all included FLTK header files. 1.10 FL_EXPORT --------------- Must be used when defining a symbol (class, member, global variable or function) in one of the FLTK libraries (e.g., libfltk, libfltk_images) so that it can be used outside this library. FL_EXPORT is defined in "FL/Fl_Export.H" which is included by "FL/Fl.H". Examples: class FL_EXPORT Fl_Graphics_Driver { .. }; FL_EXPORT void fl_open_display(); FL_EXPORT Fl_Fontsize FL_NORMAL_SIZE; 1.11 FL_OVERRIDE ----------------- Should be used when overriding a virtual function, such as where the C++11 qualifier override would be used. FL_OVERRIDE is defined in FL/fl_attr.h which is ultimately included by FL/Fl.H 1.12 WINAPI ------------ Must be used under the Windows platform when defining the type of a pointer to a function in a system library. Example: typedef BOOL(WINAPI* os_func_ptr)(HMONITOR, LPMONITORINFO); 1.13 FL_INTERNALS ------------------ Application program developers can define this variable to get access to certain internal classes (e.g., the Fl_X class) if they need it. APIs to these internal classes are highly subject to change, though. 1.14 FL_DOXYGEN ---------------- Defined when the Doxygen program that builds the FLTK documentation processes the source code. This variable has two major uses: 1. To hide code from Doxygen, e.g. #ifndef FL_DOXYGEN .. code to hide .. #endif 2. The Doxygen program does not define the platform-specific variables __APPLE__ or _WIN32 (even if it's run on macOS or Windows). Thus, platform-specific (say, macOS-specific) code must be bracketed as follows to be seen by Doxygen: #if defined(__APPLE__) || defined(FL_DOXYGEN) ... Doxygen-visible, macOS-specific code ... #endif 1.15 FL_ABI_VERSION -------------------- Used to allow developers to implement ABI breaking code in Patch Releases. Normally set to the default ABI version for each minor version (for instance 10400 for all 1.4.x releases), can be changed by users or devs with configure or CMake to enable ABI breaking features for testing or use by end users in static builds of FLTK. Note: This preprocessor variable was named FLTK_ABI_VERSION in FLTK 1.3.x and was renamed to FL_ABI_VERSION since FLTK 1.4.0. When set, the variable's value is expected to be the integer representation of the FLTK version number, where the Minor and Patch numbers are padded to two digits to allow for numbers 1 thru 99, e.g. #define FL_ABI_VERSION 10401 // FLTK ABI version 1.4.1 └┤└┤│ │ │└─ PATCH version (no padding, avoids octal issues) │ └── MINOR version (2 digit padding) └──── MAJOR version (2 digit padding) ABI breaking features are by default '#ifdef'ed out with this variable during patch releases, and are merged in by developers during the next Minor Release or Major Release. Example. If the current patch release is 1.4.0, and the developer adds an ABI-breaking fix to what will be the next 1.4.1 release, then the new code would be implemented as: #if FL_ABI_VERSION >= 10401 // FLTK 1.4.1, the next patch release # ... new ABI breaking code … #else ... old non-ABI breaking (default builds) … #endif This variable solves several issues: > Allows ABI breaking code to be implemented at any time by developers. > Gets fixes into Git sooner, so users can see/test/access it. > Testing ABI features during Patch Releases increases stability of Minor Releases. > Prevents devs deferring ABI breaking code to small windows of time preceding Minor Releases. 2 Makefile Standards ===================== The following is a guide to the makefile-based build system used by FLTK. These standards have been developed over the years to allow FLTK to be built on as many systems and environments as possible. 2.1 General Organization -------------------------- The FLTK source code is organized functionally into a top-level makefile, include file, and subdirectories each with their own makefile and dependencies files: Makefile.in configh.in configure.in makeinclude.in FL Makefile.in *.H fltk *.h fluid Makefile makedepend *.h *.c *.cxx src Makefile makedepend *.h *.c *.cxx test Makefile makedepend *.h *.c *.cxx The ".in" files are template files for the autoconf and CMake software and are used to generate a static version of the corresponding file. 2.2 Makefile Documentation ---------------------------- Each Makefile must start with the standard FLTK header containing a description of the file, and the FLTK copyright/license notice. Note: As of July 2020, we no longer use Subversion "$Id$" keywords or 'End of' trailers. Example: ────────────────────────────────────────────────────────────────────── # # Some descriptive text for the Fast Light Tool Kit (FLTK). # # Copyright 1998-2020 by Bill Spitzak and others. # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Library General Public # License as published by the Free Software Foundation; either # version 2 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Library General Public License for more details. # # You should have received a copy of the GNU Library General Public # License along with this library; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 # USA. # # Please see the following page on how to report bugs and issues: # # https://www.fltk.org/bugs.php # ────────────────────────────────────────────────────────────────────── 2.3 Portable Makefile Construction ------------------------------------ FLTK uses a common subset of make program syntax to ensure that the software can be compiled "out of the box" on as many systems as possible. The following is a list of assumptions we follow when constructing makefiles ("→" is used to indicate TAB character): ● Targets; we assume that the make program supports the notion of simple targets of the form "name:" that perform tab-indented commands that follow the target, e.g.: target: → Tab target commands ● Dependencies; we assume that the make program supports recursive dependencies on targets, e.g.: target: foo bar → target commands foo: bla → foo commands bar: → bar commands bla: → bla commands ● Variable Definition; we assume that the make program supports variable definition on the command-line or in the makefile using the following form: name=value ● Variable Substitution; we assume that the make program supports this in the following forms: ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Variable ┃ Description ┃ ┣━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ $(name) ┃ substitutes value of "name", ┃ ┃ ($name:.old=.new) ┃ substitutes value of "name" with filename extensions ".old" changed to ".new" ┃ ┃ $(MAKEFLAGS) ┃ substitutes make command-line options without leading hyphen (-) ┃ ┃ $$ ┃ substitutes a single $ character ┃ ┃ $< ┃ substitutes the current source file or dependency ┃ ┃ $@ ┃ substitutes the current target name. ┃ ┗━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ● Suffixes; we assume that the make program supports filename suffixes with assumed dependencies, e.g.: .SUFFIXES: .c .o .c.o: → $(CC) $(CFLAGS) -o $@ -c $< ● Include Files; we assume make supports the include directive, e.g.: include ../makeinclude include makedepend ● Comments; we assume comments begin with a # character and proceed to the end of the current line. ● Line Length; there is no practical limit to the length of lines. ● Continuation of long lines; the \ character at the end of a line to concatenate two or more lines in a makefile to form a single long line. ● Shell; we assume a POSIX-compatible shell is present on the build system. 2.4 Standard Variables ------------------------ The following variables are defined in the "makeinclude" file generated by the autoconf software: ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Autoconf ┃ ┃ ┃ Variable ┃ Description ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ AR ┃ the library archiver command, ┃ ┃ ARFLAGS ┃ options for the library archiver command, ┃ ┃ BUILDROOT ┃ optional installation prefix, ┃ ┃ CAT1EXT ┃ extension for formatted man pages in section 1, ┃ ┃ CAT3EXT ┃ extension for formatted man pages in section 3, ┃ ┃ CC ┃ the C compiler command, ┃ ┃ ┗CFLAGS ┃ options for the C compiler command, ┃ ┃ CXX ┃ the C++ compiler command, ┃ ┃ CXXFLAGS ┃ options for the C++ compiler command, ┃ ┃ DOXYGEN ┃ the doxygen command, ┃ ┃ DSOCOMMAND ┃ the shared library building command, ┃ ┃ EXEEXT ┃ the extension for executable programs, ┃ ┃ FLUID ┃ the FLUID executable to install, ┃ ┃ GLDEMOS ┃ the OpenGL demos to build, ┃ ┃ GLLIBS ┃ libraries for OpenGL programs, ┃ ┃ HTMLDOC ┃ the htmldoc command, ┃ ┃ IMAGEDIRS ┃ image library directories to build, ┃ ┃ IMGLIBS ┃ libraries for image programs, ┃ ┃ INSTALL ┃ the install command, ┃ ┃ INSTALL_BIN ┃ the program installation command, ┃ ┃ INSTALL_DATA ┃ the data file installation command, ┃ ┃ INSTALL_DIR ┃ the directory installation command, ┃ ┃ INSTALL_LIB ┃ the library installation command, ┃ ┃ INSTALL_MAN ┃ the documentation installation command, ┃ ┃ INSTALL_SCRIPT ┃ the shell script installation command, ┃ ┃ LDFLAGS ┃ options for the linker, ┃ ┃ LIBNAME ┃ the name of the FLTK library to install, ┃ ┃ LIBS ┃ libraries for all programs, ┃ ┃ LN ┃ the ln command, ┃ ┃ MAKEDEPEND ┃ the makedepend command, ┃ ┃ MKDIR ┃ the mkdir command, ┃ ┃ NROFF ┃ the nroff command, ┃ ┃ OPTIM ┃ common compiler optimization options, ┃ ┃ POSTBUILD ┃ the post build command to run (macOS), ┃ ┃ RM ┃ the rm command, ┃ ┃ RMDIR ┃ the rmdir command, ┃ ┃ SHAREDLIBS ┃ shared libraries for installed programs, ┃ ┃ SHELL ┃ the sh (POSIX shell) command, ┃ ┃ STRIP ┃ the strip command, ┃ ┃ THREADS ┃ the threading demos to build, ┃ ┃ bindir ┃ the binary installation directory, ┃ ┃ datadir ┃ the data file installation directory, ┃ ┃ exec_prefix ┃ the installation prefix for executable files, ┃ ┃ libdir ┃ the library installation directory, ┃ ┃ mandir ┃ the man page installation directory, ┃ ┃ prefix ┃ the installation prefix for non-executable files ┃ ┃ srcdir ┃ the source directory. ┃ ┗━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ 2.5 Standard Targets ---------------------- The following standard targets must be defined in each makefile: ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Makefile ┃ ┃ ┃ Target Name ┃ Description ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ all ┃ creates all target programs, libraries, and documentation files ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ clean ┃ removes all target programs, libraries, documentation files, ┃ ┃ ┃ and object files. ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ depend ┃ generates automatic dependencies for any C or C++ source files ┃ ┃ ┃ (see also "Dependencies") ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ distclean ┃ removes autoconf-generated files in addition to those removed by ┃ ┃ ┃ the "clean" target ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ install ┃ installs all distribution files in their corresponding locations ┃ ┃ ┃ (see also "Install/Uninstall Support") ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ uninstall ┃ removes all distribution files from their corresponding locations┃ ┃ ┃ (also see "Install/Uninstall Support") ┃ ┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ unittest ┃ runs any unit tests that have been created for the corresponding ┃ ┃ ┃ code and programs. ┃ ┗━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ 2.6 Object Files ------------------ TBD 2.7 Programs -------------- 2.8 Static Libraries ---------------------- 2.9 Shared Libraries ---------------------- 2.10 Dependencies ------------------ 2.11 Install/Uninstall Support ------------------------------- X FLTK Software Releases ========================= TBD X.1 Version Numbering ---------------------- X.2 Generation --------------- X.3 Testing ------------ X.4 Releases ------------- X.4.1 Beta Releases -------------------- X.4.2 Release Candidates ------------------------- X.4.3 Production Releases -------------------------- X.4.4 Major Releases --------------------- X.4.5 Minor Releases --------------------- X.4.6 Patch Releases ---------------------