Changeset 4200b7e

Timestamp:

Jun 27, 2021, 9:53:50 PM (4 years ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

ADT, ast-experimental, enum, forall-pointer-decay, jacob/cs343-translation, master, new-ast-unique-expr, pthread-emulation, qualifiedEnum

Children:

2ac218d

Parents:

2e19e91

Message:

update README and INSTALL files

Files:

• INSTALL (modified) (2 diffs)
• README (modified) (3 diffs)

INSTALL ¶

@@ -1 @@
-cfa-cc: The Cforall->C Compiler System
+cfa-cc: Cforall to C Trans-compiler
 ======================================
 
 Cforall is built using GNU Make and the GNU Autoconf system.  It also requires
-g++ version >= 4.6, bison and flex.  On systems where GNU Make is the default
+g++ version >= 6, bison and flex.  On systems where GNU Make is the default
 make, the system is built by entering the commands:
 
-For devs using the root git:
+For developers using the root git:
 
-  ./autogen.sh
-        ./configure
-        make
-        make install
+  $ ./autogen.sh
+  $ ./configure
+  $ make -j 8 install
 
 For users using the distributed tarball:
 
-        ./configure
-        make
-        make install
+  $ ./configure
+  $ make -j 8 install
+
+where 8 is the number of CPUs on your computer.
+
 
 Options for 'configure'
------------------------
+======================================
 The script 'configure' accepts many command line arguments.  Run './configure
 --help' to see a list of all of them.  This document attempts to summarize the
@@ -31 +32 @@
   it is important not to put quotes around the directory path; Cforall may
   appear to build, but the installed version may not work properly.
+
+
+Build Test
+======================================
+
+  $ cd ./test
+  $ make -j 8 all-tests
+
+The tests take about 2-5 minutes and can be stopped at any time.

README ¶

@@ -1 @@
-cfa-cc: The Cforall->C Compiler System
+cfa-cc: Cforall to C Trans-compiler
 ======================================
 
@@ -6 +6 @@
 responsibility for the consequences of any malfunction of the software,
 including the malfunction of any programs compiled using the software.
+
 
 What is Cforall?
@@ -25 +26 @@
 into a modern programming language.
 
+
 What is cfa-cc?
 ---------------
-cfa-cc is a collection of programs centred around a translator that takes
-Cforall code as input and outputs corresponding C code.  This is complemented
-by a compiler driver in the style of "gcc", which handles preprocessing,
-compiling, assembling, and linking and invokes the translator at appropriate
-moments.
+cfa-cc is a collection of programs centred around a translator (trans-compiler)
+that takes Cforall code as input and outputs augmented C code that implements
+new features.  The translator is complemented by a compiler driver in the style
+of "gcc", which handles preprocessing (including cfa-cc after cpp), compiling,
+assembling, and linking.
 
-What is required in order to use cfa-cc?
+cfa-cc is currently written in C++, but eventually be rewritten in Cforall.
+
+
+How to download and build cfa-cc?
 ----------------------------------------
-Building cfa-cc requires GNU Make and gcc/g++ 4.  cfa-cc is written in C++.
+Download cfa-cc using
 
-The compiler driver uses an installed version of gcc to handle all aspects of
-the compilation process except for the Cforall->C translation.  Currently, only
-gcc 4.x is supported.
+  $ git clone https://github.com/cforall/cforall.git
 
-How is cfa-cc used?
+Read the ./INSTALL file for build instructions.
+
+
+How to use cfa-cc?
 -------------------
-The compiler driver "cfa" accepts all of the arguments of gcc, and is used in
+The compiler driver "cfa" accepts all of the arguments for gcc, and is used in
 the same way.  For example:
 
-        cfa -c test.c
-        cfa test.o
+  cfa -c test.c
+  cfa test.o
 
-Cforall source files must end with '.c' in order to be compiled by the compiler
-driver.  In addition, the flag "-CFA" causes cfa to invoke the preprocessor and
-translator and send the translator output to standard output.
+Cforall source files may end with '.c' or '.cfa' in order to be compiled by the
+compiler driver.  In addition, the flag "-CFA" causes cfa to invoke the C
+preprocessor and Cforall translator and write the translator output to standard
+output.
 
-It is possible to invoke the translator directly.  The translator is installed
-by default as /usr/local/lib/cfa-cpp.  A typical invocation is:
 
-        /usr/local/lib/cfa-cpp -cp infile outfile
+How to use C code with cfa-cc?
+-----------------------------------
+cfa-cc should be able to compile and link most ANSI C programs with associated
+C standard libraries.
 
-If outfile is omitted, output goes to standard output; if infile is also
-omitted, input comes from standard input.  Options to the translator other than
-"-cp" will not produce valid C code and are only useful for debugging the
-translator.
+Like C++, Cforall supports overloading, resulting in duplicate names that are
+disambiguated using name mangling in the translated C code.  To prevent
+mangling of C names, it is necessary to wrap C declarations in an extern "C"
+block, as for C++.  For example:
 
-How can C code be used with cfa-cc?
------------------------------------
-cfa-cc should be able to compile most ANSI C programs.  It is also possible to
-link against C libraries in most cases.  Since Cforall supports overloading,
-however, names used in Cforall code are mangled in the output C code.  This
-caused linker failures when the names refer to functions and objects in code
-compiled with a standard C compiler.  For this reason, it is necessary to
-enclose the declarations of these functions and objects in extern "C" {}
-blocks.  For example:
-
-        extern "C" {
-        #include <stdio.h>
-        #include <stdlib.h>
-        }
+  extern "C" {
+  #include <curses.h>
+  #include <getopt.h>
+  }
 
 The extern "C" turns off name mangling for functions and objects declared
-within the block.  As a result, it is not possible to overload their names.
+within the block. All C standard headers are pre-wrapped, so most wrapping is
+unnecessary.
+
 
 What's wrong with cfa-cc?
 -------------------------
 
-The authors consider this software to be in an unstable state.  It is quite
-likely that there are many reasonable programs that will fail to compile.  We
-encourage users to report their experiences to cforall@plg.uwaterloo.ca, but we
-make no promises regarding support.
+The authors consider cfa-cc to be in a semi-stable state.  It is possible for
+reasonable Cforall programs to fail compilation.  A list of bugs and fixes is
+available here: https://cforall.uwaterloo.ca/trac.  We encourage users to
+report their experiences to cforall@plg.uwaterloo.ca, but we can make no
+promises regarding support.
 
-We have fixed most of the problems that we are aware of.  There are some
-exceptions:
+Also, the Cforall features web-page https://cforall.uwaterloo.ca/features lists
+small syntactic and semantic differences with standard C.
 
-- initializers are poorly implemented; in particular, file-scope initializers
-  may result in the generation of invalid C code
-
-- the ISO C99 designated initialization syntax '[n] = m' or '.n = m' is not
-  supported; use a colon in place of the equal sign
-
-- some legitimate programs will produce warnings from the C compiler; these are
-  harmless (in particular, the creation of libcfa.a in the build process should
-  cause four warnings from gcc)
-
-- abstract types introduced using the keyword 'type' are not implemented
-  (although 'type' can be used to introduce type parameters)
-
-- the implicit coercion of structure types to the type of their first member is
-  not implemented
 
 Who is responsible for cfa-cc?
 ------------------------------
-cfa-cc was written by Peter Buhr, Richard Bilson, and Rodolfo Esteves.
-Questions and comments can be sent to cforall@plg.uwaterloo.ca.
+Cforall was designed and implemented by Andrew Beach, Richard Bilson, Michael
+Brooks, Peter A. Buhr, Thierry Delisle Glen Ditchfield, Rodolfo G. Esteves,
+Aaron Moss, Colby Parsons, Rob Schluntz, Fangren Yu, Mubeen Zulfiqar, and others.
 
-The Cforall project maintains a web page:
-
-        https://cforall.uwaterloo.ca
+Check the Cforall web site https://cforall.uwaterloo.ca for news and updates.