-INSTALL - CUPS v1.2.0 - 12/26/2001
+INSTALL - CUPS v1.7b1 - 2013-04-18
----------------------------------
-This file describes how to compile and install CUPS from source
-code. For more information on CUPS see the file called
-"README.txt". A complete change log can be found in
-"CHANGES.txt".
+This file describes how to compile and install CUPS from source code. For more
+information on CUPS see the file called "README.txt". A complete change log can
+be found in "CHANGES.txt".
+
+*******************************************************************************
+*******************************************************************************
+**** ****
+**** USING CUPS REQUIRES ADDITIONAL THIRD-PARTY SUPPORT SOFTWARE AND ****
+**** PRINTER DRIVERS. THESE ARE TYPICALLY INCLUDED WITH YOUR OPERATING ****
+**** SYSTEM DISTRIBUTION. APPLE DOES NOT ENDORSE OR SUPPORT THIRD-PARTY ****
+**** SUPPORT SOFTWARE FOR CUPS. ****
+**** ****
+*******************************************************************************
+*******************************************************************************
BEFORE YOU BEGIN
-You'll need ANSI-compliant C and C++ compilers, plus a make
-program and Bourne shell. The GNU compiler tools work well -
-we've tested the current CUPS code against GCC 2.95.x with
-excellent results.
+ You'll need ANSI-compliant C and C++ compilers, plus a make program and
+ POSIX-compliant shell (/bin/sh). The GNU compiler tools and Bash work well
+ and we have tested the current CUPS code against several versions of GCC
+ with excellent results.
+
+ The makefiles used by the project should work with most versions of make.
+ We've tested them with GNU make as well as the make programs shipped by
+ Compaq, HP, SGI, and Sun. BSD users should use GNU make (gmake) since BSD
+ make does not support "include".
+
+ Besides these tools you'll want ZLIB library for compression support, the
+ CDSA, GNU TLS, or OpenSSL libraries for encryption support, and either MIT
+ (1.6.3 or higher) or Heimdal Kerberos for Kerberos support. CUPS will
+ compile and run without these, however you'll miss out on many of the
+ features provided by CUPS.
+
+ Also, please note that CUPS does not include print filters to support PDF
+ or raster printing. You *must* download GPL Ghostscript and/or the Open
+ Printing CUPS filters package separately to print on operating systems
+ other than OS X.
-The makefiles used by the project should work with all versions
-of make. We've tested them with GNU make as well as the make
-programs shipped by Compaq, HP, SGI, and Sun. FreeBSD users
-should use GNU make (gmake).
-Besides these tools you'll want the following libraries:
+COMPILING THE SUBVERSION REPOSITORY CODE
- - JPEG 6b or higher
- - PNG 1.0.6 or higher
- - TIFF 3.4 or higher
- - ZLIB 1.1.3 or higher
+ The CUPS Subversion repository doesn't hold a copy of the pre-built
+ configure script. You'll need to run the GNU autoconf software (2.60 or
+ higher) to create it:
-CUPS will compile and run without these, however you'll miss out on
-many of the features provided by CUPS.
+ autoconf
CONFIGURATION
-CUPS uses GNU autoconf, so you should find the usual "configure"
-script in the main CUPS source directory. To configure CUPS for
-your system, type:
+ CUPS uses GNU autoconf, so you should find the usual "configure" script in
+ the main CUPS source directory. To configure CUPS for your system, type:
+
+ ./configure
+
+ The default installation will put the CUPS software in the "/etc", "/usr",
+ and "/var" directories on your system, which will overwrite any existing
+ printing commands on your system. Use the "--prefix" option to install the
+ CUPS software in another location:
+
+ ./configure --prefix=/some/directory
+
+ To see a complete list of configuration options, use the --help option:
- ./configure ENTER
+ ./configure --help
-The default installation will put the CUPS software in the
-"/etc", "/usr", and "/var" directories on your system, which
-will overwrite any existing printing commands on your system.
-Use the "--prefix" option to install the CUPS software in
-another location:
+ If any of the dependent libraries are not installed in a system default
+ location (typically "/usr/include" and "/usr/lib") you'll need to set the
+ CFLAGS, CPPFLAGS, CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables
+ prior to running configure:
- ./configure --prefix=/some/directory ENTER
+ setenv CFLAGS "-I/some/directory"
+ setenv CPPFLAGS "-I/some/directory"
+ setenv CXXFLAGS "-I/some/directory"
+ setenv DSOFLAGS "-L/some/directory"
+ setenv LDFLAGS "-L/some/directory"
+ ./configure ...
-If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in
-a system default location (typically "/usr/include" and
-"/usr/lib") you'll need to set the CFLAGS, CXXFLAGS, DSOFLAGS,
-and LDFLAGS environment variables prior to running configure:
+ or:
- setenv CFLAGS "-I/some/directory" ENTER
- setenv CXXFLAGS "-I/some/directory" ENTER
- setenv DSOFLAGS "-L/some/directory" ENTER
- setenv LDFLAGS "-L/some/directory" ENTER
- ./configure ... ENTER
+ CFLAGS="-I/some/directory" \
+ CPPFLAGS="-I/some/directory" \
+ CXXFLAGS="-I/some/directory" \
+ DSOFLAGS="-L/some/directory" \
+ LDFLAGS="-L/some/directory" \
+ ./configure ...
-or:
+ The "--enable-debug" option compiles CUPS with debugging information
+ enabled. Additional debug logging support can be enabled using the
+ "--enable-debug-printfs" option - these debug messages are enabled using the
+ CUPS_DEBUG_LOG environment variable at run-time.
- CFLAGS="-I/some/directory"; export CFLAGS ENTER
- CXXFLAGS="-I/some/directory"; export CXXFLAGS ENTER
- DSOFLAGS="-L/some/directory"; export DSOFLAGS ENTER
- LDFLAGS="-L/some/directory"; export LDFLAGS ENTER
- ./configure ... ENTER
+ CUPS also includes an extensive set of unit tests that can be used to find
+ and diagnose a variety of common problems - use the "--enable-unit-tests"
+ configure option to run them at build time.
-To enable support for encryption, you'll also want to add the
-"--enable-ssl" option:
+ Once you have configured things, just type:
- ./configure --enable-ssl
+ make ENTER
-SSL and TLS support require the OpenSSL library, available at:
+ or if you have FreeBSD, NetBSD, or OpenBSD type:
- http://www.openssl.org
+ gmake ENTER
-If the OpenSSL header files and libraries are not in a standard
-location, specify the locations of these files using the
---with-openssl-includes and --with-openssl-libs directives:
+ to build the software.
- ./configure --enable-ssl \
- --with-openssl-includes=/foo/bar/include \
- --with-openssl-libs=/foo/bar/lib
-See the file "ENCRYPTION.txt" for information on using the
-encryption support in CUPS.
+TESTING THE SOFTWARE
-Once you have configured things, just type:
+ Aside from the built-in unit tests, CUPS includes an automated test
+ framework for testing the entire printing system. To run the tests, just
+ type:
- make ENTER
+ make check ENTER
-or if you have FreeBSD, NetBSD, or OpenBSD type:
+ or if you have FreeBSD, NetBSD, or OpenBSD type:
- gmake ENTER
+ gmake check ENTER
-to build the software.
+ The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631
+ in /tmp/cups-$USER and produces a nice HTML report of the results.
INSTALLING THE SOFTWARE
-Once you have built the software you need to install it. The
-"install" target provides a quick way to install the software on
-your local system:
+ Once you have built the software you need to install it. The "install"
+ target provides a quick way to install the software on your local system:
- make install ENTER
+ make install ENTER
-or for FreeBSD, NetBSD, or OpenBSD:
+ or for FreeBSD, NetBSD, or OpenBSD:
- gmake install ENTER
+ gmake install ENTER
-You can also build binary packages that can be installed on other
-machines using the RPM spec file ("cups.spec") or EPM list file
-("cups.list"). The latter also supports building of binary RPMs,
-so it may be more convenient to use - we use EPM to build all of
-our binary distributions.
+ You can also build binary packages that can be installed on other machines
+ using the RPM spec file ("packaging/cups.spec") or EPM list file
+ ("packaging/cups.list"). The latter also supports building of binary RPMs,
+ so it may be more convenient to use.
-You can find the RPM software at:
+ You can find the RPM software at:
- http://www.rpm.org
+ http://www.rpm.org/
-The EPM software is at:
+ The EPM software is available at:
- http://www.easysw.com/epm/
+ http://www.epmhome.org/
CREATING BINARY DISTRIBUTIONS WITH EPM
-The top level makefile supports generation of many types of binary
-distributions using EPM. To build a binary distribution type:
+ The top level makefile supports generation of many types of binary
+ distributions using EPM. To build a binary distribution type:
- make <format> ENTER
+ make <format> ENTER
-or
+ or
- gmake <format> ENTER
+ gmake <format> ENTER
-for FreeBSD, NetBSD, and OpenBSD. The <format> target is one of
-the following:
+ for FreeBSD, NetBSD, and OpenBSD. The <format> target is one of the
+ following:
- epm - Builds a portable shell script and tar file based
- distribution. This format will also backup your
- existing printing system if you decide to remove
- CUPS at some future time.
- aix - Builds an AIX binary distribution.
- bsd - Builds a *BSD binary distribution.
- deb - Builds a Debian binary distribution.
- depot - Builds a HP-UX binary distribution.
- pkg - Builds a Solaris binary distribution.
- rpm - Builds a RPM binary distribution.
- tardist - Builds an IRIX binary distribution.
+ epm - Builds a script + tarfile package
+ aix - Builds an AIX package
+ bsd - Builds a *BSD package
+ deb - Builds a Debian package
+ depot - Builds a HP-UX package (also swinstall)
+ inst - Builds an IRIX package (also tardist)
+ pkg - Builds a Solaris package
+ rpm - Builds a RPM package
+ setld - Build a Tru64 UNIX package
+ slackware - Build a Slackware package
+ swinstall - Build a HP-UX package (also depot)
+ tardist - Builds an IRIX package (also inst)
+
+
+GETTING DEBUG LOGGING FROM CUPS
+
+ When configured with the "--enable-debug-printfs" option, CUPS compiles in
+ additional debug logging support in the scheduler, CUPS API, and CUPS
+ Imaging API. The following environment variables are used to enable and
+ control debug logging:
+
+ CUPS_DEBUG_FILTER Specifies a POSIX regular expression to control
+ which messages are logged.
+ CUPS_DEBUG_LEVEL Specifies a number from 0 to 9 to control the
+ verbosity of the logging. The default level is 1.
+ CUPS_DEBUG_LOG Specifies a log file to use. Specify the name "-"
+ to send the messages to stderr. Prefix a filename
+ with "+" to append to an existing file.
REPORTING PROBLEMS
-If you have problems, READ THE DOCUMENTATION FIRST! If the
-documentation does not solve your problems please send an email
-to "cups-support@cups.org". Include your operating system and
-version, compiler and version, and any errors or problems you've
-run into. The "/var/log/cups/error_log" file should also be sent,
-as it often helps to determine the cause of your problem.
-
-If you are running a version of Linux, be sure to provide the
-Linux distribution you have, too.
-
-Please note that the "cups-support@cups.org" email address goes
-to the CUPS developers; they are busy people, so your email may
-go unanswered for days or weeks. In general, only general build
-or distribution problems will actually get answered - for
-end-user support see the "README.txt" for a summary of the
-resources available.
+ If you have problems, READ THE DOCUMENTATION FIRST! If the documentation
+ does not solve your problems, please post a message on the "cups.general"
+ forum at:
+
+ http://www.cups.org/newsgroups.php
+
+ Include your operating system and version, compiler and version, and any
+ errors or problems you've run into. The "config.log" file and the output
+ from the configure script and make should also be sent, as it often helps to
+ determine the cause of your problem.
+
+ If you are running a version of Linux, be sure to provide the Linux
+ distribution you have, too.
projects / thirdparty / cups.git / blobdiff