quickstart.txt

STLstlfilt.zip

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 the "low-bandwidth" solution for turning STL filtering 
    on and off. This involves the use of 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/filename but *without* the extension) of the toggle
        control file used by the Proxy CL (set to C:\FILTERING as distributed).

        Note: the toggle control file's directory must match the value of the
        toggle_file_dir setting in Proxy-CL.INI.

    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

        Note: Instead of running STLFilt.BAT manually from a DOS prompt, you
        can create a pair of MSVC IDE "Tools" to run the commands for you from
        a menu without ever having to leave the IDE. Instructions for setting
        this up are given in CUSTOMIZE.TXT.

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.

    --------------------------------------------------------------------------
    If you get a notice of a missing DLL, you probably have no MS Visual
    Studio 6 installed. To use STLTask as distributed, you need to have a DLL
    named MSVCP60.DLL installed. This DLL presumably is installed automatically
    by MSVC6, but is not supplied with MSVC7 (or at least it wasn't present
    on one Win2K system I've tried installing STLTask on). I've made the file
    available here:

        http://www.bdsoft.com/dist/missingdll.zip

    Download it and install it into either your C:\Windows\System or your
    C:\Windows\System32 directory, depending on which version of Windows 
    you're running.
    --------------------------------------------------------------------------

    The first time STLTask.EXE 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" (if you haven't turned it on yet using STLFilt.BAT),
    indicated by the "no filtering" icon in the taskbar. To turn on filtering, 
    right-click on the STLTask icon (in the taskbar) and click on the "Enable
    filtering" item. The icon in the taskbar should change to a purple-and-
    yellow (no red) "active" icon. 

    The icon overlay will change to indicate disabling of filtering (a big
    red "No" symbol), uninstalling the Proxy CL (a big red "X"), and to show
    when STLTask is in "Clipboard-only" mode (a big red paper clip).

    Note: if you use STLFilt.BAT to change filtering status, that change
    will also be reflected in the taskbar icon (it is one smart little icon).

    Now go into Visual Studio and find some STL-related program, create a 
    bug in an STL-related line of code (or use a sample file out of the
    SAMPLES.ZIP archive included with the Decryptor package), 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, configuration information is loaded from the named file instead
    of from the default Proxy-CL.INI in the Windows directory (this was my
    original attempt at multi-platform support, but it required a separate
    instance of STLTask running for each platform). HOWEVER, watch out:
    if the config file you name resides in the *current directory* when
    invoking STLTask, you *must* preface the config filename with ".\".
    For example, specifying  "myconfig.ini" in the current directory as 
    the config file requires that you write it as:
        STLTask .\myconfig.ini
    This wasn't *my* idea, it is an artifact of the way Windows handles 
    configuration files. In any case, the issue goes away if you take
    advantage of STLTask's multi-platform support via STLTask.INI. See
    README-STLTask.txt for details.


    Command Line Operation

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

    There are several ways to compile without error filtering:

    1. Use the Proxy CL with the "/NF" ("No Filter") command-line option

    2. Signal the Proxy CL to disable filtering, either by issuing this
       command on the command line (if you've configured STLFilt.BAT):
            stlfilt off
       or by selecting the STLTask menu item "Disable filtering".

       (To later re-enable filtering, either issue
            stlfilt on
       from the command line, or select "Enable filtering" from STLTask).

    3. Use the native compiler command (typically renamed to CL2.EXE) directly.


    ****************************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 update compiler" command will prevent this problem by
    restoring original filenames for you. If you forget to do this
    before updating your compiler, the result may appear as a corrupt
    configuration to STLTask the next time it starts up. STLTask will
    either attempt to fix it, if the Proxy files are still there, or
    just complain and die if not. In the latter case, you'll have to
    re-configure stuff in the compiler's bin directory as per the 
    original instructions in steps 1c-d above before running STLTask.
    *****************************************************************


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 (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 filter 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 determines whether the build process continues on to later phases, such as
linking.

The Perl script supports several runtime options, some specific to the VC7
platform. One general option controls the "Iterator Policy" to be
applied by the filter. The option is specified by
    /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. Alternatively, you can think of the code letters as
representing requests for "Short", "Medium", or "Long" iterator type 
specifications. (Note: Option prefix characters may be either '-' or '/')

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.

For details on the other Perl script command-line options, see the comments 
in STLFilt.pl.

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... Historically I've found
out about most problems by reading posts on Internet discussion boards and
newsgroups before anyone has ever emailed me directly. Figuring folks are
shy, I've created a Yahoo Group for STLFilt issues, The address is:

    http://groups.yahoo.com/group/stlfilt

Please drop by and post something, just so the list doesn't rust ;-)

If you have time, you may find it useful to read GLOSSARY.txt and
README.txt, because there are additional details in there worth knowing
about.

Also, check all the README*.txt files for supplementary information
that may be present pertaining to the specific library and/or tools
you'll be using, especially README-STLTask.txt for multi-platform info.

And...may you now spend less time suffering through intimidating error 
diagnostics, leaving you that much more time to create good code!

        -Leor Zolman
         8/29/2001 - 3/18/2003