Re: README updates?

From: Henning Meier-Geinitz (hmg-ml@gmx.de)
Date: Tue May 09 2000 - 15:34:43 PDT

  • Next message: Henning Meier-Geinitz: "Re: README updates?"

    Hi,

    > It seems like a good idea. A cleanup and/or rewrite of the README
    > would be a good idea. Would you be willing to draft the new version?

    Ok, this is the first (raw) draft. It's mostly a cleanup of the old version.
    I changed the formatting a bit, moved the os specific things to their own
    files and added all the backends I found. Comments and questions are in
    square brackets []. Please look for spelling and grammar errors, too.

    Bye,
      Henning

    ------------------------ README ------------------------------
    -*-Mode: Outline-*-
    ^^^^^^^^^^^^^^^^^^^
    [what's this?]

    How to configure, build, and install 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

            - To build the graphical frontends (xscanimage and xcam), it is
              necessary to have the GTK libraries (libgtk, libgdk, and
              libglib) and associated header files installed. In
              addition, if you want to use xscanimage from within GIMP,
              you'll need to make sure libgimp (version 0.99.13 or newer)
              and its header files are installed as well. The GTK libraries and
              GIMP can be obtained from:

                    ftp://ftp.gimp.org/pub/

    SANE is known to build on the following platforms:

            - AIX
            - Digital Unix (Alpha) [no generic SCSI support]
            - FreeBSD
            - FreeSCO
            - HP-UX (PA-RISC)
            - IRIX
            - Linux (Alpha, m68k, x86)
            - NetBSD (x86?)
            - OpenStep/NeXTStep (x86) [xscanimage/xcam untested]
            - OS/2
            - Solaris (SPARC)
            - SunOS (SPARC) [no generic SCSI support]

    [up-to-date? The only thing I know is that SANE 1.0.2 compiles and works under
    Linux/x86 and compiles under Irix5.3 (pnm works, don't know about SCSI)]

    For a detailed support matrix, see:

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

    [which is not up-to-date either]

    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.
    [is this true?]

    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)
        xscanimage xscanimage(1)
        saned saned(1)
        xcam frontend/xcam.README
    [move xcam.README to doc/ (better: add a man page)?]

      Backends for scanners:
        Abaton sane-abaton(5)
        AGFA Focus sane-agfafocus(5)
        AGFA SnapScan http://www.cs.ualberta.ca/~charter/SnapScan/snapscan.html
    [add man page?]
        Apple sane-apple(5)
        Artec sane-artec(5)
        Avision http://www.rene.rebe.myokay.net/avision/index.html
        Canon doc/canon.README
        Nikon Coolscan http://www.sema.be/coolscan/
    [add man pages?]
        Epson sane-epson(5)
        Fujitsu sane-fujitsu(5)
        HP sane-hp(5)
        Microtek sane-microtek(5)
        Mikrotek SCSI-2 sane-microtek2(5)
        Mustek sane-mustek(5)
        Sharp sane-sharp(5)
        UMAX sane-umax(5)
        
      Backends for digital cameras:
        Connectix QuickCam sane-qcam(5)
        Kodak DC20/DC25 sane-dc25(5)
        Polaroid sane-dmc(5)
      
      Miscellaneous backends:
        PNM image reader sane-pnm(5)
        PINT scanners sane-pint(5)

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

    [I couldn't find any documentation for:
        Kodak dc210
        Ricoh
        Siemens S9036
        Tamarack

     Are any backends missing? Some backends are for more than one vendor,
     should I add more vendors?]

    For more details on supported scanners and cameras look at the SANE
    website: http://www.mostang.com/sane/sane-backends.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.

    If you encounter any problems with getting your device(s) recognized,
    try setting the various environment variables that are there 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 tools/find-scanner. It is normally sufficient to
    invoke the program without any arguments. Invoking this command
    should produce output similar to this:

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

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

    --------------------------- README.aix ---------------------------------
    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
    ---------------------------end of README.aix ---------------------------

    --------------------------- README.hp-ux -------------------------------
    Under HP-UX, it is necessary to add options -Aa and -D_HPUX_SOURCE to
    the compiler flags when using HP's C compiler (not gcc). This can be
    done by invoking configure with:

            CC=cc CPPFLAGS=-D_HPUX_SOURCE CFLAGS=-Aa ./configure
    --------------------------- end of README.hp-ux ------------------------

    --------------------------- README.linux -------------------------------
    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 tools/find-scanner:

    # tools/find-scanner
    find-scanner: found scanner "SCANNER 2.02" at device /dev/scanner
    find-scanner: found scanner "SCANNER 2.02" at device /dev/sg0
    find-scanner: found scanner "SCANNER 2.02" at device /dev/sga

    It may help to set a soft link /dev/scanner to the respective device.

    [add comment on Adaptec 1542 problems and solution or move this to
     sane-scsi(5)?]

    --------------------------- end of README.linux ------------------------

    --
    Source code, list archive, and docs: http://www.mostang.com/sane/
    To unsubscribe: echo unsubscribe sane-devel | mail majordomo@mostang.com
    



    This archive was generated by hypermail 2b29 : Tue May 09 2000 - 15:38:32 PDT