Building the Blind executable:

global.h is a header file that I added to get gcc -Wall to shut up
about Sun's non-ansi header files & such. Depending upon your OS, it
will attempt to include an OS specific one as well. You may not need 
it, but this should only be a problem on an OS I've not tried to
compile the code on. In particular, the prototypes may conflict with 
those on your system.  Should you get errors about conflicting types 
as a result of this file, you can delete the offending line out of 
global.h (or the included OS specific one) without breaking anything
(you may get warnings from the compiler about implicit declariations as a 
result, fix them or not). Different versions of gcc (2.3.3 and 2.5.8 for 
example) define different prototypes, so a few changes may be needed in 
global.h. In general, for the OSs that I've tested, with a recent
version of GCC (2.7.2 or later, at present), this should not be a problem.

If you have gdb (the GNU debugger) you can set DBGFLAGS to -ggdb instead
of -g while debugging. Due to the cranky nature of the code, I recommend 
running the first couple of turns (3 or so) after installing a version with 
unoptimized code, and with debugging info on. Except for turns where there 
are major battles, the code seldom takes more than a minute or two to run a 
turn (sans report writing and data file reading/writing, which can take 
several minutes) on a sun 4 (IPX or Sparc 20 at the moment), so I personally 
don't optimize the code or turn debugging info off.

You will probably want to build three copies of the Blind program. One copy
for the GM's use, which has complete access to the datafile, and a second
"preprocessor" which has more limited access (in particular, it can not write
over the datafile, all it can do is help you to weed out player errors).
The third copy is needed to create the game's datafile and can be deleted after
you've created the game.

If you are going to be running the game where the player's e-mail you orders,
you'll probably want to have a preprocesor set up so that they can access
it. There are copies of the scripts that I use to do that for my games 
included in the distribution. What documatation there is for it is included
(I don't encourage the use of the scripts, they work well, but are poorly
written, and should really be replaced).

