autodoc.git / traditional_manual / chapter_21.html

version» Context lines:

autodoc.git/traditional_manual/chapter_21.html:1:   <!doctype html><html><head><title>Pike Reference Manual</title>   <meta charset='utf-8'></head> - <body><dl><dt><h1 class='header'>21. Writing Pike Modules</h1></dt><dd><p> -  This chapter will discuss how to extend Pike by writing -  modules. There are two major ways to write modules, either they -  can be written in Pike, or they can be written in C. Generally, -  modules can be seen as a collection of pike programs and -  functions. This is, obviously, handy for grouping related programs -  and functions. -  </p><p> -  A pike module is actually a pike program which is cloned by the -  pike compiler during compilation of programs. This means that all -  lfuns that can be used in a pike program also can be used in a -  module. This is, for instance, useful for overloading the -  operators of a module to obtain a certain behaviour. Bear in mind -  that variables defined on a module-wide bases are shared among all -  clones of programs in the module. -  <span class='fixme'>FIXME: Explain difference between .pmod and .pike</span> -  </p><p> -  Pike searches for modules in the module path as defined during the -  compilation of a pike program. The module-path defaults to contain -  the directory where all standard pike modules are installed. This -  can be altered using -  <code>/master.CompatResolver()-&gt;add_module_path()</code> in a -  program or by letting the environment variable -  <b>PIKE_MODULE_PATH</b> contain a colon-separated list of -  directories to be searched for modules before looking at the -  default location. -  </p></dd> + <body><dl><dt><h1 class='header'>21. Backward Compatibility</h1></dt><dd><p>Pike is a language under active development. This can lead to +  incompatibilities between different versions of Pike. To alleviate +  this problem Pike has a backward compatibility layer.</p><p>The backward compatibility layer can be engaged in two ways; +  either by starting the Pike interpreter with the <tt>-V</tt> option, +  or by using the <tt>#pike</tt> preprocessor directive.</p><p>The backward compatibility layer affects both the compiler and the +  available modules.</p><p>Note that the backward compatibility layer does not necessarily +  compensate for all incompatibilities documented here, and that +  there may be other incompatibilities that have not been documented.</p><p>The remainder of this chapter describes the main incompatibilities +  between the various versions of Pike and the current version.</p></dd>   <dt><a name='21.1'></a> - <h2 class='header'>21.1. Writing Modules in Pike</h2></dt> - <dd><p> -  Writing modules in pike is by far the easiest way to extend -  pike. They are also useful for structuring a larger programming -  project into different source files. -  </p><p> -  There are two ways of create a pike module written in -  pike. Either create a file named as the module will be called -  with the extension <code class='expr'>.pmod</code> and place all program and -  function definitions in it. The other way, which usually is more -  flexible, is to create a directory named as the module with the -  extension <code class='expr'>.pmod</code> and place all program definitions -  (<code class='expr'>.pike</code>-files) within this directory. If a file called -  <code class='expr'>module.pmod</code> is placed in the directory the function and -  program definitions within it will be merged with the programs -  found in the directory. This file could, as an example, be used -  to specify functions residing in the module, while programs in -  the module are placed in <code class='expr'>.pike</code>-files. -  </p><p> -  Note that Pike modules must not use try to load files relative to -  __FILE__, since such code will break in Microsoft Windows. -  <span class='fixme'>FIXME: Explain why.</span> + <h2 class='header'>21.1. Pike 8.0</h2></dt> + <dd></dd> + <dt><a name='21.1.1'></a> + <h3 class='header'>21.1.1. Global Functions</h3></dt> + <dd></dd> + <dt><a name='21.1.2'></a> + <h3 class='header'>21.1.2. Modules</h3></dt> + <dd><p>The following modules and functions have moved, been renamed or +  been deleted: +  <table class='box'> + </table> +     </p></dd> -  + <dt><a name='21.1.3'></a> + <h3 class='header'>21.1.3. Compiler</h3></dt> + <dd></dd> + <dt><a name='21.1.4'></a> + <h3 class='header'>21.1.4. Runtime</h3></dt> + <dd></dd>   <dt><a name='21.2'></a> - <h2 class='header'>21.2. Writing Modules in C</h2></dt> - <dd><p><span class='fixme'>FIXME: To be written.</span></p></dd> + <h2 class='header'>21.2. Pike 7.8</h2></dt> + <dd></dd>   <dt><a name='21.2.1'></a> - <h3 class='header'>21.2.1. Practical details</h3></dt> - <dd><p>First of all your module needs a Makefile.in file. It need not be -  more complicated than the following example: - <pre> - # $Id$ - @make_variables@ - VPATH=@srcdir@:@srcdir@/../..:../.. - OBJS= - MODULE_LDFLAGS=@LDFLAGS@ @LIBS@ + <h3 class='header'>21.2.1. Global Functions</h3></dt> + <dd><p><code>decode_value()</code> used to be able to decode programs using +  the 'old style' program encoding.</p></dd> + <dt><a name='21.2.2'></a> + <h3 class='header'>21.2.2. Modules</h3></dt> + <dd><p>The SSL module API has had major changes since Pike 7.8.</p><p>The following modules and functions have moved, been renamed or +  been deleted: +  <table class='box'> + <tr><td><code>7.8::Gdbm.gdbm</code></td><td><code>Gdbm.DB</code></td></tr> + <tr><td><code>7.8::Locale.Charset</code></td><td><code>Charset</code></td></tr> + <tr><td><code>7.8::SSL.alert</code></td><td><code>SSL.Alert</code></td></tr> + <tr><td><code>7.8::SSL.connection</code> + +  <code>7.8::SSL.handshake</code></td><td><code>SSL.ClientConnection</code> + +  <code>SSL.ServerConnection</code></td></tr> + <tr><td><code>7.8::SSL.context</code></td><td><code>SSL.Context</code></td></tr> + <tr><td><code>7.8::SSL.packet</code></td><td><code>SSL.Packet</code></td></tr> + <tr><td><code>7.8::SSL.session</code></td><td><code>SSL.Session</code></td></tr> + <tr><td><code>7.8::SSL.sslfile</code></td><td><code>SSL.File</code></td></tr> + <tr><td><code>7.8::SSL.sslport</code></td><td><code>SSL.Port</code></td></tr> + <tr><td><code>7.8::SSL.state</code></td><td><code>SSL.State</code></td></tr> + <tr><td><code>7.8::Tools.PEM</code></td><td><code>Standards.PEM</code></td></tr> + <tr><td><code>7.8::Tools.X509</code></td><td><code>Standards.X509</code></td></tr> + <tr><td><code>7.8::Yabu.db</code></td><td><code>Yabu.DB</code></td></tr> + <tr><td><code>7.8::Yabu.table</code></td><td><code>Yabu.Table</code></td></tr> + <tr><td><code>7.8::_PGsql</code></td><td>(deleted)</td></tr> + <tr><td><code>7.8:_files</code></td><td><code>_Stdio</code></td></tr> + </table>    - CONFIG_HEADERS=@CONFIG_HEADERS@ -  - @dynamic_module_makefile@ - @dependencies@ - </pre></p><p>A few customizations must however be done. The <tt>OBJS</tt> variable should -  contain all the object files produced in your module. You should -  add to the <tt>MODULE_LDFLAGS</tt> variable all the needed <tt>-L&lt;libdir&gt; -R&lt;libdir&gt;</tt> -  options followed by all the needed <tt>-l&lt;lib&gt;</tt> options. If you want your -  module to always be linked statically, change <tt>@dynamic_module_makefile@</tt> -  to <tt>@static_module_makefile@</tt>. Normally you do not need to manually add -  any dependencies to Makefile.in.</p><p>There must be a testsuite.in file in the modules directory, even if it -  only is an empty file.</p><p>You should have a configure.in file for your module and it should test -  for all features that you need. Do not trust the global configure tests -  to do thing for you. Further, your configure.in should contain the line -  <tt>sinclude(../module_configuration.in)</tt>.</p><p>All C/C++ files should include <tt>"global.h"</tt> as the first included file. It -  is also good if they contain <tt>RCSID($Id$)</tt>.</p><p>When building your module for the first time you need to: -  <ol> - </ol></p></dd> +  </p></dd> + <dt><a name='21.2.3'></a> + <h3 class='header'>21.2.3. Compiler</h3></dt> + <dd><p>The compiler used to not complain about use of +  the keyword <tt>static</tt>.</p><p>The ancient syntax for arrays (<tt>string *</tt> was an alias for +  <tt>array(string)</tt>) used to be supported (but complained about), +  but has now been removed completely.</p></dd> + <dt><a name='21.2.4'></a> + <h3 class='header'>21.2.4. Build options</h3></dt> + <dd><p>The builtin security sandbox has been deprecated.</p><p>Compiling without support for bignums is no longer supported.</p><p>The (optional) support for facet classes has been removed.</p></dd>   <dt><a name='21.3'></a> - <h2 class='header'>21.3. Special Module Variables and functions</h2></dt> + <h2 class='header'>21.3. Pike 7.6 and earlier</h2></dt>   <dd></dd>   <dt><a name='21.3.1'></a> - <h3 class='header'>21.3.1. _module_value</h3></dt> - <dd><p> -  If <code class='expr'>_module_value</code> is non-zero it will be used as -  the value of the module. <code class='expr'>_module_value</code> has to be of -  a type which is indicable, ie. an object, mapping or -  multiset. -  </p></dd> - <dt><a name='21.3.2'></a> - <h3 class='header'>21.3.2. The indexing operator</h3></dt> - <dd><p> -  If a <code>lfun::`[]</code> is defined in a module it will be -  called when the module is indexed using the .-operator. -  </p></dd></dl></body></html> + <h3 class='header'>21.3.1. Deprecated</h3></dt> + <dd><p>The backward compatibility code for Pike 7.6 and earlier +  has been removed in Pike 8.2.</p></dd></dl></body></html>