QGIS Development with Plugin Builder and pb_tool

The Plugin Builder is a great tool for generating a working plugin project that you can customize.

One of the main tasks in the development cycle is deploying the plugin to the QGIS plugin directory for testing. Plugin Builder comes with a Makefile that can be used on Linux and OS X to aid in development. Depending on your configuration, the Makefile may work on Windows.

To help in managing development of your projects, we’ve come up with another option—a Python tool called pb_tool, which works anywhere QGIS runs.

Here’s what it provides:

    Usage: pb_tool [OPTIONS] COMMAND [ARGS]...

      Simple Python tool to compile and deploy a QGIS plugin. For help on a
      command use --help after the command: pb_tool deploy --help.

      pb_tool requires a configuration file (default: pb_tool.cfg) that declares
      the files and resources used in your plugin. Plugin Builder 2.6.0 creates
      a config file when you generate a new plugin template.

      See http://g-sherman.github.io/plugin_build_tool for for an example config
      file. You can also use the create command to generate a best-guess config
      file for an existing project, then tweak as needed.

    Options:
      --help  Show this message and exit.

    Commands:
      clean       Remove compiled resource and ui files
      clean_docs  Remove the built HTML help files from the...
      compile     Compile the resource and ui files
      create      Create a config file based on source files in...
      dclean      Remove the deployed plugin from the...
      deploy      Deploy the plugin to QGIS plugin directory...
      doc         Build HTML version of the help files using...
      list        List the contents of the configuration file
      translate   Build translations using lrelease.
      validate    Check the pb_tool.cfg file for mandatory...
      version     Return the version of pb_tool and exit
      zip         Package the plugin into a zip file suitable...

In the command summary, a description ending in … means there is more to see using the help switch:

 pb_tool zip --help
Usage: pb_tool zip [OPTIONS]

  Package the plugin into a zip file suitable for uploading to the QGIS
  plugin repository

Options:
  --config TEXT  Name of the config file to use if other than pb_tool.cfg
  --help         Show this message and exit.

The Configuration File

pb_tool relies on a configuration file to do its work. Here’s a sample pb_tool.cfg file:

    # Configuration file for plugin builder tool
    # Sane defaults for your plugin generated by the Plugin Builder are
    # already set below.
    #
    [plugin]
    # Name of the plugin. This is the name of the directory that will
    # be created in .qgis2/python/plugins
    name: TestPlugin

    [files]
    # Python  files that should be deployed with the plugin
    python_files: __init__.py test_plugin.py test_plugin_dialog.py

    # The main dialog file that is loaded (not compiled)
    main_dialog: test_plugin_dialog_base.ui

    # Other ui files for dialogs you create (these will be compiled)
    compiled_ui_files: foo.ui

    # Resource file(s) that will be compiled
    resource_files: resources.qrc

    # Other files required for the plugin
    extras: icon.png metadata.txt

    # Other directories to be deployed with the plugin.
    # These must be subdirectories under the plugin directory
    extra_dirs:

    # ISO code(s) for any locales (translations), separated by spaces.
    # Corresponding .ts files must exist in the i18n directory
    locales: af

    [help]
    # the built help directory that should be deployed with the plugin
    dir: help/build/html
    # the name of the directory to target in the deployed plugin
    target: help

The configuration file is pretty much self-explanatory and represents that generated by Plugin Builder 2.6 for a new plugin. As you develop your code, you simply add the file names to the appropriate sections.

Plugin Builder 2.6 will be available the week of the QGIS 2.6 release. In the meantime, you can use pb_tool create to create a config file. See the pb_tool website for more information.

Deploying

Here’s what a deployment looks like with pb_tool:

  $ pb_tool deploy
  Deploying will:
              * Remove your currently deployed version
              * Compile the ui and resource files
              * Build the help docs
              * Copy everything to your .qgis2/python/plugins directory

  Proceed? [y/N]: y
  Removing plugin from /Users/gsherman/.qgis2/python/plugins/TestPlugin
  Deploying to /Users/gsherman/.qgis2/python/plugins/TestPlugin
  Compiling to make sure install is clean
  Skipping foo.ui (unchanged)
  Compiled 0 UI files
  Skipping resources.qrc (unchanged)
  Compiled 0 resource files
  Building the help documentation
  sphinx-build -b html -d build/doctrees   source build/html
  Running Sphinx v1.2b1
  loading pickled environment... done
  building [html]: targets for 0 source files that are out of date
  updating environment: 0 added, 0 changed, 0 removed
  looking for now-outdated files... none found
  no targets are out of date.

  Build finished. The HTML pages are in build/html.
  Copying __init__.py
  Copying test_plugin.py
  Copying test_plugin_dialog.py
  Copying test_plugin_dialog_base.ui
  Copying foo.py
  Copying resources_rc.py
  Copying icon.png
  Copying metadata.txt
  Copying help/build/html to /Users/gsherman/.qgis2/python/plugins/TestPlugin/help

Getting Started

For details on installing and using pb_tool, see: http://g-sherman.github.io/plugin_build_tool