INSTALL.txt

   1 INSTALL - CUPS v2.2rc1 - 2016-08-08
   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     GNU TLS library for encryption support on platforms other than iOS, macOS,
  34     or Windows, and either MIT (1.6.3 or higher) or Heimdal Kerberos for
  35     Kerberos support.  CUPS will compile and run without these, however you'll
  36     miss out on many of the 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 macOS.
  42
  43
  44 CONFIGURATION
  45
  46     CUPS uses GNU autoconf, so you should find the usual "configure" script in
  47     the main CUPS source directory.  To configure CUPS for your system, type:
  48
  49         ./configure
  50
  51     The default installation will put the CUPS software in the "/etc", "/usr",
  52     and "/var" directories on your system, which will overwrite any existing
  53     printing commands on your system.  Use the "--prefix" option to install the
  54     CUPS software in another location:
  55
  56         ./configure --prefix=/some/directory
  57
  58     To see a complete list of configuration options, use the --help option:
  59
  60         ./configure --help
  61
  62     If any of the dependent libraries are not installed in a system default
  63     location (typically "/usr/include" and "/usr/lib") you'll need to set the
  64     CFLAGS, CPPFLAGS, CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables
  65     prior to running configure:
  66
  67         setenv CFLAGS "-I/some/directory"
  68         setenv CPPFLAGS "-I/some/directory"
  69         setenv CXXFLAGS "-I/some/directory"
  70         setenv DSOFLAGS "-L/some/directory"
  71         setenv LDFLAGS "-L/some/directory"
  72         ./configure ...
  73
  74     or:
  75
  76         CFLAGS="-I/some/directory" \
  77         CPPFLAGS="-I/some/directory" \
  78         CXXFLAGS="-I/some/directory" \
  79         DSOFLAGS="-L/some/directory" \
  80         LDFLAGS="-L/some/directory" \
  81         ./configure ...
  82
  83     The "--enable-debug" option compiles CUPS with debugging information
  84     enabled.  Additional debug logging support can be enabled using the
  85     "--enable-debug-printfs" option - these debug messages are enabled using the
  86     CUPS_DEBUG_LOG environment variable at run-time.
  87
  88     CUPS also includes an extensive set of unit tests that can be used to find
  89     and diagnose a variety of common problems - use the "--enable-unit-tests"
  90     configure option to run them at build time.
  91
  92     On macOS, use the "--with-archflags" option to build with the correct set of
  93     architectures:
  94
  95         ./configure --with-archflags="-arch i386 -arch x86_64" ...
  96
  97         Note: Current versions of macOS DO NOT allow installation to
  98         /usr with the default system integrity settings.  In addition,
  99         we do not recommend replacing the CUPS supplied with macOS
 100         because not all versions of CUPS are compatible with every
 101         macOS release, and because software updates will replace parts
 102         of your local installation potentially rendering your system
 103         unusable.
 104
 105     Once you have configured things, just type:
 106
 107         make ENTER
 108
 109     or if you have FreeBSD, NetBSD, or OpenBSD type:
 110
 111         gmake ENTER
 112
 113     to build the software.
 114
 115
 116 TESTING THE SOFTWARE
 117
 118     Aside from the built-in unit tests, CUPS includes an automated test
 119     framework for testing the entire printing system.  To run the tests, just
 120     type:
 121
 122         make check ENTER
 123
 124     or if you have FreeBSD, NetBSD, or OpenBSD type:
 125
 126         gmake check ENTER
 127
 128     The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631
 129     in /tmp/cups-$USER and produces a nice HTML report of the results.
 130
 131
 132 INSTALLING THE SOFTWARE
 133
 134     Once you have built the software you need to install it.  The "install"
 135     target provides a quick way to install the software on your local system:
 136
 137         make install ENTER
 138
 139     or for FreeBSD, NetBSD, or OpenBSD:
 140
 141         gmake install ENTER
 142
 143     Use the BUILDROOT variable to install to an alternate root directory:
 144
 145         make BUILDROOT=/some/other/root/directory install ENTER
 146
 147     You can also build binary packages that can be installed on other machines
 148     using the RPM spec file ("packaging/cups.spec") or EPM list file
 149     ("packaging/cups.list").  The latter also supports building of binary RPMs,
 150     so it may be more convenient to use.
 151
 152     You can find the RPM software at:
 153
 154         http://www.rpm.org/
 155
 156     The EPM software is available at:
 157
 158         http://www.msweet.org/
 159
 160
 161 CREATING BINARY DISTRIBUTIONS WITH EPM
 162
 163     The top level makefile supports generation of many types of binary
 164     distributions using EPM.  To build a binary distribution type:
 165
 166         make <format> ENTER
 167
 168     or
 169
 170         gmake <format> ENTER
 171
 172     for FreeBSD, NetBSD, and OpenBSD.  The <format> target is one of the
 173     following:
 174
 175         epm       - Builds a script + tarfile package
 176         bsd       - Builds a *BSD package
 177         deb       - Builds a Debian package
 178         pkg       - Builds a Solaris package
 179         rpm       - Builds a RPM package
 180         slackware - Build a Slackware package
 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 users forum at:
 203
 204         http://www.cups.org/
 205
 206     Include your operating system and version, compiler and version, and any
 207     errors or problems you've run into.  The "config.log" file and the output
 208     from the configure script and make should also be sent, as it often helps to
 209     determine the cause of your problem.
 210
 211     If you are running a version of Linux, be sure to provide the Linux
 212     distribution you have, too.