How to build video games for Windows using Crystal

Crystal Programming Language does not yet support Windows, but there's an awesome work-in-progress fork that already allows compiling some Crystal programs and getting native Windows executables. None of that work is mine, I just rehashed their instructions and added good news that one can already make proper video games for Windows.

Note that, even though there are multiple mentions of Windows Subsystem for Linux here, it is used only for one of the build steps. The resulting binaries run natively on Windows, no strings attached.

Basic Crystal setup

You need a POSIX-compatible system that Crystal officially supports (like Linux) and also Windows. If you are already on Windows 10, the obvious choice is Bash on Ubuntu on Windows. If on a different OS, use a virtual machine with Windows — VirtualBox is a good choice.


Get the two systems running at the same time and set up a shared/synchronized (initially empty) folder between them. If your host is Windows, an easy choice would be "C:\crystal-windows", then the Windows Subsystem for Linux can see it as "/mnt/c/crystal-windows".

First, set up the folder in Bash. Save the path to it in a variable for later reference. Try to avoid whitespace in the path to the directory.
Keep in mind that if you need to open a new terminal window, you'll need to reapply this variable.

bashfolder=/full/path/to/crystal-windows
cd "$folder"

Install Crystal normally.

Install Crystal's build dependencies, here's a minimal list for Ubuntu:

bashsudo apt-get install build-essential zlib1g-dev libgc-dev libevent-dev libpcre3-dev libssl-dev libxml2-dev

Install LLVM 3.9 or later.

Compile the Crystal branch with Windows support:

bashcd "$folder"
git clone --branch win https://github.com/oprypin/crystal
cd crystal
make

Let's try an example.

bashcd "$folder"
echo 'puts "Hello, World!"' > hello.cr
crystal/bin/crystal run hello.cr

The compiler itself does not yet run on Windows, so in order to run this example on Windows later on, we need to cross-compile an object file first.

bashcrystal/bin/crystal build hello.cr --cross-compile --target x86_64-pc-windows-msvc --no-debug

And, just to make life easier, download the libraries that are needed for Crystal on Windows. Or build them yourself on Windows.

bashcd "$folder"
wget https://crystal-lang.s3.amazonaws.com/windows/gc/gc-7.6.0.zip
wget https://crystal-lang.s3.amazonaws.com/windows/libevent/libevent-2.1.8.zip
wget https://crystal-lang.s3.amazonaws.com/windows/libiconv/libiconv-1.15.zip
wget https://crystal-lang.s3.amazonaws.com/windows/pcre/pcre-8.40.zip
for f in *.zip; do unzip -j "$f" && rm "$f"; done  # -j to ignore subfolders

Now we move on to Windows.

Install Visual C++ 2015 Build Tools.

Open "Visual C++ 2015 x64 Native Build Tools Command Prompt" in the Start menu. We will be using this shell from now on. Find the same folder that you were working on in Bash and change to it here. Ensure that there is no whitespace in the path to the directory. Set a variable for further reference. Keep in mind that if you need to open a new terminal window (it needs to be the one from "Visual C++..."), you'll need to reapply this variable.

cmdset folder=C:\full\path\to\crystal-windows
cd %folder%

Now we can build and run the program from earlier because we've stored the object file here.

cmdlink hello.o libevent.lib gc.lib pcre.lib kernel32.lib ws2_32.lib user32.lib /NODEFAULTLIB:msvcrt
hello.exe

So the two-step process of compiling on a POSIX system and linking on Windows allows us to run Crystal programs on Windows. At this early stage many programs will fail. But, as it turns out, CrSFML already works well, because it's an external framework and you rarely need to interact with Crystal's standard library while using it. So, it's finally time for some real game dev!

CrSFML logo

Using CrSFML

CrSFML is Crystal bindings to Simple and Fast Multimedia Library, which is most often used to make cross-platform games.

Remember, we're still using two systems at once: bash on a POSIX system and cmd on Windows.

Start by downloading CrSFML precompiled sources:

bashcd "$folder"
git clone --branch sources https://github.com/oprypin/crsfml

Going back to Windows:
Download CMake Latest ReleaseWindows x64 Installer and install it. Make sure to select "Add CMake to the system PATH for the current user".

To apply this PATH change, close and reopen the Visual C++ 2015 x64 Native Build Tools Command Prompt window. That means reapplying the folder variable (see below).

Download SFML Latest stable versionVisual C++ 14 (2015) - 64-bit. Extract it to that same folder we've been using, but rename it from something like "SFML-2.4.2" to just "sfml" for easier reference. Get the full path to it in a variable (it is important for CMake to use forward slashes).

cmdset folder=C:\full\path\to\crystal-windows
set sfml=C:/full/path/to/crystal-windows/sfml

The next step is compiling the intermediate C bindings that connect CrSFML to SFML:

cmdcd %folder%\crsfml\voidcsfml
cmake . -DSFML_ROOT=%sfml% -DCMAKE_MODULE_PATH=%sfml%/cmake/Modules -G "Visual Studio 14 2015 Win64"
cmake --build . --config Release

And we'll continue the unfortunate pattern of just dropping all compiled libraries into the same folder, it's easier this way.

cmdcd %folder%
xcopy crsfml\voidcsfml\Release\* .

Sigh, let's even copy all the CrSFML examples and resources into that poor folder.

cmdcd %folder%
xcopy /S crsfml\examples\* .

Now we're ready for the two-step cross-compilation dance again.

bashcd "$folder"
crystal/bin/crystal build snakes.cr --cross-compile --target x86_64-pc-windows-msvc --no-debug
cmdcd %folder%
link snakes.o libevent.lib gc.lib pcre.lib kernel32.lib ws2_32.lib user32.lib voidcsfml-graphics.lib voidcsfml-window.lib voidcsfml-system.lib /NODEFAULTLIB:msvcrt
snakes.exe

With any luck, now you should be playing a two-player snake game! You can try out other examples just as well, though not all of them will work.

Screenshot
Screenshot

By the way, all these demos do work on Windows.

If you're using Windows Subsystem for Linux, you can set up a script to initiate both compilation steps from Windows. Create the file build.cmd:

build.cmdset name=%1
bash -c "crystal/bin/crystal build %name%.cr --cross-compile --target x86_64-pc-windows-msvc --no-debug"
link %name%.o libevent.lib gc.lib pcre.lib kernel32.lib ws2_32.lib user32.lib voidcsfml-*.lib /NODEFAULTLIB:msvcrt
cmdbuild transformable & transformable

Refer to the documentation to learn CrSFML.

Created (last updated )
Comments powered by Disqus