Index: README =================================================================== --- README (revision da60c63108d642781694a3bf904aa4f318d30d27) +++ README (revision 4200b7ebbc9c493ce902302e4f0925eae3da7c06) @@ -1,3 +1,3 @@ -cfa-cc: The Cforall->C Compiler System +cfa-cc: Cforall to C Trans-compiler ====================================== @@ -6,4 +6,5 @@ responsibility for the consequences of any malfunction of the software, including the malfunction of any programs compiled using the software. + What is Cforall? @@ -25,93 +26,77 @@ 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 - #include - } + extern "C" { + #include + #include + } 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.