1Notes on play configuration
2---------------------------
3
4There are two configuration files:
5
6config.h       - #defines for source code in play/*/*.[ch]
7../../Make.cfg - Makefile definitions required to compile or load
8                 (common to all packages)
9
10Both of these can hopefully be computed by the config.sh script; if
11not, you may be able to do the job by hand.
12
13------------------------------------------------------------------------
14_POSIX_SOURCE, _XOPEN_SOURCE_EXTENDED, _HPUX_SOURCE macros:
15
16I want to try to use the POSIX standard whenever possible and
17applicable.  System header files known to be affected on some systems
18include:
19<signal.h>, <dirent.h>, <sys/types.h>, <unistd.h>, <pwd.h>, <time.h>
20
21The files files.c and ugetc.c need _POSIX_SOURCE before <stdio.h> in
22order to get the fileno macro declared.  The dir.c, pathnm.c,
23usernm.c, and uinbg.c files use explicitly POSIX functions and also
24declare the macro.
25
26A few play features are implemented using non-POSIX functions.  At
27these places in the source code, I undef _POSIX_SOURCE.  The timers
28gettimeofday (timew.c) and getrusage (timeu.c) are the only examples
29so far; HPUX additionally needs _HPUX_SOURCE in the former case.
30
31The poll/select functions in uevent.c and upoll.c are the other
32non-POSIX routines and have caused some problems.  HPUX wants
33_HPUX_SOURCE defined, and Digital UNIX wants _XOPEN_SOURCE_EXTENDED
34defined in order to pick up the poll.h header correctly.
35
36A yorick package using a specifically POSIX feature should declare
37_POSIX_SOURCE before any other includes.  If a specifically non-ANSI
38feature is used, _POSIX_SOURCE should be undef'd after config.h but
39before any system headers are included (note that pstdio.h and
40pstdlib.h indirectly include system headers).
41------------------------------------------------------------------------
42
43#define USE_GETRUSAGE
44-or-
45#define USE_TIMES
46-or-
47neither
48
49------------------------------------------------------------------------
50On systems which have the BSD getrusage function, it generally provides
51the most accurate CPU timer (much better than the POSIX times often).
52The POSIX times function is an alternative; if neither is defined, the
53timeu.c source falls back to the ANSI clock function.
54------------------------------------------------------------------------
55
56/* play/unix/timew.c- specify which wall timing function to use
57 *   - gettimeofday needs <sys/time.h>
58 *   - if undefined, will use ANSI C time and difftime functions */
59#define USE_GETTIMEOFDAY
60-or-
61nothing
62
63------------------------------------------------------------------------
64The BSD gettimeofday routine is the preferred wall clock timer; it is
65the one used universally by the X11 library, so you ought to get
66agreement between X server times and p_wall_secs with it.  The
67fallback in timew.c if USE_GETTIMEOFDAY is not defined is the ANSI C
68time and difftime functions.
69------------------------------------------------------------------------
70
71nothing
72-or-
73#define NO_PASSWD
74
75------------------------------------------------------------------------
76The POSIX getlogin, getpwuid, and getuid functions permit expansion of
77~user/... pathnames (pathnm.c).  If these functions are not present,
78define NO_PASSWD and that functionality will be disabled.  This also
79affects the p_getuser function (usernm.c), which falls back to the
80deprecated cuserid function if NO_PASSWD is defined.
81------------------------------------------------------------------------
82
83nothing
84-or-
85#define USE_TIOCGPGRP_IOCTL <sys/termios.h>
86-or-
87#define USE_TIOCGPGRP_IOCTL <sgtty.h>
88
89------------------------------------------------------------------------
90If the POSIX tcgetpgrp function is missing (used to determine whether
91the program is running as a background task in uinbg.c), define
92USE_TIOCGPGRP_IOCTL as the name of the system header file which
93defines the TIOCGPGRP ioctl.
94------------------------------------------------------------------------
95
96nothing
97-or-
98/* play/unix/dir.c- use getwd instead of POSIX getcwd */
99#define USE_GETWD
100
101------------------------------------------------------------------------
102If the POSIX getcwd function is missing (used to find current working
103directory in dir.c), define USE_GETWD to use getwd instead.
104------------------------------------------------------------------------
105
106nothing
107-or-
108#define DIRENT_HEADER <sys/dir.h>
109-or-
110#define DIRENT_HEADER <sys/ndir.h>
111-or-
112#define DIRENT_HEADER <ndir.h>
113
114------------------------------------------------------------------------
115If the POSIX dirent.h header is missing or broken, define DIRENT_HEADER
116as the name of the system header file containing the directory handling
117functions.  See dir.c more more.
118------------------------------------------------------------------------
119
120nothing
121-or-
122#define USE_SYS_POLL_H
123
124-or-
125
126#define USE_SELECT
127-and-
128nothing
129-or-
130#define HAVE_SYS_SELECT_H
131-or none, one, or both of-
132#define NO_SYS_TIME_H
133#define NEED_SELECT_PROTO
134
135------------------------------------------------------------------------
136To handle multiple input sources, you need either the poll function or
137the select function.  I prefer the poll interface (and select was
138apparently broken on at least one IRIX system).  If <poll.h> exists,
139you don't need any defines; if <sys/poll.h> exists, define
140USE_SYS_POLL_H.
141
142If poll is missing or you need to use select instead (upoll.c implements
143a barebones poll in terms of select), define USE_SELECT.  In that case,
144define HAVE_SYS_SELECT_H if <sys/select.h> is present; otherwise you
145may need to define NO_SYS_TIME_H (you will need either <sys/time.h> or
146<time.h>).  You may also need to define NEED_SELECT_PROTO.
147
148See uevent.c and upoll.c for more.
149------------------------------------------------------------------------
150
151in config.h:
152-exactly one of-
153#define FPU_DIGITAL
154#define FPU_AIX
155#define FPU_HPUX
156#define FPU_IRIX
157#define FPU_SUN4
158#define FPU_SOLARIS
159#define FPU_UNICOS
160#define FPU_ALPHA_LINUX
161#define FPU_GCC_I86
162#define FPU_GCC_POWERPC
163#define FPU_GCC_SPARC
164#define FPU_GCC_M68K
165#define FPU_GCC_ARM
166#define FPU_IGNORE
167
168in config.mak:
169FPELIB =
170-or-
171FPELIB = -lsunmath
172-or-
173FPELIB = -lfpe
174
175------------------------------------------------------------------------
176UNIX systems usually do not deliver SIGFPE (floating point exception
177signals) by default.  The code to turn on SIGFPE delivery is highly
178system dependent.  You must define exactly one of the above symbols
179in order to compile fpuset.c.  The fputest.c program will tell you if
180you have succeeded in turning on SIGFPE delivery (config.sh runs it).
181
182FPU_HPUX, FPU_SUN4, and FPU_UNICOS require routines in libm (-lm).
183
184FPU_SUN4 may require libsunmath (-lsunmath), and FPU_IRIX requires
185libfpe (-lfpe).  In these two cases, the config.mak file will set the
186FPELIB flag to the required loader option.  Otherwise, FPELIB will be
187set to nil.
188------------------------------------------------------------------------
189
190in config.mak:
191
192XINC =
193-or-
194XINC = -Ipath_to_X11/Xlib.h
195
196-and-
197
198XLIB =
199-or-
200XLIB = -Lpath_to_libX11
201
202------------------------------------------------------------------------
203The X11 headers and libraries may be hidden from the compiler without
204appropriate -I and -L options, which are written into config.mak.
205------------------------------------------------------------------------
206