| title | description | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
/LTCG (Link-time code generation) |
The MSVC linker option /LTCG enables link-time code generation for whole-program optimization. |
07/08/2020 |
|
|
788c6f52-fdb8-40c2-90af-4026ea2cf2e2 |
Use /LTCG to perform whole-program optimization, or to create profile-guided optimization (PGO) instrumentation, perform training, and create profile-guided optimized builds.
/LTCG[:{INCREMENTAL|NOSTATUS|STATUS|OFF}]
These options are deprecated starting in Visual Studio 2015:
/LTCG:{PGINSTRUMENT|PGOPTIMIZE|PGUPDATE}
INCREMENTAL
(Optional) Specifies that the linker only applies whole program optimization or link-time code generation (LTCG) to files affected by an edit, instead of the entire project. By default, this flag isn't 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 isn't displayed.
OFF
(Optional) Disables link-time code generation. This behavior is the same as when /LTCG isn't specified on the command line.
PGINSTRUMENT
(Optional) This option is deprecated starting in Visual Studio 2015. 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 Optimizations. The short form of this option is /LTCG:PGI.
PGOPTIMIZE
(Optional) This option is deprecated starting in Visual Studio 2015. Instead, use /LTCG and /USEPROFILE to build an optimized image. For more information, see Profile-Guided Optimizations. The short form of this option is /LTCG:PGO.
PGUPDATE
(Optional) This option is deprecated starting in Visual Studio 2015. Instead, use /LTCG and /USEPROFILE to rebuild an optimized image. For more information, see Profile-Guided Optimizations. 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 Optimizations.
With the following exceptions, you can't add linker options to the PGO combination of /LTCG and /USEPROFILE that weren't specified in the previous PGO initialization combination of /LTCG and /GENPROFILE options:
Any linker options that are specified together with the /LTCG and /GENPROFILE options to initialize PGO don't have to be specified when you build by using /LTCG and /USEPROFILE; they're implied.
The rest of this article discusses the link-time code generation done by /LTCG.
/LTCG is implied with /GL.
The linker invokes link-time code generation if it's passed a module that was compiled by using /GL or an MSIL module (see .netmodule Files as Linker Input). If you don't explicitly specify /LTCG when you pass /GL or MSIL modules to the linker, the linker eventually detects this situation 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 reoptimize only the files affected by a source file change, instead of the entire project. This option can significantly reduce the link time required. This option isn't the same option as incremental linking.
/LTCG isn't valid for use with /INCREMENTAL.
When /LTCG is used to link modules compiled by using /Og, /O1, /O2, or /Ox, 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 /O2 causes double-alignment optimization.
If /LTCG and /O1 are specified, double alignment isn't 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 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 doesn't 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.
Modules that are compiled by using /GL and /clr can be used as input to the linker when /LTCG is specified.
-
/LTCGcan accept native object files, and mixed native/managed object files (compiled by using/clr). The/clr:pureand/clr:safecompiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. -
/LTCG:PGIdoesn't accept native modules compiled by using/GLand/clr
-
Open the project Property Pages dialog box. See Set C++ compiler and build properties in Visual Studio.
-
Select the Configuration Properties > General property page.
-
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.
- See xref:Microsoft.VisualStudio.VCProjectEngine.VCLinkerTool.LinkTimeCodeGeneration%2A.