---

Manual Reference Pages  - UPCC (1)

---

upcc - the Berkeley UPC compiler

CONTENTS

Synopsis
Description

upcc [options] foo.upc [ bar.c someobject.o ... ]

upcc is the front-end to the Berkeley UPC compiler suite. It handles all stages of the UPC compilation process: 1) initial preprocessing, 2) UPC-to-C translation, 3) back-end C compilation, and 4) linking.

upcc has the same interface as a traditional C compiler, plus some additional flags for UPC-specific options. Default options to be used for every compilation can be specified in the UPCC_FLAGS environment variable, and in the upcc configuration files (see below).

-c	Compile source files, but do not link.
-E	Preprocess source files (output sent to stdout).
-g	Generate debug objects/executables [UNIMPLEMENTED].
-DFOO[=bar]
	Define preprocessor symbol FOO [to optional value].
-I path	Add path to directories searched for header files.
-lfoo	Link executable with libfoo.a.
-Ldir	Add ’dir’ to library search path.
-O	Generate optimized objects/executables [UNIMPLEMENTED].
-o name	Output file will be called ’name’.

-network=<type>
	Set network API used: ’mpi’, ’udp’, ’elan’, ’lapi’, ’gm’, ’vapi’, ’sci’ or ’smp’.
	(run ’upcc -version’ to see which of these are available in your upcc installation).
-shared-heap=NUM
	Specify default amount (per UPC thread) of shared memory. Defaults to megabytes: use ’1GB’ for 1 gigabyte. Can override at startup via the UPC_SHARED_HEAP_SIZE environment variable.
-T=NUM	Generate code for a fixed number NUM of UPC threads This allows optimization of certain operations (such as shared pointer arithmetic), especially when NUM is a power of 2. The disgusting syntax -f(upc-)threads-NUM is also accepted, for compatibility with other UPC compilers.

-h -? -help	Print this message.
-norc	Do not read $HOME/.upccrc configuration file. This can also be achieved by setting the UPCC_NORC environment variable.
-smart-output
	Output file name will be auto-generated based on first .c/.upc/.o file on command line (ignored if -o passed).
-version	Show version information.

-[no]checks
	Turn off build consistency checking. Caveat nerdtor...
-echo-var VAR
	Print value for VAR used by the internal upcc Makefile framework (for internal use only)
-heap-offset=num
	Embed a default offset betwen the starting addresses of the regular and shared heaps into executable. Defaults to megabytes: use ’2GB’ for 2 gigabytes. Can override at startup via the UPC_SHARED_HEAP_OFFSET environment variable.
-[no]lines
	Insert line directives for original UPC code into translated C code. On by default.
-[no]link-cache
	Disable the use of the pthread-link cache directory used to speed up linking of multi-file pthread applications.
-link-with <PROG>
	Use PROG to as the back-end linker. Use to combine UPC code with external C++ and/or MPI code.
-nightly	Use nightly build of UPC-to-C translator at http://upc-translator.lbl.gov/upcc-nightly.cgi
-pthreads[=N]
	Generate a pthreaded UPC executable, and optionally embed the default number of pthreads to use per process (this can be overridden at startup via the UPC_PTHREADS_PER_PROC or UPC_PTHREADS_MAP environment variables). A value of N=0 disables creation of a pthreaded executable.
-nopthreads
	Alias for -pthreads=0.
-[no]require-size
	Die at startup if amount of shared memory available is less than requested: off by default. Can be overridden at startup by setting the UPC_REQUIRE_SHARED_SIZE environment variable to ’yes’ or ’no’
-[no]size-warn
	Warn at startup if amount of shared memory available is less than requested: on by default. Can be overridden at at startup by setting the UPC_SIZE_WARN environment variable to ’yes’ or ’no’.
-[no]save-temps
	Save ’interesting’ temporary files (.i, .trans.c, .o) generated during translation/compilation.
-[no]save-all-temps
	Save all files used during translation/compilation. Most are placed in a ’{target}_temps’ subdirectory.
-print-include-dir Prints full path to directory in which <bupc_extern.h>
	is located.
-print-mpicc
	Prints full pathname of a MPI compiler compatible with this installation of upcc, or error if MPI not supported.
-stable	Use latest ’stable’ build of UPC-to-C translator at http://upc-translator.lbl.gov/upcc-stable.cgi
-trans	Stop after translating UPC to C (outputs ’foo.trans.c’).
-uses-mpi	MPI interoperability support. Pass at compile-time if a UPC file contains calls to MPI functions. Pass at link time if any objects (including C objects/libraries) use MPI.
-v	Verbose: display programs invoked by compiler.
-vv	Extra verbose: pass verbose flag to programs invoked.
-Wp,<option>
	Pass arbitrary option to the back-end C preprocessor: use repeatedly to pass multiple options. If you need to use spaces, quote the option (ex: -Wp,"--option value").
-Wu,<option>
	Pass arbitrary option to sgiupc: use repeatedly to pass multiple options. If you need to use spaces, quote the option (ex: -Wu,"--option value").
