==========================================
STL Error Message Decryptor for visual C++
          Quick Start Guide
==========================================

Written by  Leor Zolman
            leor@bdsoft.com
            www.bdsoft.com
Decryptor web page: www.bdsoft.com/tools/stlfilt.html

This document provides an overview of the Decryptor package and a
(relatively) quick path to getting it up and running. Much of what's
here was culled from other documents in the package.

What is it?
-----------

The purpose of the STL Error Decryptor is to shorten the length of VC++
STL-related error messages down to their bare essentials, so that the
most vital information from each message can fit within the visible
portion of the status bar line at the bottom of a Visual Studio IDE.

The IDE calls a program named CL.EXE to perform compilation. Filtering
is accomplished by renaming MSVC's "native" CL.EXE, and substituting a 
"Proxy" CL.EXE that the IDE finds instead. This Proxy CL invokes the
native CL, then filters its output via a Perl script to simplify the
error messages. The Visual Studio IDE then receives the output of this
filtering instead of the output of its own native CL.EXE program alone.

Note: Message filtering may be enabled/disabled either via a simple DOS batch
file (STLFilt.bat) or via the STLTask.EXE program. For these instructions,
I'll describe using STLTask.EXE first, because that is what I use 
personally and it is much more powerful than the batch file. Step 3 below
does tell how to configure the STLFilt.bat batch file, but you may
skip that step if you choose to use STLTask.

The remainder of this document explains:
    1) How to prepare your system for using the Decryptor components
    2) How to edit and place the configuration file
    3) How to configure and use the STLFilt.BAT batch file
    4) How to use the components
    5) How the components work

1. How to prepare your system:

    a.  Determine your MSVC installation's "bin" directory. For example,
        on my system I installed Visual C++ into E:\VC98. Therefore,
        my system's "bin" directory path is: E:\VC98\bin. For the rest
        of this document, I'll refer to this directory as CL_DIR. 

    b.  Install Perl (ActiveState seems to work best; get it at
        www.activestate.com).

    c.  Make a backup copy of the native CL.EXE file in your CL_DIR 
        directory, and put it somewhere for safekeeping. With any luck, 
        you'll never actually need it ;-)

    d.  Rename the native CL.EXE file in your CL_DIR directory to CL2.EXE.


2. How to edit the configuration file, and where to put it:

    a.  Edit the Proxy CL configuration file, Proxy-CL.INI, setting any of
        the following four options for which the default values are not
        correct for your system. (Note: All configuration options supported
        by Proxy-CL.INI have default values, even if they are not set in the
        file at all. The comments at the top of the file show these default
        values. For any of those defaults are OK for your system, you don't
        need to give the corresponding options any value.)

            FILTER_SCRIPT:    Full pathname of STLFilt.pl, from this
                              distribution (the default value is C:\STLFilt.pl;
                              for that to work, copy STLFilt.pl into the 
                              C:\ directory.)

            TOGGLE_FILE_DIR:  Directory where the filtering control toggle file
                              is to reside. Note that the file may not exist
                              yet. You can specify its location as in the 
                              directory where you unzipped the stlfilt.zip 
                              archive, or just let it default to the C:\ 
                              directory.

            PERL_EXE:         Full pathname of your Perl interpreter (for
                              ActiveState, the default is C:\perl\bin\perl.exe)

            CL_DIR:           MSVC's bin directory. Defaults to:
                              c:\program files\microsoft visual studio\vc98\bin


        There are other options in the file, but having these four set
        correctly is the bare minimum. The Proxy-CL.INI file's comments
        list all the available options, and the values they get set to
        "by default" (meaning, again, if you omit them altogether,
        CL.EXE or STLTask.EXE set them internally to the values shown in
        the comments).

        For example, here the settings in my own personal Proxy-CL.INI file:

            [common]
            FILTER_SCRIPT=d:\src\cl\STLFilt.pl
            TOGGLE_FILE_DIR=d:\src\cl
            PERL_EXE=e:\perl\bin\perl.exe

            [proxy.cl]
            DEBUG=false
            DEBUG_DIR=d:\src\cl

            [stltask.exe]
            CL_DIR=e:\vc98\bin

    b.  Copy the Proxy-CL.INI file into your system Windows directory (e.g.,
        C:\Windows or C:\WINNT, etc.)

    c.  Be SURE you've completed step 1b above, then copy the Proxy CL.EXE 
        into CL_DIR.

    d.  Copy STLTask.EXE into a directory somewhere along your system PATH
        for executable files.


