chpl¶

SYNOPSIS¶

chpl [-O] [--no-checks] [--fast]

[-g] [--savec directory]
[-M directory...] [--main-module mod]
[-o outfile] [options] source-files...

DESCRIPTION¶

The chpl command invokes the Chapel compiler. chpl converts one or more Chapel source files into an executable. It does this by compiling Chapel code to C99 code and then invoking the target platform's C compiler to create the executable. However, most users will not need to be aware of the use of C as an intermediate format during compilation.

SOURCE FILES¶

Chapel recognizes four source file types: .chpl, .c, .h, and .o.

foo.chpl

Chapel sources are compiled by the Chapel compiler into C intermediate code, which is then passed to the target compiler to be compiled into object code.

foo.c

C source files are passed directly to the target C compiler.

foo.h

C header files are included in the generated C code.

foo.o

Object files are passed directly to the target linker.

OPTIONS¶

Module Processing Options

--[no-]count-tokens

Prints the total number of static lexical tokens in the Chapel code files named on the command line.

--main-module <module>

For programs that supply multiple possible entry points (main() functions or module initializers that can serve as an entry point), this option can be used to specify which module should serve as the starting point for program execution.

-M, --module-dir <directory>

Add the specified directory to the module search path. The module search path is used to satisfy module 'use' statements. In the current implementation, the compiler tries to locate unresolved modules by searching for a filename whose name matches that of the module. For example, if the user program contains 'use foo' and the .chpl files listed by the programmer on the compiler's command line do not define a module named 'foo', the compiler will search for files named 'foo.chpl' in the module search path. The complete path that will be searched can be displayed using the --print-search-dirs flag and is composed of (1) the directories containing the .chpl files that were specified on the compiler command-line (in left-to-right order), (2) all directories specified by -M flags (in left-to-right order), (3) all directories specified by the $CHPL_MODULE_PATH environment variable (colon-separated directories), (4) the compiler's standard module search path.

--[no-]print-code-size

Prints out the size of the Chapel code files named on the command line in great detail: For each code file, first the code is echoed back to the screen, prefixing each line with the number of lexical tokens it contains, or *C* if the line only contains comments, or *B* if the line is blank. Next, the total number of tokens for the file is printed. Then the number of lines is displayed, broken down into code lines, comment-only lines, and blank lines. Then the maximum and average number of tokens per line is displayed. Finally, a histogram of the number of tokens per line is shown. After this information is printed for each file, a grand total of the number of tokens across all the files is displayed.

--print-module-files

Prints the Chapel module source files parsed by the Chapel compiler.

--[no-]print-search-dirs

Print the module search path used to resolve module for further details.

Parallelism Control Options

--[no-]local

Compile code for single/[multi-] locale execution, changing on blocks to normal blocks, evaluating the locale expression for side effects, and optimizing away all remote references in the code. When $CHPL_COMM is set to "none", --local is the default; otherwise --no-local is the default.

Optimization Control Options

--baseline

Turns off all optimizations in the Chapel compiler and generates naive C code with many temporaries.

--cache-remote

Enables the cache for remote data. This cache can improve communication performance for some programs by adding aggregation, write behind, and read ahead. This cache is not enabled by any other optimization options such as --fast.

--conditional-dynamic-dispatch-limit

When greater than zero, this limit controls when the compiler will generate code to handle dynamic dispatch with conditional statements. If the number of possible method calls is less than or equal to this limit, a (possibly nested) conditional statement will be used for dynamic dispatch instead of the virtual method table. The default is zero.

--[no-]copy-propagation

Enable [disable] copy propagation.

--[no-]dead-code-elimination

Enable [disable] dead code elimination.

--fast

Turns off all runtime checks using --no-checks, turns on -O and --specialize.

--[no-]fast-followers

Enable [disable] the fast follower optimization in which fast implementations of followers will be invoked for specific leaders.

--[no-]ieee-float

Disable [enable] optimizations that may affect IEEE floating point conformance. The default is whatever level of optimization/IEEE floating point support your C compiler provides at the optimization level provided by 'chpl'.

