doc/user/builders-built-in.xml

   1 <?xml version='1.0'?>
   2
   3 <!--
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-License-Identifier: MIT
   6 SPDX-FileType: DOCUMENTATION
   7
   8 This file is processed by the bin/SConsDoc.py module.
   9 -->
  10
  11 <!DOCTYPE sconsdoc [
  12     <!ENTITY % scons SYSTEM "../scons.mod">
  13     %scons;
  14
  15     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
  16     %builders-mod;
  17     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
  18     %functions-mod;
  19     <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
  20     %tools-mod;
  21     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
  22     %variables-mod;
  23
  24 ]>
  25
  26 <chapter id="chap-builders-built-in"
  27          xmlns="http://www.scons.org/dbxsd/v1.0"
  28          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  29          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  30
  31 <!-- NOTE: this file is incomplete, and main.xml does not currently include it -->
  32 <title>Built-In Builders</title>
  33
  34   <para>
  35
  36   &SCons; provides the ability to build a lot of different
  37   types of files right "out of the box."
  38   So far, we've been using &SCons;' ability to build
  39   programs, objects and libraries to
  40   illustrate much of the underlying functionality of &SCons;
  41   This section will describe all of the different
  42   types of files that you can build with &SCons;,
  43   and the built-in &Builder; objects used to build them.
  44   By default, all of the  &Builder; objects in this section
  45   can be built either with or without an explicit
  46   construction environment.
  47
  48   </para>
  49
  50   <section>
  51   <title>Programs:  the &Program; Builder</title>
  52
  53     <para>
  54
  55     As we've seen, the &b-link-Program; Builder
  56     is used to build an executable program.
  57     The &source; argument is one or more
  58     source-code files or object files,
  59     and the &target; argument is the
  60     name of the executable program name to be created.
  61     For example:
  62
  63     </para>
  64
  65     <programlisting>
  66 Program('prog', 'file1.o')
  67     </programlisting>
  68
  69     <para>
  70
  71     Will create the &prog;
  72     executable on a POSIX system,
  73     the &prog_exe; executable on a Windows system.
  74
  75     </para>
  76
  77     <para>
  78
  79     The target file's prefix and suffix may be omitted,
  80     and the values from the
  81     &cv-link-PROGPREFIX;
  82     and
  83     &cv-link-PROGSUFFIX;
  84     construction variables
  85     will be appended appropriately.
  86     For example:
  87
  88     </para>
  89
  90     <programlisting>
  91 env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx')
  92 env.Program('prog', ['file1.o', 'file2.o'])
  93     </programlisting>
  94
  95     <para>
  96
  97     Will create a program named
  98     <filename>myprog.xxx</filename>
  99     regardless of the system on which it is run.
 100
 101     </para>
 102
 103     <para>
 104
 105     If you omit the &target;,
 106     the base of the first input
 107     file name specified
 108     becomes the base of the target
 109     program created.
 110     For example:
 111
 112     </para>
 113
 114     <programlisting>
 115 Program(['hello.c', 'goodbye.c'])
 116     </programlisting>
 117
 118     <para>
 119
 120     Will create the &hello;
 121     executable on a POSIX system,
 122     the &hello_exe; executable on a Windows system.
 123
 124     </para>
 125
 126     <para>
 127
 128     Two construction variables control what libraries
 129     will be linked with the resulting program.
 130     The &cv-link-LIBS; variable is a list of the names of
 131     libraries that will be linked into any programs,
 132     and the &cv-link-LIBPATH; variables is a list of
 133     directories that will be searched for
 134     the specified libraries.
 135     &SCons; will construct the right command-line
 136     options for the running system.
 137     For example:
 138
 139     </para>
 140
 141     <scons_example name="buildersbuiltin_libs">
 142       <file name="SConstruct" printme="1">
 143 env = Environment(LIBS=['foo1', 'foo2'], LIBPATH=['/usr/dir1', 'dir2'])
 144 env.Program(['hello.c', 'goodbye.c'])
 145       </file>
 146       <file name="hello.c">
 147 int hello() { printf("Hello, world!\n"); }
 148       </file>
 149       <file name="goodbye.c">
 150 int goodbye() { printf("Goodbye, world!\n"); }
 151       </file>
 152     </scons_example>
 153
 154     <para>
 155
 156     Will execute as follows on a POSIX system:
 157
 158     </para>
 159
 160     <scons_output example="buildersbuiltin_libs" os="posix" suffix="1">
 161       <scons_output_command>scons -Q</scons_output_command>
 162     </scons_output>
 163
 164     <para>
 165
 166     And execute as follows on a Windows system:
 167
 168     </para>
 169
 170     <scons_output example="buildersbuiltin_libs" os="win32" suffix="2">
 171       <scons_output_command>scons -Q</scons_output_command>
 172     </scons_output>
 173
 174     <para>
 175
 176     The &cv-LIBS; construction variable
 177     is turned into command line options
 178     by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX;
 179     construction variables to the beginning and end,
 180     respectively, of each specified library.
 181
 182     </para>
 183
 184     <para>
 185
 186     The &cv-LIBPATH; construction variable
 187     is turned into command line options
 188     by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX;
 189     construction variables to the beginning and end,
 190     respectively, of each specified library.
 191
 192     </para>
 193
 194     <para>
 195
 196     Other relevant construction variables
 197     include those used by the &b-link-Object;
 198     builders to affect how the
 199     source files specified as input to the <literal>Program</literal>
 200     builders are turned into object files;
 201     see the next section.
 202
 203     </para>
 204
 205     <para>
 206
 207     The command line used to control how a program is linked
 208     is specified by the &cv-link-LINKCOM; construction variable.
 209     By default, it uses the
 210     &cv-link-LINK; construction variable
 211     and the &cv-link-LINKFLAGS; construction variable.
 212
 213     </para>
 214
 215   </section>
 216
 217   <section>
 218   <title>Object-File Builders</title>
 219
 220     <para>
 221
 222     &SCons; provides separate Builder objects
 223     to create static and shared object files.
 224     The distinction becomes especially important when
 225     archiving object files into different types of libraries.
 226
 227     </para>
 228
 229     <section>
 230     <title>The &StaticObject; Builder</title>
 231
 232       <para>
 233
 234       The &b-link-StaticObject; Builder
 235       is used to build an object file
 236       suitable for static linking into a program,
 237       or for inclusion in a static library.
 238       The &source; argument is a single source-code file,
 239       and the &target; argument is the
 240       name of the static object file to be created.
 241       For example:
 242
 243       </para>
 244
 245       <programlisting>
 246 StaticObject('file', 'file.c')
 247       </programlisting>
 248
 249       <para>
 250
 251       Will create the &file_o;
 252       object file on a POSIX system,
 253       the &file_obj; executable on a Windows system.
 254
 255       </para>
 256
 257       <para>
 258
 259       The target file's prefix and suffix may be omitted,
 260       and the values from the
 261       &cv-link-OBJPREFIX;
 262       and
 263       &cv-link-OBJSUFFIX;
 264       construction variables
 265       will be appended appropriately.
 266       For example:
 267
 268       </para>
 269
 270       <programlisting>
 271 env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
 272 env.StaticObject('file', 'file.c')
 273       </programlisting>
 274
 275       <para>
 276
 277       Will create an object file named
 278       <filename>myfile.xxx</filename>
 279       regardless of the system on which it is run.
 280
 281       </para>
 282
 283       <para>
 284
 285       If you omit the &target;,
 286       the base of the first input
 287       file name specified
 288       beomces the base of the name
 289       of the static object file to be created.
 290       For example:
 291
 292       </para>
 293
 294       <programlisting>
 295 StaticObject('file.c')
 296       </programlisting>
 297
 298       <para>
 299
 300       Will create the &file_o;
 301       executable on a POSIX system,
 302       the &file_obj; executable on a Windows system.
 303
 304       </para>
 305
 306     </section>
 307
 308     <section>
 309     <title>The &SharedObject; Builder</title>
 310
 311       <para>
 312
 313       The &b-link-SharedObject; Builder
 314       is used to build an object file
 315       suitable for shared linking into a program,
 316       or for inclusion in a shared library.
 317       The &source; argument is a single source-code file,
 318       and the &target; argument is the
 319       name of the shared object file to be created.
 320       For example:
 321
 322       </para>
 323
 324       <programlisting>
 325 SharedObject('file', 'file.c')
 326       </programlisting>
 327
 328       <para>
 329
 330       Will create the &file_o;
 331       object file on a POSIX system,
 332       the &file_obj; executable on a Windows system.
 333
 334       </para>
 335
 336       <para>
 337
 338       The target file's prefix and suffix may be omitted,
 339       and the values from the
 340       &cv-link-SHOBJPREFIX;
 341       and
 342       &cv-link-SHOBJSUFFIX;
 343       construction variables
 344       will be appended appropriately.
 345       For example:
 346
 347       </para>
 348
 349       <programlisting>
 350 env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
 351 env.SharedObject('file', 'file.c')
 352       </programlisting>
 353
 354       <para>
 355
 356       Will create an object file named
 357       <filename>myfile.xxx</filename>
 358       regardless of the system on which it is run.
 359
 360       </para>
 361
 362       <para>
 363
 364       If you omit the &target;,
 365       the base of the first input
 366       file name specified
 367       becomes the base of the name
 368       of the shared object file to be created.
 369       For example:
 370
 371       </para>
 372
 373       <programlisting>
 374 SharedObject('file.c')
 375       </programlisting>
 376
 377       <para>
 378
 379       Will create the &file_o;
 380       executable on a POSIX system,
 381       the &file_obj; executable on a Windows system.
 382
 383       </para>
 384
 385     </section>
 386
 387     <section>
 388     <title>The &Object; Builder</title>
 389
 390       <para>
 391
 392       The &b-link-Object; Builder is a synonym for &b-link-StaticObject;
 393       and is completely equivalent.
 394
 395       </para>
 396
 397     </section>
 398
 399   </section>
 400
 401   <section>
 402   <title>Library Builders</title>
 403
 404     <para>
 405
 406     &SCons; provides separate Builder objects
 407     to create static and shared libraries.
 408
 409     </para>
 410
 411     <section>
 412     <title>The &StaticLibrary; Builder</title>
 413
 414       <para>
 415
 416       The &b-link-StaticLibrary; Builder
 417       is used to create a library
 418       suitable for static linking into a program.
 419       The &source; argument is one or more
 420       source-code files or object files,
 421       and the &target; argument is the
 422       name of the static library to be created.
 423       For example:
 424
 425       </para>
 426
 427       <programlisting>
 428 StaticLibrary('foo', ['file1.c', 'file2.c'])
 429       </programlisting>
 430
 431       <para>
 432
 433       The target file's prefix and suffix may be omitted,
 434       and the values from the
 435       &cv-link-LIBPREFIX;
 436       and
 437       &cv-link-LIBSUFFIX;
 438       construction variables
 439       will be appended appropriately.
 440       For example:
 441
 442       </para>
 443
 444       <programlisting>
 445 env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
 446 env.StaticLibrary('lib', ['file1.o', 'file2.o'])
 447       </programlisting>
 448
 449       <para>
 450
 451       Will create an object file named
 452       <filename>mylib.xxx</filename>
 453       regardless of the system on which it is run.
 454
 455       </para>
 456
 457       <programlisting>
 458 StaticLibrary('foo', ['file1.c', 'file2.c'])
 459       </programlisting>
 460
 461       <para>
 462
 463       If you omit the &target;,
 464       the base of the first input
 465       file name specified
 466       becomes the base of the name of the static object file to be created.
 467       For example:
 468
 469       </para>
 470
 471       <programlisting>
 472 StaticLibrary(['file.c', 'another.c'])
 473       </programlisting>
 474
 475       <para>
 476
 477       Will create the &libfile_a;
 478       library on a POSIX system,
 479       the &file_lib; library on a Windows system.
 480
 481       </para>
 482
 483     </section>
 484
 485     <section>
 486     <title>The &SharedLibrary; Builder</title>
 487
 488       <para>
 489
 490       The &b-link-SharedLibrary; Builder
 491       is used to create a shared library
 492       suitable for linking with a program.
 493       The &source; argument is one or more
 494       source-code files or object files,
 495       and the &target; argument is the
 496       name of the shared library to be created.
 497       For example:
 498
 499       </para>
 500
 501       <programlisting>
 502 SharedLibrary('foo', ['file1.c', 'file2.c'])
 503       </programlisting>
 504
 505       <para>
 506
 507       The target file's prefix and suffix may be omitted,
 508       and the values from the
 509       &cv-link-SHLIBPREFIX;
 510       and
 511       &cv-link-SHLIBSUFFIX;
 512       construction variables
 513       will be appended appropriately.
 514       For example:
 515
 516       </para>
 517
 518       <programlisting>
 519 env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
 520 env.SharedLibrary('shared', ['file1.o', 'file2.o'])
 521       </programlisting>
 522
 523       <para>
 524
 525       Will create an object file named
 526       <filename>myshared.xxx</filename>
 527       regardless of the system on which it is run.
 528
 529       </para>
 530
 531       <programlisting>
 532 SharedLibrary('foo', ['file1.c', 'file2.c'])
 533       </programlisting>
 534
 535       <para>
 536
 537       If you omit the &target;,
 538       the base of the first input
 539       file name specified
 540       becomes the base of the name of the shared library to be created.
 541       For example:
 542
 543       </para>
 544
 545       <programlisting>
 546 SharedLibrary(['file.c', 'another.c'])
 547       </programlisting>
 548
 549       <para>
 550
 551       Will create the &libfile_so;
 552       library on a POSIX system,
 553       the &file_dll; library on a Windows system.
 554
 555       </para>
 556
 557     </section>
 558
 559     <section>
 560     <title>The &Library; Builder</title>
 561
 562       <para>
 563
 564       The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary;
 565       and is completely equivalent.
 566
 567       </para>
 568
 569     </section>
 570
 571   </section>
 572
 573   <section>
 574   <title>Pre-Compiled Headers:  the &PCH; Builder</title>
 575
 576     <para>
 577
 578     XXX PCH()
 579
 580     </para>
 581
 582   </section>
 583
 584   <section>
 585   <title>&MSVC; Resource Files: the &RES; Builder</title>
 586
 587     <para>
 588
 589     XXX RES()
 590
 591     </para>
 592
 593   </section>
 594
 595   <section>
 596   <title>Source Files</title>
 597
 598     <para>
 599
 600     By default
 601     &SCons; supports two Builder objects
 602     that know how to build source files
 603     from other input files.
 604     These are typically invoked "internally"
 605     to turn files that need preprocessing into other source files.
 606
 607     </para>
 608
 609     <section>
 610     <title>The &CFile; Builder</title>
 611
 612       <para>
 613
 614       XXX CFile()
 615
 616       </para>
 617
 618       <programlisting>
 619 XXX CFile() programlisting
 620       </programlisting>
 621
 622       <screen>
 623 XXX CFile() screen
 624       </screen>
 625
 626     </section>
 627
 628     <section>
 629     <title>The &CXXFile; Builder</title>
 630
 631       <para>
 632
 633       XXX CXXFILE()
 634
 635       </para>
 636
 637       <programlisting>
 638 XXX CXXFILE() programlisting
 639       </programlisting>
 640
 641       <screen>
 642 XXX CXXFILE() screen
 643       </screen>
 644
 645     </section>
 646
 647   </section>
 648
 649   <section>
 650   <title>Documents</title>
 651
 652     <para>
 653
 654     &SCons; provides a number of Builder objects
 655     for creating different types of documents.
 656
 657     </para>
 658
 659     <section>
 660     <title>The &DVI; Builder</title>
 661
 662       <para>
 663
 664       XXX DVI() para
 665
 666       </para>
 667
 668       <programlisting>
 669 XXX DVI() programlisting
 670       </programlisting>
 671
 672       <screen>
 673 XXX DVI() screen
 674       </screen>
 675
 676     </section>
 677
 678     <section>
 679     <title>The &PDF; Builder</title>
 680
 681       <para>
 682
 683       XXX PDF() para
 684
 685       </para>
 686
 687     </section>
 688
 689     <section>
 690     <title>The &PostScript; Builder</title>
 691
 692       <para>
 693
 694       XXX PostScript() para
 695
 696       </para>
 697
 698       <programlisting>
 699 XXX PostScript() programlisting
 700       </programlisting>
 701
 702       <screen>
 703 XXX PostScript() screen
 704       </screen>
 705
 706     </section>
 707
 708   </section>
 709
 710   <section>
 711   <title>Archives</title>
 712
 713     <para>
 714
 715     &SCons; provides Builder objects
 716     for creating two different types of archive files.
 717
 718     </para>
 719
 720     <section>
 721     <title>The &Tar; Builder</title>
 722
 723       <para>
 724
 725       The &b-link-Tar; Builder object uses the &tar;
 726       utility to create archives of files
 727       and/or directory trees:
 728
 729       </para>
 730
 731       <scons_example name="buildersbuiltin_ex1">
 732         <file name="SConstruct" printme="1">
 733 env = Environment()
 734 env.Tar('out1.tar', ['file1', 'file2'])
 735 env.Tar('out2', 'directory')
 736         </file>
 737         <file name="file1">
 738 file1
 739         </file>
 740         <file name="file2">
 741 file2
 742         </file>
 743         <file name="directory/file3">
 744 directory/file3
 745         </file>
 746       </scons_example>
 747
 748       <scons_output example="buildersbuiltin_ex1" os="posix" suffix="1">
 749         <scons_output_command>scons -Q .</scons_output_command>
 750       </scons_output>
 751
 752       <para>
 753
 754       One common requirement when creating a &tar; archive
 755       is to create a compressed archive using the
 756       <option>-z</option> option.
 757       This is easily handled by specifying
 758       the value of the &cv-link-TARFLAGS; variable
 759       when you create the construction environment.
 760       Note, however, that the <option>-c</option> used to
 761       to instruct &tar; to create the archive
 762       is part of the default value of &cv-TARFLAGS;,
 763       so you need to set it both options:
 764
 765       </para>
 766
 767       <scons_example name="buildersbuiltin_ex2">
 768         <file name="SConstruct" printme="1">
 769 env = Environment(TARFLAGS = '-c -z')
 770 env.Tar('out.tar.gz', 'directory')
 771         </file>
 772         <file name="directory/file">
 773 directory/file
 774         </file>
 775       </scons_example>
 776
 777       <scons_output example="buildersbuiltin_ex2" os="posix" suffix="1">
 778         <scons_output_command>scons -Q .</scons_output_command>
 779       </scons_output>
 780
 781       <para>
 782
 783       you may also wish to set the value of the
 784       &cv-link-TARSUFFIX; construction variable
 785       to your desired suffix for compress &tar; archives,
 786       so that &SCons; can append it to the target file name
 787       without your having to specify it explicitly:
 788
 789       </para>
 790
 791       <scons_example name="buildersbuiltin_ex3">
 792         <file name="SConstruct" printme="1">
 793 env = Environment(TARFLAGS='-c -z', TARSUFFIX='.tgz')
 794 env.Tar('out', 'directory')
 795         </file>
 796         <file name="directory/file">
 797 directory/file
 798         </file>
 799       </scons_example>
 800
 801       <scons_output example="buildersbuiltin_ex3" os="posix" suffix="1">
 802         <scons_output_command>scons -Q .</scons_output_command>
 803       </scons_output>
 804
 805     </section>
 806
 807     <section>
 808     <title>The &Zip; Builder</title>
 809
 810       <para>
 811
 812       The &b-link-Zip; Builder object creates archives of files
 813       and/or directory trees in the ZIP file format.
 814       Python versions 1.6 or later
 815       contain an internal &zipfile; module
 816       that &SCons; will use.
 817       In this case, given the following
 818       &SConstruct; file:
 819
 820       </para>
 821
 822       <scons_example name="buildersbuiltin_ex4">
 823         <file name="SConstruct" printme="1">
 824 env = Environment()
 825 env.Zip('out', ['file1', 'file2'])
 826         </file>
 827         <file name="file1">
 828 file1
 829         </file>
 830         <file name="file2">
 831 file2
 832         </file>
 833       </scons_example>
 834
 835       <para>
 836
 837       Your output will reflect the fact
 838       that an internal Python function
 839       is being used to create the output ZIP archive:
 840
 841       </para>
 842
 843       <scons_output example="buildersbuiltin_ex4" os="posix" suffix="1">
 844         <scons_output_command>scons -Q .</scons_output_command>
 845       </scons_output>
 846
 847     </section>
 848
 849   </section>
 850
 851   <section>
 852   <title>Java</title>
 853
 854     <para>
 855
 856     &SCons; provides Builder objects
 857     for creating various types of Java output files.
 858
 859     </para>
 860
 861     <section>
 862     <title>Building Class Files:  the &Java; Builder</title>
 863
 864       <para>
 865
 866       The &b-link-Java; builder takes one or more input
 867       <filename>.java</filename> files
 868       and turns them into one or more
 869       <filename>.class</filename> files
 870       Unlike most builders, however,
 871       the &Java; builder takes
 872       target and source <emphasis>directories</emphasis>,
 873       not files, as input.
 874
 875       </para>
 876
 877       <programlisting>
 878 env = Environment()
 879 env.Java(target='classes', source='src')
 880       </programlisting>
 881
 882       <para>
 883
 884       The &Java; builder will then
 885       search the specified source directory
 886       tree for all <filename>.java</filename> files,
 887       and pass any out-of-date
 888
 889       </para>
 890
 891       <screen>
 892 XXX Java() screen
 893       </screen>
 894
 895     </section>
 896
 897     <section>
 898     <title>The &Jar; Builder</title>
 899
 900       <para>
 901
 902       XXX The &Jar; builder object
 903
 904       </para>
 905
 906       <programlisting>
 907 env = Environment()
 908 env.Java(target='classes', source='src')
 909 env.Jar(target='', source='classes')
 910       </programlisting>
 911
 912       <screen>
 913 XXX Jar() screen
 914       </screen>
 915
 916     </section>
 917
 918     <section>
 919     <title>Building C header and stub files:  the &JavaH; Builder</title>
 920
 921       <para>
 922
 923       XXX JavaH() para
 924
 925       </para>
 926
 927       <programlisting>
 928 XXX JavaH() programlisting
 929       </programlisting>
 930
 931       <screen>
 932 XXX JavaH() screen
 933       </screen>
 934
 935     </section>
 936
 937     <section>
 938     <title>Building RMI stub and skeleton class files:  the &RMIC; Builder</title>
 939
 940       <para>
 941
 942       XXX RMIC() para
 943
 944       </para>
 945
 946       <programlisting>
 947 XXX RMIC() programlisting
 948       </programlisting>
 949
 950       <screen>
 951 XXX RMIC() screen
 952       </screen>
 953
 954     </section>
 955
 956   </section>
 957
 958 </chapter>