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