.\"                             -*- 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 10:29:29 2017
.\" Update Count     : 44
.\" 
.\" 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.{c,cfa} - \*(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