Implementing-new-library-functions.html 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
  2. <html>
  3. <!-- Created on November 8, 2012 by texi2html 1.82
  4. texi2html was written by:
  5. Lionel Cons <[email protected]> (original author)
  6. Karl Berry <[email protected]>
  7. Olaf Bachmann <[email protected]>
  8. and many others.
  9. Maintained by: Many creative people.
  10. Send bugs and suggestions to <[email protected]>
  11. -->
  12. <head>
  13. <title>avram - a virtual machine code interpreter: 3.9.2 Implementing new library functions</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.9.2 Implementing new library functions">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.9.2 Implementing new library functions">
  16. <meta name="resource-type" content="document">
  17. <meta name="distribution" content="global">
  18. <meta name="Generator" content="texi2html 1.82">
  19. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  20. <style type="text/css">
  21. <!--
  22. a.summary-letter {text-decoration: none}
  23. blockquote.smallquotation {font-size: smaller}
  24. pre.display {font-family: serif}
  25. pre.format {font-family: serif}
  26. pre.menu-comment {font-family: serif}
  27. pre.menu-preformatted {font-family: serif}
  28. pre.smalldisplay {font-family: serif; font-size: smaller}
  29. pre.smallexample {font-size: smaller}
  30. pre.smallformat {font-family: serif; font-size: smaller}
  31. pre.smalllisp {font-size: smaller}
  32. span.roman {font-family:serif; font-weight:normal;}
  33. span.sansserif {font-family:sans-serif; font-weight:normal;}
  34. ul.toc {list-style: none}
  35. -->
  36. </style>
  37. </head>
  38. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  39. <a name="Implementing-new-library-functions"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <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>
  42. <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>
  43. <td valign="middle" align="left"> &nbsp; </td>
  44. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  45. <td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
  46. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  47. <td valign="middle" align="left"> &nbsp; </td>
  48. <td valign="middle" align="left"> &nbsp; </td>
  49. <td valign="middle" align="left"> &nbsp; </td>
  50. <td valign="middle" align="left"> &nbsp; </td>
  51. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  52. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  53. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  54. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  55. </tr></table>
  56. <hr size="1">
  57. <a name="Implementing-new-library-functions-1"></a>
  58. <h3 class="subsection">3.9.2 Implementing new library functions</h3>
  59. <p>Adding more external libraries to <code>avram</code> is currently a manual
  60. procedure requiring the attention of a developer conversant with C.
  61. To support a new library called <code>foobar</code>,
  62. these steps need to be followed at a minimum.
  63. </p>
  64. <ul>
  65. <li>
  66. Create a new file called &lsquo;<tt>foobar.h</tt>&rsquo; under the &lsquo;<tt>avm/</tt>&rsquo;
  67. directory in the main source tree whose name doesn&rsquo;t clash with any
  68. <a name="index-header-file"></a>
  69. <a name="index-library-interface-header-file"></a>
  70. existing file names and preferably doesn&rsquo;t induce any proper prefixes
  71. among them. This file should contain at least these function
  72. declarations.
  73. <table><tr><td>&nbsp;</td><td><pre class="example">
  74. extern list avm_foobar_call (list function_name,list argument,
  75. int *fault);
  76. extern list avm_have_foobar_call (list function_name,int *fault);
  77. extern void avm_initialize_foobar ();
  78. extern void avm_count_foobar ();
  79. </pre></td></tr></table>
  80. <p>There should also be the usual preprocessor directives for
  81. &lsquo;<tt>include</tt>&rsquo; files. The naming convention shown should be followed in
  82. anticipation of automated support for these operations in the future.
  83. </p></li><li>
  84. Add &lsquo;<tt>foobar.h</tt>&rsquo; to the list of other header files in
  85. &lsquo;<tt>avm/Makefile.am</tt>&rsquo;.
  86. </li><li>
  87. Create a new file called &lsquo;<tt>foobar.c</tt>&rsquo; under the &lsquo;<tt>src/</tt>&rsquo;
  88. directory whose name doesn&rsquo;t clash with any existing file names to
  89. <a name="index-library-interfac-source-file"></a>
  90. store most of the library interface code. It can start out with
  91. stubs for the functions declared in &lsquo;<tt>foobar.h</tt>&rsquo;.
  92. </li><li>
  93. Add &lsquo;<tt>foobar.c</tt>&rsquo; to the list of other source files in
  94. &lsquo;<tt>src/Makefile.am</tt>&rsquo;
  95. </li><li>
  96. Execute the following command in the main &lsquo;<tt>avram-x.x.x</tt>&rsquo;
  97. source directory where the file &lsquo;<tt>configure.in</tt>&rsquo; is found.
  98. <table><tr><td>&nbsp;</td><td><pre class="example">
  99. aclocal \
  100. &amp;&amp; automake --gnu --add-missing \
  101. &amp;&amp; autoconf
  102. </pre></td></tr></table>
  103. <p>This command requires having <code>automake</code> and
  104. <a name="index-automake"></a>
  105. <a name="index-autoconf"></a>
  106. <code>autoconf</code> installed on your system.
  107. </p></li><li>
  108. Make the following changes to &lsquo;<tt>libfuns.c</tt>&rsquo;.
  109. <ul>
  110. <li>
  111. Add the line <code>#include&lt;avm/foobar.h&gt;</code> after the
  112. <a name="index-include-directives"></a>
  113. other <code>include</code> directives.
  114. </li><li>
  115. Add the string <code>&quot;foobar&quot;</code> to the end of the array of
  116. <code>libnames</code> in <code>avm_initialize_libfuns</code>.
  117. </li><li>
  118. Add a call to <code>avm_initialize_foobar</code> to the body.
  119. </li><li>
  120. Add a call to <code>avm_count_foobar</code> to the body of
  121. <code>avm_count_libfuns</code>.
  122. </li><li>
  123. Add a case of the form
  124. <table><tr><td>&nbsp;</td><td><pre class="example">case nn:
  125. return avm_foobar_call(function_name,argument,fault);
  126. </pre></td></tr></table>
  127. <p>after the last case in <code>avm_library_call</code>, being
  128. careful not to change the order, and using the same
  129. name as above in the file &lsquo;<tt>foobar.h</tt>&rsquo;.
  130. </p></li><li>
  131. Add a case of the form
  132. <table><tr><td>&nbsp;</td><td><pre class="example">case nn:
  133. looked_up = avm_have_foobar_call(function_name,fault);
  134. break;
  135. </pre></td></tr></table>
  136. <p>after the last case in <code>avm_have_library_call</code>, being
  137. careful not to change the order, and using the same name
  138. as above in the file &lsquo;<tt>foobar.h</tt>&rsquo;.
  139. </p></li></ul>
  140. </li><li>
  141. Edit &lsquo;<tt>foobar.c</tt>&rsquo; and &lsquo;<tt>foobar.h</tt>&rsquo; to suit,
  142. periodically compiling and testing by executing <code>make</code>.
  143. </li><li>
  144. Package and install at will.
  145. </li></ul>
  146. <p>The functions shown above have the obvious interpretations, namely
  147. that <code>avm_foobar_call</code> evaluates a library function from the
  148. <code>foobar</code> library, and <code>avm_have_foobar_call</code> tests for a
  149. function&rsquo;s availability. The latter should interpret wild cards as
  150. explained in <a href="Calling-existing-library-functions.html#Calling-existing-library-functions">Calling existing library functions</a>, but should
  151. return only a list of strings for the matching function names rather
  152. than a list of pairs of strings, as the library name is redundant.
  153. The remaining functions are for static initialization and reclamation.
  154. </p>
  155. <p>These functions should consist mainly of boilerplate code similar to
  156. the corresponding functions in any of the other library source files,
  157. which should be consulted as examples. The real work would be done by
  158. other functions called by them. These should be statically declared
  159. within the &lsquo;<tt>.c</tt>&rsquo; source file and normally not listed in the
  160. &lsquo;<tt>.h</tt>&rsquo; header file unless there is some reason to think they may be
  161. of more general use. Any externally visible functions should have
  162. names beginning with <code>avm_</code> to avoid name clashes.
  163. </p>
  164. <p>Some helpful hints are reported below for what they may be worth.
  165. </p>
  166. <ul>
  167. <li>
  168. The reason for doing this is to leverage off other people&rsquo;s
  169. intelligence, so generally <code>foobar.c</code> should contain only glue
  170. code for library routines developed elsewhere with great skill rather
  171. than reinventing them in some home grown way.
  172. </li><li>
  173. The best numerical software is often written by Fortran
  174. <a name="index-Fortran-2"></a>
  175. programmers. Linking to a Fortran library is no problem on GNU systems
  176. provided that all variables are passed by reference and all arrays are
  177. converted to column order (<a href="Type-Conversions.html#Type-Conversions">Type Conversions</a>).
  178. </li><li>
  179. Most C++ programmers have yet to reach a comparable standard, but C++
  180. <a name="index-C_002b_002b-1"></a>
  181. libraries can also be linked by running <code>nm</code> on the static
  182. <a name="index-nm-utility"></a>
  183. library file to find out the real names of the functions and
  184. <a name="index-c_002b_002bfilt-utility"></a>
  185. <code>c++filt</code> to find out which is which. However, there
  186. is no obvious workaround for the use of so called derived classes
  187. by C++ programmers to simulate passing functions as parameters.
  188. </li><li>
  189. Anything worth using can probably be found in the Debian
  190. <a name="index-Debian"></a>
  191. archive.
  192. </li><li>
  193. Not all libraries are sensible candidates for interfaces to
  194. <code>avram</code>. Typical design flaws are
  195. <ul>
  196. <li>
  197. irrepressible debugging messages written to <code>stderr</code> or
  198. <code>stdout</code> that are unfit for end user consumption
  199. </li><li>
  200. deliberately crashing the application if <code>malloc</code> fails
  201. </li><li>
  202. opaque data types with undocumented storage requirements
  203. </li><li>
  204. opaque data types that would be useful to store persistently
  205. but have platform specific binary representations
  206. </li><li>
  207. heavily state dependent
  208. <a name="index-state-dependence"></a>
  209. semantics
  210. </li><li>
  211. identifiers with clashing names
  212. </li><li>
  213. restrictive
  214. <a name="index-licensing-restrictions"></a>
  215. licenses
  216. </li></ul>
  217. <p>Some of these misfeatures have workarounds as explained next in
  218. <a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures">Working around library misfeatures</a>, at least if there&rsquo;s
  219. nothing else wrong with the library.
  220. </p></li></ul>
  221. <p>Those who support <code>avram</code> are always prepared to assist in the
  222. dissemination of worthwhile contributed library modules under terms
  223. compatible with <a href="Copying.html#Copying">GNU GENERAL PUBLIC LICENCE</a>, and under separate copyrights if
  224. <a name="index-copyright"></a>
  225. preferred. Contributed modules can be integrated into the official
  226. source tree provided that they meet the following additional
  227. <a name="index-coding-standards"></a>
  228. guidelines to those above.
  229. </p>
  230. <ul>
  231. <li>
  232. source code documentation and indentation according to GNU coding
  233. standards (<a href="http://www.gnu.org/prep/standards">http://www.gnu.org/prep/standards</a>)
  234. </li><li>
  235. sufficient stability for a semi-annual release cycle
  236. </li><li>
  237. no run-time or compile-time dependence on any non-free software,
  238. although dynamic loading and client/server interaction are acceptable
  239. </li><li>
  240. portable or at least unbreakable configuration by appropriate use of
  241. <a name="index-autoconf-1"></a>
  242. <code>autoconf</code> macros and conditional defines
  243. </li><li>
  244. little or no state dependence at the level of the virtual code
  245. <a name="index-state-dependence-1"></a>
  246. interface (i.e., pure functions or something like them, except for
  247. <a name="index-random-number-generators"></a>
  248. random number generators and related applications)
  249. </li><li>
  250. adequate documentation for a section in <a href="External-Libraries.html#External-Libraries">External Libraries</a>
  251. </li></ul>
  252. <hr size="1">
  253. <table cellpadding="1" cellspacing="1" border="0">
  254. <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>
  255. <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>
  256. <td valign="middle" align="left"> &nbsp; </td>
  257. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  258. <td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
  259. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  260. <td valign="middle" align="left"> &nbsp; </td>
  261. <td valign="middle" align="left"> &nbsp; </td>
  262. <td valign="middle" align="left"> &nbsp; </td>
  263. <td valign="middle" align="left"> &nbsp; </td>
  264. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  265. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  266. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  267. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  268. </tr></table>
  269. <p>
  270. <font size="-1">
  271. This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  272. </font>
  273. <br>
  274. </p>
  275. </body>
  276. </html>