Difference between revisions of "Using LDC"

From D Wiki
Jump to: navigation, search
(Add command line options for ldc2. Probably need to clean up the formatting a bit.)
m
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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'', which offers many customization options, some of which are internal to LLVM, and ''ldmd2'', which tries to accurately replicate the DMD command line interface and can be used as a drop-in replacement for DMD.
+
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.<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.
  
== Configuration file search path ==
+
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 looks for a file called ldc.conf resp. ldc2.conf in the follow directories in order:
+
== ldc2 command-line options ==
 +
 
 +
* Use <code>ldc2 -h</code> for the list of basic options.
 +
* Use <code>ldc2 -help-hidden</code> 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 <code>-O -release</code>.
 +
** Use <code>-mattr</code> or <code>-mcpu</code> to enable advanced instructions and exploit wider SIMD registers. To tailor to the host CPU, use <code>-mcpu=native</code>.
 +
** 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.
 +
* 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 ==
 +
 
 +
LDC looks for an <tt>ldc2.conf</tt> file in the following directories:
 
# current working directory
 
# current working directory
# next to binary
+
# next to ldc2 executable
# ~/.ldc
+
# <tt>~/.ldc</tt> (Windows: <tt>%APPDATA%\.ldc</tt>)
# user home directory (Windows-only)
+
# Windows only: <tt>%APPDATA%</tt>
# in an etc directory next to the directory where the binary resides
+
# in the <tt>etc</tt> directory next to the directory containing the ldc2 executable
# install-prefix (Windows-only)
+
# non-Windows: <tt><install-prefix>/etc</tt>
# install-prefix/etc
+
# non-Windows: <tt><install-prefix>/etc/ldc</tt>
# install-prefix/etc/ldc
+
# non-Windows: <tt>/etc</tt>
# /etc
+
# non-Windows: <tt>/etc/ldc</tt>
# /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 <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).
  
== ldc2 command line options ==
+
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 troubleshooting linking issues, you can add <tt>-v</tt> to the ldc2 cmdline to have it output the invoked linker/cc cmdline.
| -D
 
| Generate Documentation
 
|-
 
|  -Dd=<docdir>                         
 
| Write documentation file to <docdir> directory
 
|-
 
|  -Df=<filename>                       
 
|  Write documentation file to <filename>
 
|-
 
|  -H                                             
 
| Generate 'header' file
 
|-
 
|  -Hd=<hdrdir>                     
 
| Write 'header' file to <hdrdir> directory
 
|-
 
|  -Hf=<filename>                         
 
| Write 'header' file to <filename>
 
|-
 
|  -Hkeep-all-bodies                     
 
| Keep all function bodies in .di files
 
|-
 
|  -I=<path>                               
 
| Where to look for imports
 
|-
 
|  -J=<path>                               
 
| Where to look for string imports
 
|-
 
|  -L=<linkerflag>                         
 
| Pass <linkerflag> to the linker
 
|-
 
|  Setting the optimization level:
 
|-
 
|    -O                                   
 
|Equivalent to -O3
 
|-
 
|    -O0                                   
 
| No optimizations (default)
 
|-
 
|    -O1                                   
 
| Simple optimisations
 
|-
 
|    -O2                                   
 
| Good optimisations
 
|-
 
|    -O3                                   
 
| Aggressive optimisations
 
|-
 
|    -O4                                   
 
| Equivalent to -O3
 
|-
 
|    -O5                                   
 
| Equivalent to -O3
 
|-
 
|    -Os                                   
 
|Like -O2 with extra optimizations for size
 
|-
 
|    -Oz                                   
 
| Like -Os but reduces code size further
 
|-
 
|  -X                                     
 
| Generate JSON file
 
|-
 
|  -Xf=<filename>                         
 
| Write JSON file to <filename>
 
|-
 
|  -aarch64-neon-syntax                   
 
| Choose style of NEON code to emit from AArch64 backend:
 
|-
 
|    =generic                             
 
|  Emit generic NEON assembly
 
|-
 
|    =apple                               
 
|  Emit Apple-style NEON assembly
 
|-
 
|  -allinst                               
 
| generate code for all template instantiations
 
|-
 
|  -boundscheck                           
 
| Enable array bounds check
 
|-
 
|    =off                                 
 
| no array bounds checks
 
|-
 
|    =safeonly                             
 
|  array bounds checks for safe functions only
 
|-
 
|    =on                                   
 
|  array bounds checks for all functions
 
|-
 
|  -c                                     
 
| Do not link
 
|-
 
|  -check-printf-calls                     
 
| Validate printf call format strings against arguments
 
|-
 
|  -code-model                           
 
| Code model
 
|-
 
|    =default                             
 
|  Target default code model
 
|-
 
|    =small                               
 
|  Small code model
 
|-
 
|    =kernel                               
 
|  Kernel code model
 
|-
 
|    =medium                               
 
|  Medium code model
 
|-
 
|    =large                               
 
|  Large code model
 
|-
 
|  -conf=<filename>                       
 
| Use configuration file <filename>
 
|-
 
|  -cov                                   
 
