lld/docs/windows_support.md

```{raw} html
<style type="text/css">
  .none { background-color: #FFCCCC }
  .partial { background-color: #FFFF99 }
  .good { background-color: #CCFF99 }
</style>
```

```{eval-rst}
.. role:: none
.. role:: partial
.. role:: good
```

# Windows support

LLD supports Windows operating system. When invoked as `lld-link.exe` or with
`-flavor link`, the driver for Windows operating system is used to parse
command line options, and it drives further linking processes. LLD accepts
almost all command line options that the linker shipped with Microsoft Visual
C++ (link.exe) supports.

The current status is that LLD is used to link production builds of large
real-world binaries such as Firefox and Chromium.

## Development status

Driver
: {good}`Mostly done`. Some exotic command line options that are not usually
  used for application development, such as `/DRIVER`, are not supported.

Linking against DLL
: {good}`Done`. LLD can read import libraries needed to link against DLL. Both
  export-by-name and export-by-ordinal are supported.

Linking against static library
: {good}`Done`. The format of static library (.lib) on Windows is actually the
  same as on Unix (.a). LLD can read it.

Creating DLL
: {good}`Done`. LLD creates a DLL if `/DLL` option is given. Exported
  functions can be specified either via command line (`/EXPORT`) or via
  module-definition file (.def). Both export-by-name and export-by-ordinal are
  supported.

Windows resource files support
: {good}`Done`. If an `.res` file is given, LLD converts the file to a COFF
  file using LLVM's Object library.

Safe Structured Exception Handler (SEH)
: {good}`Done` for both x86 and x64.

Module-definition file
: {partial}`Partially done`. LLD currently recognizes these directives:
  `EXPORTS`, `HEAPSIZE`, `STACKSIZE`, `NAME`, and `VERSION`.

Debug info
: {good}`Done`. LLD can emit PDBs that are at parity with those generated by
  link.exe. However, LLD does not support /DEBUG:FASTLINK.

## Downloading LLD

The Windows version of LLD is included in the [pre-built binaries of LLVM's
releases](https://releases.llvm.org/download.html) and in the [LLVM Snapshot
Builds](https://llvm.org/builds/).

## Building LLD

### Using Visual Studio IDE/MSBuild

1. Check out LLVM and LLD from the LLVM SVN repository (or Git mirror),
2. run `cmake -G "Visual Studio 12" <llvm-source-dir>` from VS command prompt,
3. open LLVM.sln with Visual Studio, and
4. build `lld` target in `lld executables` folder

Alternatively, you can use msbuild if you don't like to work in an IDE:

```
msbuild LLVM.sln /m /target:"lld executables\lld"
```

MSBuild.exe had been shipped as a component of the .NET framework, but since
2013 it's part of Visual Studio. You can find it at "C:\\Program Files
(x86)\\msbuild".

You can build LLD as a 64-bit application. To do that, open VS2013 x64 command
prompt and run cmake for "Visual Studio 12 Win64" target.

### Using Ninja

1. Check out LLVM and LLD from the LLVM SVN repository (or Git mirror),
2. run `cmake -G ninja <llvm-source-dir>` from VS command prompt,
3. run `ninja lld`

## Extensions

### LLD flags

- `/build-id`: Always generate GUID hash. When PDB is generated, LLD uses PDB
  content hash for GUID. Otherwise, LLD uses output binary content hash for GUID.
  LLD also provides `__buildid` symbol pointing to the 16 bytes GUID hash if
  there is a reference to it.