3. How to configure and use the STLFilt.BAT batch file to control filtering
   (If you'll be using STLTask to control filtering, this step is OPTIONAL)

    Some folks prefer to use the "low-bandwidth" solution for turning STL
    filtering on and off. This may be done via a simple batch file, STLFilt.bat,
    as follows:

    1.  Modify the TOGGLE_BASE variable in STLFilt.BAT to show the base name
        (the full pathname *without* the extension) of the toggle control file
        used by the Proxy CL (set to C:\FILTERING as distributed)

    2.  Place STLFilt.BAT somewhere along your system PATH.

    3.  To enable filtering, say this from the command line:
            stlfilt on
        To disable filtering, say:
            stlfilt off


4. How to use the components

    Now that you've installed everything, using the software should be a 
    piece of cake. 

    Start by executing STLTask.EXE. The first time it comes up, you may
    notice a message saying that it is copying files, such as CL.EXE to CL.STL.
    This is normal; it is saving the Proxy CL image in CL_DIR as CL.STL so it
    can later be copied back to CL.EXE when necessary. By default, filtering 
    will be "Off" (since you've never turned it on yet). To turn on STL 
    filtering, right-click on the STLTask icon (on the taskbar) and click on 
    the "Enable filtering" item. You'll see the new status, and it should 
    say "Filtering is ON".

    Now go into Visual Studio and find some STL-related program, create a 
    bug in an STL-related line of code, and compare the error messages with
    filtering Enabled / Disabled. You're off and running.

    To have STLTask.EXE start up automatically every time you boot up or log
    in to Windows, place a shortcut to STLTask.EXE in your Startup folder and
    edit the "target" in the shortcut properties to include the /q option as
    follows (where the "..." is the path STLTask.exe resides in):

        ...\STLTask.exe /q

    Note that STLTask.exe also accepts a filename as a command line argument;
    if present, the named files is used to read configuration information
    instead of the default Proxy-CL.INI file in the Windows directory.


    Command Line Operation

    The Proxy CL works both from the command line, or from within Visual
    Studio, since Visual Studio will invoke it for all sorts of things.

    To compile from the command line without error filtering, either 
    use CL2.EXE (the stock CL.EXE) directly, or signal the Proxy CL to
    disable filtering either by issuing this command on the command line:
            stlfilt off
    or selecting the STLTask.EXE menu choice "Disable filtering".

    To enable filtering, either issue
            stlfilt on
    from the command line, or select "Enable filtering" via STLTask.EXE.


    ****WARNING****
    If you ever update or re-install MSVC over your existing
    installation, make sure there is no "CL2.EXE" file in CL_DIR
    before you begin the MSVC installation. Otherwise, the next time 
    STLTask starts up it will copy the existing CL2.EXE on top of the 
    (perhaps) new CL.EXE, with possibly disastrous results. STLTask's 
    "Prepare to apply Visual Studio service pack" command will
    prevent this problem by doing what its name implies.


How does it work?
-----------------

When installed, 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 (default name: FILTERING.ON). If the toggle file is 
*not* detected, the Proxy CL simply invokes the renamed native CL.EXE (default
name: CL2.EXE) with the same command arguments it was itself invoked with. This
yields ordinary (unfiltered) error messages.

If the toggle file *is* detected AND the file type being compiled qualifies
for filtering (basically, if it is a C++ source file), then the Proxy CL sets
up an interprocess pipe between the CL2.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*
determines whether CL continues on to later phases of the build process, such
as linking.

The Perl script supports one runtime option, /iter:x, where x may be one of
the letters 'S', 'M' or 'L' (case insensitive), signifying a  "Small", 
"Medium" or "Large" amount of detail to retain within the iterator type expansions.

If the /iter:x option is detected on the CL command line, it is passed
directly on to the Perl interpreter and not seen by the native CL.  The default
iterator policy setting is 'M'; if you want more details on iterator types to
appear in your messages, add "/iter:L" to your compiler option settings in your
IDE project files, makefiles or manual command line compiles.


That's it!
----------


If you found any part of this quick start guide to be in error or just
plain confusing, please let me know so that I can improve it. Most of
the best ideas reflected in this entire package came from users like
you; all I did was code 'em up and debug 'em...
    
Now go back and read all the way through GLOSSARY.txt and README.txt,
because there are additional details in there worth knowing.

Also, check all the README*.txt files for supplementary information
that may be present pertaining to the specific library you'll be using.


        -Leor Zolman
         8/29/2001
