======================================================
BD Software STL Error Message Decryptor for Visual C++
                 Quick Start Guide
                 (Updated 4/05/03)
======================================================

Written by  Leor Zolman      leor@bdsoft.com
            BD Software      www.bdsoft.com

Decryptor web page:          www.bdsoft.com/tools/stlfilt.html
STLFilt Yahoo Group:         http://groups.yahoo.com/group/stlfilt

This document provides an overview of the Decryptor package and a
(relatively) quick path to getting it up and running.

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 is immediately visible. When
using the MSVC IDE, this results in messages usually fitting in their
entirety within the visible portion of the status bar (that line of
really tiny text at the bottom of the IDE). Since before filtering the
messages are really cryptic (due to their being so laden with non-
critical detail), I coined the term "Error Decryption" to describe the
filtering process, and collectively the software package then became
the "Decryptor".

A second benefit is the option to wrap very long typenames (the kind
typically appearing within error messages from template metaprogramming
applications) in strategic places, and do a bit of reformatting to
align the results in a helpful manner. See the /break, /cbreak, /meta
and /closewrap options documented in the Perl script for more info.

The MSVC IDE calls a program named CL.EXE to perform compilation. In the
full-blown installation, filtering is accomplished by renaming MSVC's
"native" CL.EXE, and then substituting a "Proxy" CL.EXE that the IDE finds
instead. This Proxy CL invokes the (renamed) native CL, then filters its
output via a Perl script to simplify the error messages. The Visual Studio
IDE then receives this filtered output and displays it in the output
window.

[Note: There are also several "non-invasive" ways to use the Perl script
without the help of the Proxy CL. One is to run a simple batch file
driver, such as the supplied MFilt.BAT, directly from the command line.
Another is to employ the MSVC Tools-based technique described in the file
README-VCTool.txt. These techniques have the benefit of not requiring you
to muck around with your MSVC installation's executable files, but they may
cost you a bit of flexibility.]

Since CL.EXE is also the MSVC's command-line compiler driver, the benefit
of STL message Decryption is also available during interactive, or even
project-file/makefile-based, invocations of the compiler. In short, anything
you can do with the "native" CL.EXE, you can do with the "Proxy" CL.EXE,
but the latter also gives you sane error messages.

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 (especially
since a single instance of STLTask now supports multiple compiler platforms
simultaneously). 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 for
controlling Decryption.

==========================================================================
Q: Why isn't there a nice, simple-to-use SETUP.EXE facility for this tool?

A: I'm not confident enough with "setup" utilities to make certain that
one I provide doesn't have the potential to scramble the guts of
your computer. If you do the installation manually, that absolutely
guarantees you'll have the ability to UN-do what you've done if you want,
no fancy uninstaller tools required. If you are a practicing or aspiring
software developer, you probably won't find these direction overly comp-
licated. If you're NOT, you probably wouldn't be here trying to install
a package for filtering STL-related C++ error messages in the first place.
==========================================================================


Trivial Command Line Usage
--------------------------

Instead of installing the Proxy CL, the least invasive way to use the
Decryptor is to work from the DOS Prompt: manually pipe the output of
CL.EXE to a Perl process with the appropriate command line args. For
example (using MSVC6):

    cl program.cpp | perl STLFilt.pl 
Under MSVC7:
    cl /WL program.cpp | perl STLFilt.pl

A batch file, MFilt.BAT, is included as a simple example of automating
this approach. It also illustrates some of the Perl script options that
are most helpful when driving the Decryptor directly from the command line.

As mentioned above, README-VCTool.txt describes a way to enable you to
invoke Decryption from within the VC++ IDE on demand without requiring the
Proxy CL installation. That may be the best way to go for some users
(depending upon circumstances such as having freedom/desire to mess with
MSVC's system files.)


Installation
------------

The remainder of this document explains how to do a full-blown installation
of the Proxy CL and related tools, specifically:

    1) How to prepare your system for using the Decryptor components
    2) How to configure (and where to put) the Proxy-CL.INI 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 (ActivePerl seems to work best; get it for free
        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.
        (Note: If you've run STLTask.EXE prior to this, then STLTask.EXE
        may already have renamed this file for you *if* your MSVC is in-
        stalled in its default location.)

2. How to edit the primary configuration file, Proxy-CL.INI, and where to
   put it:

    a.  All configuration options customizable via Proxy-CL.INI have default
        values hardwired into CL.EXE and/or STLTask.EXE. The commented config
        lines in Proxy-CL.INI show these default values. To set a different
        value, remove the *leading* semicolon (;) and set the desired value.

        If the default value for an option is already correct, there's no need
        to create an active line for that option.

        The four most important options are:

            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 might not exist
                              yet. You can specify its location as being the 
                              directory into which 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. E.g., MSVC6 defaults to:
                              c:\program files\microsoft visual studio\vc98\bin


        There are other options supported by the file, but having these four
        set correctly is the minimum necessary for getting the Decryptor going.

        E.g., here are the settings from 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
            OUTPUT_WIDTH=94

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

    b.  Copy the Proxy-CL.INI file into your TOP-LEVEL WINDOWS INSTALLATION
        DIRECTORY (typically C:\WINDOWS or C:\WINNT, or the value of
        "%systemroot%" under later versions of Windows).

    c.  Be SURE you've completed step 1c 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. You may find it useful to create a shortcut
        to it on your desktop, and/or create a shortcut to it in your
        system's "Startup" folder (see item 4. below for details).

    e.  To take advantage of STLTask's new multi-platform features, you'll
        also want to tailor and copy the STLTask.INI file into the same
        directory as Proxy-CL.INI. See README-STLTask.txt for details on
        multi-platform configuration. Don't do this, however, until you've
        gotten everything running correctly in single-platform mode.