source: README @ 3fb7f5e

aaron-thesisarm-ehcleanup-dtorsdeferred_resndemanglerjacob/cs343-translationjenkins-sandboxnew-astnew-ast-unique-exprnew-envno_listpersistent-indexerresolv-newwith_gc
Last change on this file since 3fb7f5e was 6244dfb, checked in by Peter A. Buhr <pabuhr@…>, 7 years ago

update INSTALL README documentation

  • Property mode set to 100644
File size: 4.9 KB
Line 
1cfa-cc: The Cforall->C Compiler System
2======================================
3
4This is a PRE-RELEASE version of cfa-cc.  It exists solely for the purpose of
5private experimentation and scholarly research.  The authors disclaim all
6responsibility for the consequences of any malfunction of the software,
7including the malfunction of any programs compiled using the software.
8
9What is Cforall?
10----------------
11Cforall is a language design extending ISO C. The purpose of the project is to
12engineer modern language features into C in an evolutionary rather than
13revolutionary way. Java is an example of the revolutionary approach of
14modernizing C/C++, resulting in a new language rather than an extension of its
15descendents. C++, Fortran 95 and Cobol 9X are examples of the evolutionary
16approach where modern language features are added and problems fixed within the
17framework of an existing language.
18
19The goal of this project is to produce a largely backwards compatible version
20of C containing many modern language features and fixing some of the well known
21C problems. Without continued development of the language, C will be unable to
22cope with the needs of modern programming problems and programmers; as a
23result, it will fade into disuse.  Considering the large body of existing C
24code and programmers, there is a significant impetus to ensure C is transformed
25into a modern programming language.
26
27What is cfa-cc?
28---------------
29cfa-cc is a collection of programs centred around a translator that takes
30Cforall code as input and outputs corresponding C code.  This is complemented
31by a compiler driver in the style of "gcc", which handles preprocessing,
32compiling, assembling, and linking and invokes the translator at appropriate
33moments.
34
35What is required in order to use cfa-cc?
36----------------------------------------
37Building cfa-cc requires GNU Make and gcc/g++ 4.  cfa-cc is written in C++.
38
39The compiler driver uses an installed version of gcc to handle all aspects of
40the compilation process except for the Cforall->C translation.  Currently, only
41gcc 4.x is supported.
42
43How is cfa-cc used?
44-------------------
45The compiler driver "cfa" accepts all of the arguments of gcc, and is used in
46the same way.  For example:
47
48        cfa -c test.c
49        cfa test.o
50
51Cforall source files must end with '.c' in order to be compiled by the compiler
52driver.  In addition, the flag "-CFA" causes cfa to invoke the preprocessor and
53translator and send the translator output to standard output.
54
55It is possible to invoke the translator directly.  The translator is installed
56by default as /usr/local/lib/cfa-cpp.  A typical invocation is:
57
58        /usr/local/lib/cfa-cpp -cp infile outfile
59
60If outfile is omitted, output goes to standard output; if infile is also
61omitted, input comes from standard input.  Options to the translator other than
62"-cp" will not produce valid C code and are only useful for debugging the
63translator.
64
65How can C code be used with cfa-cc?
66-----------------------------------
67cfa-cc should be able to compile most ANSI C programs.  It is also possible to
68link against C libraries in most cases.  Since Cforall supports overloading,
69however, names used in Cforall code are mangled in the output C code.  This
70caused linker failures when the names refer to functions and objects in code
71compiled with a standard C compiler.  For this reason, it is necessary to
72enclose the declarations of these functions and objects in extern "C" {}
73blocks.  For example:
74
75        extern "C" {
76        #include <stdio.h>
77        #include <stdlib.h>
78        }
79
80The extern "C" turns off name mangling for functions and objects declared
81within the block.  As a result, it is not possible to overload their names.
82
83What's wrong with cfa-cc?
84-------------------------
85
86The authors consider this software to be in an unstable state.  It is quite
87likely that there are many reasonable programs that will fail to compile.  We
88encourage users to report their experiences to cforall@plg.uwaterloo.ca, but we
89make no promises regarding support.
90
91We have fixed most of the problems that we are aware of.  There are some
92exceptions:
93
94- initializers are poorly implemented; in particular, file-scope initializers
95  may result in the generation of invalid C code
96
97- the ISO C99 designated initialization syntax '[n] = m' or '.n = m' is not
98  supported; use a colon in place of the equal sign
99
100- some legitimate programs will produce warnings from the C compiler; these are
101  harmless (in particular, the creation of libcfa.a in the build process should
102  cause four warnings from gcc)
103
104- abstract types introduced using the keyword 'type' are not implemented
105  (although 'type' can be used to introduce type parameters)
106
107- the implicit coercion of structure types to the type of their first member is
108  not implemented
109       
110Who is responsible for cfa-cc?
111------------------------------
112cfa-cc was written by Peter Buhr, Richard Bilson, and Rodolfo Esteves.
113Questions and comments can be sent to cforall@plg.uwaterloo.ca.
114
115The Cforall project maintains a web page:
116
117        http://plg.uwaterloo.ca/~cforall
Note: See TracBrowser for help on using the repository browser.