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/builders-built-in.xml | 241 +++++++++++++++++++++++++----------------
 1 file changed, 145 insertions(+), 96 deletions(-)

(limited to 'doc/user/builders-built-in.xml')

diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml
index 7151bf4..455b7a3 100644
--- a/doc/user/builders-built-in.xml
+++ b/doc/user/builders-built-in.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-builders-built-in"
+         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>Built-In Builders</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
@@ -55,7 +77,7 @@
     </para>
 
     <programlisting>
-      Program('prog', 'file1.o')
+Program('prog', 'file1.o')
     </programlisting>
 
     <para>
@@ -80,8 +102,8 @@
     </para>
 
     <programlisting>
-      env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx')
-      env.Program('prog', ['file1.o', 'file2.o'])
+env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx')
+env.Program('prog', ['file1.o', 'file2.o'])
     </programlisting>
 
     <para>
@@ -104,7 +126,7 @@
     </para>
 
     <programlisting>
-      Program(['hello.c', 'goodbye.c'])
+Program(['hello.c', 'goodbye.c'])
     </programlisting>
 
     <para>
@@ -130,11 +152,19 @@
 
     </para>
 
-    <programlisting>
-      env = Environment(LIBS = ['foo1', 'foo2'],
-                        LIBPATH = ['/usr/dir1', 'dir2'])
-      env.Program(['hello.c', 'goodbye.c'])
-    </programlisting>
+    <scons_example name="buildersbuiltin_libs">
+      <file name="SConstruct" printme="1">
+env = Environment(LIBS = ['foo1', 'foo2'],
+                  LIBPATH = ['/usr/dir1', 'dir2'])
+env.Program(['hello.c', 'goodbye.c'])
+      </file>
+      <file name="hello.c">
+int hello() { printf("Hello, world!\n"); }
+      </file>
+      <file name="goodbye.c">
+int goodbye() { printf("Goodbye, world!\n"); }
+      </file>
+    </scons_example>
 
     <para>
 
@@ -142,12 +172,9 @@
 
     </para>
 
-    <screen>
-      % <userinput>scons -Q</userinput>
-      cc -o goodbye.o -c goodbye.c
-      cc -o hello.o -c hello.c
-      cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2
-    </screen>
+    <scons_output example="buildersbuiltin_libs" os="posix" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -155,13 +182,9 @@
 
     </para>
 
-    <screen>
-      C:\><userinput>scons -Q</userinput>
-      cl /Fogoodbye.obj /c goodbye.c /nologo
-      cl /Fohello.obj /c hello.c /nologo
-      link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj
-      embedManifestExeCheck(target, source, env)
-    </screen>
+    <scons_output example="buildersbuiltin_libs" os="win32" suffix="2">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -188,7 +211,7 @@
     Other relevant construction variables
     include those used by the &b-link-Object;
     builders to affect how the
-    source files specified as input to the &t-Program;
+    source files specified as input to the <literal>Program</literal>
     builders are turned into object files;
     see the next section.
 
@@ -235,7 +258,7 @@
       </para>
 
       <programlisting>
-        StaticObject('file', 'file.c')
+StaticObject('file', 'file.c')
       </programlisting>
 
       <para>
@@ -260,8 +283,8 @@
       </para>
 
       <programlisting>
-        env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
-        env.StaticObject('file', 'file.c')
+env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
+env.StaticObject('file', 'file.c')
       </programlisting>
 
       <para>
@@ -284,7 +307,7 @@
       </para>
 
       <programlisting>
-        StaticObject('file.c')
+StaticObject('file.c')
       </programlisting>
 
       <para>
@@ -314,7 +337,7 @@
       </para>
 
       <programlisting>
-        SharedObject('file', 'file.c')
+SharedObject('file', 'file.c')
       </programlisting>
 
       <para>
@@ -339,8 +362,8 @@
       </para>
 
       <programlisting>
