Changes between Version 38 and Version 39 of HowTo


Ignore:
Timestamp:
Dec 19, 2011, 11:23:12 AM (12 years ago)
Author:
Alex Taylor
Comment:

Returned to TracWiki formatting

Legend:

Unmodified
Added
Removed
Modified

  • HowTo

    v38 v39  
    1 {{{
    2 #!html
    3 <h1>A CUPS and eCS (OS/2) How To</h1>
    4 
    5 <p><br><a name="contents"></a></p>
    6 <h2>CONTENTS</h2>
    7 <p><a href="#preamble">1. Brief Preamble</a></p>
    8 
    9 <p><a href="#whycups">2. Why CUPS?  What is it?</a>
    10 <ul style="list-style-type: none;">
    11 <li><a href="#work">How does CUPS work?</a>
    12 </ul></p>
    13 
    14 <p><a href="#required">3. List of Required Software</a>
    15 <ul style="list-style-type: none;">
    16 <li><a href="#packages">Brief description of the software packages</a>
    17 </ul></p>
    18 
    19 <p><a href="#installation">4. Installation</a>
    20 <ul style="list-style-type: none;">
    21 <li><a href="#inst_wpi">Installing with WarpIN</a>
    22 <li><a href="#inst_zip">Installing manually (from the ZIP files)</a>
    23 <li><a href="#upgrading">Upgrading from a Previous Version</a>
    24 <li><a href="#starting">Starting CUPS</a>
    25 <li><a href="#cupsgui">Using the CUPS Web Interface</a>
    26 </ul></p>
    27 
    28 <p><a href="#">5. Printing with CUPS</a>
    29 <ul style="list-style-type: none;">
    30 <li><a href="#cupsprint">Creating &amp; Configuring a CUPS Printer</a>
    31 <ul style="list-style-type: none;">
    32 <li><a href="#add_device">Selecting the printer connection</a>
    33 <li><a href="#add_name">Identifying the printer</a>
    34 <li><a href="#add_model">Selecting the printer model</a>
    35 <li><a href="#add_options">Setting the default print options</a>
    36 <li><a href="#cupstest">Testing the CUPS printer</a>
    37 <li><a href="#cupslpr">Printing from CUPS</a>
    38 </ul>
    39 <li><a href="#os2print">Creating a desktop printer object to use with CUPS</a>
    40 <ul style="list-style-type: none;">
    41 <li><a href="#obj_prep">Preparation</a>
    42 <li><a href="#object">Creating the printer</a>
    43 <li><a href="#obj_set">Configuring the printer</a>
    44 </ul>
    45 </ul></p>
    46 
    47 <p><a href="#about">About this Document</a>
    48 <ul style="list-style-type: none;">
    49 <li><a href="#credits">Contributors</a>
    50 <li><a href="#history">Revision History</a>
    51 </ul></p>
    52 
    53 <p><br><a name="preamble"></a>
    54 <h2>1. Brief Preamble</h2>
    55 <p>Hopefully this text will provide a clear enough "How To" for anyone to be able to follow.</p>
    56 
    57 <p>I am using my experience of, firstly, getting a printer working with CUPS itself; and then,
    58 creating an OS/2 desktop printer object that is capable of outputting print jobs through CUPS.</p>
    59 
    60 <p>The following text may refer to specific drive letter(s) that should be changed to reflect the
    61 correct drive letter on your systems.  Most of the paths used are specific to the CUPS installation;
    62 those that are not may need to be changed for your system.</p>
    63 
    64 
    65 <p><br><a name="whycups"></a>
    66 <h2>2. Why install CUPS?  What is it?</h2>
    67 <p>To answer the "what is it" part: CUPS is the <a href="http://www.cups.org/">Common Unix Printing
    68 System</a>.  In a nutshell, it's a generic framework for printer driver packages. You install CUPS
    69 plus a driver package that supports your printer, and if all goes well you can print. <tt>:-)</tt>
    70 </p>
    71 
    72 <p>Why install CUPS?  Simply put: because it is capable of supporting a lot of modern printers and
    73 is continually being updated to support more. The old OS/2 printer drivers are not that good with
    74 new printers. If you have a native PostScript printer, you can probably get it more or less working
    75 with some fiddling, since OS/2 supports PostScript generically.  But for most consumer-level
    76 printers, it's a different story.  If you are lucky enough to find a driver that works with your
    77 modern printer, those drivers will not be updated to take advantage of all the features... whereas
    78 the CUPS driver will.</p>
    79 
    80 <p>In short, CUPS can provide drivers for more current printers &mdash; and should provide many
    81 extra capabilities missing from the OS/2 drivers.</p>
    82 
    83 <p>What does it support? Support for actual printers is handled by the individual driver
    84 packages.  There are three basic packages available for OS/2 (not counting a couple of smaller
    85 and more experimental ones which are beyond the scope of this document).
    86 <ul>
    87   <li>Gutenprint (the biggest and most commonly-used driver package), list of supported printers:
    88       <a href="http://gutenprint.sourceforge.net/p_Supported_Printers.php ">http://gutenprint.sourceforge.net/p_Supported_Printers.php</a>
    89   <li>SpliX (supports various Samsung and Xerox printers), list of supported printers:
    90       <a href="http://splix.ap2c.org/">http://splix.ap2c.org/</a>
    91   <li>HP-LIP (supports various Hewlett-Packard printers), list of supported printers:
    92       <a href="http://hplipopensource.com/hplip-web/supported_devices/index.html">http://hplipopensource.com/hplip-web/supported_devices/index.html</a>
    93 </ul>
    94 
    95 
    96 <p><br><a name="work"></a>
    97 <h3>How does CUPS work?</h3>
    98 <p>You can think of CUPS as an emulation layer that presents all its printers as PostScript
    99 printers, even if (at the hardware level) they aren't actually.  This allows all applications to
    100 submit print jobs as standardized PostScript files (either themselves or by using a system
    101 PostScript driver), and CUPS does the job of converting them into the printer's own native format.
    102 If you're interested in the technical details, the
    103 <a href="http://svn.netlabs.org/ecups/wiki/CupsFaq">CupsFaq</a> has more information.</p>
    104 
    105 <p>In terms of the actual implementation, CUPS itself runs as a background server (daemon) with its
    106 own internal spooler. This daemon is responsible for managing all defined CUPS printers. Now, this
    107 is entirely independent of OS/2's normal printing system, which knows nothing about CUPS. So we
    108 need to also create a regular OS/2 printer object and queue that is capable of receiving print jobs
    109 from applications. Then we configure this printer object to redirect all of its print jobs to the
    110 correct queue within CUPS, by creating a virtual "port" that points to the CUPS daemon rather than
    111 to a hardware port. CUPS itself ultimately takes care of communicating with the actual hardware.
    112 See <a href="#packages">below</a> for more information.</p>
    113 
    114 <p>This HOWTO describes how to set this up.  The object is to end up with a desktop printer
    115 object that prints seamlessly to the printer, but which uses CUPS to take advantage of the
    116 extensive hardware support that provides.</p>
    117 
    118 
    119 <p><br><a name="required"></a>
    120 <h2>3. List of Required Software</h2>
    121 <p>The CUPS port is available at <a href="http://svn.netlabs.org/ecups/wiki/CupsPort">http://svn.netlabs.org/ecups/wiki/CupsPort</a>.
    122 You can download the software in WPI format or as individual ZIP files. In either case, you will
    123 need the following products.</p>
    124 
    125 <p><u>Always required:</u></p>
    126 <p><ul>
    127   <li>The basic CUPS package (this is the CUPS daemon and supporting files).
    128   <li>Ghostscript for OS/2 &mdash; version 8.71 is recommended, as later versions still have some
    129       outstanding issues with CUPS.
    130   <li>At least one of the following driver packages (choose the one which supports your printer):
    131       <ul>
    132         <li>Gutenprint (many printers)
    133         <li>SpliX (many Samsung/Xerox printers). Note that SpliX also requires custom GCC runtime,
    134             which is included in the WPI package, or available separately from
    135             <a href="http://smedley.info/gcc432.zip">http://smedley.info/gcc432.zip</a>
    136         <li>HP-LIP (various printers from HP)
    137       </ul>
    138   <li>CUPS port driver (CUPS.PDR).  If you use the WarpIN packages, this is included in the
    139       <tt>cups-base-*.wpi</tt> archive.
    140   <li>The eCups OS/2 printer driver, either ECUPS.DRV (for Gutenprint and SpliX) or ECUPS-HP.DRV
    141       (for HP-LIP).  These are modified versions of the standard OS/2 PostScript driver which
    142       include various fixes needed by CUPS.
    143   <li>LIBC runtime files required for CUPS and other components.  (You may have these already,
    144       especially if you are running eComStation).
    145       <ul>
    146         <li><a href="ftp://ftp.netlabs.org/pub/gcc/libc-0.6.3-csd3.zip">ftp://ftp.netlabs.org/pub/gcc/libc-0.6.3-csd3.zip</a>
    147         <li><a href="ftp://ftp.netlabs.org/pub/gcc/gcc4core.wpi">ftp://ftp.netlabs.org/pub/gcc/gcc4core.wpi</a>
    148       </ul>
    149 
    150 </ul></p>
    151 <p>These are described in more detail below.</p>
    152 
    153 <p><u>May be required:</u></p>
    154 <p><ul>
    155   <li>USB helper driver (required for USB printing only): <a href="http://en.ecomstation.ru/projects/usbtools/download/usbcalls-20060807.zip">http://en.ecomstation.ru/projects/usbtools/download/usbcalls-20060807.zip</a>
    156       (again, you may have this already, especially if you use a recent version of eComStation)
    157   <li><tt>PRNDRV.EXE</tt> is a useful program that can "clean up" printer entries in the INI files
    158       (not actually necessary for using CUPS, but can be very useful if you do a lot of creating
    159       and deleting of printers):
    160       <a href="http://www.os2site.com/sw/comm/faxworks/prndrv.exe">http://www.os2site.com/sw/comm/faxworks/prndrv.exe</a>
    161 </ul>
    162 
    163 
    164 <p><br><a name="packages"></a>
    165 <h3>Brief description of the software packages</h3>
    166 <p>CUPS consists of several packages that work together to provide emulated PostScript printing on
    167 raster printers. The core components on all platforms are the CUPS daemon, GhostScript, and the
    168 driver packages (Gutenprint, Splix, HPLIP etc.).</p>
    169 
    170 <p>The remaining packages are specific to the OS/2 port (a.k.a. eCups):
    171 <ul>
    172   <li>The LIBC and GCC files are required support files (the GCC runtime is required by Splix).
    173   <li>PRNDRV.EXE - a useful command line utility for listing installed OS/2 (not CUPS) printers,
    174       and deleting those that are no longer wanted. (Note: Be careful when using 'prndrv -d', as
    175       it is very easy to accidentally delete the key <tt>PM_DEVICE_DRIVERS -> ECUPS [= path to
    176       ECUPS.DRV]</tt> from OS2.INI - which will prevent all ECUPS printers from working, until
    177       you either fix the INI file manually or install a new ECUPS device.)
    178   <li>The eCups printer driver (ECUPS.DRV or ECUPS-HP.DRV) is a customized version of the OS/2
    179       PostScript driver (PSCRIPT.DRV) which has most of the popular CUPS PPD files already included,
    180       and can be updated as new printers become supported in CUPS. It also has a few tweaks and
    181       bugfixes to make it work better with CUPS. (For this reason, using the original IBM PostScript
    182       driver for CUPS printing is not really recommended, although it may happen to work for you.)
    183   <li>The eCups printer port driver (CUPS.PDR) provides the "hook-up" between an OS/2 printer
    184       object/queue and the actual CUPS printer.
    185 </ul>
    186 The port driver component in particular is crucial, because normal OS/2 applications only know
    187 how to print to an OS/2 Printer Object - not a CUPS printer! What happens is that the OS/2
    188 printer Object sends print data to a port (like a parallel/serial/USB port or an LPR network
    189 queue, and so on) which is defined by a port driver. In this case, we are implementing another
    190 type of port to be available alongside these. This driver allows the OS/2 print "engine" to talk
    191 to the CUPS daemon, which turn talks to the physical printer either over the network or over a USB
    192 connection (using what it calls a "backend", which is basically CUPS's own internal equivalent of
    193 a port driver).</p>
    194 
    195 <p>Note that we don't use the OS/2 USB port driver when using a USB attached printer via CUPS
    196 &mdash; we always use the CUPS port driver and then let the CUPS daemon control the physical
    197 IO traffic to the printer. The same is true for other connection types like network connections
    198 &mdash; in all cases, CUPS manages the connection.</p>
    199 
    200 <p>As far as CUPS goes internally, the data flow is as follows:</p>
    201 <p><tt>PRINTER <-> IO Driver "backend" <-> CUPS daemon (CUPSD.exe) <-- CUPS admin webpage (config, test print etc.)</tt></p>
    202 <p>The above suffices for printing using CUPS's own internal mechanisms. What the port driver does,
    203 in conjunction with an OS/2 Printer Object, is allow normal OS/2 programs (which know nothing about
    204 CUPS) to print to CUPS printers. So the data flow becomes:</p>
    205 <p><tt>PRINTER <-> IO Driver "backend" <-> CUPS daemon (CUPSD.exe) <-> eCups Port Driver (CUPS.PDR) <-> PostScript printer driver (ECUPS.PDR) <-> OS/2 printer support <-> OS/2 application.</tt></p>
    206 
    207 
    208 <p><br><a name="installation"></a>
    209 <h2>4. Installation</h2>
    210 
    211 <a name="inst_wpi"></a>
    212 <h3>Installing with WarpIN</h3>
    213 <p>There are now WarpIN (WPI) install packages available for eCups (see the
    214 <a href="http://svn.netlabs.org/ecups/wiki/CupsPort">CupsPort</a> page).  It is generally
    215 recommended that you use these, as they automate some of the tricker configuration steps
    216 (especially when upgrading various components from earlier versions).  On the other hand, they are
    217 still somewhat experimental, and are not always guaranteed to include the very latest versions of
    218 all components.</p>
    219 
    220 <p>Download the required WPI packages into a single directory.  You will need:
    221 <ul>
    222   <li>The main CUPS package (<tt>cups-base-<i>xx</i>.wpi</tt> where <i>xx</i> is the version
    223       number of CUPS); this includes both CUPS itself, and the CUPS port driver.
    224   <li>Ghostscript (version 8.71 is <i>strongly</i> recommended, unless you are doing development
    225       testing).
    226   <li>At least one printer support package (Gutenprint, SpliX, or HP-LIP).
    227   <li>The ECUPS printer driver in most cases, or alternatively the ECUPS-HP printer driver if
    228       you are installing HP-LIP specifically.
    229 </ul>
    230 <p>Install the selected packages by double-clicking on the <tt>cups-base-<i>xx</i>.wpi</tt> file
    231 from the Workplace Shell.  Follow the instructions shown in the installer.</p>
    232 <p>Once the installation completes, you should be able to continue with creating and configuring
    233 a printer.</p>
    234 
    235 <p><br><a name="inst_zip"></a>
    236 <h3>Installing manually (from the ZIP files)</h3>
    237 <p>Basic manual installation consists of unzipping most of the packages into the root directory of
    238 a selected drive.  It doesn't have to be the boot drive, but they must all be unzipped to the
    239 <em>same</em> (non-FAT) drive.
    240 <ul>
    241   <li><tt>cups-*.zip</tt> needs to be unzipped into the root directory, thereby creating the
    242       <tt>\cups</tt> top-level directory
    243   <li>Ghostscript needs to be unzipped into <tt>\gs</tt> - so that you end up with for example,
    244       <tt><i>x</i>:\gs\gs8.71</tt> (some zip packages contain the \gs upper directory, some don't
    245       &mdash; so make sure you end up with the correct directory structure).
    246   <li>The driver package(s) you will be using (<tt>gutenprint-*.zip</tt>, <tt>hplip-*.zip</tt>
    247       and/or <tt>splix-*.zip</tt>) must be unzipped into the root directory on the same drive.
    248       This will add various required files to the <tt>\cups</tt> directory, and in the case of
    249       Gutenprint will also create the <tt>\gutenprint</tt> top-level directory.
    250 </ul>
    251 <p>Once you have done the above, you should have the following directories off the root directory
    252 of your chosen drive:</p>
    253 <ul style="list-style-type: none;">
    254   <li><tt>\cups</tt>
    255   <li><tt>\gs</tt>
    256   <li><tt>\gutenprint</tt> (if using Gutenprint)
    257 </ul>
    258 <p>Have a read of the <tt>\cups\readme.os2</tt> before proceeding, to get an idea of what you are
    259 going to do.  Pay particular attention to the need to check/modify the Ghostscript path in
    260 <tt>\cups\lib\cups\filter\pstoraster</tt>.</p>
    261 
    262 <p>There are other required files which go into a couple of different locations:
    263 <ul>
    264   <li>The port driver is needed to enable printing from applications.  <tt>CUPS.PDR</tt> must
    265       be placed in <tt>\OS2\DLL</tt> on your boot drive so that the port install dialog can
    266       find it.  Place <tt>CUPSLPR.EXE</tt> into the <tt>\TCPIP\BIN</tt> directory on whichever
    267       drive TCP/IP is installed to (usually the boot drive).
    268   <li>The <tt>LIBC0*.DLL</tt> and <tt>GCC*.dll</tt> files should be put into a directory specified
    269       within the LIBPATH &mdash; either <tt>\ECS\DLL</tt> or <tt>\OS2\DLL</tt> is fine.
    270 </ul>
    271 
    272 <p>Other files can be unzipped now or later as they are required:</p>
    273 <ul>
    274   <li>The ECUPS (or ECUPS-HP) printer driver can be put into a directory of your choice. You will
    275       point the printer install dialog to this directory during the install process; OS/2 will
    276       then automatically copy the files to <tt>\OS2\DLL\ECUPS</tt> (which it will create if
    277       necessary).
    278   <li>If installing PRNDRV.EXE, just copy the file somewhere that's convenient for you.
    279 </ul>
    280 
    281 
    282 <p><br><a name="upgrading"></a>
    283 <h3>Upgrading from a Previous Version</h3>
    284 <p>Whether installing from WPIs or ZIP files, you can generally just install over top of the
    285 previous versions.  (If you installed from Peter Brown's old <tt>eCUPS003.wpi</tt> package, you
    286 might want to uninstall the corresponding packages from WarpIN before installing the latest WPIs
    287 &mdash; otherwise you'll probably end up with duplicated desktop objects and some orphaned entries
    288 in the WarpIN database).
    289 </p>
    290 
    291 <p>When upgrading to the most recent release of Gutenprint, you are advised to manually delete the
    292 contents of <tt>\cups\share\cups\model\gutenprint\5.2\C</tt> <strong>before</strong> installing
    293 the new version &mdash; otherwise, you may end up with a large number of duplicate entries in the
    294 CUPS driver list.  Unfortunately, even the WPI installer does not do this automatically yet.  (This
    295 is not necessary when installing a version of Gutenprint prior to 5.2.7.)</p>
    296 
    297 <p>If upgrading with the WPI packages, generally no additional steps are necessary.  However, when
    298 upgrading from ZIP files, you will need to do a bit of extra work:
    299 <ul>
    300   <li><p>When upgrading CUPS or any of the driver packages (Gutenprint, etc.), shut down the CUPS
    301       daemon by killing all running instances of <tt>cupsd.exe</tt> before starting.</p>
    302 
    303   <li><p>When upgrading either CUPS or Ghostscript, edit the file
    304       <tt>\cups\lib\cups\filter\pstoraster</tt> and make sure the "<tt>prefix=</tt>" line points to
    305       your correct GhostScript path.</p>
    306 
    307   <li><p>After upgrading Gutenprint, go into the CUPS web interface and do the following for
    308       <strong>all</strong> printers which use Gutenprint drivers:
    309       <ol>
    310          <li>Open the printer details by clicking on its queue name under the <i>Printers</i>
    311              page.
    312          <li>From the <i>Administration</i> drop-down, select "Modify Printer".
    313          <li>Leave all current settings on the first two pages unchanged; just click on
    314              <i>Continue</i> until you reach the printer manufacturer/model page.
    315          <li>Make sure the correct manufacturer and model for your printer are selected.
    316              Also make sure that the Gutenprint version shown in the driver name are
    317              correct for the version of Gutenprint you just installed.  Then click on
    318              <i>Modify Printer</i>.
    319          <li>It's a good idea to print a test page to make sure everything still works as it
    320              should.
    321       </ol></p>
    322       <p>(Alternatively, if you have Perl installed you can download and run the script
    323       <a href="http://smedley.info/cups-genppdupdate">http://smedley.info/cups-genppdupdate</a>,
    324       which does this automatically.)</p>
    325 </ul></p>
    326 
    327 
    328 <p><br><a name="starting"></a>
    329 <h3>Starting CUPS</h3>
    330 <p>If you installed from the WarpIN packages, CUPS should have been started automatically, and
    331 you can skip this step.</p>
    332 
    333 <p>To activate CUPS, start the program <tt>\cups\sbin\cupsd.exe</tt>.  This program will run
    334 continuously (until terminated), so you should run it either in a dedicated session or as a
    335 background process using "<tt>detach</tt>".</p>
    336 
    337 <p>You will presumably want to create a program object which does this, and place it in your
    338 Startup folder so that CUPS is started automatically at bootup.  You can make the program run
    339 in the background by specifying "<tt>cmd.exe</tt>" as the program name, then setting the
    340 parameters to "<tt>/c <i>x</i>:\cups\sbin\cupsd.exe</tt>" and the working directory to
    341 "<tt><i>x</i>:\cups\sbin</tt>" (where <i>x</i> is the drive letter where CUPS is installed).</p>
    342 
    343 <p>Alternatively, you can start <tt>cupsd.exe</tt> from either your <tt>\STARTUP.CMD</tt> or
    344 <tt>\TCPIP\BIN\TCPEXIT.CMD</tt> file.</p>
    345 
    346 
    347 <p><br><a name="cupsgui"></a>
    348 <h3>Using the CUPS Web Interface</h3>
    349 }}}
    350 [[Image(cupsweb01.png, right, margin=5, width=35%)]]
    351 {{{
    352 #!html
    353 Once you've finished installing CUPS, you should make sure that it's up and running by opening the
    354 CUPS web interface.  This is the main configuration tool for managing CUPS on your system.  You
    355 can use it to create and manage printers, enable other computers to access your CUPS printers,
    356 diagnose potential problems, and so on.
    357 
    358 <p>Fire up your web browser and point it at <a href="http://localhost:631/">http://localhost:631/</a>.
    359 If all goes well, this should bring up the CUPS Administration GUI.</p>
    360 <ul>
    361   <li><p>If you get a "host not found" error, try using the address <a href="http://127.0.0.1:631/">http://127.0.0.1:631/</a>
    362       instead.  If that doesn't help, make sure that you have loopback enabled in your system TCP/IP
    363       configuration.</p>
    364   <li><p>Alternatively, if you get an HTTP 404 error, it means that the CUPS daemon is not running
    365       (or is broken somehow).  Make sure you start <tt>cupsd.exe</tt> as <a href="#starting">described
    366       above</a>.</p>
    367 </ul>
    368 <p>(In some recent CUPS versions, the logo graphic on the front page may be broken, but this
    369 appears to be a harmless cosmetic issue.)</p>
    370 
    371 
    372 <p style="clear: right;"><br><a name="printing"></a></p>
    373 <h2>5. Printing with CUPS</h2>
    374 <p>There are two basic parts to setting up a printer with CUPS.</p>
    375 <ol>
    376   <li><a href="#cupsprint">Create and configure a CUPS printer queue</a>.  This sets things up so
    377       that CUPS itself knows about the printer and can print to it.
    378   <li><a href="#os2print">Create and configure a desktop printer object</a>.  This allows OS/2
    379       applications to actually print to the CUPS printer.
    380 </ol>
    381 <p>Unfortunately, this two-phase process makes things a bit complicated.  We'll describe how to
    382 set everything up, step by step.</p>
    383 
    384 
    385 <p><br><a name="cupsprint"></a>
    386 <h3>Creating &amp; Configuring a CUPS Printer</h3>
    387 }}}
    388 [[Image(cupsweb02.png, right, margin=5, width=35%)]]
    389 {{{
    390 #!html
    391 First of all, if your printer is locally-attached (e.g. via USB port), make sure that it is
    392 turned on.</p>
    393 
    394 <p>Next, go into the CUPS web interface, click on the <i>Administration</i> tab at the top, and then
    395 select the <i>Add Printer</i> button.</p>
    396 
    397 <p>The examples that follow will describe the process for adding an <strong>Epson PX-101</strong>
    398 colour inkjet printer.</p>
    399 
    400 <a name="add_device"></a><h4 style="clear: right;">Selecting the printer connection</h4>
    401 }}}
    402 [[Image(cupsweb03.png, right, margin=5, width=35%]]
    403 {{{
    404 #!html
    405 When you select <i>Add Printer</i>, CUPS scans for available printers.  Any locally-attached
    406 printers that it finds will be shown as selectable options on the following screen.  It may also
    407 detect network printers, but this seems to be a bit hit-and-miss (it probably depends on how
    408 your network is organized, among other factors).</p>
    409 
    410 <p>On this screen, select the connection that is appropriate for your printer.
    411 
    412 <dl>
    413 <dt><a name="local_usb"></a><u>Local printer (USB)</u>
    414 <dd><p>At the moment, the only local (direct) connections that are supported directly are USB.
    415     There is a workaround which can be used to enable printing via parallel port, but it requires
    416     some special setup; <a href="#local_lpt">see below</a>.</p>
    417     <p>It has been reported that some older versions of the operating systems USB support files can
    418     cause problems, so please ensure you have the latest versions of the OS/2 USB stack as well as
    419     <a href="http://en.ecomstation.ru/projects/usbtools/download/usbcalls-20060807.zip">USBCALLS</a>
    420     before you attempt this configuration.</p>
    421     <p>If your USB printer is connected and powered on, it should show up as an option on this page.
    422     This assumes, of course, that everything is working as it should.  Refer to the box below if
    423     you are having trouble getting your USB printer recognized by CUPS.</p>
    424     <p style="clear: right;"><div style="border: thin solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;">
    425     <p>If your CUPS version is older than 1.3.11, you may need to download the USB backend
    426     separately from
    427     <a href="http://download.smedley.info/cups-usb-backend-20090309.zip">http://download.smedley.info/cups-usb-backend-20090309.zip</a>
    428     and install it by unzipping into the <tt>\cups\lib\cups\backend</tt> directory.  However, all
    429     recent releases of CUPS include this file already.</p>
    430     <p>To verify that the USB support is working, open a command prompt and go to the
    431     <tt>\cups\lib\cups\backend</tt> directory.  Make sure your printer is turned on and run
    432     <tt>usb.exe</tt> with no parameters.  You should get a display like this:</p>
    433     <p>
    434     <tt>DEBUG: list_devices</tt><br>
    435     <tt>DEBUG: usb_find_busses=1</tt><br>
    436     <tt>DEBUG: usb_find_devices=2</tt><br>
    437     <tt>direct usb://EPSON/PX-101 "EPSON PX-101" "EPSON PX-101" "MFG:EPSON;CMD:ESCPL2,BDC,D4,D4PX;MDL:PX-101;CLS:PRINTER;DES:EPSON PX-101;" ""</tt>
    438     </p>
    439     <p>If you don't get such a display, check that your USB support is working correctly and that you have
    440     connected the printer with a known good cable to a known good port.</p>
    441     </div></p>
    442 <!--
    443     <p><table border="1" cellspacing="0" cellpadding="3">
    444     <tr><td><b>Field</td>            <td><b>Description</b></td>                                   <td><b>Example</b></td></tr>
    445     <tr><td><i>Device URI: </i></td> <td>USB port address (automatically determined by CUPS) </td> <td><tt>usb://EPSON/PX-101</tt></td></tr>
    446     </table>
    447     </p>
    448 -->
    449 
    450 <dt><a name="local_lpt"></a><u>Parallel port connection</u>
    451 <dd><p>The OS/2 port of CUPS does not currently support printing directly to parallel printers
    452     but there is a workaround.</p>
    453     <p><ol>
    454       <li>Create an OS/2 printer object using the IBMNULL printer driver. Select LPT<i>n</i> as
    455           the Output Port in the printer object properties, where LPT<i>n</i> is the name of the
    456           parallel port to which the printer is connected.
    457       <li>Start the OS/2 LPD service (<tt>lpd.exe</tt>). To prevent LPD from printing the control
    458           file page (an almost-blank page with few lines of information good only for debugging
    459           purposes), specify the "-c" parameter.  You can use the OS/2 TCP/IP Configuration notebook
    460           to configure LPD.
    461     </ol></p>
    462     <p>When creating the CUPS printer, select <i>LPD/LPR Host or Printer</i> and enter
    463     "<tt>lpd://localhost/<i>printer_name</i></tt>" as the Device URI, where <i>printer_name</i> is
    464     the physical name &mdash; as shown on the Properties <i>View</i> page &mdash; of the OS/2 printer
    465     object just created.</p>
    466 
    467     <p>For example: If you created a desktop printer with the object name "Canon iP4000", open the Properties
    468     for that printer and check the name displayed on the <i>View</i> page.  If the <i>Physical name</i>
    469     shows "CanoniP4", the device URI in CUPS should be "<tt>lpd://localhost/CanoniP4</tt>".
    470     <p><table border="1" cellspacing="0" cellpadding="3">
    471     <tr><td><b>Field</td>            <td><b>Description</b></td>                      <td><b>Example</b></td></tr>
    472     <tr><td><i>Device URI: </i></td> <td>Address of locally-shared LPD printer </td> <td><tt>lpd://localhost/CanoniP4</tt></td></tr>
    473     </table>
    474     </p>
    475 
    476     <p>Thanks to Rodney and others who supplied the above information regarding using locally attached
    477     printers with CUPS.</p>
    478 
    479     <p style="clear: right;"><div style="border: thin solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;"><p>In fact, the current CUPS port does include a
    480     parallel port backend (driver), but it is completely untested due to the fact that none of
    481     developers/testers actually has a parallel-port printer.  So the above workaround may or may
    482     not still be necessary.</p></div></p>
    483 
    484 <dt><a name="tcpip"></a><u>Network printer</u>
    485 <dd><p>These options allow you to connect to a network printer using various supported protocols.
    486     If the printer was not automatically detected, the following screen will prompt you to enter
    487     the necessary connection information in the form of a <i>URI</i> (a string specifying the
    488     connection protocol and address in a URL-like syntax).</p>
    489 
    490     <p>The format of the URI indicates which network protocol to use, and specifies the necessary
    491     options.  You have a choice of several different protocols; obviously, use whichever one your
    492     network printer or print server supports.</p>
    493     <ul>
    494       <li>Internet Printing Protocol (IPP) is the newest and most advanced; the URI format is
    495           "<tt>ipp://<i>server[</i>:<i>port]</i>/<i>printer[</i>?<i>option</i>=<i>value[</i>&<i>option</i>=<i>value</i>]]</tt>"
    496       <li>LPD (or LPR) is the oldest and most widely-supported; use the URI format
    497           "<tt>lpd://<i>[userid</i>@<i>]</i><i>server[</i>:<i>port]</i>/<i>printer</i></tt>"
    498       <li>AppSocket (also called JetDirect) is also widely used; use the URI format
    499           "<tt>socket://<i>server[</i>:<i>port]</i></tt>"
    500       <li>Samba is for printers which are being shared out via Windows networking,
    501           IBM LAN Server, Peer for OS/2, or a Samba server.  Use the URI format
    502           "<tt>smb://<i>[userid[</i>:<i>password]</i>@<i>]</i><i>server</i>/<i>printer</i></tt>"
    503     </ul>
    504     <p>Most TCP/IP network printers use either LPD or AppSocket (just try one or the other if
    505     you're not sure). For shared printers on a Windows server, use Samba.</p>
    506 
    507     <p style="clear: right;"><div style="border: thin solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;">
    508     <p>If you installed CUPS from ZIP files, be aware that support for Samba is not included by
    509     default.  If you want to use Samba, you need to first obtain the Samba Client Utilities package
    510     from <a href="http://svn.netlabs.org/samba">http://svn.netlabs.org/samba</a>.  Extract the
    511     file <tt>smbspool.exe</tt>, rename it to <tt>smb.exe</tt> and place it into the
    512     <tt>\cups\lib\cups\backend</tt> directory.  You should then be able to use the CUPS
    513     Samba support.</p>
    514     <p>The above is not necessary with the latest CUPS WarpIN packages, which include
    515     <tt>smb.exe</tt> out of the box.</p>
    516     </div></p>
    517 
    518     <p><table border="1" cellspacing="0" cellpadding="3">
    519     <tr><td><b>Field</td>            <td><b>Description</b></td>          <td><b>Example</b></td></tr>
    520     <tr><td><i>Device URI: </i></td> <td>Address of network printer </td> <td><tt>lpd://192.168.2.1/lpt1 </tt></td></tr>
    521     </table>
    522     </p>
    523 </dl>
    524 }}}
    525 [[Image(cupsweb03a.png, right, margin=5, width=35%)]]
    526 {{{
    527 #!html
    528 <p style="clear: right;">Select the <i>Continue</i> button when you are done with this section.</p>
    529 
    530 <a name="add_name"></a><h4 style="clear: right;">Identifying the printer</h4>
    531 }}}
    532 [[Image(cupsweb04.png, right, margin=5, width=35%)]]
    533 {{{
    534 #!html
    535 On the next page, you will be asked to give your printer a name, which CUPS itself will use to
    536 identify it.  You will also need to enter a description and a location; these are for the benefit
    537 of actual human beings.</p>
    538 
    539 <p><table border="1" cellspacing="0" cellpadding="3">
    540 <tr><td><b>Field</td>             <td><b>Description</b></td>                                              <td><b>Example</b></td></tr>
    541 <tr><td><i>Name: </i></td>        <td>A short name which CUPS will use to identify the printer </td>       <td>PX-101 </td></tr>
    542 <tr><td><i>Description: </i></td> <td>A human-readable description of the printer </td>                    <td>Epson PX-101 inkjet </td></tr>
    543 <tr><td><i>Location: </i></td>    <td>A brief description of where the printer is physically located </td> <td>Home </td></tr>
    544 </table></p>
    545 
    546 <p>The <i>Share this printer</i> checkbox allows other computers on the local network to use this
    547 printer (by accessing the current computer as a print server).</p>
    548 
    549 <p>Select <i>Continue</i> when you are happy with this section.</p>
    550 
    551 
    552 <a name="add_model"></a><h4 style="clear: right;">Selecting the printer model</h4>
    553 }}}
    554 [[Image(cupsweb05.png, right, margin=5, width=35%)]]
    555 {{{
    556 #!html
    557 This is where you select your printer's make and model.  This is obviously pretty important as it
    558 determines the driver that CUPS will use.</p>
    559 <p>There are two ways to specify the printer.
    560 <ul>
    561   <li><p>In most cases, you will choose the manufacturer and printer model from the list shown.
    562       (If the printer was auto-detected by CUPS, the manufacturer will probably be preselected
    563       and you'll only need to choose the right printer model.)  Generally, the list of models
    564       will show the printer model, followed by a dash and then the name of the driver package
    565       it belongs to (such as Gutenprint).</p>
    566       <p>Note that Gutenprint in particular normally provides two alternate drivers for each
    567       printer: a standard driver, and one called 'Simplified'.  The difference is in the level
    568       of configurability &mdash; the standard drivers support fine-tuning a number of
    569       advanced settings related to quality and colour balance.  In almost all cases, you will
    570       prefer the Simplified drivers, which are more than sufficient for most needs.</p>
    571 
    572   <li><p>If your printer model isn't listed, but you have a PPD file for your printer, supporting
    573       one of the installed driver packages (Gutenprint, etc.), then you can specify that in the
    574       field at the bottom.</p>
    575       <p>Note that any PPD file you provide here must be specifically written for use with CUPS
    576       in conjunction with one of the driver packages you have installed.  You <em>cannot</em>
    577       use a standard (e.g. Windows) PPD for this purpose.</p>
    578 </ul>
    579 </p>
    580 
    581 <p>Click on <i>Add Printer</i> when you are happy with your selections.</p>
    582 
    583 <a name="add_options"></a><h4 style="clear: right;">Setting the default print options</h4>
    584 }}}
    585 [[Image(cupsweb06.png, right, margin=5, width=35%)]]
    586 {{{
    587 #!html
    588 <p>After clicking <i>Add Printer</i> on the screen above, CUPS will load the options for the
    589 printer. This can take a little while &mdash; it is a good idea to have a look through and make
    590 sure the options look useable &mdash; especially the media size, type, and print quality settings.</p>
    591 <p>You can use the links near the top to browse various different option categories.  In most
    592 cases, you won't need to change much beyond the first page ("General").</p>
    593 <p>When satisfied, click <i>Set Default Options</i>.  CUPS should report that your printer has
    594 been configured successfully.</p>
    595 
    596 <p style="clear: right;"><div style="border: thin solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;">
    597 <p>If you see an "Internal Server Error" message right after configuring a printer, just reload
    598 the top-level page of the CUPS web interface.  This seems to be a (relatively) harmless bug that
    599 occurs now and then with some versions of CUPS.</p>
    600 </div></p>
    601 
    602 
    603 <a name="cupstest"></a><h4 style="clear: right;">Testing the CUPS printer</h4>
    604 }}}
    605 [[Image(cupsweb07.png, right, margin=5, width=35%)]]
    606 {{{
    607 #!html
    608 Click on the Printers tab.  The new printer should be listed.</p>
    609 <p>Click on the queue name to view the printer details.</p>
    610 <p>Under the <i>Maintenance</i> dropdown, choose "Print Test Page".  If all goes well the CUPS test
    611 page should pop out of the printer looking fine.</p>
    612 <p style="clear: right;"></p>
    613 }}}
    614 [[Image(cupsweb08.png, left, margin=5, width=35%)]]
    615 {{{
    616 #!html
    617 
    618 <a name="cupslpr"></a><h4 style="clear: left;">Printing from CUPS</h4>
    619 <p>You should now be able to print files using CUPS's own internal tools.</p>
    620 <p>The basic CUPS print command is <tt>\cups\bin\lpr.exe</tt>.  (This is <strong>not</strong> the
    621 same as OS/2's native LPR command; this one is specific to CUPS, and is not installed to the system
    622 PATH.)  Assuming you have the CUPS port driver installed properly, you can also use the
    623 <tt>cupslpr</tt>command (just a renamed version of the above), which should be available on the
    624 PATH.</p>
    625 <p>You can use these programs to print standard PostScript (<tt>.ps</tt>) files from a command
    626 prompt:
    627 <pre>   cupslpr -P <i>printer</i> <i>file</i></pre>
    628 <p>where <i>printer</i> is the name of the CUPS printer, and <i>file</i> is a previously-generated
    629 PostScript file.</p>
    630 
    631 <p>If this all works then you know that CUPS is configured and working correctly.</p>
    632 
    633 <p>Now the easy part is finished...</p>
    634 
    635 
    636 <p><br><a name="os2print"></a>
    637 <h3 style="clear: right;">Creating a desktop printer object to use with CUPS</h3>
    638 <p>Now to hook CUPS up to the rest of the system so that CUPS can be used for output by
    639 applications (like OpenOffice, Firefox, Lucide, PMMail, PMView... everything, basically).</p>
    640 
    641 <a name="obj_prep"></a><h4>Preparation</h4>
    642 <p>If you haven't done so already, make sure you have the ECUPS or ECUPS-HP printer driver files
    643 on your disk &mdash; either by unzipping the ZIP file, or installing the WPI, into a directory of
    644 your choice.  It doesn't really matter where this directory is; just make sure you make a note of
    645 the path, because you'll need to type it into the driver dialog (below).  I suggest somewhere like
    646 <tt>\ECS\INSTALL\PRNDRV\ECUPS</tt> &mdash; you'll probably want to keep these files around in case
    647 you ever need to install another included printer model (or to import a PPD file).</p>
    648 
    649 <p>If you installed CUPS from ZIP files, make sure that you remembered to install port driver.
    650 As a reminder, <tt>CUPS.PDR</tt> must be in your <tt>\OS2\DLL</tt> directory, and
    651 <tt>CUPSLPR.EXE</tt> needs to be in <tt>\TCPIP\BIN</tt>.  (If you installed from the WPI
    652 packages, this was done for you.)</p>
    653 
    654 <a name="object"></a><h4 style="clear: right;">Creating the printer</h4>
    655 <p>Open the desktop Templates folder and double-click on the Printer template or drag it to the
    656 Desktop in order to start the printer creation routine.  If you have eComStation, you can also
    657 use the <i>Install Printer</i> object in the Printers folder and select "Standard printer" (may
    658 be called "Local printer" in some versions).</p>
    659 
    660 }}}
    661 [[Image(obj_create01.png, right, margin=5, width=35%)]]
    662 {{{
    663 #!html
    664 <p>On the "Create a Printer" dialog, select the <i>Install new printer driver</i> button.</p>
    665 
    666 <p>Select the <i>Other eComstation printer driver</i> radio-button, and enter the path to where you
    667 placed the ECUPS driver files.  Then click on <i>Refresh</i> (at the bottom of the dialog) to see
    668 the list of printers.</p>
    669 
    670 <p>Select your printer from the list and then click on <i>Install</i>.  The driver for the selected
    671 model will be installed.  (The "Install New Printer Driver" dialog may or may not close
    672 automatically when this is done; if it doesn't, just click on <i>Cancel</i>.)</p>
    673 
    674 <p style="clear: right;"><div style="border: thin solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;">
    675 <p>If your printer model isn't shown in the list here, but <em>was</em> listed in CUPS, it means
    676 that the PPD for that printer was not pre-imported into the ECUPS (or ECUPS-HP) driver.</p>
    677 <p>If you are adventurous and/or technically inclined, you can try to import the PPD file yourself,
    678 using the <tt>PIN.EXE</tt> utility included with the driver files (assuming that you already
    679 installed the printer in CUPS, the PPD file can be found under <tt>\cups\etc\cups\ppd</tt>).</p>
    680 <p>Alternatively, you can simply select "Generic PostScript Printer" from the list.  This will
    681 prevent you from using the OS/2 Job Properties dialog to set print options from within
    682 applications &mdash; the default settings configured in the CUPS web interface will most likely
    683 always be used &mdash; but printing should more or less work.</p>
    684 </div></p>
    685 
    686 }}}
    687 [[Image(obj_create02.png, left, margin=5, width=35%)]]
    688 {{{
    689 #!html
    690 <p style="clear: left;"></p>
    691 <p>When you are back on the "Create a Printer" dialog, the new driver should appear. Select the
    692 driver, and also type a name for your printer into the entryfield at the top.</p>
    693 
    694 <p>You also need to select an output port.  We could install the CUPS port now, but it's simpler
    695 to just choose a temporary port like LPT1 for the time being, and set things up properly later.</p>
    696 
    697 <a name="obj_set"></a><h4 style="clear: right;">Configuring the printer</h4>
    698 <p>Now we need to configure the new printer object so that it prints through CUPS.</p>
    699 <ol>
    700   <li><p>Click mouse button 2 on the new desktop printer object, and select Properties.</p>
    701 
    702   <li><p>Select the <i>Printer driver</i> tab.</p>
    703       <p><a href="/ecups/attachment/wiki/HowTo/obj_props01.png"><img src="/ecups/attachment/wiki/HowTo/obj_props01.png" alt="[Printer Properties - Printer Driver]" width="35%" class="screen"></a></p>
    704       <p>Verify that the correct printer driver is selected.</p>
    705 
    706   <li><p>Open the <i>Job Properties</i> dialog.  The Paper size, Tray, Media Type, etc. should
    707       match the settings in the CUPS printer.</p>
    708       <p><a href="/ecups/attachment/wiki/HowTo/obj_props02.png"><img src="/ecups/attachment/wiki/HowTo/obj_props02.png" alt="[Default Job Properties]" width="35%" class="screen"></a></p>
    709       <p>Save your changes when done.</p>
    710 
    711   <li><p>Select the <i>Output port</i> tab.</p>
    712       <p>Click on the <i>Install new port</i> button.</p>
    713       <p><a href="/ecups/attachment/wiki/HowTo/obj_port01.png"><img src="/ecups/attachment/wiki/HowTo/obj_port01.png" alt="[Install New Port]" width="35%" class="screen"></a></p>
    714       <p>If the "CUPS" port option is not visible but the file <tt>CUPS.PDR</tt> is in <tt>\OS2\DLL</tt>,
    715       select <i>New port drivers</i> and type in <tt><i>x</i>:\OS2\DLL</tt> (where <i>x</i> is your
    716       boot drive), then click on <i>Refresh</i>. The "CUPS" port option should appear.</p>
    717       <p>Select the "CUPS" port and click <i>Install</i>.</p>
    718       <p style="clear: right;"><a href="/ecups/attachment/wiki/HowTo/obj_port03.png"><img src="/ecups/attachment/wiki/HowTo/obj_port03.png" alt="[Printer Properties - Output Port]" width="35%" class="screen"></a></p>
    719       <p><strong>Note:</strong> You will need to install a separate "CUPS<i>x</i>" port for each
    720       CUPS printer that you wish to install (CUPS1, CUPS2, CUPS3, etc.).</p>
    721 
    722   <li><p>Double-click on the CUPS<i>x</i> port (or click mouse button 2 and select "Properties").</p>
    723       <p><a href="/ecups/attachment/wiki/HowTo/obj_port02.png"><img src="/ecups/attachment/wiki/HowTo/obj_port02.png" alt="[CUPS port properties]" width="35%" class="screen"></a></p>
    724       <p>The required settings for the CUPS port are:
    725       <dl>
    726         <dt><i>CUPS Server:</i>
    727         <dd>"<tt>localhost</tt>" (or use 127.0.0.1).<p>
    728         <dt><i>CUPS Printer Name:</i>
    729         <dd>This should be the same name as used for creating the CUPS printer (in the
    730         CUPS web interface <a href="#add_name">above</a>).
    731       </dl>
    732       <p>Select <i>OK</i> when done.
    733 
    734     <li><p>Set any other printer properties that you deem appropriate.  Personally, I like to set
    735         the printer object view to Detail.</p>
    736         <p>I also suggest editing the default driver properties (by double-clicking on the driver
    737         name) and bumping up the maximum number of downloaded fonts on the <i>Options</i> page
    738         &mdash; my rule of thumb is to allow about 5 fonts per megabyte of RAM in the printer.
    739         This can make large documents print a bit faster when using Type 1 fonts, and in the case
    740         of laser printers can also make a visible difference in print quality (although with a
    741         typical inkjet you probably wouldn't be able to tell).</p>
    742         <p><a href="/ecups/attachment/wiki/HowTo/obj_props03.png"><img src="/ecups/attachment/wiki/HowTo/obj_props03.png" alt="[Driver Properties]" width="35%" class="screen"></a></p>
    743 
    744     <li><p>Close the printer properties notebook.</p>
    745 </ol>
    746 
    747 <p style="clear: right;">That should complete the setup.  Now it's time to
    748 print a test page using the desktop printer object.</p>
    749 <ol>
    750   <li>Verify that <tt>cupsd.exe</tt> is running before testing.
    751   <li>Drag-and-drop the file <tt>\cups\share\cups\data\testprint.ps</tt> onto the new
    752       desktop printer object.
    753   <li>Select <i>Printer-specific</i> when prompted.
    754 </ol>
    755 <p>You should get the CUPS test page printed.</p>
    756 
    757 <p>The next test is to print a multiple-page document from your favourite word processor, followed
     1= A CUPS and eCS (OS/2) How To =
     2
     3== CONTENTS == #contents
     41. [#preamble" Brief Preamble]
     5
     62. [#whycups Why CUPS?  What is it?]
     7  * [#work How does CUPS work?]
     8
     93. [#required List of Required Software]
     10  * [#packages Brief description of the software packages]
     11
     124. [#installation Installation]
     13  * [#inst_wpi Installing with WarpIN]
     14  * [#inst_zip Installing manually (from the ZIP files)]
     15  * [#upgrading Upgrading from a Previous Version]
     16  * [#starting Starting CUPS]
     17  * [#cupsgui Using the CUPS Web Interface]
     18
     195. [#printing Printing with CUPS]
     20  * [#cupsprint Creating & Configuring a CUPS Printer]
     21    * [#add_device Selecting the printer connection]
     22    * [#add_name Identifying the printer]
     23    * [#add_model Selecting the printer model]
     24    * [#add_options Setting the default print options]
     25    * [#cupstest Testing the CUPS printer]
     26    * [#cupslpr Printing from CUPS]
     27  * [#os2print Creating a desktop printer object to use with CUPS]
     28    * [#obj_prep Preparation]
     29    * [#object Creating the printer]
     30    * [#obj_set Configuring the printer]
     31
     32[#about About this Document]
     33  * [#credits Contributors]
     34  * [#history Revision History]
     35
     36
     37\\\\
     38== 1. Brief Preamble == #preamble
     39Hopefully this text will provide a clear enough "How To" for anyone to be able to follow.
     40
     41I am using my experience of, firstly, getting a printer working with CUPS itself; and then, creating an OS/2 desktop printer object that is capable of outputting print jobs through CUPS.
     42
     43The following text may refer to specific drive letter(s) that should be changed to reflect the correct drive letter on your systems.  Most of the paths used are specific to the CUPS installation; those that are not may need to be changed for your system.
     44
     45
     46\\\\
     47== 2. Why install CUPS?  What is it? == #whycups
     48To answer the "what is it" part: CUPS is the [http://www.cups.org/ Common Unix Printing System]. In a nutshell, it's a generic framework for printer driver packages. You install CUPS plus a driver package that supports your printer, and if all goes well you can print. `:-)`
     49
     50Why install CUPS?  Simply put: because it is capable of supporting a lot of modern printers and is continually being updated to support more. The old OS/2 printer drivers are not that good with new printers. If you have a native !PostScript printer, you can probably get it more or less working with some fiddling, since OS/2 supports !PostScript generically.  But for most consumer-level printers, it's a different story.  If you are lucky enough to find a driver that works with your modern printer, those drivers will not be updated to take advantage of all the features... whereas the CUPS driver will.
     51
     52In short, CUPS can provide drivers for more current printers — and should provide many extra capabilities missing from the OS/2 drivers.
     53
     54What does it support? Support for actual printers is handled by the individual driver packages.  There are three basic packages available for OS/2 (not counting a couple of smaller and more experimental ones which are beyond the scope of this document).
     55  * Gutenprint (the biggest and most commonly-used driver package), list of supported printers: http://gutenprint.sourceforge.net/p_Supported_Printers.php
     56  * SpliX (supports various Samsung and Xerox printers), list of supported printers: http://splix.ap2c.org/
     57  * HP-LIP (supports various Hewlett-Packard printers), list of supported printers: http://hplipopensource.com/hplip-web/supported_devices/index.html
     58
     59
     60\\
     61=== How does CUPS work? === #work
     62You can think of CUPS as an emulation layer that presents all its printers as !PostScript printers, even if (at the hardware level) they aren't actually.  This allows all applications to submit print jobs as standardized !PostScript files (either themselves or by using a system !PostScript driver), and CUPS does the job of converting them into the printer's own native format. If you're interested in the technical details, the CupsFaq has more information.
     63
     64In terms of the actual implementation, CUPS itself runs as a background server (daemon) with its own internal spooler. This daemon is responsible for managing all defined CUPS printers. Now, this is entirely independent of OS/2's normal printing system, which knows nothing about CUPS. So we need to also create a regular OS/2 printer object and queue that is capable of receiving print jobs from applications. Then we configure this printer object to redirect all of its print jobs to the correct queue within CUPS, by creating a virtual "port" that points to the CUPS daemon rather than to a hardware port. CUPS itself ultimately takes care of communicating with the actual hardware.
     65See [#portdriver below] for more information.
     66
     67This HOWTO describes how to set this up. The object is to end up with a desktop printer object that prints seamlessly to the printer, but which uses CUPS to take advantage of the extensive hardware support that provides.
     68
     69
     70\\\\
     71== 3. List of Required Software == #required
     72The CUPS port is available at [http://svn.netlabs.org/ecups/wiki/CupsPort]. You can download the software in WPI format or as individual ZIP files. In either case, you will need the following products.
     73
     74__Always required:__
     75  * The basic CUPS package (this is the CUPS daemon and supporting files).
     76  * Ghostscript for OS/2 — version 8.71 is recommended, as later versions still have some outstanding issues with CUPS.
     77  * At least one of the following driver packages (choose the one which supports your printer):
     78     * Gutenprint (many printers)
     79     * SpliX (many Samsung & Xerox printers). Note that SpliX also requires custom GCC runtime, which is included in the WPI package, or available separately from http://smedley.info/gcc432.zip
     80     * HP-LIP (various printers from HP)
     81  * CUPS port driver (CUPS.PDR).  If you use the WarpIN packages, this is included in the `cups-base-*.wpi` archive
     82  * The eCups OS/2 printer driver, either ECUPS.DRV (for Gutenprint and SpliX) or ECUPS-HP.DRV (for HP-LIP). These are modified versions of the standard OS/2 !PostScript driver which include various fixes needed by CUPS.
     83  * LIBC runtime files required for CUPS and other components. (You may have these already, especially if you are running eComStation).
     84     * ftp://ftp.netlabs.org/pub/gcc/libc-0.6.3-csd3.zip
     85     * ftp://ftp.netlabs.org/pub/gcc/gcc4core.wpi
     86These are described in more detail below.
     87
     88__May be required:__
     89  * USB helper driver (required for USB printing only): http://en.ecomstation.ru/projects/usbtools/download/usbcalls-20060807.zip (again, you may have this already, especially if you use a recent version of eComStation)
     90  * `PRNDRV.EXE` is a useful program that can "clean up" printer entries in the INI files (not actually necessary for using CUPS, but can be very useful if you do a lot of creating and deleting of printers): http://www.os2site.com/sw/comm/faxworks/prndrv.exe
     91
     92
     93\\
     94=== Brief description of the software packages === #packages
     95CUPS consists of several packages that work together to provide emulated !PostScript printing on raster printers. The core components on all platforms are the CUPS daemon, Ghostscript, and the driver packages (Gutenprint, Splix, HPLIP etc.).
     96
     97The remaining packages are specific to the OS/2 port (a.k.a. eCups):
     98  * The LIBC and GCC files are required support files (the GCC runtime is required by Splix).
     99  * PRNDRV.EXE: a useful command line utility for listing installed OS/2 (not CUPS) printers, and deleting those that are no longer wanted. (Note: Be careful when using "`prndrv -d`", as it is very easy to accidentally delete important INI file entries; see the [wiki:CupsFaq#3_2 CupsFaq] for more information.)
     100  * The eCups printer driver (ECUPS.DRV or ECUPS-HP.DRV) is a customized version of the OS/2 !PostScript driver (PSCRIPT.DRV) which has most of the popular CUPS PPD files already imported, and can be updated as new printers become supported in CUPS. It also has a few tweaks and bugfixes to make it work better with CUPS. (For this reason, using the original IBM !PostScript driver for CUPS printing is not really recommended, although it may happen to work for you.)
     101  * The eCups printer port driver (CUPS.PDR) provides the "hook-up" between an OS/2 printer object/queue and the actual CUPS printer.
     102[=#portdriver]
     103The port driver component in particular is crucial, because normal OS/2 applications only know how to print to an OS/2 printer object - not a CUPS printer! What happens is that the OS/2 printer object sends print data to a port (like a parallel/serial/USB port or an LPR network queue, and so on) which is defined by a port driver. In this case, we are implementing another type of port to be available alongside these. This driver allows the OS/2 print "engine" to talk to the CUPS daemon, which turn talks to the physical printer either over the network or over a USB connection (using what it calls a "backend", which is basically CUPS's own internal equivalent of a port driver).
     104
     105Note that we don't use the OS/2 USB port driver when using a USB attached printer via CUPS — we always use the CUPS port driver and then let the CUPS daemon control the physical IO traffic to the printer. The same is true for other connection types like network connections — in all cases, CUPS manages the connection.
     106
     107As far as CUPS goes internally, the data flow is as follows:
     108
     109`PRINTER <-> IO Driver "backend" <-> CUPS daemon (CUPSD.exe) <-- CUPS admin webpage (config, test print etc.)`
     110
     111The above suffices for printing using CUPS's own internal mechanisms. What the port driver does, in conjunction with an OS/2 Printer Object, is allow normal OS/2 programs (which know nothing about CUPS) to print to CUPS printers. So the data flow becomes:
     112
     113`PRINTER <-> IO Driver "backend" <-> CUPS daemon (CUPSD.exe) <-> eCups Port Driver (CUPS.PDR) <-> PostScript printer driver (ECUPS.PDR) <-> OS/2 printer support <-> OS/2 application.`
     114
     115
     116\\\\
     117== 4. Installation == #installation
     118
     119=== Installing with WarpIN === #inst_wpi
     120There are now WarpIN (WPI) install packages available for eCups (see the CupsPort page).  It is generally recommended that you use these, as they automate some of the trickier configuration steps (especially when upgrading various components from earlier versions).  On the other hand, they are still somewhat experimental, and are not always guaranteed to include the very latest versions of all components.
     121
     122Download the required WPI packages into a single directory.  You will need:
     123  * The main CUPS package (`cups-base-`''xx''`.wpi` where ''xx'' is the version number of CUPS); this includes both CUPS itself, and the CUPS port driver.
     124  * Ghostscript (version 8.71 is strongly recommended, unless you are doing development testing).
     125  * At least one printer support package (Gutenprint, SpliX, or HP-LIP).
     126  * The ECUPS printer driver in most cases, or alternatively the ECUPS-HP printer driver if you are installing HP-LIP specifically.
     127
     128Install the selected packages by double-clicking on the `cups-base-`''xx''`.wpi` file from the Workplace Shell.  Follow the instructions shown in the installer.
     129
     130Once the installation completes, you should be able to continue with creating and configuring a printer in CUPS.
     131
     132\\
     133=== Installing manually (from the ZIP files) === #inst_zip
     134Basic manual installation consists of unzipping most of the packages into the root directory of a selected drive. It doesn't have to be the boot drive, but they must all be unzipped to the ''same'' (non-FAT) drive.
     135  * `cups-*.zip` needs to be unzipped into the root directory, thereby creating the `\cups` top-level directory.
     136  * Ghostscript needs to be unzipped into `\gs` — so that you end up with for example,''x''`:\gs\gs8.71` (some zip packages contain the \gs upper directory, some don't — so make sure you end up with the correct directory structure).
     137  * The driver package(s) you will be using (`gutenprint-*.zip`, `hplip-*.zip` and/or `splix-*.zip`) must be unzipped into the root directory on the same drive. This will add various required files to the `\cups` directory, and in the case of Gutenprint will also create the `\gutenprint` top-level directory.
     138
     139Once you have done the above, you should have the following directories off the root directory of your chosen drive:
     140  `\cups`\\
     141  `\gs`\\
     142  `\gutenprint` (if using Gutenprint)
     143
     144Have a read of the `\cups\readme.os2` before proceeding, to get an idea of what you are going to do.  Pay particular attention to the need to check/modify the Ghostscript path in `\cups\lib\cups\filter\pstoraster`.
     145
     146There are other required files which go into a couple of different locations:
     147  * The port driver is needed to enable printing from applications.  `CUPS.PDR` must be placed in `\OS2\DLL` on your boot drive so that the port install dialog can find it.  Place `CUPSLPR.EXE` into the `\TCPIP\BIN` directory on whichever drive TCP/IP is installed to (usually the boot drive).
     148  * The `LIBC0*.DLL` and `GCC*.DLL` files should be put into a directory specified within the LIBPATH — either `\ECS\DLL` or `\OS2\DLL` is fine.
     149
     150Other files can be unzipped now or later as they are required:
     151  * The ECUPS (or ECUPS-HP) printer driver can be put into a directory of your choice. You will point the printer install dialog to this directory during the install process; OS/2 will then automatically copy the files to `\OS2\DLL\ECUPS[-HP]` (which it will create if necessary).
     152  * If installing PRNDRV.EXE, just copy the file somewhere that's convenient for you.
     153
     154
     155\\
     156=== Upgrading from a Previous Version === #upgrading
     157Whether installing from WPIs or ZIP files, you can generally just install over top of the previous versions.  (If you installed from Peter Brown's old `eCUPS003.wpi`, you might want to uninstall the corresponding packages from WarpIN before installing the latest WPIs — otherwise you'll probably end up with duplicated desktop objects and some orphaned entries in the WarpIN database).
     158
     159When upgrading to the most recent release of Gutenprint, you are advised to manually delete the contents of `\cups\share\cups\model\gutenprint\5.2\C` **before** installing the new version — otherwise, you may end up with a large number of duplicate entries in the CUPS driver list.  Unfortunately, even the WPI installer does not do this automatically yet.  (This is not necessary when installing a version of Gutenprint prior to 5.2.7.)
     160
     161If upgrading with the WPI packages, generally no additional steps are necessary.  However, when upgrading from ZIP files, you will need to do a bit of extra work:
     162
     163  * When upgrading CUPS or any of the driver packages (Gutenprint, etc.), shut down the CUPS daemon (by terminating all running instances of `cupsd.exe`) before starting.
     164
     165  * When upgrading either CUPS or Ghostscript, edit the file `\cups\lib\cups\filter\pstoraster` and make sure the "`prefix=`" line points to your correct GhostScript path.
     166
     167  * After upgrading Gutenprint, go into the CUPS web interface and do the following for **all** printers which use Gutenprint drivers:
     168      1. Open the printer details by clicking on its queue name under the ''Printers'' page.
     169      2. From the ''Administration'' drop-down, select "Modify Printer".
     170      3. Leave all current settings on the first two pages unchanged; just click on ''Continue'' until you reach the printer manufacturer/model page.
     171      4. Make sure the correct manufacturer and model for your printer are selected. Also make sure that the Gutenprint version shown in the driver name are correct for the version of Gutenprint you just installed.  Then click on ''Modify Printer''.
     172      5. It's a good idea to print a test page to make sure everything still works as it should.
     173    (Alternatively, if you have Perl installed you can download and run the script [http://smedley.info/cups-genppdupdate], which does this automatically.)
     174
     175
     176\\
     177=== Starting CUPS === #starting
     178If you installed from the WarpIN packages, CUPS should have been started automatically, and you can skip this step.
     179
     180To activate CUPS, start the program ``\cups\sbin\cupsd.exe``.  This program will run continuously (until terminated), so you should run it either in a dedicated session or as a background process using "`detach`".
     181
     182You will presumably want to create a program object which does this, and place it in your Startup folder so that CUPS is started automatically at bootup.  You can make the program run
     183in the background by specifying "`cmd.exe`" as the program name, then setting the parameters to "`/c `''x''`:\cups\sbin\cupsd.exe`" and the working directory to "''x''`:\cups\sbin`" (where ''x'' is the drive letter where CUPS is installed).
     184
     185Alternatively, you can start <tt>cupsd.exe</tt> from either your `\STARTUP.CMD` or `\TCPIP\BIN\TCPEXIT.CMD` file.
     186
     187
     188\\
     189=== Using the CUPS Web Interface === #cupsgui
     190[[Image(cupsweb01.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     191
     192Once you've finished installing CUPS, you should make sure that it's up and running by opening the CUPS web interface.  This is the main configuration tool for managing CUPS on your system. You can use it to create and manage printers, enable other computers to access your CUPS printers, diagnose potential problems, and so on.
     193
     194Fire up your web browser and point it at [http://localhost:631/]. If all goes well, this should bring up the CUPS Administration GUI.
     195
     196  * If you get a "host not found" error, try using the address http://127.0.0.1:631/ instead. If that doesn't help, make sure that you have loopback enabled in your system TCP/IP configuration.
     197
     198  * Alternatively, if you get a HTTP 404 error, it means that the CUPS daemon is not running (or is broken somehow). Make sure you start `cupsd.exe` as [#starting described above].
     199
     200(In some recent CUPS versions, the logo graphic on the front page may be broken, but this appears to be a harmless cosmetic issue.)
     201
     202{{{
     203#!div style="clear: right;"
     204}}}
     205
     206
     207\\\\
     208== 5. Printing with CUPS == #printing
     209There are two basic parts to setting up a printer with CUPS.
     210  1. [#cupsprint Create and configure a CUPS printer queue]. This sets things up so that CUPS itself knows about the printer and can print to it.
     211  2. [#os2print Create and configure a desktop printer object]. This allows OS/2 applications to actually print to the CUPS printer.
     212Unfortunately, this two-phase process makes things a bit complicated.  We'll describe how to set everything up, step by step.
     213
     214\\
     215=== Creating & Configuring a CUPS Printer === #cupsprint
     216[[Image(cupsweb02.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     217First of all, if your printer is locally-attached (e.g. via USB port), make sure that it is turned on.
     218
     219Next, go into the CUPS web interface, click on the ''Administration'' tab at the top, and then select the ''Add Printer'' button.
     220
     221The examples that follow will describe the process for adding an **Epson PX-101** colour inkjet printer.
     222
     223{{{
     224#!div style="clear: right;"
     225}}}
     226
     227\\
     228==== Selecting the printer connection ==== #add_device
     229[[Image(cupsweb03.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     230When you select ''Add Printer'', CUPS scans for available printers.  Any locally-attached printers that it finds will be shown as selectable options on the following screen.  It may also detect network printers, but this seems to be a bit hit-and-miss (it probably depends on how your network is organized, among other factors).
     231
     232On this screen, select the connection that is appropriate for your printer.
     233
     234 [=#local_usb]Local printer (USB)::
     235
     236   At the moment, the only local connections that are supported directly are USB. There is a workaround which can be used to enable printing via parallel port, but it requires some special setup; [#local_lpt see below].
     237
     238   It has been reported that some older versions of the operating systems USB support files can cause problems, so please ensure you have the latest versions of the OS/2 USB stack as well as [a href="http://en.ecomstation.ru/projects/usbtools/download/usbcalls-20060807.zip USBCALLS] before you attempt this configuration.
     239
     240   If your USB printer is connected and powered on, it should show up as an option on this page. This assumes, of course, that everything is working as it should.  Refer to the box below if you are having trouble getting your USB printer recognized by CUPS.
     241   {{{
     242   #!div style=" border: 1px solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;"
     243   If your CUPS version is older than 1.3.11, you may need to download the USB backend separately from http://download.smedley.info/cups-usb-backend-20090309.zip and install it by unzipping into the `>\cups\lib\cups\backend` directory.  However, all recent releases of CUPS include this file already.
     244
     245   To verify that the USB support is working, open a command prompt and go to the `\cups\lib\cups\backend` directory.  Make sure your printer is turned on and run `usb.exe` with no parameters.  You should get a display like this:
     246
     247   `DEBUG: list_devices`\\
     248   `DEBUG: usb_find_busses=1`\\
     249   `DEBUG: usb_find_devices=2`\\
     250   `direct usb://EPSON/PX-101 "EPSON PX-101" "EPSON PX-101" "MFG:EPSON;CMD:ESCPL2,BDC,D4,D4PX;MDL:PX-101;CLS:PRINTER;DES:EPSON PX-101;" ""`
     251
     252   If you don't get such a display, check that your USB support is working correctly and that you have connected the printer with a known good cable to a known good port.
     253   }}}
     254
     255 [=#local_lpt]Parallel port connection::
     256   The OS/2 port of CUPS does not currently support printing directly to parallel printers but there is a workaround.
     257
     258   1. Create an OS/2 printer object using the IBMNULL printer driver. Select LPT''n'' as the Output Port in the printer object properties, where LPT''n'' is the name of the parallel port to which the printer is connected.
     259   2. Start the OS/2 LPD service (`lpd.exe`). To prevent LPD from printing the control file page (an almost-blank page with few lines of information good only for debugging purposes), specify the "-c" parameter.  You can use the OS/2 TCP/IP Configuration notebook to configure LPD.
     260
     261   When creating the CUPS printer, select ''LPD/LPR Host or Printer'' and enter "`lpd://localhost/`''printer_name''" as the Device URI, where ''printer_name'' is the physical name (as shown on the Properties ''View' page) of the OS/2 printer object just created.
     262
     263   For example: If you created a desktop printer with the object name "Canon iP4000", open the Properties for that printer and check the name displayed on the ''View'' page.  If the ''Physical name'' shows "CanoniP4", the device URI in CUPS should be "`lpd://localhost/CanoniP4`".
     264
     265   ||= Field =||= Description =||= Example =||
     266   || ''Device URI:''|| Address of locally-shared LPD printer || `lpd://localhost/CanoniP4` ||
     267
     268   Thanks to Rodney and others who supplied the above information regarding using locally attached printers with CUPS.
     269
     270   {{{
     271   #!div style=" border: 1px solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;"
     272   In fact, the current CUPS port does include a parallel port backend (driver), but it is completely untested due to the fact that none of developers/testers actually has a parallel-port printer.  So the above workaround may or may not still be necessary.
     273   }}}
     274
     275 [=#tcpip]Network printer::
     276   These options allow you to connect to a network printer using various supported protocols. If the printer was not automatically detected, the following screen will prompt you to enter the necessary connection information in the form of a ''URI'' (a string specifying the connection protocol and address in a URL-like syntax).
     277
     278   [[Image(cupsweb03a.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     279   The format of the URI indicates which network protocol to use, and specifies the necessary options.  You have a choice of several different protocols; obviously, use whichever one your network printer or print server supports.
     280
     281     * Internet Printing Protocol (IPP) is the newest and most advanced; the URI format is "`ipp://`''server[''`:`''port]''`/`''printer[''`?`''option''`=`''value[''`&`''option''`=`''value]]''"
     282     * LPD (or LPR) is the oldest and most widely-supported; use the URI format "`lpd://`''[userid''`@`'']server[''`:`''port]''`/`''printer''"
     283     * !AppSocket (also called !JetDirect) is also widely used; use the URI format
     284"`socket://`''server[''`:`''port]''"
     285     * Samba is for printers which are being shared out via Windows networking, IBM LAN Server, Peer for OS/2, or a Samba server.  Use the URI format "`smb://`''[userid[''`:`''password]''`@`'']server''`/`''printer''"
     286
     287   Most TCP/IP network printers use either LPD or !AppSocket (just try one or the other if you're not sure). For shared printers on a Windows server, use Samba.
     288
     289   {{{
     290   #!div style="border: 1px solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em;"
     291   If you installed CUPS from ZIP files, be aware that support for Samba is not included by default. If you want to use Samba, you need to first obtain the Samba Client Utilities package from [http://svn.netlabs.org/samba]. Extract the file `smbspool.exe`, rename it to `smb.exe` and place it into the `\cups\lib\cups\backend` directory.  You should then be able to use the CUPS Samba support.
     292
     293   The above is not necessary with the latest CUPS WarpIN packages, which include `smb.exe out of the box.
     294   }}}
     295
     296   ||= Field =||= Description =||= Example =||
     297   || ''Device URI:'' || Address of network printer || `lpd://192.168.2.1/lpt1` ||
     298
     299
     300Select the ''Continue'' button when you are done with this section.
     301
     302{{{
     303#!div style="clear: right;"
     304}}}
     305
     306\\
     307==== Identifying the printer ==== #add_name
     308[[Image(cupsweb04.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     309On the next page, you will be asked to give your printer a name, which CUPS itself will use to identify it.  You will also need to enter a description and a location; these are for the benefit of actual human beings.
     310
     311||= Field =||= Description =||
     312|| ''Name:'' || A short name which CUPS will use to identify the printer || PX-101 ||
     313|| ''Description:'' || A human-readable description of the printer || Epson PX-101 inkjet ||
     314|| ''Location:'' || A brief description of where the printer is physically located || Home ||
     315
     316The ''Share this printer'' checkbox allows other computers on the local network to use this printer (by accessing the current computer as a print server).
     317
     318Select ''Continue'' when you are happy with this section.
     319
     320{{{
     321#!div style="clear: right;"
     322}}}
     323
     324\\
     325==== Selecting the printer model ==== #add_model
     326[[Image(cupsweb05.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     327This is where you select your printer's make and model.  This is obviously pretty important as it determines the driver that CUPS will use.
     328
     329There are two ways to specify the printer.
     330
     331  * In most cases, you will choose the manufacturer and printer model from the list shown. (If the printer was auto-detected by CUPS, the manufacturer will probably be preselected and you'll only need to choose the right printer model.)  Generally, the list of models will show the printer model, followed by a dash and then the name of the driver package it belongs to (such as Gutenprint).
     332
     333    Note that Gutenprint in particular normally provides two alternate drivers for each printer: a standard driver, and one called 'Simplified'.  The difference is in the level of configurability — the standard drivers support fine-tuning a number of advanced settings related to quality and colour balance.  In almost all cases, you will prefer the Simplified drivers, which are more than sufficient for most needs.
     334
     335  * If your printer model isn't listed, but you have a PPD file for your printer, supporting one of the installed driver packages (Gutenprint, etc.), then you can specify that in the field at the bottom.
     336
     337    Note that any PPD file you provide here must be specifically written for use with CUPS in conjunction with one of the driver packages you have installed.  You **cannot** use a standard (e.g. Windows) PPD for this purpose.
     338
     339Click on ''Add Printer'' when you are happy with your selections.
     340
     341{{{
     342#!div style="clear: right;"
     343}}}
     344
     345\\
     346==== Setting the default print options ==== #add_options
     347[[Image(cupsweb06.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     348After clicking ''Add Printer'' on the screen above, CUPS will load the options for the printer. This can take a little while — it is a good idea to have a look through and make sure the options look useable — especially the media size, type, and print quality settings.
     349
     350You can use the links near the top to browse various different option categories.  In most cases, you won't need to change much beyond the first page ("General").
     351
     352When satisfied, click ''Set Default Options''.  CUPS should report that your printer has been configured successfully.
     353
     354{{{
     355#!div style="border: 1px solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em; clear: right;"
     356If you see an "Internal Server Error" message right after configuring a printer, just reload the top-level page of the CUPS web interface.  This seems to be a (relatively) harmless bug that occurs now and then with some versions of CUPS.
     357}}}
     358
     359\\
     360==== Testing the CUPS printer ==== #cupstest
     361Click on the ''Printers'' tab.  The new printer should be listed.
     362
     363[[Image(cupsweb07.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     364{{{
     365#!div style="clear: left;"
     366}}}
     367
     368Click on the queue name to view the printer details.
     369
     370Under the ''Maintenance'' dropdown, choose "Print Test Page".  If all goes well the CUPS test page should pop out of the printer looking fine.
     371
     372[[Image(cupsweb08.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     373
     374{{{
     375#!div style="clear: left;"
     376}}}
     377
     378\\
     379==== Printing from CUPS ==== #cupslpr
     380You should now be able to print files using CUPS's own internal tools.
     381
     382The basic CUPS print command is `\cups\bin\lpr.exe`. (This is **not** the same as OS/2's native LPR command; this one is specific to CUPS, and is not installed to the system PATH.)  Assuming you have the CUPS port driver installed properly, you can also use the `cupslpr` command (just a renamed version of the above), which should be available on the PATH.
     383
     384You can use these programs to print standard !PostScript (`.ps`) files from a command prompt:
     385
     386    `cupslpr -P `''printer file
     387
     388where ''printer'' is the name of the CUPS printer, and ''file'' is a previously-generated !PostScript file.
     389
     390If this all works then you know that CUPS is configured and working correctly.
     391
     392Now the easy part is finished...
     393
     394\\
     395=== Creating a desktop printer object to use with CUPS === #os2print
     396Now to hook CUPS up to the rest of the system so that CUPS can be used for output by applications (like OpenOffice, Firefox, Lucide, PMMail, PMView... everything, basically).
     397
     398\\
     399==== Preparation ==== #obj_prep
     400If you haven't done so already, make sure you have the ECUPS or ECUPS-HP printer driver files on your disk — either by unzipping the ZIP file, or installing the WPI, into a directory of your choice.  It doesn't really matter where this directory is; just make sure you make a note of the path, because you'll need to type it into the driver dialog (below).  I suggest somewhere like `\ECS\INSTALL\PRNDRV\ECUPS` — you'll probably want to keep these files around in case you ever need to install another included printer model (or to import a PPD file).
     401
     402If you installed CUPS from ZIP files, make sure that you remembered to install port driver. As a reminder, `CUPS.PDR` must be in your `\OS2\DLL` directory, and `CUPSLPR.EXE` needs to be in `\TCPIP\BIN`. (If you installed from the WPI packages, this was done for you.)
     403
     404\\
     405
     406==== Creating the printer ==== #object
     407Open the desktop Templates folder and double-click on the Printer template or drag it to the Desktop in order to start the printer creation routine.  If you have eComStation, you can also use the ''Install Printer'' object in the Printers folder and select "Standard printer" (may be called "Local printer" in some versions).
     408
     409[[Image(obj_create01.png, right, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     410
     411On the "Create a Printer" dialog, select the ''Install new printer driver'' button.
     412
     413Select the ''Other eComstation printer driver'' radio-button, and enter the path to where you placed the ECUPS driver files.  Then click on ''Refresh'' (at the bottom of the dialog) to see the list of printers.
     414
     415Select your printer from the list and then click on ''Install''. The driver for the selected model will be installed.  (The "Install New Printer Driver" dialog may or may not close automatically when this is done; if it doesn't, just click on ''Cancel''.)
     416
     417{{{
     418#!div style="border: 1px solid black; background: #f0f0f0; font-size: smaller; padding: 0 0.5em 0 0.5em; clear: right;"
     419If your printer model isn't shown in the list here, but ''was'' listed in CUPS, it means that the PPD for that printer was not pre-imported into the ECUPS (or ECUPS-HP) driver.
     420
     421If you are adventurous and/or technically inclined, you can try to import the PPD file yourself, using the `PIN.EXE` utility included with the driver files (assuming that you already installed the printer in CUPS, the PPD file can be found under `\cups\etc\cups\ppd`).
     422
     423Alternatively, you can simply select "Generic !PostScript Printer" from the list.  This will prevent you from using the OS/2 Job Properties dialog to set print options from within applications — the default settings configured in the CUPS web interface will most likely always be used — but printing should more or less work.
     424}}}
     425
     426[[Image(obj_create02.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     427{{{
     428#!div style="clear: left;"
     429}}}
     430
     431When you are back on the "Create a Printer" dialog, the new driver should appear. Select the driver, and also type a name for your printer into the entryfield at the top.
     432
     433You also need to select an output port.  We could install the CUPS port now, but it's simpler to just choose a temporary port like LPT1 for the time being, and set things up properly later.
     434
     435\\
     436==== Configuring the printer ==== #obj_set
     437Now we need to configure the new printer object so that it prints through CUPS.
     438
     439  1. Click mouse button 2 on the new desktop printer object, and select Properties.
     440
     441  2. Select the ''Printer driver'' tab.
     442
     443     [[Image(obj_props01.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     444     {{{
     445     #!div style="clear: left;"
     446     }}}
     447
     448     Verify that the correct printer driver is selected.
     449
     450  3. Open the ''Job Properties'' dialog.  The Paper size, Tray, Media Type, etc. should match the settings in the CUPS printer.
     451
     452     [[Image(obj_props02.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     453     {{{
     454     #!div style="clear: left;"
     455     }}}
     456
     457     Save your changes when done.
     458
     459  4. Select the ''Output port'' tab.
     460
     461     Click on the ''Install new port'' button.
     462
     463     [[Image(obj_port01.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     464     {{{
     465     #!div style="clear: left;"
     466     }}}
     467
     468     If the "CUPS" port option is not visible but the file `CUPS.PDR` is in `\OS2\DLL`, select ''New port drivers'' and type in ''x''`:\OS2\DLL` (where ''x'' is your boot drive), then click on ''Refresh''. The "CUPS" port option should appear.
     469
     470     Select the "CUPS" port and click ''Install''.
     471
     472     [[Image(obj_port03.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     473     {{{
     474     #!div style="clear: left;"
     475     }}}
     476
     477     **Note:** You will need to install a separate "CUPS''x''" port for each CUPS printer that you wish to install (CUPS1, CUPS2, CUPS3, etc.).
     478
     479  5. Double-click on the CUPS''x'' port (or click mouse button 2 and select "Properties").
     480
     481     [[Image(obj_port02.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     482     {{{
     483     #!div style="clear: left;"
     484     }}}
     485
     486     The required settings for the CUPS port are:
     487     CUPS Server::
     488       "`localhost`" (or use 127.0.0.1).
     489     CUPS Printer Name::
     490       This should be the same name as used for creating the CUPS printer (in the CUPS web interface [#add_name above]).
     491
     492     Select ''OK'' when done.
     493
     494  6. Set any other printer properties that you deem appropriate.  Personally, I like to set the printer object view to Detail.
     495
     496     I also suggest editing the default driver properties (by double-clicking on the driver name) and bumping up the maximum number of downloaded fonts on the ''Options'' page — my rule of thumb is to allow about 5 fonts per megabyte of RAM in the printer. This can make large documents print a bit faster when using Type 1 fonts, and in the case of laser printers can also make a visible difference in print quality (although with a typical inkjet you probably wouldn't be able to tell).
     497
     498     [[Image(obj_props02.png, left, border=1, margin-left=5, margin-bottom=10, width=35%)]]
     499     {{{
     500     #!div style="clear: left;"
     501     }}}
     502
     503  7. Close the printer properties notebook.
     504
     505
     506That should complete the setup.  Now it's time to print a test page using the desktop printer object.
     507
     508  1. Verify that `cupsd.exe` is running before testing.
     509  2. Drag-and-drop the file `\cups\share\cups\data\testprint.ps` onto the new desktop printer object.
     510  3. Select ''Printer-specific'' when prompted.
     511
     512You should get the CUPS test page printed.
     513
     514The next test is to print a multiple-page document from your favourite word processor, followed
    758515by printing other document types from an arbitrary application (e.g. photos from PMView, web pages
    759516from Firefox, etc.) using your new OS/2 printer object.</p>
    760517
    761 <p>If you have problems, you might want to check the
    762 <a href="http://svn.netlabs.org/ecups/wiki/CupsFaq">CupsFaq</a> (in particular the Troubleshooting
    763 section).  You can also ask for help on the
    764 <a href="http://dir.gmane.org/gmane.org.netlabs.ecups.devel">eCups development list</a>.
    765 
    766 <p>Have fun and thanks to Paul Smedley for all his good work!</p>
    767 
    768 
    769 <p><br><a name="about"></a>
    770 <h2>About this Document</h2>
    771 
    772 <p><a name="credits"></a>
    773 <h3>Contributors</h3>
    774 <p><ul>
    775 <li>Peter Brown (original author)
    776 <li>Paul Smedley
    777 <li>Ed Durrant
    778 <li>Alex Taylor
    779 </ul></p>
    780 
    781 <p>Ed Durrant wrote a nice <a href="http://svn.netlabs.org/ecups/wiki/VisualStepByStep">visual step-by-step guide</a> for an earlier version of this HOWTO, which has now been moved to its own page.</p>
    782 
    783 <p><br><a name="history"></a>
    784 <h3>Revision History</h3>
    785 <p></p>
    786 <table border="1" cellpadding="2" cellspacing="0">
    787 <tr><td>Revision 1</td>
    788     <td>14/08/2008</td> <td>Peter Brown</td></tr>
    789 <tr><td>Revisions to filenames</td>
    790     <td>29/12/2008</td> <td>Paul Smedley</td></tr>
    791 <tr><td>Revisions to USB section</td>
    792     <td>29/03/2009</td> <td>Paul Smedley</td></tr>
    793 <tr><td>Revisions to the list of required software and brief description of software sections</td>
    794     <td>11/04/2009</td> <td>Ed Durrant</td></tr>
    795 <tr><td>Additional details about using USB interface and visual instructions around set up of CUPS web admin printer install</td>
    796     <td>12/04/2009</td> <td>Ed Durrant</td></tr>
    797 <tr><td>Additional visual instructions around set up of OS/2 printer object to use CUPS attached printer</td>
    798     <td>13/04/2009</td> <td>Ed Durrant</td></tr>
    799 <tr><td>Changes to the desktop printer object setup based on the later versions of the files for clarification</td>
    800     <td>10/07/2009</td> <td>Ed Durrant</td></tr>
    801 <tr><td>Various formatting improvements and clarifications</td>
    802     <td>2010-11-08</td> <td>Alex Taylor</td></tr>
    803 <tr><td>Formatting improvements and clarifications, continued</td>
    804     <td>2010-12-11</td> <td>Alex Taylor</td></tr>
    805 <tr><td>Added warning about the (hard-learned) pitfalls of prndrv -d</td>
    806     <td>2011-02-17</td> <td>Alex Taylor</td></tr>
    807 <tr><td>Added links to table of contents</td>
    808     <td>2011-12-12</td> <td>Alex Taylor</td></tr>
    809 <tr><td>Massive rewrite &amp; reorganization of content (with all new screenshots).  Converted to HTML.</td>
    810     <td>2011-12-17</td> <td>Alex Taylor</td></tr>
    811 </table>
    812 }}}
     518If you have problems, you might want to check the CupsFaq (in particular the Troubleshooting section). You can also ask for help on the [http://dir.gmane.org/gmane.org.netlabs.ecups.devel eCups development list].
     519
     520Have fun and thanks to Paul Smedley for all his good work!
     521
     522
     523\\\\
     524== About this Document == #about
     525
     526=== Contributors === #credits
     527
     528 * Peter Brown (original author)
     529 * Paul Smedley
     530 * Ed Durrant
     531 * Alex Taylor
     532
     533Ed Durrant wrote a nice [VisualStepByStep visual step-by-step guide] for an earlier version of this HOWTO, which has now been moved to its own page.
     534
     535\\
     536=== Revision History === #history
     537
     538|| Revision 1 || 14/08/2008 || Peter Brown ||
     539|| Revisions to filenames || 29/12/2008 || Paul Smedley ||
     540|| Revisions to USB section || 29/03/2009 || Paul Smedley ||
     541|| Revisions to the list of required software and brief description of software sections || 11/04/2009 || Ed Durrant ||
     542|| Additional details about using USB interface and visual instructions around set up of CUPS web admin printer install || 12/04/2009 || Ed Durrant ||
     543|| Additional visual instructions around set up of OS/2 printer object to use CUPS attached printer || 13/04/2009 || Ed Durrant ||
     544|| Changes to the desktop printer object setup based on the later versions of the files for clarification || 10/07/2009 || Ed Durrant ||
     545|| Various formatting improvements and clarifications || 2010-11-08 || Alex Taylor ||
     546|| Formatting improvements and clarifications, continued || 2010-12-11 || Alex Taylor ||
     547|| Added warning about the (hard-learned) pitfalls of `prndrv -d` || 2011-02-17 || Alex Taylor ||
     548|| Added links to table of contents || 2011-12-12 || Alex Taylor ||
     549|| Massive rewrite & reorganization of content (with all new screenshots). || 2011-12-19 || Alex Taylor ||