DOCSEARCHbyAlgolia
Submit Docs

OpenPrinting CUPS Documentation

repository·master·Indexed 23 days ago

https://github.com/openprinting/cups

A standards-based, open-source printing system for Linux and Unix-like operating systems. Supports AirPrint, IPP Everywhere, and legacy PPD drivers. Documentation covers printer management via the web interface and lpadmin CLI, printing with lp and lpr, and C/C++ development using the CUPS API, including destination enumeration, attribute retrieval, and media management.

Tokens
41.3K
Snippets
53
Records
237
Agent score
83%

What's inside OpenPrinting CUPS

  1. Overview of OpenPrinting CUPS

    master

    OpenPrinting CUPS is a standards-based, open-source printing system for Linux and other Unix-like operating systems. It supports:

    • AirPrint™ and IPP Everywhere™ printers.
    • Network and local (USB) printers using Printer Applications.
    • Network and local (USB) printers using legacy PPD-based drivers.

    CUPS provides the System V (lp) and Berkeley (lpr) command-line interfaces, a configurable web interface, a C API, and common print filters, drivers, and backends. Additional filters and drivers are provided by the cups-filters project.

  2. Retrieve supported, default, and ready values for options

    master

    Once you have a cups_dinfo_t structure, you can query different states of an option:

    1. Supported Values: Use cupsFindDestSupported to get an ipp_attribute_t containing all values the printer is capable of using.
    2. Default Values: Use cupsFindDestDefault to get the printer's default value(s). Note that user-provided defaults (from cups_dest_t) should take precedence over these.
    3. Ready (Loaded) Values: Use cupsFindDestReady to get values that are currently available (e.g., a printer might support stapling, but is currently out of staples, so stapling is not 'ready').

  3. Understand the CUPS Makefile Build System

    master
    CUPS uses a POSIX-compliant, makefile-based build system designed for maximum portability across different environments. The source code is organized functionally: a top-level makefile and include files control the build, while subdirectories contain their own makefiles and dependency files. Template files with the .in extension are used by autoconf to generate static versions of configuration files.

  4. Work with media sizes and dimensions using cups_media_t

    master

    CUPS uses the cups_media_t structure to describe media properties like dimensions, margins, color, source, and type.

    The cups_media_t structure

    typedef struct cups_media_s
{
  char media[128];   // PWG self-describing name (e.g., "iso_a4_210x297mm")
  char color[128];   // PWG color name (e.g., "white")
  char source[128];  // Standard keyword (e.g., "tray-1", "manual")
  char type[128];    // PWG media type (e.g., "stationery")
  int width, length; // Dimensions in hundredths of millimeters
  int bottom, left, right, top; // Margins in hundredths of millimeters
}

    Querying Media

    • By Name: cupsGetDestMediaByName2 looks up media using a standard name.
    • By Size: cupsGetDestMediaBySize2 looks up media using width and length.
    • Enumeration: Use cupsGetDestMediaCount and cupsGetDestMediaByIndex2 to iterate through all supported media sizes matching specific flags.
    • Default: cupsGetDestMediaDefault2 returns the printer's default media.
    typedef struct cups_media_s
{
  char media[128];
  char color[128];
  char source[128];
  char type[128];
  int width, length;
  int bottom, left, right, top;
} cups_media_t;

  5. Follow CUPS naming conventions for functions, variables, and types

    master

    CUPS enforces strict naming conventions to distinguish scope and visibility:

    EntityScopeNaming ConventionExample
    FunctionGloballowercasePrefixCapitalizedWordscupsDoThis
    FunctionPrivate Global_leadingUnderscore_cupsDoThis
    FunctionLocal (static)lowercase_with_underscoresdo_this
    VariableGlobalCapitalizedWordsThisVariable
    VariableLocallowercase_with_underscoresthis_variable
    TypePubliclowercase_with_underscores_tcups_this_type_t
    TypePrivate_leading_underscore_t_cups_this_t
    StructurePubliclowercase_with_underscores_scups_this_struct_s
    StructurePrivate_leading_underscore_s_cups_this_s
    ConstantPublicUPPERCASE_WITH_UNDERSCORESCUPS_THIS_CONSTANT
    ConstantPrivate_leading_underscore_UPPERCASE_CUPS_THIS_CONSTANT

  6. Understand CUPS interface stability and privacy

    master

    CUPS interfaces (C APIs, CLI arguments, environment variables, config files, and output formats) are stable across patch versions and generally backwards-compatible with prior major/minor versions.

    Important Restrictions:

    • Private APIs: Any C API starting with an underscore (_) is private to CUPS. Do not use these in non-CUPS source code as they lack stability guarantees.
    • Private Files: Configuration and state files are considered private if they do not have a corresponding man page. Always use a published C API to access data rather than relying on undocumented file formats.
    • Program Interfaces: Interfaces used by the scheduler to run filters, port monitors, and backends are only stable from the perspective of those specific programs. Software simulating the scheduler must be updated when these interfaces change to avoid undefined behavior.

  7. Identify CUPS version numbers and compatibility

    master

    CUPS follows a Semantic Versioning-inspired three-part numbering scheme: MAJOR.MINOR.PATCH.

    • Major: Large design changes or backwards-incompatible changes to the CUPS or CUPS Imaging API.
    • Minor: New features and smaller, backwards-compatible changes.
    • Patch: Bug fixes.

    Release Types:

    • Feature Release: The first production release in a series (MAJOR.MINOR.0). Only these may contain new features.
    • Beta-test: Identified by MAJOR.MINORbNUMBER (e.g., 2.2b1).
    • Release Candidate: Identified by MAJOR.MINORrcNUMBER (e.g., 2.2rc1).

    Compatibility Definition:

    • Binary Compatibility: Applies to public APIs.
    • Output Format Compatibility: Applies to program interfaces.
    • Note: Changes to configuration file formats or default program behaviors are generally not considered incompatible.

  8. Create and configure an IPP request

    master

    IPP requests are managed via the ipp_t type.

    1. Initialization: Create a request with ippNewRequest(ipp_op_t op). The operation code (e.g., IPP_OP_GET_PRINTER_ATTRIBUTES) defines the request type.
    2. Targeting: You must add attributes to specify the target of the operation. For example, to query a printer, add the printer-uri attribute using ippAddString.
    3. Attribute Types: CUPS provides various functions to add attributes to a request:
      • ippAddBoolean: Boolean (IPP_TAG_BOOLEAN)
      • ippAddInteger: Enum (IPP_TAG_ENUM) or integer (IPP_TAG_INTEGER)
      • ippAddStrings: Multiple strings (e.g., IPP_TAG_KEYWORD for attribute names)
      • ippAddString: Single string (e.g., IPP_TAG_URI, IPP_TAG_TEXT, IPP_TAG_NAME)
      • ippAddOctetString: Octet string
      • ippAddRanges: Range of integers
      • ippAddResolution: Resolution attribute

  9. Compile CUPS programs with GCC

    master

    When compiling with GCC, use pkg-config to automatically retrieve the necessary compiler flags and library links for your system.

    Example command to compile and run a file named simple.c:

    gcc -o simple `pkg-config --cflags cups` simple.c `pkg-config --libs cups`
