INSTALL.md

   1 INSTALL - CUPS v2.2.5 - 2017-09-25
   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 Using CUPS requires additional third-party support software and printer drivers.
   9 These are typically included with your operating system distribution.  Apple
  10 does not endorse or support third-party support software for CUPS.
  11
  12 > Note: Current versions of macOS DO NOT allow installation to /usr with the
  13 > default System Integrity Protection (SIP) settings.  In addition, we do not
  14 > recommend replacing the CUPS supplied with macOS because:
  15 >
  16 > a. not all versions of CUPS are compatible with every macOS release,
  17 >
  18 > b. code signing prevents replacement of system libraries and access to the
  19 >    system keychain (needed for encrypted printer sharing), and
  20 >
  21 > c. software updates will often replace parts of your local installation,
  22 >    potentially rendering your system unusable.
  23
  24
  25 BEFORE YOU BEGIN
  26 ----------------
  27
  28 You'll need ANSI-compliant C and C++ compilers, plus a make program and POSIX-
  29 compliant shell (/bin/sh).  The GNU compiler tools and Bash work well and we
  30 have tested the current CUPS code against several versions of GCC with excellent
  31 results.
  32
  33 The makefiles used by the project should work with most versions of make.  We've
  34 tested them with GNU make as well as the make programs shipped by Compaq, HP,
  35 SGI, and Sun.  BSD users should use GNU make (gmake) since BSD make does not
  36 support "include".
  37
  38 Besides these tools you'll want ZLIB library for compression support, the GNU
  39 TLS library for encryption support on platforms other than iOS, macOS, or
  40 Windows, and either MIT (1.6.3 or higher) or Heimdal Kerberos for Kerberos
  41 support.  CUPS will compile and run without these, however you'll miss out on
  42 many of the features provided by CUPS.
  43
  44 On a stock Ubuntu install, the following command will install the required
  45 prerequisites:
  46
  47     sudo apt-get install autoconf build-essential libavahi-client-dev \
  48          libgnutls28-dev libkrb5-dev libnss-mdns libpam-dev \
  49          libsystemd-dev libusb-1.0-0-dev zlib1g-dev
  50
  51 Also, please note that CUPS does not include print filters to support PDF or
  52 raster printing.  You *must* download GPL Ghostscript and/or the Open Printing
  53 CUPS filters package separately to print on operating systems other than macOS.
  54
  55
  56 CONFIGURATION
  57 -------------
  58
  59 CUPS uses GNU autoconf, so you should find the usual "configure" script in the
  60 main CUPS source directory.  To configure CUPS for your system, type:
  61
  62     ./configure
  63
  64 The default installation will put the CUPS software in the "/etc", "/usr", and
  65 "/var" directories on your system, which will overwrite any existing printing
  66 commands on your system.  Use the `--prefix` option to install the CUPS software
  67 in another location:
  68
  69     ./configure --prefix=/some/directory
  70
  71 > Note: Current versions of macOS DO NOT allow installation to /usr with the
  72 > default System Integrity Protection (SIP) settings.
  73
  74 To see a complete list of configuration options, use the `--help` option:
  75
  76     ./configure --help
  77
  78 If any of the dependent libraries are not installed in a system default location
  79 (typically "/usr/include" and "/usr/lib") you'll need to set the CFLAGS,
  80 CPPFLAGS, CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables prior to running
  81 configure:
  82
  83     setenv CFLAGS "-I/some/directory"
  84     setenv CPPFLAGS "-I/some/directory"
  85     setenv CXXFLAGS "-I/some/directory"
  86     setenv DSOFLAGS "-L/some/directory"
  87     setenv LDFLAGS "-L/some/directory"
  88     ./configure ...
  89
  90 or:
  91
  92     CFLAGS="-I/some/directory" \
  93     CPPFLAGS="-I/some/directory" \
  94     CXXFLAGS="-I/some/directory" \
  95     DSOFLAGS="-L/some/directory" \
  96     LDFLAGS="-L/some/directory" \
  97     ./configure ...
  98
  99 The `--enable-debug` option compiles CUPS with debugging information enabled.
 100 Additional debug logging support can be enabled using the
 101 `--enable-debug-printfs` option - these debug messages are enabled using the
 102 `CUPS_DEBUG_xxx` environment variables at run-time.
 103
 104 CUPS also includes an extensive set of unit tests that can be used to find and
 105 diagnose a variety of common problems - use the "--enable-unit-tests" configure
 106 option to run them at build time.
 107
 108 On macOS, use the `--with-archflags` option to build with the correct set of
 109 architectures:
 110
 111     ./configure --with-archflags="-arch i386 -arch x86_64" ...
 112
 113 Once you have configured things, just type:
 114
 115     make ENTER
 116
 117 or if you have FreeBSD, NetBSD, or OpenBSD type:
 118
 119     gmake ENTER
 120
 121 to build the software.
 122
 123
 124 TESTING THE SOFTWARE
 125 --------------------
 126
 127 Aside from the built-in unit tests, CUPS includes an automated test framework
 128 for testing the entire printing system.  To run the tests, just type:
 129
 130     make check ENTER
 131
 132 or if you have FreeBSD, NetBSD, or OpenBSD type:
 133
 134     gmake check ENTER
 135
 136 The test framework runs a copy of the CUPS scheduler (cupsd) on port 8631 in
 137 /tmp/cups-$USER and produces a nice HTML report of the results.
 138
 139
 140 INSTALLING THE SOFTWARE
 141 -----------------------
 142
 143 Once you have built the software you need to install it.  The "install" target
 144 provides a quick way to install the software on your local system:
 145
 146     make install ENTER
 147
 148 or for FreeBSD, NetBSD, or OpenBSD:
 149
 150     gmake install ENTER
 151
 152 Use the BUILDROOT variable to install to an alternate root directory:
 153
 154     make BUILDROOT=/some/other/root/directory install ENTER
 155
 156 You can also build binary packages that can be installed on other machines using
 157 the RPM spec file ("packaging/cups.spec") or EPM list file
 158 ("packaging/cups.list").  The latter also supports building of binary RPMs, so
 159 it may be more convenient to use.
 160
 161 You can find the RPM software at:
 162
 163     http://www.rpm.org/
 164
 165 The EPM software is available at:
 166
 167     https://michaelrsweet.github.io/epm
 168
 169
 170 CREATING BINARY DISTRIBUTIONS WITH EPM
 171 --------------------------------------
 172
 173 The top level makefile supports generation of many types of binary distributions
 174 using EPM.  To build a binary distribution type:
 175
 176     make <format> ENTER
 177
 178 or
 179
 180     gmake <format> ENTER
 181
 182 for FreeBSD, NetBSD, and OpenBSD.  The <format> target is one of the following:
 183
 184 - "epm": Builds a script + tarfile package
 185 - "bsd": Builds a *BSD package
 186 - "deb": Builds a Debian package
 187 - "pkg": Builds a Solaris package
 188 - "rpm": Builds a RPM package
 189 - "slackware": Build a Slackware package
 190
 191
 192 GETTING DEBUG LOGGING FROM CUPS
 193 -------------------------------
 194
 195 When configured with the `--enable-debug-printfs` option, CUPS compiles in
 196 additional debug logging support in the scheduler, CUPS API, and CUPS Imaging
 197 API.  The following environment variables are used to enable and control debug
 198 logging:
 199
 200 - `CUPS_DEBUG_FILTER`: Specifies a POSIX regular expression to control which
 201   messages are logged.
 202 - `CUPS_DEBUG_LEVEL`: Specifies a number from 0 to 9 to control the verbosity of
 203   the logging. The default level is 1.
 204 - `CUPS_DEBUG_LOG`: Specifies a log file to use.  Specify the name "-" to send
 205   the messages to stderr.  Prefix a filename with "+" to append to an existing
 206   file.  You can include a single "%d" in the filename to embed the current
 207   process ID.
 208
 209
 210 REPORTING PROBLEMS
 211 ------------------
 212
 213 If you have problems, *read the documentation first*!  If the documentation does
 214 not solve your problems, please post a message on the users forum at:
 215
 216     https://www.cups.org/
 217
 218 Include your operating system and version, compiler and version, and any errors
 219 or problems you've run into.  The "config.log" file and the output from the
 220 configure script and make should also be sent, as it often helps to determine
 221 the cause of your problem.
 222
 223 If you are running a version of Linux, be sure to provide the Linux distribution
 224 you have, too.