3.9.2 Implementing new library functions

Adding more external libraries to avram is currently a manual procedure requiring the attention of a developer conversant with C. To support a new library called foobar, these steps need to be followed at a minimum.

• Create a new file called ‘foobar.h’ under the ‘avm/’ directory in the main source tree whose name doesn’t clash with any existing file names and preferably doesn’t induce any proper prefixes among them. This file should contain at least these function declarations.

  extern list avm_foobar_call (list function_name,list argument, int *fault); extern list avm_have_foobar_call (list function_name,int *fault); extern void avm_initialize_foobar (); extern void avm_count_foobar ();

  There should also be the usual preprocessor directives for ‘include’ files. The naming convention shown should be followed in anticipation of automated support for these operations in the future.

• Add ‘foobar.h’ to the list of other header files in ‘avm/Makefile.am’.
• Create a new file called ‘foobar.c’ under the ‘src/’ directory whose name doesn’t clash with any existing file names to store most of the library interface code. It can start out with stubs for the functions declared in ‘foobar.h’.
• Add ‘foobar.c’ to the list of other source files in ‘src/Makefile.am’
• Execute the following command in the main ‘avram-x.x.x’ source directory where the file ‘configure.in’ is found.

  aclocal \ && automake --gnu --add-missing \ && autoconf

  This command requires having automake and autoconf installed on your system.

• Make the following changes to ‘libfuns.c’.
  • Add the line #include<avm/foobar.h> after the other include directives.
  • Add the string "foobar" to the end of the array of libnames in avm_initialize_libfuns.
  • Add a call to avm_initialize_foobar to the body.
  • Add a call to avm_count_foobar to the body of avm_count_libfuns.
  • Add a case of the form

    case nn: return avm_foobar_call(function_name,argument,fault);

    after the last case in avm_library_call, being careful not to change the order, and using the same name as above in the file ‘foobar.h’.

  • Add a case of the form

    case nn: looked_up = avm_have_foobar_call(function_name,fault); break;

    after the last case in avm_have_library_call, being careful not to change the order, and using the same name as above in the file ‘foobar.h’.

• Edit ‘foobar.c’ and ‘foobar.h’ to suit, periodically compiling and testing by executing make.
• Package and install at will.

The functions shown above have the obvious interpretations, namely that avm_foobar_call evaluates a library function from the foobar library, and avm_have_foobar_call tests for a function’s availability. The latter should interpret wild cards as explained in Calling existing library functions, but should return only a list of strings for the matching function names rather than a list of pairs of strings, as the library name is redundant. The remaining functions are for static initialization and reclamation.

These functions should consist mainly of boilerplate code similar to the corresponding functions in any of the other library source files, which should be consulted as examples. The real work would be done by other functions called by them. These should be statically declared within the ‘.c’ source file and normally not listed in the ‘.h’ header file unless there is some reason to think they may be of more general use. Any externally visible functions should have names beginning with avm_ to avoid name clashes.

Some helpful hints are reported below for what they may be worth.

• The reason for doing this is to leverage off other people’s intelligence, so generally foobar.c should contain only glue code for library routines developed elsewhere with great skill rather than reinventing them in some home grown way.
• The best numerical software is often written by Fortran programmers. Linking to a Fortran library is no problem on GNU systems provided that all variables are passed by reference and all arrays are converted to column order (Type Conversions).
• Most C++ programmers have yet to reach a comparable standard, but C++ libraries can also be linked by running nm on the static library file to find out the real names of the functions and c++filt to find out which is which. However, there is no obvious workaround for the use of so called derived classes by C++ programmers to simulate passing functions as parameters.
• Anything worth using can probably be found in the Debian archive.
• Not all libraries are sensible candidates for interfaces to avram. Typical design flaws are
  • irrepressible debugging messages written to stderr or stdout that are unfit for end user consumption
  • deliberately crashing the application if malloc fails
  • opaque data types with undocumented storage requirements
  • opaque data types that would be useful to store persistently but have platform specific binary representations
  • heavily state dependent semantics
  • identifiers with clashing names
  • restrictive licenses

  Some of these misfeatures have workarounds as explained next in Working around library misfeatures, at least if there’s nothing else wrong with the library.

Those who support avram are always prepared to assist in the dissemination of worthwhile contributed library modules under terms compatible with GNU GENERAL PUBLIC LICENCE, and under separate copyrights if preferred. Contributed modules can be integrated into the official source tree provided that they meet the following additional guidelines to those above.

• source code documentation and indentation according to GNU coding standards (http://www.gnu.org/prep/standards)
• sufficient stability for a semi-annual release cycle
• no run-time or compile-time dependence on any non-free software, although dynamic loading and client/server interaction are acceptable
• portable or at least unbreakable configuration by appropriate use of autoconf macros and conditional defines
• little or no state dependence at the level of the virtual code interface (i.e., pure functions or something like them, except for random number generators and related applications)
• adequate documentation for a section in External Libraries

This document was generated on November 8, 2012 using texi2html 1.82.