./simple

  10. Build and install CUPS from source

    master

    Once configured, use make to compile the software. For BSD-based systems (FreeBSD, NetBSD, OpenBSD), use gmake.

    Build commands:

    • make (or gmake on BSD)

    Test commands:

    • make test (or gmake test on BSD): Runs the automated test framework. This runs a copy of cupsd on port 8631 in /tmp/cups-$USER and generates an HTML report.

    Install commands:

    • make install (or gmake install on BSD): Installs the software to the configured prefix.
    • make BUILDROOT=/some/other/root/directory install: Installs to an alternate root directory.
    make
make test
make install

  11. Build CUPS using GNU autoconf

    master

    The CUPS build system uses GNU autoconf to tailor the software to the local operating system. Microsoft Visual Studio project files are also provided for Windows.

    Build Constraints:

    • Makefiles must not use features unique to GNU make to ensure portability.
    • Prohibited tools: Do not use GNU autoheader, GNU automake, or GNU libtool, as they are considered non-portable or unreliable for CUPS.

  12. Implement Install and Uninstall Support

    master

    When writing installation rules, follow these requirements to ensure compatibility with packaging tools (like rpmbuild) and correct file permissions:

    1. Use $(BUILDROOT): Prefix all installation directories with $(BUILDROOT) so CUPS can be installed into temporary locations.
    2. Use Specialized Install Variables: Use specific variables like INSTALL_BIN, INSTALL_COMPDATA, INSTALL_CONFIG, INSTALL_DATA, INSTALL_DIR, INSTALL_LIB, INSTALL_MAN, and INSTALL_SCRIPT to ensure proper ownership and permissions are applied.
    3. Run $(RANLIB): Always run the $(RANLIB) command on static libraries after installation, as some platforms invalidate the symbol table when libraries are copied.