Distributing a plugin

Distributing a QGIS plugin means placing a collection of files on a server as a ZIP file, with a special configuration file, in order to allow the QGIS plugin manager to locate and install the plugin. The QGIS project has an official repository, but third-party repositories are also permitted. The official repository is very strict regarding how the plugin is uploaded, so, for this recipe, we'll set up a simple third-party repository for a sample plugin and test it with the QGIS plugin manager to avoid polluting the main QGIS repository with a test project. You should note that QGIS is released under the GNU General Public License (GPL), so presumably all other plugins fall under the GPL as well, based on the terms of the license.

Getting ready

In order to complete this recipe, you'll need a sample plugin and a web-accessible directory. You'll also need a ZIP tool, such as the free 7-zip program (http://www.7-zip.org/download.html). Both OSX and Windows can compress and decompress zip files natively. On Linux, you may need to download a ZIP tool from your package manager. You can use the MyPlugin example from the Creating a QGIS plugin recipe as the plugin to distribute. For a web directory, you can use a Google Code repository, GitHub repository, or other online directories you can access. Code repositories work well because they are a good place to store a plugin that you are developing.

How to do it...

In the following steps, we will package our plugin, create a server configuration file for it, and place it on a server to create a QGIS plugin repository:

1. First, zip up the plugin directory to create a .zip file.
2. Rename the .zip file to contain the plugin's version number:

   Myplugin.0.1.0.zip
   

3. Upload this file to a publicly accessible web directory.
4. Upload the icon.png file from your plugin directory to the web directory.
5. Next, customize a plugins.xml metadata file for your plugin. Most of the data you need can be found in the metatdata.txt file in your plugin directory. The following example provides some guidance:

           <?xml version = '1.0' encoding = 'UTF-8'?> 
           <?xml-stylesheet type="text/xsl"href="" ?> 
           <plugins> 
             <pyqgis_plugin name="My Plugin" version="0.1.0" plugin_id="227"> 
               <description> 
                 <![CDATA[Demonstration of a QGIS Plugin]]> 
               </description> 
               <about></about> 
               <version>0.1.0</version> 
               <qgis_minimum_version>1.8.0</qgis_minimum_version> 
               <qgis_maximum_version>2.9.9</qgis_maximum_version> 
               <homepage> 
                 <![CDATA[https://github.com/GeospatialPython/Learn]]> 
               </homepage> 
               <file_name>MyPlugin.0.1.0.zip</file_name> 
               <icon>https://github.com/GeospatialPython/
               Learn/raw/master/icon_227.png</icon> 
               <author_name><![CDATA[Joel Lawhead]]></author_name> 
               <download_url>https://github.com/GeospatialPython/
               Learn/raw/master/MyPlugin.0.1.0.zip</download_url> 
               <uploaded_by><![CDATA[jll]]></uploaded_by> 
               <create_date>2016-11-19T15:31:19.824333</create_date> 
               <update_date>2016-11-19T15:31:19.824333</update_date> 
               <experimental>True</experimental> 
               <deprecated>False</deprecated> 
               <tracker> 
                 <![CDATA[https://github.com/GeospatialPython/Learn/issues]]> 
               </tracker> 
               <repository> 
                 <![CDATA[https://github.com/GeospatialPython/Learn/]]> 
               </repository> 
               <tags><![CDATA[development,debugging,tools]]></tags> 
               <downloads>0</downloads> 
               <average_vote>0</average_vote> 
               <rating_votes>0</rating_votes> 
             </pyqgis_plugin> 
           </plugins> 
   

6. Upload the plugins.xml file to your web directory.
7. Now start QGIS and launch the plugins manager by going to the Plugins menu and selecting Manage and Install Plugins....
8. In the Settings tab of the Plugins | Settings dialog, scroll down and click on the Add... button.
9. Give the plugin a name and then add the complete URL to plugins.xml in the URL field.
10. Click on the OK button.
11. To make things easier, disable the other repositories by selecting the repository name, clicking on the Edit button, and unchecking the Enabled checkbox.
12. Click on the OK button
13. Click on the Not installed tab.
14. Your test plugin should be the only plugin listed, so select it from the list.
15. Click on the Install plugin button in the bottom-right corner of the window.
16. Click on the Close button.
17. Go to the Plugins menu and select your plugin to ensure that it works.

How it works...

The QGIS repository concept is simple and effective. The plugins.xml file contains a <download_url> tag that points to a ZIP file plugin on the same server or on a different server. The name attribute of the <pyqgis_plugin> tag is what appears in the QGIS plugin manager.