--[no-]loop-invariant-code-motion

Enable [disable] the optimization that moves loop invariant code from loop runs into the loop's "pre-header." By default invariant code is moved. This is currently a rather conservative pass in the sense that it may not identify all code that is truly invariant.

--[no-]ignore-local-classes

Disable [enable] local classes

--[no-]inline

Enable [disable] function inlining.

--[no-]inline-iterators

Enable [disable] iterator inlining. When possible, the compiler optimizes the invocation of an iterator in a loop header by inlining the iterator's definition around the loop body.

--[no-]live-analysis

Enable [disable] live variable analysis, which is currently only used to optimize iterators that are not inlined.

--[no-]optimize-array-indexing

Enable [disable] an optimization that removes an extra multiply in array indexing when it's provably unnecessary. By default this is enabled.

--[no-]optimize-loop-iterators

Enable [disable] optimizations to aggressively optimize iterators that are defined in terms of a single loop. By default this is enabled.

--[no-]vectorize

Enable [disable] generating vectorization hints for the target compiler. If enabled, hints will always be generated, but the effects on performance (and in some cases correctness) will vary based on the target compiler.

--[no-]optimize-on-clauses

Enable [disable] optimization of on clauses in which qualifying on statements may be optimized in the runtime if supported by the $CHPL_COMM layer.

--optimize-on-clause-limit

Limit on the function call depth to allow for on clause optimization. The default value is 20.

--[no-]privatization

Enable [disable] privatization of distributed arrays and domains if the distribution supports it.

--[no-]remove-copy-calls

Enable [disable] removal of copy calls (including calls to what amounts to a copy constructor for records) that ensure Chapel semantics but which can often be optimized away.

--[no-]remote-value-forwarding

Enable [disable] remote value forwarding of read-only values to remote threads if reading them early does not violate program semantics.

--[no-]scalar-replacement

Enable [disable] scalar replacement of records and classes for some compiler-generated data structures that support language features such as tuples and iterators.

--scalar-replace-limit

Limit on the size of tuples being replaced during scalar replacement. The default value is 8.

--[no-]tuple-copy-opt

Enable [disable] the tuple copy optimization in which whole tuple copies of homogeneous tuples are replaced with explicit assignment of each tuple component.

--tuple-copy-limit

Limit on the size of tuples considered for the tuple copy optimization. The default value is 8.

--[no-]use-noinit

Enable [disable] ability to skip default initialization through the keyword noinit

Run-time Semantic Check Options

--no-checks

Turns off all of the run-time checks in this section of the man page. Currently, it is typically necessary to use this flag (or --fast, which implies --no-checks) to achieve performance competitive with hand-coded C or Fortran.

--[no-]bounds-checks

Enable [disable] run-time bounds checking, e.g. during slicing and array indexing.

--[no-]formal-domain-checks

Enable [disable] run-time checks to ensure that an actual array argument's domain matches its formal array argument's domain in terms of (a) describing the same index set and (b) having an equivalent domain map (if the formal domain explicitly specifies a domain map).

--[no-]local-checks

Enable [disable] run-time checking of the locality of references within local blocks.

--[no-]nil-checks

Enable [disable] run-time checking for accessing nil object references.

--[no-]stack-checks

Enable [disable] run-time checking for stack overflow.

--[no-]cast-checks

Enable [disable] run-time checks in safeCast calls for casts that wouldn't preserve the logical value being cast.

C Code Generation Options

--[no-]codegen

Enable [disable] generating C code and the binary executable. Disabling code generation is useful to reduce compilation time, for example, when only Chapel compiler warnings/errors are of interest.

--[no-]cpp-lines

Causes the compiler to emit cpp #line directives into the generated code in order to help map generated C code back to the Chapel source code that it implements. The [no-] version of this flag turns this feature off.

--max-c-ident-len

Limits the length of identifiers in the generated code, except when set to 0. The default is 0, except when $CHPL_TARGET_COMPILER indicates a PGI compiler (pgi or cray-prgenv-pgi), in which case the default is 1020.

