Documentation Index
Fetch the complete documentation index at: https://mintlify.com/MicrosoftDocs/cpp-docs/llms.txt
Use this file to discover all available pages before exploring further.
link.exe (LINK) is the Microsoft linker. It takes COFF object files (.obj), import libraries (.lib), and resource files (.res) as input and produces executables (.exe), dynamic-link libraries (.dll), and static libraries managed by lib.exe. LINK is automatically invoked when you compile and link in a single cl.exe command, or you can call it directly for finer control. Linker options are not case-sensitive — /out and /OUT are equivalent.
Linker options can be specified on the command line, in a response file (@file.rsp), or via #pragma comment(linker, "/OPTION") in source code.
link.exe must be run from a Visual Studio Developer Command Prompt or after calling vcvarsall.bat. See Building from the Command Line for environment setup.Output File Options
Control where and how the linker writes its output.
| Option | Description |
|---|
/OUT:<file> | Specifies the name of the output file (.exe or .dll) |
/PDB:<file> | Creates a Program Database file with debug symbols |
/PDBSTRIPPED:<file> | Creates a PDB with private symbols stripped (for distribution) |
/MAP[:<file>] | Generates a map file listing all public symbols, section layout, and entry points |
/MAPINFO:EXPORTS | Include exported functions in the map file |
/ILK:<file> | Override the default name of the incremental link database |
# Specify output name and PDB location
link /OUT:bin\myapp.exe /PDB:symbols\myapp.pdb main.obj engine.obj
# Generate a map file for symbol analysis
link /OUT:bin\myapp.exe /MAP:bin\myapp.map /MAPINFO:EXPORTS main.obj
# Create a stripped PDB for distribution (no private symbols)
link /OUT:bin\myapp.exe ^
/PDB:internal\myapp.pdb ^
/PDBSTRIPPED:dist\myapp_public.pdb ^
main.obj engine.obj
Library Options
Control which libraries are searched and how they are found.
| Option | Description |
|---|
/LIBPATH:<dir> | Add a directory to the library search path (checked before LIB environment variable) |
/DEFAULTLIB:<lib> | Add a library to the default set linked at the end |
/NODEFAULTLIB[:<lib>] | Ignore all (or a named) default library; useful for custom CRT or OS-level code |
/WHOLEARCHIVE[:<lib>] | Include all object files from the specified static library (overrides dead-stripping) |
# Add a custom library directory and link a specific library
link /LIBPATH:C:\libs\mylib\lib\x64 ^
/OUT:myapp.exe ^
myapp.obj mylib.lib kernel32.lib
# Ignore all default libraries and provide your own
link /NODEFAULTLIB ^
/OUT:myruntimelib.exe ^
main.obj myruntime.lib
# Force all object files from a static library to be included
link /WHOLEARCHIVE:plugins.lib /OUT:host.exe host.obj kernel32.lib
Subsystem Options
The /SUBSYSTEM option tells the Windows loader which entry point to expect and how to launch the process.
| Option | Entry Point | Use Case |
|---|
/SUBSYSTEM:CONSOLE | main() / wmain() | Command-line applications; allocates a console window |
/SUBSYSTEM:WINDOWS | WinMain() / wWinMain() | GUI applications; no console window |
/SUBSYSTEM:NATIVE | NtProcessStartup() | Device drivers and NT native applications |
/SUBSYSTEM:EFI_APPLICATION | — | UEFI applications |
# Console application (default for most C++ programs)
link /SUBSYSTEM:CONSOLE /OUT:myapp.exe main.obj kernel32.lib
# GUI Windows application
link /SUBSYSTEM:WINDOWS /OUT:mygui.exe winmain.obj user32.lib gdi32.lib kernel32.lib
# Specify minimum required Windows version (Windows 10 = 10.0)
link /SUBSYSTEM:CONSOLE,10.0 /OUT:myapp.exe main.obj kernel32.lib
Debug Options
| Option | Description |
|---|
/DEBUG | Generate debug info (full PDB); implies /OPT:NOREF /OPT:NOICF |
/DEBUG:FASTLINK | Create a PDB that references object file debug info rather than copying it — much faster for large builds, unsuitable for distribution |
/DEBUG:FULL | Copy all debug info into the PDB (default when /DEBUG is alone) |
/DEBUGTYPE:<type> | Controls what data goes into the debug info (e.g., CV, PDATA, FIXUP) |
# Standard debug build with full PDB
link /DEBUG /OUT:myapp.exe main.obj engine.obj
# Fast linking during development (PDB references obj files, not self-contained)
link /DEBUG:FASTLINK /OUT:myapp.exe main.obj engine.obj
# Release build with distributable PDB
link /DEBUG:FULL /OPT:REF /OPT:ICF /OUT:myapp.exe main.obj engine.obj
Optimization Options
| Option | Description |
|---|
/OPT:REF | Eliminate unreferenced functions and data (COMDATs) — enabled by default in release builds |
/OPT:NOREF | Keep all functions and data even if not referenced |
/OPT:ICF[=n] | Identical COMDAT Folding — merge duplicate functions/data to reduce size. n is iteration count |
/OPT:NOICF | Disable COMDAT folding |
/LTCG | Link-Time Code Generation — enables whole-program optimization across all modules |
/LTCG:INCREMENTAL | Incremental LTCG — reoptimize only changed files for faster incremental links |
/OPT:LBR | Long Branch Reduction for ARM binaries |
# Typical release build optimizations
link /OPT:REF /OPT:ICF /OUT:myapp.exe main.obj engine.obj kernel32.lib
# Full whole-program optimization with LTCG
# (requires all .obj files compiled with /GL)
link /LTCG /OPT:REF /OPT:ICF /OUT:myapp.exe main.obj engine.obj kernel32.lib
# Incremental LTCG for faster dev-release builds
link /LTCG:INCREMENTAL /OPT:REF /OPT:ICF /OUT:myapp.exe main.obj engine.obj
/OPT:REF and /OPT:ICF are automatically disabled when /DEBUG is specified, since folding functions would break the debugger. For debug builds that still need a small binary, explicitly pass /OPT:REF /OPT:NOICF.
DLL Options
| Option | Description |
|---|
/DLL | Build a dynamic-link library instead of an executable |
/EXPORT:<symbol> | Export a function or variable by name |
/EXPORT:<symbol>,DATA | Export a data symbol |
/IMPLIB:<file> | Override the default name for the generated import library |
/DEF:<file> | Use a Module Definition File (.def) for exports |
/NOENTRY | Create a resource-only DLL with no entry point |
/DYNAMICBASE | Enable ASLR (Address Space Layout Randomization) — enabled by default |
/NXCOMPAT | Mark as Data Execution Prevention (DEP) compatible — enabled by default |
# Create a DLL with an import library
link /DLL ^
/OUT:bin\mylib.dll ^
/IMPLIB:bin\mylib.lib ^
/PDB:bin\mylib.pdb ^
mylib.obj ^
kernel32.lib msvcrt.lib
# Export specific functions
link /DLL /OUT:plugin.dll ^
/EXPORT:PluginInit ^
/EXPORT:PluginShutdown ^
/EXPORT:PluginVersion,DATA ^
plugin.obj kernel32.lib
# Use a .def file for exports
link /DLL /OUT:mylib.dll /DEF:mylib.def mylib.obj kernel32.lib
LIBRARY mylib
EXPORTS
MyFunction @1
MyOtherFunction @2
MyDataVariable @3 DATA
Profile-Guided Optimization (PGO) Linker Options
PGO is a three-step process that requires specific linker options at each stage. See Optimizations for the full workflow.
| Option | PGO Phase | Description |
|---|
/GENPROFILE | Step 1 (Instrument) | Generate a profiling-instrumented build with a .pgd file |
/FASTGENPROFILE | Step 1 (Instrument) | Like /GENPROFILE but uses sampling (faster instrumentation) |
/USEPROFILE | Step 3 (Optimize) | Use collected profile data (.pgd/.pgc) to optimize |
/PGD:<file> | All steps | Specify the .pgd database file |
/LTCG | Steps 1 and 3 | Required for PGO |
# Step 1: Build instrumented binary
link /LTCG /GENPROFILE /PGD:myapp.pgd /OUT:myapp_instr.exe main.obj engine.obj
# Step 2: Run the instrumented binary with representative workloads
myapp_instr.exe --benchmark
# Step 3: Link optimized binary using collected profile data
link /LTCG /USEPROFILE /PGD:myapp.pgd /OUT:myapp_opt.exe main.obj engine.obj
Security and Safety Options
| Option | Description |
|---|
/DYNAMICBASE | Enable ASLR (on by default) |
/NXCOMPAT | Enable DEP/NX (on by default) |
/HIGHENTROPYVA | 64-bit ASLR with high-entropy virtual addresses (on by default for x64) |
/GUARD:CF | Enable Control Flow Guard |
/SAFESEH | Register exception handlers in a safe exception handler table (x86 only) |
/INTEGRITYCHECK | Require a digital signature check at load time |
# Explicitly enable all modern security features
link /DYNAMICBASE /NXCOMPAT /HIGHENTROPYVA /GUARD:CF ^
/OUT:myapp.exe main.obj kernel32.lib
Practical Examples
Console App (Release)
DLL (Release)
Debug Build
link ^
/OUT:bin\myapp.exe ^
/PDB:symbols\myapp.pdb ^
/DEBUG ^
/SUBSYSTEM:CONSOLE ^
/OPT:REF ^
/OPT:ICF ^
/LTCG ^
/DYNAMICBASE ^
/NXCOMPAT ^
obj\release\*.obj ^
kernel32.lib ^
msvcrt.lib ^
user32.lib
link ^
/DLL ^
/OUT:bin\mylib.dll ^
/IMPLIB:bin\mylib.lib ^
/PDB:symbols\mylib.pdb ^
/DEBUG ^
/SUBSYSTEM:WINDOWS ^
/OPT:REF /OPT:ICF ^
/LTCG ^
/EXPORT:MyPublicFunction ^
obj\release\*.obj ^
kernel32.lib msvcrt.lib
link ^
/OUT:bin\debug\myapp.exe ^
/PDB:bin\debug\myapp.pdb ^
/DEBUG:FASTLINK ^
/SUBSYSTEM:CONSOLE ^
/INCREMENTAL ^
obj\debug\*.obj ^
kernel32.lib ^
msvcrtd.lib
Linker Options Quick Reference
| Category | Option | Description |
|---|
| Output | /OUT:<file> | Output file name |
| Output | /PDB:<file> | PDB file name |
| Output | /MAP | Generate map file |
| Output | /IMPLIB:<file> | Import library name |
| Libraries | /LIBPATH:<dir> | Extra library search directory |
| Libraries | /DEFAULTLIB:<lib> | Add to default libraries |
| Libraries | /NODEFAULTLIB | Ignore all default libraries |
| Subsystem | /SUBSYSTEM:CONSOLE | Console application |
| Subsystem | /SUBSYSTEM:WINDOWS | Windows GUI application |
| Debug | /DEBUG | Full debug PDB |
| Debug | /DEBUG:FASTLINK | Fast local PDB |
| Optimization | /OPT:REF | Remove unreferenced code |
| Optimization | /OPT:ICF | Fold identical COMDATs |
| Optimization | /LTCG | Link-time code generation |
| DLL | /DLL | Build a DLL |
| DLL | /EXPORT:<sym> | Export a symbol |
| DLL | /DEF:<file> | Module definition file |
| Security | /DYNAMICBASE | Enable ASLR |
| Security | /GUARD:CF | Control Flow Guard |
| PGO | /GENPROFILE | Instrument for PGO |
| PGO | /USEPROFILE | Optimize using profile data |
