========================================
STLTask Tray-Icon Filter Control Utility
      Supplementary Documentation
            Updated: 6/06/03
========================================

STL Error Decryptor Web Page: www.bdsoft.com/tools/stlfilt.html
(The STLTask revision log is in the file STLTask-log.txt)

Written by: Leor Zolman
            leor@bdsoft.com
            www.bdsoft.com

----------------------------------------------------------------------------
NOTE: I haven't specialized this file for the various platforms with which
it is included, but I've tried to keep the discussion as general as possible
with respect to filenames and paths. Some of the examples are, however,
MSVC-specific; the Proxy-CL/gcc/ICL.INI file in your distribution does
show defaults as appropriate to your specific platform.
----------------------------------------------------------------------------

STLTask...
a) Replaces (and/or cooperates with) STLFilt.bat as the toggle-file manager,
   with the ability to support up to ten individual STL Decryptor platforms
   from a single instance;
b) automates installation/uninstallation of the Proxy compiler;
c) allows on-demand error decryption of clipboard contents (MSVC IDE only)

Written using wxWindows, a freeware, platform-independent C++ GUI 
library. (get it at www.wxwindows.org).

For instructions on building STLTask.EXE from the source code, see
CUSTOMIZE.txt.


=============
Configuration
=============

There are two ways to configure file/directory names:

1. In the source: Edit the user-configurable area of STLTask.cpp (not
   recommended)

2. At run time: STLTask.EXE automatically takes primary configuration info
   from the [common] and [stltask.exe] sections of the primary configuration
   file (Proxy-CL.INI, Proxy-gcc.INI or Proxy-ICL.INI, etc., depending upon
   platform) in the system's Windows directory, or from a filename specified 
   as a command-line argument (CAREFUL: if you supply the config filename on
   the STLTask command line and the config file is in the "current"
   directory, the name must have ".\" in front of it. Don't ask me why...)

   For multi-platform support, a secondary configuration file named STLTask.INI
   may be placed in the Windows directory (or at a location specified by the
   MP_CONFIG_FILE parameter described below), and information about each
   platform you wish to control will be loaded from that file.

   ==========================
   Primary Configuration File
   ==========================

   Each STL Error Decryptor platform supporting a "Proxy compiler" has its own
   primary configuration file for tailoring Decryption options and system
   files/paths. The platforms and their corresponding default primary
   configuration file names are:

        MSVC:   Proxy-CL.INI
        gcc:    Proxy-gcc.INI
        Intel:  Proxy-ICL.INI
    
   If no secondary configuration file (see below) is used, then STLTask.EXE
   reads the following options from the primary configuration file:

   ======  In the [common] section: ===========================================

      FILTER_SCRIPT             The full pathname of the Perl script (default:
                                STLFilt.pl)

      TOGGLE_FILE_DIR           Directory where the "Toggle control file"
                                resides (default: c:\)

      NATIVE_CL                 The *filename* (no path) of the renamed native
                                    compiler (default in Proxy-CL.INI: CL2.EXE)

                                Note: The *name* of this parameter (in addition
                                to its value, of course) is platform-dependent:
                                    In Proxy-GCC.INI, it is named NATIVE_GCC
                                    In Proxy-ICL.INI, it is named NATIVE_ICL

      PERL_EXE                  Full pathname of Perl interpreter executable



   =====   In the [stltask.exe] section: ======================================

      CL_DIR                  Compiler's native bin directory. Default:
                              c:\program files\microsoft visual studio\vc98\bin

      CL_EXE                    Filename and extension of native compiler's
                                "normal" name. Default: CL.EXE

      CLIPBOARD_ONLY            "true" to use STLTask *ONLY* for 
                                clipboard filtering (default: false)
                                [When STLTask is in "Clipboard-Only" mode, the
                                icon will appear to be held onto the taskbar
                                by a little red paper clip]

      PROXY_CL_UNINSTALLED_FNAME  The *filename* (no path) for the "inactive"
                                  Proxy CL (default: CL.STL)

      CHECK_FOR_PREVIOUS_INSTANCE  "true" to use a sentinel file (STLTASK.LOK)
                                   in the CL_DIR directory to mark an instance
                                   of STLTask as active. This prevents multiple
                                   instances from running at the same time.
                                   If the sentinel file is detected upon
                                   startup and CHECK_FOR_PREVIOUS_INSTANCE is
                                   true, then STLTask will present an "Are you
                                   SURE..." dialog and offer the choice of
                                   either continuing or bailing out.

      TIMER_INTERVAL_MS         Interval between timer ticks for updating icon
                                graphic with current Decryption status (in
                                milliseconds).

      MP_CONFIG_FILE            Name or full pathname of the secondary, 
                                multi-platform-specific configuration file, if
                                using one.


   ============================
   Secondary Configuration File
   ============================

   The options in the secondary configuration file (if present, typically 
   STLTask.INI in your Windows directory) override STLTask-related options
   in the primary configuration file for all supported platforms. The options
   are:

   ===== In the [common] section: ===========================================

      DEFAULT_PLATFORM          Numeric value (0-9) of the platform STLTask
                                will come up supporting. Must correspond to
                                the value of n in a subsequent [platform.n]
                                section.

      SENTINEL_DIR              Directory where the STLTask lock file will
                                reside. Defaults to C:\

   ===== In each [platform.n] section, where n is a single decimal digit: ====


      ID                        Arbitrary string identifying this platform.

      FILTER_SCRIPT             Full pathname to the Perl script for this
                                platform.

      TOGGLE_FILE_DIR           Directory for the Decryption toggle file
                                specific for this platform

      NATIVE_CL                 What you RENAMED the native compiler to (say,
                                CL2.EXE for MSVC)

      CL_DIR                    Full pathname of the compiler's "bin" directory

      CL_EXE                    Filename only of the active compiler (say,
                                CL.EXE for MSVC)

      PROXY_CL_UNINSTALLED_FNAME    File used by STLTask to store the Proxy 
                                    compiler when it is not installed (CL.STL
                                    for MSVC)

      CLIPBOARD_ONLY            true or false, if STLTask is only to be used 
                                for processing errors through the clipboard for
                                this platform (the clipboard feature only works
                                when messages are copied from an MSVC IDE's
                                output window).


   See the sample Proxy-CL.INI (or Proxy-gcc.INI or Proxy-ICL.INI, etc.
   depending upon platform) and STLTask.INI files for examples of how to set
   these up.

   ****** NOTE: Whether a secondary configuration file is present or not, the
   Proxy compilers still read many options from the [Proxy-whatever] sections
   of the primary configuration files. The secondary configuration file is used
   by STLTask only, not by the Proxy compilers.

=========
Operation
=========

Note: In the following descriptions, I refer to the filename CL.STL, but this
actual name is controlled by STLTask's configuration parameter 
PROXY_CL_UNINSTALLED_FNAME.

When I refer to a name with an underscore, such as NATIVE_CL, I'm referring to
the actual filename represented by that configuration parameter. For example,
CL_DIR represents the platform's "bin" directory.

Startup:

    Before running STLTask, make sure you've followed the QUICKSTART.txt
    instructions to
        a) rename your native compiler executable
        b) copy the Proxy compiler into your compiler's bin directory

    If compiling from the command line, the compiler's bin directory must
    be on the system PATH (either as a result of having run some compiler-
    specific batch file, such as VCVARS32.BAT for MSVC, or because this is
    permanently set in your system's environment variable settings.)

    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.
    --------------------------------------------------------------------------

    Upon startup, STLTask examines all compiler-related files in CL_DIR
    for consistency (e.g., an unambiguous "installed" or "uninstalled" state),
    as follows:

        1) makes sure the Proxy compiler is present in CL_DIR as
            CL.STL (by copying CL_EXE to CL.STL if it isn't the same
            size as NATIVE_CL)

        2) makes sure the native compiler is present in CL_DIR as CL_EXE.

    If there's any ambiguity about the current state of the Proxy's
    installation, it favors the native configuration, i.e., "uninstalled".
    During subsequent operation, it strives to keep the configuration from
    ever becoming broken. Any renaming that STLTask performs is documented 
    at the top of its startup dialog (unless run with the /q option).


