doc/help/spec-cmp.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <HTML>
   3 <!-- SECTION: Specifications -->
   4 <HEAD>
   5         <TITLE>CUPS Developer Guide</TITLE>
   6         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   7 </HEAD>
   8 <BODY>
   9
  10 <H1 CLASS="title">CUPS Developer Guide</H1>
  11
  12 <P>This developer guide documents the guidelines and processes we use when developing and maintaining CUPS and related software. Our goal is to provide reliable and efficient software and documentation that addresses the needs of our users.</P>
  13
  14 <H2 CLASS="title"><A NAME="OVERVIEW">Overview</A></H2>
  15
  16 <P>CUPS is developed by Apple Inc. and distributed as open source software under a combination of GNU GPL2 and GNU LGPL2 licenses with exceptions to allow linking to OpenSSL (which has a GPL-incompatible license) and for developers on Apple's operating systems to develop CUPS-based software until alternate license terms. Significant contributions to CUPS must be licensed to Apple using the <A HREF="http://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">Apple Contributor Agreement</A>.</P>
  17
  18 <P>Apple releases updates to the CUPS software approximately every three months. Each release has a version number consisting of the major version (currently 1), minor version (currently 6), and patch version (starting at 0) separated by the period, for example "1.6.0". Releases where only the patch version number changes will contain only bug fixes to the previous release, for example "1.6.1" includes bug fixes for the "1.6.0" release. New features require the major or minor version numbers to change, for example "1.6.0" release contains new features compared to the "1.5.3" release. Multiple beta and "candidate" releases generally precede each new feature release, for example "1.5b1", "1.5b2", and "1.5rc1" preceded the "1.5.0" release. Finally, we also post regular Subversion snapshot releases, for example "1.6svn-r10486", which represent a snapshot of the development for the next feature release.</P>
  19
  20 <P>CUPS interfaces, including the C APIs and command-line arguments, environment variables, configuration files, and output format, are stable across patch versions and are generally backwards-compatible with interfaces used in prior major and minor versions. However, program interfaces such as those used by the scheduler to run filter, port monitor, and backend processes for job processing should only be considered stable from the point of view of a filter, port monitor, or backend. Software that simulates the scheduler in order to run those programs outside of CUPS must necessarily be updated when the corresponding interface is changed in a subsequent CUPS release, otherwise undefined behavior can occur.</P>
  21
  22 <P>CUPS C APIs starting with an underscore (_) are considered to be private to CUPS and are not subject to the normal guarantees of stability between CUPS releases and must <em>never</em> be used in non-CUPS source code. Similarly, configuration and state files written by CUPS are considered private if a corresponding man page is not provided with the CUPS release. <em>Never</em> rely on undocumented files or formats when developing software for CUPS. <em>Always</em> use a published C API to access data stored in a file to avoid compatibility problems in the future.</P>
  23
  24
  25 <H2 CLASS="title"><A NAME="COMMUNICATION">Communication</A></H2>
  26
  27 <H3><A NAME="CONTACT">How to Contact the Developers</A></H3>
  28
  29 <P>The <A HREF="http://lists.cups.org/">CUPS Mailing Lists</A> are the primary means of asking questions and informally discussing issues and feature requests with the CUPS developers and other experienced CUPS users and developers. Table 1 shows the available mailing lists and their focus:</P>
  30
  31 <DIV CLASS="table"><TABLE SUMMARY="CUPS Forums">
  32 <CAPTION>Table 1: CUPS Mailing Lists</CAPTION>
  33 <TR>
  34         <TH>List</TH>
  35         <TH>Focus/Purpose</TH>
  36 </TR>
  37 <TR>
  38         <TD>cups</TD>
  39         <TD>General discussion and usage questions for the CUPS software</TD>
  40 </TR>
  41 <TR>
  42         <TD>cups-bugs</TD>
  43         <TD>Discussion of bugs and issues in the CUPS software</TD>
  44 </TR>
  45 <TR>
  46         <TD>cups-commit</TD>
  47         <TD>Report of all commits to the Subversion repository (read-only)</TD>
  48 </TR>
  49 <TR>
  50         <TD>cups-dev</TD>
  51         <TD>Development questions and discussion of new features in the CUPS software</TD>
  52 </TR>
  53 </TABLE></DIV>
  54
  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 &amp; Features</A>" page provides access to the CUPS <em>Software Trouble Report</em> (STR) database and is the formal way to submit a bug report or feature request to the CUPS developers. Please note, however, that we <em>do not</em> provide answers to usage questions or resolve problems in third-party software on this page - use the <A HREF="#CONTACT">CUPS Mailing Lists</A> for that instead.</P>
  59
  60 <P>Unlike discussions that occur on the CUPS Mailing Lists, formal bug reports and feature requests must be acted on by the CUPS developers. This does not mean that every bug report is resolved or every feature request is implemented, but we do respond and keep track of them all for posterity.</P>
  61
  62 <BLOCKQUOTE>Please use the search feature of the Bugs &amp; Features page before submitting a new bug report or feature request. If you see an existing report that matches your issue, please post a message to that report ("I have this issue as well", "I would also like to see", etc.) rather than submitting a new report. This helps speed the resolution of your issue by reducing the CUPS developers' work load and identifying popular issues.</BLOCKQUOTE>
  63
  64
  65 <H3><A NAME="PATCH">How to Prepare a Patch</A></H3>
  66
  67 <P>When submitting a bug report or feature request, you can include patch files that resolve the bug or implement the feature to speed the inclusion of that bug fix or feature in a new CUPS release. For changes to existing files, we prefer a unified diff against the current Subversion <VAR>trunk</VAR> branch, which can be generated easily using the following Subversion command:</P>
  68
  69 <PRE CLASS="command">
  70 svn diff >filename.patch
  71 </PRE>
  72
  73 <P>If you produce a patch using a released source archive, use one of the following commands instead:</P>
  74
  75 <PRE CLASS="command">
  76 diff -u oldfilename filename >filename.patch
  77
  78 diff -urN olddirectory directory >filename.patch
  79 </PRE>
  80
  81 <P>New files and files with significant changes can be submitted in their entirety, however that may delay the adoption of your changes.</P>
  82
  83 <BLOCKQUOTE><B>Note:</B>
  84
  85 <P>Patches and files must conform to the standards outlined in the "<A HREF="#CODING">Coding Guidelines</A>" and "<A HREF="#MAKEFILES">Makefile Guidelines</A>" sections in this document. In addition, since Apple Inc. provides CUPS under multiple licenses, we require that you <A HREF="http://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">license</A>  significant changes and files to us for inclusion in CUPS. The CUPS developers will inform you if licensing is required.</P></BLOCKQUOTE>
  86
  87
  88 <H2 CLASS="title"><A NAME="PRACTICES">Software Development Practices</A></H2>
  89
  90 <H3><A NAME="VERSIONS">Version Numbering</A></H3>
  91
  92 <P>CUPS uses a three-part version number separated by periods to represent the major, minor, and patch release numbers. Major release numbers indicate large design changes or backwards-incompatible changes to the CUPS API or CUPS Imaging API. Minor release numbers indicate new features and other smaller changes which are backwards-compatible with previous CUPS releases. Patch numbers indicate bug fixes to the previous feature release.</P>
  93
  94 <BLOCKQUOTE><B>Note:</B>
  95
  96 <P>When we talk about compatibility, we are talking about binary compatibility for public APIs and output format compatibility for program interfaces. Changes to configuration file formats or the default behavior of programs are not generally considered incompatible as the upgrade process can normally address such changes gracefully.</P></BLOCKQUOTE>
  97
  98 <P>Production releases use the plain version numbers:</P>
  99
 100 <PRE CLASS="command">
 101 MAJOR.MINOR.PATCH
 102 1.0.0
 103 1.0.1
 104 1.0.2
 105 ...
 106 1.1.0
 107 ...
 108 1.1.23
 109 1.2.0
 110 1.2.1
 111 ...
 112 1.3.0
 113 ...
 114 2.0.0
 115 </PRE>
 116
 117 <P>The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is called a feature release. Feature releases are the only releases that may contain new features. Subsequent production releases in a MAJOR.MINOR series may only contain bug fixes.</P>
 118
 119 <BLOCKQUOTE><B>Note:</B>
 120
 121 <P>We did not hold to this limitation in the CUPS 1.1 series for a variety of reasons. Starting with CUPS 1.2, the "no new features in a patch release" policy has been strictly enforced. The policy has also resulted in fewer new features (and interactions!) to validate/test in the subsequence feature releases.</P></BLOCKQUOTE>
 122
 123 <P>Beta-test releases are identified by appending the letter B to the major and minor version numbers followed by the beta release number:</P>
 124
 125 <PRE CLASS="command">
 126 MAJOR.MINORbNUMBER
 127 1.2b1
 128 </PRE>
 129
 130 <P>Release candidates are identified by appending the letters RC to the major and minor version numbers followed by the release candidate number:</P>
 131
 132 <PRE CLASS="command">
 133 MAJOR.MINORrcNUMBER
 134 1.2rc1
 135 </PRE>
 136
 137 <P>Developer snapshots are identified by appending the letters SVN-R to the major and minor version numbers followed by the revision number:</P>
 138
 139 <PRE CLASS="command">
 140 MAJOR.MINORsvn-rREV
 141 1.2svn-r1234
 142 </PRE>
 143
 144 <P>Beta-test releases, release candidates, and developer snapshots are only created for new minor releases. Once a production release has been made (MAJOR.MINOR.0), subsequent patch releases are issued without preliminary beta or release testing.</P>
 145
 146 <H3>Version Control (Subversion)</H3>
 147
 148 <P>The CUPS source files are managed by the Subversion ("SVN") software, available at:</P>
 149
 150 <PRE CLASS="command">
 151 <A HREF="http://subversion.apache.org/" TARGET="_blank">subversion.apache.org</A>
 152 </PRE>
 153
 154 <P>Source files are "checked in" with each change so that modifications can be tracked, and each checkin must reference any applicable STRs. The following format <em>must</em> be used for commit log messages:</P>
 155
 156 <PRE CLASS="command">
 157 Summary of the change on one line followed by bug number (STR #NNNN)
 158
 159 Detailed list of changes.
 160 </PRE>
 161
 162 <P>Primary development occurs on the <var>trunk</var> branch, with changes merged back to release branches as needed. Table 2 shows the URLs developers use for the various CUPS sub-projects and branches:</P>
 163
 164 <DIV CLASS="table"><TABLE SUMMARY="CUPS Subversion URLs">
 165 <CAPTION>Table 2: CUPS Subversion URLs</CAPTION>
 166 <TR>
 167         <TH>URL</TH>
 168         <TH>Purpose</TH>
 169 </TR>
 170 <TR>
 171         <TD><A HREF="http://svn.cups.org/public/cups/trunk/">https://svn.cups.org/public/cups/trunk/</A></TD>
 172         <TD>Primary CUPS development branch</TD>
 173 </TR>
 174 <TR>
 175         <TD><A HREF="http://svn.cups.org/public/cups/branches/">https://svn.cups.org/public/cups/branches/</A></TD>
 176         <TD>CUPS maintenance branches (merge-only)</TD>
 177 </TR>
 178 <TR>
 179         <TD><A HREF="http://svn.cups.org/public/cups/tags/">https://svn.cups.org/public/cups/tags/</A></TD>
 180         <TD>CUPS release tags (read-only)</TD>
 181 </TR>
 182 </TABLE></DIV>
 183
 184 <P>The branch for a MAJOR.MINOR release are created when the first production release (MAJOR.MINOR.0) is made using the name "branch-MAJOR.MINOR". Release tags are created for every beta, candidate, and production release using the name "release-MAJOR.MINORbNUMBER", "release-MAJOR.MINORrcNUMBER", or "release-MAJOR.MINOR.PATCH", respectively. No release tags are created for developer snapshots.</P>
 185
 186
 187 <H3>Files and Directories</H3>
 188
 189 <P>File and directory names may not exceed 16 characters in length to ensure compatibility with older UNIX filesystems. In addition, to avoid problems with case-insensitive filesystems, you may not use names which differ only by case, for example "ReadMe" and "README" are not allowed in the same directory.</P>
 190
 191 <P>Source files must be documented and formatted as described in "<A HREF="#CODING">Coding Requirements</A>". Makefiles must follow the guidelines in "<A HREF="#MAKEFILE">Makefile Guidelines</A>".</P>
 192
 193
 194 <H3>Build System</H3>
 195
 196 <P>The CUPS build system uses <A HREF="http://www.gnu.org/software/autoconf/">GNU autoconf</A> to tailor the library to the local operating system. Project files for the current release of Visual C++ are also provided for Microsoft Windows<SUP>&reg;</SUP>. To improve portability, makefiles must not make use of features unique to <A HREF="http://www.gnu.org/software/make/">GNU make</A>. See the <A HREF="#MAKEFILES">Makefile Guidelines</A> section for a description of the allowed make features and makefile guidelines.</P>
 197
 198 <P>Additional GNU build programs such as <A HREF="http://www.gnu.org/software/automake">GNU automake</A> and <A HREF="http://www.gnu.org/software/libtool">GNU libtool</A> must not be used. GNU automake produces non-portable makefiles which depend on GNU-specific extensions, and GNU libtool is not portable or reliable enough for CUPS.</P>
 199
 200
 201 <H3><A NAME="PACKAGING">Packaging</A></H3>
 202
 203 <P>Source packages are created using the <VAR>tools/makesrcdist</VAR> script in the Subversion repository. The script optionally uses a version number argument:</P>
 204
 205 <PRE CLASS="command">
 206 tools/makesrcdist
 207 tools/makesrcdist <I>version</I>
 208 </PRE>
 209
 210 <P>When run with no arguments, the script creates a snapshot of the current working copy and names it using the highest revision number in the WC, for example "/tmp/cups-1.3svn-r1234-source.tar.bz2" and "/tmp/cups-1.3svn-r1234-source.tar.gz". When run with two arguments, the script creates a release tag in the repository and exports that tag, creating the files
 211 "/tmp/cups-<I>version</I>-source.tar.bz2" and "/tmp/cups-<I>version</I>-source.tar.gz".</P>
 212
 213 <P>Binary packages are not generally distributed by the CUPS team, however the <VAR>packaging/cups.spec</VAR> and <VAR>packaging/cups.list</VAR> files may be used to create binary packages on Linux, OS X, and UNIX. The <VAR>packaging/cups.spec</VAR> file produces a binary package using the <CODE>rpmbuild(8)</CODE> software:</P>
 214
 215 <PRE CLASS="command">
 216 rpmbuild -ta cups-<I>version</I>-source.tar.gz
 217 </PRE>
 218
 219 <P>The <VAR>cups.list</VAR> file is generated by the <VAR>configure</VAR> script and produces binary packages for many platforms using the <A HREF="http://www.epmhome.org/" TARGET="_blank">EPM</A> software. Table 3 shows the targets that are available for each type of binary package:</P>
 220
 221 <DIV CLASS="table"><TABLE SUMMARY="Binary Package Targets">
 222 <CAPTION>Table 3: Binary Package Targets</CAPTION>
 223 <TR>
 224         <TH>Target</TH>
 225         <TH>Type of Package</TH>
 226 </TR>
 227 <TR>
 228         <TD>aix</TD>
 229         <TD>AIX installp</TD>
 230 </TR>
 231 <TR>
 232         <TD>bsd</TD>
 233         <TD>*BSD pkg_install</TD>
 234 </TR>
 235 <TR>
 236         <TD>deb</TD>
 237         <TD>Debian dpkg</TD>
 238 </TR>
 239 <TR>
 240         <TD>depot</TD>
 241         <TD>HP-UX swinstall</TD>
 242 </TR>
 243 <TR>
 244         <TD>epm</TD>
 245         <TD>Portable tarball with install script</TD>
 246 </TR>
 247 <TR>
 248         <TD>pkg</TD>
 249         <TD>Solaris pkgadd</TD>
 250 </TR>
 251 <TR>
 252         <TD>rpm</TD>
 253         <TD>RPM binary</TD>
 254 </TR>
 255 <TR>
 256         <TD>setld</TD>
 257         <TD>Tru64 UNIX setld</TD>
 258 </TR>
 259 <TR>
 260         <TD>slackware</TD>
 261         <TD>Slackware install</TD>
 262 </TR>
 263 <TR>
 264         <TD>swinstall</TD>
 265         <TD>HP-UX swinstall</TD>
 266 </TR>
 267 </TABLE></DIV>
 268
 269 <P>Finally, the <VAR>tools/testrpm</VAR> and <VAR>tools/testosx</VAR> scripts can be used to create binary packages from the current working copy for testing on Linux and OS X, respectively:</P>
 270
 271 <PRE CLASS="command">
 272 tools/testrpm
 273 sudo rpm -U /usr/src/redhat/RPMS/i386/cups*.rpm
 274
 275 sudo tools/testosx
 276 open cups.pkg
 277 </PRE>
 278
 279
 280 <H3><A NAME="TESTING">Testing</A></H3>
 281
 282 <P>Software testing is conducted according to the <A HREF="spec-stp.html">CUPS Software Test Plan</A>. This testing is automated via the top-level makefile <VAR>test</VAR> target:</P>
 283
 284 <PRE CLASS="command">
 285 make test
 286 </PRE>
 287
 288 <P>The test environment allows for both short-term automated testing and long-term testing and development without the automated test script.</P>
 289
 290
 291 <H2 CLASS="title"><A NAME="STR">Trouble Report Processing</A></H2>
 292
 293 <P>A Software Trouble Report ("STR") must be submitted every time a user or vendor experiences a problem with the CUPS software. Trouble reports are maintained on the <A HREF="http://www.cups.org/str.php" TARGET="_blank">Bugs &amp; Features</A> page with one of the following states:</P>
 294
 295 <OL>
 296
 297         <LI>STR is closed with complete resolution</LI>
 298
 299         <LI>STR is closed without resolution</LI>
 300
 301         <LI>STR is active, waiting on information from submitter</LI>
 302
 303         <LI>STR is pending with additional information from submitter</LI>
 304
 305         <LI>STR is newly submitted</LI>
 306
 307 </OL>
 308
 309 <P>Trouble reports are processed using the following steps.</P>
 310
 311 <H3>1. Classification</H3>
 312
 313 <P>When a trouble report is received it must be classified at one of the following priority levels:</P>
 314
 315 <OL>
 316
 317         <LI>Request for enhancement, e.g. asking for a feature
 318
 319         <LI>Low, e.g. a documentation error or undocumented side-effect
 320
 321         <LI>Moderate, e.g. unable to print a file or unable to compile the software
 322
 323         <LI>High, e.g. unable to print to a printer or key functionality not working
 324
 325         <LI>Critical, e.g. unable to print at all
 326
 327 </OL>
 328
 329 <P>Level 4 and 5 trouble reports must be resolved in the next software release. Level 2 and 3 trouble reports are scheduled for resolution in a specific release at the discretion of the release coordinator. Level 1 trouble reports are scheduled for resolution in a future feature release.</P>
 330
 331 <P>The scope of the problem is also determined as:</P>
 332
 333 <OL>
 334
 335         <LI>Specific to a machine or printer
 336
 337         <LI>Specific to an operating system
 338
 339         <LI>Applies to all machines, printers, and operating systems
 340
 341 </OL>
 342
 343 <H3>2. Identification</H3>
 344
 345 <P>Once the level and scope of the trouble report is determined the software sub-system(s) involved with the problem are determined. This may involve additional communication with the user or vendor to isolate the problem to a specific cause.</P>
 346
 347 <P>When the sub-system(s) involved have been identified, an engineer will then determine the change(s) needed and estimate the time required for the change(s).</P>
 348
 349 <H3>3. Correction</H3>
 350
 351 <P>Corrections are scheduled based upon the severity and complexity of the problem. Once all changes have been made, documented, and tested successfully a new software release snapshot is generated. Additional tests are added as necessary for proper testing of the changes.</P>
 352
 353 <H3>4. Notification</H3>
 354
 355 <P>The user or vendor is notified when the fix is available or if the problem was caused by user error.</P>
 356
 357
 358 <H2 CLASS="title"><A NAME="RELEASES">Release Management</A></H2>
 359
 360 <P>When testing has been completed successfully, a new source package is created using the <VAR>tools/makesrcdist</VAR> script. Three types of releases - beta, candidate, and production - are created and released to the public using the basic schedule in Table 4. At least one beta and one release candidate must be created prior to a production release, and there must be at least two weeks between the last beta and first candidate and last candidate and first production release.</P>
 361
 362 <DIV CLASS="table"><TABLE SUMMARY="CUPS Basic Release Schedule">
 363 <CAPTION>Table: CUPS Basic Release Schedule</CAPTION>
 364 <TR>
 365         <TH>Week</TH>
 366         <TH>Version</TH>
 367         <TH>Description</TH>
 368 </TR>
 369 <TR>
 370         <TD>T-6 weeks</TD>
 371         <TD>1.2b1</TD>
 372         <TD>First beta release</TD>
 373 </TR>
 374 <TR>
 375         <TD>T-5 weeks</TD>
 376         <TD>1.2b2</TD>
 377         <TD>Second beta release</TD>
 378 </TR>
 379 <TR>
 380         <TD>T-3 weeks</TD>
 381         <TD>1.2rc1</TD>
 382         <TD>First release candidate</TD>
 383 </TR>
 384 <TR>
 385         <TD>T-2 weeks</TD>
 386         <TD>1.2rc2</TD>
 387         <TD>Second release candidate</TD>
 388 </TR>
 389 <TR>
 390         <TD>T-0 weeks</TD>
 391         <TD>1.2.0</TD>
 392         <TD>Production (feature) release</TD>
 393 </TR>
 394 </TABLE></DIV>
 395
 396
 397 <H2 CLASS="title"><A NAME="CODING">Coding Guidelines</A></H2>
 398
 399 <P>These coding guidelines provide detailed information on source file formatting and documentation content and must be applied to all C and C++ source files provided with CUPS. Source code for other languages should conform to these guidelines as allowed by the language.</P>
 400
 401
 402 <H3>Source Files</H3>
 403
 404 <P>All source files names must be 16 characters or less in length to ensure compatibility with older UNIX filesystems. Source files containing functions have an extension of ".c" for ANSI C and ".cxx" for C++ source files. All other "include" files have an extension of ".h". Tabs are set to 8 characters.</P>
 405
 406 <BLOCKQUOTE><B>Note:</B>
 407
 408 <P>The ".cxx" extension is used because it is the only common C++ extension between Linux, OS X, UNIX, and Windows.</P></BLOCKQUOTE>
 409
 410 <P>The top of each source file contains a header giving the name of the file, the purpose or nature of the source file, the copyright and licensing notice, and the functions contained in the file.  The file name and revision information is provided by the Subversion "&#36;Id$" tag:</P>
 411
 412 <PRE CLASS="command">
 413 /*
 414  * "&#36;Id$"
 415  *
 416  *   Description of file contents.
 417  *
 418  *   Copyright 2012 by Apple Inc.
 419  *
 420  *   These coded instructions, statements, and computer programs are the
 421  *   property of Apple Inc. and are protected by Federal copyright
 422  *   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 423  *   which should have been included with this file.  If this file is
 424  *   file is missing or damaged, see the license at "http://www.cups.org/".
 425  *
 426  * Contents:
 427  *
 428  *   function1() - Description 1.
 429  *   function2() - Description 2.
 430  *   function3() - Description 3.
 431  */
 432 </PRE>
 433
 434 <P>For source files that are subject to the Apple OS-Developed Software exception, the following additional comment appears after the contact information:</P>
 435
 436 <PRE CLASS="command">
 437  *   This file is subject to the Apple OS-Developed Software exception.
 438 </PRE>
 439
 440 <P>The bottom of each source file contains a trailer giving the name of the file using the Subversion "&#36;Id$" tag. The primary purpose of this is to mark the end of a source file; if the trailer is missing it is possible that code has been lost near the end of the file:</P>
 441
 442 <PRE CLASS="command">
 443 /*
 444  * End of "&#36;Id$".
 445  */
 446 </PRE>
 447
 448
 449 <H3>Comments</H3>
 450
 451 <P>All source code utilizes block comments within functions to describe the operations being performed by a group of statements; avoid putting a comment per line unless absolutely necessary, and then consider refactoring the code so that it is not necessary.  C source files use the block comment format ("/* comment */") since many vendor C compilers still do not support C99/C++ comments ("// comment"):</P>
 452
 453 <PRE CLASS="command">
 454  /*
 455   * Clear the state array before we begin...
 456   */
 457
 458   for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 459     array[i] = CUPS_STATE_IDLE;
 460
 461  /*
 462   * Wait for state changes on another thread...
 463   */
 464
 465   do
 466   {
 467     for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 468       if (array[i] != CUPS_STATE_IDLE)
 469         break;
 470
 471     if (i == (sizeof(array) / sizeof(array[0])))
 472       sleep(1);
 473   } while (i == (sizeof(array) / sizeof(array[0])));
 474 </PRE>
 475
 476 <H3>Indentation</H3>
 477
 478 <P>All code blocks enclosed by brackets begin with the opening brace on a new line. The code then follows starting on a new line after the brace and is indented 2 spaces. The closing brace is then placed on a new line following the code at the original indentation:</P>
 479
 480 <PRE CLASS="command">
 481 {
 482   int i; /* Looping var */
 483
 484
 485  /*
 486   * Process foobar values from 0 to 999...
 487   */
 488
 489   for (i = 0; i &lt; 1000; i ++)
 490   {
 491     do_this(i);
 492     do_that(i);
 493   }
 494 }
 495 </PRE>
 496
 497 <P>Single-line statements following "do", "else", "for", "if", and "while" are indented 2 spaces as well. Blocks of code in a "switch" block are indented 4 spaces after each "case" and "default" case:</P>
 498
 499 <PRE CLASS="command">
 500 switch (array[i])
 501 {
 502   case CUPS_STATE_IDLE :
 503       do_this(i);
 504       do_that(i);
 505       break;
 506   default :
 507       do_nothing(i);
 508       break;
 509 }
 510 </PRE>
 511
 512
 513 <H3>Spacing</H3>
 514
 515 <P>A space follows each reserved word such as "if", "while", etc. Spaces are not inserted between a function name and the arguments in parenthesis.</P>
 516
 517
 518 <H3>Return Values</H3>
 519
 520 <P>Parenthesis surround values returned from a function:</P>
 521
 522 <PRE CLASS="command">
 523 return (CUPS_STATE_IDLE);
 524 </PRE>
 525
 526
 527 <H3>Functions</H3>
 528
 529 <P>Functions with a global scope have a lowercase prefix followed by capitalized words, e.g., "cupsDoThis", "cupsDoThat", "cupsDoSomethingElse", etc. Private global functions begin with a leading underscore, e.g., "_cupsDoThis", "_cupsDoThat", etc.</P>
 530
 531 <P>Functions with a local scope are declared "static" with lowercase names and underscores between words, e.g., "do_this", "do_that", "do_something_else", etc.</P>
 532
 533 <P>Each function begins with a comment header describing what the function does, the possible input limits (if any), and the possible output values (if any), and any special information needed:</P>
 534
 535 <PRE CLASS="command">
 536 /*
 537  * 'do_this()' - Compute y = this(x).
 538  *
 539  * Notes: none.
 540  */
 541
 542 static float                            /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.1 */
 543 do_this(float x)                        /* I - Power value (0.0 &lt;= x &lt;= 1.1) */
 544 {
 545   ...
 546   return (y);
 547 }
 548 </PRE>
 549
 550 <P>Return/output values are indicated using an "O" prefix, input values are indicated using the "I" prefix, and values that are both input and output use the "IO" prefix for the corresponding in-line comment.</P>
 551
 552 <P>The Mini-XML documentation generator also understands the following special text in the function description comment:</P>
 553
 554 <UL>
 555
 556         <LI><CODE>@deprecated@</CODE> - Marks the function as deprecated (not recommended for new development and scheduled for removal)</LI>
 557
 558         <LI><CODE>@since CUPS <I>version</I>@</CODE> - Marks the function as new in the specified version of CUPS.</LI>
 559
 560         <LI><CODE>@private@</CODE> - Marks the function as private (same as starting the function name with an underscore)</LI>
 561
 562 </UL>
 563
 564
 565 <H3>Variables</H3>
 566
 567 <P>Variables with a global scope are capitalized, e.g., "ThisVariable", "ThatVariable", "ThisStateVariable", etc. Globals in CUPS libraries are either part of the per-thread global values managed by the "_cupsGlobals()" function or are suitably protected for concurrent access. Global variables should be replaced by function arguments whenever possible.</P>
 568
 569 <P>Variables with a local scope are lowercase with underscores between words, e.g., "this_variable", "that_variable", etc. Any "local global" variables shared by functions within a source file are declared "static". As for global variables, local static variables are suitably protected for concurrent access.</P>
 570
 571 <P>Each variable is declared on a separate line and is immediately followed by a comment block describing the variable:</P>
 572
 573 <PRE CLASS="command">
 574 int         ThisVariable;    /* The current state of this */
 575 static int  that_variable;   /* The current state of that */
 576 </PRE>
 577
 578
 579 <H3>Types</H3>
 580
 581 <P>All type names are lowercase with underscores between words and "_t" appended to the end of the name, e.g., "cups_this_type_t", "cups_that_type_t", etc. Type names start with a prefix, typically "cups" or the name of the program, to avoid conflicts with system types. Private type names start with an underscore, e.g., "_cups_this_t", "_cups_that_t", etc.</P>
 582
 583 <P>Each type has a comment block immediately after the typedef:</P>
 584
 585 <PRE CLASS="command">
 586 typedef int cups_this_type_t;       /* This type is for CUPS foobar options. */
 587 </PRE>
 588
 589
 590 <H3>Structures</H3>
 591
 592 <P>All structure names are lowercase with underscores between words and "_s" appended to the end of the name, e.g., "cups_this_s", "cups_that_s", etc. Structure names start with a prefix, typically "cups" or the name of the program, to avoid conflicts with system types. Private structure names start with an underscore, e.g., "_cups_this_s", "_cups_that_s", etc.</P>
 593
 594 <P>Each structure has a comment block immediately after the struct and each member is documented similar to the variable naming policy above:</P>
 595
 596 <PRE CLASS="command">
 597 struct cups_this_struct_s     /* This structure is for CUPS foobar options. */
 598 {
 599   int this_member;            /* Current state for this */
 600   int that_member;            /* Current state for that */
 601 };
 602 </PRE>
 603
 604
 605 <H3>Constants</H3>
 606
 607 <P>All constant names are uppercase with underscores between words, e.g., "CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc. Constants begin with an uppercase prefix, typically "CUPS" or the program name. Private constants start with an underscore, e.g., "_CUPS_THIS_CONSTANT", "_CUPS_THAT_CONSTANT", etc.</P>
 608
 609 <P>Typed enumerations should be used whenever possible to allow for type checking by the compiler.</P>
 610
 611 <P>Comment blocks immediately follow each constant:</P>
 612
 613 <PRE CLASS="command">
 614 enum
 615 {
 616   CUPS_THIS_TRAY,                       /* This tray */
 617   CUPS_THAT_TRAY                        /* That tray */
 618 };
 619 </PRE>
 620
 621
 622 <H2 CLASS="title"><A NAME="MAKEFILES">Makefile Guidelines</A></H2>
 623
 624 <P>The following is a guide to the makefile-based build system used by CUPS. These standards have been developed over the years to allow CUPS to be built on as many systems and environments as possible.</P>
 625
 626
 627 <H3>General Organization</H3>
 628
 629 <P>The CUPS source code is organized functionally into a top-level makefile, include file, and subdirectories each with their own makefile and dependencies files. The ".in" files are template files for the <CODE>autoconf</CODE> software and are used to generate a static version of the corresponding file.</P>
 630
 631
 632 <H3>Makefile Documentation</H3>
 633
 634 <P>Each makefile starts with the standard CUPS header containing the Subversion "&#36;Id$" keyword, description of the file, and CUPS copyright and license notice:</P>
 635
 636 <PRE CLASS="command">
 637 #
 638 # "&#36;Id$"
 639 #
 640 #   Makefile for ...
 641 #
 642 #   Copyright 2012 by Apple Inc.
 643 #
 644 #   These coded instructions, statements, and computer programs are the
 645 #   property of Apple Inc. and are protected by Federal copyright
 646 #   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 647 #   which should have been included with this file.  If this file is
 648 #   file is missing or damaged, see the license at "http://www.cups.org/".
 649 #
 650 </PRE>
 651
 652 <P>The end of each makefile has a comment saying:</P>
 653
 654 <PRE CLASS="command">
 655 #
 656 # End of "&#36;Id$".
 657 #
 658 </PRE>
 659
 660 <P>The purpose of the trailer is to indicate the end of the makefile so that truncations are immediately obvious.</P>
 661
 662
 663 <H3>Portable Makefile Construction</H3>
 664
 665 <P>CUPS uses a common subset of make program syntax to ensure that the software can be compiled "out of the box" on as many systems as possible. The following is a list of assumptions we follow when constructing makefiles:</P>
 666
 667 <UL>
 668
 669         <LI><b>Targets</b>; we assume that the make program supports the notion of simple targets of the form "name:" that perform tab-indented commands that follow the target, e.g.:
 670         <PRE CLASS="command">
 671 target:
 672 &rarr; target commands</PRE></LI>
 673
 674         <LI><b>Dependencies</b>; we assume that the make program supports recursive dependencies on targets, e.g.:
 675         <PRE CLASS="command">
 676 target: foo bar
 677 &rarr; target commands
 678
 679 foo: bla
 680 &rarr; foo commands
 681
 682 bar:
 683 &rarr; bar commands
 684
 685 bla:
 686 &rarr; bla commands</PRE></LI>
 687
 688         <LI><b>Variable Definition</b>; we assume that the make program supports variable definition on the command-line or in the makefile using the following form:
 689         <PRE CLASS="command">
 690 name=value</PRE>
 691
 692         <LI><b>Variable Substitution</b>; we assume that the make program supports variable substitution using the following forms:
 693         <UL>
 694                 <LI><CODE>$(name)</CODE>; substitutes the value of "name",</LI>
 695                 <LI><CODE>($name:.old=.new)</CODE>; substitutes the value of "name"     with the filename extension ".old" changed to ".new",</LI>
 696                 <LI><CODE>$(MAKEFLAGS)</CODE>; substitutes the command-line options passed to the program without the leading hyphen (-),</LI>
 697                 <LI><CODE>$$</CODE>; substitutes a single <CODE>$</CODE> character,</LI>
 698                 <LI><CODE>$&lt;</CODE>; substitutes the current source file or dependency, and</LI>
 699                 <LI><CODE>$@</CODE>; substitutes the current target name.</LI>
 700         </UL></LI>
 701
 702         <LI><b>Suffixes</b>; we assume that the make program supports filename suffixes with assumed dependencies, e.g.:
 703         <PRE CLASS="command">
 704 .SUFFIXES: .c .o
 705 .c.o:
 706 &rarr; $(CC) $(CFLAGS) -o $@ -c $&lt;</PRE></LI>
 707
 708         <LI><b>Include Files</b>; we assume that the make program
 709         supports the <CODE>include</CODE> directive, e.g.:
 710         <PRE CLASS="command">
 711 include ../Makedefs
 712 include Dependencies</PRE></LI>
 713
 714         <LI><b>Comments</b>; we assume that comments begin with a <CODE>#</CODE> character and proceed to the end of the current line.</LI>
 715
 716         <LI><b>Line Length</b>; we assume that there is no practical limit to the length of lines.</LI>
 717
 718         <LI><b>Continuation of long lines</b>; we assume that the <CODE>\</CODE> character may be placed at the end of a line to concatenate two or more lines in a makefile to form a single long line.</LI>
 719
 720         <LI><b>Shell</b>; we assume a POSIX-compatible shell is present on the build system.</LI>
 721
 722 </UL>
 723
 724
 725 <H3>Standard Variables</H3>
 726
 727 <P>The following variables are defined in the "Makedefs" file generated by the <CODE>autoconf</CODE> software:</P>
 728
 729 <UL>
 730
 731         <LI><CODE>ALL_CFLAGS</CODE>; the combined C compiler options,</LI>
 732
 733         <LI><CODE>ALL_CXXFLAGS</CODE>; the combined C++ compiler options,</LI>
 734
 735         <LI><CODE>AMANDIR</CODE>; the administrative man page installation directory (section 8/1m depending on the platform),</LI>
 736
 737         <LI><CODE>AR</CODE>; the library archiver command,</LI>
 738
 739         <LI><CODE>ARFLAGS</CODE>; options for the library archiver command,</LI>
 740
 741         <LI><CODE>AWK</CODE>; the local awk command,</LI>
 742
 743         <LI><CODE>BINDIR</CODE>; the binary installation directory,</LI>
 744
 745         <LI><CODE>BUILDROOT</CODE>; optional installation prefix (defaults to DSTROOT),</LI>
 746
 747         <LI><CODE>CC</CODE>; the C compiler command,</LI>
 748
 749         <LI><CODE>CFLAGS</CODE>; options for the C compiler command,</LI>
 750
 751         <LI><CODE>CHMOD</CODE>; the chmod command,</LI>
 752
 753         <LI><CODE>CXX</CODE>; the C++ compiler command,</LI>
 754
 755         <LI><CODE>CXXFLAGS</CODE>; options for the C++ compiler command,</LI>
 756
 757         <LI><CODE>DATADIR</CODE>; the data file installation directory,</LI>
 758
 759         <LI><CODE>DSO</CODE>; the C shared library building command,</LI>
 760
 761         <LI><CODE>DSOXX</CODE>; the C++ shared library building command,</LI>
 762
 763         <LI><CODE>DSOFLAGS</CODE>; options for the shared library building command,</LI>
 764
 765         <LI><CODE>INCLUDEDIR</CODE>; the public header file installation directory,</LI>
 766
 767         <LI><CODE>INSTALL</CODE>; the <CODE>install</CODE> command,</LI>
 768
 769         <LI><CODE>INSTALL_BIN</CODE>; the program installation command,</LI>
 770
 771         <LI><CODE>INSTALL_COMPDATA</CODE>; the compressed data file installation command,</LI>
 772
 773         <LI><CODE>INSTALL_CONFIG</CODE>; the configuration file installation command,</LI>
 774
 775         <LI><CODE>INSTALL_DATA</CODE>; the data file installation command,</LI>
 776
 777         <LI><CODE>INSTALL_DIR</CODE>; the directory installation command,</LI>
 778
 779         <LI><CODE>INSTALL_LIB</CODE>; the library installation command,</LI>
 780
 781         <LI><CODE>INSTALL_MAN</CODE>; the documentation installation command,</LI>
 782
 783         <LI><CODE>INSTALL_SCRIPT</CODE>; the shell script installation command,</LI>
 784
 785         <LI><CODE>LD</CODE>; the linker command,</LI>
 786
 787         <LI><CODE>LDFLAGS</CODE>; options for the linker,</LI>
 788
 789         <LI><CODE>LIBDIR</CODE>; the library installation directory,</LI>
 790
 791         <LI><CODE>LIBS</CODE>; libraries for all programs,</LI>
 792
 793         <LI><CODE>LN</CODE>; the <CODE>ln</CODE> command,</LI>
 794
 795         <LI><CODE>MAN1EXT</CODE>; extension for man pages in section 1,</LI>
 796
 797         <LI><CODE>MAN3EXT</CODE>; extension for man pages in section 3,</LI>
 798
 799         <LI><CODE>MAN5EXT</CODE>; extension for man pages in section 5,</LI>
 800
 801         <LI><CODE>MAN7EXT</CODE>; extension for man pages in section 7,</LI>
 802
 803         <LI><CODE>MAN8DIR</CODE>; subdirectory for man pages in section 8,</LI>
 804
 805         <LI><CODE>MAN8EXT</CODE>; extension for man pages in section 8,</LI>
 806
 807         <LI><CODE>MANDIR</CODE>; the man page installation directory,</LI>
 808
 809         <LI><CODE>OPTIM</CODE>; common compiler optimization options,</LI>
 810
 811         <LI><CODE>PRIVATEINCLUDE</CODE>; the private header file installation directory,</LI>
 812
 813         <LI><CODE>RM</CODE>; the <CODE>rm</CODE> command,</LI>
 814
 815         <LI><CODE>SHELL</CODE>; the <CODE>sh</CODE> (POSIX shell) command,</LI>
 816
 817         <LI><CODE>STRIP</CODE>; the <CODE>strip</CODE> command,</LI>
 818
 819         <LI><CODE>srcdir</CODE>; the source directory.</LI>
 820
 821 </UL>
 822
 823
 824 <H3>Standard Targets</H3>
 825
 826 <P>The following standard targets are defined in each makefile:</P>
 827
 828 <UL>
 829
 830         <LI><CODE>all</CODE>; creates all target programs, libraries, and documentation files,</LI>
 831
 832         <LI><CODE>clean</CODE>; removes all target programs libraries, documentation files, and object files,</LI>
 833
 834         <LI><CODE>depend</CODE>; generates automatic dependencies for any C or C++ source files (also see <A HREF="#DEPEND_TARGET">"Dependencies"</A>),</LI>
 835
 836         <LI><CODE>distclean</CODE>; removes autoconf-generated files in addition to those removed by the "clean" target,</LI>
 837
 838         <LI><CODE>install</CODE>; installs all distribution files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI>
 839
 840         <LI><CODE>install-data</CODE>; installs all data files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI>
 841
 842         <LI><CODE>install-exec</CODE>; installs all executable files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI>
 843
 844         <LI><CODE>install-headers</CODE>; installs all include files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI>
 845
 846         <LI><CODE>install-libs</CODE>; installs all library files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI>
 847
 848         <LI><CODE>uninstall</CODE>; removes all distribution files from their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), and</LI>
 849
 850 </UL>
 851
 852
 853 <H3>Object Files</H3>
 854
 855 <P>Object files (the result of compiling a C or C++ source file) have the extension ".o".</P>
 856
 857
 858 <H3>Programs</H3>
 859
 860 <P>Program files are the result of linking object files and libraries together to form an executable file. A typical program target looks like:</P>
 861
 862 <PRE CLASS="command">
 863 program: $(OBJS)
 864 &rarr; echo Linking $@...
 865 &rarr; $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
 866 </PRE>
 867
 868
 869 <H3>Static Libraries</H3>
 870
 871 <P>Static libraries have a prefix of "lib" and the extension ".a". A typical static library target looks like:</P>
 872
 873 <PRE CLASS="command">
 874 libname.a: $(OBJECTS)
 875 &rarr; echo Creating $@...
 876 &rarr; $(RM) $@
 877 &rarr; $(AR) $(ARFLAGS) $@ $(OBJECTS)
 878 &rarr; $(RANLIB) $@
 879 </PRE>
 880
 881
 882 <H3>Shared Libraries</H3>
 883
 884 <P>Shared libraries have a prefix of "lib" and the extension ".dylib", ".sl", ".so", or "_s.a" depending on the operating system. A typical shared library is composed of several targets that look like:</P>
 885
 886 <PRE CLASS="command">
 887 libname.so: $(OBJECTS)
 888 &rarr; echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
 889 &rarr; $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
 890 &rarr; $(RM) libname.so libname.so.$(DSOMAJOR)
 891 &rarr; $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
 892 &rarr; $(LN) libname.so.$(DSOVERSION) libname.so
 893
 894 libname.sl: $(OBJECTS)
 895 &rarr; echo $(DSOCOMMAND) libname.sl.$(DSOVERSION) ...
 896 &rarr; $(DSOCOMMAND) libname.sl.$(DSOVERSION) $(OBJECTS)
 897 &rarr; $(RM) libname.sl libname.sl.$(DSOMAJOR)
 898 &rarr; $(LN) libname.sl.$(DSOVERSION) libname.sl.$(DSOMAJOR)
 899 &rarr; $(LN) libname.sl.$(DSOVERSION) libname.sl
 900
 901 libname.dylib: $(OBJECTS)
 902 &rarr; echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
 903 &rarr; $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
 904 &rarr; &rarr; -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
 905 &rarr; &rarr; -current_version libname.$(DSOVERSION).dylib \
 906 &rarr; &rarr; -compatibility_version $(DSOMAJOR).0 \
 907 &rarr; &rarr; $(OBJECTS) $(LIBS)
 908 &rarr; $(RM) libname.dylib
 909 &rarr; $(RM) libname.$(DSOMAJOR).dylib
 910 &rarr; $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
 911 &rarr; $(LN) libname.$(DSOVERSION).dylib libname.dylib
 912
 913 libname_s.a: $(OBJECTS)
 914 &rarr; echo $(DSOCOMMAND) libname_s.o ...
 915 &rarr; $(DSOCOMMAND) libname_s.o $(OBJECTS) $(LIBS)
 916 &rarr; echo $(LIBCOMMAND) libname_s.a libname_s.o
 917 &rarr; $(RM) $@
 918 &rarr; $(LIBCOMMAND) libname_s.a libname_s.o
 919 &rarr; $(CHMOD) +x libname_s.a
 920 </PRE>
 921
 922
 923 <H3>Dependencies</H3>
 924
 925 <P>Static dependencies are expressed in each makefile following the target, for example:</P>
 926
 927 <PRE CLASS="command">
 928 foo: bar
 929 </PRE>
 930
 931 <P>Static dependencies are only used when it is not possible to automatically generate them. Automatic dependencies are stored in a file named "Dependencies" and included at the end of the makefile. The following "depend" target rule is used to create the automatic dependencies:
 932
 933 <PRE CLASS="command">
 934 depend:
 935 &rarr; $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies
 936 </PRE>
 937
 938 <P>We regenerate the automatic dependencies on an OS X system and express any non-OS X dependencies statically in the makefile.</P>
 939
 940
 941 <H3><A NAME="TARGET_INSTALL">Install/Uninstall Support</A></H3>
 942
 943 <P>All makefiles contains install and uninstall rules which install or remove the corresponding software. These rules must use the <CODE>$(BUILDROOT)</CODE> variable as a prefix to any installation directory so that CUPS can be installed in a temporary location for packaging by programs like <CODE>rpmbuild</CODE>.</P>
 944
 945 <P>The <CODE>$(INSTALL_BIN)</CODE>, <CODE>$(INSTALL_COMPDATA)</CODE>, <CODE>$(INSTALL_CONFIG)</CODE>, <CODE>$(INSTALL_DATA)</CODE>, <CODE>$(INSTALL_DIR)</CODE>, <CODE>$(INSTALL_LIB)</CODE>, <CODE>$(INSTALL_MAN)</CODE>, and <CODE>$(INSTALL_SCRIPT)</CODE> variables must be used when installing files so that the proper ownership and permissions are set on the installed files.</P>
 946
 947 <P>The <CODE>$(RANLIB)</CODE> command must be run on any static libraries after installation since the symbol table is invalidated when the library is copied on some platforms.</P>
 948
 949 </BODY>
 950 </HTML>