Author: Eiko

Time: 2026-01-23 10:54:02 - 2026-01-23 10:54:37 (UTC)

The following setup guide is produced by chatgpt, I will try it and verify it, modifying the parts that are not correct.

Windows: Haskell + h-raylib (raylib) Setup & Distribution Guide

This is a from-zero → working demo → shipping build checklist for getting raylib + Haskell (h-raylib) running on Windows, and packaging your game so users can run it by double-clicking.

Core idea: h-raylib typically vendors the raylib C sources via the package build, so you usually do not need a separate raylib installation. What you do need is a working Haskell toolchain + a working Windows C toolchain.

What you’re building (mental model)

Your shipped game will look like:

MyGame/
  MyGame.exe
  *.dll
  assets/
  LICENSES/

If you forget required *.dll files, users will get:

• “...dll was not found”

The most common one for h-raylib builds on Windows is:

• libwinpthread-1.dll

Part A — Install Toolchain (GHCup + MSYS2)

A1) Install GHCup on Windows (PowerShell)

Open PowerShell (non-admin) and run:

Set-ExecutionPolicy Bypass -Scope Process -Force;
[System.Net.ServicePointManager]::SecurityProtocol =
  [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
try {
  & ([ScriptBlock]::Create(
      (Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing)
    )) -Interactive -DisableCurl
} catch { Write-Error $_ }

During the interactive installer, enable:

• ✅ Install GHC
• ✅ Install Cabal
• ✅ Install MSYS2 (important)
• (Optional) HLS / Stack

After install

Close the terminal, open a new PowerShell, verify:

ghc --version
cabal --version

Part B — Ensure the C toolchain exists (MSYS2)

h-raylib compiles C sources on Windows, so you need a working C compiler toolchain.

B1) Open the correct MSYS2 shell

GHCup typically installs MSYS2 under something like:

C:\ghcup\msys64\

Use one of these:

• C:\ghcup\msys64\msys2_shell.cmd -clang64
• C:\ghcup\msys64\msys2_shell.cmd -mingw64

Recommended if you’re unsure:

C:\ghcup\msys64\msys2_shell.cmd -clang64

B2) Update MSYS2 and install build tools

Inside MSYS2 shell:

pacman -Syu

If MSYS2 tells you to close the shell, do it, reopen, then run again:

pacman -Syu

Then install a toolchain:

If you opened -clang64

pacman -S --needed base-devel mingw-w64-clang-x86_64-toolchain

If you opened -mingw64

pacman -S --needed base-devel mingw-w64-x86_64-toolchain

Part C — Minimal h-raylib project (build + run)

C1) Create a new Cabal executable project

In PowerShell:

mkdir hello-raylib
cd hello-raylib
cabal init -n --is-executable --main-is Main.hs --language GHC2021

Edit hello-raylib.cabal and add:

build-depends: base, h-raylib

C2) Minimal window program

Create Main.hs:

module Main where

import Raylib.Core
  ( beginDrawing, clearBackground, closeWindow, endDrawing
  , initWindow, setTargetFPS
  )
import Raylib.Core.Text (drawText)
import Raylib.Util (whileWindowOpen0)
import Raylib.Util.Colors (rayWhite, lightGray)

main :: IO ()
main = do
  initWindow 800 450 "hello h-raylib on Windows"
  setTargetFPS 60

  whileWindowOpen0 $ do
    beginDrawing
    clearBackground rayWhite
    drawText "Hello from h-raylib!" 220 200 24 lightGray
    endDrawing

  closeWindow

C3) Run

cabal run

Part D — Common Windows problems & fixes

D1) “Nothing happens” / window closes instantly

This is usually because:

• you didn’t run a draw loop
• you didn’t pump events

Use the pattern:

• whileWindowOpen0 + beginDrawing ... endDrawing in the loop

D2) libwinpthread-1.dll was not found

This is very common.

Fix option 1 (dev machine): add MSYS2 bin to PATH

Add one of these to PATH:

• C:\ghcup\msys64\mingw64\bin
• C:\ghcup\msys64\clang64\bin

Fix option 2 (shipping build): copy the DLL next to the exe

Put libwinpthread-1.dll in the same folder as MyGame.exe.

D3) Missing (or bad) C libraries: gcc_eh

This can happen from toolchain mismatch.

Usually fixed by:

• ensuring you’re using the correct MSYS2 environment (clang64 vs mingw64)
• installing a complete toolchain via pacman (see Part B)

Part E — Shipping / Distribution (double-click works)

Goal: a fresh Windows machine can run your game with no extra installs.

E1) Build a release executable

cabal build

Find the built exe path:

cabal list-bin exe:hello-raylib

Copy to a release/ folder:

mkdir release
copy (cabal list-bin exe:hello-raylib) release\hello-raylib.exe

E2) Bundle required DLLs (most important part)

Rule of thumb:

✅ Put all required *.dll in the same folder as the .exe.

This avoids PATH problems for users.

How to find required DLLs

Pick one method:

Method A (GUI): use a dependency viewer

Use a Windows tool like Dependencies to open the exe and see what DLLs are needed.

Method B (MSYS2): list imported DLL names

From MSYS2:

objdump -p /path/to/hello-raylib.exe | grep "DLL Name"

DLLs you might need to copy

Common ones:

• libwinpthread-1.dll ✅ very common
• libgcc_s_seh-1.dll (or similar)
• libstdc++-6.dll
• libgmp-10.dll (often required by GHC builds)
• libffi-*.dll (sometimes)

Where to copy DLLs from

Usually from:

• C:\ghcup\msys64\mingw64\bin\
• or C:\ghcup\msys64\clang64\bin\

Copy these DLLs into your release/ folder beside the exe.

E3) Bundle assets safely

Put assets under:

release/assets/...

Load assets relative to the exe directory so it works when double-clicked.

Example:

import System.Environment (getExecutablePath)
import System.FilePath (takeDirectory, (</>))

assetsDir :: IO FilePath
assetsDir = do
  exe <- getExecutablePath
  pure (takeDirectory exe </> "assets")

E4) Licenses folder (recommended)

Create:

release/LICENSES/

Add license texts for:

• raylib
• h-raylib
• any other bundled dependency that requires inclusion

E5) Packaging options

Option A (simplest): ZIP portable build

Ship release/ as a .zip.

User:

1. Unzip
2. Double-click MyGame.exe

Option B: Installer (more “Windows native”)

Use an installer maker (Inno Setup / NSIS) to:

• install into Program Files
• create Start Menu shortcut
• optionally desktop shortcut

E6) The single most important test

Before publishing:

✅ Test on a fresh Windows environment:

• Windows Sandbox
• or a clean VM

If it fails, it’s almost always:

• missing DLL(s)

Copy missing DLLs into release/ and re-test.

Recommended “lowest pain” recipe

1. Install GHCup + Cabal + MSYS2
2. Ensure MSYS2 has a full toolchain (Part B)
3. Build with cabal build
4. Create release/
5. Copy .exe to release/
6. Copy required *.dll into release/
7. Add assets/
8. Zip & ship

Quick checklist

✅ cabal run works on your dev machine

✅ release/MyGame.exe exists

✅ release/*.dll includes everything the exe needs

✅ release/assets/ loads correctly when double-clicked

✅ Tested on a fresh machine / sandbox

✅ Packaged as zip or installer