doc/user/libraries.in

   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     <scons_example name="ex1" printme="1">
  46       <file name="SConstruct" printme="1">
  47       Library('foo', ['f1.c', 'f2.c', 'f3.c'])
  48       </file>
  49       <file name="f1.c">
  50       void f1() { printf("f1.c\n"); }
  51       </file>
  52       <file name="f2.c">
  53       void f2() { printf("f2.c\n"); }
  54       </file>
  55       <file name="f3.c">
  56       void f3() { printf("f3.c\n"); }
  57       </file>
  58     </scons_example>
  59
  60     <para>
  61
  62     &SCons; uses the appropriate library prefix and suffix for your system.
  63     So on POSIX or Linux systems,
  64     the above example would build as follows
  65     (although &ranlib may not be called on all systems):
  66
  67     </para>
  68
  69     <scons_output example="ex1" os="posix">
  70       <scons_output_command>scons -Q</scons_output_command>
  71     </scons_output>
  72
  73     <para>
  74
  75     On a Windows system,
  76     a build of the above example would look like:
  77
  78     </para>
  79
  80     <scons_output example="ex1" os="win32">
  81       <scons_output_command>scons -Q</scons_output_command>
  82     </scons_output>
  83
  84     <para>
  85
  86     The rules for the target name of the library
  87     are similar to those for programs:
  88     if you don't explicitly specify a target library name,
  89     &SCons; will deduce one from the
  90     name of the first source file specified,
  91     and &SCons; will add an appropriate
  92     file prefix and suffix if you leave them off.
  93
  94     </para>
  95
  96     <section>
  97     <title>Building Static Libraries Explicitly:  the &b-StaticLibrary; Builder</title>
  98
  99       <para>
 100
 101       The &b-link-Library; function builds a traditional static library.
 102       If you want to be explicit about the type of library being built,
 103       you can use the synonym &b-link-StaticLibrary; function
 104       instead of &b-Library:
 105
 106       </para>
 107
 108       <scons_example name="StaticLibrary" printme="1">
 109         <file name="SConstruct" printme="1">
 110         StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
 111         </file>
 112       </scons_example>
 113
 114       <para>
 115
 116       There is no functional difference between the
 117       &b-link-StaticLibrary; and &b-Library; functions.
 118
 119       </para>
 120
 121     </section>
 122
 123     <section>
 124     <title>Building Shared (DLL) Libraries:  the &b-SharedLibrary; Builder</title>
 125
 126       <para>
 127
 128       If you want to build a shared library (on POSIX systems)
 129       or a DLL file (on Windows systems),
 130       you use the &b-link-SharedLibrary; function:
 131
 132       </para>
 133
 134       <scons_example name="SharedLibrary" printme="1">
 135         <file name="SConstruct" printme="1">
 136         SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
 137         </file>
 138         <file name="f1.c">
 139         void f1() { printf("f1.c\n"); }
 140         </file>
 141         <file name="f2.c">
 142         void f2() { printf("f2.c\n"); }
 143         </file>
 144         <file name="f3.c">
 145         void f3() { printf("f3.c\n"); }
 146         </file>
 147       </scons_example>
 148
 149       <para>
 150
 151       The output on POSIX:
 152
 153       </para>
 154
 155       <scons_output example="SharedLibrary" os="posix">
 156         <scons_output_command>scons -Q</scons_output_command>
 157       </scons_output>
 158
 159       <para>
 160
 161       And the output on Windows:
 162
 163       </para>
 164
 165       <scons_output example="SharedLibrary" os="win32">
 166         <scons_output_command>scons -Q</scons_output_command>
 167       </scons_output>
 168
 169       <para>
 170
 171       Notice again that &SCons; takes care of
 172       building the output file correctly,
 173       adding the <literal>-shared</literal> option
 174       for a POSIX compilation,
 175       and the <literal>/dll</literal> option on Windows.
 176
 177       </para>
 178
 179     </section>
 180
 181   </section>
 182
 183   <section>
 184   <title>Linking with Libraries</title>
 185
 186     <para>
 187
 188     Usually, you build a library
 189     because you want to link it with one or more programs.
 190     You link libraries with a program by specifying
 191     the libraries in the &cv-link-LIBS; construction variable,
 192     and by specifying the directory in which
 193     the library will be found in the
 194     &cv-link-LIBPATH; construction variable:
 195
 196     </para>
 197
 198     <scons_example name="ex2">
 199       <file name="SConstruct" printme="1">
 200       Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 201       Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
 202       </file>
 203       <file name="f1.c">
 204       int main() { printf("Hello, world!\n"); }
 205       </file>
 206       <file name="f2.c">
 207       int main() { printf("Hello, world!\n"); }
 208       </file>
 209       <file name="f3.c">
 210       int main() { printf("Hello, world!\n"); }
 211       </file>
 212       <file name="prog.c">
 213       int main() { printf("Hello, world!\n"); }
 214       </file>
 215     </scons_example>
 216
 217     <para>
 218
 219     Notice, of course, that you don't need to specify a library
 220     prefix (like <literal>lib</literal>)
 221     or suffix (like <literal>.a</literal> or <literal>.lib</literal>).
 222     &SCons; uses the correct prefix or suffix for the current system.
 223
 224     </para>
 225
 226     <para>
 227
 228     On a POSIX or Linux system,
 229     a build of the above example would look like:
 230
 231     </para>
 232
 233     <scons_output example="ex2" os="posix">
 234       <scons_output_command>scons -Q</scons_output_command>
 235     </scons_output>
 236
 237     <para>
 238
 239     On a Windows system,
 240     a build of the above example would look like:
 241
 242     </para>
 243
 244     <scons_output example="ex2" os="win32">
 245       <scons_output_command>scons -Q</scons_output_command>
 246     </scons_output>
 247
 248     <para>
 249
 250     As usual, notice that &SCons; has taken care
 251     of constructing the correct command lines
 252     to link with the specified library on each system.
 253
 254     </para>
 255
 256     <para>
 257
 258     Note also that,
 259     if you only have a single library to link with,
 260     you can specify the library name in single string,
 261     instead of a Python list,
 262     so that:
 263
 264     </para>
 265
 266     <sconstruct>
 267       Program('prog.c', LIBS='foo', LIBPATH='.')
 268     </sconstruct>
 269
 270     <para>
 271
 272     is equivalent to:
 273
 274     </para>
 275
 276     <sconstruct>
 277       Program('prog.c', LIBS=['foo'], LIBPATH='.')
 278     </sconstruct>
 279
 280     <para>
 281
 282     This is similar to the way that &SCons;
 283     handles either a string or a list to
 284     specify a single source file.
 285
 286     </para>
 287
 288   </section>
 289
 290   <section>
 291   <title>Finding Libraries:  the &cv-LIBPATH; Construction Variable</title>
 292
 293     <para>
 294
 295     By default, the linker will only look in
 296     certain system-defined directories for libraries.
 297     &SCons; knows how to look for libraries
 298     in directories that you specify with the
 299     &cv-link-LIBPATH; construction variable.
 300     &cv-LIBPATH; consists of a list of
 301     directory names, like so:
 302
 303     </para>
 304
 305     <scons_example name="ex3">
 306       <file name="SConstruct" printme="1">
 307       Program('prog.c', LIBS = 'm',
 308                         LIBPATH = ['/usr/lib', '/usr/local/lib'])
 309       </file>
 310       <file name="prog.c">
 311       int main() { printf("prog.c\n"); }
 312       </file>
 313     </scons_example>
 314
 315     <para>
 316
 317     Using a Python list is preferred because it's portable
 318     across systems.  Alternatively, you could put all of
 319     the directory names in a single string, separated by the
 320     system-specific path separator character:
 321     a colon on POSIX systems:
 322
 323     </para>
 324
 325     <sconstruct>
 326       LIBPATH = '/usr/lib:/usr/local/lib'
 327     </sconstruct>
 328
 329     <para>
 330
 331     or a semi-colon on Windows systems:
 332
 333     </para>
 334
 335     <sconstruct>
 336       LIBPATH = 'C:\\lib;D:\\lib'
 337     </sconstruct>
 338
 339     <para>
 340
 341     (Note that Python requires that the backslash
 342     separators in a Windows path name
 343     be escaped within strings.)
 344
 345     </para>
 346
 347     <para>
 348
 349     When the linker is executed,
 350     &SCons; will create appropriate flags
 351     so that the linker will look for
 352     libraries in the same directories as &SCons;.
 353     So on a POSIX or Linux system,
 354     a build of the above example would look like:
 355
 356     </para>
 357
 358     <scons_output example="ex3" os="posix">
 359       <scons_output_command>scons -Q</scons_output_command>
 360     </scons_output>
 361
 362     <para>
 363
 364     On a Windows system,
 365     a build of the above example would look like:
 366
 367     </para>
 368
 369     <scons_output example="ex3" os="win32">
 370       <scons_output_command>scons -Q</scons_output_command>
 371     </scons_output>
 372
 373     <para>
 374
 375     Note again that &SCons; has taken care of
 376     the system-specific details of creating
 377     the right command-line options.
 378
 379     </para>
 380
 381   </section>