This is the README for the IBIS ICM V1.1.0 parser.

License & Warranty
------------------

  This program is the IBIS ICM Parser version 1.1.0
  Copyright (C) 2003-2005 Kelly C. Green <kgreen22@mindspring.com>
 
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  Library components of this program are licensed under the LGPL version
  2.1.;  you can redistribute the library and/or modify it under the 
  terms of the Lesser GNU General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  Each source module incorporates a header describing the appropriate
  licence.  In practice, everything but the main() driver program 
  icmchk.c is LGPL.
 
  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  for more details.
 
  You should have received a copy of the GNU General Public License and
  Lesser GNU General Public License along with this program; if not, write 
  to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 
  MA  02111-1307  USA, or visit http://www.gnu.org to view them.
 

See the file 'COPYING' for further details, as well as the files 
gpl-license.txt and lgpl-license.txt.


To unpack files
---------------

(UNIX)
cd to a suitable directory
The kit will unpack into a subdirectory 'icmchk-1.1.0'

then, depending on the archive you want to unpack:

tar -zxf icmchk-1.1.0.tar.gz

-or-

tar -jxf icmchk-1.1.0.tar.bz2

-or-

uncompress icmchk-1.1.0.tar.Z
tar -xf icmchk-1.1.0.tar



(WINDOWS)
Move the file icmchk-1.1.0.zip to a suitable directory
and unzip it with winzip or a similar tool.

NOTE:  The ZIP archive has been thoughtfully processed to convert text 
files from UNIX <newline> to Microsoft <cr><newline> line termination 
sequences.  Otherwise, the files would be rather difficult to work with.
You really DON'T want to use the .zip archive on a unix system.  If you do,
you must use an unzip option to 'convert' the files from cr/lf format
to UNIX lf format.


Building the tool
-----------------

(UNIX)

For UNIX environments, simply invoke the configuration tool, and then
'make'.  If for some reason the configure tool didn't correctly deduce
the environment, you may adjust the content of 'config.h' manually.

cd icmchk-1.1
./configure

You may review and adjust the content of 'config.h' if you wish, but
it should not be necessary to do so.  Then do:

make
make check


If you want to regenerate all files from the m4, yacc and lex source as well, 
you will need GNU flex, bison and m4 to do it.  This release is built using 
GNU FLEX version 2.5.4a, GNU BISON version 1.875c, and GNU m4 version 1.4.1.

m4 is used to simply provide a native include capability in bison source files,
a feature it is sadly lacking.  This is necessary to ensure that all versions 
of the parser's .y sources (one per released ICM specification) use the 
identical core structure definitions, and generate identical .h definitions 
for the version independent flex lexical analyzer which they all share.  
If you don't have m4, you can literally construct the necessary .y files 
from the .m4y sources by editing out the 'yy_include' and pasting in the 
included file.

Earlier versions of these tools may or may not work properly.  Since the 
output files of these tools are included in the source drop, is it not
necessary to reprocess the .m4y, lex, and yacc sources unless you feel 
compelled to make fundamental changes to the parser.

If you muck around with the automake and autoconf source files
(Makefile.am, configure.ac), you will need to run autoconf and/or automake
to regenerate the Makefile.in and configure files.  I used GNU autoconf 
version 2.59, and GNU automake version 1.8.3.  If you're starting
from scratch, the steps basically are to run the tools "aclocal", 
"libtoolize", "automake -a" and finally "configure" in that order.  
Automake is a total and complete pain to set up, but extremely useful.


Useful make targets:

'make'           make icmchk1.
'make check'     will run the regression test suite
'make install'   will install icmck1 into /usr/local/bin
'make dist'      will reconstruct the distribution archives
'make clean'     will clean up make debris
'make distclean' will remove most everything but distribution files



(WINDOWS)
The 'win' subdirectory has been pre-configured with the files
needed to construct the application in a windows environment.

Import the sources (all the files in the 'win/src' directory) 
into a visual C icmchk1 project, and then build icmchk1.exe as a console
based application.  That's pretty much it.

Alternatively, you can install the CYGWIN tools (http://www.cygwin.com)
and build the parser exactly as you would under UNIX.  Unfortunately,
the resulting binary still requires CYGWIN to run, so this isn't a good
option for building a binary to be made available for general download.

There is no difference between the files in ./win/src/ and ./src/ other
than the omission of the files for which windows lacks to tools to process.
The ./win/ directory is simply provided to keep things simple and obvious.

The files in ./win/test/v_1_0 and ./win/test_v_1_1, on the other hand, 
are extracts from the unix test scripts in ./test/ and won't be found as 
such within corresponding unix test directory.

There is no windows batch script to execute the regression test suite,
but all of the essential test files and outputs are located within win/test.
It should not be difficult to run the tests and compare the outputs.

Tests located in the v_1_0 directory are version 1.0 tests and therefore
must be run using the parser's "-f1.0" flag.  Tests in the v_1_1 directory 
are version 1.1 tests and do not require any parser flags.  The parser
fully implements both versions of the ICM specification.


ICM Documentation
-----------------

The IBIS ICM v1.0 / v1.1 specifications have been included in the 'doc'
directory, as well as all the approved "IIRDs" detailing the changes 
between the two.


Running the tool
----------------


icmchk1 <file-name>  


./icmchk1 -h

IBIS ICM Version 1.1.0 parser.
 
USAGE: lt-icmchk1 [-vschp] [-f[<ver>]] [<file name>]
       -v --> (verbose, once)  Report additional informational messages.
       -v --> (verbose, twice) Report debug messages (caution: voluminous).
       -s --> (sort)           Sort diagnostic messages by line number.
       -c --> (copyright)      Display program copyright and exit.
       -h --> (help)           Display this message and exit.
       -p --> (pipe)           Read stdin pipeline instead of file.
       -f --> (force version)  If -f<ver>, parse as version '<ver>'.
                               If -f, honor the file's [ICM Ver] keyword.
                               If omitted, always parse as version '1.1'.
       <file name>             The input IBIS ICM Model file.
 

There is a section 1 man page for icmchk1 as well.


Report Bugs Please
------------------

Have fun, but beware: there are surely bugs lurking.  If you find one,
please email me your reproducing test file, or even better, dig in and send 
me a patch too.

Kelly Green <kgreen22@mindspring.com>