-        env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
-        env.SharedObject('file', 'file.c')
+env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
+env.SharedObject('file', 'file.c')
       </programlisting>
 
       <para>
@@ -363,7 +386,7 @@
       </para>
 
       <programlisting>
-        SharedObject('file.c')
+SharedObject('file.c')
       </programlisting>
 
       <para>
@@ -417,7 +440,7 @@
       </para>
 
       <programlisting>
-        StaticLibrary('foo', ['file1.c', 'file2.c'])
+StaticLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
       <para>
@@ -434,8 +457,8 @@
       </para>
 
       <programlisting>
-        env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
-        env.StaticLibrary('lib', ['file1.o', 'file2.o'])
+env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
+env.StaticLibrary('lib', ['file1.o', 'file2.o'])
       </programlisting>
 
       <para>
@@ -447,7 +470,7 @@
       </para>
 
       <programlisting>
-        StaticLibrary('foo', ['file1.c', 'file2.c'])
+StaticLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
       <para>
@@ -461,7 +484,7 @@
       </para>
 
       <programlisting>
-        StaticLibrary(['file.c', 'another.c'])
+StaticLibrary(['file.c', 'another.c'])
       </programlisting>
 
       <para>
@@ -491,7 +514,7 @@
       </para>
 
       <programlisting>
-        SharedLibrary('foo', ['file1.c', 'file2.c'])
+SharedLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
       <para>
@@ -508,8 +531,8 @@
       </para>
 
       <programlisting>
-        env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
-        env.SharedLibrary('shared', ['file1.o', 'file2.o'])
+env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
+env.SharedLibrary('shared', ['file1.o', 'file2.o'])
       </programlisting>
 
       <para>
@@ -521,7 +544,7 @@
       </para>
 
       <programlisting>
-        SharedLibrary('foo', ['file1.c', 'file2.c'])
+SharedLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
       <para>
@@ -535,7 +558,7 @@
       </para>
 
       <programlisting>
-        SharedLibrary(['file.c', 'another.c'])
+SharedLibrary(['file.c', 'another.c'])
       </programlisting>
 
       <para>
@@ -608,11 +631,11 @@
       </para>
 
       <programlisting>
-        XXX CFile() programlisting
+XXX CFile() programlisting
       </programlisting>
 
       <screen>
-        XXX CFile() screen
+XXX CFile() screen
       </screen>
 
     </section>
@@ -627,11 +650,11 @@
       </para>
 
       <programlisting>
-        XXX CXXFILE() programlisting
+XXX CXXFILE() programlisting
       </programlisting>
 
       <screen>
-        XXX CXXFILE() screen
+XXX CXXFILE() screen
       </screen>
 
     </section>
@@ -658,11 +681,11 @@
       </para>
 
       <programlisting>
-        XXX DVI() programlisting
+XXX DVI() programlisting
       </programlisting>
 
       <screen>
-        XXX DVI() screen
+XXX DVI() screen
       </screen>
 
     </section>
@@ -688,11 +711,11 @@
       </para>
 
       <programlisting>
-        XXX PostScript() programlisting
+XXX PostScript() programlisting
       </programlisting>
 
       <screen>
-        XXX PostScript() screen
+XXX PostScript() screen
       </screen>
 
     </section>
@@ -720,17 +743,26 @@
 
       </para>
 
-      <programlisting>
-        env = Environment()
-        env.Tar('out1.tar', ['file1', 'file2'])
-        env.Tar('out2', 'directory')
-      </programlisting>
+      <scons_example name="buildersbuiltin_ex1">
+        <file name="SConstruct" printme="1">
+env = Environment()
+env.Tar('out1.tar', ['file1', 'file2'])
+env.Tar('out2', 'directory')
+        </file>
+        <file name="file1">
+file1
+        </file>
+        <file name="file2">
+file2
+        </file>
+        <file name="directory/file3">
+directory/file3
+        </file>
+      </scons_example>
 
