]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> |
2 | <HTML> | |
3 | <HEAD> | |
4 | <TITLE>CUPS Configuration Management Plan</TITLE> | |
5 | <META NAME="author" CONTENT="Easy Software Products"> | |
6 | <META NAME="copyright" CONTENT="Copyright 1997-2005, All Rights Reserved"> | |
7 | <META NAME="docnumber" CONTENT="CUPS-CMP-1.1"> | |
8 | <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1"> | |
9 | <STYLE TYPE="text/css"><!-- | |
10 | BODY { font-family: serif } | |
11 | H1 { font-family: sans-serif } | |
12 | H2 { font-family: sans-serif } | |
13 | H3 { font-family: sans-serif } | |
14 | H4 { font-family: sans-serif } | |
15 | H5 { font-family: sans-serif } | |
16 | H6 { font-family: sans-serif } | |
17 | SUB { font-size: smaller } | |
18 | SUP { font-size: smaller } | |
19 | PRE { font-family: monospace } | |
20 | --></STYLE> | |
21 | </HEAD> | |
22 | <BODY BGCOLOR="white"> | |
23 | <CENTER><A HREF="#CONTENTS"><IMG SRC="images/cups-large.gif" BORDER="0" WIDTH="431" HEIGHT="511" ALT="CUPS Configuration Management Plan"><BR> | |
24 | <H1>CUPS Configuration Management Plan</H1></A><BR> | |
25 | CUPS-CMP-1.1<BR> | |
26 | Easy Software Products<BR> | |
27 | Copyright 1997-2005, All Rights Reserved<BR> | |
28 | </CENTER> | |
29 | <HR NOSHADE> | |
30 | <H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1> | |
31 | <BR> | |
32 | <BR><B><A HREF="#1">1 Scope</A></B> | |
33 | <UL> | |
34 | <LI><A HREF="#1_1">1.1 Identification</A></LI> | |
35 | <LI><A HREF="#1_2">1.2 System Overview</A></LI> | |
36 | <LI><A HREF="#1_3">1.3 Document Overview</A></LI> | |
37 | </UL> | |
38 | <B><A HREF="#2">2 References</A></B> | |
39 | <UL> | |
40 | <LI><A HREF="#2_1">2.1 CUPS Documentation</A></LI> | |
41 | <LI><A HREF="#2_2">2.2 Other Documents</A></LI> | |
42 | </UL> | |
43 | <B><A HREF="#3">3 File Management</A></B> | |
44 | <UL> | |
45 | <LI><A HREF="#3_1">3.1 Directory Structure</A></LI> | |
46 | <LI><A HREF="#3_2">3.2 Source Files</A></LI> | |
47 | <LI><A HREF="#3_3">3.3 Configuration Management</A></LI> | |
48 | </UL> | |
49 | <B><A HREF="#4">4 Trouble Report Processing</A></B> | |
50 | <UL> | |
51 | <LI><A HREF="#4_1">4.1 Classification</A></LI> | |
52 | <LI><A HREF="#4_2">4.2 Identification</A></LI> | |
53 | <LI><A HREF="#4_3">4.3 Correction</A></LI> | |
54 | <LI><A HREF="#4_4">4.4 Notification</A></LI> | |
55 | </UL> | |
56 | <B><A HREF="#5">5 Software Releases</A></B> | |
57 | <UL> | |
58 | <LI><A HREF="#5_1">5.1 Version Numbering</A></LI> | |
59 | <LI><A HREF="#5_2">5.2 Generation</A></LI> | |
60 | <LI><A HREF="#5_3">5.3 Testing</A></LI> | |
61 | <LI><A HREF="#5_4">5.4 Releases</A> | |
62 | <UL> | |
63 | <LI><A HREF="#5_4_1">5.4.1 Beta Releases</A></LI> | |
64 | <LI><A HREF="#5_4_2">5.4.2 Release Candidates</A></LI> | |
65 | <LI><A HREF="#5_4_3">5.4.3 Production Releases</A></LI> | |
66 | </UL> | |
67 | </LI> | |
68 | </UL> | |
69 | <B><A HREF="#6">A Glossary</A></B> | |
70 | <UL> | |
71 | <LI><A HREF="#6_1">A.1 Terms</A></LI> | |
72 | <LI><A HREF="#6_2">A.2 Acronyms</A></LI> | |
73 | </UL> | |
74 | <B><A HREF="#7">B Coding Requirements</A></B> | |
75 | <UL> | |
76 | <LI><A HREF="#7_1">B.1 Source Files</A> | |
77 | <UL> | |
78 | <LI><A HREF="#7_1_1">B.1.1 Naming</A></LI> | |
79 | <LI><A HREF="#7_1_2">B.1.2 Documentation</A></LI> | |
80 | </UL> | |
81 | </LI> | |
82 | <LI><A HREF="#7_2">B.2 Functions</A> | |
83 | <UL> | |
84 | <LI><A HREF="#7_2_1">B.2.1 Naming</A></LI> | |
85 | <LI><A HREF="#7_2_2">B.2.2 Documentation</A></LI> | |
86 | </UL> | |
87 | </LI> | |
88 | <LI><A HREF="#7_3">B.3 Methods</A> | |
89 | <UL> | |
90 | <LI><A HREF="#7_3_1">B.3.1 Naming</A></LI> | |
91 | <LI><A HREF="#7_3_2">B.3.2 Documentation</A></LI> | |
92 | </UL> | |
93 | </LI> | |
94 | <LI><A HREF="#7_4">B.4 Variables</A> | |
95 | <UL> | |
96 | <LI><A HREF="#7_4_1">B.4.1 Naming</A></LI> | |
97 | <LI><A HREF="#7_4_2">B.4.2 Documentation</A></LI> | |
98 | </UL> | |
99 | </LI> | |
100 | <LI><A HREF="#7_5">B.5 Types</A> | |
101 | <UL> | |
102 | <LI><A HREF="#7_5_1">B.5.1 Naming</A></LI> | |
103 | <LI><A HREF="#7_5_2">B.5.2 Documentation</A></LI> | |
104 | </UL> | |
105 | </LI> | |
106 | <LI><A HREF="#7_6">B.6 Structures</A> | |
107 | <UL> | |
108 | <LI><A HREF="#7_6_1">B.6.1 Naming</A></LI> | |
109 | <LI><A HREF="#7_6_2">B.6.2 Documentation</A></LI> | |
110 | </UL> | |
111 | </LI> | |
112 | <LI><A HREF="#7_7">B.7 Classes</A> | |
113 | <UL> | |
114 | <LI><A HREF="#7_7_1">B.7.1 Naming</A></LI> | |
115 | <LI><A HREF="#7_7_2">B.7.2 Documentation</A></LI> | |
116 | </UL> | |
117 | </LI> | |
118 | <LI><A HREF="#7_8">B.8 Constants</A> | |
119 | <UL> | |
120 | <LI><A HREF="#7_8_1">B.8.1 Naming</A></LI> | |
121 | <LI><A HREF="#7_8_2">B.8.2 Documentation</A></LI> | |
122 | </UL> | |
123 | </LI> | |
124 | <LI><A HREF="#7_9">B.9 Code</A> | |
125 | <UL> | |
126 | <LI><A HREF="#7_9_1">B.9.1 Documentation</A></LI> | |
127 | <LI><A HREF="#7_9_2">B.9.2 Style</A></LI> | |
128 | </UL> | |
129 | </LI> | |
130 | </UL> | |
131 | <B><A HREF="#8">C Software Trouble Report Form</A></B><HR NOSHADE> | |
132 | <H1><A NAME="1">1 Scope</A></H1> | |
133 | <H2><A NAME="1_1">1.1 Identification</A></H2> | |
134 | <P>This configuration management plan document provides the guidelines | |
135 | for development and maintenance of the Common UNIX Printing System | |
136 | ("CUPS") Version 1.1 software.</P> | |
137 | <H2><A NAME="1_2">1.2 System Overview</A></H2> | |
138 | <P>CUPS provides a portable printing layer for UNIX®-based operating | |
139 | systems. It has been developed by <A HREF="http://www.easysw.com">Easy | |
140 | Software Products</A> to promote a standard printing solution for all | |
141 | UNIX vendors and users. CUPS provides the System V and Berkeley | |
142 | command-line interfaces.</P> | |
143 | <P>CUPS uses the Internet Printing Protocol ("IPP") as the basis for | |
144 | managing print jobs and queues. The Line Printer Daemon ("LPD") Server | |
145 | Message Block ("SMB"), and AppSocket (a.k.a. JetDirect) protocols are | |
146 | also supported with reduced functionality. CUPS adds network printer | |
147 | browsing and PostScript Printer Description ("PPD") based printing | |
148 | options to support real-world printing under UNIX.</P> | |
149 | <P>CUPS includes an image file RIP that supports printing of image files | |
150 | to non-PostScript printers. A customized version of GNU Ghostscript | |
151 | 7.05 for CUPS called ESP Ghostscript is available separately to support | |
152 | printing of PostScript files within the CUPS driver framework. Sample | |
153 | drivers for Dymo, EPSON, HP, and OKIDATA printers are included that use | |
154 | these filters.</P> | |
155 | <P>Drivers for thousands of printers are provided with our ESP Print Pro | |
156 | software, available at:</P> | |
157 | <PRE> | |
158 | <A HREF="http://www.easysw.com/printpro/">http://www.easysw.com/printpro/</A> | |
159 | </PRE> | |
160 | <P>CUPS is licensed under the GNU General Public License and GNU Library | |
161 | General Public License. Please contact Easy Software Products for | |
162 | commercial support and "binary distribution" rights.</P> | |
163 | <H2><A NAME="1_3">1.3 Document Overview</A></H2> | |
164 | <P>This configuration management document is organized into the | |
165 | following sections:</P> | |
166 | <UL> | |
167 | <LI>1 - Scope</LI> | |
168 | <LI>2 - References</LI> | |
169 | <LI>3 - File Management</LI> | |
170 | <LI>4 - Trouble Report Processing</LI> | |
171 | <LI>5 - Software Releases</LI> | |
172 | <LI>A - Glossary</LI> | |
173 | <LI>B - Coding Requirements</LI> | |
174 | </UL> | |
175 | <H1><A NAME="2">2 References</A></H1> | |
176 | <H2><A NAME="2_1">2.1 CUPS Documentation</A></H2> | |
177 | <P>The following CUPS documentation is referenced by this document:</P> | |
178 | <UL> | |
179 | <LI>CUPS-CMP-1.1: CUPS Configuration Management Plan</LI> | |
180 | <LI>CUPS-IDD-1.1: CUPS System Interface Design Description</LI> | |
181 | <LI>CUPS-IPP-1.1: CUPS Implementation of IPP</LI> | |
182 | <LI>CUPS-SAM-1.1.x: CUPS Software Administrators Manual</LI> | |
183 | <LI>CUPS-SDD-1.1: CUPS Software Design Description</LI> | |
184 | <LI>CUPS-SPM-1.1.x: CUPS Software Programming Manual</LI> | |
185 | <LI>CUPS-SSR-1.1: CUPS Software Security Report</LI> | |
186 | <LI>CUPS-STP-1.1: CUPS Software Test Plan</LI> | |
187 | <LI>CUPS-SUM-1.1.x: CUPS Software Users Manual</LI> | |
188 | <LI>CUPS-SVD-1.1: CUPS Software Version Description</LI> | |
189 | </UL> | |
190 | <H2><A NAME="2_2">2.2 Other Documents</A></H2> | |
191 | <P>The following non-CUPS documents are referenced by this document:</P> | |
192 | <UL> | |
193 | <LI><A HREF="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf"> | |
194 | Adobe PostScript Printer Description File Format Specification, Version | |
195 | 4.3.</A></LI> | |
196 | <LI><A HREF="http://partners.adobe.com/asn/developer/PDFS/TN/PLRM.pdf"> | |
197 | Adobe PostScript Language Reference, Third Edition.</A></LI> | |
198 | <LI>IPP/1.1: Implementers Guide</LI> | |
199 | <LI><A HREF="http://www.ietf.org/rfc/rfc1179.txt">RFC 1179, Line Printer | |
200 | Daemon Protocol</A></LI> | |
201 | <LI><A HREF="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396, Uniform | |
202 | Resource Identifiers (URI): Generic Syntax</A></LI> | |
203 | <LI><A HREF="http://www.ietf.org/rfc/rfc2567.txt">RFC 2567, Design Goals | |
204 | for an Internet Printing Protocol</A></LI> | |
205 | <LI><A HREF="http://www.ietf.org/rfc/rfc2568.txt">RFC 2568, Rationale | |
206 | for the Structure of the Model and Protocol for the Internet Printing | |
207 | Protocol</A></LI> | |
208 | <LI><A HREF="http://www.ietf.org/rfc/rfc2569.txt">RFC 2569, Mapping | |
209 | between LPD and IPP Protocols</A></LI> | |
210 | <LI><A HREF="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616, Hypertext | |
211 | Transfer Protocol -- HTTP/1.1</A></LI> | |
212 | <LI><A HREF="http://www.ietf.org/rfc/rfc2617.txt">RFC 2617, HTTP | |
213 | Authentication: Basic and Digest Access</A> Authentication</LI> | |
214 | <LI><A HREF="http://www.ietf.org/rfc/rfc2910.txt">RFC 2910, IPP/1.1: | |
215 | Encoding and Transport</A></LI> | |
216 | <LI><A HREF="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911, IPP/1.1: | |
217 | Model and Semantics</A></LI> | |
218 | <LI><A HREF="http://www.ietf.org/rfc/rfc3380.txt">RFC 3380, IPP: Job and | |
219 | Printer Set Operations</A></LI> | |
220 | </UL> | |
221 | <H1><A NAME="3">3 File Management</A></H1> | |
222 | <H2><A NAME="3_1">3.1 Directory Structure</A></H2> | |
223 | <P>Each source file shall be placed a sub-directory corresponding to the | |
224 | software sub-system it belongs to ("scheduler", "cups", etc.) To remain | |
225 | compatible with older UNIX filesystems, directory names shall not | |
226 | exceed 16 characters in length.</P> | |
227 | <H2><A NAME="3_2">3.2 Source Files</A></H2> | |
228 | <P>Source files shall be documented and formatted as described in | |
229 | Appendix B, Coding Requirements. To remain compatible with older UNIX | |
230 | filesystems, source file names shall not exceed 16 characters in | |
231 | length.</P> | |
232 | <H2><A NAME="3_3">3.3 Configuration Management</A></H2> | |
233 | <P>Source files shall be placed under the control of the Concurrent | |
234 | Versions System ("CVS") software. Source files shall be "checked in" | |
235 | with each change so that modifications can be tracked.</P> | |
236 | <P>Documentation on the CVS software is included with the whitepaper, | |
237 | "CVS II: Parallelizing Software Development".</P> | |
238 | <H1><A NAME="4">4 Trouble Report Processing</A></H1> | |
239 | <P>A Software Trouble Report ("STR") shall be submitted every time a | |
240 | user or vendor experiences a problem with the CUPS software. Trouble | |
241 | reports are maintained in a database with one of the following states:</P> | |
242 | <OL> | |
243 | <LI>STR is closed with complete resolution</LI> | |
244 | <LI>STR is closed without resolution</LI> | |
245 | <LI>STR is active</LI> | |
246 | <LI>STR is pending (new STR or additional information available)</LI> | |
247 | </OL> | |
248 | <P>Trouble reports shall be processed using the following steps.</P> | |
249 | <H2><A NAME="4_1">4.1 Classification</A></H2> | |
250 | <P>When a trouble report is received it must be classified at one of the | |
251 | following priority levels:</P> | |
252 | <OL> | |
253 | <LI>Request for enhancement, e.g. asking for a feature</LI> | |
254 | <LI>Low, e.g. a documentation error or undocumented side-effect</LI> | |
255 | <LI>Moderate, e.g. unable to print a file or unable to compile the | |
256 | software</LI> | |
257 | <LI>High, e.g. unable to print to a printer or key functionality not | |
258 | working</LI> | |
259 | <LI>Critical, e.g. unable to print at all</LI> | |
260 | </OL> | |
261 | <P>Level 4 and 5 trouble reports must be resolved in the next software | |
262 | release. Level 1 to 3 trouble reports are scheduled for resolution in a | |
263 | specific release at the discretion of the release coordinator.</P> | |
264 | <P>The scope of the problem should also be determined as:</P> | |
265 | <OL> | |
266 | <LI>Specific to a machine or printer</LI> | |
267 | <LI>Specific to an operating system</LI> | |
268 | <LI>Applies to all machines, printers, and operating systems</LI> | |
269 | </OL> | |
270 | <H2><A NAME="4_2">4.2 Identification</A></H2> | |
271 | <P>Once the level and scope of the trouble report is determined the | |
272 | software sub-system(s) involved with the problem are determined. This | |
273 | may involve additional communication with the user or vendor to isolate | |
274 | the problem to a specific cause.</P> | |
275 | <P>When the sub-system(s) involved have been identified, an engineer | |
276 | will then determine the change(s) needed and estimate the time required | |
277 | for the change(s).</P> | |
278 | <H2><A NAME="4_3">4.3 Correction</A></H2> | |
279 | <P>Corrections are scheduled based upon the severity and complexity of | |
280 | the problem. Once all changes have been made, documented, and tested | |
281 | successfully a new software release snapshot is generated. Additional | |
282 | tests are added as necessary for proper testing of the changes.</P> | |
283 | <H2><A NAME="4_4">4.4 Notification</A></H2> | |
284 | <P>The user or vendor is notified when the fix is available or if the | |
285 | problem was caused by user error.</P> | |
286 | <H1><A NAME="5">5 Software Releases</A></H1> | |
287 | <H2><A NAME="5_1">5.1 Version Numbering</A></H2> | |
288 | <P>CUPS uses a three-part version number separated by periods to | |
289 | represent the major, minor, and patch release numbers:</P> | |
290 | <PRE> | |
291 | MAJOR.MINOR.PATCH | |
292 | 1.1.0 | |
293 | </PRE> | |
294 | <P>Beta-test releases are indentified by appending the letter B followed | |
295 | by the build number:</P> | |
296 | <PRE> | |
297 | MAJOR.MINOR.PATCHbBUILD | |
298 | 1.1.0b1 | |
299 | </PRE> | |
300 | <P>Release candidates are indentified by appending the letters RC | |
301 | followed by the build number:</P> | |
302 | <PRE> | |
303 | MAJOR.MINOR.PATCHrcBUILD | |
304 | 1.1.0rc1 | |
305 | </PRE> | |
306 | <P>A CVS snapshot is generated for every beta and final release and uses | |
307 | the version number preceded by the letter "v" and with the decimal | |
308 | points replaced by underscores:</P> | |
309 | <PRE> | |
310 | v1_1_0b1 | |
311 | v1_1_0rc1 | |
312 | v1_1_0 | |
313 | </PRE> | |
314 | <P>Each change that corrects a fault in a software sub-system increments | |
315 | the patch release number. If a change affects the overall software | |
316 | design of CUPS then the minor release number will be incremented and | |
317 | the patch release number reset to 0. If CUPS is completely redesigned | |
318 | the major release number will be incremented and the minor and patch | |
319 | release numbers reset to 0:</P> | |
320 | <PRE> | |
321 | 1.1.0b1 First beta release | |
322 | 1.1.0b2 Second beta release | |
323 | 1.1.0rc1 First release candidate | |
324 | 1.1.0rc2 Second release candidate | |
325 | 1.1.0 First production release | |
326 | 1.1.1b1 First beta of 1.1.1 | |
327 | 1.1.1rc1 First release candidate of 1.1.1 | |
328 | 1.1.1 Production release of 1.1.1 | |
329 | 1.1.2b1 First beta of 1.1.2 | |
330 | 1.1.2rc1 First release candidate of 1.1.2 | |
331 | 1.1.2 Production release of 1.1.2 | |
332 | 2.0.0b1 First beta of 2.0.0 | |
333 | 2.0.0rc1 First release candidate of 2.0.0 | |
334 | 2.0.0 Production release of 2.0.0 | |
335 | </PRE> | |
336 | <H2><A NAME="5_2">5.2 Generation</A></H2> | |
337 | <P>Software releases shall be generated for each successfully completed | |
338 | software trouble report. All object and executable files shall be | |
339 | deleted prior to performing a full build to ensure that source files | |
340 | are recompiled.</P> | |
341 | <H2><A NAME="5_3">5.3 Testing</A></H2> | |
342 | <P>Software testing shall be conducted according to the CUPS Software | |
343 | Test Plan, CUPS-STP-1.1. Failed tests cause STRs to be generated to | |
344 | correct the problems found.</P> | |
345 | <H2><A NAME="5_4">5.4 Releases</A></H2> | |
346 | <P>When testing has been completed successfully a new distribution image | |
347 | is created from the current CVS code "snapshot". No release shall | |
348 | contain software that has not passed the appropriate software tests. | |
349 | Three types of releases are used, beta, release candidate, and | |
350 | production, and are released using the following basic schedule: | |
351 | <CENTER> | |
352 | <TABLE BORDER="1"> | |
353 | <TR><TH>Week</TH><TH>Version</TH><TH>Description</TH></TR> | |
354 | <TR><TD>T-6 weeks</TD><TD>1.1.0b1</TD><TD>First beta</TD></TR> | |
355 | <TR><TD>T-5 weeks</TD><TD>1.1.0b2</TD><TD>Second beta</TD></TR> | |
356 | <TR><TD>T-4 weeks</TD><TD>1.1.0b3</TD><TD>Third beta</TD></TR> | |
357 | <TR><TD>T-3 weeks</TD><TD>1.1.0rc1</TD><TD>First release candidate</TD></TR> | |
358 | <TR><TD>T-2 weeks</TD><TD>1.1.0rc2</TD><TD>Second release candidate</TD></TR> | |
359 | <TR><TD>T-0 weeks</TD><TD>1.1.0</TD><TD>Production</TD></TR> | |
360 | </TABLE> | |
361 | </CENTER> | |
362 | </P> | |
363 | <P>Beta releases are typically used prior to new major and minor version | |
364 | releases. At least one release candidate is generated prior to each | |
365 | production release.</P> | |
366 | <H3><A NAME="5_4_1">5.4.1 Beta Releases</A></H3> | |
367 | <P>Beta releases are generated when substantial changes have been made | |
368 | that may affect the reliability of the software. Beta releases may | |
369 | cause loss of data, functionality, or services and are provided for | |
370 | testing by qualified individuals.</P> | |
371 | <P>Beta releases are an OPTIONAL part of the release process and are | |
372 | generated as deemed appropriate by the release coordinator. Functional | |
373 | changes may be included in subsequent beta releases until the first | |
374 | release candidate.</P> | |
375 | <H3><A NAME="5_4_2">5.4.2 Release Candidates</A></H3> | |
376 | <P>Release candidates are generated at least two weeks prior to a | |
377 | production release. Release candidates are targeted for end-users that | |
378 | wish to test new functionality or bug fixes prior to the production | |
379 | release. While release candidates are intended to be substantially | |
380 | bug-free, they may still contain defects and/or not compile on specific | |
381 | platforms.</P> | |
382 | <P>At least one release candidate is REQUIRED prior to any production | |
383 | release. The distribution of a release candidate marks the end of any | |
384 | functional improvements. Release candidates are generated at weekly | |
385 | intervals until all level 4/5 trouble reports are resolved.</P> | |
386 | <H3><A NAME="5_4_3">5.4.3 Production Releases</A></H3> | |
387 | <P>Production releases are generated after a successful release | |
388 | candidate and represent a stable release of the software suitable for | |
389 | all users.</P> | |
390 | <H1 TYPE="A" VALUE="1"><A NAME="6">A Glossary</A></H1> | |
391 | <H2><A NAME="6_1">A.1 Terms</A></H2> | |
392 | <DL> | |
393 | <DT>C</DT> | |
394 | <DD>A computer language.</DD> | |
395 | <DT>parallel</DT> | |
396 | <DD>Sending or receiving data more than 1 bit at a time.</DD> | |
397 | <DT>pipe</DT> | |
398 | <DD>A one-way communications channel between two programs.</DD> | |
399 | <DT>serial</DT> | |
400 | <DD>Sending or receiving data 1 bit at a time.</DD> | |
401 | <DT>socket</DT> | |
402 | <DD>A two-way network communications channel.</DD> | |
403 | </DL> | |
404 | <H2><A NAME="6_2">A.2 Acronyms</A></H2> | |
405 | <DL> | |
406 | <DT>ASCII</DT> | |
407 | <DD>American Standard Code for Information Interchange</DD> | |
408 | <DT>CUPS</DT> | |
409 | <DD>Common UNIX Printing System</DD> | |
410 | <DT>ESC/P</DT> | |
411 | <DD>EPSON Standard Code for Printers</DD> | |
412 | <DT>FTP</DT> | |
413 | <DD>File Transfer Protocol</DD> | |
414 | <DT>HP-GL</DT> | |
415 | <DD>Hewlett-Packard Graphics Language</DD> | |
416 | <DT>HP-PCL</DT> | |
417 | <DD>Hewlett-Packard Page Control Language</DD> | |
418 | <DT>HP-PJL</DT> | |
419 | <DD>Hewlett-Packard Printer Job Language</DD> | |
420 | <DT>IETF</DT> | |
421 | <DD>Internet Engineering Task Force</DD> | |
422 | <DT>IPP</DT> | |
423 | <DD>Internet Printing Protocol</DD> | |
424 | <DT>ISO</DT> | |
425 | <DD>International Standards Organization</DD> | |
426 | <DT>LPD</DT> | |
427 | <DD>Line Printer Daemon</DD> | |
428 | <DT>MIME</DT> | |
429 | <DD>Multimedia Internet Mail Exchange</DD> | |
430 | <DT>PPD</DT> | |
431 | <DD>PostScript Printer Description</DD> | |
432 | <DT>SMB</DT> | |
433 | <DD>Server Message Block</DD> | |
434 | <DT>TFTP</DT> | |
435 | <DD>Trivial File Transfer Protocol</DD> | |
436 | </DL> | |
437 | <H1><A NAME="7">B Coding Requirements</A></H1> | |
438 | <P>These coding requirements provide detailed information on source file | |
439 | formatting and documentation content. These guidelines shall be applied | |
440 | to all C and C++ source files provided with CUPS. Source code for other | |
441 | languages should conform to these requirements as allowed by the | |
442 | language.</P> | |
443 | <H2><A NAME="7_1">B.1 Source Files</A></H2> | |
444 | <H3><A NAME="7_1_1">B.1.1 Naming</A></H3> | |
445 | <P>All source files names shall be 16 characters or less in length to | |
446 | ensure compatibility with older UNIX filesystems. Source files | |
447 | containing functions shall have an extension of ".c" for ANSI C and | |
448 | ".cxx" for C++ source files. All other "include" files shall have an | |
449 | extension of ".h".</P> | |
450 | <H3><A NAME="7_1_2">B.1.2 Documentation</A></H3> | |
451 | <P>The top of each source file shall contain a header giving the name of | |
452 | the file, the purpose or nature of the source file, the copyright and | |
453 | licensing notice, and the functions contained in the file. The file | |
454 | name and revision information is provided by the CVS "$Id$" tag:</P> | |
455 | <PRE> | |
456 | /* | |
457 | * "$Id$" | |
458 | * | |
459 | * Description of file contents. | |
460 | * | |
461 | * Copyright 1997-2005 by Easy Software Products, all rights | |
462 | * reserved. | |
463 | * | |
464 | * These coded instructions, statements, and computer programs are | |
465 | * the property of Easy Software Products and are protected by | |
466 | * Federal copyright law. Distribution and use rights are outlined | |
467 | * in the file "LICENSE.txt" which should have been included with | |
468 | * this file. If this file is missing or damaged please contact | |
469 | * Easy Software Products at: | |
470 | * | |
471 | * Attn: CUPS Licensing Information | |
472 | * Easy Software Products | |
473 | * 44141 Airport View Drive, Suite 204 | |
474 | * Hollywood, Maryland 20636 USA | |
475 | * | |
476 | * Voice: (301) 373-9600 | |
477 | * EMail: cups-info@cups.org | |
478 | * WWW: http://www.cups.org | |
479 | * | |
480 | * Contents: | |
481 | * | |
482 | * function1() - Description 1. | |
483 | * function2() - Description 2. | |
484 | * function3() - Description 3. | |
485 | */ | |
486 | </PRE> | |
487 | ||
488 | <!-- NEED 1in --> | |
489 | <P>For source files that are subject to the Apple OS-Developed Software | |
490 | exception, the following additional comment should appear after the | |
491 | contact information:</P> | |
492 | <PRE> | |
493 | * This file is subject to the Apple OS-Developed Software exception. | |
494 | </PRE> | |
495 | <P>The bottom of each source file shall contain a trailer giving the | |
496 | name of the file using the CVS "$Id$" tag. The primary purpose of this | |
497 | is to mark the end of a source file; if the trailer is missing it is | |
498 | possible that code has been lost near the end of the file:</P> | |
499 | <PRE> | |
500 | /* | |
501 | * End of "$Id$". | |
502 | */ | |
503 | </PRE> | |
504 | <H2><A NAME="7_2">B.2 Functions</A></H2> | |
505 | <H3><A NAME="7_2_1">B.2.1 Naming</A></H3> | |
506 | <P>Functions with a global scope shall be capitalized ("DoThis", | |
507 | "DoThat", "DoSomethingElse", etc.) The only exception to this rule | |
508 | shall be the CUPS interface library functions which may begin with a | |
509 | prefix word in lowercase ("cupsDoThis", "cupsDoThat", etc.)</P> | |
510 | <P>Functions with a local scope shall be declared "static" and be | |
511 | lowercase with underscores between words ("do_this", "do_that", | |
512 | "do_something_else", etc.)</P> | |
513 | <H3><A NAME="7_2_2">B.2.2 Documentation</A></H3> | |
514 | <P>Each function shall begin with a comment header describing what the | |
515 | function does, the possible input limits (if any), and the possible | |
516 | output values (if any), and any special information needed:</P> | |
517 | <PRE> | |
518 | /* | |
519 | * 'do_this()' - Compute y = this(x). | |
520 | * | |
521 | * Notes: none. | |
522 | */ | |
523 | ||
524 | static float /* O - Inverse power value, 0.0 <= y <= 1.1 */ | |
525 | do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */ | |
526 | { | |
527 | ... | |
528 | return (y); | |
529 | } | |
530 | </PRE> | |
531 | <P>Return/output values are indicated using an "O" prefix, input values | |
532 | are indicated using the "I" prefix, and values that are both input and | |
533 | output use the "IO" prefix for the corresponding in-line comment.</P> | |
534 | <H2><A NAME="7_3">B.3 Methods</A></H2> | |
535 | <H3><A NAME="7_3_1">B.3.1 Naming</A></H3> | |
536 | <P>Methods shall be in lowercase with underscores between words | |
537 | ("do_this", "do_that", "do_something_else", etc.)</P> | |
538 | <H3><A NAME="7_3_2">B.3.2 Documentation</A></H3> | |
539 | <P>Each method shall begin with a comment header describing what the | |
540 | method does, the possible input limits (if any), and the possible | |
541 | output values (if any), and any special information needed:</P> | |
542 | <PRE> | |
543 | /* | |
544 | * 'class::do_this()' - Compute y = this(x). | |
545 | * | |
546 | * Notes: none. | |
547 | */ | |
548 | ||
549 | float /* O - Inverse power value, 0.0 <= y <= 1.0 */ | |
550 | class::do_this(float x) /* I - Power value (0.0 <= x <= 1.0) */ | |
551 | { | |
552 | ... | |
553 | return (y); | |
554 | } | |
555 | </PRE> | |
556 | <P>Return/output values are indicated using an "O" prefix, input values | |
557 | are indicated using the "I" prefix, and values that are both input and | |
558 | output use the "IO" prefix for the corresponding in-line comment.</P> | |
559 | <H2><A NAME="7_4">B.4 Variables</A></H2> | |
560 | <H3><A NAME="7_4_1">B.4.1 Naming</A></H3> | |
561 | <P>Variables with a global scope shall be capitalized ("ThisVariable", | |
562 | "ThatVariable", "ThisStateVariable", etc.) The only exception to this | |
563 | rule shall be the CUPS interface library global variables which must | |
564 | begin with the prefix "cups" ("cupsThisVariable", "cupsThatVariable", | |
565 | etc.) Global variables shall be replaced by function arguments whenever | |
566 | possible.</P> | |
567 | <P>Variables with a local scope shall be lowercase with underscores | |
568 | between words ("this_variable", "that_variable", etc.) Any local | |
569 | variables shared by functions within a source file shall be declared | |
570 | "static".</P> | |
571 | <H3><A NAME="7_4_2">B.4.2 Documentation</A></H3> | |
572 | <P>Each variable shall be declared on a separate line and shall be | |
573 | immediately followed by a comment block describing the variable:</P> | |
574 | <PRE> | |
575 | int this_variable; /* The current state of this */ | |
576 | int that_variable; /* The current state of that */ | |
577 | </PRE> | |
578 | <H2><A NAME="7_5">B.5 Types</A></H2> | |
579 | <H3><A NAME="7_5_1">B.5.1 Naming</A></H3> | |
580 | <P>All type names shall be lowercase with underscores between words and | |
581 | "_t" appended to the end of the name ("this_type_t", "that_type_t", | |
582 | etc.)</P> | |
583 | <H3><A NAME="7_5_2">B.5.2 Documentation</A></H3> | |
584 | <P>Each type shall have a comment block immediately before the typedef:</P> | |
585 | <PRE> | |
586 | /* | |
587 | * This type is for CUPS foobar options. | |
588 | */ | |
589 | typedef int cups_this_type_t; | |
590 | </PRE> | |
591 | <H2><A NAME="7_6">B.6 Structures</A></H2> | |
592 | <H3><A NAME="7_6_1">B.6.1 Naming</A></H3> | |
593 | <P>All structure names shall be lowercase with underscores between words | |
594 | and "_str" appended to the end of the name ("this_struct_str", | |
595 | "that_struct_str", etc.)</P> | |
596 | <H3><A NAME="7_6_2">B.6.2 Documentation</A></H3> | |
597 | <P>Each structure shall have a comment block immediately before the | |
598 | struct and each member shall be documented in accordance with the | |
599 | variable naming policy above:</P> | |
600 | <PRE> | |
601 | /* | |
602 | * This structure is for CUPS foobar options. | |
603 | */ | |
604 | struct cups_this_struct_str | |
605 | { | |
606 | int this_member; /* Current state for this */ | |
607 | int that_member; /* Current state for that */ | |
608 | }; | |
609 | </PRE> | |
610 | <H2><A NAME="7_7">B.7 Classes</A></H2> | |
611 | <H3><A NAME="7_7_1">B.7.1 Naming</A></H3> | |
612 | <P>All class names shall be lowercase with underscores between words | |
613 | ("this_class", "that_class", etc.)</P> | |
614 | <H3><A NAME="7_7_2">B.7.2 Documentation</A></H3> | |
615 | <P>Each class shall have a comment block immediately before the class | |
616 | and each member shall be documented in accordance with the variable | |
617 | naming policy above:</P> | |
618 | <PRE> | |
619 | /* | |
620 | * This class is for CUPS foobar options. | |
621 | */ | |
622 | class cups_this_class | |
623 | { | |
624 | int this_member; /* Current state for this */ | |
625 | int that_member; /* Current state for that */ | |
626 | }; | |
627 | </PRE> | |
628 | <H2><A NAME="7_8">B.8 Constants</A></H2> | |
629 | <H3><A NAME="7_8_1">B.8.1 Naming</A></H3> | |
630 | <P>All constant names shall be uppercase with underscored between words | |
631 | ("THIS_CONSTANT", "THAT_CONSTANT", etc.) Constants defined for the CUPS | |
632 | interface library must begin with an uppercase prefix | |
633 | ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.)</P> | |
634 | <P>Typed enumerations shall be used whenever possible to allow for type | |
635 | checking by the compiler.</P> | |
636 | <H3><A NAME="7_8_2">B.8.2 Documentation</A></H3> | |
637 | <P>Comment blocks shall immediately follow each constant:</P> | |
638 | <PRE> | |
639 | enum | |
640 | { | |
641 | CUPS_THIS_TRAY, /* This tray */ | |
642 | CUPS_THAT_TRAY /* That tray */ | |
643 | }; | |
644 | </PRE> | |
645 | <H2><A NAME="7_9">B.9 Code</A></H2> | |
646 | <H3><A NAME="7_9_1">B.9.1 Documentation</A></H3> | |
647 | <P>All source code shall utilize block comments within functions to | |
648 | describe the operations being performed by a group of statements:</P> | |
649 | <PRE> | |
650 | /* | |
651 | * Clear the state array before we begin... | |
652 | */ | |
653 | ||
654 | for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) | |
655 | array[i] = STATE_IDLE; | |
656 | ||
657 | /* | |
658 | * Wait for state changes... | |
659 | */ | |
660 | ||
661 | do | |
662 | { | |
663 | for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) | |
664 | if (array[i] != STATE_IDLE) | |
665 | break; | |
666 | ||
667 | if (i == (sizeof(array) / sizeof(array[0]))) | |
668 | sleep(1); | |
669 | } while (i == (sizeof(array) / sizeof(array[0]))); | |
670 | </PRE> | |
671 | <H3><A NAME="7_9_2">B.9.2 Style</A></H3> | |
672 | <H4 TYPE="a">B.9.2.a Indentation</H4> | |
673 | <P>All code blocks enclosed by brackets shall begin with the opening | |
674 | brace on a new line. The code then follows starting on a new line after | |
675 | the brace and is indented 2 spaces. The closing brace is then placed on | |
676 | a new line following the code at the original indentation:</P> | |
677 | <PRE> | |
678 | { | |
679 | int i; /* Looping var */ | |
680 | ||
681 | /* | |
682 | * Process foobar values from 0 to 999... | |
683 | */ | |
684 | ||
685 | for (i = 0; i < 1000; i ++) | |
686 | { | |
687 | do_this(i); | |
688 | do_that(i); | |
689 | } | |
690 | } | |
691 | </PRE> | |
692 | <P>Single-line statements following "do", "else", "for", "if", and | |
693 | "while" shall be indented 2 spaces as well. Blocks of code in a | |
694 | "switch" block shall be indented 4 spaces after each "case" and | |
695 | "default" case:</P> | |
696 | <PRE> | |
697 | switch (array[i]) | |
698 | { | |
699 | case STATE_IDLE : | |
700 | do_this(i); | |
701 | do_that(i); | |
702 | break; | |
703 | default : | |
704 | do_nothing(i); | |
705 | break; | |
706 | } | |
707 | </PRE> | |
708 | <H4>B.9.2.b Spacing</H4> | |
709 | <P>A space shall follow each reserved word ("if", "while", etc.) Spaces | |
710 | shall not be inserted between a function name and the arguments in | |
711 | parenthesis.</P> | |
712 | <H4>B.9.2.c Return Values</H4> | |
713 | <P>Parenthesis shall surround values returned from a function using | |
714 | "return":</P> | |
715 | <PRE> | |
716 | return (STATE_IDLE); | |
717 | </PRE> | |
718 | <H4>B.9.2.d Loops</H4> | |
719 | <P>Whenever convenient loops should count downward to zero to improve | |
720 | program performance:</P> | |
721 | <PRE> | |
722 | for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --) | |
723 | array[i] = STATE_IDLE; | |
724 | </PRE> | |
725 | <H1 ALIGN="RIGHT"><A NAME="8">C Software Trouble Report Form</A></H1> | |
726 | <CENTER> | |
727 | <TABLE WIDTH="80%"> | |
728 | <TR><TH ALIGN="RIGHT">Summary of Problem:</TH><TD COLSPAN="2"> | |
729 | _____________________________________________</TD></TR> | |
730 | <TR><TD COLSPAN="3"> </TD></TR> | |
731 | <TR><TH ALIGN="RIGHT" ROWSPAN="5" VALIGN="TOP">Problem Severity:</TH><TD> | |
732 | __1</TD><TD>Request for enhancement, e.g. asking for a feature</TD></TR> | |
733 | <TR><TD>__2</TD><TD>Low, e.g. a documentation error or undocumented | |
734 | side-effect</TD></TR> | |
735 | <TR><TD>__3</TD><TD>Moderate, e.g. unable to print a file or unable to | |
736 | compile the software</TD></TR> | |
737 | <TR><TD>__4</TD><TD>High, e.g. unable to print to a printer or key | |
738 | functionality not working</TD></TR> | |
739 | <TR><TD>__5</TD><TD>Critical, e.g. unable to print at all</TD></TR> | |
740 | <TR><TD COLSPAN="3"> </TD></TR> | |
741 | <TR><TH ALIGN="RIGHT" ROWSPAN="3" VALIGN="TOP">Problem Scope:</TH><TD> | |
742 | __1</TD><TD>Machine or printer</TD></TR> | |
743 | <TR><TD>__2</TD><TD>Operating System</TD></TR> | |
744 | <TR><TD>__3</TD><TD>All machines, printers, or operating systems</TD></TR> | |
745 | <TR><TD COLSPAN="3"> </TD></TR> | |
746 | <TR><TH ALIGN="RIGHT" VALIGN="TOP">Detailed Description of Problem:</TH><TD | |
747 | COLSPAN="2">_____________________________________________ | |
748 | <BR> _____________________________________________ | |
749 | <BR> _____________________________________________ | |
750 | <BR> _____________________________________________ | |
751 | <BR> _____________________________________________</TD></TR> | |
752 | </TABLE> | |
753 | </CENTER> | |
754 | </BODY> | |
755 | </HTML> |