Bewerken

Delen via

/LTCG (Link-time code generation)

  • Artikel

Use /LTCG to perform whole-program optimization, or to create profile-guided optimization (PGO) instrumentation, perform training, and create profile-guided optimized builds.

Syntax

/LTCG[:{INCREMENTAL|NOSTATUS|STATUS|OFF}]

These options are deprecated starting in Visual Studio 2015:

/LTCG:{PGINSTRUMENT|PGOPTIMIZE|PGUPDATE}

Arguments

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. The linker treats all modules compiled with /GL as if they're compiled without that option, and any MSIL modules cause the link to fail.

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.

Remarks

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. If you remove the /LTCG:INCREMENTAL option, also remove any /LTCGOUT option to improve build times and disk utilization.

/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, 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.

/LTCG and MSIL Modules

Modules that are compiled by using /GL and /clr can be used as input to the linker when /LTCG is specified.

  • /LTCG can accept native object files, and mixed native/managed object files (compiled by using /clr). The /clr:pure and /clr:safe compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later.

  • /LTCG:PGI doesn't accept native modules compiled by using /GL and /clr

To set this compiler option in the Visual Studio development environment

The Whole Program Optimization property sets several compiler and linker options, including /LTCG. We recommend you use this property to change the settings for an entire build configuration. To set Whole Program Optimization for your project:

  1. Open the project Property Pages dialog box. For more information, see Set compiler and build properties.

  2. Select the Configuration Properties > General property page.

  3. Modify the Whole Program Optimization property. Choose OK or Apply to save your changes.

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 enable Link Time Code Generation separately or set a specific Link Time Code Generation option:

  1. Open the project Property Pages dialog box.

  2. Select the Configuration Properties > Linker > Optimization property page.

  3. Modify the Link Time Code Generation property to one of the following options:

    • Default
    • Use Fast Link Time Code Generation (LTCG:incremental)
    • Use Link Time Code Generation (LTCG)
    • Profile Guided Optimization - Instrument (LTCG:PGInstrument)
    • Profile Guided Optimization - Optimization (LTCG:PGOptimize)
    • Profile Guided Optimization - Update (LTCG:PGUpdate)

  4. Choose OK or Apply to save your changes.

To specify whether the linker displays a progress indicator for Link Time Code Generation:

  1. Open the project Property Pages dialog box.

  2. Select the Configuration Properties > Linker > General property page.

  3. Modify the Link Status property. Choose OK or Apply to save your changes.

To set this compiler option programmatically

See also

MSVC linker reference
MSVC linker options