source: doc/man/cfa.1 @ 51b1202

.\"                             -*- Mode: Nroff -*- 
.\" 
.\" uC++ Version 6.1.0, Copyright (C) Peter A. Buhr 1994
.\" 
.\" u++.1 -- 
.\" 
.\" Author           : Peter A. Buhr
.\" Created On       : Sat Jul  2 21:47:05 1994
.\" Last Modified By : Peter A. Buhr
.\" Last Modified On : Fri Apr  6 13:44:28 2012
.\" Update Count     : 52
.\" 
.\" nroff -man u++.1
.\"
.ds Ho "/usr/local
.ds Vr "u++\-6.1.0
.TH u++ 1
.SH NAME
u++ \- uC++ Translator and Concurrency Runtime System
.SH SYNOPSIS
u++ [-option [...]] [filename [...]]
.SH DESCRIPTION
The u++ command compiles uC++ and C++ source files and links C++ object files
named on the command line.

The u++ command introduces a translator pass over the specified source files
after the C preprocessor but before the actual C++ compilation.  The translator
converts several new uC++ constructs into C++ statements.  The u++ command also
provides the runtime concurrency library, which must be linked with each uC++
application.

The command line options depend on the particular C++ compiler used.  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 g++(1) and CC(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.
All of the options available to the C++ compiler are available to u++, plus the
following:
.IP -debug 3
The program is linked with the debugging version of the unikernel or
multikernel.  The debug version performs runtime checks to help during the
debugging phase of a uC++ program, but substantially slows the execution of the
program. This option is the default.
.IP -nodebug
The program is linked with the non-debugging version of the unikernel or
multikernel, so the execution of the program is faster.  However, no runtime
checks or asserts are performed so errors usually result in abnormal program
termination.
.IP -yield
When a program is translated, a random number of context switches occur at the
beginning of each member routine so that during execution on a uniprocessor
there is a better simulation of parallelism.  (This non-determinism in
execution is in addition to random context switching due to pre-emptive
scheduling.  The extra yields of execution can help during the debugging phase
of a uC++ program, but substantially slows the execution of the program.
.IP -noyield
Additional context switches are not inserted in member routines.  This option
is the default.
.IP -verify
When a program is translated, a check to verify that the stack has not
overflowed occurs at the beginning of each member routine.  Verifying the
stack has not overflowed is important during the debugging phase of a uC++
program, but slows the execution of the program.
.IP -noverify
Stack-overflow checking is not inserted in member routines.  This option is the
default.
.IP -multi
The program is linked with the multikernel.  See the uC++ RUNTIME KERNELS
section below.
.IP -nomulti
The program is linked with the unikernel.  This option is the default.  See the
uC++ RUNTIME KERNELS section below.
.IP -quiet
The uC++ compilation message is not printed at the beginning of a
compilation.
.IP -noquiet
The uC++ compilation message is printed at the beginning of a compilation.
This option is the default.
.IP -U++
Only the C preprocessor and the uC++ translator steps are performed and the
transformed program is written to standard output, which makes it possible to
examine the code generated by the uC++ translator.
.IP "-compiler path-name"
The path-name of the compiler used to compile a uC++ program(s).  The default
is the compiler used to compile the uC++ runtime library.  It is unsafe to use
a different compiler unless the generated code is binary compatible.
.SH uC++ RUNTIME KERNELS
There are two versions of the uC++ kernel: the unikernel, which is designed to
use a single processor; and the multikernel, which is designed to use several
processors.  Thus, the unikernel is sensibly used on systems with a single
hardware processor or when kernel threads are unavailable; the multikernel is
sensibly used on systems that have multiple hardware processors and when kernel
threads are available.  The table below shows the situations where each kernel
can be used.  The unikernel can be used in a system with multiple hardware
processors and kernel threads but does not take advantage of either of these
capabilities.  The multikernel can be used on a system with a single hardware
processor and kernel threads but performs less efficiently than the unikernel
because it uses multiprocessor techniques unnecessarily.
.DS B
            +-----------+-------------------------+
            | no kernel |         kernel          |
            | threads   |         threads         |
 +----------+-----------+-------------------------+
 |single    |uni: yes   |uni: yes                 |
 |processor |multi: no  |multi: yes (inefficient) |
 +----------+-----------+-------------------------+
 |multiple  |uni: yes   |uni: yes (no parallelism)|
 |processors|multi: no  |multi: yes               |
 +----------+-----------+-------------------------+
.DE
.SH PREPROCESSOR VARIABLES
When programs are compiled using u++, the following preprocessor variables are
available.  These variables allow conditional compilation of programs that must
work differently in these situations.
.IP __U_CPLUSPLUS__ 3
is always available during preprocessing and its value is the current major
version number.
.IP __U_CPLUSPLUS_MINOR__
is always available during preprocessing and its value is the current minor
version number.
.IP __U_CPLUSPLUS_PATCH__
is always available during preprocessing and its value is the current patch
version number.
.IP __U_DEBUG__
is available during preprocessing if the -debug compilation option is
specified.
.IP __U_YIELD__
is available during preprocessing if the -yield compilation option is
specified.
.IP __U_VERIFY__
is available during preprocessing if the -verify compilation option is
specified.
.IP __U_MULTI__
is available during preprocessing if the -multi compilation option is specified.
.SH FILES
.DS B
file.{cc,C} - uC++ source file
.br
file.s - assembly language file
.br
file.o - object file
.br
\*(Ho/bin/u++ - translator
.br
\*(Ho/\*(Vr/doc - reference manual and license
.br
\*(Ho/\*(Vr/inc - 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
CC(1), cpp(1), g++(1)
.br
.I "uC++ Annotated Reference Manual"
.br
.I "Understanding Control Flow with Concurrent Programming using uC++"
.SH REFERENCES
.HP 3
.I "uC++: Concurrency in the Object-Oriented Language C++,"
by P.A. Buhr, G. Ditchfield, R.A. Stroobosscher, B.M. Younger, C.R. Zarnke;
Software-Practise and Experience, 22(2):137--172, February 1992.  This paper
describes uC++ v2.0, which has been significantly extended.
.HP
.I "Examining uC++,"
by Peter A. Buhr and Richard C. Bilson;
Dr. Dobb's Journal : Software Tools for the Professional Programmer,
31(2):36--40, February 2006. <http://drdobbs.com/cpp/184406431>
.HP
.I "uC++ Annotated Reference Manual"
most up-to-date features.
.SH BUGS
Bugs should be reported to usystem@plg.uwaterloo.ca.
.SH COPYRIGHT
This library is covered under the GNU Lesser General Public License.
.SH AUTHORS
Peter A. Buhr (pabuhr@plg.uwaterloo.ca) and many others, Programming Languages
Group, University of Waterloo, Ontario, Canada, N2L 3G1.