12019-08-26 2 3Here are a few rules and tips that should help writing a 4SANE-conforming backend and including it into the SANE package: 5 6 7GETTING STARTED 8--------------- 9 10* You will need information about the protocol the scanner (or other image 11 application device) is using. The easiest way is to ask the manufacturer 12 about it. You should mention that the code will be open-source, however. 13 14* Read the SANE standard. 15 See https://sane-project.gitlab.io/standard/ 16 17* One approach is to write a stand-alone scanning program first. Debugging 18 this program is usually easier than using the SANE libraries. However, keep 19 in mind what you learned from the SANE standard. 20 21* Once your program works basically, insert its functions into a basically 22 empty SANE backend. You can get one by removing everything but the SANE 23 includes and SANE API function definitions from an existing backend (e.g. 24 test.c). 25 26* If you have any information about the scanner you want to support that 27 is not already mentioned in one of the .desc files, please contact the 28 sane-devel mailing list. Especially if you have written code (e.g. a test 29 program) or started writing a backend, contact us. 30 31* Keep other users informed about what you did and want to do. This way no 32 work is done twice and you may get volunteers for coding or testing. 33 Set up a website or at least write to sane-devel. If you have a website, 34 a link to it can be included in the .desc file and users looking for that 35 scanner will find it on the SANE website. 36 37* When you have a working backend but you don't want to have it included 38 in the SANE distribution yet, at least the .desc file can be included 39 (see below for details). So people will find a link to your backend at 40 the SANE webpage. 41 42 43CONFIGURATION AND BUILD SYSTEM 44------------------------------ 45 46Sane-backends uses the autoconf and automake tools. The configure script is 47generated from configure.ac and aclocal.m4 by running "autoreconf". 48Simple checks (e.g. for headers) should be placed into configure.ac while 49for more complex stuff acinclude.m4 is the right file. After changes in one 50of these files, "autoreconf" should be called. This will then call a 51chain of autotools, such as autoconf to generate configure, autoheader 52to generate include/sane/config.h.in, and automake to generate various 53Makefile.in's from Makefile.am's. 54 55When running configure, the Makefiles in the main and sub-directories are 56created from their respective Makefile.in files. Also include/sane/config.h 57which is included into to every c file is created from its .in file. 58 59Running "make" runs the respective targets in the sub directories recursively. 60 61The Makefile.am in each directory contains lists of files which are part of the 62distribution and which are therefore copied to the tar.gz archive, when a 63release is made. It's important that newly added files are also added to 64a variable that will cause them to be distributed (EXTRA_DIST at a minimum). 65 66For creating binaries and libraries libtool is used. The ltmain.sh script 67contains special modifications for SANE. These modifications ensure that 68the soname of each SANE backend library is "libsane.so". Without this 69change, backend libraries (like "libsane-epson.so") could not used as 70on-the-fly replacement for the dll backend. 71 72DIRECTORY OVERVIEW 73------------------ 74 75This chapter explains some details about the files and directories used in the 76sane-backends distribution. 77 78sane-backends/ 79 * acinclude.m4 aclocal.m4 compile config.guess config.sub configure 80 configure.ac depcomp install-sh ltmain.sh Makefile.am Makefile.in missing 81 mkinstalldirs: Part of the build system as explained above. 82 * ChangeLog: 83 The ChangeLog contains all the changes made since sane-backends-1.0.28 84 or a stub explaining how to create an up-to-date list of changes. 85 ChangeLogs for all releases up to and including 1.0.28 can be found in 86 the ChangeLogs/ directory. Please note that we skipped 1.0.26. 87 * AUTHORS COPYING INSTALL LICENSE: 88 General documentation + license. 89 * NEWS: 90 This is some kind of executive summary of the ChangeLog. It will be created 91 before a release. 92 * PROBLEMS: 93 General (severe) problems that all SANE users should be 94 aware. Backend-specific trouble should normally not mentioned there. 95 * PROJECTS: 96 Planned SANE-related development (e.g. ports, frontends). New backends won't 97 be listed here but a new .desc file will be created for them (see below). 98 * README: 99 General building instructions. 100 * README.aix README.beos (...): 101 Platform-dependent building and usage instructions. 102 103sane-backends/backend/ 104 This is where the actual backend code is placed. As an example the file 105 structure for a backend named "newbackend" is listed below. Backend names must 106 be unique and should not contain any special characters. Lower case letters, 107 numbers and underscores "_" are ok. 108 Backend documentation of any kind should not be placed here but in the doc/ 109 directory. Code which is useful for more than one backend should be placed in 110 sanei/ instead. 111 * newbackend.c: 112 The main backend file, usually contains the SANE API code. Mandatory. 113 * newbackend.h: 114 Header file, containing includes and so on. 115 * newbackend.conf.in: 116 Configuration file for the backend, newbackend.conf will be created by 117 running "make" from this file. Some variables are substituted, e.g. for 118 installation directories. This is especially useful for firmware 119 directories. See Makefile.am for a list. 120 * newbackend-low.c: 121 Contains low level code for the "newbackend" backend. Depending on the 122 complexity of the backend, splitting it to several files can be appropriate, 123 the total number of files shouldn't exceed approx. 10, however. 124 Other files: 125 * Makefile.am, Makefile.in: 126 Makefile.am contains rather complex rules for building the backends. For 127 adding backends, special care should be taken concerning the FIRMWARE_DIRS 128 (add your backend name here, if your scanner needs firmware files) and 129 other variables (see build system description). There is some 130 documentation inside of Makefile.am on what needs to be added and where. 131 At a minimum, a convenience library of form lib${backend}.la and 132 a installed library libsane-${backend}.la must be defined. Any 133 sanei objects referenced should be listed in a 134 libsane_${backend}_la_LIBADD line. 135 * sane_strstatus.c: 136 Contains the code for the sane_strstatus() function to avoid code 137 duplication in every backend. 138 139sane-backends/doc/ 140 Documentation for SANE. For some more details, see chapter DOCUMENTATION 141 below. Again an example for "newbackend": 142 * sane-newbackend.man: 143 The manual page of the backend. From this file, "sane-newbackend.5" is 144 generated by running "make". 145 * newbackend/ (directory) 146 Contains additional information about newbackend, e.g. READMEs or TODO 147 files. 148 General files: 149 * Makefile.am: 150 "sane-newbackend.5" must be added to variable BACKEND_5MANS and 151 "sane-newbackend.man" to EXTRA_DIST. A backend documentation directory 152 (if used) must be added to the BEDOCS variable. 153 * backend-writing.txt: 154 This file. 155 * descriptions.txt: 156 Describes the format of .desc files. 157 * doxygen-sanei.conf.in: 158 Used by doxygen to create the documentation of the sanei code. 159 * releases.txt: 160 Explains how to make releases of sane-backends. 161 * descriptions/ (directory) 162 Contains the .desc files for every backend that is included into 163 sane-backends. 164 * descriptions-external/ (directory) 165 Contains the .desc files for backend that are not included into 166 sane-backends yet (external backends). These files should only be created 167 if the code it points to is really a SANE backend (and not just a command 168 line program). 169 170sane-backends/frontend/ 171 Contains the frontends scanimage, saned, and tstbackend. 172 173sane-backends/include/ 174 Header files used by the SANE backends. The main directory contains the 175 headers used for general librar functions like getopt, while the 176 SANE-specific headers are located in include/sane/: 177 * config.h.in: 178 Main header file needed for portablility. config.h is created from this 179 file and must be included by every backend. 180 * sane.h: 181 Official SANE API header file. Don't change this without discussion on 182 the sane-devel mailing list. 183 * saneopts.h: 184 Defines several option NAMEs, TITLEs and DESCs that are (or should be) 185 used by several backends. 186 * sanei_*: 187 Sanei (SANE internal) headers. Needed for code used in several backends 188 like USB access. For more details, see the documentation on the SANE website. 189 190sane-backends/japi/ 191 Contains Java interface for SANE. See README.JAVA for details. 192 193sane-backends/lib/ 194 Contains various library functions that may miss in the standard C library 195 of some platforms. 196 197sane-backends/po/ 198 Translations of SANEbackend options. See README for details. 199 200sane-backends/sanei/ 201 Sanei (SANE internal) code. Needed for code used in several backends 202 like USB access. For more details, see the documentation on the SANE 203 website. 204 205sane-backends/testsuite/ 206 Testsuite for SANE. See README for details. 207 208sane-backends/tools/ 209 Contains several tools for SANE. There are backend-specific and general command line 210 tools as well as the hotplug support and .desc file generation code. See 211 README for details. 212 213 214PROGRAMMING 215----------- 216 217* A backend library is always only one file (libsane-backendname.so). Please do 218 not use multiple libraries e.g. for lower and higher level code. 219 220* To add the backend to the existing SANE code, the following must be done at 221 least: 222 - add the backend name to ALL_BACKENDS in configure.ac (and run autoreconf) 223 - Add new backend to BACKEND_CONFS, be_convenience_libs, be_dlopen_libs, 224 and define _lib${backend}_la_SOURCES and 225 nodist_libsane_${backend}_la_SOURCES; using an existing backend as 226 a template. Any sanei reference code should be listed in 227 libsane_${backend}_la_LIBADD as well as any external libraries 228 required to resolve all symbols. 229 - Add the source code files to the backend/ directories. All file names 230 must start with the backend name (e.g. newbackend.c, newbackend.h and 231 newbackend-usb.c). 232 233* Please follow the GNU coding standards. It's clear that the style 234 outlined there is nobody's favorite, but it's much easier to 235 maintain SANE if everybody follows more or less the same coding 236 style. It also looks more professional. The GNU standards can be 237 found at: 238 239 http://www.gnu.org/prep/standards_toc.html 240 ftp://ftp.gnu.org/pub/gnu/standards/standards.text 241 242 Note that GNU emacs supports automatic indentation according to this 243 standard. The command "indent -gnu" can be used to reformat 244 existing sources according to this standard. 245 246* Please be courteous to programmer's with terminals that are 80 247 characters wide. It's not difficult to avoid long lines, so please 248 do so. Note that in standard C you can split long strings into pieces 249 separated by white space. For example, 250 "this is an awfully long string" can be written as "this is an " 251 "awfully long string". 252 253* Use only standard C for your backend. ISO C99 support will be enabled 254 if supported by the compiler detected by configure. 255 256* Please do not depend on compiler specific features or, if you do, make 257 the dependency conditional so other compilers will still be able to 258 compile the files. In particular: 259 260 - do not declare dynamically sized automatic arrays; instead, 261 use alloca() after including "../include/lalloca.h". For example: 262 263 void 264 func (int n) 265 { 266 char buf[n]; 267 } 268 269 should be re-written as: 270 271 #ifdef _AIX 272 # include "../include/lalloca.h" /* MUST come first for AIX! */ 273 #endif 274 275 #include "../include/sane/config.h" 276 #include "../include/lalloca.h" 277 : 278 void 279 func (int n) 280 { 281 char *buf = alloca (n); 282 } 283 - Don't use any #pragma directives---they're completely 284 compiler-dependent. 285 286* If you use headers or libraries that may not be available on all systems, 287 write a check for configure.ac and include it conditionally. If your backend 288 depends on these libraries or headers, compile the backend only if they are 289 available (see pint for an example). 290 291* Use #include ".../include/sane/..." to include the sane header files 292 instead of #include <sane/...>. Otherwise problems with different installed 293 SANE versions may occur. Also this makes clear that the local files are used. 294 295* Don't forget to #include ".../include/sane/config.h" in your backend before 296 any other includes. This must be done for any .c file that generates its own 297 object file. If you use lalloca.h see above for the correct includes. 298 299* Include sanei_backend.h after the other includes. 300 301* It's no longer necessary to #define PATH_MAX (now in sanei_backend.h). 302 If you define it, do so *after* the system includes. 303 304* Please use sanei functions whenever possible (e.g. 305 sanei_config_read()). This makes porting to other os/platforms much 306 easier. Most of these functions are documented in their respective 307 header files in include/sane/sanei_*.h. For most of them there is also 308 documentation in doxygen format: http://www.sane-project.org/sanei/. These 309 HTML pages can be generated by calling "doxygen sanei-doxygen.conf" in 310 the doc/ directory. 311 312* Initialize global variables explicitly in sane_init. Keep in mind that 313 sane_init can be called more than once (if sane_exit is called every time 314 after sane_init). Therefore don't depend on automatic initialization to 315 0 / NULL. 316 317* Do make sure that your code is byte-order independent. This is 318 particularly important for networking-related code and when dealing 319 with non-textual data files. 320 321* Don't use printf, fprintf or perror to output debug or error messages. 322 Use the DBG macro instead. If your backend can't detect a scanner for 323 whatever reason it shouldn't output anything as long as 324 SANE_DEBUG_BACKENDNAME isn't set. So don't use DBG(0, ...) in this case. 325 326* Please do not assume that `size_t' is `unsigned int'. On some 327 systems, it's `unsigned long' and the size of this type may be 328 bigger than that of an int (this is true for practically any of the 329 64-bit systems). To print a variable of type size_t portably, cast 330 the variable to u_long and print it with the %lu specifier. E.g.: 331 332 size_t len; 333 334 DBG(3, "len=%lu\n", (u_long) len); 335 336* Please do not assume that `void *' has the same size as `int'. On some 337 systems, it's `long' and the size of this type may be bigger than that of 338 an int (this is true for practically any of the 64-bit systems). Where this 339 comes up is with opaque handles. For example: 340 341 int OpaqueHandle; 342 MyScanner *s = (MyScanner *)OpaqueHandle; 343 344 will FAIL on most 64 bit systems. Please use `void *' or better 345 `SANE_Handle'. 346 347* Don't use exit() in your backend. You will exit the whole program, not only 348 your backend. 349 350* If you use wait() or waitpid() in your backend, check its return value. This 351 is important, if the status value is checked for e.g. WIFEXITED after the 352 call of wait() or waitpid(). Both functions may fail if the frontend already 353 did a wait for the children. 354 355* Please try to avoid compilation warnings. At least with "--disable-warnings" 356 there shouldn't be warnings when compiling backends. It's not necessary to 357 fix every "unused parameter" warning but take care that no warnings pointing 358 to really existing problems or ambiguities are missed. Some programming 359 techniques generating warnings on gcc may lead to errors on other systems. 360 361* To support translation of SANE options, please mark the descriptions (desc) 362 and title of options with SANE_I18N() and add all files using SANE_I18N() to 363 po/POTFILES. See po/README for details. 364 365* Please check for TL_X < BR_X and TL_Y < BR_Y to avoid segfaults or even 366 scanner damage. This should NOT be done in sane_control_option, it should 367 be possible to temporary set TL_X > BR_X or TL_ > BR, otherwise it is hard 368 for a frontend to set the correct values. 369 370 371TESTING 372------- 373 374* Please test a backend with "scanimage -T" (plus other options, 375 as appropriate/necessary) as this will make sure that sane_read() 376 always returns the correct amount of data etc. 377 378* You can also test a backend with tstbackend. tstbackend is not 379 compiled nor installed by default. To do that, cd into frontend and 380 run "make tstbackend". 381 382* Please test a backend not just with scanimage and xscanimage 383 (+ other frontends), but also with saned. Based on past experience, 384 it is often the case that remote scanning can uncover subtle bugs. 385 Note that you don't have to use two different machines to test "remote" 386 scanning---you can use one and the same machine to test a backend via saned 387 (just be sure to enable the "net" backend in dll.conf and follow the 388 steps described in saned(8)). 389 390* Please test on every available platform/os. Even if no scanner is attached 391 to this system, test compilation and running scanimage. If you don't have 392 access to other platforms, ask sane-devel. 393 394* Please make sure that all global symbols exported from a SANE backend start 395 with the prefix "sane" or "sanei" to avoid clashes with exported symbols 396 of other backends. Only symbols mentioned in the SANE standard should start 397 with "sane_*". Make sure, the sanei_* symbols are unique, e.g. by using 398 sanei_backendname_*. Only export symbols that are absolutely necessary. 399 You can verify this by running GNU "nm" on the static library. For example: 400 401 nm -g backend/.libs/libsane-hp.a 402 403 would list all global symbols in the HP backend. 404 405 "./configure; make; make libcheck" in the sane-backends root directory 406 will name all backend libraries, that contain "illegal" symbols. 407 408DOCUMENTATION 409------------- 410 411* Even if you haven't written a man-page for your backend yet, you *must* 412 create a .desc file which describes it. Anytime you submit source code for 413 your backend, you should include an update to the .desc file which reflects 414 the new state of the backend. The .desc files are used to create the HTML 415 lists of supported devices. These lists are updated automatically when you 416 change a .desc file in git. See e.g. 417 http://www.sane-project.org/lists/sane-mfgs-cvs.html for the results. 418 419* The .desc files are located in the directories "doc/descriptions" and 420 "doc/descriptions-external" (for included and external backends). 421 422* "doc/descriptions.txt" describes the format of the ".desc" files. There is 423 also a template for new .desc files: "template.desc". The format of the 424 files in the two directories is very similar. If you'd like to try parsing 425 your creation to recreate the sane-backends webpages, cd into "tools/" and 426 enter "make sane-desc". You can either use sane-desc directly (try 427 "./sane-desc -h") or use "make html-pages" in "doc/". 428 429* For external backends, you don't need to supply :manpage and :version. The 430 manpage link won't work anyway and version will be outdated soon. 431 432* When your backend is included in the SANE distribution, add an entry to 433 doc/sane.man and AUTHORS. The sane.man entry should point 434 to your documentation (man-page, website, readme). Also move your .desc 435 file from "doc/descriptions-external" to "doc/descriptions" and update 436 them. 437 438* In your manual page (backend.man), use @LIBDIR@ and the other macros for 439 path names to the libraries, config files and documentation. Don't use fixed 440 paths as they will be wrong if SANE is installed with a different prefix 441 (e.g. /usr instead of /usr/local). 442 443* If you want to include READMEs, HTML files or other documentation, please 444 create your own directory (doc/backendname) and store your files in this 445 directory. If you only have a manual page a subdirectory isn't necessary. 446 447* Please keep your manpages and .desc files up-to-date especially regarding 448 version numbers. 449 450 451CHECKLIST: SUBMITTING A NEW BACKEND 452----------------------------------- 453 454In sane-backends/ 455* Add the author(s) name(s) to AUTHORS 456* Correct any related entries in the bug-tracking system 457 458In sane-backends/backend/ 459* Use the command "indent -gnu" to reformat your code according to the 460 standard. 461* Add the backend name to dll.conf 462* Check that the SANE license is in the backend source files. 463* Add the source file names and the .conf file 464 to BACKEND_CONFS in Makefile.am 465 466In sane-backends/doc/ 467* Add an entry for the man page in sane.man 468* Add the man page file in doc/Makefile.am 469* Move the description file from descriptions-external/ to doc/descriptions/ 470* Check that the description file is correct: "cd doc; make html-pages" and 471 check the html pages result with a browser. 472* Check that the backend version is the same in the source and in the 473 description file. 474 475In sane-backends/po/ 476* Add all files using SANE_I18N() to po/POTFILES 477 478 479INCLUDING INTO git 480------------------ 481 482* If you want to include your backend into SANE's git tree use the latest git 483 to make patches. Check the mailing list and the bug-tracking system for 484 information about bugs to avoid. 485 486* If your backend isn't included yet in the SANE's git tree, write an email to 487 the SANE mailing list (sane-devel) and ask for inclusion. Usually one 488 of the developers will check the backend for common mistakes and test 489 compilation. If everything is ok the backend will be added to the git tree. 490