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
- pb_tool can be invoked using the pbt alias
- Support for deploying to a specific QGIS user profile using
- Zip file generation is now done in a local build directory and no longer requires a clean/deploy to build an archive
- When creating a config file, pbt will use name and email from a .pbtconfig or .gitconfig file in your home directory
- pbt can now create two plugin skeletons as project starters for you:
- A minimalist plugin from Martin Dobias (wonder-sk)
- A dialog-based plugin similar to that generated by Plugin Builder
This version requires Python 3 and QGIS 3.x.
pb_tool provides commands to aid in developing, testing, and deploying a QGIS Python Plugin:
- Compile resource and UI files
- Deploy to your plugins directory for testing in QGIS
- Create a zip file for upload to a repository
- Clean both compiled and deployed files
- Create plugin skeletons (minimal and dialog based)
- Build and clean documentation
- Build translation files
- Works on Windows, OS X, and Linux
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:
For information on getting setup to develop on Windows, see: Quick Guide to Getting Started with PyQGIS 3 on Windows
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
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...
Every command can be referred to by an unique alias. For example:
pb_tool de is the same as
Include just enough characters to make it unique.
Here is the help for a few of the commands, as reported using the –help option:
$ 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.
$ 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.
$ 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.
$ 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.
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 --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.
# 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
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.
The minimal plugin consists of two files:
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.
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.
pb_toolcurrently doesn’t support running tests for your plugin.
- Probably other things we haven’t thought of…
Why create a build tool when
make using the Makefile generated by the
Plugin Builder plugin generally works? Here are some reasons:
pb_toollets you create configs for plugins that were not created using the Plugin Builder plugin
- The Makefile doesn’t work completely on Windows in all cases
- Writing a command line tool is fun..
Issues and pull requests can be submitted here: