|
2 | 2 | description: "Learn more about: Linking" |
3 | 3 | title: "MSVC linker reference" |
4 | 4 | ms.date: "12/10/2018" |
5 | | -ms.assetid: bb736587-d13b-4f3c-8982-3cc2c015c59c |
6 | 5 | --- |
7 | 6 | # Linking |
8 | 7 |
|
9 | | -In a C++ project, the *linking* step is performed after the compiler has compiled the source code into object files (*.obj). The linker (link.exe) combines the object files into a single executable file. |
| 8 | +In a C++ project, the *linking* step is performed after the compiler compiles the source code into object files (*.obj). The linker (`link.exe`) combines the object files into a single executable file. |
10 | 9 |
|
11 | 10 | Linker options can be set inside or outside of Visual Studio. Within Visual Studio, you access linker options by right-clicking on a project node in **Solution Explorer** and choosing **Properties** to display the property pages. Choose **Linker** in the left pane to expand the node and see all the options. |
12 | 11 |
|
13 | 12 | ## Linker command-line syntax |
14 | 13 |
|
15 | | -When you run LINK outside of Visual Studio, you can specify input in one or more ways: |
| 14 | +When you run the linker outside of Visual Studio, you can specify input in one or more ways: |
16 | 15 |
|
17 | 16 | - On the command line |
18 | | - |
19 | 17 | - Using command files |
20 | | - |
21 | 18 | - In environment variables |
22 | 19 |
|
23 | | -LINK first processes options specified in the LINK environment variable, followed by options in the order they are specified on the command line and in command files. If an option is repeated with different arguments, the last one processed takes precedence. |
| 20 | +The linker first processes options specified in the `LINK` environment variable, followed by options in the order they're specified on the command line and in command files. If an option is repeated with different arguments, the last one processed takes precedence. |
24 | 21 |
|
25 | 22 | Options apply to the entire build; no options can be applied to specific input files. |
26 | 23 |
|
27 | | -To run LINK.EXE, use the following command syntax: |
| 24 | +To run `link.exe`, use the following command syntax: |
28 | 25 |
|
29 | | -``` |
30 | | -LINK arguments |
| 26 | +```cmd |
| 27 | +link arguments |
31 | 28 | ``` |
32 | 29 |
|
33 | 30 | The `arguments` include options and filenames and can be specified in any order. Options are processed first, then files. Use one or more spaces or tabs to separate arguments. |
34 | 31 |
|
35 | 32 | > [!NOTE] |
36 | | -> You can start this tool only from the Visual Studio command prompt. You cannot start it from a system command prompt or from File Explorer. |
| 33 | +> You can start this tool only from the Visual Studio command prompt. You can't start it from a system command prompt or from File Explorer. |
37 | 34 |
|
38 | 35 | ## Command line |
39 | 36 |
|
40 | | -On the command line, an option consists of an option specifier, either a dash (-) or a forward slash (/), followed by the name of the option. Option names cannot be abbreviated. Some options take an argument, specified after a colon (:). No spaces or tabs are allowed within an option specification, except within a quoted string in the /COMMENT option. Specify numeric arguments in decimal or C-language notation. Option names and their keyword or filename arguments are not case sensitive, but identifiers as arguments are case sensitive. |
| 37 | +On the command line, an option consists of an option specifier, either a dash (`-`) or a forward slash (`/`), followed by the name of the option. Option names can't be abbreviated. Some options take an argument, specified after a colon (`:`). No spaces or tabs are allowed within an option specification, except within a quoted string in the `/COMMENT` option. Specify numeric arguments in decimal or C-language notation. Option names and their keyword or filename arguments aren't case sensitive, but identifiers as arguments are case sensitive. |
41 | 38 |
|
42 | | -To pass a file to the linker, specify the filename on the command line after the LINK command. You can specify an absolute or relative path with the filename, and you can use wildcards in the filename. If you omit the dot (.) and filename extension, LINK assumes .obj for the purpose of finding the file. LINK does not use filename extensions or the lack of them to make assumptions about the contents of files; it determines the type of file by examining it, and processes it accordingly. |
| 39 | +To pass a file to the linker, specify the filename on the command line after the `link.exe` command. You can specify an absolute or relative path with the filename, and you can use wildcards in the filename. If you omit the dot (`.`) and filename extension, the linker assumes an extension of `.obj` to find the file. The linker doesn't use filename extensions or the lack of them to make assumptions about the contents of files. It determines the type of file by examining it, and processes it accordingly. |
43 | 40 |
|
44 | | -link.exe returns zero for success (no errors). Otherwise, the linker returns the error number that stopped the link. For example, if the linker generates LNK1104, the linker returns 1104. Accordingly, the lowest error number returned on an error by the linker is 1000. A return value of 128 represents a configuration problem with either the operating system or a .config file; the loader didn't load either link.exe or c2.dll. |
| 41 | +The linker returns zero for success (no errors). Otherwise, it returns the error number that stopped the link. For example, if the linker generates `LNK1104`, the linker returns 1104. Accordingly, the lowest error number returned on an error by the linker is 1000. A return value of 128 represents a configuration problem with either the operating system or a .config file; the loader didn't load either `link.exe` or `c2.dll`. |
45 | 42 |
|
46 | | -## LINK Command Files |
| 43 | +## Linker command files |
47 | 44 |
|
48 | | -You can pass command-line arguments to LINK in the form of a command file. To specify a command file to the linker, use the following syntax: |
| 45 | +You can pass command-line arguments to `link.exe` in the form of a command file. To specify a command file to the linker, use the following syntax: |
49 | 46 |
|
50 | | -> **LINK \@**<em>commandfile</em> |
| 47 | +> `link @commandfile` |
51 | 48 |
|
52 | | -The *commandfile* is the name of a text file. No space or tab is allowed between the at sign (**\@**) and the filename. There is no default extension; you must specify the full filename, including any extension. Wildcards cannot be used. You can specify an absolute or relative path with the filename. LINK does not use an environment variable to search for the file. |
| 49 | +The *`commandfile`* is the name of a text file. No space or tab is allowed between the at sign (**\@**) and the filename. There's no default extension; you must specify the full filename, including any extension. Wildcards can't be used. You can specify an absolute or relative path with the filename. The linker doesn't use an environment variable to search for the file. |
53 | 50 |
|
54 | | -In the command file, arguments can be separated by spaces or tabs (as on the command line) and by newline characters. |
| 51 | +In the command file, arguments are separated by spaces or tabs (as on the command line) and by newline characters. |
55 | 52 |
|
56 | | -You can specify all or part of the command line in a command file. You can use more than one command file in a LINK command. LINK accepts the command-file input as if it were specified in that location on the command line. Command files cannot be nested. LINK echoes the contents of command files, unless the [/NOLOGO](nologo-suppress-startup-banner-linker.md) option is specified. |
| 53 | +You can specify all or part of the command line in a command file. You can use more than one command file in a `link.exe` command. The linker accepts the command-file input as if it was specified in that location on the command line. Command files can't be nested. The linker echoes the contents of command files, unless [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) is specified. |
57 | 54 |
|
58 | 55 | ## Example |
59 | 56 |
|
60 | | -The following command to build a DLL passes the names of object files and libraries in separate command files and uses a third command file for specification of the /EXPORTS option: |
| 57 | +The following command builds a DLL. It passes the names of object files and libraries in separate command files and uses a third command file for specification of the `/EXPORTS` option: |
61 | 58 |
|
62 | 59 | ```cmd |
63 | 60 | link /dll @objlist.txt @liblist.txt @exports.txt |
64 | 61 | ``` |
65 | 62 |
|
66 | | -## LINK Environment Variables |
67 | | - |
68 | | -The LINK tool uses the following environment variables: |
69 | | - |
70 | | -- LINK and \_LINK\_, if defined. The LINK tool prepends the options and arguments defined in the LINK environment variable and appends the options and arguments defined in the \_LINK\_ environment variable to the command line arguments before processing. |
71 | | - |
72 | | -- LIB, if defined. The LINK tools uses the LIB path when searching for an object, library, or other file specified on the command line or by the [/BASE](base-base-address.md) option. It also uses the LIB path to find a .pdb file named in an object. The LIB variable can contain one or more path specifications, separated by semicolons. One path must point to the \lib subdirectory of your Visual C++ installation. |
| 63 | +## LINK environment variables |
73 | 64 |
|
74 | | -- PATH, if the tool needs to run CVTRES and cannot find the file in the same directory as LINK itself. (LINK requires CVTRES to link a .res file.) PATH must point to the \bin subdirectory of your Visual C++ installation. |
| 65 | +The linker recognizes the following environment variables: |
75 | 66 |
|
76 | | -- TMP, to specify a directory when linking OMF or .res files. |
| 67 | +- `LINK` and `_LINK_`, if defined. The linker prepends the options and arguments defined in the `LINK` environment variable and appends the options and arguments defined in the `_LINK_` environment variable to the command line arguments before processing. |
| 68 | +- `LIB`, if defined. The linker uses the `LIB` path when it searches for an object, library, or other file specified on the command line or by the [`/BASE`](base-base-address.md) option. It also uses the `LIB` path to find a `.pdb` file named in an object. The `LIB` variable can contain one or more path specifications, separated by semicolons. One path must point to the `\lib` subdirectory of your Visual C++ installation. |
| 69 | +- `PATH`, if the tool needs to run `CVTRES` and can't find the file in the same directory as `link.exe` itself. (`link.exe` requires `CVTRES` to link a `.res` file.) `PATH` must point to the `\bin` subdirectory of your Visual C++ installation. |
| 70 | +- `TMP`, to specify a directory when linking OMF or `.res` files. |
77 | 71 |
|
78 | 72 | ## See also |
79 | 73 |
|
80 | | -[C/C++ Building Reference](c-cpp-building-reference.md) |
81 | | -[MSVC Linker Options](linker-options.md) |
82 | | -[Module-Definition (.def) Files](module-definition-dot-def-files.md) |
| 74 | +[C/C++ Building Reference](c-cpp-building-reference.md)\ |
| 75 | +[MSVC Linker Options](linker-options.md)\ |
| 76 | +[Module-Definition (.def) Files](module-definition-dot-def-files.md)\ |
83 | 77 | [Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) |
0 commit comments