Using LDC

From D Wiki
Jump to: navigation, search

Generally, LDC should be straightforward to use, like any other compiler. It comes with two different »drivers«, i.e. executables a user invokes to compile D code:

  • ldc2, the main executable.
  • ldmd2, a little wrapper which tries to accurately replicate the DMD command-line interface and can be used as a drop-in replacement for DMD.
    Unlike ldc2, ldmd2 reads the DFLAGS environment variable and appends those flags to the underlying ldc2 cmdline (use -vdmd to check the ldc2 cmdline).
    ldmd2 forwards unknown command-line options to ldc2, so advanced LDC-specific command-line options can be used with ldmd2 too.

LDC also comes with a few tools:

  • ldc-build-runtime, a tool to recompile the D runtime and standard library to your wishes (for example for cross-compiling to a different architecture), see Building LDC runtime libraries.

ldc2 command-line options

  • Use ldc2 -h for the list of basic options.
  • Use ldc2 -help-hidden for the huge list of all available options, most of which are advanced LLVM configuration options for fine-tuning.
  • Optimized release builds usually don't need much more than -O -release.
    • Use -mattr or -mcpu to enable advanced instructions and exploit wider SIMD registers. To tailor to the host CPU, use -mcpu=native.
    • Use -flto=<thin,full> to enable Link-Time Optimization. Add -defaultlib=phobos2-ldc-lto,druntime-ldc-lto to include LTO-able druntime and Phobos.
      When generating static LTO libraries, we recommend compiling with -flto=thin. The generated bitcode library can then be used with both -flto=thin and -flto=full when generating the final binary.
    • Profile-Guided Optimization is also available.
  • Use -mtriple to select the target architecture (CPU) and OS. LDC is an implicit cross-compiler, meaning that one binary of LDC can compile to many targets, see Cross-compiling with LDC.

Configuration file

LDC looks for an ldc2.conf file in the following directories:

  1. current working directory
  2. next to ldc2 executable
  3. ~/.ldc (Windows: %APPDATA%\.ldc)
  4. Windows only: %APPDATA%
  5. in the etc directory next to the directory containing the ldc2 executable
  6. non-Windows: <install-prefix>/etc
  7. non-Windows: <install-prefix>/etc/ldc
  8. non-Windows: /etc
  9. non-Windows: /etc/ldc

The file should be self-descriptive. Besides tweaking default cmdline options, its main usage is to set up cross-compilation, see Cross-compiling with LDC.

Linking

For most targets, LDC depends on a suitable installed C toolchain (e.g., gcc or clang) for linking executables and shared libraries, because druntime and Phobos build on top of a C runtime (glibc, musl, Visual C++, Bionic, …).

Windows is an exception, where LDC provides built-in linking via -link-internally and ships with custom WinSDK and MSVC import libraries (for convenience). A Visual C++ installation is still recommended though (e.g., for static linking, to prevent a MSVC runtime dependency of generated binaries). A Visual C++ installation is automatically detected in the linking step and thus is always preferred by the compiler. If no installation is found, the -link-internally flag is internally used.

For Posix targets, the default linker driver is the C compiler, cc (or the one specified in the CC environment variable). Name/path can be explicitly specified via the -gcc cmdline option.

For troubleshooting linking issues, you can add -v to the ldc2 cmdline to have it output the invoked linker/cc cmdline.