diff options
Diffstat (limited to 'doc/backend-writing.txt')
| -rw-r--r-- | doc/backend-writing.txt | 95 |
1 files changed, 43 insertions, 52 deletions
diff --git a/doc/backend-writing.txt b/doc/backend-writing.txt index 7e34d6a..736fcec 100644 --- a/doc/backend-writing.txt +++ b/doc/backend-writing.txt @@ -1,4 +1,4 @@ -2006-01-01 +2019-08-26 Here are a few rules and tips that should help writing a SANE-conforming backend and including it into the SANE package: @@ -45,12 +45,11 @@ CONFIGURATION AND BUILD SYSTEM Sane-backends uses the autoconf and automake tools. The configure script is generated from configure.ac and aclocal.m4 by running "autoreconf". Simple checks (e.g. for headers) should be placed into configure.ac while -for more complex stuff acinclude.m4 is the right file. After changes in one +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. +Makefile.in's from Makefile.am's. When running configure, the Makefiles in the main and sub-directories are created from their respective Makefile.in files. Also include/sane/config.h @@ -60,13 +59,13 @@ 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 +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 +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 @@ -76,37 +75,29 @@ 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 + * acinclude.m4 aclocal.m4 compile config.guess config.sub configure configure.ac 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, write a decent commit message documenting - your work. This commit message will be included as is in the ChangeLog - file for the next stable release. Users of development code should refer - to the `git log` output or the on-line log. - 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. + The ChangeLog contains all the changes made since sane-backends-1.0.28 + or a stub explaining how to create an up-to-date list of changes. + ChangeLogs for all releases up to and including 1.0.28 can be found in + the ChangeLogs/ directory. Please note that we skipped 1.0.26. * 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. + before a release. * PROBLEMS: General (severe) problems that all SANE users should be - aware. Backend-specific trouble should normally not mentioned there. + 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. + Platform-dependent building and usage instructions. sane-backends/backend/ This is where the actual backend code is placed. As an example the file @@ -117,13 +108,13 @@ sane-backends/backend/ 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. + 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 + 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 @@ -147,16 +138,16 @@ sane-backends/backend/ sane-backends/doc/ Documentation for SANE. For some more details, see chapter DOCUMENTATION below. Again an example for "newbackend": - * sane-newbackend.man: + * sane-newbackend.man: The manual page of the backend. From this file, "sane-newbackend.5" is - generated by running "make". + generated by running "make". * newbackend/ (directory) Contains additional information about newbackend, e.g. READMEs or TODO - files. + files. General files: * Makefile.am: "sane-newbackend.5" must be added to variable BACKEND_5MANS and - "sane-newbackend.man" to EXTRA_DIST. A backend documentation directory + "sane-newbackend.man" to EXTRA_DIST. A backend documentation directory (if used) must be added to the BEDOCS variable. * backend-writing.txt: This file. @@ -169,13 +160,13 @@ sane-backends/doc/ * 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 + 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). + line program). sane-backends/frontend/ Contains the frontends scanimage, saned, and tstbackend. @@ -186,8 +177,8 @@ sane-backends/include/ 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: + 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: @@ -202,14 +193,14 @@ sane-backends/japi/ sane-backends/lib/ Contains various library functions that may miss in the standard C library - of some platforms. + 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 + like USB access. For more details, see the documentaion on the SANE website. sane-backends/testsuite/ @@ -231,14 +222,14 @@ PROGRAMMING least: - add the backend name to ALL_BACKENDS in configure.ac (and run autoreconf) - Add new backend to BACKEND_CONFS, be_convenience_libs, be_dlopen_libs, - and define _lib${backend}_la_SOURCES and + 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 + - 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). + 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 @@ -295,7 +286,7 @@ PROGRAMMING * If you use headers or libraries that may not be available on all systems, write a check for configure.ac and include it conditionally. If your backend - depends on these libraries or headers, compile the backend only if they are + 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 @@ -311,9 +302,9 @@ PROGRAMMING * 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. +* 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 + 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 @@ -389,7 +380,7 @@ TESTING 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 +* 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" @@ -402,7 +393,7 @@ TESTING 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 + 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. @@ -410,7 +401,7 @@ TESTING nm -g backend/.libs/libsane-hp.a - would list all global symbols in the HP backend. + 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. @@ -433,14 +424,14 @@ DOCUMENTATION 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/". + 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 + doc/sane.man and AUTHORS. 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. @@ -458,7 +449,7 @@ DOCUMENTATION version numbers. -CHECKLIST: SUBMITTING A NEW BACKEND +CHECKLIST: SUBMITTING A NEW BACKEND ----------------------------------- In sane-backends/ @@ -481,7 +472,7 @@ In sane-backends/doc/ 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 |