readme.txt

STLstlfilt.zip

the following URL:
    http://www.cuj.com/articles/2001/0107/0107b/0107b.htm?topic=articles

Several substantive changes made to the software since the CUJ article was
frozen for publication render portions of the article out-of-date. They are:

    1. The iterator policy setting in STLFilt.pl was changed from a numeric
        value (1, 2 or 3) to a symbolic value (S, M or L). The original '1'
        setting corresponds to the new 'L' ("Long" or "Large" expansion), and
        the original '3' corresponds to the new 'S' ("Small" or "Short"
        expansion).  The new 'M' means, of course, "Medium" expansion. (Thanks
        to Scott Meyers for suggesting the use of symbolic, rather than
        numeric, designations.)
    2. The STLTask taskbar-based utility was added as a GUI-based alternative
        to the STLFilt.BAT batch file
    3. STLport and VC7/.NET library support has been added to STLFilt.pl.
        The same Perl script now works with all four libraries.
    4. Hash-based containers are now supported (for all libraries that have
        them, anyway...i.e., all libraries *except* native VC6)
    5. The "fine-print status line" I mention in the article actually has a
        name, as I finally learned: the "status bar", and it is turned on and 
        off within Visual Studio via the Tools...Options...Workspace
        checkbox labeled "Display status bar". I recommend you leave it turned
        on; most of the time, this will alleviate the need to scroll the output
        window.
    6. The installation instructions in the article say to place the Proxy
        CL.EXE "somewhere along your system PATH". Beginning with v2.1 of
        CL.CPP (and v2.0 of STLTask), the Proxy CL should be placed directly
        into MSVC's bin directory (...\VC98\bin or ...\VC7\bin).
        See QUICKSTART.txt for the current installation procedure.
    7.  Precompiled versions of both CL.EXE and STLTask.EXE are now included 
        in the distribution. Both programs read configuration information at 
        startup from a config file (Proxy-CL.INI) placed into the Windows
        directory. If the config file is not present, then all options default
        to values configured in the source code and compiled into the programs.
        

================
Bugs/Limitations
================

Perl script:

==> Of the various Perl implementations out there, ActiveState seems to work
    the best. I've had several reports of interprocess bugs when using the
    filter in conjunction with other Perls, such as MKS and Cygwin.
    Therefore, if you experience strange errors involving zombie Perl
    processes and such, first try installing and using ActiveState Perl for
    filtering. You should then still be able to use your *other* Perl(s) for
    whatever else you've been using them for.

==> There are still several kinds of errors that do not get filtered very
    well, including some string-related ones (see tstring.cpp in the
    samples.zip archive, for example) and others relating to some helper
    templates used within the internals of various libraries. 

Proxy compiler:

==> When the Proxy CL.EXE is linked with setargv.obj for support of automatic
    wild-card expansion, the command:

        cl /?   (with or without the space)

    will fail if the root directory of your current drive contains any 
    entries having a name exactly one character in length. Unfortunately,
    setargv.obj does not seem to recognize the slash as an option delimiter,
    and treats the sequence the same as it would "\?".

    Workaround: use /help instead of /? whenever you get a bunch of "illegal
    option" diagnostics while using cl/? .

==> Support for indirect (@filename) command lines is limited to fairly
    typical cases; The proxy CL, when detecting @filename as the *only* 
    argument on the command line, opens the indirect file and looks at only
    the *last* item on the *last* line of it. Filtering is performed only if
    this item has an acceptable C++ extension (one of the entries in the
    filterExt array of strings). That name may have quotation marks around
    it. Thus, indirect command files with more than one line's worth of
    source file names (or when the source file is not the last thing on
    the last line) may behave incorrectly if there is a mixture of
    filtering-enabled and non-filtering-enabled extensions. So far, no one
    has reported to me any VC-generated projects that my scheme fails to
    properly process, but that doesn't necessarily mean it isn't going to
    happen...please let me know if you run across any projects that trip up
    the Proxy CL, and I'll do my best to fix any such issues brought to my
    attention.

    When the first command line arg to CL is *not* an indirect "@" filename,
    then it scans argv right-to-left looking for the first argument that is
    neither a filename with an object file extension (one of the strings
    in the objExt array) nor a string with no extension at all (assumes those
    are options). The decision whether to filter or not is made based on the
    first argument (working from right to left) that *isn't* one of those
    things.

==> Command lines containing escaped double-quotes, as in /D definitions,
    probably won't be handled correctly by CL. It now handles all '"' char-
    acters by prepending a backslash to them. Going further, so as to
    handle quoting of arbitrary complexity such as:
        ... /DHAIRY="Here's a double quote: \" and a backslash: \\"
    would require a full-blown state-driven parser here to handle *all* the
    permutations...for now, anyway, the only way to compile such lines is
    to uninstall the filter (a matter of just a few clicks with STLTask).

When any of the above issues arise and you wish to revert to standard
error messages, the easiest thing to do is use STLTask to uninstall the
proxy CL until you need filtering again. Then use STLTask to install
again. 

If you have problems relating to the project file issues described above,
you might try doing a "compile only" from Visual Studio, with filtering
enabled, instead of building a project.

==================
Debugging Features
==================

CL.CPP and STLTask.EXE have debugging features built-in. CL.CPP supports
runtime debug configuration: set the DEBUG configuration option to true 
to log status messages to a file named CL-dblog.txt in the directory 
configured by the DEBUG_DIR option. For project files, when debugging is
enabled CL.EXE will also make a copy of the temporary project file named
"atfile.txt" and place it into the DEBUG_DIR directory. This may help 
to determine why CL fails to properly handle a project build.

The Proxy CL option LOG_NATIVE_MSGS may be set (via the configuration file
Proxy-CL.INI only) to force the Perl script to log its complete, UN-filtered 
input to a file named NativeLog.txt in the current directory. Sending
me a copy of this file can help me debug the Perl script when issues arise
relating to the filtering algorithm.

STLTask.cpp debugging must be configured at compile time. Set the DEBUG 
symbol to 1 and define the DEBUG_DIR symbol to the name of your
desired log file directory, and STLTask will log various status info to
a file named "debug.out" in that directory.

If you run into a situation where the Proxy CL fails, please let
me know so I can fix it. If you understand the problem and can describe the
circumstances, that's great...if not, I'd be glad to help figure out the
problem and hopefully fix CL for the future; please reduce the project to
the minimum possible configuration that results in CL failure, zip it up
and email it to me ([e-mail]). I'll do my best to determine the 
problem and correct it. This program is as reliable as it is now *only*
because folks like you informed me about the problems (and even fixed them
for me on many occasions!)

===============
Acknowledgments
===============


Thanks to:

Scott Meyers for putting on his "Effective STL" seminar -- the event that
    inspired this project. 

David Smallberg for Proxy CL idea, allowing seamless integration into MSVC

Thomas Becker for writing the Win32 interprocess communication code in CL.CPP
    and STLFilt.pl

David Abrahams for contributing the long-typename-wrapping algorithm and 
assisting me in the debugging/evolving of it.

The other folks who took the time to email me with bugs and suggestions, and/or
helped with debugging:

    Thomas Becker
    Wilka
    Sam Saariste
    Scott Lewandowski
    Scott Meyers
    Tom Malcolmson
    Jan Stette
    Dominic Mathieu
    Michael Cook
    Andy Philpotts
    Rob Bishop
    John Hattan
    Derek Price
    Bill Torpey
    John Penney
    Jonathan Sambrook 
    Argos
    Matthew Douglass
    Dave Conrad
    Scott McCaskill
    Paul Suggs
    Karl Lean
    Benoit Goudreault-Emond
    Michael Griggs
    Marco Welti
    Ed Kaulakis
    Alex Pirseyedi
    Graeme Prentice
    Larry Evans
    Karl Bouchard

=======
Courses
=======

"Programming is not a commodity" (at least not in my book).

To promote excellence in software development technology, BD Software
offers the following on-site, hands-on seminars for programmers:


==> C++ for non-C Programmers
                   Very intensive, 5-day workshop teaching C++ for those who
                   have never programmed in C. Seminar by me, based on
                   the Stephen Prata textbook "C++ Primer Plus" (4th edition).
                   Prerequisite: *SOME* programming experience, but it
                        doesn't matter in what language.

==> An Effective Introduction to the Standard Template Library (STL)
                   Course by Scott Meyers, who needs no introduction.
                   Teaches the STL to experienced C++ programmers. 4 Days.
                   Prerequisite: Real-world programming experience in C++. 

==> C++ and Object-Oriented Programming
                   5-Day course by Dan Saks, another C++ guru you probably
                   know about.
                   Teaches C++ assuming GOOD (working) knowledge of C. More in
                   depth on OO and C++ subtleties than the first course above.

==> Introduction to Programming in C
                   My own C programming course. Some programming experience
                   (not necessarily in C) is the only prerequisite.
                   4 or 5 days; 5 preferred.
                   What can I say? Not too many folks are still learning
                   "just" C anymore, but if you have two weeks available to
                   learn C++ in, it works out a lot better to take C first and
                   then the C++ and OOP course above than it does to cram
                   both C and C++ into one week. That is, at least until
                   I write a course based on the STL-first approach...

==> Object-Oriented Programming in Java
                   My (I'm co-author) Java course. Does NOT presume any C/C++
                   experience. Uses all public domain / shareware tools (Sun's
                   JDK, ModelWorks' JPadPro (awesome IDE!). 5 Days.
                   Everyone gets a CD full of Java goodies.
                   Again, presumes only some programming experience in SOME
                   language.

==> Introduction to Unix (2-3 days)
==> Korn Shell Programming (3 days)
==> Perl Programming (3 days)

                    I license materials for the three Unix courses above 
                    from a fellow instructor. Good, solid courses, all of 'em.
                    The Perl course is mostly platform-independent, but
                    includes some Unix-specific functionality.



To give feedback on this package, or get additional information on having one
of the courses listed above delivered at your site, please contact:

    Leor Zolman
    BD Software
    74 Marblehead Street
    North Reading, MA 01864-1527
    voice/FAX: [phone]
    email: [e-mail]
    web: www.bdsoft.com

===============================================================================