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.sane-project.org/

At the same location there are also links to snapshots of the Git server and
sometimes beta releases of sane-backends. These are unstable development
versions, so be careful when using them. Please report any problems to us. See
contact section for details.

There are several graphical frontends available for SANE, see the list at
http://www.sane-project.org/sane-frontends.html.


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

./autogen.sh    # only if you just cloned the git repository
./configure
make
make install

man sane

Pre-built binaries:
===================

In addition to versions included in releases, some platforms have more current versions available.

Ubuntu PPA https://launchpad.net/~sane-project/+archive/ubuntu/sane-release

sudo add-apt-repository ppa:sane-project/sane-release
sudo apt update
apt install libsane libsane-common sane-utils


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

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

	- GNU make: version 3.70 or newer

	- ISO C99 compiler: GNU C (gcc) is recommended for best results,
	  but any ISO C99 compliant compiler should do


Some more libraries are not strictly necessary to compile SANE, but some
functionality may be lost if they are not available. Make sure that these
libraries and their respective header files are available before running
configure. On some Linux distributions the header files are part of separate
packages (e.g. usb.h in libusb-devel or libusb-dev). These must also be
installed.

        - libusb: Strongly recommended if you use a USB scanner.
          Some backends won't work without libusb at all.

        - libjpeg (>=6B): For the dc210, dc240, and gphoto2 backends.

        - libieee1284 (>=0.1.5): For some parallel port backends.

        - libgphoto2 (>=2.0): For the gphoto2 backend.

        - a C++11 compliant C++ compiler for the genesys backend.

If you got the source straight from the git repository, as opposed to
a source tarball, you will need a few more utilities.  These utilities
should normally *not* be needed for source archives downloaded from
the project's website at http://www.sane-project.org/.

        - autoconf (>= 2.69) as well as the autoconf-archive (for the
          AX_CXX_COMPILE_STDCXX and AX_CXX_COMPILE_STDCXX_11 macros)

        - automake (>=1.15)

        - libtool (>=2.4.6)

        - gettext (>=0.19.8)

        - git (>= 2.1.4)

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

    http://www.sane-project.org/sane-support.html

This table may be out of date. Please tell us about any corrections or
additions. Please mention your operating system and platform and all the other
details mentioned in the table. See also the contact section.

Please check that there aren't any older versions of SANE installed on your
system. Especially if SANE libraries are installed in a different prefix
directory (e.g. /usr/lib/) this may cause problems with external
frontends. Please remove these libraries (libsane.*, sane/libsane-*) by using
your package manager or manually before installing this version of SANE.


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 --enable-static 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 -ldl).

 --enable-static
        Use static libraries (turned off by default).

 --enable-preload
        Preload backends into DLL backend.  This is useful for debugging,
	when dynamic loading is unavailable, to reduce runtime linking
	overheads, or when you only want to distribute a single DLL with
	all backends available.  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.

--enable-locking
	Means, that some backends will use a lockfile for allowing multiple
	access to one scanner. This is useful, i.e. one frontend is scanning
	the button status and another one will scan. The path to the lock
	files is defined by --localstatedir at the configure step and is
	$localstatedir/lock. The default group is uucp and can be changed
	by using --with-group=newgroup. If you do not want any backend to
	use a lockfile, simply use --disable-locking.
	Note: The Plustek backend is currently the only backend that makes
	      use of this feature.

To limit the backends that are compiled, set the variable BACKENDS to
the list of backends to compile.  The following will limit compiling
to the epson2 and fujitsu backends:

  ./configure BACKENDS="epson2 fujitsu"

To limit the backends that are preloaded into the DLL, set the variable
PRELOADABLE_BACKENDS.  The following will limit compiling to the epson2
and fujitsu backends but only preloads the epson2 backend:

  ./configure BACKENDS="epson2 fujitsu" PRELOADABLE_BACKENDS="epson2"

In addition to these configuration options, there are some more SANE-specific
options and many standard-options.  To get a description of available options,
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.

To clean up the executables and libraries in the source directory, type "make
clean". To restore everything to the status after unpacking the package, type
"make distclean".


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 page sane(7).

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


Removing
========

Type "make uninstall" to remove SANE from your system. This will also remove
older versions of SANE if they have been installed at the same prefix.
Warning: Your configuration files will be deleted also so make sure you have a
backup. By default the configuration files are located in the directory
/usr/local/etc/sane.d/.


Contact
=======

For questions and general discussion about SANE contact the sane-devel mailing
list. You must be subscribed to the list to send mail. See
http://www.sane-project.org/mailing-lists.html for details.

If you want to submit a bug report or feature request please use our bug
tracking system.  See http://www.sane-project.org/bugs.html for details. You
may also contact the author of a specific backend directly. See the AUTHORS
file for a list of addresses.

Under AIX, you'll need the generic SCSI device driver gsc written by
Matthew Jacob <mjacob@feral.com> (nice piece of work!). When you
install this driver, copy the header file gscdds.h to /usr/include, as
we look for it there.
Find this driver under:

	ftp://ftp.feral.com/pub/aix/gsc.tar.gz
	ftp://ftp.thp.Uni-Duisburg.DE/pub/source/gsc.tar.gz

A version for AIX 4.3.3 and AIX 5.1 is also available.

	http://www.zago.net/aix/gsc-1.1.tar.gz

SANE and BeOS
-------------

The information in this text is from an article of Philippe Houdoin
<philippe.houdoin@free.fr> on sane-devel (29 Aug 2002).

SANE 1.0.3 was first ported to BeOS, under the name BeSANE,
by Massimiliano Origgi:
http://www.intuiware.com/Products/BeSANE/index.html

SANE 1.0.5 BeOS port and fixes to some issues with original BeSANE port were
made by Philippe Houdoin but aren't released until now.

BeOS GUI SANE frontend project (by Philippe Houdoin):
http://philippe.houdoin.free.fr/phil/beos/sanity/index-en.html

Updates of Sanity from Kaya Memisoglu:
http://www.bebits.com/app/2847

SANE was reported to work with the following configuration and features:

Platform: BeOS R5.0.x ix86
Latest SANE version tested: 1.0.5
Compiler: gcc 2.95.3
User-level SCSI support: yes
USB support: yes
Shared library support: yes
Dynamic loading support: yes
X11 clients: no

SANE and Darwin (Mac OS X)
--------------------------

Building:
---------
You may get the message: "gcc: Internal compiler error: program cc1obj got
fatal signal 11". That's not a bug in SANE. Probably a compiler or hardware
problem.  The error usually occurs in canon.c because that's the most complex
backend (at least concerning compilation). If you can't update your compiler,
try to reduce optimization (e.g. CFLAGS="-O1" ./configure). Another
work-around: Disable the canon backend in backend/Makefile.in (look at
PRELOADABLE_BACKENDS) and rerun configure.

General:
--------
If scanimage -L (or any other frontend) stops with a segmentation fault in the
sm3600 backend, disable sm3600 in dll.conf if you don't need it.

Backends that use the function "fork" may not work at least with USB scanners.
That's a limitation of MacOS X (doesn't use file descriptors for USB access).
Most backends have been modified to use threads on MacOS X and should
work. Others don't use fork at all. Both types of backends should work with
MacOS X. Changing the backends to use threads is an ongoing effort.

SCSI-scanners and Firewire scanners:
------------------------------------
There is support for SCSI and Firewire scanners but hasn't had much
testing. Please send failure and success reports to the sane-devel mailing
list. At least the Epson Perfection 1640SU and the CANON IX-06015C (CanoScan
600) are reported to work.

USB-scanners:
-------------
Work with libusb. Try "sane-find-scanner -v -v" and report success or
failure to the SANE mailing list. At least the following scanners are
known to work: UMAX Astra 1220U and 2000U, Epson Perfection 1640SU and
2450 Photo.

Use libusb version 0.1.11 or later (or a cvs checkout from 2005-09-01
or later). If you use earlier versions the libusb code needs to be
patched.

Parport-scanners:
-----------------
I don't have any information about these. Please contact me or the SANE mailing
list if you succeeded in using one of these.

2003-12-26 Henning Meier-Geinitz <henning@meier-geinitz.de>
2005-05-07 Mattias Ellert <mattias.ellert@tsl.uu.se>

The JPEG decoder in SANE is taken mostly without change from The
Independent JPEG Group's JPEG software, release 6a.  Their "djpeg.README"
file is included below.  The only changes are to file names, e.g.
djpeg.c -> sanei_jpeg.c, and function names,
e.g. sanei_jpeg_start_output_ppm()


The Independent JPEG Group's JPEG software
==========================================

README for release 6a of 7-Feb-96
=================================

This distribution contains the sixth public release of the Independent JPEG
Group's free JPEG software.  You are welcome to redistribute this software and
to use it for any purpose, subject to the conditions under LEGAL ISSUES, below.

Serious users of this software (particularly those incorporating it into
larger programs) should contact IJG at jpeg-info@uunet.uu.net to be added to
our electronic mailing list.  Mailing list members are notified of updates
and have a chance to participate in technical discussions, etc.

