Crystal supports static linking, i.e. it can link a binary with static libraries so that these libraries don't need to be available as runtime dependencies. This improves portability at the cost of larger binaries.
Static linking can be enabled using the
--static compiler flag. See the usage instructions in the language reference.
--static is given, linking static libraries is enabled, but it's not exclusive. The produced binary won't be fully static linked if the dynamic version of a library is higher in the compiler's library lookup chain than the static variant (or if the static library is entirely missing). In order to build a static binary you need to make sure that static versions of the linked libraries are available and the compiler can find them.
The compiler uses the
CRYSTAL_LIBRARY_PATH environment variable as a first lookup destination for static and dynamic libraries that are to be linked. This can be used to provide static versions of libraries that are also available as dynamic libraries.
Not all libraries work well with being statically linked, so there may be some issues.
openssl for example is known for complications, as well as
glibc (see Fully Static Linking).
Some package managers provide specific packages for static libraries, where
foo provides the dynamic library and
foo-static for example provides the static library. Sometimes static libraries are also included in development packages.
Fully Static Linking¶
A fully statically linked program has no dynamic library dependencies at all. This is useful for delivering portable, pre-compiled binaries. Prominent examples of fully statically linked Crystal programs are the
shards binaries from the official distribution packages.
In order to link a program fully statically, all dependencies need to be available as static libraries at compiler time. This can be tricky sometimes, especially with common
glibc is the most common
libc implementation on Linux systems. Unfortunately, it doesn't play nicely with static linking and it's highly discouraged.
Instead, static linking against
musl-libc is the recommended option on Linux. Since it's statically linked, a binary linked against
musl-libc will also run on a glibc system. That's the entire point of it.
It is however completely fine to statically link other libraries besides a dynamically linked
musl-libc is a clean, efficient
libc implementation with excellent static linking support.
The recommended way to build a statically linked Crystal program is Alpine Linux, a minimal Linux distribution based on
Official Docker Images based on Alpine Linux are available on Docker Hub at
crystallang/crystal. The latest release is tagged as
crystallang/crystal:latest-alpine. The Dockerfile source is available at crystal-lang/distribution-scripts.
shards, and static libraries of all of stdlib's dependencies these Docker images allow to easily build static Crystal binaries even from
glibc-based systems. The official Crystal compiler builds for Linux are created using these images.
Here's an example how the Docker image can be used to build a statically linked Hello World program:
$ echo 'puts "Hello World!"' > hello-world.cr $ docker run --rm -it -v $(pwd):/workspace -w /workspace crystallang/crystal:latest-alpine \ crystal build hello-world.cr --static $ ./hello-world Hello World! $ ldd hello-world statically linked
Alpine’s package manager APK is also easy to work with to install static libraries. Available packages can be found at pkgs.alpinelinux.org.
macOS doesn't officially support fully static linking because the required system libraries are not available as static libraries.
Identifying Static Dependencies¶
If you want to statically link dependencies, you need to have their static libraries available. Most systems don't install static libraries by default, so you need to install them explicitly. First you have to know which libraries your program links against.
Static libraries have the file extension
.a on POSIX and
.lib on Windows.
Dynamic libraries have
.so on Linux and most other POSIX platforms,
.dylib on macOS and
.dll on Windows.
On most POSIX systems the tool
ldd shows which dynamic libraries an executable links to. The equivalent
on macOS is
The following example shows the output of
ldd for a simple Hello World program built with Crystal 0.36.1 and LLVM 10.0 on Ubuntu 18.04 LTS (in the
crystallang/crystal:0.36.1 docker image). The result varies on other systems and versions.
$ ldd hello-world_glibc linux-vdso.so.1 (0x00007ffeaf990000) libpcre.so.3 => /lib/x86_64-linux-gnu/libpcre.so.3 (0x00007fc393624000) libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fc393286000) libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fc393067000) libevent-2.1.so.6 => /usr/lib/x86_64-linux-gnu/libevent-2.1.so.6 (0x00007fc392e16000) libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007fc392c12000) libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007fc3929fa000) libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fc392609000) /lib64/ld-linux-x86-64.so.2 (0x00007fc393dde000)
These libraries are the minimal dependencies of Crystal's standard library. Even an empty program requires these libraries for setting up the Crystal runtime.
This looks like a lot, but most of these libraries are actually part of the libc distribution.
On Alpine Linux the list is much smaller because musl includes more symbols directly into a
single binary. The following example shows the output of the same program built with Crystal 0.36.1 and LLVM 10.0 on Alpine Linux 3.12 (in the
crystallang/crystal:0.36.1-alpine docker image).
$ ldd hello-world_musl /lib/ld-musl-x86_64.so.1 (0x7fe14b05b000) libpcre.so.1 => /usr/lib/libpcre.so.1 (0x7fe14af1d000) libgc.so.1 => /usr/lib/libgc.so.1 (0x7fe14aead000) libgcc_s.so.1 => /usr/lib/libgcc_s.so.1 (0x7fe14ae99000) libc.musl-x86_64.so.1 => /lib/ld-musl-x86_64.so.1 (0x7fe14b05b000)
The individual libraries are
libgc and the rest is
libc). The same libraries are used in the Ubuntu example.
In order to link this program statically, we need static versions of these three libraries.
*-alpine docker images ship with static versions of all libraries used by the standard library.
If your program links no other libraries then adding the
--static flag to the build command is all you need to link fully statically.