The Chapel Language

Chapel is an emerging programming language designed for productive parallel computing at scale. Chapel's design and implementation have been undertaken with portability in mind, permitting Chapel to run on multicore desktops and laptops, commodity clusters, and the cloud, in addition to the high-end supercomputers for which it was designed. Chapel's design and development are being led by Cray Inc. in collaboration with academia, computing centers, and industry. See chapel.cray.com for more information.

This is the 1.12.0 release of the Chapel compiler, intended to give potential users a look at what we're doing and the opportunity to provide us with feedback. See the LICENSE file for the release's licensing terms.

Quick Start Instructions

The following instructions are designed to get you up and running with Chapel with a minimum of fuss. Note that building and using Chapel in this mode disables enhanced runtime options and optional language capabilities in the interest of a simple and clean build.

0. See prereqs.rst for more information about packages you might need to have installed for Chapel to work. Download a Chapel source release from download.html if you haven't already.

1. Make sure that your shell is in the directory containing this README.rst file. For example:

   cd ~/chapel-1.12.0

2. Set up your environment to use Chapel in "Quick Start" mode.

   You must be in the top-level Chapel directory for the command scripts below to work properly. Note that there is no requirement to use these scripts long-term, they are merely designed to get new users up and running quickly. See chplenv.rst for a complete description of Chapel's environment variables and their options.

   If you use a shell other than the ones listed below and are able to create an equivalent util/quickstart/setchplenv.* script for it, please consider contributing a copy of it back to the project for inclusion in the next release.

If you use:	then type:
a bash-compatible shell (bash/zsh)	source util/quickstart/setchplenv.bash
a csh-compatible shell (csh/tcsh)	source util/quickstart/setchplenv.csh
the fish shell (fish)	. util/quickstart/setchplenv.fish
the Bourne shell (sh)	. util/quickstart/setchplenv.sh

3. Build the compiler and runtime libraries using:

   gmake

   or if your default make is GNU make compatible (as on Mac OS X or Cygwin), use:

   make

   Parallel build execution (e.g. gmake -j) is supported.

4. csh/tcsh users only: Update your shell's path cache using:

   rehash

5. Optionally, check that your Chapel installation is working correctly:

   gmake check

   or:

   make check

6. Compile an example program using:

   chpl -o hello examples/hello.chpl

7. Execute the resulting executable:

   ./hello

8. Experiment with Chapel in Quick Start mode to your heart's content.

   Once you are comfortable with Chapel and interested in using a full-featured version in the preferred configuration:

   1. Open up a new shell to avoid inheriting the previous environment settings.
   2. Repeat steps 1-7 above, but in Step 2, use util/setchplenv.* instead of util/quickstart/setchplenv.*

   This will set up your environment to use Chapel in the preferred configuration. Making this configuration will involve building one or more third-party packages which will increase the overall build time. If you run into any portability issues, please let us know at chapel_info@cray.com.

9. If you plan to do performance studies of Chapel programs, be sure to (a) use the full-featured version and (b) read the PERFORMANCE file in this directory to avoid common pitfalls.

10. All of the instructions above describe how to run Chapel programs in a single-locale / shared-memory mode. To run on multiple compute nodes, please refer to multilocale.rst.

What's next?

For more detailed information about:	refer to:
changes since the last release	CHANGES
implementation status	STATUS
performance status	PERFORMANCE
Chapel's file and directory structure	README.files
prerequisites for using this release	prereqs.rst
setting Chapel environment variables	chplenv.rst
building the compiler	building.rst
using the compiler	compiling.rst
executing Chapel programs	executing.rst
debugging Chapel programs	debugging.rst
reporting bugs	bugs.rst
Chapel modes for emacs and vim	etc/README.md
example Chapel programs	examples/README
a quick reference for Chapel syntax	doc/quickReference.pdf
the Chapel language specification	doc/chapelLanguageSpec.pdf
other Chapel Documentation	chapel.cray.com/docs
third-party software that we use	third-party/README

To use Chapel on a specific platform:	refer to:
a Cray system	cray.rst
Cygwin over Windows	cygwin.rst