SCons/Tool/link.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <tool name="link">
  28 <summary>
  29 <para>
  30 Sets construction variables for generic POSIX linkers. This is
  31 a "smart" linker tool which selects a compiler to complete the linking
  32 based on the types of source files.
  33 </para>
  34 </summary>
  35 <sets>
  36 <item>LINK</item>
  37 <item>LINKFLAGS</item>
  38 <item>LINKCOM</item>
  39 <item>LIBDIRPREFIX</item>
  40 <item>LIBDIRSUFFIX</item>
  41 <item>LIBLINKPREFIX</item>
  42 <item>LIBLINKSUFFIX</item>
  43 <item>SHLINK</item>
  44 <item>SHLINKFLAGS</item>
  45 <item>SHLINKCOM</item>
  46 <item>SHLIBSUFFIX</item>
  47 <item>__SHLIBVERSIONFLAGS</item>
  48 <item>LDMODULE</item>
  49 <item>LDMODULEPREFIX</item>
  50 <item>LDMODULESUFFIX</item>
  51 <item>LDMODULEFLAGS</item>
  52 <item>LDMODULECOM</item>
  53 <item>LDMODULEVERSION</item>
  54 <item>LDMODULENOVERSIONSYMLINKS</item>
  55 <item>LDMODULEVERSIONFLAGS</item>
  56 <item>__LDMODULEVERSIONFLAGS</item>
  57 </sets>
  58 <uses>
  59 <item>LINKCOMSTR</item>
  60 <item>SHLINKCOMSTR</item>
  61 <item>LDMODULECOMSTR</item>
  62 </uses>
  63 </tool>
  64
  65 <cvar name="__LDMODULEVERSIONFLAGS">
  66 <summary>
  67 <para>
  68 This construction variable automatically introduces &cv-link-_LDMODULEVERSIONFLAGS;
  69 if &cv-link-LDMODULEVERSION; is set. Otherwise, it evaluates to an empty string.
  70 </para>
  71 </summary>
  72 </cvar>
  73
  74 <cvar name="__SHLIBVERSIONFLAGS">
  75 <summary>
  76 <para>
  77 This construction variable automatically introduces &cv-link-_SHLIBVERSIONFLAGS;
  78 if &cv-link-SHLIBVERSION; is set. Otherwise, it evaluates to an empty string.
  79 </para>
  80 </summary>
  81 </cvar>
  82
  83 <cvar name="_LDMODULESONAME">
  84 <summary>
  85 <para>
  86 A macro that automatically generates loadable module's SONAME based on $TARGET,
  87 $LDMODULEVERSION and $LDMODULESUFFIX. Used by &b-link-LoadableModule; builder
  88 when the linker tool supports SONAME (e.g. &t-link-gnulink;).
  89 </para>
  90 </summary>
  91 </cvar>
  92
  93 <cvar name="_LDMODULEVERSIONFLAGS">
  94 <summary>
  95 <para>
  96 This macro automatically introduces extra flags to &cv-link-LDMODULECOM; when
  97 building versioned &b-link-LoadableModule; (that is when
  98 &cv-link-LDMODULEVERSION; is set). <literal>_LDMODULEVERSIONFLAGS</literal>
  99 usually adds &cv-link-SHLIBVERSIONFLAGS; and some extra dynamically generated
 100 options (such as <literal>-Wl,-soname=$_LDMODULESONAME</literal>).  It is unused
 101 by plain (unversioned) loadable modules.
 102 </para>
 103 </summary>
 104 </cvar>
 105
 106 <cvar name="_SHLIBVERSIONFLAGS">
 107 <summary>
 108 <para>
 109 This macro automatically introduces extra flags to &cv-link-SHLINKCOM; when
 110 building versioned &b-link-SharedLibrary; (that is when &cv-link-SHLIBVERSION;
 111 is set). <literal>_SHLIBVERSIONFLAGS</literal> usually adds &cv-link-SHLIBVERSIONFLAGS;
 112 and some extra dynamically generated options (such as
 113 <literal>-Wl,-soname=$_SHLIBSONAME</literal>. It is unused by "plain"
 114 (unversioned) shared libraries.
 115 </para>
 116 </summary>
 117 </cvar>
 118
 119 <cvar name="_SHLIBSONAME">
 120 <summary>
 121 <para>
 122 A macro that automatically generates shared library's SONAME based on $TARGET,
 123 $SHLIBVERSION and $SHLIBSUFFIX. Used by &b-link-SharedLibrary; builder when
 124 the linker tool supports SONAME (e.g. &t-link-gnulink;).
 125 </para>
 126 </summary>
 127 </cvar>
 128
 129 <cvar name="IMPLIBPREFIX">
 130 <summary>
 131 <para>
 132 The prefix used for import library names. For example, cygwin uses import
 133 libraries (<literal>libfoo.dll.a</literal>) in pair with dynamic libraries
 134 (<literal>cygfoo.dll</literal>). The &t-link-cyglink; linker sets
 135 &cv-link-IMPLIBPREFIX; to <literal>'lib'</literal> and &cv-link-SHLIBPREFIX;
 136 to <literal>'cyg'</literal>.
 137 </para>
 138 </summary>
 139 </cvar>
 140
 141 <cvar name="IMPLIBSUFFIX">
 142 <summary>
 143 <para>
 144 The suffix used for import library names. For example, cygwin uses import
 145 libraries (<literal>libfoo.dll.a</literal>) in pair with dynamic libraries
 146 (<literal>cygfoo.dll</literal>). The &t-link-cyglink; linker sets
 147 &cv-link-IMPLIBSUFFIX; to <literal>'.dll.a'</literal> and &cv-link-SHLIBSUFFIX;
 148 to <literal>'.dll'</literal>.
 149 </para>
 150 </summary>
 151 </cvar>
 152
 153 <cvar name="IMPLIBNOVERSIONSYMLINKS">
 154 <summary>
 155 <para>
 156 Used to override &cv-link-SHLIBNOVERSIONSYMLINKS;/&cv-link-LDMODULENOVERSIONSYMLINKS; when
 157 creating versioned import library for a shared library/loadable module. If not defined,
 158 then &cv-link-SHLIBNOVERSIONSYMLINKS;/&cv-link-LDMODULENOVERSIONSYMLINKS; is used to determine
 159 whether to disable symlink generation or not.
 160 </para>
 161 </summary>
 162 </cvar>
 163
 164 <cvar name="LDMODULE">
 165 <summary>
 166 <para>
 167 The linker for building loadable modules.
 168 By default, this is the same as &cv-link-SHLINK;.
 169 </para>
 170 </summary>
 171 </cvar>
 172
 173 <cvar name="LDMODULECOM">
 174 <summary>
 175 <para>
 176 The command line for building loadable modules.
 177 On Mac OS X, this uses the &cv-link-LDMODULE;,
 178 &cv-link-LDMODULEFLAGS; and
 179 &cv-link-FRAMEWORKSFLAGS; variables.
 180 On other systems, this is the same as &cv-link-SHLINK;.
 181 </para>
 182 </summary>
 183 </cvar>
 184
 185 <cvar name="LDMODULECOMSTR">
 186 <summary>
 187 <para>
 188 If set, the string displayed when building loadable modules.
 189 If not set, then &cv-link-LDMODULECOM; (the command line) is displayed.
 190 </para>
 191 </summary>
 192 </cvar>
 193
 194 <cvar name="LDMODULEFLAGS">
 195 <summary>
 196 <para>
 197 General user options passed to the linker for building loadable modules.
 198 </para>
 199 </summary>
 200 </cvar>
 201
 202 <cvar name="LDMODULENOVERSIONSYMLINKS">
 203 <summary>
 204 <para>
 205 Instructs the &b-link-LoadableModule; builder to not automatically create symlinks
 206 for versioned modules. Defaults to <literal>$SHLIBNOVERSIONSYMLINKS</literal>
 207 </para>
 208 </summary>
 209 </cvar>
 210
 211 <cvar name="LDMODULEPREFIX">
 212 <summary>
 213 <para>
 214 The prefix used for loadable module file names.
 215 On Mac OS X, this is null;
 216 on other systems, this is
 217 the same as &cv-link-SHLIBPREFIX;.
 218 </para>
 219 </summary>
 220 </cvar>
 221
 222 <cvar name="LDMODULESUFFIX">
 223 <summary>
 224 <para>
 225 The suffix used for loadable module file names.
 226 On Mac OS X, this is null;
 227 on other systems, this is
 228 the same as $SHLIBSUFFIX.
 229 </para>
 230 </summary>
 231 </cvar>
 232
 233 <cvar name="LDMODULEVERSIONFLAGS">
 234 <summary>
 235 <para>
 236 Extra flags added to &cv-link-LDMODULECOM; when building versioned
 237 &b-link-LoadableModule;. These flags are only used when &cv-link-LDMODULEVERSION; is
 238 set.
 239 </para>
 240 </summary>
 241 </cvar>
 242
 243 <cvar name="LINK">
 244 <summary>
 245 <para>
 246 The linker.
 247 See also &cv-link-SHLINK; for linking shared objects.
 248 </para>
 249 <para>
 250 On POSIX systems (those using the &t-link-link; tool),
 251 you should normally not change this value as it defaults
 252 to a "smart" linker tool which selects a compiler
 253 driver matching the type of source files in use.
 254 So for example, if you set &cv-link-CXX; to a specific
 255 compiler name, and are compiling C++ sources,
 256 the smartlink function will automatically select the same compiler
 257 for linking.
 258 </para>
 259 </summary>
 260 </cvar>
 261
 262 <cvar name="LINKCOM">
 263 <summary>
 264 <para>
 265 The command line used to link object files into an executable.
 266 See also &cv-link-SHLINKCOM; for linking shared objects.
 267 </para>
 268 </summary>
 269 </cvar>
 270
 271 <cvar name="LINKCOMSTR">
 272 <summary>
 273 <para>
 274 If set, the string displayed when object files
 275 are linked into an executable.
 276 If not set, then &cv-link-LINKCOM; (the command line) is displayed.
 277 See also &cv-link-SHLINKCOMSTR;.  for linking shared objects.
 278 </para>
 279
 280 <example_commands>
 281 env = Environment(LINKCOMSTR = "Linking $TARGET")
 282 </example_commands>
 283 </summary>
 284 </cvar>
 285
 286 <cvar name="LINKFLAGS">
 287 <summary>
 288 <para>
 289 General user options passed to the linker.
 290 Note that this variable should
 291 <emphasis>not</emphasis>
 292 contain
 293 <option>-l</option>
 294 (or similar) options for linking with the libraries listed in &cv-link-LIBS;,
 295 nor
 296 <option>-L</option>
 297 (or similar) library search path options
 298 that scons generates automatically from &cv-link-LIBPATH;.
 299 See
 300 &cv-link-_LIBFLAGS;
 301 above,
 302 for the variable that expands to library-link options,
 303 and
 304 &cv-link-_LIBDIRFLAGS;
 305 above,
 306 for the variable that expands to library search path options.
 307 See also &cv-link-SHLINKFLAGS;.  for linking shared objects.
 308 </para>
 309 </summary>
 310 </cvar>
 311
 312 <cvar name="SHLIBNOVERSIONSYMLINKS">
 313 <summary>
 314 <para>
 315 Instructs the &b-link-SharedLibrary; builder to not create symlinks for versioned
 316 shared libraries.
 317 </para>
 318 </summary>
 319 </cvar>
 320
 321 <cvar name="SHLIBVERSIONFLAGS">
 322 <summary>
 323 <para>
 324 Extra flags added to &cv-link-SHLINKCOM; when building versioned
 325 &b-link-SharedLibrary;. These flags are only used when &cv-link-SHLIBVERSION; is
 326 set.
 327 </para>
 328 </summary>
 329 </cvar>
 330
 331 <cvar name="SHLINK">
 332 <summary>
 333 <para>
 334 The linker for programs that use shared libraries.
 335 See also &cv-link-LINK; for linking static objects.
 336 </para>
 337 <para>
 338 On POSIX systems (those using the &t-link-link; tool),
 339 you should normally not change this value as it defaults
 340 to a "smart" linker tool which selects a compiler
 341 driver matching the type of source files in use.
 342 So for example, if you set &cv-link-SHCXX; to a specific
 343 compiler name, and are compiling C++ sources,
 344 the smartlink function will automatically select the same compiler
 345 for linking.
 346 </para>
 347 </summary>
 348 </cvar>
 349
 350 <cvar name="SHLINKCOM">
 351 <summary>
 352 <para>
 353 The command line used to link programs using shared libraries.
 354 See also &cv-link-LINKCOM; for linking static objects.
 355 </para>
 356 </summary>
 357 </cvar>
 358
 359 <cvar name="SHLINKCOMSTR">
 360 <summary>
 361 <para>
 362 The string displayed when programs using shared libraries are linked.
 363 If this is not set, then &cv-link-SHLINKCOM; (the command line) is displayed.
 364 See also &cv-link-LINKCOMSTR;  for linking static objects.
 365 </para>
 366
 367 <example_commands>
 368 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
 369 </example_commands>
 370 </summary>
 371 </cvar>
 372
 373 <cvar name="SHLINKFLAGS">
 374 <summary>
 375 <para>
 376 General user options passed to the linker for programs using shared libraries.
 377 Note that this variable should
 378 <emphasis>not</emphasis>
 379 contain
 380 <option>-l</option>
 381 (or similar) options for linking with the libraries listed in &cv-link-LIBS;,
 382 nor
 383 <option>-L</option>
 384 (or similar) include search path options
 385 that scons generates automatically from &cv-link-LIBPATH;.
 386 See
 387 &cv-link-_LIBFLAGS;
 388 above,
 389 for the variable that expands to library-link options,
 390 and
 391 &cv-link-_LIBDIRFLAGS;
 392 above,
 393 for the variable that expands to library search path options.
 394 See also &cv-link-LINKFLAGS;  for linking static objects.
 395 </para>
 396 </summary>
 397 </cvar>
 398
 399 <cvar name="SONAME">
 400 <summary>
 401 <para>
 402 Variable used to hard-code SONAME for versioned shared library/loadable module.
 403 <example_commands>
 404 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
 405 </example_commands>
 406 The variable is used, for example, by &t-link-gnulink; linker tool.
 407 </para>
 408 </summary>
 409 </cvar>
 410
 411 <cvar name="SOVERSION">
 412 <summary>
 413 <para>
 414 This will construct the <varname>SONAME</varname> using on the base library name
 415 (<parameter>test</parameter> in the example below) and use specified <varname>SOVERSION</varname>
 416 to create <varname>SONAME</varname>.
 417 <example_commands>
 418 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')
 419 </example_commands>
 420 The variable is used, for example, by &t-link-gnulink; linker tool.
 421 </para>
 422 <para>
 423 In the example above <varname>SONAME</varname> would be <filename>libtest.so.2</filename>
 424 which would be a symlink and point to <filename>libtest.so.0.1.2</filename>
 425 </para>
 426 </summary>
 427 </cvar>
 428
 429 <cvar name="STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME">
 430   <summary>
 431     <para>
 432       When this variable is true, static objects and shared objects are assumed to be the same; that is, SCons does not check for linking static objects into a shared library.
 433     </para>
 434   </summary>
 435 </cvar>
 436
 437
 438 </sconsdoc>