1 INSTALL - CUPS v2.2.4 - 2017-05-01
2 ==================================
4 This file describes how to compile and install CUPS from source code. For more
5 information on CUPS see the file called "README.txt". A complete change log can
6 be found in "CHANGES.txt".
8 > USING CUPS REQUIRES ADDITIONAL THIRD-PARTY SUPPORT SOFTWARE AND PRINTER
9 > DRIVERS. THESE ARE TYPICALLY INCLUDED WITH YOUR OPERATING SYSTEM
10 > DISTRIBUTION. APPLE DOES NOT ENDORSE OR SUPPORT THIRD-PARTY SUPPORT SOFTWARE
17 You'll need ANSI-compliant C and C++ compilers, plus a make program and POSIX-
18 compliant shell (/bin/sh). The GNU compiler tools and Bash work well and we
19 have tested the current CUPS code against several versions of GCC with excellent
22 The makefiles used by the project should work with most versions of make. We've
23 tested them with GNU make as well as the make programs shipped by Compaq, HP,
24 SGI, and Sun. BSD users should use GNU make (gmake) since BSD make does not
27 Besides these tools you'll want ZLIB library for compression support, the GNU
28 TLS library for encryption support on platforms other than iOS, macOS, or
29 Windows, and either MIT (1.6.3 or higher) or Heimdal Kerberos for Kerberos
30 support. CUPS will compile and run without these, however you'll miss out on
31 many of the features provided by CUPS.
33 On a stock Ubuntu install, the following command will install the required
36 sudo apt-get install autoconf build-essential libavahi-client-dev \
37 libgnutls28-dev libkrb5-dev libnss-mdns libpam-dev \
38 libsystemd-dev libusb-1.0-0-dev zlib1g-dev
40 Also, please note that CUPS does not include print filters to support PDF or
41 raster printing. You *must* download GPL Ghostscript and/or the Open Printing
42 CUPS filters package separately to print on operating systems other than macOS.
48 CUPS uses GNU autoconf, so you should find the usual "configure" script in the
49 main CUPS source directory. To configure CUPS for your system, type:
53 The default installation will put the CUPS software in the "/etc", "/usr", and
54 "/var" directories on your system, which will overwrite any existing printing
55 commands on your system. Use the "--prefix" option to install the CUPS software
58 ./configure --prefix=/some/directory
60 To see a complete list of configuration options, use the --help option:
64 If any of the dependent libraries are not installed in a system default location
65 (typically "/usr/include" and "/usr/lib") you'll need to set the CFLAGS,
66 CPPFLAGS, CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables prior to running
69 setenv CFLAGS "-I/some/directory"
70 setenv CPPFLAGS "-I/some/directory"
71 setenv CXXFLAGS "-I/some/directory"
72 setenv DSOFLAGS "-L/some/directory"
73 setenv LDFLAGS "-L/some/directory"
78 CFLAGS="-I/some/directory" \
79 CPPFLAGS="-I/some/directory" \
80 CXXFLAGS="-I/some/directory" \
81 DSOFLAGS="-L/some/directory" \
82 LDFLAGS="-L/some/directory" \
85 The "--enable-debug" option compiles CUPS with debugging information enabled.
86 Additional debug logging support can be enabled using the
87 "--enable-debug-printfs" option - these debug messages are enabled using the
88 CUPS_DEBUG_LOG environment variable at run-time.
90 CUPS also includes an extensive set of unit tests that can be used to find and
91 diagnose a variety of common problems - use the "--enable-unit-tests" configure
92 option to run them at build time.
94 On macOS, use the "--with-archflags" option to build with the correct set of
97 ./configure --with-archflags="-arch i386 -arch x86_64" ...
99 > Note: Current versions of macOS DO NOT allow installation to /usr with the
100 > default system integrity settings. In addition, we do not recommend replacing
101 > the CUPS supplied with macOS because not all versions of CUPS are compatible
102 > with every macOS release, and because software updates will replace parts
103 > of your local installation potentially rendering your system unusable.
105 Once you have configured things, just type:
109 or if you have FreeBSD, NetBSD, or OpenBSD type:
113 to build the software.
119 Aside from the built-in unit tests, CUPS includes an automated test framework
120 for testing the entire printing system. To run the tests, just type:
124 or if you have FreeBSD, NetBSD, or OpenBSD type:
128 The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631 in
129 /tmp/cups-$USER and produces a nice HTML report of the results.
132 INSTALLING THE SOFTWARE
133 -----------------------
135 Once you have built the software you need to install it. The "install" target
136 provides a quick way to install the software on your local system:
140 or for FreeBSD, NetBSD, or OpenBSD:
144 Use the BUILDROOT variable to install to an alternate root directory:
146 make BUILDROOT=/some/other/root/directory install ENTER
148 You can also build binary packages that can be installed on other machines using
149 the RPM spec file ("packaging/cups.spec") or EPM list file
150 ("packaging/cups.list"). The latter also supports building of binary RPMs, so
151 it may be more convenient to use.
153 You can find the RPM software at:
157 The EPM software is available at:
159 https://michaelrsweet.github.io/epm
162 CREATING BINARY DISTRIBUTIONS WITH EPM
163 --------------------------------------
165 The top level makefile supports generation of many types of binary distributions
166 using EPM. To build a binary distribution type:
174 for FreeBSD, NetBSD, and OpenBSD. The <format> target is one of the following:
176 - "epm": Builds a script + tarfile package
177 - "bsd": Builds a *BSD package
178 - "deb": Builds a Debian package
179 - "pkg": Builds a Solaris package
180 - "rpm": Builds a RPM package
181 - "slackware": Build a Slackware package
184 GETTING DEBUG LOGGING FROM CUPS
185 -------------------------------
187 When configured with the "--enable-debug-printfs" option, CUPS compiles in
188 additional debug logging support in the scheduler, CUPS API, and CUPS Imaging
189 API. The following environment variables are used to enable and control debug
192 - `CUPS_DEBUG_FILTER`: Specifies a POSIX regular expression to control which
194 - `CUPS_DEBUG_LEVEL`: Specifies a number from 0 to 9 to control the verbosity of
195 the logging. The default level is 1.
196 - `CUPS_DEBUG_LOG`: Specifies a log file to use. Specify the name "-" to send
197 the messages to stderr. Prefix a filename with "+" to append to an existing
204 If you have problems, READ THE DOCUMENTATION FIRST! If the documentation does
205 not solve your problems, please post a message on the users forum at:
207 https://www.cups.org/
209 Include your operating system and version, compiler and version, and any errors
210 or problems you've run into. The "config.log" file and the output from the
211 configure script and make should also be sent, as it often helps to determine
212 the cause of your problem.
214 If you are running a version of Linux, be sure to provide the Linux distribution