Michael Trojanek (relativkreativ) — Bootstrapper and creator of things

This article was published on February 4th 2019 and takes about 2 minutes to read.

How to compile a Crystal project with static linking

Compiling a Crystal project with static linking allows you to easily distribute it as a single file without any dependencies. Unfortunately, right not it is only possible on Alpine Linux machines. I'll show you how it's done.

If you follow me on Twitter, my love for Crystal will not have escaped your notice.

Why I am such a fan will be topic for another article, but being able to compile a Crystal project to a single binary is — besides its syntax and ideology closely resembling Ruby's — clearly the number one reason.

Dynamic linking

Crystal compiles with dynamic linking per default. This is no problem most of the time — compiling a Crystal project on CentOS, copying the resulting binary to a Ubuntu mache and running it there simply works. That's because they share the same dynamic libraries Crystal links to on compilation.

Things get a little trickier once you want to package your compiled Crystal project into an RPM: The rpmbuild command throws a dependency issue which is impossible to resolve at the moment.

This is where static linking comes into play.

Static linking

The Crystal docs have sad news on static linking currently:

Static linking using the --static compiler flag is currently only supported on Alpine Linux. The easiest way to do this is to compile your application inside an Alpine Linux Docker container.

Firing up a Docker container for the sole purpose of compiling your project only pays if you already use Docker in your workflow.

If you are one of many developers who don't, you can either build your own Alpine Linux virtual machine (which is even more work) or simply use my prebuilt Vagrant box.

Before compiling a Crystal project on an Alpine machine

After creating a Vagrantfile with vagrant init relativkreativ/alpine-3 and running vagrant up there is a little work left to do before we can compile our Crystal project:

That's all there is to it

Once this is done, you can compile your Crystal project with crystal build src/FILE.cr -o bin/FILE --release --static.

This article refers to Crystal 0.27.1.

Get in the loop!

Like this article? There's more where this one's coming from — join my email list to get new articles delivered straight into your inbox.

I'll send you a free copy of my book Build Your Own Rails Server as a welcome gift.

No spam — guaranteed. You can leave at any time.