# Copyright (c) 2001, 2002, 2003, 2004 The SCons Foundation
# src/RELEASE.txt 0.96.90.D001 2005/02/15 20:11:37 knight


                 SCons - a software construction tool

                            Release Notes


This is a PRE-RELEASE FOR TESTING of a beta release of SCons, a tool for
building software (and other files).  SCons is implemented in Python,
and its "configuration files" are actually Python scripts, allowing you to
use the full power of a real scripting language to solve build problems.
You do not, however, need to know Python to use SCons effectively.

So that everyone using SCons can help each other learn how to use it
more effectively, please sign up for the scons-users mailing list by
sending mail to:

    users-subscribe@scons.tigris.org

See the section after the next section for a description of significant
interface or behavioral changes in this release.


ABOUT THIS TESTING PRE-RELEASE:

This testing pre-release is intended to provide additional field exposure
and bug shake-out before an official 0.97 release.

We're doing this because there have been a *lot* of changes to the SCons
infrastructure since 0.96.1 was released, and we want some extra assurance
that we've caught as many bugs as possible that may have slipped through
any cracks in our regression test suite.  Here's how you can help:

    BUGS:

        If you run into any outright bugs, please file a report at our
        SourceForge bug tracker:

            http://sourceforge.net/tracker/?group_id=30337&atid=398971

        Also please send some email to either dev@scons.tigris.org or
        user@tigris.org.  We'll be monitoring the mailing lists for bug
        reports, but the bug tracker report will help make sure that
        these things get tracked and, we hope, fixed.

        WHEN YOU REPORT A BUG, please be specific.  It's more effective
        if you don't try to guess at the cause, but instead describe the
        symptom you observed *and* the differing behavior you expected.
        Cutting and pasting is good.

        If possible, it's a *huge* help if you can reduce your
        configuration to a small/simple test case that clearly
        demonstrates the problem.

    RECOMPILATIONS ON UPGRADE:

        In general, we try to make sure that upgrading SCons releases
        doesn't cause recompilations.  But with the significant changes
        in this release, we know there are configurations that will
        experience recompilations.  Unfortunately, we don't have a concise
        definition of what configurations get recompiled on upgrade.
        You can help us track this down by running with the following
        option the *first* time you run SCons 0.96.90 against your old
        build tree:

                scons --debug=explain

        If you experience recompilations, please collect the messages
        explaining why the target(s) are being recompiled and send them to
        dev@scons.tigris.org.  (No need to file a bug report this time.)

    PERFORMANCE:

        The most complicated (and highly-anticipated) changes in this
        release involved speeding up SCons and reducing how much memory
        it uses.  To set expectations clearly:  don't expect these changes
        to have suddenly made SCons as fast as Make; internally, SCons
        is doing a lot more than Make does!  Instead, our tests suggest
        that a typical small-to-medium configuration can probably expect
        a 10%-30% improvement from the changes in this release.

        However, these changes should significantly speed up large
        SCons configurations, configurations with long CPPPATH lists,
        or that were seemingly "hung" due to inappropriate scanning of
        large directory trees.  In other words, this release of SCons
        should be significantly more scalable than previous releases.

        IF THIS RELEASE PERFORMS WORSE FOR YOU:  We really really really
        want to know!  Changes that help one configuration may actually
        hurt others, and we want to know what these trade-offs are so
        we can make some conscious decisions about how to handle them.

        IF THE PERFORMANCE IMPROVED SOME, BUT NOT ENOUGH:  We want to
        know that, too.

        TO REPORT PERFORMANCE ISSUES, please run SCons on your
        configuration with the following options enabled:

                scons --debug=memory --debug=count --debug=memoizer

        Then please send email to dev@scons.tigris.org and file a bug
        report at the tracker (URL above), attaching a copy of your
        configuration and a copy of the debug output from the end of your
        run.  Note that the --debug= options above will make SCons
        take a little longer to build.

        If you can, it would also be *extremely* helpful to run SCons
        on your configuration separately with the following option:

                scons --profile=scons.prof

        This will take a *lot* longer to build (probably an order of
        magnitude) but it will dump Python profiling information to
        the "scons.prof" file.  Sending us the file will provide a
        very detailed picture of where the bottlenecks are in your
        configuration.
     
Thank you for your help and support in improving this release!



RELEASE 0.96.90 - Tue, 15 Feb 2005 21:21:12 +0000

  This is a pre-release for testing the eighth beta 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.96:

    - The ParseConfig() method now adds library file names returned
      by the specified *-config command to the $LIBS construction
      variable, instead of returning them (the same way it handles
      the -l option).

    - By default, the ParseConfig() method now avoids adding duplicate
      entries to construction variables.  The old behavior may be
      specified using a new "unique=0" keyword argument.

    - Custom builders that accept directories as source arguments no
      longer scan entire directory trees by default.  This means that
      their targets will not be automatically rebuilt if a file that
      SCons does *not* already know about changes on disk.  Note that
      the targets *will* still be rebuilt correctly if a file changes
      that SCons already knows about due to a Builder or other call.

      The existing behavior of scanning directory trees for any changed
      file on-disk can be maintained by passing the new DirScanner global
      directory scanner as the source_scanner keyword argument to the
      Builder call:

          bld = Builder("build < $SOURCE > $TARGET",
                        source_scanner = DirScanner)

      The same keyword argument can also be supplied to any Command()
      calls that need to scan directory trees on-disk for changed files:

          env.Command("archive.out", "directory",
                      "archiver -o $TARGET $SOURCE",
                      source_scanner = DirScanner)

    - When compiling with Microsoft Visual Studio, SCons no longer
      adds the ATL and MFC directories to the INCLUDE and LIB
      environment variables by default.  If you want these directories
      included in your environment variables, you should now set the
      $MSVS_USE_MFC_DIRS *construction* variable when initializing
      your environment:

          env = Environment(MSVS_USE_MFC_DIRS = 1)

    - The following deprecated global functions have been removed:
      ParseConfig(), SetBuildSignatureType(), SetContentSignatureType(),
      SetJobs() and GetJobs().

    - The deprecated "validater" keyword to the Options.Add() method
      has been removed.

    - The %TEMP% and %TMP% external environment variables are now
      propagated automatically to the command execution environment on
      Windows systems.

    - The Configure() subsystem now reports tests results as "yes" and
      "no" instead of "ok" and "failed."  This might interfere with any
      scripts that automatically parse the Configure() output from SCons.

    - The Configure() subsystem now stores its cached results in a
      different file.  This may cause configuration tests to be re-run
      the first time after you install 0.97.

  Please note the following important changes since release 0.95:

    - All Builder calls (both built-in like Program(), Library(),
      etc. and customer Builders) now always return a list of target
      Nodes.   If the Builder only builds one target, the Builder
      call will now return a list containing that target Node, not
      the target Node itself as it used to do.

      This change should be invisibile to most normal uses of the
      return values from Builder calls.  It will cause an error if the
      SConscript file was performing some direct manipulation of the
      returned Node value.  For example, an attempt to print the name
      of a target returned by the Object() Builder:

            target = Object('foo.c')
            # OLD WAY
            print target

      Will now need to access the first element in the list returned by
      the Object() call:

            target = Object('foo.c')
            # NEW AY
            print target[0]

      This change was introduced to make the data type returned by Builder
      calls consistent (always a list), regardless of platform or number
      of returned targets.

    - The SConsignFile() function now uses an internally-supplied
      SCons.dblite module as the default DB scheme for the .sconsign file.
      If you are using the SConsignFile() function without an explicitly
      specified dbm_module argument, this will cause all of your targets
      to be recompiled the first time you use SCons 0.96.  To preserve the
      previous behavior, specify the "anydbm" module explicitly:

          import anydbm
          SConsignFile('.sconsign_file_name', anydbm)

    - The internal format of .sconsign files has been changed.  This might
      cause warnings about "ignoring corrupt .sconsign files" and rebuilds
      when you use SCons 0.96 for the first time in a tree that was
      previously built with SCons 0.95 or earlier.

    - The scan_check function that can be supplied to a custom Scanner now
      must take two arguments, the Node to be checked and a construction
      environment.  It previously only used the Node as an argument.

    - The internal Scanner.add_skey() method no longer works for the
      default scanners, which now use construction variables to hold their
      lists of suffixes.  If you had a custom Tool specification that was
      reaching into the internals in this way to add a suffix to one of
      the following scanner, you must now add the suffix to a construction
      environment through which you plan to call the scanner, as follows:

          CScan.add_skey('.x')       => env.Append(CPPSUFFIXES = ['.x'])
          DScan.add_skey('.x')       => env.Append(DSUFFIXES = ['.x'])
          FortranScan.add_skey('.x') => env.Append(FORTRANSUFFIXES = ['.x'])

    - The "node_factory" and "scanner" keyword arguments to the Builder()
      function have been removed.  In their place, the separate and more
      flexible "target_factory," "source_factory," "target_scanner" and
      "source scanner" keywords should be used instead.

    - SCons now treats file "extensions" that contain all digits (for
      example, "file.123") as part of the file basename, for easier
      handling of version numbers in the names of shared libraries
      and other files.  Builders will now add their file extensions to
      file names specified with all-digit extensions.  If you need to
      generate a file with an all-digit extension using a Builder that
      adds a file extension, you can preserve the previous behavior by
      wrapping the file name in a File() call.

    - The behavior of the env.Append() and env.Prepend() methods has
      changed when appending a string value to a UserList, or vice versa.
      They now behave like normal Python addition of a string to
      a UserList.  Given an initialization and an env.Append() call like:

          env = Environment(VAR1=UserList(['foo']), VAR2='foo')
          env.Append(VAR1='bar', VAR2=UserList(['bar'])

      The resulting values of $VAR1 and $VAR2 will now be ['foo', 'b',
      'a', 'r'] and ['f', 'o', 'o', 'bar'], respectively.  This is because
      Python UserList objects treat strings as sequences of letters when
      adding them to the value of the UserList.

      The old behavior of yielding $VAR1 and $VAR2 values of ['foo',
      'bar'] when either variable is a UserList object now requires that
      the string variables be enclosed in a list:

          env = Environment(VAR1=UserList(['foo']), VAR2=['foo'])
          env.Append(VAR1='bar', VAR2=UserList(['bar']))

      Note that the SCons behavior when appending to normal lists has
      *not* changed, and the behavior of all of the default values that
      SCons uses to initialize all construction variables has *not*
      changed.  This change *only* affects any cases where you explicitly
      use UserList objects to initialize or append to a variable.

  Please note the following planned, future changes:

    - Several internal variable names in SCons.Defaults for various
      pre-made default Scanner objects have been deprecated and will
      be removed in a future revision.  In their place are several new
      global variable names that are now part of the publicly-supported
      interface:

          NEW NAME              DEPRECATED NAME
          --------              ----------------------------
          CScanner              SCons.Defaults.CScan
          DSCanner              SCons.Defaults.DScan
          SourceFileScanner     SCons.Defaults.ObjSourceScan
          ProgramScanner        SCons.Defaults.ProgScan

      Of these, only ObjSourceScan was probably used at all, to add
      new mappings of file suffixes to other scanners for use by the
      Object() Builder.  This should now be done as follows:

          SourceFileScanner.add_scanner('.x', XScanner)

  SCons is developed with an extensive regression test suite, and a
  rigorous development methodology for continually improving that suite.
  Because of this, SCons is of sufficient quality that you can use it
  for real work.  The "beta" status of the release reflects that we
  still may change interfaces in future releases, which may require
  modifications to your SConscript files.  We strive to hold these
  changes to a minimum.

  Nevertheless, please heed the following disclaimers:

    - 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
      strive to respond to problems relatively quickly.

    - Documentation is spottier than we'd like.  You may need to dive
      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.

    - 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.

    - Error messages don't always exist where they'd be helpful.
      Please let us know about any errors you ran into that would
      have benefitted from a (more) descriptive message.

  KNOWN PROBLEMS IN THIS RELEASE:

    For a complete list of known problems, consult the SCons bug tracker
    page at SourceForge:

        http://sourceforge.net/tracker/?atid=398971&group_id=30337&func=browse

    - Support for parallel builds (-j) does not work on WIN32 systems
      prior to *official* Python release 2.2 (not 2.2 pre-releases).

      Prior to Python 2.2, there is a bug in Python's Win32
      implementation such that when a thread spawns an external command,
      it blocks all threads from running.  This breaks the SCons
      multithreading architecture used to support -j builds.

      We have included a patch file, os_spawnv_fix.diff, that you can
      use if you you want to fix your version of Python to support
      parallel builds in SCons.

    - 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.

    - On Win32 systems, you must put a space between the redirection
      characters < and >, and the specified files (or construction
      variable expansions):

        command < $SOURCE > $TARGET

      If you don't supply a space (for example, "<$SOURCE"), SCons will
      not recognize the redirection.

    - MSVC .res files are not rebuilt when icons change.

    - The -c option does not clean up .sconsign files or directories
      created as part of the build, and also does not clean up
      SideEffect files (for example, Visual Studio .pdb files).

    - Switching content signatures from "MD5" to "timestamp" and back
      again can cause unusual errors.  These errors can be cleared up by
      removing all .sconsign files.

    - When using multiple Repositories, changing the name of an include
      file can cause an old version of the file to be used.

    - There is currently no way to force use of a relative path (../*)
      for directories outside the top-level SConstruct file.

    - The Jar() Builder will, on its second or subsequent invocation,
      package up the .sconsign files that SCons uses to track signatures.
      You can work around this by using the SConsignFile() function
      to collect all of the .sconsign information into a single file
      outside of the directory being packaged by Jar().

    - SCons does not currently have a way to detect that an intermediate
      file has been corrupted from outside and should be rebuilt.

    - Unicode characters in path names do not work in all circumstances.

    - A stray source file in a BuildDir can prevent targets from being
      (re)built when they should.

    - SCons does not automatically rebuild LaTeX files when the file
      has an undefined reference on the first build.

    - Use of --implicit-cache with TargetSignatures('content') can,
      for some changes, not rebuild a file when necessary.

    - SCons does not currently automatically check out SConstruct or
      SConscript files from SCCS, RCS or BitKeeper.

    - No support yet for the following planned command-line options:

         -d -e -l --list-actions --list-derived --list-where
         -o --override -p -r -R -w --write-filenames
         -W --warn-undefined-variables



Thank you for your interest, and please let us know how we can help
improve SCons for your needs.

Steven Knight
knight at baldmt dot com
http://www.baldmt.com/~knight/

With plenty of help from the SCons Development team:
        Chad Austin
        Charles Crain
        Steve Leblanc
        Gary Oberbrunner
        Anthony Roach
        Greg Spencer
        Christoph Wiedemann

