# Build System Plug-ins

The build system uses plug-ins to perform actions on modules. Which plug-in is used is based on the module type as defined in the BIF file, or by locally overriding it in the module.

All plug-ins need to be derived from the class 'Collate', located in the build system directory in the file 'collate.py'. This class provides the common interface used to invoke the plug-in:

    class Collate:
        def set_output_func(self, output_func)
        def set_error_func(self, error_func)
        def output(self, text)
        def error(self, text)
        def run(self)

Python does not allow non-virtual methods in classes, so keep in mind the only method you are meant to override is 'run'. The output and error methods are used for printing standard output and standard error, and the 'set_..' methods are used only by the build system's plug-in loader to re-direct the output from the plug-in. In addition to these methods, the Collate class is also initialized with the 'module' member class, which is a class containing all the information from the parsed module section in the BIF file, and the 'settings' member, which is a hash table of all the settings the build system was invoked with.

The build system retrieves plug-ins via it's plug-in loader, 'plugin.py', in the build system directory. Built-in plug-ins, like the 'Compile' class, are handled specially. Other plug-ins are loaded by trying to load a function called 'get_collate_class' from the file 'Buildfil' in module directory. This is how the collation of a module is overridden locally. The Python function 'get_collate_class' should return the Collate-derived class the build system should use for building in that subdirectory.

Here is an example of a simple build system plug-in that does nothing except print out the module name and the system's platform name:

    ## EXAMPLE PLUG-IN
    import os, sys, string, collate

    ## derived class from the build system's Install class, the action
    ## class used by the build system to create installers

    class ExamplePlugin(collate.Collate):
        def run(self):
            self.output('I am %s at %s' % (self.module.name, self.my_platform()))

        def my_platform(self):
            return 'UNKNOWN'

    class UNIXExamplePlugin(ExamplePlugin):
        def my_platform(self):
            return 'UNIX'

    class WindowsExamplePlugin(ExamplePlugin):
        def my_platform(self):
            return 'WINDOWS'

    class MacExamplePlugin(ExamplePlugin):
        def my_platform(self):
            return 'MACINTOSH'

    ## external class retriever used to load the installer class
    ## by the build system's plug-in loader
    def get_collate_class():
        if os.name == 'posix':
            return UNIXExamplePlugin
        elif os.name == 'nt' or os.name == 'dos':
            return WindowsExamplePlugin
        elif os.name == 'mac':
            return MacExamplePlugin

        return ExamplePlugin

### Nice Classes to Derive From

Two built-in subclasses of Collate are the 'Compile' class, and the 'Installer' class. The Compile class is the class used to compile most CVS modules, it is built into the build system and implemented in the 'compile.py' file. The 'Installer' class is the base class for installers.