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