-      <screen>
-        % <userinput>scons -Q .</userinput>
-        tar -c -f out1.tar file1 file2
-        tar -c -f out2.tar directory
-      </screen>
+      <scons_output example="buildersbuiltin_ex1" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -747,15 +779,19 @@
 
       </para>
 
-      <programlisting>
-        env = Environment(TARFLAGS = '-c -z')
-        env.Tar('out.tar.gz', 'directory')
-      </programlisting>
+      <scons_example name="buildersbuiltin_ex2">
+        <file name="SConstruct" printme="1">
+env = Environment(TARFLAGS = '-c -z')
+env.Tar('out.tar.gz', 'directory')
+        </file>
+        <file name="directory/file">
+directory/file
+        </file>
+      </scons_example>
 
-      <screen>
-        % <userinput>scons -Q .</userinput>
-        tar -c -z -f out.tar.gz directory
-      </screen>
+      <scons_output example="buildersbuiltin_ex2" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -767,16 +803,20 @@
 
       </para>
 
-      <programlisting>
-        env = Environment(TARFLAGS = '-c -z',
-                          TARSUFFIX = '.tgz')
-        env.Tar('out', 'directory')
-      </programlisting>
+      <scons_example name="buildersbuiltin_ex3">
+        <file name="SConstruct" printme="1">
+env = Environment(TARFLAGS = '-c -z',
+                  TARSUFFIX = '.tgz')
+env.Tar('out', 'directory')
+        </file>
+        <file name="directory/file">
+directory/file
+        </file>
+      </scons_example>
 
-      <screen>
-        % <userinput>scons -Q .</userinput>
-        tar -c -z -f out.tgz directory
-      </screen>
+      <scons_output example="buildersbuiltin_ex3" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
     </section>
 
@@ -795,10 +835,18 @@
 
       </para>
 
-      <programlisting>
-        env = Environment()
-        env.Zip('out', ['file1', 'file2'])
-      </programlisting>
+      <scons_example name="buildersbuiltin_ex4">
+        <file name="SConstruct" printme="1">
+env = Environment()
+env.Zip('out', ['file1', 'file2'])
+        </file>
+        <file name="file1">
+file1
+        </file>
+        <file name="file2">
+file2
+        </file>
+      </scons_example>
 
       <para>
 
@@ -808,10 +856,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q .</userinput>
-        zip(["out.zip"], ["file1", "file2"])
-      </screen>
+      <scons_output example="buildersbuiltin_ex4" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
     </section>
 
@@ -844,8 +891,8 @@
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Java(target = 'classes', source = 'src')
+env = Environment()
+env.Java(target = 'classes', source = 'src')
       </programlisting>
 
       <para>
@@ -858,7 +905,7 @@
       </para>
 
       <screen>
-        XXX Java() screen
+XXX Java() screen
       </screen>
 
     </section>
@@ -873,13 +920,13 @@
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Java(target = 'classes', source = 'src')
-        env.Jar(target = '', source = 'classes')
+env = Environment()
+env.Java(target = 'classes', source = 'src')
+env.Jar(target = '', source = 'classes')
       </programlisting>
 
       <screen>
-        XXX Jar() screen
+XXX Jar() screen
       </screen>
 
     </section>
@@ -894,11 +941,11 @@
       </para>
 
       <programlisting>
-        XXX JavaH() programlisting
+XXX JavaH() programlisting
       </programlisting>
 
       <screen>
-        XXX JavaH() screen
+XXX JavaH() screen
       </screen>
 
     </section>
@@ -913,13 +960,15 @@
       </para>
 
       <programlisting>
-        XXX RMIC() programlisting
+XXX RMIC() programlisting
       </programlisting>
 
       <screen>
-        XXX RMIC() screen
+XXX RMIC() screen
       </screen>
 
     </section>
 
   </section>
+
+</chapter>
-- 
cgit v1.2.3