sane-project-backends/README

How to configure, build, and install SANE.

Introduction:
=============
SANE stands for Scanner Access Now Easy.
This package contains the SANE libraries (this means backends and
network scanning parts) and the command line frontend scanimage.
You always find the most recent version of SANE on:

  http://www.mostang.com/sane

The source is available via anonymous CVS, hosted by The Hungry
Programmers. Information on the CVS repository is available from
<URL:http://www.student.uit.no/~pere/linux/sane/cvs-server.html>.  The
following will fetch the latests source:

  cvs -d :pserver:anoncvs@anoncvs.hungry.com:/cvsroot login 
  [password "anoncvs"] 
  cvs -d :pserver:anoncvs@anoncvs.hungry.com:/cvsroot co sane

There are several graphical frontends available for SANE.
XSane is available on http://www.xsane.org
The graphical frontends that have been included into the sane package up to
version sane-1.0.3 (xscanimage and xcam) have been put into an own package
sane-frontends-1.0.x, this package is available on http://www.mostang.com/sane


Quick install:
==============

./configure
make
make install

Prerequisites
=============

In order to build SANE, the following tools and libraries are required:

	- GNU make: version 3.70 or newer

	- ANSI C compiler: GNU C (gcc) is recommended for best performance,
	  but any ANSI-compliant compiler should do

SANE should build on most Unix-like systems. Support for OS/2 is also
available. For more details look at the operating system specific README.*
files. For a detailed support matrix, see:

    http://www.mostang.com/sane/sane-support.html

This table may be out of date. Please send any corrections or additions to
sane-devel@mostang.com together with your platform, os and version.


Configuration
=============

Simply invoke configure in the top-level directory.  Besides the usual GNU
configure options, there are the following SANE specific options:

 --disable-shared
	Don't use shared libraries.  Useful for debugging or when there
	is a problem building shared libraries.  This implicitly turns
	on --disable-dynamic as well.

 --disable-dynamic
	Disable dynamic loading of backends (in the dll backend).
	configure normally turns on dynamic loading when it
	can find the appropriate header files and libraries
	(<dlfcn.h> and -dl).

 --enable-preload
        Preload backends into DLL backend.  This is useful for debugging,
	when dynamic loading is unavailable, or to reduce runtime linking
	overheads.  If dynamic loading or shared libraries are unavailable
	or disabled, this option is turned on automatically.
	
 --enable-scsibuffersize=N 
        Specify the buffer size of the buffer for SCSI commands. The default
	value is 131072 bytes (128 kb). This may be changed at runtime by
	setting	the environment variable SANE_SG_BUFFERSIZE to the desired
	value. The option is Linux-only at this time.
	--enable-scsibuffersize and SANE_SG_BUFFERSIZE have no effect for
	the Mustek, Umax and Sharp backends. For these backends, the buffer
	size is set automatically and/or can be specified in the backend's
	configuration file. Please refer to the backend's man pages for
	details.

In addition to these SANE-specific configuration options, there are
many standard-options.  To get a description of available standard
option, invoke configure with option --help.

If you plan on debugging one of the SANE programs, we recommend to run
configure like this:

   CFLAGS="-g -O -Wall" ./configure --disable-shared

For operating system specific information, look at the README.* files.


Build
=====

To build SANE, simply type "make" in the top-level directory.


Installation and Configuration
==============================

Once the build has finished, install SANE with "make install".  By
default, this will place the SANE libraries in /usr/local/lib/, the
configuration files in /usr/local/etc/sane.d/, and the manual pages in
/usr/local/man/.  The location of these directories can be overridden
with configure options; see "configure --help" for details.

