INSTALL.txt

   1 INSTALL - CUPS v2.2b1 - 2016-05-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     Use the BUILDROOT variable to install to an alternate root directory:
 145
 146         make BUILDROOT=/some/other/root/directory install ENTER
 147
 148     You can also build binary packages that can be installed on other machines
 149     using the RPM spec file ("packaging/cups.spec") or EPM list file
 150     ("packaging/cups.list").  The latter also supports building of binary RPMs,
 151     so it may be more convenient to use.
 152
 153     You can find the RPM software at:
 154
 155         http://www.rpm.org/
 156
 157     The EPM software is available at:
 158
 159         http://www.msweet.org/
 160
 161
 162 CREATING BINARY DISTRIBUTIONS WITH EPM
 163
 164     The top level makefile supports generation of many types of binary
 165     distributions using EPM.  To build a binary distribution type:
 166
 167         make <format> ENTER
 168
 169     or
 170
 171         gmake <format> ENTER
 172
 173     for FreeBSD, NetBSD, and OpenBSD.  The <format> target is one of the
 174     following:
 175
 176         epm       - Builds a script + tarfile package
 177         bsd       - Builds a *BSD package
 178         deb       - Builds a Debian package
 179         pkg       - Builds a Solaris package
 180         rpm       - Builds a RPM package
 181         slackware - Build a Slackware package
 182
 183
 184 GETTING DEBUG LOGGING FROM CUPS
 185
 186     When configured with the "--enable-debug-printfs" option, CUPS compiles in
 187     additional debug logging support in the scheduler, CUPS API, and CUPS
 188     Imaging API.  The following environment variables are used to enable and
 189     control debug logging:
 190
 191         CUPS_DEBUG_FILTER  Specifies a POSIX regular expression to control
 192                            which messages are logged.
 193         CUPS_DEBUG_LEVEL   Specifies a number from 0 to 9 to control the
 194                            verbosity of the logging. The default level is 1.
 195         CUPS_DEBUG_LOG     Specifies a log file to use.  Specify the name "-"
 196                            to send the messages to stderr.  Prefix a filename
 197                            with "+" to append to an existing file.
 198
 199
 200 REPORTING PROBLEMS
 201
 202     If you have problems, READ THE DOCUMENTATION FIRST!  If the documentation
 203     does not solve your problems, please post a message on the users forum at:
 204
 205         http://www.cups.org/
 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.