123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
- <html>
- <!-- Created on December 10, 2012 by texi2html 1.82
- texi2html was written by:
- Lionel Cons <[email protected]> (original author)
- Karl Berry <[email protected]>
- Olaf Bachmann <[email protected]>
- and many others.
- Maintained by: Many creative people.
- Send bugs and suggestions to <[email protected]>
- -->
- <head>
- <title>avram - a virtual machine code interpreter: 3.9.2 Implementing new library functions</title>
- <meta name="description" content="avram - a virtual machine code interpreter: 3.9.2 Implementing new library functions">
- <meta name="keywords" content="avram - a virtual machine code interpreter: 3.9.2 Implementing new library functions">
- <meta name="resource-type" content="document">
- <meta name="distribution" content="global">
- <meta name="Generator" content="texi2html 1.82">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <style type="text/css">
- <!--
- a.summary-letter {text-decoration: none}
- blockquote.smallquotation {font-size: smaller}
- pre.display {font-family: serif}
- pre.format {font-family: serif}
- pre.menu-comment {font-family: serif}
- pre.menu-preformatted {font-family: serif}
- pre.smalldisplay {font-family: serif; font-size: smaller}
- pre.smallexample {font-size: smaller}
- pre.smallformat {font-family: serif; font-size: smaller}
- pre.smalllisp {font-size: smaller}
- span.roman {font-family:serif; font-weight:normal;}
- span.sansserif {font-family:sans-serif; font-weight:normal;}
- ul.toc {list-style: none}
- -->
- </style>
- </head>
- <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
- <a name="Implementing-new-library-functions"></a>
- <table cellpadding="1" cellspacing="1" border="0">
- <tr><td valign="middle" align="left">[<a href="Calling-existing-library-functions.html#Calling-existing-library-functions" title="Previous section in reading order"> < </a>]</td>
- <td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Next section in reading order"> > </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> << </a>]</td>
- <td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
- <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> >> </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
- <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
- <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
- <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
- </tr></table>
- <hr size="1">
- <a name="Implementing-new-library-functions-1"></a>
- <h3 class="subsection">3.9.2 Implementing new library functions</h3>
- <p>Adding more external libraries to <code>avram</code> is currently a manual
- procedure requiring the attention of a developer conversant with C.
- To support a new library called <code>foobar</code>,
- these steps need to be followed at a minimum.
- </p>
- <ul>
- <li>
- Create a new file called ‘<tt>foobar.h</tt>’ under the ‘<tt>avm/</tt>’
- directory in the main source tree whose name doesn’t clash with any
- <a name="index-header-file"></a>
- <a name="index-library-interface-header-file"></a>
- existing file names and preferably doesn’t induce any proper prefixes
- among them. This file should contain at least these function
- declarations.
- <table><tr><td> </td><td><pre class="example">
- 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 ();
- </pre></td></tr></table>
- <p>There should also be the usual preprocessor directives for
- ‘<tt>include</tt>’ files. The naming convention shown should be followed in
- anticipation of automated support for these operations in the future.
- </p></li><li>
- Add ‘<tt>foobar.h</tt>’ to the list of other header files in
- ‘<tt>avm/Makefile.am</tt>’.
- </li><li>
- Create a new file called ‘<tt>foobar.c</tt>’ under the ‘<tt>src/</tt>’
- directory whose name doesn’t clash with any existing file names to
- <a name="index-library-interfac-source-file"></a>
- store most of the library interface code. It can start out with
- stubs for the functions declared in ‘<tt>foobar.h</tt>’.
- </li><li>
- Add ‘<tt>foobar.c</tt>’ to the list of other source files in
- ‘<tt>src/Makefile.am</tt>’
- </li><li>
- Execute the following command in the main ‘<tt>avram-x.x.x</tt>’
- source directory where the file ‘<tt>configure.in</tt>’ is found.
- <table><tr><td> </td><td><pre class="example">
- aclocal \
- && automake --gnu --add-missing \
- && autoconf
- </pre></td></tr></table>
- <p>This command requires having <code>automake</code> and
- <a name="index-automake"></a>
- <a name="index-autoconf"></a>
- <code>autoconf</code> installed on your system.
- </p></li><li>
- Make the following changes to ‘<tt>libfuns.c</tt>’.
- <ul>
- <li>
- Add the line <code>#include<avm/foobar.h></code> after the
- <a name="index-include-directives"></a>
- other <code>include</code> directives.
- </li><li>
- Add the string <code>"foobar"</code> to the end of the array of
- <code>libnames</code> in <code>avm_initialize_libfuns</code>.
- </li><li>
- Add a call to <code>avm_initialize_foobar</code> to the body.
- </li><li>
- Add a call to <code>avm_count_foobar</code> to the body of
- <code>avm_count_libfuns</code>.
- </li><li>
- Add a case of the form
- <table><tr><td> </td><td><pre class="example">case nn:
- return avm_foobar_call(function_name,argument,fault);
- </pre></td></tr></table>
- <p>after the last case in <code>avm_library_call</code>, being
- careful not to change the order, and using the same
- name as above in the file ‘<tt>foobar.h</tt>’.
- </p></li><li>
- Add a case of the form
- <table><tr><td> </td><td><pre class="example">case nn:
- looked_up = avm_have_foobar_call(function_name,fault);
- break;
- </pre></td></tr></table>
- <p>after the last case in <code>avm_have_library_call</code>, being
- careful not to change the order, and using the same name
- as above in the file ‘<tt>foobar.h</tt>’.
- </p></li></ul>
- </li><li>
- Edit ‘<tt>foobar.c</tt>’ and ‘<tt>foobar.h</tt>’ to suit,
- periodically compiling and testing by executing <code>make</code>.
- </li><li>
- Package and install at will.
- </li></ul>
- <p>The functions shown above have the obvious interpretations, namely
- that <code>avm_foobar_call</code> evaluates a library function from the
- <code>foobar</code> library, and <code>avm_have_foobar_call</code> tests for a
- function’s availability. The latter should interpret wild cards as
- explained in <a href="Calling-existing-library-functions.html#Calling-existing-library-functions">Calling existing library functions</a>, 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.
- </p>
- <p>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 ‘<tt>.c</tt>’ source file and normally not listed in the
- ‘<tt>.h</tt>’ 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 <code>avm_</code> to avoid name clashes.
- </p>
- <p>Some helpful hints are reported below for what they may be worth.
- </p>
- <ul>
- <li>
- The reason for doing this is to leverage off other people’s
- intelligence, so generally <code>foobar.c</code> should contain only glue
- code for library routines developed elsewhere with great skill rather
- than reinventing them in some home grown way.
- </li><li>
- The best numerical software is often written by Fortran
- <a name="index-Fortran-2"></a>
- 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 (<a href="Type-Conversions.html#Type-Conversions">Type Conversions</a>).
- </li><li>
- Most C++ programmers have yet to reach a comparable standard, but C++
- <a name="index-C_002b_002b-1"></a>
- libraries can also be linked by running <code>nm</code> on the static
- <a name="index-nm-utility"></a>
- library file to find out the real names of the functions and
- <a name="index-c_002b_002bfilt-utility"></a>
- <code>c++filt</code> 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.
- </li><li>
- Anything worth using can probably be found in the Debian
- <a name="index-Debian"></a>
- archive.
- </li><li>
- Not all libraries are sensible candidates for interfaces to
- <code>avram</code>. Typical design flaws are
- <ul>
- <li>
- irrepressible debugging messages written to <code>stderr</code> or
- <code>stdout</code> that are unfit for end user consumption
- </li><li>
- deliberately crashing the application if <code>malloc</code> fails
- </li><li>
- opaque data types with undocumented storage requirements
- </li><li>
- opaque data types that would be useful to store persistently
- but have platform specific binary representations
- </li><li>
- heavily state dependent
- <a name="index-state-dependence"></a>
- semantics
- </li><li>
- identifiers with clashing names
- </li><li>
- restrictive
- <a name="index-licensing-restrictions"></a>
- licenses
- </li></ul>
- <p>Some of these misfeatures have workarounds as explained next in
- <a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures">Working around library misfeatures</a>, at least if there’s
- nothing else wrong with the library.
- </p></li></ul>
- <p>Those who support <code>avram</code> are always prepared to assist in the
- dissemination of worthwhile contributed library modules under terms
- compatible with <a href="Copying.html#Copying">GNU GENERAL PUBLIC LICENCE</a>, and under separate copyrights if
- <a name="index-copyright"></a>
- preferred. Contributed modules can be integrated into the official
- source tree provided that they meet the following additional
- <a name="index-coding-standards"></a>
- guidelines to those above.
- </p>
- <ul>
- <li>
- source code documentation and indentation according to GNU coding
- standards (<a href="http://www.gnu.org/prep/standards">http://www.gnu.org/prep/standards</a>)
- </li><li>
- sufficient stability for a semi-annual release cycle
- </li><li>
- no run-time or compile-time dependence on any non-free software,
- although dynamic loading and client/server interaction are acceptable
- </li><li>
- portable or at least unbreakable configuration by appropriate use of
- <a name="index-autoconf-1"></a>
- <code>autoconf</code> macros and conditional defines
- </li><li>
- little or no state dependence at the level of the virtual code
- <a name="index-state-dependence-1"></a>
- interface (i.e., pure functions or something like them, except for
- <a name="index-random-number-generators"></a>
- random number generators and related applications)
- </li><li>
- adequate documentation for a section in <a href="External-Libraries.html#External-Libraries">External Libraries</a>
- </li></ul>
- <hr size="1">
- <table cellpadding="1" cellspacing="1" border="0">
- <tr><td valign="middle" align="left">[<a href="Calling-existing-library-functions.html#Calling-existing-library-functions" title="Previous section in reading order"> < </a>]</td>
- <td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Next section in reading order"> > </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> << </a>]</td>
- <td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
- <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> >> </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
- <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
- <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
- <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
- </tr></table>
- <p>
- <font size="-1">
- This document was generated on <i>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
- </font>
- <br>
- </p>
- </body>
- </html>
|