1 CONTRIBUTING.txt - 2016/01/28
2 -----------------------------
4 CUPS is developed by Apple Inc. and distributed as open source software under a
5 combination of GNU GPL2 and GNU LGPL2 licenses with exceptions to allow
6 developers on Apple's operating systems to develop CUPS-based software under
7 alternate license terms. Significant contributions to CUPS must be licensed to
8 Apple using the Apple Contributor Agreement:
10 https://www.cups.org/AppleContributorAgreement_2011-03-10.pdf
12 Contributions should be submitted as attachments to bug reports on the CUPS web
13 site. Changes to existing source files should be submitted as unified diffs
14 (both Subversion and Git produce this format by default) while new source files
15 should be provided as-is or in an archive.
18 HOW TO CONTACT THE DEVELOPERS
20 The CUPS mailing lists are the primary means of asking questions and informally
21 discussing issues and feature requests with the CUPS developers and other
22 experienced CUPS users and developers. The "cups" mailing list is intended for
23 CUPS usage questions and new software announcements while the "cups-devel"
24 mailing list provides a forum for CUPS developers and monitoring new bugs.
29 CUPS interfaces, including the C APIs and command-line arguments, environment
30 variables, configuration files, and output format, are stable across patch
31 versions and are generally backwards-compatible with interfaces used in prior
32 major and minor versions. However, program interfaces such as those used by
33 the scheduler to run filter, port monitor, and backend processes for job
34 processing should only be considered stable from the point of view of a
35 filter, port monitor, or backend. Software that simulates the scheduler in
36 order to run those programs outside of CUPS must necessarily be updated when
37 the corresponding interface is changed in a subsequent CUPS release, otherwise
38 undefined behavior can occur.
40 CUPS C APIs starting with an underscore (_) are considered to be private to
41 CUPS and are not subject to the normal guarantees of stability between CUPS
42 releases and must never be used in non-CUPS source code. Similarly,
43 configuration and state files written by CUPS are considered private if a
44 corresponding man page is not provided with the CUPS release. Never rely on
45 undocumented files or formats when developing software for CUPS. Always use a
46 published C API to access data stored in a file to avoid compatibility problems
52 The CUPS build system uses GNU autoconf to tailor the library to the local
53 operating system. Project files for the current release of Microsoft Visual
54 Studio are also provided for Microsoft Windows®. To improve portability,
55 makefiles must not make use of features unique to GNU make. See the MAKEFILE
56 GUIDELINES section for a description of the allowed make features and makefile
59 Additional GNU build programs such as GNU automake and GNU libtool must not be
60 used. GNU automake produces non-portable makefiles which depend on GNU-
61 specific extensions, and GNU libtool is not portable or reliable enough for
67 CUPS uses a three-part version number separated by periods to represent the
68 major, minor, and patch release numbers. Major release numbers indicate large
69 design changes or backwards-incompatible changes to the CUPS API or CUPS
70 Imaging API. Minor release numbers indicate new features and other smaller
71 changes which are backwards-compatible with previous CUPS releases. Patch
72 numbers indicate bug fixes to the previous feature or patch release.
76 When we talk about compatibility, we are talking about binary compatibility
77 for public APIs and output format compatibility for program interfaces.
78 Changes to configuration file formats or the default behavior of programs
79 are not generally considered incompatible as the upgrade process can
80 normally address such changes gracefully.
82 Production releases use the plain version numbers:
98 The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is called
99 a feature release. Feature releases are the only releases that may contain new
100 features. Subsequent production releases in a MAJOR.MINOR series may only
103 Beta-test releases are identified by appending the letter B to the major and
104 minor version numbers followed by the beta release number:
109 Release candidates are identified by appending the letters RC to the major and
110 minor version numbers followed by the release candidate number:
118 Contributed source code must follow the guidelines below. While the examples
119 are for C and C++ source files, source code for other languages should conform
120 to the same guidelines as allowed by the language.
125 All source files names must be 16 characters or less in length to ensure
126 compatibility with older UNIX filesystems. Source files containing functions
127 have an extension of ".c" for C and ".cxx" for C++ source files. All other
128 "include" files have an extension of ".h". Tabs are set to 8 characters or
133 The ".cxx" extension is used because it is the only common C++ extension
134 between Linux, OS X, UNIX, and Windows.
136 The top of each source file contains a header giving the purpose or nature of
137 the source file and the copyright and licensing notice:
140 * Description of file contents.
142 * Copyright 2016 by Apple Inc.
144 * These coded instructions, statements, and computer programs are the
145 * property of Apple Inc. and are protected by Federal copyright
146 * law. Distribution and use rights are outlined in the file "LICENSE.txt"
147 * which should have been included with this file. If this file is
148 * file is missing or damaged, see the license at "http://www.cups.org/".
151 For source files that are subject to the Apple OS-Developed Software exception,
152 the following additional comment appears after the contact information:
154 * This file is subject to the Apple OS-Developed Software exception.
159 All public header files must include the "versioning.h" header file, or a header
160 that does so. Function declarations are then "decorated" with the correct
161 _CUPS_API_major_minor macro to define its availability based on the build
162 environment, for example:
164 extern int cupsDoThis(int foo, int bar) _CUPS_API_2_2;
166 Private API header files must be named with the suffix "-private", for example
167 the "cups.h" header file defines all of the public CUPS APIs while the
168 "cups-private.h" header file defines all of the private CUPS APIs as well.
169 Typically a private API header file will include the corresponding public API
175 All source code utilizes block comments within functions to describe the
176 operations being performed by a group of statements; avoid putting a comment
177 per line unless absolutely necessary, and then consider refactoring the code
178 so that it is not necessary. C source files use the block comment format
179 ("/* comment */") since many vendor C compilers still do not support C99/C++
180 comments ("// comment"):
183 * Clear the state array before we begin...
186 for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
187 array[i] = CUPS_STATE_IDLE;
190 * Wait for state changes on another thread...
195 for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
196 if (array[i] != CUPS_STATE_IDLE)
199 if (i == (sizeof(array) / sizeof(array[0])))
201 } while (i == (sizeof(array) / sizeof(array[0])));
206 All code blocks enclosed by brackets begin with the opening brace on a new
207 line. The code then follows starting on a new line after the brace and is
208 indented 2 spaces. The closing brace is then placed on a new line following
209 the code at the original indentation:
212 int i; /* Looping var */
216 * Process foobar values from 0 to 999...
219 for (i = 0; i < 1000; i ++)
226 Single-line statements following "do", "else", "for", "if", and "while" are
227 indented 2 spaces as well. Blocks of code in a "switch" block are indented 4
228 spaces after each "case" and "default" case:
232 case CUPS_STATE_IDLE :
245 A space follows each reserved word such as "if", "while", etc. Spaces are not
246 inserted between a function name and the arguments in parenthesis.
251 Parenthesis surround values returned from a function:
253 return (CUPS_STATE_IDLE);
258 Functions with a global scope have a lowercase prefix followed by capitalized
259 words, e.g., "cupsDoThis", "cupsDoThat", "cupsDoSomethingElse", etc. Private
260 global functions begin with a leading underscore, e.g., "_cupsDoThis",
263 Functions with a local scope are declared "static" with lowercase names and
264 underscores between words, e.g., "do_this", "do_that", "do_something_else", etc.
266 Each function begins with a comment header describing what the function does,
267 the possible input limits (if any), the possible output values (if any), and
268 any special information needed:
271 * 'do_this()' - Compute y = this(x).
276 static float /* O - Inverse power value, 0.0 <= y <= 1.1 */
277 do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
283 Return/output values are indicated using an "O" prefix, input values are
284 indicated using the "I" prefix, and values that are both input and output use
285 the "IO" prefix for the corresponding in-line comment.
287 The Mini-XML documentation generator also understands the following special
288 text in the function description comment:
290 @deprecated@ - Marks the function as deprecated (not recommended
291 for new development and scheduled for removal)
292 @since CUPS version@ - Marks the function as new in the specified version
294 @private@ - Marks the function as private (same as starting the
295 function name with an underscore)
300 Variables with a global scope are capitalized, e.g., "ThisVariable",
301 "ThatVariable", "ThisStateVariable", etc. Globals in CUPS libraries are either
302 part of the per-thread global values managed by the "_cupsGlobals()" function
303 or are suitably protected for concurrent access. Global variables should be
304 replaced by function arguments whenever possible.
306 Variables with a local scope are lowercase with underscores between words,
307 e.g., "this_variable", "that_variable", etc. Any "local global" variables
308 shared by functions within a source file are declared "static". As for global
309 variables, local static variables are suitably protected for concurrent access.
311 Each variable is declared on a separate line and is immediately followed by a
312 comment block describing the variable:
314 int ThisVariable; /* The current state of this */
315 static int that_variable; /* The current state of that */
320 All type names are lowercase with underscores between words and "_t" appended
321 to the end of the name, e.g., "cups_this_type_t", "cups_that_type_t", etc.
322 Type names start with a prefix, typically "cups" or the name of the program,
323 to avoid conflicts with system types. Private type names start with an
324 underscore, e.g., "_cups_this_t", "_cups_that_t", etc.
326 Each type has a comment block immediately after the typedef:
328 typedef int cups_this_type_t; /* This type is for CUPS foobar options. */
333 All structure names are lowercase with underscores between words and "_s"
334 appended to the end of the name, e.g., "cups_this_s", "cups_that_s", etc.
335 Structure names start with a prefix, typically "cups" or the name of the
336 program, to avoid conflicts with system types. Private structure names start
337 with an underscore, e.g., "_cups_this_s", "_cups_that_s", etc.
339 Each structure has a comment block immediately after the struct and each member
340 is documented similar to the variable naming policy above:
342 struct cups_this_struct_s /* This structure is for CUPS foobar options. */
344 int this_member; /* Current state for this */
345 int that_member; /* Current state for that */
351 All constant names are uppercase with underscores between words, e.g.,
352 "CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc. Constants begin with an
353 uppercase prefix, typically "CUPS" or the program name. Private constants
354 start with an underscore, e.g., "_CUPS_THIS_CONSTANT", "_CUPS_THAT_CONSTANT",
357 Typed enumerations should be used whenever possible to allow for type checking
360 Comment blocks immediately follow each constant:
362 typedef enum cups_tray_e /* Tray enumerations */
364 CUPS_TRAY_THIS, /* This tray */
365 CUPS_TRAY_THAT /* That tray */
371 The following is a guide to the makefile-based build system used by CUPS.
372 These standards have been developed over the years to allow CUPS to be built on
373 as many systems and environments as possible.
378 The CUPS source code is organized functionally into a top-level makefile,
379 include file, and subdirectories each with their own makefile and dependencies
380 files. The ".in" files are template files for the autoconf software and are
381 used to generate a static version of the corresponding file.
384 MAKEFILE DOCUMENTATION
386 Each makefile starts with the standard CUPS header containing the description
387 of the file, and CUPS copyright and license notice:
392 # Copyright 2016 by Apple Inc.
394 # These coded instructions, statements, and computer programs are the
395 # property of Apple Inc. and are protected by Federal copyright
396 # law. Distribution and use rights are outlined in the file "LICENSE.txt"
397 # which should have been included with this file. If this file is
398 # file is missing or damaged, see the license at "http://www.cups.org/".
402 PORTABLE MAKEFILE CONSTRUCTION
404 CUPS uses a common subset of make program syntax to ensure that the software
405 can be compiled "out of the box" on as many systems as possible. The following
406 is a list of assumptions we follow when constructing makefiles:
408 - Targets; we assume that the make program supports the notion of simple
409 targets of the form "name:" that perform tab-indented commands that follow
413 <tab> target commands
415 - Dependencies; we assume that the make program supports recursive dependencies
419 <tab> target commands
430 - Variable Definition; we assume that the make program supports variable
431 definition on the command-line or in the makefile using the following form:
435 - Variable Substitution; we assume that the make program supports variable
436 substitution using the following forms:
438 - $(name); substitutes the value of "name",
439 - $(name:.old=.new); substitutes the value of "name" with the filename
440 extension ".old" changed to ".new",
441 - $(MAKEFLAGS); substitutes the command-line options passed to the
442 program without the leading hyphen (-),
443 - $$; substitutes a single $ character,
444 - $<; substitutes the current source file or dependency, and
445 - $@; substitutes the current target name.
447 - Suffixes; we assume that the make program supports filename suffixes with
448 assumed dependencies, e.g.:
452 <tab> $(CC) $(CFLAGS) -o $@ -c $<
454 - Include Files; we assume that the make program supports the include
460 - Comments; we assume that comments begin with a # character and proceed to the
461 end of the current line.
463 - Line Length; we assume that there is no practical limit to the length of
466 - Continuation of long lines; we assume that the \ character may be placed at
467 the end of a line to concatenate two or more lines in a makefile to form a
470 - Shell; we assume a POSIX-compatible shell is present on the build system.
475 The following variables are defined in the "Makedefs" file generated by the
478 - ALL_CFLAGS; the combined C compiler options,
479 - ALL_CXXFLAGS; the combined C++ compiler options,
480 - AMANDIR; the administrative man page installation directory (section 8/1m
481 depending on the platform),
482 - AR; the library archiver command,
483 - ARFLAGS; options for the library archiver command,
484 - AWK; the local awk command,
485 - BINDIR; the binary installation directory,
486 - BUILDROOT; optional installation prefix (defaults to DSTROOT),
487 - CC; the C compiler command,
488 - CFLAGS; options for the C compiler command,
489 - CHMOD; the chmod command,
490 - CXX; the C++ compiler command,
491 - CXXFLAGS; options for the C++ compiler command,
492 - DATADIR; the data file installation directory,
493 - DSO; the C shared library building command,
494 - DSOXX; the C++ shared library building command,
495 - DSOFLAGS; options for the shared library building command,
496 - INCLUDEDIR; the public header file installation directory,
497 - INSTALL; the install command,
498 - INSTALL_BIN; the program installation command,
499 - INSTALL_COMPDATA; the compressed data file installation command,
500 - INSTALL_CONFIG; the configuration file installation command,
501 - INSTALL_DATA; the data file installation command,
502 - INSTALL_DIR; the directory installation command,
503 - INSTALL_LIB; the library installation command,
504 - INSTALL_MAN; the documentation installation command,
505 - INSTALL_SCRIPT; the shell script installation command,
506 - LD; the linker command,
507 - LDFLAGS; options for the linker,
508 - LIBDIR; the library installation directory,
509 - LIBS; libraries for all programs,
510 - LN; the ln command,
511 - MAN1EXT; extension for man pages in section 1,
512 - MAN3EXT; extension for man pages in section 3,
513 - MAN5EXT; extension for man pages in section 5,
514 - MAN7EXT; extension for man pages in section 7,
515 - MAN8DIR; subdirectory for man pages in section 8,
516 - MAN8EXT; extension for man pages in section 8,
517 - MANDIR; the man page installation directory,
518 - OPTIM; common compiler optimization options,
519 - PRIVATEINCLUDE; the private header file installation directory,
520 - RM; the rm command,
521 - SHELL; the sh (POSIX shell) command,
522 - STRIP; the strip command,
523 - srcdir; the source directory.
528 The following standard targets are defined in each makefile:
530 - all; creates all target programs, libraries, and documentation files,
531 - clean; removes all target programs libraries, documentation files, and object
533 - depend; generates automatic dependencies for any C or C++ source files (also
535 - distclean; removes autoconf-generated files in addition to those removed by
537 - install; installs all distribution files in their corresponding locations
538 (also see "INSTALL/UNINSTALL SUPPORT"),
539 - install-data; installs all data files in their corresponding locations (also
540 see "INSTALL/UNINSTALL SUPPORT"),
541 - install-exec; installs all executable files in their corresponding locations
542 (also see "INSTALL/UNINSTALL SUPPORT"),
543 - install-headers; installs all include files in their corresponding locations
544 (also see "INSTALL/UNINSTALL SUPPORT"),
545 - install-libs; installs all library files in their corresponding locations
546 (also see "INSTALL/UNINSTALL SUPPORT"), and
547 - uninstall; removes all distribution files from their corresponding locations
548 (also see "INSTALL/UNINSTALL SUPPORT").
553 Object files (the result of compiling a C or C++ source file) have the
559 Program files are the result of linking object files and libraries together to
560 form an executable file. A typical program target looks like:
563 <tab> echo Linking $@...
564 <tab> $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
568 Static libraries have a prefix of "lib" and the extension ".a". A typical
569 static library target looks like:
571 libname.a: $(OBJECTS)
572 <tab> echo Creating $@...
574 <tab> $(AR) $(ARFLAGS) $@ $(OBJECTS)
579 Shared libraries have a prefix of "lib" and the extension ".dylib" or ".so"
580 depending on the operating system. A typical shared library is composed of
581 several targets that look like:
583 libname.so: $(OBJECTS)
584 <tab> echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
585 <tab> $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
586 <tab> $(RM) libname.so libname.so.$(DSOMAJOR)
587 <tab> $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
588 <tab> $(LN) libname.so.$(DSOVERSION) libname.so
590 libname.dylib: $(OBJECTS)
591 <tab> echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
592 <tab> $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
593 <tab> <tab> -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
594 <tab> <tab> -current_version libname.$(DSOVERSION).dylib \
595 <tab> <tab> -compatibility_version $(DSOMAJOR).0 \
596 <tab> <tab> $(OBJECTS) $(LIBS)
597 <tab> $(RM) libname.dylib
598 <tab> $(RM) libname.$(DSOMAJOR).dylib
599 <tab> $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
600 <tab> $(LN) libname.$(DSOVERSION).dylib libname.dylib
604 Static dependencies are expressed in each makefile following the target, for
609 Static dependencies are only used when it is not possible to automatically
610 generate them. Automatic dependencies are stored in a file named
611 "Dependencies" and included at the end of the makefile. The following "depend"
612 target rule is used to create the automatic dependencies:
615 <tab> $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies
617 We regenerate the automatic dependencies on an OS X system and express any
618 non-OS X dependencies statically in the makefile.
621 INSTALL/UNINSTALL SUPPORT
623 All makefiles contains install and uninstall rules which install or remove the
624 corresponding software. These rules must use the $(BUILDROOT) variable as a
625 prefix to any installation directory so that CUPS can be installed in a
626 temporary location for packaging by programs like rpmbuild.
628 The $(INSTALL_BIN), $(INSTALL_COMPDATA), $(INSTALL_CONFIG), $(INSTALL_DATA),
629 $(INSTALL_DIR), $(INSTALL_LIB), $(INSTALL_MAN), and $(INSTALL_SCRIPT) variables
630 must be used when installing files so that the proper ownership and permissions
631 are set on the installed files.
633 The $(RANLIB) command must be run on any static libraries after installation
634 since the symbol table is invalidated when the library is copied on some