doc/user/libraries.sgml

   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   It's often useful to organize large software projects
  29   by collecting parts of the software into one or more libraries.
  30   &SCons; makes it easy to create libraries
  31   and to use them in the programs.
  32
  33   </para>
  34
  35   <section>
  36   <title>Building Libraries</title>
  37
  38     <para>
  39
  40     You build your own libraries by specifying &Library;
  41     instead of &Program;:
  42
  43     </para>
  44
  45     <programlisting>
  46       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     <screen>
  59       % <userinput>scons -Q</userinput>
  60       cc -c -o f1.o f1.c
  61       cc -c -o f2.o f2.c
  62       cc -c -o f3.o f3.c
  63       ar r libfoo.a f1.o f2.o f3.o
  64       ranlib libfoo.a
  65     </screen>
  66
  67     <para>
  68
  69     On a Windows system,
  70     a build of the above example would look like:
  71
  72     </para>
  73
  74     <screen>
  75       C:\><userinput>scons -Q</userinput>
  76       cl /nologo /c f1.c /Fof1.obj
  77       cl /nologo /c f2.c /Fof2.obj
  78       cl /nologo /c f3.c /Fof3.obj
  79       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
  80     </screen>
  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     <title>Building Static Libraries Explicitly:  the &StaticLibrary; Builder</title>
  96
  97       <para>
  98
  99       The &Library; function builds a traditional static library.
 100       If you want to be explicit about the type of library being built,
 101       you can use the synonym &StaticLibrary; function
 102       instead of &Library;:
 103
 104       </para>
 105
 106       <programlisting>
 107         StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
 108       </programlisting>
 109
 110       <para>
 111
 112       There is no functional difference between the
 113       &StaticLibrary; and &Library; functions.
 114
 115       </para>
 116
 117     </section>
 118
 119     <section>
 120     <title>Building Shared (DLL) Libraries:  the &SharedLibrary; Builder</title>
 121
 122       <para>
 123
 124       If you want to build a shared library (on POSIX systems)
 125       or a DLL file (on Windows systems),
 126       you use the &SharedLibrary; function:
 127
 128       </para>
 129
 130       <programlisting>
 131         SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
 132       </programlisting>
 133
 134       <para>
 135
 136       The output on POSIX:
 137
 138       </para>
 139
 140       <screen>
 141         % <userinput>scons -Q</userinput>
 142         cc -c -o f1.os f1.c
 143         cc -c -o f2.os f2.c
 144         cc -c -o f3.os f3.c
 145         cc -shared -o libfoo.so f1.os f2.os f3.os
 146       </screen>
 147
 148       <para>
 149
 150       And the output on Windows:
 151
 152       </para>
 153
 154       <screen>
 155         C:\><userinput>scons -Q</userinput>
 156         cl /nologo /c f1.c /Fof1.obj
 157         cl /nologo /c f2.c /Fof2.obj
 158         cl /nologo /c f3.c /Fof3.obj
 159         link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
 160       </screen>
 161
 162       <para>
 163
 164       Notice again that &SCons; takes care of
 165       building the output file correctly,
 166       adding the <literal>-shared</literal> option
 167       for a POSIX compilation,
 168       and the <literal>/dll</literal> option on Windows.
 169
 170       </para>
 171
 172     </section>
 173
 174   </section>
 175
 176   <section>
 177   <title>Linking with Libraries</title>
 178
 179     <para>
 180
 181     Usually, you build a library
 182     because you want to link it with one or more programs.
 183     You link libraries with a program by specifying
 184     the libraries in the &LIBS; construction variable,
 185     and by specifying the directory in which
 186     the library will be found in the
 187     &LIBPATH; construction variable:
 188
 189     </para>
 190
 191     <programlisting>
 192       Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 193       Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
 194     </programlisting>
 195
 196     <para>
 197
 198     Notice, of course, that you don't need to specify a library
 199     prefix (like <literal>lib</literal>)
 200     or suffix (like <literal>.a</literal> or <literal>.lib</literal>).
 201     &SCons; uses the correct prefix or suffix for the current system.
 202
 203     </para>
 204
 205     <para>
 206
 207     On a POSIX or Linux system,
 208     a build of the above example would look like:
 209
 210     </para>
 211
 212     <screen>
 213       % <userinput>scons -Q</userinput>
 214       cc -c -o f1.o f1.c
 215       cc -c -o f2.o f2.c
 216       cc -c -o f3.o f3.c
 217       ar r libfoo.a f1.o f2.o f3.o
 218       ranlib libfoo.a
 219       cc -c -o prog.o prog.c
 220       cc -o prog prog.o -L. -lfoo -lbar
 221     </screen>
 222
 223     <para>
 224
 225     On a Windows system,
 226     a build of the above example would look like:
 227
 228     </para>
 229
 230     <screen>
 231       C:\><userinput>scons -Q</userinput>
 232       cl /nologo /c f1.c /Fof1.obj
 233       cl /nologo /c f2.c /Fof2.obj
 234       cl /nologo /c f3.c /Fof3.obj
 235       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
 236       cl /nologo /c prog.c /Foprog.obj
 237       link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
 238     </screen>
 239
 240     <para>
 241
 242     As usual, notice that &SCons; has taken care
 243     of constructing the correct command lines
 244     to link with the specified library on each system.
 245
 246     </para>
 247
 248     <para>
 249
 250     Note also that,
 251     if you only have a single library to link with,
 252     you can specify the library name in single string,
 253     instead of a Python list,
 254     so that:
 255
 256     </para>
 257
 258     <programlisting>
 259       Program('prog.c', LIBS='foo', LIBPATH='.')
 260     </programlisting>
 261
 262     <para>
 263
 264     is equivalent to:
 265
 266     </para>
 267
 268     <programlisting>
 269       Program('prog.c', LIBS=['foo'], LIBPATH='.')
 270     </programlisting>
 271
 272     <para>
 273
 274     This is similar to the way that &SCons;
 275     handles either a string or a list to
 276     specify a single source file.
 277
 278     </para>
 279
 280   </section>
 281
 282   <section>
 283   <title>Finding Libraries:  the &LIBPATH; Construction Variable</title>
 284
 285     <para>
 286
 287     By default, the linker will only look in
 288     certain system-defined directories for libraries.
 289     &SCons; knows how to look for libraries
 290     in directories that you specify with the
 291     &LIBPATH; construction variable.
 292     &LIBPATH; consists of a list of
 293     directory names, like so:
 294
 295     </para>
 296
 297     <programlisting>
 298       Program('prog.c', LIBS = 'm',
 299                         LIBPATH = ['/usr/lib', '/usr/local/lib'])
 300     </programlisting>
 301
 302     <para>
 303
 304     Using a Python list is preferred because it's portable
 305     across systems.  Alternatively, you could put all of
 306     the directory names in a single string, separated by the
 307     system-specific path separator character:
 308     a colon on POSIX systems:
 309
 310     </para>
 311
 312     <programlisting>
 313       LIBPATH = '/usr/lib:/usr/local/lib'
 314     </programlisting>
 315
 316     <para>
 317
 318     or a semi-colon on Windows systems:
 319
 320     </para>
 321
 322     <programlisting>
 323       LIBPATH = 'C:\\lib;D:\\lib'
 324     </programlisting>
 325
 326     <para>
 327
 328     (Note that Python requires that the backslash
 329     separators in a Windows path name
 330     be escaped within strings.)
 331
 332     </para>
 333
 334     <para>
 335
 336     When the linker is executed,
 337     &SCons; will create appropriate flags
 338     so that the linker will look for
 339     libraries in the same directories as &SCons;.
 340     So on a POSIX or Linux system,
 341     a build of the above example would look like:
 342
 343     </para>
 344
 345     <screen>
 346       % <userinput>scons -Q</userinput>
 347       cc -c -o prog.o prog.c
 348       cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
 349     </screen>
 350
 351     <para>
 352
 353     On a Windows system,
 354     a build of the above example would look like:
 355
 356     </para>
 357
 358     <screen>
 359       C:\><userinput>scons -Q</userinput>
 360       cl /nologo /c prog.c /Foprog.obj
 361       link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
 362     </screen>
 363
 364     <para>
 365
 366     Note again that &SCons; has taken care of
 367     the system-specific details of creating
 368     the right command-line options.
 369
 370     </para>
 371
 372   </section>