readme-vctool.txt

STLstlfilt.zip

       ------------------------------------------------------
       MSVC Tools-Based, Non-Invasive STLFilt IDE Integration
       ------------------------------------------------------

                   Leor Zolman & Alex Pirseyedi
                              4/12/2003
                        (Updated 12/11/2003)

This document describes a nice way to integrate STL Error Decryption
capability to the MSVC 6/7 IDE *without* having to install the "Proxy
CL".  This technique was pointed out by Alex Pirseyedi, and much of
the text in this document has been taken directly from his emails
describing the configuration.


The idea is to use an MSVC project's "Build Log" along with the "Tools"
feature of MSVC. Here's how to set it up:

0.  MSVC6: Under Tools|Options|Build, make sure the checkbox next to

        Write Build Log (.plg)

    is checked.

    MSVC7: That option is under Tools|Options, Projects|VC++ Build.
    Make sure "Build Logging" is set to "yes".

1.  Create a batch file to invoke STLFilt.pl (version 2.44 or higher for
    VC6, version 2.45 or higher for VC7) on a pathname provided as its
    command-line argument, doing essentially the following (with [path...]
    replaced according to the location of STLFilt.pl on your system):

        @echo off
        if "%1" == "" goto usage
        perl /plg [path...]\STLFilt.pl < %1
        goto end
        :usage
        echo Usage: %0 MSVC_BuildLog_filename.plg
        :end

    MFiltTool.BAT (adapted from the original MFilt.BAT utility script)
    is provided as a fully functional example. The key is to provide the
    /plg option to STLFilt.pl, so that it knows the input is in .PLG
    format (this option will work for both VC6 and VC7 log files, even
    though the files no longer have the ".PLG" extension under VC7)


2.  MSVC6: Under Tools|Customize|Tools, add a new tool named "STLFilt"
    and configure its parameters as follows:

        2.1. Command: [path_to...]\MFiltTool.bat
        2.2. Argument: $(WkspDir)\$(WkspName).plg
        2.3. check the 'Use Output Window' option


    Alex's explanation of line 2.2 above:

    "This should now work for any project. What's really interesting is that
    what Microsoft calls a "Workspace Directory" (WkspDir) seems to be (very
    conveniently for us!)  the "Project" directory! (same thing for the name).
    I personally keep my workspace files (DSW files) in a separate directory
    than my projects, and that's how I spotted this. Microsoft's MFC wizards
    put everything into the same directory and that's probably when they
    introduced this bug! These should have been really called "Project
    Directory" (PrjDir) and "Project Name" (PrjName) instead."


    MSVC7: Under Tools|External Tools, add a new tool named "STLFilt" and
    configure it as follows:

        2.0. Title:   STLFilt
        2.1. Command: [path_to...]\MFiltTool.bat  
        2.2. Arguments: buildlog.htm
        2.3. Initial Directory: $(TargetDir)
        2.3. check the 'Use Output Window' option


3.  You can bring the tool out as a toolbar item using the usual
    Tools|Customize|Commands etc.

    MSVC6: What I did--and there may be a slicker way, but I don't use the 
    Tools feature much--was to move the STLFilt Tool up to the top of the
    tools list, and then drag the "Tool #1" icon up to the place I wanted
    it in the button bar.

    MSVC7: Tools|Customize, choose the "Commands" Tab, choose "Tools" in the
    "Categories" pane on the left, then in the "Commands" pane scroll down to
    "External Command 1". If you drag that up to the button bar, its caption
    will automatically turn into "STLFilt".

4.  Now every time you invoke the tool, the .PLG/.HTM file is STLFilt-ed and
    the output is shown in the MSVC output window. Thus, you don't pay for the
    overhead of using STLFilt unless you want to. If a regular compilation
    produces errors you want STLFilt-ed, the new Tool invokes Perl directly
    on the error log and does not require recompilation of the source file.


The Algorithm is Evolving
-------------------------

The original algorithm (as released 4/2003) was based on a limited sample of .PLG
files, and some inadequacies were recently brought to light. Based on some very
helpful suggestions from Karl Bouchard, the current algorithm for special processing 
of PLG files goes like this:

    1. Everything between lines beginning with '[' and subsequent lines beginning
       with ']' (inclusive) is discarded (these are typically showing the contents
       of batch files being generated).

    2. All lines containing "---Configuration" are retained.

    3. Anything else seen up until the first "Compiling..." line (not inclusive)
       is discarded.

    4. Lines starting with an HTML tag ('<' in column 1) are discarded

    5. Lines beginning with "Creating" (except beginning with "Creating library")
       are discarded

    6. All other lines are subject to standard Decryption processing.

If you happen to experience funny results during PLG processing, it would be a
great help if you could figure out how the algorithm above could be augmented to
cover the case you've encountered, and let me ([e-mail]) know. Thanks!



Alex says:

    Hopefully this will encourage even more people to use STLFilt (without
    being afraid to change their MSVC installation)."