What is CMOD?

CMOD is the name of a simplified mechanism for writing extensions to the Pike programming language. CMOD files consist of C language code plus simplified function definition elements that handle many of the most tedious tasks associated with module development. A CMOD file is pre-processed by the CMOD precompiler resulting in a standard C file that is then compiled normally.

Tasks the CMOD compiler takes care of:

• Module initialization and shutdown
• Class definition
• Storage allocation for objects (including modules)
• Function definition and registration
• Variable definition and storage
• Function argument checking and passing
• Return value handling
• Polymorphic function overloading (function variants based on function type signature)

• Parenthesis must match, even within #if 0
• Not all Pike types are supported yet.
• No support for functions that take a variable number of arguments yet.
• RETURN; (void) doesn't work yet
• need a RETURN_NULL; or something.. RETURN 0; might work but may be confusing as RETURN x; will not work if x is zero.

In short, for most module applications, using CMOD can save you a large amount of time and effort, particularly in the area of avoiding bugs. Function bodies are written using standard C, so programming skills will transfer directly.

Sample module

A sample module that can be used as a starting point for further module development can be found at http://buoy.riverweb.com:8080/viewrep/cvs/pike_modules/SampleModule

This sample module represents a minimal CMOD module with a Pike module over-wrapper. The over-wrapper in this case is non-functional, and is included to show the necessary constants for providing module repository functionality.

Elements of a CMOD file

The following represents the basic structure of a CMOD file. We'll cover each element in turn afterward.

// PIKE INCLUDES MUST BE PRESENT FOR COMPILATION.
PIKECLASS fnord
    attributes;
{
  INHERIT bar
    attributes;
  CVAR int foo;
  PIKEVAR mapping m
    attributes;
  DECLARE_STORAGE; // optional
  PIKEFUN int function_name (int x, CTYPE char * foo)
   attribute;
   attribute value;
  {
     C code using 'x' and 'foo'.
      RETURN x;
  }
    INIT
   {
     // Object initialization code.
   }
   EXIT
   {
     // Object cleanup code.
   }
    GC_RECURSE
   {
     // Code to run under the gc recurse pass.
   }
   GC_CHECK
   {
     // Code to run under the gc check pass.
   }
   EXTRA
   {
     // Code for adding extra constants etc.
   }
    OPTIMIZE
   {
     // Code for optimizing calls that clone the class.
     // The node for the call is available in the variable n.
   }
 }

Multiple CMOD files in a single module

At a certain point, a module cannot be reasonably managed as a single source file. Typically, a module will be split into multiple classes, and it is often desirable to have each class be contained in a separate file. The Pike module build system will happily compile multiple CMOD files and link them into a single module shared object. However, a few steps must be taken in order for the resulting object to be functional.

Powered by PikeWiki2