pcompress/INSTALL

Copyright (c) 2012 Moinak Ghosh

Prerequisites
=============
64-bit System.
GCC 4.4 (with mpfr, ppl and cloog support packages for loop
	 vectorization).
libz (zlib) and development packages.
Libbz2 and development packages.
Libbsc source tree if BSC support is desired.
	 See below:
	 "Steps for building with libbsc support".
OpenSSL version 0.9.8 or greater.

Basic Installation
==================
The simplest process to build and install this utility is:

./config
make
make install

The current makefiles and config scripts assume Gcc compiler is
in the PATH. Please update PATH before running config if that is
not the case.

In order to remove all binaries:
make clean

Remove all binaries and the generated Makefile:
make distclean

Strictly speaking the 'make install' step is not required to
run the utility as it is a single stand alone program for now.

The config script controls various compile time parameters and
generates the actual Makefile. You can get a short description
of all the options by running:

./config --help

NOTE: Basic Installation does not enable support for Libbsc, a
      new block-sorting compressor (similar to but better than
      Bzip2). See below for details.

Testing
=======

After running make as given above you can run:
make test

This will generate some data files from /usr/bin /usr/share and
/usr/include directories and then run a whole lot of tests. These
execute pcompress with a wide variety of combinations of options.
For every test both compression and decompression are performed
and after every decompression the decompressed file is verified
byte for byte with the original using the diff utility.

It takes a long time to run all the tests. The complete test log
is stored in the file test.log. Test failures are indicated by the
error message starting with the word "FATAL". All other error
messages visible in the log are a result of negative testing where
the utility is expected to exit with an error.

The files test/t1.tst, test/t2.tst and so on are individual test
suites. It is possible to run a single test suite. For example to
run test/t4.tst the following command can be used:
make test TESTSUITE=4

Custom Installation
===================
The options to the config script are detailed below. Note that this
is not the usual GNU Autoconf script.

./config [<options>]

<options> can be one of the following:

--prefix=<val>		The installation prefix. 
			This is set to /usr by default. However alternate
			prefix needs to eb used during packaging.

--enable-debug		Enable debug mode compilation.
			This reduces the compiler optimization level to
			basic and taks out all the loop optimization flags.
			This is primarily to aid debugging.

--disable-allocator	Disable use of internal memory allocator mechanism.
			The internal allocator can be totally disabled by
			setting this build time flag. It is also possible
			to dynamically disable the allocator by setting the
			following env variable:
			ALLOCATOR_BYPASS=1

--enable-debug-stats	Enable printing of some verbose debug info.
			This at present shows some info related to Dedupe
			efficiency.

--with-libbsc=<path_to_libbsc_source>
			Enable support for libbsc (See: libbsc.com). Full
			path to the libbsc source tree must be provided. It
			links the library statically.

--with-zlib=<path to zlib installation tree> (Default: System)
                        Enable building against an alternate Zlib installation.

--with-bzlib=<path to Bzip2 library installation tree> (Default: System)
                        Enable building against an alternate Bzip2 and library
                        installation.

--no-sse-detect         Do not try to detect the CPU's SSE capability. This
                        mode will simply use SSE2 as the fallback default.
                        Using SSE4 and later improves performance significantly.

--use-key256            Use 256-bit encryption keys. Default key length is
                        128-bit.

--help			Display the help message.

Steps for building with libbsc support
======================================
1) Download libbsc source from:  http://libbsc.com/ . Click on the
   "Download TAR Ball" button. Downloading the 3.1.0 release from the
   Github project download page will Not work.

2) Extract the gzippped tarball. It will create a directory for example:
   IlyaGrebnov-libbsc-0b12f29

3) Now cd into the pcompress directory and execute the config script
   with the full path to the libbsc source directory. For example:

   ./config --with-libbsc=/full/path/to/IlyaGrebnov-libbsc-0b12f29

4) Now run make in the pcompress directory. This will also run make in
   the libbsc source directory to build it.

5) Additional compilation flags can be passed to make like this:
   make EXTRA_CPPFLAGS=<...> EXTRA_LDFLAGS=<...>