Building Chapel

To build the Chapel compiler, set up your environment as described in Setting up Your Environment for Chapel, cd to $CHPL_HOME (the root directory of your unpacked Chapel release), and run GNU make. This will build the compiler and runtime libraries for your current environment as indicated by running $CHPL_HOME/util/printchplenv --all.

On many systems, GNU make is available simply as make. On others, it is called gmake. To check whether make refers to GNU make on your system, run:

make -v

If the first line includes “GNU Make”, you have GNU Make. The rest of these instructions will assume make refers to GNU Make. If that’s not the case, you’ll need to replace make with gmake.

Now build the Chapel compiler:

cd $CHPL_HOME
make

Parallel builds such as make -j 6 are also supported.

If everything works as intended, you ought to see:

  1. each of the compiler source subdirectories being compiled

  2. the compiler binary getting linked and stored as:

    $CHPL_HOME/bin/$CHPL_HOST_PLATFORM-$CHPL_HOST_ARCH/chpl

  3. the runtime support libraries being compiled, archived, and stored in a configuration-specific subdirectory under:

    $CHPL_HOME/lib/$CHPL_TARGET_PLATFORM/.../

If you get an error or failure during the make process, double-check that you have the required prerequisites (see Chapel Prerequisites). If you do, please submit a bug report for the failure through Reporting Chapel Issues.

After a successful build, you should be able to run the compiler and display its help message using:

chpl --help

In which case, you are ready to move on to compiling with the Chapel compiler (see Compiling Chapel Programs). The next few sections provide more information about using Chapel across multiple sessions, installing Chapel, and supporting multiple Chapel configurations. Following that are sections describing Chapel’s Makefiles for advanced users or developers of Chapel.

Using Chapel in a Different Shell / Terminal / Session

Once you have built Chapel, you can use it in other sessions (new shells or terminals) as long as:

  1. the chpl compiler is in your $PATH

  2. your $CHPL_ environment variables are set or inferred to values that match a configuration you have already built

Typically, this is accomplished in one of the following ways:

  • by manually re-sourcing the setchplenv.* file that you used when building Chapel.

  • by editing your ‘dot files’ (e.g., .bashrc, bash_profile, or whatever your shell uses to start up each session) to explicitly set your path and $CHPL_ settings as desired, or to source the appropriate setchplenv.* script.

  • by creating a chplconfig file to store your preferred $CHPL_ settings (see Chapel Configuration Files for further details on creating a chplconfig file). Note, however, that some other standard technique is still required to ensure that chpl is in your path.

  • by installing Chapel to a specific location that is in your path using the instructions in the next section.

Installing Chapel

Chapel can be built and installed to a specific location as follows:

./configure  # use './configure --help' for specific options
make
make install

Running ./configure will save your current configuration of $CHPL_ settings into a chplconfig file. This chplconfig file will be installed wherever CHPL_HOME is. Running ./configure with the --prefix or --chpl-home options permits you to specify where and how Chapel should be installed during the make install step. Specifically:

  • --prefix=/dir/for/install/ causes the Chapel compiler, libraries, and supporting code to be installed into the directories:

    • /dir/for/install/bin

    • /dir/for/install/lib

    • /dir/for/install/share

    This technique is designed to install Chapel using a standard directory structure for the purposes of integrating it into a standard location that is already in your path, such as /usr/local/. Note that elevated privileges are likely to be required for any system-wide installation locations.

    Please note that for any prefix-installed version of Chapel, the meaning of $CHPL_HOME (e.g., as printed by compiler messages) is the path printed by chpl --print-chpl-home. This is typically /dir/for/install/share/chapel/x.yz where x.yz is the Chapel version that was installed.

  • --chpl-home=/dir/for/install copies key files and directories from the Chapel source tree into /dir/for/install, preserving Chapel’s traditional directory structure. As you might expect, the meaning of $CHPL_HOME for such installs is /dir/for/install.

Switching Between Multiple Configurations

A single installation of Chapel can simultaneously support multiple configuration options, such as target platforms or compilers, because all binary files and executables are stored in unique subdirectories as determined by the CHPL_ environment variables. However, note that each make command only builds the compiler and runtime for the current set of CHPL_ environment variables defined by—and inferred for—your environment. To build support for additional configurations, you will need to modify your CHPL_ environment variables and re-make.

Once you have built multiple configurations, you can switch between them either by setting your CHPL_ environment variables to the same values as when the configuration was built, or using the chpl compiler’s command-line options that correspond to the environment variables (see the ‘Compiler Configuration Options’ section of the chpl man page for details).

Makefile Targets

The Chapel sources are structured so that a GNU-compatible make utility can be used in any source directory to build the sources contained in that directory and its subdirectories. All of these Makefiles support the following targets:

Target

Action

(nothing) default all

Build the appropriate targets — e.g., objects files, libraries, executables

check

verify basic functionality of a Chapel build

clean

Remove the intermediate files for this configuration

cleanall

Remove the intermediate files for all configurations

clobber

Remove everything created by the Makefiles as well as chplconfig

install

Install Chapel to a previously configured location

Each target processes all subdirectories, then the current directory.

Makefile Options

The Chapel Makefiles have a few options that enable or disable optimization, debugging support, profiling, and back-end C compiler warnings. The variables are described below. Set the value to 1 to enable the feature or 0 to disable it (e.g., make DEBUG=1 OPTIMIZE=1 WARNINGS=0).

Option

Effect

ASSERTS

Enables correctness assertions in the compiler and runtime

DEBUG

Generate debug information (e.g., pass -g to the C compiler)

OPTIMIZE

Enable optimizations (e.g., pass -O3 to the C compiler)

PROFILE

Enable profiling support (e.g., pass -pg to C compiler)

WARNINGS

Enable more warnings and treat them as errors

Note that these settings only affect how the chpl compiler and its runtime libraries are built, as well as the third-party packages that they rely upon. In particular, building Chapel with DEBUG or OPTIMIZE set will not cause invocations of the resulting chpl compiler to automatically generate executables with debugging or optimizations enabled.

Controlling Build Output

Aside from the default build output, the Chapel compiler Makefile also supports two options to increase or decrease the verbosity of the build. These options can be set either on the command-line as arguments to make, or through the environment. To enable either option, set the variable to 1 (e.g., make VERBOSE=1 or export VERBOSE=1).

Option

Effect

VERBOSE

Print verbose CMake output and all commands executed by the Makefiles

QUIET

Print the minimum output from CMake (e.g., only errors, warnings)