]> git.ipfire.org Git - thirdparty/cups.git/blob - INSTALL.txt
Add more debug stuff.
[thirdparty/cups.git] / INSTALL.txt
1 INSTALL - CUPS v2.0.0 - 2013-08-06
2 ----------------------------------
3
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".
7
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 *******************************************************************************
18
19
20 BEFORE YOU BEGIN
21
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.
26
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".
31
32 Besides these tools you'll want ZLIB library for compression support, the
33 CDSA, GNU TLS, or OpenSSL libraries for encryption support, and either MIT
34 (1.6.3 or higher) or Heimdal Kerberos for Kerberos support. CUPS will
35 compile and run without these, however you'll miss out on many of the
36 features provided by CUPS.
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
41 other than OS X.
42
43
44 COMPILING THE SUBVERSION REPOSITORY CODE
45
46 The CUPS Subversion repository doesn't hold a copy of the pre-built
47 configure script. You'll need to run the GNU autoconf software (2.60 or
48 higher) to create it:
49
50 autoconf
51
52
53 CONFIGURATION
54
55 CUPS uses GNU autoconf, so you should find the usual "configure" script in
56 the main CUPS source directory. To configure CUPS for your system, type:
57
58 ./configure
59
60 The default installation will put the CUPS software in the "/etc", "/usr",
61 and "/var" directories on your system, which will overwrite any existing
62 printing commands on your system. Use the "--prefix" option to install the
63 CUPS software in another location:
64
65 ./configure --prefix=/some/directory
66
67 To see a complete list of configuration options, use the --help option:
68
69 ./configure --help
70
71 If any of the dependent libraries are not installed in a system default
72 location (typically "/usr/include" and "/usr/lib") you'll need to set the
73 CFLAGS, CPPFLAGS, CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables
74 prior to running configure:
75
76 setenv CFLAGS "-I/some/directory"
77 setenv CPPFLAGS "-I/some/directory"
78 setenv CXXFLAGS "-I/some/directory"
79 setenv DSOFLAGS "-L/some/directory"
80 setenv LDFLAGS "-L/some/directory"
81 ./configure ...
82
83 or:
84
85 CFLAGS="-I/some/directory" \
86 CPPFLAGS="-I/some/directory" \
87 CXXFLAGS="-I/some/directory" \
88 DSOFLAGS="-L/some/directory" \
89 LDFLAGS="-L/some/directory" \
90 ./configure ...
91
92 The "--enable-debug" option compiles CUPS with debugging information
93 enabled. Additional debug logging support can be enabled using the
94 "--enable-debug-printfs" option - these debug messages are enabled using the
95 CUPS_DEBUG_LOG environment variable at run-time.
96
97 CUPS also includes an extensive set of unit tests that can be used to find
98 and diagnose a variety of common problems - use the "--enable-unit-tests"
99 configure option to run them at build time.
100
101 Once you have configured things, just type:
102
103 make ENTER
104
105 or if you have FreeBSD, NetBSD, or OpenBSD type:
106
107 gmake ENTER
108
109 to build the software.
110
111
112 TESTING THE SOFTWARE
113
114 Aside from the built-in unit tests, CUPS includes an automated test
115 framework for testing the entire printing system. To run the tests, just
116 type:
117
118 make check ENTER
119
120 or if you have FreeBSD, NetBSD, or OpenBSD type:
121
122 gmake check ENTER
123
124 The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631
125 in /tmp/cups-$USER and produces a nice HTML report of the results.
126
127
128 INSTALLING THE SOFTWARE
129
130 Once you have built the software you need to install it. The "install"
131 target provides a quick way to install the software on your local system:
132
133 make install ENTER
134
135 or for FreeBSD, NetBSD, or OpenBSD:
136
137 gmake install ENTER
138
139 You can also build binary packages that can be installed on other machines
140 using the RPM spec file ("packaging/cups.spec") or EPM list file
141 ("packaging/cups.list"). The latter also supports building of binary RPMs,
142 so it may be more convenient to use.
143
144 You can find the RPM software at:
145
146 http://www.rpm.org/
147
148 The EPM software is available at:
149
150 http://www.msweet.org/
151
152
153 CREATING BINARY DISTRIBUTIONS WITH EPM
154
155 The top level makefile supports generation of many types of binary
156 distributions using EPM. To build a binary distribution type:
157
158 make <format> ENTER
159
160 or
161
162 gmake <format> ENTER
163
164 for FreeBSD, NetBSD, and OpenBSD. The <format> target is one of the
165 following:
166
167 epm - Builds a script + tarfile package
168 aix - Builds an AIX package
169 bsd - Builds a *BSD package
170 deb - Builds a Debian package
171 depot - Builds a HP-UX package (also swinstall)
172 inst - Builds an IRIX package (also tardist)
173 pkg - Builds a Solaris package
174 rpm - Builds a RPM package
175 setld - Build a Tru64 UNIX package
176 slackware - Build a Slackware package
177 swinstall - Build a HP-UX package (also depot)
178 tardist - Builds an IRIX package (also inst)
179
180
181 GETTING DEBUG LOGGING FROM CUPS
182
183 When configured with the "--enable-debug-printfs" option, CUPS compiles in
184 additional debug logging support in the scheduler, CUPS API, and CUPS
185 Imaging API. The following environment variables are used to enable and
186 control debug logging:
187
188 CUPS_DEBUG_FILTER Specifies a POSIX regular expression to control
189 which messages are logged.
190 CUPS_DEBUG_LEVEL Specifies a number from 0 to 9 to control the
191 verbosity of the logging. The default level is 1.
192 CUPS_DEBUG_LOG Specifies a log file to use. Specify the name "-"
193 to send the messages to stderr. Prefix a filename
194 with "+" to append to an existing file.
195
196
197 REPORTING PROBLEMS
198
199 If you have problems, READ THE DOCUMENTATION FIRST! If the documentation
200 does not solve your problems, please post a message on the users forum at:
201
202 http://www.cups.org/
203
204 Include your operating system and version, compiler and version, and any
205 errors or problems you've run into. The "config.log" file and the output
206 from the configure script and make should also be sent, as it often helps to
207 determine the cause of your problem.
208
209 If you are running a version of Linux, be sure to provide the Linux
210 distribution you have, too.