INSTALL.txt

   1 INSTALL - CUPS v1.7b1 - 2013-04-18
   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.epmhome.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 "cups.general"
 201     forum at:
 202
 203         http://www.cups.org/newsgroups.php
 204
 205     Include your operating system and version, compiler and version, and any
 206     errors or problems you've run into.  The "config.log" file and the output
 207     from the configure script and make should also be sent, as it often helps to
 208     determine the cause of your problem.
 209
 210     If you are running a version of Linux, be sure to provide the Linux
 211     distribution you have, too.