File:		DS++ FAQ
Author:		Geoffrey Furnish
email:		furnish@dino.ph.utexas.edu
Last Modified:	28 November, 1995

Section 0: General

Section 1: Installation

Section 2: Usage

===============================================================================
Section 0: General
===============================================================================

0.1: Why is all the useful info in the FAQ?

Because I'm too lazy/busy to write real prose.

0.2:  Why should I use DS++ instead of STL?

You shouldn't.  If you have access to STL on the platforms that matter
to you, you should probably use STL.

0.3: Why was DS++ created?

Because STL didn't exist when I needed it!  Since there was no
standard, I needed a package which was free (so that I could use it on
all the platforms I needed), and portable (meaning, "compilable by
both Cfront and G++").

0.4: How mature is DS++?

It works for me :-).  Your mileage may vary.

0.5: Can I expect to use DS++ without ever having to mess around in
the source?

Unlikely.  Expect bugs, plan to find them, and please send the patches
back to me.

===============================================================================
Section 1: Installation
===============================================================================

1.1:  What's first?

Unpack the distribution.  You can currently get it via anonymous ftp
from dino.ph.utexas.edu.

1.2: What's second?

Make sure you understand the template instantiation process on your
compiler.  *Thoroughly*.

1.3: I don't understand template instantiation on my compiler.  Will
you help me?

No.  I am busy trying to get a degree, and don't have time or patience
to hold your hand.  Unless you are sending $$$, in which case I am
very sympathetic and helpful :-).

1.4:  What's left?

Edit the makefile.  Set CXX and CXXFLAGS.  Type make.  Be happy.

1.5:  What are all those *_inst.cc files?

See 1.2 above.  If your compiler can handle explicit template
instantiation syntax (like GCC 2.6+), you may wish to add those files
to the SRCS macro in the makefile.

1.6:  How does DS++ work with GCC?

I recommend using GCC 2.6+, and compiling with
-fno-implicit-templates, and then explicitly instantiation any
templates you use.  That is what the *_ints.cc files do for me.  You
may need different instances.

1.7:  How do I preinstantiate a Stack<foo> when foo is a class in some
other directory, and is not known to the compiler when it builds DS++?

I suggest making a pt_foo.cc or foo_inst.cc, or whatever file in the
directory where you compile foo.cc.  In that file, preinstantiate the
Stack<foo> class, and stuff the resulting object file in your library.

But I digress.  Remember 1.2 above.

1.8: What are these tst*.cc files?

Test programs I use to see if the DS++ classes are working.

1.9: Anything else?

There are manpages in a man subdir.  You can put those somewhere if
you want.  They are generated automatically by stripping comments from
the source code.

1.10: What's with the USAGE section in the man pages?  It doesn't make
sense to me.

DS++ is developed in the context of my dissertation research.  I
haven't had time to make the man page generator change the text for
external distributions to be different from that used in our research
group.  Basically you just need to give an appropriate -I to the
compile phase, and if using Cfront, the same -I to the link phase
(along with suitable -Lwherever and -lds++).

===============================================================================
Section 2: Usage
===============================================================================

2.1: How do I use the DS++ classes?

Assuming you have accomplished 1.2 above, you just need to include the
header file for the classes of interest, and then compile and link
your code.

For instance:

% cat main.cc

#include <iostreams.h>
#include "String.h"

main()
{
    String Bob = "has no last name";
    cout << "Bob " << Bob << endl;
}

2.2:  That's trivial.  What about the rest of the classes?  What do
they all /do/?  Etc.

Read the source.  The tst*.cc programs may provide some useful
orientation.

2.3:  What's with your Assert.h file?  I don't like it.

So change it.  You have the source.

2.4:  Yes, but what were you thinking when you wrote that, anyway?

I don't like bugs.  I want to get them out of my code.  If the code
cores, then the bug /has/ to be fixed.  Calling abort() enables me to
hop into the debugger and immediately find out what's wrong.  (Except
on HP/UX where xdb gets overstressed too easily, but that's beside the
point). 

Also, a lot of my C++ code is invoked from Tk.  (Don't know about
Tcl/Tk?  Go read comp.lang.tcl.)  I put a try/catch block around the
tcl command interpretter, and return TCL_ERROR with the Assert string
as the result.  Thus, anytime an Assert-ion fails in the code, a cute
little Tk error dialog pops up and informs the user (normally me) of
the problem.  This has proven to be an invaluable debugging aid.

Anyway, that's what I use Assert for.  If you don't like it, change it.
