
Installation Guidelines:
-----------------------

Problem is written in C++, so you must have a C++ compiler.  It runs
only in the UNIX environment for the time being.  You must also have
the GNU database management library (GDBM) installed, as well as have
the pager "less" on your system.  It has been successfully built and
tested in the following environments:

Sun Sparc running SunOS 4.1.1 with Cfront 2.0, g++ 2.2
Sun Sparc running SunOS 4.0.2 with g++ 2.2.2
IBM 3090 running AIX/370 with Cfront 2.0
IBM RS/6000 running AIX 3.1.5 with Cfront 2.1, g++ 2.2, xlC
i486 + ISC v3.2 3.0 Unix (SysVR3) with g++ 2.2.2 (use -DTERMIO -DISC)
Apollo running Domain/OS 10.3 with ANSI headers, BSD Environment, g++ 2.2
HP 9000/300 series, HP-UX 8.0, gcc/g++ v2.2.2
SCO UNIX 3.2.2, g++ 2.2.2

In order to build "problem", a few lines in the Makefile will need to be
modified.  The line

CC =

is used to define the name of your C++ compiler.

  ex.  You have some version of Cfront
  --
         CC = CC

  ex.  you have GNU g++
  --
         CC = g++

The line

CFLAGS =

is where system-specific preprocessor defines are put.  Direct from
the Makefile we have:

# Add -DSIGINTERRUPT if you both have it and NEED it to ensure that signals
# interrupt slow system calls.  This is primarily for 4.3 BSD-based systems.
# Otherwise, your system most certaily does the right thing already.
#
# Add -DOLDDELETE if your compiler can't handle the 'delete []' form
# of the delete operator for deleting arrays of objects allocated
# via new.  If you don't know whether you compiler can handle it or
# not, just don't define it and see what happens.  If your compiler
# accepts it, it'll do the right thing.
#
# You must indicate where the GDBM header file 'gdbm.h' is to be found
# using a flag of the form: -I/usr/local/include.
#
# If you have the BSD 4.3 signal mechanism, in particular, sigblock(2) and
# sigsetmask(2), add -DBSDSIGS.  Else if you have POSIX signals, in
# particular sigprocmask(2), add -DPOSIXSIGS.  Otherwise I'll use
# the usually ANSI C signal mechanism when I need to block SIGTSTP and
# SIGWINCH.  This can lead to some lost signals in very rare
# circumstances, but what can you do with a braindead signal mechanism.
#
# The default locking is done using the POSIX "lockf".  If you don't
# have "lockf" but have the BSD "flock", add -DFLOCK.  If you have
# neither, well ...
#
# By default, we assume that you have version of mail that accepts the
# "-s" flag to indicate a subject line.  If your mailer doesn't
# recognize the "-s" flag, add -DNOSUBJECT.
#
# If you don't have the pager "less" or just don't want to force its use as
# THE pager, add -DNOLESS.  We'll then use the pager in the PAGER
# environment variable, or "more" by default.  Use "less" if you have it.
#
# If you're running on ESIX, add -DESIX

  ex.  On a Sun you need to use -DSIGINTERRUPT and -DBSDSIGS
  --
         CFLAGS = -DSIGINTERRUPT -DBSDSIGNALS -I/usr/local/include

  ex.  On an RS/6000 you only need -DBSDSIGS
  --
         CFLAGS = -DBSDSIGNALS -I/usr/local/include

You should also add -O to CFLAGS, unless you really don't trust the
optimization phase of your compiler.

The line

TERMFLAGS =

is used to set which type of terminal control your OS uses.  From the
Makefile:

# Those flags needed to compile in the type of terminal
# control you have:
#
#   Use -DTERMIOS if you have <termios.h>, the POSIX terminal control.
#   Use -DTERMIO if you have <termio.h>, the SYSV terminal control.
#   Otherwise, we assume you have <sgtty.h>, the BSD terminal control.
#
# If you choose to use -DTERMIOS and have problems, try -DTERMIO.  On
# at least two systems I've tried, the vendor hasn't had all the
# include files set up correctly to include <unistd.h> together with
#  <osfcn.h> among others.
#
# On RS/6000s, AIX/370 and recent Suns, -DTERMIO works well.

  ex.  on a SYSV-based system
  --
         TERMFLAGS = -DTERMIO

  ex.  on a POSIX system
  --
         TERMFLAGS = -DTERMIOS

  ex.  on a BSD-based system
  --
         TERMFLAGS =

To control the screen, dired uses the termcap(3) library.  It used the
GNU Database Management Library  (GDBM) for low-level database
manipulations.  You'll need to link with both these libraries.  From
the Makefile we have:

