From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001
From: Luca Falavigna <dktrkranz@debian.org>
Date: Sat, 26 Apr 2014 15:11:58 +0200
Subject: Imported Upstream version 2.3.1

---
 doc/user/sideeffect.xml | 117 +++++++++++++++++++++++++++++-------------------
 1 file changed, 72 insertions(+), 45 deletions(-)

(limited to 'doc/user/sideeffect.xml')

diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml
index a656f9d..72af9cc 100644
--- a/doc/user/sideeffect.xml
+++ b/doc/user/sideeffect.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-sideeffect"
+         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>Sideeffect 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
@@ -23,8 +44,6 @@
 
 -->
 
- <!--
-
  <para>
 
  If &SCons; is unaware that a build step produces an extra file,
@@ -35,9 +54,11 @@
 
  </para>
 
+ <para>
  TODO: currently doesn't work due to issue #2154:
  http://scons.tigris.org/issues/show_bug.cgi?id=2154
-
+ </para>
+ 
  <para>
 
  If more than one build step creates or manipulates the same file,
@@ -54,14 +75,14 @@
 
  </para>
 
- <scons_example name="SideEffectSimple">
+ <scons_example name="sideeffect_simple">
    <file name="SConstruct" printme="1">
-    env = Environment()
-    f2 = env.Command('file2', 'log', Copy('$TARGET', '$SOURCE'))
-    f1 = env.Command('file1', [],
-        'echo >$TARGET data1; echo >log updated file1'))
-    env.SideEffect('log', env.Command('file1', [],
-        'echo >$TARGET data1; echo >log updated file1'))
+env = Environment()
+f2 = env.Command('file2', 'log', Copy('$TARGET', '$SOURCE'))
+f1 = env.Command('file1', [],
+    'echo >$TARGET data1; echo >log updated file1'))
+env.SideEffect('log', env.Command('file1', [],
+    'echo >$TARGET data1; echo >log updated file1'))
    </file>
  </scons_example>
 
@@ -71,12 +92,10 @@
 
  </para>
 
- <scons_output example="SideEffectSimple">
+ <scons_output example="sideeffect_simple" suffix="1">
     <scons_output_command>scons -Q --jobs=2</scons_output_command>
  </scons_output>
 
- -->
-
  <para>
 
  Sometimes a program the you need to call
@@ -95,12 +114,12 @@
  </para>
 
  <screen>
- env = Environment()
- env.Command('file1.out', 'file.in',
-             './build --log logfile.txt $SOURCE $TARGET')
- env.Command('file2.out', 'file.in',
-             './build --log logfile.txt $SOURCE $TARGET')
- <screen>
+env = Environment()
+env.Command('file1.out', 'file.in',
+            './build --log logfile.txt $SOURCE $TARGET')
+env.Command('file2.out', 'file.in',
+            './build --log logfile.txt $SOURCE $TARGET')
+ </screen>
 
  <para>
 
@@ -134,14 +153,21 @@
 
  </para>
 
- <programlisting>
-   env = Environment()
-   f1 = env.Command('file1.out', 'file1.in',
-                    './build --log logfile.txt $SOURCE $TARGET')
-   f2 = env.Command('file2.out', 'file2.in',
-                    './build --log logfile.txt $SOURCE $TARGET')
-   env.SideEffect('logfile.txt', f1 + f2)
- </programlisting>
+ <scons_example name="sideeffect_shared">
+   <file name="SConstruct" printme="1">
+env = Environment()
+f1 = env.Command('file1.out', 'file1.in',
+                 './build --log logfile.txt $SOURCE $TARGET')
+f2 = env.Command('file2.out', 'file2.in',
+                 './build --log logfile.txt $SOURCE $TARGET')
+env.SideEffect('logfile.txt', f1 + f2)
+   </file>
+   <file name="file1.in">file1.in</file>
+   <file name="file2.in">file2.in</file>
+   <file name="build" chmod="0755">
+cat
+   </file>
+ </scons_example>
 
  <para>
 
@@ -155,11 +181,9 @@
 
  </para>
 
- <screen>
-    % <userinput>scons -Q --jobs=2</userinput>
-    ./build --log logfile.txt file1.in file1.out
-    ./build --log logfile.txt file2.in file2.out
- </screen>
+ <scons_output example="sideeffect_shared" suffix="1">
+    <scons_output_command>scons -Q --jobs=2</scons_output_command>
+ </scons_output>
 
  <para>
 
@@ -173,19 +197,19 @@
 
  </para>
 
- <programlisting>
-    env = Environment()
-    f1 = env.Command('file1.out', [], 'echo &gt;$TARGET data1')
-    env.SideEffect('not_really_updated', f1)
-    f2 = env.Command('file2.out', [], 'echo &gt;$TARGET data2')
-    env.SideEffect('not_really_updated', f2)
- </programlisting>
+ <scons_example name="sideeffect_parallel">
+   <file name="SConstruct" printme="1">
+env = Environment()
+f1 = env.Command('file1.out', [], 'echo >$TARGET data1')
+env.SideEffect('not_really_updated', f1)
+f2 = env.Command('file2.out', [], 'echo >$TARGET data2')
+env.SideEffect('not_really_updated', f2)
+   </file>
+ </scons_example>
 
- <screen>
-    % <userinput>scons -Q --jobs=2</userinput>
-    echo &gt; file1.out data1
-    echo &gt; file2.out data2
- </screen>
+ <scons_output example="sideeffect_parallel" suffix="1">
+    <scons_output_command>scons -Q --jobs=2</scons_output_command>
+ </scons_output>
 
  <para>
 
@@ -209,3 +233,6 @@
  may actually updated by more than one command invocation.
 
  </para>
+
+ </chapter>
+ 
-- 
cgit v1.2.3