INSTALL.md

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