sane-project-backends/doc/backend-writing.txt

501 wiersze
22 KiB
Plaintext

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.