Before running any SANE program, read the PROBLEMS file in this directory.
For information on configuring and trouble-shooting the various SANE
components, please refer to the manual pages and other documentation listed
below:

  Regarding:	           Read:
  -----------------        ------------------------------------------
  Frontends:
    scanimage              scanimage(1)
    saned		   saned(1)

  Backends for scanners:
    Abaton                 sane-abaton(5)
    AGFA Focus             sane-agfafocus(5)
    AGFA SnapScan          sane-snapscan(5)
    Apple                  sane-apple(5)
    Artec                  sane-artec(5)
    Artec AS6E parport     sane-as6e(5)
    Avision                sane-avision(5)
    Bell+Howell CopiscanII sane-bh(5)
    Canon                  sane-canon(5)
    Nikon Coolscan         sane-coolscan(5)
    Epson                  sane-epson(5)
    Fujitsu                sane-fujitsu(5)
    HP                     sane-hp(5)
    Microtek               sane-microtek(5)
    Microtek SCSI-2        sane-microtek2(5)
    Mustek                 sane-mustek(5)
    Mustek parallel port   sane-mustek_pp(5)
    NEC                    sane-nec(5)
    Pacific Image          sane-pie(5)
    Plustek                sane-plustek(5)
    Ricoh                  sane-ricoh(5)
    Sharp                  sane-sharp(5)
    Siemens S9036          sane-s9036(5)
    Siemens ST400,ST800    sane-st400(5)
    Tamarack               sane-tamarack(5)
    UMAX SCSI              sane-umax(5)
    UMAX parallel port     sane-umax_pp(5)
    
  Backends for digital cameras:
    Connectix QuickCam     sane-qcam(5)
    Kodak DC20/DC25        sane-dc25(5)
    Kodak dc210            sane-dc210(5)
    Kodak dc240            sane-dc240(5)
    Polaroid               sane-dmc(5)
  
  Miscellaneous backends:
    PNM image reader       sane-pnm(5)
    PINT scanners          sane-pint(5)
    Video for Linux        sane-v4l(5)

  Miscellaneous:
    Dynamic loading        sane-dll(5)
    Networking             sane-net(5) and saned(1)
    SCSI configuration     sane-scsi(5)

For more details on supported scanners and cameras look at the SANE website:
http://www.mostang.com/sane/sane-backends.html.

Concerning frontends (applications): Starting from SANE 1.0.4, only scanimage
is included in the package. Some of the available frontends can be found in
the separate package sane-frontends.  For more information about frontends and
where to get them look at http://www.mostang.com/sane/sane-frontends.html.

Please note that the default configuration uses sane-dll as the top-level
backend.  Hence it is probably a good idea to start with reading sane-dll(5).
The top-level backend is determined by the libsane.* symlinks in
/usr/local/lib/.

For SCSI scanners reading of sane-scsi(5) is recommended.

Please also read the file PROJECTS for projects that are planned or not yet
included into the SANE distribution.

If you encounter any problems with getting your device(s) recognized, try
setting the various environment variables that are available to assist in
debugging such problems.  The environment variables are documented in the
relevant manual pages.  For example, to get the maximum amount of debug
information when testing a Mustek scanner, set environment variables
SANE_DEBUG_DLL, SANE_DEBUG_MUSTEK, and SANE_DEBUG_SANEI_SCSI to 128 and then
invoke scanimage or whatever program you're trying to debug.  For a Mustek
scanner at /dev/scanner, you might want to invoke scanimage as follows:

	scanimage -d mustek:/dev/scanner -h

If this works, you could try to acquire an image with:

	scanimage -d mustek:/dev/scanner >t.pnm

If you are not sure what generic SCSI device your scanner is connected to, try
the command sane-find-scanner.  It is normally sufficient to invoke the
program without any arguments.  Invoking this command should produce output
similar to this:

  $ sane-find-scanner
  sane-find-scanner: found "MUSTEK MFC-06000CZ 1.01" at device /dev/scanner
  sane-find-scanner: found "MUSTEK MFC-06000CZ 1.01" at device /dev/sge

Note that sane-find-scanner will find any scanner that is connected to a SCSI
bus.  It will even find scanners that are not supported at all by SANE.

There may be several causes for the following messages from the frontends:
"scanimage: no SANE devices found" or "xscanimage: no devices available.".
 
  * Your scanner is not recognized by any backend. It is not supported.
    You may ask the maintainer of your backend (see AUTHORS) or 
    sane-devel@mostang.com if support is planned.
 
  * SANE can't access the device files (e.g /dev/sga). Check the permissions.

  * Your backend is not listed in dll.conf (or commented out).

The tools directory contains some small programs that may be helpfull. They
are described in tools/README.