.. _man-chpl: chpl ==== .. confchpl.rst 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 ** 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. *Warning and Language Control Options* **\--[no-]permit-unhandled-module-errors** Normally, the compiler ensures that all errors are handled for code inside of a module declaration (unless the module overrides that behavior). This flag overrides this default, so that the compiler will compile code in a module that does not handle its errors. If any error comes up during execution, it will cause the program to halt. **\--[no-]warn-unstable** Enable [disable] warnings for code that has recently or will recently change in meaning due to language changes. **\--[no-]warnings** Enable [disable] the printing of compiler warnings. Defaults to printing warnings. **\--[no-]warn-unknown-attribute-toolname** [Don't] warn about attribute tool names that aren't recognized. Without this warning, attributes belonging to unknown tools will be silently ignored. The default is to warn about all unknown tool names. **\--using-attribute-toolname <**\ *toolname*\ **>** Provide a tool name whose use in an attribute will not trigger an "unknown tool name" warning. To provide multiple tool names, use one **\--using-attribute-toolname** flag per name. *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. **\--[no-]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. **\--[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-]optimize-forall-unordered-ops** Enable [disable] optimization of the last statement in forall statements to use unordered communication. This optimization works with runtime support for unordered operations with CHPL_COMM=ugni. **\--[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. **\--inline-iterators-yield-limit** Limit on the number of yield statements permitted in an inlined iterator. The default value is 10. **\--[no-]live-analysis** Enable [disable] live variable analysis, which is currently only used to optimize iterators that are not inlined. **\--[no-]optimize-range-iteration** Enable [disable] anonymous range iteration optimizations. This allows the compiler to avoid creating ranges when they are only used for iteration. 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-]remote-serialization** Enable [disable] serialization for globals and remote constants. **\--[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-]infer-local-fields** Enable [disable] analysis to infer local fields in classes and records (experimental) **\--[no-]auto-local-access** Enable [disable] an optimization applied to forall loops over domains in which accesses of the form of `A[i]` within the loop are transformed to use local accesses if the array `A` is aligned with the domain and `i` is the loop index variable. With this flag, the compiler does some static analysis and adds calls that can further analyze alignment dynamically during execution time. **\--[no-]dynamic-auto-local-access** Enable [disable] the dynamic portion of the analysis described in `\--[no-]auto-local-access`. This dynamic analysis can result in loop duplication that increases executable size and compilation time. There may also be execution time overheads independent of loop domain size. **\--[no-]auto-aggregation** Enable [disable] optimization of the last statement in forall statements to use aggregated communication. This optimization is disabled by default. *Run-time Semantic Check Options* **\--[no-]checks** Enable [disable] 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-]cast-checks** Enable [disable] run-time checks in safeCast calls for casts that wouldn't preserve the logical value being cast. **\--[no-]const-arg-checks** Enable [disable] const argument checks (only when --warn-unstable is also used) **\--[no-]div-by-zero-checks** Enable [disable] run-time checks in integer division and modulus operations to guard against dividing by zero. **\--[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. *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 ** 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 ** 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 ** Add the specified dir[ectories] to the back-end C compiler's search path for header files along with any directories in the CHPL\_INCLUDE\_PATH environment variable. Both the environment variable and this flag accept a colon-separated list of directories. **\--ldflags ** Add the specified flags to the back-end 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 ** Specify a C library to link to on the back-end C compiler command line. **-L, \--lib-search-path ** Add the specified dir[ectories] to the back-end C compiler's search path for libraries along with any directories in the CHPL\_LIB\_PATH environment variable. Both the environment variable and this flag accept a colon-separated list of directories. **-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\_CPU. The effects of this flag will vary based on choice of back-end compiler and the value of CHPL\_TARGET\_CPU. **-o, \--output ** Specify the name of the compiler-generated executable. Defaults to the filename of the main module (minus its `.chpl` extension), 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/rst/technotes/llvm.rst for details. **\--[no-]llvm-wide-opt** Enable [disable] LLVM wide pointer communication optimizations. This option requires CHPL_TARGET_COMPILER=llvm. 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/rst/technotes/llvm.rst for details. **\--mllvm