Setting up Your Environment for Chapel

To get started with Chapel, there are four environment settings that are strongly recommended for effective use of the release, and a few other optional settings that are useful for cross-compiling or overriding the default settings. To check the values of the Chapel environment variables that are set or can be inferred, run the script:

$CHPL_HOME/util/printchplenv

The setchplenv.* source scripts in the $CHPL_HOME/util/quickstart/ and $CHPL_HOME/util/ directories contain commands that set the following variables for various shells and host platforms when they are sourced from the $CHPL_HOME directory. Frequent Chapel users may want to add such settings to their shell's dotfile(s); but for getting started the setchplenv.* scripts can be convenient.

Optional Settings

CHPL_TARGET_PLATFORM

If you are cross-compiling for a platform other than your $CHPL_HOST_PLATFORM, set the CHPL_TARGET_PLATFORM environment variable to describe that platform. See CHPL_HOST_PLATFORM above for legal values (though whether or not a given setting will support cross-compilation depends on your specific environment).

Note

If CHPL_TARGET_PLATFORM is not set, the target platform defaults to the same value as $CHPL_HOST_PLATFORM.

CHPL_*_COMPILER

Optionally, you can set CHPL_HOST_COMPILER and/or CHPL_TARGET_COMPILER to indicate the compiler suite to use in building the sources. CHPL_HOST_COMPILER is the compiler used to build the Chapel compiler itself so that it will run on CHPL_HOST_PLATFORM. CHPL_TARGET_COMPILER is the compiler used to build the runtime libraries and generated code for CHPL_TARGET_PLATFORM. Currently supported values are as follows:

Value Description
clang The Clang compiler suite -- clang and clang++
clang-included The Clang compiler in third-party/llvm
cray-prgenv-cray The Cray PrgEnv compiler using the Cray CCE backend
cray-prgenv-gnu The Cray PrgEnv compiler using the GNU backend
cray-prgenv-intel The Cray PrgEnv compiler using the Intel backend
cray-prgenv-pgi The Cray PrgEnv compiler using the PGI backend
gnu The GNU compiler suite -- gcc and g++
ibm The IBM compiler suite -- xlc and xlC
intel The Intel compiler suite -- icc and icpc
pgi The PGI compiler suite -- pgcc and pgc++

The default for CHPL_*_COMPILER depends on the value of the corresponding CHPL_*_PLATFORM environment variable:

Platform Compiler
cray-x*
  • gnu (for CHPL_HOST_COMPILER)
  • cray-prgenv-$PE_ENV (for CHPL_TARGET_COMPILER, where PE_ENV is set by PrgEnv-* modules)
darwin clang if available, otherwise gnu
marenostrum ibm
pwr5, pwr6 ibm
other gnu

If CHPL_HOST_PLATFORM == CHPL_TARGET_PLATFORM and is not cray-x*, CHPL_TARGET_COMPILER will default to the same value as CHPL_HOST_COMPILER.

Note

Note that builds with LLVM Support (i.e. when CHPL_LLVM=llvm) will build the runtime twice: once with the compiler as described above and once with clang-included. We do this in order to avoid issues in linking objects built by different compilers.

CHPL_TARGET_ARCH

Optionally, set the CHPL_TARGET_ARCH environment variable to indicate that the target executable should be specialized to the given architecture when using --specialize (and --fast). Valid options are:

Value Description
native The C compiler will attempt to detect the architecture on the machine that is compiling the target executable. This is a good choice if you will be running on the same machine that you are compiling on. If you are not, see the options below.
unknown No specialization will be performed
none No specialization will be performed (will not warn)

Architecture-specific values

intel amd
core2 k8
nehalem k8sse3
westmere barcelona
sandybridge bdver1
ivybridge bdver2
haswell bdver3
broadwell bdver4

These values are defined to be the same as in GCC 4.9:

If you do not want CHPL_TARGET_ARCH to have any effect, you can set it to either unknown or none. Both will disable specialization, but the latter will not warn if --specialize is used.

Setting CHPL_TARGET_ARCH to an incorrect value for your processor may result in an invalid binary that will not run on the intended machine. Special care should be taken to select the lowest common denominator when running on machines with heterogeneous processor architectures.

The default value for this setting will vary based on settings in your environment, in order of application these rules are:

  • If CHPL_TARGET_COMPILER is cray-prgenv-* you do not need to set anything in CHPL_TARGET_ARCH. One of the craype-* modules (e.g. craype-sandybridge) should be loaded to provide equivalent functionality. Once the proper module is loaded, CRAY_CPU_TARGET will have the architecture being used in it.
  • If CHPL_TARGET_COMPILER is cray, pgi, or ibm, CHPL_TARGET_ARCH will be set to none and no specialization will occur.
  • If CHPL_COMM is set, no attempt to set a useful value will be made, CHPL_TARGET_ARCH will be unknown.
  • If CHPL_TARGET_PLATFORM is darwin, linux*, or cygwin* CHPL_TARGET_ARCH will be native, passing the responsibility off to the backend C compiler to detect the specifics of the hardware.

CHPL_MAKE

Optionally, set the CHPL_MAKE environment variable to indicate the GNU-compatible make utility that you want the compiler back-end to invoke when compiling the generated C code. If not set, this will default to a value based on $CHPL_HOST_PLATFORM:

platform make utility
cygwin*, darwin make
linux32, linux64 gmake if available, otherwise make
other gmake

CHPL_MODULE_PATH

Optionally, set the CHPL_MODULE_PATH environment variable to provide a list of directories to be added to the Module Search Paths. The value of this environment variable should be a colon-separated list of directory paths.

The module search path is used to satisfy 'use' statements in the Chapel program. The complete search path can be displayed using the compiler option --print-search-dirs. It will also include the compiler's standard module search paths, those introduced by the -M flag on the command line and directories containing the .chpl files named explicitly on the compiler command line.

CHPL_LOCALE_MODEL

Optionally, set the CHPL_LOCALE_MODEL environment variable to indicate the locale model you want to use. Current options are:

Value Description
flat top-level locales are not further subdivided
numa top-level locales are further subdivided into sublocales, each one a NUMA domain

If unset, CHPL_LOCALE_MODEL defaults to flat.

See Locale Models for more information about locale models.

CHPL_TASKS

Optionally, set the CHPL_TASKS environment variable to indicate what tasking layer you want to use to implement intra-locale parallelism (see Chapel Tasks for more information on this option). Current options are:

Value Description
qthreads use Sandia's Qthreads package
fifo use POSIX threads
massivethreads use U Tokyo's MassiveThreads package
muxed use Cray-specific lightweight threading (with Cray pre-built module only)

If CHPL_TASKS is not set it defaults to qthreads in all cases except for a few specific configurations in which it defaults to fifo:

  • target platform is cygwin*
  • target platform is netbsd*

Note

Note that the Chapel util/quickstart/setchplenv.* source scripts set CHPL_TASKS to fifo to reduce build-time and third-party dependences, while the util/setchplenv.* versions leave it unset, resulting in the behavior described just above.

See Chapel Tasks for more information about executing using the various CHPL_TASKS options. See also Using Chapel on Cray Systems for more information about Cray-specific runtime layers.

CHPL_COMM

Optionally, set the CHPL_COMM environment variable to indicate what communication layer you want to use to implement inter-locale communication. Current options are:

Value Description
none only supports single-locale execution
gasnet use the GASNet-based communication layer
ugni Cray-specific native communications (with Cray pre-built module only)

If unset, CHPL_COMM defaults to none in most cases. On a Cray system it defaults to gasnet except when using a pre-built module on a Cray XC or XE™ system, where it defaults to ugni. See Multilocale Chapel Execution for more information on executing Chapel programs using multiple locales. See also Using Chapel on Cray Systems for more information about Cray-specific runtime layers.

CHPL_MEM

Optionally, the CHPL_MEM environment variable can be used to select a memory management layer. Current options are:

Value Description
cstdlib use the standard C malloc/free commands
jemalloc use Jason Evan's memory allocator

If unset, CHPL_MEM defaults to jemalloc for most configurations. If the target platform is cygwin* it defaults to cstdlib

CHPL_LAUNCHER

Optionally, the CHPL_LAUNCHER environment variable can be used to select a launcher to get your program up and running. See Chapel Launchers for more information on this variable's default and possible settings.

CHPL_ATOMICS

Optionally, the CHPL_ATOMICS environment variable can be used to select an implementation for atomic operations in the runtime. Current options are:

Value Description
cstdlib implement Chapel atomics as a wrapper around C standard atomics (from C11)
intrinsics implement atomics using target compiler intrinsics (which typically map down to hardware capabilities)
locks implement atomics by using Chapel sync variables to protect normal operations

If unset, CHPL_ATOMICS defaults to intrinsics for most configurations. On some 32 bit platforms, or if the target compiler is pgi or cray-prgenv-pgi it defaults to locks. In a future release, cstdlib will become the default whenever possible. At this time, though, most C compilers either do not support standard atomics or have bugs in their implementation.

Note

gcc 4.8.1 added support for 64 bit atomics on 32 bit platforms. We default to intrinsics for 32 bit platforms when using the target compiler gnu with a recent enough version of gcc. For older versions or other target compilers we default to locks

See the Chapel Language Specification for more information about atomic operations in Chapel or Runtime Support for Atomics for more information about the runtime implementation.

CHPL_TIMERS

Optionally, the CHPL_TIMERS environment variable can be used to select an implementation for Chapel's timers. Current options are:

generic
use a gettimeofday()-based implementation

If unset, CHPL_TIMERS defaults to generic

CHPL_GMP

Optionally, the CHPL_GMP environment variable can select between no GMP support, using the GMP distributed with Chapel in third-party, or using a system GMP. Current options are:

Value Description
system assume GMP is already installed (#include gmp.h, -lgmp)
none do not build GMP support into the Chapel runtime
gmp use the GMP distribution bundled with Chapel in third-party

If unset, Chapel will attempt to build GMP using CHPL_TARGET_COMPILER (noting that the bundled version may not be supported by all compilers). Based on the outcome, Chapel will default to:

Value Description
gmp if the build was successful
system if unsuccessful and CHPL_TARGET_PLATFORM is cray-x*
none otherwise

Note

Note that the Chapel util/quickstart/setchplenv.* source scripts set CHPL_GMP to none while the util/setchplenv.* versions leave it unset, resulting in the behavior described just above.

CHPL_HWLOC

Optionally, the CHPL_HWLOC environment variable can select between no hwloc support or using the hwloc package distributed with Chapel in third-party. Note that hwloc is only used by the qthreads tasking layer, and does not need to be built for other tasking layers. Current options are:

Value Description
none do not build hwloc support into the Chapel runtime
hwloc use the hwloc distribution bundled with Chapel in third-party

If unset, CHPL_HWLOC defaults to hwloc if CHPL_TASKS is qthreads. In all other cases it defaults to none. In the unlikely event the bundled hwloc distribution does not build successfully, it should still be possible to use qthreads. To do this, manually set CHPL_HWLOC to none and rebuild (and please file a bug with the Chapel team.) Note that building without hwloc will have a negative impact on performance.

CHPL_REGEXP

Optionally, the CHPL_REGEXP environment variable can be used to enable regular expression operations as defined in Regexp. Current options are:

Value Description
re2 use the re2 distribution in third-party
none do not support regular expression operations

If unset, Chapel will attempt to build RE2 using CHPL_TARGET_COMPILER (noting that the bundled version may not be supported by all compilers). Based on the outcome, Chapel will default to:

Value Description
re2 if the build was successful
none otherwise

Note

Note that the Chapel util/quickstart/setchplenv.* source scripts set CHPL_REGEXP to 'none while the util/setchplenv.* versions leave it unset, resulting in the behavior described just above.

CHPL_AUX_FILESYS

Optionally, the CHPL_AUX_FILESYS environment variable can be used to request that runtime support for filesystems beyond the usual Linux one be present. Current options are:

Value Description
none only support traditional Linux filesystems
hdfs also support HDFS filesystems using Apache Hadoop libhdfs
hdfs3 support for HDFS filesystems using Pivotal libhdfs3
curl also support CURL as a filesystem interface

If unset, CHPL_AUX_FILESYS defaults to none.

See Auxiliary I/O Systems, HDFS, and Curl for more information about HDFS and CURL support.

CHPL_LLVM

Optionally, the CHPL_LLVM environment variable can be used to enable support for the LLVM back-end to the Chapel compiler (see LLVM Support) or to support extern blocks in Chapel code via the Clang compiler (see C Interoperability). Current options are:

Value Description
llvm use the llvm/clang distribution in third-party
none do not support llvm-/clang-related features

If unset, CHPL_LLVM defaults to llvm if you've already installed llvm in third-party and none otherwise.

CHPL_WIDE_POINTERS

Optionally, the CHPL_WIDE_POINTERS environment variable can be used to specify the wide pointer format for multilocale programs. Current options are:

Value Description
struct store wide pointers in structures which may span more than one word
nodeN ("N" a number, 2 <= N <= 60) store wide pointers in single words, with N bits used to store the node (top level locale) number and the rest containing the address on that node

CHPL_WIDE_POINTERS is used to select between two modes of operation. One is universally applicable; the other has restricted applicability but may reduce remote communication.

If unset, CHPL_WIDE_POINTERS defaults to struct. This setting works in all situations and in particular, it is compatible with all locale models including the hierarchical ones. The nodeN option does not work with hierarchical locale models and is only useful with the LLVM backend, which is currently experimental. However, when used, it allows LLVM to understand and optimize remote transfers, potentially reducing the amount of communication a program performs. See LLVM Support for more information about CHPL_WIDE_POINTERS=nodeN.

CHPL_UNWIND

Optionally, the CHPL_UNWIND environment variable can be used to select an unwind library for stack tracing. Current options are:

Value Description
libunwind use the libunwind bundled with Chapel in third-party
system assume libunwind is already installed on the system
none don't use an unwind library, disabling stack tracing

If unset, CHPL_UNWIND defaults to none

Compiler Command Line Option Defaults

Most of the compiler's command line options support setting a default value for the option via an environment variable. To see a list of the environment variables that support each option, run the compiler with the --help-env flag. For boolean flags and toggles, setting the environment variable to any value selects that flag.

Chapel Configuration File

The Chapel configuration file is a file named either chplconfig or .chplconfig that can store overrides of the inferred environment variables listed as a result of executing printchplenv.

Syntax

Below are the valid forms of syntax for Chapel configuration files. All other usages will result in a syntax error.

Definitions

Users can define variables with the following format:

CHPL_ENV=value

Above, the default value of CHPL_ENV will be overridden to be value. All white space is stripped away from definitions.

Ignored Lines

Any lines containing nothing or only white space will be ignored. Comments, which are denoted by the # character, similar to bash or python, are also ignored.

Example

Below is an example of a Chapel configuration file with comments:

# ~/.chplconfig

# Default to multi-locale
CHPL_COMM=gasnet

CHPL_TASKS=qthreads # Use Qthreads

# System GMP is available on these machines
CHPL_GMP=system

Generating Configuration Files

The format of the printchplenv --overrides and printchplenv --simple commands is compatible with Chapel configuration files.

The printchplenv --overrides flag can be used to print the variables currently overridden by either environment variables or Chapel configuration file.

A user can dump their current overrides into a Chapel configuration file:

printchplenv --overrides > ~/.chplconfig

The printchplenv --simple flag can be used to print all the variables of the current configuration.

A user can dump their current configuration into a Chapel configuration file as well:

printchplenv --simple > ~/.chplconfig

Search Paths and File Names

Though you can put your Chapel configuration file anywhere by setting the $CHPL_CONFIG environment variable to its enclosing directory, you can also place it in your $HOME or $CHPL_HOME directory and Chapel will be able to find it.

The search priority for Chapel configuration files is as follows:

  1. $CHPL_CONFIG
  2. $HOME (~/)
  3. $CHPL_HOME

When both a chplconfig and .chplconfig are present, the visible chplconfig will be prioritized.

Only a single chplconfig file will be used. That is, as soon as a valid Chapel configuration file is found, the definitions of that file are used.

Note

The $CHPL_CONFIG variable is the path to the enclosing directory - not the full path including chplconfig itself.

Variable Priority

Variable precedence goes in the following order:

  1. Explicit compiler flags: chpl --env=value
  2. Environment variables: CHPL_ENV=value
  3. Chapel configuration file: ~/.chplconfig
  4. Inferred environment variables: printchplenv