Version-Management.html 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176
  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.5 Version Management</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.5 Version Management">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.5 Version Management">
  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="Version-Management"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="Execution-Modes.html#Execution-Modes" title="Previous section in reading order"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="Error-Reporting.html#Error-Reporting" 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="Library-Reference.html#Library-Reference" 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="Version-Management-1"></a>
  58. <h2 class="section">3.5 Version Management</h2>
  59. <p>The <code>avram</code> library is designed to support any number of backward
  60. <a name="index-versions-1"></a>
  61. compatibility modes with itself, by way of some functions declared in
  62. &lsquo;<tt>vman.h</tt>&rsquo;. The assumption is that the library will go through a
  63. sequence of revisions during its life, each being identified by a unique
  64. number. In the event of a fork in the project, each branch will
  65. attempt to maintain compatibility at least with its own ancestors.
  66. </p>
  67. <dl>
  68. <dt><a name="index-avm_005fset_005fversion"></a><u>Function:</u> void <b>avm_set_version</b><i> (char *<var>number</var>)</i></dt>
  69. <dd><p>This function can be used to delay the demise of a client program that
  70. uses the library but is not updated very often. The argument is a null
  71. terminated string representing a version number, such as <code>&quot;0.13.0&quot;</code>.
  72. </p>
  73. <p>A call to this function requests that all library functions revert to
  74. their behavior as of that version in any cases where the current
  75. behavior is incompatible with it. It will also cause virtual code
  76. applications evaluated with <code>avm_apply</code> to detect a version number
  77. equal to the given one rather than the current one. (See <a href="Version.html#Version">Version</a>.)
  78. </p>
  79. <p>The program will exit with an internal error message if any function in
  80. the library has already interrogated the version number before this
  81. function is called, or if it is passed a null pointer. This problem can
  82. be avoided by calling it prior to any of the <code>avm_initialize</code>
  83. functions with a valid address. The program will exit with the message
  84. </p>
  85. <table><tr><td>&nbsp;</td><td><pre class="display"><code><var>program-name</var>: multiple version specifications</code>
  86. </pre></td></tr></table>
  87. <p>if this function is called more than once, even with the same number.
  88. If the number is not recognized as a present or past version, or is so
  89. old that it is no longer supported, the program will exit with this
  90. message.
  91. </p>
  92. <table><tr><td>&nbsp;</td><td><pre class="display"><code>avram: can't emulate version <var>number</var></code>
  93. </pre></td></tr></table>
  94. <p>Client programs that are built to last should allow the version number
  95. to be specified as an option by the user, and let virtual code
  96. applications that they execute take care of their own backward
  97. compatibility problems. This strategy will at least guard against
  98. changes in the virtual machine specification and other changes that do
  99. not affect the library API.
  100. </p></dd></dl>
  101. <dl>
  102. <dt><a name="index-avm_005fprior_005fto_005fversion"></a><u>Function:</u> int <b>avm_prior_to_version</b><i> (char *<var>number</var>)</i></dt>
  103. <dd><p>This function takes the address of a null terminated string representing
  104. a version number as an argument, such as <code>&quot;0.13.0&quot;</code>, and returns a
  105. non-zero value if the version currently being emulated predates it.
  106. </p>
  107. <p>If no call has been made to <code>avm_set_version</code> prior to the call to
  108. this function, the current version is assumed, and subsequent calls to
  109. <code>avm_set_version</code> will cause an internal error.
  110. </p>
  111. <p>The intended use for this function would be by a maintainer of the
  112. library introducing an enhancement that will not be backward compatible,
  113. who doesn&rsquo;t wish to break existing client programs and virtual code
  114. applications. For example, if a version <code>1.0</code> is developed at some
  115. time in the distant future, and it incorporates a previously unexpected
  116. way of doing something, code similar to the following could be used to
  117. maintain backward compatibility.
  118. </p>
  119. <table><tr><td>&nbsp;</td><td><pre class="example">if (avm_prior_to_version(&quot;1.0&quot;))
  120. {
  121. /* do it the 0.x way */
  122. }
  123. else
  124. {
  125. /* do it the 1.0-and-later way */
  126. }
  127. </pre></td></tr></table>
  128. <p>This function will cause an internal error if the parameter does not
  129. match any known past or present version number, or if it is a null pointer.
  130. </p></dd></dl>
  131. <dl>
  132. <dt><a name="index-avm_005fversion"></a><u>Function:</u> char* <b>avm_version</b><i> ()</i></dt>
  133. <dd><p>This function returns the number of the version currently being emulated
  134. as the address of a null terminated string. The string whose address is
  135. returned should not be modified by the caller.
  136. </p>
  137. <p>If no call has been made to <code>avm_set_version</code> prior to the call to
  138. this function, the current version is assumed, and subsequent calls to
  139. <code>avm_set_version</code> will cause an internal error.
  140. </p></dd></dl>
  141. <hr size="1">
  142. <table cellpadding="1" cellspacing="1" border="0">
  143. <tr><td valign="middle" align="left">[<a href="Execution-Modes.html#Execution-Modes" title="Previous section in reading order"> &lt; </a>]</td>
  144. <td valign="middle" align="left">[<a href="Error-Reporting.html#Error-Reporting" title="Next section in reading order"> &gt; </a>]</td>
  145. <td valign="middle" align="left"> &nbsp; </td>
  146. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  147. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Up section"> Up </a>]</td>
  148. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  149. <td valign="middle" align="left"> &nbsp; </td>
  150. <td valign="middle" align="left"> &nbsp; </td>
  151. <td valign="middle" align="left"> &nbsp; </td>
  152. <td valign="middle" align="left"> &nbsp; </td>
  153. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  154. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  155. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  156. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  157. </tr></table>
  158. <p>
  159. <font size="-1">
  160. This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  161. </font>
  162. <br>
  163. </p>
  164. </body>
  165. </html>