summaryrefslogtreecommitdiffstats
path: root/doc/design/issues.sgml
diff options
context:
space:
mode:
authorSteven Knight <knight@baldmt.com>2001-08-10 09:55:19 (GMT)
committerSteven Knight <knight@baldmt.com>2001-08-10 09:55:19 (GMT)
commit11251d5bd9a2f25dd424838c77cff00225e33e9d (patch)
treefca6b90698de442d96f1707a719f9fb400514fab /doc/design/issues.sgml
parent0f394bfb1e41965678937bfbc3e7cb52651ae731 (diff)
downloadSCons-11251d5bd9a2f25dd424838c77cff00225e33e9d.zip
SCons-11251d5bd9a2f25dd424838c77cff00225e33e9d.tar.gz
SCons-11251d5bd9a2f25dd424838c77cff00225e33e9d.tar.bz2
Add design documentation.
Diffstat (limited to 'doc/design/issues.sgml')
-rw-r--r--doc/design/issues.sgml176
1 files changed, 176 insertions, 0 deletions
diff --git a/doc/design/issues.sgml b/doc/design/issues.sgml
new file mode 100644
index 0000000..6772c83
--- /dev/null
+++ b/doc/design/issues.sgml
@@ -0,0 +1,176 @@
+<!--
+
+ Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+ No build tools is perfect.
+ Here are some &SCons; issues that
+ do not yet have solutions.
+
+ </para>
+
+ <section>
+ <title>Interaction with SC-config</title>
+
+ <para>
+
+ The SC-config tool will be used in the &SCons; installation
+ process to generate an appropriate default construction environment
+ so that building most software works "out of the box" on the
+ installed platform. The SC-config tool will find reasonable default
+ compilers (C, C++, Fortran), linkers/loaders, library archive tools,
+ etc. for specification in the default &SCons; construction
+ environment.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Interaction with test infrastructures</title>
+
+ <para>
+
+ &SCons; can be configured to use SC-test (or some other test tool)
+ to provide controlled, automated testing of software. The &Link;
+ method could link a <filename>test</filename> subdirectory to a build
+ subdirectory:
+
+ </para>
+
+ <programlisting>
+ Link('test', 'build')
+ SConscript('test/SConscript')</programlisting>
+
+ <para>
+
+ Any test cases checked in with the source code will be linked
+ into the <filename>test</filename> subdirectory and executed. If
+ &SConscript; files and test cases are written with this in mind, then
+ invoking:
+
+ </para>
+
+ <programlisting>
+ % sccons test</programlisting>
+
+ <para>
+
+ Would run all the automated test cases that depend on any changed
+ software.
+
+ </para>
+
+
+ <!--
+
+ YYY integrate with SC-test to provide sanity check on new tools
+ "discovery testing" of new tools
+ results recorded in a central database
+ central database can be somewhere else on web
+
+ -->
+
+ </section>
+
+ <section>
+ <title>Java dependencies</title>
+
+ <para>
+
+ Java dependencies are difficult for an external dependency-based
+ construction tool to accomodate. Determining Java class dependencies
+ is more complicated than the simple pattern-matching of C or C++
+ <literal>#include</literal> files. From the point of view of an
+ external build tool, the Java compiler behaves "unpredictably"
+ because it may create or update multiple output class files and
+ directories as a result of its internal class dependencies.
+
+ </para>
+
+ <para>
+
+ An obvious &SCons; implementation would be to have the &Scanner;
+ object parse output from <command>Java -depend -verbose</command> to
+ calculate dependencies, but this has the distinct disadvantage of
+ requiring two separate compiler invocations, thereby slowing down
+ builds.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Limitations of digital signature calculation</title>
+
+ <para>
+
+ In practice, calculating digital signatures of a file's contents is a
+ more robust mechanism than time stamps for determining what needs
+ building. However:
+
+ </para>
+
+ <orderedlist numeration="arabic">
+
+ <listitem>
+ <para>
+
+ Developers used to the time stamp model of &Make; can initially
+ find digital signatures counter-intuitive. The assumption that:
+
+ <programlisting>
+ % touch file.c</programlisting>
+
+ will cause a rebuild of <filename>file</filename> is strong...
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ Abstracting dependency calculation into a single digital signature
+ loses a little information: It is no longer possible to tell
+ (without laborious additional calculation) which input file dependency
+ caused a rebuild of a given target file. A feature that could
+ report, "I'm rebuilding file X because it's out-of-date with respect
+ to file Y," would be good, but an digital-signature implementation of
+ such a feature is non-obvious.
+
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ </section>
+
+ <section>
+ <title>Remote execution</title>
+
+ <para>
+
+ The ability to use multiple build systems through remote execution
+ of tools would be good. This should be implementable through the
+ &Job; class. Construction environments would need modification
+ to specify build systems.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Conditional builds</title>
+
+ <para>
+
+ The ability to check run-time conditions as suggested on the
+ sc-discuss mailing list ("build X only if: the machine is idle /
+ the file system has Y megabytes free space") would also be good,
+ but is not part of the current design.
+
+ </para>
+
+ </section>