# Build Flydsl

> Build and install FlyDSL (Flexible Layout Python DSL) on a remote host or Docker container. FlyDSL is a Python DSL and MLIR-based compiler stack for authoring high-performance GPU kernels with explicit layouts and tiling on AMD GPUs. Requires building LLVM/MLIR from source (~30min) then FlyDSL C++ and Python bindings (~5min). Usage: /build-flydsl [container@host]

- Skill: `rocm/build-flydsl` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rocm/build-flydsl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rocm/build-flydsl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: rocm (https://skillmd.com/u/rocm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rocm/build-flydsl

---


# Build and Install FlyDSL

Build FlyDSL from source on a remote host or Docker container. FlyDSL requires a custom
LLVM/MLIR build with Python bindings, followed by the FlyDSL C++ dialect and Python package.

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `[container@host]` | No | Target in format `container@hostname`. If omitted, build locally. Example: `my-container@gpu-host.example.com` |

## Checkout path

The steps below use `$FLYDSL_ROOT` for the checkout. Set it before starting; the
container images this skill targets conventionally clone to `/FlyDSL`, but a
developer checkout is wherever it was cloned:

```bash
export FLYDSL_ROOT="${FLYDSL_ROOT:-$PWD}"   # or /FlyDSL inside the prebuilt image
```

## Prerequisites

- **ROCm 6.x or 7.x** (for GPU execution)
- **cmake** >= 3.20, C++17 compiler, **ninja** (recommended)
- **Python** 3.10+ with pip
- **Git** (to clone LLVM)
- **Disk space**: ~50GB for LLVM build + FlyDSL
- **CPU cores**: more is better (use `-j$(nproc)` or `-j128`)

## Build Steps

### Step 1: Build LLVM/MLIR (~30 min with -j128)

This clones ROCm/llvm-project, checks out the commit specified in `thirdparty/llvm-hash.txt`,
and builds MLIR with Python bindings.

```bash
cd "$FLYDSL_ROOT"
bash scripts/build_llvm.sh -j128
```

**What it does**:
1. Clones `https://github.com/ROCm/llvm-project.git` to `../llvm-project/`
2. Checks out the pinned commit from `thirdparty/llvm-hash.txt`
3. CMake configure + build + install to `../llvm-project/mlir_install/`
4. Creates tarball `../llvm-project/mlir_install.tgz`

**If you already have an MLIR build**, skip this step and set:
```bash
export MLIR_PATH=/path/to/llvm-project/mlir_install
```

### Step 2: Build FlyDSL (~5 min)

```bash
cd "$FLYDSL_ROOT"
bash scripts/build.sh -j128
```

**What it does**:
1. Auto-detects `MLIR_PATH` from common locations (or uses env var)
2. CMake configure + build the Fly dialect (C++) and Python bindings
3. Output: `build-fly/python_packages/flydsl/` with embedded MLIR bindings

### Step 3: Install (editable mode)

```bash
cd "$FLYDSL_ROOT"
pip install -e .
```

**Or without installing** (just set paths):
```bash
export PYTHONPATH="$FLYDSL_ROOT/build-fly/python_packages:$FLYDSL_ROOT:$PYTHONPATH"
export LD_LIBRARY_PATH="$FLYDSL_ROOT/build-fly/python_packages/flydsl/_mlir/_mlir_libs:$LD_LIBRARY_PATH"
```

### Step 4: Verify

```bash
python3 -c "import flydsl; print('FlyDSL OK')"
bash scripts/run_tests.sh  # GEMM correctness tests (~15s)
```

## Remote/Docker Execution

For building inside a Docker container on a remote host:

```bash
# SSH command pattern
ssh -o LogLevel=ERROR <HOST> 'docker exec <CONTAINER> bash -c "cd "$FLYDSL_ROOT" && CMD"'

# Full build sequence (run each step, wait for completion)
ssh ... 'docker exec -d <CONTAINER> bash -c "cd "$FLYDSL_ROOT" && bash scripts/build_llvm.sh -j128 > /tmp/build_llvm.log 2>&1"'
# Monitor: ssh ... 'docker exec <CONTAINER> tail -5 /tmp/build_llvm.log'
# Wait for "LLVM_BUILD_DONE" or "Creating tarball..." followed by completion

ssh ... 'docker exec <CONTAINER> bash -c "cd "$FLYDSL_ROOT" && bash scripts/build.sh -j128"'
ssh ... 'docker exec <CONTAINER> bash -c "cd "$FLYDSL_ROOT" && pip install -e ."'
ssh ... 'docker exec <CONTAINER> bash -c "python3 -c \"import flydsl; print(\\\"FlyDSL OK\\\")\""'
```

## Build Artifacts (Do NOT Commit)

The following directories are build artifacts generated by CMake and should NOT be committed to git:
- `python/flydsl/_mlir/` — MLIR Python bindings (compiled `.so` files, platform-specific); absent until you build <!-- api-check: ignore -->
- `build/`, `build-fly/` — CMake build directories

These are already in `.gitignore`. After a fresh clone, run the build steps above to regenerate.

## Rebuild After Code Changes

```bash
# C++ changes (dialect, MLIR passes):
bash scripts/build.sh -j128

# Python-only changes:
# No rebuild needed — editable install picks up changes automatically.

# Clear kernel cache if stale results:
rm -rf ~/.flydsl/cache
# Or disable disk cache (in-memory cache remains active):
export FLYDSL_RUNTIME_ENABLE_CACHE=0
```

## Troubleshooting

- **`std::gcd not found` or redeclaration errors**: Wrong LLVM picked up. `unset MLIR_PATH` and let `build.sh` auto-detect.
- **`No module named flydsl`**: Run `pip install -e .` or set `PYTHONPATH`.
- **MLIR `.so` load errors**: Set `LD_LIBRARY_PATH` to include `build-fly/python_packages/flydsl/_mlir/_mlir_libs/`.
- **Build OOM**: Reduce parallelism (e.g., `-j64` instead of `-j128`).
- **Docker `exec -d` for long builds**: Use background mode and monitor log file. LLVM build takes ~30min with 128 cores.

## Verified Environments

| Image | Status |
|-------|--------|
| rocm/pytorch:rocm7.2_ubuntu24.04_py3.12_pytorch_release_2.8.0 | Verified 2026-03-10 |