CUPS Developer Guide

This developer guide 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.

Communication

How to Contact the Developers

The CUPS Forums 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:

Table 1: CUPS Forums
Forum	Focus/Purpose
cups.bugs	Discussion of bugs and issues in the CUPS software
cups.commit	Report of all commits to the Subversion repository (read-only)
cups.ddk	Usage and development questions for the CUPS Driver Development Kit
cups.development	Development questions and discussion of new features in the CUPS software
cups.general	Usage questions for the CUPS software

How to Submit a Bug Report or Feature Request

The CUPS "Bugs & Features" page provides access to the CUPS software trouble report database and is the formal way to submit a bug report or feature request to the CUPS developers. Please note, however, that we do not provide answers to usage questions or resolve problems in third-party software on this page - use the CUPS Forums for that instead.

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.

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.

How to Prepare a Patch

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 trunk branch, which can be generated easily using the following Subversion command:

svn diff >filename.patch

If you produce a patch using a released source archive, use one of the following commands instead:

diff -u oldfilename filename >filename.patch

diff -urN olddirectory directory >filename.patch

New files and files with significant changes can be submitted in their entirety, however that may delay the adoption of your changes.

Patches and files must conform to the standards outlined in the "Coding Guidelines" and "Makefile Guidelines" 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.

Software Development Practices

Version Numbering

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.

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.

Production releases use the plain version numbers:

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

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.

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.

Beta-test releases are identified by appending the letter B to the major and minor version numbers followed by the beta release number:

MAJOR.MINORbNUMBER
1.2b1

Release candidates are identified by appending the letters RC to the major and minor version numbers followed by the release candidate number:

MAJOR.MINORrcNUMBER
1.2rc1

Developer snapshots are identified by appending the letters SVN-R to the major and minor version numbers followed by the revision number:

MAJOR.MINORsvn-rREV
1.2svn-r1234

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.

Version Control (Subversion)

The CUPS source files are managed by the Subversion ("SVN") software, available at:

subversion.tigris.org

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 must be used for commit log messages:

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

Primary development occurs on the trunk branch, with changes merged back to release branches as needed. Table 2 shows the URLs developers use for the various CUPS subprojects and branches:

Table 2: CUPS Subversion URLs
URL	Purpose
https://svn.easysw.com/public/cups/trunk/	Primary CUPS development branch
https://svn.easysw.com/public/cups/branches/	CUPS maintenance branches (merge-only)
https://svn.easysw.com/public/cups/tags/	CUPS release tags (read-only)
https://svn.easysw.com/public/cupsddk/trunk/	Primary CUPS DDK development branch
https://svn.easysw.com/public/cupsddk/branches/	CUPS DDK maintenance branches (merge-only)
https://svn.easysw.com/public/cupsddk/tags/	CUPS DDK release tags (read-only)
https://svn.easysw.com/public/espgs/trunk/	Primary ESP Ghostscript development branch
https://svn.easysw.com/public/espgs/branches/	ESP Ghostscript maintenance branches (merge-only)
https://svn.easysw.com/public/espgs/tags/	ESP Ghostscript release tags (read-only)
https://svn.easysw.com/public/windows/trunk/	Primary CUPS Windows Driver development branch
https://svn.easysw.com/public/windows/branches/	CUPS Windows Driver maintenance branches (merge-only)
https://svn.easysw.com/public/windows/tags/	CUPS Windows Driver release tags (read-only)

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.

Files and Directories

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.

Source files must be documented and formatted as described in "Coding Requirements". Make files must follow the guidelines in "Makefile Guidelines".

Build System

The CUPS build system uses GNU autoconf to tailor the library to the local operating system. Project files for major IDEs are also provided for Microsoft Windows^®. To improve portability, makefiles must not make use of the unique features offered by GNU make. See the Makefile Guidelines section for a description of the allowed make features and makefile guidelines.

Additional GNU build programs such as GNU automake and GNU libtool 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.

Packaging

Source packages are created using the tools/makesrcdist script in the Subversion repository. The script optionally uses a version number argument:

tools/makesrcdist
tools/makesrcdist version

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-version-source.tar.bz2" and "/tmp/cups-version-source.tar.gz".

