Difference between revisions of "Using LDC"

From D Wiki
Jump to: navigation, search
(ldc2 command-line options)
(Explain how it works internally based on issue https://github.com/ldc-developers/ldc/issues/4441)
 
(One intermediate revision by one other user not shown)
Line 4: Line 4:
  
 
LDC also comes with a few tools:
 
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]].
+
* '''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 14: 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 natively a cross-compiler, meaning that one binary of LDC can compile to many targets, see [[Cross-compiling_with_LDC]].
+
* 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 ==
Line 35: Line 35:
 
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, …).
 
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 <tt>-link-internally</tt> 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).
+
'''Windows''' is an exception, where LDC provides built-in linking via <tt>-link-internally</tt> 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 <tt>-link-internally</tt> flag is internally used.  
  
 
For '''Posix''' targets, the default linker driver is the C compiler, <tt>cc</tt> (or the one specified in the <tt>CC</tt> environment variable). Name/path can be explicitly specified via the <tt>-gcc</tt> cmdline option.
 
For '''Posix''' targets, the default linker driver is the C compiler, <tt>cc</tt> (or the one specified in the <tt>CC</tt> environment variable). Name/path can be explicitly specified via the <tt>-gcc</tt> cmdline option.

Latest revision as of 10:27, 7 August 2023

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.