]>
Commit | Line | Data |
---|---|---|
4744bd90 | 1 | <HTML> |
2 | <!-- SECTION: Specifications --> | |
3 | <HEAD> | |
e1d6a774 | 4 | <TITLE>CUPS Developer Guide</TITLE> |
4744bd90 | 5 | </HEAD> |
6 | <BODY> | |
7 | ||
e1d6a774 | 8 | <P>This developer guide documents the guidelines and processes we |
9 | use when developing and maintaining the Common UNIX Printing | |
10 | System ("CUPS") and related software. Our goal is to provide | |
11 | reliable and efficient software and documentation that addresses | |
12 | the needs of our users.</P> | |
4744bd90 | 13 | |
14 | <H2 CLASS="title"><A NAME="COMMUNICATION">Communication</A></H2> | |
15 | ||
16 | <H3><A NAME="CONTACT">How to Contact the Developers</A></H3> | |
17 | ||
18 | <P>The <A HREF="http://www.cups.org/newsgroups.php">CUPS | |
19 | Forums</A> are the primary means of asking questions and | |
20 | informally discussing issues and feature requests with the CUPS | |
21 | developers. Table 1 shows the available forums and their | |
22 | focus:</P> | |
23 | ||
24 | <DIV CLASS="table"><TABLE SUMMARY="CUPS Forums"> | |
25 | <CAPTION>Table 1: CUPS Forums</CAPTION> | |
26 | <TR> | |
27 | <TH>Forum</TH> | |
28 | <TH>Focus/Purpose</TH> | |
29 | </TR> | |
30 | <TR> | |
31 | <TD>cups.bugs</TD> | |
32 | <TD>Discussion of bugs and issues in the CUPS | |
33 | software</TD> | |
34 | </TR> | |
35 | <TR> | |
36 | <TD>cups.commit</TD> | |
37 | <TD>Report of all commits to the Subversion repository | |
38 | (read-only)</TD> | |
39 | </TR> | |
40 | <TR> | |
41 | <TD>cups.ddk</TD> | |
42 | <TD>Usage and development questions for the CUPS Driver | |
43 | Development Kit</TD> | |
44 | </TR> | |
45 | <TR> | |
46 | <TD>cups.development</TD> | |
47 | <TD>Development questions and discussion of new features | |
48 | in the CUPS software</TD> | |
49 | </TR> | |
50 | <TR> | |
51 | <TD>cups.general</TD> | |
52 | <TD>Usage questions for the CUPS software</TD> | |
53 | </TR> | |
54 | </TABLE></DIV> | |
55 | ||
56 | <H3><A NAME="SUBMIT">How to Submit a Bug Report or Feature Request</A></H3> | |
57 | ||
58 | <P>The CUPS "<A HREF="http://www.cups.org/str.php">Bugs & | |
59 | Features</A>" page provides access to the CUPS <em>software | |
60 | trouble report</em> database and is the formal way to submit a | |
61 | bug report or feature request to the CUPS developers. Please | |
62 | note, however, that we <em>do not</em> provide answers to usage | |
63 | questions or resolve problems in third-party software on this | |
64 | page - use the CUPS Forums for that instead.</P> | |
65 | ||
66 | <P>Unlike discussions that occur on the CUPS Forums, formal bug | |
67 | reports and feature requests must be acted on by the CUPS | |
68 | developers. This does not mean that every bug report is resolved | |
69 | or every feature request is implemented, but we do respond and | |
70 | keep track of them all for posterity.</P> | |
71 | ||
72 | <BLOCKQUOTE>Please use the search feature of the Bugs & | |
73 | Features page before submitting a new bug report or feature | |
74 | request. If you see an existing report that matches your issue, | |
75 | please post a message to that report ("I have this issue as | |
76 | well", "I would also like to see", etc.) rather than submitting a | |
77 | new report. This helps speed the resolution of your issue by | |
78 | reducing the CUPS developers' work load.</BLOCKQUOTE> | |
79 | ||
80 | <H3><A NAME="PATCH">How to Prepare a Patch</A></H3> | |
81 | ||
82 | <P>When submitting a bug report or feature request, you can | |
83 | include patch files that resolve the bug or implement the feature | |
84 | to speed the inclusion of that bug fix or feature in a new CUPS | |
85 | release. For changes to existing files, we prefer a unified diff | |
86 | against the current Subversion <VAR>trunk</VAR> branch, which can | |
87 | be generated easily using the following Subversion command:</P> | |
88 | ||
89 | <PRE CLASS="command"> | |
90 | svn diff >filename.patch | |
91 | </PRE> | |
92 | ||
93 | <P>If you produce a patch using a released source archive, use | |
94 | one of the following commands instead:</P> | |
95 | ||
96 | <PRE CLASS="command"> | |
97 | diff -u oldfilename filename >filename.patch | |
98 | ||
99 | diff -urN olddirectory directory >filename.patch | |
100 | </PRE> | |
101 | ||
102 | <P>New files and files with significant changes can be submitted | |
103 | in their entirety, however that may delay the adoption of your | |
104 | changes.</P> | |
105 | ||
106 | <BLOCKQUOTE>Patches and files must conform to the standards | |
107 | outlined in the "<A HREF="#CODING">Coding Guidelines</A>" and "<A | |
108 | HREF="#MAKEFILES">Makefile Guidelines</A>" sections in this | |
bc44d920 | 109 | document. In addition, since Apple Inc. provides CUPS |
4744bd90 | 110 | under multiple licenses, we require that you assign the copyright |
111 | for your changes and files to us for inclusion in | |
112 | CUPS.</BLOCKQUOTE> | |
113 | ||
114 | ||
115 | <H2 CLASS="title"><A NAME="PRACTICES">Software Development Practices</A></H2> | |
116 | ||
117 | <H3><A NAME="VERSIONS">Version Numbering</A></H3> | |
118 | ||
119 | <P>CUPS uses a three-part version number separated by periods to | |
120 | represent the major, minor, and patch release numbers. Major | |
121 | release numbers indicate large design changes or | |
122 | backwards-incompatible changes to the CUPS API or CUPS Imaging | |
123 | API. Minor release numbers indicate new features and other | |
124 | smaller changes which are backwards-compatible with previous CUPS | |
125 | releases. Patch numbers indicate bug fixes to the previous | |
126 | release.</P> | |
127 | ||
128 | <BLOCKQUOTE>When we talk about compatibility, we are talking | |
129 | about binary compatibility for public APIs and output format | |
130 | compatibility for program interfaces. Changes to configuration | |
131 | file formats or the default behavior of programs are not | |
132 | generally considered incompatible as the upgrade process can | |
133 | normally address such changes gracefully.</BLOCKQUOTE> | |
134 | ||
135 | <P>Production releases use the plain version numbers:</P> | |
136 | ||
137 | <PRE CLASS="command"> | |
138 | MAJOR.MINOR.PATCH | |
139 | 1.0.0 | |
140 | 1.0.1 | |
141 | 1.0.2 | |
142 | ... | |
143 | 1.1.0 | |
144 | ... | |
145 | 1.1.23 | |
146 | 1.2.0 | |
147 | 1.2.1 | |
148 | ... | |
149 | 1.3.0 | |
150 | ... | |
151 | 2.0.0 | |
152 | </PRE> | |
153 | ||
154 | <P>The first production release in a MAJOR.MINOR series | |
155 | (MAJOR.MINOR.0) is called a feature release. Feature releases are | |
156 | the only releases that may contain new features. Subsequent | |
157 | production releases in a MAJOR.MINOR series may only contain bug | |
158 | fixes.</P> | |
159 | ||
160 | <BLOCKQUOTE>We did not hold to this limitation in the CUPS 1.1 | |
161 | series for a variety of reasons. Starting with CUPS 1.2, the "no | |
162 | new features in a patch release" policy will be strictly | |
163 | enforced. This should yield more frequent minor releases with | |
164 | fewer new features (and interactions!) to | |
165 | validate/test.</BLOCKQUOTE> | |
166 | ||
167 | <P>Beta-test releases are identified by appending the letter B | |
168 | to the major and minor version numbers followed by the beta | |
169 | release number:</P> | |
170 | ||
171 | <PRE CLASS="command"> | |
172 | MAJOR.MINORbNUMBER | |
173 | 1.2b1 | |
174 | </PRE> | |
175 | ||
176 | <P>Release candidates are identified by appending the letters RC | |
177 | to the major and minor version numbers followed by the release | |
178 | candidate number:</P> | |
179 | ||
180 | <PRE CLASS="command"> | |
181 | MAJOR.MINORrcNUMBER | |
182 | 1.2rc1 | |
183 | </PRE> | |
184 | ||
185 | <P>Developer snapshots are identified by appending the letters | |
186 | SVN-R to the major and minor version numbers followed by the | |
187 | revision number:</P> | |
188 | ||
189 | <PRE CLASS="command"> | |
190 | MAJOR.MINORsvn-rREV | |
191 | 1.2svn-r1234 | |
192 | </PRE> | |
193 | ||
194 | <P>Beta-test releases, release candidates, and developer | |
195 | snapshots are only created for new minor releases. Once a | |
196 | production release has been made (MAJOR.MINOR.0), subsequent | |
197 | patch releases are issues without preliminary beta or release | |
198 | testing.</P> | |
199 | ||
200 | <H3>Version Control (Subversion)</H3> | |
201 | ||
202 | <P>The CUPS source files are managed by the Subversion ("SVN") | |
203 | software, available at:</P> | |
204 | ||
205 | <PRE CLASS="command"> | |
206 | <A HREF="http://subversion.tigris.org/" TARGET="_blank">subversion.tigris.org</A> | |
207 | </PRE> | |
208 | ||
209 | <P>Source files are "checked in" with each change so that | |
210 | modifications can be tracked, and each checkin must reference any | |
211 | applicable STRs. The following format <em>must</em> be used for | |
212 | commit log messages:</P> | |
213 | ||
214 | <PRE CLASS="command"> | |
215 | Summary of the change ("fix PostScript printing bug") along | |
216 | with corresponding STRs ("STR #1, STR #6") | |
217 | ||
218 | foo.cxx: | |
219 | - function(): Detailed list of changes | |
220 | - function2(): Detailed list of changes | |
221 | - Summary of design changes ("added new foo struct") | |
222 | ||
223 | bar.h: | |
224 | - More detailed changes | |
225 | </PRE> | |
226 | ||
227 | <P>Primary development occurs on the <var>trunk</var> branch, | |
228 | with changes merged back to release branches as needed. Table 2 | |
229 | shows the URLs developers use for the various CUPS subprojects | |
230 | and branches:</P> | |
231 | ||
232 | <DIV CLASS="table"><TABLE SUMMARY="CUPS Subversion URLs"> | |
233 | <CAPTION>Table 2: CUPS Subversion URLs</CAPTION> | |
234 | <TR> | |
235 | <TH>URL</TH> | |
236 | <TH>Purpose</TH> | |
237 | </TR> | |
238 | <TR> | |
239 | <TD><A HREF="http://svn.easysw.com/public/cups/trunk/">https://svn.easysw.com/public/cups/trunk/</A></TD> | |
240 | <TD>Primary CUPS development branch</TD> | |
241 | </TR> | |
242 | <TR> | |
243 | <TD><A HREF="http://svn.easysw.com/public/cups/branches/">https://svn.easysw.com/public/cups/branches/</A></TD> | |
244 | <TD>CUPS maintenance branches (merge-only)</TD> | |
245 | </TR> | |
246 | <TR> | |
247 | <TD><A HREF="http://svn.easysw.com/public/cups/tags/">https://svn.easysw.com/public/cups/tags/</A></TD> | |
248 | <TD>CUPS release tags (read-only)</TD> | |
249 | </TR> | |
250 | <TR> | |
251 | <TD><A HREF="http://svn.easysw.com/public/cupsddk/trunk/">https://svn.easysw.com/public/cupsddk/trunk/</A></TD> | |
252 | <TD>Primary CUPS DDK development branch</TD> | |
253 | </TR> | |
254 | <TR> | |
255 | <TD><A HREF="http://svn.easysw.com/public/cupsddk/branches/">https://svn.easysw.com/public/cupsddk/branches/</A></TD> | |
256 | <TD>CUPS DDK maintenance branches (merge-only)</TD> | |
257 | </TR> | |
258 | <TR> | |
259 | <TD><A HREF="http://svn.easysw.com/public/cupsddk/tags/">https://svn.easysw.com/public/cupsddk/tags/</A></TD> | |
260 | <TD>CUPS DDK release tags (read-only)</TD> | |
261 | </TR> | |
262 | <TR> | |
263 | <TD><A HREF="http://svn.easysw.com/public/espgs/trunk/">https://svn.easysw.com/public/espgs/trunk/</A></TD> | |
264 | <TD>Primary ESP Ghostscript development branch</TD> | |
265 | </TR> | |
266 | <TR> | |
267 | <TD><A HREF="http://svn.easysw.com/public/espgs/branches/">https://svn.easysw.com/public/espgs/branches/</A></TD> | |
268 | <TD>ESP Ghostscript maintenance branches (merge-only)</TD> | |
269 | </TR> | |
270 | <TR> | |
271 | <TD><A HREF="http://svn.easysw.com/public/espgs/tags/">https://svn.easysw.com/public/espgs/tags/</A></TD> | |
272 | <TD>ESP Ghostscript release tags (read-only)</TD> | |
273 | </TR> | |
274 | <TR> | |
275 | <TD><A HREF="http://svn.easysw.com/public/windows/trunk/">https://svn.easysw.com/public/windows/trunk/</A></TD> | |
276 | <TD>Primary CUPS Windows Driver development branch</TD> | |
277 | </TR> | |
278 | <TR> | |
279 | <TD><A HREF="http://svn.easysw.com/public/windows/branches/">https://svn.easysw.com/public/windows/branches/</A></TD> | |
280 | <TD>CUPS Windows Driver maintenance branches (merge-only)</TD> | |
281 | </TR> | |
282 | <TR> | |
283 | <TD><A HREF="http://svn.easysw.com/public/windows/tags/">https://svn.easysw.com/public/windows/tags/</A></TD> | |
284 | <TD>CUPS Windows Driver release tags (read-only)</TD> | |
285 | </TR> | |
286 | </TABLE></DIV> | |
287 | ||
288 | <P>The branch for a MAJOR.MINOR release are created when the | |
289 | first production release (MAJOR.MINOR.0) is made using the name | |
290 | "branch-MAJOR.MINOR". Release tags are created for every beta, | |
291 | candidate, and production release using the name | |
292 | "release-MAJOR.MINOR.PATCHbNUMBER", | |
293 | "release-MAJOR.MINOR.PATCHrcNUMBER", or | |
294 | "release-MAJOR.MINOR.PATCH", respectively. No release tags are | |
295 | created for developer snapshots.</P> | |
296 | ||
297 | ||
298 | <H3>Files and Directories</H3> | |
299 | ||
300 | <P>File and directory names may not exceed 16 characters in | |
301 | length to ensure compability with older UNIX filesystems. In | |
302 | addition, to avoid problems with case-insensitive filesystems, | |
303 | you may not use names which differ only by case, for example | |
304 | "ReadMe" and "README" are not allowed in the same directory.</P> | |
305 | ||
306 | <P>Source files must be documented and formatted as described in | |
307 | "<A HREF="#CODING">Coding Requirements</A>". Make files must | |
308 | follow the guidelines in "<A HREF="#MAKEFILE">Makefile | |
309 | Guidelines</A>".</P> | |
310 | ||
311 | ||
312 | <H3>Build System</H3> | |
313 | ||
314 | <P>The CUPS build system uses <A | |
315 | HREF="http://www.gnu.org/software/autoconf/">GNU autoconf</A> to | |
316 | tailor the library to the local operating system. Project files | |
317 | for major IDEs are also provided for Microsoft | |
bc44d920 | 318 | Windows<SUP>®</SUP>. To improve portability, makefiles must |
4744bd90 | 319 | not make use of the unique features offered by <A |
320 | HREF="http://www.gnu.org/software/make/">GNU make</A>. See the <A | |
321 | HREF="#MAKEFILES">Makefile Guidelines</A> section for a | |
322 | description of the allowed make features and makefile | |
323 | guidelines.</P> | |
324 | ||
325 | <P>Additional GNU build programs such as <A | |
326 | HREF="http://www.gnu.org/software/automake">GNU automake</A> and | |
327 | <A HREF="http://www.gnu.org/software/libtool">GNU libtool</A> | |
328 | must not be used. GNU automake produces non-portable makefiles | |
329 | which depend on GNU-specific extensions, and GNU libtool is not | |
330 | portable or reliable enough for CUPS.</P> | |
331 | ||
332 | ||
333 | <H3><A NAME="PACKAGING">Packaging</A></H3> | |
334 | ||
335 | <P>Source packages are created using the | |
336 | <VAR>tools/makesrcdist</VAR> script in the Subversion repository. | |
337 | The script optionally uses a version number argument:</P> | |
338 | ||
339 | <PRE CLASS="command"> | |
340 | tools/makesrcdist | |
341 | tools/makesrcdist <I>version</I> | |
342 | </PRE> | |
343 | ||
344 | <P>When run with no arguments, the script creates a snapshot of | |
345 | the current working copy and names it using the highest revision | |
346 | number in the WC, for example | |
bc44d920 | 347 | "/tmp/cups-1.3svn-r1234-source.tar.bz2" and |
348 | "/tmp/cups-1.3svn-r1234-source.tar.gz". When run with two | |
4744bd90 | 349 | arguments, the script creates a release tag in the repository and |
350 | exports that tag, creating the files | |
351 | "/tmp/cups-<I>version</I>-source.tar.bz2" and | |
352 | "/tmp/cups-<I>version</I>-source.tar.gz".</P> | |
353 | ||
354 | <P>Binary packages are not generally distributed by the CUPS | |
355 | team, however the <VAR>packaging/cups.spec</VAR> and | |
356 | <VAR>packaging/cups.list</VAR> files may be used to create binary | |
bc44d920 | 357 | packages on Linux, Mac OS X, and UNIX. The |
4744bd90 | 358 | <VAR>packaging/cups.spec</VAR> file produces a binary package |
359 | using the <CODE>rpmbuild(8)</CODE> software:</P> | |
360 | ||
361 | <PRE CLASS="command"> | |
362 | rpmbuild -ta cups-<I>version</I>-source.tar.gz | |
363 | </PRE> | |
364 | ||
365 | <P>The <VAR>cups.list</VAR> file is generated by the | |
366 | <VAR>configure</VAR> script and produces binary packages for many | |
367 | platforms using the <A HREF="http://www.easysw.com/epm/" | |
368 | TARGET="_blank">EPM</A> software. Table 3 shows the targets that | |
369 | are available for each type of binary package:</P> | |
370 | ||
371 | <DIV CLASS="table"><TABLE SUMMARY="Binary Package Targets"> | |
372 | <CAPTION>Table 3: Binary Package Targets</CAPTION> | |
373 | <TR> | |
374 | <TH>Target</TH> | |
375 | <TH>Type of Package</TH> | |
376 | </TR> | |
377 | <TR> | |
378 | <TD>aix</TD> | |
379 | <TD>AIX installp</TD> | |
380 | </TR> | |
381 | <TR> | |
382 | <TD>bsd</TD> | |
383 | <TD>*BSD pkg_install</TD> | |
384 | </TR> | |
385 | <TR> | |
386 | <TD>deb</TD> | |
387 | <TD>Debian dpkg</TD> | |
388 | </TR> | |
389 | <TR> | |
390 | <TD>depot</TD> | |
391 | <TD>HP-UX swinstall</TD> | |
392 | </TR> | |
393 | <TR> | |
394 | <TD>epm</TD> | |
395 | <TD>Portable tarball with install script</TD> | |
396 | </TR> | |
397 | <TR> | |
398 | <TD>inst</TD> | |
399 | <TD>IRIX inst/tardist</TD> | |
400 | </TR> | |
401 | <TR> | |
402 | <TD>osx</TD> | |
bc44d920 | 403 | <TD>Mac OS X Install</TD> |
4744bd90 | 404 | </TR> |
405 | <TR> | |
406 | <TD>pkg</TD> | |
407 | <TD>Solaris pkgadd</TD> | |
408 | </TR> | |
409 | <TR> | |
410 | <TD>rpm</TD> | |
411 | <TD>RPM binary</TD> | |
412 | </TR> | |
413 | <TR> | |
414 | <TD>setld</TD> | |
415 | <TD>Tru64 UNIX setld</TD> | |
416 | </TR> | |
417 | <TR> | |
418 | <TD>slackware</TD> | |
419 | <TD>Slackware install</TD> | |
420 | </TR> | |
421 | <TR> | |
422 | <TD>swinstall</TD> | |
423 | <TD>HP-UX swinstall</TD> | |
424 | </TR> | |
425 | <TR> | |
426 | <TD>tardist</TD> | |
427 | <TD>IRIX inst/tardist</TD> | |
428 | </TR> | |
429 | </TABLE></DIV> | |
430 | ||
431 | <P>Finally, the <VAR>tools/testrpm</VAR> and | |
432 | <VAR>tools/testosx</VAR> scripts can be used to create binary | |
433 | packages from the current working copy for testing on Linux and | |
bc44d920 | 434 | Mac OS X, respectively:</P> |
4744bd90 | 435 | |
436 | <PRE CLASS="command"> | |
437 | tools/testrpm | |
438 | sudo rpm -U /usr/src/redhat/RPMS/i386/cups*.rpm | |
439 | ||
440 | sudo tools/testosx | |
441 | open cups.pkg | |
442 | </PRE> | |
443 | ||
444 | ||
445 | <H3><A NAME="TESTING">Testing</A></H3> | |
446 | ||
447 | <P>Software testing is conducted according to the <A | |
448 | HREF="spec-stp.html">CUPS Software Test Plan</A>. This testing is | |
449 | automated via the top-level makefile <VAR>test</VAR> target:</P> | |
450 | ||
451 | <PRE CLASS="command"> | |
452 | make test | |
453 | </PRE> | |
454 | ||
455 | <P>The test environment allows for both short-term automated | |
456 | testing and long-term testing and development without the | |
457 | automated test script.</P> | |
458 | ||
459 | ||
460 | <H2 CLASS="title"><A NAME="STR">Trouble Report Processing</A></H2> | |
461 | ||
462 | <P>A Software Trouble Report ("STR") must be submitted every time | |
463 | a user or vendor experiences a problem with the CUPS software. | |
464 | Trouble reports are maintained on the <A | |
465 | HREF="http://www.cups.org/str.php" TARGET="_blank">Bugs & | |
466 | Features</A> page with one of the following states:</P> | |
467 | ||
468 | <OL> | |
469 | ||
470 | <LI>STR is closed with complete resolution</LI> | |
471 | ||
472 | <LI>STR is closed without resolution</LI> | |
473 | ||
474 | <LI>STR is active, waiting on information from submitter</LI> | |
475 | ||
476 | <LI>STR is pending with additional information from submitter</LI> | |
477 | ||
478 | <LI>STR is newly submitted</LI> | |
479 | ||
480 | </OL> | |
481 | ||
482 | <P>Trouble reports are processed using the following steps.</P> | |
483 | ||
484 | <OL> | |
485 | ||
486 | <LI>Classification | |
487 | ||
488 | <P>When a trouble report is received it must be classified at one | |
489 | of the following priority levels:</P> | |
490 | ||
491 | <OL> | |
492 | ||
493 | <LI>Request for enhancement, e.g. asking for a | |
494 | feature | |
495 | ||
496 | <LI>Low, e.g. a documentation error or undocumented | |
497 | side-effect | |
498 | ||
499 | <LI>Moderate, e.g. unable to print a file or unable to | |
500 | compile the software | |
501 | ||
502 | <LI>High, e.g. unable to print to a printer or key | |
503 | functionality not working | |
504 | ||
505 | <LI>Critical, e.g. unable to print at all | |
506 | ||
507 | </OL> | |
508 | ||
509 | <P>Level 4 and 5 trouble reports must be resolved in the next | |
510 | software release. Level 2 and 3 trouble reports are scheduled for | |
511 | resolution in a specific release at the discretion of the release | |
512 | coordinator. Level 1 trouble reports are scheduled for resolution | |
513 | in a future feature release.</P> | |
514 | ||
515 | <P>The scope of the problem is also determined as:</P> | |
516 | ||
517 | <OL> | |
518 | ||
519 | <LI>Specific to a machine or printer | |
520 | ||
521 | <LI>Specific to an operating system | |
522 | ||
523 | <LI>Applies to all machines, printers, and operating systems | |
524 | ||
525 | </OL> | |
526 | ||
527 | <LI>Identification | |
528 | ||
529 | <P>Once the level and scope of the trouble report is determined | |
530 | the software sub-system(s) involved with the problem are | |
531 | determined. This may involve additional communication with the | |
532 | user or vendor to isolate the problem to a specific cause.</P> | |
533 | ||
534 | <P>When the sub-system(s) involved have been identified, an | |
535 | engineer will then determine the change(s) needed and estimate | |
536 | the time required for the change(s).</P> | |
537 | ||
538 | <LI>Correction | |
539 | ||
540 | <P>Corrections are scheduled based upon the severity and | |
541 | complexity of the problem. Once all changes have been made, | |
542 | documented, and tested successfully a new software release | |
543 | snapshot is generated. Additional tests are added as necessary | |
544 | for proper testing of the changes.</P> | |
545 | ||
546 | <LI>Notification | |
547 | ||
548 | <P>The user or vendor is notified when the fix is available or if | |
549 | the problem was caused by user error.</P> | |
550 | ||
551 | </OL> | |
552 | ||
553 | ||
554 | <H2 CLASS="title"><A NAME="RELEASES">Release Management</A></H2> | |
555 | ||
556 | <P>When testing has been completed successfully, a new source | |
557 | package is created using the <VAR>tools/makesrcdist</VAR> script. | |
558 | Three types of releases, beta, candidate, and production, are | |
559 | created and released to the public using the basic schedule in | |
560 | Table 4. At least one beta and one release candidate must be | |
561 | created prior to a production release, and there must be at least | |
562 | two weeks between the last beta and first candidate and last | |
563 | candidate and first production release.</P> | |
564 | ||
565 | <DIV CLASS="table"><TABLE SUMMARY="CUPS Basic Release Schedule"> | |
566 | <CAPTION>Table: CUPS Basic Release Schedule</CAPTION> | |
567 | <TR> | |
568 | <TH>Week</TH> | |
569 | <TH>Version</TH> | |
570 | <TH>Description</TH> | |
571 | </TR> | |
572 | <TR> | |
573 | <TD>T-6 weeks</TD> | |
574 | <TD>1.2b1</TD> | |
575 | <TD>First beta release</TD> | |
576 | </TR> | |
577 | <TR> | |
578 | <TD>T-5 weeks</TD> | |
579 | <TD>1.2b2</TD> | |
580 | <TD>Second beta release</TD> | |
581 | </TR> | |
582 | <TR> | |
583 | <TD>T-3 weeks</TD> | |
584 | <TD>1.2rc1</TD> | |
585 | <TD>First release candidate</TD> | |
586 | </TR> | |
587 | <TR> | |
588 | <TD>T-2 weeks</TD> | |
589 | <TD>1.2rc2</TD> | |
590 | <TD>Second release candidate</TD> | |
591 | </TR> | |
592 | <TR> | |
593 | <TD>T-0 weeks</TD> | |
594 | <TD>1.2.0</TD> | |
595 | <TD>Production (feature) release</TD> | |
596 | </TR> | |
597 | </TABLE></DIV> | |
598 | ||
599 | ||
600 | <H2 CLASS="title"><A NAME="CODING">Coding Guidelines</A></H2> | |
601 | ||
602 | <P>These coding guidelines provide detailed information on source | |
603 | file formatting and documentation content and must be applied to | |
604 | all C and C++ source files provided with CUPS. Source code for | |
605 | other languages should conform to these guidelines as allowed by | |
606 | the language.</P> | |
607 | ||
608 | <H3>Source Files</H3> | |
609 | ||
610 | <P>All source files names shall be 16 characters or less in | |
611 | length to ensure compatibility with older UNIX filesystems. | |
612 | Source files containing functions shall have an extension of ".c" | |
613 | for ANSI C and ".cxx" for C++ source files. All other "include" | |
614 | files shall have an extension of ".h".</P> | |
615 | ||
616 | <P>The top of each source file shall contain a header giving the | |
617 | name of the file, the purpose or nature of the source file, the | |
618 | copyright and licensing notice, and the functions contained in | |
619 | the file. The file name and revision information is provided by | |
620 | the Subversion "$Id$" tag:</P> | |
621 | ||
622 | <PRE CLASS="command"> | |
623 | /* | |
624 | * "$Id$" | |
625 | * | |
626 | * Description of file contents. | |
627 | * | |
bc44d920 | 628 | * Copyright 2007 by Apple Inc. |
4744bd90 | 629 | * |
bc44d920 | 630 | * These coded instructions, statements, and computer programs are the |
631 | * property of Apple Inc. and are protected by Federal copyright | |
632 | * law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
633 | * which should have been included with this file. If this file is | |
634 | * file is missing or damaged, see the license at "http://www.cups.org/". | |
4744bd90 | 635 | * |
636 | * Contents: | |
637 | * | |
638 | * function1() - Description 1. | |
639 | * function2() - Description 2. | |
640 | * function3() - Description 3. | |
641 | */ | |
642 | </PRE> | |
643 | ||
644 | <P>For source files that are subject to the Apple OS-Developed | |
645 | Software exception, the following additional comment should | |
646 | appear after the contact information:</P> | |
647 | ||
648 | <PRE CLASS="command"> | |
649 | * This file is subject to the Apple OS-Developed Software exception. | |
650 | </PRE> | |
651 | ||
652 | <P>The bottom of each source file shall contain a trailer giving | |
653 | the name of the file using the Subversion "$Id$" tag. The | |
654 | primary purpose of this is to mark the end of a source file; if | |
655 | the trailer is missing it is possible that code has been lost | |
656 | near the end of the file:</P> | |
657 | ||
658 | <PRE CLASS="command"> | |
659 | /* | |
660 | * End of "$Id$". | |
661 | */ | |
662 | </PRE> | |
663 | ||
664 | <H3>Functions</H3> | |
665 | ||
666 | <P>Functions with a global scope shall have a lowercase prefix | |
667 | followed by capitalized words ("cupsDoThis", "cupsDoThat", | |
668 | "cupsDoSomethingElse", etc.) Private global functions shall begin | |
669 | with a leading underscore ("_cupsDoThis", "_cupsDoThat", | |
670 | etc.)</P> | |
671 | ||
672 | <P>Functions with a local scope shall be declared "static" and be | |
673 | lowercase with underscores between words ("do_this", "do_that", | |
674 | "do_something_else", etc.)</P> | |
675 | ||
676 | <P>Each function shall begin with a comment header describing | |
677 | what the function does, the possible input limits (if any), and | |
678 | the possible output values (if any), and any special information | |
679 | needed:</P> | |
680 | ||
681 | <PRE CLASS="command"> | |
682 | /* | |
683 | * 'do_this()' - Compute y = this(x). | |
684 | * | |
685 | * Notes: none. | |
686 | */ | |
687 | ||
688 | static float /* O - Inverse power value, 0.0 <= y <= 1.1 */ | |
689 | do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */ | |
690 | { | |
691 | ... | |
692 | return (y); | |
693 | } | |
694 | </PRE> | |
695 | ||
696 | <P>Return/output values are indicated using an "O" prefix, input | |
697 | values are indicated using the "I" prefix, and values that are | |
698 | both input and output use the "IO" prefix for the corresponding | |
699 | in-line comment.</P> | |
700 | ||
701 | <P>The Mini-XML documentation generator also understands the following | |
702 | special text in the function description comment:</P> | |
703 | ||
704 | <UL> | |
705 | ||
706 | <LI><CODE>@since CUPS <I>version</I>@</CODE> - Marks the | |
707 | function as new in the specified version of CUPS.</LI> | |
708 | ||
709 | <LI><CODE>@deprecated@</CODE> - Marks the function as | |
710 | deprecated (not recommended for new development and | |
711 | scheduled for removal)</LI> | |
712 | ||
713 | </UL> | |
714 | ||
715 | <H3>Variables</H3> | |
716 | ||
717 | <P>Variables with a global scope shall be capitalized | |
718 | ("ThisVariable", "ThatVariable", "ThisStateVariable", etc.) The | |
719 | only exception to this rule shall be the CUPS interface library | |
720 | global variables which must begin with the prefix "cups" | |
721 | ("cupsThisVariable", "cupsThatVariable", etc.) Global variables | |
722 | shall be replaced by function arguments whenever possible.</P> | |
723 | ||
724 | <P>Variables with a local scope shall be lowercase with | |
725 | underscores between words ("this_variable", "that_variable", | |
726 | etc.) Any local variables shared by functions within a source | |
727 | file shall be declared "static".</P> | |
728 | ||
729 | <P>Each variable shall be declared on a separate line and shall | |
730 | be immediately followed by a comment block describing the | |
731 | variable:</P> | |
732 | ||
733 | <PRE CLASS="command"> | |
734 | int this_variable; /* The current state of this */ | |
735 | int that_variable; /* The current state of that */ | |
736 | </PRE> | |
737 | ||
738 | <H3>Types</H3> | |
739 | ||
740 | <P>All type names shall be lowercase with underscores between | |
741 | words and "_t" appended to the end of the name | |
742 | ("cups_this_type_t", "cups_that_type_t", etc.) Type names must | |
743 | start with a prefix, typically "cups" or the name of the program, | |
744 | to avoid conflicts with system types. Private type names must | |
745 | start with an underscore ("_cups_this_t", "_cups_that_t", | |
746 | etc.)</P> | |
747 | ||
748 | <P>Each type shall have a comment block immediately after the | |
749 | typedef:</P> | |
750 | ||
751 | <PRE CLASS="command"> | |
752 | typedef int cups_this_type_t; /* This type is for CUPS foobar options. */ | |
753 | </PRE> | |
754 | ||
755 | <H3>Structures</H3> | |
756 | ||
757 | <P>All structure names shall be lowercase with underscores | |
758 | between words and "_s" appended to the end of the name | |
759 | ("cups_this_s", "cups_that_s", etc.) Structure names must start | |
760 | with a prefix, typically "cups" or the name of the program, to | |
761 | avoid conflicts with system types. Private structure names must | |
762 | start with an underscore ("_cups_this_s", "_cups_that_s", | |
763 | etc.)</P> | |
764 | ||
765 | <P>Each structure shall have a comment block immediately after | |
766 | the struct and each member shall be documented in accordance with | |
767 | the variable naming policy above:</P> | |
768 | ||
769 | <PRE CLASS="command"> | |
770 | struct cups_this_struct_s /* This structure is for CUPS foobar options. */ | |
771 | { | |
772 | int this_member; /* Current state for this */ | |
773 | int that_member; /* Current state for that */ | |
774 | }; | |
775 | </PRE> | |
776 | ||
777 | <H3>Constants</H3> | |
778 | ||
779 | <P>All constant names shall be uppercase with underscored between | |
780 | words ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.) | |
781 | Constants must begin with an uppercase prefix, typically "CUPS" | |
782 | or the program name.</P> | |
783 | ||
784 | <P>Typed enumerations shall be used whenever possible to allow | |
785 | for type checking by the compiler.</P> | |
786 | ||
787 | <P>Comment blocks shall immediately follow each constant:</P> | |
788 | ||
789 | <PRE CLASS="command"> | |
790 | enum | |
791 | { | |
792 | CUPS_THIS_TRAY, /* This tray */ | |
793 | CUPS_THAT_TRAY /* That tray */ | |
794 | }; | |
795 | </PRE> | |
796 | ||
797 | <H3>Code</H3> | |
798 | ||
799 | <P>All source code shall utilize block comments within functions | |
800 | to describe the operations being performed by a group of | |
801 | statements; avoid putting a comment per line unless absolutely | |
802 | necessary, and then consider refactoring the code so that it is | |
803 | not necessary:</P> | |
804 | ||
805 | <PRE CLASS="command"> | |
806 | /* | |
807 | * Clear the state array before we begin... | |
808 | */ | |
809 | ||
810 | for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) | |
811 | array[i] = STATE_IDLE; | |
812 | ||
813 | /* | |
814 | * Wait for state changes... | |
815 | */ | |
816 | ||
817 | do | |
818 | { | |
819 | for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) | |
820 | if (array[i] != STATE_IDLE) | |
821 | break; | |
822 | ||
823 | if (i == (sizeof(array) / sizeof(array[0]))) | |
824 | sleep(1); | |
825 | } while (i == (sizeof(array) / sizeof(array[0]))); | |
826 | </PRE> | |
827 | ||
828 | <H3>Indentation</H3> | |
829 | ||
830 | <P>All code blocks enclosed by brackets shall begin with the | |
831 | opening brace on a new line. The code then follows starting on a | |
832 | new line after the brace and is indented 2 spaces. The closing | |
833 | brace is then placed on a new line following the code at the | |
834 | original indentation:</P> | |
835 | ||
836 | <PRE CLASS="command"> | |
837 | { | |
838 | int i; /* Looping var */ | |
839 | ||
840 | /* | |
841 | * Process foobar values from 0 to 999... | |
842 | */ | |
843 | ||
844 | for (i = 0; i < 1000; i ++) | |
845 | { | |
846 | do_this(i); | |
847 | do_that(i); | |
848 | } | |
849 | } | |
850 | </PRE> | |
851 | ||
852 | <P>Single-line statements following "do", "else", "for", "if", | |
853 | and "while" shall be indented 2 spaces as well. Blocks of code | |
854 | in a "switch" block shall be indented 4 spaces after each "case" | |
855 | and "default" case:</P> | |
856 | ||
857 | <PRE CLASS="command"> | |
858 | switch (array[i]) | |
859 | { | |
860 | case STATE_IDLE : | |
861 | do_this(i); | |
862 | do_that(i); | |
863 | break; | |
864 | default : | |
865 | do_nothing(i); | |
866 | break; | |
867 | } | |
868 | </PRE> | |
869 | ||
870 | <H3>Spacing</H3> | |
871 | ||
872 | <P>A space shall follow each reserved word ("if", "while", etc.) | |
873 | Spaces shall not be inserted between a function name and the | |
874 | arguments in parenthesis.</P> | |
875 | ||
876 | <H3>Return Values</H3> | |
877 | ||
878 | <P>Parenthesis shall surround values returned from a function | |
879 | using "return":</P> | |
880 | ||
881 | <PRE CLASS="command"> | |
882 | return (CUPS_STATE_IDLE); | |
883 | </PRE> | |
884 | ||
885 | <H3>Loops</H3> | |
886 | ||
887 | <P>Whenever convenient loops should count downward to zero to | |
888 | improve program performance:</P> | |
889 | ||
890 | <PRE CLASS="command"> | |
891 | for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --) | |
892 | array[i] = CUPS_STATE_IDLE; | |
893 | </PRE> | |
894 | ||
895 | <H2 CLASS="title"><A NAME="MAKEFILES">Makefile Guidelines</A></H2> | |
896 | ||
897 | <P>The following is a guide to the makefile-based build system | |
898 | used by CUPS. These standards have been developed over the years | |
899 | to allow CUPS to be built on as many systems and environments as | |
900 | possible.</P> | |
901 | ||
902 | <H3>General Organization</H3> | |
903 | ||
904 | <P>The CUPS source code is organized functionally into a | |
905 | top-level makefile, include file, and subdirectories each with | |
906 | their own makefile and dependencies files. The ".in" files are | |
907 | template files for the <CODE>autoconf</CODE> software and are | |
908 | used to generate a static version of the corresponding file.</P> | |
909 | ||
910 | <H3>Makefile Documentation</H3> | |
911 | ||
912 | <P>Each make file must start with the standard CUPS header | |
913 | containing the Subversion "$Id$" keyword, description of the | |
914 | file, and CUPS copyright and license notice:</P> | |
915 | ||
916 | <PRE CLASS="command"> | |
917 | # | |
918 | # "$Id$" | |
919 | # | |
920 | # Makefile for ... | |
921 | # | |
bc44d920 | 922 | # Copyright 2007 by Apple Inc. |
4744bd90 | 923 | # |
bc44d920 | 924 | # These coded instructions, statements, and computer programs are the |
925 | # property of Apple Inc. and are protected by Federal copyright | |
926 | # law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
927 | # which should have been included with this file. If this file is | |
928 | # file is missing or damaged, see the license at "http://www.cups.org/". | |
4744bd90 | 929 | # |
930 | </PRE> | |
931 | ||
932 | <P>The end of each makefile must have a comment saying:</P> | |
933 | ||
934 | <PRE CLASS="command"> | |
935 | # | |
936 | # End of "$Id$". | |
937 | # | |
938 | </PRE> | |
939 | ||
940 | <P>The purpose of the trailer is to indicate the end of the | |
941 | makefile so that truncations are immediately obvious.</P> | |
942 | ||
943 | <H3>Portable Makefile Construction</H3> | |
944 | ||
945 | <P>CUPS uses a common subset of make program syntax to ensure | |
946 | that the software can be compiled "out of the box" on as many | |
947 | systems as possible. The following is a list of assumptions we | |
948 | follow when constructing makefiles:</P> | |
949 | ||
950 | <UL> | |
951 | ||
952 | <LI><b>Targets</b>; we assume that the make program | |
953 | supports the notion of simple targets of the form | |
954 | "name:" that perform tab-indented commands that follow | |
955 | the target, e.g.: | |
956 | <PRE CLASS="command"> | |
957 | target: | |
958 | → target commands</PRE></LI> | |
959 | ||
960 | <LI><b>Dependencies</b>; we assume that the make program | |
961 | supports recursive dependencies on targets, e.g.: | |
962 | <PRE CLASS="command"> | |
963 | target: foo bar | |
964 | → target commands | |
965 | ||
966 | foo: bla | |
967 | → foo commands | |
968 | ||
969 | bar: | |
970 | → bar commands | |
971 | ||
972 | bla: | |
973 | → bla commands</PRE></LI> | |
974 | ||
975 | <LI><b>Variable Definition</b>; we assume that the make program | |
976 | supports variable definition on the command-line or in the makefile | |
977 | using the following form: | |
978 | <PRE CLASS="command"> | |
979 | name=value</PRE> | |
980 | ||
981 | <LI><b>Variable Substitution</b>; we assume that the make program | |
982 | supports variable substitution using the following forms: | |
983 | <UL> | |
984 | <LI><CODE>$(name)</CODE>; substitutes the value of "name",</LI> | |
985 | <LI><CODE>($name:.old=.new)</CODE>; substitutes the value of "name" | |
986 | with the filename extensions ".old" changed to ".new",</LI> | |
987 | <LI><CODE>$(MAKEFLAGS)</CODE>; substitutes the | |
988 | command-line options passed to the program | |
989 | without the leading hyphen (-),</LI> | |
990 | <LI><CODE>$$</CODE>; substitutes a single <CODE>$</CODE> character,</LI> | |
991 | <LI><CODE>$<</CODE>; substitutes the current source file or dependency, and</LI> | |
992 | <LI><CODE>$@</CODE>; substitutes the current target name.</LI> | |
993 | </UL></LI> | |
994 | ||
995 | <LI><b>Suffixes</b>; we assume that the make program | |
996 | supports filename suffixes with assumed dependencies, e.g.: | |
997 | <PRE CLASS="command"> | |
998 | .SUFFIXES: .c .o | |
999 | .c.o: | |
1000 | → $(CC) $(CFLAGS) -o $@ -c $<</PRE></LI> | |
1001 | ||
1002 | <LI><b>Include Files</b>; we assume that the make program | |
1003 | supports the <CODE>include</CODE> directive, e.g.: | |
1004 | <PRE CLASS="command"> | |
1005 | include ../Makedefs | |
1006 | include Dependencies</PRE></LI> | |
1007 | ||
1008 | <LI><b>Comments</b>; we assume that comments begin with | |
1009 | a <CODE>#</CODE> character and proceed to the end of the | |
1010 | current line.</LI> | |
1011 | ||
1012 | <LI><b>Line Length</b>; we assume that there is no | |
1013 | practical limit to the length of lines.</LI> | |
1014 | ||
1015 | <LI><b>Continuation of long lines</b>; we assume that | |
1016 | the <CODE>\</CODE> character may be placed at the end of a | |
1017 | line to concatenate two or more lines in a | |
1018 | makefile to form a single long line.</LI> | |
1019 | ||
1020 | <LI><b>Shell</b>; we assume a POSIX-compatible shell is | |
1021 | present on the build system.</LI> | |
1022 | ||
1023 | </UL> | |
1024 | ||
1025 | <H3>Standard Variables</H3> | |
1026 | ||
1027 | <P>The following variables are defined in the "Makedefs" file | |
1028 | generated by the <CODE>autoconf</CODE> software:</P> | |
1029 | ||
1030 | <UL> | |
1031 | ||
1032 | <LI><CODE>AR</CODE>; the library archiver command,</LI> | |
1033 | ||
1034 | <LI><CODE>ARFLAGS</CODE>; options for the library archiver command,</LI> | |
1035 | ||
1036 | <LI><CODE>BUILDROOT</CODE>; optional installation prefix,</LI> | |
1037 | ||
1038 | <LI><CODE>MAN1EXT</CODE>; extension for man pages in section 1,</LI> | |
1039 | ||
1040 | <LI><CODE>MAN3EXT</CODE>; extension for man pages in section 3,</LI> | |
1041 | ||
1042 | <LI><CODE>MAN5EXT</CODE>; extension for man pages in section 5,</LI> | |
1043 | ||
1044 | <LI><CODE>MAN7EXT</CODE>; extension for man pages in section 7,</LI> | |
1045 | ||
1046 | <LI><CODE>MAN8DIR</CODE>; subdirectory for man pages in section 8,</LI> | |
1047 | ||
1048 | <LI><CODE>MAN8EXT</CODE>; extension for man pages in section 8,</LI> | |
1049 | ||
1050 | <LI><CODE>CC</CODE>; the C compiler command,</LI> | |
1051 | ||
1052 | <LI><CODE>CFLAGS</CODE>; options for the C compiler command,</LI> | |
1053 | ||
1054 | <LI><CODE>CXX</CODE>; the C++ compiler command,</LI> | |
1055 | ||
1056 | <LI><CODE>CXXFLAGS</CODE>; options for the C++ compiler command,</LI> | |
1057 | ||
1058 | <LI><CODE>DSOCOMMAND</CODE>; the shared library building command,</LI> | |
1059 | ||
1060 | <LI><CODE>DSOFLAGS</CODE>; options for the shared library building command,</LI> | |
1061 | ||
1062 | <LI><CODE>INSTALL</CODE>; the <CODE>install</CODE> command,</LI> | |
1063 | ||
1064 | <LI><CODE>INSTALL_BIN</CODE>; the program installation command,</LI> | |
1065 | ||
1066 | <LI><CODE>INSTALL_DATA</CODE>; the data file installation command,</LI> | |
1067 | ||
1068 | <LI><CODE>INSTALL_DIR</CODE>; the directory installation command,</LI> | |
1069 | ||
1070 | <LI><CODE>INSTALL_LIB</CODE>; the library installation command,</LI> | |
1071 | ||
1072 | <LI><CODE>INSTALL_MAN</CODE>; the documentation installation command,</LI> | |
1073 | ||
1074 | <LI><CODE>INSTALL_SCRIPT</CODE>; the shell script installation command,</LI> | |
1075 | ||
1076 | <LI><CODE>LDFLAGS</CODE>; options for the linker,</LI> | |
1077 | ||
1078 | <LI><CODE>LIBS</CODE>; libraries for all programs,</LI> | |
1079 | ||
1080 | <LI><CODE>LN</CODE>; the <CODE>ln</CODE> command,</LI> | |
1081 | ||
1082 | <LI><CODE>OPTIM</CODE>; common compiler optimization options,</LI> | |
1083 | ||
1084 | <LI><CODE>RM</CODE>; the <CODE>rm</CODE> command,</LI> | |
1085 | ||
1086 | <LI><CODE>SHELL</CODE>; the <CODE>sh</CODE> (POSIX shell) command,</LI> | |
1087 | ||
1088 | <LI><CODE>STRIP</CODE>; the <CODE>strip</CODE> command,</LI> | |
1089 | ||
1090 | <LI><CODE>bindir</CODE>; the binary installation directory,</LI> | |
1091 | ||
1092 | <LI><CODE>datadir</CODE>; the data file installation directory,</LI> | |
1093 | ||
1094 | <LI><CODE>exec_prefix</CODE>; the installation prefix for executable files,</LI> | |
1095 | ||
1096 | <LI><CODE>libdir</CODE>; the library installation directory,</LI> | |
1097 | ||
1098 | <LI><CODE>mandir</CODE>; the man page installation directory,</LI> | |
1099 | ||
1100 | <LI><CODE>prefix</CODE>; the installation prefix for non-executable files, and</LI> | |
1101 | ||
1102 | <LI><CODE>srcdir</CODE>; the source directory.</LI> | |
1103 | ||
1104 | </UL> | |
1105 | ||
1106 | <H3>Standard Targets</H3> | |
1107 | ||
1108 | <P>The following standard targets must be defined in each | |
1109 | makefile:</P> | |
1110 | ||
1111 | <UL> | |
1112 | ||
1113 | <LI><CODE>all</CODE>; creates all target programs, | |
1114 | libraries, and documentation files,</LI> | |
1115 | ||
1116 | <LI><CODE>clean</CODE>; removes all target programs, | |
1117 | libraries, documentation files, and object files,</LI> | |
1118 | ||
1119 | <LI><CODE>depend</CODE>; generates automatic dependencies | |
1120 | for any C or C++ source files (also see <A | |
1121 | HREF="#DEPEND_TARGET">"Dependencies"</A>),</LI> | |
1122 | ||
1123 | <LI><CODE>distclean</CODE>; removes autoconf-generated files | |
1124 | in addition to those removed by the "clean" target,</LI> | |
1125 | ||
1126 | <LI><CODE>install</CODE>; installs all distribution files in | |
1127 | their corresponding locations (also see <A | |
1128 | HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), </LI> | |
1129 | ||
1130 | <LI><CODE>uninstall</CODE>; removes all distribution files from | |
1131 | their corresponding locations (also see <A | |
1132 | HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), and</LI> | |
1133 | ||
1134 | </UL> | |
1135 | ||
1136 | ||
1137 | <H3>Object Files</H3> | |
1138 | ||
1139 | <P>Object files (the result of compiling a C or C++ source file) | |
1140 | have the extension ".o".</P> | |
1141 | ||
1142 | <H3>Programs</H3> | |
1143 | ||
1144 | <P>Program files are the result of linking object files and | |
1145 | libraries together to form an executable file. A typical | |
1146 | program target looks like:</P> | |
1147 | ||
1148 | <PRE CLASS="command"> | |
1149 | program: $(OBJS) | |
1150 | → echo Linking $@... | |
1151 | → $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) | |
1152 | </PRE> | |
1153 | ||
1154 | <H3>Static Libraries</H3> | |
1155 | ||
1156 | <P>Static libraries have a prefix of "lib" and the extension | |
1157 | ".a". A typical static library target looks like:</P> | |
1158 | ||
1159 | <PRE CLASS="command"> | |
1160 | libname.a: $(OBJECTS) | |
1161 | → echo Creating $@... | |
1162 | → $(RM) $@ | |
1163 | → $(AR) $(ARFLAGS) $@ $(OBJECTS) | |
1164 | → $(RANLIB) $@ | |
1165 | </PRE> | |
1166 | ||
1167 | <H3>Shared Libraries</H3> | |
1168 | ||
1169 | <P>Shared libraries have a prefix of "lib" and the extension | |
1170 | ".dylib", ".sl", ".so", or "_s.a" depending on the operating | |
1171 | system. A typical shared library is composed of several targets | |
1172 | that look like:</P> | |
1173 | ||
1174 | <PRE CLASS="command"> | |
1175 | libname.so: $(OBJECTS) | |
1176 | → echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ... | |
1177 | → $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS) | |
1178 | → $(RM) libname.so libname.so.$(DSOMAJOR) | |
1179 | → $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR) | |
1180 | → $(LN) libname.so.$(DSOVERSION) libname.so | |
1181 | ||
1182 | libname.sl: $(OBJECTS) | |
1183 | → echo $(DSOCOMMAND) libname.sl.$(DSOVERSION) ... | |
1184 | → $(DSOCOMMAND) libname.sl.$(DSOVERSION) $(OBJECTS) | |
1185 | → $(RM) libname.sl libname.sl.$(DSOMAJOR) | |
1186 | → $(LN) libname.sl.$(DSOVERSION) libname.sl.$(DSOMAJOR) | |
1187 | → $(LN) libname.sl.$(DSOVERSION) libname.sl | |
1188 | ||
1189 | libname.dylib: $(OBJECTS) | |
1190 | → echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ... | |
1191 | → $(DSOCOMMAND) libname.$(DSOVERSION).dylib \ | |
1192 | → → -install_name $(libdir)/libname.$(DSOMAJOR).dylib \ | |
1193 | → → -current_version libname.$(DSOVERSION).dylib \ | |
1194 | → → -compatibility_version $(DSOMAJOR).0 \ | |
1195 | → → $(OBJECTS) $(LIBS) | |
1196 | → $(RM) libname.dylib | |
1197 | → $(RM) libname.$(DSOMAJOR).dylib | |
1198 | → $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib | |
1199 | → $(LN) libname.$(DSOVERSION).dylib libname.dylib | |
1200 | ||
1201 | libname_s.a: $(OBJECTS) | |
1202 | → echo $(DSOCOMMAND) libname_s.o ... | |
1203 | → $(DSOCOMMAND) libname_s.o $(OBJECTS) $(LIBS) | |
1204 | → echo $(LIBCOMMAND) libname_s.a libname_s.o | |
1205 | → $(RM) $@ | |
1206 | → $(LIBCOMMAND) libname_s.a libname_s.o | |
1207 | → $(CHMOD) +x libname_s.a | |
1208 | </PRE> | |
1209 | ||
1210 | ||
1211 | <H3>Dependencies</H3> | |
1212 | ||
1213 | <P>Static dependencies are expressed in each makefile following the | |
1214 | target, for example:</P> | |
1215 | ||
1216 | <PRE CLASS="command"> | |
1217 | foo: bar | |
1218 | </PRE> | |
1219 | ||
1220 | <P>Static dependencies shall only be used when it is not | |
1221 | possible to automatically generate them. Automatic dependencies | |
1222 | are stored in a file named "Dependencies" and included at the | |
1223 | end of the makefile. The following "depend" target rule shall be | |
1224 | used to create the automatic dependencies: | |
1225 | ||
1226 | <PRE CLASS="command"> | |
1227 | depend: | |
1228 | → $(MAKEDEPEND) -Y -I.. -f Dependencies $(OBJS:.o=.c) | |
1229 | </PRE> | |
1230 | ||
1231 | <P>We only regenerate the automatic dependencies on a Linux | |
1232 | system and express any non-Linux dependencies statically in the | |
1233 | makefile.</P> | |
1234 | ||
1235 | <H3><A NAME="TARGET_INSTALL">Install/Uninstall Support</A></H3> | |
1236 | ||
1237 | <P>All makefiles must contain install and uninstall rules which | |
1238 | install or remove the corresponding software. These rules must | |
1239 | use the <CODE>$(BUILDROOT)</CODE> variable as a prefix to any | |
1240 | installation directory so that CUPS can be installed in a | |
1241 | temporary location for packaging by programs like | |
1242 | <CODE>rpmbuild</CODE>.</P> | |
1243 | ||
1244 | <P>The <CODE>$(INSTALL_BIN)</CODE>, <CODE>$(INSTALL_DATA)</CODE>, | |
1245 | <CODE>$(INSTALL_DIR)</CODE>, <CODE>$(INSTALL_LIB)</CODE>, | |
1246 | <CODE>$(INSTALL_MAN)</CODE>, and <CODE>$(INSTALL_SCRIPT)</CODE> | |
1247 | variables must be used when installing files so that the proper | |
1248 | ownership and permissions are set on the installed files.</P> | |
1249 | ||
1250 | <P>The <CODE>$(RANLIB)</CODE> command must be run on any static | |
1251 | libraries after installation since the symbol table is | |
1252 | invalidated when the library is copied on some platforms.</P> | |
1253 | ||
1254 | </BODY> | |
1255 | </HTML> |