Display Git revision in docs generated from releases (#499)

- makesrcdist: store Git revision in a file in the tarball
 - CMake/resources.cmake: get git revision either from Git or file and
   store it as CMake cache variable 'FLTK_GIT_REVISION' for reference
 - documentation/*: get git revision from git or file
 - fluid/documentation/*: get git revision from git or file

CMake/resources.cmake

@@ -40,6 +40,55 @@ macro(fl_find_header VAR HEADER)
   endif(NOT CMAKE_REQUIRED_QUIET)
 endmacro(fl_find_header)
 
+
+#######################################################################
+# find git revision and store it in the CMake cache for reference
+#######################################################################
+
+# (1) Get current Git revision from `git rev-parse ...`
+# (2) Read Git revision from file `fltk_git_rev.dat`
+#
+# (1) This can fail if the FLTK source directory is not a Git checkout,
+#     i.e. FLTK was downloaded as a distro (tarball).
+# (2) If (1) fails the file `fltk_git_rev.dat` is read. This file is
+#     generated by the process to generate the distribution (makesrcdist).
+#
+
+set(git_rev_file ${FLTK_SOURCE_DIR}/fltk_git_rev.dat)
+
+set(git_revision "")                    # temporary variable
+
+execute_process(COMMAND
+  git rev-parse HEAD                    # --short=${git_rev_size} HEAD
+  OUTPUT_VARIABLE git_revision
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+  WORKING_DIRECTORY ${FLTK_SOURCE_DIR}
+  ERROR_QUIET
+)
+
+if(git_revision STREQUAL "")
+
+  # Read git revision from a file generated by makesrcdist.
+  # This file is located in the FLTK source directory
+
+  if(EXISTS ${git_rev_file})
+    file(READ ${git_rev_file} git_revision)
+    string(STRIP "${git_revision}" git_revision)
+  else()
+    set(git_revision "unknown")
+  endif()
+endif()
+
+set(FLTK_GIT_REVISION "${git_revision}"
+    CACHE STRING
+    "FLTK Git revision (do not change)"
+    FORCE)
+
+# debug and unset temporary variables
+# fl_debug_var(git_revision)
+unset(git_rev_file)
+unset(git_revision)
+
 #######################################################################
 # Include FindPkgConfig for later use of pkg-config
 #######################################################################

documentation/CMakeLists.txt

@@ -1,7 +1,7 @@
 #
 # CMakeLists.txt to build docs for the FLTK project using CMake (www.cmake.org)
 #
-# Copyright 1998-2023 by Bill Spitzak and others.
+# Copyright 1998-2024 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
@@ -16,7 +16,6 @@
 
 set(DOCS)
 set(GENERATE_DOCS FALSE)
-set(GIT_REVISION "")
 set(YEAR "")
 set(CURRENT_DATE "")
 
@@ -49,28 +48,8 @@ if(GENERATE_DOCS)
     OUTPUT_STRIP_TRAILING_WHITESPACE
   )
 
-  # find git revision
-
-  # FIXME: This must also work with tarballs where git is not available.
-  #        For now we just ignore errors and set GIT_REVISION = "unknown".
-  #        In the future tarball/zip generation should create a file
-  #        that contains the git revision.
-
-  execute_process(COMMAND
-    git rev-parse --short=10 HEAD
-    OUTPUT_VARIABLE GIT_REVISION
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    WORKING_DIRECTORY ${FLTK_SOURCE_DIR}
-    ERROR_QUIET
-  )
-
-  # set to "'unknown'" if git is not available
-  if(GIT_REVISION STREQUAL "")
-    set(GIT_REVISION "'unknown'")
-  endif()
-
   # Find "short" doxygen version if it was built from Git
-  # Note: this is still needed in CMake 3.12.0 but later CMake versions
+  # Note: this is still needed in CMake 3.15 but later CMake versions
   #       (notably 3.25) remove the Git revision in 'DOXYGEN_VERSION'.
   # Todo: Find the "first good" CMake version and remove this redundant
   #       code once we require this as our minimal version and replace the
@@ -98,7 +77,7 @@ if(GENERATE_DOCS)
   if(0) # debug
     fl_debug_var(YEAR)
     fl_debug_var(CURRENT_DATE)
-    fl_debug_var(GIT_REVISION)
+    fl_debug_var(FLTK_GIT_REVISION)
     fl_debug_var(DOXYGEN_FOUND)
     fl_debug_var(DOXYGEN_EXECUTABLE)
     fl_debug_var(DOXYGEN_VERSION)

documentation/Makefile

@@ -55,6 +55,17 @@ MANPAGES =	$(SRC_DOCDIR)/fltk.$(CAT3EXT) $(SRC_DOCDIR)/fltk-config.$(CAT1EXT) \
 		$(SRC_DOCDIR)/checkers.$(CAT6EXT) $(SRC_DOCDIR)/sudoku.$(CAT6EXT) \
 		$(SRC_DOCDIR)/fltk-options.$(CAT1EXT)
 
+# Get FLTK's Git Revision either from Git /or/ from fltk_git_rev.dat (Issue #499)
+#
+# Note: this may fail (return "unknown") if the sources were downloaded
+# from GitHub as a "release" (zip) archive. This is not supported.
+
+# Test/debug only: should be commented out unless used (see: debug_git_rev)
+# GIT_REV_FROM_GIT  := "$$(git rev-parse HEAD 2>/dev/null)"
+# GIT_REV_FROM_FILE := "$$(cat ../fltk_git_rev.dat 2>/dev/null)"
+
+FLTK_GIT_REVISION := "`( (git rev-parse HEAD || cat ../fltk_git_rev.dat;) || echo 'unknown'; ) 2>/dev/null`"
+
 all:	$(MANPAGES)
 
 # Use `make docs' to create all docs for distribution files.
@@ -67,6 +78,11 @@ docs:	all html pdf
 alldocs: docs
 dist:	docs
 
+debug_git_rev:
+	# echo "GIT_REV_FROM_GIT  = $(GIT_REV_FROM_GIT)"
+	# echo "GIT_REV_FROM_FILE = $(GIT_REV_FROM_FILE)"
+	echo "FLTK_GIT_REVISION = $(FLTK_GIT_REVISION)"
+
 clean:
 	$(RM) Doxyfile Doxybook
 	$(RM) copyright.dox generated.dox
@@ -203,8 +219,7 @@ refman.pdf: $(HTMLFILES) Doxybook src/fltk-book.tex
 
 src/fltk-title.tex: src/fltk-title.tex.in
 	echo "Generating $@ ..."
-	GIT_REVISION=`git rev-parse --short=10 HEAD`; \
+	sed -e"s/@FLTK_GIT_REVISION@/$(FLTK_GIT_REVISION)/g" \
-	sed -e"s/@GIT_REVISION@/$$GIT_REVISION/g" \
 	    < $< > $@
 
 src/fltk-book.tex.in: src/fltk-title.tex
@@ -223,10 +238,9 @@ src/fltk-book.tex: src/fltk-book.tex.in
 generated.dox: generated.dox.in
 	echo "Generating $@ ..."
 	CURRENT_DATE=`date "+%b %d, %Y"`; \
-	GIT_REVISION=`git rev-parse --short=10 HEAD`; \
 	DOXYGEN_VERSION_SHORT=`"$(DOXYDOC)" --version|cut -f1 -d' '`; \
 	sed -e"s/@CURRENT_DATE@/$$CURRENT_DATE/g" \
-	    -e"s/@GIT_REVISION@/$$GIT_REVISION/g" \
+	    -e"s/@FLTK_GIT_REVISION@/$(FLTK_GIT_REVISION)/g" \
 	    -e"s/@DOXYGEN_VERSION_SHORT@/$$DOXYGEN_VERSION_SHORT/g" \
 	    < $< > $@
 

documentation/generated.dox.in

@@ -1,6 +1,6 @@
 <br>
 <small>
   Generated on @CURRENT_DATE@
-  from Git revision @GIT_REVISION@
+  from Git revision '@FLTK_GIT_REVISION@'
-  by Doxygen @DOXYGEN_VERSION_SHORT@
+  by Doxygen version '@DOXYGEN_VERSION_SHORT@'
 </small>

documentation/src/fltk-title.tex.in

@@ -27,7 +27,7 @@ provided this copyright and permission notice are preserved.}\\
 \vspace*{0.5cm}
 \today{}\\
 \vspace*{0.5cm}
-{\small Git revision @GIT_REVISION@}\\
+{\small Git revision '@FLTK_GIT_REVISION@'}\\
 \end{center}
 \end{titlepage}
 %

fluid/documentation/CMakeLists.txt

@@ -15,7 +15,6 @@
 #
 
 set(DOCS)
-set(GIT_REVISION "")
 set(YEAR "")
 set(CURRENT_DATE "")
 
@@ -38,26 +37,6 @@ if(FLTK_BUILD_FLUID_DOCS OR FLTK_BUILD_PDF_DOCS)
     OUTPUT_STRIP_TRAILING_WHITESPACE
   )
 
-  # find git revision
-
-  # FIXME: This must also work with tarballs where git is not available.
-  #        For now we just ignore errors and set GIT_REVISION = "unknown".
-  #        In the future tarball/zip generation should create a file
-  #        that contains the git revision.
-
-  execute_process(COMMAND
-    git rev-parse --short=10 HEAD
-    OUTPUT_VARIABLE GIT_REVISION
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    WORKING_DIRECTORY ${FLTK_SOURCE_DIR}
-    ERROR_QUIET
-  )
-
-  # set to "'unknown'" if git is not available
-  if(GIT_REVISION STREQUAL "")
-    set(GIT_REVISION "'unknown'")
-  endif()
-
   # Find "short" doxygen version if it was built from Git
   # Note: this is still needed in CMake 3.12.0 but later CMake versions
   #       (notably 3.25) remove the Git revision in 'DOXYGEN_VERSION'.

fluid/documentation/generated.dox.in

@@ -1,6 +1,6 @@
 <br>
 <small>
   Generated on @CURRENT_DATE@
-  from Git revision @GIT_REVISION@
+  from Git revision '@FLTK_GIT_REVISION@'
-  by Doxygen @DOXYGEN_VERSION_SHORT@
+  by Doxygen version '@DOXYGEN_VERSION_SHORT@'
 </small>

fluid/documentation/src/fluid-title.tex.in

@@ -27,7 +27,7 @@ provided this copyright and permission notice are preserved.}\\
 \vspace*{0.5cm}
 \today{}\\
 \vspace*{0.5cm}
-{\small Git revision @GIT_REVISION@}\\
+{\small Git revision '@FLTK_GIT_REVISION@'}\\
 \end{center}
 \end{titlepage}
 %

makesrcdist

@@ -52,6 +52,8 @@ SNAPSHOT='https://www.fltk.org/pub/fltk/snapshots'
 
 DATE="`date +'%Y%m%d'`"
 
+GIT_REVISION=$(git rev-parse HEAD)
+
 # VS = short version number ('major.minor'), for instance '1.4'.
 # Note: VS is used only for snapshot generation
 # fltk_version = full version number w/o 'rcN' (from file fltk_version.dat)
@@ -118,6 +120,13 @@ sed -e '1,$s/@VERSION@/'$version'/' \
 	-e '1,$s#^Source:.*#Source: '$fileurl'#' \
 	<fltk.spec.in >fltk.spec
 
+
+# Write git revision file with full git revision
+# which will be stored in the distribution tarball
+
+echo Writing git revision file...
+echo "$GIT_REVISION" > fltk_git_rev.dat
+
 echo Creating configure script...
 autoconf -f