warning on grass alpha port

[James Ganong]

There is a problem in the script long2LONG, which can make a mess out
of your source directory.  Some users do not have /lib in their path,
and the script long2LONG uses cpp, without giving a full path name.  I
have fixed it by having it use /lib/cpp, and put the new version on my
anonymous ftp site ohlone.ced.berkeley.edu in
/pub/grass/grass-alpha-axp-0.3.tar.Z.  If you have been using the
previous version successfully there is no reason to upgrade.

by James Ganong, jeg at ced.berkeley.edu, (510)849-1909 

AVAILABILITY

You can get it by anonymous ftp from ohlone.ced.berkeley.edu
in /pub/grass/grass-alpha-axp-0.3.tar.Z
If you use this port, please write me (jeg at ced.berkeley.edu) and
say hi.  If you have problems I will probably be able to help.

INSTALLATION

install the patch file
cd to the directory where you unpacked the grass4.1 update 3 distribution.
% zcat grass-alpha-axp-0.3.tar.Z | tar -xvf -
% patch < grass-alpha-axp-0.3/patches.grass.axp

patches.grass.axp contains all the manual edits (see below for program
to make automatic global substitutions) i made to the standard grass.
the following patch files might also be useful to you:

grass-alpha-axp-0.3/patches.xgre.bugs 
	patches xgre cell editor bugs found in alpha axp port
	xgre is not part of the GRASS distribution yet
	if you want this package,
	get it by anonymous ftp from
	ohlone.ced.berkeley.edu:/pub/grass/xgre.tar.Z

grass-alpha-axp-0.3/patches.xdriver.24bit 
	these changes are duplicated in patches.grass.axp
	they are kept here separately also because they are
	potentially useful as a separate release for
	sites that have 24 bit graphics but no alpha axps.
	allows XDRIVER to use 24 bit truecolor hardware 
	to do typical GRASS 8 bit graphics,
	admittedly not an ideal solution,
	but better than restarting your X server in 8 bit mode
	does not change normal operation on 8 bit displays,
	except it might fix a bug or two.

run grass-alpha-axp-0.3/long2LONG on the patched sources.
this does global substitutions to make long into LONG
and %ld in a scanf to "LDSET".
it descends the current directory and scans every *.c and *.h file 
in the current directory and every subdirectory.

run src/CMD/utils/setup program as patched by patches.grass.axp
to make an head file that will work on an alpha.
these changes are mostly cc options to get it to compile.

copy grass-alpha-axp-0.3/local to src/CMD/lists/local
it lists xgre at the end, so if you don't have this package
comment it out.

do a GISGEN.axp (or GISGEN.whatever_you_called_it_when_you_ran_setup)

try it out!  please send buggestions to jeg at ced.berkeley.edu

if you find bugs and fix them in the globally substituted code,
you can use grass-alpha-axp-0.3/filterdiff to make a patch file
that looks like it is relative to the original state of the code
before the global substitutions.
this way the diffs are applicable to all grass installations.
to use filterdiff you need to have a two copies of the grass source directory,
the one you have modified, and a clean unchanged vanilla original grass4.1
update 3 directory.
grass-alpha-axp-0.3/filterdiff compares every file in the original directory
and subdirectories against the modified directory.  the *.c and *.h files
are run through sed to elimate the global changes in the input to diff.

PORTING STRATEGY

the byte order and sizes of types are the same on a decstation
and an alpha axp, except for longs and pointers which are 64 bits.
GRASS on a decstation works and has been tested for years,
so i use a macro trick to change all the longs in GRASS to ints,
which are 32 bits on an alpha axp,
which is the same as a long on a decstation.
the macro trick is this:
i have replaced every long in the .c and .h files with the macro LONG.
then, when compiling on an alpha axp, i define LONG as int.
this could be a problem when GRASS substracts
one pointer from another and puts the result in a LONG, because
the difference between two pointers could be greater that 2^32,
but i haven't seen this to be a problem in practice yet.  
i have been compiling with -trapuv which i think helps limit the
pointers to a smaller address space, but i a not really sure if
it does so.

this strategy allows me to use the portable GRASS vector file format
without any fuss, which is a big win when you have a bunch of non-alpha
machines on your network.  in the long run we may want instead of have
GRASS work with 64 bit longs, so that we can process larger datasets
before we hit limitations, but maybe GRASS should be ansi-ized first?

i think that my port generally will work wherever grass 
works on 32 bit machine.  but there will be situations were
you want to handle data that is too big for a 32 bit machine,
and then my port will need to be reworked.  (a friend of mine says
then why bother with a 64 bit machine?) but the work
that goes into cleaning up grass to run in 32 bits will be
a good starting point for the 64 bit grass.
to have a 64 bit grass i think that we will have to look at
all the ints and longs and for each one replace it with a new
type.  then you would define what all of these types should
be on the machine you are porting to.

MACROS USED IN GRASS ALPHA AXP PORT

LONG -- macro for when GRASS code had long
on alpha -- int
elsewhere -- long

LDSET
on alpha -- "%d"
elsewhere -- "%ld"
macro for when GRASS code has scanf reading a long
this macro is put in by a global substitution
these global substitutions vanish in the patch files made with filterdiff
the substitution process only works when the scanf and the %ld are the same line

L_IN_LD 
on alpha -- ""
elsewhere -- "l"
macro for when GRASS code has scanf reading a long
this macro replaces the l in %l
this macro is put in by hand
whenever a scanf's appears without a " on the same line a human needs to check.
usually this is because the fmt string is being dynamically calculated.
grep can find these: 
find . -name '*.c' -print | xargs grep -n 'scanf[^"]*$' /dev/null
there are a couple of places where scanf tries to read LONG that is not an %ld,
for example it reads %lu in ./src.contrib/SCS/imp_exp/tig_dig/imp_tig.c
you can spot these with grep by looking for %l on a scanf line,
but %lf is ok, so the following grep command skips %lf:
find . -name '*.c' -print | xargs grep -n 'scanf.*%l[^f]' /dev/null

DO_NOT_REDEFINE_STDLIB
on alpha -- #define'ed with -DDO_NOT_REDECLARE_STDLIB on cc command line
elsewhere -- optional
many places in GRASS there are redeclarations of functions from
the stardard libraries, like ftell() and malloc().
i think it is better just to #include the right header file,
and the redeclarations often trip over my long to LONG trick,
so i have #ifdef'ed them out.  if you do not define DO_NOT_REDEFINE_STDLIB
then you get the equivalent of the original GRASS code, with the 
redeclarations.  if you do define DO_NOT_REDEFINE_STDLIB,
then you lose the redeclarations and gain some #includes.

ChANGE HISTORY

new versions are put at the ftp site listed in the AVAILABLITY section.

0.1 first test release
0.2 fixed configuration errors found by Bob Haxo <haxo at toro.ucdavis.edu>
by that prevented out of the box build.  also fixed a few 
scanf problems of the %lu type where the item being scanned is a LONG.
0.3 moved src/CMD/lists/local out of the patchfile,
used explicit path /lib/cpp in long2LONG, because some users do not have 
/lib in their path, as reported by Boris Livshitz <boris at postgres.Berkeley.EDU>.