Difference between revisions of "Using LDC"

From D Wiki
Jump to: navigation, search
m (ldc2 command-line options: fix URL)
m
(4 intermediate revisions by one other user not shown)
Line 2: Line 2:
 
* '''ldc2''', the main executable.
 
* '''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.<br> Unlike ldc2, ldmd2 reads the <tt>DFLAGS</tt> environment variable and appends those flags to the underlying ldc2 cmdline (use <tt>-vdmd</tt> to check the ldc2 cmdline).<br>ldmd2 forwards unknown command-line options to ldc2, so advanced LDC-specific command-line options can be used with ldmd2 too.
 
* '''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.<br> Unlike ldc2, ldmd2 reads the <tt>DFLAGS</tt> environment variable and appends those flags to the underlying ldc2 cmdline (use <tt>-vdmd</tt> to check the ldc2 cmdline).<br>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 ==
 
== ldc2 command-line options ==
Line 11: Line 14:
 
** Use <code>-flto=<thin,full></code> to enable [http://johanengelen.github.io/ldc/2016/11/10/Link-Time-Optimization-LDC.html Link-Time Optimization]. Add <code>-defaultlib=phobos2-ldc-lto,druntime-ldc-lto</code> to include LTO-able druntime and Phobos.<br>When generating static LTO libraries, we recommend compiling with <code>-flto=thin</code>. The generated bitcode library can then be used with both <code>-flto=thin</code> and <code>-flto=full</code> when generating the final binary.
 
** Use <code>-flto=<thin,full></code> to enable [http://johanengelen.github.io/ldc/2016/11/10/Link-Time-Optimization-LDC.html Link-Time Optimization]. Add <code>-defaultlib=phobos2-ldc-lto,druntime-ldc-lto</code> to include LTO-able druntime and Phobos.<br>When generating static LTO libraries, we recommend compiling with <code>-flto=thin</code>. The generated bitcode library can then be used with both <code>-flto=thin</code> and <code>-flto=full</code> when generating the final binary.
 
** [http://johanengelen.github.io/ldc/2016/07/15/Profile-Guided-Optimization-with-LDC.html Profile-Guided Optimization] is also available.
 
** [http://johanengelen.github.io/ldc/2016/07/15/Profile-Guided-Optimization-with-LDC.html Profile-Guided Optimization] is also available.
 +
* Use <code>-mtriple</code> 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 ==
 
== Configuration file ==

Revision as of 22:23, 9 May 2020

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).

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.