|
Packit |
2fc92b |
# Contributing to CUPS
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
CUPS is developed by Apple Inc. and distributed as open source software under a
|
|
Packit |
2fc92b |
combination of GNU GPL2 and GNU LGPL2 licenses with exceptions to allow
|
|
Packit |
2fc92b |
developers on Apple's operating systems to develop CUPS-based software under
|
|
Packit |
2fc92b |
alternate license terms. Significant contributions to CUPS must be licensed to
|
|
Packit |
2fc92b |
Apple using the Apple Contributor Agreement:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
https://www.cups.org/AppleContributorAgreement_2011-03-10.pdf
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Contributions should be submitted as attachments to bug reports on the CUPS web
|
|
Packit |
2fc92b |
site. Changes to existing source files should be submitted as unified diffs
|
|
Packit |
2fc92b |
(both Subversion and Git produce this format by default) while new source files
|
|
Packit |
2fc92b |
should be provided as-is or in an archive. Github pull requests can also be
|
|
Packit |
2fc92b |
used to submit changes.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
## HOW TO CONTACT THE DEVELOPERS
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The CUPS mailing lists are the primary means of asking questions and informally
|
|
Packit |
2fc92b |
discussing issues and feature requests with the CUPS developers and other
|
|
Packit |
2fc92b |
experienced CUPS users and developers. The "cups" mailing list is intended for
|
|
Packit |
2fc92b |
CUPS usage questions and new software announcements while the "cups-devel"
|
|
Packit |
2fc92b |
mailing list provides a forum for CUPS developers and monitoring new bugs.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
## INTERFACES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
CUPS interfaces, including the C APIs and command-line arguments, environment
|
|
Packit |
2fc92b |
variables, configuration files, and output format, are stable across patch
|
|
Packit |
2fc92b |
versions and are generally backwards-compatible with interfaces used in prior
|
|
Packit |
2fc92b |
major and minor versions. However, program interfaces such as those used by
|
|
Packit |
2fc92b |
the scheduler to run filter, port monitor, and backend processes for job
|
|
Packit |
2fc92b |
processing should only be considered stable from the point of view of a
|
|
Packit |
2fc92b |
filter, port monitor, or backend. Software that simulates the scheduler in
|
|
Packit |
2fc92b |
order to run those programs outside of CUPS must necessarily be updated when
|
|
Packit |
2fc92b |
the corresponding interface is changed in a subsequent CUPS release, otherwise
|
|
Packit |
2fc92b |
undefined behavior can occur.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
CUPS C APIs starting with an underscore (_) are considered to be private to
|
|
Packit |
2fc92b |
CUPS and are not subject to the normal guarantees of stability between CUPS
|
|
Packit |
2fc92b |
releases and must never be used in non-CUPS source code. Similarly,
|
|
Packit |
2fc92b |
configuration and state files written by CUPS are considered private if a
|
|
Packit |
2fc92b |
corresponding man page is not provided with the CUPS release. Never rely on
|
|
Packit |
2fc92b |
undocumented files or formats when developing software for CUPS. Always use a
|
|
Packit |
2fc92b |
published C API to access data stored in a file to avoid compatibility problems
|
|
Packit |
2fc92b |
in the future.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
## BUILD SYSTEM
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The CUPS build system uses GNU autoconf to tailor the library to the local
|
|
Packit |
2fc92b |
operating system. Project files for the current release of Microsoft Visual
|
|
Packit |
2fc92b |
Studio are also provided for Microsoft Windows®. To improve portability,
|
|
Packit |
2fc92b |
makefiles must not make use of features unique to GNU make. See the MAKEFILE
|
|
Packit |
2fc92b |
GUIDELINES section for a description of the allowed make features and makefile
|
|
Packit |
2fc92b |
guidelines.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Additional GNU build programs such as GNU automake and GNU libtool must not be
|
|
Packit |
2fc92b |
used. GNU automake produces non-portable makefiles which depend on GNU-
|
|
Packit |
2fc92b |
specific extensions, and GNU libtool is not portable or reliable enough for
|
|
Packit |
2fc92b |
CUPS.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
## VERSION NUMBERING
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
CUPS uses a three-part version number separated by periods to represent the
|
|
Packit |
2fc92b |
major, minor, and patch release numbers. Major release numbers indicate large
|
|
Packit |
2fc92b |
design changes or backwards-incompatible changes to the CUPS API or CUPS
|
|
Packit |
2fc92b |
Imaging API. Minor release numbers indicate new features and other smaller
|
|
Packit |
2fc92b |
changes which are backwards-compatible with previous CUPS releases. Patch
|
|
Packit |
2fc92b |
numbers indicate bug fixes to the previous feature or patch release.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
> Note:
|
|
Packit |
2fc92b |
>
|
|
Packit |
2fc92b |
> When we talk about compatibility, we are talking about binary compatibility
|
|
Packit |
2fc92b |
> for public APIs and output format compatibility for program interfaces.
|
|
Packit |
2fc92b |
> Changes to configuration file formats or the default behavior of programs
|
|
Packit |
2fc92b |
> are not generally considered incompatible as the upgrade process can
|
|
Packit |
2fc92b |
> normally address such changes gracefully.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Production releases use the plain version numbers:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
MAJOR.MINOR.PATCH
|
|
Packit |
2fc92b |
1.0.0
|
|
Packit |
2fc92b |
...
|
|
Packit |
2fc92b |
1.1.0
|
|
Packit |
2fc92b |
...
|
|
Packit |
2fc92b |
1.1.23
|
|
Packit |
2fc92b |
...
|
|
Packit |
2fc92b |
2.0.0
|
|
Packit |
2fc92b |
...
|
|
Packit |
2fc92b |
2.1.0
|
|
Packit |
2fc92b |
2.1.1
|
|
Packit |
2fc92b |
2.1.2
|
|
Packit |
2fc92b |
2.1.3
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is called
|
|
Packit |
2fc92b |
a feature release. Feature releases are the only releases that may contain new
|
|
Packit |
2fc92b |
features. Subsequent production releases in a MAJOR.MINOR series may only
|
|
Packit |
2fc92b |
contain bug fixes.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Beta-test releases are identified by appending the letter B to the major and
|
|
Packit |
2fc92b |
minor version numbers followed by the beta release number:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
MAJOR.MINORbNUMBER
|
|
Packit |
2fc92b |
2.2b1
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Release candidates are identified by appending the letters RC to the major and
|
|
Packit |
2fc92b |
minor version numbers followed by the release candidate number:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
MAJOR.MINORrcNUMBER
|
|
Packit |
2fc92b |
2.2rc1
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
## CODING GUIDELINES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Contributed source code must follow the guidelines below. While the examples
|
|
Packit |
2fc92b |
are for C and C++ source files, source code for other languages should conform
|
|
Packit |
2fc92b |
to the same guidelines as allowed by the language.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### SOURCE FILES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All source files names must be 16 characters or less in length to ensure
|
|
Packit |
2fc92b |
compatibility with older UNIX filesystems. Source files containing functions
|
|
Packit |
2fc92b |
have an extension of ".c" for C and ".cxx" for C++ source files. All other
|
|
Packit |
2fc92b |
"include" files have an extension of ".h". Tabs are set to 8 characters or
|
|
Packit |
2fc92b |
columns.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
> Note:
|
|
Packit |
2fc92b |
>
|
|
Packit |
2fc92b |
> The ".cxx" extension is used because it is the only common C++ extension
|
|
Packit |
2fc92b |
> between Linux, macOS, UNIX, and Windows.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The top of each source file contains a header giving the purpose or nature of
|
|
Packit |
2fc92b |
the source file and the copyright and licensing notice:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
/*
|
|
Packit |
2fc92b |
* Description of file contents.
|
|
Packit |
2fc92b |
*
|
|
Packit |
2fc92b |
* Copyright 2016 by Apple Inc.
|
|
Packit |
2fc92b |
*
|
|
Packit |
2fc92b |
* These coded instructions, statements, and computer programs are the
|
|
Packit |
2fc92b |
* property of Apple Inc. and are protected by Federal copyright
|
|
Packit |
2fc92b |
* law. Distribution and use rights are outlined in the file "LICENSE.txt"
|
|
Packit |
2fc92b |
* which should have been included with this file. If this file is
|
|
Packit |
2fc92b |
* file is missing or damaged, see the license at "http://www.cups.org/".
|
|
Packit |
2fc92b |
*/
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
For source files that are subject to the Apple OS-Developed Software exception,
|
|
Packit |
2fc92b |
the following additional comment appears after the contact information:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
* This file is subject to the Apple OS-Developed Software exception.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### HEADER FILES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All public header files must include the "versioning.h" header file, or a header
|
|
Packit |
2fc92b |
that does so. Function declarations are then "decorated" with the correct
|
|
Packit |
2fc92b |
_CUPS_API_major_minor macro to define its availability based on the build
|
|
Packit |
2fc92b |
environment, for example:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
extern int cupsDoThis(int foo, int bar) _CUPS_API_2_2;
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Private API header files must be named with the suffix "-private", for example
|
|
Packit |
2fc92b |
the "cups.h" header file defines all of the public CUPS APIs while the
|
|
Packit |
2fc92b |
"cups-private.h" header file defines all of the private CUPS APIs as well.
|
|
Packit |
2fc92b |
Typically a private API header file will include the corresponding public API
|
|
Packit |
2fc92b |
header file.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### COMMENTS
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All source code utilizes block comments within functions to describe the
|
|
Packit |
2fc92b |
operations being performed by a group of statements; avoid putting a comment
|
|
Packit |
2fc92b |
per line unless absolutely necessary, and then consider refactoring the code
|
|
Packit |
2fc92b |
so that it is not necessary. C source files use the block comment format
|
|
Packit |
2fc92b |
("/* comment */") since many vendor C compilers still do not support C99/C++
|
|
Packit |
2fc92b |
comments ("// comment"):
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
/*
|
|
Packit |
2fc92b |
* Clear the state array before we begin...
|
|
Packit |
2fc92b |
*/
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
|
|
Packit |
2fc92b |
array[i] = CUPS_STATE_IDLE;
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
/*
|
|
Packit |
2fc92b |
* Wait for state changes on another thread...
|
|
Packit |
2fc92b |
*/
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
do
|
|
Packit |
2fc92b |
{
|
|
Packit |
2fc92b |
for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
|
|
Packit |
2fc92b |
if (array[i] != CUPS_STATE_IDLE)
|
|
Packit |
2fc92b |
break;
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
if (i == (sizeof(array) / sizeof(array[0])))
|
|
Packit |
2fc92b |
sleep(1);
|
|
Packit |
2fc92b |
} while (i == (sizeof(array) / sizeof(array[0])));
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### INDENTATION
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All code blocks enclosed by brackets begin with the opening brace on a new
|
|
Packit |
2fc92b |
line. The code then follows starting on a new line after the brace and is
|
|
Packit |
2fc92b |
indented 2 spaces. The closing brace is then placed on a new line following
|
|
Packit |
2fc92b |
the code at the original indentation:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
{
|
|
Packit |
2fc92b |
int i; /* Looping var */
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
/*
|
|
Packit |
2fc92b |
* Process foobar values from 0 to 999...
|
|
Packit |
2fc92b |
*/
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
for (i = 0; i < 1000; i ++)
|
|
Packit |
2fc92b |
{
|
|
Packit |
2fc92b |
do_this(i);
|
|
Packit |
2fc92b |
do_that(i);
|
|
Packit |
2fc92b |
}
|
|
Packit |
2fc92b |
}
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Single-line statements following "do", "else", "for", "if", and "while" are
|
|
Packit |
2fc92b |
indented 2 spaces as well. Blocks of code in a "switch" block are indented 4
|
|
Packit |
2fc92b |
spaces after each "case" and "default" case:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
switch (array[i])
|
|
Packit |
2fc92b |
{
|
|
Packit |
2fc92b |
case CUPS_STATE_IDLE :
|
|
Packit |
2fc92b |
do_this(i);
|
|
Packit |
2fc92b |
do_that(i);
|
|
Packit |
2fc92b |
break;
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
default :
|
|
Packit |
2fc92b |
do_nothing(i);
|
|
Packit |
2fc92b |
break;
|
|
Packit |
2fc92b |
}
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### SPACING
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
A space follows each reserved word such as "if", "while", etc. Spaces are not
|
|
Packit |
2fc92b |
inserted between a function name and the arguments in parenthesis.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### RETURN VALUES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Parenthesis surround values returned from a function:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
return (CUPS_STATE_IDLE);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### FUNCTIONS
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Functions with a global scope have a lowercase prefix followed by capitalized
|
|
Packit |
2fc92b |
words, e.g., "cupsDoThis", "cupsDoThat", "cupsDoSomethingElse", etc. Private
|
|
Packit |
2fc92b |
global functions begin with a leading underscore, e.g., "\_cupsDoThis",
|
|
Packit |
2fc92b |
"\_cupsDoThat", etc.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Functions with a local scope are declared "static" with lowercase names and
|
|
Packit |
2fc92b |
underscores between words, e.g., "do\_this", "do\_that", "do\_something\_else", etc.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Each function begins with a comment header describing what the function does,
|
|
Packit |
2fc92b |
the possible input limits (if any), the possible output values (if any), and
|
|
Packit |
2fc92b |
any special information needed:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
/*
|
|
Packit |
2fc92b |
* 'do_this()' - Compute y = this(x).
|
|
Packit |
2fc92b |
*
|
|
Packit |
2fc92b |
* Notes: none.
|
|
Packit |
2fc92b |
*/
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
static float /* O - Inverse power value, 0.0 <= y <= 1.1 */
|
|
Packit |
2fc92b |
do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
|
|
Packit |
2fc92b |
{
|
|
Packit |
2fc92b |
...
|
|
Packit |
2fc92b |
return (y);
|
|
Packit |
2fc92b |
}
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Return/output values are indicated using an "O" prefix, input values are
|
|
Packit |
2fc92b |
indicated using the "I" prefix, and values that are both input and output use
|
|
Packit |
2fc92b |
the "IO" prefix for the corresponding in-line comment.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The Mini-XML documentation generator also understands the following special
|
|
Packit |
2fc92b |
text in the function description comment:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
@deprecated@ - Marks the function as deprecated (not recommended
|
|
Packit |
2fc92b |
for new development and scheduled for removal)
|
|
Packit |
2fc92b |
@since CUPS version@ - Marks the function as new in the specified version
|
|
Packit |
2fc92b |
of CUPS.
|
|
Packit |
2fc92b |
@private@ - Marks the function as private (same as starting the
|
|
Packit |
2fc92b |
function name with an underscore)
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### VARIABLES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Variables with a global scope are capitalized, e.g., "ThisVariable",
|
|
Packit |
2fc92b |
"ThatVariable", "ThisStateVariable", etc. Globals in CUPS libraries are either
|
|
Packit |
2fc92b |
part of the per-thread global values managed by the "\_cupsGlobals()" function
|
|
Packit |
2fc92b |
or are suitably protected for concurrent access. Global variables should be
|
|
Packit |
2fc92b |
replaced by function arguments whenever possible.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Variables with a local scope are lowercase with underscores between words,
|
|
Packit |
2fc92b |
e.g., "this\_variable", "that\_variable", etc. Any "local global" variables
|
|
Packit |
2fc92b |
shared by functions within a source file are declared "static". As for global
|
|
Packit |
2fc92b |
variables, local static variables are suitably protected for concurrent access.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Each variable is declared on a separate line and is immediately followed by a
|
|
Packit |
2fc92b |
comment block describing the variable:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
int ThisVariable; /* The current state of this */
|
|
Packit |
2fc92b |
static int that_variable; /* The current state of that */
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### TYPES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All type names are lowercase with underscores between words and "\_t" appended
|
|
Packit |
2fc92b |
to the end of the name, e.g., "cups\_this\_type\_t", "cups\_that\_type\_t", etc.
|
|
Packit |
2fc92b |
Type names start with a prefix, typically "cups" or the name of the program,
|
|
Packit |
2fc92b |
to avoid conflicts with system types. Private type names start with an
|
|
Packit |
2fc92b |
underscore, e.g., "\_cups\_this\_t", "\_cups\_that\_t", etc.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Each type has a comment block immediately after the typedef:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
typedef int cups_this_type_t; /* This type is for CUPS foobar options. */
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### STRUCTURES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All structure names are lowercase with underscores between words and "\_s"
|
|
Packit |
2fc92b |
appended to the end of the name, e.g., "cups\_this\_s", "cups\_that\_s", etc.
|
|
Packit |
2fc92b |
Structure names start with a prefix, typically "cups" or the name of the
|
|
Packit |
2fc92b |
program, to avoid conflicts with system types. Private structure names start
|
|
Packit |
2fc92b |
with an underscore, e.g., "\_cups\_this\_s", "\_cups\_that\_s", etc.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Each structure has a comment block immediately after the struct and each member
|
|
Packit |
2fc92b |
is documented similar to the variable naming policy above:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
struct cups_this_struct_s /* This structure is for CUPS foobar options. */
|
|
Packit |
2fc92b |
{
|
|
Packit |
2fc92b |
int this_member; /* Current state for this */
|
|
Packit |
2fc92b |
int that_member; /* Current state for that */
|
|
Packit |
2fc92b |
};
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### CONSTANTS
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All constant names are uppercase with underscores between words, e.g.,
|
|
Packit |
2fc92b |
"CUPS\_THIS\_CONSTANT", "CUPS\_THAT\_CONSTANT", etc. Constants begin with an
|
|
Packit |
2fc92b |
uppercase prefix, typically "CUPS" or the program name. Private constants
|
|
Packit |
2fc92b |
start with an underscore, e.g., "\_CUPS\_THIS\_CONSTANT", "\_CUPS\_THAT\_CONSTANT",
|
|
Packit |
2fc92b |
etc.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Typed enumerations should be used whenever possible to allow for type checking
|
|
Packit |
2fc92b |
by the compiler.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Comment blocks immediately follow each constant:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
typedef enum cups_tray_e /* Tray enumerations */
|
|
Packit |
2fc92b |
{
|
|
Packit |
2fc92b |
CUPS_TRAY_THIS, /* This tray */
|
|
Packit |
2fc92b |
CUPS_TRAY_THAT /* That tray */
|
|
Packit |
2fc92b |
} cups_tray_t;
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
## MAKEFILE GUIDELINES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The following is a guide to the makefile-based build system used by CUPS.
|
|
Packit |
2fc92b |
These standards have been developed over the years to allow CUPS to be built on
|
|
Packit |
2fc92b |
as many systems and environments as possible.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### GENERAL ORGANIZATION
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The CUPS source code is organized functionally into a top-level makefile,
|
|
Packit |
2fc92b |
include file, and subdirectories each with their own makefile and dependencies
|
|
Packit |
2fc92b |
files. The ".in" files are template files for the autoconf software and are
|
|
Packit |
2fc92b |
used to generate a static version of the corresponding file.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### MAKEFILE DOCUMENTATION
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Each makefile starts with the standard CUPS header containing the description
|
|
Packit |
2fc92b |
of the file, and CUPS copyright and license notice:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
#
|
|
Packit |
2fc92b |
# Makefile for ...
|
|
Packit |
2fc92b |
#
|
|
Packit |
2fc92b |
# Copyright 2016 by Apple Inc.
|
|
Packit |
2fc92b |
#
|
|
Packit |
2fc92b |
# These coded instructions, statements, and computer programs are the
|
|
Packit |
2fc92b |
# property of Apple Inc. and are protected by Federal copyright
|
|
Packit |
2fc92b |
# law. Distribution and use rights are outlined in the file "LICENSE.txt"
|
|
Packit |
2fc92b |
# which should have been included with this file. If this file is
|
|
Packit |
2fc92b |
# file is missing or damaged, see the license at "http://www.cups.org/".
|
|
Packit |
2fc92b |
#
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### PORTABLE MAKEFILE CONSTRUCTION
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
CUPS uses a common subset of make program syntax to ensure that the software
|
|
Packit |
2fc92b |
can be compiled "out of the box" on as many systems as possible. The following
|
|
Packit |
2fc92b |
is a list of assumptions we follow when constructing makefiles:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Targets; we assume that the make program supports the notion of simple
|
|
Packit |
2fc92b |
targets of the form "name:" that perform tab-indented commands that follow
|
|
Packit |
2fc92b |
the target, e.g.:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
target:
|
|
Packit |
2fc92b |
TAB target commands
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Dependencies; we assume that the make program supports recursive dependencies
|
|
Packit |
2fc92b |
on targets, e.g.:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
target: foo bar
|
|
Packit |
2fc92b |
TAB target commands
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
foo: bla
|
|
Packit |
2fc92b |
TAB foo commands
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
bar:
|
|
Packit |
2fc92b |
TAB bar commands
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
bla:
|
|
Packit |
2fc92b |
TAB bla commands
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Variable Definition; we assume that the make program supports variable
|
|
Packit |
2fc92b |
definition on the command-line or in the makefile using the following form:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
name=value
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Variable Substitution; we assume that the make program supports variable
|
|
Packit |
2fc92b |
substitution using the following forms:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- $(name); substitutes the value of "name",
|
|
Packit |
2fc92b |
- $(name:.old=.new); substitutes the value of "name" with the filename
|
|
Packit |
2fc92b |
extension ".old" changed to ".new",
|
|
Packit |
2fc92b |
- $(MAKEFLAGS); substitutes the command-line options passed to the
|
|
Packit |
2fc92b |
program without the leading hyphen (-),
|
|
Packit |
2fc92b |
- $$; substitutes a single $ character,
|
|
Packit |
2fc92b |
- $<; substitutes the current source file or dependency, and
|
|
Packit |
2fc92b |
- $@; substitutes the current target name.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Suffixes; we assume that the make program supports filename suffixes with
|
|
Packit |
2fc92b |
assumed dependencies, e.g.:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
.SUFFIXES: .c .o
|
|
Packit |
2fc92b |
.c.o:
|
|
Packit |
2fc92b |
TAB $(CC) $(CFLAGS) -o $@ -c $<
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Include Files; we assume that the make program supports the include
|
|
Packit |
2fc92b |
directive, e.g.:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
include ../Makedefs
|
|
Packit |
2fc92b |
include Dependencies
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Comments; we assume that comments begin with a # character and proceed to the
|
|
Packit |
2fc92b |
end of the current line.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Line Length; we assume that there is no practical limit to the length of
|
|
Packit |
2fc92b |
lines.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Continuation of long lines; we assume that the \ character may be placed at
|
|
Packit |
2fc92b |
the end of a line to concatenate two or more lines in a makefile to form a
|
|
Packit |
2fc92b |
single long line.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- Shell; we assume a POSIX-compatible shell is present on the build system.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### STANDARD VARIABLES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The following variables are defined in the "Makedefs" file generated by the
|
|
Packit |
2fc92b |
autoconf software:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- ALL_CFLAGS; the combined C compiler options,
|
|
Packit |
2fc92b |
- ALL_CXXFLAGS; the combined C++ compiler options,
|
|
Packit |
2fc92b |
- AMANDIR; the administrative man page installation directory (section 8/1m
|
|
Packit |
2fc92b |
depending on the platform),
|
|
Packit |
2fc92b |
- AR; the library archiver command,
|
|
Packit |
2fc92b |
- ARFLAGS; options for the library archiver command,
|
|
Packit |
2fc92b |
- AWK; the local awk command,
|
|
Packit |
2fc92b |
- BINDIR; the binary installation directory,
|
|
Packit |
2fc92b |
- BUILDROOT; optional installation prefix (defaults to DSTROOT),
|
|
Packit |
2fc92b |
- CC; the C compiler command,
|
|
Packit |
2fc92b |
- CFLAGS; options for the C compiler command,
|
|
Packit |
2fc92b |
- CHMOD; the chmod command,
|
|
Packit |
2fc92b |
- CXX; the C++ compiler command,
|
|
Packit |
2fc92b |
- CXXFLAGS; options for the C++ compiler command,
|
|
Packit |
2fc92b |
- DATADIR; the data file installation directory,
|
|
Packit |
2fc92b |
- DSO; the C shared library building command,
|
|
Packit |
2fc92b |
- DSOXX; the C++ shared library building command,
|
|
Packit |
2fc92b |
- DSOFLAGS; options for the shared library building command,
|
|
Packit |
2fc92b |
- INCLUDEDIR; the public header file installation directory,
|
|
Packit |
2fc92b |
- INSTALL; the install command,
|
|
Packit |
2fc92b |
- INSTALL_BIN; the program installation command,
|
|
Packit |
2fc92b |
- INSTALL_COMPDATA; the compressed data file installation command,
|
|
Packit |
2fc92b |
- INSTALL_CONFIG; the configuration file installation command,
|
|
Packit |
2fc92b |
- INSTALL_DATA; the data file installation command,
|
|
Packit |
2fc92b |
- INSTALL_DIR; the directory installation command,
|
|
Packit |
2fc92b |
- INSTALL_LIB; the library installation command,
|
|
Packit |
2fc92b |
- INSTALL_MAN; the documentation installation command,
|
|
Packit |
2fc92b |
- INSTALL_SCRIPT; the shell script installation command,
|
|
Packit |
2fc92b |
- LD; the linker command,
|
|
Packit |
2fc92b |
- LDFLAGS; options for the linker,
|
|
Packit |
2fc92b |
- LIBDIR; the library installation directory,
|
|
Packit |
2fc92b |
- LIBS; libraries for all programs,
|
|
Packit |
2fc92b |
- LN; the ln command,
|
|
Packit |
2fc92b |
- MAN1EXT; extension for man pages in section 1,
|
|
Packit |
2fc92b |
- MAN3EXT; extension for man pages in section 3,
|
|
Packit |
2fc92b |
- MAN5EXT; extension for man pages in section 5,
|
|
Packit |
2fc92b |
- MAN7EXT; extension for man pages in section 7,
|
|
Packit |
2fc92b |
- MAN8DIR; subdirectory for man pages in section 8,
|
|
Packit |
2fc92b |
- MAN8EXT; extension for man pages in section 8,
|
|
Packit |
2fc92b |
- MANDIR; the man page installation directory,
|
|
Packit |
2fc92b |
- OPTIM; common compiler optimization options,
|
|
Packit |
2fc92b |
- PRIVATEINCLUDE; the private header file installation directory,
|
|
Packit |
2fc92b |
- RM; the rm command,
|
|
Packit |
2fc92b |
- SHELL; the sh (POSIX shell) command,
|
|
Packit |
2fc92b |
- STRIP; the strip command,
|
|
Packit |
2fc92b |
- srcdir; the source directory.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### STANDARD TARGETS
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The following standard targets are defined in each makefile:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
- all; creates all target programs, libraries, and documentation files,
|
|
Packit |
2fc92b |
- clean; removes all target programs libraries, documentation files, and object
|
|
Packit |
2fc92b |
files,
|
|
Packit |
2fc92b |
- depend; generates automatic dependencies for any C or C++ source files (also
|
|
Packit |
2fc92b |
see "DEPENDENCIES"),
|
|
Packit |
2fc92b |
- distclean; removes autoconf-generated files in addition to those removed by
|
|
Packit |
2fc92b |
the "clean" target,
|
|
Packit |
2fc92b |
- install; installs all distribution files in their corresponding locations
|
|
Packit |
2fc92b |
(also see "INSTALL/UNINSTALL SUPPORT"),
|
|
Packit |
2fc92b |
- install-data; installs all data files in their corresponding locations (also
|
|
Packit |
2fc92b |
see "INSTALL/UNINSTALL SUPPORT"),
|
|
Packit |
2fc92b |
- install-exec; installs all executable files in their corresponding locations
|
|
Packit |
2fc92b |
(also see "INSTALL/UNINSTALL SUPPORT"),
|
|
Packit |
2fc92b |
- install-headers; installs all include files in their corresponding locations
|
|
Packit |
2fc92b |
(also see "INSTALL/UNINSTALL SUPPORT"),
|
|
Packit |
2fc92b |
- install-libs; installs all library files in their corresponding locations
|
|
Packit |
2fc92b |
(also see "INSTALL/UNINSTALL SUPPORT"), and
|
|
Packit |
2fc92b |
- uninstall; removes all distribution files from their corresponding locations
|
|
Packit |
2fc92b |
(also see "INSTALL/UNINSTALL SUPPORT").
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### OBJECT FILES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Object files (the result of compiling a C or C++ source file) have the
|
|
Packit |
2fc92b |
extension ".o".
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### PROGRAMS
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Program files are the result of linking object files and libraries together to
|
|
Packit |
2fc92b |
form an executable file. A typical program target looks like:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
program: $(OBJS)
|
|
Packit |
2fc92b |
TAB echo Linking $@...
|
|
Packit |
2fc92b |
TAB $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### STATIC LIBRARIES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Static libraries have a prefix of "lib" and the extension ".a". A typical
|
|
Packit |
2fc92b |
static library target looks like:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
libname.a: $(OBJECTS)
|
|
Packit |
2fc92b |
TAB echo Creating $@...
|
|
Packit |
2fc92b |
TAB $(RM) $@
|
|
Packit |
2fc92b |
TAB $(AR) $(ARFLAGS) $@ $(OBJECTS)
|
|
Packit |
2fc92b |
TAB $(RANLIB) $@
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### SHARED LIBRARIES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Shared libraries have a prefix of "lib" and the extension ".dylib" or ".so"
|
|
Packit |
2fc92b |
depending on the operating system. A typical shared library is composed of
|
|
Packit |
2fc92b |
several targets that look like:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
libname.so: $(OBJECTS)
|
|
Packit |
2fc92b |
TAB echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
|
|
Packit |
2fc92b |
TAB $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
|
|
Packit |
2fc92b |
TAB $(RM) libname.so libname.so.$(DSOMAJOR)
|
|
Packit |
2fc92b |
TAB $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
|
|
Packit |
2fc92b |
TAB $(LN) libname.so.$(DSOVERSION) libname.so
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
libname.dylib: $(OBJECTS)
|
|
Packit |
2fc92b |
TAB echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
|
|
Packit |
2fc92b |
TAB $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
|
|
Packit |
2fc92b |
TAB TAB -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
|
|
Packit |
2fc92b |
TAB TAB -current_version libname.$(DSOVERSION).dylib \
|
|
Packit |
2fc92b |
TAB TAB -compatibility_version $(DSOMAJOR).0 \
|
|
Packit |
2fc92b |
TAB TAB $(OBJECTS) $(LIBS)
|
|
Packit |
2fc92b |
TAB $(RM) libname.dylib
|
|
Packit |
2fc92b |
TAB $(RM) libname.$(DSOMAJOR).dylib
|
|
Packit |
2fc92b |
TAB $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
|
|
Packit |
2fc92b |
TAB $(LN) libname.$(DSOVERSION).dylib libname.dylib
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### DEPENDENCIES
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Static dependencies are expressed in each makefile following the target, for
|
|
Packit |
2fc92b |
example:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
foo: bar
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
Static dependencies are only used when it is not possible to automatically
|
|
Packit |
2fc92b |
generate them. Automatic dependencies are stored in a file named
|
|
Packit |
2fc92b |
"Dependencies" and included at the end of the makefile. The following "depend"
|
|
Packit |
2fc92b |
target rule is used to create the automatic dependencies:
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
depend:
|
|
Packit |
2fc92b |
TAB $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
We regenerate the automatic dependencies on an macOS system and express any
|
|
Packit |
2fc92b |
non-macOS dependencies statically in the makefile.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
### INSTALL/UNINSTALL SUPPORT
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
All makefiles contains install and uninstall rules which install or remove the
|
|
Packit |
2fc92b |
corresponding software. These rules must use the $(BUILDROOT) variable as a
|
|
Packit |
2fc92b |
prefix to any installation directory so that CUPS can be installed in a
|
|
Packit |
2fc92b |
temporary location for packaging by programs like rpmbuild.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The $(INSTALL\_BIN), $(INSTALL\_COMPDATA), $(INSTALL\_CONFIG), $(INSTALL\_DATA),
|
|
Packit |
2fc92b |
$(INSTALL\_DIR), $(INSTALL\_LIB), $(INSTALL\_MAN), and $(INSTALL\_SCRIPT) variables
|
|
Packit |
2fc92b |
must be used when installing files so that the proper ownership and permissions
|
|
Packit |
2fc92b |
are set on the installed files.
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
The $(RANLIB) command must be run on any static libraries after installation
|
|
Packit |
2fc92b |
since the symbol table is invalidated when the library is copied on some
|
|
Packit |
2fc92b |
platforms.
|
|
Packit |
2fc92b |
|