Debian Codegraph @

proginfo/ZipPorts

raw
1 __________________________________________________________________________
2
3 This is the Info-ZIP file ZipPorts, last updated on 17 February 1996.
4 __________________________________________________________________________
5
6
7 This document defines a set of rules and guidelines for those who wish to
8 contribute patches to Zip and UnZip (or even entire ports to new operating
9 systems). The list below is something between a style sheet and a "Miss
10 Manners" etiquette guide. While Info-ZIP encourages contributions and
11 fixes from anyone who finds something worth changing, we are also aware
12 of the fact that no two programmers have the programming style and that
13 unrestrained changes by a few dozen contributors would result in hideously
14 ugly (and unmaintainable) Frankenstein code. So consider the following an
15 attempt by the maintainers to maintain sanity as well as useful code.
16
17 (The first version of this document was called either "ZipRules" or the
18 "No Feelthy ..." file and was compiled by David Kirschbaum in consulta-
19 tion with Mark Adler, Cave McNewt and others. The current incarnation
20 expands upon the original with insights gained from a few more years of
21 happy hacking...)
22
23
24 Summary:
25
26 (0) The Platinum Rule: DON'T BREAK EXISTING PORTS
27 (0.1) The Golden Rule: DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
28 (0.2) The Silver Rule: DO UNTO THE LATEST BETA CODE
29 (0.3) The Bronze Rule: NO FEELTHY PIGGYBACKS
30
31 (1) NO FEELTHY TABS
32 (2) NO FEELTHY CARRIAGE RETURNS
33 (3) NO FEELTHY 8-BIT CHARS
34 (4) NO FEELTHY LEFT-JUSTIFIED DASHES
35 (5) NO FEELTHY FANCY_FILENAMES
36 (6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
37 (7) NO FEELTHY E-MAIL BINARIES
38
39
40 Explanations:
41
42 (0) The Platinum Rule: DON'T BREAK EXISTING PORTS
43
44 No doubt about it, this is the one which really pisses us off and
45 pretty much guarantees that your port or patch will be ignored and/
46 or laughed at. Examples range from the *really* severe cases which
47 "port" by ripping out all of the existing multi-OS code, to more
48 subtle oopers like relying on a local capability which doesn't exist
49 on other OSes or in older compilers (e.g., the use of ANSI "#elif"
50 or "#pragma" or "##" constructs, C++ comments, GNU extensions, etc.).
51 As to the former, use #ifdefs for your new code (see rule 0.3). And
52 as to the latter, trust us--there are few things we'd like better
53 than to be able to use some of the elegant "new" features out there
54 (many of which have been around for a decade or more). But our code
55 still compiles on machines dating back even longer, at least in spirit
56 --e.g., the AT&T 3B1 family and Dynix/ptx. Until we say otherwise,
57 dinosaurs are supported.
58
59
60 (0.1) The Golden Rule: DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
61
62 In other words, try to fit into the local style of programming--no
63 matter how painful it may be. This includes cosmetic aspects like
64 indenting the same amount (both in the main C code and in the in-
65 clude files), using braces and comments similarly, NO TABS (see rule
66 #1), etc.; but also more substantive things like (for UnZip) putting
67 character strings into static (far) variables and using the LoadFar-
68 String macros to avoid overflowing limited MS-DOS data segments, and
69 using the ugly Info() macro instead of the more usual *printf()
70 functions so that dynamic-link-library ports are simpler. NEVER put
71 single-OS code (e.g., OS/2) of more than two or three lines into the
72 main (generic) modules; those are shared by everybody, and nobody else
73 cares about it or wants to see it.
74
75 Note that not only do Zip and UnZip differ in these respects, so do
76 individual parts of each program. While it would be nice to have
77 global consistency, cosmetic changes are not a high priority; for
78 now we'll settle for local consistency--i.e., don't make things any
79 worse than they already are.
80
81 Exception (BIG exception): single-letter variable names. Despite
82 the prevailing practice in much of Zip and parts of UnZip, and de-
83 spite the fact that one-letter variables allow you to pack really
84 cool, compact and complicated expressions onto one line, they also
85 make the code very difficult to maintain and are therefore *strongly*
86 discouraged. Don't ask us who is responsible in the first place;
87 while this sort of brain damage is not uncommon among former BASIC
88 programmers, it is nevertheless a lifelong embarrassment, and we do
89 try to pity the poor sod (that is, when we're not chasing bugs and
90 cursing him). :-)
91
92
93 (0.2) The Silver Rule: DO UNTO THE LATEST BETA CODE
94
95 Few things are as annoying as receiving a large patch which obviously
96 represents a lot of time and careful work but which is relative to
97 an old version of Info-ZIP code. As wonderful as Larry Wall's patch
98 program is at applying context diffs to modified code, we regularly
99 make near-global changes and/or reorganize big chunks of the sources
100 (particularly in UnZip), and "patch" can't work miracles--big changes
101 invariably break any patch which is relative to an old version of the
102 code.
103
104 Bottom line: contact the Info-ZIP core team FIRST (via the zip-bugs
105 e-mail address) and get up to date with the latest code before begin-
106 ning a big new port. And try to *stay* up to date while working on
107 your port--at least, as much as possible.
108
109
110 (0.3) The Bronze Rule: NO FEELTHY PIGGYBACKS
111
112 UnZip is currently ported to something like 12 operating systems
113 (a few more or less depending on how one counts), and each of these,
114 with the possible exception of VM/CMS, has a unique macro identifying
115 it: AMIGA, ATARI_ST, __human68k__, MACOS, MSDOS, MVS, OS2, TOPS20,
116 UNIX, VMS, WIN32. Zip is moving in the same direction. New ports
117 should NOT piggyback one of the existing ports unless they are sub-
118 stantially similar--for example, Minix and Coherent are basically Unix
119 and therefore are included in the UNIX macro, but DOS djgpp ports and
120 OS/2 emx ports (both of which use the Unix-originated GNU C compiler
121 and often have "unix" defined by default) are obviously *not* Unix.
122 [The existing MTS port is a special exception; basically only one per-
123 son knows what MTS really is, and he's not telling. Presumably it's
124 not very close to Unix, but it's not worth arguing about it now.]
125 Along the same lines, neither OS/2 nor Human68K is the same as (or
126 even close to) MS-DOS. MVS and VM/CMS, on the other hand, are quite
127 similar to each other and are therefore combined in most places.
128
129 Bottom line: when adding a new port (e.g., QDOS), create a new macro
130 for it ("QDOS"), a new subdirectory ("qdos") and a new source file for
131 OS-specific code ("qdos/qdos.c"). Use #ifdefs to fit any OS-specific
132 changes into the existing code (e.g., unzpriv.h). If it's close enough
133 to an existing port that piggybacking is a temptation, define a new
134 "combination macro" (e.g., "CMS_MVS") and replace the old macros as
135 required. (This last applies to UnZip, at least; the old preference
136 in Zip was fewer macros and long #ifdef lines, so talk to Onno or Jean-
137 loup about that.) See also rule 0.1.
138
139 (Note that, for UnZip, new ports need not attempt to deal with all
140 features. Among other things, the wildcard-zipfile code in do_wild()
141 may be replaced with a supplied dummy version, since opendir/readdir/
142 closedir() or the equivalent can be difficult to implement.)
143
144
145 (1) NO FEELTHY TABS
146
147 Some editors and e-mail systems either have no capability to use
148 and/or display tab characters (ASCII 9) correctly, or they use non-
149 standard or variable-width tab columns, or other horrors. Some edi-
150 tors auto-convert spaces to tabs, after which the blind use of "diff
151 -c" results in a huge and mostly useless patch. Yes, *we* know about
152 diff's "-b" option, but not everyone does. And yes, we also know this
153 makes the source files bigger, even after compression; so be it. If
154 we *really* cared that much about the size of the sources, we'd still
155 be writing Unix-only utilities.
156
157 Bottom line: use spaces, not tabs.
158
159 Exception: some of the makefiles (the Unix one in particular) require
160 tabs as part of the syntax.
161
162 Related utility programs:
163 Unix, OS/2 and MS-DOS: expand, unexpand.
164 MS-DOS: Buerg's TABS; Toad Hall's TOADSOFT.
165 And some editors have the conversion built-in.
166
167
168 (2) NO FEELTHY CARRIAGE RETURNS
169
170 All source, documentation and other text files shall have Unix style
171 line endings (LF only, a.k.a. ctrl-J), not the DOS/OS2/NT CR+LF or Mac
172 CR-only line endings.
173
174 Reason: "real programmers" in any environment can convert back and
175 forth between Unix and DOS/Mac style. All PC compilers but a few old
176 Borland versions can use either Unix or MS-DOS end-of-lines. Buerg's
177 LIST (file-display utility) for MS-DOS can use Unix or MS-DOS EOLs.
178 Both Zip and UnZip can convert line-endings as appropriate. But Unix
179 utilities like diff and patch die a horrible death (or produce horrible
180 output) if the target files have CRs.
181
182 Related utilities: flip for Unix, OS/2 and MS-DOS; Unix "tr".
183
184 Exceptions: documentation in pre-compiled binary distributions should
185 be in the local (target) format.
186
187
188 (3) NO FEELTHY 8-BIT CHARS
189
190 Do all your editing in a plain-text ASCII editor. No WordPerfect, MS
191 Word, WordStar document mode, or other word processor files, thenkyew.
192 No desktop publishing. *Especially* no EBCDIC. No TIFFs, no GIFs, no
193 embedded pictures or dancing ladies (too bad, Cave Newt). [Sigh... -CN]
194
195 Reason: compatibility with different consoles. My old XT clone is
196 the most limited!
197
198 Exceptions: some Macintosh makefiles apparently require some 8-bit
199 characters; the Human68k port uses 8-bit characters for Kanji or Kana
200 comments (I think); etc.
201
202 Related utilities: vi, emacs, EDLIN, Turbo C editor, other programmers'
203 editors, various word processor -> text conversion utilities.
204
205
206 (4) NO FEELTHY LEFT-JUSTIFIED DASHES
207
208 Always precede repeated dashes (------) with one or more leading non-
209 dash characters: spaces, tabs, pound signs (#), comments (/*), what-
210 ever.
211
212 Reason: sooner or later your source file will be e-mailed through an
213 undigestifier utility, most of which treat leading dashes as end-of-
214 message separators. We'd rather not have your code broken up into a
215 dozen separate untitled messages, thank you.
216
217
218 (5) NO FEELTHY FANCY_FILENAMES
219
220 Assume the worst: that someone on a brain-damaged DOS system has to
221 work with everything your magic fingers produced. Keep the filenames
222 unimaginative and within MS-DOS limits (i.e., ordinary A..Z, 1..9,
223 "-$_!"-type characters, in the 8.3 "filename.ext" format). Mac and
224 Unix users, giggle all you want, but no spaces or multiple dots.
225
226 Reason: compatibility with different file systems. MS-DOS FAT is the
227 most limited, with the exception of CompuServe (6.3, argh).
228
229 Exceptions: slightly longer names are occasionally acceptable within
230 OS-specific subdirectories, but don't do that unless there's a good
231 reason for it.
232
233
234 (6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
235
236 Beta testers and developers are in general expected to have both
237 ftp capability and the ability to deal with zipfiles. Those without
238 should either find a friend who does or else learn about ftp-mailers.
239
240 Reason: the core development team barely has time to work on the
241 code, much less prepare oddball formats and/or mail betas out (and
242 the situation is getting worse, sigh).
243
244 Exceptions: anyone seriously proposing to do a new port will be
245 given special treatment, particularly with respect to UnZip; we
246 obviously realize that bootstrapping a completely new port can be
247 quite difficult and have no desire to make it even harder due to
248 lack of access to the latest code (rule 0.2).
249
250 Public releases of UnZip, on the other hand, will be available in
251 two formats: .tar.Z (16-bit compress'd tar) and .zip (either "plain"
252 or self-extracting). Zip sources and executables will generally only
253 be distributed in .zip format, since Zip is pretty much useless without
254 UnZip.
255
256
257 (7) NO FEELTHY E-MAIL BINARIES
258
259 Binary files (e.g., executables, test zipfiles, etc.) should NEVER
260 be mailed raw. Where possible, they should be uploaded via ftp in
261 BINARY mode; if that's impossible, Mark's "ship" ASCII-encoder should
262 be used; and if that's unavailable, uuencode or xxencode should be
263 used. Weirdo NeXTmail, mailtool and MIME formats are also Right Out.
264
265 Files larger than 50KB may need to be broken into pieces for mailing
266 (be sure to label them in order!), unless "ship" is used (it can
267 auto-split, label and mail files if told to do so). If Down Under
268 is involved, files must be broken into under-20KB chunks.
269
270 Reasons: to prevent sounds of gagging mailers from resounding through-
271 out the land. To be relatively efficient in the binary->ASCII conver-
272 sion. (Yeah, yeah, I know, there's better conversions out there. But
273 not as widely known, and they often break on BITNET gateways.)
274
275 Related utilities: ship, uuencode, uudecode, uuxfer20, quux, others.
276 Just make sure they don't leave embedded or trailing spaces (that is,
277 they should use the "`" character in place of ASCII 32). Otherwise
278 mailers are prone to truncate or whatever.
279
280
281 Greg Roelofs (a.k.a. Cave Newt)
282 Info-ZIP UnZip maintainer
283
284 David Kirschbaum
285 former Info-ZIP Coordinator