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