1How to configure, build, and install SANE.
2
3
4Introduction:
5=============
6SANE stands for Scanner Access Now Easy.
7This package contains the SANE libraries (this means backends and
8network scanning parts) and the command line frontend scanimage.
9You always find the most recent version of SANE on:
10
11  http://www.sane-project.org/
12
13At the same location there are also links to snapshots of the Git server and
14sometimes beta releases of sane-backends. These are unstable development
15versions, so be careful when using them. Please report any problems to us. See
16contact section for details.
17
18There are several graphical frontends available for SANE, see the list at
19http://www.sane-project.org/sane-frontends.html.
20
21
22Quick install:
23==============
24
25./autogen.sh    # only if you just cloned the git repository
26./configure
27make
28make install
29
30man sane
31
32Pre-built binaries:
33===================
34
35In addition to versions included in releases, some platforms have more current versions available.
36
37Ubuntu PPA https://launchpad.net/~sane-project/+archive/ubuntu/sane-release
38
39sudo add-apt-repository ppa:sane-project/sane-release
40sudo apt update
41apt install libsane libsane-common sane-utils
42
43
44Prerequisites
45=============
46
47In order to build SANE, the following tools and libraries are required:
48
49	- GNU make: version 3.70 or newer
50
51	- ISO C99 compiler: GNU C (gcc) is recommended for best results,
52	  but any ISO C99 compliant compiler should do
53
54
55Some more libraries are not strictly necessary to compile SANE, but some
56functionality may be lost if they are not available. Make sure that these
57libraries and their respective header files are available before running
58configure. On some Linux distributions the header files are part of separate
59packages (e.g. usb.h in libusb-devel or libusb-dev). These must also be
60installed.
61
62        - libusb: Strongly recommended if you use a USB scanner.
63          Some backends won't work without libusb at all.
64
65        - libjpeg (>=6B): For the dc210, dc240, and gphoto2 backends.
66
67        - libieee1284 (>=0.1.5): For some parallel port backends.
68
69        - libgphoto2 (>=2.0): For the gphoto2 backend.
70
71        - a C++11 compliant C++ compiler for the genesys backend.
72
73If you got the source straight from the git repository, as opposed to
74a source tarball, you will need a few more utilities.  These utilities
75should normally *not* be needed for source archives downloaded from
76the project's website at http://www.sane-project.org/.
77
78        - autoconf (>= 2.69) as well as the autoconf-archive (for the
79          AX_CXX_COMPILE_STDCXX and AX_CXX_COMPILE_STDCXX_11 macros)
80
81        - automake (>=1.15)
82
83        - libtool (>=2.4.6)
84
85        - gettext (>=0.19.8)
86
87        - git (>= 2.1.4)
88
89SANE should build on most Unix-like systems. Support for OS/2, MacOS X, BeOS,
90and Microsoft Windows is also available. For more details look at the
91operating system specific README.* files. For a detailed support matrix, see:
92
93    http://www.sane-project.org/sane-support.html
94
95This table may be out of date. Please tell us about any corrections or
96additions. Please mention your operating system and platform and all the other
97details mentioned in the table. See also the contact section.
98
99Please check that there aren't any older versions of SANE installed on your
100system. Especially if SANE libraries are installed in a different prefix
101directory (e.g. /usr/lib/) this may cause problems with external
102frontends. Please remove these libraries (libsane.*, sane/libsane-*) by using
103your package manager or manually before installing this version of SANE.
104
105
106Configuration
107=============
108
109Simply invoke configure in the top-level directory.  Besides the usual GNU
110configure options, there are the following SANE specific options:
111
112 --disable-shared
113	Don't use shared libraries.  Useful for debugging or when there
114	is a problem building shared libraries.  This implicitly turns
115	on --disable-dynamic --enable-static as well.
116
117 --disable-dynamic
118	Disable dynamic loading of backends (in the dll backend).
119	configure normally turns on dynamic loading when it
120	can find the appropriate header files and libraries
121	(<dlfcn.h> and -ldl).
122
123 --enable-static
124        Use static libraries (turned off by default).
125
126 --enable-preload
127        Preload backends into DLL backend.  This is useful for debugging,
128	when dynamic loading is unavailable, to reduce runtime linking
129	overheads, or when you only want to distribute a single DLL with
130	all backends available.  If dynamic loading or shared libraries are
131	unavailable or disabled, this option is turned on automatically.
132
133 --enable-scsibuffersize=N
134        Specify the buffer size of the buffer for SCSI commands. The default
135	value is 131072 bytes (128 kb). This may be changed at runtime by
136	setting	the environment variable SANE_SG_BUFFERSIZE to the desired
137	value. The option is Linux-only at this time.
138	--enable-scsibuffersize and SANE_SG_BUFFERSIZE have no effect for
139	the Mustek, Umax and Sharp backends. For these backends, the buffer
140	size is set automatically and/or can be specified in the backend's
141	configuration file. Please refer to the backend's man pages for
142	details.
143
144--enable-locking
145	Means, that some backends will use a lockfile for allowing multiple
146	access to one scanner. This is useful, i.e. one frontend is scanning
147	the button status and another one will scan. The path to the lock
148	files is defined by --localstatedir at the configure step and is
149	$localstatedir/lock. The default group is uucp and can be changed
150	by using --with-group=newgroup. If you do not want any backend to
151	use a lockfile, simply use --disable-locking.
152	Note: The Plustek backend is currently the only backend that makes
153	      use of this feature.
154
155To limit the backends that are compiled, set the variable BACKENDS to
156the list of backends to compile.  The following will limit compiling
157to the epson2 and fujitsu backends:
158
159  ./configure BACKENDS="epson2 fujitsu"
160
161To limit the backends that are preloaded into the DLL, set the variable
162PRELOADABLE_BACKENDS.  The following will limit compiling to the epson2
163and fujitsu backends but only preloads the epson2 backend:
164
165  ./configure BACKENDS="epson2 fujitsu" PRELOADABLE_BACKENDS="epson2"
166
167In addition to these configuration options, there are some more SANE-specific
168options and many standard-options.  To get a description of available options,
169invoke configure with option --help.
170
171If you plan on debugging one of the SANE programs, we recommend to run
172configure like this:
173
174   CFLAGS="-g -O -Wall" ./configure --disable-shared
175
176For operating system specific information, look at the README.* files.
177
178
179Build
180=====
181
182To build SANE, simply type "make" in the top-level directory.
183
184To clean up the executables and libraries in the source directory, type "make
185clean". To restore everything to the status after unpacking the package, type
186"make distclean".
187
188
189Installation and Configuration
190==============================
191
192Once the build has finished, install SANE with "make install".  By
193default, this will place the SANE libraries in /usr/local/lib/, the
194configuration files in /usr/local/etc/sane.d/, and the manual pages in
195/usr/local/man/.  The location of these directories can be overridden
196with configure options; see "configure --help" for details.
197
198Before running any SANE program, read the PROBLEMS file in this directory.
199
200For information on configuring and trouble-shooting the various SANE
201components, please refer to the manual page sane(7).
202
203The tools/ directory contains some small programs that may be helpful. They
204are described in tools/README.
205
206
207Removing
208========
209
210Type "make uninstall" to remove SANE from your system. This will also remove
211older versions of SANE if they have been installed at the same prefix.
212Warning: Your configuration files will be deleted also so make sure you have a
213backup. By default the configuration files are located in the directory
214/usr/local/etc/sane.d/.
215
216
217Contact
218=======
219
220For questions and general discussion about SANE contact the sane-devel mailing
221list. You must be subscribed to the list to send mail. See
222http://www.sane-project.org/mailing-lists.html for details.
223
224If you want to submit a bug report or feature request please use our bug
225tracking system.  See http://www.sane-project.org/bugs.html for details. You
226may also contact the author of a specific backend directly. See the AUTHORS
227file for a list of addresses.
228