--[no-]munge-user-idents

By default, chpl munges all user identifiers in the generated C code in order to minimize the chances of conflict with an identifier or keyword in C (in the current implementation, this is done by appending '_chpl' to the identifier). This flag provides the ability to disable this munging. Note that whichever mode, the flag is in, chpl may perform additional munging in order to implement Chapel semantics in C, or for other reasons.

--savec <dir>

Saves the compiler-generated C code in the specified directory, creating the directory if it does not already exist. This option may overwrite existing files in the directory.

C Code Compilation Options

--ccflags <flags>

Add the specified flags to the C compiler command line when compiling the generated code. Multiple --ccflags options can be provided and in that case the combination of the flags will be forwarded to the C compiler.

-g, --[no-]debug

Causes the generated C code to be compiled with debugging turned on. If you are trying to debug a Chapel program, this flag is virtually essential along with the --savec flag. This flag also turns on the --cpp-lines option unless compiling as a developer (for example, via --devel).

--dynamic

Use dynamic linking when generating the final binary. If neither --dynamic or --static are specified, use the backend compiler's default.

-I, --hdr-search-path <dir>

Add dir to the back-end C compiler's search path for header files.

--ldflags <flags>

Add the specified flags to the C compiler link line when linking the generated code. Multiple --ldflags options can be provided and in that case the combination of the flags will be forwarded to the C compiler.

-l, --lib-linkage <library>

Specify a C library to link in on the C compiler command line.

-L, --lib-search-path <dir>

Specify a C library search path on the C compiler command line.

-O, --[no-]optimize

Causes the generated C code to be compiled with [without] optimizations turned on. The specific set of flags used by this option is platform-dependent; use the --print-commands option to view the C compiler command used. If you would like additional flags to be used with the C compiler command, use the --ccflags option.

--[no-]specialize

Causes the generated C code to be compiled with flags that specialize the executable to the architecture that is defined by CHPL_TARGET_ARCH. The effects of this flag will vary based on choice of back-end compiler and the value of CHPL_TARGET_ARCH.

-o, --output <filename>

Specify the name of the compiler-generated executable (defaults to a.out if unspecified).

--static

Use static linking when generating the final binary. If neither --static or --dynamic are specified, use the backend compiler's default.

LLVM Code Generation Options

--[no-]llvm

Use LLVM as the code generation target rather than C. See $CHPL_HOME/doc/technotes/llvm.rst for details.

--[no-]llvm-wide-opt

Enable [disable] LLVM wide pointer communication optimizations. This option requires --llvm and packed wide pointers. Packed wide pointers are enabled by setting CHPL_WIDE_POINTERS = node16. You must also supply --fast to enable wide pointer optimizations. This flag allows existing LLVM optimizations to work with wide pointers - for example, they might be able to hoist a 'get' out of a loop. See $CHPL_HOME/doc/technotes/llvm.rst for details.

Compilation Trace Options

--[no-]print-commands

Prints the system commands that the compiler executes in order to compile the Chapel program.

--[no-]print-passes

Prints the compiler passes during compilation and the amount of wall clock time required for the pass. After compilation is complete two tables are produced that provide more detail of how time is spent in each pass (compiling, verifying, and memory management) and the percentage of the total time that is attributed to each pass. The first table is sorted by pass and the second table is sorted by the time for the pass in descending order.

--print-passes-file <filename>

Saves the compiler passes and the amount of wall clock time required for the pass to <filename>. An error is displayed if the file cannot be opened but no recovery attempt is made.

Miscellaneous Options

--[no-]devel

Puts the compiler into [out of] developer mode, which takes off some of the safety belts, changes default behaviors, and exposes additional undocumented command-line options. Use at your own risk and direct any questions to the Chapel team.

--explain-call <call>[:<module>][:<line>]

Helps explain the function resolution process for the named function by printing out the visible and candidate functions. Specifying a module name and/or line number can focus the explanation to those calls within a specific module or at a particular line number.

--explain-instantiation <function|type>[:<module>][:<line>]

