kopia lustrzana https://gitlab.com/sane-project/backends
New chapters about the build system and the files and directories of
sane-backends. Fixed building instructions for tstbackend. Mentioned that sane_* symbols should be only used for API symbols.merge-requests/1/head
rodzic
e5f47c5dab
commit
6f039aa829
|
@ -57,6 +57,10 @@
|
|||
gt68xx, and snapscan backends variables were used. Bug #302590.
|
||||
* backend/.cvsignore: Added *.conf.
|
||||
* README.linux: Mentioned udev.
|
||||
* doc/backend-writing.txt: New chapters about the build system and
|
||||
the files and directories of sane-backends. Fixed building
|
||||
instructions for tstbackend. Mentioned that sane_* symbols
|
||||
should be only used for API symbols.
|
||||
|
||||
2006-01-03 Henning Meier-Geinitz <henning@meier-geinitz.de>
|
||||
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
2005-12-27
|
||||
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,16 +39,190 @@ 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)
|
||||
|
@ -209,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,
|
||||
|
@ -226,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:
|
||||
|
||||
|
|
Ładowanie…
Reference in New Issue