home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BURKS 2
/
BURKS_AUG97.ISO
/
BURKS
/
SOFTWARE
/
SOURCES
/
UNZIP52.ZIP
/
proginfo
/
ZipPorts
(
.txt
)
< prev
Wrap
Text File
|
1996-02-17
|
14KB
|
286 lines
__________________________________________________________________________
This is the Info-ZIP file ZipPorts, last updated on 17 February 1996.
__________________________________________________________________________
This document defines a set of rules and guidelines for those who wish to
contribute patches to Zip and UnZip (or even entire ports to new operating
systems). The list below is something between a style sheet and a "Miss
Manners" etiquette guide. While Info-ZIP encourages contributions and
fixes from anyone who finds something worth changing, we are also aware
of the fact that no two programmers have the programming style and that
unrestrained changes by a few dozen contributors would result in hideously
ugly (and unmaintainable) Frankenstein code. So consider the following an
attempt by the maintainers to maintain sanity as well as useful code.
(The first version of this document was called either "ZipRules" or the
"No Feelthy ..." file and was compiled by David Kirschbaum in consulta-
tion with Mark Adler, Cave McNewt and others. The current incarnation
expands upon the original with insights gained from a few more years of
happy hacking...)
Summary:
(0) The Platinum Rule: DON'T BREAK EXISTING PORTS
(0.1) The Golden Rule: DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
(0.2) The Silver Rule: DO UNTO THE LATEST BETA CODE
(0.3) The Bronze Rule: NO FEELTHY PIGGYBACKS
(1) NO FEELTHY TABS
(2) NO FEELTHY CARRIAGE RETURNS
(3) NO FEELTHY 8-BIT CHARS
(4) NO FEELTHY LEFT-JUSTIFIED DASHES
(5) NO FEELTHY FANCY_FILENAMES
(6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
(7) NO FEELTHY E-MAIL BINARIES
Explanations:
(0) The Platinum Rule: DON'T BREAK EXISTING PORTS
No doubt about it, this is the one which really pisses us off and
pretty much guarantees that your port or patch will be ignored and/
or laughed at. Examples range from the *really* severe cases which
"port" by ripping out all of the existing multi-OS code, to more
subtle oopers like relying on a local capability which doesn't exist
on other OSes or in older compilers (e.g., the use of ANSI "#elif"
or "#pragma" or "##" constructs, C++ comments, GNU extensions, etc.).
As to the former, use #ifdefs for your new code (see rule 0.3). And
as to the latter, trust us--there are few things we'd like better
than to be able to use some of the elegant "new" features out there
(many of which have been around for a decade or more). But our code
still compiles on machines dating back even longer, at least in spirit
--e.g., the AT&T 3B1 family and Dynix/ptx. Until we say otherwise,
dinosaurs are supported.
(0.1) The Golden Rule: DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
In other words, try to fit into the local style of programming--no
matter how painful it may be. This includes cosmetic aspects like
indenting the same amount (both in the main C code and in the in-
clude files), using braces and comments similarly, NO TABS (see rule
#1), etc.; but also more substantive things like (for UnZip) putting
character strings into static (far) variables and using the LoadFar-
String macros to avoid overflowing limited MS-DOS data segments, and
using the ugly Info() macro instead of the more usual *printf()
functions so that dynamic-link-library ports are simpler. NEVER put
single-OS code (e.g., OS/2) of more than two or three lines into the
main (generic) modules; those are shared by everybody, and nobody else
cares about it or wants to see it.
Note that not only do Zip and UnZip differ in these respects, so do
individual parts of each program. While it would be nice to have
global consistency, cosmetic changes are not a high priority; for
now we'll settle for local consistency--i.e., don't make things any
worse than they already are.
Exception (BIG exception): single-letter variable names. Despite
the prevailing practice in much of Zip and parts of UnZip, and de-
spite the fact that one-letter variables allow you to pack really
cool, compact and complicated expressions onto one line, they also
make the code very difficult to maintain and are therefore *strongly*
discouraged. Don't ask us who is responsible in the first place;
while this sort of brain damage is not uncommon among former BASIC
programmers, it is nevertheless a lifelong embarrassment, and we do
try to pity the poor sod (that is, when we're not chasing bugs and
cursing him). :-)
(0.2) The Silver Rule: DO UNTO THE LATEST BETA CODE
Few things are as annoying as receiving a large patch which obviously
represents a lot of time and careful work but which is relative to
an old version of Info-ZIP code. As wonderful as Larry Wall's patch
program is at applying context diffs to modified code, we regularly
make near-global changes and/or reorganize big chunks of the sources
(particularly in UnZip), and "patch" can't work miracles--big changes
invariably break any patch which is relative to an old version of the
code.
Bottom line: contact the Info-ZIP core team FIRST (via the zip-bugs
e-mail address) and get up to date with the latest code before begin-
ning a big new port. And try to *stay* up to date while working on
your port--at least, as much as possible.
(0.3) The Bronze Rule: NO FEELTHY PIGGYBACKS
UnZip is currently ported to something like 12 operating systems
(a few more or less depending on how one counts), and each of these,
with the possible exception of VM/CMS, has a unique macro identifying
it: AMIGA, ATARI_ST, __human68k__, MACOS, MSDOS, MVS, OS2, TOPS20,
UNIX, VMS, WIN32. Zip is moving in the same direction. New ports
should NOT piggyback one of the existing ports unless they are sub-
stantially similar--for example, Minix and Coherent are basically Unix
and therefore are included in the UNIX macro, but DOS djgpp ports and
OS/2 emx ports (both of which use the Unix-originated GNU C compiler
and often have "unix" defined by default) are obviously *not* Unix.
[The existing MTS port is a special exception; basically only one per-
son knows what MTS really is, and he's not telling. Presumably it's
not very close to Unix, but it's not worth arguing about it now.]
Along the same lines, neither OS/2 nor Human68K is the same as (or
even close to) MS-DOS. MVS and VM/CMS, on the other hand, are quite
similar to each other and are therefore combined in most places.
Bottom line: when adding a new port (e.g., QDOS), create a new macro
for it ("QDOS"), a new subdirectory ("qdos") and a new source file for
OS-specific code ("qdos/qdos.c"). Use #ifdefs to fit any OS-specific
changes into the existing code (e.g., unzpriv.h). If it's close enough
to an existing port that piggybacking is a temptation, define a new
"combination macro" (e.g., "CMS_MVS") and replace the old macros as
required. (This last applies to UnZip, at least; the old preference
in Zip was fewer macros and long #ifdef lines, so talk to Onno or Jean-
loup about that.) See also rule 0.1.
(Note that, for UnZip, new ports need not attempt to deal with all
features. Among other things, the wildcard-zipfile code in do_wild()
may be replaced with a supplied dummy version, since opendir/readdir/
closedir() or the equivalent can be difficult to implement.)
(1) NO FEELTHY TABS
Some editors and e-mail systems either have no capability to use
and/or display tab characters (ASCII 9) correctly, or they use non-
standard or variable-width tab columns, or other horrors. Some edi-
tors auto-convert spaces to tabs, after which the blind use of "diff
-c" results in a huge and mostly useless patch. Yes, *we* know about
diff's "-b" option, but not everyone does. And yes