doc/help/spec-cmp.html

   1 <HTML>
   2 <!-- SECTION: Specifications -->
   3 <HEAD>
   4         <TITLE>CUPS Developer Guide</TITLE>
   5 </HEAD>
   6 <BODY>
   7
   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>
  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
 107 outlined in the "<A HREF="#CODING">Coding Guidelines</A>" and "<A
 108 HREF="#MAKEFILES">Makefile Guidelines</A>" sections in this
 109 document. In addition, since Easy Software Products provides CUPS
 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
 318 Windows<suP>&reg;</suP>. To improve portability, makefiles must
 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
 347 "/tmp/cups-1.2svn-r1234-source.tar.bz2" and
 348 "/tmp/cups-1.2svn-r1234-source.tar.gz". When run with two
 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
 357 packages on Linux, MacOS X, and UNIX. The
 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>
 403         <TD>MacOS X Install</TD>
 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
 434 MacOS X, respectively:</P>
 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 &amp;
 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 "&#36;Id$" tag:</P>
 621
 622 <PRE CLASS="command">
 623 /*
 624  * "&#36;Id$"
 625  *
 626  *   Description of file contents.
 627  *
 628  *   Copyright yyyy-YYYY by Easy Software Products, all rights
 629  *   reserved.
 630  *
 631  *   These coded instructions, statements, and computer programs are
 632  *   the property of Easy Software Products and are protected by
 633  *   Federal copyright law.  Distribution and use rights are outlined
 634  *   in the file "LICENSE.txt" which should have been included with
 635  *   this file.  If this file is missing or damaged please contact
 636  *   Easy Software Products at:
 637  *
 638  *       Attn: CUPS Licensing Information
 639  *       Easy Software Products
 640  *       44141 Airport View Drive, Suite 204
 641  *       Hollywood, Maryland 20636 USA
 642  *
 643  *       Voice: (301) 373-9600
 644  *       EMail: cups-info@cups.org
 645  *         WWW: http://www.cups.org/
 646  *
 647  * Contents:
 648  *
 649  *   function1() - Description 1.
 650  *   function2() - Description 2.
 651  *   function3() - Description 3.
 652  */
 653 </PRE>
 654
 655 <P>For source files that are subject to the Apple OS-Developed
 656 Software exception, the following additional comment should
 657 appear after the contact information:</P>
 658
 659 <PRE CLASS="command">
 660  *   This file is subject to the Apple OS-Developed Software exception.
 661 </PRE>
 662
 663 <P>The bottom of each source file shall contain a trailer giving
 664 the name of the file using the Subversion "&#36;Id$" tag. The
 665 primary purpose of this is to mark the end of a source file; if
 666 the trailer is missing it is possible that code has been lost
 667 near the end of the file:</P>
 668
 669 <PRE CLASS="command">
 670 /*
 671  * End of "&#36;Id$".
 672  */
 673 </PRE>
 674
 675 <H3>Functions</H3>
 676
 677 <P>Functions with a global scope shall have a lowercase prefix
 678 followed by capitalized words ("cupsDoThis", "cupsDoThat",
 679 "cupsDoSomethingElse", etc.) Private global functions shall begin
 680 with a leading underscore ("_cupsDoThis", "_cupsDoThat",
 681 etc.)</P>
 682
 683 <P>Functions with a local scope shall be declared "static" and be
 684 lowercase with underscores between words ("do_this", "do_that",
 685 "do_something_else", etc.)</P>
 686
 687 <P>Each function shall begin with a comment header describing
 688 what the function does, the possible input limits (if any), and
 689 the possible output values (if any), and any special information
 690 needed:</P>
 691
 692 <PRE CLASS="command">
 693 /*
 694  * 'do_this()' - Compute y = this(x).
 695  *
 696  * Notes: none.
 697  */
 698
 699 static float                            /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.1 */
 700 do_this(float x)                        /* I - Power value (0.0 &lt;= x &lt;= 1.1) */
 701 {
 702   ...
 703   return (y);
 704 }
 705 </PRE>
 706
 707 <P>Return/output values are indicated using an "O" prefix, input
 708 values are indicated using the "I" prefix, and values that are
 709 both input and output use the "IO" prefix for the corresponding
 710 in-line comment.</P>
 711
 712 <P>The Mini-XML documentation generator also understands the following
 713 special text in the function description comment:</P>
 714
 715 <UL>
 716
 717         <LI><CODE>@since CUPS <I>version</I>@</CODE> - Marks the
 718         function as new in the specified version of CUPS.</LI>
 719
 720         <LI><CODE>@deprecated@</CODE> - Marks the function as
 721         deprecated (not recommended for new development and
 722         scheduled for removal)</LI>
 723
 724 </UL>
 725
 726 <H3>Variables</H3>
 727
 728 <P>Variables with a global scope shall be capitalized
 729 ("ThisVariable", "ThatVariable", "ThisStateVariable", etc.) The
 730 only exception to this rule shall be the CUPS interface library
 731 global variables which must begin with the prefix "cups"
 732 ("cupsThisVariable", "cupsThatVariable", etc.) Global variables
 733 shall be replaced by function arguments whenever possible.</P>
 734
 735 <P>Variables with a local scope shall be lowercase with
 736 underscores between words ("this_variable", "that_variable",
 737 etc.) Any local variables shared by functions within a source
 738 file shall be declared "static".</P>
 739
 740 <P>Each variable shall be declared on a separate line and shall
 741 be immediately followed by a comment block describing the
 742 variable:</P>
 743
 744 <PRE CLASS="command">
 745 int this_variable;   /* The current state of this */
 746 int that_variable;   /* The current state of that */
 747 </PRE>
 748
 749 <H3>Types</H3>
 750
 751 <P>All type names shall be lowercase with underscores between
 752 words and "_t" appended to the end of the name
 753 ("cups_this_type_t", "cups_that_type_t", etc.) Type names must
 754 start with a prefix, typically "cups" or the name of the program,
 755 to avoid conflicts with system types. Private type names must
 756 start with an underscore ("_cups_this_t", "_cups_that_t",
 757 etc.)</P>
 758
 759 <P>Each type shall have a comment block immediately after the
 760 typedef:</P>
 761
 762 <PRE CLASS="command">
 763 typedef int cups_this_type_t;           /* This type is for CUPS foobar options. */
 764 </PRE>
 765
 766 <H3>Structures</H3>
 767
 768 <P>All structure names shall be lowercase with underscores
 769 between words and "_s" appended to the end of the name
 770 ("cups_this_s", "cups_that_s", etc.) Structure names must start
 771 with a prefix, typically "cups" or the name of the program, to
 772 avoid conflicts with system types. Private structure names must
 773 start with an underscore ("_cups_this_s", "_cups_that_s",
 774 etc.)</P>
 775
 776 <P>Each structure shall have a comment block immediately after
 777 the struct and each member shall be documented in accordance with
 778 the variable naming policy above:</P>
 779
 780 <PRE CLASS="command">
 781 struct cups_this_struct_s               /* This structure is for CUPS foobar options. */
 782 {
 783   int this_member;                      /* Current state for this */
 784   int that_member;                      /* Current state for that */
 785 };
 786 </PRE>
 787
 788 <H3>Constants</H3>
 789
 790 <P>All constant names shall be uppercase with underscored between
 791 words ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.)
 792 Constants must begin with an uppercase prefix, typically "CUPS"
 793 or the program name.</P>
 794
 795 <P>Typed enumerations shall be used whenever possible to allow
 796 for type checking by the compiler.</P>
 797
 798 <P>Comment blocks shall immediately follow each constant:</P>
 799
 800 <PRE CLASS="command">
 801 enum
 802 {
 803   CUPS_THIS_TRAY,                       /* This tray */
 804   CUPS_THAT_TRAY                        /* That tray */
 805 };
 806 </PRE>
 807
 808 <H3>Code</H3>
 809
 810 <P>All source code shall utilize block comments within functions
 811 to describe the operations being performed by a group of
 812 statements; avoid putting a comment per line unless absolutely
 813 necessary, and then consider refactoring the code so that it is
 814 not necessary:</P>
 815
 816 <PRE CLASS="command">
 817 /*
 818  * Clear the state array before we begin...
 819  */
 820
 821 for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 822   array[i] = STATE_IDLE;
 823
 824 /*
 825  * Wait for state changes...
 826  */
 827
 828 do
 829 {
 830   for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 831     if (array[i] != STATE_IDLE)
 832       break;
 833
 834   if (i == (sizeof(array) / sizeof(array[0])))
 835     sleep(1);
 836 } while (i == (sizeof(array) / sizeof(array[0])));
 837 </PRE>
 838
 839 <H3>Indentation</H3>
 840
 841 <P>All code blocks enclosed by brackets shall begin with the
 842 opening brace on a new line. The code then follows starting on a
 843 new line after the brace and is indented 2 spaces. The closing
 844 brace is then placed on a new line following the code at the
 845 original indentation:</P>
 846
 847 <PRE CLASS="command">
 848 {
 849   int i; /* Looping var */
 850
 851  /*
 852   * Process foobar values from 0 to 999...
 853   */
 854
 855   for (i = 0; i &lt; 1000; i ++)
 856   {
 857     do_this(i);
 858     do_that(i);
 859   }
 860 }
 861 </PRE>
 862
 863 <P>Single-line statements following "do", "else", "for", "if",
 864 and "while" shall be indented 2 spaces as well. Blocks of code
 865 in a "switch" block shall be indented 4 spaces after each "case"
 866 and "default" case:</P>
 867
 868 <PRE CLASS="command">
 869 switch (array[i])
 870 {
 871   case STATE_IDLE :
 872       do_this(i);
 873       do_that(i);
 874       break;
 875   default :
 876       do_nothing(i);
 877       break;
 878 }
 879 </PRE>
 880
 881 <H3>Spacing</H3>
 882
 883 <P>A space shall follow each reserved word ("if", "while", etc.)
 884 Spaces shall not be inserted between a function name and the
 885 arguments in parenthesis.</P>
 886
 887 <H3>Return Values</H3>
 888
 889 <P>Parenthesis shall surround values returned from a function
 890 using "return":</P>
 891
 892 <PRE CLASS="command">
 893 return (CUPS_STATE_IDLE);
 894 </PRE>
 895
 896 <H3>Loops</H3>
 897
 898 <P>Whenever convenient loops should count downward to zero to
 899 improve program performance:</P>
 900
 901 <PRE CLASS="command">
 902 for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
 903   array[i] = CUPS_STATE_IDLE;
 904 </PRE>
 905
 906 <H2 CLASS="title"><A NAME="MAKEFILES">Makefile Guidelines</A></H2>
 907
 908 <P>The following is a guide to the makefile-based build system
 909 used by CUPS. These standards have been developed over the years
 910 to allow CUPS to be built on as many systems and environments as
 911 possible.</P>
 912
 913 <H3>General Organization</H3>
 914
 915 <P>The CUPS source code is organized functionally into a
 916 top-level makefile, include file, and subdirectories each with
 917 their own makefile and dependencies files. The ".in" files are
 918 template files for the <CODE>autoconf</CODE> software and are
 919 used to generate a static version of the corresponding file.</P>
 920
 921 <H3>Makefile Documentation</H3>
 922
 923 <P>Each make file must start with the standard CUPS header
 924 containing the Subversion "&#36;Id$" keyword, description of the
 925 file, and CUPS copyright and license notice:</P>
 926
 927 <PRE CLASS="command">
 928 #
 929 # "&#36;Id$"
 930 #
 931 #   Makefile for ...
 932 #
 933 #   Copyright yyyy-YYYY by Easy Software Products, all rights
 934 #   reserved.
 935 #
 936 #   These coded instructions, statements, and computer programs are
 937 #   the property of Easy Software Products and are protected by
 938 #   Federal copyright law.  Distribution and use rights are outlined
 939 #   in the file "LICENSE.txt" which should have been included with
 940 #   this file.  If this file is missing or damaged please contact
 941 #   Easy Software Products at:
 942 #
 943 #       Attn: CUPS Licensing Information
 944 #       Easy Software Products
 945 #       44141 Airport View Drive, Suite 204
 946 #       Hollywood, Maryland 20636 USA
 947 #
 948 #       Voice: (301) 373-9600
 949 #       EMail: cups-info@cups.org
 950 #         WWW: http://www.cups.org/
 951 #
 952 </PRE>
 953
 954 <P>The end of each makefile must have a comment saying:</P>
 955
 956 <PRE CLASS="command">
 957 #
 958 # End of "&#36;Id$".
 959 #
 960 </PRE>
 961
 962 <P>The purpose of the trailer is to indicate the end of the
 963 makefile so that truncations are immediately obvious.</P>
 964
 965 <H3>Portable Makefile Construction</H3>
 966
 967 <P>CUPS uses a common subset of make program syntax to ensure
 968 that the software can be compiled "out of the box" on as many
 969 systems as possible. The following is a list of assumptions we
 970 follow when constructing makefiles:</P>
 971
 972 <UL>
 973
 974         <LI><b>Targets</b>; we assume that the make program
 975         supports the notion of simple targets of the form
 976         "name:" that perform tab-indented commands that follow
 977         the target, e.g.:
 978         <PRE CLASS="command">
 979 target:
 980 &rarr; target commands</PRE></LI>
 981
 982         <LI><b>Dependencies</b>; we assume that the make program
 983         supports recursive dependencies on targets, e.g.:
 984         <PRE CLASS="command">
 985 target: foo bar
 986 &rarr; target commands
 987
 988 foo: bla
 989 &rarr; foo commands
 990
 991 bar:
 992 &rarr; bar commands
 993
 994 bla:
 995 &rarr; bla commands</PRE></LI>
 996
 997         <LI><b>Variable Definition</b>; we assume that the make program
 998         supports variable definition on the command-line or in the makefile
 999         using the following form:
