			IO_LIB VERSION 1.14.4
			=====================

Io_lib is a library of file reading and writing code to provide a general
purpose trace file (and Experiment File) reading interface. The programmer
simply calls the (eg) read_reading to create a "Read" C structure with the
data loaded into memory. It has been compiled and tested on a variety
of unix systems, MacOS X and MS Windows.

The directories below here contain the io_lib code. These support the
following file formats:

	SCF trace files
	ABI trace files
	ALF trace files
	ZTR trace files
	SFF trace archives
	SRF trace archives
	Experiment files
	Plain text files
	SAM/BAM sequence files
	CRAM sequence files

These link together to form a single "libstaden-read" library supporting
all the file formats via a single read_reading (or fread_reading or
mfread_reading) function call and analogous write_reading functions
too. See the file include/Read.h for the generic 'Read' structure.


See the CHANGES or ChangeLog file for the full list of chanegs.  A
quick summary follows.

What's new in 1.14.5
====================

CRAM now has a maximum number of bases per slice limit, specified in
scramble with -b.  The defaults mean that the code is now faster and
less memory hungry on long reads (PacBio, ONT) but has no change with
Illumina short-read data.  Long read data file sizes may be impacted
slightly.

Various CRAM bug fixes including multi-slice containers, the
biobambam interfaces and MacOS X support.

What's new in 1.14.4
====================

Bug fix release: fixed a CRAM encoding bug with compression level 6
and above where the resulting CRAM file could not be decoded.  This
has been in existance since 1.13.8 (and possibly 1.13.6 under rarer
conditions).


What's new in 1.14.3
====================

CRAM: disabled the experimental slice checksum headers (SD and BD
*slice* tags) as their behaviour is still undefined and not in the
CRAM specification.  These were left in in error.

Also fixed a bug with decoding lzma compression level 9.


What's new in 1.14.2
====================

Minor CRAM bug fixes and a speed improvement (bug fix to 1.14.1).


What's new in 1.14.1
====================

More CRAM tweaks.  The primary purpose for this release is slightly
better compression ratios on some (although not all) CRAM files due to
splitting auxiliary tags into their own per-tag data blocks.


What's new in 1.14.0
====================

The primary change with this release is the default CRAM version is
now version 3.0.  This has been extensively cross-validated with the
Cramtools-3.0.jar implementation.

In addition to this many bugs have been fixed and the code has been
"hardened" by both visual inspection, automated fuzzing and fixing all
the compiler warnings.


Older comments
==============

1.13.x saw the arrival of CRAM (version 2) format.  1.14.0
introduced CRAM version 3. 

In 1.12.x saw various improvements to building and linking,
specifically on Fedora and MacOS X plus the use of libtool to create
dynamic libraries.  The library name is now libstaden-read.so too, as
this was already renamed within Debian.

We removed illumina2srf and srf2illumina in this release too (they
have their own package on SourceForge now).

In 1.11.x the SRF support was added. The SRF v1.3 format specification can
be found here:

http://www.bcgsc.ca/pipermail/ssrformat/attachments/20071209/b0f865a0/ShortSequenceFormatDec9th_v_1_3-0001.doc

The ZTR specification changes involve adding some new compression
types (the general purpose XRLE2 plus some more solexa specific TSHIT
and QSHIFT methods), a region chunk (REGN) to indicate the location of
paired-end data stored in a single trace, improved meta-data support
for SMP4/SAMP chunks including specifying the baseline (OFFS meta-data
tag) and various minor tweaks. There's still a few questions in the
ZTR format itself (pending feedback), but what is implemented
currently is also what has been described in the docs/ZTR_format
file.

Finally the directory layout has been greatly simplified with the
merging of all the format directories into a single "io_lib"
directory and the programs utilising it remaining in the "progs"
subdirectory.


Building
========

Linux
-----

We use the GNU autoconf build mechanism.

To build:

1. ./configure

"./configure --help" will give a list of the options for GNU autoconf. For
modifying the compiler options or flags you may wish to redefine the CC or
CFLAGS variable.

Eg (in sh or bash):
   CC=cc CFLAGS=-g ./configure

2. make (or gmake)

This will build the sources.

CFLAGS may also be changed a build time using (eg):
    make 'CFLAGS=-g ...'

3. make install

The default installation location is /usr/local/bin and /usr/local/lib. These
can be changed with the --prefix option to "configure".

Windows
-------

Under Microsoft Windows we recommend the use of MSYS and MINGW as a
build environment.

These contain enough tools to build using the configure script as per
Linux. Visit http://sourceforge.net/projects/mingw/files/ and
download/install Automated MinGW Installer (eg MinGW-5.1.4.exe), MSYS
Base System (eg MSYS-1.0.11.exe) and MSYS Supplementary Tools (eg
msysDTK-1.0.1.exe).


MacOS X
-------

The configure script should work by default, but if you are attempting
to build FAT binaries to work on both i386 and ppc targets you'll need
to disable dependency tracking. Ie:

    CFLAGS="-arch i386 -arch ppc" LDFLAGS="-arch i386 -arch ppc" \
      ../configure --disable-dependency-tracking
