Introduction to the Pike Module Development Kit

updated May 16, 2006

About

This document describes the basic procedures and requirements for developing modules for the Pike programming language. The tools and procedures contained in this document should be considered the official supported methods. Pike modules may consist of a combination of Pike components and compiled shared libraries, usually written in C or the CMOD format. This document also lays out the basic requirements for submitting a module to the currently unnamed Pike module repository (or simply “the repository”). This document assumes that the reader has a working knowledge of the Pike language, as well as a basic understanding of the standard development tools described below. This document should not be considered the final authority for building modules; for assistance or clarification, please refer to one of the resources listed in the final section of this document, “Further reading and assistance.”

Requirements

This procedure was developed for and using UNIX based operating systems. This procedure does not currently function for developers targeting the NT operating system.

The basic requirements for developing Pike modules are relatively simple. These include (in addition to the tools commonly supplied with an end user UNIX):

C compiler, such as gcc
autoconf 2.13 or 2.52
Pike version 7.5 or higher

Optional components include:

automake
autoheader

It should be noted that the version of autoconf used is significant. Versions of autoconf greater than 2.52 currently do not work. The recommended version for developing with Pike is 2.13. Modules that are properly prepared for distribution do not require the end user to have installed autoconf, automake or autoheader.

The Pike Module tool

Pike versions 7.5 and higher have a built in tool that performs module building. When given a module distribution written using these procedures, the module tool will perform all of the steps required to build and install the module. The tool also performs a number of other useful query functions for determining system dependent paths for directories such as the module path.

Usage:

pike -x module [arguments] [make args]

When the tool is run from the module source directory, without any arguments, the tool will determine what steps need to be performed in order to build the module. The steps that the module may perform include running autoconf, automake, autoheader, configure, and make. You may pass additional arguments to the configure script by adding the argument CONFIGUREARGS=”my args to configure”. The default target for modules should be to build the module. Additionally, you may instruct the module tool to perform any of a number of make targets, including (but not limited to):

install	installs the module in the system module directory. Note that the module must already have been built for this target to perform properly.
install_local	installs the module in the user's module directory, usually `$HOME/lib/pike/modules`. See the note for the "install" target for information about prerequisite handling.
clean	removes most of the byproduct files from the make process.
spotless	removes all of the build byproduct files.
dump_module	precompiles (dumps) the installed module for faster startup time
dump_local_module	precompiles (dumps) the local user's installed module for faster startup time
modref	builds the reference documentation for the module by extracting it from the module source. The system module reference is then rebuilt to include the new module documentaion.
module_modref	builds the reference documentation for the module by extracting it from the module source. The resulting modref is then placed in the `modref/` directory in the module build directory. This is used to provide module documentation from the module repository website.
verify	generates a testsuite, if any tests are defined, then runs the test.
verbose_verify	same as verify, but more output is generated from the tests.

Additional usage information may be found by running:

pike -x module --help

A bare-bones module

Pike modules can consist of zero or more pike language files, plus a shared object built from one or more c language files, of which any or none may be precompiled from CMOD files. In addition to these source files, a pike module distribution must include a minimum of the following files in order to compile and install properly:

configure.in

This is the input to autoconf, and is used to configure the source and build environment for the particular system the module is being built on. At the very least, this file must contain the following lines:

AC_INIT(module.pmod.in)

AC_MODULE_INIT()

AC_OUTPUT(Makefile)

The first line initializes autoconf, and checks for the file or directory provided as an argument in order to verify that it's being run from the right location. The argument should be a file in the same directory; in this example, it points to a directory of Pike code that the module will be built from. Note that this particular file may not exist, especially if you're developing a module that is C only, so try to pick a file that is unique to your module.

The second line initializes the Pike module build system. This macro takes no arguments.

The third line will generate the Makefile from the input file, Makefile.in, expanding any autoconf expansions that have been defined. You may add any tests or valid autoconf code between the second and third lines as may be necessary for your module to configure. Additionally, you may also have autoconf generate more files than have been demonstrated here.

Makefile.in

This is the shell for the Makefile that will be used to build your module. This file may be modified to include a number of additional rules, but at a minimum, must contan the following content:

@make_variables@

VPATH=@srcdir@

OBJS=

AUTODOC_SRC_IN=

MODDIR=Protocols.pmod/BEEP.pmod/

MODNAME=client

MODULE_PMOD_IN=module.pmod.in

MODULE_LDFLAGS=@LDFLAGS@ @LIBS@

CONFIG_HEADERS=@CONFIG_HEADERS@

@dynamic_module_makefile@

@dependencies@

Important pieces of this makefile include:

MODDIR

