Source directory links to build directory all managed in configure

Until now, the `tex/build' symbolic link was put in the clone/source tree
when the build-directory's `tex' directory was being built. Thanks to
Roberto Baena, we just found a bug because of this behavior: when a second
group member is trying to build the pipeline, since the build directory's
`tex' directory already exists, no `tex/build' will be put in their
clone/source directory. As a result, the PDF building will crash.

To fix this (and keep things organized), the two `tex/build' and `tex/tikz'
links (to the build directory) are now built in the configure step while it
is building all the top-level directories. They are no longer built within
the Makefiles.

Also, a comment was added on top of every directory built during the
configuration phase to be clear.

This fixes bug #56362.

5 files changed, 53 insertions, 18 deletions

diff --git a/.file-metadata b/.file-metadata
index 065d3df..94e2c05 100644
--- a/.file-metadata
+++ b/.file-metadata
diff --git a/configure b/configure
index 000ec4f..af14f84 100755
--- a/configure
+++ b/configure
@@ -176,8 +176,6 @@ done
 #
 # These are defined to help make this script more readable.
 topdir=$(pwd)
-lbdir=.build
-installedlink=.local
 optionaldir="/optional/path"
 adir=reproduce/analysis/config
 cdir=reproduce/software/config
@@ -383,7 +381,7 @@ the source directory. The build directory also needs a relatively large
 amount of free space (atleast serveral Giga-bytes), while the source
 directory (all plain text) will usually be a mega-byte or less.
 
-'$lbdir' (a symbolic link to the build directory) will also be created
+'.build' (a symbolic link to the build directory) will also be created
 during this configuration. It can help encourage you to set the actual
 build directory in a very different address from this one (one that can be
 deleted and has large volume), while having easy access to it from here.
@@ -623,48 +621,88 @@ fi
 
 
 
-# Setup the top-level directories
+# Project's top-level directories
 # -------------------------------
-rm -f $lbdir
-ln -s $bdir $lbdir
-
+#
+# These directories are possibly needed by many steps of process, so to
+# avoid too many directory dependencies throughout the software and
+# analysis Makefiles (thus making them hard to read), we are just building
+# them here
+# Top-level software
 sdir=$bdir/software
 if ! [ -d $sdir ];  then mkdir $sdir; fi
 
+# Software tarballs
 tardir=$sdir/tarballs
 if ! [ -d $tardir ];  then mkdir $tardir; fi
 
+# Installed software
 instdir=$sdir/installed
 if ! [ -d $instdir ]; then mkdir $instdir; fi
 
+# Temporary software un-packing.
 tmpblddir=$sdir/build-tmp
 if ! [ -d $tmpblddir ]; then mkdir $tmpblddir; fi
 
+# To record software versions and citation.
 verdir=$instdir/version-info
 if ! [ -d $verdir ]; then mkdir $verdir; fi
 
+# Program and library versions and citation.
 ibidir=$verdir/proglib
 if ! [ -d $ibidir ]; then mkdir $ibidir; fi
 
+# Python module versions and citation.
 ipydir=$verdir/python
 if ! [ -d $ipydir ]; then mkdir $ipydir; fi
 
+# Used software BibTeX entries.
 ictdir=$verdir/cite
 if ! [ -d $ictdir ]; then mkdir $ictdir; fi
 
+# TeXLive versions.
 itidir=$verdir/tex
 if ! [ -d $itidir ]; then mkdir $itidir; fi
 
+# Top-level LaTeX.
 texdir=$bdir/tex
-if ! [ -d $texdir ]; then mkdir $texdir; ln -s $texdir tex/build; fi
+if ! [ -d $texdir ]; then mkdir $texdir; fi
 
+# LaTeX macros.
 mtexdir=$texdir/macros
 if ! [ -d $mtexdir ]; then mkdir $mtexdir; fi
 
