INSTALL.txt

   1 INSTALL - CUPS v1.5.3 - 2012-05-15
   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 **** 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.                                                  ****
  12
  13
  14 BEFORE YOU BEGIN
  15
  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.
  20
  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".
  25
  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.
  32
  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.
  38
  39
  40 COMPILING THE SUBVERSION REPOSITORY CODE
  41
  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:
  45
  46         autoconf
  47
  48
  49 CONFIGURATION
  50
  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:
  53
  54         ./configure
  55
  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:
  60
  61         ./configure --prefix=/some/directory
  62
  63     To see a complete list of configuration options, use the --help option:
  64
  65         ./configure --help
  66
  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:
  71
  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 ...
  78
  79     or:
  80
  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 ...
  87
  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.
  96
  97     Once you have configured things, just type:
  98
  99         make ENTER
 100
 101     or if you have FreeBSD, NetBSD, or OpenBSD type:
 102
 103         gmake ENTER
 104
 105     to build the software.
 106
 107
 108 TESTING 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
 124 INSTALLING THE SOFTWARE
 125
 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:
 128
 129         make install ENTER
 130
 131     or for FreeBSD, NetBSD, or OpenBSD:
 132
 133         gmake install ENTER
 134
 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.
 139
 140     You can find the RPM software at:
 141
 142         http://www.rpm.org/
 143
 144     The EPM software is available at:
 145
 146         http://www.epmhome.org/
 147
 148
 149 CREATING BINARY DISTRIBUTIONS WITH EPM
 150
 151     The top level makefile supports generation of many types of binary
 152     distributions using EPM.  To build a binary distribution type:
 153
 154         make <format> ENTER
 155
 156     or
 157
 158         gmake <format> ENTER
 159
 160     for FreeBSD, NetBSD, and OpenBSD.  The <format> target is one of the
 161     following:
 162
 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)
 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)
 175
 176
 177 GETTING DEBUG LOGGING FROM CUPS
 178
 179     When configured with the "--enable-debug-printfs" option, CUPS compiles in
 180     additional debug logging support in the scheduler, CUPS API, and CUPS
 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.
 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.
 191
 192
 193 REPORTING PROBLEMS
 194
 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:
 198
 199         http://www.cups.org/newsgroups.php
 200
 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.
 205
 206     If you are running a version of Linux, be sure to provide the Linux
 207     distribution you have, too.