How to write a plugin

edited May 2011 in KLayout Development
Looking at the source code, I see that plugins are supported, and it appears that there are already several plugins included with KLayout.

I suspect you do not have documentation on writing plugins. That's fine. Can you just:

1. Confirm that KLayout really does support plugins.

2. Tell me which existing plugin would make a good model for me to study?


John McGehee
http://www.voom.net

Comments

  • edited May 2011

    Hallo John,

    "plugin" may not be the appropriate term, but KLayout internally features some interfaces that allow writing extensions that are dynamically loaded. Such extensions can be located in a shared object (a DLL on Windows) and KLayout internally makes use of these interfaces to achieve a certain level of modularity.

    It's somewhat questionable to have a plugin concept for an open source tool, because everybody is free to modify the source code to add new functionality. However, I personally like the idea of a modular system mainly because it leads to a partitioned design. Therefore, I tried to follow the plugin concept as far as possible myself, although the parts and not "pluggable" in that sense - they are basically compiled into the executable. Hence, I'd prefer to talk of "extensions" rather than plugins in the classical sense.

    Before I explain some details, let me issue a warning ahead: although extensions/plugins can be DLL's or shared objects, it's usually somewhat tedious to build them because they must be C++ class libraries. That is usually an issue because it requires both the main executable and the shared objects to be build with the same compiler, libraries and often compiler settings in order to be compatible. If you plan to write extensions for the Windows executable I published on the download page, you will need to compile them with exactly the same version of VC++ and Qt than I did or build klayout.exe yourself.

    However, I don't want to disencourage you. Here are some explanations that may be helpful:

    Basically there are

    • Ruby extensions (not based on the same mechanism than the other extensions, but mentioned here for completeness)
    • Readers and writers for new layout file formats
    • Editables: provides editable objects that support some basic functionality (selection, clipboard, transformation)
    • Drawing: adds new objects to the drawing
    • ViewService: adds new modes to the layout view and implements mouse event handling
    • Browsers: add generic non-modal (but exclusive) dialogs to the view (with the intention to implement browsers of every kind)

    Plugins are implemented starting with a declaration class. This declaration class is usually the factory for the actual plugin and specifies additional informations. The declaration is a singleton that is registered internally within a plugin repository.

    One basic responsibility of the declaration class is to specify the configuration options which will be stored in the configuration file. KLayout will use this information to initialize and dispatch the configuration information.

    Extensions may also register menu entries, which is done in some generic way using an abstract description of the menu items to create (rather that accessing the menu directly).

    To study the first two kind of extensions, layGDS2ReaderPlugin.cc is a good starting point. The reader plugin for GDS2 is declared with this line of code:

    static tl::RegisteredClass<lay::PluginDeclaration> plugin_decl (
      new lay::GDS2ReaderPluginDeclaration (), 10000, "GDS2Reader"
    );
    

    This file also demonstrates how to extend Ruby with specific options for GDS2:

    static gsi::Class<db::SaveLayoutOptions> gds2_writer_options ("SaveLayoutOptions", ...);
    

    gsi stands for "generic scripting interface" because it's not limited to Ruby alone. How that is done internally is a topic for some article by itself. Here, the "RBA::SaveLayoutOptions" class is extended by some methods and properties specific for GDS2.

    A good example for a browser extension is the instance browser (layBrowseInstancesForm.cc). The plugin is declared with this line of code:

    static tl::RegisteredClass<lay::PluginDeclaration> config_decl (
      new BrowseInstancesPluginDeclaration (), 11000, "BrowseInstancesPlugin"
    );
    

    A more complex example covering the Editables, Drawing and ViewService aspects of a plugin is the handling of rulers (annotations). The starting point of that implementation is the plugin declaration in antPlugin.cc:

    static tl::RegisteredClass<lay::PluginDeclaration> config_decl (new ant::PluginDeclaration (), 3000, "ant::Plugin");
    

    The ant namespace which covers all ruler related functionality is a good example for a self-contained extension - it is probably possible to compile all ant* files into a DLL or shared object and dynamically load them to the KLayout executable. This demonstrates the capabilities of the extension concept.

    Bascially I'd say that the extension interface, although not well documented, is the best way to implement add-ons of every kind without having to hack the internals of KLayout. The possibilities are limited by intention to keep the core architecture lean, but many applications can possibly be covered by the interfaces supported currently.

    Hopefully that helps for the beginning. There are a lot of details I have not mentioned yet, but looking at the code locations given above should reveal enough to be able to start with a simple extension.

    Best regards,

    Matthias

Sign In or Register to comment.