Fresh Fish 5/FreshFish_July-August1994.bin/bbs/util/mg-3b.lha/mg-3b/docs/Porting

Text File | 1990-06-02 | 5.7 KB | 103 lines

This file contains notes for those working on convincing mg3a to work
on systems using system-dependent code from mg2a.

First, the major changes are cosmetic. The first one is that I've
gotten tired of having code formatted with diffent styles for every
person who worked on the code. It's been run through indent, with
everything having the default setting. You can get a copy of indent
from uunet.uu.net. While the format it uses isn't pretty by anyones
standards, it's more readable for all concerned than most of the
formats that were here (mine included), and it's the same everywhere.
Please try and keep changes to the system-indendent code in the style
that indent uses. Better yet, get a copy of indent, and run it over
the file with your changes in it before doing the diffs.

Second, all the typedefs for things that aren't system-dependent have
vanished. This allows programmers to see what they are dealing with,
and leads to more readable text by having less upper-case text. The
system-independent code has all been changed to match this useage, as
well as the amiga, bsd & termcap system-dependent code. You can either
add the typdefs back to your sysdef.h, add them to each file that uses
them, or change the system-dependent code to match that useage.

Finally, the header files have all been reorganized. Each data
structure (well, set of interdependent data structures) now lives in a
.h file of it's own, and is specifically included by those c source
files that need it. This allows changes in (for instance) one data
structure to be made without make (or similar automatic program
maintenance tools) to want to recompile all the .c files. To aid this,
each of these .h files defins a symbol derived from it's name, and
it's entire contents is #ifdef'ed on that symbol. Likewise, those .h
files that need other .h files have conditional includes on the
symbols defined by the .h file to be included.

The first noncosmetic change is related to this. All the various
compile-time #defines that control which features/behavior you get
have moved into seperate .h files, and the .h files should be included
by c source files that which to check those symbols. There's a tool
called config that probably won't run on anything but an Amiga in the
rexx directory that makes maintaining these .h files (among other
things) much simpler. It should be straightforward to rewrite this in
C, if someone is interested. Documentation can be found in the docs
directory.

The second noncosmetic change is the reorganization of the directory
structure of mg. Instead of all the source files living in the
top-level directory, with the system-dependent files in sys/<sysname>,
the c sources have moved down a level into "mg"; the include files
have moved down a level into "h", and the directories in sys have
moved up a level. In addition, the following directories are now in
the top level: "conf", holding descriptions of the options available
for all of mg, and for mg on various systems, and with various
compilers.  It's suggested that you build .options files (see the
config doc for an explanation of those) for a version, even if you
don't use config - it documents the options that are available, and
the list of .h files that each version will try and include; "doc"
holding documentation for mg and the stuff in tools; "tools" holding
misc. tools that may or may not be usefull to you in building mg3;
"rexx" which holds Rexx scripts for those Amiga users who build in the
Rexx interface, and hopefully the MS/DOS & OS-2 users after someone
builds in a Rexx interface for mg3 on those machines. Finally, there
is one directory for each version that has been configured out of the
sources in that directory.

That last sentence holds the reason for most of this: it's now
possible to maintain multiple mg's with different feature sets out of
the same source tree; it's possible to use different compiler or
compiler flags on the different versions; if you have a system where
disks are shared, you can even maintain versions for different
machines/OS's out of the same source tree.

Note that this new structure depends on the ability to specify a list
of directories to search for include files. The list should be:
current directory (if that's not the default), system directory (i.e.,
where sysdef.h lives; for example, /amiga), mg h directory.

The macro code has been completely rewritten, allowing the GNU macro
facilities to be used. To accomodate this, the keymap structure has
been changed. Any locally-provided keymaps will have to be changed to
match the new structure. These changes cause macros to be executed
from inside of the routine that is used to run macros, which has
driven stack use - especially in startup files - up noticably. If you
use macros heavily and have a system that doesn't automatically expand
the stack, you'll want to up the stack size. The amiga version crashes
in the startup-file with a 4K stack. I normally run with a 50K stack,
and have been told that 20K works fine; I don't have any better data,
for which I apologize. Please let me know what's going on.

I think that's it. If you find something I forgot to mention, please
let me know.

One final comment: I have a fair list of _extensions_ I'd like to
make. However, I feel that it's important to get this version out now,
so people can start beating on it. Likewise, I'd like for real users
to start working on it ASAP. Therefore, I'd like to restrict any
changes to bug fixes, or fixes that needed to get the code to work on
a specific system. If you have extensions you've already made, I'd
prefer to wait for the next update. If you have extensions you'd like
to make, please hold them until after we do a real release. I'd like
to go over everybodies list of extensions, and see which ones want to
get added _after_ it goes out to the real world.

    <mike