Chapel Quickstart Instructions¶

These instructions are designed to help you get started with a source distribution of the latest Chapel release.

In the following instructions, note that building and using Chapel as described in steps 2-5 disables optional and advanced features in the interest of getting you a clean build as quickly as possible. Later sections explain how to re-build in the preferred configuration and how to enable more features, such as distributed memory execution.

See prereqs.rst for more information about system tools and packages you may need to have installed to build and run Chapel.
If you don't already have Chapel 1.19, see https://chapel-lang.org/download.html .
If you are using a source release, build Chapel in a quickstart configuration. The quickstart script used below is designed to help you get started with Chapel. After that, you may want to switch to a more full-featured configuration. See using-a-more-full-featured-chapel below.
1. Expand the source release if you haven't already:
```
tar xzf chapel-1.19.0.tar.gz
```
2. Make sure that your shell is in the directory containing QUICKSTART.rst, for example:
```
cd chapel-1.19.0
```
3. Set up your environment for Chapel's Quickstart mode. If you are using a shell other than bash, see quickstart-with-other-shells below.
```
source util/quickstart/setchplenv.bash
```
4. Use GNU make to build Chapel. On some systems, you will have to use gmake. See building.rst for more information about building Chapel.
```
make
```
5. Optionally, check that your Chapel build is working correctly
```
make check
```
Compile an example program:
```
chpl -o hello examples/hello.chpl
```
Run the resulting executable:
```
./hello
```
Experiment with Chapel in this Quickstart mode to your heart's content. Once you are comfortable with Chapel and interested in using a full-featured version in the preferred configuration, see the next section.

Using a More Full-Featured Chapel¶

To use Chapel in a more full-featured and preferred configuration, you will need to rebuild Chapel from source in a different configuration.

Open up a new shell to avoid inheriting the previous environment settings.
Repeat steps 2-5 above, but in Step 2, source util/setchplenv.bash instead of util/quickstart/setchplenv.bash. This will set up your environment to use Chapel in the preferred configuration. Building this configuration involves compiling third-party packages, which will increase the overall build time. If you run into any portability issues, please let us know via bugs.rst.
```
# Set environment variables to preferred configuration
source util/setchplenv.bash

# re-build Chapel
make

# make check is available but optional
make check

# compile a sample program
chpl -o hello examples/hello.chpl

# run the sample program
./hello
```
At this point, you can choose to continue using setchplenv.bash or use another method to configure Chapel. In particular, you might use a chplconfig file or set environment variables your in dot files or your own script.

See chplenv.rst for a complete description of Chapel's configuration variables, what they mean, and how they can be set.

Using Chapel in Multi-Locale Mode¶

All of the instructions above describe how to run Chapel programs in a single-locale (shared-memory) mode. To run using multiple locales (distributed memory), please refer to multilocale.rst.

Performance¶

If you plan to do performance studies of Chapel programs, be sure to use the full-featured version from using-a-more-full-featured-chapel above and read $CHPL_HOME/PERFORMANCE.md to avoid common pitfalls.

Quickstart with Other Shells¶

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`

What's next?¶

For more information about Chapel, refer to the following resources:

Online documentation:	chapel-lang.org/docs
Platform-specific notes:	../platforms
Example Chapel programs:	`$CHPL_HOME/examples/README`
Setting Chapel env vars:	chplenv.rst
Building the compiler:	building.rst
Compiling Chapel programs:	compiling.rst
Executing Chapel programs:	executing.rst
Debugging Chapel programs:	debugging.rst
Reporting bugs:	bugs.rst
Performance status:	`$CHPL_HOME/PERFORMANCE.md`
Chapel modes for emacs/vim:	`$CHPL_HOME/highlight/README.md`
Chapel's file/dir structure:	`$CHPL_HOME/README.files`
Changes since last release:	`$CHPL_HOME/CHANGES.md`