General Operation:

    Once STLTask is in the taskbar, right-click on the taskbar icon to 
    bring up the context menu. Or, double-(left)click the icon to directly 
    bring up the Status report.

    When you select "Enable filtering" or "Disable filtering" (exactly one
    of the two will be available any time a Proxy compiler is installed), 
    STLTask simply toggles the filter control file and updates the display 
    icon accordingly.

    When you select "Install Proxy CL_EXE", STLTask copies CL.STL to CL_EXE
    and begins showing the Filtering Enabled/Disabled icon.

    When you select "Uninstall Proxy CL_EXE", STLTask copies CL2.EXE to CL_EXE
    and shows an "X-ed out" Icon.


Clipboard Filtering:

    You can use STLTask to apply the Perl filtering directly to message
    text copied into the clipboard -- but *only* if that text came directly
    from MSVC's "output" area. Just copy the text you want to filter from MSVC
    into the clipboard, and choose the "filter Clipboard" command from the 
    STLTask context menu. The text in the clipboard will be Decrypted, 
    and the result of the filtering will be displayed in a dialog box.

    This feature is provided so you can leave the proxy CL uninstalled, and
    still be able to filter error messages  upon demand. This would be the 
    most useful on slow (<300 MHz) machines, or during monstrously long builds
    where you know there won't be any STL errors worth filtering, where keeping
    the Proxy compiler installed may slow the compilations down too much.

    At this time, clipboard filtering is tuned for processing diagnostics
    generated within the Microsoft Visual Studio IDE *ONLY*.

    If you'd like to use STLTask for clipboard filtering *without* having
    to install the Proxy CL at all, you may do so by setting CLIPBOARD_ONLY
    in the primary configuration file (or in the appropriate [platform.n]
    section of STLTask.INI) to true. See the "Configuration" section above
    for details.


Running STLTask on Startup

    To having STLTask loaded upon system startup, place a shortcut in
    your "Startup" folder and give it the /q ("quiet") option. You won't
    get the initial status dialog, nor will STLTask bother to warn you if
    a lock file from a "previous instance" is detected (however, if you start
    up STLTask using /q when there's already another instance active, you will
    end up with multiple simultaneous instances.)


Important note regarding updating compilers:

    WARNING: If applying a compiler update (such as via a Visual Studio
    Service Pack) you must "Uninstall" the Proxy CL and then DELETE CL2.EXE
    from the CL_DIR directory before applying the Service Pack. Otherwise, the
    next time STLTask starts up it may copy the old CL2.EXE on top of
    a possibly updated CL.EXE.

    STLTask has a context-menu selection to take care of this for you. If you
    forget to use it, though, things can get nasty.  However, STLTask tries
    to deal with this eventuality if it encounters it, since this happened to
    me once and I didn't like the confusion it caused. If STLTask sees things
    royally mixed up, it tries to fix them. I'd highly recommend not letting
    it come to that, however ;-)

-- END --