source: README@ bd72c284

cfa-cc: Cforall to C Trans-compiler
======================================

This is a PRE-RELEASE version of cfa-cc.  It exists solely for the purpose of
private experimentation and scholarly research.  The authors disclaim all
responsibility for the consequences of any malfunction of the software,
including the malfunction of any programs compiled using the software.


What is Cforall?
----------------
Cforall is a language design extending ISO C. The purpose of the project is to
engineer modern language features into C in an evolutionary rather than
revolutionary way. Java is an example of the revolutionary approach of
modernizing C/C++, resulting in a new language rather than an extension of its
descendents. C++, Fortran 95 and Cobol 9X are examples of the evolutionary
approach where modern language features are added and problems fixed within the
framework of an existing language.

The goal of this project is to produce a largely backwards compatible version
of C containing many modern language features and fixing some of the well known
C problems. Without continued development of the language, C will be unable to
cope with the needs of modern programming problems and programmers; as a
result, it will fade into disuse.  Considering the large body of existing C
code and programmers, there is a significant impetus to ensure C is transformed
into a modern programming language.


What is cfa-cc?
---------------
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.

cfa-cc is currently written in C++, but will be eventually rewritten in Cforall.


How to download and build cfa-cc?
----------------------------------------
Download cfa-cc using

  $ git clone https://github.com/cforall/cforall.git

Read the ./INSTALL file for build instructions.


How to use cfa-cc?
-------------------
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

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.


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.

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:

  extern "C" {
  #include <curses.h>
  #include <getopt.h>
  }

The extern "C" turns off name mangling for functions and objects declared
within the block. All C standard headers are pre-wrapped, so most wrapping is
unnecessary.


What's wrong with cfa-cc?
-------------------------

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.

Also, the Cforall features web-page https://cforall.uwaterloo.ca/features lists
small syntactic and semantic differences with standard C.


Who is responsible for cfa-cc?
------------------------------
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.

Check the Cforall web site https://cforall.uwaterloo.ca for news and updates.