"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.

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