/*------------------------------------------------------------------------- * C-Pluff, a plug-in framework for C * Copyright 2007 Johannes Lehtinen * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included * in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. *-----------------------------------------------------------------------*/ /** * @page plugin Plug-in * * @section pluginOverview Overview * * Plug-in is the core element of an extensible application. The extensions and * also the main application logic are implemented as plug-ins. Plug-ins can * be developed, distributed and deployed independently, subject to * inter-plugin dependencies. Deploying a new plug-in does not require * recompilation or relinking if the operating system platform supports * required dynamic linking facilities. * * @section pluginStructure Structure * * A plug-in includes the following structural elements. * * - @ref pluginDescriptor "Plug-in descriptor" * - @ref pluginRuntime "Plug-in runtime library" * - @ref pluginData "Static plug-in data" * * @subsection pluginDescriptor Plug-in descriptor * * A plug-in descriptor is an XML document describing a plug-in. It includes * information about the contents of the plug-in, the features provided by * the plug-in, plug-in version information and static dependencies of the * plug-in. Most of the elements are optional. Most of the descriptor * information described here is available to software via * @ref cp_plugin_info_t structure. The plug-in descriptor must be located * in the plug-in directory as @c plugin.xml. * * The formal declaration of plug-in descriptor is available as * XML Schema Definition in @c plugin.xsd located in the top level source * directory. Currently there is no namespace associated with the plug-in * descriptor. Here is an example of a plug-in descriptor. Click element name * to jump into documentation for that element. * *

 * <plugin id="org.c-pluff.example" name="Example Plug-in" version="0.3.2" provider-name="Johannes Lehtinen">
 *     <backwards-compatibility abi="0.3" api="0.2.8"/>
 *     <requires>
 *         <c-pluff version="0.1"/>
 *         <import plugin="org.c-pluff.util" version="0.2"/>
 *         <import plugin="org.c-pluff.extra" optional="true"/> 
 *     </requires>
 *     <runtime library="libruntime" funcs="org_cpluff_example_funcs"/>
 *     <extension-point id="editors" name="Text Editors" schema="editors_schema.xsd"/>
 *     <extension-point id="url-families"/>
 *     <extension point="org.c-pluff.util.archivers" id="tar" name="Tar Archiver Support">
 *         <type random-access="false"/>
 *         <exec bin="tar"/>
 *     </extension>
 *     <extension point="org.c-pluff.example.editors>
 *         <editor name="Text Editor" runtime="org_cpluff_example_txteditor_runtime">
 *             <file-types>
 *                 <file-type mime-type="text/plain"/>
 *             </file-types>
 *         </editor>
 *     </extension>
 * </plugin>

* * A descriptor can also be much simpler, depending on the plug-in. * Here is an example of a minimal descriptor (of a useless plug-in). * *

 * <plugin id="org.c-pluff.useless"/>

* * @subsubsection pluginDescPlugin plugin * * This is the top level element of the plug-in descriptor. It can have * following attributes. * * - @a id: A mandatory unique identifier for the plug-in. Plug-in identifiers * should preferably be generated using a reversed DNS domain name as * prefix to prevent identifier conflicts. * - @a name: An optional human-readable name for the plug-in. * - @a version: An optional version number for the plug-in. Version numbers * are used for checking compatibility when resolving versioned plug-in * dependencies. See also information about * @ref pluginVersions "plug-in versions". * - @a provider-name: The name of the plug-in provider or author. Optional. * * This element can contain following elements. * * - @ref pluginDescPluginBWC "backwards-compatibility": Optional information about backwards * compatibility of this plug-in version. * - @ref pluginDescPluginRequires "requires": Information about static plug-in dependencies. Can be omitted * if the plug-in does not have static dependencies. * - @ref pluginDescPluginRuntime "runtime": Information about the plug-in runtime library. Can be omitted * if the plug-in does not have a runtime library but only data. * - @ref pluginDescPluginEP "extension-point": Information about extension points provided by the * plug-in. This element is repeated if there are multiple extension points * and omitted if there are none. * - @ref pluginDescPluginE "extension": Information about extensions provided by the plug-in. * This element is repeated if there are multiple extensions and omitted * if there are none. * * @subsubsection pluginDescPluginBWC backwards-compatibility * * This element includes optional information about the backwards compatibility * of this plug-in version. It can have following attributes. * * - @a abi: Backwards compatibility of the application binary interface (ABI) * of the plug-in. ABI includes any public symbols exported by the plug-in, * data structures associated with exported symbols and any extension points * provided by the plug-in. The ABI of the current plug-in version is * backwards compatible with any plug-in version from the version specified * here to the current version. This information is used when resolving * versioned plug-in dependencies. See also information about * @ref pluginVersions "plug-in versions". * - @a api: Backwards compatibility of the application programming interface * (API) of the plug-in. API compatibility means that source code developed * against one version of the plug-in also compiles against another version * of the plug-in. This information is not used by framework but it can be * used by a developer developing dependent plug-ins. * * These apply to plug-ins that provide header files and runtime libraries. * For example, a plug-in might export global functions to other plug-ins or it * might provide an extension point where an extension installed by other * plug-in must conform to data structures defined by the plug-in. * Both attributes are optional. * * @subsubsection pluginDescPluginRequires requires * * This element includes information about static plug-in dependencies. * It can be omitted if there are no dependencies. It can contain following * elements. * * - @ref pluginDescPluginReqCP "c-pluff": An optional version dependency * on the C-Pluff implementation. * - @ref pluginDescPluginReqImport "import": Declares a static dependency * on other plug-in. This element is repeated if there are multiple * dependencies and omitted if there are none. * * @subsubsection pluginDescPluginReqCP c-pluff * * This element declares a version dependency on the C-Pluff * implementation. It can be used to ensure that the plug-in is not loaded by * incompatible C-Pluff version. It has the following attribute. * * - @a version: The required version of the C-Pluff implementation. * This is used when resolving the plug-in. It is checked that the used * C-Pluff implementation is backwards compatible with the version specified * here when it comes to the application binary interface (ABI) of C-Pluff. * * @subsubsection pluginDescPluginReqImport import * * This element declares a static dependency on other plug-in. It must be * used when a plug-in uses global symbols or data from other plug-in or when * a plug-in uses an extension point defined by other plug-in or whenever some * other plug-in needs to be there for the plug-in to work. The framework takes * care of resolving and starting the dependencies whenever the plug-in is * resolved or started. * * This element can have following attributes. * * - @a plugin: The identifier of the imported plug-in. * - @a version: An optional version dependency on the imported plug-in. * The plug-in can be resolved only if the version of the imported plug-in * is backwards compatible with the version specified here when it comes * to the application binary interface (ABI) of the imported plug-in. * - @a optional: Is the import optional or not ("true" or "false"). Default is * false, a mandatory import. * An optional import behaves just like the mandatory import as long as the * imported plug-in is present. However, if it is not present then the * import is ignored. Optional import can be used if the plug-in works * in limited capacity even without the specified plug-in. * * @subsubsection pluginDescPluginRuntime runtime * * This element contains information about the plug-in runtime library. It is * omitted if the plug-in does not have a runtime library but contains only * data. It can have following attributes. * * - @a library: The name of the plug-in runtime library in the plug-in * directory. A platform specific extension (for example, ".so" or ".dll") * is added to the value specified here when loading the library. * - @a funcs: The functions to be used to create an instance of the plug-in * runtime. This attribute is optional. It is needed if the plug-in has * a start or stop function. The value specified here is a name of an * exported symbol which contains a pointer to @ref cp_plugin_runtime_t * structure. * * @subsubsection pluginDescPluginEP extension-point * * This element defines an extension point provided by the plug-in. * It can have following attributes. * * - @a id: The local identifier of the extension point. The value specified * here is prefixed with the identifier of the plug-in and dot to construct * the global identifier of the extension point. * - @a name: An optional human-readable name describing the use of the * extension point. * - @a schema: An optional path to the extension point XML schema in * the plug-in directory. This information is not currently used by the * framework. But it can be used by a developer to determine what information * should be provided by extensions attached to this extension point. * * @subsubsection pluginDescPluginE extension * * This element defines an extension installed into a specified extension * point provided by the defining plug-in or some other plug-in. * It can have following attributes. * * - @a point: The global identifier of the associated extension point. * - @a id: An optional local identifier for the extension. The value specified * here is prefixed with the identifier of the plug-in and dot to construct * the global identifier for the extension. * - @a name: An optional human-readable name describing the extension. * * The extension element can contain XML elements specific to the associated * extension point (conforming to the schema defined by the extension point). * * @subsection pluginRuntime Plug-in runtime library * * A plug-in runtime library is an optional plug-in element. Plug-ins only * supplying static data in form of XML data and files do not need a runtime * library. However, a typical plug-in does provide program logic as well. * * The plug-in runtime library includes all program logic and program * data provided by the plug-in. It is simply a shared library, or a * dynamically linked library, which is linked in to the application when * the plug-in is started. When plug-in is unloaded, the runtime library is * unloaded as well. The framework has been designed to manage dependencies * so that unloading of the runtime library does not cause problems, provided * that plug-ins behave properly. * * A plug-in can expose functionality to other plug-ins either as exported * global symbols that are directly resolved by other plug-ins or by supplying * extensions. When other plug-ins are directly using exported symbols the * plug-in acts just like any standard shared library. Nothing special there. * The more interesting case is exposing functionality as extensions. Because * the extension is registered at a specific extension point, the logic in * other plug-ins can use the extension and the associated program logic even * if they are not aware of the existence of the extension supplying plug-in. * * The extension points accepting program logic as extensions define a way * to specify the name of the symbol pointing to the supplied logic. This is * typically an attribute of an XML element contained in the extension * definition. The plug-in supplying the extension can then export the program * logic as a global symbol with arbitrary name and then place the name of the * symbol in extension data. Alternatively, the plug-in can define a virtual * symbol at runtime using ::cp_define_symbol. Other plug-ins that are using * extensions registered at the extension point can then resolve the named * symbol using ::cp_resolve_symbol at runtime. The framework automatically * creates a dependency from the symbol using plug-in to the symbol supplying * plug-in to prevent failures in case the symbol supplying plug-in is stopped * or unloaded. * * @subsection pluginData Static plug-in data * * Plug-in can supply static data to other plug-ins using at least two * different mechanisms. A plug-in can easily provide static XML data as part * of extension elements. Additionally, a plug-in directory can contain * files that may be accessed by other plug-ins. Currently the platform does * not provide assistance in accessing data files provided by other plug-ins. * However, a plug-in can locate the plug-in directory and thus any included * data files by using plug-in path available in @ref cp_plugin_info_t * structure of the data providing plug-in. */