diff --git a/README.linux b/README.linux index 0ae9d8a6..5cc6e202 100644 --- a/README.linux +++ b/README.linux @@ -11,11 +11,12 @@ attention. So if scanimage -L lists your scanner as root but not as normal user read on this text. The device files used by libusb are located in /proc/bus/usb/ -(e.g. /proc/bus/usb/001/003). 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. +(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 are the Linux hot-plug tools that should come with any current distribution. Your distribution should have set up @@ -119,6 +120,12 @@ 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 diff --git a/backend-writing.txt b/backend-writing.txt index d4878fdf..17aff221 100644 --- a/backend-writing.txt +++ b/backend-writing.txt @@ -1,4 +1,4 @@ -2005-09-03 +2006-01-01 Here are a few rules and tips that should help writing a SANE-conforming backend and including it into the SANE package: @@ -39,15 +39,201 @@ GETTING STARTED the SANE webpage. +CONFIGURATION AND BUILD SYSTEM +------------------------------ + +Sane-backends uses the autoconf tools but not automake. The configure script is +generated from configure.in and aclocal.m4 by running "autoconf". Simple checks +(e.g. for headers) should be placed into configure.in while for more complex +stuff acinclude.m4 is the right file. After changes in one of these files +"autoheader" and "autoconf" should be called. Autoheader creates +include/sane/config.h.in, while autoconf createts the "configure" script. In +CVS, all these changes must be commited (configure.in, configure, acinclude.m4, +include/sane/config.h.in). + +When running configure, the Makefiles in the main and sub-directories are +created from their respective Makefile.in files. Also include/sane/config.h +which is included into to every c file is created from its .in file. + +Running "make" runs the respective targets in the sub directories recursively. + +The Makefile.in in each directory contains lists of files which are part of the +distribution and which are therefore copied to the tar.gz archive, when a +release is made. It's important that newly added files are also added to their +respective DISTFILES variables in the Makefile.in. + +For creating binaries and libraries libtool is used. The ltmain.sh script +contains special modifications for SANE. In addition to fixes for MacOS these +modifications ensure that the soname of each SANE backend library is +"libsane.so". Without this change, backend libraries (like "libsane-epson.so") +could not used as on-the-fly replacement for the dll backend. + + +DIRECTORY OVERVIEW +------------------ + +This chapter explains some details about the files and directories used in the +sane-backends distribution. + +sane-backends/ + * acinclude.m4 aclocal.m4 config.guess config.sub configure configure.in + install-sh ltmain.sh Makefile.in mkinstalldirs: + Part of the build system as explained above. + * ChangeLog: + The ChangeLog contains all the changes made since the last stable release. If + anything is changed in CVS, it must be also mentioned in ChangeLog. It's not + enough to write just a CVS commit message, as users won't have access to + these messages. For more details on the format, see the SANE CVS page on the + website. + * ChangeLog-1.0.0, ChangeLog-1.0.1 (...): + These files contain the ChangeLogs of older releases. Once a new release has + been made, the current ChangeLog renamed to ChangeLog-1.something.something + and a new empty ChangeLog is created. + * AUTHORS COPYING LICENSE: + General documentation + license. + * NEWS: + This is some kind of executive summary of the ChangeLog. It will be created + before a release. + * PROBLEMS: + General (severe) problems that all SANE users should be + aware. Backend-specific trouble should normally not mentioned there. + * PROJECTS: + Planned SANE-related development (e.g. ports, frontends). New backends won't + be listed here but a new .desc file will be created for them (see below). + * README: + General building instructions. + * README.aix README.beos (...): + Platform-dependent building and usage instructions. + * sane-backends.lsm: + The .lsm file as used for the ibiblio archive. + +sane-backends/backend/ + This is where the actual backend code is placed. As an example the file + structure for a backend named "newbackend" is listed below. Backend names must + be unique and should not contain any special characters. Lower case letters, + numbers and underscores "_" are ok. + Backend documentation of any kind should not be placed here but in the doc/ + directory. Code which is useful for more than one backend should be placed in + sanei/ instead. + * newbackend.c: + The main backend file, usually contains the SANE API code. Mandatory. + * newbackend.h: + Header file, containing includes and so on. + * newbackend.conf.in: + Configuration file for the backend, newbackend.conf will be created by running + "make" from this file. Some variables are substituted, e.g. for installation + directories. This is especially usefukl for frimware directories. See + Makefile.in for a list. + * newbackend-low.c: + Contains low level code for the "newbackend" backend. Depending on the + complexity of the backend, splitting it toseveral files can be appropriate, + the total number of files shouldn't exceed approx. 10, however. + Other files: + * Makefile.in: + Makefile.in contains rather complex rules for building the backends. For + adding backends, special care should be taken concerning the FIRMWARE_DIRS + (add your backend name here, if your scanner needs firmware files) and + DISTFILES variables (see build system description). If your backend uses + separate object files, the additional dependencies must be added to the + EXTRA_newbackend variable. Also each backend that uses code from sanei must add + a line for each sanei file used, for sanei_usb code: + libsane-newbackend.la: ../sanei/sanei_usb.lo + * sane_strstatus.c: + Contains the code for the sane_strstatus() function to avoid code + duplication in every backend. + +sane-backends/doc/ + Documentation for SANE. For some more details, see chapter DOCUMENTATION + below. Again an example for "newbackend": + * sane-newbackend.man: + The manual page of the backend. From this file, "sane-newbackend.5" is + generated by running "make". + * newbackend/ (directory) + Contains additional information about newbackend, e.g. READMEs or TODO + files. + General files: + * Makefile.in: + "sane-newbackend.5" must be added to variable SECT5 and + "sane-newbackend.man" to DISTFILES. A backend documentation directory (if + used) must be added to the BACKDIRS variable. + * backend-writing.txt: + This file. + * descriptions.txt: + Describes the format of .desc files. + * doxygen-sanei.conf.in: + Used by doxygen to create the documentation of the sanei code. + * releases.txt: + Explains how to make releases of sane-backends. + * sane.tex, net.tex: + Contains the LaTeX source of the SANE standard. + * descriptions/ (directory) + Contains the .desc files for every backend that is included into sane-backends. + * descriptions-external/ (directory) + Contains the .desc files for backend that are not included into + sane-backends yet (external backends). These files should only be created + if the code it points to is really a SANE backend (and not just a command + line program). + +sane-backends/frontend/ + Contains the frontends scanimage, saned, and tstbackend. + +sane-backends/include/ + Header files used by the SANE backends. The main directory contains the + headers used for general librar functions like getopt, while the + SANE-specific headers are located in include/sane/: + * config.h.in: + Main header file needed for portablility. config.h is created from this + file and must be included by every backend. + * sane.h: + Official SANE API header file. Don't change this without discussion on + the sane-devel mailing list. + * saneopts.h: + Defines several option NAMEs, TITLEs and DESCs that are (or should be) + used by several backends. + * sanei_*: + Sanei (SANE internal) headers. Needed for code used in several backends + like USB access. For more details, see the documentaion on the SANE website. + +sane-backends/japi/ + Contains Java interface for SANE. See README.JAVA for details. + +sane-backends/lib/ + Contains various library functions that may miss in the standard C library + of some platforms. + +sane-backends/po/ + Translations of SANEbackend options. See README for details. + +sane-backends/sanei/ + Sanei (SANE internal) code. Needed for code used in several backends + like USB access. For more details, see the documentaion on the SANE website. + +sane-backends/testsuite/ + Testsuite for SANE. See README for details. + +sane-backends/tools/ + Contains several tools for SANE. There are backend-specific and general command line + tools as well as the hotplug support and .desc file generation code. See + README for details. + + PROGRAMMING ----------- * A backend library is always only one file (libsane-backendname.so). Please do not use miltiple libraries e.g. for lower and higher level code. -* The number of source code files for your backend should be limited. While it - is useful to split big backends into several files, the number of .c files - shouldn't exceed 5-10. Please see the existing backends for examples. +* To add the backend to the existing SANE code, the following must be done at + least: + - add the backend name to BACKENDS in configure.in (and rerun autoconf) + - add any parts of SANE that are used in the backend in + backend/Makefile.in. E.g., for the backend "newbackend" that uses + sanei_usb code: + libsane-newbackend.la: ../sanei/sanei_usb.lo + See the lines near the end of Makefile.in for examples. + - Add the source code files to the backend/ directories. All file names must + start with the backend name (e.g. newbackend.c, newbackend.h and + newbackend-usb.c). * Please follow the GNU coding standards. It's clear that the style outlined there is nobody's favorite, but it's much easier to @@ -197,8 +383,7 @@ TESTING * You can also test a backend with tstbackend. tstbackend is not compiled nor installed by default. To do that, cd into frontend and - edit the Makefile. Add "tstbackend" to BINPROGS. "tstbackend --help" - gives a short help. + run "make tstbackend". * Please test a backend not just with scanimage and xscanimage (+ other frontends), but also with saned. Based on past experience, @@ -214,7 +399,8 @@ TESTING * Please make sure that all global symbols exported from a SANE backend start with the prefix "sane" or "sanei" to avoid clashes with exported symbols - of other backends. Make sure, the sanei_* symbols are unique, e.g. by using + of other backends. Only symbols mentioned in the SANE standard should start + with "sane_*". Make sure, the sanei_* symbols are unique, e.g. by using sanei_backendname_*. Only export symbols that are absolutely necessary. You can verify this by running GNU "nm" on the static library. For example: