summaryrefslogtreecommitdiff
path: root/src/engine/SCons/Tool/mslink.xml
blob: 24b79c751394353e87e8a99cf650eecc4190c792 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2001 - 2017 The SCons Foundation

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'>
%variables-mod;
]>

<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<tool name="mslink">
<summary>
<para>
Sets construction variables for the Microsoft linker.
</para>
</summary>
<sets>
<item>SHLINK</item>
<item>SHLINKFLAGS</item>
<item>SHLINKCOM</item>
<item>LINK</item>
<item>LINKFLAGS</item>
<item>LINKCOM</item>
<item>LIBDIRPREFIX</item>
<item>LIBDIRSUFFIX</item>
<item>LIBLINKPREFIX</item>
<item>LIBLINKSUFFIX</item>
<item>WIN32DEFPREFIX</item>
<item>WIN32DEFSUFFIX</item>
<item>WINDOWSDEFPREFIX</item>
<item>WINDOWSDEFSUFFIX</item>
<item>WINDOWS_INSERT_DEF</item>
<item>WIN32EXPPREFIX</item>
<item>WIN32EXPSUFFIX</item>
<item>WINDOWSEXPPREFIX</item>
<item>WINDOWSEXPSUFFIX</item>
<item>WINDOWSSHLIBMANIFESTPREFIX</item>
<item>WINDOWSSHLIBMANIFESTSUFFIX</item>
<item>WINDOWSPROGMANIFESTPREFIX</item>
<item>WINDOWSPROGMANIFESTSUFFIX</item>
<item><!--REGSVRACTION--></item>
<item>REGSVR</item>
<item>REGSVRFLAGS</item>
<item>REGSVRCOM</item>
<item>LDMODULE</item>
<item>LDMODULEPREFIX</item>
<item>LDMODULESUFFIX</item>
<item>LDMODULEFLAGS</item>
<item>LDMODULECOM</item>
</sets>
<uses>
<item>SHLINKCOMSTR</item>
<item>LINKCOMSTR</item>
<item>REGSVRCOMSTR</item>
<item>LDMODULECOMSTR</item>
</uses>
</tool>

<cvar name="no_import_lib">
<summary>
<para>
When set to non-zero,
suppresses creation of a corresponding Windows static import lib by the
<literal>SharedLibrary</literal>
builder when used with
MinGW, Microsoft Visual Studio or Metrowerks.
This also suppresses creation
of an export (.exp) file
when using Microsoft Visual Studio.
</para>
</summary>
</cvar>

<cvar name="PDB">
<summary>
<para>
The Microsoft Visual C++ PDB file that will store debugging information for
object files, shared libraries, and programs. This variable is ignored by
tools other than Microsoft Visual C++.
When this variable is
defined SCons will add options to the compiler and linker command line to
cause them to generate external debugging information, and will also set up the
dependencies for the PDB file.
Example:
</para>

<example_commands>
env['PDB'] = 'hello.pdb'
</example_commands>

<para>
The Visual C++ compiler switch that SCons uses by default
to generate PDB information is <option>/Z7</option>.
This works correctly with parallel (<option>-j</option>) builds
because it embeds the debug information in the intermediate object files,
as opposed to sharing a single PDB file between multiple object files.
This is also the only way to get debug information
embedded into a static library.
Using the <option>/Zi</option> instead may yield improved
link-time performance,
although parallel builds will no longer work.
You can generate PDB files with the <option>/Zi</option>
switch by overriding the default &cv-link-CCPDBFLAGS; variable;
see the entry for that variable for specific examples.
</para>
</summary>
</cvar>

<cvar name="WINDOWS_EMBED_MANIFEST">
<summary>
<para>
Set this variable to True or 1 to embed the compiler-generated manifest
(normally <literal>${TARGET}.manifest</literal>)
into all Windows exes and DLLs built with this environment,
as a resource during their link step.
This is done using &cv-link-MT; and &cv-link-MTEXECOM; and &cv-link-MTSHLIBCOM;.
</para>
</summary>
</cvar>

<cvar name="MT">
<summary>
<para>
The program used on Windows systems to embed manifests into DLLs and EXEs.
See also &cv-link-WINDOWS_EMBED_MANIFEST;.
</para>
</summary>
</cvar>

<cvar name="MTFLAGS">
<summary>
<para>
Flags passed to the &cv-link-MT; manifest embedding program (Windows only).
</para>
</summary>
</cvar>

<cvar name="MTEXECOM">
<summary>
<para>
The Windows command line used to embed manifests into executables.
See also &cv-link-MTSHLIBCOM;.
</para>
</summary>
</cvar>