The following options are available to be changed in the Makefile:

 Game specific compile flags:
   -DINTERACTIVE - user prompted again for parts of commands that are incorrect,
            rather than having them tossed. This option is not supported,
            and may go away in the future.
            Default: off

 [All the flags below where added by Howard Bampton (bampton@cs.utk.edu):]

                 ++++ GM helper flags ++++

   -DBACKUPS Make backup copy of data file on exit. The backup file
           will be named 'blindrc.<turnnumber>.bak' Implies
           PREPROC not defined.
           Default: off
           TESTED (provided the system call works, no error checking)

   -DREPORTDIR=\"directory\" Reports will be written to directory, instead
           of the current one.
           Default: off
           TESTED (fails if direcotory isn't writable/there)

   -DGAMENAME Allows you to save the gamename into the blindrc file
           Default: off
           **** MODIFIED DATAFILE ****

   -DFCASTNAMES forecast reports by default are named "forecast.F"
           Enabling this option, will cause them to be named.
           <empirename>.F [with naming restrictions similar to
           normal reports- spaces, back tics, quotes all get stripped.]

   -DVERBOSE Prints out status info (phases in particular) while 
           running a turn.
           Default: on
           TESTED

                 ++++ New game flags ++++

   -DNEWGAME This includes the functions for creating a new game. It is
           no longer used by most of the code, other than the version file.
           Implies PREPROC not defined.
           Default: off
           TESTED

   -DRANDPLACE If defined, random player placement is done (otherwise
           GM enters locations). This option is only of use if you are
           creating a new game. Implies PREPROC not defined.
           Default: off
           TESTED

   -DMINSEP=# sets the minimum separation between players to #LY, requires
           -DRANDPLACE. Implies PREPROC not defined.
           This option only has to be defined if you are creating a new
           galaxy, and wish to change the default value of 20LY (in
           the code, 30 or so in the Makefile).
           Default: off
           TESTED, typical values range from 20-40LY. (25-30 is best?)


   -DBALANCE If defined, attempts to "Balance" the planet distribution
           in a "fair" manner. Check doc/Starting-a-game for a discussion
           of what I am doing with the Balance option. It is strongly
           recomended that you use this option. Note: This may
           substantially increase the ammount of time it takes to
           create a galaxy.
           Default: off
           TESTED

                 ++++ Optional features ++++

   -DKCMD  Adds the K-command (allowing you to set war/peace status on
           a per planet/per empire basis).
           Default: on
           *** Modified data files. ***
           TESTED


   -DCARRYOVER *** This switch is no longer used, it is always enabled
           keeps track of opposing player's & their tech levels from 
           turn to turn.

   -DV3    *** This switch is no longer used, it is always enabled
           Include more V3 compatibility. Changed weapon mass, population 
           to industry mods, new cargo rules, battle summary [left over 
           ships], map sizing code

   -DNEW   *** This switch is no longer used, it is always enabled
           Adds upgrade code, and potential for selective planet defense code.
           Also adds scrap command, ships in production tables, limited options
           the code with, for example, V3 defined and NEW not defined.

   -DUPGRADE *** This switch is no longer used, it is always enabled
           Fleets, partial techs (potential for this, see below), 
           ships built in a class, etc. 

   -DPTECH Adds code for 'Partial techs'. Check the rules for details.
           Mostly TESTED (use at own risk, appears to work)

                 ++++ Bug Workarounds ++++

   -DBOMBBUG *** This switch is no longer supported after 2.45**
           The save/load game functions don't save the ID of the
           person who bombed a planet. If you are running a game created
           under a version before 2.37, define this.
           Implies UPGRADE not defined 
           *** Modified data files. ***

   -DSIZEBUG For reasons unknown, sizeof(shiptype) doesn't change when
           you add the UPGRADE numbuilt data to shiptype, so it can not
           read the data file. This works around that bug.

   -DNONAMEBUG *** This switch is no longer used, it is always enabled
           This changes the time that the C command takes effect.

                 ++++ Preprocesor options ++++

   -DPREPROC if you are using a preprocessor (returns error code==
           #errors encountered, extra newlines, reduced top level
           command set) This implies INTERACTIVE not defined...
           TESTED

   -DSMART  OBSOLETE

   -DFORECAST Adds functions to allow forecasts of next turn's status
           to be made & mailed. Note: this slows down execution speed
           by a large amount, since it is potentially writing a report
           every time the program is run.
           Implies PREPROC defined (pointless without it).
           TESTED 

                 ++++ Experimental, under construction ++++

   -DSPEED=? Experimental code, primarily intended (at
           present) to speed up the forecaster. See "Using the SPEED
           code" below for details. This appears to be stable.

   -DSMARTC Allows the C command to rewrite the races:players file (if
           you use it) with new empire names. This code has not been
           fully tested.

   -DPASSWORDS Allows the Y (password) command. Passwords are assumed
           to be in races:passwords. This code sometimes misbehaves
           when passwords are set/unset, or in conjunction with a C
           command.

   -DNEW[1-3]  Experimental code, use at own risk (may not work or compile)
            Once it works, it is merged into either -DUPGRADE, or given it's
            own flag.

   -DBLINDCARRY Planned new feature. May be renamed.

                 ++++ Reserved, for internal use ++++

   -DNOTIMEB
   -DIO    Do not use these flags. It is for playing fancy games with header
           files, or updating data files.

   -DPASSWORDFILE - The name of the password file, if passwords are used.

                 ++++ OS specific compile options: ++++

            Note: Define only 1 of these. Defining 0, or more than 1
            may cause strange behavior.

   -DSUNOS4 If you are compiling on a Sun running SunOS 4.1 through 4.1.4,
            define this. It might also work on a SunOS 4.0 box, but I no
            longer have access to one. This is NOT "SunOS 5.x" aka
            Solaris 2.x. Those that have been brainwashed may also
            call SunOS 4.1.x Solaris 1.y "uname -a" should show something like:
            SunOS plsu144 4.1.4 6 sun4c
                           ^--- SunOS 4.1.x

   -DHPUX9  If you are using HP-UX 9.03 (or 9.05), define this. It will 
            probably work under 8.07 and other flavors of 9.x as well. 
            "uname -a" should show something like: 
            HP-UX plhp666 A.09.03 A 9000/735 2016356359 two-user license
                            ^--- HP-UX 9.03

   -DSOLARIS If you are compiling on a Solaris 2.x machine, aka "SunOS
            5.x" define this.  Do not define the SUNOS4 flag! I tested 
            this on a Solaris 2.5 box. "uname -a" should show
            something like: 
            SunOS plsu001 5.4 Generic_101945-36 sun4d sparc
                          ^--- Solaris 2.4

   -DULTRIX The Ultrix boxes I tested this on did not have a strdup()
            function. This compile switch provides one. 
            There are actually two- one I wrote (which works now), 
            and one from Mr SJ Murphy <sjmur2@aurora.cc.monash.edu.au>
            which replaces mine (which didn't work at the time).
            Both are in misc.c. Take your pick, one should work.
            11/20/94 Addendum: my strdup function had the args to
            memcpy() backwards.
            Note: Ultrix's make appears to be stupid. All the @if
            stuff has to go for the targets to build.
            "uname -a" should show something like:
            ULTRIX wilma 4.4 0 RISC
                         ^-- Ultrix 4.4

   -DAIX    If you want to use an AIX machine (I tried a Risc6000, 3.25 box)
            Start with this flag. "uname -a" will show something like:
            AIX vose 2 3 000056881000

   -DLINUX  This might work for Linux. Give it a try. The machines I
            currently have tried this on have a 2.0.2[79] kernel.
            Note that I've only tested this on x86 flavors of Linux.

   -DOSF1   This is used for OSF1 V4.0. Note that the port is incomplete.
            Dumbing down the compiler flags seems to work (i.e. take
            out -ansi -pedantic and the paranoid ones). "uname -a" output
            OSF1 ig V4.0 464 alpha
                    ^--- 4.0

   -DIRIX5  This appears to work for IRIX5.3.
            Note: IRIX's make appears to be stupid, even compared to Ultrix's. 
            All the @if stuff has to go for the targets to build.
            "uname -a":
            IRIX blueberry 5.3 11091812 IP22 mips

   -DIRIX6  This appears to work for IRIX6.2.
            Note: IRIX's make appears to be stupid, even compared to Ultrix's. 
            All the @if stuff has to go for the targets to build.
            

Notes:
   *** Modified data files. ***
      If you use an option marked as this, you will be unable to read the data
   file unless you have those options compiled into the executable.
   I.e. A blindrc written by a Blind executable compiled with -DNEW
   can't read a blindrc file with -DNEW, -DCARRYOVER. 
      There are some exceptions- adding -DKCMD to one with -DNEW, 
   works (but no the other way around).

Once you've decided what features listed above you want, edit the makefile,
and look for this line:
# Comment out lines which have undesired compile flags

comment out (with #'s) those features you do not want.

The current makefile has all its own dependencies, so there is no need to 
use makedepend. If you are not using a sun running SunOS 4.1.? on a sun4
platform, you may need to make additional changes. Likely changes (more 
detail in the relevant chunk of the Makefile): CCPIPE should be undefined
on sun3's and Ultrix 4.3, 4.4 machines; CC if you want to use something
other than gcc (good luck)


++++++

After that you are ready to go type (For the lazy, see the section labeled
"Lazy Compiling").

There are 3 executables you are likely to want:
1) One for creating new games
2) One for running games in progress
3) One for preprocessing player orders

