-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE html>
<HTML>
<!-- SECTION: Specifications -->
<HEAD>
<P>This developer guide documents the guidelines and processes we use when developing and maintaining CUPS and related software. Our goal is to provide reliable and efficient software and documentation that addresses the needs of our users.</P>
+
<H2 CLASS="title"><A NAME="OVERVIEW">Overview</A></H2>
-<P>CUPS is developed by Apple Inc. and distributed as open source software under a combination of GNU GPL2 and GNU LGPL2 licenses with exceptions to allow linking to OpenSSL (which has a GPL-incompatible license) and for developers on Apple's operating systems to develop CUPS-based software until alternate license terms. Significant contributions to CUPS must be licensed to Apple using the <A HREF="http://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">Apple Contributor Agreement</A>.</P>
+<P>CUPS is developed by Apple Inc. and distributed as open source software under a combination of GNU GPL2 and GNU LGPL2 licenses with exceptions to allow linking to OpenSSL (which has a GPL-incompatible license) and for developers on Apple's operating systems to develop CUPS-based software until alternate license terms. Significant contributions to CUPS must be licensed to Apple using the <A HREF="https://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">Apple Contributor Agreement</A>.</P>
<P>Apple releases updates to the CUPS software approximately every three months. Each release has a version number consisting of the major version (currently 1), minor version (currently 6), and patch version (starting at 0) separated by the period, for example "1.6.0". Releases where only the patch version number changes will contain only bug fixes to the previous release, for example "1.6.1" includes bug fixes for the "1.6.0" release. New features require the major or minor version numbers to change, for example "1.6.0" release contains new features compared to the "1.5.3" release. Multiple beta and "candidate" releases generally precede each new feature release, for example "1.5b1", "1.5b2", and "1.5rc1" preceded the "1.5.0" release. Finally, we also post regular Subversion snapshot releases, for example "1.6svn-r10486", which represent a snapshot of the development for the next feature release.</P>
<H3><A NAME="CONTACT">How to Contact the Developers</A></H3>
-<P>The <A HREF="http://lists.cups.org/">CUPS Mailing Lists</A> are the primary means of asking questions and informally discussing issues and feature requests with the CUPS developers and other experienced CUPS users and developers. Table 1 shows the available mailing lists and their focus:</P>
-
-<DIV CLASS="table"><TABLE SUMMARY="CUPS Forums">
-<CAPTION>Table 1: CUPS Mailing Lists</CAPTION>
-<TR>
- <TH>List</TH>
- <TH>Focus/Purpose</TH>
-</TR>
-<TR>
- <TD>cups</TD>
- <TD>General discussion and usage questions for the CUPS software</TD>
-</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-dev</TD>
- <TD>Development questions and discussion of new features in the CUPS software</TD>
-</TR>
-</TABLE></DIV>
+<P>The <A HREF="https://www.cups.org/lists.php">CUPS.org mailing lists</A> are the primary means of asking questions and informally discussing issues and feature requests with the CUPS developers and other experienced CUPS users and developers. The <a href="https://www.cups.org/mailman/listinfo/cups">cups@cups.org</a> mailing list is intended for CUPS usage questions and new software announcements while the <a href="https://www.cups.org/mailman/listinfo/cups-devel">cups-devel@cups.org</a> mailing list provides a forum for CUPS developers and monitoring new bugs.</p>
<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> (STR) database and is the formal way to submit a bug report or feature request to the CUPS developers. Please note, however, that we <em>do not</em> provide answers to usage questions or resolve problems in third-party software on this page - use the <A HREF="#CONTACT">CUPS Mailing Lists</A> for that instead.</P>
+<P>The CUPS.org <A HREF="https://www.cups.org/str.php">Bugs</A> page provides access to the CUPS <em>Software Trouble Report</em> (STR) database and is the formal way to submit a bug report or feature request to the CUPS developers. Please note, however, that we <em>do not</em> provide answers to usage questions or resolve problems in third-party software on this page - use the <A HREF="#CONTACT">CUPS.org mailing lists</A> for that instead.</P>
-<P>Unlike discussions that occur on the CUPS Mailing Lists, formal bug reports and feature requests must be acted on by the CUPS developers. This does not mean that every bug report is resolved or every feature request is implemented, but we do respond and keep track of them all for posterity.</P>
+<P>Unlike discussions that occur on the CUPS.org mailing lists, formal bug reports and feature requests must be acted on by the CUPS developers. This does not mean that every bug report is resolved or every feature request is implemented, but we do respond and keep track of them all for posterity.</P>
-<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 and identifying popular issues.</BLOCKQUOTE>
+<BLOCKQUOTE><B>Note:</B>
+
+<P>Please use the search feature of the Bugs page before submitting a new bug report or feature request. If you see an existing report that matches your issue, please post a message to that report ("I have this issue as well", "I would also like to see", etc.) rather than submitting a new report. This helps speed the resolution of your issue by reducing the CUPS developers' work load and identifying popular issues.</P></BLOCKQUOTE>
<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>
+<P>When submitting a bug report or feature request, you can include patch files that resolve the bug or implement the feature to speed the inclusion of that bug fix or feature in a new CUPS release. For changes to existing files, we prefer a unified diff against the current GIT "master" branch, which can be generated easily using the following Git command:</P>
<PRE CLASS="command">
-svn diff >filename.patch
+git format-patch remotes/trunk >filename.patch
</PRE>
<P>If you produce a patch using a released source archive, use one of the following commands instead:</P>
<BLOCKQUOTE><B>Note:</B>
-<P>Patches and files must conform to the standards outlined in the "<A HREF="#CODING">Coding Guidelines</A>" and "<A HREF="#MAKEFILES">Makefile Guidelines</A>" sections in this document. In addition, since Apple Inc. provides CUPS under multiple licenses, we require that you <A HREF="http://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">license</A> significant changes and files to us for inclusion in CUPS. The CUPS developers will inform you if licensing is required.</P></BLOCKQUOTE>
+<P>Patches and files must conform to the standards outlined in the "<A HREF="#CODING">Coding Guidelines</A>" and "<A HREF="#MAKEFILES">Makefile Guidelines</A>" sections in this document. In addition, since Apple Inc. provides CUPS under multiple licenses, we require that you <A HREF="https://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">license</A> significant changes and files to us for inclusion in CUPS. The CUPS developers will inform you if licensing is required.</P></BLOCKQUOTE>
<H2 CLASS="title"><A NAME="PRACTICES">Software Development Practices</A></H2>
<A HREF="http://subversion.apache.org/" TARGET="_blank">subversion.apache.org</A>
</PRE>
+<p>A public read-only Git mirror is maintained for external developers. Details can be found on the CUPS.org <a href="https://www.cups.org/software.php">Software</a> page.</P>
+
<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">
Detailed list of 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 sub-projects 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.cups.org/public/cups/trunk/">https://svn.cups.org/public/cups/trunk/</A></TD>
- <TD>Primary CUPS development branch</TD>
-</TR>
-<TR>
- <TD><A HREF="http://svn.cups.org/public/cups/branches/">https://svn.cups.org/public/cups/branches/</A></TD>
- <TD>CUPS maintenance branches (merge-only)</TD>
-</TR>
-<TR>
- <TD><A HREF="http://svn.cups.org/public/cups/tags/">https://svn.cups.org/public/cups/tags/</A></TD>
- <TD>CUPS release tags (read-only)</TD>
-</TR>
-</TABLE></DIV>
+<P>Primary development occurs on the <var>trunk</var> branch, with changes merged back to release branches as needed.</P>
<P>The branch for a MAJOR.MINOR release are created when the first production release (MAJOR.MINOR.0) is made using the name "branch-MAJOR.MINOR". Release tags are created for every beta, candidate, and production release using the name "release-MAJOR.MINORbNUMBER", "release-MAJOR.MINORrcNUMBER", or "release-MAJOR.MINOR.PATCH", respectively. No release tags are created for developer snapshots.</P>
<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 the current release of
Visual C++ are also provided for Microsoft Windows<SUP>®</SUP>. To improve portability, makefiles must not make use of features unique to <A HREF="http://www.gnu.org/software/make/">GNU make</A>. See the <A HREF="#MAKEFILES">Makefile Guidelines</A> section for a description of the allowed make features and makefile guidelines.</P>
+<P>The CUPS build system uses <A HREF="http://www.gnu.org/software/autoconf/">GNU autoconf</A> to tailor the library to the local operating system. Project files for the current release of
Microsoft Visual Studio are also provided for Microsoft Windows<SUP>®</SUP>. To improve portability, makefiles must not make use of features unique to <A HREF="http://www.gnu.org/software/make/">GNU make</A>. See the <A HREF="#MAKEFILES">Makefile Guidelines</A> section for a description of the allowed make features and makefile guidelines.</P>
<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>
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.epmhome.org/" TARGET="_blank">EPM</A> software. Table 3 shows the targets that are available for each type of binary package:</P>
+<P>The <VAR>cups.list</VAR> file is generated by the <VAR>configure</VAR> script and produces binary packages for many platforms using the <A HREF="https://www.msweet.org/projects.php?Z2" TARGET="_blank">EPM</A> software. Table 3 shows the targets that are available for each type of binary package:</P>
<DIV CLASS="table"><TABLE SUMMARY="Binary Package Targets">
<CAPTION>Table 3: Binary Package Targets</CAPTION>
<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>
+<P>A Software Trouble Report ("STR") must be submitted every time a user or vendor experiences a problem with the CUPS software. Trouble reports are maintained on the <A HREF="https://www.cups.org/str.php" TARGET="_blank">Bugs</A> page with one of the following states:</P>
<OL>
</PRE>
+<H3>Header Files</H3>
+
+<P>All public header files must include the <var>versioning.h</var> header file, or a header that does so. Function declarations are then "decorated" with the correct <tt>_CUPS_API_major_minor</tt> macro to define its availability based on the build environment, for example:</p>
+
+<PRE CLASS="command">
+extern int cupsDoThis(int foo, int bar) _CUPS_API_2_0;
+</PRE>
+
+<P>Private API header files must be named with the suffix "-private", for example the <var>cups.h</var> header file defines all of the public CUPS APIs while the <var>cups-private.h</var> header file defines all of the private CUPS APIs as well. Typically a private API header file will include the corresponding public API header file.</P>
+
+
<H3>Comments</H3>
<P>All source code utilizes block comments within functions to describe the operations being performed by a group of statements; avoid putting a comment per line unless absolutely necessary, and then consider refactoring the code so that it is not necessary. C source files use the block comment format ("/* comment */") since many vendor C compilers still do not support C99/C++ comments ("// comment"):</P>
<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>
+<P>Shared libraries have a prefix of "lib" and the extension ".dylib" or ".so" depending on the operating system. A typical shared library is composed of several targets that look like:</P>
<PRE CLASS="command">
libname.so: $(OBJECTS)
→ $(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 \
→ $(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>
projects / thirdparty / cups.git / commitdiff
