Difference between revisions of "Building LDC runtime libraries"
m (→How it works) |
(Tweaks for final 1.4) |
||
| Line 1: | Line 1: | ||
| − | Starting with version 1.4, LDC ships with a small build tool to allow you to recompile the runtime standard library (and optionally the accompanying testrunners) the way you want, [https://github.com/ldc-developers/ldc/blob/master/runtime/ldc-build-runtime.d.in ldc-build-runtime]. | + | Starting with version 1.4, LDC ships with a small build tool to allow you to recompile the D runtime and standard library (and optionally the accompanying testrunners) the way you want, [https://github.com/ldc-developers/ldc/blob/master/runtime/ldc-build-runtime.d.in ldc-build-runtime]. |
== Use cases == | == Use cases == | ||
| − | * | + | * Link-Time Optimization (LTO) for the runtime libraries by recompiling with <tt>-flto</tt>, which produces smaller binaries and may show significant performance gains |
| − | * | + | * Adding sanitizer checks via <tt>-fsanitize</tt> |
| − | * Cross-compilation | + | * Cross-compilation for other platforms, as the D runtime and standard library must be generated for your target platform before you can cross-compile and link D executables and shared libraries |
| − | |||
== Prerequisites == | == Prerequisites == | ||
* [https://cmake.org/download/ CMake] | * [https://cmake.org/download/ CMake] | ||
| − | * Either [https://www.gnu.org/software/make/ Make] or [https://github.com/ninja-build/ninja/releases Ninja] (recommended, enable with <tt>--ninja</tt>) | + | * Either [https://www.gnu.org/software/make/ Make], the default, or [https://github.com/ninja-build/ninja/releases Ninja] (recommended, enable with <tt>--ninja</tt>) |
* C toolchain (compiler, linker and libraries): gcc, clang, Microsoft Visual C++, … | * C toolchain (compiler, linker and libraries): gcc, clang, Microsoft Visual C++, … | ||
| Line 20: | Line 19: | ||
* Creating a build directory | * Creating a build directory | ||
* Downloading & extracting the LDC source archive matching the LDC version | * Downloading & extracting the LDC source archive matching the LDC version | ||
| − | * Invoking CMake to generate the | + | * Invoking CMake to generate the Make or Ninja build script for the runtime libraries |
| − | * | + | * Calling Make or Ninja to build the runtime libraries |
| − | The libraries end up in the <tt>lib</tt> subdirectory of the build directory, i.e. | + | The runtime libraries end up in the <tt>lib</tt> subdirectory of the build directory, i.e. <tt>./ldc-build-runtime.tmp/lib</tt> by default. You can replace your existing LDC runtime libraries or link against the new libraries by specifying their directory in the LDC command line: <tt>ldc2 … -L-L/path/to/ldc-build-runtime.tmp/lib</tt>. |
== Basic usage == | == Basic usage == | ||
| Line 30: | Line 29: | ||
<pre> | <pre> | ||
| − | ldc-build-runtime [--ninja] [-j4] [--testrunners] [--dFlags=…] [--cFlags=…] [--linkerFlags=…] [CMAKE_VAR1=value1] [CMAKE_VAR2=value2 …] | + | ldc-build-runtime [--ninja] [-j4] [--testrunners] [--targetPreset=…] [--dFlags=…] [--cFlags=…] [--linkerFlags=…] [CMAKE_VAR1=value1] [CMAKE_VAR2=value2 …] |
</pre> | </pre> | ||
| − | + | For example, to prepare for link-time optimization between your user code and the static runtime libraries, you can recompile the runtime libraries with: | |
<pre> | <pre> | ||
| Line 39: | Line 38: | ||
</pre> | </pre> | ||
| − | OSX only: a ThinLTO version of the standard library will result in linker errors due to this issue: https://github.com/ldc-developers/ldc/issues/2312 | + | OSX only: a ThinLTO version of the standard library will result in linker errors due to this issue: https://github.com/ldc-developers/ldc/issues/2312 (not an issue if gold or lld is used) |
== Usage for cross-compilation == | == Usage for cross-compilation == | ||
| Line 60: | Line 59: | ||
</pre> | </pre> | ||
| − | Cross-compiling to Android/ARM using the Android NDK is more involved, so LDC features a [https://github.com/ldc-developers/ldc/blob/master/runtime/PresetRuntimeConfiguration.cmake target preset] | + | Cross-compiling to Android/ARM using the Android NDK is more involved, so LDC features a [https://github.com/ldc-developers/ldc/blob/master/runtime/PresetRuntimeConfiguration.cmake target configuration preset for Android]. On Linux/x86_64, set the path to your NDK's C cross-compiler and simply specify the Android target configuration which has been preset for you, while still being able to override the C and linker flags or append your own D flags, by passing those flags in yourself: |
<pre> | <pre> | ||
| − | export | + | export CC=/path/to/your/android-ndk-r15c/toolchains/llvm/prebuilt/linux-x86_64/bin/clang |
| − | + | ldc-build-runtime [--ninja] [--testrunners] --targetPreset=Android-arm | |
| − | ldc-build-runtime --ninja [--testrunners] --targetPreset=Android-arm | ||
</pre> | </pre> | ||
| − | |||
| − | |||
[[Category:LDC]] | [[Category:LDC]] | ||
Revision as of 10:18, 12 September 2017
Starting with version 1.4, LDC ships with a small build tool to allow you to recompile the D runtime and standard library (and optionally the accompanying testrunners) the way you want, ldc-build-runtime.
Use cases
- Link-Time Optimization (LTO) for the runtime libraries by recompiling with -flto, which produces smaller binaries and may show significant performance gains
- Adding sanitizer checks via -fsanitize
- Cross-compilation for other platforms, as the D runtime and standard library must be generated for your target platform before you can cross-compile and link D executables and shared libraries
Prerequisites
- CMake
- Either Make, the default, or Ninja (recommended, enable with --ninja)
- C toolchain (compiler, linker and libraries): gcc, clang, Microsoft Visual C++, …
How it works
If run without special command-line options, ldc-build-runtime automates:
- Creating a build directory
- Downloading & extracting the LDC source archive matching the LDC version
- Invoking CMake to generate the Make or Ninja build script for the runtime libraries
- Calling Make or Ninja to build the runtime libraries
The runtime libraries end up in the lib subdirectory of the build directory, i.e. ./ldc-build-runtime.tmp/lib by default. You can replace your existing LDC runtime libraries or link against the new libraries by specifying their directory in the LDC command line: ldc2 … -L-L/path/to/ldc-build-runtime.tmp/lib.
Basic usage
The primary aim is to allow specifying additional compiler/linker command-line options and customizing CMake variables.
Run ldc-build-runtime -h for the full list of command-line options.
ldc-build-runtime [--ninja] [-j4] [--testrunners] [--targetPreset=…] [--dFlags=…] [--cFlags=…] [--linkerFlags=…] [CMAKE_VAR1=value1] [CMAKE_VAR2=value2 …]
For example, to prepare for link-time optimization between your user code and the static runtime libraries, you can recompile the runtime libraries with:
ldc-build-runtime --ninja --dFlags="-flto=full" BUILD_SHARED_LIBS=OFF
OSX only: a ThinLTO version of the standard library will result in linker errors due to this issue: https://github.com/ldc-developers/ldc/issues/2312 (not an issue if gold or lld is used)
Usage for cross-compilation
CC=cross-gcc ldc-build-runtime [--ninja] [-j4] [--testrunners] --dFlags="-mtriple=…;…" [--cFlags=…] [--linkerFlags=…] --targetSystem=… …
For example, to cross-compile from Linux/x86_64 to Linux/ARM:
CC=arm-linux-gnueabihf-gcc ldc-build-runtime --ninja --dFlags="-w;-mtriple=arm-linux-gnueabihf" --targetSystem="Linux;UNIX"
From Windows to Linux/ARM, e.g., by using an official Raspberry PI toolchain:
set CC=arm-linux-gnueabihf-gcc ldc-build-runtime --ninja --dFlags=-w;-mtriple=arm-linux-gnueabihf --targetSystem=Linux;UNIX CMAKE_SYSTEM_NAME=Linux CMAKE_C_COMPILER_WORKS=True BUILD_SHARED_LIBS=OFF
Cross-compiling to Android/ARM using the Android NDK is more involved, so LDC features a target configuration preset for Android. On Linux/x86_64, set the path to your NDK's C cross-compiler and simply specify the Android target configuration which has been preset for you, while still being able to override the C and linker flags or append your own D flags, by passing those flags in yourself:
export CC=/path/to/your/android-ndk-r15c/toolchains/llvm/prebuilt/linux-x86_64/bin/clang ldc-build-runtime [--ninja] [--testrunners] --targetPreset=Android-arm
