/INCREMENTAL   (Link Incrementally)

Home |  Overview |  How Do I |  Linker Options

The Link Incrementally (/INCREMENTAL:{YES|NO}) option controls how the linker handles incremental linking. (To find this option in the development environment, click Settings on the Project menu. Then click the Link tab, and click Customize in the Category box.)

By default, the linker runs in incremental mode. To override a default incremental link, clear the Link Incrementally check box (or specify /INCREMENTAL:NO on the command line).

An incrementally linked program is functionally equivalent to a program that is nonincrementally linked. However, because it is prepared for subsequent incremental links, an incrementally linked executable (.EXE) file or dynamic-link library (DLL):

• Is larger than a nonincrementally linked program because of padding of code and data. (Padding allows the linker to increase the size of functions and data without recreating the .EXE file.)
  
  
• May contain jump thunks to handle relocation of functions to new addresses.

Note To ensure that your final release build does not contain padding or thunks, link your program nonincrementally.

To link incrementally regardless of the default, select the Link Incrementally check box (or specify /INCREMENTAL:YES on the command line). When this option is selected, the linker issues a warning if it cannot link incrementally, and then links the program nonincrementally. Certain options and situations override the Link Incrementally (/INCREMENTAL:YES) option.

Most programs can be linked incrementally. However, some changes are too great, and some options are incompatible with incremental linking. LINK performs a full link if any of the following options are specified:

• Link Incrementally is not selected (/INCREMENTAL:NO).
  
  
• COFF Format (/DEBUGTYPE:COFF) is selected.
  
  
• Both Formats (/DEBUGTYPE:BOTH) is selected.
  
  
• /OPT:REF is selected.
  
  
• /OPT:ICF is selected.
  
  
• /ORDER is selected.
  
  
• Use Program Database is not selected (/PDB:NONE) when Generate Debug Info (/DEBUG) is selected.

Additionally, LINK performs a full link if any of the following situations occur:

• The incremental status (.ILK) file is missing. (LINK creates a new .ILK file in preparation for subsequent incremental linking.)
  
  
• There is no write permission for the .ILK file. (LINK ignores the .ILK file and links nonincrementally.)
  
  
• The .EXE or .DLL output file is missing.
  
  
• The timestamp of the .ILK, .EXE, or .DLL is changed.
  
  
• A LINK option is changed. Most LINK options, when changed between builds, cause a full link.
  
  
• An object (.OBJ) file is added or omitted.
  
  
• An object that was compiled with the /Yu /Z7 option is changed.