CONTENTS AND COPYRIGHT

This archive contains the entire source tree for Jim Kent's suite 
of biological analysis and web display programs.  All files are
copyrighted, but license is hereby granted for personal,
academic, and non-profit use.  Commercial users should contact
jim_kent@pacbell.net.

Most users will only be interested in the inc and lib
directories, which contain the interfaces and implementations
to the library routines,  and in a few specific applications.
The applications are scattered in other directories.
Many of them are web based.  A few of them expect
the MySQL database to be around.

GENERAL INSTALL INSTRUCTIONS

1. Create a directory named "jksrc" and go to it.
2. Unzip jksrcXXX.zip, where XXX is the latest version,
   currently 417.
3. Check that the environment variable MACHTYPE
   exists on your system.  It should on Unix.  
   (And making this on non-Unix systems is beyond
   the scope of this README).  For a Linux 
   system MACHTYPE will probably be 'i386', for
   and Alpha it will be 'alpha', for a Sun
   probably 'sparc'.  If necessary set up
   this environment variable.
4. Make the directory ~/bin/$MACHTYPE which is
   where the (non-web) executables will go.
   Add this directory to your path.
5. Go to the jksrc/lib directory.  If it doesn't
   already exist do a mkdir $MACHTYPE.
6. Type make.  On Alphas there will be 
   some warning messages about "crudeAli.c"
   otherwise it should compile cleanly.
   It's using gcc.
7. Go to the application you want to make and type 
   make.  (If you're not sure, as a simple test
   go to jksrc/utils/fixcr and type make,
   then 'rehash' if necessary so your shell
   can find the fixcr program in ~/bin/$(MACHTYPE).
   The fixcr program changes Microsoft style
   <CR><LF> line terminations to Unix style
   <LF> terminations.  Look at the "gotCr.c"
   file in the fixCr directory, and then
   do a "fixcr gotCr.c" on it.

INSTALL INSTRUCTIONS FOR BLAT

1. Follow the general install instructions above.
2. If you're on a non-Linux system do a:
     setenv SOCKETLIB -lxnet
3. Execute make in each of the following directories:
     jksrc/gfServer
     jksrc/gfClient
     jksrc/blat
     jksrc/utils/faToNib

INSTALL INSTRUCTIONS FOR CODE USING THE BROWSER DATABASE
(and other code in the jkSrc/hg subdirectory)

1. Follow the general install instructions above.
2. Make the environment variable MYSQLINC point to
   where MySQL's include files are.  (On my
   system they are at /usr/include/mysql.)
   While you're at it set the MYSQLLIBS
   variable to point to something like
   /usr/lib/mysql/libmysqlclient.a
3. Execute make in jksrc/hg/lib
4. Execute make in the directory containing the
   application you wish to build.


CODE CONVENTIONS

The code follows a few conventions that are a bit
unusual for C.  Opening and closing braces are on
a line by themselves and are indented at the same
level as the block they enclose:
    if (someTest)
	{
	doSomething();
	doSomethingElse();
	}
Almost any structure with more than three or four
elements includes a "next" pointer as its first
member, so that it can be part of a singly-linked
list.  There's a whole set of routines (see
common.c and common.h) which work on singly-linked
lists where the next field comes first. Their
names all start with "sl."

Another convention is that errors are reported
at a fairly low level, and the programs simply
print an error message and abort.  If you
need to catch errors underneath you see the
file errAbort.h and install an "abort handler".

Memory is generally allocated through "needMem"
(which aborts on failure to allocate) and the
macros "AllocVar" and "AllocArray".  This 
memory is initially set to zero, and the programs
very much depend on this fact.

MAJOR MODULES

Here is a list of some of the more useful modules in
the library.  Unless noted the module is a .h file
in the inc directory and a .c file in the lib
directory.

o - common  - String handling, singly-linked list handling. 
    Other basic stuff every other module uses.
o - hash - Simple but effective hash table routines.
o - linefile - Line oriented file input, on some systems
    much faster than fgets().
o - cheapcgi - Parses out cgi variables for scripts called
    from web pages.
o - htmshell - Helps generate HTML output for scripts that
    are called from web pages or just want to make web
    pages.
o - memgfx - Creates a 256 color image in memory which
    can be drawn on, then saved as a .GIF file which
    can be encorperated into a web page.
o - fuzzyFind - Align two pieces of DNA that are 
    relatively similar (~80% base identity or better).
    Works best when one sequence is less than 30,000
    bases and the other less than 100,000 bases.
o - patSpace and supStitch - Align longer pieces of
    DNA.
o - xensmall - Align two small pieces of dissimilar DNA.
    (7 State Pairwise HMM)
o - xenbig - Align two large pieces of dissimilar DNA.
o - jksql - Interface to mySQL that frees resources on
    exit and error conditions.
o - dnautils and dnaseq - Simple utilities on DNA.
o - fa - Read/write fasta format files.
o - serv* and port* - Adapt the code to the peculiarities of
    various web servers.