/LTCG (Link-time Code Generation)
Visual Studio 2015
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
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)
Show: