Changeset 4783

Show
Ignore:
Timestamp:
05/09/09 15:02:06 (4 years ago)
Author:
nopper
Message:

Updating documentation to the new schema

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • branch/UmitPlugins/share/doc/umit/src/plugins_dev.rst

    r4743 r4783  
    4646The entire plugin system is based on the ``Manifest.xml`` file previously introduceed. This file is responsible to provide information to the Plugin Engine. These information are provided trough an xml file. 
    4747 
    48 You could add you custom elements to the xml file but someone are reserved by UMIT Plugin system: 
    49  
    50    +--------------------+-------------------------------------------------------+ 
    51    | Element            |                                                       | 
    52    +====================+=======================================================+ 
    53    | ``<needs>``        | A list (``VersionString``) of needed virtual plugins  | 
    54    |                    | that must be already loaded to enable the target      | 
    55    |                    | plugin.                                               | 
    56    +--------------------+-------------------------------------------------------+ 
    57    | ``<conflicts>``    | A list (``VersionString``) of conflicting virtual     | 
    58    |                    | plugins that must be **NOT** present to load the      | 
    59    |                    | target plugin.                                        | 
    60    +--------------------+-------------------------------------------------------+ 
    61    | ``<provides>``     | A list (``VersionString``) of exported virtual names  | 
    62    |                    | that the target plugin provides to the others.        | 
    63    +--------------------+-------------------------------------------------------+ 
    64    | ``<start-file>``   | A string pointing to the main file in ``bin/``        | 
    65    |                    | directory.                                            | 
    66    +--------------------+-------------------------------------------------------+ 
    67    | ``<url>``          |A string (URL) pointing to the target plugins homepage.| 
    68    +--------------------+-------------------------------------------------------+ 
    69    | ``<author>``       | A string representing the name of the plugin's author.| 
    70    +--------------------+-------------------------------------------------------+ 
    71    | ``<license>``      | A string representing the license used for the plugin.| 
    72    +--------------------+-------------------------------------------------------+ 
    73    | ``<name>``         | A *non-operator* ``VersionString`` describing the     | 
    74    |                    | plugin.                                               | 
    75    +--------------------+-------------------------------------------------------+ 
    76    | ``<update>``       | A string (URL) pointing to the target plugins update  | 
    77    |                    | directory.                                            | 
    78    +--------------------+-------------------------------------------------------+ 
    79    | ``<description>``  | A string containing a description of the plugin.      | 
    80    +--------------------+-------------------------------------------------------+ 
    81    | ``<version>``      | A string represetnting the plugin version.            | 
    82    +--------------------+-------------------------------------------------------+ 
    83    | ``<contributors>`` | A list of plugin's contributors.                      | 
    84    +--------------------+-------------------------------------------------------+ 
    85    | ``<translators>``  | A list of plugin's translators.                       | 
    86    +--------------------+-------------------------------------------------------+ 
    87    | ``<artists>``      | A list of plugin's artists.                           | 
    88    +--------------------+-------------------------------------------------------+ 
     48You could add you custom elements to the xml file but someone are reserved by UMIT Plugin system (Elements marked with * could compare several times in the Manifest file): 
     49 
     50   +---------------------+---------------------------------------------------------------------+ 
     51   | /UmitPlugin         | Description                                                         | 
     52   +=====================+=====================================================================+ 
     53   | ``<name>``          | A string representing the plugin name.                              | 
     54   +---------------------+---------------------------------------------------------------------+ 
     55   | ``<version>``       | A string represetnting the plugin version.                          | 
     56   +---------------------+---------------------------------------------------------------------+ 
     57   | ``<description>``   | A string containing a description of the plugin.                    | 
     58   +---------------------+---------------------------------------------------------------------+ 
     59   | ``<url>``           | A URI string pointing to the target plugins homepage.               | 
     60   +---------------------+---------------------------------------------------------------------+ 
     61   | ``<runtime>``       | Required.                                                           | 
     62   +---------------------+---------------------------------------------------------------------+ 
     63   | ``<deptree>``       | Optional.                                                           | 
     64   +---------------------+---------------------------------------------------------------------+ 
     65   | ``<credits>``       | Required.                                                           | 
     66   +---------------------+---------------------------------------------------------------------+ 
     67 
     68``<runtime>`` description: 
     69 
     70   +---------------------+---------------------------------------------------------------------+ 
     71   | /UmitPlugin/runtime | Description                                                         | 
     72   +=====================+=====================================================================+ 
     73   | ``<start_file>``    | A string pointing to the main file in ``bin/`` directory.           | 
     74   +---------------------+---------------------------------------------------------------------+ 
     75   | ``<update>`` *      | A URI string pointing to the target plugins update remote location. | 
     76   |                     | In a manifest you could provide multiple ``<update>`` elements for  | 
     77   |                     | mirroring reasons. Optional.                                        | 
     78   +---------------------+---------------------------------------------------------------------+ 
     79 
     80``<deptree>`` description (all elements are optional here): 
     81 
     82   +---------------------+---------------------------------------------------------------------+ 
     83   | /UmitPlugin/deptree | Description                                                         | 
     84   +=====================+=====================================================================+ 
     85   | ``<provide>`` *     | A ``VersionString`` that describes what the target plugin provides  | 
     86   |                     | to the others. Example ``=ftplib-1.0`` or ``=trayicon-2.0``.        | 
     87   +---------------------+---------------------------------------------------------------------+ 
     88   | ``<need>`` *        | A ``VersionString`` of a needed virtual plugin that must be loaded  | 
     89   |                     | in order to enable the target plugin.                               | 
     90   +---------------------+---------------------------------------------------------------------+ 
     91   | ``<conflict>`` *    | A ``VersionString`` of a conflicting virtual plugin that must be    | 
     92   |                     | **NOT** loaded in order to enable the target plugin.                | 
     93   +---------------------+---------------------------------------------------------------------+ 
     94 
     95``credits`` description: 
     96 
     97   +---------------------+---------------------------------------------------------------------+ 
     98   | /UmitPlugin/credits | Description                                                         | 
     99   +=====================+=====================================================================+ 
     100   | ``<license>`` *     | A string representing the license used for the plugin.              | 
     101   +---------------------+---------------------------------------------------------------------+ 
     102   | ``<copyright>`` *   | A string representing the copyright information for plugin.         | 
     103   +---------------------+---------------------------------------------------------------------+ 
     104   | ``<author>`` *      | A string representing a plugin's author.                            | 
     105   +---------------------+---------------------------------------------------------------------+ 
     106   | ``<contributor>`` * | A string representing a plugin's contributor. Optional.             | 
     107   +---------------------+---------------------------------------------------------------------+ 
     108   | ``<translator>`` *  | A string representing a plugin's translator. Optional.              | 
     109   +---------------------+---------------------------------------------------------------------+ 
     110   | ``<artist>`` *      | A string representing a plugin's artist. Optional.                  | 
     111   +---------------------+---------------------------------------------------------------------+ 
     112 
     113 
     114UmitPlugin element could have also an attribute called type to indicate if the plugin is a UI addition or just a library. You could have respectively ``<UmitPlugin .. type="ui">`` or ``<UmitPlugin .. type="lib">``. 
    89115 
    90116Following an example of a Manifest.xml:: 
    91117 
    92     <?xml version="1.0" ?> 
    93     <UmitPlugin> 
    94       <url>http://www.umitproject.org</url> 
    95       <conflicts></conflicts> 
    96       <provides>&gt;=SystemInfo-1.0</provides> 
    97       <needs></needs><type></type> 
    98       <start_file>main</start_file> 
     118    <?xml version="1.0" encoding="utf-8"?> 
     119    <UmitPlugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.umitproject.org" xsi:schemaLocation="http://www.umitproject.org UmitPlugins.xsd" type="ui"> 
    99120      <name>SystemInfo</name> 
    100121      <version>0.1</version> 
    101122      <description>A plugin that provides info about the system</description> 
    102       <author>Francesco Piccinno</author> 
    103       <license>GPL</license> 
    104       <update>http://localhost/~stack/plugins/systeminfo</update> 
     123      <url>http://blog.archpwn.org</url> 
     124      <runtime> 
     125        <start_file>main</start_file> 
     126        <update>http://localhost/mia/</update> 
     127        <update>http://localhost/</update> 
     128      </runtime> 
     129      <deptree> 
     130        <provide>&gt;=SystemInfo-1.0</provide> 
     131      </deptree> 
     132      <credits> 
     133        <license>GPL</license> 
     134        <copyright>(C) 2009 Adriano Monteiro Marques</copyright> 
     135        <author>Francesco Piccinno</author> 
     136      </credits> 
    105137    </UmitPlugin> 
    106138 
    … …  
    108140^^^^^^^^^^^^^^ 
    109141 
    110 Elements like ``<needs>`` , ``<conflicts>`` , ``<provides>`` and ``<name>`` are ``VersionString`` elements. 
     142Elements like ``<need>`` , ``<conflict>`` , ``<provide>`` are ``VersionString`` elements. 
    111143 
    112144EBNF/regex form for op and *non-operator* ``VersionString`` is:: 
    … …  
    144176 
    145177   +--------------------+-------------------------------------------------------+ 
    146    | Element            |                                                       | 
     178   | /UmitPluginUpdate  | Description                                           | 
    147179   +====================+=======================================================+ 
    148    | ``<update-uri>``   | A string (URL) pointing to the new version of the     | 
     180   | ``<version>``      | A *non-operative* ``VersionString`` like for Manifest.| 
     181   +--------------------+-------------------------------------------------------+ 
     182   | ``<desciption>``   | A string representing a description of the update or  | 
     183   |                    | a changelog. Optional.                                | 
     184   +--------------------+-------------------------------------------------------+ 
     185   | ``<url>`` *        | A string (URL) pointing to the new version of the     | 
    149186   |                    | plugin.                                               | 
    150187   +--------------------+-------------------------------------------------------+ 
    151    | ``<version>``      | A *non-operative* ``VersionString`` like for Manifest.| 
     188   | ``<integrity>`` *  | This element is optional and could compare several    | 
     189   |                    | times. You have to set also ``<type>`` and            | 
     190   |                    | ``value`` attribute. Example:                         | 
     191   |                    | ``<integrity type="sha1" value="yourhexdigest"/>``    | 
    152192   +--------------------+-------------------------------------------------------+ 
    153    | ``<md5>``          | This element is optional and contains the MD5 hex     | 
    154    |                    | digest string used for integrity check on the         | 
    155    |                    | downloaded file (the ``<update-uri>`` file).          | 
    156    +--------------------+-------------------------------------------------------+ 
    157193 
    158194An example of the ``latest.xml`` follows:: 
    159195 
    160     <UmitPluginUpdate> 
    161         <update-uri>http://localhost/~stack/plugins/systeminfo/SystemInfo.ump</update-uri> 
    162         <version>2.0.0</version> 
    163         <md5>c7487b08545f58999512f6155852050e</md5> 
     196    <UmitPluginUpdate xmlns="http://www.umitproject.org" xsi:schemaLocation="http://www.umitproject.org UmitPlugins.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
     197        <update> 
     198            <version>2.0</version> 
     199            <description>Don't use this is only there for testing.</description> 
     200            <url>http://localhost/test.ump</url> 
     201        </update> 
     202        <update> 
     203            <version>0.1</version> 
     204            <description>&lt;tt&gt;Changelog: 
     205    &lt;b&gt;* Version 1.0&lt;/b&gt;: 
     206    - Fixed blah 
     207    - Fixed blah 
     208    - Fixed blah 
     209    - Fixed blah&lt;/tt&gt;</description> 
     210            <url>http://localhost/system.ump</url> 
     211            <integrity type="md5" value="d488cbec9b6a3de7de1502ab962a907a"/> 
     212            <integrity type="sha1" value="1851a284568c2fa5fab81384559a3e945b1f2744"/> 
     213        </update> 
    164214    </UmitPluginUpdate> 
    165  
    166215 
    167216API Reference 
    … …  
    251300   That returns an instance of the class *classname* (optional) of the plugin that provides *needstr* or the respective module if *need_module* is True, or None on error. 
    252301    
    253    For example taking a look to the setup.py of Notifier plugin we could see that the autogenerated ``Manifest.xml`` will have the ``<needs>`` element set to ``>=tray-2.0``. Assuming that we have already loaded the TrayPlugin that's taking care of providing ``=tray-2.0`` in his ``<provides>`` element in the Manifest file, we will have something like that:: 
     302   For example taking a look to the setup.py of Notifier plugin we could see that the autogenerated ``Manifest.xml`` will have the ``<need>`` element set to ``>=tray-2.0``. Assuming that we have already loaded the TrayPlugin that's taking care of providing ``=tray-2.0`` in his ``<provide>`` element in the Manifest file, we will have something like that:: 
    254303 
    255304        DEBUG - 2009-04-25 11:26:35,422 - >>> Core.get_need() -> [<main.TrayPlugin object at 0xa4c986c>] (module: False) 
    … …  
    492541        name='helloworld', 
    493542        version='1.0', 
    494         author='Francesco Piccinno', 
     543        author=['Francesco Piccinno'], 
    495544        url='http://www.umitproject.org', 
    496         #update='http://localhost/~stack/plugins/dummywork', 
     545        #update=['http://localhost/~stack/plugins/dummywork'], 
     546        license=['GPL'], 
     547        copyright=['(C) 2009 Francesco Piccinno'], 
    497548        scripts=['sources/main.py'], 
    498549        start_file="main", 
    … …  
    534585    running install_egg_info 
    535586    >> Creating plugin 
    536     Field url setted to http://www.umitproject.org 
    537     Field conflicts setted to 
    538     Field provides setted to =helloworld-1.0 
    539     Field needs setted to 
    540     Field type setted to 
    541     Field start_file setted to main 
    542     Field name setted to helloworld 
    543     Field version setted to 1.0 
    544     Field description setted to Say hello to world! 
    545     Field author setted to Francesco Piccinno 
    546     Field license setted to 
    547     Field artist setted to 
    548     Field copyright setted to 
    549     Field update setted to 
    550587    Adding file bin main.py bin 
    551588    Adding file data logo.png data