lld/docs/windows_support.rst

   1 .. raw:: html
   2
   3   <style type="text/css">
   4     .none { background-color: #FFCCCC }
   5     .partial { background-color: #FFFF99 }
   6     .good { background-color: #CCFF99 }
   7   </style>
   8
   9 .. role:: none
  10 .. role:: partial
  11 .. role:: good
  12
  13 ===============
  14 Windows support
  15 ===============
  16
  17 LLD supports Windows operating system. When invoked as ``lld-link.exe`` or with
  18 ``-flavor link``, the driver for Windows operating system is used to parse
  19 command line options, and it drives further linking processes. LLD accepts
  20 almost all command line options that the linker shipped with Microsoft Visual
  21 C++ (link.exe) supports.
  22
  23 The current status is that LLD is used to link production builds of large
  24 real-world binaries such as Firefox and Chromium.
  25
  26 Development status
  27 ==================
  28
  29 Driver
  30   :good:`Mostly done`. Some exotic command line options that are not usually
  31   used for application development, such as ``/DRIVER``, are not supported.
  32
  33 Linking against DLL
  34   :good:`Done`. LLD can read import libraries needed to link against DLL. Both
  35   export-by-name and export-by-ordinal are supported.
  36
  37 Linking against static library
  38   :good:`Done`. The format of static library (.lib) on Windows is actually the
  39   same as on Unix (.a). LLD can read it.
  40
  41 Creating DLL
  42   :good:`Done`. LLD creates a DLL if ``/DLL`` option is given. Exported
  43   functions can be specified either via command line (``/EXPORT``) or via
  44   module-definition file (.def). Both export-by-name and export-by-ordinal are
  45   supported.
  46
  47 Windows resource files support
  48   :good:`Done`. If an ``.res`` file is given, LLD converts the file to a COFF
  49   file using LLVM's Object library.
  50
  51 Safe Structured Exception Handler (SEH)
  52   :good:`Done` for both x86 and x64.
  53
  54 Module-definition file
  55   :partial:`Partially done`. LLD currently recognizes these directives:
  56   ``EXPORTS``, ``HEAPSIZE``, ``STACKSIZE``, ``NAME``, and ``VERSION``.
  57
  58 Debug info
  59   :good:`Done`.  LLD can emit PDBs that are at parity with those generated by
  60   link.exe.  However, LLD does not support /DEBUG:FASTLINK.
  61
  62
  63 Downloading LLD
  64 ===============
  65
  66 The Windows version of LLD is included in the `pre-built binaries of LLVM's
  67 releases <https://releases.llvm.org/download.html>`_ and in the `LLVM Snapshot
  68 Builds <https://llvm.org/builds/>`_.
  69
  70 Building LLD
  71 ============
  72
  73 Using Visual Studio IDE/MSBuild
  74 -------------------------------
  75
  76 1. Check out LLVM and LLD from the LLVM SVN repository (or Git mirror),
  77 #. run ``cmake -G "Visual Studio 12" <llvm-source-dir>`` from VS command prompt,
  78 #. open LLVM.sln with Visual Studio, and
  79 #. build ``lld`` target in ``lld executables`` folder
  80
  81 Alternatively, you can use msbuild if you don't like to work in an IDE::
  82
  83   msbuild LLVM.sln /m /target:"lld executables\lld"
  84
  85 MSBuild.exe had been shipped as a component of the .NET framework, but since
  86 2013 it's part of Visual Studio. You can find it at "C:\\Program Files
  87 (x86)\\msbuild".
  88
  89 You can build LLD as a 64 bit application. To do that, open VS2013 x64 command
  90 prompt and run cmake for "Visual Studio 12 Win64" target.
  91
  92 Using Ninja
  93 -----------
  94
  95 1. Check out LLVM and LLD from the LLVM SVN repository (or Git mirror),
  96 #. run ``cmake -G ninja <llvm-source-dir>`` from VS command prompt,
  97 #. run ``ninja lld``
  98
  99 Extensions
 100 ==========
 101
 102 LLD flags
 103 ---------
 104
 105 * ``/build-id``: Always generate GUID hash. When PDB is generated, LLD uses PDB
 106   content hash for GUID. Otherwise, LLD uses output binary content hash for GUID.
 107   LLD also provides ``__buildid`` symbol pointing to the 16 bytes GUID hash if
 108   there is a reference to it.