doc/user/libraries.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   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 -o f1.o -c f1.c
  61       cc -o f2.o -c f2.c
  62       cc -o f3.o -c f3.c
  63       ar rc 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
  77       scons: warning: No installed VCs
  78       File "&lt;stdin&gt;", line 67, in __call__
  79
  80       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
  81       File "&lt;stdin&gt;", line 67, in __call__
  82       cl /Fof1.obj /c f1.c /nologo
  83       cl /Fof2.obj /c f2.c /nologo
  84       cl /Fof3.obj /c f3.c /nologo
  85       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
  86     </screen>
  87
  88     <para>
  89
  90     The rules for the target name of the library
  91     are similar to those for programs:
  92     if you don't explicitly specify a target library name,
  93     &SCons; will deduce one from the
  94     name of the first source file specified,
  95     and &SCons; will add an appropriate
  96     file prefix and suffix if you leave them off.
  97
  98     </para>
  99
 100     <section>
 101     <title>Building Libraries From Source Code or Object Files</title>
 102
 103       <para>
 104
 105       The previous example shows building a library from a
 106       list of source files.
 107       You can, however, also give the &b-link-Library; call
 108       object files,
 109       and it will correctly realize
 110       In fact, you can arbitrarily mix source code files
 111       and object files in the source list:
 112
 113       </para>
 114
 115       <programlisting>
 116         Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o'])
 117       </programlisting>
 118
 119       <para>
 120
 121       And SCons realizes that only the source code files
 122       must be compiled into object files
 123       before creating the final library:
 124
 125       </para>
 126
 127       <screen>
 128         % <userinput>scons -Q</userinput>
 129         cc -o f1.o -c f1.c
 130         cc -o f3.o -c f3.c
 131         ar rc libfoo.a f1.o f2.o f3.o f4.o
 132         ranlib libfoo.a
 133       </screen>
 134
 135       <para>
 136
 137       Of course, in this example, the object files
 138       must already exist for the build to succeed.
 139       See <xref linkend="chap-nodes"></xref>, below,
 140       for information about how you can
 141       build object files explicitly
 142       and include the built files in a library.
 143
 144       </para>
 145
 146     </section>
 147
 148     <section>
 149     <title>Building Static Libraries Explicitly:  the &b-StaticLibrary; Builder</title>
 150
 151       <para>
 152
 153       The &b-link-Library; function builds a traditional static library.
 154       If you want to be explicit about the type of library being built,
 155       you can use the synonym &b-link-StaticLibrary; function
 156       instead of &b-Library;:
 157
 158       </para>
 159
 160       <programlisting>
 161         StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
 162       </programlisting>
 163
 164       <para>
 165
 166       There is no functional difference between the
 167       &b-link-StaticLibrary; and &b-Library; functions.
 168
 169       </para>
 170
 171     </section>
 172
 173     <section>
 174     <title>Building Shared (DLL) Libraries:  the &b-SharedLibrary; Builder</title>
 175
 176       <para>
 177
 178       If you want to build a shared library (on POSIX systems)
 179       or a DLL file (on Windows systems),
 180       you use the &b-link-SharedLibrary; function:
 181
 182       </para>
 183
 184       <programlisting>
 185         SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
 186       </programlisting>
 187
 188       <para>
 189
 190       The output on POSIX:
 191
 192       </para>
 193
 194       <screen>
 195         % <userinput>scons -Q</userinput>
 196         cc -o f1.os -c f1.c
 197         cc -o f2.os -c f2.c
 198         cc -o f3.os -c f3.c
 199         cc -o libfoo.so -shared f1.os f2.os f3.os
 200       </screen>
 201
 202       <para>
 203
 204       And the output on Windows:
 205
 206       </para>
 207
 208       <screen>
 209         C:\><userinput>scons -Q</userinput>
 210
 211         scons: warning: No installed VCs
 212         File "&lt;stdin&gt;", line 67, in __call__
 213
 214         scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
 215         File "&lt;stdin&gt;", line 67, in __call__
 216         cl /Fof1.obj /c f1.c /nologo
 217         cl /Fof2.obj /c f2.c /nologo
 218         cl /Fof3.obj /c f3.c /nologo
 219         link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
 220         RegServerFunc(target, source, env)
 221       </screen>
 222
 223       <para>
 224
 225       Notice again that &SCons; takes care of
 226       building the output file correctly,
 227       adding the <literal>-shared</literal> option
 228       for a POSIX compilation,
 229       and the <literal>/dll</literal> option on Windows.
 230
 231       </para>
 232
 233     </section>
 234
 235   </section>
 236
 237   <section>
 238   <title>Linking with Libraries</title>
 239
 240     <para>
 241
 242     Usually, you build a library
 243     because you want to link it with one or more programs.
 244     You link libraries with a program by specifying
 245     the libraries in the &cv-link-LIBS; construction variable,
 246     and by specifying the directory in which
 247     the library will be found in the
 248     &cv-link-LIBPATH; construction variable:
 249
 250     <!-- In the preceding paragraph, the "$" notation for
 251          LIBS, LIBPATH etc. is used for the first time.
 252          Maybe some words of explanation would be nice. -->
 253
 254     </para>
 255
 256     <programlisting>
 257       Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 258       Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
 259     </programlisting>
 260
 261     <para>
 262
 263     Notice, of course, that you don't need to specify a library
 264     prefix (like <literal>lib</literal>)
 265     or suffix (like <literal>.a</literal> or <literal>.lib</literal>).
 266     &SCons; uses the correct prefix or suffix for the current system.
 267
 268     </para>
 269
 270     <para>
 271
 272     On a POSIX or Linux system,
 273     a build of the above example would look like:
 274
 275     </para>
 276
 277     <screen>
 278       % <userinput>scons -Q</userinput>
 279       cc -o f1.o -c f1.c
 280       cc -o f2.o -c f2.c
 281       cc -o f3.o -c f3.c
 282       ar rc libfoo.a f1.o f2.o f3.o
 283       ranlib libfoo.a
 284       cc -o prog.o -c prog.c
 285       cc -o prog prog.o -L. -lfoo -lbar
 286     </screen>
 287
 288     <para>
 289
 290     On a Windows system,
 291     a build of the above example would look like:
 292
 293     </para>
 294
 295     <screen>
 296       C:\><userinput>scons -Q</userinput>
 297
 298       scons: warning: No installed VCs
 299       File "&lt;stdin&gt;", line 67, in __call__
 300
 301       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
 302       File "&lt;stdin&gt;", line 67, in __call__
 303       cl /Fof1.obj /c f1.c /nologo
 304       cl /Fof2.obj /c f2.c /nologo
 305       cl /Fof3.obj /c f3.c /nologo
 306       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
 307       cl /Foprog.obj /c prog.c /nologo
 308       link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
 309     </screen>
 310
 311     <para>
 312
 313     As usual, notice that &SCons; has taken care
 314     of constructing the correct command lines
 315     to link with the specified library on each system.
 316
 317     </para>
 318
 319     <para>
 320
 321     Note also that,
 322     if you only have a single library to link with,
 323     you can specify the library name in single string,
 324     instead of a Python list,
 325     so that:
 326
 327     </para>
 328
 329     <programlisting>
 330       Program('prog.c', LIBS='foo', LIBPATH='.')
 331     </programlisting>
 332
 333     <para>
 334
 335     is equivalent to:
 336
 337     </para>
 338
 339     <programlisting>
 340       Program('prog.c', LIBS=['foo'], LIBPATH='.')
 341     </programlisting>
 342
 343     <para>
 344
 345     This is similar to the way that &SCons;
 346     handles either a string or a list to
 347     specify a single source file.
 348
 349     </para>
 350
 351   </section>
 352
 353   <section>
 354   <title>Finding Libraries:  the &cv-LIBPATH; Construction Variable</title>
 355
 356     <para>
 357
 358     By default, the linker will only look in
 359     certain system-defined directories for libraries.
 360     &SCons; knows how to look for libraries
 361     in directories that you specify with the
 362     &cv-link-LIBPATH; construction variable.
 363     &cv-LIBPATH; consists of a list of
 364     directory names, like so:
 365
 366     </para>
 367
 368     <programlisting>
 369       Program('prog.c', LIBS = 'm',
 370                         LIBPATH = ['/usr/lib', '/usr/local/lib'])
 371     </programlisting>
 372
 373     <para>
 374
 375     Using a Python list is preferred because it's portable
 376     across systems.  Alternatively, you could put all of
 377     the directory names in a single string, separated by the
 378     system-specific path separator character:
 379     a colon on POSIX systems:
 380
 381     </para>
 382
 383     <programlisting>
 384       LIBPATH = '/usr/lib:/usr/local/lib'
 385     </programlisting>
 386
 387     <para>
 388
 389     or a semi-colon on Windows systems:
 390
 391     </para>
 392
 393     <programlisting>
 394       LIBPATH = 'C:\\lib;D:\\lib'
 395     </programlisting>
 396
 397     <para>
 398
 399     (Note that Python requires that the backslash
 400     separators in a Windows path name
 401     be escaped within strings.)
 402
 403     </para>
 404
 405     <para>
 406
 407     When the linker is executed,
 408     &SCons; will create appropriate flags
 409     so that the linker will look for
 410     libraries in the same directories as &SCons;.
 411     So on a POSIX or Linux system,
 412     a build of the above example would look like:
 413
 414     </para>
 415
 416     <screen>
 417       % <userinput>scons -Q</userinput>
 418       cc -o prog.o -c prog.c
 419       cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
 420     </screen>
 421
 422     <para>
 423
 424     On a Windows system,
 425     a build of the above example would look like:
 426
 427     </para>
 428
 429     <screen>
 430       C:\><userinput>scons -Q</userinput>
 431
 432       scons: warning: No installed VCs
 433       File "&lt;stdin&gt;", line 67, in __call__
 434
 435       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
 436       File "&lt;stdin&gt;", line 67, in __call__
 437       cl /Foprog.obj /c prog.c /nologo
 438       link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
 439     </screen>
 440     <!-- The link command is too wide in the PDF version.
 441          There are some other examples of this throughout the document. -->
 442
 443     <para>
 444
 445     Note again that &SCons; has taken care of
 446     the system-specific details of creating
 447     the right command-line options.
 448
 449     </para>
 450
 451   </section>