Binary packages are not generally distributed by the CUPS team, however the packaging/cups.spec and packaging/cups.list files may be used to create binary packages on Linux, MacOS X, and UNIX. The packaging/cups.spec file produces a binary package using the rpmbuild(8) software:

rpmbuild -ta cups-version-source.tar.gz

The cups.list file is generated by the configure script and produces binary packages for many platforms using the EPM software. Table 3 shows the targets that are available for each type of binary package:

Table 3: Binary Package Targets
Target	Type of Package
aix	AIX installp
bsd	*BSD pkg_install
deb	Debian dpkg
depot	HP-UX swinstall
epm	Portable tarball with install script
inst	IRIX inst/tardist
osx	MacOS X Install
pkg	Solaris pkgadd
rpm	RPM binary
setld	Tru64 UNIX setld
slackware	Slackware install
swinstall	HP-UX swinstall
tardist	IRIX inst/tardist

Finally, the tools/testrpm and tools/testosx scripts can be used to create binary packages from the current working copy for testing on Linux and MacOS X, respectively:

tools/testrpm
sudo rpm -U /usr/src/redhat/RPMS/i386/cups*.rpm

sudo tools/testosx
open cups.pkg

Testing

Software testing is conducted according to the CUPS Software Test Plan. This testing is automated via the top-level makefile test target:

make test

The test environment allows for both short-term automated testing and long-term testing and development without the automated test script.

Trouble Report Processing

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 Bugs & Features page with one of the following states:

STR is closed with complete resolution
STR is closed without resolution
STR is active, waiting on information from submitter
STR is pending with additional information from submitter
STR is newly submitted

Trouble reports are processed using the following steps.

Classification
When a trouble report is received it must be classified at one of the following priority levels:
1. Request for enhancement, e.g. asking for a feature
2. Low, e.g. a documentation error or undocumented side-effect
3. Moderate, e.g. unable to print a file or unable to compile the software
4. High, e.g. unable to print to a printer or key functionality not working
5. Critical, e.g. unable to print at all
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.

The scope of the problem is also determined as:
1. Specific to a machine or printer
2. Specific to an operating system
3. Applies to all machines, printers, and operating systems
Identification
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.

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).
Correction
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.
Notification
The user or vendor is notified when the fix is available or if the problem was caused by user error.

Release Management

When testing has been completed successfully, a new source package is created using the tools/makesrcdist 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.

Table: CUPS Basic Release Schedule
Week	Version	Description
T-6 weeks	1.2b1	First beta release
T-5 weeks	1.2b2	Second beta release
T-3 weeks	1.2rc1	First release candidate
T-2 weeks	1.2rc2	Second release candidate
T-0 weeks	1.2.0	Production (feature) release

Coding Guidelines

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.

Source Files

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".

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:

/*
 * "$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.
 */

For source files that are subject to the Apple OS-Developed Software exception, the following additional comment should appear after the contact information:

 *   This file is subject to the Apple OS-Developed Software exception.

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:

/*
 * End of "$Id$".
 */

Functions

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.)

Functions with a local scope shall be declared "static" and be lowercase with underscores between words ("do_this", "do_that", "do_something_else", etc.)

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:

/*
 * '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);
}

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.

The Mini-XML documentation generator also understands the following special text in the function description comment:

@since CUPS version@ - Marks the function as new in the specified version of CUPS.
@deprecated@ - Marks the function as deprecated (not recommended for new development and scheduled for removal)

Variables

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.

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".

Each variable shall be declared on a separate line and shall be immediately followed by a comment block describing the variable:

int this_variable;   /* The current state of this */
int that_variable;   /* The current state of that */

Types

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.)

Each type shall have a comment block immediately after the typedef:

typedef int cups_this_type_t;           /* This type is for CUPS foobar options. */

Structures

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.)

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:

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 */
};

Constants

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.

Typed enumerations shall be used whenever possible to allow for type checking by the compiler.

Comment blocks shall immediately follow each constant:

enum
{
  CUPS_THIS_TRAY,                       /* This tray */
  CUPS_THAT_TRAY                        /* That tray */
};

Code

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:

/*
 * 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])));

Indentation

All code blocks enclosed by br/TD> CUPS Windows Driver release tags (read-only)