Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
6725 | siemargl | 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 |