Notes on play configuration
---------------------------

There are two configuration files:

config.h       - #defines for source code in play/*/*.[ch]
../../Make.cfg - Makefile definitions required to compile or load
                 (common to all packages)

Both of these can hopefully be computed by the config.sh script; if
not, you may be able to do the job by hand.

------------------------------------------------------------------------
_POSIX_SOURCE, _XOPEN_SOURCE_EXTENDED, _HPUX_SOURCE macros:

I want to try to use the POSIX standard whenever possible and
applicable.  System header files known to be affected on some systems
include:
<signal.h>, <dirent.h>, <sys/types.h>, <unistd.h>, <pwd.h>, <time.h>

The files files.c and ugetc.c need _POSIX_SOURCE before <stdio.h> in
order to get the fileno macro declared.  The dir.c, pathnm.c,
usernm.c, and uinbg.c files use explicitly POSIX functions and also
declare the macro.

A few play features are implemented using non-POSIX functions.  At
these places in the source code, I undef _POSIX_SOURCE.  The timers
gettimeofday (timew.c) and getrusage (timeu.c) are the only examples
so far; HPUX additionally needs _HPUX_SOURCE in the former case.

The poll/select functions in uevent.c and upoll.c are the other
non-POSIX routines and have caused some problems.  HPUX wants
_HPUX_SOURCE defined, and Digital UNIX wants _XOPEN_SOURCE_EXTENDED
defined in order to pick up the poll.h header correctly.

A yorick package using a specifically POSIX feature should declare
_POSIX_SOURCE before any other includes.  If a specifically non-ANSI
feature is used, _POSIX_SOURCE should be undef'd after config.h but
before any system headers are included (note that pstdio.h and
pstdlib.h indirectly include system headers).
------------------------------------------------------------------------

#define USE_GETRUSAGE
-or-
#define USE_TIMES
-or-
neither

------------------------------------------------------------------------
On systems which have the BSD getrusage function, it generally provides
the most accurate CPU timer (much better than the POSIX times often).
The POSIX times function is an alternative; if neither is defined, the
timeu.c source falls back to the ANSI clock function.
------------------------------------------------------------------------

/* play/unix/timew.c- specify which wall timing function to use
 *   - gettimeofday needs <sys/time.h>
 *   - if undefined, will use ANSI C time and difftime functions */
#define USE_GETTIMEOFDAY
-or-
nothing

------------------------------------------------------------------------
The BSD gettimeofday routine is the preferred wall clock timer; it is
the one used universally by the X11 library, so you ought to get
agreement between X server times and p_wall_secs with it.  The
fallback in timew.c if USE_GETTIMEOFDAY is not defined is the ANSI C
time and difftime functions.
------------------------------------------------------------------------

nothing
-or-
#define NO_PASSWD

------------------------------------------------------------------------
The POSIX getlogin, getpwuid, and getuid functions permit expansion of
~user/... pathnames (pathnm.c).  If these functions are not present,
define NO_PASSWD and that functionality will be disabled.  This also
affects the p_getuser function (usernm.c), which falls back to the
deprecated cuserid function if NO_PASSWD is defined.
------------------------------------------------------------------------

nothing
-or-
#define USE_TIOCGPGRP_IOCTL <sys/termios.h>
-or-
#define USE_TIOCGPGRP_IOCTL <sgtty.h>

------------------------------------------------------------------------
If the POSIX tcgetpgrp function is missing (used to determine whether
the program is running as a background task in uinbg.c), define
USE_TIOCGPGRP_IOCTL as the name of the system header file which
defines the TIOCGPGRP ioctl.
------------------------------------------------------------------------

nothing
-or-
/* play/unix/dir.c- use getwd instead of POSIX getcwd */
#define USE_GETWD

------------------------------------------------------------------------
If the POSIX getcwd function is missing (used to find current working
directory in dir.c), define USE_GETWD to use getwd instead.
------------------------------------------------------------------------

nothing
-or-
#define DIRENT_HEADER <sys/dir.h>
-or-
#define DIRENT_HEADER <sys/ndir.h>
-or-
#define DIRENT_HEADER <ndir.h>

------------------------------------------------------------------------
If the POSIX dirent.h header is missing or broken, define DIRENT_HEADER
as the name of the system header file containing the directory handling
functions.  See dir.c more more.
------------------------------------------------------------------------

nothing
-or-
#define USE_SYS_POLL_H

-or-

#define USE_SELECT
-and-
nothing
-or-
#define HAVE_SYS_SELECT_H
-or none, one, or both of-
#define NO_SYS_TIME_H
#define NEED_SELECT_PROTO

------------------------------------------------------------------------
To handle multiple input sources, you need either the poll function or
the select function.  I prefer the poll interface (and select was
apparently broken on at least one IRIX system).  If <poll.h> exists,
you don't need any defines; if <sys/poll.h> exists, define
USE_SYS_POLL_H.

If poll is missing or you need to use select instead (upoll.c implements
a barebones poll in terms of select), define USE_SELECT.  In that case,
define HAVE_SYS_SELECT_H if <sys/select.h> is present; otherwise you
may need to define NO_SYS_TIME_H (you will need either <sys/time.h> or
<time.h>).  You may also need to define NEED_SELECT_PROTO.

See uevent.c and upoll.c for more.
------------------------------------------------------------------------

in config.h:
-exactly one of-
#define FPU_DIGITAL
#define FPU_AIX
#define FPU_HPUX
#define FPU_IRIX
#define FPU_SUN4
#define FPU_SOLARIS
#define FPU_UNICOS
#define FPU_ALPHA_LINUX
#define FPU_GCC_I86
#define FPU_GCC_POWERPC
#define FPU_GCC_SPARC
#define FPU_GCC_M68K
#define FPU_GCC_ARM
#define FPU_IGNORE

in config.mak:
FPELIB =
-or-
FPELIB = -lsunmath
-or-
FPELIB = -lfpe

------------------------------------------------------------------------
UNIX systems usually do not deliver SIGFPE (floating point exception
signals) by default.  The code to turn on SIGFPE delivery is highly
system dependent.  You must define exactly one of the above symbols
in order to compile fpuset.c.  The fputest.c program will tell you if
you have succeeded in turning on SIGFPE delivery (config.sh runs it).

FPU_HPUX, FPU_SUN4, and FPU_UNICOS require routines in libm (-lm).

FPU_SUN4 may require libsunmath (-lsunmath), and FPU_IRIX requires
libfpe (-lfpe).  In these two cases, the config.mak file will set the
FPELIB flag to the required loader option.  Otherwise, FPELIB will be
set to nil.
------------------------------------------------------------------------

in config.mak:

XINC =
-or-
XINC = -Ipath_to_X11/Xlib.h

-and-

XLIB =
-or-
XLIB = -Lpath_to_libX11

------------------------------------------------------------------------
The X11 headers and libraries may be hidden from the compiler without
appropriate -I and -L options, which are written into config.mak.
------------------------------------------------------------------------
