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