f0d81ffd1c
which included commits to RCS files with non-trunk default branches. git-svn-id: svn://10.65.10.50/trunk@5403 c028cbd2-c16b-5b4b-a496-9718f37d4682
286 lines
14 KiB
Plaintext
Executable File
286 lines
14 KiB
Plaintext
Executable File
__________________________________________________________________________
|
|
|
|
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, we also know this
|
|
makes the source files bigger, even after compression; so be it. If
|
|
we *really* cared that much about the size of the sources, we'd still
|
|
be writing Unix-only utilities.
|
|
|
|
Bottom line: use spaces, not tabs.
|
|
|
|
Exception: some of the makefiles (the Unix one in particular) require
|
|
tabs as part of the syntax.
|
|
|
|
Related utility programs:
|
|
Unix, OS/2 and MS-DOS: expand, unexpand.
|
|
MS-DOS: Buerg's TABS; Toad Hall's TOADSOFT.
|
|
And some editors have the conversion built-in.
|
|
|
|
|
|
(2) NO FEELTHY CARRIAGE RETURNS
|
|
|
|
All source, documentation and other text files shall have Unix style
|
|
line endings (LF only, a.k.a. ctrl-J), not the DOS/OS2/NT CR+LF or Mac
|
|
CR-only line endings.
|
|
|
|
Reason: "real programmers" in any environment can convert back and
|
|
forth between Unix and DOS/Mac style. All PC compilers but a few old
|
|
Borland versions can use either Unix or MS-DOS end-of-lines. Buerg's
|
|
LIST (file-display utility) for MS-DOS can use Unix or MS-DOS EOLs.
|
|
Both Zip and UnZip can convert line-endings as appropriate. But Unix
|
|
utilities like diff and patch die a horrible death (or produce horrible
|
|
output) if the target files have CRs.
|
|
|
|
Related utilities: flip for Unix, OS/2 and MS-DOS; Unix "tr".
|
|
|
|
Exceptions: documentation in pre-compiled binary distributions should
|
|
be in the local (target) format.
|
|
|
|
|
|
(3) NO FEELTHY 8-BIT CHARS
|
|
|
|
Do all your editing in a plain-text ASCII editor. No WordPerfect, MS
|
|
Word, WordStar document mode, or other word processor files, thenkyew.
|
|
No desktop publishing. *Especially* no EBCDIC. No TIFFs, no GIFs, no
|
|
embedded pictures or dancing ladies (too bad, Cave Newt). [Sigh... -CN]
|
|
|
|
Reason: compatibility with different consoles. My old XT clone is
|
|
the most limited!
|
|
|
|
Exceptions: some Macintosh makefiles apparently require some 8-bit
|
|
characters; the Human68k port uses 8-bit characters for Kanji or Kana
|
|
comments (I think); etc.
|
|
|
|
Related utilities: vi, emacs, EDLIN, Turbo C editor, other programmers'
|
|
editors, various word processor -> text conversion utilities.
|
|
|
|
|
|
(4) NO FEELTHY LEFT-JUSTIFIED DASHES
|
|
|
|
Always precede repeated dashes (------) with one or more leading non-
|
|
dash characters: spaces, tabs, pound signs (#), comments (/*), what-
|
|
ever.
|
|
|
|
Reason: sooner or later your source file will be e-mailed through an
|
|
undigestifier utility, most of which treat leading dashes as end-of-
|
|
message separators. We'd rather not have your code broken up into a
|
|
dozen separate untitled messages, thank you.
|
|
|
|
|
|
(5) NO FEELTHY FANCY_FILENAMES
|
|
|
|
Assume the worst: that someone on a brain-damaged DOS system has to
|
|
work with everything your magic fingers produced. Keep the filenames
|
|
unimaginative and within MS-DOS limits (i.e., ordinary A..Z, 1..9,
|
|
"-$_!"-type characters, in the 8.3 "filename.ext" format). Mac and
|
|
Unix users, giggle all you want, but no spaces or multiple dots.
|
|
|
|
Reason: compatibility with different file systems. MS-DOS FAT is the
|
|
most limited, with the exception of CompuServe (6.3, argh).
|
|
|
|
Exceptions: slightly longer names are occasionally acceptable within
|
|
OS-specific subdirectories, but don't do that unless there's a good
|
|
reason for it.
|
|
|
|
|
|
(6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
|
|
|
|
Beta testers and developers are in general expected to have both
|
|
ftp capability and the ability to deal with zipfiles. Those without
|
|
should either find a friend who does or else learn about ftp-mailers.
|
|
|
|
Reason: the core development team barely has time to work on the
|
|
code, much less prepare oddball formats and/or mail betas out (and
|
|
the situation is getting worse, sigh).
|
|
|
|
Exceptions: anyone seriously proposing to do a new port will be
|
|
given special treatment, particularly with respect to UnZip; we
|
|
obviously realize that bootstrapping a completely new port can be
|
|
quite difficult and have no desire to make it even harder due to
|
|
lack of access to the latest code (rule 0.2).
|
|
|
|
Public releases of UnZip, on the other hand, will be available in
|
|
two formats: .tar.Z (16-bit compress'd tar) and .zip (either "plain"
|
|
or self-extracting). Zip sources and executables will generally only
|
|
be distributed in .zip format, since Zip is pretty much useless without
|
|
UnZip.
|
|
|
|
|
|
(7) NO FEELTHY E-MAIL BINARIES
|
|
|
|
Binary files (e.g., executables, test zipfiles, etc.) should NEVER
|
|
be mailed raw. Where possible, they should be uploaded via ftp in
|
|
BINARY mode; if that's impossible, Mark's "ship" ASCII-encoder should
|
|
be used; and if that's unavailable, uuencode or xxencode should be
|
|
used. Weirdo NeXTmail, mailtool and MIME formats are also Right Out.
|
|
|
|
Files larger than 50KB may need to be broken into pieces for mailing
|
|
(be sure to label them in order!), unless "ship" is used (it can
|
|
auto-split, label and mail files if told to do so). If Down Under
|
|
is involved, files must be broken into under-20KB chunks.
|
|
|
|
Reasons: to prevent sounds of gagging mailers from resounding through-
|
|
out the land. To be relatively efficient in the binary->ASCII conver-
|
|
sion. (Yeah, yeah, I know, there's better conversions out there. But
|
|
not as widely known, and they often break on BITNET gateways.)
|
|
|
|
Related utilities: ship, uuencode, uudecode, uuxfer20, quux, others.
|
|
Just make sure they don't leave embedded or trailing spaces (that is,
|
|
they should use the "`" character in place of ASCII 32). Otherwise
|
|
mailers are prone to truncate or whatever.
|
|
|
|
|
|
Greg Roelofs (a.k.a. Cave Newt)
|
|
Info-ZIP UnZip maintainer
|
|
|
|
David Kirschbaum
|
|
former Info-ZIP Coordinator
|