This variable may be left empty for a root level module, or it may point to the place in the module filesystem where this module should be installed. If not empty, it must end with a / in order for the module to be installed in the proper location.

IMPORTANT NOTE: not including a trailing forward-slash (/) will cause the module to be installed in an incorrect location.

MODNAME

This variable is the name of this module, and may not be empty. If MODDIR is empty, the module will be installed as $(MODNAME).pmod in the root of the module tree, or as $(MODDIR)$(MODNAME) if MODDIR is defined.

OBJS

This variable may point to one or more object files that the shared objet portion of the module will be built from. Rules exist to compile .c files and .cmod files into the appropriate .o file. If this variable is empty, the shared object (.so) file will not be created. The shared object file will be installed as ___$(MODNAME).so in the appropriate place in the pike tree.

AUTODOC_SRC_IN

This may contain a list of files containing AutoDoc markup. Used for specifiying C files that documentation should be searched for markup. CMOD files should not be specified on this line, but rather the compiled C files (change the extension from .cmod to .c to determine the files to specify for this variable.

MODULE_PMOD_IN

This should be a directory that contains the pike code for the module. This directory may consist of a directory tree of pike code, and will be installed as $(MODDIR)(MODNAME).pmod. The contents of the tree will be run through a substitution, with instances of @module@ being replaced with the final name of the .so file. If this variable is empty and a shared object file is being built, a stub will be generated which inherits the .so file, placing the module in its proper location in the Pike module tree.

Other Makefile Variables

The following Makefile variables are less commonly used, but are fully supported by the module build system.

MODULE_ARCHIVES

MODULE_SUBDIRS

MODULE_LDFLAGS

MODULE_CPPFLAGS

MODULE_MAKE_FLAGS

CONFIG_HEADERS

MODULE_CLEAN_EXTRA

MODULE_SPOTLESS_EXTRA

Examples:

To build a module Protocols.BEEP.client, from a source tree of pike files stored in a directory called module.pmod.in, we would use the following variable definitions:

MODDIR = Protocols.pmod/BEEP.pmod/

MODNAME = client

MODULE_PMOD_IN = module.pmod.in

This would result in the pike module input directory module.pmod.in being substituted and stored in Protocols.pmod/BEEP.pmod/client.pmod, and if we supplied a number of object files in OBJS, they would be compiled and installed as a .so file called Protocols.pmod/BEEP.pmod/___client.so. If we were using a shared object file, we should also include in our Pike language module (presumably in the file $(MODULE_PMOD_IN)/module.pmod) code the following line:

inherit @module@;

If you are building a module strictly from compiled code, this procedure still stands, however if you do not provide $(MODULE_PMOD_IN), a minimal stub will be generated that will inherit the .so file to the module's final name in the Pike module namespace.

Also, it is important to note that MODDIR is a relative path ending with a slash, and MODNAME is not (that is, it should not end with .pmod).

Source Components

Pike modules may be developed using any combination of C, CMOD (the preprocessed version of C used for easing Pike module development), C++ or Pike.

Pike language components (either a single pike file, or a directory of Pike language files are specified on the MODULE_PMOD_IN makefile variable.

C and other compiled components are specified as a series of object files specified in the makefile variable OBJS (for instance, if the source file is called module.c or module.cmod, then the file specified should be module.o).

If you need to build a library which the module will link, you can use the MODULE_ARCHIVES makefile variable.

All publicly available methods and properties made available through the module should be documented using the pike AutoDoc system. Discussion of AutoDoc is beyond the scope of this document, however additional information is available in the refdoc directory in the Pike source distribution.

Optional components

testsuite.in

The optional testsuite code is provided in this file. The testsuite generator uses M4, so the syntax of this file may be a bit strange if you're not used to working with M4. An example of a minimal testsuite looks like this:

test_true(functionp(HelloWorld.run))

This sample code does one thing: it tests for the the code functionp(Protocols.BEEP.client.run) to be true.

More information about the testsuite generator and the syntax of testsuites may be found by examining the testsuite.in files within the Pike source tree or by reviewing the Testsuites chapter of the Pike Reference Manual.

Preparing a module for distribution

A module may be prepared for distribution (and ultimate submission to the Pike module repository) by performing the following tasks:

Properly naming the module build directory.
Verify that the module will build successfully.
Verify thaat the module documentation will build properly for end users.
Create metadata files (these files, while optional are highly recommended)
Adding the required information fields to the module
Creating the configure script
Clean the build directory tree

Please note that these guidelines are important to adhere to. Many of these guidelines exist to allow automated installation of modules, which is an important feature for end users. In order to promote the proper distribution of modules, the module repository will refuse to accept modules that are not packaged using these steps.