-rm -f $installedlink
-ln -s $instdir $installedlink
+
+# TeX build directory. If built in a group scenario, the TeX build
+# directory must be separate for each member (so they can work on their
+# relevant parts of the paper without conflicting with each other).
+if [ "x$reproducible_paper_group_name" = x ]; then
+    texbdir=$texdir/build
+else
+    user = $(whoami)
+    texbdir = $texdir/build-$user
+fi
+if ! [ -d $texbdir ]; then mkdir $texbdir; fi
+
+# TiKZ (for building figures within LaTeX).
+tikzdir=$texbdir/tikz
+if ! [ -d $tikzdir ]; then mkdir $tikzdir; fi
+
+
+# Set the symbolic links for easy access to the top project build
+# directories. Note that these are put in each user's source/cloned
+# directory, not in the build directory (which can be shared between many
+# users and thus may already exist).
+#
+# Note: if we don't delete them first, it can happen that an extra link
+# will be created in each directory that points to its parent. So to be
+# safe, we are deleting all the links on each re-configure of the project.
+rm -f .build .local tex/build tex/tikz .gnuastro
+ln -s $bdir .build
+ln -s $instdir .local
+ln -s $texdir tex/build
+ln -s $tikzdir tex/tikz
 # --------- Delete for no Gnuastro ---------
-rm -f .gnuastro
 ln -s $topdir/reproduce/software/config/gnuastro .gnuastro
 # ------------------------------------------
 
diff --git a/paper.tex b/paper.tex
index 628e9aa..b80c4e9 100644
--- a/paper.tex
+++ b/paper.tex
@@ -95,8 +95,8 @@ are actually macros that were calculated from the same dataset (they will
 change if the dataset, or function that produced it, changes).
 
 The individual {\small PDF} file of Figure \ref{delete-me} is available
-under the \texttt{tex/build/tikz/} directory of your build directory. You
-can use this PDF file in other contexts (for example in slides showing your
+under the \texttt{tex/tikz/} directory of your build directory. You can use
+this PDF file in other contexts (for example in slides showing your
 progress or after publishing the work). If you want to directly use the
 {\small PDF} file in the figure without having to let {\small T}i{\small
   KZ} decide if it should be remade or not, you can also comment the
diff --git a/reproduce/analysis/make/initialize.mk b/reproduce/analysis/make/initialize.mk
index 5f8a062..fe7b5ea 100644
--- a/reproduce/analysis/make/initialize.mk
+++ b/reproduce/analysis/make/initialize.mk
@@ -151,8 +151,6 @@ export MPI_PYTHON3_SITEARCH   :=
 # are looking for in the outputs.
 .SUFFIXES:
 $(lockdir): | $(BDIR); mkdir $@
-$(texbdir): | $(texdir); mkdir $@
-$(tikzdir): | $(texbdir); mkdir $@ && ln -fs $@ tex/tikz
 
 
 
diff --git a/reproduce/analysis/make/paper.mk b/reproduce/analysis/make/paper.mk
index c1d5b33..34d88a4 100644
--- a/reproduce/analysis/make/paper.mk
+++ b/reproduce/analysis/make/paper.mk
@@ -91,7 +91,7 @@ $(mtexdir)/project.tex: $(foreach s, $(subst paper,,$(makesrc)), $(mtexdir)/$(s)
 # been modified, we don't want to re-build the bibliography, only the final
 # PDF.
 $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
-                      | $(tikzdir) $(texbdir) $(mtexdir)/project.tex
+                      | $(mtexdir)/project.tex
         # If `$(mtexdir)/project.tex' is empty, don't build PDF.
 	@macros=$$(cat $(mtexdir)/project.tex)
 	if [ x"$$macros" != x ]; then
@@ -118,8 +118,7 @@ $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
 # to run everything cleanly from there, it is necessary to add the current
 # directory (top project directory) to the `TEXINPUTS' environment
 # variable.
-paper.pdf: $(mtexdir)/project.tex paper.tex $(texbdir)/paper.bbl \
-	   | $(tikzdir) $(texbdir)
+paper.pdf: $(mtexdir)/project.tex paper.tex $(texbdir)/paper.bbl
 
         # If `$(mtexdir)/project.tex' is empty, don't build the PDF.
 	@macros=$$(cat $(mtexdir)/project.tex)