 STL Error Decryption Filter
 Installation Instructions

 Copyright (C) 2001 Leor Zolman (leor@bdsoft.com, www.bdsoft.com)


 Customization Instructions
 --------------------------

    Note: All compilation steps are performed from the command line,
    assuming you've set up your compiler environment with VCVARS32.BAT

    Please read GLOSARRY.txt to become familiar with the terminology
    used in this document.

    This document includes information on customizing CL.CPP, STLTask.CPP
    and STLFilt.BAT by modifying their source code. If you've already
    got things going by working through QUICKSTART.txt, and don't
    need to customize the source code, you can skip these instructions.

    A.  1. Determine where you want to place STLFilt.pl, where your Perl
           interpreter resides, and where you want the toggle-control file
           to reside. 

        2. Configure the symbolic constants FILTER_SCRIPT, PERL_EXE and
           TOGGLE_FILE_DIR at the top of CL.CPP to specify these three
           locations determined in step 1.

        3. To enable the Proxy CL to perform filtering on C++ source files
           having filename extensions *other* than .cpp or .cxx, add the 
           desired extensions to the filterExt array in CL.CPP.

        4. Compile CL.CPP. Assuming you have renamed the native CL.EXE to
           CL2.EXE as directed in step 2 above, this command should do it:

                CL2 /Ox /GX CL.CPP

           This produces CL.EXE. Don't compile CL.CPP with the "CL" command,
           because it will try to use CL.EXE in the current directory and then
           the linker won't be able to overwrite it ;-) Also, don't try to
           compile CL.CPP using the IDE when there's a CL.EXE in the same
           directory as the CL.CPP source file, or the IDE will insist on
           using *that* CL.EXE, *even though* the directory may not be in
           the IDE's "executable" search path. This has happened to me on
           several occasions and always causes me to tear my hair out...since I
           usually compile CL.CPP using the command line and CL2, I normally
           don't encounter the problem. If you prefer to use the IDE for
           compiling CL.CPP, consider renaming CL.CPP to, say, PROXY-CL.CPP 
           and copying the PROXY-CL.EXE you create into MSVC's bin directory 
           as CL.EXE.

           To have the Proxy CL use the configuration options you've 
           just compiled into it, make sure there isn't a Proxy CL 
           configuration file (PROXY-CL.INI) in MSVC's bin directory
           (or, at the location specified by the CONFIG_FILE symbol if you've
           configured it with a full pathname).

        5. Place the Proxy CL.EXE into MSVC's bin directory (e.g.
           C:\Program Files\Microsoft Visual Studio\vc98\bin in the default
           MSVC installation) 

           IMPORTANT: In the future, if you've ever run STLTask and need to
           update the Proxy CL in MSVC's bin directory, be sure to remove 
           any instance of the file CL.STL first. This file is a copy of the 
           Proxy CL that STLTask.EXE creates automatically.

    Proceed on to section B if you'll be using the STLFilt.BAT batch file
    to control filtering, or go to section C if you'll be using STLTask.EXE
    (recommended!).  Note that it is OK to use *both*... STLFilt.BAT and
    STLTask.EXE cooperatively manage the same toggle control file.

 B. If you wish to control the Proxy CL via the simple batch file
    STLFilt.BAT, do the following:

    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

C. If you wish to use STLTask to control the Proxy CL, do the following:

    0.  Download and install wxWindows from www.wxwindows.org. Don't forget
        to set your WXWIN environment variable to point to the installation
        directory.

        Build the NON-DEBUG library. If you installed wxWindows into E:\wx2,
        for example, run VCVARS32.BAT to set up the environment, cd to the
        directory

            e:\wx2\src\msw

        and run the command:

            nmake FINAL=1 -f makefile.vc


        Note: If you build STLTask With the debug library, STLTask crashes 
        with an assert macro violation if still loaded when you shut down 
        Windows (or a user logs out). The wxWindows "tbtest.cpp" taskbar demo 
        (which I cloned as the basis for STLTask) crashes in the same manner...
        Anyone who knows why and/or has a fix is invited to share that wisdom
        with me!


    1.  Unzip STLTask.zip into a fresh directory

    2.  Configure the symbolic constants at the top of STLTask.cpp to match
        your primary configuration. If this is your ONLY configuration,
        you're done configuring (you don't need any startup configuration
        files.)

    3.  Build STLTask.EXE via the command:

            nmake FINAL=1 -f makefile.vc

        Note: I get a bunch of linker warnings when building STLTask.EXE. 
        I've been ignoring them.

    4.  If you have more than one configuration (versions of MSVC installed)
        or you have skipped to this step because you're using the precompiled
        STLTask.EXE, then set up a config file for each different compiler
        configuration you wish to support (use my sample CONFIG.STL as
        a boilerplate)

    5.  Before you run STLTask for the first time, be SURE you've installed
        the Proxy CL as per QUICKSTART.txt. I.e., The MSVC bin directory 
        should already contain CL2.EXE as a copy of the native CL.EXE, and
        CL.EXE should be the *Proxy* CL.

        Run STLTask.EXE either with no command line arguments to have it
        read additional configuration info (if any) from Proxy-CL.INI in 
        the Windows directory, or provide a command line argument with the 
        name of an alternative configuration file to use.

        >>> Note: The config file, if specified, overrides the configuration
            hard-wired into STLTask.EXE itself

    6.  To have STLTask run automatically upon startup, place a shortcut
        to it in your StartUp folder with "/q" on the command line. This
        will start it up in "quiet" mode, skipping the initial status dialog.
        An alternative config file name may be provided alongside /q, in
        any order.
