=========================================================================== BD Software STL Error Message Decryptor for gcc 2/3 Note: Versions for MSVC 6, Visual Studio.NET 200x, Comeau C++, Intel C++, CodeWarrior, EDG and Borland and Digital Mars C++ are available at: http://www.bdsoft.com/tools/stlfilt.html Copyright 2001-2004 Leor Zolman =========================================================================== Unix/Windows: gSTLFilt.pl (the Perl script): Release 2.47a (06/29/2005) Windows only: C++.cpp (The Proxy c++ compiler): Release 3.44 (11/25/2004) STLTask Taskbar Icon Controller: Release 3.07 (09/08/2004) Written by Leor Zolman (leor@bdsoft.com) BD Software www.bdsoft.com BD Software offers on-site, hands-on programming seminars in introductory to advanced C/C++, and introductory Java, Unix and Perl. You can find more course information at the end of this document, and full course descriptions at wwww.bdsoft.com. Windows users: See QUICKSTART.txt for a brief overview and quick setup instructions. Unix/Linux users: The file "gfilt" is a sample shell script driver for invoking the Decryptor. That and the script itself (gSTLFilt.pl) should provide enough information to get you on your way. **************************************************************************** * Please do not redistribute any part of this package directly; rather, * * to ensure folks get the latest version, please direct anyone interested * * to download the latest distribution directly from its web page: * * * * www.bdsoft.com/tools/stlfilt.html * * * **************************************************************************** This package is updated frequently; check the web page for the date of the latest posting, and click on the version numbers in the component table to see reverse-chronological revision logs. **************************************************************************** * To participate in a forum with other filter users, come visit the * * STLFilt section of the BD Software Message Board at: * * http://bdsoft.proboards34.com/ * **************************************************************************** ============================================================ What's in this archive (both Windows and Unix distributions) ============================================================ README.txt: You're reading it: purpose, manifest, acknowledgments and shameless self-promotion are all to be found here. gfilt.BAT: Simple command-line compiler/decryptor driver, if you'd prefer not to install the Proxy CL and just drive the decryptor manually on demand. Note that this batch file will NOT work under Windows95/98/ME due to lack of standard *error* redirection capability in the Windows9x command processor. If you are running a replacement command processor for Win9x (such as 4DOS) that does have standard error redirection, make appropriate changes to the compile line and you may be able to get it to work. This error redirection issue does not arise if you use the "Proxy C++" command instead of the batch file. gfilt: Unix shell script driver for compiler/Decryptor. This script is smart enough to dispatch Decryptor options to the Perl script, and other options and arguments to the compiler. gSTLFilt.pl: The Perl script. gcc-log.txt: Revision log for C++.cpp and gSTLFilt.pl Samples.zip/.tar: A slew of CPP files that draw various STL-related errors. Try 'em with and without the filter! metatest.cpp: Short sample source file illustrated the new template metaprogramming-specific line wrapping features (uses Boost) ================================= In the Windows distribution only: ================================= QUICKSTART.txt: Fast track setup instructions, for the impatient. Contains just the essential instructions necessary to put the Decryptor into service quickly. GLOSSARY.txt: Definition of terms used in this software and documentation. C++.EXE: The C++-spoofing proxy compiler. Replaces the stock C++.EXE during C++ compilations, and invokes it indirectly. STLFilt.BAT: Low-bandwidth batch file utility to toggle the filtering control file. Say stlfilt on or stlfilt off to control filtering. Most useful when working from within an IDE (you can run STLFilt.BAT from a DOS window). When compiling directly from the command line, just choose between running c++2 (c++2.EXE is the recommended name for the copy of the native c++.exe). The Proxy c++'s "/NF" option may also be used to force "no filtering" during an individual compile. Note: STLFilt.BAT and STLTask.EXE cooperate, and may be run interchangeably to enable/disable Proxy c++ filtering. README-STLTask.txt: Supplementary documentation on using the STLTask program (now supporting concurrent multiple compiler platforms!) STLTask.EXE: Taskbar-based Proxy C++ control utility. STLTask controls Proxy C++ installation/uninstallation, filter toggling and clipboard filtering for up to ten compiler platforms from the same instance. STLTask provides an alternative to STLFilt.BAT to toggle the filter control file. The installation/uninstallation feature of STLTask is provided for situations where the Proxy C++ may not play well with other project controlling software. The "Uninstall" feature makes it easy to suspend use of the Proxy C++ during these types of builds, if necessary, then bring it back for later work by selecting "Install". The STLTask tray icon automatically reflects the current status of the filtering toggle file--even when the toggle file is renamed using the STLFilt.BAT batch file or any other means. Proxy-gcc.INI: ASCII configuration file for use with C++.EXE and STLTask.EXE. Edit this file as appropriate for your system (remember to remove the leading semicolons of lines you wish to be active!!), place it in your Windows %SystemRoot% directory C:\Windows or C:\Winnt, etc.) and its settings will override the hard-wired defaults built into C++.EXE and STLTask.EXE. STLTask.INI: Secondary (optional) configuration file for activating STLTask's new simultaneous multi-platform support capability. STLFilt.BAT: Low-bandwidth batch file utility to toggle the filtering control file. Say stlfilt on or stlfilt off to toggle whether or not the Proxy C++ performs STL message Decryption. Most useful when c++.exe is invoked automatically from within some kind of IDE. When compiling directly from the command line, you can also simply choose between executing c++ (for filtering via the proxy compiler) or c++2 (to use the non-filtering native gcc compiler). The Proxy C++'s "/NF" option may also be used to force "no filtering" during an individual compile. Note: STLFilt.BAT and STLTask.EXE cooperate, and may be run interchangeably to enable/disable Proxy CL filtering. C++.cpp: Source to the Proxy C++ program. STLTask-src.zip: Source code to the STLTask utility. Installation of the wxWindows library is required to rebuild STLTask.EXE. STLTask-log.txt: Revision log for the STLTask utility. CUSTOMIZE.txt: Instructions for rebuilding C++.EXE and STLTask.EXE from their source code, and for using the STLFilt.BAT batch file for enabling/disabling filtering. MinGW-install.txt Some notes in configuring MinGW32 gcc for use with extended containers. ======= Purpose ======= The idea is to shorten the length of STL-related error messages, and selectively suppress several kinds of messages, so that the most vital information out of the usual flood of diagnostics is visible front-and-center. Lots of things you don't usually need to see are deleted, e.g.: --> The qualifiers "std::", "class", "struct", "__gnu_cxx", etc. disappear --> Iterators are radically shortened to either just "IT", "iter", or, for a container "cont", "cont::iter" (you pick which form to use). You can then typically deduce the type details from the remaining context of error messages --> Any functors of the form less are deleted; others are left intact. Thus the default "less<...>" functors don't clutter the messages when dealing with associative containers --> strings, istreams and ostreams of , their traits, etc. reduce to just "string", "istream", "ostream", etc. Ahhh! --> iostream iterators are recognized and abbreviated --> Allocators in type names totally disappear, and allocators in function parameter lists reduce to just "alloc" (good riddance...) --> Excessive template "candidate" lines are selectively suppressed --> Excessive errors from deep within the Standard Library headers are selectively suppressed Another feature is intelligent line-wrapping for very-long type names typical of template metaprogramming applications (if you have Boost installed, the supplied sample source file metatest.cpp illustrates these features.) There are certainly cases I'll have overlooked, and some I just don't know how to filter. Feedback is welcome, but here's the disclaimer: The original reason I wrote this was to make it possible to teach C++ using the STL-first approach without scaring away students due to outlandishly complicated STL error messages. Thus, the filter addresses messages resulting from the most common coding errors (wrong number of arguments, wrong argument type, etc.) in standard container operations involving most everyday data types. If the Decryptor's command-line options don't provide the needed flexibility, STL power users are always free to disable filtering to track down errors where the deleted detail needs to be seen, and then re-enable filtering when such detail is no longer needed. Two methods are provided to enable/ disable filtering: 1) The STLFilt.BAT file (low-bandwidth, and calls to it can easily be wired into the IDE's Tools menu) 2) the STLTask tray icon program is convenient to use, allows instantaneous installation/uninstallation/reinstallation of the Proxy C++ at any time, and provides a facility to filter system clipboard contents on-the-fly at any time ========================================================================== Note about the name "c++" versus the name "g++": In this package, I refer to the gcc compiler as "c++" since that is one of its names. Another is "g++". I had to choose one or the other when naming files and writing up instructions, but everything here referring to "c++" will work just as well if you substitute "g++"... just make sure you name files and configure parameters consistently. For example, you can rename c++.cpp to g++.cpp (or just rename the executable to g++.exe) and configure Proxy-gcc.INI / STLTask.INI to specify "g++" and "g++2" instead of "c++" and "c++2" in the appropriate sections. ========================================================================== ============ How it Works ============ 1. Nuts and Bolts [Windows Only] When installed/active, the Proxy C++ (c++.exe as distributed) is invoked as if it were the native gcc compiler. The Proxy C++ checks for the existence of the controlling toggle file (FILTERING.ON). If the toggle file is *not* detected, the Proxy C++ simply invokes the native c++ (usually renamed to C++2.EXE within gcc's bin directory) with the same command arguments it was itself invoked with. This yields ordinary, unfiltered error message output. If the toggle file *is* detected AND the file type being compiled qualifies for filtering, then the Proxy C++ sets up an interprocess pipe between the native c++ and an invocation of Perl. The native C++'s output stream is then piped into the standard input of the Perl process executing the gSTLFilt.pl script, to simplify STL-related messages. The output of the Perl script is then sent to the standard output while the process status code of the *native* c++ process controls the subsequent behavior of any controlling build mechanism. 2. Rationale [Windows Only] The Proxy C++ allows Decryptor command-line options (conveyed to the Perl interpreter) and gcc command-line options (conveyed to the native gcc c++ compiler) to be freely intermixed on the Proxy C++ command line. STLTask (the taskbar utility) has the power to install/uninstall the filter (see the description of Active/Inactive in GLOSSARY.txt) to make it easier to run native builds unencumbered by possible Proxy C++ bugs. This installation/uninstallation copies either the Proxy C++ (CL.STL) or the native c++ (C++2.EXE) over c++.EXE. Because of the possibility of crashes etc. in the middle of such operations, STLTask tries *real hard* to make sure the files remain in a consistent state. If there is any doubt as to the current status of the filter (installed or not installed?) upon startup, STLTask resets everything to the native gcc configuration (Proxy c++ uninstalled) by default. 3. Configurability [Windows and Unix] One programmer's essential details are another programmer's noise; I've put a lot of effort into allowing users to "roll their own" feature set for the decryption process. Be sure to carefully examine the entire "User-Configurable Options" section near the top of the Perl script, gSTLFilt.pl, to see what your options are. Many of those options may be controlled via the configuration file (Proxy-gcc.INI) and command-line options to the Proxy C++, the Perl script itself, or a driver script (see below). Some configuration options can only be changed by editing the Perl script. The gfilt (for Unix) and gfilt.bat (for Windows) scripts show examples of using the options, and let you set a default set of Perl script options via the DOPTS variable. You may augment DOPTS variable set within the gfilt/gfilt.bat scripts by manually setting an environment variable named GFILTOPTS to your desired additional options (don't forget to export it under Unix). When gfilt/ gfilt.bat run, they'll append GFILTOPTS to DOPTS. This was done to allow quick-and- dirty option switching without having to edit the scripts or enter a cumbersome command-line pipe sequence manually under Windows if all you're using is the batch file. Note that both the Proxy C++.exe under Windows and the gfilt shell script under Unix allow for arbitrary intermixing of compiler and Decryptor options on the command line. =============== The CUJ Article =============== For background information on the origins and philosophy of the Decryptor, see my article in the July, 2001 issue of The C/C++ Users Journal. The article was the Web Feature for July, 2001--that means it is now and forever available for viewing in its entirety on the CUJ web site, at the following URL: http://www.cuj.com/articles/2001/0107/0107b/0107b.htm?topic=articles Note that the article describes the MSVC-specific version of the Decryptor, so ignore installation details from the article (which are out-of-date even for the MSVC-specific version). ================================= Debugging Features [Windows Only] ================================= C++.CPP and STLTask.EXE have debugging features built-in. C++.CPP supports runtime debug configuration: set the DEBUG configuration option to true to log status messages to a file named CL-dblog.txt in the directory configured by the DEBUG_DIR option. The Proxy CL option LOG_NATIVE_MSGS may be set (via the configuration file Proxy-gcc.INI only) to force the Perl script to log its complete, UN-filtered input to a file named NativeLog.txt in the current directory. Sending me a copy of this file can help me debug the Perl script when issues arise relating to the filtering algorithm. STLTask.cpp debugging must be configured at compile time. Set the DEBUG symbol to 1 and define the DEBUG_DIR symbol to the name of your desired log file directory, and STLTask will log various status info to a file named "debug.out" in that directory. If you run into a situation where the Proxy C++ fails, please let me know so I can fix it. If you understand the problem and can describe the circumstances, that's great...if not, I'd be glad to help figure out the problem and hopefully fix C++.cpp for the future; please reduce the project to the minimum possible configuration that results in CL failure, zip it up and email it to me (leor@bdsoft.com). I'll do my best to determine the problem and correct it. This program is as reliable as it is now *only* because folks like you informed me about the problems (and even fixed them for me on many occasions!) =============== Acknowledgments =============== Thanks to: Scott Meyers for putting on his "Effective STL" seminar -- the event that inspired this project. David Abrahams for suggesting the features relating to the /hdr:LD1, /hdr:LD2 and /BREAK:D functionality, and then generously supporting my efforts to implement those features. David Smallberg for the Proxy compiler idea. Thomas Becker for writing the Win32 interprocess communication code in C++.CPP David Abrahams for contributing the long-typename-wrapping algorithm and assisting me in the debugging/evolving of it. The other folks who took the time to email me with bugs and suggestions, and/or helped with debugging: Thomas Becker Wilka Sam Saariste Scott Lewandowski Scott Meyers Tom Malcolmson Jan Stette Dominic Mathieu Michael Cook Andy Philpotts Rob Bishop John Hattan Derek Price Bill Torpey John Penney Jonathan Sambrook Argos Matthew Douglass Dave Conrad Scott McCaskill Paul Suggs Karl Lean Benoit Goudreault-Emond Michael Griggs Marco Welti Ed Kaulakis Shing-Fat Fred Ma George Katsirelos Graeme Prentice Larry Evans ======= Courses ======= "Programming is not a commodity" (at least not in my book). To promote excellence in software development technology, BD Software offers the following on-site, hands-on seminars for programmers: ==> C++ for non-C Programmers Very intensive, 5-day workshop teaching C++ for those who have never programmed in C. Seminar by me, based on the Stephen Prata textbook "C++ Primer Plus" (4th edition). Prerequisite: *SOME* programming experience, but it doesn't matter in what language. ==> An Effective Introduction to the Standard Template Library (STL) Course by Scott Meyers, who needs no introduction. Teaches the STL to experienced C++ programmers. 4 Days. Prerequisite: Real-world programming experience in C++. ==> C++ and Object-Oriented Programming 5-Day course by Dan Saks, another C++ guru you probably know about. Teaches C++ assuming GOOD (working) knowledge of C. More in depth on OO and C++ subtleties than the first course above. ==> Advanced C Programming This five day, hands-on C training is designed to bring practicing C programmers up to the next level of C expertise. Since one area where C syntax and semantics present a major hurdle is in the understanding of declaration syntax, the course leads participants in the incremental design and implementation of their own limited C declaration parser, written (of course) in C itself. After going through this process, you'll most likely understand declarations almost as well as Dan Saks does (which is saying a lot). ==> Introduction to Programming in C My own C programming course. Some programming experience (not necessarily in C) is the only prerequisite. 4 or 5 days; 5 preferred. What can I say? Not too many folks are still learning "just" C anymore, but if you have two weeks available to learn C++ in, it works out a lot better to take C first and then the C++ and OOP course above than it does to cram both C and C++ into one week. That is, at least until I write a course based on the STL-first approach... ==> Object-Oriented Programming in Java My (I'm co-author) Java course. Does NOT presume any C/C++ experience. Uses all public domain / shareware tools (Sun's JDK, ModelWorks' JPadPro (awesome IDE!). 5 Days. Everyone gets a CD full of Java goodies. Again, presumes only some programming experience in SOME language. ==> Introduction to Unix (2-3 days) ==> Korn Shell Programming (3 days) ==> Perl Programming (3 days) All three Unix courses above written by Danette Morris. The Perl course is mostly platform-independent, but includes some Unix-specific functionality. To give feedback on this package, or get additional information on having one of the courses listed above delivered at your site, please contact: Leor Zolman BD Software 74 Marblehead Street North Reading, MA 01864-1527 voice/FAX: 978-664-4178 email: leor@bdsoft.com web: www.bdsoft.com ===============================================================================