1000         <PRE CLASS="command">
1001 name=value</PRE>
1002
1003         <LI><b>Variable Substitution</b>; we assume that the make program
1004         supports variable substitution using the following forms:
1005         <UL>
1006                 <LI><CODE>$(name)</CODE>; substitutes the value of "name",</LI>
1007                 <LI><CODE>($name:.old=.new)</CODE>; substitutes the value of "name"
1008                 with the filename extensions ".old" changed to ".new",</LI>
1009                 <LI><CODE>$(MAKEFLAGS)</CODE>; substitutes the
1010                 command-line options passed to the program
1011                 without the leading hyphen (-),</LI>
1012                 <LI><CODE>$$</CODE>; substitutes a single <CODE>$</CODE> character,</LI>
1013                 <LI><CODE>$&lt;</CODE>; substitutes the current source file or dependency, and</LI>
1014                 <LI><CODE>$@</CODE>; substitutes the current target name.</LI>
1015         </UL></LI>
1016
1017         <LI><b>Suffixes</b>; we assume that the make program
1018         supports filename suffixes with assumed dependencies, e.g.:
1019         <PRE CLASS="command">
1020 .SUFFIXES: .c .o
1021 .c.o:
1022 &rarr; $(CC) $(CFLAGS) -o $@ -c $&lt;</PRE></LI>
1023
1024         <LI><b>Include Files</b>; we assume that the make program
1025         supports the <CODE>include</CODE> directive, e.g.:
1026         <PRE CLASS="command">
1027 include ../Makedefs
1028 include Dependencies</PRE></LI>
1029
1030         <LI><b>Comments</b>; we assume that comments begin with
1031         a <CODE>#</CODE> character and proceed to the end of the
1032         current line.</LI>
1033
1034         <LI><b>Line Length</b>; we assume that there is no
1035         practical limit to the length of lines.</LI>
1036
1037         <LI><b>Continuation of long lines</b>; we assume that
1038         the <CODE>\</CODE> character may be placed at the end of a
1039         line to concatenate two or more lines in a
1040         makefile to form a single long line.</LI>
1041
1042         <LI><b>Shell</b>; we assume a POSIX-compatible shell is
1043         present on the build system.</LI>
1044
1045 </UL>
1046
1047 <H3>Standard Variables</H3>
1048
1049 <P>The following variables are defined in the "Makedefs" file
1050 generated by the <CODE>autoconf</CODE> software:</P>
1051
1052 <UL>
1053
1054         <LI><CODE>AR</CODE>; the library archiver command,</LI>
1055
1056         <LI><CODE>ARFLAGS</CODE>; options for the library archiver command,</LI>
1057
1058         <LI><CODE>BUILDROOT</CODE>; optional installation prefix,</LI>
1059
1060         <LI><CODE>MAN1EXT</CODE>; extension for man pages in section 1,</LI>
1061
1062         <LI><CODE>MAN3EXT</CODE>; extension for man pages in section 3,</LI>
1063
1064         <LI><CODE>MAN5EXT</CODE>; extension for man pages in section 5,</LI>
1065
1066         <LI><CODE>MAN7EXT</CODE>; extension for man pages in section 7,</LI>
1067
1068         <LI><CODE>MAN8DIR</CODE>; subdirectory for man pages in section 8,</LI>
1069
1070         <LI><CODE>MAN8EXT</CODE>; extension for man pages in section 8,</LI>
1071
1072         <LI><CODE>CC</CODE>; the C compiler command,</LI>
1073
1074         <LI><CODE>CFLAGS</CODE>; options for the C compiler command,</LI>
1075
1076         <LI><CODE>CXX</CODE>; the C++ compiler command,</LI>
1077
1078         <LI><CODE>CXXFLAGS</CODE>; options for the C++ compiler command,</LI>
1079
1080         <LI><CODE>DSOCOMMAND</CODE>; the shared library building command,</LI>
1081
1082         <LI><CODE>DSOFLAGS</CODE>; options for the shared library building command,</LI>
1083
1084         <LI><CODE>INSTALL</CODE>; the <CODE>install</CODE> command,</LI>
1085
1086         <LI><CODE>INSTALL_BIN</CODE>; the program installation command,</LI>
1087
1088         <LI><CODE>INSTALL_DATA</CODE>; the data file installation command,</LI>
1089
1090         <LI><CODE>INSTALL_DIR</CODE>; the directory installation command,</LI>
1091
1092         <LI><CODE>INSTALL_LIB</CODE>; the library installation command,</LI>
1093
1094         <LI><CODE>INSTALL_MAN</CODE>; the documentation installation command,</LI>
1095
1096         <LI><CODE>INSTALL_SCRIPT</CODE>; the shell script installation command,</LI>
1097
1098         <LI><CODE>LDFLAGS</CODE>; options for the linker,</LI>
1099
1100         <LI><CODE>LIBS</CODE>; libraries for all programs,</LI>
1101
1102         <LI><CODE>LN</CODE>; the <CODE>ln</CODE> command,</LI>
1103
1104         <LI><CODE>OPTIM</CODE>; common compiler optimization options,</LI>
1105
1106         <LI><CODE>RM</CODE>; the <CODE>rm</CODE> command,</LI>
1107
1108         <LI><CODE>SHELL</CODE>; the <CODE>sh</CODE> (POSIX shell) command,</LI>
1109
1110         <LI><CODE>STRIP</CODE>; the <CODE>strip</CODE> command,</LI>
1111
1112         <LI><CODE>bindir</CODE>; the binary installation directory,</LI>
1113
1114         <LI><CODE>datadir</CODE>; the data file installation directory,</LI>
1115
1116         <LI><CODE>exec_prefix</CODE>; the installation prefix for executable files,</LI>
1117
1118         <LI><CODE>libdir</CODE>; the library installation directory,</LI>
1119
1120         <LI><CODE>mandir</CODE>; the man page installation directory,</LI>
1121
1122         <LI><CODE>prefix</CODE>; the installation prefix for non-executable files, and</LI>
1123
1124         <LI><CODE>srcdir</CODE>; the source directory.</LI>
1125
1126 </UL>
1127
1128 <H3>Standard Targets</H3>
1129
1130 <P>The following standard targets must be defined in each
1131 makefile:</P>
1132
1133 <UL>
1134
1135         <LI><CODE>all</CODE>; creates all target programs,
1136         libraries, and documentation files,</LI>
1137
1138         <LI><CODE>clean</CODE>; removes all target programs,
1139         libraries, documentation files, and object files,</LI>
1140
1141         <LI><CODE>depend</CODE>; generates automatic dependencies
1142         for any C or C++ source files (also see <A
1143         HREF="#DEPEND_TARGET">"Dependencies"</A>),</LI>
1144
1145         <LI><CODE>distclean</CODE>; removes autoconf-generated files
1146         in addition to those removed by the "clean" target,</LI>
1147
1148         <LI><CODE>install</CODE>; installs all distribution files in
1149         their corresponding locations (also see <A
1150         HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), </LI>
1151
1152         <LI><CODE>uninstall</CODE>; removes all distribution files from
1153         their corresponding locations (also see <A
1154         HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), and</LI>
1155
1156 </UL>
1157
1158
1159 <H3>Object Files</H3>
1160
1161 <P>Object files (the result of compiling a C or C++ source file)
1162 have the extension ".o".</P>
1163
1164 <H3>Programs</H3>
1165
1166 <P>Program files are the result of linking object files and
1167 libraries together to form an executable file. A typical
1168 program target looks like:</P>
1169
1170 <PRE CLASS="command">
1171 program: $(OBJS)
1172 &rarr; echo Linking $@...
1173 &rarr; $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
1174 </PRE>
1175
1176 <H3>Static Libraries</H3>
1177
1178 <P>Static libraries have a prefix of "lib" and the extension
1179 ".a". A typical static library target looks like:</P>
1180
1181 <PRE CLASS="command">
1182 libname.a: $(OBJECTS)
1183 &rarr; echo Creating $@...
1184 &rarr; $(RM) $@
1185 &rarr; $(AR) $(ARFLAGS) $@ $(OBJECTS)
1186 &rarr; $(RANLIB) $@
1187 </PRE>
1188
1189 <H3>Shared Libraries</H3>
1190
1191 <P>Shared libraries have a prefix of "lib" and the extension
1192 ".dylib", ".sl", ".so", or "_s.a" depending on the operating
1193 system. A typical shared library is composed of several targets
1194 that look like:</P>
1195
1196 <PRE CLASS="command">
1197 libname.so: $(OBJECTS)
1198 &rarr; echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
1199 &rarr; $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
1200 &rarr; $(RM) libname.so libname.so.$(DSOMAJOR)
1201 &rarr; $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
1202 &rarr; $(LN) libname.so.$(DSOVERSION) libname.so
1203
1204 libname.sl: $(OBJECTS)
1205 &rarr; echo $(DSOCOMMAND) libname.sl.$(DSOVERSION) ...
1206 &rarr; $(DSOCOMMAND) libname.sl.$(DSOVERSION) $(OBJECTS)
1207 &rarr; $(RM) libname.sl libname.sl.$(DSOMAJOR)
1208 &rarr; $(LN) libname.sl.$(DSOVERSION) libname.sl.$(DSOMAJOR)
1209 &rarr; $(LN) libname.sl.$(DSOVERSION) libname.sl
1210
1211 libname.dylib: $(OBJECTS)
1212 &rarr; echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
1213 &rarr; $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
1214 &rarr; &rarr; -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
1215 &rarr; &rarr; -current_version libname.$(DSOVERSION).dylib \
1216 &rarr; &rarr; -compatibility_version $(DSOMAJOR).0 \
1217 &rarr; &rarr; $(OBJECTS) $(LIBS)
1218 &rarr; $(RM) libname.dylib
1219 &rarr; $(RM) libname.$(DSOMAJOR).dylib
1220 &rarr; $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
1221 &rarr; $(LN) libname.$(DSOVERSION).dylib libname.dylib
1222
1223 libname_s.a: $(OBJECTS)
1224 &rarr; echo $(DSOCOMMAND) libname_s.o ...
1225 &rarr; $(DSOCOMMAND) libname_s.o $(OBJECTS) $(LIBS)
1226 &rarr; echo $(LIBCOMMAND) libname_s.a libname_s.o
1227 &rarr; $(RM) $@
1228 &rarr; $(LIBCOMMAND) libname_s.a libname_s.o
1229 &rarr; $(CHMOD) +x libname_s.a
1230 </PRE>
1231
1232
1233 <H3>Dependencies</H3>
1234
1235 <P>Static dependencies are expressed in each makefile following the
1236 target, for example:</P>
1237
1238 <PRE CLASS="command">
1239 foo: bar
1240 </PRE>
1241
1242 <P>Static dependencies shall only be used when it is not
1243 possible to automatically generate them. Automatic dependencies
1244 are stored in a file named "Dependencies" and included at the
1245 end of the makefile. The following "depend" target rule shall be
1246 used to create the automatic dependencies:
1247
1248 <PRE CLASS="command">
1249 depend:
1250 &rarr; $(MAKEDEPEND) -Y -I.. -f Dependencies $(OBJS:.o=.c)
1251 </PRE>
1252
1253 <P>We only regenerate the automatic dependencies on a Linux
1254 system and express any non-Linux dependencies statically in the
1255 makefile.</P>
1256
1257 <H3><A NAME="TARGET_INSTALL">Install/Uninstall Support</A></H3>
1258
1259 <P>All makefiles must contain install and uninstall rules which
1260 install or remove the corresponding software. These rules must
1261 use the <CODE>$(BUILDROOT)</CODE> variable as a prefix to any
1262 installation directory so that CUPS can be installed in a
1263 temporary location for packaging by programs like
1264 <CODE>rpmbuild</CODE>.</P>
1265
1266 <P>The <CODE>$(INSTALL_BIN)</CODE>, <CODE>$(INSTALL_DATA)</CODE>,
1267 <CODE>$(INSTALL_DIR)</CODE>, <CODE>$(INSTALL_LIB)</CODE>,
1268 <CODE>$(INSTALL_MAN)</CODE>, and <CODE>$(INSTALL_SCRIPT)</CODE>
1269 variables must be used when installing files so that the proper
1270 ownership and permissions are set on the installed files.</P>
1271
1272 <P>The <CODE>$(RANLIB)</CODE> command must be run on any static
1273 libraries after installation since the symbol table is
1274 invalidated when the library is copied on some platforms.</P>
1275
1276 </BODY>
1277 </HTML>