<cvar name="MTSHLIBCOM">
<summary>
<para>
The Windows command line used to embed manifests into shared libraries (DLLs).
See also &cv-link-MTEXECOM;.
</para>
</summary>
</cvar>

<cvar name="REGSVR">
<summary>
<para>
The program used on Windows systems
to register a newly-built DLL library
whenever the &b-SharedLibrary; builder
is passed a keyword argument of <literal>register=1</literal>.
</para>
</summary>
</cvar>

<cvar name="REGSVRCOM">
<summary>
<para>
The command line used on Windows systems
to register a newly-built DLL library
whenever the &b-SharedLibrary; builder
is passed a keyword argument of <literal>register=1</literal>.
</para>
</summary>
</cvar>

<cvar name="REGSVRCOMSTR">
<summary>
<para>
The string displayed when registering a newly-built DLL file.
If this is not set, then &cv-link-REGSVRCOM; (the command line) is displayed.
</para>
</summary>
</cvar>

<cvar name="REGSVRFLAGS">
<summary>
<para>
Flags passed to the DLL registration program
on Windows systems when a newly-built DLL library is registered.
By default,
this includes the <option>/s</option>
that prevents dialog boxes from popping up
and requiring user attention.
</para>
</summary>
</cvar>

<cvar name="WIN32_INSERT_DEF">
<summary>
<para>
A deprecated synonym for &cv-link-WINDOWS_INSERT_DEF;.
</para>
</summary>
</cvar>

<cvar name="WIN32DEFPREFIX">
<summary>
<para>
A deprecated synonym for &cv-link-WINDOWSDEFPREFIX;.
</para>
</summary>
</cvar>

<cvar name="WIN32DEFSUFFIX">
<summary>
<para>
A deprecated synonym for &cv-link-WINDOWSDEFSUFFIX;.
</para>
</summary>
</cvar>

<cvar name="WIN32EXPPREFIX">
<summary>
<para>
A deprecated synonym for &cv-link-WINDOWSEXPSUFFIX;.
</para>
</summary>
</cvar>

<cvar name="WIN32EXPSUFFIX">
<summary>
<para>
A deprecated synonym for &cv-link-WINDOWSEXPSUFFIX;.
</para>
</summary>
</cvar>

<cvar name="WINDOWS_INSERT_DEF">
<summary>
<para>
When this is set to true,
a library build of a Windows shared library
(<filename>.dll</filename> file)
will also build a corresponding <filename>.def</filename> file
at the same time,
if a <filename>.def</filename> file
is not already listed as a build target.
The default is 0 (do not build a <filename>.def</filename> file).
</para>
</summary>
</cvar>

<cvar name="WINDOWS_INSERT_MANIFEST">
<summary>
<para>
When this is set to true,
&scons;
will be aware of the
<filename>.manifest</filename>
files generated by Microsoft Visua C/C++ 8.
</para>
</summary>
</cvar>

<cvar name="WINDOWSDEFPREFIX">
<summary>
<para>
The prefix used for Windows <filename>.def</filename> file names.
</para>
</summary>
</cvar>

<cvar name="WINDOWSDEFSUFFIX">
<summary>
<para>
The suffix used for Windows <filename>.def</filename> file names.
</para>
</summary>
</cvar>

<cvar name="WINDOWSEXPPREFIX">
<summary>
<para>
The prefix used for Windows <filename>.exp</filename> file names.
</para>
</summary>
</cvar>

<cvar name="WINDOWSEXPSUFFIX">
<summary>
<para>
The suffix used for Windows <filename>.exp</filename> file names.
</para>
</summary>
</cvar>

<cvar name="WINDOWSPROGMANIFESTPREFIX">
<summary>
<para>
The prefix used for executable program <filename>.manifest</filename> files
generated by Microsoft Visual C/C++.
</para>
</summary>
</cvar>

<cvar name="WINDOWSPROGMANIFESTSUFFIX">
<summary>
<para>
The suffix used for executable program <filename>.manifest</filename> files
generated by Microsoft Visual C/C++.
</para>
</summary>
</cvar>

<cvar name="WINDOWSSHLIBMANIFESTPREFIX">
<summary>
<para>
The prefix used for shared library <filename>.manifest</filename> files
generated by Microsoft Visual C/C++.
</para>
</summary>
</cvar>

<cvar name="WINDOWSSHLIBMANIFESTSUFFIX">
<summary>
<para>
The suffix used for shared library <filename>.manifest</filename> files
generated by Microsoft Visual C/C++.
</para>
</summary>
</cvar>

</sconsdoc>