| Compile-in code coverage analysis (use -cov=n for n% minimum required coverage)
 
|-
 
| Allow deprecated code/language features:
 
|-
 
|    -de                                 
 
| Do not allow deprecated features
 
|-
 
|    -d                                   
 
| Silently allow deprecated features
 
|-
 
|    -dw                                 
 
| Warn about the use of deprecated features
 
|-
 
|  -d-debug=<level/idents>                 
 
| Compile in debug code >= <level> or identified by <idents>.
 
|-
 
|  -d-version=<level/idents>             
 
| Compile in version code >= <level> or identified by <idents>
 
|-
 
|  -debuglib=<lib1,lib2,...>             
 
| Debug versions of default libraries (overrides previous)
 
|-
 
|  -defaultlib=<lib1,lib2,...>            
 
| Default libraries to link with (overrides previous)
 
|-
 
|  -deps=<filename>                       
 
| Write module dependencies to filename (only imports)
 
|-
 
|  -dip25                                 
 
| implement http://wiki.dlang.org/DIP25 (experimental)
 
|-
 
|  -enable-asserts                         
 
| (*) Enable assertions
 
|-
 
|    =enable-asserts                     
 
|  (*) Enable assertions
 
|-
 
|  -enable-color                         
 
| Force colored console output
 
|-
 
|    =enable-color                         
 
|  Force colored console output
 
|-
 
|  -disable-d-passes                       
 
| Disable all D-specific passes
 
|-
 
|  -disable-fp-elim                       
 
| Disable frame pointer elimination optimisation
 
|-
 
|  -disable-gc2stack                     
 
| Disable promotion of GC allocations to stack memory
 
|-
 
|  -enable-inlining                       
 
| Enable function inlining (default in -O2 and higher)
 
|-
 
|    =enable-inlining                     
 
|  Enable function inlining (default in -O2 and higher)
 
|-
 
|  -enable-invariants                     
 
| (*) Enable invariants
 
|-
 
|    =enable-invariants                   
 
|  (*) Enable invariants
 
|-
 
|  -disable-linker-strip-dead             
 
| Do not try to remove unused symbols during linking
 
|-
 
|  -disable-loop-unrolling               
 
| Disable loop unrolling in all relevant passes
 
|-
 
|  -disable-loop-vectorization           
 
| Disable the loop vectorization pass
 
|-
 
|  -enable-preconditions                 
 
| (*) Enable function preconditions
 
|-
 
|    =enable-preconditions               
 
|  (*) Enable function preconditions
 
|-
 
|  -disable-red-zone                     
 
| Do not emit code that uses the red zone.
 
|-
 
|  -disable-simplify-drtcalls             
 
| Disable simplification of druntime calls
 
|-
 
|  -disable-simplify-libcalls             
 
| Disable simplification of well-known C runtime calls
 
|-
 
|  -disable-slp-vectorization           
 
| Disable the slp vectorization pass
 
|-
 
|  -enable-contracts                     
 
| (*) Enable function pre- and post-conditions
 
|-
 
|    =enable-contracts                   
 
|  (*) Enable function pre- and post-conditions
 
|-
 
|  -enable-postconditions                 
 
| (*) Enable function postconditions
 
|-
 
|    =enable-postconditions             
 
|  (*) Enable function postconditions
 
|-
 
|  -float-abi                             
 
| ABI/operations to use for floating-point types:
 
|-
 
|    =default                             
 
|  Target default floating-point ABI
 
|-
 
|    =soft                               
 
|  Software floating-point ABI and operations
 
|-
 
|    =softfp                             
 
|  Soft-float ABI, but hardware floating-point instructions
 
|-
 
|    =hard                               
 
|  Hardware floating-point ABI and instructions
 
|-
 
|  -fthread-model                         
 
| Thread model
 
|-
 
|  =global-dynamic                     
 
|  Global dynamic TLS model (default)
 
|-
 
|    =local-dynamic                     
 
|  Local dynamic TLS model
 
|-
 
|    =initial-exec                       
 
|  Initial exec TLS model
 
|-
 
|    =local-exec                         
 
|  Local exec TLS model
 
|-
 
|  Generating debug information:
 
|-
 
|    -g                                   
 
| Generate debug information
 
|-
 
|    -gc                                   
 
| Same as -g, but pretend to be C
 
|-
 
|  -hash-threshold=<uint>                 
 
| hash symbol names longer than this threshold (experimental)
 
|-
 
|  -help                                   
 
| Display available options (-help-hidden for more)
 
|-
 
|  -ignore                                 
 
| Ignore unsupported pragmas
 
|-
 
|  -ir2obj-cache=<cache dir>             
 
| Use <cache dir> to cache object files for whole IR modules (experimental)
 
|-
 
|  -ir2obj-cache-prune                     
 
| Enable cache pruning.
 
|-
 
|  -ir2obj-cache-prune-expiration=<dur>   
 
| Sets the pruning expiration time of cache files to <dur> seconds (default: 1 week). Implies -ir2obj-cache-prune.
 
|-
 
|  -ir2obj-cache-prune-interval=<dur>     
 