LIBS =  -lgdbm -ltermcap

You shouldn't need to change this unless you don't have termcap(3).
If this is the case, try one of '-lterminfo' or '-lcurses'.

The macro HOMEBASE is used to control where "problem" stores its
databases, mailing lists, SEQUENCE file and AREA file.  It must be a
full pathname.  From the Makefile:

# Directory is which the databases, AREA file (this is the file, with
# one area per line, listing the valid problem areas), SEQUENCE file
# (this is the file used to keep the unique problem #), and
# MAILLIST.* files (which contains the names of interested parties)
# will be stored.

The macro MAILPROG is a version of mail.  It must be a full pathname.
If you haven't specified -DNOSUBJECT above, make sure this version of
mail accepts the "-s" flag to indicate a subject line.

  ex.  on AIX/370
  --
       MAILPROG = /bin/mail

  ex.  on a RS/6000
  --
       MAILPROG = /usr/bin/mail

Problem maintains some limit on the amount of text it will accept for
any initial problem log, or for any single append or close.  From
experience, this is important to keep people from putting lots of
exxtraneous information in their problem reports which does nothing
except cause the databases to grow excessively fast.  The size of this
limit is configurable by setting the MAXFILESIZE.  At the authors site
we use

MAXFILESIZE = 16000

Problem is designed to be run SUID from an account which has write
permission to the HOMEBASE directory.  This is so that it can update
its SEQUENCE file and mailing list files, without giving write access
to the world.  To start with, it is probably easiest to just make the
HOMEBASE directory writeable only by the "problem" administrator and
then make it SUID to that user.

Once you've edited Makefile, type 'make'.  Hopefully, the make will
complete with no errors and you will have a working "problem".  Then
move the executable "problem" to a suitable binary directory making
sure to set it up SUID to the owner of the HOMEBASE directory.  You
then need to add some areas to the AREA file.

A Word On GDBM:
--------------

Regarding GDBM, you'll need to do a bit of work to make it work from
C++ code.  Specifically, the gdbm.h file generated when GDBM is built
isn't callable from C++; it doesn't have the functions prototyped.
The file 'gdbm.h-proto' should be a dropin replacement for the gdbm.h
file generated on your system from GDBM version 1.5.  I've also sent
this to the author of GDBM so that future releases will hopefully be
both C and C++ compatible.

There is a potential problem with calling the GDBM functions on Suns
from C++ code if you use g++.  Basically, you need to compile GDBM and
"problem" with compilers from the same "family".  That is, if you
compile GDBM with gcc, you must compile "problem" with g++.  Likewise,
if you compiled GDBM with cc, you must use a Cfront-based compiler to
compile "problem".  Otherwise, "problem" will seg fault when you try
to call any of the GDBM functions.  The problem is due to incompatible
struct passing conventions between gcc and the native C compiler.  I'm
told that this has been fixed in gcc/g++ versions 2.0 and higher.
Moral: don't use a version of g++ lower than 2.0 on Suns.

A Note Regarding Portability:
----------------------------

Unfortunately, from experience, it appears that C++ code is much more
difficult to port than C code.  The main difficulty seems to be header
files.  Since every function must be prototyped before it is used, one
necessarily includes many system include files to properly prototype
functions, especially in an application such as "problem" which uses a
fair number of system services and library functions.  When one starts
including many include files, the inconsistencies of the files becomes
apparent.  The most common "bug" is when two different include files
prototype a function differently.  C++ compilers consider this as a
hard error.  The only thing to be done in this situation is to fix the
header file(s) and continue with the build process.

Another common difficulty is a header file which doesn't prototype a
function when in fact it should.  In this case your best bet is to
manually add the prototype to "problem.h".

Another more fundamental difficulty with include files is that they are
incompletely or inconsistently standardized.  ANSI C dictates the
contents of only fifteen include files which are meant to cover the C
library.  In order to use a function not covered by ANSI C, which, by
necessity, will include all operating system specific functions, one
must have some other scheme for deciding what file(s) to include.
Where ANSI C stops, "problem" development has followed the rules
proposed by POSIX 1003.1 as regards which file to include to get the
prototype of some system-specific function.  Not all systems follow or
even purport to follow the POSIX standard.

If nothing else, attempting to compile "problem" will probably point out
a number of deficiencies in the implementation of your header files.
Persevere and report all bugs to your vendor.


Mike Lijewski (W)607/254-8686 (H)607/272-0238
Goddard Space Flight Center
INTERNET: lijewski@rosserv.gsfc.nasa.gov
SMAIL:  446 Ridge Rd. Apt. 3, Greenbelt, MD  20770
