/LTCG (Link-time Code Generation)
The latest version of this topic can be found at -LTCG (Link-time Code Generation).
LTCG[:INCREMENTAL|:NOSTATUS|:STATUS|:OFF|:PGINSTRUMENT|:PGOPTIMIZE|:PGUPDATE]
## Remarks
:INCREMENTAL (optional)
Specifies that the linker only applies whole program optimization or link-time code generation (LTCG) to the set of files affected by an edit, instead of the entire project. By default, this flag is not set when /LTCG is specified, and the entire project is linked by using whole program optimization.
:NOSTATUS | :STATUS (optional)
Specifies whether the linker displays a progress indicator that shows what percentage of the link is complete. By default, this status information is not displayed.
:OFF (optional)
Disables link-time code generation. This behavior is the same as when /LTCG is not specified on the command line.
:PGINSTRUMENT (optional)
This option is deprecated. Instead, use **/LTCG** and **/GENPROFILE** or **/FASTGENPROFILE** to generate an instrumented build for profile-guided optimization.
The data that is collected from instrumented runs is used to create an optimized image. For more information, see [Profile Guided Optimization](../Topic/Profile-Guided%20Optimizations.md). The short form of this option is /LTCG:PGI.
:PGOPTIMIZE (optional)
This option is deprecated. Instead, use **/LTCG** and **/USEPROFILE** to build an optimized image. For more information, see [Profile Guided Optimization](../Topic/Profile-Guided%20Optimizations.md). The short form of this option is /LTCG:PGO.
:PGUPDATE (optional)
This option is deprecated. Instead, use **/LTCG** and **/USEPROFILE** to build an optimized image. For more information, see [Profile Guided Optimization](../Topic/Profile-Guided%20Optimizations.md). The short form of this option is /LTCG:PGU.
The /LTCG option tells the linker to call the compiler and perform whole-program optimization. You can also do profile guided optimization. For more information, see [Profile Guided Optimization](../Topic/Profile-Guided%20Optimizations.md).
With the following exceptions, you cannot add linker options to the PGO combination of /LTCG and /USEPROFILE that were not specified in the previous PGO initialization combination of /LTCG and /GENPROFILE options:
- [/BASE](../Topic/-BASE%20\(Base%20Address\).md)
- [/FIXED](../Topic/-FIXED%20\(Fixed%20Base%20Address\).md)
- /LTCG
- [/MAP](../Topic/-MAP%20\(Generate%20Mapfile\).md)
- [/MAPINFO](../Topic/-MAPINFO%20\(Include%20Information%20in%20Mapfile\).md)
- [/NOLOGO](../Topic/-NOLOGO%20\(Suppress%20Startup%20Banner\)%20\(Linker\).md)
- [/OUT](../Topic/-OUT%20\(Output%20File%20Name\).md)
- [/PGD](../Topic/-PGD%20\(Specify%20Database%20for%20Profile-Guided%20Optimizations\).md)
- [/PDB](../Topic/-PDB%20\(Use%20Program%20Database\).md)
- [/PDBSTRIPPED](../Topic/-PDBSTRIPPED%20\(Strip%20Private%20Symbols\).md)
- [/STUB](../Topic/-STUB%20\(MS-DOS%20Stub%20File%20Name\).md)
- [/VERBOSE](../Topic/-VERBOSE%20\(Print%20Progress%20Messages\).md)
Any linker options that are specified together with the /LTCG and /GENPROFILE options to initialize PGO do not have to be specified when you build by using /LTCG and /USEPROFILE; they are implied.
The rest of this topic discusses /LTCG in terms of link-time code generation.
/LTCG is implied with [/GL](../Topic/-GL%20\(Whole%20Program%20Optimization\).md).
The linker invokes link-time code generation if it is passed a module that was compiled by using **/GL** or an MSIL module (see [.netmodule Files as Linker Input](../Topic/.netmodule%20Files%20as%20Linker%20Input.md)). If you do not explicitly specify **/LTCG** when you pass **/GL** or MSIL modules to the linker, the linker eventually detects this and restarts the link by using **/LTCG**. Explicitly specify **/LTCG** when you pass **/GL** and MSIL modules to the linker for the fastest possible build performance.
For even faster performance, use **/LTCG:INCREMENTAL**. This option tells the linker to only re-optimize the set of files that is affected by a source file change, instead of the entire project. This can significantly reduce the link time required. This is not the same option as incremental linking.
**/LTCG** is not valid for use with [/INCREMENTAL](../Topic/-INCREMENTAL%20\(Link%20Incrementally\).md).
When **/LTCG** is used to link modules compiled by using [/Og](../Topic/-Og%20\(Global%20Optimizations\).md), [/O1](../Topic/-O1,%20-O2%20\(Minimize%20Size,%20Maximize%20Speed\).md), [/O2](../Topic/-O1,%20-O2%20\(Minimize%20Size,%20Maximize%20Speed\).md), or [/Ox](../Topic/-Ox%20\(Full%20Optimization\).md), the following optimizations are performed:
- Cross-module inlining
- Interprocedural register allocation (64-bit operating systems only)
- Custom calling convention (x86 only)
- Small TLS displacement (x86 only)
- Stack double alignment (x86 only)
- Improved memory disambiguation (better interference information for global variables and input parameters)
> [!NOTE]
> The linker determines which optimizations were used to compile each function and applies the same optimizations at link time.
Using **/LTCG** and **/Ogt** causes double-alignment optimization.
If **/LTCG** and **/Ogs** are specified, double alignment is not performed. If most of the functions in an application are compiled for speed, with a few functions compiled for size (for example, by using the [optimize](../Topic/optimize.md) pragma), the compiler double-aligns the functions that are optimized for size if they call functions that require double alignment.
If the compiler can identify all of the call sites of a function, the compiler ignores explicit calling-convention modifiers on a function and tries to optimize the function's calling convention:
- pass parameters in registers
- reorder parameters for alignment
- remove unused parameters
If a function is called through a function pointer, or if a function is called from outside a module that is compiled by using **/GL**, the compiler does not attempt to optimize the function's calling convention.
> [!NOTE]
> If you use **/LTCG** and redefine mainCRTStartup, your application can have unpredictable behavior that relates to user code that executes before global objects are initialized. There are three ways to address this issue: do not redefine mainCRTStartup, do not compile the file that contains mainCRTStartup by using **/LTCG**, or initialize global variables and objects statically.
## /LTCG and MSIL Modules
Modules that are compiled by using [/GL](../Topic/-GL%20\(Whole%20Program%20Optimization\).md) and [/clr](../Topic/-clr%20\(Common%20Language%20Runtime%20Compilation\).md) can be used as input to the linker when **/LTCG** is specified.
- **/LTCG** can accept native object files, mixed native/managed object files (compiled by using **/clr**), and pure object files (compiled by using **/clr:pure**), and safe object files (compiled by using **/clr:safe**)
- **/LTCG** can accept safe .netmodules, which can be created by using **/clr:safe /LN** in Visual C++ and **/target:module** in any other Visual Studio compiler. .Netmodules produced by using**/clr** or **/clr:pure** are not accepted by **/LTCG**.
- /LTCG:PGI does not accept native modules compiled by using **/GL** and **/clr**, or pure modules (produced by using **/clr:pure**)
#### To set this compiler option in the Visual Studio development environment
1. Open the project **Property Pages** dialog box. See [Working with Project Properties](../Topic/Working%20with%20Project%20Properties.md).
2. Select the **Configuration Properties** folder.
3. Select the **General** property page.
4. Modify the **Whole Program Optimization** property.
You can also apply **/LTCG** to specific builds by choosing **Build**, **Profile Guided Optimization** on the menu bar, or by choosing one of the Profile Guided Optimization options on the shortcut menu for the project.
#### To set this compiler option programmatically
- See [LinkTimeCodeGeneration](assetId:///P:Microsoft.VisualStudio.VCProjectEngine.VCLinkerTool.LinkTimeCodeGeneration?qualifyHint=False&autoUpgrade=True).
## See Also
[Setting Linker Options](../Topic/Setting%20Linker%20Options.md)
[Linker Options](../Topic/Linker%20Options.md)