-Ww,<option>
	Pass arbitrary option to whirl2c translator: use repeatedly to pass multiple options. If you need to use spaces, quote the option (ex: -Ww,"--option value").
-Wc,<option>
	Pass arbitrary option to the back-end C compiler: use repeatedly to pass multiple options. If you need to use spaces, quote the option (ex: -Wc,"--option value").
-Wl,<option>
	Pass arbitrary option to the back-end C linker: use repeatedly to pass multiple options. If you need to use spaces, quote the option (ex: -Wl,"--option value").
-yesterday|-hier
	Use yesterday’s UPC-to-C translator at http://upc-translator.lbl.gov/upcc-yesterday.cgi

upcc recognizes both ‘.c’ and ‘.upc’ as valid file name extensions for UPC code. Header files may have either a ‘.uph’ or ‘.h’ extension.

‘.trans.c’ is recognized specially as a file which has already been translated (via a previous call to ‘upcc -trans’). upcc passes ‘.trans.c’ files directly to the C compiler/linker.

Berkeley UPC is fully interoperable with regular C source, object, and library files. You may pass regular C files to upcc, include regular .h files in your UPC code, and link C-based libraries and object files into a UPC application.

upcc uses a site-wide ‘upcc.conf’ file to get some of its settings. You may override any of the settings found in the global upcc.conf file by creating a ‘.upccrc’ file in your $HOME directory.

To choose a different default network API for your programs:

default_network=[mpi, udp, smp, lapi, gm, vapi, sci, elan]

To specify flags to pass to upcc each time it is invoked, set ‘default_options’:

default_options = -save-all-temps -v -DFOO=bar

To specify flags to pass to upcc each time it is invoked for a specific network (a.k.a. conduit), set ‘<conduit>_options’:

mpi_options = -v -DUSING_MPI=1

To override the default amount of shared memory (per UPC thread) to be used by your UPC applications:

shared_heap = 128MB // or ‘2GB’, etc.

To use a different UPC-to-C translator:

translator = /path/to/translator # local translator
translator = http://foo.org/upcc.cgi # remote via HTTP
translator = foo.org:/path/to/translator # remote via SSH

See the Berkeley UPC User’s Guide for more information on using a remote translator.

To have upcc use the basename of the first file argument for the executable name (i.e., ‘upcc foo.upc bar.upc’ will produce ‘foo’ instead of ‘a.out’):

smart_output = yes #or put -smart-output in ‘default_options’

The UPCC_FLAGS environment variable can be set to pass any flags/arguments that you wish to use for every invocation of upcc. This is in addition to the ‘default_options’ parameter described above.

Options are read from the site-wide and user-specific configuration files, the environment and the command-line. The precedence of options is equivalent to parsing the options in the following order:

default_options <conduit>_options UPCC_FLAGS command-line

For options which set a value (such as -T and -shared-heap), the last value seen is the one used. Thus values on the command-line always take precedence over any others.

The ‘default_options’ and ‘<conduit>_options’ are taken from your $HOME/.upccrc file if present there, or from the site-wide upcc.conf otherwise. If a given setting is present in both files only the settings in $HOME/.upccrc are used; they are not additive. However, passing the option -norc on the command-line or setting the UPCC_NORC environment variable will disable reading of the $HOME/.upccrc file, causing ‘default_options’ and ‘<conduit>_options’ to be taken only from the site-wide upcc.conf.

Arguments in ‘default_options’, ‘<conduit>_options’ and UPCC_FLAGS are split on whitespace, but single- or double-quotes will suppress splitting. The backslash character ‘#146; does not have any special meaning.

To avoid ambiguity ‘-network=FOO’ is not allowed in the ‘<conduit>_options’ settings. The option ‘-norc’ is only permitted on the command-line, though its affect can also be achieved by setting UPCC_NORC.

The following small Makefile shows how you might handle the .upc extension if you use ‘make’ to build your programs:

_______________________________________________________

# A simple Makefile for building UPC programs

TARGET = foobar
UPCC = upcc
UPCFLAGS = -g

UPC_OBJS = foo.o bar.o

.SUFFIXES:
.SUFFIXES: .upc .o

# suffix rule for compiling .upc files
.upc.o:
$(UPCC) -c $(UPCFLAGS) -o $@ $<

$(TARGET): $(UPC_OBJS)
$(UPCC) $(UPCFLAGS) -o $(TARGET) $(UPC_OBJS)
_______________________________________________________

$make
upcc -c -g foo.upc
upcc -c -g bar.upc
upcc -g -o foobar foo.o bar.o

Alternatively, if you use the .c extension for your UPC files, you can simply set the CC variable in your Makefile (or your shell environment) to ‘upcc’, after which the regular make rules for C files will handle your UPC files (and the standard CFLAGS variable can be set to pass upcc options).

We are very interested in fixing any bugs in our UPC implementation. For bug reporting instructions, please go to http://upc.lbl.gov.

upcrun(1)

The Berkeley UPC User’s Guide (available at http://upc.lbl.gov)