summaryrefslogtreecommitdiff
path: root/doc/developer
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:35 +0100
committerLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:35 +0100
commit64c458487151933ee0ba093cf4ac69e177d9be37 (patch)
treef6e3755704f53406eea85532e4ffe5d5ef50b7f0 /doc/developer
parent2aec9cc58398cac1376509a7d75edb83b41f984e (diff)
parent72c578fd4b0b4a5a43e18594339ac4ff26c376dc (diff)
Merge commit 'upstream/1.2.0.d20091224'
Diffstat (limited to 'doc/developer')
-rw-r--r--doc/developer/MANIFEST9
-rw-r--r--doc/developer/architecture.xml40
-rw-r--r--doc/developer/branches.xml40
-rw-r--r--doc/developer/copyright.xml32
-rw-r--r--doc/developer/cycle.xml40
-rw-r--r--doc/developer/main.xml110
-rw-r--r--doc/developer/packaging.xml40
-rw-r--r--doc/developer/preface.xml175
-rw-r--r--doc/developer/sourcetree.xml40
-rw-r--r--doc/developer/testing.xml40
10 files changed, 566 insertions, 0 deletions
diff --git a/doc/developer/MANIFEST b/doc/developer/MANIFEST
new file mode 100644
index 0000000..eece338
--- /dev/null
+++ b/doc/developer/MANIFEST
@@ -0,0 +1,9 @@
+architecture.xml
+branches.xml
+copyright.xml
+cycle.xml
+main.xml
+packaging.xml
+preface.xml
+sourcetree.xml
+testing.xml
diff --git a/doc/developer/architecture.xml b/doc/developer/architecture.xml
new file mode 100644
index 0000000..3a6e18c
--- /dev/null
+++ b/doc/developer/architecture.xml
@@ -0,0 +1,40 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ XXX
+
+ </para>
+
+ <section>
+ <title>Architecture</title>
+
+ <para>
+
+ XXX
+ </para>
+
+ </section>
diff --git a/doc/developer/branches.xml b/doc/developer/branches.xml
new file mode 100644
index 0000000..e46b616
--- /dev/null
+++ b/doc/developer/branches.xml
@@ -0,0 +1,40 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ XXX
+
+ </para>
+
+ <section>
+ <title>&SCons; Branches</title>
+
+ <para>
+
+ XXX
+ </para>
+
+ </section>
diff --git a/doc/developer/copyright.xml b/doc/developer/copyright.xml
new file mode 100644
index 0000000..7a37cb9
--- /dev/null
+++ b/doc/developer/copyright.xml
@@ -0,0 +1,32 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<blockquote>
+ <para>
+
+ SCons Developer's Guide Copyright (c) 2007 Steven Knight
+
+ </para>
+</blockquote>
diff --git a/doc/developer/cycle.xml b/doc/developer/cycle.xml
new file mode 100644
index 0000000..b56edd2
--- /dev/null
+++ b/doc/developer/cycle.xml
@@ -0,0 +1,40 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ XXX
+
+ </para>
+
+ <section>
+ <title>Development Cycle</title>
+
+ <para>
+
+ XXX
+ </para>
+
+ </section>
diff --git a/doc/developer/main.xml b/doc/developer/main.xml
new file mode 100644
index 0000000..0ebed33
--- /dev/null
+++ b/doc/developer/main.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+
+ <!ENTITY % version SYSTEM "../version.xml">
+ %version;
+
+ <!ENTITY % scons SYSTEM "../scons.mod">
+ %scons;
+
+ <!ENTITY architecture SYSTEM "architecture.xml">
+ <!ENTITY branches SYSTEM "branches.xml">
+ <!ENTITY copyright SYSTEM "copyright.xml">
+ <!ENTITY cycle SYSTEM "cycle.xml">
+ <!ENTITY packaging SYSTEM "packaging.xml">
+ <!ENTITY preface SYSTEM "preface.xml">
+ <!ENTITY sourcetree SYSTEM "sourcetree.xml">
+ <!ENTITY testing SYSTEM "testing.xml">
+
+]>
+
+<book>
+ <bookinfo>
+ <title>SCons Developer's Guide &buildversion;</title>
+
+ <author>
+ <firstname>Steven</firstname>
+ <surname>Knight</surname>
+ </author>
+
+ <edition>Revision &buildrevision; (&builddate;)</edition>
+
+ <pubdate>2007</pubdate>
+
+ <copyright>
+ <year>2007</year>
+ <holder>Steven Knight</holder>
+ </copyright>
+
+ <legalnotice>
+ &copyright;
+ </legalnotice>
+
+ <releaseinfo>version &buildversion;</releaseinfo>
+
+ </bookinfo>
+
+ <preface id="chap-preface">
+ <title>Preface</title>
+ &preface;
+ </preface>
+
+ <chapter id="chap-development-cycle">
+ <title>Development Cycle</title>
+ &cycle;
+ </chapter>
+
+ <chapter id="chap-source-tree">
+ <title>Source Tree</title>
+ &sourcetree;
+ </chapter>
+
+ <chapter id="chap-testing">
+ <title>Testing</title>
+ &testing;
+ </chapter>
+
+ <chapter id="chap-branches">
+ <title>Branches</title>
+ &branches;
+ </chapter>
+
+ <chapter id="chap-packaging">
+ <title>Packaging</title>
+ &packaging;
+ </chapter>
+
+ <chapter id="chap-architecture">
+ <title>Architecture</title>
+ &architecture;
+ </chapter>
+
+</book>
diff --git a/doc/developer/packaging.xml b/doc/developer/packaging.xml
new file mode 100644
index 0000000..92b6a31
--- /dev/null
+++ b/doc/developer/packaging.xml
@@ -0,0 +1,40 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ XXX
+
+ </para>
+
+ <section>
+ <title>Packaging</title>
+
+ <para>
+
+ XXX
+ </para>
+
+ </section>
diff --git a/doc/developer/preface.xml b/doc/developer/preface.xml
new file mode 100644
index 0000000..ece9cdc
--- /dev/null
+++ b/doc/developer/preface.xml
@@ -0,0 +1,175 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ This document assumes that you already know how &SCons;
+ and that you want to learn how to work on the code.
+
+ </para>
+
+ <section>
+ <title>&SCons; Principles</title>
+
+ <para>
+
+ There are a few overriding principles
+ we try to live up to in designing and implementing &SCons:
+
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>Correctness</term>
+
+ <listitem>
+ <para>
+
+ First and foremost,
+ by default, &SCons; guarantees a correct build
+ even if it means sacrificing performance a little.
+ We strive to guarantee the build is correct
+ regardless of how the software being built is structured,
+ how it may have been written,
+ or how unusual the tools are that build it.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Performance</term>
+
+ <listitem>
+ <para>
+
+ Given that the build is correct,
+ we try to make &SCons; build software
+ as quickly as possible.
+ In particular, wherever we may have needed to slow
+ down the default &SCons; behavior to guarantee a correct build,
+ we also try to make it easy to speed up &SCons;
+ through optimization options that let you trade off
+ guaranteed correctness in all end cases for
+ a speedier build in the usual cases.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Convenience</term>
+
+ <listitem>
+ <para>
+
+ &SCons; tries to do as much for you out of the box as reasonable,
+ including detecting the right tools on your system
+ and using them correctly to build the software.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+
+ In a nutshell, we try hard to make &SCons; just
+ "do the right thing" and build software correctly,
+ with a minimum of hassles.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Acknowledgements</title>
+
+ <para>
+
+ &SCons; would not exist without a lot of help
+ from a lot of people,
+ many of whom may not even be aware
+ that they helped or served as inspiration.
+ So in no particular order,
+ and at the risk of leaving out someone:
+
+ </para>
+
+ <para>
+
+ First and foremost,
+ &SCons; owes a tremendous debt to Bob Sidebotham,
+ the original author of the classic Perl-based &Cons; tool
+ which Bob first released to the world back around 1996.
+ Bob's work on Cons classic provided the underlying architecture
+ and model of specifying a build configuration
+ using a real scripting language.
+ My real-world experience working on Cons
+ informed many of the design decisions in SCons,
+ including the improved parallel build support,
+ making Builder objects easily definable by users,
+ and separating the build engine from the wrapping interface.
+
+ </para>
+
+ <para>
+
+ Greg Wilson was instrumental in getting
+ &SCons; started as a real project
+ when he initiated the Software Carpentry design
+ competition in February 2000.
+ Without that nudge,
+ marrying the advantages of the Cons classic
+ architecture with the readability of Python
+ might have just stayed no more than a nice idea.
+
+ </para>
+
+ <para>
+
+ Thanks to Peter Miller
+ for his splendid change management system, &Aegis;,
+ which has provided the &SCons; project
+ with a robust development methodology from day one,
+ and which showed me how you could
+ integrate incremental regression tests into
+ a practical development cycle
+ (years before eXtreme Programming arrived on the scene).
+
+ </para>
+
+ <para>
+
+ And last, thanks to Guido van Rossum
+ for his elegant scripting language,
+ which is the basis not only for the &SCons; implementation,
+ but for the interface itself.
+
+ </para>
+
+ </section>
diff --git a/doc/developer/sourcetree.xml b/doc/developer/sourcetree.xml
new file mode 100644
index 0000000..97bfee0
--- /dev/null
+++ b/doc/developer/sourcetree.xml
@@ -0,0 +1,40 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ XXX
+
+ </para>
+
+ <section>
+ <title>Source Tree</title>
+
+ <para>
+
+ XXX
+ </para>
+
+ </section>
diff --git a/doc/developer/testing.xml b/doc/developer/testing.xml
new file mode 100644
index 0000000..a41c61b
--- /dev/null
+++ b/doc/developer/testing.xml
@@ -0,0 +1,40 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ XXX
+
+ </para>
+
+ <section>
+ <title>Testing</title>
+
+ <para>
+
+ XXX
+ </para>
+
+ </section>