]> git.ipfire.org Git - thirdparty/cups.git/blame - DEVELOPING.md
The web interface did not show that a job was held for authentication (Issue #5604)
[thirdparty/cups.git] / DEVELOPING.md
CommitLineData
e3101897
MS
1Developing for CUPS
2===================
3
4Please see the [Contributing to CUPS](CONTRIBUTING.md) file for information on
5contributing to the CUPS project.
6
7
8How To Contact The Developers
9-----------------------------
10
11The CUPS mailing lists are the primary means of asking questions and informally
12discussing issues and feature requests with the CUPS developers and other
13experienced CUPS users and developers. The "cups" mailing list is intended for
14CUPS usage questions and new software announcements while the "cups-devel"
15mailing list provides a forum for CUPS developers and monitoring new bugs.
16
17
18Interfaces
19----------
20
21CUPS interfaces, including the C APIs and command-line arguments, environment
22variables, configuration files, and output format, are stable across patch
23versions and are generally backwards-compatible with interfaces used in prior
24major and minor versions. However, program interfaces such as those used by
25the scheduler to run filter, port monitor, and backend processes for job
26processing should only be considered stable from the point of view of a
27filter, port monitor, or backend. Software that simulates the scheduler in
28order to run those programs outside of CUPS must necessarily be updated when
29the corresponding interface is changed in a subsequent CUPS release, otherwise
30undefined behavior can occur.
31
32CUPS C APIs starting with an underscore (`_`) are considered to be private to
33CUPS and are not subject to the normal guarantees of stability between CUPS
34releases and must never be used in non-CUPS source code. Similarly,
35configuration and state files written by CUPS are considered private if a
36corresponding man page is not provided with the CUPS release. Never rely on
37undocumented files or formats when developing software for CUPS. Always use a
38published C API to access data stored in a file to avoid compatibility problems
39in the future.
40
41
42Build System
43------------
44
45The CUPS build system uses GNU autoconf to tailor the library to the local
46operating system. Project files for the current release of Microsoft Visual
47Studio are also provided for Microsoft Windows®. To improve portability,
48makefiles must not make use of features unique to GNU make. See the MAKEFILE
49GUIDELINES section for a description of the allowed make features and makefile
50guidelines.
51
52Additional GNU build programs such as GNU automake and GNU libtool must not be
53used. GNU automake produces non-portable makefiles which depend on GNU-
54specific extensions, and GNU libtool is not portable or reliable enough for
55CUPS.
56
57
58Version Numbering
59-----------------
60
61CUPS uses a three-part version number separated by periods to represent the
62major, minor, and patch release numbers. Major release numbers indicate large
63design changes or backwards-incompatible changes to the CUPS API or CUPS
64Imaging API. Minor release numbers indicate new features and other smaller
65changes which are backwards-compatible with previous CUPS releases. Patch
66numbers indicate bug fixes to the previous feature or patch release.
67
68> Note:
69>
70> When we talk about compatibility, we are talking about binary compatibility
71> for public APIs and output format compatibility for program interfaces.
72> Changes to configuration file formats or the default behavior of programs
73> are not generally considered incompatible as the upgrade process can
74> normally address such changes gracefully.
75
76Production releases use the plain version numbers:
77
78 MAJOR.MINOR.PATCH
79 1.0.0
80 ...
81 1.1.0
82 ...
83 1.1.23
84 ...
85 2.0.0
86 ...
87 2.1.0
88 2.1.1
89 2.1.2
90 2.1.3
91
92The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is called
93a feature release. Feature releases are the only releases that may contain new
94features. Subsequent production releases in a MAJOR.MINOR series may only
95contain bug fixes.
96
97Beta-test releases are identified by appending the letter B to the major and
98minor version numbers followed by the beta release number:
99
100 MAJOR.MINORbNUMBER
101 2.2b1
102
103Release candidates are identified by appending the letters RC to the major and
104minor version numbers followed by the release candidate number:
105
106 MAJOR.MINORrcNUMBER
107 2.2rc1
108
109
110Coding Guidelines
111-----------------
112
113Contributed source code must follow the guidelines below. While the examples
114are for C and C++ source files, source code for other languages should conform
115to the same guidelines as allowed by the language.
116
117
118### Source Files
119
120All source files names must be 16 characters or less in length to ensure
121compatibility with older UNIX filesystems. Source files containing functions
122have an extension of ".c" for C and ".cxx" for C++ source files. All other
123"include" files have an extension of ".h". Tabs are set to 8 characters or
124columns.
125
126> Note:
127>
128> The ".cxx" extension is used because it is the only common C++ extension
129> between Linux, macOS, UNIX, and Windows.
130
131The top of each source file contains a header giving the purpose or nature of
132the source file and the copyright and licensing notice:
133
134 /*
135 * Description of file contents.
136 *
137 * Copyright 2017 by Apple Inc.
138 *
139 * Licensed under Apache License v2.0. See the file "LICENSE" for more
140 * information.
141 */
142
143
144### Header Files
145
146All public header files must include the "versioning.h" header file, or a header
147that does so. Function declarations are then "decorated" with the correct
148`_CUPS_API_major_minor` macro to define its availability based on the build
149environment, for example:
150
151 extern int cupsDoThis(int foo, int bar) _CUPS_API_2_2;
152
153Private API header files must be named with the suffix "-private", for example
154the "cups.h" header file defines all of the public CUPS APIs while the
155"cups-private.h" header file defines all of the private CUPS APIs as well.
156Typically a private API header file will include the corresponding public API
157header file.
158
159
160### Comments
161
162All source code utilizes block comments within functions to describe the
163operations being performed by a group of statements; avoid putting a comment
164per line unless absolutely necessary, and then consider refactoring the code
165so that it is not necessary. C source files use the block comment format
166("/* comment */") since many vendor C compilers still do not support C99/C++
167comments ("// comment"):
168
169 /*
170 * Clear the state array before we begin...
171 */
172
173 for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
174 array[i] = CUPS_STATE_IDLE;
175
176 /*
177 * Wait for state changes on another thread...
178 */
179
180 do
181 {
182 for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
183 if (array[i] != CUPS_STATE_IDLE)
184 break;
185
186 if (i == (sizeof(array) / sizeof(array[0])))
187 sleep(1);
188 } while (i == (sizeof(array) / sizeof(array[0])));
189
190
191### Indentation
192
193All code blocks enclosed by brackets begin with the opening brace on a new
194line. The code then follows starting on a new line after the brace and is
195indented 2 spaces. The closing brace is then placed on a new line following
196the code at the original indentation:
197
198 {
199 int i; /* Looping var */
200
201 /*
202 * Process foobar values from 0 to 999...
203 */
204
205 for (i = 0; i < 1000; i ++)
206 {
207 do_this(i);
208 do_that(i);
209 }
210 }
211
212Single-line statements following "do", "else", "for", "if", and "while" are
213indented 2 spaces as well. Blocks of code in a "switch" block are indented 4
214spaces after each "case" and "default" case:
215
216 switch (array[i])
217 {
218 case CUPS_STATE_IDLE :
219 do_this(i);
220 do_that(i);
221 break;
222
223 default :
224 do_nothing(i);
225 break;
226 }
227
228
229### Spacing
230
231A space follows each reserved word such as `if`, `while`, etc. Spaces are not
232inserted between a function name and the arguments in parenthesis.
233
234
235### Return Values
236
237Parenthesis surround values returned from a function:
238
239 return (CUPS_STATE_IDLE);
240
241
242### Functions
243
244Functions with a global scope have a lowercase prefix followed by capitalized
245words, e.g., `cupsDoThis`, `cupsDoThat`, `cupsDoSomethingElse`, etc. Private
246global functions begin with a leading underscore, e.g., `_cupsDoThis`,
247`_cupsDoThat`, etc.
248
249Functions with a local scope are declared static with lowercase names and
250underscores between words, e.g., `do_this`, `do_that`, `do_something_else`, etc.
251
252Each function begins with a comment header describing what the function does,
253the possible input limits (if any), the possible output values (if any), and
254any special information needed:
255
256 /*
257 * 'do_this()' - Compute y = this(x).
258 *
259 * Notes: none.
260 */
261
262 static float /* O - Inverse power value, 0.0 <= y <= 1.1 */
263 do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
264 {
265 ...
266 return (y);
267 }
268
269Return/output values are indicated using an "O" prefix, input values are
270indicated using the "I" prefix, and values that are both input and output use
271the "IO" prefix for the corresponding in-line comment.
272
273The Mini-XML documentation generator also understands the following special
274text in the function description comment:
275
276 @deprecated@ - Marks the function as deprecated (not recommended
277 for new development and scheduled for removal)
278 @since CUPS version@ - Marks the function as new in the specified version
279 of CUPS.
280 @private@ - Marks the function as private (same as starting the
281 function name with an underscore)
282
283
284### Variables
285
286Variables with a global scope are capitalized, e.g., `ThisVariable`,
287`ThatVariable`, `ThisStateVariable`, etc. Globals in CUPS libraries are either
288part of the per-thread global values managed by the `_cupsGlobals` function
289or are suitably protected for concurrent access. Global variables should be
290replaced by function arguments whenever possible.
291
292Variables with a local scope are lowercase with underscores between words,
293e.g., `this_variable`, `that_variable`, etc. Any "local global" variables
294shared by functions within a source file are declared static. As for global
295variables, local static variables are suitably protected for concurrent access.
296
297Each variable is declared on a separate line and is immediately followed by a
298comment block describing the variable:
299
300 int ThisVariable; /* The current state of this */
301 static int that_variable; /* The current state of that */
302
303
304### Types
305
306All type names are lowercase with underscores between words and `_t` appended
307to the end of the name, e.g., `cups_this_type_t`, `cups_that_type_t`, etc.
308Type names start with a prefix, typically `cups` or the name of the program,
309to avoid conflicts with system types. Private type names start with an
310underscore, e.g., `_cups_this_t`, `_cups_that_t`, etc.
311
312Each type has a comment block immediately after the typedef:
313
314 typedef int cups_this_type_t; /* This type is for CUPS foobar options. */
315
316
317### Structures
318
319All structure names are lowercase with underscores between words and `_s`
320appended to the end of the name, e.g., `cups_this_s`, `cups_that_s`, etc.
321Structure names start with a prefix, typically `cups` or the name of the
322program, to avoid conflicts with system types. Private structure names start
323with an underscore, e.g., `_cups_this_s`, `_cups_that_s`, etc.
324
325Each structure has a comment block immediately after the struct and each member
326is documented similar to the variable naming policy above:
327
328 struct cups_this_struct_s /* This structure is for CUPS foobar options. */
329 {
330 int this_member; /* Current state for this */
331 int that_member; /* Current state for that */
332 };
333
334
335### Constants
336
337All constant names are uppercase with underscores between words, e.g.,
338`CUPS_THIS_CONSTANT`, `CUPS_THAT_CONSTANT`, etc. Constants begin with an
339uppercase prefix, typically `CUPS_` or the program or type name. Private
340constants start with an underscore, e.g., `_CUPS_THIS_CONSTANT`,
341`_CUPS_THAT_CONSTANT`, etc.
342
343Typed enumerations should be used whenever possible to allow for type checking
344by the compiler.
345
346Comment blocks immediately follow each constant:
347
348 typedef enum cups_tray_e /* Tray enumerations */
349 {
350 CUPS_TRAY_THIS, /* This tray */
351 CUPS_TRAY_THAT /* That tray */
352 } cups_tray_t;
353
354
355## Makefile Guidelines
356
357The following is a guide to the makefile-based build system used by CUPS.
358These standards have been developed over the years to allow CUPS to be built on
359as many systems and environments as possible.
360
361
362### General Organization
363
364The CUPS source code is organized functionally into a top-level makefile,
365include file, and subdirectories each with their own makefile and dependencies
366files. The ".in" files are template files for the autoconf software and are
367used to generate a static version of the corresponding file.
368
369
370### Makefile Documentation
371
372Each makefile starts with the standard CUPS header containing the description
373of the file, and CUPS copyright and license notice:
374
375 #
376 # Makefile for ...
377 #
378 # Copyright 2017 by Apple Inc.
379 #
380 # Licensed under Apache License v2.0. See the file "LICENSE" for more
381 # information.
382 #
383
384
385### Portable Makefile Construction
386
387CUPS uses a common subset of make program syntax to ensure that the software
388can be compiled "out of the box" on as many systems as possible. The following
389is a list of assumptions we follow when constructing makefiles:
390
391- Targets; we assume that the make program supports the notion of simple
392 targets of the form "name:" that perform tab-indented commands that follow
393 the target, e.g.:
394
395 target:
396 TAB target commands
397
398- Dependencies; we assume that the make program supports recursive dependencies
399 on targets, e.g.:
400
401 target: foo bar
402 TAB target commands
403
404 foo: bla
405 TAB foo commands
406
407 bar:
408 TAB bar commands
409
410 bla:
411 TAB bla commands
412
413- Variable Definition; we assume that the make program supports variable
414 definition on the command-line or in the makefile using the following form:
415
416 name=value
417
418- Variable Substitution; we assume that the make program supports variable
419 substitution using the following forms:
420
421 - `$(name)`; substitutes the value of "name",
422 - `$(name:.old=.new)`; substitutes the value of "name" with the filename
423 extension ".old" changed to ".new",
424 - `$(MAKEFLAGS)`; substitutes the command-line options passed to the
425 program without the leading hyphen (-),
426 - `$$`; substitutes a single $ character,
427 - `$<`; substitutes the current source file or dependency, and
428 - `$@`; substitutes the current target name.
429
430- Suffixes; we assume that the make program supports filename suffixes with
431 assumed dependencies, e.g.:
432
433 .SUFFIXES: .c .o
434 .c.o:
435 TAB $(CC) $(CFLAGS) -o $@ -c $<
436
437- Include Files; we assume that the make program supports the include
438 directive, e.g.:
439
440 include ../Makedefs
441 include Dependencies
442
443- Comments; we assume that comments begin with a # character and proceed to the
444 end of the current line.
445
446- Line Length; we assume that there is no practical limit to the length of
447 lines.
448
449- Continuation of long lines; we assume that the `\` character may be placed at
450 the end of a line to concatenate two or more lines in a makefile to form a
451 single long line.
452
453- Shell; we assume a POSIX-compatible shell is present on the build system.
454
455
456### Standard Variables
457
458The following variables are defined in the "Makedefs" file generated by the
459autoconf software:
460
461- `ALL_CFLAGS`; the combined C compiler options,
462- `ALL_CXXFLAGS`; the combined C++ compiler options,
463- `AMANDIR`; the administrative man page installation directory (section 8/1m
464 depending on the platform),
465- `AR`; the library archiver command,
466- `ARFLAGS`; options for the library archiver command,
467- `AWK`; the local awk command,
468- `BINDIR`; the binary installation directory,
469- `BUILDROOT`; optional installation prefix (defaults to DSTROOT),
470- `CC`; the C compiler command,
471- `CFLAGS`; options for the C compiler command,
472- `CHMOD`; the chmod command,
473- `CXX`; the C++ compiler command,
474- `CXXFLAGS`; options for the C++ compiler command,
475- `DATADIR`; the data file installation directory,
476- `DSO`; the C shared library building command,
477- `DSOXX`; the C++ shared library building command,
478- `DSOFLAGS`; options for the shared library building command,
479- `INCLUDEDIR`; the public header file installation directory,
480- `INSTALL`; the install command,
481- `INSTALL_BIN`; the program installation command,
482- `INSTALL_COMPDATA`; the compressed data file installation command,
483- `INSTALL_CONFIG`; the configuration file installation command,
484- `INSTALL_DATA`; the data file installation command,
485- `INSTALL_DIR`; the directory installation command,
486- `INSTALL_LIB`; the library installation command,
487- `INSTALL_MAN`; the documentation installation command,
488- `INSTALL_SCRIPT`; the shell script installation command,
489- `LD`; the linker command,
490- `LDFLAGS`; options for the linker,
491- `LIBDIR`; the library installation directory,
492- `LIBS`; libraries for all programs,
493- `LN`; the ln command,
494- `MAN1EXT`; extension for man pages in section 1,
495- `MAN3EXT`; extension for man pages in section 3,
496- `MAN5EXT`; extension for man pages in section 5,
497- `MAN7EXT`; extension for man pages in section 7,
498- `MAN8DIR`; subdirectory for man pages in section 8,
499- `MAN8EXT`; extension for man pages in section 8,
500- `MANDIR`; the man page installation directory,
501- `OPTIM`; common compiler optimization options,
502- `PRIVATEINCLUDE`; the private header file installation directory,
503- `RM`; the rm command,
504- `SHELL`; the sh (POSIX shell) command,
505- `STRIP`; the strip command,
506- `srcdir`; the source directory.
507
508
509### Standard Targets
510
511The following standard targets are defined in each makefile:
512
513- `all`; creates all target programs, libraries, and documentation files,
514- `clean`; removes all target programs libraries, documentation files, and object
515 files,
516- `depend`; generates automatic dependencies for any C or C++ source files (also
517 see "DEPENDENCIES"),
518- `distclean`; removes autoconf-generated files in addition to those removed by
519 the "clean" target,
520- `install`; installs all distribution files in their corresponding locations
521 (also see "INSTALL/UNINSTALL SUPPORT"),
522- `install-data`; installs all data files in their corresponding locations (also
523 see "INSTALL/UNINSTALL SUPPORT"),
524- `install-exec`; installs all executable files in their corresponding locations
525 (also see "INSTALL/UNINSTALL SUPPORT"),
526- `install-headers`; installs all include files in their corresponding locations
527 (also see "INSTALL/UNINSTALL SUPPORT"),
528- `install-libs`; installs all library files in their corresponding locations
529 (also see "INSTALL/UNINSTALL SUPPORT"), and
530- `uninstall`; removes all distribution files from their corresponding locations
531 (also see "INSTALL/UNINSTALL SUPPORT").
532
533
534### Object Files
535
536Object files (the result of compiling a C or C++ source file) have the
537extension ".o".
538
539
540### Programs
541
542Program files are the result of linking object files and libraries together to
543form an executable file. A typical program target looks like:
544
545 program: $(OBJS)
546 TAB echo Linking $@...
547 TAB $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
548
549### Static Libraries
550
551Static libraries have a prefix of "lib" and the extension ".a". A typical
552static library target looks like:
553
554 libname.a: $(OBJECTS)
555 TAB echo Creating $@...
556 TAB $(RM) $@
557 TAB $(AR) $(ARFLAGS) $@ $(OBJECTS)
558 TAB $(RANLIB) $@
559
560### Shared Libraries
561
562Shared libraries have a prefix of "lib" and the extension ".dylib" or ".so"
563depending on the operating system. A typical shared library is composed of
564several targets that look like:
565
566 libname.so: $(OBJECTS)
567 TAB echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
568 TAB $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
569 TAB $(RM) libname.so libname.so.$(DSOMAJOR)
570 TAB $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
571 TAB $(LN) libname.so.$(DSOVERSION) libname.so
572
573 libname.dylib: $(OBJECTS)
574 TAB echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
575 TAB $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
576 TAB TAB -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
577 TAB TAB -current_version libname.$(DSOVERSION).dylib \
578 TAB TAB -compatibility_version $(DSOMAJOR).0 \
579 TAB TAB $(OBJECTS) $(LIBS)
580 TAB $(RM) libname.dylib
581 TAB $(RM) libname.$(DSOMAJOR).dylib
582 TAB $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
583 TAB $(LN) libname.$(DSOVERSION).dylib libname.dylib
584
585### Dependencies
586
587Static dependencies are expressed in each makefile following the target, for
588example:
589
590 foo: bar
591
592Static dependencies are only used when it is not possible to automatically
593generate them. Automatic dependencies are stored in a file named
594"Dependencies" and included at the end of the makefile. The following "depend"
595target rule is used to create the automatic dependencies:
596
597 depend:
598 TAB $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies
599
600We regenerate the automatic dependencies on an macOS system and express any
601non-macOS dependencies statically in the makefile.
602
603
604### Install/Uninstall Support
605
606All makefiles contains install and uninstall rules which install or remove the
607corresponding software. These rules must use the $(BUILDROOT) variable as a
608prefix to any installation directory so that CUPS can be installed in a
609temporary location for packaging by programs like rpmbuild.
610
611The `INSTALL_BIN`, `INSTALL_COMPDATA`, `INSTALL_CONFIG`, `INSTALL_DATA`,
612`INSTALL_DIR`, `INSTALL_LIB`, `INSTALL_MAN`, and `INSTALL_SCRIPT` variables
613must be used when installing files so that the proper ownership and permissions
614are set on the installed files.
615
616The `$(RANLIB)` command must be run on any static libraries after installation
617since the symbol table is invalidated when the library is copied on some
618platforms.