| Sets the cache pruning interval to <dur> seconds (default: 20 min). Set to 0 to force pruning. Implies -ir2obj-cache-prune.
 
|-
 
|  -ir2obj-cache-prune-maxbytes=<size>     
 
| Sets the maximum cache size to <size> bytes. Implies -ir2obj-cache-prune.
 
|-
 
|  -ir2obj-cache-prune-maxpercentage=<perc>
 
| Sets the cache size limit to <perc> percent of the available space (default: 75%). Implies -ir2obj-cache-prune.
 
|-
 
|  -lib                                   
 
| Create static library
 
|-
 
|  -link-debuglib                         
 
| Link with libraries specified in -debuglib, not -defaultlib
 
|-
 
|  -linkonce-templates                   
 
| Use linkonce_odr linkage for template symbols instead of weak_odr
 
|-
 
|  -m32                                   
 
| 32 bit target
 
|-
 
|  -m64                                   
 
| 64 bit target
 
|-
 
|  -main                                   
 
| Add empty main() (e.g. for unittesting)
 
|-
 
|  -march=<string>                       
 
| Architecture to generate code for:
 
|-
 
|  -mattr=<a1,+a2,-a3,...>               
 
| Target specific attributes (-mattr=help for details)
 
|-
 
|  -mcpu=<cpu-name>                       
 
| Target a specific cpu type (-mcpu=help for details)
 
|-
 
#|  -mdcompute-targets=<ocl-210,cuda-350> 
 
#| DCompute targets to generate for:OpenCl (ocl-xy0 for x.y) CUDA (cuda-xy0 for cc x.y)
 
#|-
 
|  -mtriple=<string>                      
 
| Override target triple
 
|-
 
|  -noasm                                 
 
| Disallow use of inline assembler
 
|-
 
|  -nogc                                   
 
| Do not allow code that generates implicit garbage collector calls
 
|-
 
|  -o-                                     
 
| Do not write object file
 
|-
 
|  -od=<objdir>                           
 
| Write object files to directory <objdir>
 
|-
 
|  -of=<filename>                         
 
| Use <filename> as output file name
 
|-
 
|  -op                                   
 
| Do not strip paths from source file
 
|-
 
|  -oq                                   
 
| Write object files with fully qualified names
 
|-
 
|  -output-bc                             
 
| Write LLVM bitcode
 
|-
 
|  -output-ll                             
 
| Write LLVM IR
 
|-
 
|  -output-o                             
 
| Write native object
 
|-
 
|  -output-s                             
 
| Write native assembly
 
|-
 
|  -property                             
 
| Enforce property syntax
 
|-
 
|  -release                               
 
| Disables asserts, invariants, contracts and boundscheck
 
|-
 
|  -relocation-model                     
 
| Relocation model
 
|-
 
|    =default                           
 
|  Target default relocation model
 
|-
 
|    =static                             
 
|  Non-relocatable code
 
|-
 
|    =pic                                 
 
|  Fully relocatable, position independent code
 
|-
 
|    =dynamic-no-pic                     
 
|  Relocatable external references, non-relocatable code
 
|-
 
|  -run=<string>                         
 
| Runs the resulting program, passing the remaining arguments to it
 
|-
 
|  -sanitize                               
 
| Enable runtime instrumentation for bug detection
 
|-
 
|    =address                           
 
|  memory errors
 
|-
 
|    =memory                             
 
|  memory errors
 
|-
 
|    =thread                             
 
|  race detection
 
|-
 
|  -shared                                 
 
| Create shared library
 
|-
 
|  -singleobj                             
 
| Create only a single output object file
 
|-
 
|  -static                                 
 
| Create a statically linked binary, including all system dependencies
 
|-
 
|  -template-depth=<uint>             
 
| (experimental) set maximum number of nested template instantiations
 
|-
 
|  -transition=<idents>                 
 
| help with language change identified by <idents>, use ? for list
 
|-
 
|  -unittest                             
 
| Compile in unit tests
 
|-
 
|  -v                                     
 
| Verbose
 
|-
 
|  -v-cg                                 
 
| Verbose codegen
 
|-
 
|  -vcolumns                           
 
| print character (column) numbers in diagnostics
 
|-
 
|  -verrors=<uint>                   
 
| limit the number of error messages (0 means unlimited)
 
|-
 
|  -version                             
 
|-
 
| Display the version of this program
 
|-
 
|  -vgc                                 
 
| list all gc allocations including hidden ones
 
|-
 
|  -vv                                   
 
| Print front-end/glue code debug log
 
|-
 
|  Warnings:
 
|-
 
|  -w                                 
 
| Enable warnings
 
|-
 
|    -wi                                 
 
| Enable informational warnings
 
|-
 
|  -x86-asm-syntax                 
 
| Choose style of code to emit from X86 backend:
 
|-
 
|    =att                               
 
|  Emit AT&T-style assembly
 
|-
 
|    =intel                             
 
|  Emit Intel-style assembly
 
|-
 
  
|}
 
 
[[Category:LDC]]
 
[[Category:LDC]]

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.