Getting Started

Prerequisites

  • JDK 22 or newer: required for the Foreign Function API (see Coffi & Panama Internals for why JDK 22+ specifically)
  • Clojure CLI (recommended) or Leiningen
  • Babashka (optional, for task automation)

Installing JDK 22+

Clojure runs on the JVM, so you need Java installed. This project requires JDK 22 or later because we use the new Foreign Function API to call native code.

On macOS with Homebrew:

brew install openjdk@22

On Linux (Ubuntu/Debian):

sudo apt install openjdk-22-jdk

Alternatively, you can use SDKMAN which works on macOS, Linux, and Windows (WSL):

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 22.0.2-open

Installing the Clojure CLI

The Clojure CLI is the modern way to run Clojure projects using deps.edn.

On macOS with Homebrew:

brew install clojure/tools/clojure

On Linux:

curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh
chmod +x linux-install.sh
sudo ./linux-install.sh

Verify installation:

clj --version

Installing Leiningen

If you prefer Leiningen over the Clojure CLI:

On macOS with Homebrew:

brew install leiningen

On Linux:

curl -O https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein
chmod +x lein
sudo mv lein /usr/local/bin/
lein  # This will download the rest automatically

Installing Babashka

Babashka provides fast task automation for Clojure projects.

On macOS with Homebrew:

brew install borkdude/brew/babashka

On Linux:

bash < <(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)

Verify installation:

bb --version

Running examples

The example programs live in raylib-clj-demo, one project per example. Clone it and follow its README to run one. This repo holds the library only, so there is nothing to launch here. To check your checkout, run bb check, which compiles every namespace under src/ and then lints.

Two things to know when you run any raylib-clj game yourself:

Use clojure, not clj. clj wraps the same launcher in rlwrap for line editing, which interferes with a GUI app's event loop.

-XstartOnFirstThread is macOS-only. macOS requires it to run OpenGL on the main thread. The JVM treats an unrecognized -X option as fatal, so on Linux a command that carries it dies before it starts:

Unrecognized option: -XstartOnFirstThread
Error: Could not create the Java Virtual Machine.

On Linux, leave it out:

clojure -J--enable-native-access=ALL-UNNAMED \
        -J-Djava.library.path=libs:libs/linux_amd64:/usr/local/lib:/usr/lib \
        -M -m your.game.ns

Setting JAVA_HOME

If you have multiple Java versions installed, you may need to set JAVA_HOME:

export JAVA_HOME=/path/to/jdk-22

On macOS with Homebrew:

export JAVA_HOME=/opt/homebrew/opt/openjdk@22

IDE Setup

Clojure development is best experienced with a good editor that supports REPL integration.

VS Code with Calva

  1. Install VS Code
  2. Install the "Calva" extension
  3. Open this project folder
  4. Press Ctrl+Alt+C then Ctrl+Alt+J (or Cmd on macOS) to start a REPL
  5. Select "deps.edn" when prompted

Calva provides syntax highlighting, inline evaluation, and a connected REPL. Evaluate code by placing your cursor on an expression and pressing Ctrl+Enter.

IntelliJ IDEA with Cursive

  1. Install IntelliJ IDEA (Community or Ultimate)
  2. Install the "Cursive" plugin
  3. Open this project folder
  4. Cursive will detect deps.edn and set everything up

To start a REPL, right-click on deps.edn and select "Run REPL".

Connecting to nREPL

For live game development (recommended):

Run a game from raylib-clj-demo. It starts an embedded nREPL on port 7888. Then connect your editor to localhost:7888.

For standalone REPL (non-GUI work):

bb nrepl   # Starts nREPL on port 7999

Then connect your editor to localhost:7999.

See REPL Workflow for the full live-development workflow, including hot-reloading running games from the connected REPL.