Cross-compiling with LDC
LDC is an implicit cross-compiler, i.e., you don't need multiple LDC executables for each host → target combination. This page shows how to set up LDC for cross-compilation and -linking.
Contents
The -mtriple command-line option
The fundamental instrument for cross-compilation is LDC's -mtriple
command-line option (the corresponding clang switch is -target). It defines the target for code-generation, incl. architecture and operating system.
Here are some popular triples:
x86_64-linux-gnu
: Linux x86_64 with glibcx86_64-apple-darwin16.7.0
: macOSx86_64-windows-msvc
: Windows x64i686-linux-gnu
: Linux x86 with glibci686-windows-msvc
: Windows x86armv6-linux-gnueabihf
: Linux ARMv6 with glibc and hard-float ABIaarch64-linux-gnu
: Linux AArch64 with glibcwasm32-unknown-unknown-webassembly
: 32-bit WebAssembly
Run ldc2 -version
to check your default/host triple (Default target).
Generating LLVM IR
Generating textual LLVM IR (-output-ll
) and LLVM bitcode (-output-bc
) works for all supported targets, on all hosts.
ldc2 -mtriple=x86_64-apple-darwin16.7.0 -output-ll foo.d
: generates a foo.ll text file with the textual LLVM IR for macOS
Cross-compiling
Cross-compiling object files (-c
) and textual assembly files (-output-s
) works for all targets supported by the LLVM which was linked against LDC, which depends on the LLVM CMake build configuration (enabled target architectures).
Running ldc2 -version
shows the list of enabled/registered LLVM backends.
ldc2 -mtriple=x86_64-windows-msvc -c foo.d
: generates a foo.obj COFF object file for Win64
Generating static libraries
Generating suited static libraries (-lib
) works for all targets, on all hosts.
ldc2 -mtriple=x86_64-linux-gnu -lib foo.o
: generates a libfoo.a archiveldc2 -mtriple=x86_64-windows-msvc -lib foo.obj
: generates a foo.lib library
As long as your LLVM features the backend for your target, you can obviously directly cross-compile and -archive a library:
ldc2 -mtriple=… -lib foo.d
Cross-linking requires more work, as we have these requirements:
- Default libraries (e.g., druntime and Phobos) for the target, as (non-betterC) binaries are linked against these default libraries.
- C runtime libraries (and startup object files etc.) for the target, as druntime and Phobos don't completely reinvent the wheel and build on top of a C runtime (glibc, musl, Visual C++, Bionic, …). This also applies to
-betterC
binaries. - A cross-linker.
Default libraries
If there's a prebuilt LDC package for your desired target, then the simplest variant is to download it and copy the lib[32,64] subdirectories to your host LDC installation (or wherever you like).
If there's no prebuilt LDC package or you prefer cross-compiling druntime and Phobos yourself, check out Building LDC runtime libraries.
C runtime libraries
Windows targets
The WinSDK and Visual C++ libraries are included in the prebuilt LDC Windows packages since v1.13 (in the mingw subdirectory in the lib directories), so you're already set after copying the lib directories in the previous step.
Non-Apple POSIX targets
The preferred way is to install a gcc toolchain for cross-compilation, e.g., the gcc-aarch64-linux-gnu package on Debian/Ubuntu hosts when targeting Linux/AArch64. It includes the C libraries as well as a cross-linker (aarch64-linux-gnu-gcc) configured for those libs and startup object files etc.
Cross-linker
Windows targets
For Windows targets, LLVM's LLD works nicely as cross-linker on all hosts. Official prebuilt LDC packages feature an integrated LLD, which can be enabled via -link-internally
. Usually, you don't need to use that command-line option explicitly; LDC should default to it automatically on non-Windows hosts.
Non-Apple POSIX targets
The preferred way is to use the cross-gcc installed in the previous step as linker driver, as it is preconfigured for the accompanying C runtime libs and object files.
- Option 1: set the CC environment variable, e.g.,
CC=aarch64-linux-gnu-gcc ldc2 …
- Option 2: use LDC's
-gcc
switch, e.g.,ldc2 -gcc=aarch64-linux-gnu-gcc …
Tweaking the LDC configuration file
This is the last step. :) LDC needs information about where to find the target's libraries and which cross-linker to use. While you can specify that information on the command-line, it's tedious and error-prone, so the preferred way is to extend the etc/ldc2.conf configuration file by appending a section for your target triple.
- Exemplary section for a Win64 target, assuming the lib directory from the prebuilt LDC Win64 package was copied to <LDC root>/lib-win64:
"x86_64-.*-windows-msvc": { switches = [ "-defaultlib=phobos2-ldc,druntime-ldc", "-link-defaultlib-shared=false", ]; lib-dirs = [ "%%ldcbinarypath%%/../lib-win64", ]; };
- Exemplary section for a Linux/AArch64 target, assuming the lib directory from the prebuilt LDC AArch64 package was copied to <LDC root>/lib-aarch64 and the cross-gcc binary is found via aarch64-linux-gnu-gcc:
"aarch64-.*-linux-gnu": { switches = [ "-defaultlib=phobos2-ldc,druntime-ldc", "-gcc=aarch64-linux-gnu-gcc", ]; lib-dirs = [ "%%ldcbinarypath%%/../lib-aarch64", ]; rpath = "%%ldcbinarypath%%/../lib-aarch64"; };
- Exemplary section for an Android/ARMv7-A target on a Linux x64 host, assuming the lib directory from the prebuilt LDC armv7a package was copied to <LDC root>/lib-armv7a and the Android NDK r20 has been unzipped into /home/me:
"armv7a-.*-linux-androideabi": { switches = [ "-defaultlib=phobos2-ldc,druntime-ldc", "-link-defaultlib-shared=false", "-gcc=/home/me/android-ndk-r20/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi21-clang", "-linker=bfd", "-mcpu=cortex-a8", ]; lib-dirs = [ "%%ldcbinarypath%%/../lib-armv7a", ]; };
These settings will be used automatically when specifying a matching target triple, so that ldc2 -mtriple=x86_64-windows-msvc foo.d
is enough to generate a foo.exe Win64 executable.
Limitations
LDC doesn't have a software compile-time real for arbitrary target real
precision yet, but uses the host's real for storage and CTFE (exception: it uses 80-bit x87 compile-time precision on Windows/MSVC hosts). So if the target real features a higher precision (e.g., 32-bit ARM → x86, x86 → AArch64), real.max
will overflow to infinity, real.min_normal
may underflow to 0, CTFE computations will be performed with lower host precision etc.