INSTALL.txt

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