Changeset 4200b7e for README


Ignore:
Timestamp:
Jun 27, 2021, 9:53:50 PM (3 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

File:
1 edited

Legend:

Unmodified
Added
Removed

  • README

    r2e19e91 r4200b7e  
    1 cfa-cc: The Cforall->C Compiler System
     1cfa-cc: Cforall to C Trans-compiler
    22======================================
    33
    … …  
    66responsibility for the consequences of any malfunction of the software,
    77including the malfunction of any programs compiled using the software.
     8
    89
    910What is Cforall?
    … …  
    2526into a modern programming language.
    2627
     28
    2729What is cfa-cc?
    2830---------------
    29 cfa-cc is a collection of programs centred around a translator that takes
    30 Cforall code as input and outputs corresponding C code.  This is complemented
    31 by a compiler driver in the style of "gcc", which handles preprocessing,
    32 compiling, assembling, and linking and invokes the translator at appropriate
    33 moments.
     31cfa-cc is a collection of programs centred around a translator (trans-compiler)
     32that takes Cforall code as input and outputs augmented C code that implements
     33new features.  The translator is complemented by a compiler driver in the style
     34of "gcc", which handles preprocessing (including cfa-cc after cpp), compiling,
     35assembling, and linking.
    3436
    35 What is required in order to use cfa-cc?
     37cfa-cc is currently written in C++, but eventually be rewritten in Cforall.
     38
     39
     40How to download and build cfa-cc?
    3641----------------------------------------
    37 Building cfa-cc requires GNU Make and gcc/g++ 4.  cfa-cc is written in C++.
     42Download cfa-cc using
    3843
    39 The compiler driver uses an installed version of gcc to handle all aspects of
    40 the compilation process except for the Cforall->C translation.  Currently, only
    41 gcc 4.x is supported.
     44  $ git clone https://github.com/cforall/cforall.git
    4245
    43 How is cfa-cc used?
     46Read the ./INSTALL file for build instructions.
     47
     48
     49How to use cfa-cc?
    4450-------------------
    45 The compiler driver "cfa" accepts all of the arguments of gcc, and is used in
     51The compiler driver "cfa" accepts all of the arguments for gcc, and is used in
    4652the same way.  For example:
    4753
    48         cfa -c test.c
    49         cfa test.o
     54  cfa -c test.c
     55  cfa test.o
    5056
    51 Cforall source files must end with '.c' in order to be compiled by the compiler
    52 driver.  In addition, the flag "-CFA" causes cfa to invoke the preprocessor and
    53 translator and send the translator output to standard output.
     57Cforall source files may end with '.c' or '.cfa' in order to be compiled by the
     58compiler driver.  In addition, the flag "-CFA" causes cfa to invoke the C
     59preprocessor and Cforall translator and write the translator output to standard
     60output.
    5461
    55 It is possible to invoke the translator directly.  The translator is installed
    56 by default as /usr/local/lib/cfa-cpp.  A typical invocation is:
    5762
    58         /usr/local/lib/cfa-cpp -cp infile outfile
     63How to use C code with cfa-cc?
     64-----------------------------------
     65cfa-cc should be able to compile and link most ANSI C programs with associated
     66C standard libraries.
    5967
    60 If outfile is omitted, output goes to standard output; if infile is also
    61 omitted, 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
    63 translator.
     68Like C++, Cforall supports overloading, resulting in duplicate names that are
     69disambiguated using name mangling in the translated C code.  To prevent
     70mangling of C names, it is necessary to wrap C declarations in an extern "C"
     71block, as for C++.  For example:
    6472
    65 How can C code be used with cfa-cc?
    66 -----------------------------------
    67 cfa-cc should be able to compile most ANSI C programs.  It is also possible to
    68 link against C libraries in most cases.  Since Cforall supports overloading,
    69 however, names used in Cforall code are mangled in the output C code.  This
    70 caused linker failures when the names refer to functions and objects in code
    71 compiled with a standard C compiler.  For this reason, it is necessary to
    72 enclose the declarations of these functions and objects in extern "C" {}
    73 blocks.  For example:
    74 
    75         extern "C" {
    76         #include <stdio.h>
    77         #include <stdlib.h>
    78         }
     73  extern "C" {
     74  #include <curses.h>
     75  #include <getopt.h>
     76  }
    7977
    8078The extern "C" turns off name mangling for functions and objects declared
    81 within the block.  As a result, it is not possible to overload their names.
     79within the block. All C standard headers are pre-wrapped, so most wrapping is
     80unnecessary.
     81
    8282
    8383What's wrong with cfa-cc?
    8484-------------------------
    8585
    86 The authors consider this software to be in an unstable state.  It is quite
    87 likely that there are many reasonable programs that will fail to compile.  We
    88 encourage users to report their experiences to cforall@plg.uwaterloo.ca, but we
    89 make no promises regarding support.
     86The authors consider cfa-cc to be in a semi-stable state.  It is possible for
     87reasonable Cforall programs to fail compilation.  A list of bugs and fixes is
     88available here: https://cforall.uwaterloo.ca/trac.  We encourage users to
     89report their experiences to cforall@plg.uwaterloo.ca, but we can make no
     90promises regarding support.
    9091
    91 We have fixed most of the problems that we are aware of.  There are some
    92 exceptions:
     92Also, the Cforall features web-page https://cforall.uwaterloo.ca/features lists
     93small syntactic and semantic differences with standard C.
    9394
    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
    10995
    11096Who is responsible for cfa-cc?
    11197------------------------------
    112 cfa-cc was written by Peter Buhr, Richard Bilson, and Rodolfo Esteves.
    113 Questions and comments can be sent to cforall@plg.uwaterloo.ca.
     98Cforall was designed and implemented by Andrew Beach, Richard Bilson, Michael
     99Brooks, Peter A. Buhr, Thierry Delisle Glen Ditchfield, Rodolfo G. Esteves,
     100Aaron Moss, Colby Parsons, Rob Schluntz, Fangren Yu, Mubeen Zulfiqar, and others.
    114101
    115 The Cforall project maintains a web page:
    116 
    117         https://cforall.uwaterloo.ca
     102Check the Cforall web site https://cforall.uwaterloo.ca for news and updates.
Note: See TracChangeset for help on using the changeset viewer.