» Plugin Development: Packaging & Distribution

This page documents how to organize the file structure of your pluginand distribute it so that it is installable usingstandard installation methods.Prior to reading this, you should be familiarwith the plugin development basics.

Warning: Advanced Topic! Developing plugins is anadvanced topic that only experienced Vagrant users who are reasonablycomfortable with Ruby should approach.

» Example Plugin

The best way to describe packaging and distribution is to look athow another plugin does it. The best example plugin available for thisis vagrant-aws.

By using Bundler and Rake, building a newvagrant-aws package is easy. By simply calling rake package, agem file is dropped into the directory. By calling rake release,the gem is built and it is uploaded to the central RubyGemsrepository so that it can be installed using vagrant plugin install.

Your plugin can and should be this easy, too, since you basicallyget this for free by using Bundler.

» Setting Up Your Project

To setup your project, run bundle gem vagrant-my-plugin. This will create avagrant-my-plugin directory that has the initial layout to be a RubyGem.

You should modify the vagrant-my-plugin.gemspec file to add anydependencies and change any metadata. View the vagrant-aws.gemspecfor a good example.

Do not depend on Vagrant for your gem. Vagrantis no longer distributed as a gem, and you can assume that it willalways be available when your plugin is installed.

Once the directory structure for a RubyGem is setup, you will wantto modify your Gemfile. Here is the basic structure of a Gemfile forVagrant plugin development:

source "https://rubygems.org"
group :development do
  gem "vagrant", git: "https://github.com/hashicorp/vagrant.git"
end
group :plugins do
  gem "my-vagrant-plugin", path: "."
end

This Gemfile gets "vagrant" for development. This allows you tobundle exec vagrant to run Vagrant with your plugin already loaded,so that you can test it manually that way.

The only thing about this Gemfile that may stand out as odd is the"plugins" group and putting your plugin in that group. Becausevagrant plugin commands do not work in development, this is howyou "install" your plugin into Vagrant. Vagrant will automaticallyload any gems listed in the "plugins" group. Note that this alsoallows you to add multiple plugins to Vagrant for development, ifyour plugin works with another plugin.

Next, create a Rakefile that has at the very least, the followingcontents:

require "rubygems"
require "bundler/setup"
Bundler::GemHelper.install_tasks

If you run rake -T now, which lists all the available rake tasks,you should see that you have the package and release tasks. Youcan now develop your plugin and build it!

You can view the vagrant-aws Rakefilefor a more comprehensive example that includes testing.

» Testing Your Plugin

To manually test your plugin during development, usebundle exec vagrant to execute Vagrant with your plugin loaded(thanks to the Gemfile setup we did earlier).

For automated testing, thevagrant-specproject provides helpers for both unit and acceptance testingplugins. See the giant README for that project for a detaileddescription of how to integrate vagrant-spec into your project.Vagrant itself (and all of its core plugins) use vagrant-specfor automated testing.