"README"
	$Id: README,v 1.31 2011/02/14 08:03:16 fang Exp $

Welcome to HACKT (Hierarchical Asynchronous Circuit Kompiler Toolkit),
a compiler suite for asynchronous system design!  

Fang (fangism)

===============================================================================
Quick start:

The majority of this section is described in more detail in INSTALL.  
To start the build run "./configure" with your elected options.  
Assuming configure is happy with the system, you're ready to run "make".  
(You should, however, read the next section on requirements and portability.)

After the build is finished, I strongly recommend running "make check"
from the root directory to run the test suite on the built executables.  

===============================================================================
Requirements and Portability:

To maximize compatibility, the HACKT project is build with the strictest
compiler settings: strictly conforming to the ISO C++ 1998 standard (c++98), 
in particular, GNU extensions are rejected by the -pedantic-error flag.  
In the future, we may decided to upgrade the standard to the C++0x
standard, which is currently in review.  (Update: we have successfully built 
against g++-4.3 -std=c++0x, which is experimental.)

The following compilers are known to DIE a horrible death and should NOT
be used to compile this project:

	gcc-2.95.x or earlier
	gcc-3.2.x or earlier

The following compilers are supported and recommended:
	gcc-3.3.x, -3.4.x, -4.0.x, -4.1.x, -4.2.x, -4.3.x *
	gcc-4.6.x

(*) gcc-4.3 and above need CXXFLAGS: -Wno-conversion

The following compilers have a bug that prevent compilation:
	gcc-4.4.4+, gcc-4.5.x
	http://gcc.gnu.org/bugzilla/show_bug.cgi?id=46170

The following platforms and compilers are actively supported by this project:
	Mac OS X 10.3+, gcc-3.3+ (either Apple* or FSF)
	FreeBSD 4.3+, gcc-3.4+
	SuSE (or any) linux, gcc-3.3+

* Apple's gcc-4.0 release with OS X 10.4 (build 4061) is buggy and missing
6 months of bug fixes from FSF.  You'll need at least the XCode 2.1 upgrade 
for a working compiler (build 5026).  

These are the platforms to which the developer has access and can maintain
build success and consistency.  
Currently, there are no other known platforms which fail to build and
run the project, but that means they have yet to be discovered.  

AWK.  Any posix conforming version of awk should suffice.  
Known to work: awk (traditional), nawk, gawk.
Trouble with: mawk (some basic syntax rejected!?)
When testing, it is recommended to set the POSIXLY_CORRECT environment variable.

To build the source, one need at least bison-1.35 (that's not asking too much),
or some POSIX-compliant implementation of yacc.  
For example, bison-1.28 is known to fail, and is not actively supported(*1).  
Some versions of byaccj (in C mode) have been known to work.  
The YACC variable is used to set the parser generator and may be 
passed to the configure script.  
lex or flex is required to generate the scanner, and may be set using the
LEX configure variable.  

(*1)	The output file produced by bison-1.28 does not conform to 
	standard, it produces name.yy.tab.c instead of y.tab.c, 
	same with the header file.  The yacc rules from automake/autoconf
	do not account for this deviation.  

Supported versions of bison: 1.35, 1.875, 2.0, 2.1, 2.3
Supported versions of flex: 2.5.4, 2.5.31, 2.5.33, 2.5.35
	2.5.31's skeleton may cause some warnings which may require -Wno-error
	2.5.33+ work after portability fix after version:
		git Tag: HACKT-00-01-04-main-00-84-49
Supported revisions of Berkeley yacc skeletons: 1.14, 1.28, 1.37
	(can be seen from generated y.tab.cc)

Unsupported versions of bison:
	1.28 -- see comment *1
Known flex issues:
	2.5.33 -- fails -Wundef (__STDC_VERSION__) and -Werror (signed comp.)
		workaround: pass -Wno-error to CXXFLAGS at configure-time
		but WORST of all, after workarounds, lexing crashes horribly.
Unsupported versions of yacc (skeleton): 1.9 (1993)

Other required tools:
dot (part of the graphviz package)
	graph figure generator, needed for documentation building.
fig2dev (usually comes with a 'transfig' package)
	exports xfig figures, only needed for documentation building.
texinfo programs: makeinfo, texi2dvi, texi2pdf, texi2html
	needed for building documentation.  
latex,pdflatex (part of tetex package)
	needed for building documentation.
guile-1.6+
	Guile is a scheme environment for extensible languages.  
	known to work API: 1.8 (preferred)
	known to work: 1.8.0+
	known to work: 1.6.7+
	known to fail: 1.6.4
		(some bug with force evaluation, affects stream-for-each (many))

The following guile (scheme) modules are used and required by HACKT:
	ice-9 streams
They are most likely installed in /prefix/share/guile/.../ice-9
as they are architecture-independent files.  

-------------------------------------------------------------------------------
Other optional dependencies:

Supported versions of readline: 4.1, 4.3, 5.0, 5.2
editline also tested

===============================================================================
KNOWN ISSUES

2005-12-07:
	The flags used in conftest's during configuration are not
	aware of the AM_CXXFLAGS in src/Makefile.am.
	Some of the results (such as testing for long long) may
	be inconsistent.  
	Workaround: explicitly pass the relevant flags to CXXFLAGS
	at configure time to guarantee consistency.
	TODO: find way to coordinate use and selection of flags
	between autoconf and automake.  
	Status: Fixed with autoconf flag tests.

2005-12-07:
	An early release of gcc-3.3 doesn't correctly heed the
	-Wno-unused-parameter flag.  
	(Tested on some sun-sparc-solaris2.9 machine.)
	This causes -Werror to error out unfortunately.  
	If this is the problem, then you need to add -Wno-error
	to CXXFLAGS at configure-time.  
	Also suspecting (not confirmed) a wrong code-generation bug
		in gcc-3.3 (sun-sparc-solaris2.9) 
		when optimizations are *OFF*.  

2005-07-26:
It has been reported that some implementations of libc's getopt don't work
as expected, especially if your name is Chris LaFrieda and you run linux.  
Here's the reason why: from the man (3) page of linux's getopt:
	By  default,  getopt() permutes the contents of argv as it
	scans, so that eventually all the non-options are  at  the
	end.   Two other modes are also implemented.  If the first
	character of optstring is '+' or the environment  variable
	POSIXLY_CORRECT  is  set,  then option processing stops as
	soon as a non-option  argument  is  encountered.   If  the
	first  character of optstring is '-', then each non-option
	argv-element is handled as if it were the argument  of  an
	option  with  character code 1.  (This is used by programs
	that were written to expect options  and  other  arguments
	in  any order  and that  care about  the ordering  of  the
	two.)  The special argument '--' forces an end of  option-
	scanning regardless of the scanning mode.
The problem is fixed by passing '+' to enforce POSIX behavior.  

===============================================================================