Skip to content

setup.md

Latest commit

 

History

History
334 lines (231 loc) · 7.56 KB

setup.md

File metadata and controls

334 lines (231 loc) · 7.56 KB

Setup Instructions

Welcome to the ACT Tutorial at ICFP/SPLASH 2025! This guide will help you set up your environment for the hands-on exercises.

Prerequisites: A laptop with ~10GB free disk space and a working internet connection.

Time Required: 1-2 minutes (depending on internet speed)

Quick Start (For Docker Users)

If you already have Docker installed, follow these steps:

# 1. Clone the repository with submodules
git clone --recursive https://github.com/act-compiler/tutorials-splash25.git
cd tutorials-splash25

# 2. Pull the Docker image
docker pull devanshdvj/act-tutorials:splash25

# 3. Launch the environment
./docker.sh

# 4. Inside the container, verify the setup
ls /opt/cargo /opt/ortools /opt/nlohmann_json # Should exist
python --version  # Should show Python 3.10.18

If you don't have Docker installed, follow the Detailed Setup below.

Detailed Setup

Step 1: Clone the Repository

Clone the tutorial repository with all submodules:

git clone --recursive https://github.com/act-compiler/tutorials-splash25.git
cd tutorials-splash25

Already cloned without --recursive? Run this inside the cloned repository to fetch submodules:

cd tutorials-splash25
git submodule update --init --recursive

Step 2: Install Docker

Check if Docker is installed:

docker --version

If Docker is already installed, skip to Step 3.

Installing Docker on Linux (Ubuntu/Debian)

# Remove old Docker versions
sudo apt-get remove docker docker-engine docker.io containerd runc 2>/dev/null || true

# Update package index
sudo apt-get update

# Install dependencies
sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up the Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start Docker service
sudo systemctl enable docker
sudo systemctl start docker

# Add your user to the docker group (to run without sudo)
sudo usermod -aG docker $USER

# Apply group changes (logout/login or use newgrp)
newgrp docker

# Verify installation
docker run hello-world

Note: If you see a permission error, you may need to log out and log back in for the group changes to take effect.

Installing Docker on macOS

  1. Download Docker Desktop from: https://docs.docker.com/desktop/install/mac-install/
  2. Install the .dmg file
  3. Launch Docker Desktop
  4. Verify installation: 
    docker --version

Installing Docker on Windows

  1. Enable WSL 2 (Windows Subsystem for Linux)
  2. Download Docker Desktop from: https://docs.docker.com/desktop/install/windows-install/
  3. Install the .exe file
  4. Launch Docker Desktop
  5. Verify installation in PowerShell or WSL terminal: 
    docker --version

Step 3: Pull the Docker Image

Pull the pre-built Docker image containing all tutorial dependencies:

docker pull devanshdvj/act-tutorials:splash25

Expected Output:

splash25: Pulling from devanshdvj/act-tutorials
...
Status: Downloaded newer image for devanshdvj/act-tutorials:splash25
docker.io/devanshdvj/act-tutorials:splash25

Image Details:

  • Base: Ubuntu 22.04 (Jammy)
  • Size: ~5 GB
  • Includes:
    • Python 3.10 (via Miniconda)
    • ML libraries (JAX, NumPy, etc.)
    • ANTLR4 (for parsing)
    • Rust toolchain (stable)
    • C++ build tools (CMake, Ninja)
    • nlohmann/json (JSON library)
    • Google OR-Tools (constraint solver)
  • Dockerfile: Dockerfile

Step 4: Launch the Docker Environment

We provide a convenience script to launch the Docker container:

./docker.sh

What this does:

  • Mounts code/ directory at /workspace/ in the container
  • Sets working directory to /workspace/
  • Preserves file ownership (uses your UID/GID)
  • Removes container on exit (no leftover containers)

Step 5: Verify the Setup

Once inside the Docker container, run these verification checks:

Check 1: Verify Directory Structure

ls

Expected Output:

README.md  docker  generators  taidlv2  xla-debug

Check 2: Verify Installed Tools

# Check Rust
/opt/cargo/bin/cargo --version
/opt/cargo/bin/rustc --version

# Check OR-Tools
find /opt/ortools/lib/ -name "libortools.so"

# Check nlohmann/json
find /opt/nlohmann_json/include/nlohmann/ -name "json.hpp"

Expected Output:

cargo 1.90.0 (840b83a10 2025-07-30)
rustc 1.90.0 (1159e78c4 2025-09-14)
/opt/ortools/lib/libortools.so
/opt/nlohmann_json/include/nlohmann/json.hpp

Check 3: Verify Python Environment

# Check Python
python --version
python -c "import jax; print(f'JAX version: {jax.__version__}')"
python -c "import numpy as np; print(f'NumPy version: {np.__version__}')"

Expected Output:

Python 3.10.18
JAX version: 0.4.33
NumPy version: 1.26.4

Check 4: Test TAIDL

cd /workspace/ && python -c "from taidlv2.accelerator import *; print('TAIDLv2 import successful')"

Expected Output:

TAIDLv2 import successful

Troubleshooting

Issue: "Cannot connect to Docker daemon"

Solution: Make sure Docker is running:

# Linux
sudo systemctl start docker

# macOS/Windows
# Launch Docker Desktop application

Issue: "Permission denied" when running Docker

Solution: Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker  # Or log out and log back in

Issue: Submodules not fetched

Solution: Initialize submodules manually:

cd tutorials-splash25
git submodule update --init --recursive

Issue: Docker image pull fails

Solution: Check internet connection and try again:

docker pull devanshdvj/act-tutorials:splash25

If pull continues to fail, the image may also be available on a USB drive at the tutorial venue.

Issue: Conda environment not activated

Solution: Manually activate the environment:

source /opt/miniconda/etc/profile.d/conda.sh
conda activate act

What's Next?

Once your setup is verified, you're ready for the tutorial! During the tutorial, you'll:

  1. Session 1: Specify a QKV accelerator ISA using TAIDL
  2. Session 2: Write accelerator kernels using generated APIs
  3. Session 3: Generate a compiler backend automatically
  4. Session 4: Integrate with JAX and XLA for end-to-end compilation

Tutorial Materials:

  • Exercises: exercise1/README.md, exercise2/README.md, exercise3/README.md

Additional Resources

Getting Help

If you encounter issues during setup:

  1. Check troubleshooting section above
  2. Contact organizers:

We look forward to seeing you at the tutorial! 🚀