Index: README =================================================================== --- README (revision 5faa3a5390d1a4845f728030a7e3e373db2eaaac) +++ README (revision 51b734528489f81a5af985bfee9aa3b6625b9774) @@ -1,112 +1,131 @@ -cfa-cc: Cforall to C Trans-compiler +cfa-cc: The Cforall->C Compiler System ====================================== -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. - +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. +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. - +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 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 currently written in C++, but will be eventually rewritten in Cforall. +What is required in order to use cfa-cc? +---------------------------------------- +Building cfa-cc requires GNU Make and gcc/g++ 3. cfa-cc is written in +C++. +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 3.2 is supported. -How to download and build cfa-cc? ----------------------------------------- -Download cfa-cc using +How is cfa-cc used? +------------------- +The compiler driver "cfa" accepts all of the arguments of gcc, and is +used in the same way. For example: - $ git clone https://github.com/cforall/cforall.git + cfa -c test.c + cfa test.o -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 +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. +In cases where the compiler driver is not useful (i.e., where gcc 3.2 +is not available), it is still possible to invoke the translator +directly. The translator is installed by default as +/usr/local/lib/cfa-cpp. A typical invocation is: -How to use C code with cfa-cc? + /usr/local/lib/cfa-cpp -cp infile outfile + +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. + +How can C code be used with cfa-cc? ----------------------------------- -cfa-cc should be able to compile and link most ANSI C programs with associated -C standard libraries. +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 will cause 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: -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 - #include - } + extern "C" { + #include + #include + } 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. +within the block. As a result, it is not possible to overload their +names. +It is our intention to have a transparent solution to this problem +in place for our first official release. 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) -Can I contribute to Cforall? -------------------------- + - abstract types introduced using the keyword 'type' are not + implemented (although 'type' can be used to introduce type + parameters) -Not at the moment. Cforall is a research project that is not stable enough to -have outside contributes adding or making significant changes. You can help us -my trying Cforall to get a flavour for what we are trying to accomplish. Please -identify design problems and small issues or errors, which we will try to -incorporate/fix. However, we are a small team, so nothing happens quickly. - - + - the implicit coercion of structure types to the type of their + first member is not implemented + 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. +cfa-cc was written by Peter Buhr, Richard Bilson, and Rodolfo Esteves. +Questions and comments can be sent to cforall@plg.uwaterloo.ca. -Check the Cforall web site https://cforall.uwaterloo.ca for news and updates. +The Cforall project maintains a web page: + + http://plg.uwaterloo.ca/~cforall