1Welcome to Gutenprint 5.3.3! Please read these notes carefully.
2
3*** NOTE TO PACKAGERS: Please read the file README.package for issues
4 that are of interest to distributors and packagers of Gutenprint.
5 It is not necessary for end users of Gutenprint to read this file.
6
7================================================================
8
9I) INTRODUCTION
10
11 Gutenprint is a suite of printer drivers for UNIX, Linux, and
12 Macintosh OS X systems (10.6 and above) that use CUPS as their
13 printing system. Gutenprint currently supports over 3000
14 printers. It also includes an enhanced Print plug-in for GIMP
15 that replaces the print plug-in packaged with the GIMP
16 distribution.
17
18 Gutenprint was renamed from its original name of Gimp-Print in
19 order to clearly distinguish it from GIMP. While this package
20 started out as the Print plugin for GIMP, it has expanded into a
21 collection of general purpose printer drivers, and the enhanced
22 Print plugin for GIMP is now only a small part of the package.
23 Furthermore, the name Gutenprint recognizes Johannes Gutenberg,
24 the inventor of the movable type printing press. Finally, the
25 word "guten" means "good" in German.
26
27 Please read the user's manual (doc/gutenprint-users-manual.pdf)
28 carefully, as it covers much more information than this README
29 file. In addition, please read the release notes (NEWS), as it
30 has information on the latest changes.
31
32 Gutenprint supports only the printer part of multi-function
33 devices (devices that typically include scanning, copying, and fax
34 capabilities).
35
36 We recommend that all users who wish to use this package for
37 general purpose printing use CUPS. CUPS provides an excellent
38 web-based interface for easy printer administration, and all
39 CUPS-enabled applications (OpenOffice.org, all KDE apps, etc.) and
40 printing dialogs (kprinter, xpp, etc.) show all the options in
41 easy to use GUIs. Please visit http://www.cups.org/ for
42 information on downloading and installing CUPS.
43
44
45================================================================
46
47II) INSTALLATION
48
49 This section is provided for people installing the package from
50 source. If you are installing from a pre-compiled package (such
51 as the Macintosh OS X package, or a package provided by your
52 distribution vendor), you may skip this section.
53
54 Installing packages from source requires some level of system
55 administration skills along with superuser privileges. Superuser
56 privilege allows you to perform actions that may be damaging to
57 your system. If you are not comfortable with the material
58 discussed here and in the release notes, or with performing simple
59 administrative actions, we recommend that you not attempt to
60 install this package from source.
61
62 If you are building Gutenprint from the CVS repository, you need
63 to take some additional steps. Please read doc/README.maintaining
64 for instructions on how to build from CVS.
65
66 Before beginning, please read the release notes carefully for any
67 updates.
68
69----------------
70
71A) OVERVIEW
72
73 Gutenprint includes the following primary components:
74
75 - The core driver library (required for everything else)
76 - A CUPS (Common UNIX Printing System) driver
77 - A CUPS backend, required for selected dye-sublimation printers
78 - A command-line utility to administer and maintain Epson
79 printers
80 - An enhanced Print plug-in for GIMP
81 - GTK-based UI libraries (used by the enhanced GIMP plug-in)
82
83 This package requires the use of GNU Make to compile. On systems
84 with both GNU make and another make installed, GNU make may be
85 named `gmake' or `gnumake'. BSD users in particular must take
86 care to use 'gmake'.
87
88 The general procedure to build Gutenprint is as follows:
89
90 ./configure [options]
91 make
92 make install
93
94 The "configure" script, which must be run before doing anything
95 else, controls which of these components are built along with any
96 options desired. This script determines what software is
97 installed on your system and what components will be compatible
98 with it, and prepares the package to be built and installed. If
99 the script emits any warnings or errors, please be certain that
100 you understand them before proceeding.
101
102 After the configure script has completed its work, it will print
103 a summary of its choices. Please ensure that it is correct before
104 proceeding. The summary looks like this:
105
106 Configuration Summary:
107 ------------- --------
108
109 If you have any problems, please report the information below to
110 gimp-print-devel@lists.sourceforge.net
111
112 ================================================================
113 Release: gutenprint 5.3.3 generated on 25 Aug 2019
114 Generated at Sun Aug 25 11:11:14 EDT 2019 by rlk
115
116 Features:
117 Build CUPS: yes, installing in /usr
118 Build CUPS 1.2 enhancements: yes
119 Build CUPS PPD files: no
120 Generate PS level 3 CUPS PPD files: yes
121 Build genppd statically: yes
122 Build CUPS dyesub USB backend: yes
123 Build EPSON inkjet utility: yes
124 Build enhanced Print plugin for GIMP: yes
125 GIMP plugin will be named: gutenprint
126 Install plugin(s) in home directory: no
127 Build test programs: yes
128 Build testpattern generator: yes
129
130 Installation summary:
131 Installation prefix: /usr/local
132 Exec prefix: /usr/local (${prefix})
133 Data directory: /usr/local/share/gutenprint
134 Library directory: /usr/local/lib64/gutenprint (${exec_prefix}/lib64/gutenprint)
135 Executable directory: /usr/local/bin (/usr/local/bin)
136 XML data directory: /usr/local/share/gutenprint/5.3/xml
137 Module directory: /usr/local/lib64/gutenprint/5.3/modules (${exec_prefix}/lib64/gutenprint/5.3/modules)
138 Install sample images: yes
139
140 General configuration:
141 Configure arguments: --enable-maintainer-mode
142 Compiler: gcc
143 Compiler Version: gcc version 7.4.1 20190725 [gcc-7-branch revision 273795] (SUSE Linux)
144 Compiler options: -Disfinite=finite -O3 -Wmissing-prototypes -Wmissing-declarations -Wnested-externs -Wwrite-strings -Werror-implicit-function-declaration -Winline -Wformat=2 -finline-limit=131072 -Wformat -Werror=format-security -Wmissing-prototypes -D_POSIX_C_SOURCE=200809L -std=c99 -pedantic -Waggregate-return -Wcast-qual -Wshadow -Wredundant-decls
145 Build static libraries: yes
146 Build shared libraries: yes
147 Maintainer mode: yes
148 Use i18n: yes
149 Generate profiling information: no
150 Generate debugging symbols: no
151 Use modules: static
152 Use readline libraries: yes, extra arguments: -lncurses
153 uname -a output: Linux dsl092-065-009 4.12.14-lp151.28.13-default #1 SMP Wed Aug 7 07:20:16 UTC 2019 (0c09ad2) x86_64 x86_64 x86_64 GNU/Linux
154 ================================================================
155
156
157 The CUPS and GIMP components require that the appropriate packages
158 be installed on your system. Many distribution vendors separate
159 packages into runtime and development packages. The development
160 packages are required in order to successfully compile Gutenprint.
161 In many cases the configure script cannot detect whether these
162 development packages are installed, in which case you will get an
163 error during compilation. Also note that it is necessary for the
164 versions of the development packages to match exactly the versions
165 of the runtime packages they are related to.
166
167 PLEASE INSPECT THE OUTPUT CAREFULLY BEFORE PROCEEDING. If you
168 expect to build a particular component (particularly the CUPS
169 driver, CUPS backends, or enhanced Print plugin for GIMP), and
170 the configure output states that that component will not be built,
171 please make certain that you have the required development packages
172 installed, as described below in the sections for the particular
173 components.
174
175
176----------------
177
178B) CORE DRIVER LIBRARY
179
180 The core driver library, which is always built, contains all of
181 the printer drivers comprising the Gutenprint package. When the
182 package is built, it consists of a core library (libgutenprint), a
183 set of XML files, and depending upon the options selected,
184 additional libraries containing the drivers for each family of
185 printers.
186
187 By default dynamically loadable modules (plug-ins) will be built
188 for the family drivers, and loaded at run-time if your operating
189 system supports it. If you experience problems,
190 --with-modules=dlopen or --with-modules=ltdl may be used to select
191 the module loading method (dlopen is the default, but GNU libltdl
192 is more portable), or --with-modules=static or --without-modules
193 disables them. If you wish to compile Gutenprint entirely
194 statically (with no use of shared libraries), you may use the
195 option --disable-shared.
196
197
198----------------
199
200C) CUPS
201
202 Gutenprint is normally used as a driver under CUPS (Common UNIX
203 Printing System). Full description of CUPS is beyond the scope of
204 this README file; full information may be found at
205 http://www.cups.org. Gutenprint 5.3 requires CUPS 1.1.9 or
206 higher. We recommend use of 1.1.15 or above; that release of CUPS
207 fixes some important bugs. Gutenprint supports CUPS 1.2, and
208 supports the CUPS 1.2 enhancements, including dynamic PPD file
209 generation.
210
211 Gutenprint will fail to configure if the necessary CUPS
212 development packages are not installed. This is to protect users
213 against attempting to install newer versions of Gutenprint without
214 installing the CUPS development package. This results in an
215 installation that does not work with CUPS, which has created
216 confusion in the past.
217
218 Normally, you should install the CUPS development package, which
219 on most systems is "cups-devel", "cups-dev", or similar, using
220 your operating system's package manager.
221
222 If you really want to install Gutenprint without CUPS, you may run
223 configure with "--without-cups". This may be useful if you intend
224 to use only the Gutenprint plugin for GIMP, or you intend to use
225 the Gutenprint library to support a custom printing solution that
226 does not involve CUPS. However, for most users, simply running
227 configure --without-cups is not the correct course of action.
228
229 If Gutenprint thinks it has detected a correct installation of
230 CUPS, but that installation is in fact not correct, you will get
231 errors when you compile the package. The errors will typically
232 look like this; the important error is "cups/cups.h: No such file
233 or directory" (other ".h" files may also be missing, depending
234 upon the missing packages):
235
236 make[3]: Entering directory `/opt/gutenprint/gutenprint-5.3.0-pre2/src/cups'
237 gcc -DHAVE_CONFIG_H -I. -I../.. -I../../include -I../../include
238 -Wall -Wcast-align -Wstrict-prototypes -Wmissing-prototypes
239 -Wmissing-declarations -Wnested-externs -Wwrite-strings
240 -Werror-implicit-function-declaration -Winline -Wformat=2
241 -finline-limit=131072 -DCUPS_DRIVER_INTERFACE -DALL_LINGUAS='"cs da
242 de el en_GB es fr hu it ja nb nl pl pt sk sv zh_TW"'
243 -Disfinite=finite -O6 -MT gutenprint_5_3-genppd.o -MD -MP -MF
244 .deps/gutenprint_5_3-genppd.Tpo -c -o gutenprint_5_3-genppd.o
245 `test -f 'genppd.c' || echo './'`genppd.c
246 genppd.c:79:23: error: cups/cups.h: No such file or directory
247 genppd.c:80:25: error: cups/raster.h: No such file or directory
248 make[3]: *** [gutenprint_5_3-genppd.o] Error 1
249 make[3]: Leaving directory `/opt/gutenprint/gutenprint-5.3.0-pre2/src/cups'
250 make[2]: *** [all-recursive] Error 1
251 make[2]: Leaving directory `/opt/gutenprint/gutenprint-5.3.0-pre2/src'
252 make[1]: *** [all-recursive] Error 1
253 make[1]: Leaving directory `/opt/gutenprint/gutenprint-5.3.0-pre2'
254 make: *** [all] Error 2
255
256 Installing the CUPS driver for Gutenprint 5.3 will not interfere
257 with your ability to continue using the Gutenprint 5.2 or earlier
258 drivers.
259
260 WARNING: The "canon" and "epson" CUPS backends that previously
261 were distributed with Gutenprint are no longer distributed, so you
262 will need to ensure that none of your printer queues use these
263 backends. Please read the Critical Upgrade Note in the release
264 notes for more information and the procedure for modifying your
265 printer queues.
266
267 The Gutenprint CUPS driver consists of the following components:
268
269 * The core Gutenprint CUPS driver, rastertogutenprint.5.3. This
270 is a CUPS filter that converts CUPS raster data into
271 printer-specific data. This is most commonly installed in
272 /usr/lib/cups/filter.
273
274 * Additional utilities to send certain commands to these printers
275 are installed as commandtocanon and commandtoepson; they are
276 installed in /usr/lib/cups/filter.
277
278 * A custom backend, gutenprint53usb, to send data to certain dye
279 sublimation printers. Some dye sublimation printers use custom
280 USB protocols to send data to the printer and will not work with
281 the standard USB back end.
282
283 * One or more sets of PPD files describing all of the printers
284 supported by Gutenprint. These are normally installed in
285 /usr/share/cups/model/gutenprint. These PPD files can only be
286 used by the precise version of Gutenprint that they were built
287 with; for example, it is not possible to use PPD files from
288 Gutenprint 5.3.0-pre2 with Gutenprint 5.3.0.
289
290 If you are using CUPS 1.2 or above, these PPD files may not be
291 actually installed by default, depending upon your system.
292 Instead, a CUPS driver generates these PPD files on demand.
293
294 * A utility to update PPD files from an earlier release of
295 Gutenprint, cups-genppdupdate. This utility may be used to
296 update PPD files generated by earlier versions of Gutenprint
297 starting from 4.3.21, including any 5.0, 5.1, 5.2, or 5.3
298 release or pre-release. This is normally installed in
299 /usr/sbin. This utility cannot update PPD files from Gimp-Print
300 4.2.
301
302 * A utility to generate PPD files, cups-genppd.5.3. Normally this
303 is only required when the package is built, and only with CUPS
304 1.1.
305
306 * A driver to generate PPD files on the fly, gutenprint.5.3. This
307 is normally used to generate PPD files on the fly with CUPS 1.2
308 and above.
309
310 * A utility to permit additional color calibration for
311 Gutenprint-supported printers, cups-calibrate. This is normally
312 installed in /usr/bin.
313
314 WARNING: With certain versions of CUPS and in certain non-standard
315 configurations, if a new version of Gutenprint is installed
316 over an existing version genppd will create PPD files based on
317 the older version of Gutenprint rather than the newer version.
318 This will happen if all of the following are true:
319
320 i) The cups-config provided by the CUPS driver adds
321 -Wl,rpath=/usr/lib (or wherever the CUPS system libraries
322 live). This is done by some versions of CUPS reportedly
323 because in some cases the runtime linker does not pick up
324 libraries out of /usr/lib. This can be checked by running
325
326 cups-config --libs --ldflags
327
328 and inspecting the output for any mention of "rpath",
329 "RPATH", "RUN_PATH", or the like. This is controlled by
330 the CUPS installation on your system.
331
332 ii) There is presently a version of Gutenprint installed in
333 the system default, typically /usr (--prefix=/usr) rather
334 than /usr/local or the like. The default location of
335 Gutenprint installation is in /usr/local, but system
336 vendors typically install Gutenprint in /usr.
337
338 iii) Gutenprint is built dynamically only (--disable-static or
339 --disable-static-genppd). This is not standard, and
340 requires the explicit --disable-static or
341 --disable-static-genppd on the Gutenprint "configure"
342 command line. Therefore, if you build Gutenprint normally
343 you should not be vulnerable to this problem.
344
345 iv) Gutenprint is configured to build the PPD files at compile
346 time. This is the case when using CUPS 1.1, but is not the
347 case when using CUPS 1.2 unless you explicitly use
348 --enable-cups-ppds.
349
350 Note that in general if you install CUPS into a non-standard
351 location, and install Gutenprint into the same location, this
352 problem can surface. For example, if you choose to install
353 CUPS in /usr/local and Gutenprint in /usr/local you are
354 vulnerable to this. However, it is not standard practice to
355 install CUPS anywhere but /usr.
356
357 In this case, the run path embedded in the genppd executable
358 points to the version of Gutenprint installed in /usr/lib.
359 This run path overrides any attempt by libtool to look in the
360 build directory. The result is that cups-genppd and
361 rastertogutenprint are run against the older version of
362 Gutenprint. If the new version contains additional features
363 (more printers, changes to printer options, etc.) they will
364 not be available.
365
366 This bug is difficult to detect in a normal build. It
367 normally does not cause an error to happen during build unless
368 there is an API change from the version installed and the
369 version being built; the only failure is frequently that some
370 PPD files may not be built or may be built with missing
371 options. Due to the PPD version checking introduced in this
372 release, the behavior might manifest itself as a runtime
373 error. It is also possible that there will be no error at all
374 other than the older version of Gutenprint being used, with
375 the result that new features and bug fixes are not available.
376
377 If you wish to use only shared libraries, do not wish to build
378 static libraries at all, and are vulnerable to this issue
379 (because cups-config --ldflags sets the run path), there are
380 three workarounds available:
381
382 i) Build and install Gutenprint into /usr (rather than
383 /usr/local) and then rebuild Gutenprint from scratch. This
384 will install the correct libgutenprint.so in /usr/lib, and
385 in the rebuild genppd will be run against the correct
386 library.
387
388 ii) Remove the old version of Gutenprint prior to building the
389 new version of Gutenprint. The important files to remove
390 are anything named /usr/lib/libgutenprint*.
391
392 iii) Edit cups-config to remove the reference to the run path.
393
394 Following installation of the package with "make install", you
395 must restart CUPS to permit CUPS to see the new PPD files. The
396 exact command to restart CUPS varies; it is typically something
397 like systemctl restart cups (which will be the case on most modern
398 Linux systems), /etc/init.d/cups restart,
399 /etc/software/init.d/cups restart, /etc/rc.d/cups restart,
400 /usr/sbin/rccups, or even /etc/rc.d/init.d/cups restart.
401
402 You may optionally choose to update your existing PPD files using
403 the command cups-genppdupdate, after which you should restart CUPS
404 as described above. We strongly recommend use of this update
405 procedure, which is fast and simple. This script will
406 automatically update Gutenprint PPD files from earlier versions of
407 Gutenprint 5.3. It will not at present automatically upgrade PPD
408 files from Gutenprint 5.0, 5.1, or 5.2; if you want to do so, you
409 need to run cups-genppdupdate -x. This allows you to continue
410 running older versions of Gutenprint concurrently with Gutenprint
411 5.3. This script cannot update PPD files from Gimp-Print 4.2 or
412 non-Gutenprint PPD files.
413
414 The following options to configure are available for compiling the
415 Gutenprint driver for CUPS:
416
417 --enable-cups-ppds
418
419 With CUPS 1.2, it is possible to arrange for PPD files to be
420 generated when a new printer queue is generated rather than
421 having all pre-generated PPD files in the filesystem. This
422 saves considerable disk space and avoids the possible build
423 problem described above. Normally, Gutenprint detects which
424 version of CUPS is in use and configures itself to create the
425 PPD files at build time only when CUPS 1.1 is in use.
426
427 If you wish to generate the PPD files at build time, you may
428 use this option. If you are running CUPS 1.1, and for some
429 reason do not wish to generate the PPD files, you may use
430 --disable-cups-ppds.
431
432 --disable-translated-cups-ppds
433
434 By default, PPD files for all languages available in
435 Gutenprint are created. If this option is used, only the
436 default (US-English) PPD files are created. Distributors may
437 wish to package up the PPD files separately for each language.
438
439 Some systems may not build the translated PPD files correctly,
440 in which case all of the PPD files will be in English. If
441 this is the case on your system, you should use
442 --disable-translated-cups-ppds to avoid having many duplicate
443 PPD files.
444
445 --disable-globalized-cups-ppds
446
447 Starting with Gutenprint 5.2, Gutenprint builds PPD files
448 containing translations for all languages if CUPS 1.2 or above
449 is in use. This greatly reduces the number of PPD files
450 created or PPD file choices offered.
451
452 If you have problems with the globalized PPD files, you may
453 use this option to generate standard translated PPD files (or
454 English-only, if --disable-translated-cups-ppds is also in
455 use). This option only has effect if --enable-cups-ppds is
456 used.
457
458 --enable-simplified-cups-ppds
459
460 Gutenprint 5.3 offers an option of creating simplified PPD
461 files (containing only basic options and standard paper sizes)
462 in addition to PPD files offering all available options
463 (including all color correction options). If this option is
464 used, both the simplified and standard PPD files are created.
465 If --enable-simplified-cups-ppds=only is specified, only the
466 simplified PPD files are built.
467
468 If the new dynamic PPD file generation is used with CUPS 1.2,
469 the simplified PPD files are always offered.
470
471 --disable-cups-level3-ppds
472
473 By default, the Gutenprint PPD files are configured for
474 PostScript Level 3. If this option is used, Level 2 PPD files
475 are created. This may be useful if you are using a version of
476 CUPS older than 1.1.15. It is normally not necessary to use
477 this explicitly, as the configure script detects the version
478 of CUPS in use and selects the appropriate PostScript level
479 automatically.
480
481 --disable-cups-ppds-at-top-level
482
483 Normally, the PPD files are placed in
484 /usr/share/cups/model/gutenprint/5.3. If this option is used,
485 the PPD files are placed in /usr/share/cups/model. There is
486 normally no good reason to use this option.
487
488 --disable-static-genppd
489
490 Build genppd and rastertogutenprint dynamically linked rather
491 than statically linked. WARNING: Use of this option may lead
492 to failure during build or installation, or incorrect
493 installation. It is *STRONGLY* recommended that you not use
494 this option unless you are certain that you understand the
495 problem and how to work around it.
496
497----------------
498
499D) CUPS dye-sublimation backend
500
501 A new CUPS backend was added to support specific dye-sublimation USB
502 printers that require a special communications protocol. This backend is
503 called 'gutenprint53+usb' and currently supports the models listed below.
504 If you do not have a printer on this list, you may skip the remainder
505 of this section.
506
507 Canon SELPHY ES series
508 Canon SELPHY CP series
509 Ciaat Brava 21
510 Citizen CW-01 / Olmec OP900
511 Citizen CW-02
512 DNP DS40 / Citizen CX
513 DNP DS80 / Citizen CX-W
514 DNP DS80DX (experimental)
515 DNP DS-RX1 / DS-RX1HS / Citizen CY
516 DNP DS620
517 DNP DS820
518 Kodak Professional 1400
519 Kodak 305 Photo Printer
520 Kodak 605 Photo Printer
521 Kodak 805 Photo Printer
522 Kodak 6800 Photo Printer
523 Kodak 6850 Photo Printer
524 Mitsubishi CP-3800DW
525 Mitsubishi CP-9550D/DW/DW-S/DZ/DZ-S
526 Mitsubishi CP-9600D/DW
527 Mitsubishi CP-9800DW/DW-S (experimental)
528 Mitsubishi CP-9810DW (experimental)
529 Mitsubishi CP-K60DW-S
530 Mitsubishi CP-D70DW / CP-D707DW
531 Mitsubishi P93DW
532 Mitsubishi P95DW
533 Shinko CHC-S1245 (aka Sinfonia E1) (experimental)
534 Shinko CHC-S6245 (aka Sinfonia CE1) (experimental)
535 Shinko CHC-S2145 (aka Sinfonia S2)
536 Shinko CHC-S6145 (aka Sinfonia CS2)
537 Sony UP-DR150
538 Sony UP-DR200
539 Sony UP-CR10L / DNP DS-SL10 (experimental)
540
541 Although these printers advertise themselves as standard USB Printer
542 Class devices, they do not actually obey those specifications, and
543 require two-way handshaking in order to successfully print.
544
545 Over time, it is expected that additional printer models will be
546 supported by this backend.
547
548 NOTE: If you are upgrading from 5.2.9 (or earlier) and using one of
549 the following models, you will need to remove and re-create your
550 printer queue:
551
552 Canon SELPHY ES series (All models)
553 Canon SELPHY CP series (All models)
554 DNP DS40
555 DNP DS80
556 Sony UP-DR150
557
558 Build Requirements
559
560 This backend requires libusb (or libusbx) 1.0 or newer.
561
562 CUPS Integration
563
564 If you are using up-to-date versions of CUPS (1.6.4 or newer) on
565 Linux, then your system will automatically select this backend if
566 the you plug in one of its supported printers. No further intervention
567 on the your part should be necessary.
568
569 Unfortunately, if you are using an older version of CUPS or a non-Linux
570 system (particularly OSX) then you will probably need to manually
571 configure the use of this backend because the system may attempt to
572 use the default usb backend, which will not work properly with these
573 printers.
574
575 To check which backend your printers are using, run the 'lpstat
576 -s' command. Below is an example of its output:
577
578 device for Canon_SELPHY_ES1: gutenprint53+usb://Canon/SELPHY%20ES1?serial=221CD10131&backend=canonselphy
579 device for Canon_SELPHY_ES3: usb://Canon/Canon%20SELPHY%20ES3
580
581 In this example, the SELPHY ES1 is using the correct gutenprint
582 backend, but the ES3 is using the incorrect 'usb' backend. In
583 order for the ES3 to function properly, you need to configure it
584 to use the correct backend.
585
586 The most expedient way to accomplish this is to remove the printer
587 via your system's printer configuration interface, then manually
588 add a new one, taking care to select the correct backend
589 ("gutenprint53+usb"). This backend name is present in the device
590 URI for the printer, as demonstrated in the above example. An
591 alternative to the system printer configuration interface is to
592 use your local system's CUPS web interface, if it is enabled.
593 Step-by-step instructions for using any of these interfaces is
594 beyond the scope of this document.
595
596 Once the printer is properly configured, this backend will be
597 automatically invoked as needed; you will never invoke the backend
598 directly.
599
600 Note on Use of Multiple Printers of the Same Model
601
602 If you do not use (and do not intend to use) more than one printer of
603 the same model connected via USB to one computer, you may skip this
604 section.
605
606 If you have more than one printer connected to a computer (via
607 separate queues), CUPS inspects each printer to determine which
608 printer is attached to which queue. Most printers provide a
609 serial number, which is different for each individual printer, to
610 determine which unique printer is which. Unfortunately, certain
611 printers do not provide this serial number, so CUPS cannot
612 uniquely identify each printer.
613
614 To determine if your printer model is affected, you should inspect the
615 CUPS queue URI, specifically the "serial=" portion. If the serial is
616 NONE_UNKNOWN, it indicates that the printer does not report a serial
617 number and so CUPS cannot uniquely that printer, if more than one of
618 that type is plugged in.
619
620 For example, a device URI of
621
622 gutenprint53+usb://Canon/SELPHY+ES1?serial=221CD10131&backend=canonselphy
623 has a proper serial number (221CD10131), and CUPS can uniquely
624 identify the printer.
625
626 A device URI of
627
628 gutenprint53+usb://Canon/CP-10?serial=NONE_UNKNOWN&backend=canonselphy
629
630 indicates that the printer does not report a valid serial number,
631 so that CUPS cannot uniquely identify the printer if there are
632 two or more Canon CP-10 printers attached.
633
634 If you attach more than one of any one of these printer models to
635 the same computer (such as two Canon CP-10 printers), you may
636 experience incorrect behavior, including:
637
638 * Printing (or attempting to print) to a printer other than
639 the desired one
640 * Failing to print a particular job at all
641 * Inability to create a queue for each printer
642 * Attempt to create a queue that already exists
643
644 Note on the Shinko CHC-S2145
645
646 The Shinko CHC-S2145 does not report a serial number in the traditional
647 sense; instead it reports a user identification string, which the backend
648 will use if one is configured.
649
650 The backend supports configuring this user identification string.
651 To do so, first disconnect all other Shinko CHC-S2145 printers from the
652 system, and then connect each printer individually, and run the
653 following command. Please ensure that the text you choose for each
654 printer is different.
655
656 /usr/lib/cups/backend/gutenprint53+usb -B shinkos2145 -U "sometext"
657
658 After changing the user string, you will need to remove and re-create
659 the CUPS queue.
660
661 Note on Mitsubishi Dye-Sublimation models with an '-S' and '-U' suffixes
662
663 As well as manufacturing standalone photo printers, Mitsubishi also
664 manufactures photo lab and kiosk solutions which use their printers.
665 However, the printers intended for use with those kiosks are *not*
666 compatible with the standalone models, despite having similar model
667 names. They are incompatible from a software perspective, and also
668 require different media.
669
670 With two exceptions, if the model ends in '-S' or has a red face-
671 plate, it is intended only for use with a Mitsubishi lab or kiosk, and
672 consequently not supportable by Gutenprint. For example, see the
673 (non-comprehensive) list below:
674
675 Supported/Compatible | Unsupported/Incompatible
676 ---------------------------------------------------
677 CP-D70DW | CP-D70DW-S
678 CP9600DW | CP9600DW-S
679 CP9550DW | CP9550DW-U
680
681 The exceptions to this rule are the CP-K60DW-S, which is sold as a
682 standalone "event" printer, and the CP9550DW-S, which has been
683 successfully reverse-engineered.
684
685----------------
686
687E) ESCPUTIL
688
689 "escputil" is a command line utility for administering Epson
690 inkjet printers. It performs head alignment, retrieval of ink
691 levels and status information, printing of test patterns, etc. It
692 is built and installed by default; if you don't want it, you may
693 use --without-escputil when configuring.
694
695 escputil uses the readline package for interactive commands
696 (currently only head alignment falls into this category). Linking
697 against libreadline sometimes requires linking against other
698 packages. Gutenprint attempts to determine the correct packages
699 to link against; the exact sequence is described in the release
700 notes. If you do not wish to use readline, you may use
701 --without-readline.
702
703
704----------------
705
706F) GIMP
707
708 Gutenprint may be used as an enhanced Print plug-in for GIMP (2.0
709 and above), providing the ability to print images. Please read
710 the release notes in addition to this README.
711
712 The enhanced Print plugin for GIMP replaces the Gimp-Print
713 4.2-based plugin provided with GIMP 2.0 and 2.2. As of the GIMP
714 2.4, GIMP team provides a new Print plugin based on the GtkPrint
715 framework. This plugin provides standard printing capabilities,
716 but does not provide all of the new Gutenprint 5.3 features.
717 Therefore, the enhanced Print plugin for GIMP distributed with
718 Gutenprint does not replace that plugin, but is installed
719 alongside that plugin.
720
721 If your system separates development packages from runtime
722 packages, you will typically have to install development packages
723 for GIMP itself, in addition to Gtk and Glib. With GIMP 2.x and
724 GTK 2.x, additional packages may be required. Failure to install
725 these packages will lead to errors when the package is compiled.
726 The errors will typically look like this; the important errors are
727 the ones "No such file or directory".
728
729 make[3]: Entering directory `/opt/gutenprint/gutenprint-5.3.0-pre2/src/gimp2'
730 gcc -DHAVE_CONFIG_H -I. -I../.. -I../../include -I../../include
731 -Wall -Wcast-align -Wstrict-prototypes -Wmissing-prototypes
732 -Wmissing-declarations -Wnested-externs -Wwrite-strings
733 -Werror-implicit-function-declaration -Winline -Wformat=2
734 -finline-limit=131072 -Disfinite=finite -O6 -MT print-image-gimp.o
735 -MD -MP -MF .deps/print-image-gimp.Tpo -c -o print-image-gimp.o
736 print-image-gimp.c
737 In file included from print-image-gimp.c:30:
738 print_gimp.h:36:21: error: gtk/gtk.h: No such file or directory
739 print_gimp.h:37:26: error: libgimp/gimp.h: No such file or directory
740 print_gimp.h:38:28: error: libgimp/gimpui.h: No such file or directory
741 make[3]: *** [print-image-gimp.o] Error 1
742 make[3]: Leaving directory `/opt/gutenprint/gutenprint-5.3.0-pre2/src/gimp2'
743 make[2]: *** [all-recursive] Error 1
744 make[2]: Leaving directory `/opt/gutenprint/gutenprint-5.3.0-pre2/src'
745 make[1]: *** [all-recursive] Error 1
746 make[1]: Leaving directory `/opt/gutenprint/gutenprint-5.3.0-pre2'
747 make: *** [all] Error 2
748
749 Normally, the Gutenprint configure script detects which version,
750 if any, of GIMP is installed and builds an appropriate plugin. If
751 the configure script does not detect it properly, you may need to
752 specify --with-gimp or --with-gimp2. However, it's more likely
753 that you need to install appropriate development packages.
754
755 Normally Gutenprint installs GIMP Print plugin in your system
756 plug-in directory. If you wish to install it in your personal
757 plugin directory, you may use
758
759 ./configure --enable-user-install
760
761 It is not possible for Gimp-Print 4.2, Gutenprint 5.0, Gutenprint
762 5.2, and Gutenprint 5.3 (or any future release) to coexist in the
763 same installation of GIMP. The Gutenprint 5.3-based plugin can
764 read settings from previous versions of Gutenprint and Gimp-Print,
765 but the configuration file format in Gutenprint 5.3 cannot be read
766 by older versions of Gimp-Print or Gutenprint.
767
768
769================================================================
770
771III) GETTING STARTED
772
773 This section describes how to get started by installing printers
774 under Gutenprint. Please see the user's manual (in
775 doc/gutenprint-users-manual.odt or
776 doc/gutenprint-users-manual.pdf) for more information.
777
778----------------
779
780A) PRINTER INSTALLATION
781
782 The actual procedure to install a printer depends upon your
783 operating system.
784
785 Gutenprint does not normally require the use of non-standard
786 procedures (such as starting special programs) to install
787 printers. Assuming that you are using CUPS, it integrates with
788 your printing system, so the tools provided by your distribution
789 vendor should work correctly with Gutenprint.
790
791 CUPS uses PPD files to describe printer capabilities. Some
792 printers are supported by more than one driver, so you may find
793 more than one PPD file for your printer. Gutenprint PPD files are
794 described as
795
796 Epson Stylus Photo R300 - CUPS+Gutenprint v5.3.0-pre2
797 Epson Stylus Photo R300 - CUPS+Gutenprint v5.3.0-pre2 Simplified
798
799 The "simplified" PPD files offer a basic set of options only, for
800 selecting printer options, standard paper sizes, and basic quality
801 settings. The PPD files that are not "simplified" offer a much
802 broader set of controls, giving the user extensive control over
803 quality and color adjustment.
804
805 Other PPD files are described differently, such as
806
807 EPSON New Stylus Color Series CUPS v1.1 (recommended)
808
809 These PPD files, whether "recommended" or not, are not Gutenprint
810 PPD files.
811
812 NOTES FOR CUPS USERS:
813
814 If you do not choose to automatically update existing PPD files,
815 you should reinstall any printer queues that you are using
816 Gutenprint PPD files with. The Gutenprint driver and the PPD
817 files must be kept in sync, since the PPD files reflect the
818 particular version of the driver that they were built against. If
819 you attempt to use a version of Gutenprint with PPD files not
820 built for that precise version, the driver will fail with a
821 diagnostic error message. For example, PPD files built for
822 Gutenprint 5.3.0-pre2 will not work with driver version 5.3.0.
823 You can identify printers using Gutenprint PPD files by the name
824 of the PPD file, which will be something like:
825
826 EPSON Stylus Photo EX - CUPS+Gutenprint v5.3.0-pre2(en)
827
828 Linux users please note: If you are using CUPS 1.1.11 or higher,
829 and you have a USB-connected printer, you must have a printer
830 connected to each USB port that you plan to use and powered on
831 when you restart CUPS. If you do not do so, you will not be able
832 to reinstall the printer. It is only necessary to do this if you
833 wish to update PPD files manually; if you use cups-genppdupdate,
834 you do not need to do this.
835
836 Starting with CUPS 1.1.11, you cannot choose an AppSocket
837 connection and enter "usb:/dev/usblp0" or the like as the URI; you
838 will get a "client-error-not-possible" error at the end of the
839 installation process, and you will have a message like the
840 following in your CUPS error log (typically
841 /var/log/cups/error_log):
842
843E [21/Nov/2001:17:59:07 +0500] add_printer: bad device-uri attribute 'usb:/dev/usb/lp0'!
844
845 If the printer was turned on correctly, you will be given a choice
846 of a USB connection in the Device dialog.
847
848 You may also have problems if you have a .lpoptions file that has
849 old options set. If you have problems printing, please remove any
850 existing .lpoptions file in your home directory and try printing
851 again.
852
853================================================================
854
855IV) SOLVING PROBLEMS
856
857 While we have attempted to make use of Gutenprint as
858 straightforward and trouble-free as possible, we certainly
859 recognize that there may be problems with installing and using
860 Gutenprint. In the event of any difficulty, we ask that you take
861 the following actions:
862
863 1) Read the release notes (NEWS).
864
865 2) Read the FAQ, in doc/FAQ.html. Your question may be answered
866 there.
867
868 3) Make sure that the paper type and size, and media source, that
869 you have selected matches the paper loaded into the printer.
870 This is only necessary if the printer attempts to print, but
871 does not succeed. It is a good starting point if quality is
872 poor (too dark or too light, wet ink on the paper, etc.).
873
874 4) Reset all settings (particularly the color and quality
875 settings) to their defaults.
876
877 5) If you are using CUPS, search /var/log/cups/error_log (which
878 may be located elsewhere on some systems) for lines starting
879 with 'E' (these lines indicate errors). Also search for log
880 information produced by Gutenprint; all such output lines will
881 contain "Gutenprint". These lines may help you solve the
882 problem and will help us investigate your problem if necessary.
883
884 6) If you are using CUPS, enable debugging output. This can be
885 done by editing /etc/cups/cupsd.conf (which must be done as
886 root). There will be a line in that file:
887
888 LogLevel Info
889
890 which should be changed to
891
892 LogLevel Debug
893
894 This will allow CUPS to produce extensive debugging output.
895 You will need to restart CUPS (the exact procedure is
896 system-dependent) after doing this. If you report a problem to
897 the Gutenprint team, you will be asked for this information.
898
899 7) There are public forums on Sourceforge dedicated to this
900 package. Please see
901 http://sourceforge.net/forum/?group_id=1537 for more
902 information. The Help forum is a good source of information.
903
904 8) If you have a technical support issue that does not appear to
905 be a bug in the software, you can use the Tech Support Manager.
906 Please see http://sourceforge.net/support/?group_id=1537.
907
908 9) If you have found a clear bug in the package, you may file a
909 bug report at http://sourceforge.net/bugs/?group_id=1537.
910
911 10) You may send mail to the gimp-print-devel@sourceforge.net
912 mailing list. This is recommended as a last resort only.
913
914================================================================
915
916V) USE OF THE CVS REPOSITORY
917
918 Please read doc/README.maintaining for instructions on how to
919 build from the CVS repository. You will need additional packages
920 and tools for this purpose.
921
1This file describes issues that packagers and distributors of
2Gutenprint should be aware of. This information is targeted at Linux
3distributions and others who deliver Gutenprint packages intended for
4end-user use.
5
61) As of 5.2 and until further notice, Gutenprint will no longer
7 deliver separate "development" and "stable" release series.
8
9 The point release will be advanced between beta/RC releases and
10 stable releases. The first stable release of 5.2 will be numbered
11 5.2.1; the betas and release candidates will be numbered
12 5.2.0-betaN or 5.2.0-rcN. Any betas for the next stable release
13 will be numbered 5.2.2-betaN; the next stable release will be
14 numbered 5.2.3 (if there are beta or release candidate builds) or
15 5.2.2 (if there are not).
16
17 This ensures that the highest numbered release is always the most
18 current, and that there will be no confusion between beta releases
19 and stable releases. Our experience with 5.0 was that many users
20 continued to use beta releases of 5.0 even after 5.0.0 was
21 released, and worse, in some cases referred to the 5.0.0-beta2
22 release (for example) as "5.0.2". We believe that the numbering
23 scheme described above will avoid that problem.
24
252) We request that you subscribe to
26 gimp-print-devel@lists.sourceforge.net to get the latest
27 information about upcoming changes.
28
293) If you intend to make any changes or patches to the source code of
30 this package, we request that you inform us of these changes and
31 discuss them with us prior to distribution, and identify a point of
32 contact to us.
33
34 While this is not required by the GPL, we would greatly appreciate
35 knowing about any changes you plan to make for three reasons:
36
37 * The changes may benefit all users of Gutenprint.
38
39 * We may have already considered this kind of change in the past
40 and elected not to make it, or may be planning to make this kind
41 of change in a different way from what you have done.
42 Coordination in this case may save everyone a lot of work.
43
44 * If we receive bug reports or support requests from users of your
45 package, we will either know who we can direct them to or will
46 have a better understanding of what is different in your package
47 that may cause observed differences from what we expect.
48
494) We specifically request that you *not* make changes to the margins
50 of any paper size in src/xml/papers.xml, or in general change
51 papers.xml other than to add additional paper sizes. In the past,
52 a number of distributions have imposed margins for certain paper
53 sizes in this file because printing on certain printers was cut off
54 (cropped). Change to papers.xml to work around these problems is
55 not an appropriate workaround for this problem, as it results in
56 *all* printers being bound by those margins. Furthermore, the
57 margin problem has since been fixed in a different way. Margins
58 should only be listed in papers.xml for papers that intrinsically
59 have margins of their own, such as photo papers with tear-off
60 margins.
61
62 Historically, in Gutenprint 5.0.0 all printers that offered
63 different margins under different circumstances (e. g. a choice
64 between normal margins and full-bleed printing, such as many Epson
65 inkjet printers, or different margins for certain paper sizes, such
66 as many laser printers that offer different margins for A4 than for
67 other paper sizes) always listed the wide margins in the PPD files,
68 and if the full bleed option was not selected (or a paper size that
69 required narrower margins was), the printed image was simply
70 clipped to the margins. This preserved the image dimension on the
71 page, but in some cases resulted in parts of the image being
72 clipped. The workaround that some packagers applied, to add
73 margins in papers.xml, made it impossible to print full bleed to
74 these paper sizes even on printers capable of this. None of these
75 packagers ever discussed this change with us, and as a result we
76 were caught by surprise by some bug reports that it took us a while
77 to track down.
78
79 This issue was fixed in 5.0.1 (in the native CUPS driver) by means
80 of a new PPD option to allow users to either shrink the image to
81 the appropriate margins or to crop the image. This allows users to
82 select whether they prefer dimensional accuracy or printing the
83 entire image. However, we have observed that this workaround has
84 still not been removed from all distributors' packages.
85
86 At this point, there should be no reason to specify margins in
87 papers.xml for any reason other than adding a media size that has
88 intrinsic margins of its own, such as a new paper with tear-off
89 margins. If you think you need to do this for any other reason,
90 please discuss it with us first!
91
925) Packaging the Core Library (libgutenprint)
93
94 * You may wish to create a development package containing header
95 files and linkable libraries separate from the runtime package.
96 There are a few third party applications that link against
97 Gutenprint.
98
99 * Gutenprint permits installation of Gimp-Print 4.2 and Gutenprint
100 5.0 alongside Gutenprint 5.2, and in the future will permit
101 concurrent installation of different stable versions of
102 Gutenprint with different minor version numbers. Therefore, you
103 may consider allowing Gutenprint 5.0, Gutenprint 5.2, and
104 Gimp-Print 4.2 to be installed concurrently.
105
106 * The core driver library component also includes XML data files
107 (in src/xml), locale files for the library, and documentation.
108 The XML data files in src/xml are mandatory; the driver will not
109 function without these files.
110
111 * We do not recommend installing any program linked against
112 libgutenprint with enhanced privileges (via the setuid or setgid
113 mechanism, or any other such mechanism). We have not audited
114 libgutenprint for safety in this kind of environment, and changes
115 in Gutenprint 5.2 (in particular, moving the Epson driver data
116 into external data files whose root can be changed by means of
117 the environment variable STP_DATA_PATH) may increase risk.
118 Furthermore, if you build the Gutenprint library in modular
119 fashion, such that drivers may be dynamically loaded into running
120 applications, there is an additional hazard in the form of an
121 environment variable that allows specifying where those modules
122 should be loaded from (STP_MODULE_PATH).
123
124 The only program in the core Gutenprint package that has any
125 reason to be installed this way is escputil, because it needs to
126 talk directly to the printer. See the discussion of escputil
127 below.
128
1296) Packaging the CUPS Driver
130
131 * IMPORTANT: As a special part of the install/upgrade procedure,
132 your installer should check for any queues using the "epson" or
133 "canon" backends and convert them to use an appropriate standard
134 backend, usually the "usb" or "parallel" backend. Please see the
135 Critical Upgrade Note in the release notes (NEWS file) for more
136 information.
137
138 Note that the epson and canon backends are no longer distributed
139 by Gutenprint, so your installer will have to fix this up in any
140 event.
141
142 * We recommend that your installation package run cups-genppdupdate
143 and restart CUPS as part of the installation process. This will
144 copy changes made by the user and ensure that the user has
145 correct PPD files. The CUPS driver will refuse to use a PPD file
146 built with a different version of Gutenprint.
147
148 * Some applications do not translate PPD file contents (option
149 names and values) when globalized PPD files are used (see the
150 release notes for general discussion of globalized PPD files).
151 At the time these notes are being written, we have determined
152 that versions of OpenOffice.org up to and including 3.0.0-rc1 do
153 not translate PPD file contents with globalized PPD files, but
154 language-specific localized PPD files are translated correctly.
155 We have also determined that GIMP 2.4, using the GtkPrint plugin,
156 does not translate PPD contents using globalized PPD files, but
157 does with single language files.
158
159 The CUPS development team has informed us that they have not
160 received complaints from users about this, despite the fact that
161 the basic set of PPD files distributed by CUPS is globalized.
162 Unlike Gutenprint, however, CUPS does not require that its PPD
163 files be upgraded with each release, so users upgrading from
164 older versions of CUPS may not be exposed to this issue.
165
166 Gutenprint does provide a way to upgrade PPD files to
167 language-specific ones, using the -l option to
168 cups-genppdupdate. PPD files that are being upgraded from a
169 previous release of Gutenprint may be upgraded with
170 cups-genppdupdate -loriginal to update to the original language.
171 Note that this works even if the PPD files have been updated to
172 globalized files, since cups-genppdupdate stores the language of
173 the PPD file it was upgrading. cups-genppdupdate -l<language>
174 updates PPD files into the specified language; see the release
175 notes or user's manual for the set of languages supported.
176
177 Note that -loriginal will *not* work with PPD files that had been
178 upgraded with Gutenprint 5.2.0-beta4, since cups-genppdupdate in
179 that release does not preserve the original language of the PPD
180 file.
181
182 Distributions have a number of possible options to address this
183 issue, for example:
184
185 - Use globalized PPD files and accept the translation problem or
186 fix the applications that do not translate the PPD files
187 correctly. You may wish to document the procedure of using
188 cups-genppdupdate to generate language-specific PPD files in
189 this case.
190
191 - Configure Gutenprint with --disable-globalized-cups-ppds, to
192 generate only single-language PPD files.
193
194 - Provide an administrative utility to update either individual
195 PPD files or all PPD files on the system. If you provide this
196 kind of utility, we recommend using the -l<language> option
197 rather than -loriginal.
198
199 * All files and directories with versioned names (such as
200 rastertogutenprint and the PPD files) may be installed and used
201 concurrently with other versions of Gimp-Print and Gutenprint as
202 described above. Other executables (such as cups-calibrate) are
203 not versioned, but are not linked against libgutenprint and do
204 not have any other dependencies on Gutenprint.
205
2067) Packaging the Enhanced Print Plugin for GIMP
207
208 * The enhanced Print plugin for GIMP, unlike the core library and
209 CUPS drivers, may not be installed concurrently with other
210 versions. For example, you may not install both the Gimp-Print
211 4.2 and the Gutenprint 5.2 version of the Print plugin, as they
212 use different configuration file formats.
213
2148) Packaging the Epson Inkjet Management Utility, escputil
215
216 * We do not recommend installing this utility with enhanced
217 privileges (via the setuid or setgid mechanism, or any other such
218 mechanism) without a careful security audit on your part. If
219 elevated privileges are required in your installation, we suggest
220 ensuring that the variables STP_DATA_PATH and STP_MODULE_PATH be
221 cleared prior to invoking escputil (or that you patch escputil to
222 clear those variables prior to calling stp_init()) and otherwise
223 using the least privilege required to allow escputil to run.
224 Another option may be to allow (by means of device permissions)
225 an appropriate group of users to run this command.
226
227 With the conversion of the Epson driver to using external data
228 files in XML format rather than data hard-coded into the library
229 binary, there are more opportunities for injection of bad data
230 into the driver.
231
232 Note that the default configuration of Gutenprint does not
233 install escputil with elevated privileges.
234