README

Beginnings of a PDF parser in Hammer
====================================

 - Currently needs a custom Hammer branch. You'll need to build against this:

   https://gitlab.special-circumstanc.es/pesco/hammer/tree/pdf

   For detailed build instructions, see README.md in that repository.

 - Help the default Makefile find Hammer

       $ ln -s ../hammer/src hammer         # needed for building pdf, include files
       $ ln -s ../hammer/build/opt/src lib  # needed for running pdf, to locate libhammer.so

 - 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

 - Build:

       $ pushd ../hammer; scons; popd       # build Hammer
       $ make 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>

   In case of a non-fatal parse error, error messages may be displayed, but presence of the "OK" indicates pdf exited successfully. On a failed test run, only parse error messages are displayed.

 - Copyright:

  - pesco 2019,2020
  - pompolic 2020
  - Paul Vines 2020
  - David Bryant (modified lzw-ab code)

  See LICENSE and lzw-ab-license.txt for full copyright and licensing notice.