commit 3c43ae86b3dedae4261574e86c34125f8e52273d
from: Pompolic <pompolic@special-circumstanc.es>
date: Wed Apr 15 17:25:36 2020 UTC

Troubleshooting, interpreting test results

commit - 2759867fa808051c773991e8b3254abdf710230a
commit + 3c43ae86b3dedae4261574e86c34125f8e52273d
blob - 26bfc1b870492b8dfafdf25e6a93d072d8e31060
blob + c2914cbc3f92d1c94c4c71e668ae62dc48192f56
--- README
+++ README
@@ -14,24 +14,45 @@ Beginnings of a PDF parser in Hammer
 
  - Notes for 2020-04-27 release:
 
-	  The release branch has been tested to build with the 2020-04-27_RELEASE` branch located at https://gitlab.special-circumstanc.es/pesco/hammer/tree/2020-04-27_RELEASE
+	The release branch has been tested to build with the 2020-04-27_RELEASE` branch located at https://gitlab.special-circumstanc.es/pesco/hammer/tree/2020-04-27_RELEASE
 
- - Build/Usage:
+ - Build:
 
        $ pushd ../hammer; scons; popd  		# build Hammer
        $ make pdf
-       $ ./pdf test.pdf
 
+ - Usage:
+
+	   $ export LD_LIBRARY_PATH=./lib		# see Troubleshooting section below to see if this is needed
+	   $ ldd ./pdf | grep libhammer			# verify that libhammer.so was found
+       $ ./pdf <filename>
+
        # place some test files in the t/ directory...
        $ make test
 
+ - Troubleshooting:
+
+	   libhammer.so not found:
+
+	       If Hammer is not installed as a system library, ld may fail to locate libhammer.so. The quick fix for this is altering LD_LIBRARY_PATH before running pdf:
+
+		   $ export LD_LIBRARY_PATH=./lib
+		   $ make test
+
+		   The second solution is executing "scons install" when building Hammer, which will install it in ld's usual search path:
+
+		   $ pushd ../hammer; scons install; popd
+		   # ... Update ldconfig cache if needed
+		   $ make pdf
+		   $ make test
+
  - Evaluating test results:
  
    For every file in the t/ directory, the pdf parser is executed. On successful parse, a message of the following form is displayed:
 
    OK: t/<filename>
 
-   On a failed test run, parse error messages are displayed.
+   In case of a non-fatal parse error, error messages may be displayed, but presence of the "OK" indicates a successful execution. On a failed test run, only parse error messages are displayed.
 
  - Copyright: