2 <!-- SECTION: Specifications -->
4 <TITLE>CUPS Configuration Management Plan
</TITLE>
8 <P>This configuration management plan documents the guidelines
9 and processes we use when developing and maintaining the Common
10 UNIX Printing System (
"CUPS") and related software. Our goal is
11 to provide reliable and efficient software and documentation that
12 addresses the needs of our users.
</P>
14 <H2 CLASS=
"title"><A NAME=
"COMMUNICATION">Communication
</A></H2>
16 <H3><A NAME=
"CONTACT">How to Contact the Developers
</A></H3>
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
24 <DIV CLASS=
"table"><TABLE SUMMARY=
"CUPS Forums">
25 <CAPTION>Table
1: CUPS Forums
</CAPTION>
28 <TH>Focus/Purpose
</TH>
32 <TD>Discussion of bugs and issues in the CUPS
37 <TD>Report of all commits to the Subversion repository
42 <TD>Usage and development questions for the CUPS Driver
46 <TD>cups.development
</TD>
47 <TD>Development questions and discussion of new features
48 in the CUPS software
</TD>
52 <TD>Usage questions for the CUPS software
</TD>
56 <H3><A NAME=
"SUBMIT">How to Submit a Bug Report or Feature Request
</A></H3>
58 <P>The CUPS
"<A HREF="http://www.cups.org/str.php
">Bugs &
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>
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>
72 <BLOCKQUOTE>Please use the search feature of the Bugs
&
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>
80 <H3><A NAME=
"PATCH">How to Prepare a Patch
</A></H3>
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>
90 svn diff
>filename.patch
93 <P>If you produce a patch using a released source archive, use
94 one of the following commands instead:
</P>
97 diff -u oldfilename filename
>filename.patch
99 diff -urN olddirectory directory
>filename.patch
102 <P>New files and files with significant changes can be submitted
103 in their entirety, however that may delay the adoption of your
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
115 <H2 CLASS=
"title"><A NAME=
"PRACTICES">Software Development Practices
</A></H2>
117 <H3><A NAME=
"VERSIONS">Version Numbering
</A></H3>
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
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>
135 <P>Production releases use the plain version numbers:
</P>
137 <PRE CLASS=
"command">
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
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>
167 <P>Beta-test releases are identified by appending the letter B
168 to the major and minor version numbers followed by the beta
171 <PRE CLASS=
"command">
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>
180 <PRE CLASS=
"command">
185 <P>Developer snapshots are identified by appending the letters
186 SVN-R to the major and minor version numbers followed by the
189 <PRE CLASS=
"command">
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
200 <H3>Version Control (Subversion)
</H3>
202 <P>The CUPS source files are managed by the Subversion (
"SVN")
203 software, available at:
</P>
205 <PRE CLASS=
"command">
206 <A HREF=
"http://subversion.tigris.org/" TARGET=
"_blank">subversion.tigris.org
</A>
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>
214 <PRE CLASS=
"command">
215 Summary of the change (
"fix PostScript printing bug") along
216 with corresponding STRs (
"STR #1, STR #6")
219 - function(): Detailed list of changes
220 - function2(): Detailed list of changes
221 - Summary of design changes (
"added new foo struct")
224 - More detailed changes
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
232 <DIV CLASS=
"table"><TABLE SUMMARY=
"CUPS Subversion URLs">
233 <CAPTION>Table
2: CUPS Subversion URLs
</CAPTION>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
298 <H3>Files and Directories
</H3>
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>
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
312 <H3>Build System
</H3>
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>®</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
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>
333 <H3><A NAME=
"PACKAGING">Packaging
</A></H3>
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>
339 <PRE CLASS=
"command">
341 tools/makesrcdist
<I>version
</I>
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>
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>
361 <PRE CLASS=
"command">
362 rpmbuild -ta cups-
<I>version
</I>-source.tar.gz
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>
371 <DIV CLASS=
"table"><TABLE SUMMARY=
"Binary Package Targets">
372 <CAPTION>Table
3: Binary Package Targets
</CAPTION>
375 <TH>Type of Package
</TH>
379 <TD>AIX installp
</TD>
383 <TD>*BSD pkg_install
</TD>
391 <TD>HP-UX swinstall
</TD>
395 <TD>Portable tarball with install script
</TD>
399 <TD>IRIX inst/tardist
</TD>
403 <TD>MacOS X Install
</TD>
407 <TD>Solaris pkgadd
</TD>
415 <TD>Tru64 UNIX setld
</TD>
419 <TD>Slackware install
</TD>
423 <TD>HP-UX swinstall
</TD>
427 <TD>IRIX inst/tardist
</TD>
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>
436 <PRE CLASS=
"command">
438 sudo rpm -U /usr/src/redhat/RPMS/i386/cups*.rpm
445 <H3><A NAME=
"TESTING">Testing
</A></H3>
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>
451 <PRE CLASS=
"command">
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>
460 <H2 CLASS=
"title"><A NAME=
"STR">Trouble Report Processing
</A></H2>
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
&
466 Features
</A> page with one of the following states:
</P>
470 <LI>STR is closed with complete resolution
</LI>
472 <LI>STR is closed without resolution
</LI>
474 <LI>STR is active, waiting on information from submitter
</LI>
476 <LI>STR is pending with additional information from submitter
</LI>
478 <LI>STR is newly submitted
</LI>
482 <P>Trouble reports are processed using the following steps.
</P>
488 <P>When a trouble report is received it must be classified at one
489 of the following priority levels:
</P>
493 <LI>Request for enhancement, e.g. asking for a
496 <LI>Low, e.g. a documentation error or undocumented
499 <LI>Moderate, e.g. unable to print a file or unable to
502 <LI>High, e.g. unable to print to a printer or key
503 functionality not working
505 <LI>Critical, e.g. unable to print at all
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>
515 <P>The scope of the problem is also determined as:
</P>
519 <LI>Specific to a machine or printer
521 <LI>Specific to an operating system
523 <LI>Applies to all machines, printers, and operating systems
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>
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>
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>
548 <P>The user or vendor is notified when the fix is available or if
549 the problem was caused by user error.
</P>
554 <H2 CLASS=
"title"><A NAME=
"RELEASES">Release Management
</A></H2>
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>
565 <DIV CLASS=
"table"><TABLE SUMMARY=
"CUPS Basic Release Schedule">
566 <CAPTION>Table: CUPS Basic Release Schedule
</CAPTION>
575 <TD>First beta release
</TD>
580 <TD>Second beta release
</TD>
585 <TD>First release candidate
</TD>
590 <TD>Second release candidate
</TD>
595 <TD>Production (feature) release
</TD>
600 <H2 CLASS=
"title"><A NAME=
"CODING">Coding Guidelines
</A></H2>
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
608 <H3>Source Files
</H3>
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>
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
"$Id$" tag:
</P>
622 <PRE CLASS=
"command">
626 * Description of file contents.
628 * Copyright yyyy-YYYY by Easy Software Products, all rights
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:
638 * Attn: CUPS Licensing Information
639 * Easy Software Products
640 *
44141 Airport View Drive, Suite
204
641 * Hollywood, Maryland
20636 USA
643 * Voice: (
301)
373-
9600
644 * EMail: cups-info@cups.org
645 * WWW: http://www.cups.org/
649 * function1() - Description
1.
650 * function2() - Description
2.
651 * function3() - Description
3.
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>
659 <PRE CLASS=
"command">
660 * This file is subject to the Apple OS-Developed Software exception.
663 <P>The bottom of each source file shall contain a trailer giving
664 the name of the file using the Subversion
"$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>
669 <PRE CLASS=
"command">
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",
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>
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
692 <PRE CLASS=
"command">
694 * 'do_this()' - Compute y = this(x).
699 static float /* O - Inverse power value,
0.0 <= y
<=
1.1 */
700 do_this(float x) /* I - Power value (
0.0 <= x
<=
1.1) */
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
712 <P>The Mini-XML documentation generator also understands the following
713 special text in the function description comment:
</P>
717 <LI><CODE>@since CUPS
<I>version
</I>@
</CODE> - Marks the
718 function as new in the specified version of CUPS.
</LI>
720 <LI><CODE>@deprecated@
</CODE> - Marks the function as
721 deprecated (not recommended for new development and
722 scheduled for removal)
</LI>
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>
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>
740 <P>Each variable shall be declared on a separate line and shall
741 be immediately followed by a comment block describing the
744 <PRE CLASS=
"command">
745 int this_variable; /* The current state of this */
746 int that_variable; /* The current state of that */
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",
759 <P>Each type shall have a comment block immediately after the
762 <PRE CLASS=
"command">
763 typedef int cups_this_type_t; /* This type is for CUPS foobar options. */
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",
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>
780 <PRE CLASS=
"command">
781 struct cups_this_struct_s /* This structure is for CUPS foobar options. */
783 int this_member; /* Current state for this */
784 int that_member; /* Current state for that */
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>
795 <P>Typed enumerations shall be used whenever possible to allow
796 for type checking by the compiler.
</P>
798 <P>Comment blocks shall immediately follow each constant:
</P>
800 <PRE CLASS=
"command">
803 CUPS_THIS_TRAY, /* This tray */
804 CUPS_THAT_TRAY /* That tray */
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
816 <PRE CLASS=
"command">
818 * Clear the state array before we begin...
821 for (i =
0; i
< (sizeof(array) / sizeof(sizeof(array[
0])); i ++)
822 array[i] = STATE_IDLE;
825 * Wait for state changes...
830 for (i =
0; i
< (sizeof(array) / sizeof(sizeof(array[
0])); i ++)
831 if (array[i] != STATE_IDLE)
834 if (i == (sizeof(array) / sizeof(array[
0])))
836 } while (i == (sizeof(array) / sizeof(array[
0])));
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>
847 <PRE CLASS=
"command">
849 int i; /* Looping var */
852 * Process foobar values from
0 to
999...
855 for (i =
0; i
< 1000; i ++)
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>
868 <PRE CLASS=
"command">
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>
887 <H3>Return Values
</H3>
889 <P>Parenthesis shall surround values returned from a function
892 <PRE CLASS=
"command">
893 return (CUPS_STATE_IDLE);
898 <P>Whenever convenient loops should count downward to zero to
899 improve program performance:
</P>
901 <PRE CLASS=
"command">
902 for (i = sizeof(array) / sizeof(array[
0]) -
1; i
>=
0; i --)
903 array[i] = CUPS_STATE_IDLE;
906 <H2 CLASS=
"title"><A NAME=
"MAKEFILES">Makefile Guidelines
</A></H2>
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
913 <H3>General Organization
</H3>
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>
921 <H3>Makefile Documentation
</H3>
923 <P>Each make file must start with the standard CUPS header
924 containing the Subversion
"$Id$" keyword, description of the
925 file, and CUPS copyright and license notice:
</P>
927 <PRE CLASS=
"command">
933 # Copyright yyyy-YYYY by Easy Software Products, all rights
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:
943 # Attn: CUPS Licensing Information
944 # Easy Software Products
945 #
44141 Airport View Drive, Suite
204
946 # Hollywood, Maryland
20636 USA
948 # Voice: (
301)
373-
9600
949 # EMail: cups-info@cups.org
950 # WWW: http://www.cups.org/
954 <P>The end of each makefile must have a comment saying:
</P>
956 <PRE CLASS=
"command">
962 <P>The purpose of the trailer is to indicate the end of the
963 makefile so that truncations are immediately obvious.
</P>
965 <H3>Portable Makefile Construction
</H3>
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>
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
978 <PRE CLASS=
"command">
980 → target commands
</PRE></LI>
982 <LI><b>Dependencies
</b>; we assume that the make program
983 supports recursive dependencies on targets, e.g.:
984 <PRE CLASS=
"command">
986 → target commands
995 → bla commands
</PRE></LI>
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">
1003 <LI><b>Variable Substitution
</b>; we assume that the make program
1004 supports variable substitution using the following forms:
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>$
<</CODE>; substitutes the current source file or dependency, and
</LI>
1014 <LI><CODE>$@
</CODE>; substitutes the current target name.
</LI>
1017 <LI><b>Suffixes
</b>; we assume that the make program
1018 supports filename suffixes with assumed dependencies, e.g.:
1019 <PRE CLASS=
"command">
1022 → $(CC) $(CFLAGS) -o $@ -c $
<</PRE></LI>
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">
1028 include Dependencies
</PRE></LI>
1030 <LI><b>Comments
</b>; we assume that comments begin with
1031 a
<CODE>#
</CODE> character and proceed to the end of the
1034 <LI><b>Line Length
</b>; we assume that there is no
1035 practical limit to the length of lines.
</LI>
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>
1042 <LI><b>Shell
</b>; we assume a POSIX-compatible shell is
1043 present on the build system.
</LI>
1047 <H3>Standard Variables
</H3>
1049 <P>The following variables are defined in the
"Makedefs" file
1050 generated by the
<CODE>autoconf
</CODE> software:
</P>
1054 <LI><CODE>AR
</CODE>; the library archiver command,
</LI>
1056 <LI><CODE>ARFLAGS
</CODE>; options for the library archiver command,
</LI>
1058 <LI><CODE>BUILDROOT
</CODE>; optional installation prefix,
</LI>
1060 <LI><CODE>MAN1EXT
</CODE>; extension for man pages in section
1,
</LI>
1062 <LI><CODE>MAN3EXT
</CODE>; extension for man pages in section
3,
</LI>
1064 <LI><CODE>MAN5EXT
</CODE>; extension for man pages in section
5,
</LI>
1066 <LI><CODE>MAN7EXT
</CODE>; extension for man pages in section
7,
</LI>
1068 <LI><CODE>MAN8DIR
</CODE>; subdirectory for man pages in section
8,
</LI>
1070 <LI><CODE>MAN8EXT
</CODE>; extension for man pages in section
8,
</LI>
1072 <LI><CODE>CC
</CODE>; the C compiler command,
</LI>
1074 <LI><CODE>CFLAGS
</CODE>; options for the C compiler command,
</LI>
1076 <LI><CODE>CXX
</CODE>; the C++ compiler command,
</LI>
1078 <LI><CODE>CXXFLAGS
</CODE>; options for the C++ compiler command,
</LI>
1080 <LI><CODE>DSOCOMMAND
</CODE>; the shared library building command,
</LI>
1082 <LI><CODE>DSOFLAGS
</CODE>; options for the shared library building command,
</LI>
1084 <LI><CODE>INSTALL
</CODE>; the
<CODE>install
</CODE> command,
</LI>
1086 <LI><CODE>INSTALL_BIN
</CODE>; the program installation command,
</LI>
1088 <LI><CODE>INSTALL_DATA
</CODE>; the data file installation command,
</LI>
1090 <LI><CODE>INSTALL_DIR
</CODE>; the directory installation command,
</LI>
1092 <LI><CODE>INSTALL_LIB
</CODE>; the library installation command,
</LI>
1094 <LI><CODE>INSTALL_MAN
</CODE>; the documentation installation command,
</LI>
1096 <LI><CODE>INSTALL_SCRIPT
</CODE>; the shell script installation command,
</LI>
1098 <LI><CODE>LDFLAGS
</CODE>; options for the linker,
</LI>
1100 <LI><CODE>LIBS
</CODE>; libraries for all programs,
</LI>
1102 <LI><CODE>LN
</CODE>; the
<CODE>ln
</CODE> command,
</LI>
1104 <LI><CODE>OPTIM
</CODE>; common compiler optimization options,
</LI>
1106 <LI><CODE>RM
</CODE>; the
<CODE>rm
</CODE> command,
</LI>
1108 <LI><CODE>SHELL
</CODE>; the
<CODE>sh
</CODE> (POSIX shell) command,
</LI>
1110 <LI><CODE>STRIP
</CODE>; the
<CODE>strip
</CODE> command,
</LI>
1112 <LI><CODE>bindir
</CODE>; the binary installation directory,
</LI>
1114 <LI><CODE>datadir
</CODE>; the data file installation directory,
</LI>
1116 <LI><CODE>exec_prefix
</CODE>; the installation prefix for executable files,
</LI>
1118 <LI><CODE>libdir
</CODE>; the library installation directory,
</LI>
1120 <LI><CODE>mandir
</CODE>; the man page installation directory,
</LI>
1122 <LI><CODE>prefix
</CODE>; the installation prefix for non-executable files, and
</LI>
1124 <LI><CODE>srcdir
</CODE>; the source directory.
</LI>
1128 <H3>Standard Targets
</H3>
1130 <P>The following standard targets must be defined in each
1135 <LI><CODE>all
</CODE>; creates all target programs,
1136 libraries, and documentation files,
</LI>
1138 <LI><CODE>clean
</CODE>; removes all target programs,
1139 libraries, documentation files, and object files,
</LI>
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>
1145 <LI><CODE>distclean
</CODE>; removes autoconf-generated files
1146 in addition to those removed by the
"clean" target,
</LI>
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>
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>
1159 <H3>Object Files
</H3>
1161 <P>Object files (the result of compiling a C or C++ source file)
1162 have the extension
".o".
</P>
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>
1170 <PRE CLASS=
"command">
1172 → echo Linking $@...
1173 → $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
1176 <H3>Static Libraries
</H3>
1178 <P>Static libraries have a prefix of
"lib" and the extension
1179 ".a". A typical static library target looks like:
</P>
1181 <PRE CLASS=
"command">
1182 libname.a: $(OBJECTS)
1183 → echo Creating $@...
1185 → $(AR) $(ARFLAGS) $@ $(OBJECTS)
1189 <H3>Shared Libraries
</H3>
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
1196 <PRE CLASS=
"command">
1197 libname.so: $(OBJECTS)
1198 → echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
1199 → $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
1200 → $(RM) libname.so libname.so.$(DSOMAJOR)
1201 → $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
1202 → $(LN) libname.so.$(DSOVERSION) libname.so
1204 libname.sl: $(OBJECTS)
1205 → echo $(DSOCOMMAND) libname.sl.$(DSOVERSION) ...
1206 → $(DSOCOMMAND) libname.sl.$(DSOVERSION) $(OBJECTS)
1207 → $(RM) libname.sl libname.sl.$(DSOMAJOR)
1208 → $(LN) libname.sl.$(DSOVERSION) libname.sl.$(DSOMAJOR)
1209 → $(LN) libname.sl.$(DSOVERSION) libname.sl
1211 libname.dylib: $(OBJECTS)
1212 → echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
1213 → $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
1214 → → -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
1215 → → -current_version libname.$(DSOVERSION).dylib \
1216 → → -compatibility_version $(DSOMAJOR)
.0 \
1217 → → $(OBJECTS) $(LIBS)
1218 → $(RM) libname.dylib
1219 → $(RM) libname.$(DSOMAJOR).dylib
1220 → $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
1221 → $(LN) libname.$(DSOVERSION).dylib libname.dylib
1223 libname_s.a: $(OBJECTS)
1224 → echo $(DSOCOMMAND) libname_s.o ...
1225 → $(DSOCOMMAND) libname_s.o $(OBJECTS) $(LIBS)
1226 → echo $(LIBCOMMAND) libname_s.a libname_s.o
1228 → $(LIBCOMMAND) libname_s.a libname_s.o
1229 → $(CHMOD) +x libname_s.a
1233 <H3>Dependencies
</H3>
1235 <P>Static dependencies are expressed in each makefile following the
1236 target, for example:
</P>
1238 <PRE CLASS=
"command">
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:
1248 <PRE CLASS=
"command">
1250 → $(MAKEDEPEND) -Y -I.. -f Dependencies $(OBJS:.o=.c)
1253 <P>We only regenerate the automatic dependencies on a Linux
1254 system and express any non-Linux dependencies statically in the
1257 <H3><A NAME=
"TARGET_INSTALL">Install/Uninstall Support
</A></H3>
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>
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>
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>