.\" -*- 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. .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.