1Building and Installing OpenPrinting CUPS 2========================================= 3 4This file describes how to compile and install CUPS from source code. For more 5information on CUPS see the file called `README.md`. 6 7Using CUPS requires additional third-party support software and printer drivers. 8These are typically included with your operating system distribution. 9 10 11Before You Begin 12---------------- 13 14You'll need ANSI-compliant C and C++ compilers, plus a make program and POSIX- 15compliant shell (/bin/sh). The GNU compiler tools and Bash work well and we 16have tested the current CUPS code against several versions of Clang and GCC with 17excellent results. 18 19The makefiles used by the project should work with POSIX-compliant versions of 20`make`. We've tested them with GNU make as well as several vendor make programs. 21BSD users should use GNU make (`gmake`) since BSD make is not POSIX-compliant 22and does not support the `include` directive. 23 24Besides these tools you'll want ZLIB for compression support, Avahi for mDNS 25support, LIBUSB for USB printing support, the GNU TLS, LibreSSL, or OpenSSL 26libraries for encryption support on platforms other than iOS, macOS, or Windows, 27and PAM for authentication support. CUPS will compile and run without these, 28however you'll miss out on many of the features provided by CUPS. 29 30> Note: Kerberos support is deprecated starting with CUPS 2.4.0 and will be 31> removed in a future version of CUPS. To build CUPS with Kerberos support, 32> specify the "--enable-gssapi" configure option below. 33 34On a stock Ubuntu install, the following command will install the required 35prerequisites: 36 37 sudo apt-get install autoconf build-essential libavahi-client-dev \ 38 libgnutls28-dev libkrb5-dev libnss-mdns libpam-dev \ 39 libsystemd-dev libusb-1.0-0-dev zlib1g-dev 40 41 42For Fedora you can install these packages: 43 44 sudo dnf install autoconf make automake gcc gcc-c++ krb5-devel avahi-devel \ 45 gnutls-devel krb5-libs nss-mdns pam-devel \ 46 systemd-devel libusb1-devel zlib-devel 47 48Configuration 49------------- 50 51CUPS uses GNU autoconf, so you should find the usual "configure" script in the 52main CUPS source directory. To configure CUPS for your system, type: 53 54 ./configure 55 56The default installation will put the CUPS software in the "/etc", "/usr", and 57"/var" directories on your system, which will overwrite any existing printing 58commands on your system. Use the `--prefix` option to install the CUPS software 59in another location: 60 61 ./configure --prefix=/some/directory 62 63To see a complete list of configuration options, use the `--help` option: 64 65 ./configure --help 66 67If any of the dependent libraries are not installed in a system default location 68(typically "/usr/include" and "/usr/lib") you'll need to set the `CFLAGS`, 69`CPPFLAGS`, `CXXFLAGS`, `DSOFLAGS`, and `LDFLAGS` environment variables prior to 70running configure: 71 72 setenv CFLAGS "-I/some/directory" 73 setenv CPPFLAGS "-I/some/directory" 74 setenv CXXFLAGS "-I/some/directory" 75 setenv DSOFLAGS "-L/some/directory" 76 setenv LDFLAGS "-L/some/directory" 77 ./configure ... 78 79or: 80 81 CFLAGS="-I/some/directory" \ 82 CPPFLAGS="-I/some/directory" \ 83 CXXFLAGS="-I/some/directory" \ 84 DSOFLAGS="-L/some/directory" \ 85 LDFLAGS="-L/some/directory" \ 86 ./configure ... 87 88The `--enable-debug` option compiles CUPS with debugging information enabled. 89Additional debug logging support can be enabled using the 90`--enable-debug-printfs` option - these debug messages are enabled using the 91`CUPS_DEBUG_xxx` environment variables at run-time. 92 93CUPS also includes an extensive set of unit tests that can be used to find and 94diagnose a variety of common problems - use the "--enable-unit-tests" configure 95option to run them at build time. 96 97Once you have configured things, just type: 98 99 make 100 101or if you have FreeBSD, NetBSD, or OpenBSD type: 102 103 gmake 104 105to build the software. 106 107 108Testing the Software 109-------------------- 110 111Aside from the built-in unit tests, CUPS includes an automated test framework 112for testing the entire printing system. To run the tests, just type: 113 114 make test 115 116or if you have FreeBSD, NetBSD, or OpenBSD type: 117 118 gmake test 119 120The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631 in 121"/tmp/cups-$USER" and produces a nice HTML report of the results. 122 123 124Installing the Software 125----------------------- 126 127Once you have built the software you need to install it. The "install" target 128provides a quick way to install the software on your local system: 129 130 make install 131 132or for FreeBSD, NetBSD, or OpenBSD: 133 134 gmake install 135 136Use the `BUILDROOT` variable to install to an alternate root directory: 137 138 make BUILDROOT=/some/other/root/directory install 139 140You can also build binary packages that can be installed on other machines using 141the RPM spec file ("packaging/cups.spec") or EPM list file 142("packaging/cups.list"). The latter also supports building of binary RPMs, so 143it may be more convenient to use. 144 145You can find the RPM software at <http://www.rpm.org/>. 146 147The EPM software is available at <https://jimjag.github.io/epm/>. 148 149 150Creating Binary Distributions With Epm 151-------------------------------------- 152 153The top level makefile supports generation of many types of binary distributions 154using EPM. To build a binary distribution type: 155 156 make FORMAT 157 158or 159 160 gmake FORMAT 161 162for FreeBSD, NetBSD, and OpenBSD. The "FORMAT" target is one of the following: 163 164- "epm": Builds a script + tarfile package 165- "bsd": Builds a *BSD package 166- "deb": Builds a Debian package 167- "pkg": Builds a Solaris package 168- "rpm": Builds a RPM package 169- "slackware": Build a Slackware package 170 171 172Getting Debug Logging From CUPS 173------------------------------- 174 175When configured with the `--enable-debug-printfs` option, CUPS compiles in 176additional debug logging support in the scheduler, CUPS API, and CUPS Imaging 177API. The following environment variables are used to enable and control debug 178logging: 179 180- `CUPS_DEBUG_FILTER`: Specifies a POSIX regular expression to control which 181 messages are logged. 182- `CUPS_DEBUG_LEVEL`: Specifies a number from 0 to 9 to control the verbosity of 183 the logging. The default level is 1. 184- `CUPS_DEBUG_LOG`: Specifies a log file to use. Specify the name "-" to send 185 the messages to stderr. Prefix a filename with "+" to append to an existing 186 file. You can include a single "%d" in the filename to embed the current 187 process ID. 188