doc/user/libraries.sgml

   1 <!--
   2
   3   Copyright (c) 2001, 2002, 2003 Steven Knight
   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   One of the more useful ways in which you can use multiple
  29   construction environments is to link programs
  30   with different sets of libraries.
  31
  32   </para>
  33
  34   <section>
  35   <title>Building Libraries</title>
  36
  37     <para>
  38
  39     You build your own libraries by specifying &Library;
  40     instead of &Program;:
  41
  42     </para>
  43
  44     <programlisting>
  45       env = Environment()
  46       env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
  47     </programlisting>
  48
  49     <para>
  50
  51     &SCons; uses the appropriate library prefix and suffix for your system.
  52     So on POSIX or Linux systems,
  53     the above example would build as follows
  54     (although &ranlib may not be called on all systems):
  55
  56     </para>
  57
  58     <literallayout>
  59       % <userinput>scons</userinput>
  60       cc -c f1.c -o f1.o
  61       cc -c f2.c -o f2.o
  62       cc -c f3.c -o f3.o
  63       ar r libfoo.a f1.o f2.o f3.o
  64       ranlib libfoo.a
  65     </literallayout>
  66
  67     <para>
  68
  69     On a Windows system,
  70     a build of the above example would look like:
  71
  72     </para>
  73
  74     <literallayout>
  75       C:\><userinput>scons</userinput>
  76       cl /Fof1.obj f1.c
  77       cl /Fof2.obj f2.c
  78       cl /Fof3.obj f3.c
  79       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
  80     </literallayout>
  81
  82     <para>
  83
  84     The rules for the target name of the library
  85     are similar to those for programs:
  86     if you don't explicitly specify a target library name,
  87     &SCons; will deduce one from the
  88     name of the first source file specified,
  89     and &SCons; will add an appropriate
  90     file prefix and suffix if you leave them off.
  91
  92     </para>
  93
  94   </section>
  95
  96   <section>
  97   <title>Linking with Libraries</title>
  98
  99     <para>
 100
 101     Usually, the goal of building a library
 102     is to link it with one or more programs.
 103     You link libraries with a program by specifying
 104     the libraries in the &LIBS; construction variable,
 105     and by specifying the directory in which
 106     the library will be found in the
 107     &LIBPATH; construction variable:
 108
 109     </para>
 110
 111     <programlisting>
 112       env = Environment(LIBS = 'foo', LIBPATH = '.')
 113       env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 114       env.Program('prog.c')
 115     </programlisting>
 116
 117     <para>
 118
 119     Notice, of course, that you don't need to specify a library
 120     prefix (like <literal>lib</literal>)
 121     or suffix (like <literal>.a</literal> or <literal>.lib</literal>).
 122     &SCons; uses the correct prefix or suffix for the current system.
 123
 124     </para>
 125
 126     <para>
 127
 128     On a POSIX or Linux system,
 129     a build of the above example would look like:
 130
 131     </para>
 132
 133     <literallayout>
 134       % <userinput>scons</userinput>
 135       cc -c f1.c -o f1.o
 136       cc -c f2.c -o f2.o
 137       cc -c f3.c -o f3.o
 138       ar r libfoo.a f1.o f2.o f3.o
 139       ranlib libfoo.a
 140       cc -c prog.c -o prog.o
 141       cc -o prog -L. -lfoo prog.o
 142     </literallayout>
 143
 144     <para>
 145
 146     On a Windows system,
 147     a build of the above example would look like:
 148
 149     </para>
 150
 151     <literallayout>
 152       C:\><userinput>scons</userinput>
 153       cl /Fof1.obj f1.c
 154       cl /Fof2.obj f2.c
 155       cl /Fof3.obj f3.c
 156       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
 157       cl /Foprog.obj prog.c
 158       link /OUT:prog.exe /LIBPATH:. foo.lib prog.obj
 159     </literallayout>
 160
 161     <para>
 162
 163     As usual, notice that &SCons; has taken care
 164     of constructing the correct command lines
 165     to link with the specified library on each system.
 166
 167     </para>
 168
 169   </section>
 170
 171   <section>
 172   <title>Finding Libraries:  the &LIBPATH; Construction Variable</title>
 173
 174     <para>
 175
 176     By default, the linker will only look in
 177     certain system-defined directories for libraries.
 178     &SCons; knows how to look for libraries
 179     in directories that you specify with the
 180     &LIBPATH; construction variable.
 181     &LIBPATH; consists of a list of
 182     directory names, like so:
 183
 184     </para>
 185
 186     <programlisting>
 187       env = Environment(LIBS = 'm',
 188                         LIBPATH = ['/usr/lib', '/usr/local/lib'])
 189       env.Program('prog.c')
 190     </programlisting>
 191
 192     <para>
 193
 194     Using a Python list is preferred because it's portable
 195     across systems.  Alternatively, you could put all of
 196     the directory names in a single string, separated by the
 197     system-specific path separator character:
 198     a colon on POSIX systems:
 199
 200     </para>
 201
 202     <programlisting>
 203       LIBPATH = '/usr/lib:/usr/local/lib'
 204     </programlisting>
 205
 206     <para>
 207
 208     or a semi-colon on Windows systems:
 209
 210     </para>
 211
 212     <programlisting>
 213       LIBPATH = 'C:\lib;D:\lib'
 214     </programlisting>
 215
 216     <para>
 217
 218     On a POSIX or Linux system,
 219     a build of the above example would look like:
 220
 221     </para>
 222
 223     <literallayout>
 224       % <userinput>scons</userinput>
 225       cc -c prog.c -o prog.o
 226       cc -o prog -L/usr/lib -L/usr/local/lib -lm prog.o
 227     </literallayout>
 228
 229     <para>
 230
 231     On a Windows system,
 232     a build of the above example would look like:
 233
 234     </para>
 235
 236     <literallayout>
 237       C:\><userinput>scons</userinput>
 238       cl /Foprog.obj prog.c
 239       link /nologo /OUT:program.exe /LIBPATH:\usr\lib;\usr\local\lib m.lib prog.obj
 240     </literallayout>
 241
 242     <para>
 243
 244     Note again that &SCons; has taken care of
 245     the system-specific details of creating
 246     the right command-line options.
 247
 248     </para>
 249
 250   </section>