Introduction to writing plugins for pkgng in FreeBSD

Table of Contents

• General Information
• Requirements
• How plugins work inside pkgng
• Plugins discovery
• Plugins initialization
• Plugins registration and hooking
• Exposing libpkg to plugins
• Plugins shutdown
• Plugin applications
• Example pkgng plugins and demos

General Information

Soon after the 1.0 release announcement of pkgng, the development branch of pkgng got support for plugins.

Plugins are being used for extending pkgng's functionallity allowing you to write a custom code which hooks into pkgng's library.

Another use of plugins is the ability to write new commands for the frontend.

In this handbook we will see how plugins work and how to write a few simple plugins for pkgng.

At the end of this handbook you can find links to example pkgng plugins and some demos of pkgng plugins in action.

Requirements

• Basic programming skills

How plugins work inside pkgng

Here I will add a few short notes on how plugins work inside libpkg.

In general they can be summarized in these simple steps:

• Plugins discovery
• Plugins initialization
• Plugins registration and hooking
• Exposing libpkg to plugins
• Plugins shutdown

In the next sections of this handbook we discuss about each of the above.

Plugins discovery

The first thing we need in order to get plugins working in pkgng is that we have a way to discover them.

Plugins are being discovered by pkgng during initialization and each valid plugin is being loaded as a dynamic shared library.

So how does plugins discovery work?

Upon initialization pkgng will try to load the plugins defined by the PLUGINS configuration option.

The PLUGINS configuration option is a comma-separated list, which specifies the plugins we want to have loaded.

Example of setting the PLUGINS option in pkg.conf(5) would look like this:

PLUGINS : [commands/mystats, zfssnap]

This would load the mystats plugins which provides a new pkg mystats command and the zfssnap plugin for creating ZFS snapshots before any install/deinstall actions are taken.

As mentioned in the beginning of this handbook, plugins a simply a shared libraries and reside in the directory pointed by the PKG_PLUGINS_DIR directory, which by default is set to /usr/local/lib/pkg/ directory.

It is important to mention that only the plugins specified by the PLUGINS configuration option will be loaded. With that being said this means that if you just place a file in PKG_PLUGINS_DIR directory, that plugin will not be loaded until you add it to the PLUGINS list.

And that is how simple the plugins discover in pkgng is - just add drop your plugin to PKG_PLUGINS_DIR directory and add the plugin to the PLUGINS option in order to load the plugin and make it available for use.

In the next chapter of this handbook we will see how initialize our plugins.