]> git.ipfire.org Git - thirdparty/cups.git/blame - INSTALL.md
Update man pages.
[thirdparty/cups.git] / INSTALL.md
CommitLineData
b1e7afd5 1INSTALL - CUPS v2.3b7 - 2018-12-14
63f8dcbd 2==================================
2a20b512
MS
3
4This file describes how to compile and install CUPS from source code. For more
79424d8b
MS
5information on CUPS see the file called "README.md". A complete change log can
6be found in "CHANGES.md".
2a20b512 7
fd2f0a7a
MS
8Using CUPS requires additional third-party support software and printer drivers.
9These are typically included with your operating system distribution. Apple
10does not endorse or support third-party support software for CUPS.
11
12> Note: Current versions of macOS DO NOT allow installation to /usr with the
13> default System Integrity Protection (SIP) settings. In addition, we do not
14> recommend replacing the CUPS supplied with macOS because:
15>
16> a. not all versions of CUPS are compatible with every macOS release,
17>
18> b. code signing prevents replacement of system libraries and access to the
19> system keychain (needed for encrypted printer sharing), and
20>
21> c. software updates will often replace parts of your local installation,
22> potentially rendering your system unusable.
2cf3a36a
MS
23>
24> Apple only supports using the Clang supplied with Xcode to build CUPS on
25> macOS.
2a20b512
MS
26
27
28BEFORE YOU BEGIN
29----------------
30
31You'll need ANSI-compliant C and C++ compilers, plus a make program and POSIX-
32compliant shell (/bin/sh). The GNU compiler tools and Bash work well and we
33have tested the current CUPS code against several versions of GCC with excellent
34results.
35
36The makefiles used by the project should work with most versions of make. We've
37tested them with GNU make as well as the make programs shipped by Compaq, HP,
38SGI, and Sun. BSD users should use GNU make (gmake) since BSD make does not
39support "include".
40
41Besides these tools you'll want ZLIB library for compression support, the GNU
42TLS library for encryption support on platforms other than iOS, macOS, or
43Windows, and either MIT (1.6.3 or higher) or Heimdal Kerberos for Kerberos
44support. CUPS will compile and run without these, however you'll miss out on
45many of the features provided by CUPS.
46
bb719eb3
MS
47On a stock Ubuntu install, the following command will install the required
48prerequisites:
49
50 sudo apt-get install autoconf build-essential libavahi-client-dev \
51 libgnutls28-dev libkrb5-dev libnss-mdns libpam-dev \
52 libsystemd-dev libusb-1.0-0-dev zlib1g-dev
53
2a20b512
MS
54Also, please note that CUPS does not include print filters to support PDF or
55raster printing. You *must* download GPL Ghostscript and/or the Open Printing
56CUPS filters package separately to print on operating systems other than macOS.
57
58
59CONFIGURATION
60-------------
61
62CUPS uses GNU autoconf, so you should find the usual "configure" script in the
63main CUPS source directory. To configure CUPS for your system, type:
64
65 ./configure
66
67The default installation will put the CUPS software in the "/etc", "/usr", and
68"/var" directories on your system, which will overwrite any existing printing
fd2f0a7a 69commands on your system. Use the `--prefix` option to install the CUPS software
2a20b512
MS
70in another location:
71
72 ./configure --prefix=/some/directory
73
fd2f0a7a
MS
74> Note: Current versions of macOS DO NOT allow installation to /usr with the
75> default System Integrity Protection (SIP) settings.
76
77To see a complete list of configuration options, use the `--help` option:
2a20b512
MS
78
79 ./configure --help
80
81If any of the dependent libraries are not installed in a system default location
82(typically "/usr/include" and "/usr/lib") you'll need to set the CFLAGS,
83CPPFLAGS, CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables prior to running
84configure:
85
86 setenv CFLAGS "-I/some/directory"
87 setenv CPPFLAGS "-I/some/directory"
88 setenv CXXFLAGS "-I/some/directory"
89 setenv DSOFLAGS "-L/some/directory"
90 setenv LDFLAGS "-L/some/directory"
91 ./configure ...
92
93or:
94
95 CFLAGS="-I/some/directory" \
96 CPPFLAGS="-I/some/directory" \
97 CXXFLAGS="-I/some/directory" \
98 DSOFLAGS="-L/some/directory" \
99 LDFLAGS="-L/some/directory" \
100 ./configure ...
101
fd2f0a7a 102The `--enable-debug` option compiles CUPS with debugging information enabled.
2a20b512 103Additional debug logging support can be enabled using the
fd2f0a7a
MS
104`--enable-debug-printfs` option - these debug messages are enabled using the
105`CUPS_DEBUG_xxx` environment variables at run-time.
2a20b512
MS
106
107CUPS also includes an extensive set of unit tests that can be used to find and
108diagnose a variety of common problems - use the "--enable-unit-tests" configure
109option to run them at build time.
110
fd2f0a7a 111On macOS, use the `--with-archflags` option to build with the correct set of
2a20b512
MS
112architectures:
113
114 ./configure --with-archflags="-arch i386 -arch x86_64" ...
115
2a20b512
MS
116Once you have configured things, just type:
117
118 make ENTER
119
120or if you have FreeBSD, NetBSD, or OpenBSD type:
121
122 gmake ENTER
123
124to build the software.
125
126
127TESTING THE SOFTWARE
128--------------------
129
130Aside from the built-in unit tests, CUPS includes an automated test framework
131for testing the entire printing system. To run the tests, just type:
132
133 make check ENTER
134
135or if you have FreeBSD, NetBSD, or OpenBSD type:
136
137 gmake check ENTER
138
139The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631 in
140/tmp/cups-$USER and produces a nice HTML report of the results.
141
142
143INSTALLING THE SOFTWARE
144-----------------------
145
146Once you have built the software you need to install it. The "install" target
147provides a quick way to install the software on your local system:
148
149 make install ENTER
150
151or for FreeBSD, NetBSD, or OpenBSD:
152
153 gmake install ENTER
154
155Use the BUILDROOT variable to install to an alternate root directory:
156
157 make BUILDROOT=/some/other/root/directory install ENTER
158
159You can also build binary packages that can be installed on other machines using
160the RPM spec file ("packaging/cups.spec") or EPM list file
161("packaging/cups.list"). The latter also supports building of binary RPMs, so
162it may be more convenient to use.
163
164You can find the RPM software at:
165
166 http://www.rpm.org/
167
168The EPM software is available at:
169
170 https://michaelrsweet.github.io/epm
171
172
173CREATING BINARY DISTRIBUTIONS WITH EPM
174--------------------------------------
175
176The top level makefile supports generation of many types of binary distributions
177using EPM. To build a binary distribution type:
178
179 make <format> ENTER
180
181or
182
183 gmake <format> ENTER
184
185for FreeBSD, NetBSD, and OpenBSD. The <format> target is one of the following:
186
187- "epm": Builds a script + tarfile package
188- "bsd": Builds a *BSD package
189- "deb": Builds a Debian package
190- "pkg": Builds a Solaris package
191- "rpm": Builds a RPM package
192- "slackware": Build a Slackware package
193
194
195GETTING DEBUG LOGGING FROM CUPS
196-------------------------------
197
fd2f0a7a 198When configured with the `--enable-debug-printfs` option, CUPS compiles in
2a20b512
MS
199additional debug logging support in the scheduler, CUPS API, and CUPS Imaging
200API. The following environment variables are used to enable and control debug
201logging:
202
203- `CUPS_DEBUG_FILTER`: Specifies a POSIX regular expression to control which
204 messages are logged.
205- `CUPS_DEBUG_LEVEL`: Specifies a number from 0 to 9 to control the verbosity of
206 the logging. The default level is 1.
207- `CUPS_DEBUG_LOG`: Specifies a log file to use. Specify the name "-" to send
208 the messages to stderr. Prefix a filename with "+" to append to an existing
fd2f0a7a
MS
209 file. You can include a single "%d" in the filename to embed the current
210 process ID.
2a20b512
MS
211
212
213REPORTING PROBLEMS
214------------------
215
fd2f0a7a 216If you have problems, *read the documentation first*! If the documentation does
2a20b512
MS
217not solve your problems, please post a message on the users forum at:
218
219 https://www.cups.org/
220
221Include your operating system and version, compiler and version, and any errors
222or problems you've run into. The "config.log" file and the output from the
223configure script and make should also be sent, as it often helps to determine
224the cause of your problem.
225
226If you are running a version of Linux, be sure to provide the Linux distribution
227you have, too.