---

Manual Reference Pages  - UPCC (1)

---

upcc - the Berkeley UPC compiler, version 2.4.0

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.
-DFOO[=bar]
	Define preprocessor symbol FOO [to optional value].
-E	Preprocess source files (output sent to stdout).
-g	Generate debug objects/executables [UNIMPLEMENTED].
-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]. Does *not* enable experimental translator optimizations.
-opt	Enable EXPERIMENTAL UPC translator optimizations
-o name	Output file will be called ’name’.
-pg	Generate OS-specific sequential performance profiling information in the executable (on supported platforms)
-s	Strip the symbolic information from the final executable.
-UBAR	Undefine preprocessor symbol BAR.

-network=<type>
	Set network API use for communication. Valid types include: mpi, udp, elan, lapi, gm, smp, vapi, sci, shmem, portals
	Run ’upcc -version’ to see which are available, and the default.
-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).
-V -version
	Show version information.
-v	Verbose: display programs invoked by compiler.
-vv	Extra verbose: pass verbose flag to programs invoked.

-[no]checks
	Turn off build consistency checking. Caveat nerdtor...
-compress=NUM
	Specify a gzip compression level for the HTTP netcompile data stream, from 0 (off) to 9 (best). Higher values may speed compilation over slow links, at an increase in CPU cost.
-echo-var VAR
	Print value for VAR used by the internal upcc Makefile framework (for internal use only)
-[no]fast-symptr
	Use fast symmetric pointers for power-of-two static threads. (Available only for ’-network=smp -pthreads’ (or ’-network=shmem’ on the Cray X1). If available, on by default if -T passed a power-of-two value.
-shared-heap-max=NUM
	Specify the hard limit (per UNIX process) of the shared memory heap. This constitutes an upper limit on -shared-heap (although unlike -shared-heap this is a per-NODE setting, so under -pthreads, all UPC threads on a node share this space). Setting this value too high can lead to long application startup times or memory exhaustion on some systems. Defaults to megabytes: use ’1GB’ for 1 gigabyte. Can be overridden at startup via the GASNET_MAX_SEGSIZE environment variable on *most* networks.
-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
-nopthreads
	Alias for -pthreads=0.
-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.
-inst[-local,-functions]
	Used internally by GASP performance tool wrapper scripts
-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.
-[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]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.
-show-sizes
	Show the internally used platform sizes file
-[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’.
-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’).
-translator=<path> Use UPC-to-C translator at <path>, which is formatted
	identically to the ’translator’ conf-file option
-tv	Compile an executable that can be debugged by Totalview: Implies -g. Not supported on all platforms.
-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 libraries) use MPI.
-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), upc_trace(1)

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