This software is the work of Tom Lane, Philip Gladstone, Luis Ortiz, Jim
Boucher, Lee Crocker, Julian Minguillon, George Phillips, Davide Rossi,
Ge' Weijers, and other members of the Independent JPEG Group.

IJG is not affiliated with the official ISO JPEG standards committee.


DOCUMENTATION ROADMAP
=====================

This file contains the following sections:

OVERVIEW            General description of JPEG and the IJG software.
LEGAL ISSUES        Copyright, lack of warranty, terms of distribution.
REFERENCES          Where to learn more about JPEG.
ARCHIVE LOCATIONS   Where to find newer versions of this software.
RELATED SOFTWARE    Other stuff you should get.
FILE FORMAT WARS    Software *not* to get.
TO DO               Plans for future IJG releases.

Other documentation files in the distribution are:

User documentation:
  install.doc       How to configure and install the IJG software.
  usage.doc         Usage instructions for cjpeg, djpeg, jpegtran,
                    rdjpgcom, and wrjpgcom.
  *.1               Unix-style man pages for programs (same info as usage.doc).
  wizard.doc        Advanced usage instructions for JPEG wizards only.
  change.log        Version-to-version change highlights.
Programmer and internal documentation:
  libjpeg.doc       How to use the JPEG library in your own programs.
  example.c         Sample code for calling the JPEG library.
  structure.doc     Overview of the JPEG library's internal structure.
  filelist.doc      Road map of IJG files.
  coderules.doc     Coding style rules --- please read if you contribute code.

Please read at least the files install.doc and usage.doc.  Useful information
can also be found in the JPEG FAQ (Frequently Asked Questions) article.  See
ARCHIVE LOCATIONS below to find out where to obtain the FAQ article.

If you want to understand how the JPEG code works, we suggest reading one or
more of the REFERENCES, then looking at the documentation files (in roughly
the order listed) before diving into the code.


OVERVIEW
========

This package contains C software to implement JPEG image compression and
decompression.  JPEG (pronounced "jay-peg") is a standardized compression
method for full-color and gray-scale images.  JPEG is intended for compressing
"real-world" scenes; line drawings, cartoons and other non-realistic images
are not its strong suit.  JPEG is lossy, meaning that the output image is not
exactly identical to the input image.  Hence you must not use JPEG if you
have to have identical output bits.  However, on typical photographic images,
very good compression levels can be obtained with no visible change, and
remarkably high compression levels are possible if you can tolerate a
low-quality image.  For more details, see the references, or just experiment
with various compression settings.

This software implements JPEG baseline, extended-sequential, and progressive
compression processes.  Provision is made for supporting all variants of these
processes, although some uncommon parameter settings aren't implemented yet.
For legal reasons, we are not distributing code for the arithmetic-coding
variants of JPEG; see LEGAL ISSUES.  We have made no provision for supporting
the hierarchical or lossless processes defined in the standard.

We provide a set of library routines for reading and writing JPEG image files,
plus two sample applications "cjpeg" and "djpeg", which use the library to
perform conversion between JPEG and some other popular image file formats.
The library is intended to be reused in other applications.

In order to support file conversion and viewing software, we have included
considerable functionality beyond the bare JPEG coding/decoding capability;
for example, the color quantization modules are not strictly part of JPEG
decoding, but they are essential for output to colormapped file formats or
colormapped displays.  These extra functions can be compiled out of the
library if not required for a particular application.  We have also included
"jpegtran", a utility for lossless transcoding between different JPEG
processes, and "rdjpgcom" and "wrjpgcom", two simple applications for
inserting and extracting textual comments in JFIF files.

The emphasis in designing this software has been on achieving portability and
flexibility, while also making it fast enough to be useful.  In particular,
the software is not intended to be read as a tutorial on JPEG.  (See the
REFERENCES section for introductory material.)  Rather, it is intended to
be reliable, portable, industrial-strength code.  We do not claim to have
achieved that goal in every aspect of the software, but we strive for it.

We welcome the use of this software as a component of commercial products.
No royalty is required, but we do ask for an acknowledgement in product
documentation, as described under LEGAL ISSUES.


LEGAL ISSUES
============

In plain English:

1. We don't promise that this software works.  (But if you find any bugs,
   please let us know!)
2. You can use this software for whatever you want.  You don't have to pay us.
3. You may not pretend that you wrote this software.  If you use it in a
   program, you must acknowledge somewhere in your documentation that
   you've used the IJG code.

In legalese:

The authors make NO WARRANTY or representation, either express or implied,
with respect to this software, its quality, accuracy, merchantability, or
fitness for a particular purpose.  This software is provided "AS IS", and you,
its user, assume the entire risk as to its quality and accuracy.

This software is copyright (C) 1991-1996, Thomas G. Lane.
All Rights Reserved except as specified below.

Permission is hereby granted to use, copy, modify, and distribute this
software (or portions thereof) for any purpose, without fee, subject to these
conditions:
(1) If any part of the source code for this software is distributed, then this
README file must be included, with this copyright and no-warranty notice
unaltered; and any additions, deletions, or changes to the original files
must be clearly indicated in accompanying documentation.
(2) If only executable code is distributed, then the accompanying
documentation must state that "this software is based in part on the work of
the Independent JPEG Group".
(3) Permission for use of this software is granted only if the user accepts
full responsibility for any undesirable consequences; the authors accept
NO LIABILITY for damages of any kind.

These conditions apply to any software derived from or based on the IJG code,
not just to the unmodified library.  If you use our work, you ought to
acknowledge us.

Permission is NOT granted for the use of any IJG author's name or company name
in advertising or publicity relating to this software or products derived from
it.  This software may be referred to only as "the Independent JPEG Group's
software".

We specifically permit and encourage the use of this software as the basis of
commercial products, provided that all warranty or liability claims are
assumed by the product vendor.


ansi2knr.c is included in this distribution by permission of L. Peter Deutsch,
sole proprietor of its copyright holder, Aladdin Enterprises of Menlo Park, CA.
ansi2knr.c is NOT covered by the above copyright and conditions, but instead
by the usual distribution terms of the Free Software Foundation; principally,
that you must include source code if you redistribute it.  (See the file
ansi2knr.c for full details.)  However, since ansi2knr.c is not needed as part
of any program generated from the IJG code, this does not limit you more than
the foregoing paragraphs do.

The configuration script "configure" was produced with GNU Autoconf.  It
is copyright by the Free Software Foundation but is freely distributable.

It appears that the arithmetic coding option of the JPEG spec is covered by
patents owned by IBM, AT&T, and Mitsubishi.  Hence arithmetic coding cannot
legally be used without obtaining one or more licenses.  For this reason,
support for arithmetic coding has been removed from the free JPEG software.
(Since arithmetic coding provides only a marginal gain over the unpatented
Huffman mode, it is unlikely that very many implementations will support it.)
So far as we are aware, there are no patent restrictions on the remaining
code.

WARNING: Unisys has begun to enforce their patent on LZW compression against
GIF encoders and decoders.  You will need a license from Unisys to use the
included rdgif.c or wrgif.c files in a commercial or shareware application.
At this time, Unisys is not enforcing their patent against freeware, so
distribution of this package remains legal.  However, we intend to remove
GIF support from the IJG package as soon as a suitable replacement format
becomes reasonably popular.

We are required to state that
    "The Graphics Interchange Format(c) is the Copyright property of
    CompuServe Incorporated.  GIF(sm) is a Service Mark property of
    CompuServe Incorporated."


REFERENCES
==========

We highly recommend reading one or more of these references before trying to
understand the innards of the JPEG software.

The best short technical introduction to the JPEG compression algorithm is
	Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",
	Communications of the ACM, April 1991 (vol. 34 no. 4), pp. 30-44.
(Adjacent articles in that issue discuss MPEG motion picture compression,
applications of JPEG, and related topics.)  If you don't have the CACM issue
handy, a PostScript file containing a revised version of Wallace's article
is available at ftp.uu.net, graphics/jpeg/wallace.ps.gz.  The file (actually
a preprint for an article that appeared in IEEE Trans. Consumer Electronics)
omits the sample images that appeared in CACM, but it includes corrections
and some added material.  Note: the Wallace article is copyright ACM and
IEEE, and it may not be used for commercial purposes.

A somewhat less technical, more leisurely introduction to JPEG can be found in
"The Data Compression Book" by Mark Nelson, published by M&T Books (Redwood
City, CA), 1991, ISBN 1-55851-216-0.  This book provides good explanations and
example C code for a multitude of compression methods including JPEG.  It is
an excellent source if you are comfortable reading C code but don't know much
about data compression in general.  The book's JPEG sample code is far from
industrial-strength, but when you are ready to look at a full implementation,
you've got one here...

