|
| 1 | +# Introduction to Chapel |
| 2 | + |
| 3 | +[Chapel](https://chapel-lang.org/) is a programming language for productive parallel computing. This repository contains code from the [ChapelCon 2024](https://chapel-lang.org/ChapelCon24.html) Chapel tutorial. |
| 4 | + |
| 5 | +To get started with this template, you can either use [GitHub Codespaces](#using-a-codespace) or your own machine (via [Docker](#using-docker) or by [building from source](#building-chapel-from-source-on-your-machine)). |
| 6 | + |
| 7 | +The files in this repository correspond to files in the tutorial slide deck. |
| 8 | +They are listed with numerical prefixes (e.g., `01-heat-1D-serial.chpl`) |
| 9 | +that represent the order in which they appear in the slides. |
| 10 | + |
| 11 | +## Learning Resources |
| 12 | +To learn about Chapel beyond what's presented in the slides, consider the |
| 13 | +following resources: |
| 14 | + |
| 15 | +* For Chapel’s core features, check out the [Advent of Code](https://chapel-lang.org/blog/series/advent-of-code-2022/) blog series |
| 16 | +* For more information on Chapel’s various loops, including ‘forall’, check out the [Loops primer](https://chapel-lang.org/docs/primers/loops.html) |
| 17 | +* For details on Chapel's GPU support, see [Introduction to GPU Programming](https://chapel-lang.org/blog/posts/intro-to-gpus/) |
| 18 | + |
| 19 | +For a broader list of resources, check out the [Learning Chapel](https://chapel-lang.org/learning.html) page on the Chapel website. |
| 20 | + |
| 21 | +## Using a Codespace |
| 22 | + |
| 23 | +> :warning: Because Codespaces are a virtualized environment running on shared hardware with a modest core count, don't expect parallelism or performance observed here to be reflective of what a native installation of Chapel can achieve. |
| 24 | +
|
| 25 | +This repo includes a `devcontainer.json` file, making it usable from GitHub Codespaces. When viewing this repository from GitHub's UI, click __Use this template > Open in a codespace__ to get started. The codespace includes the Visual Studio Code extension for Chapel, and tools such as [`chpl-language-server`](https://chapel-lang.org/docs/main/tools/chpl-language-server/chpl-language-server.html) and [`chplcheck`](https://chapel-lang.org/docs/main/tools/chplcheck/chplcheck.html). |
| 26 | + |
| 27 | +In the Codespace, compile Chapel programs using the __Terminal__ tab by using the `chpl` compiler: |
| 28 | + |
| 29 | +```bash |
| 30 | +chpl 01-hello.chpl |
| 31 | +./01-hello |
| 32 | +``` |
| 33 | + |
| 34 | +### Simulating Multiple Nodes |
| 35 | +Although the Codespace is set to a single-locale (single-node) mode by default, you can simulate multiple nodes by setting the `CHPL_COMM` environment variable to `gasnet` when compiling. |
| 36 | + |
| 37 | +```bash |
| 38 | +# Compile a program that distributes computation to multiple nodes |
| 39 | +CHPL_COMM=gasnet chpl 01-hellopar.chpl |
| 40 | + |
| 41 | +# Run hello using two simulated nodes |
| 42 | +./01-hellopar -nl 2 |
| 43 | +``` |
| 44 | + |
| 45 | +To avoid having to include `CHPL_COMM` in each compilation command, you can |
| 46 | +`export` it: |
| 47 | + |
| 48 | +```bash |
| 49 | +export CHPL_COMM=gasnet |
| 50 | +chpl 01-hellopar.chpl |
| 51 | +./01-hellopar -nl 2 |
| 52 | +``` |
| 53 | + |
| 54 | +### Simulating GPU Support |
| 55 | +GitHub codespaces do not have GPUs available to them. However, Chapel |
| 56 | +provides a mode called ["CPU-as-device"](https://chapel-lang.org/docs/technotes/gpu.html#cpu-as-device-mode), |
| 57 | +which mocks GPU support by running GPU-eligible loops on the CPU. To enable |
| 58 | +this mode, set the `CHPL_LOCALE_MODEL` to `gpu` (to enable GPU support) |
| 59 | +and `CHPL_GPU` to `cpu` to select "CPU-as-device" mode. |
| 60 | + |
| 61 | +```bash |
| 62 | +CHPL_LOCALE_MODEL=gpu CHPL_GPU=cpu chpl 01-hellopar.chpl |
| 63 | +``` |
| 64 | + |
| 65 | +## Using Docker |
| 66 | + |
| 67 | +Install Docker (see the [Installing Docker](#installing-docker) section below for suggestions). Then, use the following command: |
| 68 | + |
| 69 | +```bash |
| 70 | +docker pull docker.io/chapel/chapel-gasnet |
| 71 | +``` |
| 72 | + |
| 73 | +Next follow the instructions at https://hub.docker.com/r/chapel/chapel to compile a hello world in Chapel, but use the `chapel-gasnet` container and when you run the “hello” executable specify `-nl 1`. Here are the commands to use: |
| 74 | + |
| 75 | +``` |
| 76 | +echo 'writeln("Hello, world!");' > hello.chpl |
| 77 | +
|
| 78 | +docker run --rm -it -v "$PWD":/myapp -w /myapp chapel/chapel-gasnet /bin/bash |
| 79 | +
|
| 80 | +root@xxxxxxxxx:/myapp# chpl hello.chpl |
| 81 | +root@xxxxxxxxx:/myapp# ./hello -nl 1 |
| 82 | +Hello, world! |
| 83 | +``` |
| 84 | + |
| 85 | +Note that the Chapel docker image with GASNet support does not have |
| 86 | +any GPU-related support. To use GPU support, you might be better served |
| 87 | +by [building from source](#building-chapel-from-source-on-your-machine) on |
| 88 | +your own machine. |
| 89 | + |
| 90 | +## Building Chapel from Source on Your Machine |
| 91 | + |
| 92 | +Please follow the instructions on the [Download Chapel](https://chapel-lang.org/download.html) page to build the Chapel compiler and runtime from source and get set up with the Chapel compiler executable `chpl`. From there, you can compile and run the `01-hello.chpl` file in this repository as follows: |
| 93 | + |
| 94 | +```bash |
| 95 | +chpl 01-hello.chpl |
| 96 | +./01-hello |
| 97 | +``` |
| 98 | + |
| 99 | +To make use of multiple nodes (or to simulate multi-node execution), please |
| 100 | +refer to [Multilocale Chapel Execution](https://chapel-lang.org/docs/usingchapel/multilocale.html). |
| 101 | +To set up for Chapel's GPU support, refer to the [GPU Programming](https://chapel-lang.org/docs/technotes/gpu.html) tech note. |
| 102 | + |
| 103 | +## Installing Docker |
| 104 | + |
| 105 | +### Mac |
| 106 | + |
| 107 | +Download the docker desktop for Intel or Arm as appropriate from |
| 108 | +https://docs.docker.com/get-docker/. |
| 109 | + |
| 110 | +Start up docker desktop. You do not need a docker account. |
| 111 | + |
| 112 | + |
| 113 | +### Linux |
| 114 | + |
| 115 | +* First three steps on https://docs.docker.com/engine/install/ubuntu/ |
| 116 | + 1. Set up Docker's Apt repository. |
| 117 | + ``` |
| 118 | + # Add Docker's official GPG key: |
| 119 | + sudo apt-get update |
| 120 | + sudo apt-get install ca-certificates curl gnupg |
| 121 | + sudo install -m 0755 -d /etc/apt/keyrings |
| 122 | + curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg |
| 123 | + sudo chmod a+r /etc/apt/keyrings/docker.gpg |
| 124 | +
|
| 125 | + # Add the repository to Apt sources: |
| 126 | + echo "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null |
| 127 | + sudo apt-get update |
| 128 | + ``` |
| 129 | +
|
| 130 | + 2. Install the Docker packages. |
| 131 | + ``` |
| 132 | + sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin |
| 133 | + ``` |
| 134 | +
|
| 135 | + 3. Verify that the Docker Engine installation is successful by running the hello-world image. |
| 136 | + ``` |
| 137 | + sudo docker run hello-world |
| 138 | + ``` |
| 139 | +
|
| 140 | +
|
| 141 | +* Additional steps |
| 142 | + ``` |
| 143 | + sudo groupadd docker |
| 144 | + sudo usermod -aG docker ${USER} |
| 145 | +
|
| 146 | + # maybe not necessary |
| 147 | + sudo chmod 666 /var/run/docker.sock |
| 148 | +
|
| 149 | + ``` |
| 150 | +
|
| 151 | +### Windows |
| 152 | +
|
| 153 | +1. download docker for windows from: https://docs.docker.com/desktop/install/windows-install/ |
| 154 | + a. when promted to log in or create an account, select continue without logging in |
| 155 | +
|
| 156 | +2. open a Powershell terminal (preferably as admin) |
| 157 | + a. if you don't have WSL installed, execute `wsl --install` |
| 158 | + b. next, ensure that your Ubuntu distro is using WSL2 (rather than WSL1). |
| 159 | + Execute `wsl -l -v` and ensure that ubuntu says 2 under version. |
| 160 | + i. If it is on version 1, execute `wsl --set-version ubuntu 2` (may take some time) |
| 161 | +
|
| 162 | +3. open the docker desktop app to start the docker daemon |
| 163 | + a. you can check that docker is using WSL Ubuntu by going to |
| 164 | + Settings > Resources > WSL Integration |
| 165 | +
|
| 166 | +4. in Powershell, execute docker pull chapel/chapel-gasnet |
| 167 | +
|
| 168 | +*NOTE*: For Windows you will probably have to replace the `$PWD` from the instructions |
| 169 | +at https://hub.docker.com/r/chapel/chapel with the Windows version of the current path |
| 170 | +written out |
0 commit comments