--- /dev/null
+<HTML>
+<!-- SECTION: Specifications -->
+<HEAD>
+ <TITLE>CUPS Configuration Management Plan</TITLE>
+</HEAD>
+<BODY>
+
+<P>This configuration management plan documents the guidelines
+and processes we use when developing and maintaining the Common
+UNIX Printing System ("CUPS") and related software. Our goal is
+to provide reliable and efficient software and documentation that
+addresses the needs of our users.</P>
+
+<H2 CLASS="title"><A NAME="COMMUNICATION">Communication</A></H2>
+
+<H3><A NAME="CONTACT">How to Contact the Developers</A></H3>
+
+<P>The <A HREF="http://www.cups.org/newsgroups.php">CUPS
+Forums</A> are the primary means of asking questions and
+informally discussing issues and feature requests with the CUPS
+developers. Table 1 shows the available forums and their
+focus:</P>
+
+<DIV CLASS="table"><TABLE SUMMARY="CUPS Forums">
+<CAPTION>Table 1: CUPS Forums</CAPTION>
+<TR>
+ <TH>Forum</TH>
+ <TH>Focus/Purpose</TH>
+</TR>
+<TR>
+ <TD>cups.bugs</TD>
+ <TD>Discussion of bugs and issues in the CUPS
+ software</TD>
+</TR>
+<TR>
+ <TD>cups.commit</TD>
+ <TD>Report of all commits to the Subversion repository
+ (read-only)</TD>
+</TR>
+<TR>
+ <TD>cups.ddk</TD>
+ <TD>Usage and development questions for the CUPS Driver
+ Development Kit</TD>
+</TR>
+<TR>
+ <TD>cups.development</TD>
+ <TD>Development questions and discussion of new features
+ in the CUPS software</TD>
+</TR>
+<TR>
+ <TD>cups.general</TD>
+ <TD>Usage questions for the CUPS software</TD>
+</TR>
+</TABLE></DIV>
+
+<H3><A NAME="SUBMIT">How to Submit a Bug Report or Feature Request</A></H3>
+
+<P>The CUPS "<A HREF="http://www.cups.org/str.php">Bugs &
+Features</A>" page provides access to the CUPS <em>software
+trouble report</em> 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 CUPS Forums for that instead.</P>
+
+<P>Unlike discussions that occur on the CUPS Forums, 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>
+
+<BLOCKQUOTE>Please use the search feature of the Bugs &
+Features 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.</BLOCKQUOTE>
+
+<H3><A NAME="PATCH">How to Prepare a Patch</A></H3>
+
+<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 Subversion <VAR>trunk</VAR> branch, which can
+be generated easily using the following Subversion command:</P>
+
+<PRE CLASS="command">
+svn diff >filename.patch
+</PRE>
+
+<P>If you produce a patch using a released source archive, use
+one of the following commands instead:</P>
+
+<PRE CLASS="command">
+diff -u oldfilename filename >filename.patch
+
+diff -urN olddirectory directory >filename.patch
+</PRE>
+
+<P>New files and files with significant changes can be submitted
+in their entirety, however that may delay the adoption of your
+changes.</P>
+
+<BLOCKQUOTE>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 Easy Software Products provides CUPS
+under multiple licenses, we require that you assign the copyright
+for your changes and files to us for inclusion in
+CUPS.</BLOCKQUOTE>
+
+
+<H2 CLASS="title"><A NAME="PRACTICES">Software Development Practices</A></H2>
+
+<H3><A NAME="VERSIONS">Version Numbering</A></H3>
+
+<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
+release.</P>
+
+<BLOCKQUOTE>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.</BLOCKQUOTE>
+
+<P>Production releases use the plain version numbers:</P>
+
+<PRE CLASS="command">
+MAJOR.MINOR.PATCH
+1.0.0
+1.0.1
+1.0.2
+...
+1.1.0
+...
+1.1.23
+1.2.0
+1.2.1
+...
+1.3.0
+...
+2.0.0
+</PRE>
+
+<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>
+
+<BLOCKQUOTE>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 will be strictly
+enforced. This should yield more frequent minor releases with
+fewer new features (and interactions!) to
+validate/test.</BLOCKQUOTE>
+
+<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>
+
+<PRE CLASS="command">
+MAJOR.MINORbNUMBER
+1.2b1
+</PRE>
+
+<P>Release candidates are identified by appending the letters RC
+to the major and minor version numbers followed by the release
+candidate number:</P>
+
+<PRE CLASS="command">
+MAJOR.MINORrcNUMBER
+1.2rc1
+</PRE>
+
+<P>Developer snapshots are identified by appending the letters
+SVN-R to the major and minor version numbers followed by the
+revision number:</P>
+
+<PRE CLASS="command">
+MAJOR.MINORsvn-rREV
+1.2svn-r1234
+</PRE>
+
+<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 issues without preliminary beta or release
+testing.</P>
+
+<H3>Version Control (Subversion)</H3>
+
+<P>The CUPS source files are managed by the Subversion ("SVN")
+software, available at:</P>
+
+<PRE CLASS="command">
+<A HREF="http://subversion.tigris.org/" TARGET="_blank">subversion.tigris.org</A>
+</PRE>
+
+<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>
+
+<PRE CLASS="command">
+Summary of the change ("fix PostScript printing bug") along
+with corresponding STRs ("STR #1, STR #6")
+
+foo.cxx:
+ - function(): Detailed list of changes
+ - function2(): Detailed list of changes
+ - Summary of design changes ("added new foo struct")
+
+bar.h:
+ - More detailed changes
+</PRE>
+
+<P>Primary development occurs on the <var>trunk</var> branch,
+with changes merged back to release branches as needed. Table 2
+shows the URLs developers use for the various CUPS subprojects
+and branches:</P>
+
+<DIV CLASS="table"><TABLE SUMMARY="CUPS Subversion URLs">
+<CAPTION>Table 2: CUPS Subversion URLs</CAPTION>
+<TR>
+ <TH>URL</TH>
+ <TH>Purpose</TH>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/cups/trunk/">https://svn.easysw.com/public/cups/trunk/</A></TD>
+ <TD>Primary CUPS development branch</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/cups/branches/">https://svn.easysw.com/public/cups/branches/</A></TD>
+ <TD>CUPS maintenance branches (merge-only)</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/cups/tags/">https://svn.easysw.com/public/cups/tags/</A></TD>
+ <TD>CUPS release tags (read-only)</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/cupsddk/trunk/">https://svn.easysw.com/public/cupsddk/trunk/</A></TD>
+ <TD>Primary CUPS DDK development branch</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/cupsddk/branches/">https://svn.easysw.com/public/cupsddk/branches/</A></TD>
+ <TD>CUPS DDK maintenance branches (merge-only)</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/cupsddk/tags/">https://svn.easysw.com/public/cupsddk/tags/</A></TD>
+ <TD>CUPS DDK release tags (read-only)</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/espgs/trunk/">https://svn.easysw.com/public/espgs/trunk/</A></TD>
+ <TD>Primary ESP Ghostscript development branch</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/espgs/branches/">https://svn.easysw.com/public/espgs/branches/</A></TD>
+ <TD>ESP Ghostscript maintenance branches (merge-only)</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/espgs/tags/">https://svn.easysw.com/public/espgs/tags/</A></TD>
+ <TD>ESP Ghostscript release tags (read-only)</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/windows/trunk/">https://svn.easysw.com/public/windows/trunk/</A></TD>
+ <TD>Primary CUPS Windows Driver development branch</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/windows/branches/">https://svn.easysw.com/public/windows/branches/</A></TD>
+ <TD>CUPS Windows Driver maintenance branches (merge-only)</TD>
+</TR>
+<TR>
+ <TD><A HREF="http://svn.easysw.com/public/windows/tags/">https://svn.easysw.com/public/windows/tags/</A></TD>
+ <TD>CUPS Windows Driver release tags (read-only)</TD>
+</TR>
+</TABLE></DIV>
+
+<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.MINOR.PATCHbNUMBER",
+"release-MAJOR.MINOR.PATCHrcNUMBER", or
+"release-MAJOR.MINOR.PATCH", respectively. No release tags are
+created for developer snapshots.</P>
+
+
+<H3>Files and Directories</H3>
+
+<P>File and directory names may not exceed 16 characters in
+length to ensure compability 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>
+
+<P>Source files must be documented and formatted as described in
+"<A HREF="#CODING">Coding Requirements</A>". Make files must
+follow the guidelines in "<A HREF="#MAKEFILE">Makefile
+Guidelines</A>".</P>
+
+
+<H3>Build System</H3>
+
+<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 major IDEs are also provided for Microsoft
+Windows<suP>®</suP>. To improve portability, makefiles must
+not make use of the unique features offered by <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>
+
+<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>
+
+
+<H3><A NAME="PACKAGING">Packaging</A></H3>
+
+<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>
+
+<PRE CLASS="command">
+tools/makesrcdist
+tools/makesrcdist <I>version</I>
+</PRE>
+
+<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.2svn-r1234-source.tar.bz2" and
+"/tmp/cups-1.2svn-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
+"/tmp/cups-<I>version</I>-source.tar.bz2" and
+"/tmp/cups-<I>version</I>-source.tar.gz".</P>
+
+<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, MacOS X, and UNIX. The
+<VAR>packaging/cups.spec</VAR> file produces a binary package
+using the <CODE>rpmbuild(8)</CODE> software:</P>
+
+<PRE CLASS="command">
+rpmbuild -ta cups-<I>version</I>-source.tar.gz
+</PRE>
+
+<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="http://www.easysw.com/epm/"
+TARGET="_blank">EPM</A> software. Table 3 shows the targets that
+are available for each type of binary package:</P>
+
+<DIV CLASS="table"><TABLE SUMMARY="Binary Package Targets">
+<CAPTION>Table 3: Binary Package Targets</CAPTION>
+<TR>
+ <TH>Target</TH>
+ <TH>Type of Package</TH>
+</TR>
+<TR>
+ <TD>aix</TD>
+ <TD>AIX installp</TD>
+</TR>
+<TR>
+ <TD>bsd</TD>
+ <TD>*BSD pkg_install</TD>
+</TR>
+<TR>
+ <TD>deb</TD>
+ <TD>Debian dpkg</TD>
+</TR>
+<TR>
+ <TD>depot</TD>
+ <TD>HP-UX swinstall</TD>
+</TR>
+<TR>
+ <TD>epm</TD>
+ <TD>Portable tarball with install script</TD>
+</TR>
+<TR>
+ <TD>inst</TD>
+ <TD>IRIX inst/tardist</TD>
+</TR>
+<TR>
+ <TD>osx</TD>
+ <TD>MacOS X Install</TD>
+</TR>
+<TR>
+ <TD>pkg</TD>
+ <TD>Solaris pkgadd</TD>
+</TR>
+<TR>
+ <TD>rpm</TD>
+ <TD>RPM binary</TD>
+</TR>
+<TR>
+ <TD>setld</TD>
+ <TD>Tru64 UNIX setld</TD>
+</TR>
+<TR>
+ <TD>slackware</TD>
+ <TD>Slackware install</TD>
+</TR>
+<TR>
+ <TD>swinstall</TD>
+ <TD>HP-UX swinstall</TD>
+</TR>
+<TR>
+ <TD>tardist</TD>
+ <TD>IRIX inst/tardist</TD>
+</TR>
+</TABLE></DIV>
+
+<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
+MacOS X, respectively:</P>
+
+<PRE CLASS="command">
+tools/testrpm
+sudo rpm -U /usr/src/redhat/RPMS/i386/cups*.rpm
+
+sudo tools/testosx
+open cups.pkg
+</PRE>
+
+
+<H3><A NAME="TESTING">Testing</A></H3>
+
+<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>
+
+<PRE CLASS="command">
+make test
+</PRE>
+
+<P>The test environment allows for both short-term automated
+testing and long-term testing and development without the
+automated test script.</P>
+
+
+<H2 CLASS="title"><A NAME="STR">Trouble Report Processing</A></H2>
+
+<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="http://www.cups.org/str.php" TARGET="_blank">Bugs &
+Features</A> page with one of the following states:</P>
+
+<OL>
+
+ <LI>STR is closed with complete resolution</LI>
+
+ <LI>STR is closed without resolution</LI>
+
+ <LI>STR is active, waiting on information from submitter</LI>
+
+ <LI>STR is pending with additional information from submitter</LI>
+
+ <LI>STR is newly submitted</LI>
+
+</OL>
+
+<P>Trouble reports are processed using the following steps.</P>
+
+<OL>
+
+<LI>Classification
+
+<P>When a trouble report is received it must be classified at one
+of the following priority levels:</P>
+
+<OL>
+
+ <LI>Request for enhancement, e.g. asking for a
+ feature
+
+ <LI>Low, e.g. a documentation error or undocumented
+ side-effect
+
+ <LI>Moderate, e.g. unable to print a file or unable to
+ compile the software
+
+ <LI>High, e.g. unable to print to a printer or key
+ functionality not working
+
+ <LI>Critical, e.g. unable to print at all
+
+</OL>
+
+<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>
+
+<P>The scope of the problem is also determined as:</P>
+
+<OL>
+
+ <LI>Specific to a machine or printer
+
+ <LI>Specific to an operating system
+
+ <LI>Applies to all machines, printers, and operating systems
+
+</OL>
+
+<LI>Identification
+
+<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>
+
+<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>
+
+<LI>Correction
+
+<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>
+
+<LI>Notification
+
+<P>The user or vendor is notified when the fix is available or if
+the problem was caused by user error.</P>
+
+</OL>
+
+
+<H2 CLASS="title"><A NAME="RELEASES">Release Management</A></H2>
+
+<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>
+
+<DIV CLASS="table"><TABLE SUMMARY="CUPS Basic Release Schedule">
+<CAPTION>Table: CUPS Basic Release Schedule</CAPTION>
+<TR>
+ <TH>Week</TH>
+ <TH>Version</TH>
+ <TH>Description</TH>
+</TR>
+<TR>
+ <TD>T-6 weeks</TD>
+ <TD>1.2b1</TD>
+ <TD>First beta release</TD>
+</TR>
+<TR>
+ <TD>T-5 weeks</TD>
+ <TD>1.2b2</TD>
+ <TD>Second beta release</TD>
+</TR>
+<TR>
+ <TD>T-3 weeks</TD>
+ <TD>1.2rc1</TD>
+ <TD>First release candidate</TD>
+</TR>
+<TR>
+ <TD>T-2 weeks</TD>
+ <TD>1.2rc2</TD>
+ <TD>Second release candidate</TD>
+</TR>
+<TR>
+ <TD>T-0 weeks</TD>
+ <TD>1.2.0</TD>
+ <TD>Production (feature) release</TD>
+</TR>
+</TABLE></DIV>
+
+
+<H2 CLASS="title"><A NAME="CODING">Coding Guidelines</A></H2>
+
+<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>
+
+<H3>Source Files</H3>
+
+<P>All source files names shall be 16 characters or less in
+length to ensure compatibility with older UNIX filesystems.
+Source files containing functions shall have an extension of ".c"
+for ANSI C and ".cxx" for C++ source files. All other "include"
+files shall have an extension of ".h".</P>
+
+<P>The top of each source file shall contain a header giving the
+name of the file, the purpose or nature of the source file, the
+copyright and licensing notice, and the functions contained in
+the file. The file name and revision information is provided by
+the Subversion "$Id$" tag:</P>
+
+<PRE CLASS="command">
+/*
+ * "$Id$"
+ *
+ * Description of file contents.
+ *
+ * Copyright yyyy-YYYY by Easy Software Products, all rights
+ * reserved.
+ *
+ * These coded instructions, statements, and computer programs are
+ * the property of Easy Software Products and are protected by
+ * Federal copyright law. Distribution and use rights are outlined
+ * in the file "LICENSE.txt" which should have been included with
+ * this file. If this file is missing or damaged please contact
+ * Easy Software Products at:
+ *
+ * Attn: CUPS Licensing Information
+ * Easy Software Products
+ * 44141 Airport View Drive, Suite 204
+ * Hollywood, Maryland 20636 USA
+ *
+ * Voice: (301) 373-9600
+ * EMail: cups-info@cups.org
+ * WWW: http://www.cups.org/
+ *
+ * Contents:
+ *
+ * function1() - Description 1.
+ * function2() - Description 2.
+ * function3() - Description 3.
+ */
+</PRE>
+
+<P>For source files that are subject to the Apple OS-Developed
+Software exception, the following additional comment should
+appear after the contact information:</P>
+
+<PRE CLASS="command">
+ * This file is subject to the Apple OS-Developed Software exception.
+</PRE>
+
+<P>The bottom of each source file shall contain 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>
+
+<PRE CLASS="command">
+/*
+ * End of "$Id$".
+ */
+</PRE>
+
+<H3>Functions</H3>
+
+<P>Functions with a global scope shall have a lowercase prefix
+followed by capitalized words ("cupsDoThis", "cupsDoThat",
+"cupsDoSomethingElse", etc.) Private global functions shall begin
+with a leading underscore ("_cupsDoThis", "_cupsDoThat",
+etc.)</P>
+
+<P>Functions with a local scope shall be declared "static" and be
+lowercase with underscores between words ("do_this", "do_that",
+"do_something_else", etc.)</P>
+
+<P>Each function shall begin 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>
+
+<PRE CLASS="command">
+/*
+ * 'do_this()' - Compute y = this(x).
+ *
+ * Notes: none.
+ */
+
+static float /* O - Inverse power value, 0.0 <= y <= 1.1 */
+do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
+{
+ ...
+ return (y);
+}
+</PRE>
+
+<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>
+
+<P>The Mini-XML documentation generator also understands the following
+special text in the function description comment:</P>
+
+<UL>
+
+ <LI><CODE>@since CUPS <I>version</I>@</CODE> - Marks the
+ function as new in the specified version of CUPS.</LI>
+
+ <LI><CODE>@deprecated@</CODE> - Marks the function as
+ deprecated (not recommended for new development and
+ scheduled for removal)</LI>
+
+</UL>
+
+<H3>Variables</H3>
+
+<P>Variables with a global scope shall be capitalized
+("ThisVariable", "ThatVariable", "ThisStateVariable", etc.) The
+only exception to this rule shall be the CUPS interface library
+global variables which must begin with the prefix "cups"
+("cupsThisVariable", "cupsThatVariable", etc.) Global variables
+shall be replaced by function arguments whenever possible.</P>
+
+<P>Variables with a local scope shall be lowercase with
+underscores between words ("this_variable", "that_variable",
+etc.) Any local variables shared by functions within a source
+file shall be declared "static".</P>
+
+<P>Each variable shall be declared on a separate line and shall
+be immediately followed by a comment block describing the
+variable:</P>
+
+<PRE CLASS="command">
+int this_variable; /* The current state of this */
+int that_variable; /* The current state of that */
+</PRE>
+
+<H3>Types</H3>
+
+<P>All type names shall be lowercase with underscores between
+words and "_t" appended to the end of the name
+("cups_this_type_t", "cups_that_type_t", etc.) Type names must
+start with a prefix, typically "cups" or the name of the program,
+to avoid conflicts with system types. Private type names must
+start with an underscore ("_cups_this_t", "_cups_that_t",
+etc.)</P>
+
+<P>Each type shall have a comment block immediately after the
+typedef:</P>
+
+<PRE CLASS="command">
+typedef int cups_this_type_t; /* This type is for CUPS foobar options. */
+</PRE>
+
+<H3>Structures</H3>
+
+<P>All structure names shall be lowercase with underscores
+between words and "_s" appended to the end of the name
+("cups_this_s", "cups_that_s", etc.) Structure names must start
+with a prefix, typically "cups" or the name of the program, to
+avoid conflicts with system types. Private structure names must
+start with an underscore ("_cups_this_s", "_cups_that_s",
+etc.)</P>
+
+<P>Each structure shall have a comment block immediately after
+the struct and each member shall be documented in accordance with
+the variable naming policy above:</P>
+
+<PRE CLASS="command">
+struct cups_this_struct_s /* This structure is for CUPS foobar options. */
+{
+ int this_member; /* Current state for this */
+ int that_member; /* Current state for that */
+};
+</PRE>
+
+<H3>Constants</H3>
+
+<P>All constant names shall be uppercase with underscored between
+words ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.)
+Constants must begin with an uppercase prefix, typically "CUPS"
+or the program name.</P>
+
+<P>Typed enumerations shall be used whenever possible to allow
+for type checking by the compiler.</P>
+
+<P>Comment blocks shall immediately follow each constant:</P>
+
+<PRE CLASS="command">
+enum
+{
+ CUPS_THIS_TRAY, /* This tray */
+ CUPS_THAT_TRAY /* That tray */
+};
+</PRE>
+
+<H3>Code</H3>
+
+<P>All source code shall utilize 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:</P>
+
+<PRE CLASS="command">
+/*
+ * Clear the state array before we begin...
+ */
+
+for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
+ array[i] = STATE_IDLE;
+
+/*
+ * Wait for state changes...
+ */
+
+do
+{
+ for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
+ if (array[i] != STATE_IDLE)
+ break;
+
+ if (i == (sizeof(array) / sizeof(array[0])))
+ sleep(1);
+} while (i == (sizeof(array) / sizeof(array[0])));
+</PRE>
+
+<H3>Indentation</H3>
+
+<P>All code blocks enclosed by brackets shall 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>
+
+<PRE CLASS="command">
+{
+ int i; /* Looping var */
+
+ /*
+ * Process foobar values from 0 to 999...
+ */
+
+ for (i = 0; i < 1000; i ++)
+ {
+ do_this(i);
+ do_that(i);
+ }
+}
+</PRE>
+
+<P>Single-line statements following "do", "else", "for", "if",
+and "while" shall be indented 2 spaces as well. Blocks of code
+in a "switch" block shall be indented 4 spaces after each "case"
+and "default" case:</P>
+
+<PRE CLASS="command">
+switch (array[i])
+{
+ case STATE_IDLE :
+ do_this(i);
+ do_that(i);
+ break;
+ default :
+ do_nothing(i);
+ break;
+}
+</PRE>
+
+<H3>Spacing</H3>
+
+<P>A space shall follow each reserved word ("if", "while", etc.)
+Spaces shall not be inserted between a function name and the
+arguments in parenthesis.</P>
+
+<H3>Return Values</H3>
+
+<P>Parenthesis shall surround values returned from a function
+using "return":</P>
+
+<PRE CLASS="command">
+return (CUPS_STATE_IDLE);
+</PRE>
+
+<H3>Loops</H3>
+
+<P>Whenever convenient loops should count downward to zero to
+improve program performance:</P>
+
+<PRE CLASS="command">
+for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
+ array[i] = CUPS_STATE_IDLE;
+</PRE>
+
+<H2 CLASS="title"><A NAME="MAKEFILES">Makefile Guidelines</A></H2>
+
+<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>
+
+<H3>General Organization</H3>
+
+<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>
+
+<H3>Makefile Documentation</H3>
+
+<P>Each make file must start with the standard CUPS header
+containing the Subversion "$Id$" keyword, description of the
+file, and CUPS copyright and license notice:</P>
+
+<PRE CLASS="command">
+#
+# "$Id$"
+#
+# Makefile for ...
+#
+# Copyright yyyy-YYYY by Easy Software Products, all rights
+# reserved.
+#
+# These coded instructions, statements, and computer programs are
+# the property of Easy Software Products and are protected by
+# Federal copyright law. Distribution and use rights are outlined
+# in the file "LICENSE.txt" which should have been included with
+# this file. If this file is missing or damaged please contact
+# Easy Software Products at:
+#
+# Attn: CUPS Licensing Information
+# Easy Software Products
+# 44141 Airport View Drive, Suite 204
+# Hollywood, Maryland 20636 USA
+#
+# Voice: (301) 373-9600
+# EMail: cups-info@cups.org
+# WWW: http://www.cups.org/
+#
+</PRE>
+
+<P>The end of each makefile must have a comment saying:</P>
+
+<PRE CLASS="command">
+#
+# End of "$Id$".
+#
+</PRE>
+
+<P>The purpose of the trailer is to indicate the end of the
+makefile so that truncations are immediately obvious.</P>
+
+<H3>Portable Makefile Construction</H3>
+
+<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>
+
+<UL>
+
+ <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.:
+ <PRE CLASS="command">
+target:
+→ target commands</PRE></LI>
+
+ <LI><b>Dependencies</b>; we assume that the make program
+ supports recursive dependencies on targets, e.g.:
+ <PRE CLASS="command">
+target: foo bar
+→ target commands
+
+foo: bla
+→ foo commands
+
+bar:
+→ bar commands
+
+bla:
+→ bla commands</PRE></LI>
+
+ <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:
+ <PRE CLASS="command">
+name=value</PRE>
+
+ <LI><b>Variable Substitution</b>; we assume that the make program
+ supports variable substitution using the following forms:
+ <UL>
+ <LI><CODE>$(name)</CODE>; substitutes the value of "name",</LI>
+ <LI><CODE>($name:.old=.new)</CODE>; substitutes the value of "name"
+ with the filename extensions ".old" changed to ".new",</LI>
+ <LI><CODE>$(MAKEFLAGS)</CODE>; substitutes the
+ command-line options passed to the program
+ without the leading hyphen (-),</LI>
+ <LI><CODE>$$</CODE>; substitutes a single <CODE>$</CODE> character,</LI>
+ <LI><CODE>$<</CODE>; substitutes the current source file or dependency, and</LI>
+ <LI><CODE>$@</CODE>; substitutes the current target name.</LI>
+ </UL></LI>
+
+ <LI><b>Suffixes</b>; we assume that the make program
+ supports filename suffixes with assumed dependencies, e.g.:
+ <PRE CLASS="command">
+.SUFFIXES: .c .o
+.c.o:
+→ $(CC) $(CFLAGS) -o $@ -c $<</PRE></LI>
+
+ <LI><b>Include Files</b>; we assume that the make program
+ supports the <CODE>include</CODE> directive, e.g.:
+ <PRE CLASS="command">
+include ../Makedefs
+include Dependencies</PRE></LI>
+
+ <LI><b>Comments</b>; we assume that comments begin with
+ a <CODE>#</CODE> character and proceed to the end of the
+ current line.</LI>
+
+ <LI><b>Line Length</b>; we assume that there is no
+ practical limit to the length of lines.</LI>
+
+ <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>
+
+ <LI><b>Shell</b>; we assume a POSIX-compatible shell is
+ present on the build system.</LI>
+
+</UL>
+
+<H3>Standard Variables</H3>
+
+<P>The following variables are defined in the "Makedefs" file
+generated by the <CODE>autoconf</CODE> software:</P>
+
+<UL>
+
+ <LI><CODE>AR</CODE>; the library archiver command,</LI>
+
+ <LI><CODE>ARFLAGS</CODE>; options for the library archiver command,</LI>
+
+ <LI><CODE>BUILDROOT</CODE>; optional installation prefix,</LI>
+
+ <LI><CODE>MAN1EXT</CODE>; extension for man pages in section 1,</LI>
+
+ <LI><CODE>MAN3EXT</CODE>; extension for man pages in section 3,</LI>
+
+ <LI><CODE>MAN5EXT</CODE>; extension for man pages in section 5,</LI>
+
+ <LI><CODE>MAN7EXT</CODE>; extension for man pages in section 7,</LI>
+
+ <LI><CODE>MAN8DIR</CODE>; subdirectory for man pages in section 8,</LI>
+
+ <LI><CODE>MAN8EXT</CODE>; extension for man pages in section 8,</LI>
+
+ <LI><CODE>CC</CODE>; the C compiler command,</LI>
+
+ <LI><CODE>CFLAGS</CODE>; options for the C compiler command,</LI>
+
+ <LI><CODE>CXX</CODE>; the C++ compiler command,</LI>
+
+ <LI><CODE>CXXFLAGS</CODE>; options for the C++ compiler command,</LI>
+
+ <LI><CODE>DSOCOMMAND</CODE>; the shared library building command,</LI>
+
+ <LI><CODE>DSOFLAGS</CODE>; options for the shared library building command,</LI>
+
+ <LI><CODE>INSTALL</CODE>; the <CODE>install</CODE> command,</LI>
+
+ <LI><CODE>INSTALL_BIN</CODE>; the program installation command,</LI>
+
+ <LI><CODE>INSTALL_DATA</CODE>; the data file installation command,</LI>
+
+ <LI><CODE>INSTALL_DIR</CODE>; the directory installation command,</LI>
+
+ <LI><CODE>INSTALL_LIB</CODE>; the library installation command,</LI>
+
+ <LI><CODE>INSTALL_MAN</CODE>; the documentation installation command,</LI>
+
+ <LI><CODE>INSTALL_SCRIPT</CODE>; the shell script installation command,</LI>
+
+ <LI><CODE>LDFLAGS</CODE>; options for the linker,</LI>
+
+ <LI><CODE>LIBS</CODE>; libraries for all programs,</LI>
+
+ <LI><CODE>LN</CODE>; the <CODE>ln</CODE> command,</LI>
+
+ <LI><CODE>OPTIM</CODE>; common compiler optimization options,</LI>
+
+ <LI><CODE>RM</CODE>; the <CODE>rm</CODE> command,</LI>
+
+ <LI><CODE>SHELL</CODE>; the <CODE>sh</CODE> (POSIX shell) command,</LI>
+
+ <LI><CODE>STRIP</CODE>; the <CODE>strip</CODE> command,</LI>
+
+ <LI><CODE>bindir</CODE>; the binary installation directory,</LI>
+
+ <LI><CODE>datadir</CODE>; the data file installation directory,</LI>
+
+ <LI><CODE>exec_prefix</CODE>; the installation prefix for executable files,</LI>
+
+ <LI><CODE>libdir</CODE>; the library installation directory,</LI>
+
+ <LI><CODE>mandir</CODE>; the man page installation directory,</LI>
+
+ <LI><CODE>prefix</CODE>; the installation prefix for non-executable files, and</LI>
+
+ <LI><CODE>srcdir</CODE>; the source directory.</LI>
+
+</UL>
+
+<H3>Standard Targets</H3>
+
+<P>The following standard targets must be defined in each
+makefile:</P>
+
+<UL>
+
+ <LI><CODE>all</CODE>; creates all target programs,
+ libraries, and documentation files,</LI>
+
+ <LI><CODE>clean</CODE>; removes all target programs,
+ libraries, documentation files, and object files,</LI>
+
+ <LI><CODE>depend</CODE>; generates automatic dependencies
+ for any C or C++ source files (also see <A
+ HREF="#DEPEND_TARGET">"Dependencies"</A>),</LI>
+
+ <LI><CODE>distclean</CODE>; removes autoconf-generated files
+ in addition to those removed by the "clean" target,</LI>
+
+ <LI><CODE>install</CODE>; installs all distribution files in
+ their corresponding locations (also see <A
+ HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), </LI>
+
+ <LI><CODE>uninstall</CODE>; removes all distribution files from
+ their corresponding locations (also see <A
+ HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), and</LI>
+
+</UL>
+
+
+<H3>Object Files</H3>
+
+<P>Object files (the result of compiling a C or C++ source file)
+have the extension ".o".</P>
+
+<H3>Programs</H3>
+
+<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>
+
+<PRE CLASS="command">
+program: $(OBJS)
+→ echo Linking $@...
+→ $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
+</PRE>
+
+<H3>Static Libraries</H3>
+
+<P>Static libraries have a prefix of "lib" and the extension
+".a". A typical static library target looks like:</P>
+
+<PRE CLASS="command">
+libname.a: $(OBJECTS)
+→ echo Creating $@...
+→ $(RM) $@
+→ $(AR) $(ARFLAGS) $@ $(OBJECTS)
+→ $(RANLIB) $@
+</PRE>
+
+<H3>Shared Libraries</H3>
+
+<P>Shared libraries have a prefix of "lib" and the extension
+".dylib", ".sl", ".so", or "_s.a" depending on the operating
+system. A typical shared library is composed of several targets
+that look like:</P>
+
+<PRE CLASS="command">
+libname.so: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
+→ $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
+→ $(RM) libname.so libname.so.$(DSOMAJOR)
+→ $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
+→ $(LN) libname.so.$(DSOVERSION) libname.so
+
+libname.sl: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname.sl.$(DSOVERSION) ...
+→ $(DSOCOMMAND) libname.sl.$(DSOVERSION) $(OBJECTS)
+→ $(RM) libname.sl libname.sl.$(DSOMAJOR)
+→ $(LN) libname.sl.$(DSOVERSION) libname.sl.$(DSOMAJOR)
+→ $(LN) libname.sl.$(DSOVERSION) libname.sl
+
+libname.dylib: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
+→ $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
+→ → -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
+→ → -current_version libname.$(DSOVERSION).dylib \
+→ → -compatibility_version $(DSOMAJOR).0 \
+→ → $(OBJECTS) $(LIBS)
+→ $(RM) libname.dylib
+→ $(RM) libname.$(DSOMAJOR).dylib
+→ $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
+→ $(LN) libname.$(DSOVERSION).dylib libname.dylib
+
+libname_s.a: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname_s.o ...
+→ $(DSOCOMMAND) libname_s.o $(OBJECTS) $(LIBS)
+→ echo $(LIBCOMMAND) libname_s.a libname_s.o
+→ $(RM) $@
+→ $(LIBCOMMAND) libname_s.a libname_s.o
+→ $(CHMOD) +x libname_s.a
+</PRE>
+
+
+<H3>Dependencies</H3>
+
+<P>Static dependencies are expressed in each makefile following the
+target, for example:</P>
+
+<PRE CLASS="command">
+foo: bar
+</PRE>
+
+<P>Static dependencies shall only be 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 shall be
+used to create the automatic dependencies:
+
+<PRE CLASS="command">
+depend:
+→ $(MAKEDEPEND) -Y -I.. -f Dependencies $(OBJS:.o=.c)
+</PRE>
+
+<P>We only regenerate the automatic dependencies on a Linux
+system and express any non-Linux dependencies statically in the
+makefile.</P>
+
+<H3><A NAME="TARGET_INSTALL">Install/Uninstall Support</A></H3>
+
+<P>All makefiles must contain 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>
+
+<P>The <CODE>$(INSTALL_BIN)</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>
+
+<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>
+
+</BODY>
+</HTML>
projects / thirdparty / cups.git / blobdiff