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