source: doc/man/cfa.1 @ 99f4165

Last change on this file since 99f4165 was 99f4165, checked in by Peter A. Buhr <pabuhr@…>, 6 years ago

create documentation directory and insert stubs for files

  • Property mode set to 100644
File size: 7.4 KB
1.\"                             -*- Mode: Nroff -*-
3.\" uC++ Version 6.1.0, Copyright (C) Peter A. Buhr 1994
5.\" u++.1 --
7.\" Author           : Peter A. Buhr
8.\" Created On       : Sat Jul  2 21:47:05 1994
9.\" Last Modified By : Peter A. Buhr
10.\" Last Modified On : Fri Apr  6 13:44:28 2012
11.\" Update Count     : 52
13.\" nroff -man u++.1
15.ds Ho "/usr/local
16.ds Vr "u++\-6.1.0
17.TH u++ 1
19u++ \- uC++ Translator and Concurrency Runtime System
21u++ [-option [...]] [filename [...]]
23The u++ command compiles uC++ and C++ source files and links C++ object files
24named on the command line.
26The u++ command introduces a translator pass over the specified source files
27after the C preprocessor but before the actual C++ compilation.  The translator
28converts several new uC++ constructs into C++ statements.  The u++ command also
29provides the runtime concurrency library, which must be linked with each uC++
32The command line options depend on the particular C++ compiler used.  As with
33most C compilers, the output is sent to the file a.out(5) unless the -o option
34is present on the command line.  See the reference pages for g++(1) and CC(1)
35for more information.
37When multiple conflicting options appear on the command line, e.g.,
38.B -debug
39followed by
40.B -nodebug,
41the last option takes precedence.
42All of the options available to the C++ compiler are available to u++, plus the
44.IP -debug 3
45The program is linked with the debugging version of the unikernel or
46multikernel.  The debug version performs runtime checks to help during the
47debugging phase of a uC++ program, but substantially slows the execution of the
48program. This option is the default.
49.IP -nodebug
50The program is linked with the non-debugging version of the unikernel or
51multikernel, so the execution of the program is faster.  However, no runtime
52checks or asserts are performed so errors usually result in abnormal program
54.IP -yield
55When a program is translated, a random number of context switches occur at the
56beginning of each member routine so that during execution on a uniprocessor
57there is a better simulation of parallelism.  (This non-determinism in
58execution is in addition to random context switching due to pre-emptive
59scheduling.  The extra yields of execution can help during the debugging phase
60of a uC++ program, but substantially slows the execution of the program.
61.IP -noyield
62Additional context switches are not inserted in member routines.  This option
63is the default.
64.IP -verify
65When a program is translated, a check to verify that the stack has not
66overflowed occurs at the beginning of each member routine.  Verifying the
67stack has not overflowed is important during the debugging phase of a uC++
68program, but slows the execution of the program.
69.IP -noverify
70Stack-overflow checking is not inserted in member routines.  This option is the
72.IP -multi
73The program is linked with the multikernel.  See the uC++ RUNTIME KERNELS
74section below.
75.IP -nomulti
76The program is linked with the unikernel.  This option is the default.  See the
77uC++ RUNTIME KERNELS section below.
78.IP -quiet
79The uC++ compilation message is not printed at the beginning of a
81.IP -noquiet
82The uC++ compilation message is printed at the beginning of a compilation.
83This option is the default.
84.IP -U++
85Only the C preprocessor and the uC++ translator steps are performed and the
86transformed program is written to standard output, which makes it possible to
87examine the code generated by the uC++ translator.
88.IP "-compiler path-name"
89The path-name of the compiler used to compile a uC++ program(s).  The default
90is the compiler used to compile the uC++ runtime library.  It is unsafe to use
91a different compiler unless the generated code is binary compatible.
93There are two versions of the uC++ kernel: the unikernel, which is designed to
94use a single processor; and the multikernel, which is designed to use several
95processors.  Thus, the unikernel is sensibly used on systems with a single
96hardware processor or when kernel threads are unavailable; the multikernel is
97sensibly used on systems that have multiple hardware processors and when kernel
98threads are available.  The table below shows the situations where each kernel
99can be used.  The unikernel can be used in a system with multiple hardware
100processors and kernel threads but does not take advantage of either of these
101capabilities.  The multikernel can be used on a system with a single hardware
102processor and kernel threads but performs less efficiently than the unikernel
103because it uses multiprocessor techniques unnecessarily.
104.DS B
105            +-----------+-------------------------+
106            | no kernel |         kernel          |
107            | threads   |         threads         |
108 +----------+-----------+-------------------------+
109 |single    |uni: yes   |uni: yes                 |
110 |processor |multi: no  |multi: yes (inefficient) |
111 +----------+-----------+-------------------------+
112 |multiple  |uni: yes   |uni: yes (no parallelism)|
113 |processors|multi: no  |multi: yes               |
114 +----------+-----------+-------------------------+
117When programs are compiled using u++, the following preprocessor variables are
118available.  These variables allow conditional compilation of programs that must
119work differently in these situations.
120.IP __U_CPLUSPLUS__ 3
121is always available during preprocessing and its value is the current major
122version number.
124is always available during preprocessing and its value is the current minor
125version number.
127is always available during preprocessing and its value is the current patch
128version number.
129.IP __U_DEBUG__
130is available during preprocessing if the -debug compilation option is
132.IP __U_YIELD__
133is available during preprocessing if the -yield compilation option is
135.IP __U_VERIFY__
136is available during preprocessing if the -verify compilation option is
138.IP __U_MULTI__
139is available during preprocessing if the -multi compilation option is specified.
141.DS B
142file.{cc,C} - uC++ source file
144file.s - assembly language file
146file.o - object file
148\*(Ho/bin/u++ - translator
150\*(Ho/\*(Vr/doc - reference manual and license
152\*(Ho/\*(Vr/inc - header files
154\*(Ho/\*(Vr/lib - run time libraries
156\*(Ho/\*(Vr/man - command documentation
158\*(Ho/\*(Vr/src - source code (optional)
161CC(1), cpp(1), g++(1)
163.I "uC++ Annotated Reference Manual"
165.I "Understanding Control Flow with Concurrent Programming using uC++"
167.HP 3
168.I "uC++: Concurrency in the Object-Oriented Language C++,"
169by P.A. Buhr, G. Ditchfield, R.A. Stroobosscher, B.M. Younger, C.R. Zarnke;
170Software-Practise and Experience, 22(2):137--172, February 1992.  This paper
171describes uC++ v2.0, which has been significantly extended.
173.I "Examining uC++,"
174by Peter A. Buhr and Richard C. Bilson;
175Dr. Dobb's Journal : Software Tools for the Professional Programmer,
17631(2):36--40, February 2006. <>
178.I "uC++ Annotated Reference Manual"
179most up-to-date features.
181Bugs should be reported to
183This library is covered under the GNU Lesser General Public License.
185Peter A. Buhr ( and many others, Programming Languages
186Group, University of Waterloo, Ontario, Canada, N2L 3G1.
Note: See TracBrowser for help on using the repository browser.