Merge tag 'upstream/2.3.1'

Upstream version 2.3.1

1 files changed, 128 insertions, 108 deletions

diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index afa6e6f..2f5642b 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -1,6 +1,28 @@
+<?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-caching"
+         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>Caching Built Files</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
@@ -43,9 +65,21 @@
 
     </para>
 
-    <programlisting>
-       CacheDir('/usr/local/build_cache')
-    </programlisting>
+    <scons_example name="caching_ex1">
+       <file name="SConstruct">
+env = Environment()
+env.Program('hello.c')
+CacheDir('cache')
+       </file>
+       <file name="hello.c">
+hello.c
+       </file>
+       <directory name="cache">
+       </directory>
+       <file name="not_used" printme="1">
+CacheDir('/usr/local/build_cache')
+       </file>
+    </scons_example>
 
     <para>
 
@@ -86,17 +120,11 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
-      % <userinput>scons -Q</userinput>
-      Retrieved `hello.o' from cache
-      Retrieved `hello' from cache
-    </screen>
+    <scons_output example="caching_ex1" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -142,17 +170,11 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
-      % <userinput>scons -Q --cache-show</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-    </screen>
+    <scons_output example="caching_ex1" suffix="2">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q --cache-show</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -181,13 +203,20 @@
 
     </para>
 
-    <programlisting>
-       env = Environment()
-       obj = env.Object('hello.c')
-       env.Program('hello.c')
-       CacheDir('cache')
-       NoCache('hello.o')
-    </programlisting>
+    <scons_example name="ex-NoCache">
+       <file name="SConstruct" printme="1">
+env = Environment()
+obj = env.Object('hello.c')
+env.Program('hello.c')
+CacheDir('cache')
+NoCache('hello.o')
+       </file>
+       <file name="hello.c">
+hello.c
+       </file>
+       <directory name="cache">
+       </directory>
+    </scons_example>
 
     <para>
 
@@ -203,7 +232,7 @@
 
     <!--
 
-    <scons_output example="ex1">
+    <scons_output example="caching_ex1" suffix="3">
       <scons_output_command>scons -Q</scons_output_command>
       <scons_output_command>scons -Q -c</scons_output_command>
       <scons_output_command>scons -Q</scons_output_command>
@@ -212,15 +241,15 @@
     -->
 
     <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c hello.c
-      Retrieved `hello' from cache
+% <userinput>scons -Q</userinput>
+cc -o hello.o -c hello.c
+cc -o hello hello.o
+% <userinput>scons -Q -c</userinput>
+Removed hello.o
+Removed hello
+% <userinput>scons -Q</userinput>
+cc -o hello.o -c hello.c
+Retrieved `hello' from cache
     </screen>
 
   </section>
@@ -255,23 +284,13 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
-      % <userinput>scons -Q</userinput>
-      Retrieved `hello.o' from cache
-      Retrieved `hello' from cache
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
-      % <userinput>scons -Q --cache-disable</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-    </screen>
+    <scons_output example="caching_ex1" suffix="4">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q --cache-disable</scons_output_command>
+    </scons_output>
 
   </section>
 
@@ -306,21 +325,13 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q --cache-disable</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
-      % <userinput>scons -Q --cache-disable</userinput>
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o
-      % <userinput>scons -Q --cache-force</userinput>
-      scons: `.' is up to date.
-      % <userinput>scons -Q</userinput>
-      scons: `.' is up to date.
-    </screen>
+    <scons_output example="caching_ex1" suffix="5">
+      <scons_output_command>scons -Q --cache-disable</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q --cache-disable</scons_output_command>
+      <scons_output_command>scons -Q --cache-force</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -354,10 +365,18 @@
 
     </para>
 
-    <programlisting>
-       Program('prog',
-               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
-    </programlisting>
+    <scons_example name="caching_ex-random">
+       <file name="SConstruct" printme="1">
+Program('prog',
+        ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+       </file>
+       <file name="f1.c">f1.c</file>
+       <file name="f2.c">f2.c</file>
+       <file name="f3.c">f3.c</file>
+       <file name="f4.c">f4.c</file>
+       <file name="f5.c">f5.c</file>
+       <file name="f6.c">f6.c</file>
+    </scons_example>
 
     <para>
 
@@ -366,15 +385,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
-      cc -o f4.o -c f4.c
-      cc -o f5.o -c f5.c
-      cc -o prog f1.o f2.o f3.o f4.o f5.o
-    </screen>
+    <scons_output example="caching_ex-random" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -407,24 +420,24 @@
 
     The following <screen> output was generated by this:
 
-    <scons_output example="ex-random">
+    <scons_output example="caching_ex-random" suffix="2">
       <scons_output_command>scons -Q - -random</scons_output_command>
     </scons_output>
 
-    We captured it directly here to guarantee a "random" order,
-    guarding against the potential for - -random to happen
-    to return things in the original sorted order.
+We captured it directly here to guarantee a "random" order,
+guarding against the potential for - -random to happen
+to return things in the original sorted order.
 
-    -->
+-->
 
     <screen>
-      % <userinput>scons -Q --random</userinput>
-      cc -o f3.o -c f3.c
-      cc -o f1.o -c f1.c
-      cc -o f5.o -c f5.c
-      cc -o f2.o -c f2.c
-      cc -o f4.o -c f4.c
-      cc -o prog f1.o f2.o f3.o f4.o f5.o
+  % <userinput>scons -Q --random</userinput>
+  cc -o f3.o -c f3.c
+  cc -o f1.o -c f1.c
+  cc -o f5.o -c f5.c
+  cc -o f2.o -c f2.c
+  cc -o f4.o -c f4.c
+  cc -o prog f1.o f2.o f3.o f4.o f5.o
     </screen>
 
     <para>
@@ -464,14 +477,19 @@
 
     </para>
 
-    <programlisting>
-       Program('prog',
-               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
-
-       SetOption('random', 1)
-       Program('prog',
-               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
-    </programlisting>
+    <scons_example name="caching_ex-random">
+       <file name="SConstruct" printme="1">
+SetOption('random', 1)
+Program('prog',
+        ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+       </file>
+       <file name="f1.c">f1.c</file>
+       <file name="f2.c">f2.c</file>
+       <file name="f3.c">f3.c</file>
+       <file name="f4.c">f4.c</file>
+       <file name="f5.c">f5.c</file>
+       <file name="f6.c">f6.c</file>
+    </scons_example>
 
   </section>
 
@@ -504,3 +522,5 @@
   </section>
 
   -->
+
+</chapter>