Make FL_ABI_VERSION configurable (STR #3161).

This commit adds the configure option --with-abiversion and the CMake option
OPTION_ABI_VERSION. Both options can be set e.g. to 10304 to build with
FL_ABI_VERSION = 10304 (FLTK 1.3.4).

For IDE builds there are new files ide/<IDE-NAME>/FL/abi-version.h that
can be edited to change the ABI version before the FLTK lib is built.
Note that this file MUST be copied to the include/FL directory if the
IDE-built library is to be installed.

The default is FL_ABI_VERSION = FL_MAJOR*10000 + FL_MINOR*100 + 0, i.e.
10300 for all FLTK 1.3.x versions to keep binary compatibility (ABI).

Todo: more tests and more documentation.


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@10786 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

.gitignore

@@ -21,7 +21,8 @@
 /*.bck
 /TAGS
 
-# /FL/
+# /FL
+/FL/abi-version.h
 /FL/Makefile
 /FL/*.bck
 

CHANGES

@@ -2,6 +2,9 @@ CHANGES IN FLTK 1.3.4					RELEASED: ??? ?? ????
 
 	New features and extensions
 
+	- FLTK's ABI version can now be configured with configure or CMake.
+*FIXME*	  See further documentation in ... [TBD].
+
 	- Added full support of true subwindows to the Mac OS X platform.
 	  Window nesting to any depth is possible. An Fl_Gl_Window window or
 	  subwindow can contain Fl_Window's as subwindows.

CMake/install.cmake

@@ -36,6 +36,10 @@ install(DIRECTORY ${FLTK_SOURCE_DIR}/FL
    PATTERN ".svn" EXCLUDE
 )
 
+install(DIRECTORY ${FLTK_BINARY_DIR}/FL
+   DESTINATION ${FLTK_INCLUDEDIR} USE_SOURCE_PERMISSIONS
+)
+
 if(OPTION_CREATE_LINKS)
    install(SCRIPT ${FLTK_BINARY_DIR}/install-symlinks.cmake)
 endif(OPTION_CREATE_LINKS)

CMake/options.cmake

@@ -33,6 +33,13 @@ set(OPTION_ARCHFLAGS ""
    )
 add_definitions(${OPTION_ARCHFLAGS})
 
+#######################################################################
+set(OPTION_ABI_VERSION ""
+   CACHE STRING
+   "FLTK ABI Version (FL_ABI_VERSION - define as 10x0y for 1.x.y)"
+   )
+set(FL_ABI_VERSION ${OPTION_ABI_VERSION})
+
 #######################################################################
 #######################################################################
 if(UNIX)

CMakeLists.txt

@@ -57,6 +57,12 @@ include(CMake/variables.cmake)
 #######################################################################
 include(CMake/export.cmake)
 
+configure_file(
+ ${FLTK_SOURCE_DIR}/abi-version.cmake.in
+ ${FLTK_BINARY_DIR}/FL/abi-version.h
+ @ONLY
+ )
+
 #######################################################################
 # build examples - these have to be built after fluid is built/imported
 #######################################################################

FL/Enumerations.H

@@ -23,23 +23,28 @@
 #ifndef Fl_Enumerations_H
 #define Fl_Enumerations_H
 
-/* Uncomment the following FL_ABI_VERSION line to enable ABI breaking fixes
+/*
- * in the current patch release of FLTK. ** Use for static builds only! **
- * For more info on this macro, see: http://fltk.org/cmp.php#FLTK_ABI_VERSION
  ******************************************************************************
- * Note: the link above is outdated.
+ * Notes on FL_ABI_VERSION and deprecated (obsolete) FLTK_ABI_VERSION:
+ *
+ * (1)	FLTK_ABI_VERSION is deprecated, but still defined below.
+ *	Do NOT define FLTK_ABI_VERSION here - it would be overwritten later.
+ *
+ * (2)	FL_ABI_VERSION is now (as of FLTK 1.3.4) defined by configure
+ *	or CMake. Do NOT define it here. Its definition will be included
+ *	below by "#include <FL/abi-version.h>".
+ *
+ * (3)	If you use the provided IDE files (Windows VC++ or Xcode) you should
+ *	edit the definition in the provided IDE subdirectory. The correct
+ *	file is `/path/to/fltk/ide/<IDE-name>/FL/abi-version.h' .
+ *
+ ******************************************************************************
+ * For more info on FL_ABI_VERSION, see: http://fltk.org/cmp.php#FL_ABI_VERSION
  * FIXME: Update docs ...
  ******************************************************************************
- * This is work in progress!
- *
- *  OLD: FLTK_ABI_VERSION	deprecated, but defined later (see below)
- *  NEW: FL_ABI_VERSION		FIXME: to be defined by configure !
- *
- * The intent is to define FL_ABI_VERSION by configure and CMake.
- * When this is done, the definition will be #include'd here !
- ******************************************************************************
  */
-//#define FL_ABI_VERSION 10304
+
+#include <FL/abi-version.h>
 
 #  include "Fl_Export.H"
 #  include "fl_types.h"
@@ -166,7 +171,8 @@
 
     10300 <= FL_ABI_VERSION <= 10304
 
-  Note: configure + CMake not yet implemented, see also STR #3161.
+  Note: configure + CMake can be used to define FL_ABI_VERSION, but they
+  do not check validity. This is done here.
 */
 
 #if FL_ABI_VERSION < FL_MAJOR_VERSION*10000 + FL_MINOR_VERSION*100
@@ -184,8 +190,8 @@
 /*
   FLTK_ABI_VERSION is deprecated (replaced by FL_ABI_VERSION).
 
-  This deprecated constant should be removed in FLTK 1.4.0 and later.
+  This deprecated constant will be removed in FLTK 1.4.0 and later.
-  Please use FL_ABI_VERSION instead.
+  Please use FL_ABI_VERSION when FLTK 1.4.0 has been released.
 */
 
 #ifdef FLTK_ABI_VERSION

Makefile

@@ -70,6 +70,7 @@ distclean: clean
 	$(RM) fltk-config fltk.list makeinclude
 	$(RM) fltk.spec
 	$(RM) FL/Makefile
+	$(RM) FL/abi-version.h
 	$(RM) documentation/*.$(CAT1EXT)
 	$(RM) documentation/*.$(CAT3EXT)
 	$(RM) documentation/*.$(CAT6EXT)

README.MSWindows.txt

@@ -389,6 +389,9 @@ without adding link and include paths to the solution.
 
   copy the entire FL directory into the include path
 
+  add all files from ide\VisualC2008\FL to the FL directory copied above
+    (this is currently only one file: abi-version.h)
+
   copy all .lib files from the fltk lib directory to the VC lib directory
 
   copy fluid.exe in the fluid directory to the bin directory
@@ -500,6 +503,9 @@ without adding link and include paths to the solution.
 
   copy the entire FL directory into the include path
 
+  add all files from ide\VisualC2010\FL to the FL directory copied above
+    (this is currently only one file: abi-version.h)
+
   copy all .lib files from the fltk lib directory to the VC lib directory
 
   copy fluid.exe in the fluid directory to the bin directory
@@ -638,3 +644,4 @@ Oct 25 2010 - matt: restructured entire document and verified instructions
 Dec 20 2010 - matt: merged with README.win32
 Dec 22 2010 - AlbrechtS: added newer Cygwin (cross/mingw-w64) options
 Feb 24 2012 - AlbrechtS: clarified console window FAQ
+Jul 12 2015 - AlbrechtS: add abi-config.h to files to be copied

abi-version.cmake.in

@@ -0,0 +1,7 @@
+/*
+  DO NOT EDIT - This file is generated by CMake
+*/
+
+/* define FL_ABI_VERSION as 10x0y for FLTK ABI version 1.x.y */
+
+#cmakedefine FL_ABI_VERSION @FL_ABI_VERSION@

abi-version.in

@@ -0,0 +1,7 @@
+/*
+  DO NOT EDIT - This file is generated by configure
+*/
+
+/* define FL_ABI_VERSION as 10x0y for FLTK ABI version 1.x.y */
+
+#undef FL_ABI_VERSION

configure.in

@@ -172,6 +172,21 @@ AC_SUBST(GLLIBBASENAME)
 AC_SUBST(IMGLIBBASENAME)
 AC_SUBST(CAIROLIBBASENAME)
 
+has_abiversion=""
+AC_ARG_WITH(abiversion,
+[  --with-abiversion       Build with FL_ABI_VERSION, e.g. 10304 for FLTK 1.3.4])
+has_abiversion="$with_abiversion"
+if test "$has_abiversion" = "yes" ; then
+ has_abiversion=""
+else
+ if test "$has_abiversion" = "no" ; then
+  has_abiversion=""
+ fi
+fi
+if test ! "$has_abiversion" = "" ; then
+ AC_DEFINE_UNQUOTED(FL_ABI_VERSION, [$has_abiversion], [define to FL_ABI_VERSION])
+fi
+
 dnl Handle compile-time options...
 AC_ARG_ENABLE(debug, [  --enable-debug          turn on debugging [[default=no]]])
 if test x$enable_debug = xyes; then
@@ -1475,6 +1490,7 @@ fi
 
 dnl Write all of the files...
 AC_CONFIG_HEADER(config.h:configh.in)
+AC_CONFIG_HEADER(FL/abi-version.h:abi-version.in)
 AC_OUTPUT(makeinclude fltk.list fltk-config fltk.spec FL/Makefile)
 
 dnl Make sure the fltk-config script is executable...

ide/VisualC2008/FL/abi-version.h

@@ -0,0 +1,31 @@
+/*
+  DO NOT EDIT - This file must be configured BEFORE building FLTK !
+*/
+
+/*
+  ============================================================================
+  Important note to IDE users:
+  ============================================================================
+
+  This file *may* be edited *before* building FLTK with your IDE project,
+  i.e. in /path/to/fltk/ide/<your-ide>/FL/abi-version.h:
+
+    (1) Define FL_ABI_VERSION as described below.
+    (2) Rebuild the entire FLTK library.
+    (3) Optional: install files as usual including THIS file.
+
+  DO NOT edit this file after building the FLTK library, i.e. when this
+  file is already installed in a (system) directory used to build your
+  programs.
+
+  Editing this file w/o rebuilding the entire FLTK library will change
+  the ABI and thus render your programs unusable - they may crash or
+  show other unpredictable errors. You have been warned!
+
+  ============================================================================
+  End of important note to IDE users.
+  ============================================================================
+
+/* define FL_ABI_VERSION as 10x0y for FLTK ABI version 1.x.y */
+
+#define FL_ABI_VERSION 10300

ide/VisualC2010/FL/abi-version.h

@@ -0,0 +1,31 @@
+/*
+  DO NOT EDIT - This file must be configured BEFORE building FLTK !
+*/
+
+/*
+  ============================================================================
+  Important note to IDE users:
+  ============================================================================
+
+  This file *may* be edited *before* building FLTK with your IDE project,
+  i.e. in /path/to/fltk/ide/<your-ide>/FL/abi-version.h:
+
+    (1) Define FL_ABI_VERSION as described below.
+    (2) Rebuild the entire FLTK library.
+    (3) Optional: install files as usual including THIS file.
+
+  DO NOT edit this file after building the FLTK library, i.e. when this
+  file is already installed in a (system) directory used to build your
+  programs.
+
+  Editing this file w/o rebuilding the entire FLTK library will change
+  the ABI and thus render your programs unusable - they may crash or
+  show other unpredictable errors. You have been warned!
+
+  ============================================================================
+  End of important note to IDE users.
+  ============================================================================
+
+/* define FL_ABI_VERSION as 10x0y for FLTK ABI version 1.x.y */
+
+#define FL_ABI_VERSION 10300

ide/VisualC6/FL/abi-version.h

@@ -0,0 +1,31 @@
+/*
+  DO NOT EDIT - This file must be configured BEFORE building FLTK !
+*/
+
+/*
+  ============================================================================
+  Important note to IDE users:
+  ============================================================================
+
+  This file *may* be edited *before* building FLTK with your IDE project,
+  i.e. in /path/to/fltk/ide/<your-ide>/FL/abi-version.h:
+
+    (1) Define FL_ABI_VERSION as described below.
+    (2) Rebuild the entire FLTK library.
+    (3) Optional: install files as usual including THIS file.
+
+  DO NOT edit this file after building the FLTK library, i.e. when this
+  file is already installed in a (system) directory used to build your
+  programs.
+
+  Editing this file w/o rebuilding the entire FLTK library will change
+  the ABI and thus render your programs unusable - they may crash or
+  show other unpredictable errors. You have been warned!
+
+  ============================================================================
+  End of important note to IDE users.
+  ============================================================================
+
+/* define FL_ABI_VERSION as 10x0y for FLTK ABI version 1.x.y */
+
+#define FL_ABI_VERSION 10300

ide/Xcode4/FL/abi-version.h

@@ -0,0 +1,31 @@
+/*
+  DO NOT EDIT - This file must be configured BEFORE building FLTK !
+*/
+
+/*
+  ============================================================================
+  Important note to IDE users:
+  ============================================================================
+
+  This file *may* be edited *before* building FLTK with your IDE project,
+  i.e. in /path/to/fltk/ide/<your-ide>/FL/abi-version.h:
+
+    (1) Define FL_ABI_VERSION as described below.
+    (2) Rebuild the entire FLTK library.
+    (3) Optional: install files as usual including THIS file.
+
+  DO NOT edit this file after building the FLTK library, i.e. when this
+  file is already installed in a (system) directory used to build your
+  programs.
+
+  Editing this file w/o rebuilding the entire FLTK library will change
+  the ABI and thus render your programs unusable - they may crash or
+  show other unpredictable errors. You have been warned!
+
+  ============================================================================
+  End of important note to IDE users.
+  ============================================================================
+
+/* define FL_ABI_VERSION as 10x0y for FLTK ABI version 1.x.y */
+
+#define FL_ABI_VERSION 10300