Lists all of the instantiations of a function or type. The location of one of possibly many points of instantiation is shown. Specifying a module name and/or line number can focus the explanation to those calls within a specific module or at a particular line number.

--[no-]explain-verbose

In combination with explain-call or explain-instantiation, causes the compiler to output more debug information related to disambiguation.

--instantiate-max <max>

In order to avoid infinite loops when instantiating generic functions, the compiler limits the number of times a single function can be instantiated. This flag raises that maximum in the event that a legal instantiation is being pruned too aggressively.

--[no-]print-callstack-on-error

Accompany certain error and warning messages with the Chapel call stack that the compiler was working on when it reached the error or warning location. This is useful when the underlying cause of the issue is in one of the callers.

-s, --set <config param>[=<value>]

Overrides the default value of a configuration parameter in the code. For boolean configuration variables, the value can be omitted, causing the default value to be toggled.

--[no-]task-tracking

Enable [disable] the Chapel-implemented task tracking table that supports the execution-time -b / -t flags. This option is currently only useful when $CHPL_TASKS is set or inferred to 'fifo' and adds compilation-time overhead when it will not be used, so is off by default.

--[no-]warn-const-loops

Enable [disable] warnings for 'while' loops whose condition is a 'const' variable, because such a loop condition is likely unintended. 'While' loops with 'param' conditions do not trigger this warning.

--[no-]warn-special

Enable [disable] all special compiler warnings issued due to syntax and other language changes. Currently, these include --[no-]warn-domain-literal and --[no-]warn-tuple-iteration.

--[no-]warn-domain-literal

Enable [disable] compiler warnings regarding the potential use of the old-style domain literal syntax (e.g. [1..2, 3..4]). All array literals with range elements will result in warnings.

--[no-]warn-tuple-iteration

Enable [disable] compiler warnings regarding the potential use of old-style zippering syntax. All uses of tuple iteration will produce warnings.

--[no-]warnings

Enable [disable] the printing of compiler warnings. Defaults to printing warnings.

Compiler Configuration Options

--home <path>

Specify the location of the Chapel installation directory. This flag corresponds with and overrides the $CHPL_HOME environment variable.

--atomics <atomics-impl>

Specify the implementation to use for Chapel's atomic variables. This flag corresponds with and overrides the $CHPL_ATOMICS environment variable. (defaults to a best guess based on $CHPL_TARGET_COMPILER, $CHPL_TARGET_PLATFORM, and $CHPL_COMM)

--network-atomics <network>

Specify the network atomics implementation for all atomic variables. This flag corresponds with and overrides the $CHPL_NETWORK_ATOMICS environment variable (defaults to best guess based on $CHPL_COMM).

--aux-filesys <aio-system>

Specify runtime support for additional file systems. This flag corresponds with and overrides the $CHPL_AUX_FILESYS environment variable (defaults to 'none').

--comm <comm-impl>

Specify the communication implementation to use for inter-locale data transfers. This flag corresponds with and overrides the $CHPL_COMM environment variable (defaults to 'none').

--comm-substrate <conduit>

Specify the communication conduit for the communication implementation. This flag corresponds with and overrides the $CHPL_COMM_SUBSTRATE environment variable (defaults to best guess based on $CHPL_TARGET_PLATFORM).

--gasnet-segment <segment>

Specify memory segment to use with GASNet. This flag corresponds with and overrides the $CHPL_GASNET_SEGMENT environment variable. (defaults to best guess based on $CHPL_COMM_SUBSTRATE).

--gmp <gmp-version>

