txlyre
/
avram


			
							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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>foobar.h</tt>&rsquo; under the &lsquo;<tt>avm/</tt>&rsquo;
directory in the main source tree whose name doesn&rsquo;t clash with any
<a name="index-header-file"></a>
<a name="index-library-interface-header-file"></a>
existing file names and preferably doesn&rsquo;t induce any proper prefixes
among them. This file should contain at least these function
declarations.
<table><tr><td>&nbsp;</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
&lsquo;<tt>include</tt>&rsquo; files. The naming convention shown should be followed in
anticipation of automated support for these operations in the future.
</p></li><li>
Add &lsquo;<tt>foobar.h</tt>&rsquo; to the list of other header files in
&lsquo;<tt>avm/Makefile.am</tt>&rsquo;.
</li><li>
Create a new file called &lsquo;<tt>foobar.c</tt>&rsquo; under the &lsquo;<tt>src/</tt>&rsquo;
directory whose name doesn&rsquo;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 &lsquo;<tt>foobar.h</tt>&rsquo;.
</li><li>
Add &lsquo;<tt>foobar.c</tt>&rsquo; to the list of other source files in
&lsquo;<tt>src/Makefile.am</tt>&rsquo;
</li><li>
Execute the following command in the main &lsquo;<tt>avram-x.x.x</tt>&rsquo;
source directory where the file &lsquo;<tt>configure.in</tt>&rsquo; is found.
<table><tr><td>&nbsp;</td><td><pre class="example">
aclocal \
&amp;&amp; automake --gnu --add-missing \
&amp;&amp; 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 &lsquo;<tt>libfuns.c</tt>&rsquo;.

<ul>
<li>
Add the line <code>#include&lt;avm/foobar.h&gt;</code> after the
<a name="index-include-directives"></a>
other <code>include</code> directives.
</li><li>
Add the string <code>&quot;foobar&quot;</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>&nbsp;</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 &lsquo;<tt>foobar.h</tt>&rsquo;.
</p></li><li>
Add a case of the form
<table><tr><td>&nbsp;</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 &lsquo;<tt>foobar.h</tt>&rsquo;.
</p></li></ul>
</li><li>
Edit &lsquo;<tt>foobar.c</tt>&rsquo; and &lsquo;<tt>foobar.h</tt>&rsquo; 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&rsquo;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 &lsquo;<tt>.c</tt>&rsquo; source file and normally not listed in the
&lsquo;<tt>.h</tt>&rsquo; 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&rsquo;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&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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>