doc/reference/Library.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE sconsdoc [
   3     <!ENTITY % scons SYSTEM "../scons.mod">
   4     %scons;
   5 ]>
   6
   7 <section id="sect-Library"
   8          xmlns="http://www.scons.org/dbxsd/v1.0"
   9          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  10          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  11 <title>The Library Builder</title>
  12
  13 <!--
  14
  15   __COPYRIGHT__
  16
  17   Permission is hereby granted, free of charge, to any person obtaining
  18   a copy of this software and associated documentation files (the
  19   "Software"), to deal in the Software without restriction, including
  20   without limitation the rights to use, copy, modify, merge, publish,
  21   distribute, sublicense, and/or sell copies of the Software, and to
  22   permit persons to whom the Software is furnished to do so, subject to
  23   the following conditions:
  24
  25   The above copyright notice and this permission notice shall be included
  26   in all copies or substantial portions of the Software.
  27
  28   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  29   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  30   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  31   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  32   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  33   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  34   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  35
  36 -->
  37
  38 <!--
  39
  40 =head2 The C<Library> method
  41
  42 The C<Library> method arranges to create the specified library from the
  43 specified object files. It is invoked as follows:
  44
  45   Library $env <library name>, <source or object files>;
  46
  47 The library name will have the value of the C<SUFLIB> construction
  48 variable appended (by default, C<.lib> on Win32 systems, C<.a> on Unix
  49 systems) if the suffix is not already present.
  50
  51 Source files may be specified in place of objects files-,-the C<Objects>
  52 method will be invoked to arrange the conversion of all the files into
  53 object files, and hence all the observations about the C<Objects> method,
  54 above, apply to this method also.
  55
  56 The actual creation of the library will be handled by an external
  57 command which results from expanding the C<ARCOM> construction variable,
  58 with C<%E<lt>> set to the library members (in the order presented),
  59 and C<%E<gt>> to the library to be created.  (See the section above
  60 on construction variable expansion for details.)  The user may set
  61 variables in the construction environment which will affect the
  62 operation of the command. These include C<AR>, the archive program
  63 to use, C<ARFLAGS>, which can be used to modify the flags given to
  64 the program specified by C<AR>, and C<RANLIB>, the name of a archive
  65 index generation program, if needed (if the particular need does not
  66 require the latter functionality, then C<ARCOM> must be redefined to not
  67 reference C<RANLIB>).
  68
  69 The C<Library> method allows the same library to be specified in multiple
  70 method invocations. All of the contributing objects from all the invocations
  71 (which may be from different directories) are combined and generated by a
  72 single archive command. Note, however, that if you prune a build so that
  73 only part of a library is specified, then only that part of the library will
  74 be generated (the rest will disappear!).
  75
  76 -->
  77
  78  <section>
  79  <title>Linking With a Library</title>
  80
  81    <programlisting>
  82 env = Environment(CC = 'gcc',
  83                   LIBS = 'world')
  84 env.Program('hello.c')
  85    </programlisting>
  86
  87    <literallayout>
  88 % <userinput>scons</userinput>
  89 gcc -c hello.c -o hello.o
  90 gcc -c world.c -o world.o
  91 gcc -o hello hello.o -lworld
  92    </literallayout>
  93
  94  </section>
  95
  96  <section>
  97  <title>Creating a Library</title>
  98
  99    <programlisting>
 100 env = Environment(CC = 'gcc',
 101                   LIBS = 'world')
 102 env.Program('hello.c')
 103 env.Library('world.c')
 104    </programlisting>
 105
 106    <literallayout>
 107 % <userinput>scons</userinput>
 108 gcc -c hello.c -o hello.o
 109 gcc -c world.c -o world.o
 110 ar r libworld.a world.o
 111 ar: creating libworld.a
 112 ranlib libworld.a
 113 gcc -o hello hello.o libworld.a
 114    </literallayout>
 115
 116  </section>
 117
 118 <!--
 119
 120 A key simplification of Cons is the idea of a B<construction environment>. A
 121 construction environment is an B<object> characterized by a set of key/value
 122 pairs and a set of B<methods>. In order to tell Cons how to build something,
 123 you invoke the appropriate method via an appropriate construction
 124 environment. Consider the following example:
 125
 126
 127
 128   $env = new cons(
 129         CC      =>      'gcc',
 130         LIBS    =>      'libworld.a'
 131   );
 132
 133   Program $env 'hello', 'hello.c';
 134
 135 In this case, rather than using the default construction environment, as is,
 136 we have overridden the value of C<CC> so that the GNU C Compiler equivalent
 137 is used, instead. Since this version of B<Hello, World!> requires a library,
 138 F<libworld.a>, we have specified that any program linked in this environment
 139 should be linked with that library. If the library exists already, well and
 140 good, but if not, then we'll also have to include the statement:
 141
 142
 143
 144   Library $env 'libworld', 'world.c';
 145
 146 Now if you type C<cons hello>, the library will be built before the program
 147 is linked, and, of course, C<gcc> will be used to compile both modules:
 148
 149
 150
 151   % cons hello
 152
 153 -->
 154
 155  <section>
 156  <title>The &Library; Builder</title>
 157
 158    <para>
 159
 160    X
 161
 162    </para>
 163
 164  </section>
 165
 166 </section>