diff options
Diffstat (limited to 'doc/backend-writing.txt')
| -rw-r--r-- | doc/backend-writing.txt | 500 |
1 files changed, 500 insertions, 0 deletions
diff --git a/doc/backend-writing.txt b/doc/backend-writing.txt new file mode 100644 index 0000000..7b49041 --- /dev/null +++ b/doc/backend-writing.txt @@ -0,0 +1,500 @@ +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: + + +GETTING STARTED +--------------- + +* You will need information about the protocol the scanner (or other image + application device) is using. The easiest way is to ask the manufacturer + about it. You should mention that the code will be open-source, however. + +* Read the SANE standard. + +* One approach is to write a stand-alone scanning program first. Debugging + this program is usually easier than using the SANE libraries. However, keep + in mind what you learned from the SANE standard. + +* Once your program works basically, insert its functions into a basically + empty SANE backend. You can get one by removing everything but the SANE + includes and SANE API function definitions from an existing backend (e.g. + test.c). + +* If you have any information about the scanner you want to support that + is not already mentioned in one of the .desc files, please contact the + sane-devel mailing list. Especially if you have written code (e.g. a test + program) or started writing a backend, contact us. + +* Keep other users informed about what you did and want to do. This way no + work is done twice and you may get volunteers for coding or testing. + Set up a website or at least write to sane-devel. If you have a website, + a link to it can be included in the .desc file and users looking for that + scanner will find it on the SANE website. + +* When you have a working backend but you don't want to have it included + in the SANE distribution yet, at least the .desc file can be included + (see below for details). So people will find a link to your backend at + the SANE webpage. + + +CONFIGURATION AND BUILD SYSTEM +------------------------------ + +Sane-backends uses the autoconf and automake tools. The configure script is +generated from configure.in and aclocal.m4 by running "autoreconf". +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, "autoreconf" should be called. This will then call a +chain of autotools, such as autoconf to generate configure, autoheader +to generate include/sane/config.h.in, and automake to generate various +Makefile.in's from Makefile.am's. All changes made by "autoreconf" must +be commited together. + +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.am 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 +a variable that will cause them to be distributed (EXTRA_DIST at a minimum). + +For creating binaries and libraries libtool is used. The ltmain.sh script +contains special modifications for SANE. 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 compile config.guess config.sub configure + configure.in depcomp install-sh ltmain.sh Makefile.am Makefile.in missing + 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 git, it must be also mentioned in ChangeLog. + It's not enough to write just a git commit message, as users won't have + access to these messages. For more details on the format, see the SANE + git 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 INSTALL 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 useful for firmware + directories. See Makefile.am for a list. + * newbackend-low.c: + Contains low level code for the "newbackend" backend. Depending on the + complexity of the backend, splitting it to several files can be appropriate, + the total number of files shouldn't exceed approx. 10, however. + Other files: + * Makefile.am, Makefile.in: + Makefile.am 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 + other variables (see build system description). There is some + documentation inside of Makefile.am on what needs to be added and where. + At a minimum, a convenience library of form lib${backend}.la and + a installed library libsane-${backend}.la must be defined. Any + sanei objects referenced should be listed in a + libsane_${backend}_la_LIBADD line. + * 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 BACKEND_5MANS and + "sane-newbackend.man" to EXTRA_DIST. A backend documentation directory + (if used) must be added to the BEDOCS 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 multiple libraries e.g. for lower and higher level code. + +* To add the backend to the existing SANE code, the following must be done at + least: + - add the backend name to ALL_BACKENDS in configure.in (and run autoreconf) + - Add new backend to BACKEND_CONFS, be_convenience_libs, be_dlopen_libs, + and define _lib${backend}_la_SOURCES and + nodist_libsane_${backend}_la_SOURCES; using an existing backend as + a template. Any sanei reference code should be listed in + libsane_${backend}_la_LIBADD as well as any external libraries + required to resolve all symbols. + - 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 + maintain SANE if everybody follows more or less the same coding + style. It also looks more professional. The GNU standards can be + found at: + + http://www.gnu.org/prep/standards_toc.html + ftp://ftp.gnu.org/pub/gnu/standards/standards.text + + Note that GNU emacs supports automatic indentation according to this + standard. The command "indent -gnu" can be used to reformat + existing sources according to this standard. + +* Please be courteous to programmer's with terminals that are 80 + characters wide. It's not difficult to avoid long lines, so please + do so. Note that in ANSI C you can split long strings into pieces + separated by white space. For example, + "this is an awfully long string" can be written as "this is an " + "awfully long string". + +* Use only ANSI C for your backend. C99 is not supported by the compilers of + some older platforms so please avoid using its features. + +* Please do not depend on compiler specific features or, if you do, make + the dependency conditional so other compilers will still be able to + compile the files. In particular: + + - do not use C++ style comments (//-line comments) + + - do not declare dynamically sized automatic arrays; instead, + use alloca() after including "../include/lalloca.h". For example: + + void + func (int n) + { + char buf[n]; + } + + should be re-written as: + + #ifdef _AIX + # include "../include/lalloca.h" /* MUST come first for AIX! */ + #endif + + #include "../include/sane/config.h" + #include "../include/lalloca.h" + : + void + func (int n) + { + char *buf = alloca (n); + } + - Don't use any #pragma directives---they're completely + compiler-dependent. + +* If you use headers or libraries that may not be available on all systems, + write a check for configure.in and include it conditionally. If your backend + depends on these libraries or headers, compile the backend only if they are + available (see pint for an example). + +* Use #include ".../include/sane/..." to include the sane header files + instead of #include <sane/...>. Otherwise problems with different installed + SANE versions may occur. Also this makes clear that the local files are used. + +* Don't forget to #include ".../include/sane/config.h" in your backend before + any other includes. This must be done for any .c file that generates its own + object file. If you use lalloca.h see above for the correct includes. + +* Include sanei_backend.h after the other includes. + +* It's no longer necessary to #define PATH_MAX (now in sanei_backend.h). + If you define it, do so *after* the system includes. + +* Please use sanei functions whenever possible (e.g. + sanei_config_read()). This makes porting to other os/platforms much + easier. Most of these functions are documented in their respective + header files in include/sane/sanei_*.h. For most of them there is also + documentation in doxygen format: http://www.sane-project.org/sanei/. These + HTML pages can be generated by calling "doxygen sanei-doxygen.conf" in + the doc/ directory. + +* Initialize global variables explicitly in sane_init. Keep in mind that + sane_init can be called more than once (if sane_exit is called everytime + after sane_init). Therefore don't depend on automatic initialization to + 0 / NULL. + +* Do make sure that your code is byte-order independent. This is + particularly important for networking-related code and when dealing + with non-textual data files. + +* Don't use printf, fprintf or perror to output debug or error messages. + Use the DBG macro instead. If your backend can't detect a scanner for + whatever reason it shouldn't output anything as long as + SANE_DEBUG_BACKENDNAME isn't set. So don't use DBG(0, ...) in this case. + +* Please do not assume that `size_t' is `unsigned int'. On some + systems, it's `unsigned long' and the size of this type may be + bigger than that of an int (this is true for practically any of the + 64-bit systems). To print a variable of type size_t portably, cast + the variable to u_long and print it with the %lu specifier. E.g.: + + size_t len; + + DBG(3, "len=%lu\n", (u_long) len); + +* Please do not assume that `void *' has the same size as `int'. On some + systems, it's `long' and the size of this type may be bigger than that of + an int (this is true for practically any of the 64-bit systems). Where this + comes up is with opaque handles. For example: + + int OpaqueHandle; + MyScanner *s = (MyScanner *)OpaqueHandle; + + will FAIL on most 64 bit systems. Please use `void *' or better + `SANE_Handle'. + +* Don't use exit() in your backend. You will exit the whole program, not only + your backend. + +* If you use wait() or waitpid() in your backend, check its return value. This + is important, if the status value is checked for e.g. WIFEXITED after the + call of wait() or waitpid(). Both functions may fail if the frontend already + did a wait for the children. + +* Please try to avoid compilation warnings. At least with "--disable-warnings" + there shouldn't be warnings when compiling backends. It's not necessary to + fix every "unused parameter" warning but take care that no warnings pointing + to really existing problems or ambiguities are missed. Some programming + techniques generating warnings on gcc may lead to errors on other systems. + +* To support translation of SANE options, please mark the descriptions (desc) + and title of options with SANE_I18N() and add all files using SANE_I18N() to + po/POTFILES. See po/README for details. + +* Please check for TL_X < BR_X and TL_Y < BR_Y to avoid segfaults or even + scanner damage. This should NOT be done in sane_control_option, it should + be possible to temporary set TL_X > BR_X or TL_ > BR, otherwise it is hard + for a frontend to set the correct values. + + +TESTING +------- + +* Please test a backend with "scanimage -T" (plus other options, + as appropriate/necessary) as this will make sure that sane_read() + always returns the correct amount of data etc. + +* You can also test a backend with tstbackend. tstbackend is not + compiled nor installed by default. To do that, cd into frontend and + run "make tstbackend". + +* Please test a backend not just with scanimage and xscanimage + (+ other frontends), but also with saned. Based on past experience, + it is often the case that remote scanning can uncover subtle bugs. + Note that you don't have to use two different machines to test "remote" + scanning---you can use one and the same machine to test a backend via saned + (just be sure to enable the "net" backend in dll.conf and follow the + steps described in saned(8)). + +* Please test on every available platform/os. Even if no scanner is attached + to this system, test compilation and running scanimage. If you don't have + access to other platforms, ask sane-devel. + +* 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. 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: + + nm -g backend/.libs/libsane-hp.a + + would list all global symbols in the HP backend. + + "./configure; make; make libcheck" in the sane-backends root directory + will name all backend libraries, that contain "illegal" symbols. + +DOCUMENTATION +------------- + +* Even if you haven't written a man-page for your backend yet, you *must* + create a .desc file which describes it. Anytime you submit source code for + your backend, you should include an update to the .desc file which reflects + the new state of the backend. The .desc files are used to create the HTML + lists of supported devices. These lists are updated automatically when you + change a .desc file in git. See e.g. + http://www.sane-project.org/lists/sane-mfgs-cvs.html for the results. + +* The .desc files are located in the directories "doc/descriptions" and + "doc/descriptions-external" (for included and external backends). + +* "doc/descriptions.txt" describes the format of the ".desc" files. There is + also a template for new .desc files: "template.desc.". The format of the + files in the two directories is very similar. If you'd like to try parsing + your creation to recreate the sane-backends webpages, cd into "tools/" and + enter "make sane-desc". You can either use sane-desc directly (try + "./sane-desc -h") or use "make html-pages" in "doc/". + +* For external backends, you don't need to supply :manpage and :version. The + manpage link won't work anyway and version will be outdated soon. + +* When your backend is included in the SANE distribution, add an entry to + doc/sane.man, AUTHORS and sane-backends.lsm. The sane.man entry should point + to your documentation (man-page, website, readme). Also move your .desc + file from "doc/descriptions-external" to "doc/descriptions" and update + them. + +* In your manual page (backend.man), use @LIBDIR@ and the other macros for + path names to the libraries, config files and documentation. Don't use fixed + paths as they will be wrong if SANE is installed with a different prefix + (e.g. /usr instead of /usr/local). + +* If you want to include READMEs, HTML files or other documentation, please + create your own directory (doc/backendname) and store your files in this + directory. If you only have a manual page a subdirectory isn't necessary. + +* Please keep your manpages and .desc files up-to-date especially regarding + version numbers. + + +CHECKLIST: SUBMITTING A NEW BACKEND +----------------------------------- + +In sane-backends/ +* Add the author(s) name(s) to AUTHORS +* Correct any related entries in the bug-tracking system + +In sane-backends/backend/ +* Use the command "indent -gnu" to reformat your code according to the + standard. +* Add the backend name to dll.conf +* Check that the SANE license is in the backend source files. +* Add the source file names and the .conf file + to BACKEND_CONFS in Makefile.am + +In sane-backends/doc/ +* Add an entry for the man page in sane.man +* Add the man page file in doc/Makefile.in +* Move the description file from descriptions-external/ to doc/descriptions/ +* Check that the description file is correct: "cd doc; make html-pages" and + check the html pages result with a browser. +* Check that the backend version is the same in the source and in the + description file. + +In sane-backends/po/ +* Add all files using SANE_I18N() to po/POTFILES + + +INCLUDING INTO git +------------------ + +* If you want to include your backend into SANE's git tree use the latest git + to make patches. Check the mailing list and the bug-tracking system for + information about bugs to avoid. + +* If your backend isn't included yet in the SANE's git tree, write an email to + the SANE mailing list (sane-devel) and ask for inclusion. Usually one + of the developers will check the backend for common mistakes and test + compilation. If everything is ok the backend will be added to the git tree. |