readme.txt

STLstlfilt.zip

===============================================================================
       BD Software STL Error Message Decryptor for Microsoft Visual C++

    Versions for Comeau C++, Intel C++, gcc 2/3, Borland 5.5.1, Metrowerks
CodeWarrior 7/8 and EDG are also available at www.bdsoft.com/tools/stlfilt.html
                        Copyright 2002-2004  Leor Zolman
===============================================================================

STLFilt.pl (the Perl script):       Release 2.70  (12/23/2003)
CL.CPP (The Proxy CL.EXE):          Release 2.42a (01/15/2004)
STLTask Taskbar Icon Controller:    Release 3.05  (05/06/2003)

Written by  Leor Zolman ([e-mail])
            BD Software
            www.bdsoft.com
                             
   BD Software offers on-site, hands-on programming seminars in
   introductory C/C++, Java, Unix and Perl. You can find  more
   course information at the end of this document, and full course
   descriptions at wwww.bdsoft.com.

See QUICKSTART.txt for a brief overview and quick setup instructions.

 ****************************************************************************
 * Please do not redistribute any part of this package directly; rather,    *
 * to ensure folks get the latest version, please direct anyone interested  *
 * to download the latest stlfilt.zip directly from its web page:           *
 *                                                                          *
 *      www.bdsoft.com/tools/stlfilt.html                                   *
 *                                                                          *
 ****************************************************************************

This package is updated frequently; check the web page for the date of the
latest posting, and click on the version numbers in the component table
to see reverse-chronological revision logs for CL/STLFilt.pl and STLTask.

 ****************************************************************************
 *  To participate in a forum with other filter users, join the new STLFilt *
 *  Yahoo Group at:                                                         *
 *                http://groups.yahoo.com/group/stlfilt                     *
 ****************************************************************************

======================
What's in this archive
======================

README.txt:     You're reading it: purpose, bugs/limitations, manifest, 
                acknowledgments and shameless self-promotion are all to 
                be found here.

GLOSSARY.txt:   Definition of terms used in this software and documentation.

QUICKSTART.txt: Fast track setup instructions, for the impatient. Contains
                just the essential instructions necessary to put the Decryptor
                into service quickly.

README-VCTool.txt:
                A technique to integrate on-demand STL Error Decryption into
                the VC++ IDE without requiring installation of the Proxy CL.

README-STLTask.txt:
                Supplementary documentation on using the STLTask.EXE program.

README-hashed-containers.txt:
                Supplementary documentation on hash-based container support.

README-VC7.txt: Supplementary VC7/Visual Studio.NET notes.

CL.EXE:         The CL-spoofing proxy compiler. Replaces the stock CL.EXE
                during Visual Studio compilations, and invokes it indirectly.

STLTask.EXE:    Taskbar-based Proxy CL control utility.
                STLTask controls Proxy CL installation/uninstallation, filter
                toggling, clipboard filtering and preparation for applying a 
                Visual Studio Service Pack.
                STLTask provides an alternative to STLFilt.BAT to toggle the
                filter control file. The installation/uninstallation feature
                of STLTask is provided for situations where the Proxy CL does 
                not work correctly, e.g., complex projects, projects built
                with certain third-party tools, projects having a 
                mixture of C++ and non-C++ (idl/odl?) targets on the 
                same command line, etc. The "Uninstall" feature makes it 
                easy to suspend use of the Proxy CL during these types of
                builds, then bring it back for later work by selecting
                "Install".
                Latest feature: The STLTask tray icon automatically reflects
                the current status of the filtering toggle file--even when the
                toggle file is renamed using only the STLFilt.BAT batch file!

PROXY-CL.INI:   Primary configuration file for use with CL.EXE and STLTask.EXE.
                Edit this file as appropriate for your system (remember to
                remove the leading semicolons of lines you wish to be
                active!!), place it in the Windows directory (C:\Windows or
                C:\Winnt, etc.) and your settings will override defaults built
                into CL.EXE and STLTask.EXE.

STLTask.INI:    Secondary (optional) configuration file for activating
                STLTask's new simultaneous multi-platform support capability.

STLFilt.pl:     The Perl script.

STLFilt.BAT:    Low-bandwidth batch file utility to toggle the filtering
                control file. Say
                    stlfilt on
                or
                    stlfilt off
                to control filtering. Most useful when working from within
                Visual Studio (you can run STLFilt.BAT from a DOS window, or
                install options to invoke it directly into the VC++ "Tools"
                menu) or using makefiles. When compiling directly from the 
                command line, just choose between running CL or CL2 (CL2.EXE
                is the recommended name for the copy of the native CL.EXE).

                The Proxy CL's "/NF" option may also be used to force
                "no filtering" during an individual compile.

                Note: STLFilt.BAT and STLTask.EXE cooperate, and may be run
                interchangeably to enable/disable Proxy CL filtering.

MFilt.BAT:      Simple command-line compiler/Decryptor driver, if you'd prefer
                not to install the Proxy CL and just drive the Decryptor
                manually on demand from the command line.

MFiltTool.BAT:  Batch file for use with the MSVC "Tool" technique described
                the file README-VCTool.txt above.

CL.cpp:         Source to the Proxy CL program.

STLTask-src.zip:
                Source code to the STLTask utility. Installation of the
                wxWindows library is required to rebuild STLTask.EXE.

CUSTOMIZE.txt:  Instructions for rebuilding CL.EXE and STLTask.EXE from
                their source code, and for using the STLFilt.bat batch file
                for enabling/disabling filtering.

Samples.zip:    A slew of CPP files that draw various STL-related errors.
                Try 'em with and without the filter!

CL-log.txt:     Revision log for CL.cpp and STLFilt.pl

STLTASK-log.txt:
                Revision log for STLTask.cpp
                
README-STLport.txt:
                Some notes regarding STLport-specific filtering issues
                in the Perl script

=======
Purpose
=======

The idea is to shorten the length of VC++ STL-related error messages
so that the most vital information from a message fits within
the visible portion of the status bar line at the bottom of the Visual
Studio IDE (see item "5." in the section below entitled "The CUJ Article"
for instructions on enabling the status bar).

Lots of things you don't usually need to see are deleted, e.g.:

    --> The qualifiers "std::", "class", "struct", "__thiscall" and
        "__cdecl" disappear
    --> Iterators are radically shortened to either just "IT", "iter", or,
        for a container "cont", "cont::iter" (you pick which form to use).
        You can then typically deduce the type details from the remaining
        context of error messages
    --> Any functors of the form less<whatever> are deleted; others are left
        intact. Thus the default "less<...>" functors don't clutter the
        messages when dealing with associative containers
    --> strings, istreams and ostreams of <char>, their traits, etc. reduce
        to just "string", "istream", "ostream", etc. Ahhh!
    --> iostream iterators are recognized and abbreviated
    --> Allocators in type names totally disappear, and allocators in function
        parameter lists reduce to just "alloc" (good riddance...)
    --> Those obnoxious C4786 warnings ("identifiers truncated to 255 
        characters"), along with subsequent messages relating to those
        warnings, become history
 
Currently, all standard and hash-based containers have been addressed,
for the distribution version of the VC++6 library, version 3.08 of the
Dinkumware library, STLport 4.x *AND* Visual C++ 7 ("Visual Studio.NET").

There are certainly cases I'll have overlooked, and some I just don't know
how to filter. Feedback is welcome, but here's the disclaimer:

        The reason I wrote this was to make it possible to teach
        C++ using the STL-first approach without scaring away students
        due to outlandishly complicated STL error messages. Thus, the filter
        address messages resulting from the *most common* coding errors (wrong
        number of arguments, wrong argument type, etc.) in standard container
        operations involving most everyday data types. STL power users
        are always free to disable filtering to track down errors where the
        deleted detail needs to be seen, and then re-enable filtering when such
        detail is no longer needed. Two methods are provided to enable/disable
        filtering:
            1) The STLFilt.BAT file (low-bandwidth, and calls to it can easily
               be wired into the IDE's Tools menu)
            2) the STLTask tray icon program is convenient to use, allows
                instantaneous installation/uninstallation/reinstallation of
                the Proxy CL at any time, and provides a facility to filter
                system clipboard contents on-the-fly at any time
 
============
How it Works
============

1. Nuts and Bolts

When installed/active, the Proxy CL is found by the MSVC IDE and invoked as if
it were the native CL.EXE program. The Proxy CL checks for the existence of the
controlling toggle file (FILTERING.ON). If the toggle file is *not* detected,
the Proxy CL simply invokes the native CL.EXE (usually renamed to CL2.EXE) with
the same command arguments it was itself invoked with. This yields ordinary,
unfiltered error message output.

If the toggle file *is* detected AND the file type being compiled qualifies
for filtering (see the fourth item in the Bugs/Limitations section below for
details on how the Proxy CL makes this determination), then the Proxy CL sets 
up an interprocess pipe between the native CL.EXE and an invocation of Perl.
The native CL's output stream is then piped into the standard input of the
Perl process executing the STLFilt.pl script, to simplify STL-related 
messages. The output of the Perl script is then captured by the MSVC IDE 
and displayed in its output area, while the process status code of the *native*
CL process controls the subsequent behavior of the IDE's build sequence.


2. Rationale

While the command-line processing that the Proxy CL has to perform is a bit on
the tricky side, it seems to now handle most MSVC-generated build scripts
satisfactorily (the exception possibly being third-party-based builds, such as
when using tools such as TrueTime). The main benefit of the toggle file scheme
I'm using for enabling/disabling filtering is that it does not require constant
file renaming--my theory is that if major EXE files are constantly having to be
renamed, that is asking for trouble.

In the early days of the filter there were several persistent bugs in
the processing of MSVC-generated build scripts, so I did give STLTask (the 
taskbar utility) the power to install/uninstall the filter (see the description
of Active/Inactive in GLOSSARY.txt) to make it easier to run native 
builds unencumbered by Proxy CL bugs...or just run massive builds faster via
bypassing the Proxy CL completely. This installation/uninstallation copies
either the Proxy CL (CL.STL) or the native CL (CL2.EXE) over CL.EXE.
Because of the possibility of crashes etc. in the middle of such operations, 
STLTask tries *real hard* to make sure the files remain in a consistent state. 
If there is any doubt as to the current status of the filter (installed or not 
installed?) upon startup, STLTask resets everything to the native MSVC 
configuration (Proxy CL uninstalled) by default.


3. Configurability

One programmer's essential details are another programmer's noise; I've put a
lot of effort into allowing users to "roll their own" feature set for the
Decryption process. Be sure to carefully examine the entire "User-Configurable
Options" section near the top of the Perl script, STLFilt.pl, to see what
your options are. Many of those options may be controlled via the primary 
configuration file (Proxy-CL.INI) and command-line options to either the
Proxy CL, the Perl script itself, or both. Note that some options can only
be changed by tailoring the Perl script's "user-configurable settings" 
directly.


===============
The CUJ Article
===============

For background information on the origins and philosophy of the Decryptor,
see my article in the July, 2001 issue of The C/C++ Users Journal.
The article was the Web Feature for July, 2001--that means it is now
and forever available for viewing in its entirety on the CUJ web site, at