For making a new game, you will want to make the target 'New-game', by typing
make New-game
[After deciding on features to enable, as well as the features relating to
how you want to create a new game.] If all goes well, there will be an
executable named "New-game" when the compilation finishes. See the file
doc/Starting-a-game for what to do now.

make Blind
[for running an inprogress game]
If all goes well, you will have a file named "Blind". 
Change the PROGRAM variable in the makefile if you want it named 
something else.

Note:
  If NEWGAME is defined, you _must_ do "make New-game".

for making the preprocessor, type (after changing the makefile as
desired): make blind.dbg
which will produce the file blind.dbg Change the PREPROC variable in 
the makefile if you want it named something else. If you use the FORECAST
option, do a "make dbg-plus" instead (the forecast option requires an
additional file to be compiled)

Note:
  Doing a "make" with PREPROC defined will generate errors when it gets
to the final stage of compiling (it will be unable to resolve the symbols
sterilize and frand). If PREPROC is defined, you _must_ do
"make blind.dbg" or "make dbg-plus"

WARNING: gnu's make does not honor the ".KEEP_STATE" directive in the
makefile. You will either have to do a make clean every time you change the
Makefile, or add a dependency of all the .o files on the Makefile.
[They are commented out at the end of the current makefile]
If you can't stand doing that, do as suggested in Lazy Compiling.

++++++
Lazy Compiling

If you absolutely hate editing the makefile all the time to switch between
compiling a Blind and blind.dbg executable, enable the features you want 
in the Makefile (with or without the preprocessor options). 

Edit support/Compile-all to build a forecasting blind.dbg (or not).

