[gnuastro-commits] master 63cb02a: Bootstrapping: separate target for building all necessary images

[Mohammad Akhlaghi]

branch: master
commit 63cb02a78b7d5c0d8ea9ea67d31337be4a075997
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Bootstrapping: separate target for building all necessary images
    
    The 'doc/plotsrc/Makefile' is in charge of building the figures in the
    PDF/HTML manual. However, its main rule (to build 'doc/plotsrc/all.pdf')
    didn't take into account that when a command fails in standard Make, the
    rest of the commands in the rule continue without problem!
    
    On the other hand, the main target in 'doc/Makefile' to build the figures
    (that would trigger calling 'doc/plotsrc/Makefile') was one of the image
    '.txt' files that was created relatively early.
    
    As a result of both the issues above combined: when building of one of the
    figures failed during bootstrapping, the error was hidden in the middle of
    the output and only show itself when 'make pdf' was ran. Confusing us on
    why the image is not built.
    
    With this commit, the main target of 'doc/plotsrc/Makefile' is no longer a
    file that is actually used. But a specific file called 'done.txt' which is
    made in the 'doc/gnuastro-figures' directory, only when all the images are
    built. Also, the recipe of this target is all effectively a single shell
    line (with many individual commands, separated by '&&'). So if any of the
    commands fail, the final target will never be built and nothing extra will
    be printed, helping find the cause of the problem much more easily.
    
    This issue was reported by Francois Ochsenbein.
---
 doc/Makefile.am      |  4 ++--
 doc/plotsrc/Makefile | 46 ++++++++++++++++++++++++++--------------------
 2 files changed, 28 insertions(+), 22 deletions(-)

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a7d152f..12dc957 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -28,10 +28,10 @@ SHELL=/bin/sh
 
 
 # Built files that should be treated as sources for the main job.
-# img_representative: This is just one of the images that is used in the
+# imgrepresentative: This is just one of the images that is used in the
 # book as a representative for all of them because they are all built with
 # one script.
-imgrepresentative = $(top_srcdir)/doc/gnuastro-figures/flatplane.txt
+imgrepresentative = $(top_srcdir)/doc/gnuastro-figures/done.txt
 BUILT_SOURCES = $(srcdir)/authors.texi $(imgrepresentative)
 
 
diff --git a/doc/plotsrc/Makefile b/doc/plotsrc/Makefile
index 2d956ad..482dfc0 100644
--- a/doc/plotsrc/Makefile
+++ b/doc/plotsrc/Makefile
@@ -20,7 +20,8 @@
 # <http://www.gnu.org/licenses/>.
 
 # Definitions of which rules to apply:
-all: all.pdf
+finaltarget=../gnuastro-figures/done.txt
+all: $(finaltarget)
 .PHONY: clean
 
 
@@ -35,22 +36,27 @@ tikz:
 
 
 
-# Make all the plots and convert all the figures
-all.pdf: all.tex ./tex/*.tex ./conversions.sh | tikz
-
-#       Run the LaTeX script:
-       latex -shell-escape all.tex
-       dvipdf all.dvi
-       rm -f *.bcf *.xml *.aux *.auxlock *.log *.out *.dvi
-
-#       Put all the EPS files in their appropriate place:
-       cp tikz/all-figure0.eps ../gnuastro-figures/iandtime.eps
-       cp tikz/all-figure1.eps ../gnuastro-figures/samplingfreq.eps
-       cp tikz/all-figure2.eps ../gnuastro-figures/flatplane.eps
-       cp tikz/all-figure3.eps ../gnuastro-figures/sphereandplane.eps
+# Make all the plots with LaTeX, then convert all the figures to the
+# necessary formats using a separate script and finally write the final
+# target.
+#
+# Explanation for putting all the commands in one line (by ending them with
+# a '\' and starting the next one with '&&'). We do this because we can't
+# assume GNU Make, or GNU Bash here (to use the '.SHELLFLAGS = -ec' and
+# '.ONESHELL:' features in the Makefile). The user's Make or shell can be
+# any implementation. If any of these commands fails, the final target
+# should not be built and the Makefile should crash.
+$(finaltarget): all.tex ./tex/*.tex ./conversions.sh | tikz
 
-#       Do all the conversions:
-       ./conversions.sh ../gnuastro-figures/
+       latex -shell-escape all.tex \
+       && dvipdf all.dvi \
+       && rm -f *.bcf *.xml *.aux *.auxlock *.log *.out *.dvi \
+       && cp tikz/all-figure0.eps ../gnuastro-figures/iandtime.eps \
+       && cp tikz/all-figure1.eps ../gnuastro-figures/samplingfreq.eps \
+       && cp tikz/all-figure2.eps ../gnuastro-figures/flatplane.eps \
+       && cp tikz/all-figure3.eps ../gnuastro-figures/sphereandplane.eps \
+       && ./conversions.sh ../gnuastro-figures/ \
+       && echo "All necessary images created." > $(finaltarget)
 
 
 
@@ -63,7 +69,7 @@ all.pdf: all.tex ./tex/*.tex ./conversions.sh | tikz
 #   2. Remove everything in the gnuastro-figures directory
 #   3. Put the actual images back in that directory.
 clean:
-       rm -rf all.pdf tikz
-       cp ../gnuastro-figures/epicycles.png ./
-       rm ../gnuastro-figures/*
-       mv epicycles.png ../gnuastro-figures/
+       rm -rf all.pdf tikz \
+       && cp ../gnuastro-figures/epicycles.png ./ \
+       && rm ../gnuastro-figures/* \
+       && mv epicycles.png ../gnuastro-figures/