Skip to content

Commit 44b7520

Browse files
committed
Add initial README
Signed-off-by: Danila Fedorin <daniel.fedorin@hpe.com>
1 parent 47da5e0 commit 44b7520

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

README.md

+170
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
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

Comments
 (0)