From a2d5a170cc1f83e0b4d738e23e4a9952e17be24f Mon Sep 17 00:00:00 2001 From: Steven Knight Date: Mon, 29 Apr 2002 14:35:35 +0000 Subject: Doc and README/RELEASE updates in preparation for eventual 0.07 release. (Later this week?) --- Construct | 538 ------------------------------------------------------- README | 24 +-- debian/changelog | 2 +- doc/Conscript | 254 -------------------------- doc/man/scons.1 | 250 +++++++++++++++++++++++--- etc/Conscript | 15 -- src/CHANGES.txt | 2 +- src/RELEASE.txt | 70 +++++--- 8 files changed, 290 insertions(+), 865 deletions(-) delete mode 100644 Construct delete mode 100644 doc/Conscript delete mode 100644 etc/Conscript diff --git a/Construct b/Construct deleted file mode 100644 index fce4470..0000000 --- a/Construct +++ /dev/null @@ -1,538 +0,0 @@ -# -# Construct file to build scons during development. -# (Kind of ironic that we're using the classic Perl Cons -# to build its Python child...) -# - -# -# Copyright (c) 2001, 2002 Steven Knight -# -# 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. -# - -print <<_EOF_; - - Using Cons to build the SCons packages is no longer supported, - and this Construct file is deprecated. - - Use SCons to build its own packages instead. - - See the README file for details. - -_EOF_ -exit 0; - -$project = 'scons'; - -Default qw( . ); - -# -# An internal "whereis" routine to figure out if we have a -# given program available. Put it in the "cons::" package -# so subsidiary Conscript files can get at it easily, too. -# -use Config; -sub cons::whereis { - my $file = shift; - foreach my $dir (split(/$Config{path_sep}/, $ENV{PATH})) { - $f = File::Spec->catfile($dir, $file); - return $f if -x $f && ! -d $f; - } - return undef -} - -sub cons::read_file { - my $file = shift; - open(F, "<$file") || die "cannot open $file: $!"; - my @lines = ; - close(F); - return wantarray ? @lines : join('', @lines); -} - -# -# We let the presence or absence of various utilities determine -# whether or not we bother to build certain pieces of things. -# This will allow people to still do SCons work even if they -# don't have Aegis or RPM installed, for example. -# -$aegis = cons::whereis('aegis'); -$aesub = cons::whereis('aesub'); -$rpm = cons::whereis('rpm'); -$dh_builddeb = cons::whereis('dh_builddeb'); -$fakeroot = cons::whereis('fakeroot'); - -# My installation on Red Hat doesn't like any debhelper version -# beyond 2, so let's use 2 as the default on any non-Debian build. -$DH_COMPAT = (-f "/etc/debian_version") ? 3 : 2; - -# -# Now grab the information that we "build" into the files (using sed). -# -chomp($date = $ARG{date}); -if (! $date) { - ($sec,$min,$hour,$mday,$mon,$year) = localtime(time); - $year += 1900; - $date = sprintf("%4d/%02d/%02d %02d:%02d:%02d", - $year, $mon, $mday, $hour, $min, $sec); -} - -$developer = $ARG{developer} || $ENV{USERNAME} || $ENV{LOGNAME} || $ENV{USER}; - -$revision = $ARG{version}; -chomp($revision = `$aesub '\$version' 2>/dev/null`) if $aesub && ! $revision; -$revision = '0.05' if ! $revision; - -@arr = split(/\./, $revision); -@arr = ($arr[0], map {length($_) == 1 ? "0$_" : $_} @arr[1 .. $#arr]); -$revision = join('.', @arr); - -# Here's how we'd turn the calculated $revision into our package $version. -# This makes it difficult to coordinate with other files (debian/changelog -# and rpm/scons.spec) that hard-code the version number, so just go with -# the flow for now. -#pop @arr if $#arr >= 2; -#map {s/^[CD]//, s/^0*(\d\d)$/$1/} @arr; -#$version = join('.', @arr); -$version = '0.05'; - -$change = $ARG{change}; -chomp($change = `$aesub '\$change' 2>/dev/null`) if $aesub && ! $change; - -chomp($python_ver = `python -c "import sys; print sys.version[0:3]"`); - -chomp($platform = `python -c "from distutils.util import get_platform; print get_platform()"`); - -if ($platform eq "win32") { - $archsuffix = "zip" -} else { - $archsuffix = "tar.gz" -} - -use Cwd; -$test1_dir = File::Spec->catfile(cwd, "build", "test1"); -$test2_dir = File::Spec->catfile(cwd, "build", "test2"); - -$lib_project = File::Spec->catfile("lib", "$project"); - -# Originally, we were going to package the build engine in a -# private SCons library that contained the version number, so -# we could easily have multiple side-by-side versions of SCons -# installed. Keep this around in case we ever want to go back -# to that scheme. Note that this also requires changes to -# runtest.py and src/setup.py. -#$lib_project = File::Spec->catfile("lib", "$project-$version"); - -$test1_lib_dir = File::Spec->catfile($test1_dir, $lib_project); - -$test2_lib_dir = File::Spec->catfile($test2_dir, - "lib", - "python${python_ver}", - "site-packages"); - -$unpack_dir = File::Spec->catfile(cwd, "build", "unpack"); - -$env = new cons( ENV => { - AEGIS_PROJECT => $ENV{AEGIS_PROJECT}, - PATH => $ENV{PATH}, - }, - - TEST1_LIB_DIR => $test1_lib_dir, - TEST2_LIB_DIR => $test2_lib_dir, - - DATE => $date, - DEVELOPER => $developer, - REVISION => $revision, - VERSION => $version, - - SED => 'sed', - # Use %(-%) around the date so date - # changes don't cause rebuilds. - SEDFLAGS => " %( -e 's+__DATE__+%DATE+' %)" . - " -e 's+__DEVELOPER__+%DEVELOPER+'" . - " -e 's+__FILE__+%<+'" . - " -e 's+__REVISION__+%REVISION+'" . - " -e 's+__VERSION__+%VERSION+'", - SEDCOM => "%SED %SEDFLAGS %< > %>", - ); - -# -# Define SCons packages. -# -# In the original, more complicated packaging scheme, we were going -# to have separate packages for: -# -# python-scons only the build engine -# scons-script only the script -# scons the script plus the build engine -# -# We're now only delivering a single "scons" package, but this is still -# "built" as two sub-packages (the build engine and the script), so -# the definitions remain here, even though we're not using them for -# separate packages. -# - -$python_scons = { - 'pkg' => "python-$project", - 'src_subdir' => 'engine', - 'inst_subdir' => File::Spec->catfile("lib", - "python1.5", - "site-packages"), - 'prefix' => $test2_dir, - - 'debian_deps' => [ qw(debian/rules debian/control - debian/changelog debian/copyright - debian/python-scons.postinst - debian/python-scons.prerm) ], - - 'files' => [ qw(LICENSE.txt README.txt setup.cfg setup.py) ], - 'filemap' => { - 'LICENSE.txt' => '../LICENSE.txt', - } -}; - -# -# The original packaging scheme would have have required us to push -# the Python version number into the package name (python1.5-scons, -# python2.0-scons, etc.), which would have required a definition -# like the following. Leave this here in case we ever decide to do -# this in the future, but note that this would require some modification -# to src/engine/setup.py before it would really work. -# -#$python2_scons = { -# 'pkg' => "python2-$project", -# 'src_subdir' => 'engine', -# 'inst_subdir' => File::Spec->catfile("lib", -# "python2.1", -# "site-packages"), -# 'prefix' => $test2_dir, -# -# 'debian_deps' => [ qw(debian/rules debian/control -# debian/changelog debian/copyright -# debian/python2-scons.postinst -# debian/python2-scons.prerm) ], -# -# 'files' => [ qw(LICENSE.txt README.txt setup.cfg setup.py) ], -# 'filemap' => { -# 'LICENSE.txt' => '../LICENSE.txt', -# } -#}; - -$scons_script = { - 'pkg' => "$project-script", - 'src_subdir' => 'script', - 'inst_subdir' => 'bin', - 'prefix' => $test2_dir, - - 'debian_deps' => [ qw(debian/rules debian/control - debian/changelog debian/copyright - debian/python-scons.postinst - debian/python-scons.prerm) ], - - 'files' => [ qw(LICENSE.txt README.txt setup.cfg setup.py) ], - 'filemap' => { - 'LICENSE.txt' => '../LICENSE.txt', - 'scons' => 'scons.py', - } -}; - -$scons = { - 'pkg' => $project, - 'inst_subdir' => undef, - 'prefix' => $test1_dir, - - 'debian_deps' => [ qw(debian/rules debian/control - debian/changelog debian/copyright - debian/scons.postinst - debian/scons.prerm) ], - - 'files' => [ qw(CHANGES.txt LICENSE.txt - README.txt RELEASE.txt - os_spawnv_fix.diff scons.1 - script/scons.bat setup.cfg setup.py) ], - 'filemap' => { - 'scons.1' => '../doc/man/scons.1', - }, - - 'subpkgs' => [ $python_scons, $scons_script ], - 'subinst_dirs' => { "python-$project" => $lib_project, - "$project-script" => 'bin', - }, -}; - -my @src_deps; - -for $p ($scons) { - # - # Initialize variables with the right directories for this package. - # - my $pkg = $p->{'pkg'}; - - my $src = 'src'; - $src = File::Spec->catfile($src, $p->{'src_subdir'}) if $p->{'src_subdir'}; - - my $build = File::Spec->catfile('build', $pkg); - - my $prefix = $p->{'prefix'}; - my $install = $prefix; - if ($p->{'inst_subdir'}) { - $install = File::Spec->catfile($install, $p->{'inst_subdir'}); - } - - # - # Read up the list of source files from our MANIFEST.in. - # This list should *not* include LICENSE.txt, MANIFEST, - # README.txt, or setup.py. Make a copy of the list for the - # destination files. - # - my @src_files = cons::read_file("$src/MANIFEST.in"); - chomp(@src_files); - my @dst_files = map(File::Spec->catfile($install, $_), @src_files); - - if ($p->{'subpkgs'}) { - # - # This package includes some sub-packages. Read up their - # MANIFEST.in files, and add them to our source and destination - # file lists, modifying them as appropriate to add the - # specified subdirs. - # - foreach $sp (@{$p->{'subpkgs'}}) { - my $ssubdir = $sp->{'src_subdir'}; - my $isubdir = $p->{'subinst_dirs'}->{$sp->{'pkg'}}; - my $manifest = File::Spec->catfile($src, $ssubdir, 'MANIFEST.in'); - my @f = cons::read_file($manifest); - chomp(@f); - push(@src_files, map(File::Spec->catfile($sp->{'src_subdir'}, $_), - @f)); - push(@dst_files, map(File::Spec->catfile($install, $isubdir, $_), - @f)); - my $k; - foreach $k (keys %{$sp->{'filemap'}}) { - my $f = $sp->{'filemap'}->{$k}; - next if ! defined $f; - $k = File::Spec->catfile($sp->{'src_subdir'}, $k); - $p->{'filemap'}->{$k} = File::Spec->catfile($sp->{'src_subdir'}, - $f); - } - } - } - - # - # Now that we have the "normal" source files, add those files - # that are standard for each distribution. Note that we don't - # add these to dst_files, because they don't get installed. - # And we still have the MANIFEST to add. - # - push(@src_files, @{$p->{'files'}}); - - # - # Now run everything in src_file through the sed command we - # concocted to expand __FILE__, __VERSION__, etc. - # - foreach $b (@src_files) { - my $s = $p->{'filemap'}->{$b} || $b; - $env->Command("$build/$b", "$src/$s", "%SEDCOM"); - } - - # - # NOW, finally, we can create the MANIFEST, which we do - # by having Perl spit out the contents of the @src_files - # array we've carefully created. After we've added - # MANIFEST itself to the array, of course. - # - push(@src_files, "MANIFEST"); - $env->Command("$build/MANIFEST", "$src/MANIFEST.in", - qq([perl] open(F, ">%>"); print F join("\\n", sort qw(@src_files)), "\\n"; close(F))); - - # - # Use the Python distutils to generate the packages. - # - my $archive = "$build/dist/$pkg-$version.$archsuffix"; - - push(@src_deps, $archive); - - my @build_targets = ( - "$build/dist/$pkg-$version.$platform.$archsuffix", - $archive, - "$build/dist/$pkg-$version.win32.exe", - ); - my @install_targets = @build_targets; - - # We can get away with calling setup.py using a directory path - # like this because we put a preamble in it that will chdir() - # to the directory in which setup.py exists. - my @bdist_dirs = ("$build/build/lib", "$build/build/scripts"); - my $commands = qq(rm -rf @bdist_dirs && python $build/setup.py bdist - python $build/setup.py sdist - python $build/setup.py bdist_wininst); - - if ($rpm) { - chomp($cwd = `pwd`); - $topdir = "$cwd/$build/build/bdist.$platform/rpm"; - - $BUILDdir = "$topdir/BUILD/$pkg-$version"; - $RPMSdir = "$topdir/RPMS/noarch"; - $SOURCESdir = "$topdir/SOURCES"; - $SPECSdir = "$topdir/SPECS"; - $SRPMSdir = "$topdir/SRPMS"; - - $specfile = "$SPECSdir/$pkg-$version-1.spec"; - $sourcefile = "$SOURCESdir/$pkg-$version.$archsuffix"; - $rpm = "$RPMSdir/$pkg-$version-1.noarch.rpm"; - $src_rpm = "$SRPMSdir/$pkg-$version-1.src.rpm"; - - # We'd like to use the following here: - # - # $env->InstallAs($specfile, "rpm/$pkg.spec"); - # $env->InstallAs($sourcefile, $archive); - # - # but it looks like InstallAs doesn't propogate the - # signatures correctly, which means that the RPM file - # wouldn't always get rebuilt when it should. Work - # around it. - use File::Copy; - $env->Command($specfile, "rpm/$pkg.spec", - "[perl] File::Copy::copy('%<', '%>')"); - $env->Command($sourcefile, $archive, - "[perl] File::Copy::copy('%<', '%>')"); - - if (! -d $BUILDdir) { - $cmd = "mkdir -p $BUILDdir; "; - } - my @targets = ( $rpm, $src_rpm ); - $env->Command(\@targets, $specfile, - "${cmd}rpm --define '_topdir $topdir' -ba %<"); - $env->Depends(\@targets, $sourcefile); - - push(@install_targets, @targets); - }; - - @build_src_files = map("$build/$_", @src_files); - - if ($dh_builddeb && $fakeroot) { - # Debian builds directly into build/dist, so we don't - # need to add the .debs to the install_targets. - my $deb = "build/dist/${pkg}_$version-1_all.deb"; - $env->Command($deb, @build_src_files, qq( - fakeroot make -f debian/rules VERSION=%VERSION DH_COMPAT=$DH_COMPAT ENVOKED_BY_CONSTRUCT=1 binary-$pkg - env DH_COMPAT=$DH_COMPAT dh_clean)); - $env->Depends($deb, @{$p->{'debian_deps'}}); - } - - # - # Now set up creation and installation of the packages. - # - $env->Command([@build_targets], @build_src_files, $commands); - - $env->Install("build/dist", @install_targets); - - # - # Unpack the archive created by the distutils into build/unpack. - # - my @unpack_files = map("$unpack_dir/$pkg-$version/$_", @src_files); - - # We'd like to replace the last three lines with the following: - # - # tar zxf %< -C $unpack_dir - # - # but that gives heartburn to Cygwin's tar, so work around it - # with separate zcat-tar-rm commands. - Command $env [@unpack_files], $archive, qq( - rm -rf $unpack_dir/$pkg-$version - zcat %< > .temp - tar xf .temp -C $unpack_dir - rm -f .temp - ); - - # - # Run setup.py in the unpacked subdirectory to "install" everything - # into our build/test subdirectory. Auxiliary modules that we need - # (TestCmd.py, TestSCons.py, unittest.py) will be copied in by - # etc/Conscript. The runtest.py script will set PYTHONPATH so that - # the tests only look under build/test. This makes sure that our - # tests pass with what we really packaged, not because of something - # hanging around in the development directory. - # - # We can get away with calling setup.py using a directory path - # like this because we put a preamble in it that will chdir() - # to the directory in which setup.py exists. - Command $env [@dst_files], @unpack_files, qq( - rm -rf $install - python $unpack_dir/$pkg-$version/setup.py install --prefix=$prefix - ); -} - -# -# Arrange for supporting packages to be installed in the test directories. -# -Export qw( env ); - -Build "etc/Conscript"; - -# -# Documentation. -# -Link 'build/doc' => 'doc'; - -Build 'build/doc/Conscript'; - - -# -# If we're running in the actual Aegis project, pack up a complete -# source archive from the project files and files in the change, -# so we can share it with helpful developers who don't use Aegis. -# -# First, lie and say that we've seen any files removed by this -# change, so they don't get added to the source files list -# that goes into the archive. -# - -if ($change) { - foreach (`aegis -list -unf -c $change cf 2>/dev/null`) { - $seen{"$1\n"}++ if /^(?:source|test) remove(?:\s.*)+\s(\S+)$/; - } - - eval '@src_files = grep(! $seen{$_}++, - `aegis -list -terse pf 2>/dev/null`, - `aegis -list -terse cf 2>/dev/null`)'; - - @src_files = grep($_ !~ /(\.aeignore|\.consign)$/, @src_files); - - if (@src_files) { - chomp(@src_files); - - foreach $file (@src_files) { - $env->Command("build/$project-src/$file", - $file, - qq(%SEDCOM - chmod --reference=%< %>) - ); - } - - $env->Command("build/dist/$project-src-$version.tar.gz", - @src_deps, - map("build/$project-src/$_", @src_files), - qq( - rm -rf build/$project-src-$version - cp -rp build/$project-src build/$project-src-$version - find build/$project-src-$version -name .consign -exec rm {} \\; - tar zcf %> -C build $project-src-$version - )); - } -} diff --git a/README b/README index d2c511f..c7f5a99 100644 --- a/README +++ b/README @@ -55,7 +55,7 @@ system, populate the build/scons/ directory by running: $ scons build/scons -If you don't have SCons version 0.06 or later already installed on your +If you don't have SCons version 0.07 or later already installed on your system, you can use SCons itself to populate the build/scons/ directory with a little more work: @@ -116,21 +116,21 @@ unsuccessful tests. The above invocations all test directly the files underneath the src/ subdirectory, and do not require that a build be performed first. The -runtest.py script supports supports additional options to run tests -against unpacked packages in the build/test-*/ subdirectories. See -the "TESTING PACKAGES" section below. +runtest.py script supports additional options to run tests against +unpacked packages in the build/test-*/ subdirectories. See the "TESTING +PACKAGES" section below. BUILDING PACKAGES ================= -We now use SCons (version 0.06 or later) to build its own packages. +We now use SCons (version 0.07 or later) to build its own packages. If you already have an appropriate version of SCons installed on your system, you can build everything by simply running it: $ scons -If you don't have SCons version 0.06 or later already installed on your +If you don't have SCons version 0.07 or later already installed on your system, you can build this version of SCons with itself with a little more work: @@ -203,11 +203,6 @@ build/ tree. This is generated as part of our build process, and it's where, believe it or not, we *build* everything. -Construct - The old Cons-based "Makefile" for the SCons distribution. This - is obsolete as of version 0.04, but it's being left around for a - little while, just in case... - config The Aegis configuration, governing much of how we use Aegis to build, test, control source, etc. @@ -252,7 +247,12 @@ runtest.py (aeb) before running tests. SConstruct - The "Makefile" for the SCons distribution. + The "Makefile" for the SCons distribution. (It has been + pointed out that it's hard to find the SCons API in here, and + it looks a lot more like a straight Python script than a build + configuration file, but that's mainly because all of the magick + we have to do to deal with a variety of packaging formats + requires a lot of straight Python manipulation.) src/ Where the actual source code is kept, of course. diff --git a/debian/changelog b/debian/changelog index ef0eb56..651eee2 100644 --- a/debian/changelog +++ b/debian/changelog @@ -2,7 +2,7 @@ scons (0.07-1) unstable; urgency=low * Folding uploaded Debian build into SCons source - -- Steven Knight Tue, 23 Apr 2002 07:04:54 -0500 + -- Steven Knight Thu, 25 Apr 2002 06:24:50 -0500 scons (0.05-1) unstable; urgency=low diff --git a/doc/Conscript b/doc/Conscript deleted file mode 100644 index 9eef3e6..0000000 --- a/doc/Conscript +++ /dev/null @@ -1,254 +0,0 @@ -# -# Conscript file for building SCons documentation. -# - -# -# Copyright (c) 2001, 2002 Steven Knight -# -# 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. -# - -Import qw( env ); - -# -# -# -$doc_tar_gz = "#build/dist/scons-doc-${\$env->{VERSION}}.tar.gz"; - -# -# We'll only try to build text files (for some documents) -# if lynx is available to do the dump. -# -$fig2dev = cons::whereis('fig2dev'); -$groff = cons::whereis('groff'); -$lynx = cons::whereis('lynx'); -$man2html = cons::whereis('man2html'); -$jw = cons::whereis('jw'); - -if ($jw) { - # - # Always create a version.sgml file containing the version information - # for this run. Ignore it for dependency purposes so we don't - # rebuild all the docs every time just because the date changes. - # - $verfile = SourcePath("version.sgml"); - unlink($verfile); - chmod(0664, $verfile); - open(FILE, ">$verfile") || die "Cannot open '$verfile': $!"; - print FILE <<_EOF_; - -{DATE}}"> -{VERSION}}"> -{REVISION}}"> -_EOF_ - close(FILE); - - Ignore("version.sgml"); - - # Find internal dependencies in .sgml files: - # - # - # - # - # - # This only finds one per line, and assumes that anything - # defined as a SYSTEM entity is, in fact, a file included - # somewhere in the document. - sub scansgml { - my $dir = shift; - my @includes = (); - do { - if (//i) { - push(@includes, $1); - } elsif (/<(?:graphic|imagedata)\s+fileref="([^"]*)"\s+format="([^"]*)"/) { - ($file, $format) = ($1, $2); - $file = "$file.$format" if ($file !~ /\.$format$/); - if ($dir && ! File::Spec->file_name_is_absolute($file)) { - $file = "build/doc/$dir/$file"; - } - push(@includes, $file); - } elsif (/<(?:graphic|imagedata)\s+fileref="([^"]*)"/) { - $file = $1; - if ($dir && ! File::Spec->file_name_is_absolute($file)) { - $file = "build/doc/$dir/$file"; - } - push(@includes, $file); - } - } while (); - @includes; - } - - # - # Each document will live in its own subdirectory. List them here - # as hash keys, with a hash of the info to control its build. - # - %docs = ( - 'design' => { - 'htmlindex' => 'book1.html', - 'ps' => 1, - 'pdf' => 1, - 'text' => 0, - 'scan' => sub { scansgml("design") }, - }, - 'python10' => { - 'htmlindex' => 't1.html', - 'html' => 1, - 'ps' => 1, - 'pdf' => 0, - 'text' => 0, - 'graphics' => [qw( arch builder job-task node scanner sig )], - 'scan' => sub { scansgml("python10") }, - }, - 'user' => { - 'htmlindex' => 'book1.html', - 'html' => 1, - 'ps' => 1, - 'pdf' => 1, - 'text' => 0, - 'scan' => sub { scansgml("user") }, - }, - ); - - # - # We have to tell Cons to QuickScan the top-level SGML files which - # get included by the document SGML files in the subdirectories. - # - @included_sgml = qw( - scons.mod - copyright.sgml - ); - - foreach $sgml (@included_sgml) { - $env->QuickScan(\&scansgml, $sgml); - } - - # - # For each document, build the document itself in HTML, Postscript, - # and PDF formats. - # - foreach $doc (keys %docs) { - my $main = "$doc/main.sgml"; - my $out = "main.out"; - - my $htmldir = "HTML/scons-$doc"; - my $htmlindex = "$htmldir/" . $docs{$doc}->{'htmlindex'}; - my $html = "HTML/scons-$doc.html"; - my $ps = "PS/scons-$doc.ps"; - my $pdf = "PDF/scons-$doc.pdf"; - my $text = "TEXT/scons-$doc.txt"; - - if ($docs{$doc}->{'scan'}) { - $env->QuickScan($docs{$doc}->{'scan'}, $main); - } - - if ($docs{$doc}->{'html'}) { - $env->Command($htmlindex, $main, - qq(rm -f %>:d/*.html - jw -b html -o %>:d %< - mv -v %>:d/index.html %> || true - )); - - $env->Command($html, $main, qq(jw -u -b html %< > %>)); - - push(@tar_deps, $html, $htmlindex); - push(@tar_list, $html, $htmldir); - if ($fig2dev) { - for $g (@{$docs{$doc}->{'graphics'}}) { - $fig = "$doc/$g.fig"; - $jpg = "$htmldir/$g.jpg"; - $env->Command($jpg, $fig, qq($fig2dev -L jpeg -q 100 %< %>)); - $env->Depends($ps, $jpg); - } - } - } - - if ($docs{$doc}->{'ps'}) { - $env->Command($ps, $main, - qq(rm -f %>:d/$out - jw -b ps -o %>:d %< - mv %>:d/main.ps %> - rm -f %>:d/$out - )); - push(@tar_deps, $ps); - push(@tar_list, $ps); - if ($fig2dev) { - for $g (@{$docs{$doc}->{'graphics'}}) { - $fig = "$doc/$g.fig"; - $eps = "PS/$g.eps"; - $env->Command($eps, $fig, qq($fig2dev -L eps %< %>)); - $env->Depends($ps, $eps); - } - } - } - - if ($docs{$doc}->{'pdf'}) { - $env->Command($pdf, $main, - qq(rm -f %>:d/$out - jw -b pdf -o %>:d %< - mv %>:d/main.pdf %> - rm -f %>:d/$out - )); - push(@tar_deps, $pdf); - push(@tar_list, $pdf); - } - - if ($docs{$doc}->{'text'} && $lynx) { - $env->Command($text, $html, qq(lynx -dump %<:a > %>)); - push(@tar_deps, $text); - push(@tar_list, $text); - } - } -} - -# -# Man page(s), in good ol' troff format. -# -my $scons_1 = "man/scons.1"; - -if ($groff) { - my $ps = "PS/scons-man.ps"; - my $text = "TEXT/scons-man.txt"; - - $env->Command($ps, $scons_1, "groff -man -Tps %< > %>"); - - $env->Command($text, $scons_1, "groff -man -Tascii %< > %>"); - - push(@tar_deps, $ps, $text); - push(@tar_list, $ps, $text); -} - -if ($man2html) { - my $html = "HTML/scons-man.html"; - - $env->Command($html, $scons_1, "man2html %< > %>"); - - push(@tar_deps, $html); - push(@tar_list, $html); -} - -# -# Now actually create the tar file of the documentation, -# for easy distribution to the web site. -# -$env->Command($doc_tar_gz, - @tar_deps, - qq(tar zchv -f %> -C build/doc @tar_list)); diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 5fdc1aa..afd4c16 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -614,6 +614,8 @@ Turn off -w, even if it was turned on implicitly. .\" repositories are searched in the order specified. .SH CONFIGURATION FILE REFERENCE +.\" .SS Python Basics +.\" XXX Adding this in the future would be a help. .SS Construction Environments A construction environment is the basic means by which the configuration files communicate build information to @@ -646,7 +648,25 @@ provides the following builders: .IP Object Builds an object file from one or more C, C++, or Fortran source files. Source files must have one of the following extensions: -.c, .C, .cc, .cpp, .cxx, .c++, .C++, .f, .F, .for, .FOR, .fpp, .FPP. +.ES + .c C file + .C WIN32: C file + POSIX: C++ file + .cc C++ file + .cpp C++ file + .cxx C++ file + .cxx C++ file + .c++ C++ file + .C++ C++ file + .f Fortran file + .F WIN32: Fortran file + POSIX: Fortran file + C pre-processor + .for Fortran file + .FOR Fortran file + .fpp Fortran file + C pre-processor + .FPP Fortran file + C pre-processor +.EE +.IP The target object file prefix and suffix (if any) are automatically added. Examples: @@ -668,9 +688,17 @@ env.Object(target = 'ddd.obj', source = 'ddd.c', shared = 1) .EE .IP Program -Builds an executable given one or more object files or C/C++ source -files. If any C/C++ source files are given, then they will be automatically -compiled to object files. The executable prefix and suffix (if any) are +Builds an executable given one or more object files or C, C++ +or Fortran source files. +If any C, C++ or Fortran source files are specified, +then they will be automatically +compiled to object files using the +.B Object +builder; +see that builder's description for +a list of legal source file suffixes +and how they are interpreted. +The executable prefix and suffix (if any) are automatically added to the target. Example: .ES @@ -730,8 +758,10 @@ is automatically added to the target if it is not already present. Example: .ES -env.CFile(target = 'foo.c', source = 'foo.l') # builds foo.c -env.CFile(target = 'bar', source = 'bar.y') # builds bar.c +# builds foo.c +env.CFile(target = 'foo.c', source = 'foo.l') +# builds bar.c +env.CFile(target = 'bar', source = 'bar.y') .EE .IP CXXFile @@ -742,8 +772,10 @@ is automatically added to the target if it is not already present. Example: .ES -env.CXXFile(target = 'foo.cc', source = 'foo.ll') # builds foo.cc -env.CXXFile(target = 'bar', source = 'bar.yy') # builds bar.cc +# builds foo.cc +env.CXXFile(target = 'foo.cc', source = 'foo.ll') +# builds bar.cc +env.CXXFile(target = 'bar', source = 'bar.yy') .EE .IP DVI @@ -754,9 +786,12 @@ is automatically added to the target if it is not already present. Example: .ES -env.DVI(target = 'aaa.dvi', source = 'aaa.tex') # builds from aaa.tex -env.DVI(target = 'bbb', source = 'bbb.ltx') # builds bbb.dvi -env.DVI(target = 'ccc.dvi', source = 'ccc.latex') # builds from ccc.latex +# builds from aaa.tex +env.DVI(target = 'aaa.dvi', source = 'aaa.tex') +# builds bbb.dvi +env.DVI(target = 'bbb', source = 'bbb.ltx') +# builds from ccc.latex +env.DVI(target = 'ccc.dvi', source = 'ccc.latex') .EE .IP PDF @@ -768,8 +803,10 @@ is added automatically to the target if it is not already present. Example: .ES -env.PDF(target = 'aaa.pdf', source = 'aaa.tex') # builds from aaa.tex -env.PDF(target = 'bbb', source = 'bbb.dvi') # builds bbb.dvi +# builds from aaa.tex +env.PDF(target = 'aaa.pdf', source = 'aaa.tex') +# builds bbb.dvi +env.PDF(target = 'bbb', source = 'bbb.dvi') .EE .IP PostScript @@ -781,13 +818,22 @@ is added automatically to the target if it is not already present. Example: .ES -env.PostScript(target = 'aaa.ps', source = 'aaa.tex') # builds from aaa.tex -env.PostScript(target = 'bbb', source = 'bbb.dvi') # builds bbb.dvi +# builds from aaa.tex +env.PostScript(target = 'aaa.ps', source = 'aaa.tex') +# builds bbb.dvi +env.PostScript(target = 'bbb', source = 'bbb.dvi') .EE .LP .B scons automatically scans -C, C++ and Fortran source files with .F, .fpp, or .FOR file extensions +C source files, C++ source files, and +Fortran source files with +.B .F +(POSIX systems only), +.B .fpp, +or +.B .FPP +file extensions for C preprocessor dependencies, so the dependencies do not need to be specified explicitly. In addition, all builder @@ -801,19 +847,34 @@ Additional Environment methods include: .TP .RI Command( target ", " source ", " commands ) -Executes a specific command -(or list of commands) +Executes a specific action +(or list of actions) to build a target file or files. This is more convenient than defining a separate Builder object for a single special-case build. +Note that an action can be an external command, +specified as a string, +or a callable Python object; +see "Action Objects," below. +Examples: + .ES env.Command('foo.out', 'foo.in', "$FOO_BUILD < $SOURCES > $TARGET") + env.Command('bar.out', 'bar.in', ["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"]) + +def rename(env, target, source): + import os + os.rename('.tmp', str(target[0])) + +env.Command('baz.out', 'baz.in', + ["$BAZ_BUILD < $SOURCES > .tmp", + rename ]) .EE .TP @@ -926,7 +987,22 @@ env.Update(CCFLAGS = '-g', FOO = 'foo.xxx') .EE .SS Construction Variables - +.\" XXX From Gary Ruben, 23 April 2002: +.\" I think it would be good to have an example with each construction +.\" variable description in the documentation. +.\" eg. +.\" CC The C compiler +.\" Example: env["CC"] = "c68x" +.\" Default: env["CC"] = "cc" +.\" +.\" CCCOM The command line ... +.\" Example: +.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES +.\" env["CC"] = "c68x" +.\" env["CFLAGS"] = "-ps -qq -mr" +.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES +.\" Default: +.\" (I dunno what this is ;-) A construction environment has an associated dictionary of construction variables that are used by built-in or user-supplied build rules. A number of useful construction variables are automatically defined by scons for @@ -961,7 +1037,13 @@ The suffix for C source files. This is used by the internal CFile builder when generating C files from Lex (.l) or YACC (.y) input files. The default suffix, of course, is -.IR .c . +.I .c +(lower case). +On case-insensitive systems (like Win32), +SCons also treats +.I .C +(upper case) files +as C files. .IP CPPFLAGS C preprocessor options. @@ -1005,6 +1087,18 @@ This is used by the internal CXXFile builder when generating C++ files from Lex (.ll) or YACC (.yy) input files. The default suffix is .IR .cc . +SCons also treats files with the suffixes +.IR .cpp , +.IR .cxx , +.IR .c++ , +and +.I .C++ +as C++ files. +On case-sensitive systems (Linux, UNIX, and other POSIX-alikes), +SCons also treats +.I .C +(upper case) files +as C++ files. .IP CXXCOM The command line used to compile a C++ source file to an object file. @@ -1711,6 +1805,16 @@ a command-line Action is returned. Action('$CC -c -o $TARGET $SOURCES') .EE +.\" XXX From Gary Ruben, 23 April 2002: +.\" What would be useful is a discussion of how you execute command +.\" shell commands ie. what is the process used to spawn the shell, pass +.\" environment variables to it etc., whether there is one shell per +.\" environment or one per command etc. It might help to look at the Gnu +.\" make documentation to see what they think is important to discuss about +.\" a build system. I'm sure you can do a better job of organising the +.\" documentation than they have :-) + + .IP List If the argument is a list, then a list of Action objects is returned. @@ -1982,6 +2086,112 @@ The argument is the argument supplied when the scanner was created, if any. +.SH SYSTEM-SPECIFIC BEHAVIOR +SCons and its configuration files are very portable, +due largely to its implementation in Python. +There are, however, a few portability +issues waiting to trap the unwary. +.SS .C file suffix +SCons handles the upper-case +.B .C +file suffix differently, +depending on the capabilities of +the underlying system. +On a case-sensitive system +such as Linux or UNIX, +SCons treats a file with a +.B .C +suffix as a C++ source file. +On a case-insensitive system +such as Windows, +SCons treats a file with a +.B .C +suffix as a C source file. +.SS .F file suffix +SCons handles the upper-case +.B .F +file suffix differently, +depending on the capabilities of +the underlying system. +On a case-sensitive system +such as Linux or UNIX, +SCons treats a file with a +.B .F +suffix as a Fortran source file +that is to be first run through +the standard C preprocessor. +On a case-insensitive system +such as Windows, +SCons treats a file with a +.B .F +suffix as a Fortran source file that should +.I not +be run through the C preprocessor. +.SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons +Cygwin supplies a set of tools and utilities +that let users work on a +Windows system using a more POSIX-like environment. +The Cygwin tools, including Cygwin Python, +do this, in part, +by sharing an ability to interpret UNIX-like path names. +For example, the Cygwin tools +will internally translate a Cygwin path name +like /cygdrive/c/mydir +to an equivalent Windows pathname +of C:/mydir (equivalent to C:\\mydir). + +Versions of Python +that are built for native Windows execution, +such as the python.org and ActiveState versions, +do not have the Cygwin path name semantics. +This means that using a native Windows version of Python +to build compiled programs using Cygwin tools +(such as gcc, bison, and flex) +may yield unpredictable results. +"Mixing and matching" in this way +can be made to work, +but it requires careful attention to the use of path names +in your SConscript files. + +In practice, users can sidestep +the issue by adopting the following rules: +When using gcc, +use the Cygwin-supplied Python interpreter +to run SCons; +when using Microsoft Visual C/C++ +(or some other Windows compiler) +use the python.org or ActiveState version of Python +to run SCons. +.SS WIN32: scons.bat file +On WIN32 systems, +SCons is executed via a wrapper +.B scons.bat +file. +This has (at least) two ramifications: + +First, Windows command-line users +that want to use variable assignment +on the command line +may have to put double quotes +around the assignments: + +.ES +scons "FOO=BAR" "BAZ=BLEH" +.EE + +Second, the Cygwin shell does not +recognize this file as being the same +as an +.B scons +command issued at the command-line prompt. +You can work around this either by +executing +.B scons.bat +from the Cygwin command line, +or by creating a wrapper shell +script named +.B scons . + .SH EXAMPLES To help you get started using SCons, diff --git a/etc/Conscript b/etc/Conscript deleted file mode 100644 index 552ab26..0000000 --- a/etc/Conscript +++ /dev/null @@ -1,15 +0,0 @@ -# -# Conscript for installing auxiliary modules, external stuff that -# we keep checked in so everyone doesn't have to install a bunch -# of stuff to work on SCons. -# - -Import qw( env ); - -@modules = qw(TestCmd.py TestSCons.py unittest.py); - -foreach $module (@modules) { - for $dir ($env->{TEST1_LIB_DIR}, $env->{TEST2_LIB_DIR}) { - $env->Command(File::Spec->catfile($dir, $module), $module, "%SEDCOM"); - } -} diff --git a/src/CHANGES.txt b/src/CHANGES.txt index 3bb532d..f162a59 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -8,7 +8,7 @@ -RELEASE 0.07 - +RELEASE 0.07 - Thu, 25 Apr 2002 06:24:50 -0500 From Chad Austin: diff --git a/src/RELEASE.txt b/src/RELEASE.txt index b3442e8..8a79ffc 100644 --- a/src/RELEASE.txt +++ b/src/RELEASE.txt @@ -20,19 +20,39 @@ more effectively, please sign up for the scons-users mailing list at: -RELEASE 0.07 - +RELEASE 0.07 - Thu, 25 Apr 2002 06:24:50 -0500 This is the seventh alpha release of SCons. Please consult the CHANGES.txt file for a list of specific changes since last release. Please note the following important changes since release 0.06: - - The functionality of the -U option has changed. XXX + - The functionality of the -U option has changed. It now works + exactly like the -u option (searches up the directory tree for an + SConstruct file) but, when no targets are specified on the command + line, it will build all targets that are defined in any SConscript + files in the current directory. - Please note the following important changes since release 0.05: + The previous functionality of this option is now available in the + -D option: when no targets are specified on the command line, + SCons will build *all* Default() targets, not just those at or + below the current directory, + + - The default Fortran compilation command on Windows systems now + uses Windows conventions (/Fo) instead of UNIX conventions (-o). + + - The $SOURCE construction variable is now a synonym for + ${SOURCES[0]}. This will affect you if you previously set $SOURCE + explicitly in a construction environment. - - Scanner functions now take four arguments. + - Scanner functions now take three or four arguments. The target + Node is now passed in as the third argument; the fourth argument + is an optional SCons.Node.FS.FS object. You will need to update + the interfaces of any local Scanner functions you have defined. + + Please note the following important changes since release 0.05: + - Python functions as Builder actions now take Node objects, not strings, as arguments. The string representation of a Node object is the file name, so you should change your function actions to use the str() built-in function to fetch the file @@ -50,14 +70,14 @@ RELEASE 0.07 - Nevertheless, because this is an alpha release, heed the following disclaimers: - - Do not be surprised if there are bugs. Please report any bugs - or other problems that you find to our bug tracker at our - SourceForge project page: + - There may, of course, be bugs. Please report any bugs or other + problems that you find to our bug tracker at our SourceForge + project page: http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971 - We have a reliable bug-fixing methodology already in place and - have been responding to problems relatively quickly. + We have a reliable bug-fixing methodology already in place and aim + to respond to problems relatively quickly. - It is possible that interfaces will change in future releases. We will strive to hold this to a minimum, but you may need to modify @@ -65,17 +85,19 @@ RELEASE 0.07 - to change an interface. - Documentation is spottier than we'd like. You may need to dive - into the source code to figure out how to do something. We will - be addressing this in upcoming releases, but would be more than - glad to have your assistance in correcting this problem... :-) + into the source code to figure out how to do something. Asking + questions on the scons-users mailing list is also welcome. We + will be addressing the documentation in upcoming releases, but + would be more than glad to have your assistance in correcting this + problem... :-) In particular, the "SCons Design" documentation on the SCons web site is currently out of date, as we made significant changes to portions of the interface as we figured out what worked and what didn't during implementation.L - - There may be performance issues. This release has still more - performance improvements. If you still find the performance + - There may be performance issues. Improving SCons performance + is an ongoing priority. If you still find the performance unacceptable, we would very much like to hear from you and learn more about your configuration so we can optimize the right things. @@ -97,20 +119,20 @@ RELEASE 0.07 - use if you you want to fix your version of Python to support parallel builds in SCons. - - Even on officialy Python release 2.2., values greater than 1 for - the -j option on Windows seemingly hang SCons. This problem is - being investigated. - - - Extremely long command lines (thousands of characters) can - reportedly crash Python. This problem is being investigated. - - Again, the "SCons Design" documentation on the SCons web site is currently out of date. Take what you read there with a grain of salt. - - There is a hard-coding that prevents using file timestamps instead - of MD5 signatures to determine if a file is up-to-date. (There - also isn't yet a mechanism to configure that.) + - There is not yet a mechanism to configure using file timestamps + instead of MD5 signatures to determine if a file is up-to-date. + + - Executing the -u option from a source directory that has an + associated BuildDir() does not build the targets in the BuildDir(). + + - On Windows systems using MSVC/C++, long link lines are handled + by writing the arguments to a temporary file. Because the + temporary file name may change from invocation to invocation, + long link lines may be rebuilt more often than necessary. - No support yet for the following future features: -- cgit v0.12