Merge tag 'upstream/2.3.1'

Upstream version 2.3.1

1 files changed, 140 insertions, 102 deletions

diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml
index f3a5492..aa4561e 100644
--- a/doc/user/libraries.xml
+++ b/doc/user/libraries.xml
@@ -1,6 +1,27 @@
+<?xml version='1.0'?>
+<!DOCTYPE sconsdoc [
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+    
+    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
+    %builders-mod;
+    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
+    %functions-mod;
+    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
+    %tools-mod;
+    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
+    %variables-mod;
+]>
+
+<chapter id="chap-libraries"
+         xmlns="http://www.scons.org/dbxsd/v1.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
+<title>Building and Linking with Libraries</title>
+
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -42,9 +63,20 @@
 
     </para>
 
-    <programlisting>
-      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
-    </programlisting>
+    <scons_example name="libraries_ex1" printme="1">
+      <file name="SConstruct" printme="1">
+Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+      </file>
+      <file name="f1.c">
+void f1() { printf("f1.c\n"); }
+      </file>
+      <file name="f2.c">
+void f2() { printf("f2.c\n"); }
+      </file>
+      <file name="f3.c">
+void f3() { printf("f3.c\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -55,14 +87,9 @@
 
     </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>
+    <scons_output example="libraries_ex1" os="posix" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -71,13 +98,9 @@
 
     </para>
 
-    <screen>
-      C:\><userinput>scons -Q</userinput>
-      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>
+    <scons_output example="libraries_ex1" os="win32" suffix="2">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -106,9 +129,23 @@
 
       </para>
 
-      <programlisting>
-        Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o'])
-      </programlisting>
+      <scons_example name="libraries_objects" printme="1">
+        <file name="SConstruct" printme="1">
+Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o'])
+        </file>
+        <file name="f1.c">
+void f1() { printf("f1.c\n"); }
+        </file>
+        <file name="f2.o">
+object file
+        </file>
+        <file name="f3.c">
+void f3() { printf("f3.c\n"); }
+        </file>
+        <file name="f4.o">
+object file
+        </file>
+      </scons_example>
 
       <para>
 
@@ -118,13 +155,9 @@
 
       </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>
+      <scons_output example="libraries_objects" os="posix" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -151,9 +184,11 @@
 
       </para>
 
-      <programlisting>
-        StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
-      </programlisting>
+      <scons_example name="libraries_StaticLibrary" printme="1">
+        <file name="SConstruct" printme="1">
+StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+        </file>
+      </scons_example>
 
       <para>
 
@@ -175,9 +210,20 @@
 
       </para>
 
-      <programlisting>
-        SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
-      </programlisting>
+      <scons_example name="libraries_SharedLibrary" printme="1">
+        <file name="SConstruct" printme="1">
+SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+        </file>
+        <file name="f1.c">
+void f1() { printf("f1.c\n"); }
+        </file>
+        <file name="f2.c">
+void f2() { printf("f2.c\n"); }
+        </file>
+        <file name="f3.c">
+void f3() { printf("f3.c\n"); }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -185,13 +231,9 @@
 
       </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>
+      <scons_output example="libraries_SharedLibrary" os="posix" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -199,15 +241,9 @@
 
       </para>
 
-      <screen>
-        C:\><userinput>scons -Q</userinput>
-        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)
-        embedManifestDllCheck(target, source, env)
-      </screen>
+      <scons_output example="libraries_SharedLibrary" os="win32" suffix="2">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -242,10 +278,24 @@
 
     </para>
 
-    <programlisting>
-      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
-      Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
-    </programlisting>
+    <scons_example name="libraries_ex2">
+      <file name="SConstruct" printme="1">
+Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
+      </file>
+      <file name="f1.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+      <file name="f2.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+      <file name="f3.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+      <file name="prog.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -263,16 +313,9 @@
 
     </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>
+    <scons_output example="libraries_ex2" os="posix" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -281,16 +324,9 @@
 
     </para>
 
-    <screen>
-      C:\><userinput>scons -Q</userinput>
-      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
-      embedManifestExeCheck(target, source, env)
-    </screen>
+    <scons_output example="libraries_ex2" os="win32" suffix="2">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -310,9 +346,9 @@
 
     </para>
 
-    <programlisting>
-      Program('prog.c', LIBS='foo', LIBPATH='.')
-    </programlisting>
+    <sconstruct>
+Program('prog.c', LIBS='foo', LIBPATH='.')
+    </sconstruct>
 
     <para>
 
@@ -320,9 +356,9 @@
 
     </para>
 
-    <programlisting>
-      Program('prog.c', LIBS=['foo'], LIBPATH='.')
-    </programlisting>
+    <sconstruct>
+Program('prog.c', LIBS=['foo'], LIBPATH='.')
+    </sconstruct>
 
     <para>
 
@@ -349,10 +385,15 @@
 
     </para>
 
-    <programlisting>
-      Program('prog.c', LIBS = 'm',
-                        LIBPATH = ['/usr/lib', '/usr/local/lib'])
-    </programlisting>
+    <scons_example name="libraries_ex3">
+      <file name="SConstruct" printme="1">
+Program('prog.c', LIBS = 'm',
+                  LIBPATH = ['/usr/lib', '/usr/local/lib'])
+      </file>
+      <file name="prog.c">
+int main() { printf("prog.c\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -364,9 +405,9 @@
 
     </para>
 
-    <programlisting>
-      LIBPATH = '/usr/lib:/usr/local/lib'
-    </programlisting>
+    <sconstruct>
+LIBPATH = '/usr/lib:/usr/local/lib'
+    </sconstruct>
 
     <para>
 
@@ -374,9 +415,9 @@
 
     </para>
 
-    <programlisting>
-      LIBPATH = 'C:\\lib;D:\\lib'
-    </programlisting>
+    <sconstruct>
+LIBPATH = 'C:\\lib;D:\\lib'
+    </sconstruct>
 
     <para>
 
@@ -397,11 +438,9 @@
 
     </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>
+    <scons_output example="libraries_ex3" os="posix" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -410,12 +449,9 @@
 
     </para>
 
-    <screen>
-      C:\><userinput>scons -Q</userinput>
-      cl /Foprog.obj /c prog.c /nologo
-      link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
-      embedManifestExeCheck(target, source, env)
-    </screen>
+    <scons_output example="libraries_ex3" os="win32" suffix="2">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
     <!-- The link command is too wide in the PDF version. 
          There are some other examples of this throughout the document. -->
 
@@ -428,3 +464,5 @@
     </para>
 
   </section>
+
+</chapter>