The best full description of JPEG is the textbook "JPEG Still Image Data
Compression Standard" by William B. Pennebaker and Joan L. Mitchell, published
by Van Nostrand Reinhold, 1993, ISBN 0-442-01272-1.  Price US$59.95, 638 pp.
The book includes the complete text of the ISO JPEG standards (DIS 10918-1
and draft DIS 10918-2).  This is by far the most complete exposition of JPEG
in existence, and we highly recommend it.

The JPEG standard itself is not available electronically; you must order a
paper copy through ISO or ITU.  (Unless you feel a need to own a certified
official copy, we recommend buying the Pennebaker and Mitchell book instead;
it's much cheaper and includes a great deal of useful explanatory material.)
In the USA, copies of the standard may be ordered from ANSI Sales at (212)
642-4900, or from Global Engineering Documents at (800) 854-7179.  (ANSI
doesn't take credit card orders, but Global does.)  It's not cheap: as of
1992, ANSI was charging $95 for Part 1 and $47 for Part 2, plus 7%
shipping/handling.  The standard is divided into two parts, Part 1 being the
actual specification, while Part 2 covers compliance testing methods.  Part 1
is titled "Digital Compression and Coding of Continuous-tone Still Images,
Part 1: Requirements and guidelines" and has document numbers ISO/IEC IS
10918-1, ITU-T T.81.  Part 2 is titled "Digital Compression and Coding of
Continuous-tone Still Images, Part 2: Compliance testing" and has document
numbers ISO/IEC IS 10918-2, ITU-T T.83.

Extensions to the original JPEG standard are defined in JPEG Part 3, a new ISO
document.  Part 3 is undergoing ISO balloting and is expected to be approved
by the end of 1995; it will have document numbers ISO/IEC IS 10918-3, ITU-T
T.84.  IJG currently does not support any Part 3 extensions.

The JPEG standard does not specify all details of an interchangeable file
format.  For the omitted details we follow the "JFIF" conventions, revision
1.02.  A copy of the JFIF spec is available from:
	Literature Department
	C-Cube Microsystems, Inc.
	1778 McCarthy Blvd.
	Milpitas, CA 95035
	phone (408) 944-6300,  fax (408) 944-6314
A PostScript version of this document is available at ftp.uu.net, file
graphics/jpeg/jfif.ps.gz.  It can also be obtained by e-mail from the C-Cube
mail server, netlib@c3.pla.ca.us.  Send the message "send jfif_ps from jpeg"
to the server to obtain the JFIF document; send the message "help" if you have
trouble.

The TIFF 6.0 file format specification can be obtained by FTP from sgi.com
(192.48.153.1), file graphics/tiff/TIFF6.ps.Z; or you can order a printed
copy from Aldus Corp. at (206) 628-6593.  The JPEG incorporation scheme
found in the TIFF 6.0 spec of 3-June-92 has a number of serious problems.
IJG does not recommend use of the TIFF 6.0 design (TIFF Compression tag 6).
Instead, we recommend the JPEG design proposed by TIFF Technical Note #2
(Compression tag 7).  Copies of this Note can be obtained from sgi.com or
from ftp.uu.net:/graphics/jpeg/.  It is expected that the next revision of
the TIFF spec will replace the 6.0 JPEG design with the Note's design.
Although IJG's own code does not support TIFF/JPEG, the free libtiff library
uses our library to implement TIFF/JPEG per the Note.  libtiff is available
from sgi.com:/graphics/tiff/.


ARCHIVE LOCATIONS
=================

The "official" archive site for this software is ftp.uu.net (Internet
address 192.48.96.9).  The most recent released version can always be found
there in directory graphics/jpeg.  This particular version will be archived
as graphics/jpeg/jpegsrc.v6a.tar.gz.  If you are on the Internet, you
can retrieve files from ftp.uu.net by standard anonymous FTP.  If you don't
have FTP access, UUNET's archives are also available via UUCP; contact
help@uunet.uu.net for information on retrieving files that way.

Numerous Internet sites maintain copies of the UUNET files.  However, only
ftp.uu.net is guaranteed to have the latest official version.

You can also obtain this software in DOS-compatible "zip" archive format from
the SimTel archives (ftp.coast.net:/SimTel/msdos/graphics/), or on CompuServe
in the Graphics Support forum (GO CIS:GRAPHSUP), library 12 "JPEG Tools".
Again, these versions may sometimes lag behind the ftp.uu.net release.

The JPEG FAQ (Frequently Asked Questions) article is a useful source of
general information about JPEG.  It is updated constantly and therefore is
not included in this distribution.  The FAQ is posted every two weeks to
Usenet newsgroups comp.graphics.misc, news.answers, and other groups.
You can always obtain the latest version from the news.answers archive at
rtfm.mit.edu.  By FTP, fetch /pub/usenet/news.answers/jpeg-faq/part1 and
.../part2.  If you don't have FTP, send e-mail to mail-server@rtfm.mit.edu
with body
	send usenet/news.answers/jpeg-faq/part1
	send usenet/news.answers/jpeg-faq/part2


RELATED SOFTWARE
================

Numerous viewing and image manipulation programs now support JPEG.  (Quite a
few of them use this library to do so.)  The JPEG FAQ described above lists
some of the more popular free and shareware viewers, and tells where to
obtain them on Internet.

If you are on a Unix machine, we highly recommend Jef Poskanzer's free
PBMPLUS image software, which provides many useful operations on PPM-format
image files.  In particular, it can convert PPM images to and from a wide
range of other formats.  You can obtain this package by FTP from ftp.x.org
(contrib/pbmplus*.tar.Z) or ftp.ee.lbl.gov (pbmplus*.tar.Z).  There is also
a newer update of this package called NETPBM, available from
wuarchive.wustl.edu under directory /graphics/graphics/packages/NetPBM/.
Unfortunately PBMPLUS/NETPBM is not nearly as portable as the IJG software
is; you are likely to have difficulty making it work on any non-Unix machine.

A different free JPEG implementation, written by the PVRG group at Stanford,
is available from havefun.stanford.edu in directory pub/jpeg.  This program
is designed for research and experimentation rather than production use;
it is slower, harder to use, and less portable than the IJG code, but it
is easier to read and modify.  Also, the PVRG code supports lossless JPEG,
which we do not.


FILE FORMAT WARS
================

Some JPEG programs produce files that are not compatible with our library.
The root of the problem is that the ISO JPEG committee failed to specify a
concrete file format.  Some vendors "filled in the blanks" on their own,
creating proprietary formats that no one else could read.  (For example, none
of the early commercial JPEG implementations for the Macintosh were able to
exchange compressed files.)

The file format we have adopted is called JFIF (see REFERENCES).  This format
has been agreed to by a number of major commercial JPEG vendors, and it has
become the de facto standard.  JFIF is a minimal or "low end" representation.
We recommend the use of TIFF/JPEG (TIFF revision 6.0 as modified by TIFF
Technical Note #2) for "high end" applications that need to record a lot of
additional data about an image.  TIFF/JPEG is fairly new and not yet widely
supported, unfortunately.

The upcoming JPEG Part 3 standard defines a file format called SPIFF.
SPIFF is interoperable with JFIF, in the sense that most JFIF decoders should
be able to read the most common variant of SPIFF.  SPIFF has some technical
advantages over JFIF, but its major claim to fame is simply that it is an
official standard rather than an informal one.  At this point it is unclear
whether SPIFF will supersede JFIF or whether JFIF will remain the de-facto
standard.  IJG intends to support SPIFF once the standard is frozen, but we
have not decided whether it should become our default output format or not.
(In any case, our decoder will remain capable of reading JFIF indefinitely.)

Various proprietary file formats incorporating JPEG compression also exist.
We have little or no sympathy for the existence of these formats.  Indeed,
one of the original reasons for developing this free software was to help
force convergence on common, open format standards for JPEG files.  Don't
use a proprietary file format!


TO DO
=====

In future versions, we are considering supporting some of the upcoming JPEG
Part 3 extensions --- principally, variable quantization and the SPIFF file
format.

Tuning the software for better behavior at low quality/high compression
settings is also of interest.  The current method for scaling the
quantization tables is known not to be very good at low Q values.

As always, speeding things up is high on our priority list.

Please send bug reports, offers of help, etc. to jpeg-info@uunet.uu.net.

SANE and FreeBSD
----------------

Building:
---------
Don't forget to use GNU make (gmake). E.g. "MAKE=gmake ./configure".
SANE should compile and install out-of-the-box.

If you've installed some of the optional libraries that sane-backends
can make use of (see README for list) using Ports then you will need to
let configure know about their locations:

MAKE=gmake CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib ./configure

SCSI-scanners:
--------------
If the SCSI host adapter is supported, there are no known problems.

USB-scanners:
-------------
USB-Scanners are supported by FreeBSD. The USB scanner driver "uscanner" and
access over libusb can be used.

For some backends (e.g. gt68xx) you MUST use libusb. The uscanner driver won't
work because it doesn't support control messages or interrupt endpoints.

If you want to use libusb, your scanner should *not* be claimed by the uscanner
driver. Make sure, that /dev/ugen* and /dev/usb* devices are available. Use
/dev/MAKEDEV to create them, if necessary. Make sure that the user has write
access to the appropriate device files.

To get your scanner detected by the uscanner driver, it may be necessary to add
its vendor and device ids to the kernel and recompile. Use MAKEDEV to generate
the /dev/uscanner* files if they are not already there. Use sane-find-scanner to
find your scanner. scanimage -L should find it automatically. Make sure that the
user has read access to /dev/usb* and read and write access to /dev/uscanner*.

Parport-scanners:
-----------------
I don't have much information about these. The Mustek 600 II N scanner seems to
work, others may or may not work. Please contact me or the SANE mailing list if
you succeeded in using a parport scanner.

2005-11-01 Henning Meier-Geinitz <henning@meier-geinitz.de>

Building and Installing SANE on HP-UX
-------------------------------------

This file contains some notes on building and installing SANE on
HP-UX.  It tells you which compiler switches to use, how to find out
to which controller card your scanner is connected, and how to create
a device file for it.

Building SANE
-------------

On HP-UX, SANE can be built using either the HP ANSI C compiler or
GCC.  For GCC, no special arguments to configure are necessary.  For
the HP compiler, invoke configure like this:

  CC=cc CFLAGS="-Ae -O" ./configure

Higher optimization levels than -O (equivalent to +O2) may fail
to compile correctly.

If you're using the HP compiler on 64-bit HP-UX 11, you must build
64-bit executables:

  CC=cc CFLAGS="-Ae +DA2.0W -O" ./configure



Some of the make files use GNU extensions, so you have to use gmake
(GNU make).  Gmake binaries are available from the HP-UX Porting and
Archive Centre <http://hpux.connect.org.uk> and its mirror sites.

Installing SANE
---------------

The SCSI pass-through driver (sctl) must be enabled in your kernel,
but it is by default.

Naturally, the scanner must have a non-conflicting SCSI address and it
must be connected to the right SCSI bus to work.

You'll probably need to create a device file for your scanner.  To do
this, you'll need to know its SCSI address, and, if your machine has
multiple SCSI controllers, the number of the one it's connected to.
As root, you can use ioscan -f to find this information.

For example, here's the partial ioscan output for a C200:

Class       I  H/W Path      Driver      S/W State   H/W Type     Description
==============================================================================
[...]
ext_bus     0  8/0/19/0      c720        CLAIMED     INTERFACE    Ultra Wide SCSI
target      0  8/0/19/0.6    tgt         CLAIMED     DEVICE
disk        0  8/0/19/0.6.0  sdisk       CLAIMED     DEVICE       IBM     DDYS-T09170N
target      1  8/0/19/0.7    tgt         CLAIMED     DEVICE
ctl         0  8/0/19/0.7.0  sctl        CLAIMED     DEVICE       Initiator
[...]
ext_bus     1  8/16/5        c720        CLAIMED     INTERFACE    Built-in SCSI
target      4  8/16/5.1      tgt         CLAIMED     DEVICE
unknown    -1  8/16/5.1.0                UNCLAIMED   UNKNOWN      EPSON   Perfection1640
target      2  8/16/5.2      tgt         CLAIMED     DEVICE
disk        1  8/16/5.2.0    sdisk       CLAIMED     DEVICE       TOSHIBA CD-ROM XM-5401TA
target      3  8/16/5.7      tgt         CLAIMED     DEVICE
ctl         1  8/16/5.7.0    sctl        CLAIMED     DEVICE       Initiator
[...]

You can see that there are two SCSI controllers, Ultra Wide SCSI and
Built-in SCSI (narrow single-ended).  The I column shows the number of
the controller card.  Our scanner, an Epson Perfection 1640, is
connected to controller 1, and has SCSI address 1 (that's the 1 in the
H/W Path number).

You can now create the device file using mknod(1M).  In this example,
the command would be:

  mknod /dev/rscsi/c1t1d0 c 203 0x011000

In the filename, c1 specifies controller 1, t1 is target 1 (i.e., the
SCSI address), d0 (device 0) because it's the only device at that
address.  203 is the major number of the sctl driver.  In the minor
number (0x011000), 01 again means controller 1, and the second one
means SCSI address 1.  See scsi_ctl(7) for details.

For ease of use with SANE, I'd recommend to create a link to
/dev/scanner, e.g.,

  ln -s /dev/rscsi/c1t1d0 /dev/scanner

To allow normal users to access the scanner, the best approach is
probably to create a new group, say, "scanner", and make the scanner
device file readable and writable for the group, e.g.,

  chown bin:scanner /dev/rscsi/c1t1d0
  chmod g+rw /dev/rscsi/c1t1d0

You would then add all users that are allowed to use the scanner to
that group.  If you haven't already done so, you should do

  ln -s /etc/group /etc/logingroup

so that users are automatically in all groups to which they belong
(and don't have to use newgrp(1)).

Information about USB scanners:
================================

With Linux 2.4.* you could either use the kernel scanner module or libusb to
access USB scanners.  In Linux 2.6.4 the kernel scanner module was removed.
Therefore with this and later kernels libusb must be used.

Permissions:
------------
While SANE automatically uses libusb when the library and its header file were
present during the build of sane-backends, setting permissions will require some
attention. So if scanimage -L lists your scanner as root but not as normal user
read on this text.

Most distributions support setting permissions without much manual
configuration. Usually you must just add the users that are allowed to access
the scanner to group "scanner". To make that change active, the user must login
again. For more details, see your distribution's documentation e.g. for Debian:
README.debian.gz. If this doesn't work you you want to know more, read on.

The device files used by libusb are located in /proc/bus/usb/
(e.g. /proc/bus/usb/001/003) or in /dev/bus/usb/ (e.g. /dev/bus/usb/001/003), if
you use udev.  The exact file name can be found out by running sane-find-scanner
which would print "libusb:001:003" in this case.  While setting permissions with
e.g. "chmod a+rw /proc/bus/usb/001/003" works, this change is not permanent.
The permissions will be reset when the scanner is replugged or Linux is
rebooted.

One solution to set permissions on-the-fly is Linux udev which comes with
current distributions. SANE comes with a udev rules file in the tools/udev
directory which may be used by distributions or can be copied to
/etc/udev/rules.d manually. The file format is explained on top of the file
itself. Either you need libusb 0.1.12 or newer or USB_DEVFS_PATH=/dev/bus/usb
must be exported as a system-wide environment variable.

Older distributions may use the Linux hot-plug tools (or hotplug-ng). Your
distribution should have set up the scripts to automatically change permissions
correctly. Look for "libsane.usermap" and "libusbscanner" in /etc/hotplug/usb.
If you build SANE from source you can use the hotplug script that comes with
SANE. See the tools/hotplug/ directory in the source distribution. Please refer
to the README in that directory for the details.

Gentoo information:
-------------------
Gentoo users: If your USB scanner is not detected at all check that USE=usb is
set when emerging.

Information about SCSI scanners:
================================

Under Linux, your kernel must have generic SCSI support (sg) as well as a
driver for your SCSI adapter. You may want to increase the SCSI buffer size
to increase scan speed. Details on all of the above can be found in
sane-scsi(5).

If your SCSI and sg driver are build as moduls you will need to load them
with modprobe:

# modprobe your-driver-name
# modprobe sg

You may find error messages in /var/log/messages. Look at the documentation
for your SCSI driver. Maybe you need to add options like the io port.

Now the SCSI adapter and your scanner should be visible at /proc/scsi/scsi.
Example:

# cat /proc/scsi/scsi
Host: scsi0 Channel: 00 Id: 06 Lun: 00
  Vendor: SCANNER  Model:                  Rev: 2.02
  Type:   Scanner                          ANSI SCSI revision: 01 CCS

In this case the real vendor and scanner name are not shown (Mustek
Scannexpress 12000SP) but SANE will detect it nevertheless.

If your scanner is supported by SANE, scanimage -L will list it now:

# scanimage -L
device mustek:/dev/scanner' is a Mustek ScanExpress 12000SP flatbed scanner

If this doesn't work you may have to add the right SCSI generic device name
to the configuration file. This should be documented in the man page for
your backend. To find out about the right SCSI device use sane-find-scanner:

# sane-find-scanner
found SCSI scanner "SCANNER  2.02" at /dev/scanner
found SCSI scanner "SCANNER  2.02" at /dev/sg0
found SCSI scanner "SCANNER  2.02" at /dev/sga

It may help to set a symbolic link /dev/scanner to the respective device if
automatic detection does not work.

If you need more information on the Linux SCSI subsystem, look at
http://www.torque.net/scsi/linux_scsi_24/index.html. Although this
documentation is about the 2.4 kernels, large parts are also valid for
older kernels. One important exception is the section on "Device Names
in devfs".

Adaptec 1542 SCSI adapter:
  Using buffer sizes of more than 32768 bytes with the aha1542 driver can
  lead to kernel panic with older kernels. To avoid this, run configure with
  the option --enable-scsibuffersize or set the environment variable
  SANE_SG_BUFFERSIZE to 32768 before running scanimage or another frontend,
  or download and install the SG driver 2.1.37 or newer from
  http://www.torque.net/sg.

idescsi:
  The Linux kernel "Emulation of a SCSI host adapter for IDE ATAPI
  devices" (idescsi) is reported to cause problems in connection with
  SANE. If your scanner isn't found or you encounter segmentation faults
  try to disable idescsi.

SCSI Direct IO: Recent versions of the Linux SG driver for the 2.4 kernels
  support direct IO, i.e., the SCSI adapter's DMA chip copies data directly
  to/from user memory. Direct IO reduces memory usage, but it can lead to
  access conflicts, if a backend uses shared memory. SANE does not use
  direct IO by default. If you want to use it, run

	configure --enable-scsi-directio=yes

Very old Linux distributions are missing the /usr/include/scsi directory.  In
such a case, it is necessary to copy the relevant files from the kernel
distribution.  Normally, the command:

  cp -a /usr/src/linux/include/scsi /usr/include

should fix this problem. Don't do this if you don't get compilation errors
about missing SCSI headers.


Other Information
=================

ld.so.conf configuration:
  "/usr/local/lib/sane" or "/usr/lib/sane" MUST NOT be listed in
  /etc/ld.so.conf. If your scanner is not detected or only Video for Linux
  devices are found, check for one of the above lines in ld.so.conf.
  A line "/usr/local/lib" or "/usr/lib" in ld.so.conf is ok, however.

Excessive warnings "pointer of type `void *' used in arithmetic":
  Some older versions of glibc generate these warnings not related to SANE
  source code. To suppress these warnings do

  export CFLAGS="-g -O2 -D__NO_STRING_INLINES"

  and rerun configure.

If you use DEC cc on Linux Alpha, you may need to set LDFLAGS="-N" to
  be able to build sane-backends.

The Intel C++ Compiler for IA32 and IA64 isn't supported yet. If you want
  to try nevertheless, you will experience undefined references to inb
  and outb functions. To avoid those replace #include <sys/io.h> with

  #if defined(__ICC) && __ICC >= 700
  # define __GNUC__ 2
  #endif
  #include <sys/io.h>
  #if defined(__ICC) && __ICC >= 700
  # undef __GNUC__
  #elif defined(__ICC) && defined(HAVE_ASM_IO_H)
  # include <asm/io.h>
  #endif

Have a lot of fun with the latest SANE backend.

# SANE
## Introduction
SANE is an application programming interface (API) that provides standardized access to any raster image scanner hardware (flatbed scanner, hand-held scanner, video- and still-cameras, frame-grabbers, etc.). 

You can also learn more about the SANE project through [the official website](http://sane-project.org/)

## Background Brief
In the process of OpenHarmony's southward ecological development, it is necessary to be compatible with printers in the stock market. The use of CUPS printing system can directly connect with most printers in the market, which also reduces the difficulty for printer manufacturers to adapt to OpenHarmony.

## Directory structure
```
- LICENSE                           Copyright File
- OAT.xml                           OAT.XML filtering configuration file
- README.OpenSource                 Project README OpenSource files
- README.md                         English Description
- README_zh.md                      Chinese Description
- backend                           scanning device backend source code
- include                           SANE API interface
- lib                               SANE library source code
- sanei                             SANE internal utility functions and tools
- doc                               documents and instruction files
```

## How to use
### 1、Header file import
```c
#include <sane/sane.h>
```
### 2、Add Compilation Dependency
Add in the bundle. json file
```json
"deps": {
  "third_party": [
    "backends"
  ]
}
```
Add dependencies where needed in BUILD.gn

```json
deps += [ "//third_party/backends:third_sane" ]
```
### 3、Example of interface usage
```c
SANE_Status status;
SANE_Handle handle;

// Initialize SANE
status = sane_init(NULL, NULL);
if (status != SANE_STATUS_GOOD) {
    fprintf(stderr, "Failed to initialize SANE: %s\n", sane_strstatus(status));
    return 1;
}

// Open the first scanner device
status = sane_open("your_scanner_device_name", &handle);
if (status != SANE_STATUS_GOOD) {
    fprintf(stderr, "Failed to open scanner: %s\n", sane_strstatus(status));
    return 1;
}

// Get scanner device information
const SANE_Device *device_info;
status = sane_get_devices(&device_info, SANE_FALSE);
if (status != SANE_STATUS_GOOD) {
    fprintf(stderr, "Failed to get scanner device information: %s\n", sane_strstatus(status));
    return 1;
}

// Set scan parameters
SANE_Parameters parameters;
status = sane_get_parameters(handle, &parameters);
if (status != SANE_STATUS_GOOD) {
    fprintf(stderr, "Failed to get scan parameters: %s\n", sane_strstatus(status));
    return 1;
}

// Start scanning
SANE_Image image;
status = sane_start(handle);
if (status != SANE_STATUS_GOOD) {
    fprintf(stderr, "Failed to start scanning: %s\n", sane_strstatus(status));
    return 1;
}

// Read scan data
do {
    status = sane_read(handle, &image);
    if (status != SANE_STATUS_GOOD) {
        fprintf(stderr, "Failed to read scan data: %s\n", sane_strstatus(status));
        break;
    }

} while (status == SANE_STATUS_GOOD);

// Finish scanning
status = sane_cancel(handle);
if (status != SANE_STATUS_GOOD) {
    fprintf(stderr, "Failed to cancel scanning: %s\n", sane_strstatus(status));
    return 1;
}

// Close the scanner device
status = sane_close(handle);
if (status != SANE_STATUS_GOOD) {
    fprintf(stderr, "Failed to close scanner: %s\n", sane_strstatus(status));
    return 1;
}

// Exit SANE
sane_exit();
```

### 相关仓
[print_print_fwk](https://gitee.com/openharmony/print_print_fwk)

### 参与贡献
[How to involve](https://gitee.com/openharmony/docs/blob/HEAD/zh-cn/contribute/参与贡献.md)

[Commit message spec](https://gitee.com/openharmony/device_qemu/wikis/Commit%20message%E8%A7%84%E8%8C%83)

SANE and NetBSD
----------------

Building:
---------
Don't forget to use GNU make (gmake). E.g. "MAKE=gmake ./configure".
SANE should compile and install out-of-the-box.

SCSI-scanners:
--------------
SANE only supports the generic /dev/uk? devices. /dev/ss? won't work. If your
scanner is detected by the ss driver, disable the driver with the "config"
utility or compile a new kernel without ss. Set a link /dev/scanner to /dev/uk0
(or whatever you use) and/or edit your backend's config file
appropriately. Don't forget to set up permissions to the device file correctly
for access by a non-root user (read/write). Auto-configuration using the "scsi
*" lines in the config files doesn't work.

Scanners with higher resolutions need bigger SCSI buffers. Therefore, edit
sanei/sanei_scsi.c and look for these lines:

#ifndef MAX_DATA
# define MAX_DATA	(32*1024)
#endif

Increase the buffer size to e.g. 128 * 1024. Recompile.

USB-scanners:
-------------

USB-Scanners are supported in principle. Using libusb is recommended.

Problems when using libusb:

Older kernels may need to be compiled WITHOUT DIAGNOSTIC. Disable it in the
config file or use a GENERIC kernel without DIAGNOSTIC. If it is, you will get
errors like "ugenioctl: USB_SET_TIMEOUT, no pipe".

When using libusb, make sure, that /dev/ugen* and /dev/usb* devices are
available. Use /dev/MAKEDEV to create them, if necessary.

If you want to use libusb, disable the uscanner driver.

Problems with uscanner driver:

The uscanner driver also works (tested with the plustek backend). As the
uscanner driver can't detect the vendor and product ids automatically, it's
necessary to add the name of the device file to the backends's configuration
file. Some backends also need the vendor and product id of the scanner.

Some backends won't work with the uscanner driver because they need USB
control messages. Use libusb instead.

Parport-scanners:
-----------------
I don't have any information about these. Please contact me or the SANE mailing
list if you succeeded in using one of these.

2003-04-24 Henning Meier-Geinitz <henning@meier-geinitz.de>

SANE and OpenBSD
----------------

Building:
---------
Don't forget to use GNU make (gmake). E.g. "MAKE=gmake ./configure".
SANE should compile and install out-of-the-box.

If some libraries and headers (like libjpeg) are installed in /usr/local/, adding
"-I/usr/local/include/ -L/usr/local/lib/" to the CPPFLAGS environment variable
before running configure may be necessary to get them detected.

Since release 3.9, SANE is available from OpenBSD ports.

SCSI-scanners:
--------------
SANE only supports the generic /dev/uk? devices. /dev/ss? won't work. If your
scanner is detected by the ss driver, disable the driver with the "config"
utility or compile a new kernel without ss. Set a link /dev/scanner to
/dev/uk0 (or whatever you use) and/or edit your backend's config file
appropriately. Don't forget to set up permissions to the device file correctly
for access by a non-root user (read/write).

USB-scanners:
-------------
USB-Scanners are supported in principle since OpenBSD 2.9. The USB scanner
driver "uscanner" and access over libusb is supported.

To get your scanner detected by the uscanner driver, it may be necessary to
add its vendor and device ids to the kernel and recompile
(sys/devs/usb/uscanner.c). With OpenBSD 3.0 there is also a bug concerning
uscanner that prevents accessing the /dev/uscanner devices.  Get a newer
kernel in this case. If your MAKEDEV won't make /dev/uscanner0 do it manually:
"mknod /dev/uscanner0 c 77 0" for the first scanner. Edit your backend's
configuration file appropriately.

If you want to use libusb, your scanner should *not* be claimed by the
uscanner driver. Also make sure that the ugen driver is NOT compiled with
DIAGNOSTIC. If it is, you will get errors like "ugenioctl: USB_SET_TIMEOUT,
no pipe". Make sure, that /dev/ugen* and /dev/usb* devices are available. Use
/dev/MAKEDEV to create them, if necessary.

For some backends you must use libusb. The uscanner driver won't work because
automatic detection, control messages, or interrupt endpoints are needed.

When using libusb, you need read/write permissions to ugen(4) (/dev/ugen*.*) and
the usb(4) controller (/dev/usb*) your scanner is connected to.  Consider adding
a group usb and setting the device permissions using the hotplugd(8) attach
and detach scripts.  See tools/openbsd for an example.

Parport-scanners:
-----------------
I don't have any information about these. Please contact me or the SANE mailing
list if you succeeded in using one of these.

2005-12-23 Henning Meier-Geinitz <henning@meier-geinitz.de>

[
    {
        "Name"                  : "sane-backends",
        "License"               : "GPL v2",
        "License File"          : "LICENSE",
        "Version Number"        : "1.2.1",
        "Owner"                 : "guoshengbang@huawei.com",
        "Upstream URL"          : "https://gitlab.com/sane-project/backends/-/releases/1.1.1",
        "Description"           : "SANE stands is an application programming interface (API) that provides standardized access to any raster image scanner hardware. "
    }
]

2002-01-03

Look at http://home.tiscalinet.de/fbakan/sane-os2.htm for information about
compiling SANE on OS/2 (from Franz Bakan).


The following text was for 1.0.3, but it may help nevertheless.


   SANE 1.03 for OS/2 - build 1
   ----------------------------
   09 Jul 2000, Yuri Dario <mc6530@mclink.it>


WARNING:
--------
This release of has been compiled with EMX 0.9D, so it doesn't work with
the previous runtime. You must upgrade to the latest runtime before running
SANE (actually EMX 0.9D fix 03).


SANE (Scanner Access Now Easy)
------------------------------
For more info about the SANE Project, please visit

	http://www.sane-project.org/

You should also check the main site for an updated list of supported scanners.

Note that I can't say you if your scanner is supported; check SANE homepage
instead.


SUPPORT
-------
I'm sorry to tell you that it is hard for me to help you: if your scanner
doesn't work or your problem can't be reproduced on my pc, there are high
choices that I can't fix the bug. Most problems are specific to same PC/scanner
combinations, and can't be solved without having a full development environment
and programming experience.

I have setup a mailing list for users, where I hope most people can find an
answer to their questions. You will find that I answer only sometimes, because
I'm too busy.
To subscribe please visit

	http://www.egroups.com

and look for sane-os2, or fill the form available on my site.


DOCUMENTATION
-------------
To read docs with correct format, you should type

	more < doc\sane-epson.txt

If someone has more ideas on how to get a correct .txt starting from a .man
file, he is welcome (actually I'm using groff).


INSTALLATION
------------
If you already didn't it, install the correct driver for your scsi adapter.
The drivers has usually a .ADD extension and looks like

	BASEDEV=AHA154X.ADD

Then you need the ASPI driver: this driver is already in your OS2\BOOT
directory, so you have only to add

	BASEDEV=OS2ASPI.DMD /ALL

The /ALL switch is required only if you need to use other devices with
aspirout.sys, e.g. if you have a CD-RW and CDRecord/2 installed.

Last, add aspirout.sys to your config.sys

	DEVICE=D:\OS2\BOOT\ASPIROUT.SYS

N.B. you can change the path to other directories.
Now reboot.

To run scanimage.exe you need also to download the latest EMX runtime,
available on Hobbes or Leo as emxrt.zip.

find-scanner.exe can be used to recognize a scanner on the scsi bus. Then
you should edit your xxx.conf file and add the scanner address, a string like
b0t4l0. This can be simplified using autodetection: with autodetection you can
use a string like

	scsi EPSON

in your xxx.conf file; the autodection will enable the backend that recognize
'EPSON' in the scanner id.

To test scanimage, run

	scanimage --help

you should see your scanner following the list of internal devices:

	List of available devices:
	    pnm:0 pnm:1

If it is not present, check your scsi driver, the aspi driver OS2ASPI.DMD and
aspirout.sys; on Warp4 you can use the Hardware Manager to check scanner
presence. Then look at your xxx.conf, maybe there is something wrong in the
text.


USAGE:
------
Once configured your system, create a proper .conf file (edit one of the
supplied templates) and run

	scanimage -L

The output should be like

	device `umax:b0t3l0' is a UMAX     Vista-S8         flatbed scanner
	device `pnm:0' is a Noname PNM file reader virtual device
	device `pnm:1' is a Noname PNM file reader virtual device

The pnm devices are always available, while on the first line you should
read the id of your scanner.

A simple scan

	scanimage -d umax > test.pnm

will do a scan with default parameters. Run

	scanimage -d umax --help

to get a full list of available switches.


SANED:
------
In this release the SANE network daemon can be used (with a limit).
First edit your \mptn\etc\services and add

sane            6566/tcp   # SANE network scanner daemon

(maybe a reboot is required to apply that change).
Create a saned.conf in the same directory of saned.exe and add a list of valid
client addresses; the clients are allowed to access the local scanner.
Now run the server in debug mode

	saned -d

On the client side, you need to create a net.conf file in the same directory
of scanimage.exe: here you have to add a list of valid saned servers.
Run

	scanimage -L

The output is like this

device `umax:b0t3l0' is a UMAX     Vista-S8         flatbed scanner
device `pnm:0' is a Noname PNM file reader virtual device
device `pnm:1' is a Noname PNM file reader virtual device
device `net:pippo.intranet:umax:b0t3l0' is a UMAX     Vista-S8      flatbed scanner
device `net:pippo.intranet:pnm:0' is a Noname PNM file reader virtual device
device `net:pippo.intranet:pnm:1' is a Noname PNM file reader virtual device

Then saned will quit. To run it forever, you have to configure the INETD
daemon: create a \mptn\etc\inetd.lst with the following line

	sane   tcp /rd/sane/sane-1.0.1/frontend/saned.exe

Be aware that this configuration shouldn't work: I have been unable to get it
working on my PC without running saned under the debugger PMGDB.
The correct syntax for running scanimage over the net is

	scanimage -d net:HOSTNAME:umax:b0t3l0 > test.pnm

where HOSTNAME is a valid DNS host name.
You can log server access using syslogd: if syslogd is running, saned will
send to it all messages.


HOW TO COMPILE:
---------------
To compile SANE with emx, you need

- EMX 0.9D
- GNU Make 3.75 (rename to make.exe)
- GNU Patch 2.5
- KSH 5.2.13 (rename to sh.exe)
- GNU Bison
- GNU File utilities
- GNU SED (stream editor)
- Autoconf 2.13

Steps:
- untar the original Unix distribution;
- unzip this file somewhere;
- copy src\* into sane-1.0.1;
- enter sane-1.0.1 directory;
- apply patches to original distribution:
    [...\sane-1.0.1]gnupatch -p 0 < patch.os2
- run autoconf to rebuild the configure script
- edit configure and change autoconf default optimization flags;
  search for -O2 -m486 and change to your preferred settings;
- add the following line after :${LDFLAGS="...."}
  : ${LIBS="-lsocket"}
- run configure.os2 to build all installation files;
- add -Zexe to LDFLAGS in frontend\Makefile and tools\Makefile;
- run make (compiler warnings are ok);
- wait to complete all makes;

Remember to install a Unix like shell in your path; I use ksh.exe
renamed to sh.exe, and saved in d:\bin
(that's because most unix scripts uses SHELL=/bin/sh)

You need also a compatible dl.a and syslog.a library; look in .\contrib
for a couple of simple sources.

Flags needed under EMX:
-Zsysv-signals	enables signal management as in SystemV, otherwise emx
                convention is used (and it is different from sysv).
-Zcrtdll	link dynamically with EMXLIBCM.DLL;


PARALLEL PORT
-------------
This release has support for parallel port enabled: actually only the Epson
backend makes uses of such support; the Epson GT-300 can be recognized, but
scanning can't be completed.

Also HP-5100C parallel scanner can be run under OS/2: you need to download
the EPST driver from Shuttle Tech. homepage (www.shuttletech.com); follow the
instruction for installation. Then the scanner is seen as a scsi HP, so the
HP backend can work with it.

The Quickcam backend is also included with lpt support, but I can't say how it
is working.

History:
--------
09 Jul 2000 release 1.03

20 Jun 1999 release 1.01
	- changed runtime to EMX 0.9D
	- fixed: find-scanner should now work correctly.
	- added: how to compile instructions.

07 Mar 1999 release 1.01 pre-test3
	no OS/2 specific fixes

20 Oct 1998 release 0.74
	fixed fork()ing backends with new sanei_thread api.
	fixed scsi autodetection
	added parallel port support

===============================================================================
Yuri Dario <mc6530@mclink.it>
http://www.quasarbbs.com/yuri

This is a report on how to build SANE on Solaris/x86 using a USB scanner. See
below for SCSI.

Another report for SANE on OpenSolaris can be found here:
http://ginfo.egim-mrs.fr/article.php3?id_article=44

From: Tomasz Orlinski <tomasz.orlinski@wp.pl>
To: sane-devel@lists.alioth.debian.org
Subject: [sane-devel] USB scanners DO work on Solaris 10 x86
Date: Thu, 7 Oct 2004 20:26:50 +0200

I would like to inform you, that I have compiled SANE on Sun Solaris 10 x86
with built-in USB scanner support. It was possible, because Sun had prepared
libusb library wrapper for Solaris 10. I know, that Solaris 10 Software
Express Release 08/04 is required. I have done it in that way:
LD_LIBRARY_PATH=/usr/sfw/lib:$LD_LIBRARY_PATH
CFLAGS="-I/usr/sfw/include"
CPPFLAGS="-I/usr/sfw/include"
LDFLAGS="-L/usr/sfw/lib -R/usr/sfw/lib -lusb"
export LD_LIBRARY_PATH CFLAGS CPPFLAGS LDFLAGS
./configure --prefix=/opt/sane --disable-fork-process
make
make install
It was also required to add a generic USB kernel driver. I had to look for
my scanner device name in output of
prtconf -D -v
command. My scanner is Plustek UT24 and the appropriate part of output looked
like this:
name='compatible' type=string items=8 value='usb7b3,17.100' + ...
I had to remove the not used kernel driver
rem_drv ugen
And add it again:
add_drv -i 'usb7b3,17.100' ugen
Then, /opt/sane/bin/sane-find-scanner detected my scanner and everything
worked fine. I to add " " signs around usb7b3,17.100 name in
/etc/driver_aliases to have the scanner working after reboot.
To compile this packages SUNWlibusb and SUNWlibusbugen were needed. I used
Solaris Software Companion CD gcc 2.95.3 compiler and Sun's /usr/ccs/bin/ld
linker. USB support DOES NOT work in Solaris 9 and earlier versions.
I hope, that this information would be useful for other USB scanner users.

From: Tomasz Orlinski <tomasz.orlinski@wp.pl>
To: sane-devel@lists.alioth.debian.org
Subject: Re: [sane-devel] USB scanners DO work on Solaris 10 x86
Date: Fri, 8 Oct 2004 16:06:14 +0200

[...]

Sun in Driver Development Kit v. 0.9 writes how to compile SANE, but it does not
really work :) They write about compiling with gcc and give options for Sun
Forte compiler (cc) and forget about attaching a kernel driver. But they write,
that versions earlier than 1.0.14 cannot be used. They want also to build SANE
with Posix threads enabled. So I think that can be true. Sun writes also, that
Solaris Software Express release at least S10_62 is needed to use
libusb. Release number can be checked in /etc/release. The newest version can be
downloaded from www.sun.com/solaris for free.

In my opinion it is important to be cautious when using scanner or just libusb
on important Solaris machines (especially multi-processor ones), because unlike
in other systems, Solaris kernel is fully preemtible, what means, that many
instances of the same driver can run simultaneously - it's dangerous, when
drivers are not perfect. And Solaris USB framework is absolutely new, so it can
contain bugs. I tried to crash my Solaris using USB subsystem and SANE, I didn't
manage to, but it doesn't mean, it's impossible.

SANE frontends work without any problems with Xsun and GIMP included in Solaris
Software Companion CD.

---------------------------------------------------------------------------
The following text describes, how to use a SCSI scanner (2002-06-11).

You need a generic SCSI driver to run SANE on Solaris.  There are at
least three such drivers: the scg driver by Joerg Schillig, the
sg driver by Kevin Sheehan, and starting with Solaris 8 Sun's own
sgen(7D) driver.

NOTE: You should install the SCSI generic driver BEFORE you run
`configure' in the sane directory---otherwise configure won't set up
SANE to work with the generic scsi driver.

*** scg driver

The SCSI general driver scg is

	Copyright 1986-1995 Joerg Schilling,

It is supplied binary in pkgadd(1m) format and is tested from Solaris
2.3 to Solaris 2.6 (sparc) and Solaris 2.3 to Solaris 2.5.1 (x86).  It
can be found in

	ftp://ftp.fokus.gmd.de/pub/unix/kernel/scg/

To install it on a SPARC do:

	cd /tmp
	get SCHILYscg.sparc.tar.Z
	uncompress SCHILYscg.sparc.tar.Z
	tar -xvf SCHILYscg.sparc.tar
as root:
	pkgadd -d .

NOTE: Be very careful with pkgadd as it does not check for the correct
      target architecture. Do not install drivers for x86 on sparc
      and vice versa.  You will get a corrupt system otherwise.

For Solaris on an x86 do:

	cd /tmp
	get SCHILYscg.i386.tar.Z
	uncompress SCHILYscg.i386.tar.Z
	tar -xvf SCHILYscg.i386.tar
as root:
	pkgadd -d .

Then do a reboot --r

Once the system has rebooted, there should be a device node /dev/scgXX
for each of your SCSI adapters (/dev/scg0 for the first adapter,
/dev/scg1 for the second, and so on...)

Because the device name specifies a SCSI adapter, you need to use a
special device naming syntax so SANE can tell which device you want to
talk to.  If the device is at SCSI id 0, the character 'a' should be
appended, character 'b' should be used for SCSI id 1, and so on
(see also the Solaris section in sane-scsi(5)).

E.g., to configure an HP scanner, configuration file
/opt/local/etc/sane.d/hp.conf might contain:

	/dev/scg0c	if the scanner has the SCSI target id 2

WARNING! Everybody who can read/write a generic SCSI device can do
with all your disks whatever he/she wants. It takes only a few lines
of code to send a FORMAT control block...  Rather than giving users
access to the SCSI adapter special device, it may be a better idea to
install scanimage/xscanimage setgid to a special "scanner" group and
then turn on write permission for the scanner group.

*** sg driver

Another solution to the permission problem is to use the generic SCSI
driver sg by Kevin Sheehan.  This driver is not free but uses separate
device node for each SCSI target:

	/dev/sg/0, /dev/sg/1, ...

This allows to control device access on a per-device basis.

*** sgen driver

The solaris 8 sgen driver must be configured before it can be used.
See /kernel/drv/sgen.conf and the manual page sgen(7D).

The minimal config includes defining the correct
"device-type-config-list" property in /kernel/drv/sgen.conf.  The
typical SCSI device type for a scanner is either "scanner" or
"processor". You can optionally restrict the devices sgen attaches to,
by defining the "inquiry-config-list" property.  You also have to
uncomment the scanner's "target/lun" entry, so that the sgen driver is
allowed to attach to the SCSI scanner hardware.

After the configuration file /kernel/drv/sgen.conf is set up for the
scanner, run the command "devfsadm -v -i sgen" to create sgen device
nodes for the scanner.  In case you need to rerun devfsadm to
incorporate changes to the sgen.conf file, make sure the sgen driver
is unloaded from the kernel before you re-run devfsadm.  The driver is
unloaded using the "modunload -i {id}" command; the {id} of the sgen
driver can be determined with the modinfo command.


The device nodes use names of the following form:

	/dev/scsi/device-type/cXtXdX

Example:  A HP Scanjet 4c (SCSI device type: "processor") on controller
#1, target #6, lun #0 uses the device name

	/dev/scsi/processor/c1t6d0

/kernel/drv/sgen.conf contains:

	device-type-config-list="processor";
	name="sgen" class="scsi" target=6 lun=0;



If you have questions or problems with the Solaris support in SANE,
send mail to:

     hu@garfield.m.isar.de

UNIXWARE PORT of SANE - HOWTO build and what you need to run

You need a sane SCSI driver to run SANE on Unixware 2.x. There is at
least one such driver: the sane driver by R=I+S.

The Unixware sane driver is a binary loadable module driver for UW2.x.
Please send Email to wolfgang@rapp-informatik.de to receive.

What you need to build xane on Unixware 2.x
- gnu make

You don't need gcc. All is build with the standard Unixware cc and
libs!!

For the X-frontends xscanimage and xsane (separately distributed) you need
libs like libgtk libgimp and the image libs for jpeg, tiff and png.  It is
also good to have gettext with libintl installed.  Most of the libs are
available on the Skunkware CD's from SCO in pkgadd format.  If you build the
frontends with this libs gimp plugin is also supported by xscanimage and
xsane. Latest xsane version tested was 0.48.

With the following configure should run an build shared libs with
libtool 1.3.4

LD_RUN_PATH=/usr/local/lib CPPFLAGS="-I/usr/local/include -I/isr/X/include" CFLAGS="-I/usr/local/include -I/usr/X/include
-I/usr/ucbinclude -L/usr/local/lib -L/usr/ucblib -l ucb" LIBS="-lsocket -lnsl -lgen -I/opt/include -L/usr/ucblib -lucb" ./configure

After running configure you have to edit the generated file libtool

Append to the line
archive_cmds="\$LD -G -o \$lib \$libobjs \$deplibs \$linkopts

so that it looks like this.
archive_cmds="\$LD -G -o \$lib \$libobjs \$deplibs \$linkopts -B bind_now -L/usr/local/lib -lintl -L/usr/ucblib -lucb -lm"

This is a must to link the libucb.a , libintl.a in when the sane libs
are build.It's also necessary for mathematic lib -lm .  Not doing this
will bring runtime errors like missimg usleep or pow function.

ATTENTION:!!! libucb.a of Unixware 2.x has a buggy readdir function so
it is recommended to remove readdir.o from libucb.a with ar -d
readdir.o libucb.a Often used and needed functions from libucb.a are
strncasecmp or getpagesize.

If you use -I/usr/ucbinclude it is also a good idea to move
/usr/ucbinlcude/unistd.h to another file, because it will be included
first and some sources will not compile.

Then you can run make with GNU make.

After this say su and then it's good to say
LD_RUN_PATH=/usr/local/lib export LD_RUN_PATH

after this you can install with
make install

Tested on Unixware 2.0.x with Umax Astra 1220S and HP C5100A with
sane-1.0.1.  With Microtek backend earlier on sane-0.74.

If you use the net backend you do not need the Unixware sanedrv.

The driver is a shareware product.

The driver is supplied binary in pkgadd(1m) format and is tested from
UW2.0x.  Please send Email to wolfgang@rapp-informatik.de to get the
driver in binary pkgadd package.

To install it on a Unixware do:

        cd /tmp
        get sanedrv.pkg.tgz
        gunzip sanedrv.pkg.tgz
        tar xvf sanedrv.pkg.tar
as root:
        pkgadd -d /tmp/sanedrv

Once the driver is installed, there should be a device nodes /dev/sane
and /dev/scanner /dev/scanner1 for the second, and so on...)

The scanner my be connected to any SCSI controller in the system, also
if you have additional devices like disks or cdroms on the same
controller.  The UW2.x sane driver do not block the controller. The
scanner must be switched on to be recognized by UW, if the low level
driver p.e. adsl is loaded.

To configure an UMAX scanner, configuration file
/usr/local/etc/sane.d/umax.conf might contain:

        /dev/scanner

The driver is configured to recognice all scsi scanners with ID
SCANNER and all HP Scsi scanners with ID Processor and Inquiry string
starting with "HP" string. For details have a look to
/etc/conf/pack.d/sane/space.c.

If you change this then you must unload the sane driver modadmin -U
sane, build the new module by /etc/conf/bin/idbuild -M sane and the
install the driver with modadmin -l sane.

If you have questions or problems with the Unixware support in SANE,
send mail to:

wolfgang@rapp-informatik.de

SANE on UnixWare 7
==================

The easiest way to get SANE working on a UnixWare 7.1.X system (UW 7.0.0
and 7.0.1 are not supported) is to download and install the SANE binary
distribution from SCOs Skunkware web site. The URL is:

        ftp://ftp.sco.com/skunkware/uw7/Packages

Use the pkgadd command to install the files, e.g.:

        # pkgadd -d `pwd`/sane-1.0.2.pkg

A web page with further information specific to SANE on UnixWare 7 can be
found here:

        http://www.sco.com/skunkware/sane/index.html

However, please note that the SANE package that is available from the
Skunkware server will most likely contain the latest stable version of
SANE. Since SANE is continuously being worked on, you might want to download
the latest source from the Git repository and build the source yourself.

To build SANE on a UnixWare 7.1.X system the following packages are required:

        * make (GNU make)
        * glibs (contains gtk, glib, libjpeg, libpnm, libtiff etc.; only
          necessary for frontends xscanimage, xcam, and xsane which are
          distributed separately)

The packages can be downloaded from the Skunkware ftp server (see URL above).
I've used the following versions to build sane-1.0.2:

        * make-3.78.1.pkg
        * glibs-2.0.3.pkg

If you want to include support for The Gimp (this is optional), you need to
install the gimp package, too. This is the version I've used:

        * gimp-1.0.4.pkg

GCC is not required. SANE compiles quite happily (and faster) with UnixWares
native C compiler.

Set the LD_RUN_PATH variable to add /usr/local/lib to the list of directories
to be searched by the dynamic linker:

        $ LD_RUN_PATH=/usr/local/lib
        $ export LD_RUN_PATH

Run the configure script as following:

        $ LIBS="-lsdi" ./configure

(The sdi library contains the SCSI passthrough functions the UW7 port of SANE
uses to access the scanner from user space.)

Run gmake to build SANE:

        $ gmake

SCSI access from user space requires special privileges. If you want users
without root perms to be able to use the scanner you can use the filepriv
command to change the privileges that are associated with the SANE
applications:

        # /sbin/filepriv -f driver -f sysops /usr/local/bin/scanimage
        # /sbin/filepriv -f driver -f sysops /usr/local/bin/xscanimage
        # /sbin/filepriv -f sysops /usr/local/bin/xcam

If you have built SANE with support for The Gimp you might want to create
a symlink from the plug-in directory to the xscanimage and xcam binaries,
e.g.:

        # ln -s /usr/local/bin/xscanimage \
                /usr/local/lib/gimp/1.0/plug-ins/xscanimage
        # ln -s /usr/local/bin/xcam /usr/local/lib/gimp/1.0/plug-ins/xcam

Questions? Comments? Please send e-mail to jenss@sco.com or skunkware@sco.com!

SANE on Windows

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

To be able to compile sane-backends, you need to have either Cygwin
or Mingw compilers and a suitable POSIX compatible environment.

You can get the Cygwin POSIX compatible environment for Windows
Windows and the Cygwin gcc compiler at http://www.cygwin.com

You can get the MSYS POSIX compatible environment for Windows and the
MinGW gcc compiler at http://www.mingw.org/wiki/MSYS

The scanner must be detected by Windows and not be disabled. Check
with the hardware manager.


Building
========

See general README for build basics. If a given backend fails to
compile, you can use the BACKENDS variable to limit compilation
to backends your interested in:

  ./configure BACKENDS=epson2


Configuring
===========

If you have more than one scanner, you should do the following:

  - run sane-find-scanner to get the device name of the scanner. The
    name for scsi devices is something like h0b0t6l0, meaning hba 0, bus 0,
    scsi id 6 and lun 0.

  - edit the config file for the backend
    (/path/to/sane/etc/sane.d/xxxx.conf) and add the scanner device name on
    an empty line.

  - Set environment variable SANE_CONFIG_DIR to point to the directory
    where the config files are located.

Run "scanimage > out.pnm" to get a scan.

xscanimage and XSane have been reported to compile and run in the past
under Cygwin.

Notes
=====

- Only SCSI, USB (with libusb-win32), and network scanners may work. No
  FireWire/Parallel. The Cygwin libusb port can be installed
  with Cygwin setup.exe or can be compiled manually under cygwin
  or mingw using the libusb-win32 port:
  http://sourceforge.net/apps/trac/libusb-win32/wiki

- Tested on Windows XP, 7, and using Wine on Linux.

- Some scanners' backend may not work because of requirement not
  supported by Cygwin or MinGW.


2011/10/08

SANE and Zeta
-------------

The Zeta port is based on existing BeOS port, with some changes
to accommodate yellowTAB's internal build procedure, and some new
conventions brought up by Zeta.

Cf. README.beos for more historical stuff.

SANE 1.0.9 was updated for Zeta by Ithamar Adema for yellowTAB.

SANE 1.0.15 was updated for BeOS and Zeta by François Revol for yellowTAB.

Zeta uses a modified version of Philippe Houdoin's Sanity GUI frontend.
http://philippe.houdoin.free.fr/phil/beos/sanity/index-en.html

SANE was reported to work with the following configuration and features:

Platform: Zeta R1 (== BeOS R6.x) ix86
Latest SANE version tested: 1.0.15
Compiler: gcc 2.95.3
User-level SCSI support: yes
USB support: yes
Shared library support: yes
Dynamic loading support: yes
X11 clients: no

Indexes created Thu Nov 07 10:32:03 CST 2024