INSTALL.txt

   1 INSTALL - CUPS v2.1b1 - 2014-10-31
   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     On OS X, use the "--with-archflags" option to build with the correct set of
 102     architectures:
 103
 104         ./configure --with-archflags="-arch i386 -arch x86_64" ...
 105
 106     Once you have configured things, just type:
 107
 108         make ENTER
 109
 110     or if you have FreeBSD, NetBSD, or OpenBSD type:
 111
 112         gmake ENTER
 113
 114     to build the software.
 115
 116
 117 TESTING THE SOFTWARE
 118
 119     Aside from the built-in unit tests, CUPS includes an automated test
 120     framework for testing the entire printing system.  To run the tests, just
 121     type:
 122
 123         make check ENTER
 124
 125     or if you have FreeBSD, NetBSD, or OpenBSD type:
 126
 127         gmake check ENTER
 128
 129     The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631
 130     in /tmp/cups-$USER and produces a nice HTML report of the results.
 131
 132
 133 INSTALLING THE SOFTWARE
 134
 135     Once you have built the software you need to install it.  The "install"
 136     target provides a quick way to install the software on your local system:
 137
 138         make install ENTER
 139
 140     or for FreeBSD, NetBSD, or OpenBSD:
 141
 142         gmake install ENTER
 143
 144     You can also build binary packages that can be installed on other machines
 145     using the RPM spec file ("packaging/cups.spec") or EPM list file
 146     ("packaging/cups.list").  The latter also supports building of binary RPMs,
 147     so it may be more convenient to use.
 148
 149     You can find the RPM software at:
 150
 151         http://www.rpm.org/
 152
 153     The EPM software is available at:
 154
 155         http://www.msweet.org/
 156
 157
 158 CREATING BINARY DISTRIBUTIONS WITH EPM
 159
 160     The top level makefile supports generation of many types of binary
 161     distributions using EPM.  To build a binary distribution type:
 162
 163         make <format> ENTER
 164
 165     or
 166
 167         gmake <format> ENTER
 168
 169     for FreeBSD, NetBSD, and OpenBSD.  The <format> target is one of the
 170     following:
 171
 172         epm       - Builds a script + tarfile package
 173         bsd       - Builds a *BSD package
 174         deb       - Builds a Debian package
 175         pkg       - Builds a Solaris package
 176         rpm       - Builds a RPM package
 177         slackware - Build a Slackware package
 178
 179
 180 GETTING DEBUG LOGGING FROM CUPS
 181
 182     When configured with the "--enable-debug-printfs" option, CUPS compiles in
 183     additional debug logging support in the scheduler, CUPS API, and CUPS
 184     Imaging API.  The following environment variables are used to enable and
 185     control debug logging:
 186
 187         CUPS_DEBUG_FILTER  Specifies a POSIX regular expression to control
 188                            which messages are logged.
 189         CUPS_DEBUG_LEVEL   Specifies a number from 0 to 9 to control the
 190                            verbosity of the logging. The default level is 1.
 191         CUPS_DEBUG_LOG     Specifies a log file to use.  Specify the name "-"
 192                            to send the messages to stderr.  Prefix a filename
 193                            with "+" to append to an existing file.
 194
 195
 196 REPORTING PROBLEMS
 197
 198     If you have problems, READ THE DOCUMENTATION FIRST!  If the documentation
 199     does not solve your problems, please post a message on the users forum at:
 200
 201         http://www.cups.org/
 202
 203     Include your operating system and version, compiler and version, and any
 204     errors or problems you've run into.  The "config.log" file and the output
 205     from the configure script and make should also be sent, as it often helps to
 206     determine the cause of your problem.
 207
 208     If you are running a version of Linux, be sure to provide the Linux
 209     distribution you have, too.