Merge tag 'upstream/2.3.1'

Upstream version 2.3.1

1 files changed, 161 insertions, 92 deletions

diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml
index 0d90d2e..c0ca5ee 100644
--- a/doc/user/repositories.xml
+++ b/doc/user/repositories.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-repositories"
+         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 From Code Repositories</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
@@ -73,11 +94,16 @@
 
     </para>
 
-    <programlisting>
-       env = Environment()
-       env.Program('hello.c')
-       Repository('/usr/repository1', '/usr/repository2')
-    </programlisting>
+    <scons_example name="repositories_ex1">
+      <file name="SConstruct" printme="1">
+env = Environment()
+env.Program('hello.c')
+Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2')
+      </file>
+      <file name="hello.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -124,11 +150,9 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-    </screen>
+    <scons_output example="repositories_ex1" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -139,13 +163,20 @@
 
     </para>
 
-    
-
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c /usr/repository1/hello.c
-      cc -o hello hello.o
-    </screen>
+    <scons_example name="repositories_ex2">
+      <file name="SConstruct">
+env = Environment()
+env.Program('hello.c')
+Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2')
+      </file>
+      <file name="__ROOT__/usr/repository1/hello.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
+
+    <scons_output example="repositories_ex2" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -155,13 +186,20 @@
 
     </para>
 
-    
-
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c /usr/repository2/hello.c
-      cc -o hello hello.o
-    </screen>
+    <scons_example name="repositories_ex3">
+      <file name="SConstruct">
+env = Environment()
+env.Program('hello.c')
+Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2')
+      </file>
+      <file name="__ROOT__/usr/repository2/hello.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
+
+    <scons_output example="repositories_ex3" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -200,9 +238,9 @@
     </para>
 
     <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c hello.c
-      hello.c:1: hello.h: No such file or directory
+% <userinput>scons -Q</userinput>
+cc -o hello.o -c hello.c
+hello.c:1: hello.h: No such file or directory
     </screen>
 
     <para>
@@ -216,11 +254,16 @@
 
     </para>
 
-    <programlisting>
-       env = Environment(CPPPATH = ['.'])
-       env.Program('hello.c')
-       Repository('/usr/repository1')
-    </programlisting>
+    <scons_example name="repositories_CPPPATH">
+      <file name="SConstruct" printme="1">
+env = Environment(CPPPATH = ['.'])
+env.Program('hello.c')
+Repository('__ROOT__/usr/repository1')
+      </file>
+      <file name="hello.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -228,11 +271,9 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c -I. -I/usr/repository1 hello.c
-      cc -o hello hello.o
-    </screen>
+    <scons_output example="repositories_CPPPATH" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -249,11 +290,16 @@
 
     </para>
 
-    <programlisting>
-       env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3'])
-       env.Program('hello.c')
-       Repository('/r1', '/r2')
-    </programlisting>
+    <scons_example name="repositories_CPPPATH3">
+      <file name="SConstruct" printme="1">
+env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3'])
+env.Program('hello.c')
+Repository('__ROOT__/r1', '__ROOT__/r2')
+      </file>
+      <file name="hello.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -264,11 +310,9 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c -Idir1 -I/r1/dir1 -I/r2/dir1 -Idir2 -I/r1/dir2 -I/r2/dir2 -Idir3 -I/r1/dir3 -I/r2/dir3 hello.c
-      cc -o hello hello.o
-    </screen>
+    <scons_output example="repositories_CPPPATH3" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
 <!--
 
@@ -311,13 +355,13 @@ coming into existence.)
       </para>
 
       <programlisting>
-        #include "hello.h"
-        int
-        main(int argc, char *argv[])
-        {
-            printf(HELLO_MESSAGE);
-            return (0);
-        }
+#include "hello.h"
+int
+main(int argc, char *argv[])
+{
+    printf(HELLO_MESSAGE);
+    return (0);
+}
       </programlisting>
 
       <para>
@@ -330,13 +374,20 @@ coming into existence.)
 
       </para>
 
-      
-
-      <screen>
-        % <userinput>scons -Q</userinput>
-        cc -o hello.o -c -I. -I/usr/repository1 /usr/repository1/hello.c
-        cc -o hello hello.o
-      </screen>
+      <scons_example name="repositories_quote1">
+        <file name="SConstruct">
+env = Environment(CPPPATH = ['.'])
+env.Program('hello.c')
+Repository('__ROOT__/usr/repository1')
+        </file>
+        <file name="__ROOT__/usr/repository1/hello.c">
+int main() { printf("Hello, world!\n"); }
+        </file>
+      </scons_example>
+
+      <scons_output example="repositories_quote1" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -372,7 +423,7 @@ coming into existence.)
         <para>
 
         Change all occurrences of <literal>#include "file.h"</literal>
-        to <literal>#include &lt;file.h&gt;</literal>.
+        to <literal>#include &amp;lt;file.h&amp;gt;</literal>.
         Use of <literal>#include</literal> with angle brackets
         does not have the same behavior--the <literal>-I</literal>
         directories are searched first
@@ -420,7 +471,7 @@ coming into existence.)
     </para>
 
     <screen>
-      % <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput>
+% <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput>
     </screen>
 
     <para>
@@ -462,16 +513,27 @@ coming into existence.)
 
     </para>
 
-    
-
-    <screen>
-      % <userinput>cd /usr/repository1</userinput>
-      % <userinput>scons -Q</userinput>
-      cc -o file1.o -c file1.c
-      cc -o file2.o -c file2.c
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o file1.o file2.o
-    </screen>
+    <scons_example name="repositories_ex4">
+      <file name="SConstruct">
+env = Environment()
+env.Program(['hello.c', 'file1.c', 'file2.c'])
+Repository('/usr/repository1', '/usr/repository2')
+      </file>
+      <file name="hello.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+      <file name="file1.c">
+int f1() { printf("file1\n"); }
+      </file>
+      <file name="file2.c">
+int f2() { printf("file2.c\n"); }
+      </file>
+    </scons_example>
+
+    <scons_output example="repositories_ex4" suffix="1">
+      <scons_output_command>cd /usr/repository1</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
     
@@ -494,18 +556,18 @@ coming into existence.)
     </para>
 
     <!--
-    <scons_output example="ex4">
+    <scons_output example="repositories_ex4" suffix="2">
       <scons_output_command>cd $HOME/build</scons_output_command>
       <scons_output_command>edit hello.c</scons_output_command>
       <scons_output_command>scons -Q -Y __ROOT__/usr/repository1</scons_output_command>
     </scons_output>
     -->
     <screen>
-      % <userinput>cd $HOME/build</userinput>
-      % <userinput>edit hello.c</userinput>
-      % <userinput>scons -Q -Y /usr/repository1</userinput>
-      cc -c -o hello.o hello.c
-      cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o
+% <userinput>cd $HOME/build</userinput>
+% <userinput>edit hello.c</userinput>
+% <userinput>scons -Q -Y /usr/repository1</userinput>
+cc -c -o hello.o hello.c
+cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o
     </screen>
 
     <para>
@@ -532,10 +594,10 @@ coming into existence.)
     </para>
 
     <screen>
-      % <userinput>mkdir $HOME/build2</userinput>
-      % <userinput>cd $HOME/build2</userinput>
-      % <userinput>scons -Q -Y /usr/all/repository hello</userinput>
-      scons: `hello' is up-to-date.
+% <userinput>mkdir $HOME/build2</userinput>
+% <userinput>cd $HOME/build2</userinput>
+% <userinput>scons -Q -Y /usr/all/repository hello</userinput>
+scons: `hello' is up-to-date.
     </screen>
 
     <para>
@@ -563,11 +625,16 @@ coming into existence.)
 
     </para>
 
-    <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       Local(hello)
-    </programlisting>
+    <scons_example name="repositories_ex5">
+      <file name="SConstruct" printme="1">
+env = Environment()
+hello = env.Program('hello.c')
+Local(hello)
+      </file>
+      <file name="hello.c">
+int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -579,9 +646,9 @@ coming into existence.)
     </para>
 
     <screen>
-      % <userinput>scons -Y /usr/all/repository hello</userinput>
-      Local copy of hello from /usr/all/repository/hello
-      scons: `hello' is up-to-date.
+% <userinput>scons -Y /usr/all/repository hello</userinput>
+Local copy of hello from /usr/all/repository/hello
+scons: `hello' is up-to-date.
     </screen>
 
     <para>
@@ -593,3 +660,5 @@ coming into existence.)
     </para>
 
   </section>
+
+</chapter>