From 58912f68c2489bcee787599837447e0d64dfd61a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Wed, 24 May 2017 21:03:56 +0200 Subject: New upstream version 1.0.27 --- doc/backend-writing.txt | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) (limited to 'doc/backend-writing.txt') diff --git a/doc/backend-writing.txt b/doc/backend-writing.txt index 7b49041..7e34d6a 100644 --- a/doc/backend-writing.txt +++ b/doc/backend-writing.txt @@ -43,8 +43,8 @@ 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 +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 of these files, "autoreconf" should be called. This will then call a chain of autotools, such as autoconf to generate configure, autoheader @@ -77,14 +77,15 @@ 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 + 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, 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. + 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 @@ -153,7 +154,7 @@ sane-backends/doc/ Contains additional information about newbackend, e.g. READMEs or TODO files. General files: - * Makefile.in: + * Makefile.am: "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. @@ -228,7 +229,7 @@ PROGRAMMING * 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 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 nodist_libsane_${backend}_la_SOURCES; using an existing backend as @@ -254,20 +255,18 @@ PROGRAMMING * 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 + do so. Note that in standard 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. +* Use only standard C for your backend. ISO C99 support will be enabled + if supported by the compiler detected by configure. * 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: @@ -295,7 +294,7 @@ PROGRAMMING 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 + 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 available (see pint for an example). @@ -476,7 +475,7 @@ In sane-backends/backend/ In sane-backends/doc/ * Add an entry for the man page in sane.man -* Add the man page file in doc/Makefile.in +* Add the man page file in doc/Makefile.am * 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. -- cgit v1.2.3 From 1687222e1b9e74c89cafbb5910e72d8ec7bfd40f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Wed, 31 Jul 2019 16:59:49 +0200 Subject: New upstream version 1.0.28 --- doc/backend-writing.txt | 79 ++++++++++++++++++++++++------------------------- 1 file changed, 38 insertions(+), 41 deletions(-) (limited to 'doc/backend-writing.txt') diff --git a/doc/backend-writing.txt b/doc/backend-writing.txt index 7e34d6a..576e8e4 100644 --- a/doc/backend-writing.txt +++ b/doc/backend-writing.txt @@ -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,7 +75,7 @@ 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: @@ -94,19 +93,17 @@ sane-backends/ 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 +114,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 +144,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 +166,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 +183,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 +199,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 +228,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 +292,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 +308,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 +386,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 +399,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 +407,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 +430,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 +455,7 @@ DOCUMENTATION version numbers. -CHECKLIST: SUBMITTING A NEW BACKEND +CHECKLIST: SUBMITTING A NEW BACKEND ----------------------------------- In sane-backends/ @@ -481,7 +478,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 -- cgit v1.2.3