Plugin Build Tool - pb_tool

Python command line tool for compiling and deploying QGIS plugins on all OS platforms.

What’s New in 3.0.8

This version requires Python 3 and QGIS 3.x.

Features

pb_tool provides commands to aid in developing, testing, and deploying a QGIS Python Plugin:

Installation

You can install the tool using pip:

pip install pb_tool

To upgrade to the latest version, use:

pip install --upgrade pb_tool

You can also install using easy_install:

easy_install pb_tool

For information on getting setup to develop on Windows, see: Quick Guide to Getting Started with PyQGIS 3 on Windows

Usage

pb_tool requires a configuration file in order to do most tasks. The following commands don’t require a configuration file:

pb_tool assumes a file name of pb_tool.cfg, although you can specify a different one using the --config options in most commands.

To display the available commands, just enter pb_tool or pbt on the command line:

$ pbt
Usage: pbt [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.

  You can invoke the tool using pbt as well: pbt 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.

  Bugs and enhancement requests, see:
  https://github.com/g-sherman/plugin_build_tool

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 build directory
  compile     Compile the resource and ui files
  config      Create a config file based on source files in the current...
  create      Create a new dialog-based plugin in the current directory
  dclean      Remove the deployed plugin from the deployment directory
  deploy      Deploy the plugin to QGIS plugin directory using parameters
              in...
  doc         Build HTML version of the help files using sphinx
  help        Open the pb_tools web page in your default browser
  list        List the contents of the configuration file
  minimal     Create a QGIS minimalist plugin skeleton in the current...
  translate   Build translations using lrelease.
  update      Check for update to pb_tool
  validate    Check the pb_tool.cfg file for mandatory sections/files.
  version     Return the version of pb_tool and exit
  zip         Package the plugin into a zip file suitable for uploading to...

Aliases

Every command can be referred to by an unique alias. For example:

pb_tool de is the same as pb_tool deploy

Include just enough characters to make it unique.

Command Help

Here is the help for a few of the commands, as reported using the –help option:

Compile

$ pb_tool compile --help
Usage: pb_tool compile [OPTIONS]

  Compile the resource and ui files

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

Clean Deployment

$ pb_tool dclean --help
Usage: pb_tool dclean [OPTIONS]

  Remove the deployed plugin from the deployment directory

Options:
  --config TEXT  Name of the config file to use if other than pb_tool.cfg
  --help         Show this message and exit. **Note**: Confirmation is required to remove the plugin

Clean Compiled Files

$ pb_tool clean --help
Usage: pb_tool clean [OPTIONS]

  Remove compiled resource and ui files

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

Deploy

$ pbt deploy --help
  Usage: pbt deploy [OPTIONS]

    Deploy the plugin to QGIS plugin directory using parameters in pb_tool.cfg

  Options:
    --config_file TEXT       Name of the config file to use if other than
                            pb_tool.cfg
    -p, --plugin_path TEXT   Specify the directory where to deploy your plugin
                            if not using the standard location
    -u, --user-profile TEXT  Specify the QGIS user profile to use for
                            deployment. Ignored if -p is set or plugin_path is
                            specified in pb_tool.cfg
    -q, --quick              Do a quick install without compiling ui, resource,
                            docs, and translation files
    -y, --no-confirm         Don't ask for confirmation to overwrite existing
                            files
    --help                   Show this message and exit.

Note: Unless using the –quick option, confirmation is required before deploying as it removes the current version.

Deploying to a Profile

If you use the --user-profile option, any --plugin_path or setting in pb_tool.cfg will be ignored and the plugin will be deployed to the appropriate user profile directory.

Zip

$ 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.

Your zipped plugin is created in a zip_build subdirectory of your project. This directory is for building the archive—anything placed there will ultimately be lost.

The zip command leaves a copy of your plugin in the zip_build directory. You can take a look at it to make sure your pb_tool.cfg is properly setup to deploy all the files needed.

Creating a Config File for an Existing Project

You can create a config file for an existing plugin project by changing to the directory containing the plugin source and using pb_tool create:

$ pb_tool create --help
Usage: pb_tool create [OPTIONS]

  Create a config file based on source files in the current directory

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

Once the config file is created you can try deploy to see if it picked up everything needed for your plugin—or open it in your favorite text editor to tweak it as needed. The config file is annotated and should be self-explanatory.

Sample pb_tool.cfg

# Sane defaults for your plugin generated by the Plugin Builder are
# already set below.
# 
# As you add Python source files and UI files to your plugin, add
# them to the appropriate [files] section below.

[plugin]
# Name of the plugin. This is the name of the directory that will
# be created in .qgis2/python/plugins
name: pbtnewtest

# Full path to where you want your plugin directory copied. If empty,
# the QGIS default path will be used. Don't include the plugin name in
# the path.
plugin_path:

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

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

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

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

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

# 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:

[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

Deploying

Use pb_tool deploy to build your plugin and copy it to the QGIS plugins directory

pbt deploy
Deploying to /home/gsherman/.local/share/QGIS/QGIS3/profiles/default/python/plugins/pbtnewtest
Deploying will:
                * Remove your currently deployed version
                * Compile the ui and resource files
                * Build the help docs
                * Copy everything to your /home/gsherman/.local/share/QGIS/QGIS3/profiles/default/python/plugins/pbtnewtest directory

Proceed? [y/N]: y
Removing plugin from /home/gsherman/.local/share/QGIS/QGIS3/profiles/default/python/plugins/pbtnewtest
Deploying to /home/gsherman/.local/share/QGIS/QGIS3/profiles/default/python/plugins/pbtnewtest
Compiling to make sure install is clean
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 v2.2.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
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 succeeded.

The HTML pages are in build/html.

Build finished. The HTML pages are in build/html.
Copying __init__.py
Copying pbtnewtest.py
Copying pbtnewtest_dialog.py
Copying pbtnewtest_dialog_base.ui
Copying resources.py
Copying metadata.txt
Copying icon.png
Copying help/build/html to /home/gsherman/.local/share/QGIS/QGIS3/profiles/default/python/plugins/pbtnewtest/help

Creating Plugin Skeletons

Two plugin skeletons are available: minimal and dialog-based.

Minimal plugin

The minimal plugin consists of two files: __init__.py and metadata.txt. The files are taken directly from Martin Dobias’ (wonder-sk) github project. The plugin places an action on the toolbar and pops up a message when clicked. You can expand this to implement your plugin when you don’t need all the bells and whistles added by other plugin generators.

Creating a minimal plugin is as simple as creating a new directory, changing to it, then:

$ pbt minimal
Created new config file in pb_tool.cfg
Created minimal plugin
$ pbt deploy
Deploying to /home/gsherman/.local/share/QGIS/QGIS3/profiles/default/python/plugins/Minimal
Doing quick deployment
Copying __init__.py
Copying metadata.txt
No help files configured---skipping...
Quick deployment complete---if you have problems with your plugin, try doing a full deploy.

Open QGIS and click Go! on the toolbar to see what it does.

For information, see https://github.com/wonder-sk/qgis-minimal-plugin.

Dialog-based plugin

The dialog-based plugin generates a lot more boilerplate, including both the main module and dialog files. You can generate the plugin by specifying all the switches on the command line:

pbt create --modulename my_plugin --classname MyPlugin --menutext "My Plugin"

or by interactively entering them:

$ pbt create
Module name (lowercase): my_plugin
Class name: (mixed case): MyPlugin
Text for the plugin menu: My Plugin
Creating MyPlugin in module my_plugin with menu text My Plugin
Using /home/gsherman/.gitconfig to set some items in the plugin
Created new config file in pb_tool.cfg

When you run the plugin in QGIS an empty dialog pops up. You can then customize with controls using Qt Designer and add code to implement your features.

What’s Missing

Why?

Why create a build tool when make using the Makefile generated by the Plugin Builder plugin generally works? Here are some reasons:

Contributing

Issues and pull requests can be submitted here: