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.
Contents
Recommended Settings¶
CHPL_HOME¶
Set the
CHPL_HOME
environment variable to point to the location of the chapel/ directory that was created when you unpacked the release. For example:export CHPL_HOME=~/chapel-1.16.0Note
This, and all other examples in the Chapel documentation, assumes you're using the
bash
shell. If usingcsh
ortcsh
, mentally changeexport FOO=BAR
tosetenv FOO BAR
. If using some other shell, make the appropriate adjustment.
CHPL_HOST_PLATFORM¶
Set the
CHPL_HOST_PLATFORM
environment variable to represent the platform on which you're working. For standard UNIX workstations, this can be done by running the$CHPL_HOME/util/chplenv/chpl_platform.py
script. For example:export CHPL_HOST_PLATFORM=`$CHPL_HOME/util/chplenv/chpl_platform.py`For other platforms that appear very similar to a UNIX workstation from the shell prompt (e.g., a Cray XK™), the value may need to be set explicitly. The strings for our currently-supported host platforms are as follows:
Value Description cygwin32 x86 Cygwin (Windows) platforms cygwin64 x86_64 Cygwin (Windows) platforms darwin Macintosh OS X platforms linux32 32-bit Linux platforms linux64 64-bit Linux platforms marenostrum BSC's MareNostrum platform netbsd32 32-bit NetBSD platforms netbsd64 64-bit NetBSD platforms pwr5 IBM Power5 SMP cluster pwr6 IBM Power6 SMP cluster sunos SunOS platforms cray-cs Cray CS™ cray-xc Cray XC™ cray-xe Cray XE™ cray-xk Cray XK™ Platform-specific documentation is available for most of these platforms in Platform-Specific Notes.
The Chapel Makefiles and sources are designed to work for any UNIX-compatible environment that supports a GNU-compatible make utility. The list above represents the set of platforms that we have access to and can test easily. We are interested in making our code framework portable to other platforms -- if you are using Chapel on a platform other than the ones listed above, please refer to Platform-specific Settings for ways to set up a Makefile for this platform and/or contact us at: chapel_info@cray.com
Optional Settings¶
CHPL_TARGET_PLATFORM¶
If you are cross-compiling for a platform other than your
$CHPL_HOST_PLATFORM
, set theCHPL_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/orCHPL_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 onCHPL_HOST_PLATFORM
.CHPL_TARGET_COMPILER
is the compiler used to build the runtime libraries and generated code forCHPL_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 correspondingCHPL_*_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 notcray-x*
,CHPL_TARGET_COMPILER
will default to the same value asCHPL_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 eitherunknown
ornone
. 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 inCHPL_TARGET_ARCH
. One of thecraype-*
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
iscray
,pgi
, oribm
,CHPL_TARGET_ARCH
will be set tonone
and no specialization will occur.- If CHPL_COMM is set, no attempt to set a useful value will be made,
CHPL_TARGET_ARCH
will beunknown
.- If CHPL_TARGET_PLATFORM is
darwin
,linux*
, orcygwin*
CHPL_TARGET_ARCH
will benative
, 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 knl a processor-specific locale model for the self-hosted Xeon Phi (Knight's Landing) which includes NUMA support and access to the tightly-coupled high-bandwidth memory If unset,
CHPL_LOCALE_MODEL
defaults toflat
.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 If
CHPL_TASKS
is not set it defaults toqthreads
in all cases except for a few specific configurations in which it defaults tofifo
:
- target platform is
cygwin*
- target platform is
netbsd*
Note
Note that the Chapel
util/quickstart/setchplenv.*
source scripts setCHPL_TASKS
tofifo
to reduce build-time and third-party dependences, while theutil/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.
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 communication layer If unset,
CHPL_COMM
defaults tonone
in most cases. On Cray XE and XC systems it defaults tougni
. On Cray CS systems it defaults togasnet
. See Multilocale Chapel Execution for more information on executing Chapel programs using multiple locales. See 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 tojemalloc
for most configurations. If the target platform iscygwin*
it defaults tocstdlib
Note
Certain
CHPL_COMM
settings (e.g. ugni and gasnet segment fast/large) register the heap to improve communication performance. Registering the heap requires special allocator support that not all allocators provide. Currently onlyjemalloc
is capable of supporting configurations that require a registered heap.
CHPL_LAUNCHER¶
Optionally, theCHPL_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 ispgi
orcray-prgenv-pgi
it defaults tolocks
. 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 compilergnu
with a recent enough version of gcc. For older versions or other target compilers we default tolocks
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 implementationIf unset,
CHPL_TIMERS
defaults togeneric
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 use a system install of GMP (#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 setCHPL_GMP
tonone
while theutil/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.
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 tohwloc
if CHPL_TASKS isqthreads
. In all other cases it defaults tonone
. In the unlikely event the bundled hwloc distribution does not build successfully, it should still be possible to use qthreads. To do this, manually setCHPL_HWLOC
tonone
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 inRegexp
. 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 setCHPL_REGEXP
to'none
while theutil/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 tonone
.See Auxiliary I/O Systems,
HDFS
, andCurl
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 system find a compatible LLVM in system libraries; note: the LLVM must be a version supported by Chapel none do not support llvm-/clang-related features If unset,
CHPL_LLVM
defaults tollvm
if you've already installed llvm in third-party andnone
otherwise.Chapel currently supports LLVM 3.7 through 4.0.
Note
We have had success with these commands to install LLVM 3.7 dependencies
# Fedora 25 dnf install llvm3.7 llvm3.7-devel llvm3.7-static zlib-static # Ubuntu 16.04 apt-get install llvm-3.7-dev llvm-3.7 clang-3.7 libclang-3.7-dev libedit-dev
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 tostruct
. This setting works in all situations and in particular, it is compatible with all locale models including the hierarchical ones. ThenodeN
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 aboutCHPL_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 tonone
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¶
To generate a configuration file, use printchplenv
or
./configure
.
When using printchplenv
, run it with --simple
or
--overrides
to get a format 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.
For example, to save the 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. For example:
printchplenv --simple > ~/.chplconfig
Alternatively, the ./configure
script will generate a chplconfig
file. See Installing Chapel.
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:
$CHPL_CONFIG
$HOME
(~/
)$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:
- Explicit compiler flags:
chpl --env=value
- Environment variables:
CHPL_ENV=value
- Chapel configuration file:
~/.chplconfig
- Inferred environment variables:
printchplenv