From f2713b610418e75524a92a2be87ad8ca4ee2a8ee Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 5 Feb 2014 15:56:57 -0800 Subject: [PATCH] website/docs: clarify plugin development with latest changes --- .../v2/plugins/development-basics.html.md | 39 +++++++++++ .../docs/source/v2/plugins/packaging.html.md | 67 +++++++++++-------- 2 files changed, 77 insertions(+), 29 deletions(-) diff --git a/website/docs/source/v2/plugins/development-basics.html.md b/website/docs/source/v2/plugins/development-basics.html.md index e57936bcf..bb48939ac 100644 --- a/website/docs/source/v2/plugins/development-basics.html.md +++ b/website/docs/source/v2/plugins/development-basics.html.md @@ -27,6 +27,45 @@ using [RubyGems](http://rubygems.org/). Familiarity with Ruby is required, but the [packaging and distribution](/v2/plugins/packaging.html) section should help guide you to packaging your plugin into a RubyGem. +## Setup and Workflow + +Because plugins are packaged as RubyGems, Vagrant plugins should be +developed as if you were developing a regular RubyGem. The easiest +way to do this is to use the `bundle gem` command. + +Once the directory structure for a RubyGem is setup, you'll want +to modify your Gemfile. Here is the basic structure of a Gemfile for +Vagrant plugin development: + +```ruby +source "https://rubygems.org" + +group :development do + gem "vagrant", :git => "https://github.com/mitchellh/vagrant.git" +end + +group :plugins do + gem "my-vagrant-plugin", path: "." +end +``` + +This Gemfile gets "vagrant" for development. This allows you to +`bundle 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. Because +`vagrant plugin` commands don't work in development, this is how +you "install" your plugin into Vagrant. Vagrant will automatically +load any gems listed in the "plugins" group. Note that this also +allows you to add multiple plugins to Vagrant for development, if +your plugin works with another plugin. + +With this structure in place, your workflow should be like any other +Ruby project. When you want to manually test your plugin, use +`bundle exec vagrant` in order to run Vagrant with your plugin +loaded (as we specified in the Gemfile). + ## Plugin Definition All plugins are required to have a definition. A definition contains details diff --git a/website/docs/source/v2/plugins/packaging.html.md b/website/docs/source/v2/plugins/packaging.html.md index 8921bc043..04dda1da2 100644 --- a/website/docs/source/v2/plugins/packaging.html.md +++ b/website/docs/source/v2/plugins/packaging.html.md @@ -51,6 +51,34 @@ for a good example.

+Once the directory structure for a RubyGem is setup, you'll want +to modify your Gemfile. Here is the basic structure of a Gemfile for +Vagrant plugin development: + +```ruby +source "https://rubygems.org" + +group :development do + gem "vagrant", :git => "https://github.com/mitchellh/vagrant.git" +end + +group :plugins do + gem "my-vagrant-plugin", path: "." +end +``` + +This Gemfile gets "vagrant" for development. This allows you to +`bundle 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. Because +`vagrant plugin` commands don't work in development, this is how +you "install" your plugin into Vagrant. Vagrant will automatically +load any gems listed in the "plugins" group. Note that this also +allows you to add multiple plugins to Vagrant for development, if +your plugin works with another plugin. + Next, create a `Rakefile` that has at the very least, the following contents: @@ -69,33 +97,14 @@ for a more comprehensive example that includes testing. ## Testing Your Plugin -You have a couple options for testing your plugin. First, you can run -`rake package`, then `vagrant plugin install` the resulting file to -test it. The downside of this is that there is a pretty slow feedback -loop every time you want to test the plugin. +To manually test your plugin during development, use +`bundle exec vagrant` to execute Vagrant with your plugin loaded +(thanks to the Gemfile setup we did earlier). -Alternatively, you can depend on Vagrant from your Gemfile for development -purposes only. Then you can use `bundle exec vagrant` and a Vagrantfile -in your own directory to test it. This has a fast feedback loop, but requires -that Vagrant has all the dependencies it needs installed on your system. - -vagrant-aws uses the second option. You can see the dependency in the -[Gemfile](https://github.com/mitchellh/vagrant-aws/blob/master/Gemfile). -The Vagrantfile is gitignored so that sensitive and volatile test -information can be put into it. The important bit is that the Vagrantfile -must have a `Vagrant.require_plugin` call so that it is loaded, since -Vagrant doesn't automatically know about plugins not installed using -`vagrant plugin`. - -For example, a vagrant-aws development Vagrantfile might look like this: - -```ruby -Vagrant.require_plugin "vagrant-aws" - -Vagrant.configure("2") do |config| - config.vm.box = "test" -end -``` - -Then you can run `bundle exec vagrant up` to test it. Note the "bundle exec" -is required so that Bundler uses the proper Vagrant installation. +For automated testing, the +[vagrant-spec](https://github.com/mitchellh/vagrant-spec) +project provides helpers for both unit and acceptance testing +plugins. See the giant README for that project for a detailed +description of how to integrate vagrant-spec into your project. +Vagrant itself (and all of its core plugins) use vagrant-spec +for automated testing.