Merge commit 'upstream/1.2.0.d20091224'

1 files changed, 451 insertions, 0 deletions

diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml
new file mode 100644
index 0000000..e3821ce
--- /dev/null
+++ b/doc/user/libraries.xml
@@ -0,0 +1,451 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+  <para>
+
+  It's often useful to organize large software projects
+  by collecting parts of the software into one or more libraries.
+  &SCons; makes it easy to create libraries
+  and to use them in the programs.
+
+  </para>
+
+  <section>
+  <title>Building Libraries</title>
+
+    <para>
+
+    You build your own libraries by specifying &b-link-Library;
+    instead of &b-link-Program;:
+
+    </para>
+
+    <programlisting>
+      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+    </programlisting>
+
+    <para>
+
+    &SCons; uses the appropriate library prefix and suffix for your system.
+    So on POSIX or Linux systems,
+    the above example would build as follows
+    (although &ranlib; may not be called on all systems):
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o f1.o -c f1.c
+      cc -o f2.o -c f2.c
+      cc -o f3.o -c f3.c
+      ar rc libfoo.a f1.o f2.o f3.o
+      ranlib libfoo.a
+    </screen>
+
+    <para>
+
+    On a Windows system,
+    a build of the above example would look like:
+
+    </para>
+
+    <screen>
+      C:\><userinput>scons -Q</userinput>
+      
+      scons: warning: No installed VCs
+      File "&lt;stdin&gt;", line 67, in __call__
+      
+      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+      File "&lt;stdin&gt;", line 67, in __call__
+      cl /Fof1.obj /c f1.c /nologo
+      cl /Fof2.obj /c f2.c /nologo
+      cl /Fof3.obj /c f3.c /nologo
+      lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
+    </screen>
+
+    <para>
+
+    The rules for the target name of the library
+    are similar to those for programs:
+    if you don't explicitly specify a target library name,
+    &SCons; will deduce one from the
+    name of the first source file specified,
+    and &SCons; will add an appropriate
+    file prefix and suffix if you leave them off.
+
+    </para>
+
+    <section>
+    <title>Building Libraries From Source Code or Object Files</title>
+
+      <para>
+
+      The previous example shows building a library from a
+      list of source files.
+      You can, however, also give the &b-link-Library; call
+      object files,
+      and it will correctly realize
+      In fact, you can arbitrarily mix source code files
+      and object files in the source list:
+
+      </para>
+
+      <programlisting>
+        Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o'])
+      </programlisting>
+
+      <para>
+
+      And SCons realizes that only the source code files
+      must be compiled into object files
+      before creating the final library:
+
+      </para>
+
+      <screen>
+        % <userinput>scons -Q</userinput>
+        cc -o f1.o -c f1.c
+        cc -o f3.o -c f3.c
+        ar rc libfoo.a f1.o f2.o f3.o f4.o
+        ranlib libfoo.a
+      </screen>
+
+      <para>
+
+      Of course, in this example, the object files
+      must already exist for the build to succeed.
+      See <xref linkend="chap-nodes"></xref>, below,
+      for information about how you can
+      build object files explicitly
+      and include the built files in a library.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Building Static Libraries Explicitly:  the &b-StaticLibrary; Builder</title>
+
+      <para>
+
+      The &b-link-Library; function builds a traditional static library.
+      If you want to be explicit about the type of library being built,
+      you can use the synonym &b-link-StaticLibrary; function
+      instead of &b-Library;:
+
+      </para>
+
+      <programlisting>
+        StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+      </programlisting>
+
+      <para>
+
+      There is no functional difference between the
+      &b-link-StaticLibrary; and &b-Library; functions.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>Building Shared (DLL) Libraries:  the &b-SharedLibrary; Builder</title>
+
+      <para>
+
+      If you want to build a shared library (on POSIX systems)
+      or a DLL file (on Windows systems),
+      you use the &b-link-SharedLibrary; function:
+
+      </para>
+
+      <programlisting>
+        SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+      </programlisting>
+
+      <para>
+
+      The output on POSIX:
+
+      </para>
+
+      <screen>
+        % <userinput>scons -Q</userinput>
+        cc -o f1.os -c f1.c
+        cc -o f2.os -c f2.c
+        cc -o f3.os -c f3.c
+        cc -o libfoo.so -shared f1.os f2.os f3.os
+      </screen>
+
+      <para>
+
+      And the output on Windows:
+
+      </para>
+
+      <screen>
+        C:\><userinput>scons -Q</userinput>
+        
+        scons: warning: No installed VCs
+        File "&lt;stdin&gt;", line 67, in __call__
+        
+        scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+        File "&lt;stdin&gt;", line 67, in __call__
+        cl /Fof1.obj /c f1.c /nologo
+        cl /Fof2.obj /c f2.c /nologo
+        cl /Fof3.obj /c f3.c /nologo
+        link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
+        RegServerFunc(target, source, env)
+      </screen>
+
+      <para>
+
+      Notice again that &SCons; takes care of
+      building the output file correctly,
+      adding the <literal>-shared</literal> option
+      for a POSIX compilation,
+      and the <literal>/dll</literal> option on Windows.
+
+      </para>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Linking with Libraries</title>
+
+    <para>
+
+    Usually, you build a library
+    because you want to link it with one or more programs.
+    You link libraries with a program by specifying
+    the libraries in the &cv-link-LIBS; construction variable,
+    and by specifying the directory in which
+    the library will be found in the 
+    &cv-link-LIBPATH; construction variable:
+
+    <!-- In the preceding paragraph, the "$" notation for
+         LIBS, LIBPATH etc. is used for the first time.
+         Maybe some words of explanation would be nice. -->
+
+    </para>
+
+    <programlisting>
+      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+      Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
+    </programlisting>
+
+    <para>
+
+    Notice, of course, that you don't need to specify a library
+    prefix (like <literal>lib</literal>)
+    or suffix (like <literal>.a</literal> or <literal>.lib</literal>).
+    &SCons; uses the correct prefix or suffix for the current system.
+
+    </para>
+
+    <para>
+
+    On a POSIX or Linux system,
+    a build of the above example would look like:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o f1.o -c f1.c
+      cc -o f2.o -c f2.c
+      cc -o f3.o -c f3.c
+      ar rc libfoo.a f1.o f2.o f3.o
+      ranlib libfoo.a
+      cc -o prog.o -c prog.c
+      cc -o prog prog.o -L. -lfoo -lbar
+    </screen>
+
+    <para>
+
+    On a Windows system,
+    a build of the above example would look like:
+
+    </para>
+
+    <screen>
+      C:\><userinput>scons -Q</userinput>
+      
+      scons: warning: No installed VCs
+      File "&lt;stdin&gt;", line 67, in __call__
+      
+      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+      File "&lt;stdin&gt;", line 67, in __call__
+      cl /Fof1.obj /c f1.c /nologo
+      cl /Fof2.obj /c f2.c /nologo
+      cl /Fof3.obj /c f3.c /nologo
+      lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
+      cl /Foprog.obj /c prog.c /nologo
+      link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
+    </screen>
+
+    <para>
+
+    As usual, notice that &SCons; has taken care
+    of constructing the correct command lines
+    to link with the specified library on each system.
+
+    </para>
+
+    <para>
+
+    Note also that,
+    if you only have a single library to link with,
+    you can specify the library name in single string,
+    instead of a Python list,
+    so that:
+
+    </para>
+
+    <programlisting>
+      Program('prog.c', LIBS='foo', LIBPATH='.')
+    </programlisting>
+
+    <para>
+
+    is equivalent to:
+
+    </para>
+
+    <programlisting>
+      Program('prog.c', LIBS=['foo'], LIBPATH='.')
+    </programlisting>
+
+    <para>
+
+    This is similar to the way that &SCons;
+    handles either a string or a list to
+    specify a single source file.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Finding Libraries:  the &cv-LIBPATH; Construction Variable</title>
+
+    <para>
+
+    By default, the linker will only look in
+    certain system-defined directories for libraries.
+    &SCons; knows how to look for libraries
+    in directories that you specify with the
+    &cv-link-LIBPATH; construction variable.
+    &cv-LIBPATH; consists of a list of
+    directory names, like so:
+
+    </para>
+
+    <programlisting>
+      Program('prog.c', LIBS = 'm',
+                        LIBPATH = ['/usr/lib', '/usr/local/lib'])
+    </programlisting>
+
+    <para>
+
+    Using a Python list is preferred because it's portable
+    across systems.  Alternatively, you could put all of
+    the directory names in a single string, separated by the
+    system-specific path separator character:
+    a colon on POSIX systems:
+
+    </para>
+
+    <programlisting>
+      LIBPATH = '/usr/lib:/usr/local/lib'
+    </programlisting>
+
+    <para>
+
+    or a semi-colon on Windows systems:
+
+    </para>
+
+    <programlisting>
+      LIBPATH = 'C:\\lib;D:\\lib'
+    </programlisting>
+
+    <para>
+
+    (Note that Python requires that the backslash
+    separators in a Windows path name
+    be escaped within strings.)
+
+    </para>
+
+    <para>
+
+    When the linker is executed,
+    &SCons; will create appropriate flags
+    so that the linker will look for
+    libraries in the same directories as &SCons;.
+    So on a POSIX or Linux system,
+    a build of the above example would look like:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o prog.o -c prog.c
+      cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
+    </screen>
+
+    <para>
+
+    On a Windows system,
+    a build of the above example would look like:
+
+    </para>
+
+    <screen>
+      C:\><userinput>scons -Q</userinput>
+      
+      scons: warning: No installed VCs
+      File "&lt;stdin&gt;", line 67, in __call__
+      
+      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+      File "&lt;stdin&gt;", line 67, in __call__
+      cl /Foprog.obj /c prog.c /nologo
+      link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
+    </screen>
+    <!-- The link command is too wide in the PDF version. 
+         There are some other examples of this throughout the document. -->
+
+    <para>
+
+    Note again that &SCons; has taken care of
+    the system-specific details of creating
+    the right command-line options.
+
+    </para>
+
+  </section>