SCons/Tool/Tool.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 <builder name="CFile">
  28 <summary>
  29 <para>
  30 Builds a C source file given a lex (<filename>.l</filename>)
  31 or yacc (<filename>.y</filename>) input file.
  32 The suffix specified by the &cv-link-CFILESUFFIX; &consvar;
  33 (<filename>.c</filename> by default)
  34 is automatically added to the target
  35 if it is not already present.
  36 Example:
  37 </para>
  38
  39 <example_commands>
  40 # builds foo.c
  41 env.CFile(target='foo.c', source='foo.l')
  42
  43 # builds bar.c
  44 env.CFile(target='bar', source='bar.y')
  45 </example_commands>
  46
  47 <!--para>  ** Left here for reference, does not need to be user-visible. **
  48 Note that for yacc files,
  49 the output file name is derived from <parameter>target</parameter>,
  50 or from the source file name if a target is not specified;
  51 the traditional yacc default name
  52 <filename>y.tab.c</filename> is not used.
  53 </para-->
  54 </summary>
  55 </builder>
  56
  57 <builder name="CXXFile">
  58 <summary>
  59 <para>
  60 Builds a C++ source file given a lex (<filename>.ll</filename>)
  61 or yacc (<filename>.yy</filename>)
  62 input file.
  63 The suffix specified by the &cv-link-CXXFILESUFFIX; &consvar;
  64 (<filename>.cc</filename> by default)
  65 is automatically added to the target
  66 if it is not already present.
  67 Example:
  68 </para>
  69
  70 <example_commands>
  71 # builds foo.cc
  72 env.CXXFile(target='foo.cc', source='foo.ll')
  73
  74 # builds bar.cc
  75 env.CXXFile(target='bar', source='bar.yy')
  76 </example_commands>
  77
  78 <!--para>  ** Left here for reference, does not need to be user-visible. **
  79 Note that for yacc files,
  80 the output file name is derived from <parameter>target</parameter>,
  81 or from the source file name if a target is not specified;
  82 the traditional yacc default name
  83 <filename>y.tab.cc</filename> is not used.
  84 </para -->
  85 </summary>
  86 </builder>
  87
  88 <builder name="Library">
  89 <summary>
  90 <para>
  91 A synonym for the
  92 &b-StaticLibrary;
  93 builder method.
  94 </para>
  95 </summary>
  96 </builder>
  97
  98 <builder name="LoadableModule">
  99 <summary>
 100 <para>
 101 On most systems,
 102 this is the same as
 103 &b-SharedLibrary;.
 104 On Mac OS X (Darwin) platforms,
 105 this creates a loadable module bundle.
 106 </para>
 107 </summary>
 108 </builder>
 109
 110 <builder name="Object">
 111 <summary>
 112 <para>
 113 A synonym for the
 114 &b-StaticObject;
 115 builder method.
 116 </para>
 117 </summary>
 118 </builder>
 119
 120 <builder name="Program">
 121 <summary>
 122 <para>
 123 Builds an executable given one or more object files
 124 or C, C++, D, or Fortran source files.
 125 If any C, C++, D or Fortran source files are specified,
 126 then they will be automatically
 127 compiled to object files using the
 128 &b-Object;
 129 builder method;
 130 see that builder method's description for
 131 a list of legal source file suffixes
 132 and how they are interpreted.
 133 The target executable file prefix,
 134 specified by the &cv-link-PROGPREFIX; &consvar;
 135 (nothing by default),
 136 and suffix,
 137 specified by the &cv-link-PROGSUFFIX; &consvar;
 138 (by default, <filename>.exe</filename> on Windows systems,
 139 nothing on POSIX systems),
 140 are automatically added to the target if not already present.
 141 Example:
 142 </para>
 143
 144 <example_commands>
 145 env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
 146 </example_commands>
 147 </summary>
 148 </builder>
 149
 150 <builder name="SharedLibrary">
 151 <summary>
 152 <para>
 153 Builds a shared library
 154 given one or more object files
 155 and/or C, C++, D or Fortran source files.
 156 Any source files listed in the
 157 <parameter>source</parameter> parameter
 158 will be automatically
 159 compiled to object files suitable
 160 for use in a shared library.
 161 Any object files listed in the
 162 <parameter>source</parameter> parameter
 163 must have been built for a shared library
 164 (that is, using the
 165 &b-SharedObject;
 166 builder method).
 167 &scons;
 168 will raise an error if there is any mismatch.
 169 </para>
 170
 171 <para>
 172 The target library file prefix,
 173 specified by the &cv-link-SHLIBPREFIX; &consvar;
 174 (by default, <filename>lib</filename> on POSIX systems,
 175 nothing on Windows systems),
 176 and suffix,
 177 specified by the &cv-link-SHLIBSUFFIX; &consvar;
 178 (by default, <filename>.dll</filename> on Windows systems,
 179 <filename>.so</filename> on POSIX systems),
 180 are automatically added (if not already present)
 181 to the target name to make up the library filename.
 182 On a POSIX system, if the &cv-link-SHLIBVERSION; &consvar; is set,
 183 it is appended (following a period) to the resulting library name.
 184 </para>
 185
 186 <para>
 187 Example:
 188 </para>
 189
 190 <example_commands>
 191 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
 192 </example_commands>
 193
 194 <para>
 195 On Windows systems, the
 196 &b-SharedLibrary;
 197 builder method will always build an import library
 198 (<filename>.lib</filename>)
 199 in addition to the shared library (<filename>.dll</filename>),
 200 adding a <filename>.lib</filename> library with the same basename
 201 if there is not already a <filename>.lib</filename> file explicitly
 202 listed in the targets.
 203 </para>
 204
 205 <para>
 206 On Cygwin systems, the
 207 &b-SharedLibrary;
 208 builder method will always build an import library
 209 (<filename>.dll.a</filename>)
 210 in addition to the shared library (<filename>.dll</filename>),
 211 adding a <filename>.dll.a</filename> library with the same basename
 212 if there is not already a <filename>.dll.a</filename> file explicitly
 213 listed in the targets.
 214 </para>
 215
 216
 217 <para>
 218 On some platforms, there is a distinction between a shared library
 219 (loaded automatically by the system to resolve external references)
 220 and a loadable module (explicitly loaded by user action).
 221 For maximum portability, use the &b-link-LoadableModule; builder for the latter.
 222 </para>
 223
 224 <para>
 225 If &cv-link-SHLIBVERSION; is defined, a versioned
 226 shared library is created. This modifies &cv-link-SHLINKFLAGS; as required,
 227 adds the version number to the library name, and creates any
 228 symbolic links that are needed.
 229 </para>
 230
 231 <example_commands>
 232 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
 233 </example_commands>
 234
 235 <para>
 236 On a POSIX system, supplying a simple version string (no dots)
 237 creates exactly one symbolic link: <literal>SHLIBVERSION="1"</literal>
 238 would create (for example) library <filename>libbar.so.1</filename>
 239 and symbolic link <filename>libbar.so</filename>.
 240 Supplying a dotted version string will create two symbolic links
 241 (irrespective of the number of segments in the version):
 242 <literal>SHLIBVERSION="1.5.2"</literal> for the same library
 243 would create library <filename>libbar.so.1.5.2</filename>
 244 and symbolic links <filename>libbar.so</filename> and
 245 <filename>libbar.so.1</filename>. A Darwin (OSX)
 246 system creates one symlink in either case,
 247 for the second example the library would be
 248 <filename>libbar.1.5.2.dylib</filename>
 249 and the link would be <filename>libbar.dylib</filename>.
 250 </para>
 251
 252 <para>
 253 On Windows systems, specifying the
 254 <parameter>register=1</parameter> keyword argument
 255 will cause the <filename>.dll</filename> to be
 256 registered after it is built.
 257 The command that is run is determined by the &cv-link-REGSVR; &consvar;
 258 (<command>regsvr32</command> by default),
 259 and the flags passed are determined by &cv-link-REGSVRFLAGS;.  By
 260 default, &cv-link-REGSVRFLAGS; includes the <option>/s</option> option,
 261 to prevent dialogs from popping
 262 up and requiring user attention when it is run.  If you change
 263 &cv-link-REGSVRFLAGS;, be sure to include the <option>/s</option> option.
 264 For example,
 265 </para>
 266
 267 <example_commands>
 268 env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
 269 </example_commands>
 270
 271 <para>
 272 will register <filename>bar.dll</filename> as a COM object
 273 when it is done linking it.
 274 </para>
 275 </summary>
 276 </builder>
 277
 278 <builder name="SharedObject">
 279 <summary>
 280 <para>
 281 Builds an object file intended for
 282 inclusion in a shared library.
 283 Source files must have one of the same set of extensions
 284 specified above for the
 285 &b-StaticObject;
 286 builder method.
 287 On some platforms building a shared object requires additional
 288 compiler option
 289 (e.g. <option>-fPIC</option> for <command>gcc</command>)
 290 in addition to those needed to build a
 291 normal (static) object, but on some platforms there is no difference between a
 292 shared object and a normal (static) one. When there is a difference, SCons
 293 will only allow shared objects to be linked into a shared library, and will
 294 use a different suffix for shared objects. On platforms where there is no
 295 difference, SCons will allow both normal (static)
 296 and shared objects to be linked into a
 297 shared library, and will use the same suffix for shared and normal
 298 (static) objects.
 299 The target object file prefix,
 300 specified by the &cv-link-SHOBJPREFIX; &consvar;
 301 (by default, the same as &cv-link-OBJPREFIX;),
 302 and suffix,
 303 specified by the &cv-link-SHOBJSUFFIX; &consvar;,
 304 are automatically added to the target if not already present.
 305 Examples:
 306 </para>
 307
 308 <example_commands>
 309 env.SharedObject(target='ddd', source='ddd.c')
 310 env.SharedObject(target='eee.o', source='eee.cpp')
 311 env.SharedObject(target='fff.obj', source='fff.for')
 312 </example_commands>
 313
 314 <para>
 315 Note that the source files will be scanned
 316 according to the suffix mappings in the
 317 <classname>SourceFileScanner</classname>
 318 object.
 319 See the manpage section "Scanner Objects"
 320 for more information.
 321 </para>
 322 </summary>
 323 </builder>
 324
 325 <builder name="StaticLibrary">
 326 <summary>
 327 <para>
 328 Builds a static library given one or more object files
 329 or C, C++, D or Fortran source files.
 330 If any source files are given,
 331 then they will be automatically
 332 compiled to object files.
 333 The static library file prefix,
 334 specified by the &cv-link-LIBPREFIX; &consvar;
 335 (by default, <filename>lib</filename> on POSIX systems,
 336 nothing on Windows systems),
 337 and suffix,
 338 specified by the &cv-link-LIBSUFFIX; &consvar;
 339 (by default, <filename>.lib</filename> on Windows systems,
 340 <filename>.a</filename> on POSIX systems),
 341 are automatically added to the target if not already present.
 342 Example:
 343 </para>
 344
 345 <example_commands>
 346 env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
 347 </example_commands>
 348
 349 <para>
 350 Any object files listed in the
 351 <parameter>source</parameter>
 352 must have been built for a static library
 353 (that is, using the
 354 &b-StaticObject;
 355 builder method).
 356 &scons;
 357 will raise an error if there is any mismatch.
 358 </para>
 359 </summary>
 360 </builder>
 361
 362 <builder name="StaticObject">
 363 <summary>
 364 <para>
 365 Builds a static object file
 366 from one or more C, C++, D, or Fortran source files.
 367 Source files must have one of the following extensions:
 368 </para>
 369
 370 <example_commands>
 371   .asm    assembly language file
 372   .ASM    assembly language file
 373   .c      C file
 374   .C      Windows:  C file
 375           POSIX:  C++ file
 376   .cc     C++ file
 377   .cpp    C++ file
 378   .cxx    C++ file
 379   .cxx    C++ file
 380   .c++    C++ file
 381   .C++    C++ file
 382   .d      D file
 383   .f      Fortran file
 384   .F      Windows:  Fortran file
 385           POSIX:  Fortran file + C pre-processor
 386   .for    Fortran file
 387   .FOR    Fortran file
 388   .fpp    Fortran file + C pre-processor
 389   .FPP    Fortran file + C pre-processor
 390   .m      Object C file
 391   .mm     Object C++ file
 392   .s      assembly language file
 393   .S      Windows:  assembly language file
 394           ARM: CodeSourcery Sourcery Lite
 395   .sx     assembly language file + C pre-processor
 396           POSIX:  assembly language file + C pre-processor
 397   .spp    assembly language file + C pre-processor
 398   .SPP    assembly language file + C pre-processor
 399 </example_commands>
 400
 401 <para>
 402 The target object file prefix,
 403 specified by the &cv-link-OBJPREFIX; &consvar;
 404 (nothing by default),
 405 and suffix,
 406 specified by the &cv-link-OBJSUFFIX; &consvar;
 407 (<filename>.obj</filename> on Windows systems,
 408 <filename>.o</filename> on POSIX systems),
 409 are automatically added to the target if not already present.
 410 Examples:
 411 </para>
 412
 413 <example_commands>
 414 env.StaticObject(target='aaa', source='aaa.c')
 415 env.StaticObject(target='bbb.o', source='bbb.c++')
 416 env.StaticObject(target='ccc.obj', source='ccc.f')
 417 </example_commands>
 418
 419 <para>
 420 Note that the source files will be scanned
 421 according to the suffix mappings in the
 422 <classname>SourceFileScanner</classname>
 423 object.
 424 See the manpage section "Scanner Objects"
 425 for more information.
 426 </para>
 427 </summary>
 428 </builder>
 429
 430 <cvar name="CCVERSION">
 431 <summary>
 432 <para>
 433 The version number of the C compiler.
 434 This may or may not be set,
 435 depending on the specific C compiler being used.
 436 </para>
 437 </summary>
 438 </cvar>
 439
 440 <cvar name="CFILESUFFIX">
 441 <summary>
 442 <para>
 443 The suffix for C source files.
 444 This is used by the internal CFile builder
 445 when generating C files from Lex (.l) or YACC (.y) input files.
 446 The default suffix, of course, is
 447 <filename>.c</filename>
 448 (lower case).
 449 On case-insensitive systems (like Windows),
 450 SCons also treats
 451 <filename>.C</filename>
 452 (upper case) files
 453 as C files.
 454 </para>
 455 </summary>
 456 </cvar>
 457
 458 <cvar name="CXXVERSION">
 459 <summary>
 460 <para>
 461 The version number of the C++ compiler.
 462 This may or may not be set,
 463 depending on the specific C++ compiler being used.
 464 </para>
 465 </summary>
 466 </cvar>
 467
 468 <cvar name="CXXFILESUFFIX">
 469 <summary>
 470 <para>
 471 The suffix for C++ source files.
 472 This is used by the internal CXXFile builder
 473 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
 474 The default suffix is
 475 <filename>.cc</filename>.
 476 SCons also treats files with the suffixes
 477 <filename>.cpp</filename>,
 478 <filename>.cxx</filename>,
 479 <filename>.c++</filename>,
 480 and
 481 <filename>.C++</filename>
 482 as C++ files,
 483 and files with
 484 <filename>.mm</filename>
 485 suffixes as Objective-C++ files.
 486 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
 487 SCons also treats
 488 <filename>.C</filename>
 489 (upper case) files
 490 as C++ files.
 491 </para>
 492 </summary>
 493 </cvar>
 494
 495 <cvar name="IMPLIBVERSION">
 496 <summary>
 497 <para>
 498 Used to override &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; when
 499 generating versioned import library for a shared library/loadable module. If
 500 undefined, the &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; is used to
 501 determine the version of versioned import library.
 502 </para>
 503 </summary>
 504 </cvar>
 505
 506 <cvar name="LIBEMITTER">
 507 <summary>
 508 <para>
 509 Contains the emitter specification for the
 510 &b-link-StaticLibrary; builder.
 511 The manpage section "Builder Objects" contains
 512 general information on specifying emitters.
 513 </para>
 514 </summary>
 515 </cvar>
 516
 517 <cvar name="LDMODULEVERSION">
 518 <summary>
 519 <para>
 520 When this &consvar; is defined, a versioned loadable module
 521 is created by &b-link-LoadableModule; builder. This activates the
 522 &cv-link-_LDMODULEVERSIONFLAGS; and thus modifies the &cv-link-LDMODULECOM; as
 523 required, adds the version number to the library name, and creates the symlinks
 524 that are needed. &cv-link-LDMODULEVERSION; versions should exist in the same
 525 format as &cv-link-SHLIBVERSION;.
 526 </para>
 527 </summary>
 528 </cvar>
 529
 530 <cvar name="LDMODULEEMITTER">
 531 <summary>
 532 <para>
 533 Contains the emitter specification for the
 534 &b-link-LoadableModule; builder.
 535 The manpage section "Builder Objects" contains
 536 general information on specifying emitters.
 537 </para>
 538 </summary>
 539 </cvar>
 540
 541 <cvar name="SHLIBEMITTER">
 542 <summary>
 543 <para>
 544 Contains the emitter specification for the
 545 &b-link-SharedLibrary; builder.
 546 The manpage section "Builder Objects" contains
 547 general information on specifying emitters.
 548 </para>
 549 </summary>
 550 </cvar>
 551
 552 <cvar name="PROGEMITTER">
 553 <summary>
 554 <para>
 555 Contains the emitter specification for the
 556 &b-link-Program; builder.
 557 The manpage section "Builder Objects" contains
 558 general information on specifying emitters.
 559 </para>
 560 </summary>
 561 </cvar>
 562
 563 <cvar name="SHLIBVERSION">
 564 <summary>
 565 <para>
 566 When this &consvar; is defined, a versioned shared library
 567 is created by the &b-link-SharedLibrary; builder. This activates the
 568 &cv-link-_SHLIBVERSIONFLAGS; and thus modifies the &cv-link-SHLINKCOM; as
 569 required, adds the version number to the library name, and creates the symlinks
 570 that are needed.  &cv-link-SHLIBVERSION; versions should exist as alphanumeric,
 571 decimal-delimited values as defined by the regular expression "\w+[\.\w+]*".
 572 Example &cv-link-SHLIBVERSION; values include '1', '1.2.3', and '1.2.gitaa412c8b'.
 573 </para>
 574 </summary>
 575 </cvar>
 576
 577 </sconsdoc>