-CONTRIBUTING.txt - 2016/01/28
------------------------------
+# Contributing to CUPS
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
Contributions should be submitted as attachments to bug reports on the CUPS web
site. Changes to existing source files should be submitted as unified diffs
(both Subversion and Git produce this format by default) while new source files
-should be provided as-is or in an archive.
+should be provided as-is or in an archive. Github pull requests can also be
+used to submit changes.
-HOW TO CONTACT THE DEVELOPERS
+## HOW TO CONTACT THE DEVELOPERS
The CUPS mailing lists are the primary means of asking questions and informally
discussing issues and feature requests with the CUPS developers and other
mailing list provides a forum for CUPS developers and monitoring new bugs.
-INTERFACES
+## INTERFACES
CUPS interfaces, including the C APIs and command-line arguments, environment
variables, configuration files, and output format, are stable across patch
in the future.
-BUILD SYSTEM
+## BUILD SYSTEM
The CUPS build system uses GNU autoconf to tailor the library to the local
operating system. Project files for the current release of Microsoft Visual
CUPS.
-VERSION NUMBERING
+## 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
changes which are backwards-compatible with previous CUPS releases. Patch
numbers indicate bug fixes to the previous feature or patch release.
- Note:
-
- 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.
+> Note:
+>
+> 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:
2.2rc1
-CODING GUIDELINES
+## CODING GUIDELINES
Contributed source code must follow the guidelines below. While the examples
are for C and C++ source files, source code for other languages should conform
to the same guidelines as allowed by the language.
-SOURCE FILES
+### SOURCE FILES
All source files names must be 16 characters or less in length to ensure
compatibility with older UNIX filesystems. Source files containing functions
"include" files have an extension of ".h". Tabs are set to 8 characters or
columns.
- Note:
-
- The ".cxx" extension is used because it is the only common C++ extension
- between Linux, OS X, UNIX, and Windows.
+> Note:
+>
+> The ".cxx" extension is used because it is the only common C++ extension
+> between Linux, OS X, UNIX, and Windows.
The top of each source file contains a header giving the purpose or nature of
the source file and the copyright and licensing notice:
* This file is subject to the Apple OS-Developed Software exception.
-HEADER FILES
+### HEADER FILES
All public header files must include the "versioning.h" header file, or a header
that does so. Function declarations are then "decorated" with the correct
header file.
-COMMENTS
+### COMMENTS
All source code utilizes block comments within functions to describe the
operations being performed by a group of statements; avoid putting a comment
} while (i == (sizeof(array) / sizeof(array[0])));
-INDENTATION
+### INDENTATION
All code blocks enclosed by brackets 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:
- {
- int i; /* Looping var */
-
+ {
+ int i; /* Looping var */
- /*
- * Process foobar values from 0 to 999...
- */
+ /*
+ * Process foobar values from 0 to 999...
+ */
- for (i = 0; i < 1000; i ++)
- {
- do_this(i);
- do_that(i);
+ for (i = 0; i < 1000; i ++)
+ {
+ do_this(i);
+ do_that(i);
+ }
}
- }
Single-line statements following "do", "else", "for", "if", and "while" are
indented 2 spaces as well. Blocks of code in a "switch" block are indented 4
}
-SPACING
+### SPACING
A space follows each reserved word such as "if", "while", etc. Spaces are not
inserted between a function name and the arguments in parenthesis.
-RETURN VALUES
+### RETURN VALUES
Parenthesis surround values returned from a function:
return (CUPS_STATE_IDLE);
-FUNCTIONS
+### FUNCTIONS
Functions with a global scope have a lowercase prefix followed by capitalized
words, e.g., "cupsDoThis", "cupsDoThat", "cupsDoSomethingElse", etc. Private
-global functions begin with a leading underscore, e.g., "_cupsDoThis",
-"_cupsDoThat", etc.
+global functions begin with a leading underscore, e.g., "\_cupsDoThis",
+"\_cupsDoThat", etc.
Functions with a local scope are declared "static" with lowercase names and
-underscores between words, e.g., "do_this", "do_that", "do_something_else", etc.
+underscores between words, e.g., "do\_this", "do\_that", "do\_something\_else", etc.
Each function begins with a comment header describing what the function does,
the possible input limits (if any), the possible output values (if any), and
function name with an underscore)
-VARIABLES
+### VARIABLES
Variables with a global scope are capitalized, e.g., "ThisVariable",
"ThatVariable", "ThisStateVariable", etc. Globals in CUPS libraries are either
-part of the per-thread global values managed by the "_cupsGlobals()" function
+part of the per-thread global values managed by the "\_cupsGlobals()" function
or are suitably protected for concurrent access. Global variables should be
replaced by function arguments whenever possible.
Variables with a local scope are lowercase with underscores between words,
-e.g., "this_variable", "that_variable", etc. Any "local global" variables
+e.g., "this\_variable", "that\_variable", etc. Any "local global" variables
shared by functions within a source file are declared "static". As for global
variables, local static variables are suitably protected for concurrent access.
static int that_variable; /* The current state of that */
-TYPES
+### TYPES
-All type names are lowercase with underscores between words and "_t" appended
-to the end of the name, e.g., "cups_this_type_t", "cups_that_type_t", etc.
+All type names are lowercase with underscores between words and "\_t" appended
+to the end of the name, e.g., "cups\_this\_type\_t", "cups\_that\_type\_t", etc.
Type names start with a prefix, typically "cups" or the name of the program,
to avoid conflicts with system types. Private type names start with an
-underscore, e.g., "_cups_this_t", "_cups_that_t", etc.
+underscore, e.g., "\_cups\_this\_t", "\_cups\_that\_t", etc.
Each type has a comment block immediately after the typedef:
typedef int cups_this_type_t; /* This type is for CUPS foobar options. */
-STRUCTURES
+### STRUCTURES
-All structure names are lowercase with underscores between words and "_s"
-appended to the end of the name, e.g., "cups_this_s", "cups_that_s", etc.
+All structure names are lowercase with underscores between words and "\_s"
+appended to the end of the name, e.g., "cups\_this\_s", "cups\_that\_s", etc.
Structure names start with a prefix, typically "cups" or the name of the
program, to avoid conflicts with system types. Private structure names start
-with an underscore, e.g., "_cups_this_s", "_cups_that_s", etc.
+with an underscore, e.g., "\_cups\_this\_s", "\_cups\_that\_s", etc.
Each structure has a comment block immediately after the struct and each member
is documented similar to the variable naming policy above:
};
-CONSTANTS
+### CONSTANTS
All constant names are uppercase with underscores between words, e.g.,
-"CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc. Constants begin with an
+"CUPS\_THIS\_CONSTANT", "CUPS\_THAT\_CONSTANT", etc. Constants begin with an
uppercase prefix, typically "CUPS" or the program name. Private constants
-start with an underscore, e.g., "_CUPS_THIS_CONSTANT", "_CUPS_THAT_CONSTANT",
+start with an underscore, e.g., "\_CUPS\_THIS\_CONSTANT", "\_CUPS\_THAT\_CONSTANT",
etc.
Typed enumerations should be used whenever possible to allow for type checking
} cups_tray_t;
-MAKEFILE GUIDELINES
+## MAKEFILE GUIDELINES
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.
-GENERAL ORGANIZATION
+### GENERAL ORGANIZATION
The CUPS source code is organized functionally into a top-level makefile,
include file, and subdirectories each with their own makefile and dependencies
used to generate a static version of the corresponding file.
-MAKEFILE DOCUMENTATION
+### MAKEFILE DOCUMENTATION
Each makefile starts with the standard CUPS header containing the description
of the file, and CUPS copyright and license notice:
#
-PORTABLE MAKEFILE CONSTRUCTION
+### PORTABLE MAKEFILE CONSTRUCTION
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
the target, e.g.:
target:
- <tab> target commands
+
+ _TAB_ target commands
- Dependencies; we assume that the make program supports recursive dependencies
on targets, e.g.:
target: foo bar
- <tab> target commands
+
+ _TAB_ target commands
foo: bla
- <tab> foo commands
+
+ _TAB_ foo commands
bar:
- <tab> bar commands
+
+ _TAB_ bar commands
bla:
- <tab> bla commands
+
+ _TAB_ bla commands
- Variable Definition; we assume that the make program supports variable
definition on the command-line or in the makefile using the following form:
assumed dependencies, e.g.:
.SUFFIXES: .c .o
+
.c.o:
- <tab> $(CC) $(CFLAGS) -o $@ -c $<
+
+ _TAB_ $(CC) $(CFLAGS) -o $@ -c $<
- Include Files; we assume that the make program supports the include
directive, e.g.:
include ../Makedefs
+
include Dependencies
- Comments; we assume that comments begin with a # character and proceed to the
- Shell; we assume a POSIX-compatible shell is present on the build system.
-STANDARD VARIABLES
+### STANDARD VARIABLES
The following variables are defined in the "Makedefs" file generated by the
autoconf software:
- srcdir; the source directory.
-STANDARD TARGETS
+### STANDARD TARGETS
The following standard targets are defined in each makefile:
(also see "INSTALL/UNINSTALL SUPPORT").
-OBJECT FILES
+### OBJECT FILES
Object files (the result of compiling a C or C++ source file) have the
extension ".o".
-PROGRAMS
+### PROGRAMS
Program files are the result of linking object files and libraries together to
form an executable file. A typical program target looks like:
program: $(OBJS)
- <tab> echo Linking $@...
- <tab> $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
+ TAB echo Linking $@...
+ TAB $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
-STATIC LIBRARIES
+### STATIC LIBRARIES
Static libraries have a prefix of "lib" and the extension ".a". A typical
static library target looks like:
libname.a: $(OBJECTS)
- <tab> echo Creating $@...
- <tab> $(RM) $@
- <tab> $(AR) $(ARFLAGS) $@ $(OBJECTS)
- <tab> $(RANLIB) $@
+ TAB echo Creating $@...
+ TAB $(RM) $@
+ TAB $(AR) $(ARFLAGS) $@ $(OBJECTS)
+ TAB $(RANLIB) $@
-SHARED LIBRARIES
+### SHARED LIBRARIES
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:
libname.so: $(OBJECTS)
- <tab> echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
- <tab> $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
- <tab> $(RM) libname.so libname.so.$(DSOMAJOR)
- <tab> $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
- <tab> $(LN) libname.so.$(DSOVERSION) libname.so
+ TAB echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
+ TAB $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
+ TAB $(RM) libname.so libname.so.$(DSOMAJOR)
+ TAB $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
+ TAB $(LN) libname.so.$(DSOVERSION) libname.so
libname.dylib: $(OBJECTS)
- <tab> echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
- <tab> $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
- <tab> <tab> -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
- <tab> <tab> -current_version libname.$(DSOVERSION).dylib \
- <tab> <tab> -compatibility_version $(DSOMAJOR).0 \
- <tab> <tab> $(OBJECTS) $(LIBS)
- <tab> $(RM) libname.dylib
- <tab> $(RM) libname.$(DSOMAJOR).dylib
- <tab> $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
- <tab> $(LN) libname.$(DSOVERSION).dylib libname.dylib
-
-DEPENDENCIES
+ TAB echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
+ TAB $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
+ TAB TAB -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
+ TAB TAB -current_version libname.$(DSOVERSION).dylib \
+ TAB TAB -compatibility_version $(DSOMAJOR).0 \
+ TAB TAB $(OBJECTS) $(LIBS)
+ TAB $(RM) libname.dylib
+ TAB $(RM) libname.$(DSOMAJOR).dylib
+ TAB $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
+ TAB $(LN) libname.$(DSOVERSION).dylib libname.dylib
+
+### DEPENDENCIES
Static dependencies are expressed in each makefile following the target, for
example:
target rule is used to create the automatic dependencies:
depend:
- <tab> $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies
+ TAB $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies
We regenerate the automatic dependencies on an OS X system and express any
non-OS X dependencies statically in the makefile.
-INSTALL/UNINSTALL SUPPORT
+### INSTALL/UNINSTALL SUPPORT
All makefiles contains install and uninstall rules which install or remove the
corresponding software. These rules must use the $(BUILDROOT) variable as a
prefix to any installation directory so that CUPS can be installed in a
temporary location for packaging by programs like rpmbuild.
-The $(INSTALL_BIN), $(INSTALL_COMPDATA), $(INSTALL_CONFIG), $(INSTALL_DATA),
-$(INSTALL_DIR), $(INSTALL_LIB), $(INSTALL_MAN), and $(INSTALL_SCRIPT) variables
+The $(INSTALL\_BIN), $(INSTALL\_COMPDATA), $(INSTALL\_CONFIG), $(INSTALL\_DATA),
+$(INSTALL\_DIR), $(INSTALL\_LIB), $(INSTALL\_MAN), and $(INSTALL\_SCRIPT) variables
must be used when installing files so that the proper ownership and permissions
are set on the installed files.
projects / thirdparty / cups.git / commitdiff
