]> git.ipfire.org Git - thirdparty/cups.git/blame - INSTALL.txt
Update documentation and dependencies for 1.5b1.
[thirdparty/cups.git] / INSTALL.txt
CommitLineData
a1a2e89a 1INSTALL - CUPS v1.5b1 - 2011-05-11
729c4d7d 2----------------------------------
61bdcfa6 3
639ca68a 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".
61bdcfa6 7
67774b09 8**** IF YOU HAVE A NON-POSTSCRIPT PRINTER AND ARE NOT ****
9**** RUNNING MAC OS X, YOU WILL ALSO NEED TO INSTALL GPL ****
10**** GHOSTSCRIPT WITH THE "cups" DRIVER AFTER YOU INSTALL ****
11**** CUPS. ****
c5488f2f 12
61bdcfa6 13
14BEFORE YOU BEGIN
15
639ca68a 16 You'll need ANSI-compliant C and C++ compilers, plus a make program and
17 POSIX-compliant shell (/bin/sh). The GNU compiler tools and Bash work well
18 and we have tested the current CUPS code against several versions of GCC
19 with excellent results.
61bdcfa6 20
639ca68a 21 The makefiles used by the project should work with most versions of make.
22 We've tested them with GNU make as well as the make programs shipped by
23 Compaq, HP, SGI, and Sun. BSD users should use GNU make (gmake) since BSD
24 make does not support "include".
61bdcfa6 25
639ca68a 26 Besides these tools you'll want the JPEG, PNG, TIFF, and ZLIB libraries for
27 image support, the CDSA, GNU TLS, or OpenSSL libraries for encryption
28 support, the OpenLDAP and OpenSLP libraries for directory services support,
29 and either MIT (1.6.3 or higher) or Heimdal Kerberos for Kerberos support.
30 CUPS will compile and run without these, however you'll miss out on many of
31 the features provided by CUPS.
61bdcfa6 32
639ca68a 33 Also, please note that CUPS does not include the Ghostscript-based
34 PostScript filter needed by non-PostScript printers. You *must* download
35 GPL Ghostscript separately from the CUPS web site if you want to print
36 PostScript files to non-PostScript printers on operating systems other than
37 Mac OS X.
f3955b6b 38
61bdcfa6 39
639ca68a 40COMPILING THE SUBVERSION REPOSITORY CODE
61bdcfa6 41
639ca68a 42 The CUPS Subversion repository doesn't hold a copy of the pre-built
43 configure script. You'll need to run the GNU autoconf software (2.60 or
44 higher) to create it:
61bdcfa6 45
729c4d7d 46 autoconf
415199da 47
48
61bdcfa6 49CONFIGURATION
50
639ca68a 51 CUPS uses GNU autoconf, so you should find the usual "configure" script in
52 the main CUPS source directory. To configure CUPS for your system, type:
93d2f0c0 53
781996c9 54 ./configure
93d2f0c0 55
639ca68a 56 The default installation will put the CUPS software in the "/etc", "/usr",
57 and "/var" directories on your system, which will overwrite any existing
58 printing commands on your system. Use the "--prefix" option to install the
59 CUPS software in another location:
93d2f0c0 60
781996c9 61 ./configure --prefix=/some/directory
93d2f0c0 62
639ca68a 63 To see a complete list of configuration options, use the --help option:
93d2f0c0 64
781996c9 65 ./configure --help
7428af94 66
639ca68a 67 If any of the dependent libraries are not installed in a system default
68 location (typically "/usr/include" and "/usr/lib") you'll need to set the
69 CFLAGS, CPPFLAGS, CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables
70 prior to running configure:
7428af94 71
781996c9 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 ...
7428af94 78
781996c9 79 or:
7428af94 80
781996c9 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 ...
753453e4 87
639ca68a 88 The "--enable-debug" option compiles CUPS with debugging information
89 enabled. Additional debug logging support can be enabled using the
90 "--enable-debug-printfs" option - these debug messages are enabled using the
91 CUPS_DEBUG_LOG environment variable at run-time.
92
93 CUPS also includes an extensive set of unit tests that can be used to find
94 and diagnose a variety of common problems - use the "--enable-unit-tests"
95 configure option to run them at build time.
3ba676e9 96
781996c9 97 Once you have configured things, just type:
753453e4 98
781996c9 99 make ENTER
1c9e0181 100
781996c9 101 or if you have FreeBSD, NetBSD, or OpenBSD type:
93d2f0c0 102
781996c9 103 gmake ENTER
93d2f0c0 104
781996c9 105 to build the software.
93d2f0c0 106
107
639ca68a 108TESTING THE SOFTWARE
109
110 Aside from the built-in unit tests, CUPS includes an automated test
111 framework for testing the entire printing system. To run the tests, just
112 type:
113
114 make check ENTER
115
116 or if you have FreeBSD, NetBSD, or OpenBSD type:
117
118 gmake check ENTER
119
120 The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631
121 in /tmp/cups-$USER and produces a nice HTML report of the results.
122
123
93d2f0c0 124INSTALLING THE SOFTWARE
125
639ca68a 126 Once you have built the software you need to install it. The "install"
127 target provides a quick way to install the software on your local system:
93d2f0c0 128
781996c9 129 make install ENTER
93d2f0c0 130
781996c9 131 or for FreeBSD, NetBSD, or OpenBSD:
93d2f0c0 132
781996c9 133 gmake install ENTER
93d2f0c0 134
639ca68a 135 You can also build binary packages that can be installed on other machines
136 using the RPM spec file ("packaging/cups.spec") or EPM list file
137 ("packaging/cups.list"). The latter also supports building of binary RPMs,
138 so it may be more convenient to use.
93d2f0c0 139
781996c9 140 You can find the RPM software at:
93d2f0c0 141
781996c9 142 http://www.rpm.org/
93d2f0c0 143
781996c9 144 The EPM software is available at:
93d2f0c0 145
639ca68a 146 http://www.epmhome.org/
93d2f0c0 147
148
149CREATING BINARY DISTRIBUTIONS WITH EPM
150
781996c9 151 The top level makefile supports generation of many types of binary
152 distributions using EPM. To build a binary distribution type:
93d2f0c0 153
781996c9 154 make <format> ENTER
93d2f0c0 155
781996c9 156 or
93d2f0c0 157
781996c9 158 gmake <format> ENTER
93d2f0c0 159
639ca68a 160 for FreeBSD, NetBSD, and OpenBSD. The <format> target is one of the
161 following:
93d2f0c0 162
781996c9 163 epm - Builds a script + tarfile package
164 aix - Builds an AIX package
165 bsd - Builds a *BSD package
166 deb - Builds a Debian package
167 depot - Builds a HP-UX package (also swinstall)
168 inst - Builds an IRIX package (also tardist)
781996c9 169 pkg - Builds a Solaris package
170 rpm - Builds a RPM package
171 setld - Build a Tru64 UNIX package
172 slackware - Build a Slackware package
173 swinstall - Build a HP-UX package (also depot)
174 tardist - Builds an IRIX package (also inst)
93d2f0c0 175
176
3ba676e9 177GETTING DEBUG LOGGING FROM CUPS
178
639ca68a 179 When configured with the "--enable-debug-printfs" option, CUPS compiles in
180 additional debug logging support in the scheduler, CUPS API, and CUPS
571af0ea 181 Imaging API. The following environment variables are used to enable and
182 control debug logging:
183
184 CUPS_DEBUG_FILTER Specifies a POSIX regular expression to control
185 which messages are logged.
186 CUPS_DEBUG_LEVEL Specifies a number from 0 to 9 to control the
187 verbosity of the logging. The default level is 1.
aa14682a 188 CUPS_DEBUG_LOG Specifies a log file to use. Specify the name "-"
189 to send the messages to stderr. Prefix a filename
190 with "+" to append to an existing file.
3ba676e9 191
192
93d2f0c0 193REPORTING PROBLEMS
194
639ca68a 195 If you have problems, READ THE DOCUMENTATION FIRST! If the documentation
196 does not solve your problems, please post a message on the "cups.general"
197 forum at:
781996c9 198
199 http://www.cups.org/newsgroups.php
200
639ca68a 201 Include your operating system and version, compiler and version, and any
202 errors or problems you've run into. The "config.log" file and the output
203 from the configure script and make should also be sent, as it often helps to
204 determine the cause of your problem.
781996c9 205
639ca68a 206 If you are running a version of Linux, be sure to provide the Linux
207 distribution you have, too.