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 &b-link-Library;
  41     instead of &b-link-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 &b-StaticLibrary; Builder</title>
  96
  97       <para>
  98
  99       The &b-link-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 &b-link-StaticLibrary; function
 102       instead of &b-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       &b-link-StaticLibrary; and &b-Library; functions.
 114
 115       </para>
 116
 117     </section>
 118
 119     <section>
 120     <title>Building Shared (DLL) Libraries:  the &b-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 &b-link-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         RegServerFunc(target, source, env)
 161       </screen>
 162
 163       <para>
 164
 165       Notice again that &SCons; takes care of
 166       building the output file correctly,
 167       adding the <literal>-shared</literal> option
 168       for a POSIX compilation,
 169       and the <literal>/dll</literal> option on Windows.
 170
 171       </para>
 172
 173     </section>
 174
 175   </section>
 176
 177   <section>
 178   <title>Linking with Libraries</title>
 179
 180     <para>
 181
 182     Usually, you build a library
 183     because you want to link it with one or more programs.
 184     You link libraries with a program by specifying
 185     the libraries in the &cv-link-LIBS; construction variable,
 186     and by specifying the directory in which
 187     the library will be found in the
 188     &cv-link-LIBPATH; construction variable:
 189
 190     </para>
 191
 192     <programlisting>
 193       Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 194       Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
 195     </programlisting>
 196
 197     <para>
 198
 199     Notice, of course, that you don't need to specify a library
 200     prefix (like <literal>lib</literal>)
 201     or suffix (like <literal>.a</literal> or <literal>.lib</literal>).
 202     &SCons; uses the correct prefix or suffix for the current system.
 203
 204     </para>
 205
 206     <para>
 207
 208     On a POSIX or Linux system,
 209     a build of the above example would look like:
 210
 211     </para>
 212
 213     <screen>
 214       % <userinput>scons -Q</userinput>
 215       cc -c -o f1.o f1.c
 216       cc -c -o f2.o f2.c
 217       cc -c -o f3.o f3.c
 218       ar r libfoo.a f1.o f2.o f3.o
 219       ranlib libfoo.a
 220       cc -c -o prog.o prog.c
 221       cc -o prog prog.o -L. -lfoo -lbar
 222     </screen>
 223
 224     <para>
 225
 226     On a Windows system,
 227     a build of the above example would look like:
 228
 229     </para>
 230
 231     <screen>
 232       C:\><userinput>scons -Q</userinput>
 233       cl /nologo /c f1.c /Fof1.obj
 234       cl /nologo /c f2.c /Fof2.obj
 235       cl /nologo /c f3.c /Fof3.obj
 236       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
 237       cl /nologo /c prog.c /Foprog.obj
 238       link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
 239     </screen>
 240
 241     <para>
 242
 243     As usual, notice that &SCons; has taken care
 244     of constructing the correct command lines
 245     to link with the specified library on each system.
 246
 247     </para>
 248
 249     <para>
 250
 251     Note also that,
 252     if you only have a single library to link with,
 253     you can specify the library name in single string,
 254     instead of a Python list,
 255     so that:
 256
 257     </para>
 258
 259     <programlisting>
 260       Program('prog.c', LIBS='foo', LIBPATH='.')
 261     </programlisting>
 262
 263     <para>
 264
 265     is equivalent to:
 266
 267     </para>
 268
 269     <programlisting>
 270       Program('prog.c', LIBS=['foo'], LIBPATH='.')
 271     </programlisting>
 272
 273     <para>
 274
 275     This is similar to the way that &SCons;
 276     handles either a string or a list to
 277     specify a single source file.
 278
 279     </para>
 280
 281   </section>
 282
 283   <section>
 284   <title>Finding Libraries:  the &cv-LIBPATH; Construction Variable</title>
 285
 286     <para>
 287
 288     By default, the linker will only look in
 289     certain system-defined directories for libraries.
 290     &SCons; knows how to look for libraries
 291     in directories that you specify with the
 292     &cv-link-LIBPATH; construction variable.
 293     &cv-LIBPATH; consists of a list of
 294     directory names, like so:
 295
 296     </para>
 297
 298     <programlisting>
 299       Program('prog.c', LIBS = 'm',
 300                         LIBPATH = ['/usr/lib', '/usr/local/lib'])
 301     </programlisting>
 302
 303     <para>
 304
 305     Using a Python list is preferred because it's portable
 306     across systems.  Alternatively, you could put all of
 307     the directory names in a single string, separated by the
 308     system-specific path separator character:
 309     a colon on POSIX systems:
 310
 311     </para>
 312
 313     <programlisting>
 314       LIBPATH = '/usr/lib:/usr/local/lib'
 315     </programlisting>
 316
 317     <para>
 318
 319     or a semi-colon on Windows systems:
 320
 321     </para>
 322
 323     <programlisting>
 324       LIBPATH = 'C:\\lib;D:\\lib'
 325     </programlisting>
 326
 327     <para>
 328
 329     (Note that Python requires that the backslash
 330     separators in a Windows path name
 331     be escaped within strings.)
 332
 333     </para>
 334
 335     <para>
 336
 337     When the linker is executed,
 338     &SCons; will create appropriate flags
 339     so that the linker will look for
 340     libraries in the same directories as &SCons;.
 341     So on a POSIX or Linux system,
 342     a build of the above example would look like:
 343
 344     </para>
 345
 346     <screen>
 347       % <userinput>scons -Q</userinput>
 348       cc -c -o prog.o prog.c
 349       cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
 350     </screen>
 351
 352     <para>
 353
 354     On a Windows system,
 355     a build of the above example would look like:
 356
 357     </para>
 358
 359     <screen>
 360       C:\><userinput>scons -Q</userinput>
 361       cl /nologo /c prog.c /Foprog.obj
 362       link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
 363     </screen>
 364
 365     <para>
 366
 367     Note again that &SCons; has taken care of
 368     the system-specific details of creating
 369     the right command-line options.
 370
 371     </para>
 372
 373   </section>