Specify the GMP library implementation to be used by the GMP module. This flag corresponds with and overrides the $CHPL_GMP environment variable (defaults to best guess based on $CHPL_TARGET_PLATFORM and whether you've built the included GMP library in the third-party directory).

--hwloc <hwloc-impl>

Specify whether or not to use the hwloc library. This flag corresponds with and overrides the $CHPL_HWLOC environment variable (defaults to a best guess based on whether you've built the included library in the third-party hwloc directory).

--launcher <launcher-system>

Specify the launcher, if any, used to start job execution. This flag corresponds with and overrides the $CHPL_LAUNCHER environment variable (defaults to a best guess based on $CHPL_COMM and $CHPL_TARGET_PLATFORM).

--locale-model <locale-model>

Specify the locale model to use for describing your locale architecture. This flag corresponds with and overrides the $CHPL_LOCALE_MODEL environment variable (defaults to 'flat').

--make <make utility>

Specify the GNU compatible make utility. This flag corresponds with and overrides the $CHPL_MAKE environment variable (defaults to a best guess based on $CHPL_HOST_PLATFORM).

--mem <mem-impl>

Specify the memory allocator used for dynamic memory management. This flag corresponds with and overrides the $CHPL_MEM environment variable (defaults to a best guess based on $CHPL_COMM).

--regexp <regexp>

Specify the regular expression library to use. This flag corresponds with and overrides the $CHPL_REGEXP environment variable (defaults to 'none' or 're2' if you've installed the re2 package in the third-party directory).

--target-arch <architecture>

Specify the architecture that the compiled executable will be specialized to when --specialize is enabled. This flag corresponds with and overrides the $CHPL_TARGET_ARCH environment variable (defaults to a best guess based on $CHPL_COMM, $CHPL_TARGET_COMPILER, and $CHPL_TARGET_PLATFORM).

--target-compiler <compiler>

Specify the compiler suite that should be used to build the generated C code for a Chapel program and the Chapel runtime. This flag corresponds with and overrides the $CHPL_TARGET_COMPILER environment variable (defaults to a best guess based on $CHPL_HOST_PLATFORM, $CHPL_TARGET_PLATFORM, and $CHPL_HOST_COMPILER).

--target-platform <platform>

Specify the platform on which the target executable is to be run for the purposes of cross-compiling. This flag corresponds with and overrides the $CHPL_TARGET_PLATFORM environment variable (defaults to $CHPL_HOST_PLATFORM).

--tasks <task-impl>

Specify the tasking layer to use for implementing tasks. This flag corresponds with and overrides the $CHPL_TASKS environment variable (defaults to a best guess based on $CHPL_TARGET_PLATFORM).

--timers <timer-impl>

Specify a timer implementation to be used by the Time module. This flag corresponds with and overrides the $CHPL_TIMERS environment variable (defaults to 'generic').

--wide-pointers <format>

Specify the wide pointer format format. This flag corresponds with and overrides the $CHPL_WIDE_POINTERS environment variable (defaults to 'struct').

Compiler Information Options

--copyright

Print the compiler's copyright information.

-h, --help

Print a list of the command line options, indicating the arguments that they expect and a brief summary of their purpose.

--help-env

Print the command line option help message, listing the environment variable equivalent for each flag (see ENVIRONMENT) and its current value.

--help-settings

Print the command line option help message, listing the current setting of each option as specified by environment variables and other flags on the command line.

--license

Print the compiler's license information.

--version

Print the version number of the compiler.

ENVIRONMENT¶

Most compiler command-line options have an environment variable that can be used to specify a default value. Use the --help-env option to list the environment variable equivalent for each option. Command-line options will always override environment variable settings in the event of a conflict, except for ccflags and ldflags, which stack.

If the environment variable equivalent is set to empty, it is considered unset. This does not apply to options expecting a string or a path.

For options that can be used with or without the leading --no (they are shown with "[no-]" in the help text), the environment variable equivalent, when set to a non-empty string, has the following effect. When the first character of the string is one of:

Y y T t 1 - same as passing the option without --no,

N n F f 0 - same as passing the option with --no,

anything else - generates an error.

For the other options that enable, disable or toggle some feature, any non-empty value of the environment variable equivalent has the same effect as passing that option once.

BUGS¶

See $CHPL_HOME/STATUS for a list of known bugs and $CHPL_HOME/doc/bugs.rst for instructions on reporting bugs.

AUTHORS¶

See $CHPL_HOME/CONTRIBUTORS.md for a list of contributors to Chapel.