DEVELOPING.md

   1 Developing for CUPS
   2 ===================
   3
   4 Please see the [Contributing to CUPS](CONTRIBUTING.md) file for information on
   5 contributing to the CUPS project.
   6
   7
   8 How To Contact The Developers
   9 -----------------------------
  10
  11 The CUPS mailing lists are the primary means of asking questions and informally
  12 discussing issues and feature requests with the CUPS developers and other
  13 experienced CUPS users and developers.  The "cups" mailing list is intended for
  14 CUPS usage questions and new software announcements while the "cups-devel"
  15 mailing list provides a forum for CUPS developers and monitoring new bugs.
  16
  17
  18 Interfaces
  19 ----------
  20
  21 CUPS interfaces, including the C APIs and command-line arguments, environment
  22 variables, configuration files, and output format, are stable across patch
  23 versions and are generally backwards-compatible with interfaces used in prior
  24 major and minor versions.  However, program interfaces such as those used by
  25 the scheduler to run filter, port monitor, and backend processes for job
  26 processing should only be considered stable from the point of view of a
  27 filter, port monitor, or backend.  Software that simulates the scheduler in
  28 order to run those programs outside of CUPS must necessarily be updated when
  29 the corresponding interface is changed in a subsequent CUPS release, otherwise
  30 undefined behavior can occur.
  31
  32 CUPS C APIs starting with an underscore (`_`) are considered to be private to
  33 CUPS and are not subject to the normal guarantees of stability between CUPS
  34 releases and must never be used in non-CUPS source code.  Similarly,
  35 configuration and state files written by CUPS are considered private if a
  36 corresponding man page is not provided with the CUPS release.  Never rely on
  37 undocumented files or formats when developing software for CUPS.  Always use a
  38 published C API to access data stored in a file to avoid compatibility problems
  39 in the future.
  40
  41
  42 Build System
  43 ------------
  44
  45 The CUPS build system uses GNU autoconf to tailor the library to the local
  46 operating system.  Project files for the current release of Microsoft Visual
  47 Studio are also provided for Microsoft Windows®.  To improve portability,
  48 makefiles must not make use of features unique to GNU make.  See the MAKEFILE
  49 GUIDELINES section for a description of the allowed make features and makefile
  50 guidelines.
  51
  52 Additional GNU build programs such as GNU automake and GNU libtool must not be
  53 used.  GNU automake produces non-portable makefiles which depend on GNU-
  54 specific extensions, and GNU libtool is not portable or reliable enough for
  55 CUPS.
  56
  57
  58 Version Numbering
  59 -----------------
  60
  61 CUPS uses a three-part version number separated by periods to represent the
  62 major, minor, and patch release numbers.  Major release numbers indicate large
  63 design changes or backwards-incompatible changes to the CUPS API or CUPS
  64 Imaging API.  Minor release numbers indicate new features and other smaller
  65 changes which are backwards-compatible with previous CUPS releases.  Patch
  66 numbers indicate bug fixes to the previous feature or patch release.  This
  67 version 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
  78 Production 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
  94 The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is called
  95 a feature release.  Feature releases are the only releases that may contain new
  96 features.  Subsequent production releases in a MAJOR.MINOR series may only
  97 contain bug fixes.
  98
  99 Beta-test releases are identified by appending the letter B to the major and
 100 minor version numbers followed by the beta release number:
 101
 102     MAJOR.MINORbNUMBER
 103     2.2b1
 104
 105 Release candidates are identified by appending the letters RC to the major and
 106 minor version numbers followed by the release candidate number:
 107
 108     MAJOR.MINORrcNUMBER
 109     2.2rc1
 110
 111
 112 Coding Guidelines
 113 -----------------
 114
 115 Contributed source code must follow the guidelines below.  While the examples
 116 are for C and C++ source files, source code for other languages should conform
 117 to the same guidelines as allowed by the language.
 118
 119 Source code comments provide the reference portion of the CUPS Programming
 120 Manual, which is generated using the [codedoc](https://www.msweet.org/codedoc)
 121 software.
 122
 123
 124 ### Source Files
 125
 126 All source files names must be 16 characters or less in length to ensure
 127 compatibility with older UNIX filesystems.  Source files containing functions
 128 have 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
 130 columns.
 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
 137 The top of each source file contains a header giving the purpose or nature of
 138 the 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
 152 All public header files must include the "versioning.h" header file, or a header
 153 that does so.  Function declarations are then "decorated" with the correct
 154 `_CUPS_API_major_minor` macro to define its availability based on the build
 155 environment, for example:
 156
 157     extern int cupsDoThis(int foo, int bar) _CUPS_API_2_2;
 158
 159 Private API header files must be named with the suffix "-private", for example
 160 the "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.
 162 Typically a private API header file will include the corresponding public API
 163 header file.
 164
 165
 166 ### Comments
 167
 168 All source code utilizes block comments within functions to describe the
 169 operations being performed by a group of statements; avoid putting a comment
 170 per line unless absolutely necessary, and then consider refactoring the code
 171 so 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++
 173 comments ("// 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
 199 All code blocks enclosed by brackets begin with the opening brace on a new
 200 line.  The code then follows starting on a new line after the brace and is
 201 indented 2 spaces.  The closing brace is then placed on a new line following
 202 the 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
 218 Single-line statements following "do", "else", "for", "if", and "while" are
 219 indented 2 spaces as well.  Blocks of code in a "switch" block are indented 4
 220 spaces 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
 237 A space follows each reserved word such as `if`, `while`, etc.  Spaces are not
 238 inserted between a function name and the arguments in parenthesis.
 239
 240
 241 ### Return Values
 242
 243 Parenthesis surround values returned from a function:
 244
 245     return (CUPS_STATE_IDLE);
 246
 247
 248 ### Functions
 249
 250 Functions with a global scope have a lowercase prefix followed by capitalized
 251 words, e.g., `cupsDoThis`, `cupsDoThat`, `cupsDoSomethingElse`, etc.  Private
 252 global functions begin with a leading underscore, e.g., `_cupsDoThis`,
 253 `_cupsDoThat`, etc.
 254
 255 Functions with a local scope are declared static with lowercase names and
 256 underscores between words, e.g., `do_this`, `do_that`, `do_something_else`, etc.
 257
 258 Each function begins with a comment header describing what the function does,
 259 the possible input limits (if any), the possible output values (if any), and
 260 any 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
 275 Return/output values are indicated using an "O" prefix, input values are
 276 indicated using the "I" prefix, and values that are both input and output use
 277 the "IO" prefix for the corresponding in-line comment.
 278
 279 The [codedoc](https://www.msweet.org/codedoc) documentation generator also
 280 understands 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
 294 Variables with a global scope are capitalized, e.g., `ThisVariable`,
 295 `ThatVariable`, `ThisStateVariable`, etc.  Globals in CUPS libraries are either
 296 part of the per-thread global values managed by the `_cupsGlobals` function
 297 or are suitably protected for concurrent access.  Global variables should be
 298 replaced by function arguments whenever possible.
 299
 300 Variables with a local scope are lowercase with underscores between words,
 301 e.g., `this_variable`, `that_variable`, etc.  Any "local global" variables
 302 shared by functions within a source file are declared static.  As for global
 303 variables, local static variables are suitably protected for concurrent access.
 304
 305 Each variable is declared on a separate line and is immediately followed by a
 306 comment 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
 314 All type names are lowercase with underscores between words and `_t` appended
 315 to the end of the name, e.g., `cups_this_type_t`, `cups_that_type_t`, etc.
 316 Type names start with a prefix, typically `cups` or the name of the program,
 317 to avoid conflicts with system types.  Private type names start with an
 318 underscore, e.g., `_cups_this_t`, `_cups_that_t`, etc.
 319
 320 Each 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
 327 All structure names are lowercase with underscores between words and `_s`
 328 appended to the end of the name, e.g., `cups_this_s`, `cups_that_s`, etc.
 329 Structure names start with a prefix, typically `cups` or the name of the
 330 program, to avoid conflicts with system types.  Private structure names start
 331 with an underscore, e.g., `_cups_this_s`, `_cups_that_s`, etc.
 332
 333 Each structure has a comment block immediately after the struct and each member
 334 is 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
 345 All constant names are uppercase with underscores between words, e.g.,
 346 `CUPS_THIS_CONSTANT`, `CUPS_THAT_CONSTANT`, etc.  Constants begin with an
 347 uppercase prefix, typically `CUPS_` or the program or type name.  Private
 348 constants start with an underscore, e.g., `_CUPS_THIS_CONSTANT`,
 349 `_CUPS_THAT_CONSTANT`, etc.
 350
 351 Typed enumerations should be used whenever possible to allow for type checking
 352 by the compiler.
 353
 354 Comment 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
 365 The following is a guide to the makefile-based build system used by CUPS.
 366 These standards have been developed over the years to allow CUPS to be built on
 367 as many systems and environments as possible.
 368
 369
 370 ### General Organization
 371
 372 The CUPS source code is organized functionally into a top-level makefile,
 373 include file, and subdirectories each with their own makefile and dependencies
 374 files.  The ".in" files are template files for the autoconf software and are
 375 used to generate a static version of the corresponding file.
 376
 377
 378 ### Makefile Documentation
 379
 380 Each makefile starts with the standard CUPS header containing the description
 381 of 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
 395 CUPS uses a common subset of make program syntax to ensure that the software
 396 can be compiled "out of the box" on as many systems as possible.  The following
 397 is 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
 466 The following variables are defined in the "Makedefs" file generated by the
 467 autoconf 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
 519 The 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
 544 Object files (the result of compiling a C or C++ source file) have the
 545 extension ".o".
 546
 547
 548 ### Programs
 549
 550 Program files are the result of linking object files and libraries together to
 551 form 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
 559 Static libraries have a prefix of "lib" and the extension ".a". A typical
 560 static 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
 570 Shared libraries have a prefix of "lib" and the extension ".dylib" or ".so"
 571 depending on the operating system.  A typical shared library is composed of
 572 several 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
 595 Static dependencies are expressed in each makefile following the target, for
 596 example:
 597
 598     foo: bar
 599
 600 Static dependencies are only used when it is not possible to automatically
 601 generate them.  Automatic dependencies are stored in a file named
 602 "Dependencies" and included at the end of the makefile.  The following "depend"
 603 target rule is used to create the automatic dependencies:
 604
 605     depend:
 606     TAB $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies
 607
 608 We regenerate the automatic dependencies on an macOS system and express any
 609 non-macOS dependencies statically in the makefile.
 610
 611
 612 ### Install/Uninstall Support
 613
 614 All makefiles contains install and uninstall rules which install or remove the
 615 corresponding software.  These rules must use the $(BUILDROOT) variable as a
 616 prefix to any installation directory so that CUPS can be installed in a
 617 temporary location for packaging by programs like rpmbuild.
 618
 619 The `INSTALL_BIN`, `INSTALL_COMPDATA`, `INSTALL_CONFIG`, `INSTALL_DATA`,
 620 `INSTALL_DIR`, `INSTALL_LIB`, `INSTALL_MAN`, and `INSTALL_SCRIPT` variables
 621 must be used when installing files so that the proper ownership and permissions
 622 are set on the installed files.
 623
 624 The `$(RANLIB)` command must be run on any static libraries after installation
 625 since the symbol table is invalidated when the library is copied on some
 626 platforms.