BD Software STL Error Decryption Filter
 Extended Installation / Recompilation Instructions

 Copyright (C) 2001-2003 Leor Zolman (leor@bdsoft.com)

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

    This document describes how to customize CL.CPP, STLTask.CPP
    and STLFilt.BAT by modifying their source code. Such customization
    of CL.CPP and STLTask.CPP can, for example, eliminate the dependence
    on the Proxy-CL.INI configuration file or add additional file 
    extensions to the list CL.CPP "recognizes" as belonging to C++ programs.

    If, however, you've already got things working well enough by following
    the directions in QUICKSTART.txt, you probably don't need to do any more
    customization.

    (Step B. also explains how to configure Visual Studio to run the
    STLFilt.BAT batch file directly from Visual Studio's "Tools" menu.)

    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.

    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, this command should do it:

                CL2 /Ox /GX CL.CPP

           This produces CL.EXE. Don't compile CL.CPP with the "CL" command
           if there's a CL.EXE already present in the current directory,
           because the local CL.EXE will be still be active when the linker
           tries (and fails!) to write out the new CL.EXE. Another pitfall:
           don't try to compile CL.CPP from the IDE when there's a CL.EXE
           present in the CL.CPP source directory, 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 happened to me on
           several occasions and never fails to drive me crazy...but 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's no Proxy CL 
           configuration file (PROXY-CL.INI) in your Windows directory
           when the Proxy CL executes.

        5. Place the Proxy CL.EXE into MSVC's bin directory (e.g.
           C:\Program Files\Microsoft Visual Studio\vc98\bin in the default
           VC6 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). STLTask does
           have a menu selection to do this for you, "Prepare to update
           compiler", and it is a good idea to use it ;-)

    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 can cooperatively manage the same toggle control file(s).

 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

    NOTE: You can easily configure a pair of Visual Studio "Tools" to invoke
    the batch file for you, eliminating the need to run it from a DOS prompt.
    To create the tools, follow these steps:
        1. Select the Tools...Customize menu item, and click on the "Tools" tab
           in the "Customize" dialog that appears.
        2. Scroll down to the bottom of the list of tools, and there should be
           a blank space. Type in what you want to call the tool to turn on
           filtering, e.g., "Turn ON STL Decryption"
        3. In the "Command" field, enter the full pathname to STLFilt.BAT
        4. In the "Arguments" field, enter the text "On"
        5. Click the "Use Output Window" checkbox so it is activated
        6. If you like, move the new Tool up to the top of the menu by using
           the arrow icon at the upper right of the dialog
        7. Go back to step 2 and repeat everything for the companion "Off"
           tool, changing the Tool's title and Arguments fields accordingly.
        8. Close the Customize dialog.

    That's it! You can now turn filtering on and off right from the Tools menu
    (and if you have STLTask installed, the taskbar icon will correctly reflect
    the current state of the toggle file!)

C. If you wish to build a customized version of STLTask.EXE to control the 
   Proxy CL, do the following:

    0.  Download and install wxWindows 2.4.x from www.wxwindows.org. Don't
        forget to set your WXWIN environment variable to point to the instal-
        lation directory. 

        Replace the stock taskbar.cpp (in %WXWIN%\src\msw) with the one sup-
        plied with the STLTask source archive, and replace the stock taskbar.h
        (in %WXWIN%\include\wx\msw) with the one supplied with STLTask. The
        replacement taskbar.* files correct a problem with the 2.4.0 wxWindows
        distribution that loses tray icons during a taskbar re-initialization.
        Many thanks to Graeme Prentice for this fix!

        Build the NON-DEBUG library. If you installed wxWindows into E:\wx2,
        for example, run VCVARS32.BAT (or whatever MSVC-supplied or custom
        batch file you'd normally run to configure the environment for 
        command-line compilation), cd to the directory

            e:\wx2\src\msw

        and run the command:

            nmake FINAL=1 -f makefile.vc


    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 exception-handling and linker warnings when
        building STLTask.EXE.  I ignore them.

    4.  If you have more than one configuration (versions of MSVC or gcc
        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
        Proxy-CL.INI as a boilerplate)

        For the best way to get multi-platform support, see README-STLTask.INI
        for information on tailoring the STLTask.INI secondary configuration
        file. The *old* way to support multiple platforms required a separate
        instance of STLTask to be running for each platform. That was a losing
        proposition, so I won't say anything more about it ;-)

    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.