INSTALL.md

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