doc/user/builders-built-in.xml

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