[gnuastro-commits] master 53e6266: Book: fix to known issue in CFITSIO installation explained

[Mohammad Akhlaghi]

branch: master
commit 53e6266d54f06f19e86b918ccd5b915a53a32b48
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: fix to known issue in CFITSIO installation explained
    
    On some operating systems, the 'testprog' program of CFITSIO will give a
    linking error with the just-installed library, and crash. To fix it, it is
    necessary to add the running directory to 'LD_LIBRARY_PATH'.
    
    With this commit, an explanation has been added after the series of
    commands to install CFITSIO, describing the problem and how to fix it.
    
    This issue, and its fix, was reported by Aaron Watkins.
---
 doc/announce-acknowledge.txt |  1 +
 doc/gnuastro.texi            | 17 ++++++++++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index b89910e..c95bdd0 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -1,6 +1,7 @@
 Alphabetically ordered list to acknowledge in the next release.
 
 Zahra Sharbaf
+Aaron Watkins
 
 
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 46fff2b..04de232 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -5248,13 +5248,28 @@ $ cd cfitsio-X.XX                   # Replace X.XX with 
version
 $ ./configure --prefix=/usr/local --enable-sse2 --enable-reentrant
 $ make
 $ make utils
-$ ./testprog > testprog.lis
+$ ./testprog > testprog.lis         # See below if this has an errotr
 $ diff testprog.lis testprog.out    # Should have no output
 $ cmp testprog.fit testprog.std     # Should have no output
 $ rm cookbook fitscopy imcopy smem speed testprog
 $ sudo make install
 @end example
 
+In the @code{./testprog > testprog.lis} step, you may confront an error, 
complaining that it can't find @file{libcfitsio.so.AAA} (where @code{AAA} is an 
integer).
+This is the library that you just built and haven't yet installed.
+But unfrotunately some versions of CFISIO don't account for this on some OSs.
+To fix the problem, you need to tell your OS to also look into current CFITSIO 
build directory with the first command below, afterwards, the problematic 
command (second below) should run properly.
+
+@example
+$ export LD_LIBRARY_PATH="$(pwd):$LD_LIBRARY_PATH"
+$ ./testprog > testprog.lis
+@end example
+
+Recall that the modification above is ONLY NECESSARY FOR THIS STEP.
+@emph{Don't} put the @code{LD_LIBRARY_PATH} modification command in a 
permanent place (like your bash startup file).
+After installing CFITSIO, close your terminal and continue working on a new 
terminal (so @code{LD_LIBRARY_PATH} has its default value).
+For more on @code{LD_LIBRARY_PATH}, see @ref{Installation directory}.
+