Index: doc/man/README =================================================================== --- doc/man/README (revision ab6ed1ec3913e43b5fa20701bcf9f158b93e099f) +++ doc/man/README (revision ab6ed1ec3913e43b5fa20701bcf9f158b93e099f) @@ -0,0 +1,5 @@ +There are troff variables at the beginning of the source files that define the +home path to cfa and the version number. The version variable should be set +properly (we sometimes forget); change the path for the home variable to the +location where cfa is installed. There is a command at the beginning of the +source file to format the manual entry. Index: doc/man/cfa.1 =================================================================== --- doc/man/cfa.1 (revision ab6ed1ec3913e43b5fa20701bcf9f158b93e099f) +++ doc/man/cfa.1 (revision ab6ed1ec3913e43b5fa20701bcf9f158b93e099f) @@ -0,0 +1,131 @@ +.\" -*- Mode: Nroff -*- +.\" +.\" Cforall Version 1.0.0 Copyright (C) 2017 University of Waterloo +.\" +.\" The contents of this file are covered under the licence agreement in the +.\" file "LICENCE" distributed with Cforall. +.\" +.\" cfa.1 -- +.\" +.\" Author : Peter A. Buhr +.\" Created On : Wed Jul 26 22:34:47 2017 +.\" Last Modified By : Peter A. Buhr +.\" Last Modified On : Thu Jul 27 07:25:59 2017 +.\" Update Count : 43 +.\" +.\" nroff -man cfa.1 +.\" +.ds Ho "/usr/local +.ds Mg "1 +.ds Mn "0 +.ds Pt "0 +.ds Vr "cfa-\*(Mg.\*(Mn.\*(Pt +.ds Cf "Cforall +.\" +.TH cfa 1 2017-07-27 cfa-\*(Mg +.SH NAME +cfa \- \*(Cf Translator and Runtime Library +.SH SYNOPSIS +cfa [gcc-options] [C/\*(Cf source-files] [assembler/loader files] +.SH DESCRIPTION +The cfa command compiles C and \*(Cf source files and links C/\*(Cf object +files named on the command line. + +The cfa command introduces a translator pass over the specified source files +after the C preprocessor but before the C compilation. The translator converts +new \*(Cf constructs into C statements. The cfa command also provides the +runtime library, which is linked with each \*(Cf application. + +The command line options depend on the particular C compiler used (gcc/clang +supported). As with most C compilers, the output is sent to the file a.out(5) +unless the -o option is present on the command line. See the reference pages +for gcc(1) for more information. +.SH OPTIONS +When multiple conflicting options appear on the command line, e.g., +.B -debug +followed by +.B -nodebug, +the last option takes precedence. +.LP +All of the options available to the gcc compiler are available to the cfa +translator. The following gcc flags are implicitly turned on: +.IP -std=gnu99 3 +The 1999 C standard plus GNU extensions. +.IP -fgnu89-inline +Use the traditional GNU semantics for inline routines in C99 mode, which allows inline routines in header files. +.LP +The following additional options are available: +.IP -CFA 3 +Only the C preprocessor and the \*(Cf translator steps are performed and the transformed program is written to standard output, which makes it possible to examine the code generated by the \*(Cf translator. +The generated code starts with the standard \*(Cf prelude. +.IP -debug +The program is linked with the debugging version of the runtime system. +The debug version performs runtime checks to help during the debugging phase of a \*(Cf program, but can substantially slow program execution. +The runtime checks should only be removed after the program is completely debugged. +.B This option is the default. +.IP -nodebug +The program is linked with the non-debugging version of the runtime system, so the execution of the program is faster. +.I However, no runtime checks or asserts are performed so errors usually result in abnormal program behaviour or termination. +.IP -help +Information about the set of \*(Cf compilation flags is printed. +.IP -nohelp +Information about the set of \*(Cf compilation flags is not printed. +.B This option is the default. +.IP -quiet +The \*(Cf compilation message is not printed at the beginning of a compilation. +.IP -noquiet +The \*(Cf compilation message is printed at the beginning of a compilation. +.B This option is the default. +.SH PREPROCESSOR VARIABLES +When programs are compiled using cfa, the following preprocessor variables are +available. These variables allow conditional compilation of programs that must +work differently in these situations. +.IP __CFA_MAJOR__ 3 +is available during preprocessing and its value is the major version number of \*(Cf. +.IP __CFA_MINOR__ +is available during preprocessing and its value is the minor version number of \*(Cf. +.IP __CFA_PATCH__ +is available during preprocessing and its value is the patch level number of \*(Cf. +.IP "__CFA__, __CFORALL__, and __cforall" +are always available during preprocessing and have no value. +.IP __CFA_DEBUG__ +is available during preprocessing if the -debug compilation option is +specified. +.SH FILES +.DS B +file.{cc,C} - \*(Cf source file +.br +file.s - assembly language file +.br +file.o - object file +.br +\*(Ho/\*(Vr/bin/cfa - translator +.br +\*(Ho/\*(Vr/doc - reference manuals and documents +.br +\*(Ho/\*(Vr/include - header files +.br +\*(Ho/\*(Vr/lib - run time libraries +.br +\*(Ho/\*(Vr/man - command documentation +.br +\*(Ho/\*(Vr/src - source code (optional) +.DE +.SH SEE ALSO +cpp(1), gcc(1), gdb(1) +.SH REFERENCES +.HP 3 +\*(Cf Reference and Rational Manual +.br +http://plg.uwaterloo.ca/~cforall/refrat.pdf +.HP +.I \*(Cf User Manual +.br +http://plg.uwaterloo.ca/~cforall/user.pdf +.SH BUGS +Bugs should be reported to trac@plg.cs.uwaterloo.ca. +.SH COPYRIGHT +\*(Cf is covered under the licence agreement in the distribution. +.SH AUTHORS +Andrew Beach, Richard Bilson, Peter A. Buhr, Thierry Delisle, Glen Ditchfield, +Rodolfo G. Esteves, Aaron Moss, Rob Schluntz