Run support/Compile-all from the same directory as the C source code.
It will build Blind and blind.dbg executables for you. Note: This is slower
than editing the makefile, since it compiles both programs from scratch.

++++++

Installing

I don't install it myself using the Makefile, but if you wish, edit
INSTALLDIR in the Makefile to point to the right place, and do a
make install after you have a Blind and blind.dbg executable.

Warning: make install will NOT check for Blind and blind.dbg being up
to date, nor will it make backup copies of the old executables.

++++++

Summary of common make options:
make Blind      - "normal" game executable
make New-game   - for creating new games (includes game creation code)
make blind.dbg  - for the original preprocessor (obsolete)
make dbg-plus   - for the preprocessor with the FORECAST code
make clean      - deletes cruft
make very-clean - deletes all cruft - core *.o blindrc forecast.F Blind
                  blind.dbg New-game Edit

++++++

File descriptions:
Blind.c         The "main" file.
addplayer.c     Code for adding new players, not needed after first turn.
battle.c        Combat/bombing section of the code
cmds.c          The command entering/parsing code.
edit.c          Prototype of a data file editor.
enterturn.c     Name to number functions, plus support functions for cmds.c
loadgame.c      loading game functions
misc.c          miscellany
new-game.c      start a new game code (planet stuff)
new-galaxy.c    start a new game code (main driver)
report.c        report printing code
savegame.c      saving game functions
turn.c          turn running code (sans battle code).
version.c       info on compile options, rcsid stuff
report/Battle.c report writing code for battles
report/gm.c     report writing code for gm snooping functions
report/Main.c   main report writing code and misc functions for it
report/map.c    report writing code for maps
report/planets.c report writing code for system printing
report/ships.c  report writing code for ship printing
report/status.c report writing code for player status
cmds/Cmds-lib.c misc functions for parsing player commands
cmds/?.c        code to deal with the command (e.g. a.c for the "A" command)
protos/*        Prototypes for various functions, and data structure definitions
protos/global.h   Shut up gcc -Wall prototypes 
protos/sunos4.h   Prototypes for SunOS 4.1.x specific functions.
protos/solaris2.h Prototypes for Solaris 2.x specific functions.
protos/hpux9.h    Prototypes for HP-UX 9 specific functions.
protos/ultrix.h   Prototypes for ultrix 4.4 specific functions.
protos/aix.h      Prototypes for AIX specific functions.
util/blindrc-to-ascii.c Blindrc to ascii converter (see Notes for details)
util/ascii-to-blindrc.c Ascii to blindrc converter
util/edit.c     blindrc file editor. Very primative, not complete by any means.



+++++++
Compiler errors/warnings:

  If SPEED is an odd value, expect to see this:
loadgame.c: In function `Read':
loadgame.c:79: warning: pointer of type `void *' used in arithmetic

From most OS's (not SunOS 4, however):
Blind.c: In function `main':
Blind.c:129: warning: passing arg 1 of `_flsbuf' with different width
due to prototype

  On my test Sun's, with gcc -Wall, these are the errors that you'll get.
All of these errors can be safely ignored:

Blind.c: warning: implicit declaration of function `_flsbuf'

From several files (savegame,new-game,new-galaxy,addplayer):
global.h:42: warning: `struct timeb' declared inside parameter list
global.h:42: warning: its scope is only this definition or declaration,
global.h:42: warning: which is probably not what you want.

This appears to only happen under gcc 2.5.8 and older:
report-main.c: In function `spf':
report-main.c:64: warning: precision and `0' flag both used in one %-sequence
report-main.c: In function `ff':
report-main.c:141: warning: precision and `0' flag both used in one %-sequence

For OSF1:
Lots of warnings about:
passing arg x of function with differernt width due to prototype 
passing arg x as unsigned due to prototype
as0: Warning: /tmp/blah line 1: extraneous values on version stamp ignored

Port is preliminary and UNTESTED.

Any other errors/warnings should to be checked into, but probably are
not serious.

+++++++++ Troubleshooting the compile process ++++++

1) I get gazilions of errors on the system's header files.
   A: Have your sys-admin run "fixincludes". gcc -ansi
      doesn't like certain vendor's header files (Sun OS 4.x)
   A2: Drop the -ansi flag from the CFLAGS
   A3: This is an OS I haven't expermiented with yet. As long as they
       are Warnings, you can probably get away with it.

2) I get warnings about -Wconversion -Wmissing-prototypes
    -Wstrict-prototypes or -ggdb being unknown flags from gcc/gcc-cc1
   A: You are using an old version of gcc. Upgrade (:-)
   A2: Drop them. They are intended to warn you of brain death on
       my part, and inconsistences between header files. You will need
       to replace "-ggdb" with "-g" 

3) I can't get an executable under Ultrix 4.3/4.4, even though you claim
   it will compile.
   A: The idiot checking in the Makefile tickles a misfeature of Ultrix.
      You can get the Makefile to work correctly if you remove the code
      between the @if and fi blocks for the the Blind, New-game etc targets.
   A: Gnu make might not cause the problem.

4) When I tried to read in the blindrc file, I got this error:
   Reading game from file blindrc...Can't read # bytes from file,
   returncode = #.
   A: This has two main causes:
      a) You are using a blindrc file from a different hardware
         platform (i.e. a Sun4 blindrc file on a Sun3). A workaround
         for this problem is planned for 2.50. There exists a
         blindrc->ascii and ascii->blindrc converter that will solve this 
         (at the risk of munging some data).
      b) You used a compile flag which modifies the data file format
         this time that you did not when you created the blindrc file
         (or forgot to this time, when you had). The 2.50 release will
         also try to fix this too.

++++++

Using the SPEED code
  
By compiling the code with profiling on, and examining the output, it
was noticed that two time consuming blocks of code existed in the 
loadgame() code specifically:
   Read()'s calls to the system call read()),
   the numtop() calls to rebuild linked lists.
sortphase() in midgame situations also chewed up massive ammounts of CPU time

defining SPEED=1 only enables the Read() speedup,
defining SPEED=2 only enables the numtop() speedup.
defining SPEED=4 only enables the sortphase() speedup.
defining SPEED=8 only enables the canseeplanet() speedup.
compiling with SPEED=15 turns on all of these functions, 
 
                 Forcaster %                      Forcaster  Time
            Std   Speed=1 Speed=2 Speed=3   Std   Speed=1 Speed=2 Speed=3
loadgame    8.8     4.5     4.7     0.7    7.32    3.56    3.67     0.55
Read        4.2     0.3     4.0     0.4    3.53    0.31    3.12     0.32
numtop      4.0     3.8     0.2     0.0    3.35    2.98    0.15     0.05
report      8.2     8.8     8.5     8.8    6.84    6.99    6.65     6.63
sortphase  71.2    74.2    74.6    77.4   59.51   58.84   58.65    58.56
total                                     85.53   79.28   78.66    75.71


In order to make use of the numtop code, several constants need to be
defined in protos/speed.h:
  MAXPLAN - the maximum number of planets that you will have in a
galaxy, plus 1
  MAXPLAY - same, except players
  MAXSHIP - an approximate number of shiptypes that will exist at any
one time, per player.

Both MAXPLAN and MAXPLAY can be larger than the actual number of
players/planets (wasting a bit of memory), but can not be smaller. 
MAXSHIP should be about right but can be too low, at the price of the 
code being slower (it will fail back to the unhacked lookup method). In 
theory, if MAXPLAN or MAXPLAY are set too low the game should intentionally
crash, rather than allowing you to run with an executable which could
corrupt your blindrc file.

This test was done when the sortphase() code was changed, since the
other code was not, I didn't see much point in redoing my datapoints
(nor does a larger table make much sense). Note the the other tests
were done using the forecaster, while this was done using the GM
executable, and running a turn. Therefore, since there is the overhead
of actual combat plus writing multiple reports, the SPEEDUP code
should be understated in its impact, since it is intended to influence
the forecaster more than the GM binary.

Normal exectable         %                        Time
             Std Std,O4 Speed=7 Speed=7,O4    Std  Std,O4 Speed=7 Speed=7,O4
sortphase   37.5   26.8     0.3        0.2 111.19   55.44   0.59    0.31
report      32.3   38.8    53.6       59.2  95.76   80.34  96.96   91.25
fightphase  22.6   25.5    37.0       32.3  67.16   52.72  67.03   49.76
loadgame     2.4    2.2     0.3        0.2   7.03    4.51   0.46    0.30
Read         1.2    1.5     0.3        0.2   3.60    3.18   0.16    0.43
numtop       1.0    0.6     0.0        0.0   3.04    1.16   0.01    0.02
total                                      296.58  207.08 180.92  154.11
